From a54dc3c54371d1cd86fdc1e4bc1630ebd27862be Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Sun, 19 Jul 2026 01:19:37 -0700
Subject: [PATCH 01/78] split: add a bounded application-message side channel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add an opaque, bounded application payload that firmware can exchange
between the split central and peripheral alongside the normal split
traffic, without ever taking priority over key events.

* `split_app` module: `SplitAppData` (a small, `MaxSize`, postcard
  length-prefixed payload) plus four statics — `SPLIT_APP_TX`
  (central -> peripheral), `SPLIT_APP_PERIPH_TX` (peripheral ->
  central), the symmetric `SPLIT_APP_RX` inbox, and the `SPLIT_APP_LINK`
  watch that reports split-link state to the application.
* Producers use `try_send` only (bounded, drop-on-full) so the split
  read/write loops never block or get starved by application traffic;
  key events are always polled first.
* The split driver and peripheral drain the application queues as the
  lowest-priority arm of their outgoing selects and forward received
  `SplitMessage::Application` payloads into the inbox.
* `SPLIT_APP_LINK` is state-based (a `Watch`), so a late-subscribing
  application still observes the current link state; the `false -> true`
  edge is a resync trigger. Link-down edges are emitted from a drop
  guard so they survive async cancellation of the split session.
* On the peripheral the link is raised on the FIRST inbound message from
  the central rather than on bare connection: over BLE, notifications to
  a central that has not yet subscribed are silently dropped, so the
  connection alone is not proof the application channel is usable.

Developed for a split keyboard port.
---
 rmk/src/lib.rs              |   3 +
 rmk/src/split/driver.rs     |  34 ++++-
 rmk/src/split/mod.rs        |   6 +
 rmk/src/split/peripheral.rs | 266 ++++++++++++++++++++++--------------
 rmk/src/split_app.rs        | 124 +++++++++++++++++
 5 files changed, 328 insertions(+), 105 deletions(-)
 create mode 100644 rmk/src/split_app.rs

diff --git a/rmk/src/lib.rs b/rmk/src/lib.rs
index 1be3ed35a..a69f69d8c 100644
--- a/rmk/src/lib.rs
+++ b/rmk/src/lib.rs
@@ -105,6 +105,9 @@ pub mod matrix;
 pub mod processor;
 #[cfg(feature = "split")]
 pub mod split;
+// Bounded application-message hook for the split protocol.
+#[cfg(feature = "split")]
+pub mod split_app;
 pub mod state;
 #[cfg(feature = "storage")]
 pub mod storage;
diff --git a/rmk/src/split/driver.rs b/rmk/src/split/driver.rs
index 7fcdb5119..7be44f26a 100644
--- a/rmk/src/split/driver.rs
+++ b/rmk/src/split/driver.rs
@@ -184,6 +184,24 @@ impl<T: SplitReader + SplitWriter> PeripheralManager<T> {
         #[cfg(feature = "display")]
         let mut sleep_sub = crate::event::SleepStateEvent::subscriber();
 
+        // Expose the split-link state to the application. This
+        // manager runs exactly while the peripheral session is up; the
+        // `false → true` edge is the application's resync trigger.
+        //
+        // The link-down edge MUST be sent from a drop guard: on connection
+        // loss the outer `select3` in `split/ble/central.rs` resolves via its
+        // connection-monitor arm and this future is *cancelled*, so any
+        // `send(false)` written on an error path here would never run.
+        struct LinkDownGuard;
+        impl Drop for LinkDownGuard {
+            fn drop(&mut self) {
+                crate::split_app::SPLIT_APP_LINK.sender().send(false);
+            }
+        }
+        let _link_guard = LinkDownGuard;
+        let app_link = crate::split_app::SPLIT_APP_LINK.sender();
+        app_link.send(true);
+
         // Send the current state once on startup so the peripheral matches us
         // even when no transition has happened since the central booted.
         if self
@@ -193,7 +211,7 @@ impl<T: SplitReader + SplitWriter> PeripheralManager<T> {
             .await
             .is_err()
         {
-            return;
+            return; // guard sends the link-down edge
         }
 
         #[cfg(feature = "dfu_split")]
@@ -225,6 +243,10 @@ impl<T: SplitReader + SplitWriter> PeripheralManager<T> {
                     with_feature("display"): e = wpm_sub.next_event().fuse() => SplitMessage::Wpm(e.0),
                     with_feature("display"): e = modifier_sub.next_event().fuse() => SplitMessage::Modifier(e.modifier.into_bits()),
                     with_feature("display"): e = sleep_sub.next_event().fuse() => SplitMessage::SleepState(e.0),
+                    // Application messages, deliberately the
+                    // last (lowest-priority) outgoing arm; the read arm of the
+                    // outer select still beats all outgoing traffic.
+                    m = crate::split_app::SPLIT_APP_TX.receive().fuse() => SplitMessage::Application(m),
                 }
             };
 
@@ -254,7 +276,7 @@ impl<T: SplitReader + SplitWriter> PeripheralManager<T> {
                 #[cfg(not(feature = "dfu_split"))]
                 Either::Second(msg) => {
                     if self.send(&msg).await.is_err() {
-                        return;
+                        return; // guard sends the link-down edge
                     }
                 }
             }
@@ -283,6 +305,14 @@ impl<T: SplitReader + SplitWriter> PeripheralManager<T> {
             },
             // Non-key events are drop-on-full to keep the split read loop responsive.
             SplitMessage::Pointing(e) => publish_event(e),
+            // Forward peripheral → central application
+            // payloads into the (symmetric) inbox; drop-on-full so a slow
+            // consumer can never stall the split read loop.
+            SplitMessage::Application(data) => {
+                if crate::split_app::SPLIT_APP_RX.try_send(data).is_err() {
+                    warn!("split app message dropped (inbox full)");
+                }
+            }
             #[cfg(feature = "_ble")]
             SplitMessage::BatteryStatus(state) => set_peripheral_battery(self.id, state.0),
             #[cfg(feature = "dfu_split")]
diff --git a/rmk/src/split/mod.rs b/rmk/src/split/mod.rs
index 9cd58ad22..20a525f0c 100644
--- a/rmk/src/split/mod.rs
+++ b/rmk/src/split/mod.rs
@@ -102,6 +102,12 @@ pub(crate) enum SplitMessage {
     /// Peripheral → Central: confirm mark_updated succeeded, about to reset.
     #[cfg(feature = "dfu_split")]
     FirmwareUpdateConfirm,
+
+    /// opaque bounded application payload, central →
+    /// peripheral (see `crate::split_app`). Kept as the LAST variant so
+    /// the postcard discriminants of all existing messages stay stable across
+    /// halves flashed at different revisions.
+    Application(crate::split_app::SplitAppData),
 }
 
 // -----------------------------------------------------------------------
diff --git a/rmk/src/split/peripheral.rs b/rmk/src/split/peripheral.rs
index 15446c1de..6f465929c 100644
--- a/rmk/src/split/peripheral.rs
+++ b/rmk/src/split/peripheral.rs
@@ -83,6 +83,40 @@ impl<S: SplitWriter + SplitReader> SplitPeripheral<S> {
     /// The peripheral uses the general matrix, does scanning and sends key events through `SplitWriter`.
     /// It also receives split messages from the central through `SplitReader`.
     pub(crate) async fn run(&mut self) {
+        // Expose the split-link state to the application.
+        // `run` executes exactly while a central session is up (for BLE it is
+        // invoked per connection and returns on disconnect).
+        //
+        // As on the central side (split/driver.rs), the link-down edge MUST
+        // come from a drop guard: this future can be cancelled from outside
+        // when the session dies, so no in-line `send(false)` is guaranteed to
+        // run. Without the false edge, reconnects look like true->true and
+        // link-up-triggered behavior (e.g. the version announcement) never
+        // re-arms.
+        //
+        // The link-UP edge is deliberately NOT sent here at session start:
+        // for BLE the connection is up, but the central has not yet
+        // subscribed to the peripheral's notify characteristic (CCCD write),
+        // and trouble-host silently drops notifications to an unsubscribed
+        // peer — anything the application sent in that window would vanish.
+        // Instead, link-up is declared on the FIRST message received from
+        // the central: the central's `PeripheralManager` sends its
+        // `ConnectionStatus` snapshot immediately after subscribing, and ATT
+        // bearer ordering guarantees the CCCD write was processed before
+        // that message, so peripheral → central traffic is deliverable from
+        // this point on. (Serial split has no subscription step and reaches
+        // the same first message; the edge is simply "the session is
+        // bidirectionally live".)
+        struct LinkDownGuard;
+        impl Drop for LinkDownGuard {
+            fn drop(&mut self) {
+                crate::split_app::SPLIT_APP_LINK.sender().send(false);
+            }
+        }
+        let _link_guard = LinkDownGuard;
+        let app_link = crate::split_app::SPLIT_APP_LINK.sender();
+        let mut link_up_sent = false;
+
         // Proactively announce our firmware hash so the central can detect
         // us even when it booted first and already gave up waiting for a query response.
         #[cfg(feature = "dfu_split")]
@@ -113,127 +147,150 @@ impl<S: SplitWriter + SplitReader> SplitPeripheral<S> {
                     },
                     e = pointing_sub.next_message_pure().fuse() => SplitMessage::Pointing(e),
                     with_feature("_ble"): e = battery_sub.next_event().fuse() => SplitMessage::BatteryStatus(e),
+                    // Peripheral → central application
+                    // messages, deliberately the last (lowest-priority)
+                    // outgoing arm behind key events.
+                    m = crate::split_app::SPLIT_APP_PERIPH_TX.receive().fuse() => SplitMessage::Application(m),
                 }
             };
 
             match select(self.split_driver.read(), read_message_to_send).await {
                 Either::First(m) => match m {
                     // Process split messages from the central
-                    Ok(split_message) => match split_message {
-                        SplitMessage::ConnectionStatus(status) => {
-                            trace!("Received central connection status: {:?}", status);
-                            update_status(|c| *c = status);
-                        }
-                        #[cfg(all(feature = "_ble", feature = "storage"))]
-                        SplitMessage::ClearPeer => {
-                            // Clear the peer address
-                            FLASH_CHANNEL
-                                .send(crate::storage::FlashOperationMessage::PeerAddress(PeerAddress::new(
-                                    0, false, [0; 6],
-                                )))
-                                .await;
-                        }
-                        SplitMessage::KeyboardIndicator(indicator) => {
-                            // Publish KeyboardIndicator event
-                            publish_event(LedIndicatorEvent::new(
-                                rmk_types::led_indicator::LedIndicator::from_bits(indicator),
-                            ));
-                        }
-                        SplitMessage::Layer(layer) => {
-                            // Publish Layer event
-                            publish_event(LayerChangeEvent::new(layer));
-                        }
-                        #[cfg(feature = "display")]
-                        SplitMessage::Wpm(wpm) => publish_event(WpmUpdateEvent::new(wpm)),
-                        #[cfg(feature = "display")]
-                        SplitMessage::Modifier(bits) => {
-                            publish_event(ModifierEvent {
-                                modifier: rmk_types::modifier::ModifierCombination::from_bits(bits),
-                            });
-                        }
-                        #[cfg(feature = "display")]
-                        SplitMessage::SleepState(sleeping) => {
-                            publish_event(SleepStateEvent::new(sleeping));
+                    Ok(split_message) => {
+                        // First traffic from the central ⇒ the
+                        // session is bidirectionally live (see the LinkDownGuard
+                        // comment above for why link-up is not sent at start).
+                        if !link_up_sent {
+                            app_link.send(true);
+                            link_up_sent = true;
                         }
-                        // --- dfu_split: firmware update handlers ---
-                        #[cfg(feature = "dfu_split")]
-                        SplitMessage::FirmwareHashQuery => {
-                            let hash = crate::dfu::read_embedded_firmware_hash();
-                            info!("dfu_split: hash query, responding with {:#x}", hash);
-                            self.split_driver
-                                .write(&SplitMessage::FirmwareHashResponse(hash))
-                                .await
-                                .ok();
-                        }
-                        #[cfg(feature = "dfu_split")]
-                        SplitMessage::FirmwareChunk { offset, len, data } => {
-                            if self.dfu_handler.is_none() {
-                                self.dfu_handler = crate::dfu::SplitDfuHandler::new();
+                        match split_message {
+                            SplitMessage::ConnectionStatus(status) => {
+                                trace!("Received central connection status: {:?}", status);
+                                update_status(|c| *c = status);
+                            }
+                            #[cfg(all(feature = "_ble", feature = "storage"))]
+                            SplitMessage::ClearPeer => {
+                                // Clear the peer address
+                                FLASH_CHANNEL
+                                    .send(crate::storage::FlashOperationMessage::PeerAddress(PeerAddress::new(
+                                        0, false, [0; 6],
+                                    )))
+                                    .await;
+                            }
+                            SplitMessage::KeyboardIndicator(indicator) => {
+                                // Publish KeyboardIndicator event
+                                publish_event(LedIndicatorEvent::new(
+                                    rmk_types::led_indicator::LedIndicator::from_bits(indicator),
+                                ));
+                            }
+                            SplitMessage::Layer(layer) => {
+                                // Publish Layer event
+                                publish_event(LayerChangeEvent::new(layer));
+                            }
+                            #[cfg(feature = "display")]
+                            SplitMessage::Wpm(wpm) => publish_event(WpmUpdateEvent::new(wpm)),
+                            #[cfg(feature = "display")]
+                            SplitMessage::Modifier(bits) => {
+                                publish_event(ModifierEvent {
+                                    modifier: rmk_types::modifier::ModifierCombination::from_bits(bits),
+                                });
+                            }
+                            #[cfg(feature = "display")]
+                            SplitMessage::SleepState(sleeping) => {
+                                publish_event(SleepStateEvent::new(sleeping));
+                            }
+                            // --- dfu_split: firmware update handlers ---
+                            #[cfg(feature = "dfu_split")]
+                            SplitMessage::FirmwareHashQuery => {
+                                let hash = crate::dfu::read_embedded_firmware_hash();
+                                info!("dfu_split: hash query, responding with {:#x}", hash);
+                                self.split_driver
+                                    .write(&SplitMessage::FirmwareHashResponse(hash))
+                                    .await
+                                    .ok();
+                            }
+                            #[cfg(feature = "dfu_split")]
+                            SplitMessage::FirmwareChunk { offset, len, data } => {
                                 if self.dfu_handler.is_none() {
-                                    error!("dfu_split: FlashManager not initialized, skipping chunk");
-                                    continue;
+                                    self.dfu_handler = crate::dfu::SplitDfuHandler::new();
+                                    if self.dfu_handler.is_none() {
+                                        error!("dfu_split: FlashManager not initialized, skipping chunk");
+                                        continue;
+                                    }
                                 }
-                            }
-                            let handler = self.dfu_handler.as_mut().unwrap();
-                            let actual_len = len as usize;
-                            let chunk_data = &data.0[..actual_len];
-                            match handler.write_chunk(offset as u32, chunk_data) {
-                                Ok(()) => {
-                                    debug!("dfu_split: wrote {} bytes at offset {}", actual_len, offset);
-                                    let ack = SplitMessage::FirmwareChunkAck {
-                                        offset,
-                                        crc: crate::crc32::crc32(chunk_data),
-                                    };
-                                    self.split_driver.write(&ack).await.ok();
+                                let handler = self.dfu_handler.as_mut().unwrap();
+                                let actual_len = len as usize;
+                                let chunk_data = &data.0[..actual_len];
+                                match handler.write_chunk(offset as u32, chunk_data) {
+                                    Ok(()) => {
+                                        debug!("dfu_split: wrote {} bytes at offset {}", actual_len, offset);
+                                        let ack = SplitMessage::FirmwareChunkAck {
+                                            offset,
+                                            crc: crate::crc32::crc32(chunk_data),
+                                        };
+                                        self.split_driver.write(&ack).await.ok();
+                                    }
+                                    Err(()) => error!("dfu_split: write error at offset {}", offset),
                                 }
-                                Err(()) => error!("dfu_split: write error at offset {}", offset),
                             }
-                        }
-                        #[cfg(feature = "dfu_split")]
-                        SplitMessage::FirmwareUpdateComplete => {
-                            if let Some(ref mut handler) = self.dfu_handler {
-                                let dfu_crc = handler.compute_dfu_crc();
-                                info!("dfu_split: DFU partition CRC: {:#010x}", dfu_crc);
-                                let crc_msg = SplitMessage::FirmwareCrcReport(dfu_crc);
-                                self.split_driver.write(&crc_msg).await.ok();
-                                info!("dfu_split: CRC report sent");
+                            #[cfg(feature = "dfu_split")]
+                            SplitMessage::FirmwareUpdateComplete => {
+                                if let Some(ref mut handler) = self.dfu_handler {
+                                    let dfu_crc = handler.compute_dfu_crc();
+                                    info!("dfu_split: DFU partition CRC: {:#010x}", dfu_crc);
+                                    let crc_msg = SplitMessage::FirmwareCrcReport(dfu_crc);
+                                    self.split_driver.write(&crc_msg).await.ok();
+                                    info!("dfu_split: CRC report sent");
 
-                                let deadline = embassy_time::Instant::now() + embassy_time::Duration::from_secs(5);
-                                let ok = loop {
-                                    match select(self.split_driver.read(), embassy_time::Timer::at(deadline)).await {
-                                        Either::First(Ok(SplitMessage::FirmwareCrcOk)) => {
-                                            info!("dfu_split: central confirmed CRC, resetting");
-                                            break true;
-                                        }
-                                        Either::First(Ok(SplitMessage::FirmwareCrcFail)) => {
-                                            warn!("dfu_split: central rejected CRC, stopping update");
-                                            break false;
-                                        }
-                                        Either::First(Ok(_)) => {}
-                                        Either::First(Err(e)) => {
-                                            error!("read error: {:?}", e);
-                                            break false;
-                                        }
-                                        Either::Second(_) => {
-                                            error!("timeout");
-                                            break false;
+                                    let deadline = embassy_time::Instant::now() + embassy_time::Duration::from_secs(5);
+                                    let ok = loop {
+                                        match select(self.split_driver.read(), embassy_time::Timer::at(deadline)).await
+                                        {
+                                            Either::First(Ok(SplitMessage::FirmwareCrcOk)) => {
+                                                info!("dfu_split: central confirmed CRC, resetting");
+                                                break true;
+                                            }
+                                            Either::First(Ok(SplitMessage::FirmwareCrcFail)) => {
+                                                warn!("dfu_split: central rejected CRC, stopping update");
+                                                break false;
+                                            }
+                                            Either::First(Ok(_)) => {}
+                                            Either::First(Err(e)) => {
+                                                error!("read error: {:?}", e);
+                                                break false;
+                                            }
+                                            Either::Second(_) => {
+                                                error!("timeout");
+                                                break false;
+                                            }
                                         }
-                                    }
-                                };
+                                    };
 
-                                if ok {
-                                    self.split_driver.write(&SplitMessage::FirmwareUpdateConfirm).await.ok();
-                                    embassy_time::Timer::after_millis(50).await;
-                                    handler.mark_updated_and_reset().ok();
+                                    if ok {
+                                        self.split_driver.write(&SplitMessage::FirmwareUpdateConfirm).await.ok();
+                                        embassy_time::Timer::after_millis(50).await;
+                                        handler.mark_updated_and_reset().ok();
+                                    } else {
+                                        self.dfu_handler = None;
+                                    }
                                 } else {
-                                    self.dfu_handler = None;
+                                    error!("dfu_split: no active DFU session");
+                                }
+                            }
+                            // Forward application payloads;
+                            // drop-on-full so a slow consumer can never stall the
+                            // split read loop (the application resyncs on
+                            // reconnect and must tolerate loss).
+                            SplitMessage::Application(data) => {
+                                if crate::split_app::SPLIT_APP_RX.try_send(data).is_err() {
+                                    warn!("split app message dropped (inbox full)");
                                 }
-                            } else {
-                                error!("dfu_split: no active DFU session");
                             }
+                            _ => (),
                         }
-                        _ => (),
-                    },
+                    }
                     Err(e) => {
                         error!("Split message read error: {:?}", e);
                         if let crate::split::driver::SplitDriverError::Disconnected = e {
@@ -247,5 +304,8 @@ impl<S: SplitWriter + SplitReader> SplitPeripheral<S> {
                 }
             }
         }
+
+        // The loop only exits on disconnect.
+        app_link.send(false);
     }
 }
diff --git a/rmk/src/split_app.rs b/rmk/src/split_app.rs
new file mode 100644
index 000000000..7dc37f3dd
--- /dev/null
+++ b/rmk/src/split_app.rs
@@ -0,0 +1,124 @@
+//! Bounded application-message hook for the split protocol.
+//!
+//! A small, opaque, bounded payload that an application can send between the
+//! split central and its peripheral alongside — but never in front of — the
+//! normal split traffic. RMK itself attaches no meaning to the bytes; a
+//! firmware built on RMK can use it for application-level side-band state
+//! (for example, propagating lighting or UI state across the split link).
+//!
+//! Flow:
+//!
+//! - Central: the application queues [`SplitAppData`] into [`SPLIT_APP_TX`]
+//!   (bounded, `try_send` only — the queue must never be awaited full).
+//!   `PeripheralManager` drains it as one more (lowest-priority) arm of its
+//!   outgoing-message select and wraps each payload in
+//!   `SplitMessage::Application`. Peripheral→central key events always win:
+//!   they arrive on the read arm, which is polled first.
+//! - Peripheral: `SplitPeripheral` forwards received `Application` messages
+//!   into [`SPLIT_APP_RX`] with `try_send` (drop-on-full keeps the split read
+//!   loop responsive; the application is expected to tolerate loss, e.g. by
+//!   resyncing on reconnect).
+//! - Peripheral → central: the peripheral application queues
+//!   [`SplitAppData`] into [`SPLIT_APP_PERIPH_TX`] (bounded, `try_send`
+//!   only); `SplitPeripheral` drains it as one more outgoing arm of its
+//!   select, behind key events. The central's `PeripheralManager` forwards
+//!   received `Application` messages into [`SPLIT_APP_RX`] the same way the
+//!   peripheral does — the inbox is symmetric ("this side's received
+//!   application messages"), only the senders differ.
+//! - Both sides: [`SPLIT_APP_LINK`] carries the split-link state (central:
+//!   "peripheral link up"; peripheral: "central link up"), set by the split
+//!   driver. The central raises it at session start; the peripheral raises
+//!   it on the FIRST message received from the central — for BLE the bare
+//!   connection is not enough, since notifications to a central that has
+//!   not yet subscribed are silently dropped (see `split/peripheral.rs`).
+//!   Both lower it at session end. Applications use the `false → true` edge
+//!   to trigger an idempotent resync.
+//!
+//! Note: the queues assume a single split peripheral. Extending this hook to
+//! multiple peripherals would key them by peripheral id.
+
+use embassy_sync::channel::Channel;
+use embassy_sync::watch::Watch;
+use postcard::experimental::max_size::MaxSize;
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+
+use crate::RawMutex;
+
+/// Maximum payload of one application split message. Deliberately small:
+/// every split BLE transfer is `SPLIT_MESSAGE_MAX_SIZE` bytes on the wire,
+/// so this bound also taxes key-event messages. Hard cap: the trouble
+/// `gatt_service` macro initializes its characteristic arrays via
+/// `Default`, which arrays only implement up to 32 elements — so
+/// `SPLIT_MESSAGE_MAX_SIZE` (this + 1-byte length prefix + 1-byte enum
+/// discriminant + 4 bytes margin) must stay ≤ 32.
+pub const SPLIT_APP_MSG_MAX: usize = 26;
+
+/// One opaque application payload. Only `data[..len]` is meaningful.
+#[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub struct SplitAppData {
+    pub len: u8,
+    pub data: [u8; SPLIT_APP_MSG_MAX],
+}
+
+impl SplitAppData {
+    /// Wrap `payload`; `None` if it exceeds [`SPLIT_APP_MSG_MAX`].
+    pub fn new(payload: &[u8]) -> Option<Self> {
+        if payload.len() > SPLIT_APP_MSG_MAX {
+            return None;
+        }
+        let mut data = [0u8; SPLIT_APP_MSG_MAX];
+        data[..payload.len()].copy_from_slice(payload);
+        Some(Self {
+            len: payload.len() as u8,
+            data,
+        })
+    }
+
+    pub fn payload(&self) -> &[u8] {
+        &self.data[..(self.len as usize).min(SPLIT_APP_MSG_MAX)]
+    }
+}
+
+// Postcard stores the payload as `&[u8]` (varint length prefix + bytes), so
+// only the used bytes travel inside the (fixed-size) split transfer buffer.
+impl Serialize for SplitAppData {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        self.payload().serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for SplitAppData {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        use serde::de::Error;
+        let buf: &[u8] = Deserialize::deserialize(deserializer)?;
+        SplitAppData::new(buf).ok_or_else(|| D::Error::custom("split app message too long"))
+    }
+}
+
+impl MaxSize for SplitAppData {
+    // 1-byte varint length prefix + payload.
+    const POSTCARD_MAX_SIZE: usize = SPLIT_APP_MSG_MAX + 1;
+}
+
+/// Central → peripheral queue, drained by `PeripheralManager` while the link
+/// is up. Producers MUST use `try_send` (bounded, never block); capacity is
+/// sized so one full application resync burst fits with headroom.
+pub static SPLIT_APP_TX: Channel<RawMutex, SplitAppData, 26> = Channel::new();
+
+/// This side's inbox of received application messages (peripheral: from the
+/// central's `SPLIT_APP_TX`; central: from the peripheral's
+/// `SPLIT_APP_PERIPH_TX`). Filled with `try_send` (drop-on-full) by the
+/// split read loops.
+pub static SPLIT_APP_RX: Channel<RawMutex, SplitAppData, 8> = Channel::new();
+
+/// Peripheral → central queue, drained by `SplitPeripheral` while the link
+/// is up. Producers MUST use `try_send`. Small: the application announces
+/// tiny, rare state (e.g. its build identity once per link-up).
+pub static SPLIT_APP_PERIPH_TX: Channel<RawMutex, SplitAppData, 2> = Channel::new();
+
+/// Split-link state for the application: on the central, "peripheral link
+/// up"; on the peripheral, "central link up". Written by the split driver at
+/// session start/end; state-based (a late receiver still observes the latest
+/// value), so edges cannot be lost the way pub/sub events can.
+pub static SPLIT_APP_LINK: Watch<RawMutex, bool, 2> = Watch::new();

From a1ce157734066e9873b86cb929c110ca0cfa89c7 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 10:25:25 -0700
Subject: [PATCH 02/78] feat(lighting): add topology-aware lighting system

---
 .../src/default_config/event_default.toml     |    6 +
 .../default_config/subscriber_default.toml    |   13 +
 rmk-config/src/layout.rs                      |  101 ++
 rmk-config/src/lib.rs                         |  143 +++
 rmk-config/src/resolved/build_constants.rs    |   13 +-
 rmk-config/src/resolved/layout.rs             |   57 +-
 rmk-config/src/resolved/lighting.rs           |  632 ++++++++++
 rmk-config/src/resolved/mod.rs                |    4 +-
 rmk-macro/src/codegen/lighting.rs             |  405 +++++++
 rmk-macro/src/codegen/mod.rs                  |    1 +
 rmk-macro/src/codegen/orchestrator.rs         |  101 +-
 rmk-types/Cargo.toml                          |    3 +-
 rmk/Cargo.toml                                |    6 +-
 rmk/src/ble/battery_service.rs                |    5 +-
 rmk/src/ble/sleep.rs                          |   29 +-
 rmk/src/display/mod.rs                        |   15 +
 rmk/src/event/mod.rs                          |    2 +-
 rmk/src/event/state.rs                        |   15 +
 rmk/src/hid.rs                                |    4 +-
 rmk/src/keyboard.rs                           |   13 +
 rmk/src/lib.rs                                |    3 +
 rmk/src/lighting/color.rs                     |   26 +
 rmk/src/lighting/compositor.rs                |  309 +++++
 rmk/src/lighting/context.rs                   |   74 ++
 rmk/src/lighting/effect.rs                    |  247 ++++
 rmk/src/lighting/mod.rs                       |   59 +
 rmk/src/lighting/output.rs                    |  583 +++++++++
 rmk/src/lighting/processor.rs                 |  358 ++++++
 rmk/src/lighting/rmk_state.rs                 |   67 ++
 rmk/src/lighting/selector.rs                  |  216 ++++
 rmk/src/lighting/service.rs                   | 1045 +++++++++++++++++
 rmk/src/lighting/source.rs                    |  527 +++++++++
 rmk/src/lighting/standard.rs                  |  975 +++++++++++++++
 rmk/src/lighting/topology.rs                  |  668 +++++++++++
 rmk/src/physical_layout.rs                    |  135 +++
 rmk/src/split/driver.rs                       |    4 +-
 rmk/src/split/mod.rs                          |    2 +-
 rmk/src/split/peripheral.rs                   |   12 +-
 rmk/src/state.rs                              |   38 +-
 39 files changed, 6840 insertions(+), 76 deletions(-)
 create mode 100644 rmk-config/src/resolved/lighting.rs
 create mode 100644 rmk-macro/src/codegen/lighting.rs
 create mode 100644 rmk/src/lighting/color.rs
 create mode 100644 rmk/src/lighting/compositor.rs
 create mode 100644 rmk/src/lighting/context.rs
 create mode 100644 rmk/src/lighting/effect.rs
 create mode 100644 rmk/src/lighting/mod.rs
 create mode 100644 rmk/src/lighting/output.rs
 create mode 100644 rmk/src/lighting/processor.rs
 create mode 100644 rmk/src/lighting/rmk_state.rs
 create mode 100644 rmk/src/lighting/selector.rs
 create mode 100644 rmk/src/lighting/service.rs
 create mode 100644 rmk/src/lighting/source.rs
 create mode 100644 rmk/src/lighting/standard.rs
 create mode 100644 rmk/src/lighting/topology.rs
 create mode 100644 rmk/src/physical_layout.rs

diff --git a/rmk-config/src/default_config/event_default.toml b/rmk-config/src/default_config/event_default.toml
index e6d054cfb..0c81357a3 100644
--- a/rmk-config/src/default_config/event_default.toml
+++ b/rmk-config/src/default_config/event_default.toml
@@ -39,6 +39,12 @@ channel_size = 1
 pubs = 1
 subs = 1
 
+# Unit invalidation published after authoritative lighting state changes.
+[event.lighting_changed]
+channel_size = 1
+pubs = 1
+subs = 1
+
 # Power events
 [event.battery_status]
 channel_size = 1
diff --git a/rmk-config/src/default_config/subscriber_default.toml b/rmk-config/src/default_config/subscriber_default.toml
index 4c6824616..e9182c264 100644
--- a/rmk-config/src/default_config/subscriber_default.toml
+++ b/rmk-config/src/default_config/subscriber_default.toml
@@ -68,6 +68,12 @@ events = [
     { name = "led_indicator" },
 ]
 
+[[subscriber]]
+features = ["rynk", "lighting"]
+events = [
+    { name = "lighting_changed" },
+]
+
 [[subscriber]]
 features = ["rynk", "_ble"]
 events = [
@@ -82,6 +88,13 @@ events = [
     { name = "led_indicator" },
 ]
 
+[[subscriber]]
+features = ["rynk", "lighting", "_ble"]
+events = [
+    # Second Rynk session slot on dual-transport boards.
+    { name = "lighting_changed" },
+]
+
 # --- Split-gated internal subscribers ---
 
 [[subscriber]]
diff --git a/rmk-config/src/layout.rs b/rmk-config/src/layout.rs
index 275b2aaf8..cbcd79d6a 100644
--- a/rmk-config/src/layout.rs
+++ b/rmk-config/src/layout.rs
@@ -113,6 +113,12 @@ impl LayoutInfo {
     }
 }
 
+pub(crate) struct ResolvedLayout {
+    pub blob: Vec<u8>,
+    pub keys: Vec<[u8; 2]>,
+    pub physical: crate::resolved::PhysicalLayout,
+}
+
 /// A resolved shape: every default applied. `rect2` is the L-key's second
 /// rectangle stored as center-relative offsets — its `x`/`y` are offsets from
 /// the primary center, not absolute positions (the walk resolves them).
@@ -668,6 +674,101 @@ pub(crate) fn build_layout_blob(
     Ok(miniz_oxide::deflate::compress_to_vec(&bytes, 10))
 }
 
+/// Resolve both host-facing KLE data and the compact firmware geometry from
+/// one parse/walk. This keeps `[layout].map` the only board-layout authority.
+pub(crate) fn build_resolved_layout(
+    layout: &LayoutTomlConfig,
+    expected_encoders: Option<usize>,
+) -> Result<ResolvedLayout, String> {
+    let Some(info) = build_layout_info(layout, expected_encoders)? else {
+        return Ok(ResolvedLayout {
+            blob: Vec::new(),
+            keys: Vec::new(),
+            physical: crate::resolved::PhysicalLayout::default(),
+        });
+    };
+
+    let bytes =
+        postcard::to_allocvec(&info).map_err(|e| format!("keyboard.toml: layout blob serialize failed: {e}"))?;
+    let blob = miniz_oxide::deflate::compress_to_vec(&bytes, 10);
+    let keys = parse_map(layout.map.as_deref().unwrap_or_default(), layout.rows, layout.cols)?
+        .into_iter()
+        .filter_map(|token| match token {
+            MapToken::Key { row, col, .. } => Some([row, col]),
+            _ => None,
+        })
+        .collect();
+    let variant = &info.variants[info.default_variant as usize];
+    let physical = crate::resolved::PhysicalLayout {
+        keys: variant
+            .keys
+            .iter()
+            .map(|key| {
+                let center = fixed_point(key.rect.x, key.rect.y)
+                    .map_err(|reason| format!("layout.map key ({},{}) center {reason}", key.row, key.col))?;
+                let size = fixed_size(key.rect.w, key.rect.h)
+                    .map_err(|reason| format!("layout.map key ({},{}) size {reason}", key.row, key.col))?;
+                let rotation_centidegrees = centidegrees(key.r)
+                    .map_err(|reason| format!("layout.map key ({},{}) rotation {reason}", key.row, key.col))?;
+                Ok(crate::resolved::PhysicalKey {
+                    matrix: [key.row, key.col],
+                    center,
+                    size,
+                    rotation_centidegrees,
+                })
+            })
+            .collect::<Result<Vec<_>, String>>()?,
+    };
+
+    Ok(ResolvedLayout { blob, keys, physical })
+}
+
+fn fixed_point(x: f32, y: f32) -> Result<crate::resolved::FixedPoint3, &'static str> {
+    fn axis(value: f32) -> Result<i16, &'static str> {
+        if !value.is_finite() {
+            return Err("must be finite");
+        }
+        let raw = (value * 256.0).round();
+        if raw < i16::MIN as f32 || raw > i16::MAX as f32 {
+            return Err("does not fit signed Q8.8 key-pitch units");
+        }
+        Ok(raw as i16)
+    }
+    Ok(crate::resolved::FixedPoint3 {
+        x: axis(x)?,
+        y: axis(y)?,
+        z: 0,
+    })
+}
+
+fn fixed_size(width: f32, height: f32) -> Result<crate::resolved::FixedSize2, &'static str> {
+    fn axis(value: f32) -> Result<u16, &'static str> {
+        if !value.is_finite() || value <= 0.0 {
+            return Err("must be finite and positive");
+        }
+        let raw = (value * 256.0).round();
+        if raw < 1.0 || raw > u16::MAX as f32 {
+            return Err("does not fit unsigned Q8.8 key-pitch units");
+        }
+        Ok(raw as u16)
+    }
+    Ok(crate::resolved::FixedSize2 {
+        width: axis(width)?,
+        height: axis(height)?,
+    })
+}
+
+fn centidegrees(degrees: f32) -> Result<i16, &'static str> {
+    if !degrees.is_finite() {
+        return Err("must be finite");
+    }
+    let raw = (degrees * 100.0).round();
+    if raw < i16::MIN as f32 || raw > i16::MAX as f32 {
+        return Err("does not fit signed centidegrees");
+    }
+    Ok(raw as i16)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/rmk-config/src/lib.rs b/rmk-config/src/lib.rs
index d858da563..882e34790 100644
--- a/rmk-config/src/lib.rs
+++ b/rmk-config/src/lib.rs
@@ -89,6 +89,9 @@ pub struct KeyboardTomlConfig {
     /// Layout config: the physical key arrangement (`map`) plus the rendered layout.
     /// For split keyboards, the total row/col is defined in this section.
     layout: Option<LayoutTomlConfig>,
+    /// Topology-aware lighting. Key geometry is always derived from
+    /// `[layout].map`; emitters add semantic identity and electrical routing.
+    lighting: Option<LightingTomlConfig>,
     /// Behavior config
     behavior: Option<BehaviorConfig>,
     /// Light config
@@ -466,6 +469,7 @@ define_event_config!(
     wpm_update,
     led_indicator,
     sleep_state,
+    lighting_changed,
     // Power events
     battery_status,
     battery_adc,
@@ -526,6 +530,141 @@ pub(crate) struct VariantToml {
     pub hidden: Option<Vec<String>>,
 }
 
+#[derive(Clone, Debug, Default, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingTomlConfig {
+    #[serde(default = "default_topology_revision")]
+    pub topology_revision: u32,
+    #[serde(default, rename = "zone")]
+    pub zones: Vec<LightingZoneTomlConfig>,
+    #[serde(default, rename = "output")]
+    pub outputs: Vec<LightingOutputTomlConfig>,
+    #[serde(default, rename = "emitter")]
+    pub emitters: Vec<LightingEmitterTomlConfig>,
+    #[serde(default, rename = "layer_scene")]
+    pub layer_scenes: Vec<LightingLayerSceneTomlConfig>,
+    pub background: Option<LightingBackgroundTomlConfig>,
+}
+
+fn default_topology_revision() -> u32 {
+    1
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingZoneTomlConfig {
+    pub id: u8,
+    pub name: String,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingOutputTomlConfig {
+    pub node: u8,
+    pub id: u8,
+    pub pixel_count: u16,
+    pub capabilities: Vec<String>,
+    #[serde(default)]
+    pub sparse: bool,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingEmitterTomlConfig {
+    pub id: u16,
+    pub key: Option<[u8; 2]>,
+    pub position: Option<[f32; 3]>,
+    #[serde(default)]
+    pub zones: Vec<u8>,
+    pub node: u8,
+    pub output: u8,
+    pub physical_index: u16,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingLayerSceneTomlConfig {
+    pub layer: u8,
+    #[serde(default, rename = "cell")]
+    pub cells: Vec<LightingSceneCellTomlConfig>,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingSceneCellTomlConfig {
+    pub target: LightingTargetTomlConfig,
+    pub effect: LightingEffectTomlConfig,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(untagged)]
+pub(crate) enum LightingTargetTomlConfig {
+    Led { led: u16 },
+    Key { key: [u8; 2] },
+    Zone { zone: u8 },
+    All { all: bool },
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+pub(crate) enum LightingEffectTomlConfig {
+    Solid {
+        color: [u8; 3],
+    },
+    Blink {
+        color: [u8; 3],
+        period_ms: u32,
+        #[serde(default)]
+        phase_ms: u32,
+        duty_percent: u8,
+    },
+    Breathe {
+        color: [u8; 3],
+        period_ms: u32,
+        #[serde(default)]
+        phase_ms: u32,
+        #[serde(default = "default_breathe_step_ms")]
+        step_ms: u16,
+    },
+}
+
+fn default_breathe_step_ms() -> u16 {
+    16
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingBackgroundTomlConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
+    #[serde(default)]
+    pub hue: u8,
+    #[serde(default)]
+    pub saturation: u8,
+    #[serde(default = "default_background_value")]
+    pub value: u8,
+    #[serde(default = "default_background_speed")]
+    pub speed: u8,
+    #[serde(default)]
+    pub mode: LightingBackgroundModeToml,
+}
+
+fn default_background_value() -> u8 {
+    32
+}
+
+fn default_background_speed() -> u8 {
+    128
+}
+
+#[derive(Clone, Copy, Debug, Default, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum LightingBackgroundModeToml {
+    #[default]
+    Solid,
+    Breathe,
+}
+
 /// The `[keymap]` section: layer count plus the per-layer key actions.
 #[derive(Clone, Debug, Default, Deserialize)]
 #[serde(deny_unknown_fields)]
@@ -1434,6 +1573,10 @@ mod tests {
         assert_eq!(config.led_indicator.pubs, 2);
         assert_eq!(config.led_indicator.subs, 3);
 
+        assert_eq!(config.lighting_changed.channel_size, 1);
+        assert_eq!(config.lighting_changed.pubs, 1);
+        assert_eq!(config.lighting_changed.subs, 1);
+
         assert_eq!(config.pointing.channel_size, 8);
         assert_eq!(config.pointing.subs, 2);
 
diff --git a/rmk-config/src/resolved/build_constants.rs b/rmk-config/src/resolved/build_constants.rs
index 7c4ef3f54..3274333b9 100644
--- a/rmk-config/src/resolved/build_constants.rs
+++ b/rmk-config/src/resolved/build_constants.rs
@@ -105,6 +105,7 @@ impl crate::KeyboardTomlConfig {
             wpm_update,
             led_indicator,
             sleep_state,
+            lighting_changed,
             battery_status,
             battery_adc,
             charging_state,
@@ -267,7 +268,9 @@ mod tests {
     #[test]
     fn reserves_led_subscribers_for_display_split_and_dual_rynk_sessions() {
         let config: KeyboardTomlConfig = toml::from_str("").unwrap();
-        let constants = config.build_constants(&["display", "split", "rynk", "_ble"]).unwrap();
+        let constants = config
+            .build_constants(&["display", "split", "rynk", "lighting", "_ble"])
+            .unwrap();
         let led_indicator = constants
             .events
             .iter()
@@ -276,6 +279,14 @@ mod tests {
 
         // Three indicator processors, the display, two split peripherals, and USB/BLE Rynk sessions.
         assert_eq!(led_indicator.subs, 8);
+
+        let lighting_changed = constants
+            .events
+            .iter()
+            .find(|event| event.name == "lighting_changed")
+            .unwrap();
+        // One public subscriber plus USB and BLE Rynk sessions.
+        assert_eq!(lighting_changed.subs, 3);
     }
 
     #[test]
diff --git a/rmk-config/src/resolved/layout.rs b/rmk-config/src/resolved/layout.rs
index dbdb32416..0f860cfd4 100644
--- a/rmk-config/src/resolved/layout.rs
+++ b/rmk-config/src/resolved/layout.rs
@@ -1,16 +1,61 @@
-/// Resolved physical layout: the compressed, opaque blob the firmware streams
-/// verbatim over `GetLayout`. Empty when there's no `[layout].map`.
+/// Signed Q8.8 board-space point in key-pitch units.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct FixedPoint3 {
+    pub x: i16,
+    pub y: i16,
+    pub z: i16,
+}
+
+/// Unsigned Q8.8 key size in key-pitch units.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct FixedSize2 {
+    pub width: u16,
+    pub height: u16,
+}
+
+/// Fixed-point geometry for one key in the selected/default KLE variant.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct PhysicalKey {
+    pub matrix: [u8; 2],
+    pub center: FixedPoint3,
+    pub size: FixedSize2,
+    /// Clockwise rotation in hundredths of one degree.
+    pub rotation_centidegrees: i16,
+}
+
+#[derive(Clone, Debug, Default, Eq, PartialEq)]
+pub struct PhysicalLayout {
+    pub keys: Vec<PhysicalKey>,
+}
+
+/// Resolved physical layout. `blob` preserves the complete variant-aware KLE
+/// representation streamed over `GetLayout`; `physical` is the allocation-free
+/// firmware geometry derived from its selected/default variant. `keys` is the
+/// variant-independent set of logical matrix positions from `[layout].map`.
 pub struct Layout {
     pub blob: Vec<u8>,
+    pub rows: u8,
+    pub cols: u8,
+    pub keys: Vec<[u8; 2]>,
+    pub physical: PhysicalLayout,
 }
 
 impl crate::KeyboardTomlConfig {
     /// Resolve the physical layout blob from the `[layout]` section.
     pub fn layout(&self) -> Result<Layout, String> {
-        let blob = match &self.layout {
-            Some(l) => crate::layout::build_layout_blob(l, Some(self.total_encoders()))?,
-            None => Vec::new(),
+        let (blob, keys, physical, rows, cols) = match &self.layout {
+            Some(l) => {
+                let resolved = crate::layout::build_resolved_layout(l, Some(self.total_encoders()))?;
+                (resolved.blob, resolved.keys, resolved.physical, l.rows, l.cols)
+            }
+            None => (Vec::new(), Vec::new(), PhysicalLayout::default(), 0, 0),
         };
-        Ok(Layout { blob })
+        Ok(Layout {
+            blob,
+            rows,
+            cols,
+            keys,
+            physical,
+        })
     }
 }
diff --git a/rmk-config/src/resolved/lighting.rs b/rmk-config/src/resolved/lighting.rs
new file mode 100644
index 000000000..30f9a9eab
--- /dev/null
+++ b/rmk-config/src/resolved/lighting.rs
@@ -0,0 +1,632 @@
+use std::collections::{HashMap, HashSet};
+
+use crate::{LightingBackgroundModeToml, LightingEffectTomlConfig, LightingTargetTomlConfig};
+
+use super::Keymap;
+use super::layout::{FixedPoint3, Layout};
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct LightingKey {
+    pub matrix: [u8; 2],
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct LightingZone {
+    pub id: u8,
+    pub name: String,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LightingEmitter {
+    pub id: u16,
+    pub key: Option<[u8; 2]>,
+    pub position: Option<FixedPoint3>,
+    pub zone_start: u16,
+    pub zone_len: u8,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LightingOutput {
+    pub node: u8,
+    pub id: u8,
+    pub pixel_count: u16,
+    pub capabilities: u8,
+    pub sparse: bool,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LightingRoute {
+    pub slot: u16,
+    pub node: u8,
+    pub output: u8,
+    pub physical_index: u16,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum LightingEffect {
+    Solid {
+        color: [u8; 3],
+    },
+    Blink {
+        color: [u8; 3],
+        period_ms: u32,
+        phase_ms: u32,
+        duty_percent: u8,
+    },
+    Breathe {
+        color: [u8; 3],
+        period_ms: u32,
+        phase_ms: u32,
+        step_ms: u16,
+    },
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LightingSceneCell {
+    pub slot: u16,
+    pub effect: LightingEffect,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct LightingLayerScene {
+    pub layer: u8,
+    pub cells: Vec<LightingSceneCell>,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum LightingBackgroundMode {
+    Solid,
+    Breathe,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LightingBackground {
+    pub enabled: bool,
+    pub hue: u8,
+    pub saturation: u8,
+    pub value: u8,
+    pub speed: u8,
+    pub mode: LightingBackgroundMode,
+}
+
+impl Default for LightingBackground {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            hue: 0,
+            saturation: 0,
+            value: 32,
+            speed: 128,
+            mode: LightingBackgroundMode::Solid,
+        }
+    }
+}
+
+/// Fully validated build-time lighting data. Key identities and fallback key
+/// geometry come from the already-resolved `[layout].map`; emitters and routes
+/// add semantic and electrical topology without redefining the board layout.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct Lighting {
+    pub topology_revision: u32,
+    pub matrix: [u8; 2],
+    pub keys: Vec<LightingKey>,
+    pub zones: Vec<LightingZone>,
+    pub emitters: Vec<LightingEmitter>,
+    pub zone_memberships: Vec<u8>,
+    pub outputs: Vec<LightingOutput>,
+    pub routes: Vec<LightingRoute>,
+    pub layer_scenes: Vec<LightingLayerScene>,
+    pub background: LightingBackground,
+}
+
+impl crate::KeyboardTomlConfig {
+    pub fn lighting(&self, layout: &Layout, keymap: &Keymap) -> Result<Option<Lighting>, String> {
+        let Some(config) = &self.lighting else {
+            return Ok(None);
+        };
+        if layout.keys.is_empty() {
+            return Err("[lighting] requires `[layout].map` as the canonical logical key layout".into());
+        }
+        if config.emitters.is_empty() {
+            return Err("[lighting] must define at least one [[lighting.emitter]]".into());
+        }
+        if config.emitters.len() > u16::MAX as usize {
+            return Err("[lighting] emitter count exceeds LedSlot u16 capacity".into());
+        }
+
+        let zones = resolve_zones(&config.zones)?;
+        let zone_ids: HashSet<u8> = zones.iter().map(|zone| zone.id).collect();
+        let mut emitter_ids = HashSet::new();
+        let mut zone_memberships = Vec::new();
+        let mut emitters = Vec::with_capacity(config.emitters.len());
+        let mut routes = Vec::with_capacity(config.emitters.len());
+        for (slot, emitter) in config.emitters.iter().enumerate() {
+            if !emitter_ids.insert(emitter.id) {
+                return Err(format!("duplicate lighting emitter id {}", emitter.id));
+            }
+            if let Some(key) = emitter.key
+                && !layout.keys.contains(&key)
+            {
+                return Err(format!(
+                    "lighting emitter {} key [{}, {}] is not a logical key in layout.map",
+                    emitter.id, key[0], key[1]
+                ));
+            }
+            let mut local_zones = HashSet::new();
+            for zone in &emitter.zones {
+                if !zone_ids.contains(zone) {
+                    return Err(format!(
+                        "lighting emitter {} references unknown zone {zone}",
+                        emitter.id
+                    ));
+                }
+                if !local_zones.insert(*zone) {
+                    return Err(format!("lighting emitter {} repeats zone {zone}", emitter.id));
+                }
+            }
+            if emitter.zones.len() > u8::MAX as usize
+                || zone_memberships.len() + emitter.zones.len() > u16::MAX as usize
+            {
+                return Err("lighting zone membership table exceeds bounded representation".into());
+            }
+            let zone_start = zone_memberships.len() as u16;
+            zone_memberships.extend_from_slice(&emitter.zones);
+            emitters.push(LightingEmitter {
+                id: emitter.id,
+                key: emitter.key,
+                position: emitter
+                    .position
+                    .map(to_fixed_point)
+                    .transpose()
+                    .map_err(str::to_owned)?,
+                zone_start,
+                zone_len: emitter.zones.len() as u8,
+            });
+            routes.push(LightingRoute {
+                slot: slot as u16,
+                node: emitter.node,
+                output: emitter.output,
+                physical_index: emitter.physical_index,
+            });
+        }
+
+        let outputs = resolve_outputs(&config.outputs)?;
+        validate_routes(&outputs, &routes)?;
+        let layer_scenes = resolve_layer_scenes(
+            keymap.layers,
+            &config.layer_scenes,
+            &emitters,
+            &zone_memberships,
+            &zone_ids,
+        )?;
+        let background = config
+            .background
+            .as_ref()
+            .map(|background| LightingBackground {
+                enabled: background.enabled,
+                hue: background.hue,
+                saturation: background.saturation,
+                value: background.value,
+                speed: background.speed,
+                mode: match background.mode {
+                    LightingBackgroundModeToml::Solid => LightingBackgroundMode::Solid,
+                    LightingBackgroundModeToml::Breathe => LightingBackgroundMode::Breathe,
+                },
+            })
+            .unwrap_or_default();
+
+        Ok(Some(Lighting {
+            topology_revision: config.topology_revision,
+            matrix: [layout.rows, layout.cols],
+            keys: layout
+                .keys
+                .iter()
+                .copied()
+                .map(|matrix| LightingKey { matrix })
+                .collect(),
+            zones,
+            emitters,
+            zone_memberships,
+            outputs,
+            routes,
+            layer_scenes,
+            background,
+        }))
+    }
+}
+
+fn to_fixed_point(point: [f32; 3]) -> Result<FixedPoint3, &'static str> {
+    fn axis(value: f32) -> Result<i16, &'static str> {
+        if !value.is_finite() {
+            return Err("must contain finite coordinates");
+        }
+        let raw = (value * 256.0).round();
+        if raw < i16::MIN as f32 || raw > i16::MAX as f32 {
+            return Err("does not fit signed Q8.8 key-pitch units");
+        }
+        Ok(raw as i16)
+    }
+    Ok(FixedPoint3 {
+        x: axis(point[0])?,
+        y: axis(point[1])?,
+        z: axis(point[2])?,
+    })
+}
+
+fn resolve_zones(config: &[crate::LightingZoneTomlConfig]) -> Result<Vec<LightingZone>, String> {
+    let mut ids = HashSet::new();
+    let mut names = HashSet::new();
+    config
+        .iter()
+        .map(|zone| {
+            if !ids.insert(zone.id) {
+                return Err(format!("duplicate lighting zone id {}", zone.id));
+            }
+            if zone.name.is_empty() || !names.insert(zone.name.clone()) {
+                return Err(format!("duplicate or empty lighting zone name {:?}", zone.name));
+            }
+            Ok(LightingZone {
+                id: zone.id,
+                name: zone.name.clone(),
+            })
+        })
+        .collect()
+}
+
+fn resolve_outputs(config: &[crate::LightingOutputTomlConfig]) -> Result<Vec<LightingOutput>, String> {
+    let mut ids = HashSet::new();
+    config
+        .iter()
+        .map(|output| {
+            if !ids.insert((output.node, output.id)) {
+                return Err(format!(
+                    "duplicate lighting output node {} id {}",
+                    output.node, output.id
+                ));
+            }
+            if output.pixel_count == 0 {
+                return Err(format!(
+                    "lighting output node {} id {} has zero pixels",
+                    output.node, output.id
+                ));
+            }
+            let mut capabilities = 0u8;
+            for capability in &output.capabilities {
+                let bit = match capability.as_str() {
+                    "binary" => 1 << 0,
+                    "intensity" => 1 << 1,
+                    "rgb" => 1 << 2,
+                    "white" => 1 << 3,
+                    "rgbw" => (1 << 2) | (1 << 3),
+                    "addressable" => 1 << 4,
+                    other => return Err(format!("unknown lighting output capability {other:?}")),
+                };
+                if capabilities & bit != 0 {
+                    return Err(format!(
+                        "lighting output node {} id {} repeats capability {capability:?}",
+                        output.node, output.id
+                    ));
+                }
+                capabilities |= bit;
+            }
+            if capabilities & 0b1111 == 0 {
+                return Err(format!(
+                    "lighting output node {} id {} has no color capability",
+                    output.node, output.id
+                ));
+            }
+            Ok(LightingOutput {
+                node: output.node,
+                id: output.id,
+                pixel_count: output.pixel_count,
+                capabilities,
+                sparse: output.sparse,
+            })
+        })
+        .collect()
+}
+
+fn validate_routes(outputs: &[LightingOutput], routes: &[LightingRoute]) -> Result<(), String> {
+    let output_map: HashMap<(u8, u8), &LightingOutput> = outputs
+        .iter()
+        .map(|output| ((output.node, output.id), output))
+        .collect();
+    let mut addresses = HashSet::new();
+    for route in routes {
+        let Some(output) = output_map.get(&(route.node, route.output)) else {
+            return Err(format!(
+                "lighting slot {} routes to unknown node {} output {}",
+                route.slot, route.node, route.output
+            ));
+        };
+        if route.physical_index >= output.pixel_count {
+            return Err(format!(
+                "lighting slot {} physical index {} is outside node {} output {} length {}",
+                route.slot, route.physical_index, route.node, route.output, output.pixel_count
+            ));
+        }
+        if !addresses.insert((route.node, route.output, route.physical_index)) {
+            return Err(format!(
+                "duplicate lighting physical route node {} output {} index {}",
+                route.node, route.output, route.physical_index
+            ));
+        }
+    }
+    for output in outputs.iter().filter(|output| !output.sparse) {
+        for physical_index in 0..output.pixel_count {
+            if !addresses.contains(&(output.node, output.id, physical_index)) {
+                return Err(format!(
+                    "complete lighting output node {} id {} has hole at index {}",
+                    output.node, output.id, physical_index
+                ));
+            }
+        }
+    }
+    Ok(())
+}
+
+fn resolve_layer_scenes(
+    layer_count: u8,
+    config: &[crate::LightingLayerSceneTomlConfig],
+    emitters: &[LightingEmitter],
+    zone_memberships: &[u8],
+    zone_ids: &HashSet<u8>,
+) -> Result<Vec<LightingLayerScene>, String> {
+    let id_to_slot: HashMap<u16, u16> = emitters
+        .iter()
+        .enumerate()
+        .map(|(slot, emitter)| (emitter.id, slot as u16))
+        .collect();
+    let mut scenes = Vec::with_capacity(config.len());
+    for scene in config {
+        if scene.layer >= layer_count {
+            return Err(format!(
+                "lighting layer scene {} is outside configured layer count {}",
+                scene.layer, layer_count
+            ));
+        }
+        if scene.cells.is_empty() {
+            return Err(format!("lighting layer scene {} has no cells", scene.layer));
+        }
+        let mut cells = Vec::new();
+        for cell in &scene.cells {
+            let slots: Vec<u16> = match cell.target {
+                LightingTargetTomlConfig::Led { led } => vec![
+                    *id_to_slot
+                        .get(&led)
+                        .ok_or_else(|| format!("lighting scene references unknown emitter id {led}"))?,
+                ],
+                LightingTargetTomlConfig::Key { key } => emitters
+                    .iter()
+                    .enumerate()
+                    .filter(|(_, emitter)| emitter.key == Some(key))
+                    .map(|(slot, _)| slot as u16)
+                    .collect(),
+                LightingTargetTomlConfig::Zone { zone } => {
+                    if !zone_ids.contains(&zone) {
+                        return Err(format!("lighting scene references unknown zone {zone}"));
+                    }
+                    emitters
+                        .iter()
+                        .enumerate()
+                        .filter(|(_, emitter)| {
+                            let start = emitter.zone_start as usize;
+                            let end = start + emitter.zone_len as usize;
+                            zone_memberships[start..end].contains(&zone)
+                        })
+                        .map(|(slot, _)| slot as u16)
+                        .collect()
+                }
+                LightingTargetTomlConfig::All { all: true } => (0..emitters.len() as u16).collect(),
+                LightingTargetTomlConfig::All { all: false } => {
+                    return Err("lighting target `{ all = false }` is invalid".into());
+                }
+            };
+            if slots.is_empty() {
+                return Err(format!(
+                    "lighting layer scene {} target resolves to no emitters",
+                    scene.layer
+                ));
+            }
+            let effect = resolve_effect(&cell.effect)?;
+            cells.extend(slots.into_iter().map(|slot| LightingSceneCell { slot, effect }));
+        }
+        scenes.push(LightingLayerScene {
+            layer: scene.layer,
+            cells,
+        });
+    }
+    Ok(scenes)
+}
+
+fn resolve_effect(config: &LightingEffectTomlConfig) -> Result<LightingEffect, String> {
+    Ok(match *config {
+        LightingEffectTomlConfig::Solid { color } => LightingEffect::Solid { color },
+        LightingEffectTomlConfig::Blink {
+            color,
+            period_ms,
+            phase_ms,
+            duty_percent,
+        } => {
+            if period_ms == 0 {
+                return Err("blink period_ms must be greater than zero".into());
+            }
+            if duty_percent > 100 {
+                return Err(format!("blink duty_percent {duty_percent} exceeds 100"));
+            }
+            LightingEffect::Blink {
+                color,
+                period_ms,
+                phase_ms,
+                duty_percent,
+            }
+        }
+        LightingEffectTomlConfig::Breathe {
+            color,
+            period_ms,
+            phase_ms,
+            step_ms,
+        } => {
+            if period_ms < 2 {
+                return Err("breathe period_ms must be at least two".into());
+            }
+            if step_ms == 0 || u32::from(step_ms) >= period_ms {
+                return Err(format!(
+                    "breathe step_ms {step_ms} must be greater than zero and less than period_ms {period_ms}"
+                ));
+            }
+            LightingEffect::Breathe {
+                color,
+                period_ms,
+                phase_ms,
+                step_ms,
+            }
+        }
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    fn parse(config: &str) -> crate::KeyboardTomlConfig {
+        toml::from_str(config).unwrap()
+    }
+
+    const BASE: &str = r#"
+[matrix]
+row_pins = ["r0"]
+col_pins = ["c0", "c1"]
+
+[layout]
+rows = 1
+cols = 2
+map = "(0,0,@wide) (0,1)"
+
+[layout.shapes]
+wide = { w = 1.5, r = -7.5 }
+
+[keymap]
+layers = 2
+[[keymap.layer]]
+keys = "A B"
+[[keymap.layer]]
+keys = "A B"
+
+[lighting]
+topology_revision = 7
+[[lighting.zone]]
+id = 1
+name = "keys"
+[[lighting.output]]
+node = 0
+id = 0
+pixel_count = 2
+capabilities = ["rgb", "addressable"]
+[[lighting.emitter]]
+id = 10
+key = [0, 0]
+zones = [1]
+node = 0
+output = 0
+physical_index = 1
+[[lighting.emitter]]
+id = 20
+key = [0, 1]
+position = [1.0, 0.0, 0.25]
+zones = [1]
+node = 0
+output = 0
+physical_index = 0
+[[lighting.layer_scene]]
+layer = 1
+[[lighting.layer_scene.cell]]
+target = { zone = 1 }
+effect = { kind = "solid", color = [1, 2, 3] }
+"#;
+
+    #[test]
+    fn derives_geometry_and_logical_keys_from_layout_map() {
+        let config = parse(BASE);
+        let layout = config.layout().unwrap();
+        let keymap = config.keymap().unwrap();
+        assert_eq!(layout.keys, vec![[0, 0], [0, 1]]);
+        assert_eq!(layout.physical.keys[0].size.width, 384);
+        assert_eq!(layout.physical.keys[0].rotation_centidegrees, -750);
+        let lighting = config.lighting(&layout, &keymap).unwrap().unwrap();
+        assert_eq!(lighting.keys.len(), 2);
+        assert_eq!(lighting.emitters.len(), 2);
+        assert_eq!(lighting.routes[0].physical_index, 1);
+        assert_eq!(lighting.layer_scenes[0].cells.len(), 2);
+    }
+
+    #[test]
+    fn rejects_emitter_key_that_is_only_inside_matrix_bounds() {
+        let hole = BASE
+            .replace("col_pins = [\"c0\", \"c1\"]", "col_pins = [\"c0\", \"c1\", \"c2\"]")
+            .replace("cols = 2", "cols = 3")
+            .replace("(0,1)", "(0,2)");
+        let config = parse(&hole);
+        let layout = config.layout().unwrap();
+        let keymap = config.keymap().unwrap();
+        let error = config.lighting(&layout, &keymap).unwrap_err();
+        assert!(error.contains("not a logical key in layout.map"), "{error}");
+    }
+
+    #[test]
+    fn hidden_default_variant_key_remains_a_logical_emitter_key_without_geometry() {
+        let source = BASE.replace(
+            "map = \"(0,0,@wide) (0,1)\"",
+            r#"map = "(0,0,@wide) (0,1)"
+default_variant = "compact"
+[[layout.variant]]
+name = "full"
+[[layout.variant]]
+name = "compact"
+hidden = ["(0,1)"]"#,
+        );
+        let config = parse(&source);
+        let layout = config.layout().unwrap();
+        let keymap = config.keymap().unwrap();
+
+        assert!(layout.keys.contains(&[0, 1]), "logical identity is variant-independent");
+        assert!(
+            layout.physical.keys.iter().all(|key| key.matrix != [0, 1]),
+            "the selected/default variant has no fallback center for its hidden key"
+        );
+        let lighting = config.lighting(&layout, &keymap).unwrap().unwrap();
+        assert_eq!(lighting.emitters[1].key, Some([0, 1]));
+        assert_eq!(lighting.emitters[1].position.unwrap().z, 64);
+    }
+
+    #[test]
+    fn rejects_degenerate_animated_effects() {
+        for (source, expected) in [
+            (
+                BASE.replace(
+                    "effect = { kind = \"solid\", color = [1, 2, 3] }",
+                    "effect = { kind = \"blink\", color = [1, 2, 3], period_ms = 0, duty_percent = 50 }",
+                ),
+                "blink period_ms",
+            ),
+            (
+                BASE.replace(
+                    "effect = { kind = \"solid\", color = [1, 2, 3] }",
+                    "effect = { kind = \"breathe\", color = [1, 2, 3], period_ms = 1, step_ms = 1 }",
+                ),
+                "breathe period_ms",
+            ),
+            (
+                BASE.replace(
+                    "effect = { kind = \"solid\", color = [1, 2, 3] }",
+                    "effect = { kind = \"breathe\", color = [1, 2, 3], period_ms = 100, step_ms = 100 }",
+                ),
+                "breathe step_ms",
+            ),
+        ] {
+            let config = parse(&source);
+            let layout = config.layout().unwrap();
+            let keymap = config.keymap().unwrap();
+            let error = config.lighting(&layout, &keymap).unwrap_err();
+            assert!(error.contains(expected), "{error}");
+        }
+    }
+}
diff --git a/rmk-config/src/resolved/mod.rs b/rmk-config/src/resolved/mod.rs
index e5957ded6..6fa30a97a 100644
--- a/rmk-config/src/resolved/mod.rs
+++ b/rmk-config/src/resolved/mod.rs
@@ -32,6 +32,7 @@ pub mod host;
 pub mod identity;
 pub mod keymap;
 pub mod layout;
+pub mod lighting;
 
 pub use behavior::Behavior;
 pub use build_constants::BuildConstants;
@@ -39,7 +40,8 @@ pub use hardware::Hardware;
 pub use host::Host;
 pub use identity::Identity;
 pub use keymap::Keymap;
-pub use layout::Layout;
+pub use layout::{FixedPoint3, FixedSize2, Layout, PhysicalKey, PhysicalLayout};
+pub use lighting::Lighting;
 
 // Re-export constants used by codegen
 pub use crate::keycode_alias::KEYCODE_ALIAS;
diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
new file mode 100644
index 000000000..74763cee2
--- /dev/null
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -0,0 +1,405 @@
+//! Generate flash-resident shared geometry and semantic lighting topology.
+
+use proc_macro2::TokenStream as TokenStream2;
+use quote::quote;
+use rmk_config::resolved::lighting::{
+    Lighting, LightingBackgroundMode, LightingEffect, LightingSceneCell,
+};
+use rmk_config::resolved::{FixedPoint3, PhysicalLayout};
+
+pub(crate) fn expand_physical_layout(layout: &PhysicalLayout) -> TokenStream2 {
+    let keys = layout.keys.iter().map(|key| {
+        let [row, col] = key.matrix;
+        let center = expand_point(key.center);
+        let width = key.size.width;
+        let height = key.size.height;
+        let rotation = key.rotation_centidegrees;
+        quote! {
+            ::rmk::physical_layout::PhysicalKey {
+                matrix: ::rmk::physical_layout::KeyPosition::new(#row, #col),
+                center: #center,
+                size: ::rmk::physical_layout::KeySize::new(
+                    ::rmk::physical_layout::Extent::from_raw(#width),
+                    ::rmk::physical_layout::Extent::from_raw(#height),
+                ),
+                rotation: ::rmk::physical_layout::Rotation::from_centidegrees(#rotation),
+            }
+        }
+    });
+    let len = layout.keys.len();
+
+    quote! {
+        pub static PHYSICAL_KEYS: [::rmk::physical_layout::PhysicalKey; #len] = [#(#keys),*];
+        pub const PHYSICAL_LAYOUT: ::rmk::physical_layout::PhysicalLayout<'static> =
+            ::rmk::physical_layout::PhysicalLayout::new(&PHYSICAL_KEYS);
+    }
+}
+
+/// Generate the flash-resident topology, routing, and built-in semantic
+/// lighting configuration for a resolved `[lighting]` section.
+pub(crate) fn expand_lighting_topology(lighting: Option<&Lighting>) -> TokenStream2 {
+    let Some(lighting) = lighting else {
+        return TokenStream2::new();
+    };
+    let revision = lighting.topology_revision;
+    let [rows, cols] = lighting.matrix;
+    let led_count = lighting.emitters.len();
+
+    let keys = lighting.keys.iter().map(|key| {
+        let [row, col] = key.matrix;
+        quote! { ::rmk::lighting::topology::MatrixPosition::new(#row, #col) }
+    });
+    let key_count = lighting.keys.len();
+    let zones = lighting.zones.iter().map(|zone| {
+        let id = zone.id;
+        let name = &zone.name;
+        quote! {
+            ::rmk::lighting::topology::ZoneMetadata {
+                id: ::rmk::lighting::topology::ZoneId(#id),
+                name: #name,
+            }
+        }
+    });
+    let zone_count = lighting.zones.len();
+    let emitters = lighting.emitters.iter().map(|emitter| {
+        let id = emitter.id;
+        let key = match emitter.key {
+            Some([row, col]) => quote! {
+                ::core::option::Option::Some(::rmk::lighting::topology::MatrixPosition::new(#row, #col))
+            },
+            None => quote! { ::core::option::Option::None },
+        };
+        let position = match emitter.position {
+            Some(point) => {
+                let point = expand_point(point);
+                quote! { ::core::option::Option::Some(#point) }
+            }
+            None => quote! { ::core::option::Option::None },
+        };
+        let zone_start = emitter.zone_start;
+        let zone_len = emitter.zone_len;
+        quote! {
+            ::rmk::lighting::topology::LedMetadata {
+                id: ::rmk::lighting::topology::LedId(#id),
+                key: #key,
+                position: #position,
+                zones: ::rmk::lighting::topology::ZoneSpan::new(#zone_start, #zone_len),
+            }
+        }
+    });
+    let memberships = lighting.zone_memberships.iter().map(|id| {
+        quote! { ::rmk::lighting::topology::ZoneId(#id) }
+    });
+    let membership_count = lighting.zone_memberships.len();
+    let outputs = lighting.outputs.iter().map(|output| {
+        let node = output.node;
+        let id = output.id;
+        let pixel_count = output.pixel_count;
+        let capabilities = output.capabilities;
+        let coverage = if output.sparse {
+            quote! { ::rmk::lighting::topology::OutputCoverage::Sparse }
+        } else {
+            quote! { ::rmk::lighting::topology::OutputCoverage::Complete }
+        };
+        quote! {
+            ::rmk::lighting::topology::OutputMetadata {
+                node: ::rmk::lighting::topology::LightingNodeId(#node),
+                id: ::rmk::lighting::topology::OutputId(#id),
+                pixel_count: #pixel_count,
+                capabilities: ::rmk::lighting::topology::OutputCapabilities::from_bits(#capabilities)
+                    .expect("rmk-config emitted validated output capabilities"),
+                coverage: #coverage,
+            }
+        }
+    });
+    let output_count = lighting.outputs.len();
+    let routes = lighting.routes.iter().map(|route| {
+        let slot = route.slot;
+        let node = route.node;
+        let output = route.output;
+        let physical_index = route.physical_index;
+        quote! {
+            ::rmk::lighting::topology::PhysicalRoute {
+                slot: ::rmk::lighting::topology::LedSlot(#slot),
+                node: ::rmk::lighting::topology::LightingNodeId(#node),
+                output: ::rmk::lighting::topology::OutputId(#output),
+                physical_index: #physical_index,
+            }
+        }
+    });
+    let route_count = lighting.routes.len();
+    let layer_scene_cells = lighting.layer_scenes.iter().enumerate().map(|(index, scene)| {
+        let name = quote::format_ident!("LIGHTING_LAYER_SCENE_{index}_CELLS");
+        let cells = scene.cells.iter().map(expand_scene_cell);
+        let len = scene.cells.len();
+        quote! {
+            pub static #name: [::rmk::lighting::SceneCell<::rmk::lighting::BuiltinEffect>; #len] =
+                [#(#cells),*];
+        }
+    });
+    let layer_scene_table = lighting
+        .layer_scenes
+        .iter()
+        .enumerate()
+        .map(|(index, scene)| {
+            let name = quote::format_ident!("LIGHTING_LAYER_SCENE_{index}_CELLS");
+            let layer = scene.layer;
+            quote! {
+                ::rmk::lighting::LayerScene {
+                    layer: #layer,
+                    cells: &#name,
+                }
+            }
+        });
+    let layer_scene_count = lighting.layer_scenes.len();
+    let background = &lighting.background;
+    let background_enabled = background.enabled;
+    let background_hue = background.hue;
+    let background_saturation = background.saturation;
+    let background_value = background.value;
+    let background_speed = background.speed;
+    let background_mode = match background.mode {
+        LightingBackgroundMode::Solid => quote! { ::rmk::lighting::BackgroundMode::Solid },
+        LightingBackgroundMode::Breathe => quote! { ::rmk::lighting::BackgroundMode::Breathe },
+    };
+
+    quote! {
+        pub const LIGHTING_TOPOLOGY_REVISION: u32 = #revision;
+        pub const LIGHTING_LED_COUNT: usize = #led_count;
+        pub static LIGHTING_KEYS: [::rmk::lighting::topology::MatrixPosition; #key_count] = [#(#keys),*];
+        pub static LIGHTING_ZONES: [::rmk::lighting::topology::ZoneMetadata<'static>; #zone_count] = [#(#zones),*];
+        pub static LIGHTING_EMITTERS: [::rmk::lighting::topology::LedMetadata; #led_count] = [#(#emitters),*];
+        pub static LIGHTING_ZONE_MEMBERSHIPS: [::rmk::lighting::topology::ZoneId; #membership_count] = [#(#memberships),*];
+        pub static LIGHTING_OUTPUTS: [::rmk::lighting::topology::OutputMetadata; #output_count] = [#(#outputs),*];
+        pub static LIGHTING_ROUTES: [::rmk::lighting::topology::PhysicalRoute; #route_count] = [#(#routes),*];
+        pub const LIGHTING_TOPOLOGY: ::rmk::lighting::topology::LightingTopology<'static> =
+            ::rmk::lighting::topology::LightingTopology {
+                matrix: ::rmk::lighting::topology::MatrixSize::new(#rows, #cols),
+                keys: &LIGHTING_KEYS,
+                physical_layout: PHYSICAL_LAYOUT,
+                leds: &LIGHTING_EMITTERS,
+                zones: &LIGHTING_ZONES,
+                zone_memberships: &LIGHTING_ZONE_MEMBERSHIPS,
+            };
+        pub const LIGHTING_ROUTING: ::rmk::lighting::topology::LightingRouting<'static> =
+            ::rmk::lighting::topology::LightingRouting {
+                outputs: &LIGHTING_OUTPUTS,
+                routes: &LIGHTING_ROUTES,
+            };
+
+        #(#layer_scene_cells)*
+        pub static LIGHTING_LAYER_SCENE_TABLE:
+            [::rmk::lighting::LayerScene<'static, ::rmk::lighting::BuiltinEffect>; #layer_scene_count] =
+            [#(#layer_scene_table),*];
+        pub const LIGHTING_LAYER_SCENES:
+            ::rmk::lighting::LayerScenes<'static, ::rmk::lighting::BuiltinEffect> =
+            ::rmk::lighting::LayerScenes {
+                scenes: &LIGHTING_LAYER_SCENE_TABLE,
+                policy: ::rmk::lighting::LayerPolicy::ActiveStack,
+            };
+        pub const LIGHTING_BACKGROUND: ::rmk::lighting::BackgroundState =
+            ::rmk::lighting::BackgroundState {
+                enabled: #background_enabled,
+                hue: #background_hue,
+                saturation: #background_saturation,
+                value: #background_value,
+                speed: #background_speed,
+                mode: #background_mode,
+            };
+    }
+}
+
+fn expand_scene_cell(cell: &LightingSceneCell) -> TokenStream2 {
+    let slot = cell.slot;
+    let effect = expand_effect(cell.effect);
+    quote! {
+        ::rmk::lighting::SceneCell {
+            slot: ::rmk::lighting::topology::LedSlot(#slot),
+            effect: #effect,
+        }
+    }
+}
+
+fn expand_effect(effect: LightingEffect) -> TokenStream2 {
+    match effect {
+        LightingEffect::Solid { color } => {
+            let [r, g, b] = color;
+            quote! {
+                ::rmk::lighting::BuiltinEffect::Solid {
+                    color: ::rmk::lighting::Rgb8::new(#r, #g, #b),
+                }
+            }
+        }
+        LightingEffect::Blink {
+            color,
+            period_ms,
+            phase_ms,
+            duty_percent,
+        } => {
+            let [r, g, b] = color;
+            quote! {
+                ::rmk::lighting::BuiltinEffect::Blink {
+                    color: ::rmk::lighting::Rgb8::new(#r, #g, #b),
+                    period_ms: #period_ms,
+                    phase_ms: #phase_ms,
+                    duty: #duty_percent,
+                }
+            }
+        }
+        LightingEffect::Breathe {
+            color,
+            period_ms,
+            phase_ms,
+            step_ms,
+        } => {
+            let [r, g, b] = color;
+            quote! {
+                ::rmk::lighting::BuiltinEffect::Breathe {
+                    color: ::rmk::lighting::Rgb8::new(#r, #g, #b),
+                    period_ms: #period_ms,
+                    phase_ms: #phase_ms,
+                    step_ms: #step_ms,
+                }
+            }
+        }
+    }
+}
+
+fn expand_point(point: FixedPoint3) -> TokenStream2 {
+    let x = point.x;
+    let y = point.y;
+    let z = point.z;
+    quote! {
+        ::rmk::physical_layout::Point3::new(
+            ::rmk::physical_layout::Coordinate::from_raw(#x),
+            ::rmk::physical_layout::Coordinate::from_raw(#y),
+            ::rmk::physical_layout::Coordinate::from_raw(#z),
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rmk_config::resolved::lighting::{
+        LightingBackground, LightingEmitter, LightingKey, LightingLayerScene, LightingOutput,
+        LightingRoute, LightingSceneCell, LightingZone,
+    };
+    use rmk_config::resolved::{FixedSize2, PhysicalKey};
+
+    #[test]
+    fn emits_shared_geometry_and_topology_without_electrical_order_leaking_into_ids() {
+        let physical = PhysicalLayout {
+            keys: vec![PhysicalKey {
+                matrix: [0, 0],
+                center: FixedPoint3 {
+                    x: -128,
+                    y: 256,
+                    z: 0,
+                },
+                size: FixedSize2 {
+                    width: 384,
+                    height: 256,
+                },
+                rotation_centidegrees: -750,
+            }],
+        };
+        let geometry = expand_physical_layout(&physical).to_string();
+        assert!(geometry.contains("PHYSICAL_LAYOUT"));
+        assert!(geometry.contains("from_raw (- 128i16)"));
+
+        let lighting = Lighting {
+            topology_revision: 4,
+            matrix: [1, 1],
+            keys: vec![LightingKey { matrix: [0, 0] }],
+            zones: vec![LightingZone {
+                id: 1,
+                name: "keys".into(),
+            }],
+            emitters: vec![LightingEmitter {
+                id: 42,
+                key: Some([0, 0]),
+                position: None,
+                zone_start: 0,
+                zone_len: 1,
+            }],
+            zone_memberships: vec![1],
+            outputs: vec![LightingOutput {
+                node: 2,
+                id: 3,
+                pixel_count: 2,
+                capabilities: 0b10100,
+                sparse: true,
+            }],
+            routes: vec![LightingRoute {
+                slot: 0,
+                node: 2,
+                output: 3,
+                physical_index: 1,
+            }],
+            layer_scenes: vec![
+                LightingLayerScene {
+                    layer: 0,
+                    cells: vec![LightingSceneCell {
+                        slot: 0,
+                        effect: LightingEffect::Solid { color: [1, 2, 3] },
+                    }],
+                },
+                LightingLayerScene {
+                    layer: 1,
+                    cells: vec![
+                        LightingSceneCell {
+                            slot: 0,
+                            effect: LightingEffect::Blink {
+                                color: [4, 5, 6],
+                                period_ms: 1000,
+                                phase_ms: 250,
+                                duty_percent: 40,
+                            },
+                        },
+                        LightingSceneCell {
+                            slot: 0,
+                            effect: LightingEffect::Breathe {
+                                color: [7, 8, 9],
+                                period_ms: 2000,
+                                phase_ms: 500,
+                                step_ms: 20,
+                            },
+                        },
+                    ],
+                },
+            ],
+            background: LightingBackground {
+                enabled: false,
+                hue: 11,
+                saturation: 22,
+                value: 33,
+                speed: 44,
+                mode: LightingBackgroundMode::Breathe,
+            },
+        };
+        let topology = expand_lighting_topology(Some(&lighting)).to_string();
+        assert!(topology.contains("LedId (42u16)"));
+        assert!(topology.contains("physical_index : 1u16"));
+        assert!(topology.contains("physical_layout : PHYSICAL_LAYOUT"));
+        assert!(topology.contains("LIGHTING_LAYER_SCENE_0_CELLS"));
+        assert!(topology.contains("LIGHTING_LAYER_SCENE_1_CELLS"));
+        assert!(topology.contains("LIGHTING_LAYER_SCENE_TABLE"));
+        assert!(topology.contains("LIGHTING_LAYER_SCENES"));
+        assert!(topology.contains("LayerPolicy :: ActiveStack"));
+        assert!(topology.contains("BuiltinEffect :: Solid"));
+        assert!(topology.contains("BuiltinEffect :: Blink"));
+        assert!(topology.contains("duty : 40u8"));
+        assert!(topology.contains("BuiltinEffect :: Breathe"));
+        assert!(topology.contains("step_ms : 20u16"));
+        assert!(topology.contains("LIGHTING_BACKGROUND"));
+        assert!(topology.contains("enabled : false"));
+        assert!(topology.contains("hue : 11u8"));
+        assert!(topology.contains("mode : :: rmk :: lighting :: BackgroundMode :: Breathe"));
+    }
+
+    #[test]
+    fn omits_all_lighting_symbols_without_resolved_lighting() {
+        assert!(expand_lighting_topology(None).is_empty());
+    }
+}
diff --git a/rmk-macro/src/codegen/mod.rs b/rmk-macro/src/codegen/mod.rs
index 0908c6755..935d4cbcd 100644
--- a/rmk-macro/src/codegen/mod.rs
+++ b/rmk-macro/src/codegen/mod.rs
@@ -8,6 +8,7 @@ pub(crate) mod import;
 pub(crate) mod input_device;
 pub(crate) mod keyboard_config;
 pub(crate) mod keymap;
+pub(crate) mod lighting;
 pub(crate) mod matrix;
 pub(crate) mod orchestrator;
 pub(crate) mod override_helper;
diff --git a/rmk-macro/src/codegen/orchestrator.rs b/rmk-macro/src/codegen/orchestrator.rs
index 3583a6722..75928523e 100644
--- a/rmk-macro/src/codegen/orchestrator.rs
+++ b/rmk-macro/src/codegen/orchestrator.rs
@@ -22,6 +22,7 @@ use super::keyboard_config::{
     expand_keyboard_info, expand_lock_config, expand_vial_config, read_keyboard_toml_config,
 };
 use super::keymap::expand_default_keymap;
+use super::lighting::{expand_lighting_topology, expand_physical_layout};
 use super::matrix::{expand_bootmagic_check, expand_matrix_config};
 use super::registered_processor::expand_registered_processor_init;
 use super::split::central::expand_split_central_config;
@@ -56,18 +57,29 @@ pub(crate) fn parse_keyboard_mod(item_mod: syn::ItemMod) -> TokenStream2 {
     let layout = keyboard_config
         .layout()
         .expect("failed to resolve layout config");
+    let lighting = keyboard_config
+        .lighting(&layout, &keymap)
+        .expect("failed to resolve lighting config");
 
     validate_feature_config_parity(
         &rmk_features,
         hardware.storage.is_some(),
         host.vial_enabled,
         host.rynk_enabled,
+        lighting.is_some(),
     )
     .unwrap_or_else(|err| panic!("{err}"));
 
     // Generate imports and statics
-    let imports_and_statics =
-        expand_imports_and_constants(&identity, &host, &hardware, &behavior, &keymap);
+    let imports_and_statics = expand_imports_and_constants(
+        &identity,
+        &host,
+        &hardware,
+        &behavior,
+        &keymap,
+        &layout,
+        lighting.as_ref(),
+    );
 
     // Generate main function body
     let main_function = expand_main(
@@ -92,6 +104,7 @@ fn validate_feature_config_parity(
     storage_in_config: bool,
     vial_in_config: bool,
     rynk_in_config: bool,
+    lighting_in_config: bool,
 ) -> Result<(), String> {
     // A feature enabled in keyboard.toml must have its rmk Cargo feature enabled, and vice versa.
     // (Cargo feature, keyboard.toml field, enabled in keyboard.toml?)
@@ -120,6 +133,17 @@ fn validate_feature_config_parity(
         );
     }
 
+    // Unlike the host/storage integrations, lighting also has a public Rust
+    // construction path, so enabling the feature without TOML is valid. A
+    // TOML section does require the feature because codegen emits lighting
+    // runtime types.
+    if lighting_in_config && !is_feature_enabled(rmk_features, "lighting") {
+        return Err(
+            "A `[lighting]` section in keyboard.toml requires enabling the \"lighting\" Cargo feature for rmk."
+                .to_string(),
+        );
+    }
+
     Ok(())
 }
 
@@ -129,6 +153,8 @@ pub(crate) fn expand_imports_and_constants(
     hardware: &Hardware,
     behavior: &Behavior,
     keymap: &Keymap,
+    layout: &Layout,
+    lighting: Option<&rmk_config::resolved::Lighting>,
 ) -> TokenStream2 {
     // Generate keyboard info and number of rows/cols/layers
     let keyboard_info_static_var = expand_keyboard_info(identity, keymap);
@@ -138,6 +164,8 @@ pub(crate) fn expand_imports_and_constants(
     let vial_static_var = expand_vial_config(host);
     // Generate rynk lock-gate config
     let lock_static_var = expand_lock_config(host);
+    let physical_layout = expand_physical_layout(&layout.physical);
+    let lighting_topology = expand_lighting_topology(lighting);
 
     // Generate extra imports, panic handler and logger
     let imports = match hardware.chip.series {
@@ -178,6 +206,8 @@ pub(crate) fn expand_imports_and_constants(
         #vial_static_var
         #lock_static_var
         #default_keymap
+        #physical_layout
+        #lighting_topology
     }
 }
 
@@ -193,22 +223,45 @@ mod tests {
     #[test]
     fn accepts_matching_storage_vial_rynk_feature_states() {
         assert!(
-            validate_feature_config_parity(&features(&["storage", "vial"]), true, true, false)
+            validate_feature_config_parity(
+                &features(&["storage", "vial"]),
+                true,
+                true,
+                false,
+                false
+            )
+            .is_ok()
+        );
+        assert!(validate_feature_config_parity(&features(&[]), false, false, false, false).is_ok());
+        assert!(
+            validate_feature_config_parity(&features(&["storage"]), true, false, false, false)
                 .is_ok()
         );
-        assert!(validate_feature_config_parity(&features(&[]), false, false, false).is_ok());
         assert!(
-            validate_feature_config_parity(&features(&["storage"]), true, false, false).is_ok()
+            validate_feature_config_parity(
+                &features(&["storage", "rynk"]),
+                true,
+                false,
+                true,
+                false
+            )
+            .is_ok()
+        );
+        assert!(
+            validate_feature_config_parity(&features(&["lighting"]), false, false, false, false)
+                .is_ok(),
+            "the lighting feature supports public Rust construction without TOML"
         );
         assert!(
-            validate_feature_config_parity(&features(&["storage", "rynk"]), true, false, true)
+            validate_feature_config_parity(&features(&["lighting"]), false, false, false, true)
                 .is_ok()
         );
     }
 
     #[test]
     fn rejects_storage_enabled_in_config_without_feature() {
-        let err = validate_feature_config_parity(&features(&[]), true, false, false).unwrap_err();
+        let err =
+            validate_feature_config_parity(&features(&[]), true, false, false, false).unwrap_err();
         assert_eq!(
             err,
             "If the \"storage\" Cargo feature is disabled, `storage.enabled` must be set to false in keyboard.toml."
@@ -217,8 +270,9 @@ mod tests {
 
     #[test]
     fn rejects_storage_feature_without_config() {
-        let err = validate_feature_config_parity(&features(&["storage"]), false, false, false)
-            .unwrap_err();
+        let err =
+            validate_feature_config_parity(&features(&["storage"]), false, false, false, false)
+                .unwrap_err();
         assert_eq!(
             err,
             "`storage.enabled = false` in keyboard.toml requires disabling the \"storage\" Cargo feature for rmk in Cargo.toml (for example with `default-features = false` and explicitly re-enabling the features you need)."
@@ -227,7 +281,8 @@ mod tests {
 
     #[test]
     fn rejects_vial_enabled_in_config_without_feature() {
-        let err = validate_feature_config_parity(&features(&[]), false, true, false).unwrap_err();
+        let err =
+            validate_feature_config_parity(&features(&[]), false, true, false, false).unwrap_err();
         assert_eq!(
             err,
             "If the \"vial\" Cargo feature is disabled, `host.vial_enabled` must be set to false in keyboard.toml."
@@ -236,8 +291,8 @@ mod tests {
 
     #[test]
     fn rejects_vial_feature_without_config() {
-        let err =
-            validate_feature_config_parity(&features(&["vial"]), false, false, false).unwrap_err();
+        let err = validate_feature_config_parity(&features(&["vial"]), false, false, false, false)
+            .unwrap_err();
         assert_eq!(
             err,
             "`host.vial_enabled = false` in keyboard.toml requires disabling the \"vial\" Cargo feature for rmk in Cargo.toml (for example with `default-features = false` and explicitly re-enabling the features you need)."
@@ -246,7 +301,8 @@ mod tests {
 
     #[test]
     fn rejects_rynk_enabled_in_config_without_feature() {
-        let err = validate_feature_config_parity(&features(&[]), false, false, true).unwrap_err();
+        let err =
+            validate_feature_config_parity(&features(&[]), false, false, true, false).unwrap_err();
         assert_eq!(
             err,
             "If the \"rynk\" Cargo feature is disabled, `host.rynk_enabled` must be set to false in keyboard.toml."
@@ -255,8 +311,8 @@ mod tests {
 
     #[test]
     fn rejects_rynk_feature_without_config() {
-        let err =
-            validate_feature_config_parity(&features(&["rynk"]), false, false, false).unwrap_err();
+        let err = validate_feature_config_parity(&features(&["rynk"]), false, false, false, false)
+            .unwrap_err();
         assert_eq!(
             err,
             "`host.rynk_enabled = false` in keyboard.toml requires disabling the \"rynk\" Cargo feature for rmk in Cargo.toml (for example with `default-features = false` and explicitly re-enabling the features you need)."
@@ -265,13 +321,24 @@ mod tests {
 
     #[test]
     fn rejects_vial_and_rynk_both_enabled() {
-        let err = validate_feature_config_parity(&features(&["vial", "rynk"]), false, true, true)
-            .unwrap_err();
+        let err =
+            validate_feature_config_parity(&features(&["vial", "rynk"]), false, true, true, false)
+                .unwrap_err();
         assert_eq!(
             err,
             "`host.vial_enabled` and `host.rynk_enabled` are mutually exclusive — set exactly one to true (the underlying Cargo features for rmk also conflict)."
         );
     }
+
+    #[test]
+    fn rejects_lighting_config_without_feature() {
+        let err =
+            validate_feature_config_parity(&features(&[]), false, false, false, true).unwrap_err();
+        assert_eq!(
+            err,
+            "A `[lighting]` section in keyboard.toml requires enabling the \"lighting\" Cargo feature for rmk."
+        );
+    }
 }
 
 fn expand_main(
diff --git a/rmk-types/Cargo.toml b/rmk-types/Cargo.toml
index f26d49d27..1b604bfff 100644
--- a/rmk-types/Cargo.toml
+++ b/rmk-types/Cargo.toml
@@ -42,7 +42,7 @@ _codegen = []
 # Enable RMK's Rynk protocol
 rynk = ["dep:cobs"]
 # Host tool
-host = ["rynk", "_ble", "split", "steno", "serde/alloc"]
+host = ["rynk", "_ble", "split", "steno", "lighting", "serde/alloc"]
 # TypeScript type + wasm ABI export for the web client. Enabled by a codegen/wasm
 # build, never by firmware.
 wasm = ["dep:tsify", "dep:wasm-bindgen", "dep:serde-wasm-bindgen", "host"]
@@ -50,6 +50,7 @@ wasm = ["dep:tsify", "dep:wasm-bindgen", "dep:serde-wasm-bindgen", "host"]
 _ble = []
 split = []
 display = []
+lighting = []
 passkey_entry = []
 # DFU firmware update support
 dfu = []
diff --git a/rmk/Cargo.toml b/rmk/Cargo.toml
index 4917d530d..406ab6caa 100644
--- a/rmk/Cargo.toml
+++ b/rmk/Cargo.toml
@@ -179,7 +179,11 @@ std = [
 ]
 
 ## Enable display support (traits + processor)
-display = ["dep:embedded-graphics", "rmk-types/display"]
+display = ["dep:embedded-graphics", "rmk-types/display", "_render_state"]
+## Enable topology-aware composable lighting support.
+lighting = ["rmk-types/lighting", "_render_state"]
+## Shared authoritative state needed by display and lighting renderers.
+_render_state = []
 ## Enable SSD1306 OLED driver
 ssd1306 = ["display", "dep:ssd1306", "dep:display-interface", "dep:display-interface-i2c"]
 ## Enable OLED drivers via oled_async (SH1106, SH1107, SH1108, SSD1309)
diff --git a/rmk/src/ble/battery_service.rs b/rmk/src/ble/battery_service.rs
index 5461b0b0c..0c1811e87 100644
--- a/rmk/src/ble/battery_service.rs
+++ b/rmk/src/ble/battery_service.rs
@@ -1,5 +1,3 @@
-use core::sync::atomic::Ordering;
-
 use embassy_futures::join::join;
 use embassy_futures::select::{Either, select};
 use embassy_sync::pubsub::Subscriber;
@@ -8,7 +6,6 @@ use rmk_types::battery::BatteryStatus;
 use trouble_host::prelude::*;
 
 use super::ble_server::Server;
-use crate::ble::sleep::SLEEPING_STATE;
 use crate::core_traits::Runnable;
 use crate::event::{BatteryStatusEvent, SubscribableEvent};
 use crate::keyboard::LAST_KEY_TIMESTAMP;
@@ -109,7 +106,7 @@ impl<P: PacketPool> BleBatteryServer<'_, '_, '_, P> {
                 loop {
                     embassy_time::Timer::after_secs(1800).await;
                     // 30 minutes passed and the keyboard isn't in sleep mode: timeout
-                    if !SLEEPING_STATE.load(Ordering::Acquire) {
+                    if !crate::state::current_sleeping() {
                         break;
                     }
                 }
diff --git a/rmk/src/ble/sleep.rs b/rmk/src/ble/sleep.rs
index 0c7cb8a6a..bcc3aa264 100644
--- a/rmk/src/ble/sleep.rs
+++ b/rmk/src/ble/sleep.rs
@@ -1,26 +1,19 @@
 //! Keyboard-wide sleep management.
 //!
-//! One manager owns the keyboard's sleep state: it watches [`SLEEP_INPUT`],
-//! latches each decision in [`SLEEPING_STATE`] for pollers like the battery
-//! service, and publishes it as [`SleepStateEvent`] for everything else — the
-//! display, and on split centrals the per-link connection-parameter followers
-//! in `split::ble::central`.
-
-use core::sync::atomic::{AtomicBool, Ordering};
+//! One manager owns the keyboard's sleep state: it watches [`SLEEP_INPUT`] and
+//! latches each decision through [`crate::state::set_sleeping`], which both
+//! stores the value for pollers like the battery service and publishes it as
+//! [`crate::event::SleepStateEvent`] for everything else — the display, the
+//! lighting engine, host readback, and on split centrals the per-link
+//! connection-parameter followers in `split::ble::central`.
 
 use embassy_futures::select::{Either, select};
 use embassy_sync::signal::Signal;
 use embassy_time::{Duration, Timer};
 
 use crate::SPLIT_CENTRAL_SLEEP_TIMEOUT_SECONDS;
-use crate::event::{SleepStateEvent, publish_event};
-
-/// The latched sleep state.
-/// - `true`: the keyboard is idle and sleeping
-/// - `false`: the keyboard is awake
-pub(crate) static SLEEPING_STATE: AtomicBool = AtomicBool::new(false);
 
-/// Input to [`run_sleep_manager`], same encoding as [`SLEEPING_STATE`]:
+/// Input to [`run_sleep_manager`], same encoding as the latched sleep state:
 /// - `true`: sleep now, without waiting out the idle timeout
 /// - `false`: activity — wake up, or restart the idle timeout
 static SLEEP_INPUT: Signal<crate::RawMutex, bool> = Signal::new();
@@ -71,15 +64,13 @@ async fn manage_sleep_state(idle_timeout: Duration) -> ! {
             }
         }
         info!("Entering sleep mode");
-        SLEEPING_STATE.store(true, Ordering::Release);
-        publish_event(SleepStateEvent::new(true));
+        crate::state::set_sleeping(true);
 
         // Asleep: only activity wakes us; further sleep requests change nothing.
         while SLEEP_INPUT.wait().await {}
 
         info!("Waking up from sleep mode due to activity");
-        SLEEPING_STATE.store(false, Ordering::Release);
-        publish_event(SleepStateEvent::new(false));
+        crate::state::set_sleeping(false);
     }
 }
 
@@ -96,7 +87,7 @@ mod tests {
     }
 
     fn sleeping() -> bool {
-        SLEEPING_STATE.load(Ordering::Acquire)
+        crate::state::current_sleeping()
     }
 
     #[test]
diff --git a/rmk/src/display/mod.rs b/rmk/src/display/mod.rs
index a9481faba..242da1a50 100644
--- a/rmk/src/display/mod.rs
+++ b/rmk/src/display/mod.rs
@@ -100,6 +100,9 @@ use crate::processor::Processor;
 /// corresponding features in their `Cargo.toml` dependency on `rmk`,
 /// and guard access with matching `#[cfg]` attributes.
 pub struct RenderContext {
+    /// Board-global key geometry generated from the same physical-layout
+    /// source used by lighting and host layout readback.
+    pub physical_layout: crate::physical_layout::PhysicalLayout<'static>,
     /// Current active layer index.
     pub layer: u8,
     /// Current words-per-minute estimate.
@@ -138,6 +141,7 @@ pub struct RenderContext {
 impl Default for RenderContext {
     fn default() -> Self {
         Self {
+            physical_layout: crate::physical_layout::PhysicalLayout::default(),
             layer: 0,
             wpm: 0,
             caps_lock: false,
@@ -291,6 +295,13 @@ where
         self
     }
 
+    /// Provide the keyboard's generated board-global key geometry to custom
+    /// renderers. This does not force built-in renderers to draw a keyboard.
+    pub fn with_physical_layout(mut self, physical_layout: crate::physical_layout::PhysicalLayout<'static>) -> Self {
+        self.ctx.physical_layout = physical_layout;
+        self
+    }
+
     /// Set the minimum time between event-driven renders.
     ///
     /// When events arrive faster than this interval, redraws are coalesced
@@ -420,6 +431,10 @@ where
 
         // Prime from current state after subscribing, so the first render
         // reflects state that was set before the processor started.
+        self.ctx.sleeping = crate::state::current_sleeping();
+        let indicators = crate::keyboard::current_led_indicator();
+        self.ctx.caps_lock = indicators.caps_lock();
+        self.ctx.num_lock = indicators.num_lock();
         #[cfg(feature = "_ble")]
         {
             self.ctx.ble_status = crate::state::current_ble_status();
diff --git a/rmk/src/event/mod.rs b/rmk/src/event/mod.rs
index 52017a5ee..01023971f 100644
--- a/rmk/src/event/mod.rs
+++ b/rmk/src/event/mod.rs
@@ -67,7 +67,7 @@ pub use input::{
 pub use split::ClearPeerEvent;
 #[cfg(feature = "split")]
 pub use split::{CentralConnectedEvent, PeripheralBatteryEvent, PeripheralConnectedEvent};
-pub use state::{LayerChangeEvent, LedIndicatorEvent, SleepStateEvent, WpmUpdateEvent};
+pub use state::{LayerChangeEvent, LedIndicatorEvent, LightingChangedEvent, SleepStateEvent, WpmUpdateEvent};
 
 /// Trait for event publishers
 pub trait EventPublisher {
diff --git a/rmk/src/event/state.rs b/rmk/src/event/state.rs
index eb38b7213..8bf34389e 100644
--- a/rmk/src/event/state.rs
+++ b/rmk/src/event/state.rs
@@ -58,3 +58,18 @@ impl SleepStateEvent {
 }
 
 impl_payload_wrapper!(SleepStateEvent, bool);
+
+/// Authoritative lighting state changed.
+///
+/// This is deliberately a unit invalidation: consumers read a fresh state
+/// snapshot from the lighting controller instead of trusting an event mirror.
+#[event(channel_size = crate::LIGHTING_CHANGED_EVENT_CHANNEL_SIZE, pubs = crate::LIGHTING_CHANGED_EVENT_PUB_SIZE, subs = crate::LIGHTING_CHANGED_EVENT_SUB_SIZE)]
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub struct LightingChangedEvent;
+
+impl LightingChangedEvent {
+    pub const fn new() -> Self {
+        Self
+    }
+}
diff --git a/rmk/src/hid.rs b/rmk/src/hid.rs
index b21747793..45d144d61 100644
--- a/rmk/src/hid.rs
+++ b/rmk/src/hid.rs
@@ -1,6 +1,5 @@
 /// Traits and types for HID message reporting and listening.
 use core::future::Future;
-use core::sync::atomic::Ordering;
 
 use embassy_usb::class::hid::ReadError;
 use embassy_usb::driver::EndpointError;
@@ -13,7 +12,6 @@ use usbd_hid::descriptor::generator_prelude::*;
 use usbd_hid::descriptor::{AsInputReport, MediaKeyboardReport, MouseReport, SystemControlReport};
 
 use crate::event::{LedIndicatorEvent, publish_event};
-use crate::keyboard::LOCK_LED_STATES;
 
 /// KeyboardReport describes a report and its companion descriptor that can be
 /// used to send keyboard button presses to a host and receive the status of the
@@ -403,7 +401,7 @@ pub(crate) async fn run_led_reader<R: HidReaderTrait<ReportType = LedIndicator>>
             Ok(led_indicator) => {
                 info!("Got led indicator");
                 if crate::state::active_transport() == Some(kind) {
-                    LOCK_LED_STATES.store(led_indicator.into_bits(), Ordering::Relaxed);
+                    crate::keyboard::set_current_led_indicator(led_indicator);
                     publish_event(LedIndicatorEvent::new(led_indicator));
                 }
             }
diff --git a/rmk/src/keyboard.rs b/rmk/src/keyboard.rs
index beb231428..814357097 100644
--- a/rmk/src/keyboard.rs
+++ b/rmk/src/keyboard.rs
@@ -64,6 +64,13 @@ pub(crate) fn current_led_indicator() -> LedIndicator {
     LedIndicator::from_bits(LOCK_LED_STATES.load(core::sync::atomic::Ordering::Relaxed))
 }
 
+/// Update the authoritative host-driven lock LED state before publishing its
+/// invalidation event. This also covers split peripherals, which do not have a
+/// local HID reader.
+pub(crate) fn set_current_led_indicator(indicator: LedIndicator) {
+    LOCK_LED_STATES.store(indicator.into_bits(), core::sync::atomic::Ordering::Relaxed);
+}
+
 /// State machine for Caps Word
 #[derive(Debug, Default)]
 enum CapsWordState {
@@ -1221,6 +1228,12 @@ impl<'a> Keyboard<'a> {
     }
 
     async fn process_key_action_normal(&mut self, action: Action, event: KeyboardEvent) {
+        #[cfg(feature = "lighting")]
+        if event.pressed
+            && let Action::Light(light_action) = action
+        {
+            crate::lighting::send_light_action(light_action).await;
+        }
         publish_event_async(ActionEvent {
             action,
             keyboard_event: event,
diff --git a/rmk/src/lib.rs b/rmk/src/lib.rs
index a69f69d8c..71437ebe1 100644
--- a/rmk/src/lib.rs
+++ b/rmk/src/lib.rs
@@ -101,7 +101,10 @@ pub mod keyboard_macros;
 pub mod keymap;
 pub mod layout_macro;
 pub mod light;
+#[cfg(feature = "lighting")]
+pub mod lighting;
 pub mod matrix;
+pub mod physical_layout;
 pub mod processor;
 #[cfg(feature = "split")]
 pub mod split;
diff --git a/rmk/src/lighting/color.rs b/rmk/src/lighting/color.rs
new file mode 100644
index 000000000..c3c33d680
--- /dev/null
+++ b/rmk/src/lighting/color.rs
@@ -0,0 +1,26 @@
+/// Device-independent, linear RGB sample used by RMK's standard compositor.
+///
+/// A driver or output transform is responsible for channel order, gamma,
+/// RGBW/mono conversion, brightness, and electrical safety limits.
+#[derive(Copy, Clone, Default, Debug, Eq, PartialEq)]
+#[repr(C)]
+pub struct Rgb8 {
+    pub r: u8,
+    pub g: u8,
+    pub b: u8,
+}
+
+impl Rgb8 {
+    pub const BLACK: Self = Self::new(0, 0, 0);
+
+    pub const fn new(r: u8, g: u8, b: u8) -> Self {
+        Self { r, g, b }
+    }
+
+    pub const fn scale(self, level: u8) -> Self {
+        const fn channel(value: u8, level: u8) -> u8 {
+            ((value as u16 * level as u16) / 255) as u8
+        }
+        Self::new(channel(self.r, level), channel(self.g, level), channel(self.b, level))
+    }
+}
diff --git a/rmk/src/lighting/compositor.rs b/rmk/src/lighting/compositor.rs
new file mode 100644
index 000000000..6ee8fa2b7
--- /dev/null
+++ b/rmk/src/lighting/compositor.rs
@@ -0,0 +1,309 @@
+use super::effect::EffectSample;
+use super::topology::LedSlot;
+
+/// One source contribution. Transparent samples may carry a deadline because
+/// a currently invisible effect can become opaque later.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum Contribution<C> {
+    Transparent { next_change_ms: Option<u64> },
+    Opaque(EffectSample<C>),
+}
+
+/// Inputs common to all sources in one render transaction.
+#[derive(Copy, Clone, Debug)]
+pub struct RenderInput<'a, Context> {
+    pub now_ms: u64,
+    pub context: &'a Context,
+}
+
+/// Allocation-free pull interface for sparse or dense sources.
+///
+/// Targets are exposed separately so the transaction can validate the whole
+/// source before changing the frame. That makes an invalid target atomic.
+pub trait LightingSource<C, Context> {
+    fn len(&self, input: &RenderInput<'_, Context>) -> usize;
+    fn slot(&self, index: usize, input: &RenderInput<'_, Context>) -> LedSlot;
+    /// Sample one previously validated target.
+    ///
+    /// `len` and `slot` must be pure for the duration of this call. Sampling
+    /// is mutable so cached, RNG-backed, and otherwise stateful effects do not
+    /// require interior mutability.
+    fn contribution(&mut self, index: usize, input: &RenderInput<'_, Context>) -> Contribution<C>;
+
+    fn is_empty(&self, input: &RenderInput<'_, Context>) -> bool {
+        self.len(input) == 0
+    }
+}
+
+/// User-level transform applied after composition but before changed
+/// detection. Hard electrical limits remain the output driver's job.
+pub trait OutputTransform<C> {
+    fn transform(&mut self, slot: LedSlot, color: C) -> C;
+
+    fn next_change_ms(&self, _slot: LedSlot, _before: C, _after: C, source_next_change_ms: Option<u64>) -> Option<u64> {
+        source_next_change_ms
+    }
+}
+
+#[derive(Copy, Clone, Debug, Default)]
+pub struct IdentityTransform;
+
+impl<C> OutputTransform<C> for IdentityTransform {
+    fn transform(&mut self, _slot: LedSlot, color: C) -> C {
+        color
+    }
+}
+
+/// Standard dense logical frame. Its slot order has semantic meaning only in
+/// conjunction with a validated topology; it is never physical chain order.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct LogicalFrame<C, const N: usize> {
+    pixels: [C; N],
+}
+
+impl<C: Copy, const N: usize> LogicalFrame<C, N> {
+    pub const fn new(fill: C) -> Self {
+        Self { pixels: [fill; N] }
+    }
+
+    pub const fn as_array(&self) -> &[C; N] {
+        &self.pixels
+    }
+
+    pub fn as_mut_array(&mut self) -> &mut [C; N] {
+        &mut self.pixels
+    }
+
+    pub fn as_slice(&self) -> &[C] {
+        &self.pixels
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum RenderError {
+    PriorityRegression { previous: u8, attempted: u8 },
+    SlotOutOfRange { slot: LedSlot, frame_len: usize },
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct RenderResult {
+    pub changed: bool,
+    /// Absolute deadline. `None` means no timer should be armed.
+    pub next_wake_ms: Option<u64>,
+}
+
+/// Keeps the last frame successfully presented by the output.
+///
+/// [`Compositor::commit`] is deliberately separate from rendering. A service
+/// commits only after a successful driver write, so failures remain dirty and
+/// can be retried without waiting for an unrelated event.
+pub struct Compositor<C, const N: usize> {
+    committed: LogicalFrame<C, N>,
+    has_committed: bool,
+}
+
+impl<C: Copy + Eq, const N: usize> Compositor<C, N> {
+    pub const fn new(fill: C) -> Self {
+        Self {
+            committed: LogicalFrame::new(fill),
+            has_committed: false,
+        }
+    }
+
+    pub fn begin<'a, 'context, Context>(
+        &'a self,
+        now_ms: u64,
+        context: &'context Context,
+        fill: C,
+        frame: &'a mut LogicalFrame<C, N>,
+    ) -> RenderTransaction<'a, 'context, C, Context, N> {
+        frame.pixels.fill(fill);
+        RenderTransaction {
+            compositor: self,
+            frame,
+            deadlines: [None; N],
+            input: RenderInput { now_ms, context },
+            last_priority: None,
+        }
+    }
+
+    pub fn commit(&mut self, frame: &LogicalFrame<C, N>) {
+        self.committed.pixels.copy_from_slice(&frame.pixels);
+        self.has_committed = true;
+    }
+
+    pub fn has_committed(&self) -> bool {
+        self.has_committed
+    }
+}
+
+pub struct RenderTransaction<'a, 'context, C, Context, const N: usize> {
+    compositor: &'a Compositor<C, N>,
+    frame: &'a mut LogicalFrame<C, N>,
+    deadlines: [Option<u64>; N],
+    input: RenderInput<'context, Context>,
+    last_priority: Option<u8>,
+}
+
+impl<C: Copy + Eq, Context, const N: usize> RenderTransaction<'_, '_, C, Context, N> {
+    /// Apply a source. Priorities must be nondecreasing; equal priorities use
+    /// stable call order, with the later opaque contribution winning.
+    pub fn apply(&mut self, priority: u8, source: &mut impl LightingSource<C, Context>) -> Result<(), RenderError> {
+        if let Some(previous) = self.last_priority
+            && priority < previous
+        {
+            return Err(RenderError::PriorityRegression {
+                previous,
+                attempted: priority,
+            });
+        }
+
+        // Validate every target before mutating anything.
+        for index in 0..source.len(&self.input) {
+            let slot = source.slot(index, &self.input);
+            if slot.index() >= N {
+                return Err(RenderError::SlotOutOfRange { slot, frame_len: N });
+            }
+        }
+
+        for index in 0..source.len(&self.input) {
+            let slot = source.slot(index, &self.input).index();
+            match source.contribution(index, &self.input) {
+                Contribution::Transparent { next_change_ms } => {
+                    self.deadlines[slot] =
+                        earliest(self.deadlines[slot], future_deadline(self.input.now_ms, next_change_ms));
+                }
+                Contribution::Opaque(sample) => {
+                    self.frame.pixels[slot] = sample.color;
+                    // Opaque replacement intentionally erases all deadlines
+                    // belonging to sources hidden below this winner.
+                    self.deadlines[slot] = future_deadline(self.input.now_ms, sample.next_change_ms);
+                }
+            }
+        }
+        self.last_priority = Some(priority);
+        Ok(())
+    }
+
+    pub fn finish(self) -> RenderResult {
+        self.finish_with(&mut IdentityTransform)
+    }
+
+    pub fn finish_with(self, transform: &mut impl OutputTransform<C>) -> RenderResult {
+        let now_ms = self.input.now_ms;
+        let mut next_wake_ms = None;
+        for slot_index in 0..N {
+            let slot = LedSlot::from_index(slot_index);
+            let before = self.frame.pixels[slot_index];
+            let after = transform.transform(slot, before);
+            self.frame.pixels[slot_index] = after;
+            let transformed_deadline = transform.next_change_ms(slot, before, after, self.deadlines[slot_index]);
+            next_wake_ms = earliest(next_wake_ms, future_deadline(now_ms, transformed_deadline));
+        }
+
+        RenderResult {
+            changed: !self.compositor.has_committed || self.frame.pixels != self.compositor.committed.pixels,
+            next_wake_ms,
+        }
+    }
+}
+
+fn future_deadline(now_ms: u64, deadline: Option<u64>) -> Option<u64> {
+    match deadline {
+        Some(deadline) if deadline > now_ms => Some(deadline),
+        Some(_) => now_ms.checked_add(1),
+        None => None,
+    }
+}
+
+fn earliest(left: Option<u64>, right: Option<u64>) -> Option<u64> {
+    match (left, right) {
+        (Some(left), Some(right)) => Some(left.min(right)),
+        (Some(value), None) | (None, Some(value)) => Some(value),
+        (None, None) => None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::Rgb8;
+    use super::*;
+
+    struct Source<const M: usize>([(LedSlot, Contribution<Rgb8>); M]);
+
+    impl<Context, const M: usize> LightingSource<Rgb8, Context> for Source<M> {
+        fn len(&self, _: &RenderInput<'_, Context>) -> usize {
+            M
+        }
+        fn slot(&self, index: usize, _: &RenderInput<'_, Context>) -> LedSlot {
+            self.0[index].0
+        }
+        fn contribution(&mut self, index: usize, _: &RenderInput<'_, Context>) -> Contribution<Rgb8> {
+            self.0[index].1
+        }
+    }
+
+    fn opaque(slot: usize, color: Rgb8, next: Option<u64>) -> (LedSlot, Contribution<Rgb8>) {
+        (
+            LedSlot::from_index(slot),
+            Contribution::Opaque(EffectSample {
+                color,
+                next_change_ms: next,
+            }),
+        )
+    }
+
+    #[test]
+    fn transparency_ties_and_occluded_deadlines_are_deterministic() {
+        let mut compositor = Compositor::<Rgb8, 2>::new(Rgb8::BLACK);
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        let context = ();
+        let mut low = Source([opaque(0, Rgb8::new(1, 0, 0), Some(10))]);
+        let mut transparent = Source([(
+            LedSlot(0),
+            Contribution::Transparent {
+                next_change_ms: Some(20),
+            },
+        )]);
+        let mut high = Source([opaque(0, Rgb8::new(0, 1, 0), None)]);
+        let mut tx = compositor.begin(0, &context, Rgb8::BLACK, &mut frame);
+        tx.apply(1, &mut low).unwrap();
+        tx.apply(1, &mut transparent).unwrap();
+        tx.apply(2, &mut high).unwrap();
+        let result = tx.finish();
+        assert_eq!(frame.as_slice(), &[Rgb8::new(0, 1, 0), Rgb8::BLACK]);
+        assert_eq!(result.next_wake_ms, None);
+        assert!(result.changed);
+
+        compositor.commit(&frame);
+    }
+
+    #[test]
+    fn failed_apply_is_atomic_and_priority_regression_does_not_advance_order() {
+        let compositor = Compositor::<Rgb8, 1>::new(Rgb8::BLACK);
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        let mut good = Source([opaque(0, Rgb8::new(3, 0, 0), None)]);
+        let mut bad = Source([opaque(0, Rgb8::new(9, 0, 0), None), opaque(2, Rgb8::new(8, 0, 0), None)]);
+        let mut tx = compositor.begin(0, &(), Rgb8::BLACK, &mut frame);
+        assert!(matches!(tx.apply(5, &mut bad), Err(RenderError::SlotOutOfRange { .. })));
+        tx.apply(4, &mut good).unwrap();
+        assert_eq!(tx.finish().next_wake_ms, None);
+        assert_eq!(frame.as_slice(), &[Rgb8::new(3, 0, 0)]);
+    }
+
+    #[test]
+    fn uncommitted_output_remains_changed_for_driver_retry() {
+        let mut compositor = Compositor::<Rgb8, 1>::new(Rgb8::BLACK);
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        let mut source = Source([opaque(0, Rgb8::new(1, 2, 3), None)]);
+        for _ in 0..2 {
+            let mut tx = compositor.begin(0, &(), Rgb8::BLACK, &mut frame);
+            tx.apply(0, &mut source).unwrap();
+            assert!(tx.finish().changed);
+        }
+        compositor.commit(&frame);
+        let mut tx = compositor.begin(0, &(), Rgb8::BLACK, &mut frame);
+        tx.apply(0, &mut source).unwrap();
+        assert!(!tx.finish().changed);
+    }
+}
diff --git a/rmk/src/lighting/context.rs b/rmk/src/lighting/context.rs
new file mode 100644
index 000000000..594ac8f12
--- /dev/null
+++ b/rmk/src/lighting/context.rs
@@ -0,0 +1,74 @@
+/// Bounded snapshot of RMK's layer state.
+///
+/// The complete active set is retained because the effective layer alone is
+/// insufficient for transparent fallthrough and held-layer indicators.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct LayerState {
+    pub effective: u8,
+    pub default: u8,
+    active: u64,
+}
+
+impl LayerState {
+    pub const CAPACITY: u8 = 64;
+
+    pub const fn new(effective: u8, default: u8, active: u64) -> Self {
+        Self {
+            effective,
+            default,
+            active,
+        }
+    }
+
+    pub const fn active_bits(self) -> u64 {
+        self.active
+    }
+
+    pub const fn is_active(self, layer: u8) -> bool {
+        layer < Self::CAPACITY && self.active & (1_u64 << layer) != 0
+    }
+}
+
+impl Default for LayerState {
+    fn default() -> Self {
+        Self::new(0, 0, 1)
+    }
+}
+
+/// Host-controlled keyboard indicators available to lighting sources.
+///
+/// This deliberately mirrors the semantic HID state rather than exposing its
+/// wire bitfield. Sources can therefore use the same context on USB, BLE, and
+/// split peripherals.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct IndicatorState {
+    pub num_lock: bool,
+    pub caps_lock: bool,
+    pub scroll_lock: bool,
+    pub compose: bool,
+    pub kana: bool,
+}
+
+/// State RMK makes available to standard and external lighting sources.
+/// Additional firmware-specific state can be carried in a source of the
+/// board's own type; it does not belong in the core compositor.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct LightingContext {
+    pub layers: LayerState,
+    pub indicators: IndicatorState,
+}
+
+/// Access to RMK's standard lighting state from a board-extended snapshot.
+///
+/// A board may add battery, connection, or sensor fields to its snapshot and
+/// still reuse built-in layer and indicator sources by implementing this
+/// trait. The compositor itself remains generic over the complete context.
+pub trait LightingContextProvider {
+    fn lighting_context(&self) -> &LightingContext;
+}
+
+impl LightingContextProvider for LightingContext {
+    fn lighting_context(&self) -> &LightingContext {
+        self
+    }
+}
diff --git a/rmk/src/lighting/effect.rs b/rmk/src/lighting/effect.rs
new file mode 100644
index 000000000..3dbc25fee
--- /dev/null
+++ b/rmk/src/lighting/effect.rs
@@ -0,0 +1,247 @@
+use super::Rgb8;
+
+/// One opaque effect sample and the next instant its visible value can
+/// change. `None` means the sample is static until an external event.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct EffectSample<C> {
+    pub color: C,
+    pub next_change_ms: Option<u64>,
+}
+
+/// Extensibility boundary for effects supplied by board or third-party
+/// crates. The compositor owns ordering and scheduling; the effect owns only
+/// its waveform.
+pub trait LightingEffect<C> {
+    fn sample(&self, now_ms: u64) -> EffectSample<C>;
+}
+
+/// Small built-in set sufficient for static scenes and common indicators.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum BuiltinEffect {
+    Solid {
+        color: Rgb8,
+    },
+    Blink {
+        color: Rgb8,
+        period_ms: u32,
+        phase_ms: u32,
+        duty: u8,
+    },
+    Breathe {
+        color: Rgb8,
+        period_ms: u32,
+        phase_ms: u32,
+        step_ms: u16,
+    },
+}
+
+impl Default for BuiltinEffect {
+    fn default() -> Self {
+        Self::solid(Rgb8::BLACK)
+    }
+}
+
+impl BuiltinEffect {
+    pub const fn solid(color: Rgb8) -> Self {
+        Self::Solid { color }
+    }
+}
+
+impl LightingEffect<Rgb8> for BuiltinEffect {
+    fn sample(&self, now_ms: u64) -> EffectSample<Rgb8> {
+        match *self {
+            Self::Solid { color } => EffectSample {
+                color,
+                next_change_ms: None,
+            },
+            Self::Blink {
+                color,
+                period_ms,
+                phase_ms,
+                duty,
+            } => {
+                if color == Rgb8::BLACK {
+                    return EffectSample {
+                        color,
+                        next_change_ms: None,
+                    };
+                }
+                if period_ms == 0 || duty >= 100 {
+                    return EffectSample {
+                        color,
+                        next_change_ms: None,
+                    };
+                }
+                if duty == 0 {
+                    return EffectSample {
+                        color: Rgb8::BLACK,
+                        next_change_ms: None,
+                    };
+                }
+                let local = phase_local(now_ms, period_ms, phase_ms);
+                let on_ms = ((period_ms as u64 * duty as u64) / 100) as u32;
+                if on_ms == 0 {
+                    return EffectSample {
+                        color: Rgb8::BLACK,
+                        next_change_ms: None,
+                    };
+                }
+                let (shown, delta) = if local < on_ms {
+                    (color, on_ms - local)
+                } else {
+                    (Rgb8::BLACK, period_ms - local)
+                };
+                EffectSample {
+                    color: shown,
+                    next_change_ms: now_ms.checked_add(delta as u64),
+                }
+            }
+            Self::Breathe {
+                color,
+                period_ms,
+                phase_ms,
+                step_ms,
+            } => {
+                if period_ms < 2 || step_ms == 0 || color == Rgb8::BLACK {
+                    return EffectSample {
+                        color,
+                        next_change_ms: None,
+                    };
+                }
+                let local = phase_local(now_ms, period_ms, phase_ms) as u64;
+                let period = period_ms as u64;
+                let step = step_ms as u64;
+                if step >= period {
+                    return EffectSample {
+                        color: Rgb8::BLACK,
+                        next_change_ms: None,
+                    };
+                }
+                // Quantize both sampling and scheduling to phase-local step
+                // boundaries. An unrelated event between boundaries can
+                // therefore re-render without changing the advertised value.
+                let sampled_local = local / step * step;
+                let half = period / 2;
+                let level = if sampled_local < half {
+                    sampled_local * 255 / half
+                } else {
+                    (period - sampled_local) * 255 / (period - half)
+                } as u8;
+                let delta = (step - local % step).min(period - local);
+                EffectSample {
+                    color: color.scale(level),
+                    next_change_ms: now_ms.checked_add(delta),
+                }
+            }
+        }
+    }
+}
+
+fn phase_local(now_ms: u64, period_ms: u32, phase_ms: u32) -> u32 {
+    let period = period_ms as u64;
+    ((now_ms % period + phase_ms as u64 % period) % period) as u32
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn blink_wakes_on_exact_edges_and_dark_is_opaque() {
+        let effect = BuiltinEffect::Blink {
+            color: Rgb8::new(10, 20, 30),
+            period_ms: 100,
+            phase_ms: 0,
+            duty: 25,
+        };
+        assert_eq!(effect.sample(24).next_change_ms, Some(25));
+        assert_eq!(effect.sample(25).color, Rgb8::BLACK);
+        assert_eq!(effect.sample(25).next_change_ms, Some(100));
+    }
+
+    #[test]
+    fn phase_math_does_not_overflow_at_u64_max() {
+        let effect = BuiltinEffect::Blink {
+            color: Rgb8::new(1, 2, 3),
+            period_ms: 100,
+            phase_ms: 7,
+            duty: 50,
+        };
+        assert_eq!(effect.sample(u64::MAX).next_change_ms, None);
+    }
+
+    #[test]
+    fn breathe_is_constant_between_its_reported_phase_local_boundaries() {
+        let effect = BuiltinEffect::Breathe {
+            color: Rgb8::new(200, 100, 50),
+            period_ms: 100,
+            phase_ms: 7,
+            step_ms: 10,
+        };
+        let first = effect.sample(3); // phase-local 10: exactly on a boundary
+        assert_eq!(first.next_change_ms, Some(13));
+        for now in 4..13 {
+            assert_eq!(effect.sample(now).color, first.color);
+            assert_eq!(effect.sample(now).next_change_ms, Some(13));
+        }
+        assert_ne!(effect.sample(13).color, first.color);
+    }
+
+    #[test]
+    fn degenerate_effects_are_static() {
+        let color = Rgb8::new(1, 2, 3);
+        let effects = [
+            BuiltinEffect::Blink {
+                color,
+                period_ms: 0,
+                phase_ms: 0,
+                duty: 50,
+            },
+            BuiltinEffect::Blink {
+                color,
+                period_ms: 10,
+                phase_ms: 0,
+                duty: 0,
+            },
+            BuiltinEffect::Blink {
+                color,
+                period_ms: 10,
+                phase_ms: 0,
+                duty: 1,
+            },
+            BuiltinEffect::Blink {
+                color,
+                period_ms: 10,
+                phase_ms: 0,
+                duty: 100,
+            },
+            BuiltinEffect::Breathe {
+                color,
+                period_ms: 1,
+                phase_ms: 0,
+                step_ms: 16,
+            },
+            BuiltinEffect::Breathe {
+                color,
+                period_ms: 10,
+                phase_ms: 0,
+                step_ms: 0,
+            },
+            BuiltinEffect::Blink {
+                color: Rgb8::BLACK,
+                period_ms: 10,
+                phase_ms: 0,
+                duty: 50,
+            },
+            BuiltinEffect::Breathe {
+                color: Rgb8::BLACK,
+                period_ms: 10,
+                phase_ms: 0,
+                step_ms: 1,
+            },
+        ];
+        for effect in effects {
+            assert_eq!(effect.sample(5).next_change_ms, None);
+        }
+    }
+}
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
new file mode 100644
index 000000000..79b4f5449
--- /dev/null
+++ b/rmk/src/lighting/mod.rs
@@ -0,0 +1,59 @@
+//! Hardware- and protocol-independent lighting primitives.
+//!
+//! The module separates stable semantic LED identity, local frame slots, and
+//! physical routing. Rendering uses caller-provided fixed storage and performs
+//! no allocation, I/O, sleeping, or protocol handling.
+
+use embassy_sync::channel::Channel;
+use rmk_types::action::LightAction;
+
+use crate::RawMutex;
+
+pub mod color;
+pub mod compositor;
+pub mod context;
+pub mod effect;
+pub mod output;
+pub mod processor;
+pub mod rmk_state;
+pub mod selector;
+pub mod service;
+pub mod source;
+pub mod standard;
+pub mod topology;
+
+pub use color::Rgb8;
+pub use compositor::{Compositor, LogicalFrame, RenderError, RenderResult, RenderTransaction};
+pub use context::{IndicatorState, LayerState, LightingContext, LightingContextProvider};
+pub use effect::{BuiltinEffect, EffectSample, LightingEffect};
+pub use output::{
+    BrightnessTransform, OutputSelection, RouteError, RoutedFrameSink, RoutedPixel, ValidatedRouting, VisitSummary,
+};
+pub use processor::{LightingMailbox, LightingProcessor};
+pub use rmk_state::{KeymapLightingState, TooManyLayers};
+pub use selector::{LedSelector, ResolveError, ResolvedTargets};
+pub use service::{
+    CommandResult, Invalidation, LightingEngine, LightingOutput, LightingService, OutputCompletion, OutputOperation,
+    OutputState, PowerState, RenderOutcome, ServiceAction, SnapshotProvider,
+};
+pub use source::{
+    DenseSource, Indicator, IndicatorScene, IndicatorScenes, LayerPolicy, LayerScene, LayerScenes, OverlayError,
+    OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
+};
+pub use standard::{
+    BackgroundMode, BackgroundPatch, BackgroundState, EmptySource, OverlayBatch, OverlayCell, StandardCommand,
+    StandardError, StandardInput, StandardLightingEngine, StandardMutableState, StandardState, UniformBackground,
+};
+pub use topology::*;
+
+/// Dedicated lossless path for edge-sensitive lighting key actions. State
+/// notifications may be coalesced, but brightness/toggle/mode presses may not.
+static LIGHT_ACTIONS: Channel<RawMutex, LightAction, 4> = Channel::new();
+
+pub(crate) async fn send_light_action(action: LightAction) {
+    LIGHT_ACTIONS.send(action).await;
+}
+
+async fn next_light_action() -> LightAction {
+    LIGHT_ACTIONS.receive().await
+}
diff --git a/rmk/src/lighting/output.rs b/rmk/src/lighting/output.rs
new file mode 100644
index 000000000..e3fe95f78
--- /dev/null
+++ b/rmk/src/lighting/output.rs
@@ -0,0 +1,583 @@
+//! Allocation-free routing from semantic lighting frames to physical outputs.
+//!
+//! [`LogicalFrame`] order is the dense [`LedSlot`] order defined by a
+//! [`LightingTopology`]. It is deliberately unrelated to electrical chain
+//! order. This module joins a logical frame with validated [`LightingRouting`]
+//! and visits pixels in physical output order without depending on a HAL or
+//! concrete driver.
+
+use super::color::Rgb8;
+use super::compositor::{LogicalFrame, OutputTransform};
+use super::topology::{
+    LedId, LedSlot, LightingNodeId, LightingRouting, LightingTopology, OutputCapabilities, OutputId, OutputMetadata,
+    ValidationError, validate,
+};
+
+/// A topology and routing pair whose complete structural contract has been
+/// validated.
+///
+/// Construction checks that every semantic slot has exactly one route, every
+/// physical address is unique and in bounds, and complete outputs have no
+/// holes. Keeping this proof object separate prevents frame delivery from
+/// repeating quadratic validation on every write.
+#[derive(Clone, Copy, Debug)]
+pub struct ValidatedRouting<'a> {
+    topology: LightingTopology<'a>,
+    routing: LightingRouting<'a>,
+}
+
+impl<'a> ValidatedRouting<'a> {
+    pub fn new(topology: LightingTopology<'a>, routing: LightingRouting<'a>) -> Result<Self, ValidationError> {
+        validate(&topology, &routing)?;
+        Ok(Self { topology, routing })
+    }
+
+    pub const fn topology(&self) -> &LightingTopology<'a> {
+        &self.topology
+    }
+
+    pub const fn routing(&self) -> &LightingRouting<'a> {
+        &self.routing
+    }
+
+    /// Visit a standard logical frame in deterministic physical order.
+    pub fn visit_frame<C: Copy, const N: usize, S: RoutedFrameSink<C>>(
+        &self,
+        frame: &LogicalFrame<C, N>,
+        selection: OutputSelection,
+        sink: &mut S,
+    ) -> Result<VisitSummary, RouteError<S::Error>> {
+        self.visit_slice(frame.as_slice(), selection, sink)
+    }
+
+    /// Visit any logical slice whose indices use this topology's slot order.
+    ///
+    /// Outputs are visited in `LightingRouting::outputs` order and pixels in
+    /// ascending physical index. Route table order and semantic slot order do
+    /// not affect delivery. Sparse-output holes simply produce no pixel call.
+    /// The frame length is checked before the first sink callback.
+    pub fn visit_slice<C: Copy, S: RoutedFrameSink<C>>(
+        &self,
+        frame: &[C],
+        selection: OutputSelection,
+        sink: &mut S,
+    ) -> Result<VisitSummary, RouteError<S::Error>> {
+        let expected = self.topology.len();
+        if frame.len() != expected {
+            return Err(RouteError::FrameLength {
+                expected,
+                actual: frame.len(),
+            });
+        }
+
+        let mut summary = VisitSummary::default();
+        for output in self.routing.outputs {
+            if !selection.matches(output.capabilities) {
+                continue;
+            }
+
+            sink.begin_output(*output).map_err(RouteError::Sink)?;
+            summary.outputs += 1;
+
+            for physical_index in 0..output.pixel_count {
+                let Some(route) = self.routing.routes.iter().find(|route| {
+                    route.node == output.node && route.output == output.id && route.physical_index == physical_index
+                }) else {
+                    // Validated sparse outputs may intentionally contain holes.
+                    continue;
+                };
+                let slot_index = route.slot.index();
+                let led = self
+                    .topology
+                    .led(route.slot)
+                    .expect("validated routes always reference a topology slot");
+                sink.write_pixel(RoutedPixel {
+                    slot: route.slot,
+                    led_id: led.id,
+                    node: output.node,
+                    output: output.id,
+                    physical_index,
+                    capabilities: output.capabilities,
+                    value: frame[slot_index],
+                })
+                .map_err(RouteError::Sink)?;
+                summary.pixels += 1;
+            }
+
+            sink.end_output(*output).map_err(RouteError::Sink)?;
+        }
+
+        Ok(summary)
+    }
+}
+
+/// Capability filter applied before an output is presented to a sink.
+///
+/// `required` bits must all be present. When `any` is non-empty, at least one
+/// of those bits must also be present. This supports, for example, selecting
+/// addressable RGB/RGBW outputs separately from binary or intensity outputs
+/// while retaining one heterogeneous route table.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct OutputSelection {
+    required: OutputCapabilities,
+    any: OutputCapabilities,
+}
+
+impl OutputSelection {
+    pub const ALL: Self = Self {
+        required: OutputCapabilities::NONE,
+        any: OutputCapabilities::NONE,
+    };
+
+    pub const fn requiring(required: OutputCapabilities) -> Self {
+        Self {
+            required,
+            any: OutputCapabilities::NONE,
+        }
+    }
+
+    pub const fn any_of(any: OutputCapabilities) -> Self {
+        Self {
+            required: OutputCapabilities::NONE,
+            any,
+        }
+    }
+
+    pub const fn requiring_any(required: OutputCapabilities, any: OutputCapabilities) -> Self {
+        Self { required, any }
+    }
+
+    pub const fn required(self) -> OutputCapabilities {
+        self.required
+    }
+
+    pub const fn any(self) -> OutputCapabilities {
+        self.any
+    }
+
+    pub const fn matches(self, capabilities: OutputCapabilities) -> bool {
+        capabilities.contains(self.required) && (self.any.bits() == 0 || capabilities.intersects(self.any))
+    }
+}
+
+impl Default for OutputSelection {
+    fn default() -> Self {
+        Self::ALL
+    }
+}
+
+/// One logical value annotated with both semantic and physical identity.
+///
+/// A heterogeneous sink can choose RGB, RGBW, intensity, or binary conversion
+/// from `capabilities` and store the result in board-owned output buffers.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct RoutedPixel<C> {
+    pub slot: LedSlot,
+    pub led_id: LedId,
+    pub node: LightingNodeId,
+    pub output: OutputId,
+    pub physical_index: u16,
+    pub capabilities: OutputCapabilities,
+    pub value: C,
+}
+
+/// Hardware-independent consumer of physically addressed frame values.
+///
+/// Implementations normally fill caller-owned fixed arrays or forward each
+/// output to a board-specific adapter. The core does not prescribe a common
+/// physical pixel type: the output metadata and every pixel carry capability
+/// information so the sink owns conversion policy.
+pub trait RoutedFrameSink<C> {
+    type Error;
+
+    fn begin_output(&mut self, _output: OutputMetadata) -> Result<(), Self::Error> {
+        Ok(())
+    }
+
+    fn write_pixel(&mut self, pixel: RoutedPixel<C>) -> Result<(), Self::Error>;
+
+    fn end_output(&mut self, _output: OutputMetadata) -> Result<(), Self::Error> {
+        Ok(())
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub struct VisitSummary {
+    pub outputs: usize,
+    pub pixels: usize,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum RouteError<E> {
+    FrameLength { expected: usize, actual: usize },
+    Sink(E),
+}
+
+/// User brightness applied after composition and before changed detection.
+///
+/// This is intentionally not a hardware safety limit. Drivers must still
+/// enforce their immutable channel/current policy after routing.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct BrightnessTransform {
+    level: u8,
+}
+
+impl BrightnessTransform {
+    pub const OFF: Self = Self::new(0);
+    pub const FULL: Self = Self::new(u8::MAX);
+
+    pub const fn new(level: u8) -> Self {
+        Self { level }
+    }
+
+    pub const fn level(self) -> u8 {
+        self.level
+    }
+
+    pub fn set_level(&mut self, level: u8) {
+        self.level = level;
+    }
+}
+
+impl Default for BrightnessTransform {
+    fn default() -> Self {
+        Self::FULL
+    }
+}
+
+impl OutputTransform<Rgb8> for BrightnessTransform {
+    fn transform(&mut self, _slot: LedSlot, color: Rgb8) -> Rgb8 {
+        color.scale(self.level)
+    }
+
+    fn next_change_ms(
+        &self,
+        _slot: LedSlot,
+        _before: Rgb8,
+        _after: Rgb8,
+        source_next_change_ms: Option<u64>,
+    ) -> Option<u64> {
+        // Zero brightness makes every possible source value visibly black,
+        // so source animation cannot change the transformed frame.
+        (self.level != 0).then_some(source_next_change_ms).flatten()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::compositor::{Compositor, Contribution, LightingSource, RenderInput};
+    use super::super::effect::EffectSample;
+    use super::super::topology::{LedMetadata, MatrixSize, OutputCoverage, PhysicalLayout, PhysicalRoute, ZoneSpan};
+    use super::*;
+
+    const RGB_ADDRESSABLE: OutputCapabilities = OutputCapabilities::RGB.union(OutputCapabilities::ADDRESSABLE);
+
+    static LEDS: [LedMetadata; 4] = [
+        LedMetadata {
+            id: LedId(100),
+            key: None,
+            position: None,
+            zones: ZoneSpan::EMPTY,
+        },
+        LedMetadata {
+            id: LedId(200),
+            key: None,
+            position: None,
+            zones: ZoneSpan::EMPTY,
+        },
+        LedMetadata {
+            id: LedId(300),
+            key: None,
+            position: None,
+            zones: ZoneSpan::EMPTY,
+        },
+        LedMetadata {
+            id: LedId(400),
+            key: None,
+            position: None,
+            zones: ZoneSpan::EMPTY,
+        },
+    ];
+
+    static OUTPUTS: [OutputMetadata; 3] = [
+        OutputMetadata {
+            node: LightingNodeId(0),
+            id: OutputId(0),
+            pixel_count: 2,
+            capabilities: RGB_ADDRESSABLE,
+            coverage: OutputCoverage::Complete,
+        },
+        OutputMetadata {
+            node: LightingNodeId(0),
+            id: OutputId(1),
+            pixel_count: 1,
+            capabilities: OutputCapabilities::BINARY,
+            coverage: OutputCoverage::Complete,
+        },
+        OutputMetadata {
+            node: LightingNodeId(1),
+            id: OutputId(0),
+            pixel_count: 1,
+            capabilities: OutputCapabilities::INTENSITY,
+            coverage: OutputCoverage::Complete,
+        },
+    ];
+
+    // Deliberately neither semantic-slot nor physical-output order.
+    static ROUTES: [PhysicalRoute; 4] = [
+        PhysicalRoute {
+            slot: LedSlot(0),
+            node: LightingNodeId(1),
+            output: OutputId(0),
+            physical_index: 0,
+        },
+        PhysicalRoute {
+            slot: LedSlot(2),
+            node: LightingNodeId(0),
+            output: OutputId(1),
+            physical_index: 0,
+        },
+        PhysicalRoute {
+            slot: LedSlot(1),
+            node: LightingNodeId(0),
+            output: OutputId(0),
+            physical_index: 1,
+        },
+        PhysicalRoute {
+            slot: LedSlot(3),
+            node: LightingNodeId(0),
+            output: OutputId(0),
+            physical_index: 0,
+        },
+    ];
+
+    fn topology() -> LightingTopology<'static> {
+        LightingTopology {
+            matrix: MatrixSize::new(0, 0),
+            keys: &[],
+            physical_layout: PhysicalLayout::EMPTY,
+            leds: &LEDS,
+            zones: &[],
+            zone_memberships: &[],
+        }
+    }
+
+    fn validated() -> ValidatedRouting<'static> {
+        ValidatedRouting::new(
+            topology(),
+            LightingRouting {
+                outputs: &OUTPUTS,
+                routes: &ROUTES,
+            },
+        )
+        .unwrap()
+    }
+
+    #[derive(Default)]
+    struct RecordingSink<C> {
+        begun: std::vec::Vec<(LightingNodeId, OutputId)>,
+        pixels: std::vec::Vec<RoutedPixel<C>>,
+        ended: std::vec::Vec<(LightingNodeId, OutputId)>,
+    }
+
+    impl<C> RoutedFrameSink<C> for RecordingSink<C> {
+        type Error = core::convert::Infallible;
+
+        fn begin_output(&mut self, output: OutputMetadata) -> Result<(), Self::Error> {
+            self.begun.push((output.node, output.id));
+            Ok(())
+        }
+
+        fn write_pixel(&mut self, pixel: RoutedPixel<C>) -> Result<(), Self::Error> {
+            self.pixels.push(pixel);
+            Ok(())
+        }
+
+        fn end_output(&mut self, output: OutputMetadata) -> Result<(), Self::Error> {
+            self.ended.push((output.node, output.id));
+            Ok(())
+        }
+    }
+
+    #[test]
+    fn physical_visit_order_is_independent_of_semantic_and_route_order() {
+        let frame = LogicalFrame::new(0u16);
+        let mut values = frame;
+        *values.as_mut_array() = [10, 20, 30, 40];
+        let mut sink = RecordingSink::default();
+
+        let summary = validated()
+            .visit_frame(&values, OutputSelection::ALL, &mut sink)
+            .unwrap();
+
+        assert_eq!(summary, VisitSummary { outputs: 3, pixels: 4 });
+        assert_eq!(
+            sink.begun,
+            [
+                (LightingNodeId(0), OutputId(0)),
+                (LightingNodeId(0), OutputId(1)),
+                (LightingNodeId(1), OutputId(0))
+            ]
+        );
+        assert_eq!(
+            sink.pixels
+                .iter()
+                .map(|pixel| (pixel.slot, pixel.led_id, pixel.physical_index, pixel.value))
+                .collect::<std::vec::Vec<_>>(),
+            [
+                (LedSlot(3), LedId(400), 0, 40),
+                (LedSlot(1), LedId(200), 1, 20),
+                (LedSlot(2), LedId(300), 0, 30),
+                (LedSlot(0), LedId(100), 0, 10),
+            ]
+        );
+        assert_eq!(sink.ended, sink.begun);
+    }
+
+    #[test]
+    fn capability_selection_handles_heterogeneous_outputs() {
+        let frame = [10u8, 20, 30, 40];
+
+        let mut rgb = RecordingSink::default();
+        let summary = validated()
+            .visit_slice(&frame, OutputSelection::requiring(OutputCapabilities::RGB), &mut rgb)
+            .unwrap();
+        assert_eq!(summary, VisitSummary { outputs: 1, pixels: 2 });
+        assert!(
+            rgb.pixels
+                .iter()
+                .all(|pixel| pixel.capabilities.contains(OutputCapabilities::RGB))
+        );
+
+        let mut mono = RecordingSink::default();
+        let summary = validated()
+            .visit_slice(
+                &frame,
+                OutputSelection::any_of(OutputCapabilities::BINARY.union(OutputCapabilities::INTENSITY)),
+                &mut mono,
+            )
+            .unwrap();
+        assert_eq!(summary, VisitSummary { outputs: 2, pixels: 2 });
+        assert_eq!(
+            mono.pixels
+                .iter()
+                .map(|pixel| pixel.value)
+                .collect::<std::vec::Vec<_>>(),
+            [30, 10]
+        );
+    }
+
+    #[test]
+    fn frame_length_is_rejected_before_sink_observes_output() {
+        let mut sink = RecordingSink::default();
+        assert_eq!(
+            validated().visit_slice(&[1u8, 2, 3], OutputSelection::ALL, &mut sink),
+            Err(RouteError::FrameLength { expected: 4, actual: 3 })
+        );
+        assert!(sink.begun.is_empty());
+        assert!(sink.pixels.is_empty());
+    }
+
+    #[test]
+    fn invalid_routing_cannot_construct_proof_object() {
+        let duplicate = [ROUTES[0], ROUTES[0], ROUTES[2], ROUTES[3]];
+        assert!(matches!(
+            ValidatedRouting::new(
+                topology(),
+                LightingRouting {
+                    outputs: &OUTPUTS,
+                    routes: &duplicate,
+                },
+            ),
+            Err(ValidationError::DuplicateRouteForSlot { .. })
+        ));
+    }
+
+    #[test]
+    fn sparse_physical_holes_are_skipped_without_placeholder_values() {
+        let leds = [LEDS[0]];
+        let outputs = [OutputMetadata {
+            node: LightingNodeId(9),
+            id: OutputId(4),
+            pixel_count: 3,
+            capabilities: OutputCapabilities::INTENSITY,
+            coverage: OutputCoverage::Sparse,
+        }];
+        let routes = [PhysicalRoute {
+            slot: LedSlot(0),
+            node: LightingNodeId(9),
+            output: OutputId(4),
+            physical_index: 2,
+        }];
+        let routing = ValidatedRouting::new(
+            LightingTopology {
+                matrix: MatrixSize::new(0, 0),
+                keys: &[],
+                physical_layout: PhysicalLayout::EMPTY,
+                leds: &leds,
+                zones: &[],
+                zone_memberships: &[],
+            },
+            LightingRouting {
+                outputs: &outputs,
+                routes: &routes,
+            },
+        )
+        .unwrap();
+        let mut sink = RecordingSink::default();
+        assert_eq!(
+            routing.visit_slice(&[77u8], OutputSelection::ALL, &mut sink).unwrap(),
+            VisitSummary { outputs: 1, pixels: 1 }
+        );
+        assert_eq!(sink.pixels[0].physical_index, 2);
+    }
+
+    struct AnimatedSource;
+
+    impl<Context> LightingSource<Rgb8, Context> for AnimatedSource {
+        fn len(&self, _: &RenderInput<'_, Context>) -> usize {
+            1
+        }
+
+        fn slot(&self, _: usize, _: &RenderInput<'_, Context>) -> LedSlot {
+            LedSlot(0)
+        }
+
+        fn contribution(&mut self, _: usize, _: &RenderInput<'_, Context>) -> Contribution<Rgb8> {
+            Contribution::Opaque(EffectSample {
+                color: Rgb8::new(255, 128, 64),
+                next_change_ms: Some(25),
+            })
+        }
+    }
+
+    #[test]
+    fn brightness_is_applied_before_diffing_and_zero_suppresses_deadlines() {
+        let compositor = Compositor::<Rgb8, 1>::new(Rgb8::BLACK);
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        let mut half = BrightnessTransform::new(128);
+        let mut source = AnimatedSource;
+        let mut tx = compositor.begin(0, &(), Rgb8::BLACK, &mut frame);
+        tx.apply(0, &mut source).unwrap();
+        let result = tx.finish_with(&mut half);
+        assert_eq!(frame.as_slice(), &[Rgb8::new(128, 64, 32)]);
+        assert_eq!(result.next_wake_ms, Some(25));
+
+        let mut off = BrightnessTransform::OFF;
+        let mut tx = compositor.begin(0, &(), Rgb8::BLACK, &mut frame);
+        tx.apply(0, &mut source).unwrap();
+        let result = tx.finish_with(&mut off);
+        assert_eq!(frame.as_slice(), &[Rgb8::BLACK]);
+        assert_eq!(result.next_wake_ms, None);
+    }
+
+    #[test]
+    fn brightness_level_is_runtime_mutable() {
+        let color = Rgb8::new(255, 100, 1);
+        let mut brightness = BrightnessTransform::OFF;
+        assert_eq!(brightness.transform(LedSlot(0), color), Rgb8::BLACK);
+        brightness.set_level(u8::MAX);
+        assert_eq!(brightness.level(), u8::MAX);
+        assert_eq!(brightness.transform(LedSlot(0), color), color);
+    }
+}
diff --git a/rmk/src/lighting/processor.rs b/rmk/src/lighting/processor.rs
new file mode 100644
index 000000000..a176ea667
--- /dev/null
+++ b/rmk/src/lighting/processor.rs
@@ -0,0 +1,358 @@
+//! RMK event, command, deadline, and output integration for lighting.
+
+use core::cell::Cell;
+use core::num::NonZeroU32;
+
+use embassy_futures::select::{Either, Either3, Either4, select, select3, select4};
+use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
+use embassy_sync::channel::Channel;
+use embassy_sync::mutex::Mutex;
+use embassy_sync::signal::Signal;
+use embassy_time::{Instant, Timer};
+use rmk_types::action::LightAction;
+
+use super::service::{
+    LightingEngine, LightingOutput, LightingService, OutputCompletion, OutputOperation, PowerState, ServiceAction,
+    ServiceError, SnapshotProvider,
+};
+use crate::RawMutex;
+use crate::core_traits::Runnable;
+use crate::event::{
+    EventSubscriber, LayerChangeEvent, LedIndicatorEvent, LightingChangedEvent, SleepStateEvent, publish_event,
+};
+use crate::processor::Processor;
+
+/// Reliable single-owner request/reply path used by Rynk, Vial, or a board
+/// API. Concurrent callers are serialized; commands are never coalesced.
+pub struct LightingMailbox<Command, Reply, Error, const CAPACITY: usize> {
+    requests: Channel<RawMutex, MailboxRequest<Command>, CAPACITY>,
+    response: Signal<RawMutex, MailboxResponse<Reply, Error>>,
+    retry_output: Signal<RawMutex, ()>,
+    caller: Mutex<RawMutex, ()>,
+    next_id: BlockingMutex<RawMutex, Cell<u32>>,
+}
+
+struct MailboxRequest<Command> {
+    id: u32,
+    command: Command,
+}
+
+struct MailboxResponse<Reply, Error> {
+    id: u32,
+    result: Result<Reply, Error>,
+}
+
+impl<Command, Reply, Error, const CAPACITY: usize> LightingMailbox<Command, Reply, Error, CAPACITY> {
+    pub const fn new() -> Self {
+        Self {
+            requests: Channel::new(),
+            response: Signal::new(),
+            retry_output: Signal::new(),
+            caller: Mutex::new(()),
+            next_id: BlockingMutex::new(Cell::new(0)),
+        }
+    }
+
+    /// Submit one command and wait for authoritative service readback.
+    pub async fn request(&self, command: Command) -> Result<Reply, Error> {
+        let _caller = self.caller.lock().await;
+        let id = self.next_id.lock(|next| {
+            let id = next.get();
+            next.set(id.wrapping_add(1));
+            id
+        });
+        self.requests.send(MailboxRequest { id, command }).await;
+        loop {
+            let response = self.response.wait().await;
+            if response.id == id {
+                return response.result;
+            }
+        }
+    }
+
+    /// Wake a processor whose output policy blocked automatic retries.
+    pub fn retry_output(&self) {
+        self.retry_output.signal(());
+    }
+
+    async fn receive(&self) -> MailboxRequest<Command> {
+        self.requests.receive().await
+    }
+
+    fn reply(&self, id: u32, result: Result<Reply, Error>) {
+        self.response.signal(MailboxResponse { id, result });
+    }
+}
+
+impl<Command, Reply, Error, const CAPACITY: usize> Default for LightingMailbox<Command, Reply, Error, CAPACITY> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Sole mutable runtime owner for one lighting engine and output.
+///
+/// State notifications invalidate a fresh authoritative snapshot. LightAction
+/// edges and mailbox commands remain reliable and ordered. The loop arms only
+/// the deadline returned by the service; static output has no timer.
+#[::rmk::macros::processor(subscribe = [LayerChangeEvent, LedIndicatorEvent, SleepStateEvent])]
+#[::rmk::macros::runnable_generated]
+pub struct LightingProcessor<'mailbox, P, E, O, const COMMAND_CAPACITY: usize>
+where
+    P: SnapshotProvider,
+    E: LightingEngine<P::Snapshot>,
+    E::Input: From<LightAction>,
+    E::Command: Send,
+    E::Reply: Send,
+    E::Error: Send,
+    O: LightingOutput<E::Frame>,
+{
+    service: LightingService<P, E>,
+    output: O,
+    mailbox: &'mailbox LightingMailbox<E::Command, E::Reply, E::Error, COMMAND_CAPACITY>,
+    engine_retry: NonZeroU32,
+}
+
+impl<'mailbox, P, E, O, const COMMAND_CAPACITY: usize> LightingProcessor<'mailbox, P, E, O, COMMAND_CAPACITY>
+where
+    P: SnapshotProvider,
+    E: LightingEngine<P::Snapshot>,
+    E::Input: From<LightAction>,
+    E::Command: Send,
+    E::Reply: Send,
+    E::Error: Send,
+    O: LightingOutput<E::Frame>,
+{
+    pub fn new(
+        service: LightingService<P, E>,
+        output: O,
+        mailbox: &'mailbox LightingMailbox<E::Command, E::Reply, E::Error, COMMAND_CAPACITY>,
+    ) -> Self {
+        Self {
+            service,
+            output,
+            mailbox,
+            engine_retry: NonZeroU32::new(10).unwrap(),
+        }
+    }
+
+    pub fn with_engine_retry(mut self, delay: NonZeroU32) -> Self {
+        self.engine_retry = delay;
+        self
+    }
+
+    pub const fn service(&self) -> &LightingService<P, E> {
+        &self.service
+    }
+
+    pub fn service_mut(&mut self) -> &mut LightingService<P, E> {
+        &mut self.service
+    }
+
+    fn publish_pending_lighting_change(&mut self) {
+        if self.service.take_lighting_change() {
+            publish_event(LightingChangedEvent::new());
+        }
+    }
+
+    /// Drive immediate lifecycle/render/present work and return the next
+    /// absolute millisecond deadline.
+    async fn drive_until_wait(&mut self) -> Option<u64> {
+        loop {
+            let now_ms = Instant::now().as_millis();
+            let action = match self.service.next_action(now_ms) {
+                Ok(action) => action,
+                Err(ServiceError::Engine(_)) => {
+                    return now_ms.checked_add(self.engine_retry.get() as u64);
+                }
+                Err(ServiceError::OperationInFlight(_)) => {
+                    // Only this method begins and completes operations, so an
+                    // in-flight action here is an internal invariant failure.
+                    return now_ms.checked_add(self.engine_retry.get() as u64);
+                }
+            };
+
+            match action {
+                ServiceAction::Wait { next_wake_ms } => {
+                    self.publish_pending_lighting_change();
+                    return next_wake_ms;
+                }
+                ServiceAction::Initialize => {
+                    let completion = match self.output.initialize().await {
+                        Ok(()) => OutputCompletion::Succeeded,
+                        Err(error) => OutputCompletion::Failed {
+                            retry_in_ms: self.output.retry_after(OutputOperation::Initialize, &error),
+                        },
+                    };
+                    let _ = self.service.complete_output(Instant::now().as_millis(), completion);
+                }
+                ServiceAction::Present(frame) => {
+                    let completion = match self.output.present(frame).await {
+                        Ok(()) => OutputCompletion::Succeeded,
+                        Err(error) => OutputCompletion::Failed {
+                            retry_in_ms: self.output.retry_after(OutputOperation::Present, &error),
+                        },
+                    };
+                    let _ = self.service.complete_output(Instant::now().as_millis(), completion);
+                }
+                ServiceAction::Suspend => {
+                    let completion = match self.output.suspend().await {
+                        Ok(()) => OutputCompletion::Succeeded,
+                        Err(error) => OutputCompletion::Failed {
+                            retry_in_ms: self.output.retry_after(OutputOperation::Suspend, &error),
+                        },
+                    };
+                    let _ = self.service.complete_output(Instant::now().as_millis(), completion);
+                }
+                ServiceAction::Resume => {
+                    let completion = match self.output.resume().await {
+                        Ok(()) => OutputCompletion::Succeeded,
+                        Err(error) => OutputCompletion::Failed {
+                            retry_in_ms: self.output.retry_after(OutputOperation::Resume, &error),
+                        },
+                    };
+                    let _ = self.service.complete_output(Instant::now().as_millis(), completion);
+                }
+            }
+            self.publish_pending_lighting_change();
+        }
+    }
+
+    async fn handle_mailbox_command(&mut self, request: MailboxRequest<E::Command>) {
+        let response = self.service.handle_command(Instant::now().as_millis(), request.command);
+        self.publish_pending_lighting_change();
+        self.mailbox.reply(request.id, response);
+    }
+
+    async fn on_layer_change_event(&mut self, _event: LayerChangeEvent) {
+        self.service.request_render();
+    }
+
+    async fn on_led_indicator_event(&mut self, _event: LedIndicatorEvent) {
+        self.service.request_render();
+    }
+
+    async fn on_sleep_state_event(&mut self, event: SleepStateEvent) {
+        let target = if event.0 {
+            PowerState::Suspended
+        } else {
+            PowerState::Active
+        };
+        let _ = self.service.set_power(target);
+    }
+}
+
+impl<P, E, O, const COMMAND_CAPACITY: usize> Runnable for LightingProcessor<'_, P, E, O, COMMAND_CAPACITY>
+where
+    P: SnapshotProvider,
+    E: LightingEngine<P::Snapshot>,
+    E::Input: From<LightAction>,
+    E::Command: Send,
+    E::Reply: Send,
+    E::Error: Send,
+    O: LightingOutput<E::Frame>,
+{
+    async fn run(&mut self) -> ! {
+        let mut subscriber = <Self as Processor>::subscriber();
+        if crate::state::current_sleeping() {
+            let _ = self.service.set_power(PowerState::Suspended);
+        }
+
+        loop {
+            let deadline = self.drive_until_wait().await;
+            match deadline {
+                Some(deadline) => {
+                    match select4(
+                        Timer::at(Instant::from_millis(deadline)),
+                        subscriber.next_event(),
+                        self.mailbox.receive(),
+                        select(self.mailbox.retry_output.wait(), super::next_light_action()),
+                    )
+                    .await
+                    {
+                        Either4::First(_) => {}
+                        Either4::Second(event) => self.process(event).await,
+                        Either4::Third(request) => self.handle_mailbox_command(request).await,
+                        Either4::Fourth(Either::First(())) => {
+                            let _ = self.service.retry_output_now();
+                        }
+                        Either4::Fourth(Either::Second(action)) => {
+                            let _ = self.service.on_input(E::Input::from(action));
+                            self.publish_pending_lighting_change();
+                        }
+                    }
+                }
+                None => {
+                    match select3(
+                        subscriber.next_event(),
+                        self.mailbox.receive(),
+                        select(self.mailbox.retry_output.wait(), super::next_light_action()),
+                    )
+                    .await
+                    {
+                        Either3::First(event) => self.process(event).await,
+                        Either3::Second(request) => self.handle_mailbox_command(request).await,
+                        Either3::Third(Either::First(())) => {
+                            let _ = self.service.retry_output_now();
+                        }
+                        Either3::Third(Either::Second(action)) => {
+                            let _ = self.service.on_input(E::Input::from(action));
+                            self.publish_pending_lighting_change();
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use embassy_futures::join::join;
+
+    use super::LightingMailbox;
+    use crate::test_support::test_block_on as block_on;
+
+    #[test]
+    fn mailbox_delivers_ordered_request_and_authoritative_reply() {
+        let mailbox = LightingMailbox::<u8, u16, (), 2>::new();
+        let (reply, ()) = block_on(join(mailbox.request(7), async {
+            let request = mailbox.receive().await;
+            assert_eq!(request.command, 7);
+            mailbox.reply(request.id, Ok(42));
+        }));
+        assert_eq!(reply, Ok(42));
+    }
+
+    #[test]
+    fn mailbox_propagates_command_errors() {
+        let mailbox = LightingMailbox::<(), (), u8, 1>::new();
+        let (reply, ()) = block_on(join(mailbox.request(()), async {
+            let request = mailbox.receive().await;
+            mailbox.reply(request.id, Err(9));
+        }));
+        assert_eq!(reply, Err(9));
+    }
+
+    #[test]
+    fn cancelled_request_reply_cannot_poison_the_next_caller() {
+        use embassy_futures::select::{Either, select};
+        use embassy_futures::yield_now;
+
+        let mailbox = LightingMailbox::<u8, u16, (), 2>::new();
+        let cancelled = block_on(select(mailbox.request(1), async {
+            yield_now().await;
+        }));
+        assert!(matches!(cancelled, Either::Second(())));
+
+        let (reply, ()) = block_on(join(mailbox.request(2), async {
+            let abandoned = mailbox.receive().await;
+            assert_eq!(abandoned.command, 1);
+            mailbox.reply(abandoned.id, Ok(11));
+            let current = mailbox.receive().await;
+            assert_eq!(current.command, 2);
+            mailbox.reply(current.id, Ok(22));
+        }));
+        assert_eq!(reply, Ok(22));
+    }
+}
diff --git a/rmk/src/lighting/rmk_state.rs b/rmk/src/lighting/rmk_state.rs
new file mode 100644
index 000000000..48dd83769
--- /dev/null
+++ b/rmk/src/lighting/rmk_state.rs
@@ -0,0 +1,67 @@
+//! Adapters from authoritative RMK state to lighting snapshots.
+
+use super::{IndicatorState, LayerState, LightingContext, SnapshotProvider};
+use crate::keymap::KeyMap;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct TooManyLayers {
+    pub configured: usize,
+    pub supported: usize,
+}
+
+/// Authoritative layer snapshot provider backed by the live RMK keymap.
+///
+/// Layer-change events are only wakeups. Every render and command reads this
+/// provider, so startup and coalesced events cannot leave lighting with a
+/// reconstructed or stale active-layer set.
+#[derive(Clone, Copy)]
+pub struct KeymapLightingState<'keymap, 'data> {
+    keymap: &'keymap KeyMap<'data>,
+}
+
+impl<'keymap, 'data> KeymapLightingState<'keymap, 'data> {
+    pub fn new(keymap: &'keymap KeyMap<'data>) -> Result<Self, TooManyLayers> {
+        let configured = keymap.num_layer();
+        if configured > LayerState::CAPACITY as usize {
+            return Err(TooManyLayers {
+                configured,
+                supported: LayerState::CAPACITY as usize,
+            });
+        }
+        Ok(Self { keymap })
+    }
+
+    pub const fn keymap(&self) -> &'keymap KeyMap<'data> {
+        self.keymap
+    }
+}
+
+impl SnapshotProvider for KeymapLightingState<'_, '_> {
+    type Snapshot = LightingContext;
+
+    fn snapshot(&self) -> Self::Snapshot {
+        let effective = self.keymap.get_activated_layer();
+        let default = self.keymap.get_default_layer();
+        let mut active = 1_u64 << default;
+        for layer in 0..self.keymap.num_layer() as u8 {
+            if self.keymap.is_layer_active(layer) {
+                active |= 1_u64 << layer;
+            }
+        }
+        LightingContext {
+            layers: LayerState::new(effective, default, active),
+            indicators: indicator_state(),
+        }
+    }
+}
+
+fn indicator_state() -> IndicatorState {
+    let indicator = crate::keyboard::current_led_indicator();
+    IndicatorState {
+        num_lock: indicator.num_lock(),
+        caps_lock: indicator.caps_lock(),
+        scroll_lock: indicator.scroll_lock(),
+        compose: indicator.compose(),
+        kana: indicator.kana(),
+    }
+}
diff --git a/rmk/src/lighting/selector.rs b/rmk/src/lighting/selector.rs
new file mode 100644
index 000000000..8f09e0526
--- /dev/null
+++ b/rmk/src/lighting/selector.rs
@@ -0,0 +1,216 @@
+use super::topology::{LedId, LedSlot, LightingTopology, MatrixPosition, ZoneId};
+
+/// Stable configuration-level selector. None of these variants exposes a
+/// local frame slot or electrical chain index.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum LedSelector {
+    Led(LedId),
+    Key(MatrixPosition),
+    Zone(ZoneId),
+    All,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum ResolveError {
+    EmptySelection,
+    NoMatches(LedSelector),
+    UnknownLed(LedId),
+    UnknownKey(MatrixPosition),
+    UnknownZone(ZoneId),
+    CapacityExceeded { capacity: usize },
+}
+
+/// Deduplicated, fixed-capacity target set resolved once at configuration or
+/// source installation time.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ResolvedTargets<const CAP: usize> {
+    slots: [LedSlot; CAP],
+    len: usize,
+}
+
+impl<const CAP: usize> ResolvedTargets<CAP> {
+    pub const fn new() -> Self {
+        Self {
+            slots: [LedSlot(0); CAP],
+            len: 0,
+        }
+    }
+
+    pub fn resolve(topology: &LightingTopology<'_>, selectors: &[LedSelector]) -> Result<Self, ResolveError> {
+        if selectors.is_empty() {
+            return Err(ResolveError::EmptySelection);
+        }
+        let mut resolved = Self::new();
+        for selector in selectors {
+            let mut matched = false;
+            match *selector {
+                LedSelector::Led(id) => {
+                    let slot = topology.slot(id).ok_or(ResolveError::UnknownLed(id))?;
+                    matched = true;
+                    resolved.insert(slot)?;
+                }
+                LedSelector::Key(key) => {
+                    if !topology.has_key(key) {
+                        return Err(ResolveError::UnknownKey(key));
+                    }
+                    for (slot, _) in topology.leds_for_key(key) {
+                        matched = true;
+                        resolved.insert(slot)?;
+                    }
+                }
+                LedSelector::Zone(zone) => {
+                    if !topology.zones.iter().any(|metadata| metadata.id == zone) {
+                        return Err(ResolveError::UnknownZone(zone));
+                    }
+                    for index in 0..topology.len() {
+                        let slot = LedSlot::from_index(index);
+                        if topology.has_zone(slot, zone) {
+                            matched = true;
+                            resolved.insert(slot)?;
+                        }
+                    }
+                }
+                LedSelector::All => {
+                    for index in 0..topology.len() {
+                        matched = true;
+                        resolved.insert(LedSlot::from_index(index))?;
+                    }
+                }
+            }
+            if !matched {
+                return Err(ResolveError::NoMatches(*selector));
+            }
+        }
+        Ok(resolved)
+    }
+
+    pub const fn len(&self) -> usize {
+        self.len
+    }
+
+    pub const fn is_empty(&self) -> bool {
+        self.len == 0
+    }
+
+    pub fn as_slice(&self) -> &[LedSlot] {
+        &self.slots[..self.len]
+    }
+
+    fn insert(&mut self, slot: LedSlot) -> Result<(), ResolveError> {
+        if self.as_slice().contains(&slot) {
+            return Ok(());
+        }
+        if self.len == CAP {
+            return Err(ResolveError::CapacityExceeded { capacity: CAP });
+        }
+        self.slots[self.len] = slot;
+        self.len += 1;
+        Ok(())
+    }
+}
+
+impl<const CAP: usize> Default for ResolvedTargets<CAP> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::topology::{LedMetadata, LightingTopology, MatrixSize, PhysicalLayout, ZoneMetadata, ZoneSpan};
+    use super::*;
+
+    const KEY: MatrixPosition = MatrixPosition::new(0, 0);
+    static KEYS: [MatrixPosition; 1] = [KEY];
+    static ZONES: [ZoneMetadata<'static>; 1] = [ZoneMetadata {
+        id: ZoneId(7),
+        name: "thumb",
+    }];
+    static MEMBERSHIPS: [ZoneId; 2] = [ZoneId(7), ZoneId(7)];
+    static LEDS: [LedMetadata; 3] = [
+        LedMetadata {
+            id: LedId(10),
+            key: Some(KEY),
+            position: None,
+            zones: ZoneSpan::new(0, 1),
+        },
+        LedMetadata {
+            id: LedId(20),
+            key: Some(KEY),
+            position: None,
+            zones: ZoneSpan::new(1, 1),
+        },
+        LedMetadata {
+            id: LedId(99),
+            key: None,
+            position: None,
+            zones: ZoneSpan::EMPTY,
+        },
+    ];
+
+    fn topology() -> LightingTopology<'static> {
+        LightingTopology {
+            matrix: MatrixSize::new(1, 1),
+            keys: &KEYS,
+            physical_layout: PhysicalLayout::EMPTY,
+            leds: &LEDS,
+            zones: &ZONES,
+            zone_memberships: &MEMBERSHIPS,
+        }
+    }
+
+    #[test]
+    fn resolves_keys_to_multiple_leds_and_deduplicates_selectors() {
+        let targets = ResolvedTargets::<3>::resolve(
+            &topology(),
+            &[
+                LedSelector::Led(LedId(10)),
+                LedSelector::Key(KEY),
+                LedSelector::Zone(ZoneId(7)),
+            ],
+        )
+        .unwrap();
+        assert_eq!(targets.as_slice(), &[LedSlot(0), LedSlot(1)]);
+    }
+
+    #[test]
+    fn resolution_failure_is_atomic() {
+        assert_eq!(
+            ResolvedTargets::<1>::resolve(&topology(), &[LedSelector::All]),
+            Err(ResolveError::CapacityExceeded { capacity: 1 })
+        );
+        assert_eq!(
+            ResolvedTargets::<3>::resolve(&topology(), &[LedSelector::Led(LedId(404))]),
+            Err(ResolveError::UnknownLed(LedId(404)))
+        );
+        assert_eq!(
+            ResolvedTargets::<3>::resolve(&topology(), &[]),
+            Err(ResolveError::EmptySelection)
+        );
+    }
+
+    #[test]
+    fn known_but_empty_key_or_zone_is_rejected() {
+        let empty_keys = [KEY];
+        let empty_zone = [ZoneMetadata {
+            id: ZoneId(8),
+            name: "empty",
+        }];
+        let empty = LightingTopology {
+            matrix: MatrixSize::new(1, 1),
+            keys: &empty_keys,
+            physical_layout: PhysicalLayout::EMPTY,
+            leds: &[],
+            zones: &empty_zone,
+            zone_memberships: &[],
+        };
+        assert_eq!(
+            ResolvedTargets::<1>::resolve(&empty, &[LedSelector::Key(KEY)]),
+            Err(ResolveError::NoMatches(LedSelector::Key(KEY)))
+        );
+        assert_eq!(
+            ResolvedTargets::<1>::resolve(&empty, &[LedSelector::Zone(ZoneId(8))]),
+            Err(ResolveError::NoMatches(LedSelector::Zone(ZoneId(8))))
+        );
+    }
+}
diff --git a/rmk/src/lighting/service.rs b/rmk/src/lighting/service.rs
new file mode 100644
index 000000000..447607719
--- /dev/null
+++ b/rmk/src/lighting/service.rs
@@ -0,0 +1,1045 @@
+//! Executor-independent lighting service ownership and scheduling.
+//!
+//! The service in this module deliberately knows nothing about RMK events,
+//! Embassy, pixels, or physical LED protocols. An adapter translates its event
+//! types into [`LightingEngine::Input`], polls [`LightingService::next_action`],
+//! performs the requested asynchronous output operation, and reports the
+//! result with [`LightingService::complete_output`]. Keeping that loop outside
+//! the core makes command ordering, deadlines, and retry behavior deterministic
+//! in host tests.
+
+use core::num::NonZeroU32;
+
+/// Read-only access to the current authoritative keyboard state.
+///
+/// Notifications are only invalidations: a consumer must take a fresh
+/// snapshot instead of reconstructing state from event history. This lets
+/// lossy or coalesced state notifications still converge after startup and
+/// bursts of changes. Edge-sensitive operations belong in
+/// [`LightingEngine::Input`] or [`LightingEngine::Command`].
+pub trait SnapshotProvider {
+    type Snapshot;
+
+    fn snapshot(&self) -> Self::Snapshot;
+}
+
+/// Authoritative state-change and render invalidation produced by an engine.
+///
+/// `Render` means engine-owned state changed and another render is required.
+/// Application-owned state such as layers requests a render directly through
+/// [`LightingService::request_render`] and therefore does not emit a lighting
+/// state-change notification.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub enum Invalidation {
+    #[default]
+    None,
+    Render,
+    /// Engine-owned state changed without changing the visible frame.
+    StateChanged,
+}
+
+impl Invalidation {
+    pub const fn requires_render(self) -> bool {
+        matches!(self, Self::Render)
+    }
+
+    pub const fn state_changed(self) -> bool {
+        !matches!(self, Self::None)
+    }
+}
+
+/// Result of a serialized mutation request.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct CommandResult<R> {
+    pub reply: R,
+    pub invalidation: Invalidation,
+}
+
+impl<R> CommandResult<R> {
+    pub const fn new(reply: R, invalidation: Invalidation) -> Self {
+        Self { reply, invalidation }
+    }
+
+    pub const fn unchanged(reply: R) -> Self {
+        Self::new(reply, Invalidation::None)
+    }
+
+    pub const fn render(reply: R) -> Self {
+        Self::new(reply, Invalidation::Render)
+    }
+
+    pub const fn changed(reply: R) -> Self {
+        Self::new(reply, Invalidation::StateChanged)
+    }
+}
+
+/// Inputs to one pure render pass.
+#[derive(Clone, Copy, Debug)]
+pub struct RenderInput<'a, S> {
+    pub now_ms: u64,
+    pub snapshot: &'a S,
+}
+
+/// Result of one render pass.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub struct RenderOutcome {
+    /// The completed frame differs from the last successfully presented frame.
+    pub changed: bool,
+    /// Rendering itself changed authoritative engine state, for example by
+    /// pruning an expired overlay. The service coalesces this into one unit
+    /// invalidation for consumers to refresh their snapshot.
+    pub state_changed: bool,
+    /// Positive relative delay until visible output can next differ.
+    ///
+    /// `None` means static output and therefore no render timer. Relative time
+    /// keeps the engine independent of an executor's clock representation.
+    pub next_wake_in_ms: Option<NonZeroU32>,
+}
+
+impl RenderOutcome {
+    pub const fn static_frame(changed: bool) -> Self {
+        Self {
+            changed,
+            state_changed: false,
+            next_wake_in_ms: None,
+        }
+    }
+}
+
+/// Stateful rendering policy owned exclusively by a [`LightingService`].
+///
+/// `Frame` is the *whole* logical output shape selected by the board. It may
+/// be a conventional dense RGB frame, but it can equally be a struct combining
+/// RGB chains, PWM channels, and indicator bits. This boundary intentionally
+/// makes no homogeneous-slice assumption.
+pub trait LightingEngine<S> {
+    type Frame;
+    type Input;
+    type Command;
+    type Reply;
+    type Error;
+
+    /// Consume an edge-sensitive or transient input.
+    fn on_input(&mut self, input: Self::Input, snapshot: &S) -> Result<Invalidation, Self::Error>;
+
+    /// Apply one serialized mutation and return protocol-independent readback.
+    fn handle_command(
+        &mut self,
+        now_ms: u64,
+        command: Self::Command,
+        snapshot: &S,
+    ) -> Result<CommandResult<Self::Reply>, Self::Error>;
+
+    /// Render the complete logical frame from current authoritative state.
+    fn render(&mut self, input: RenderInput<'_, S>, frame: &mut Self::Frame) -> Result<RenderOutcome, Self::Error>;
+
+    /// Commit renderer history after, and only after, successful presentation.
+    ///
+    /// A compositor commonly uses this hook to update the frame against which
+    /// its next `changed` result is calculated. Failed writes must not call it.
+    fn on_presented(&mut self, _frame: &Self::Frame) {}
+}
+
+/// Hardware-facing lifecycle and presentation contract.
+///
+/// The pure [`LightingService`] does not run these futures. An RMK or other
+/// executor adapter performs the operation requested by [`ServiceAction`] and
+/// reports its result. Implementations retain electrical ordering, encoding,
+/// power sequencing, and hard safety limits.
+#[allow(async_fn_in_trait)]
+pub trait LightingOutput<F> {
+    type Error;
+
+    async fn initialize(&mut self) -> Result<(), Self::Error>;
+    async fn present(&mut self, frame: &F) -> Result<(), Self::Error>;
+    async fn suspend(&mut self) -> Result<(), Self::Error>;
+    async fn resume(&mut self) -> Result<(), Self::Error>;
+
+    /// Select an automatic retry delay for a failed operation.
+    ///
+    /// Returning `None` blocks that operation until the adapter explicitly
+    /// calls [`LightingService::retry_output_now`].
+    fn retry_after(&self, _operation: OutputOperation, _error: &Self::Error) -> Option<NonZeroU32> {
+        None
+    }
+}
+
+/// Desired logical power state.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub enum PowerState {
+    #[default]
+    Active,
+    Suspended,
+}
+
+/// Last successfully completed output lifecycle state.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub enum OutputState {
+    #[default]
+    Uninitialized,
+    Active,
+    Suspended,
+}
+
+/// One operation performed by the executor-facing adapter.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum OutputOperation {
+    Initialize,
+    Present,
+    Suspend,
+    Resume,
+}
+
+/// The next externally performed service action.
+#[derive(Debug, Eq, PartialEq)]
+pub enum ServiceAction<'a, F> {
+    /// No immediate work. `next_wake_ms` is the earliest absolute instant at
+    /// which the adapter should poll again, or `None` when only an external
+    /// input/command can make progress.
+    Wait {
+        next_wake_ms: Option<u64>,
+    },
+    Initialize,
+    Present(&'a F),
+    Suspend,
+    Resume,
+}
+
+impl<F> ServiceAction<'_, F> {
+    pub const fn operation(&self) -> Option<OutputOperation> {
+        match self {
+            Self::Wait { .. } => None,
+            Self::Initialize => Some(OutputOperation::Initialize),
+            Self::Present(_) => Some(OutputOperation::Present),
+            Self::Suspend => Some(OutputOperation::Suspend),
+            Self::Resume => Some(OutputOperation::Resume),
+        }
+    }
+}
+
+/// Result reported after an output operation completes.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum OutputCompletion {
+    Succeeded,
+    Failed {
+        /// Positive relative retry delay selected by
+        /// [`LightingOutput::retry_after`]. `None` requires explicit retry.
+        retry_in_ms: Option<NonZeroU32>,
+    },
+}
+
+/// Failure while calculating the next service action.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ServiceError<E> {
+    Engine(E),
+    OperationInFlight(OutputOperation),
+}
+
+/// Invalid completion/retry call made by an adapter.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum CompletionError {
+    NoOperationInFlight,
+    OperationInFlight(OutputOperation),
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+struct RetryState {
+    operation: OutputOperation,
+    at_ms: Option<u64>,
+}
+
+/// Synchronous ownership, scheduling, and output-retry state machine.
+///
+/// The service owns the snapshot provider, engine, and complete logical frame.
+/// It intentionally does not own an async output object: this keeps the state
+/// transitions directly testable and lets RMK, another executor, or a blocking
+/// host harness drive the exact same logic.
+pub struct LightingService<P, E>
+where
+    P: SnapshotProvider,
+    E: LightingEngine<P::Snapshot>,
+{
+    provider: P,
+    engine: E,
+    frame: E::Frame,
+    desired_power: PowerState,
+    output_state: OutputState,
+    dirty: bool,
+    present_required: bool,
+    next_render_ms: Option<u64>,
+    retry: Option<RetryState>,
+    in_flight: Option<OutputOperation>,
+    lighting_change_pending: bool,
+}
+
+impl<P, E> LightingService<P, E>
+where
+    P: SnapshotProvider,
+    E: LightingEngine<P::Snapshot>,
+{
+    /// Construct a service with explicit board-selected frame storage.
+    ///
+    /// The first active poll initializes the output, renders authoritative
+    /// state, and presents once even if the engine reports `changed == false`.
+    pub const fn new(provider: P, engine: E, frame: E::Frame) -> Self {
+        Self {
+            provider,
+            engine,
+            frame,
+            desired_power: PowerState::Active,
+            output_state: OutputState::Uninitialized,
+            dirty: true,
+            present_required: true,
+            next_render_ms: None,
+            retry: None,
+            in_flight: None,
+            lighting_change_pending: false,
+        }
+    }
+
+    pub const fn desired_power(&self) -> PowerState {
+        self.desired_power
+    }
+
+    pub const fn output_state(&self) -> OutputState {
+        self.output_state
+    }
+
+    pub const fn is_dirty(&self) -> bool {
+        self.dirty
+    }
+
+    pub const fn presentation_pending(&self) -> bool {
+        self.present_required
+    }
+
+    pub const fn next_render_ms(&self) -> Option<u64> {
+        self.next_render_ms
+    }
+
+    pub const fn in_flight(&self) -> Option<OutputOperation> {
+        self.in_flight
+    }
+
+    pub const fn lighting_change_pending(&self) -> bool {
+        self.lighting_change_pending
+    }
+
+    /// Take one coalesced authoritative-lighting-state invalidation.
+    pub fn take_lighting_change(&mut self) -> bool {
+        core::mem::take(&mut self.lighting_change_pending)
+    }
+
+    pub const fn frame(&self) -> &E::Frame {
+        &self.frame
+    }
+
+    pub const fn engine(&self) -> &E {
+        &self.engine
+    }
+
+    pub fn engine_mut(&mut self) -> &mut E {
+        &mut self.engine
+    }
+
+    pub const fn snapshot_provider(&self) -> &P {
+        &self.provider
+    }
+
+    pub fn snapshot_provider_mut(&mut self) -> &mut P {
+        &mut self.provider
+    }
+
+    /// Request active or suspended hardware state.
+    ///
+    /// Power transitions supersede a blocked retry of a now-irrelevant output
+    /// operation. Rendering deadlines are disarmed while suspended; current
+    /// state is rendered and force-presented after a successful resume.
+    pub fn set_power(&mut self, power: PowerState) -> Result<(), CompletionError> {
+        if let Some(operation) = self.in_flight {
+            return Err(CompletionError::OperationInFlight(operation));
+        }
+        if self.desired_power != power {
+            self.desired_power = power;
+            self.retry = None;
+            if power == PowerState::Suspended {
+                self.next_render_ms = None;
+            }
+        }
+        Ok(())
+    }
+
+    /// Deliver one edge-sensitive input using a fresh authoritative snapshot.
+    pub fn on_input(&mut self, input: E::Input) -> Result<(), E::Error> {
+        let snapshot = self.provider.snapshot();
+        let invalidation = self.engine.on_input(input, &snapshot)?;
+        self.invalidate(invalidation);
+        Ok(())
+    }
+
+    /// Apply one mutation synchronously through the sole mutable owner.
+    pub fn handle_command(&mut self, now_ms: u64, command: E::Command) -> Result<E::Reply, E::Error> {
+        let snapshot = self.provider.snapshot();
+        let result = self.engine.handle_command(now_ms, command, &snapshot)?;
+        self.invalidate(result.invalidation);
+        Ok(result.reply)
+    }
+
+    /// Explicitly request a render after application-owned state changes.
+    pub fn request_render(&mut self) {
+        self.dirty = true;
+    }
+
+    /// Unblock the last failed operation without waiting for another event.
+    pub fn retry_output_now(&mut self) -> Result<(), CompletionError> {
+        if let Some(operation) = self.in_flight {
+            return Err(CompletionError::OperationInFlight(operation));
+        }
+        self.retry = None;
+        Ok(())
+    }
+
+    /// Produce the next action and mark output operations as in flight.
+    ///
+    /// Callers must report every non-`Wait` action through
+    /// [`complete_output`](Self::complete_output) before polling again.
+    pub fn next_action(&mut self, now_ms: u64) -> Result<ServiceAction<'_, E::Frame>, ServiceError<E::Error>> {
+        if let Some(operation) = self.in_flight {
+            return Err(ServiceError::OperationInFlight(operation));
+        }
+
+        let lifecycle_operation = match (self.output_state, self.desired_power) {
+            (OutputState::Uninitialized, _) => Some(OutputOperation::Initialize),
+            (OutputState::Active, PowerState::Suspended) => Some(OutputOperation::Suspend),
+            (OutputState::Suspended, PowerState::Active) => Some(OutputOperation::Resume),
+            _ => None,
+        };
+        if let Some(operation) = lifecycle_operation {
+            if self.operation_ready(operation, now_ms) {
+                return Ok(self.begin_operation(operation));
+            }
+            return Ok(ServiceAction::Wait {
+                next_wake_ms: self.wait_deadline(),
+            });
+        }
+
+        if self.output_state == OutputState::Suspended {
+            return Ok(ServiceAction::Wait { next_wake_ms: None });
+        }
+
+        if self.next_render_ms.is_some_and(|deadline| deadline <= now_ms) {
+            self.next_render_ms = None;
+            self.dirty = true;
+        }
+
+        if self.dirty {
+            let snapshot = self.provider.snapshot();
+            let outcome = self
+                .engine
+                .render(
+                    RenderInput {
+                        now_ms,
+                        snapshot: &snapshot,
+                    },
+                    &mut self.frame,
+                )
+                .map_err(ServiceError::Engine)?;
+            self.dirty = false;
+            self.next_render_ms = outcome
+                .next_wake_in_ms
+                .and_then(|delay| now_ms.checked_add(delay.get() as u64));
+            self.present_required |= outcome.changed;
+            self.lighting_change_pending |= outcome.state_changed;
+        }
+
+        if self.present_required {
+            if self.operation_ready(OutputOperation::Present, now_ms) {
+                self.in_flight = Some(OutputOperation::Present);
+                return Ok(ServiceAction::Present(&self.frame));
+            }
+            return Ok(ServiceAction::Wait {
+                next_wake_ms: self.wait_deadline(),
+            });
+        }
+
+        // A successful render/present makes any stale presentation retry moot.
+        if self
+            .retry
+            .is_some_and(|retry| retry.operation == OutputOperation::Present)
+        {
+            self.retry = None;
+        }
+        Ok(ServiceAction::Wait {
+            next_wake_ms: self.wait_deadline(),
+        })
+    }
+
+    /// Complete the operation most recently returned by [`next_action`].
+    pub fn complete_output(&mut self, now_ms: u64, completion: OutputCompletion) -> Result<(), CompletionError> {
+        let operation = self.in_flight.take().ok_or(CompletionError::NoOperationInFlight)?;
+
+        match completion {
+            OutputCompletion::Succeeded => {
+                self.retry = None;
+                match operation {
+                    OutputOperation::Initialize => {
+                        self.output_state = OutputState::Active;
+                    }
+                    OutputOperation::Present => {
+                        self.engine.on_presented(&self.frame);
+                        self.present_required = false;
+                    }
+                    OutputOperation::Suspend => {
+                        self.output_state = OutputState::Suspended;
+                        self.next_render_ms = None;
+                    }
+                    OutputOperation::Resume => {
+                        self.output_state = OutputState::Active;
+                        self.dirty = true;
+                        self.present_required = true;
+                    }
+                }
+            }
+            OutputCompletion::Failed { retry_in_ms } => {
+                self.retry = Some(RetryState {
+                    operation,
+                    at_ms: retry_in_ms.and_then(|delay| now_ms.checked_add(delay.get() as u64)),
+                });
+                // Lifecycle state and successfully presented renderer history
+                // intentionally remain unchanged.
+                if operation == OutputOperation::Present {
+                    self.present_required = true;
+                }
+            }
+        }
+        Ok(())
+    }
+
+    fn invalidate(&mut self, invalidation: Invalidation) {
+        self.lighting_change_pending |= invalidation.state_changed();
+        if invalidation.requires_render() {
+            self.dirty = true;
+        }
+    }
+
+    fn operation_ready(&mut self, operation: OutputOperation, now_ms: u64) -> bool {
+        let Some(retry) = self.retry else {
+            return true;
+        };
+        if retry.operation != operation {
+            self.retry = None;
+            return true;
+        }
+        match retry.at_ms {
+            Some(deadline) if deadline <= now_ms => {
+                self.retry = None;
+                true
+            }
+            Some(_) | None => false,
+        }
+    }
+
+    fn begin_operation(&mut self, operation: OutputOperation) -> ServiceAction<'_, E::Frame> {
+        self.in_flight = Some(operation);
+        match operation {
+            OutputOperation::Initialize => ServiceAction::Initialize,
+            OutputOperation::Present => ServiceAction::Present(&self.frame),
+            OutputOperation::Suspend => ServiceAction::Suspend,
+            OutputOperation::Resume => ServiceAction::Resume,
+        }
+    }
+
+    fn wait_deadline(&self) -> Option<u64> {
+        earliest(self.next_render_ms, self.retry.and_then(|retry| retry.at_ms))
+    }
+}
+
+const fn earliest(left: Option<u64>, right: Option<u64>) -> Option<u64> {
+    match (left, right) {
+        (Some(left), Some(right)) => Some(if left < right { left } else { right }),
+        (Some(value), None) | (None, Some(value)) => Some(value),
+        (None, None) => None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+    struct Snapshot {
+        value: u8,
+        indicator: bool,
+    }
+
+    #[derive(Debug)]
+    struct Provider {
+        current: Snapshot,
+    }
+
+    impl Provider {
+        fn new(value: u8) -> Self {
+            Self {
+                current: Snapshot {
+                    value,
+                    indicator: false,
+                },
+            }
+        }
+    }
+
+    impl SnapshotProvider for Provider {
+        type Snapshot = Snapshot;
+
+        fn snapshot(&self) -> Self::Snapshot {
+            // The production trait deliberately takes `&self`; use interior
+            // mutability only when read accounting matters. Most tests infer
+            // reads through the engine's recorded snapshots instead.
+            self.current
+        }
+    }
+
+    #[derive(Clone, Debug, Default, Eq, PartialEq)]
+    struct BoardFrame {
+        rgb: [u8; 2],
+        indicator: bool,
+    }
+
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    enum Input {
+        Add(u8),
+        Ignore,
+    }
+
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    enum Command {
+        SetOffset(u8),
+        Read,
+        Fail,
+    }
+
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    enum EngineError {
+        Requested,
+        Render,
+    }
+
+    struct Engine {
+        offset: u8,
+        committed: Option<BoardFrame>,
+        render_calls: usize,
+        presented_calls: usize,
+        snapshots: [Option<Snapshot>; 8],
+        snapshot_count: usize,
+        next_wake: Option<NonZeroU32>,
+        fail_render_once: bool,
+        state_change_on_render: bool,
+    }
+
+    impl Engine {
+        fn new() -> Self {
+            Self {
+                offset: 0,
+                committed: None,
+                render_calls: 0,
+                presented_calls: 0,
+                snapshots: [None; 8],
+                snapshot_count: 0,
+                next_wake: None,
+                fail_render_once: false,
+                state_change_on_render: false,
+            }
+        }
+
+        fn record(&mut self, snapshot: Snapshot) {
+            if let Some(slot) = self.snapshots.get_mut(self.snapshot_count) {
+                *slot = Some(snapshot);
+            }
+            self.snapshot_count += 1;
+        }
+    }
+
+    impl LightingEngine<Snapshot> for Engine {
+        type Frame = BoardFrame;
+        type Input = Input;
+        type Command = Command;
+        type Reply = u8;
+        type Error = EngineError;
+
+        fn on_input(&mut self, input: Self::Input, snapshot: &Snapshot) -> Result<Invalidation, Self::Error> {
+            self.record(*snapshot);
+            match input {
+                Input::Add(value) => {
+                    self.offset = self.offset.wrapping_add(value);
+                    Ok(Invalidation::Render)
+                }
+                Input::Ignore => Ok(Invalidation::None),
+            }
+        }
+
+        fn handle_command(
+            &mut self,
+            _now_ms: u64,
+            command: Self::Command,
+            snapshot: &Snapshot,
+        ) -> Result<CommandResult<Self::Reply>, Self::Error> {
+            self.record(*snapshot);
+            match command {
+                Command::SetOffset(value) => {
+                    let previous = self.offset;
+                    self.offset = value;
+                    Ok(CommandResult::render(previous))
+                }
+                Command::Read => Ok(CommandResult::unchanged(self.offset)),
+                Command::Fail => Err(EngineError::Requested),
+            }
+        }
+
+        fn render(
+            &mut self,
+            input: RenderInput<'_, Snapshot>,
+            frame: &mut Self::Frame,
+        ) -> Result<RenderOutcome, Self::Error> {
+            self.record(*input.snapshot);
+            self.render_calls += 1;
+            if core::mem::take(&mut self.fail_render_once) {
+                return Err(EngineError::Render);
+            }
+            let value = input.snapshot.value.wrapping_add(self.offset);
+            frame.rgb = [value, value.wrapping_add(1)];
+            frame.indicator = input.snapshot.indicator;
+            Ok(RenderOutcome {
+                changed: self.committed.as_ref() != Some(frame),
+                state_changed: core::mem::take(&mut self.state_change_on_render),
+                next_wake_in_ms: self.next_wake,
+            })
+        }
+
+        fn on_presented(&mut self, frame: &Self::Frame) {
+            self.committed = Some(frame.clone());
+            self.presented_calls += 1;
+        }
+    }
+
+    type Service = LightingService<Provider, Engine>;
+
+    fn service(value: u8) -> Service {
+        LightingService::new(Provider::new(value), Engine::new(), BoardFrame::default())
+    }
+
+    fn complete(service: &mut Service, now_ms: u64) {
+        service.complete_output(now_ms, OutputCompletion::Succeeded).unwrap();
+    }
+
+    fn initialize(service: &mut Service, now_ms: u64) {
+        assert_eq!(service.next_action(now_ms), Ok(ServiceAction::Initialize));
+        complete(service, now_ms);
+    }
+
+    fn initial_present(service: &mut Service, now_ms: u64) {
+        initialize(service, now_ms);
+        let expected = service.provider.current.value;
+        match service.next_action(now_ms).unwrap() {
+            ServiceAction::Present(frame) => {
+                assert_eq!(frame.rgb, [expected, expected + 1]);
+            }
+            other => panic!("expected presentation, got {other:?}"),
+        }
+        complete(service, now_ms);
+    }
+
+    #[test]
+    fn initial_render_uses_latest_authoritative_snapshot_and_whole_frame() {
+        let mut service = service(1);
+        assert_eq!(service.next_action(0), Ok(ServiceAction::Initialize));
+        complete(&mut service, 0);
+
+        // No state event is required: the render queries authoritative state.
+        service.provider.current = Snapshot {
+            value: 7,
+            indicator: true,
+        };
+        match service.next_action(1).unwrap() {
+            ServiceAction::Present(frame) => {
+                assert_eq!(frame.rgb, [7, 8]);
+                assert!(frame.indicator);
+            }
+            other => panic!("expected presentation, got {other:?}"),
+        }
+        complete(&mut service, 1);
+        assert_eq!(service.engine.presented_calls, 1);
+        assert_eq!(service.engine.committed, Some(service.frame.clone()));
+    }
+
+    #[test]
+    fn successful_static_frame_is_not_rendered_or_presented_twice() {
+        let mut service = service(3);
+        initial_present(&mut service, 0);
+
+        assert_eq!(service.next_action(100), Ok(ServiceAction::Wait { next_wake_ms: None }));
+        assert_eq!(service.engine.render_calls, 1);
+        assert_eq!(service.engine.presented_calls, 1);
+
+        service.on_input(Input::Ignore).unwrap();
+        assert!(!service.is_dirty());
+        assert_eq!(service.next_action(101), Ok(ServiceAction::Wait { next_wake_ms: None }));
+    }
+
+    #[test]
+    fn input_and_command_use_fresh_snapshots_and_serialize_mutation() {
+        let mut service = service(2);
+        service.provider.current.value = 4;
+        service.on_input(Input::Add(1)).unwrap();
+        service.provider.current.value = 6;
+        assert_eq!(service.handle_command(10, Command::SetOffset(9)), Ok(1));
+        assert_eq!(service.handle_command(11, Command::Read), Ok(9));
+        assert_eq!(service.handle_command(12, Command::Fail), Err(EngineError::Requested));
+
+        assert_eq!(service.engine.snapshots[0].unwrap().value, 4);
+        assert_eq!(service.engine.snapshots[1].unwrap().value, 6);
+        assert_eq!(service.engine.snapshots[2].unwrap().value, 6);
+        assert_eq!(service.engine.snapshots[3].unwrap().value, 6);
+        assert!(service.is_dirty());
+    }
+
+    #[test]
+    fn authoritative_change_is_coalesced_and_render_requests_are_not_changes() {
+        let mut service = service(2);
+        assert!(!service.lighting_change_pending());
+
+        service.request_render();
+        assert!(!service.lighting_change_pending());
+        service.on_input(Input::Ignore).unwrap();
+        assert!(!service.lighting_change_pending());
+
+        service.on_input(Input::Add(1)).unwrap();
+        assert!(service.lighting_change_pending());
+        assert_eq!(service.handle_command(1, Command::SetOffset(9)), Ok(1));
+        assert!(service.take_lighting_change());
+        assert!(!service.take_lighting_change());
+
+        assert_eq!(service.handle_command(2, Command::Read), Ok(9));
+        assert_eq!(service.handle_command(3, Command::Fail), Err(EngineError::Requested));
+        assert!(!service.lighting_change_pending());
+    }
+
+    #[test]
+    fn render_owned_state_change_is_reported_once() {
+        let mut service = service(2);
+        initialize(&mut service, 0);
+        service.engine.state_change_on_render = true;
+        assert!(matches!(service.next_action(0), Ok(ServiceAction::Present(_))));
+        assert!(service.take_lighting_change());
+        assert!(!service.take_lighting_change());
+    }
+
+    #[test]
+    fn failed_present_retries_at_exact_deadline_without_recommitting_or_rerendering() {
+        let mut service = service(5);
+        initialize(&mut service, 0);
+        assert!(matches!(service.next_action(0), Ok(ServiceAction::Present(_))));
+        service
+            .complete_output(
+                0,
+                OutputCompletion::Failed {
+                    retry_in_ms: NonZeroU32::new(10),
+                },
+            )
+            .unwrap();
+
+        assert_eq!(service.engine.presented_calls, 0);
+        assert_eq!(service.engine.render_calls, 1);
+        assert_eq!(
+            service.next_action(9),
+            Ok(ServiceAction::Wait { next_wake_ms: Some(10) })
+        );
+        assert!(matches!(service.next_action(10), Ok(ServiceAction::Present(_))));
+        assert_eq!(service.engine.render_calls, 1);
+        complete(&mut service, 10);
+        assert_eq!(service.engine.presented_calls, 1);
+    }
+
+    #[test]
+    fn unscheduled_failure_stays_blocked_until_explicit_retry_but_can_rerender_latest_state() {
+        let mut service = service(1);
+        initialize(&mut service, 0);
+        assert!(matches!(service.next_action(0), Ok(ServiceAction::Present(_))));
+        service
+            .complete_output(0, OutputCompletion::Failed { retry_in_ms: None })
+            .unwrap();
+
+        service.provider.current.value = 8;
+        service.request_render();
+        assert_eq!(service.next_action(50), Ok(ServiceAction::Wait { next_wake_ms: None }));
+        assert_eq!(service.frame.rgb, [8, 9]);
+        assert_eq!(service.engine.render_calls, 2);
+
+        service.retry_output_now().unwrap();
+        match service.next_action(50).unwrap() {
+            ServiceAction::Present(frame) => assert_eq!(frame.rgb, [8, 9]),
+            other => panic!("expected presentation, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn engine_deadline_renders_exactly_when_due_and_reschedules_relatively() {
+        let mut service = service(1);
+        service.engine.next_wake = NonZeroU32::new(25);
+        initial_present(&mut service, 100);
+        assert_eq!(service.next_render_ms(), Some(125));
+        assert_eq!(
+            service.next_action(124),
+            Ok(ServiceAction::Wait {
+                next_wake_ms: Some(125)
+            })
+        );
+
+        // The frame is unchanged at the deadline, so there is no write, but
+        // the next visible-change deadline is still advanced.
+        assert_eq!(
+            service.next_action(125),
+            Ok(ServiceAction::Wait {
+                next_wake_ms: Some(150)
+            })
+        );
+        assert_eq!(service.engine.render_calls, 2);
+    }
+
+    #[test]
+    fn a_new_event_before_the_old_deadline_replaces_the_schedule() {
+        let mut service = service(1);
+        service.engine.next_wake = NonZeroU32::new(20);
+        initial_present(&mut service, 10);
+        assert_eq!(service.next_render_ms(), Some(30));
+
+        service.engine.next_wake = NonZeroU32::new(50);
+        service.on_input(Input::Add(1)).unwrap();
+        assert!(matches!(service.next_action(15), Ok(ServiceAction::Present(_))));
+        assert_eq!(service.next_render_ms(), Some(65));
+    }
+
+    #[test]
+    fn suspend_disarms_deadline_and_resume_forces_fresh_render_and_present() {
+        let mut service = service(4);
+        service.engine.next_wake = NonZeroU32::new(10);
+        initial_present(&mut service, 0);
+
+        service.set_power(PowerState::Suspended).unwrap();
+        assert_eq!(service.next_render_ms(), None);
+        assert_eq!(service.next_action(1), Ok(ServiceAction::Suspend));
+        complete(&mut service, 1);
+        assert_eq!(service.output_state(), OutputState::Suspended);
+
+        service.provider.current.value = 9;
+        service.on_input(Input::Add(0)).unwrap();
+        assert_eq!(service.next_action(100), Ok(ServiceAction::Wait { next_wake_ms: None }));
+
+        service.set_power(PowerState::Active).unwrap();
+        assert_eq!(service.next_action(101), Ok(ServiceAction::Resume));
+        complete(&mut service, 101);
+        match service.next_action(101).unwrap() {
+            ServiceAction::Present(frame) => assert_eq!(frame.rgb, [9, 10]),
+            other => panic!("expected presentation, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn lifecycle_failure_retries_without_changing_successful_state() {
+        let mut service = service(0);
+        assert_eq!(service.next_action(0), Ok(ServiceAction::Initialize));
+        service
+            .complete_output(
+                0,
+                OutputCompletion::Failed {
+                    retry_in_ms: NonZeroU32::new(5),
+                },
+            )
+            .unwrap();
+        assert_eq!(service.output_state(), OutputState::Uninitialized);
+        assert_eq!(
+            service.next_action(4),
+            Ok(ServiceAction::Wait { next_wake_ms: Some(5) })
+        );
+        assert_eq!(service.next_action(5), Ok(ServiceAction::Initialize));
+        complete(&mut service, 5);
+        assert_eq!(service.output_state(), OutputState::Active);
+    }
+
+    #[test]
+    fn output_operation_must_complete_before_any_other_mutating_transition() {
+        let mut service = service(0);
+        assert_eq!(service.next_action(0), Ok(ServiceAction::Initialize));
+        assert_eq!(
+            service.next_action(0),
+            Err(ServiceError::OperationInFlight(OutputOperation::Initialize))
+        );
+        assert_eq!(
+            service.set_power(PowerState::Suspended),
+            Err(CompletionError::OperationInFlight(OutputOperation::Initialize))
+        );
+        assert_eq!(
+            service.retry_output_now(),
+            Err(CompletionError::OperationInFlight(OutputOperation::Initialize))
+        );
+        complete(&mut service, 0);
+        assert_eq!(
+            service.complete_output(0, OutputCompletion::Succeeded),
+            Err(CompletionError::NoOperationInFlight)
+        );
+    }
+
+    #[test]
+    fn render_failure_leaves_service_dirty_for_a_deterministic_retry() {
+        let mut service = service(2);
+        initialize(&mut service, 0);
+        service.engine.fail_render_once = true;
+        assert_eq!(service.next_action(0), Err(ServiceError::Engine(EngineError::Render)));
+        assert!(service.is_dirty());
+        assert!(matches!(service.next_action(0), Ok(ServiceAction::Present(_))));
+        assert_eq!(service.engine.render_calls, 2);
+    }
+
+    #[test]
+    fn deadline_overflow_does_not_create_a_busy_loop() {
+        let mut service = service(0);
+        service.engine.next_wake = NonZeroU32::new(2);
+        initialize(&mut service, u64::MAX - 1);
+        assert!(matches!(
+            service.next_action(u64::MAX - 1),
+            Ok(ServiceAction::Present(_))
+        ));
+        assert_eq!(service.next_render_ms(), None);
+    }
+
+    #[test]
+    fn retry_deadline_overflow_requires_explicit_retry() {
+        let mut service = service(0);
+        assert_eq!(service.next_action(u64::MAX), Ok(ServiceAction::Initialize));
+        service
+            .complete_output(
+                u64::MAX,
+                OutputCompletion::Failed {
+                    retry_in_ms: NonZeroU32::new(1),
+                },
+            )
+            .unwrap();
+        assert_eq!(
+            service.next_action(u64::MAX),
+            Ok(ServiceAction::Wait { next_wake_ms: None })
+        );
+        service.retry_output_now().unwrap();
+        assert_eq!(service.next_action(u64::MAX), Ok(ServiceAction::Initialize));
+    }
+
+    #[test]
+    fn power_change_supersedes_a_blocked_presentation_retry() {
+        let mut service = service(0);
+        initialize(&mut service, 0);
+        assert!(matches!(service.next_action(0), Ok(ServiceAction::Present(_))));
+        service
+            .complete_output(0, OutputCompletion::Failed { retry_in_ms: None })
+            .unwrap();
+        service.set_power(PowerState::Suspended).unwrap();
+        assert_eq!(service.next_action(1), Ok(ServiceAction::Suspend));
+    }
+}
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
new file mode 100644
index 000000000..1a61d16dc
--- /dev/null
+++ b/rmk/src/lighting/source.rs
@@ -0,0 +1,527 @@
+use super::compositor::{Contribution, LightingSource, RenderInput};
+use super::context::{LightingContext, LightingContextProvider};
+use super::effect::{EffectSample, LightingEffect};
+use super::topology::LedSlot;
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct SceneCell<E> {
+    pub slot: LedSlot,
+    pub effect: E,
+}
+
+/// A pre-resolved sparse scene. Key, stable-ID, and zone selectors are
+/// resolved to local slots when configuration is installed, not while
+/// rendering.
+#[derive(Copy, Clone, Debug)]
+pub struct SparseScene<'a, E> {
+    pub cells: &'a [SceneCell<E>],
+}
+
+impl<C, Context, E> LightingSource<C, Context> for SparseScene<'_, E>
+where
+    E: LightingEffect<C>,
+{
+    fn len(&self, _: &RenderInput<'_, Context>) -> usize {
+        self.cells.len()
+    }
+
+    fn slot(&self, index: usize, _: &RenderInput<'_, Context>) -> LedSlot {
+        self.cells[index].slot
+    }
+
+    fn contribution(&mut self, index: usize, input: &RenderInput<'_, Context>) -> Contribution<C> {
+        Contribution::Opaque(self.cells[index].effect.sample(input.now_ms))
+    }
+}
+
+#[derive(Copy, Clone, Debug)]
+pub struct LayerScene<'a, E> {
+    pub layer: u8,
+    pub cells: &'a [SceneCell<E>],
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum LayerPolicy {
+    /// Only the effective layer contributes.
+    EffectiveOnly,
+    /// Default first, then the complete active set in ascending RMK layer
+    /// precedence, with the effective layer last. Sparse cells fall through.
+    ActiveStack,
+}
+
+/// RMK's built-in, layer-aware sparse source.
+#[derive(Copy, Clone, Debug)]
+pub struct LayerScenes<'a, E> {
+    pub scenes: &'a [LayerScene<'a, E>],
+    pub policy: LayerPolicy,
+}
+
+impl<'a, E> LayerScenes<'a, E> {
+    fn cell_for_layer(&self, layer: u8, wanted: &mut usize) -> Option<&SceneCell<E>> {
+        for scene in self.scenes.iter().filter(|scene| scene.layer == layer) {
+            if *wanted < scene.cells.len() {
+                return Some(&scene.cells[*wanted]);
+            }
+            *wanted -= scene.cells.len();
+        }
+        None
+    }
+
+    fn cell_at(&self, context: &LightingContext, mut wanted: usize) -> &SceneCell<E> {
+        let effective = context.layers.effective;
+        match self.policy {
+            LayerPolicy::EffectiveOnly => self.cell_for_layer(effective, &mut wanted),
+            LayerPolicy::ActiveStack => {
+                let default = context.layers.default;
+                if let Some(cell) = self.cell_for_layer(default, &mut wanted) {
+                    return cell;
+                }
+                for layer in 0..super::context::LayerState::CAPACITY {
+                    if layer != default
+                        && layer != effective
+                        && context.layers.is_active(layer)
+                        && let Some(cell) = self.cell_for_layer(layer, &mut wanted)
+                    {
+                        return cell;
+                    }
+                }
+                if effective != default {
+                    self.cell_for_layer(effective, &mut wanted)
+                } else {
+                    None
+                }
+            }
+        }
+        .expect("LightingSource index must be below len")
+    }
+
+    fn included_len(&self, context: &LightingContext) -> usize {
+        let effective = context.layers.effective;
+        self.scenes
+            .iter()
+            .filter(|scene| match self.policy {
+                LayerPolicy::EffectiveOnly => scene.layer == effective,
+                LayerPolicy::ActiveStack => {
+                    scene.layer == context.layers.default
+                        || scene.layer == effective
+                        || context.layers.is_active(scene.layer)
+                }
+            })
+            .map(|scene| scene.cells.len())
+            .sum()
+    }
+}
+
+impl<C, Context, E> LightingSource<C, Context> for LayerScenes<'_, E>
+where
+    E: LightingEffect<C>,
+    Context: LightingContextProvider,
+{
+    fn len(&self, input: &RenderInput<'_, Context>) -> usize {
+        self.included_len(input.context.lighting_context())
+    }
+
+    fn slot(&self, index: usize, input: &RenderInput<'_, Context>) -> LedSlot {
+        self.cell_at(input.context.lighting_context(), index).slot
+    }
+
+    fn contribution(&mut self, index: usize, input: &RenderInput<'_, Context>) -> Contribution<C> {
+        Contribution::Opaque(
+            self.cell_at(input.context.lighting_context(), index)
+                .effect
+                .sample(input.now_ms),
+        )
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum Indicator {
+    NumLock,
+    CapsLock,
+    ScrollLock,
+    Compose,
+    Kana,
+}
+
+#[derive(Copy, Clone, Debug)]
+pub struct IndicatorScene<'a, E> {
+    pub indicator: Indicator,
+    pub active: bool,
+    pub cells: &'a [SceneCell<E>],
+}
+
+/// Sparse status scenes driven from the authoritative indicator snapshot.
+/// Multiple matching scenes compose in declaration order within the source.
+#[derive(Copy, Clone, Debug)]
+pub struct IndicatorScenes<'a, E> {
+    pub scenes: &'a [IndicatorScene<'a, E>],
+}
+
+impl<E> IndicatorScenes<'_, E> {
+    fn scene_active<Context: LightingContextProvider>(scene: &IndicatorScene<'_, E>, context: &Context) -> bool {
+        let indicators = context.lighting_context().indicators;
+        let actual = match scene.indicator {
+            Indicator::NumLock => indicators.num_lock,
+            Indicator::CapsLock => indicators.caps_lock,
+            Indicator::ScrollLock => indicators.scroll_lock,
+            Indicator::Compose => indicators.compose,
+            Indicator::Kana => indicators.kana,
+        };
+        actual == scene.active
+    }
+
+    fn cell_at<Context: LightingContextProvider>(&self, context: &Context, mut wanted: usize) -> &SceneCell<E> {
+        for scene in self.scenes.iter().filter(|scene| Self::scene_active(scene, context)) {
+            if wanted < scene.cells.len() {
+                return &scene.cells[wanted];
+            }
+            wanted -= scene.cells.len();
+        }
+        panic!("LightingSource index must be below len")
+    }
+}
+
+impl<C, Context, E> LightingSource<C, Context> for IndicatorScenes<'_, E>
+where
+    Context: LightingContextProvider,
+    E: LightingEffect<C>,
+{
+    fn len(&self, input: &RenderInput<'_, Context>) -> usize {
+        self.scenes
+            .iter()
+            .filter(|scene| Self::scene_active(scene, input.context))
+            .map(|scene| scene.cells.len())
+            .sum()
+    }
+
+    fn slot(&self, index: usize, input: &RenderInput<'_, Context>) -> LedSlot {
+        self.cell_at(input.context, index).slot
+    }
+
+    fn contribution(&mut self, index: usize, input: &RenderInput<'_, Context>) -> Contribution<C> {
+        Contribution::Opaque(self.cell_at(input.context, index).effect.sample(input.now_ms))
+    }
+}
+
+/// Adapter for a caller-owned dense effect buffer.
+#[derive(Copy, Clone, Debug)]
+pub struct DenseSource<'a, C> {
+    pub pixels: &'a [C],
+    pub next_change_ms: Option<u64>,
+}
+
+impl<C: Copy, Context> LightingSource<C, Context> for DenseSource<'_, C> {
+    fn len(&self, _: &RenderInput<'_, Context>) -> usize {
+        self.pixels.len()
+    }
+
+    fn slot(&self, index: usize, _: &RenderInput<'_, Context>) -> LedSlot {
+        LedSlot::from_index(index)
+    }
+
+    fn contribution(&mut self, index: usize, _: &RenderInput<'_, Context>) -> Contribution<C> {
+        Contribution::Opaque(EffectSample {
+            color: self.pixels[index],
+            next_change_ms: self.next_change_ms,
+        })
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct OverlayUpdate<E> {
+    pub slot: LedSlot,
+    pub effect: E,
+    pub expires_ms: Option<u64>,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+struct OverlayEntry<E> {
+    active: bool,
+    update: OverlayUpdate<E>,
+}
+
+impl<E: Copy + Default> OverlayEntry<E> {
+    fn empty() -> Self {
+        Self {
+            active: false,
+            update: OverlayUpdate {
+                slot: LedSlot(0),
+                effect: E::default(),
+                expires_ms: None,
+            },
+        }
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum OverlayError {
+    Full,
+    TooManyEntries { supplied: usize, capacity: usize },
+    DuplicateSlot { slot: LedSlot },
+}
+
+/// Fixed-capacity host/transient overlay. It is an ordinary source rather
+/// than a privileged side channel, so priority and occlusion rules stay
+/// uniform.
+pub struct TtlOverlay<E, const CAP: usize> {
+    entries: [OverlayEntry<E>; CAP],
+}
+
+impl<E: Copy + Default, const CAP: usize> TtlOverlay<E, CAP> {
+    pub fn new() -> Self {
+        Self {
+            entries: [OverlayEntry::empty(); CAP],
+        }
+    }
+
+    pub fn set(&mut self, now_ms: u64, update: OverlayUpdate<E>) -> Result<(), OverlayError> {
+        self.prune_expired(now_ms);
+        if let Some(entry) = self
+            .entries
+            .iter_mut()
+            .find(|entry| entry.active && entry.update.slot == update.slot)
+        {
+            entry.update = update;
+            return Ok(());
+        }
+        let Some(entry) = self.entries.iter_mut().find(|entry| !entry.active) else {
+            return Err(OverlayError::Full);
+        };
+        *entry = OverlayEntry { active: true, update };
+        Ok(())
+    }
+
+    pub fn unset(&mut self, slot: LedSlot) -> bool {
+        if let Some(entry) = self
+            .entries
+            .iter_mut()
+            .find(|entry| entry.active && entry.update.slot == slot)
+        {
+            entry.active = false;
+            true
+        } else {
+            false
+        }
+    }
+
+    pub fn clear(&mut self) {
+        for entry in &mut self.entries {
+            entry.active = false;
+        }
+    }
+
+    /// Atomically replace the overlay; validation happens before mutation.
+    pub fn replace(&mut self, now_ms: u64, updates: &[OverlayUpdate<E>]) -> Result<(), OverlayError> {
+        if updates.len() > CAP {
+            return Err(OverlayError::TooManyEntries {
+                supplied: updates.len(),
+                capacity: CAP,
+            });
+        }
+        for (index, update) in updates.iter().enumerate() {
+            if updates[..index].iter().any(|previous| previous.slot == update.slot) {
+                return Err(OverlayError::DuplicateSlot { slot: update.slot });
+            }
+        }
+        self.clear();
+        for (entry, update) in self.entries.iter_mut().zip(updates.iter().copied()) {
+            if !update.expires_ms.is_some_and(|expires| expires <= now_ms) {
+                *entry = OverlayEntry { active: true, update };
+            }
+        }
+        Ok(())
+    }
+
+    pub fn prune_expired(&mut self, now_ms: u64) {
+        for entry in &mut self.entries {
+            if entry.active && entry.update.expires_ms.is_some_and(|expires| expires <= now_ms) {
+                entry.active = false;
+            }
+        }
+    }
+
+    pub fn active_len(&self) -> usize {
+        self.entries.iter().filter(|entry| entry.active).count()
+    }
+
+    fn active_entry(&self, wanted: usize) -> &OverlayEntry<E> {
+        self.entries
+            .iter()
+            .filter(|entry| entry.active)
+            .nth(wanted)
+            .expect("LightingSource index must be below len")
+    }
+}
+
+impl<E: Copy + Default, const CAP: usize> Default for TtlOverlay<E, CAP> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<C, E, Context, const CAP: usize> LightingSource<C, Context> for TtlOverlay<E, CAP>
+where
+    E: Copy + Default + LightingEffect<C>,
+{
+    fn len(&self, _: &RenderInput<'_, Context>) -> usize {
+        self.active_len()
+    }
+
+    fn slot(&self, index: usize, _: &RenderInput<'_, Context>) -> LedSlot {
+        self.active_entry(index).update.slot
+    }
+
+    fn contribution(&mut self, index: usize, input: &RenderInput<'_, Context>) -> Contribution<C> {
+        let update = self.active_entry(index).update;
+        if update.expires_ms.is_some_and(|expires| expires <= input.now_ms) {
+            Contribution::Transparent { next_change_ms: None }
+        } else {
+            let mut sample = update.effect.sample(input.now_ms);
+            sample.next_change_ms = earliest(sample.next_change_ms, update.expires_ms);
+            Contribution::Opaque(sample)
+        }
+    }
+}
+
+fn earliest(left: Option<u64>, right: Option<u64>) -> Option<u64> {
+    match (left, right) {
+        (Some(left), Some(right)) => Some(left.min(right)),
+        (Some(value), None) | (None, Some(value)) => Some(value),
+        (None, None) => None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::{BuiltinEffect, Compositor, LayerState, LogicalFrame, Rgb8};
+    use super::*;
+
+    const RED: Rgb8 = Rgb8::new(10, 0, 0);
+    const GREEN: Rgb8 = Rgb8::new(0, 10, 0);
+    const BLUE: Rgb8 = Rgb8::new(0, 0, 10);
+
+    #[test]
+    fn layer_source_has_sparse_active_stack_fallthrough() {
+        let base = [SceneCell {
+            slot: LedSlot(0),
+            effect: BuiltinEffect::solid(RED),
+        }];
+        let held = [SceneCell {
+            slot: LedSlot(1),
+            effect: BuiltinEffect::solid(GREEN),
+        }];
+        let effective = [SceneCell {
+            slot: LedSlot(0),
+            effect: BuiltinEffect::solid(BLUE),
+        }];
+        let scenes = [
+            LayerScene { layer: 0, cells: &base },
+            LayerScene { layer: 2, cells: &held },
+            LayerScene {
+                layer: 3,
+                cells: &effective,
+            },
+        ];
+        let mut source = LayerScenes {
+            scenes: &scenes,
+            policy: LayerPolicy::ActiveStack,
+        };
+        let context = LightingContext {
+            layers: LayerState::new(3, 0, 0b1101),
+            indicators: Default::default(),
+        };
+        let compositor = Compositor::<Rgb8, 2>::new(Rgb8::BLACK);
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        let mut tx = compositor.begin(0, &context, Rgb8::BLACK, &mut frame);
+        tx.apply(10, &mut source).unwrap();
+        tx.finish();
+        assert_eq!(frame.as_slice(), &[BLUE, GREEN]);
+    }
+
+    #[test]
+    fn ttl_overlay_expires_exactly_and_replace_is_atomic() {
+        let mut overlay = TtlOverlay::<BuiltinEffect, 2>::new();
+        overlay
+            .set(
+                0,
+                OverlayUpdate {
+                    slot: LedSlot(0),
+                    effect: BuiltinEffect::solid(RED),
+                    expires_ms: Some(10),
+                },
+            )
+            .unwrap();
+        overlay
+            .set(
+                0,
+                OverlayUpdate {
+                    slot: LedSlot(1),
+                    effect: BuiltinEffect::solid(GREEN),
+                    expires_ms: None,
+                },
+            )
+            .unwrap();
+        let before = overlay.active_len();
+        assert_eq!(
+            overlay.replace(
+                0,
+                &[
+                    OverlayUpdate {
+                        slot: LedSlot(0),
+                        effect: BuiltinEffect::solid(BLUE),
+                        expires_ms: None
+                    },
+                    OverlayUpdate {
+                        slot: LedSlot(0),
+                        effect: BuiltinEffect::solid(GREEN),
+                        expires_ms: None
+                    },
+                ]
+            ),
+            Err(OverlayError::DuplicateSlot { slot: LedSlot(0) })
+        );
+        assert_eq!(overlay.active_len(), before);
+
+        let compositor = Compositor::<Rgb8, 2>::new(Rgb8::BLACK);
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        let mut tx = compositor.begin(9, &(), Rgb8::BLACK, &mut frame);
+        tx.apply(0, &mut overlay).unwrap();
+        assert_eq!(tx.finish().next_wake_ms, Some(10));
+        let mut tx = compositor.begin(10, &(), Rgb8::BLACK, &mut frame);
+        tx.apply(0, &mut overlay).unwrap();
+        tx.finish();
+        assert_eq!(frame.as_slice(), &[Rgb8::BLACK, GREEN]);
+    }
+
+    #[test]
+    fn indicator_scenes_use_extended_context_provider() {
+        #[derive(Default)]
+        struct Extended {
+            lighting: LightingContext,
+            _battery_percent: u8,
+        }
+        impl LightingContextProvider for Extended {
+            fn lighting_context(&self) -> &LightingContext {
+                &self.lighting
+            }
+        }
+        let cells = [SceneCell {
+            slot: LedSlot(0),
+            effect: BuiltinEffect::solid(RED),
+        }];
+        let scenes = [IndicatorScene {
+            indicator: Indicator::CapsLock,
+            active: true,
+            cells: &cells,
+        }];
+        let mut source = IndicatorScenes { scenes: &scenes };
+        let mut context = Extended::default();
+        context.lighting.indicators.caps_lock = true;
+        let compositor = Compositor::<Rgb8, 1>::new(Rgb8::BLACK);
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        let mut tx = compositor.begin(0, &context, Rgb8::BLACK, &mut frame);
+        tx.apply(0, &mut source).unwrap();
+        tx.finish();
+        assert_eq!(frame.as_slice(), &[RED]);
+    }
+}
diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
new file mode 100644
index 000000000..1e11a5552
--- /dev/null
+++ b/rmk/src/lighting/standard.rs
@@ -0,0 +1,975 @@
+//! Ready-to-use compositor engine for ordinary RMK lighting.
+//!
+//! Boards provide static layer scenes plus optional extension and status
+//! sources. The engine supplies a controllable uniform background, TTL host
+//! overlay, deterministic priority bands, output brightness, frame history,
+//! `LightAction` handling, and protocol-independent commands/readback.
+
+use core::num::NonZeroU32;
+
+use rmk_types::action::LightAction;
+
+use super::Rgb8;
+use super::compositor::{
+    Compositor, Contribution, LightingSource, LogicalFrame, RenderError, RenderInput as SourceRenderInput,
+};
+use super::context::LightingContextProvider;
+use super::effect::{BuiltinEffect, LightingEffect};
+use super::output::BrightnessTransform;
+use super::service::{CommandResult, Invalidation, LightingEngine, RenderInput, RenderOutcome};
+use super::source::{LayerScenes, OverlayError, OverlayUpdate, TtlOverlay};
+use super::topology::LedSlot;
+
+/// Stable default priority bands. Equal-priority call order remains stable.
+pub mod priority {
+    pub const BACKGROUND: u8 = 0;
+    pub const EXTENSION: u8 = 32;
+    pub const LAYER: u8 = 64;
+    pub const HOST_OVERLAY: u8 = 128;
+    pub const STATUS: u8 = 192;
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum BackgroundMode {
+    Solid,
+    Breathe,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct BackgroundState {
+    pub enabled: bool,
+    pub hue: u8,
+    pub saturation: u8,
+    pub value: u8,
+    pub speed: u8,
+    pub mode: BackgroundMode,
+}
+
+impl Default for BackgroundState {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            hue: 0,
+            saturation: 0,
+            value: 32,
+            speed: 128,
+            mode: BackgroundMode::Solid,
+        }
+    }
+}
+
+/// Atomic partial update of the designated background.
+///
+/// Protocol adapters use this instead of a `ReadState` followed by
+/// `SetBackground`: the lighting engine remains the sole mutable owner and
+/// concurrent callers cannot overwrite fields changed between two mailbox
+/// requests.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct BackgroundPatch {
+    pub enabled: Option<bool>,
+    pub hue: Option<u8>,
+    pub saturation: Option<u8>,
+    pub value: Option<u8>,
+    pub speed: Option<u8>,
+    pub mode: Option<BackgroundMode>,
+}
+
+impl BackgroundPatch {
+    pub const fn apply_to(self, state: &mut BackgroundState) {
+        if let Some(enabled) = self.enabled {
+            state.enabled = enabled;
+        }
+        if let Some(hue) = self.hue {
+            state.hue = hue;
+        }
+        if let Some(saturation) = self.saturation {
+            state.saturation = saturation;
+        }
+        if let Some(value) = self.value {
+            state.value = value;
+        }
+        if let Some(speed) = self.speed {
+            state.speed = speed;
+        }
+        if let Some(mode) = self.mode {
+            state.mode = mode;
+        }
+    }
+}
+
+/// Built-in designated background controlled by RGB/Vial-compatible fields.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct UniformBackground<const N: usize> {
+    state: BackgroundState,
+}
+
+impl<const N: usize> UniformBackground<N> {
+    pub const fn new(state: BackgroundState) -> Self {
+        Self { state }
+    }
+
+    pub const fn state(&self) -> BackgroundState {
+        self.state
+    }
+
+    pub fn set_state(&mut self, state: BackgroundState) {
+        self.state = state;
+    }
+
+    fn effect(&self) -> BuiltinEffect {
+        let color = if self.state.enabled {
+            hsv(self.state.hue, self.state.saturation, self.state.value)
+        } else {
+            Rgb8::BLACK
+        };
+        match self.state.mode {
+            BackgroundMode::Solid => BuiltinEffect::Solid { color },
+            BackgroundMode::Breathe => BuiltinEffect::Breathe {
+                color,
+                period_ms: 250 + ((u8::MAX - self.state.speed) as u32 * 3_750 / 255),
+                phase_ms: 0,
+                step_ms: 16,
+            },
+        }
+    }
+}
+
+impl<Context, const N: usize> LightingSource<Rgb8, Context> for UniformBackground<N> {
+    fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
+        N
+    }
+
+    fn slot(&self, index: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
+        LedSlot::from_index(index)
+    }
+
+    fn contribution(&mut self, _: usize, input: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
+        Contribution::Opaque(self.effect().sample(input.now_ms))
+    }
+}
+
+/// Zero-sized source used when a board does not need an extension band.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct EmptySource;
+
+impl<C, Context> LightingSource<C, Context> for EmptySource {
+    fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
+        0
+    }
+
+    fn slot(&self, _: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
+        unreachable!("EmptySource has no targets")
+    }
+
+    fn contribution(&mut self, _: usize, _: &SourceRenderInput<'_, Context>) -> Contribution<C> {
+        unreachable!("EmptySource has no samples")
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct OverlayCell {
+    pub slot: LedSlot,
+    pub effect: BuiltinEffect,
+    /// Relative lifetime from command application. `None` persists until an
+    /// explicit unset/clear or reboot.
+    pub ttl_ms: Option<NonZeroU32>,
+}
+
+const EMPTY_OVERLAY_CELL: OverlayCell = OverlayCell {
+    slot: LedSlot(0),
+    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+    ttl_ms: None,
+};
+
+/// Fixed-capacity, owned batch suitable for a bounded async mailbox.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct OverlayBatch<const CAP: usize> {
+    cells: [OverlayCell; CAP],
+    len: usize,
+}
+
+impl<const CAP: usize> OverlayBatch<CAP> {
+    pub const fn new() -> Self {
+        Self {
+            cells: [EMPTY_OVERLAY_CELL; CAP],
+            len: 0,
+        }
+    }
+
+    pub fn push(&mut self, cell: OverlayCell) -> Result<(), OverlayError> {
+        if self.len == CAP {
+            return Err(OverlayError::TooManyEntries {
+                supplied: self.len + 1,
+                capacity: CAP,
+            });
+        }
+        self.cells[self.len] = cell;
+        self.len += 1;
+        Ok(())
+    }
+
+    pub fn as_slice(&self) -> &[OverlayCell] {
+        &self.cells[..self.len]
+    }
+}
+
+impl<const CAP: usize> Default for OverlayBatch<CAP> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum StandardCommand<const OVERLAY_CAP: usize> {
+    SetOutputEnabled(bool),
+    SetOutputBrightness(u8),
+    SetBackground(BackgroundState),
+    PatchBackground(BackgroundPatch),
+    SetStateIfRevision {
+        expected_revision: u32,
+        state: StandardMutableState,
+    },
+    SetOverlay(OverlayCell),
+    SetOverlayIfRevision {
+        expected_revision: u32,
+        cell: OverlayCell,
+    },
+    UnsetOverlay(LedSlot),
+    UnsetOverlayIfRevision {
+        expected_revision: u32,
+        slot: LedSlot,
+    },
+    ClearOverlay,
+    ClearOverlayIfRevision {
+        expected_revision: u32,
+    },
+    ReplaceOverlay(OverlayBatch<OVERLAY_CAP>),
+    ReplaceOverlayIfRevision {
+        expected_revision: u32,
+        batch: OverlayBatch<OVERLAY_CAP>,
+    },
+    ReadState,
+}
+
+/// Mutable standard state excluding the transient overlay contents and the
+/// engine-owned optimistic-concurrency revision.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct StandardMutableState {
+    pub output_enabled: bool,
+    pub output_brightness: u8,
+    pub background: BackgroundState,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct StandardState {
+    pub revision: u32,
+    pub output_enabled: bool,
+    pub output_brightness: u8,
+    pub background: BackgroundState,
+    pub overlay_len: usize,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum StandardError {
+    Render(RenderError),
+    Overlay(OverlayError),
+    DeadlineOverflow,
+    RevisionConflict { expected: u32, current: u32 },
+}
+
+impl From<RenderError> for StandardError {
+    fn from(value: RenderError) -> Self {
+        Self::Render(value)
+    }
+}
+
+impl From<OverlayError> for StandardError {
+    fn from(value: OverlayError) -> Self {
+        Self::Overlay(value)
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct StandardInput(pub LightAction);
+
+impl From<LightAction> for StandardInput {
+    fn from(value: LightAction) -> Self {
+        Self(value)
+    }
+}
+
+/// End-to-end standard engine. `Extension` composes above the designated
+/// background and below layers; `Status` composes last. Either can be an
+/// external stateful source, or [`EmptySource`].
+pub struct StandardLightingEngine<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize> {
+    compositor: Compositor<Rgb8, N>,
+    background: UniformBackground<N>,
+    extension: Extension,
+    layers: LayerScenes<'scenes, BuiltinEffect>,
+    overlay: TtlOverlay<BuiltinEffect, OVERLAY_CAP>,
+    status: Status,
+    revision: u32,
+    output_enabled: bool,
+    output_brightness: u8,
+}
+
+impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize>
+    StandardLightingEngine<'scenes, Extension, Status, N, OVERLAY_CAP>
+{
+    pub fn new(
+        background: BackgroundState,
+        layers: LayerScenes<'scenes, BuiltinEffect>,
+        extension: Extension,
+        status: Status,
+    ) -> Self {
+        Self {
+            compositor: Compositor::new(Rgb8::BLACK),
+            background: UniformBackground::new(background),
+            extension,
+            layers,
+            overlay: TtlOverlay::new(),
+            status,
+            revision: 0,
+            output_enabled: true,
+            output_brightness: u8::MAX,
+        }
+    }
+
+    pub fn state(&self) -> StandardState {
+        StandardState {
+            revision: self.revision,
+            output_enabled: self.output_enabled,
+            output_brightness: self.output_brightness,
+            background: self.background.state(),
+            overlay_len: self.overlay.active_len(),
+        }
+    }
+
+    pub const fn extension(&self) -> &Extension {
+        &self.extension
+    }
+
+    pub fn extension_mut(&mut self) -> &mut Extension {
+        &mut self.extension
+    }
+
+    pub const fn status(&self) -> &Status {
+        &self.status
+    }
+
+    pub fn status_mut(&mut self) -> &mut Status {
+        &mut self.status
+    }
+
+    fn apply_light_action(&mut self, action: LightAction) -> bool {
+        const STEP: u8 = 17;
+        let background = &mut self.background.state;
+        match action {
+            LightAction::BacklightOn => self.output_enabled = true,
+            LightAction::BacklightOff => self.output_enabled = false,
+            LightAction::BacklightToggle => self.output_enabled = !self.output_enabled,
+            LightAction::BacklightDown => self.output_brightness = self.output_brightness.saturating_sub(STEP),
+            LightAction::BacklightUp => self.output_brightness = self.output_brightness.saturating_add(STEP),
+            LightAction::BacklightStep => self.output_brightness = self.output_brightness.wrapping_add(STEP),
+            LightAction::BacklightToggleBreathing => {
+                background.mode = match background.mode {
+                    BackgroundMode::Solid => BackgroundMode::Breathe,
+                    BackgroundMode::Breathe => BackgroundMode::Solid,
+                }
+            }
+            LightAction::RgbTog => background.enabled = !background.enabled,
+            LightAction::RgbModeForward | LightAction::RgbModeReverse => {
+                background.mode = match background.mode {
+                    BackgroundMode::Solid => BackgroundMode::Breathe,
+                    BackgroundMode::Breathe => BackgroundMode::Solid,
+                }
+            }
+            LightAction::RgbHui => background.hue = background.hue.wrapping_add(STEP),
+            LightAction::RgbHud => background.hue = background.hue.wrapping_sub(STEP),
+            LightAction::RgbSai => background.saturation = background.saturation.saturating_add(STEP),
+            LightAction::RgbSad => background.saturation = background.saturation.saturating_sub(STEP),
+            LightAction::RgbVai => background.value = background.value.saturating_add(STEP),
+            LightAction::RgbVad => background.value = background.value.saturating_sub(STEP),
+            LightAction::RgbSpi => background.speed = background.speed.saturating_add(STEP),
+            LightAction::RgbSpd => background.speed = background.speed.saturating_sub(STEP),
+            LightAction::RgbModePlain => background.mode = BackgroundMode::Solid,
+            LightAction::RgbModeBreathe => background.mode = BackgroundMode::Breathe,
+            // The standard engine advertises only Solid and Breathe. Other
+            // named modes remain available to an extension source/command.
+            _ => return false,
+        }
+        true
+    }
+
+    fn check_revision(&self, expected: u32) -> Result<(), StandardError> {
+        if expected == self.revision {
+            Ok(())
+        } else {
+            Err(StandardError::RevisionConflict {
+                expected,
+                current: self.revision,
+            })
+        }
+    }
+
+    fn advance_revision(&mut self) {
+        self.revision = self.revision.wrapping_add(1);
+    }
+
+    fn set_mutable_state(&mut self, state: StandardMutableState) {
+        self.output_enabled = state.output_enabled;
+        self.output_brightness = state.output_brightness;
+        self.background.set_state(state.background);
+    }
+
+    fn expires_at(now_ms: u64, ttl_ms: Option<NonZeroU32>) -> Result<Option<u64>, StandardError> {
+        ttl_ms
+            .map(|ttl| {
+                now_ms
+                    .checked_add(ttl.get() as u64)
+                    .ok_or(StandardError::DeadlineOverflow)
+            })
+            .transpose()
+    }
+
+    fn overlay_update(now_ms: u64, cell: OverlayCell) -> Result<OverlayUpdate<BuiltinEffect>, StandardError> {
+        Ok(OverlayUpdate {
+            slot: cell.slot,
+            effect: cell.effect,
+            expires_ms: Self::expires_at(now_ms, cell.ttl_ms)?,
+        })
+    }
+}
+
+impl<'scenes, Context, Extension, Status, const N: usize, const OVERLAY_CAP: usize> LightingEngine<Context>
+    for StandardLightingEngine<'scenes, Extension, Status, N, OVERLAY_CAP>
+where
+    Context: LightingContextProvider,
+    Extension: LightingSource<Rgb8, Context>,
+    Status: LightingSource<Rgb8, Context>,
+{
+    type Frame = LogicalFrame<Rgb8, N>;
+    type Input = StandardInput;
+    type Command = StandardCommand<OVERLAY_CAP>;
+    type Reply = StandardState;
+    type Error = StandardError;
+
+    fn on_input(&mut self, input: Self::Input, _snapshot: &Context) -> Result<Invalidation, Self::Error> {
+        if self.apply_light_action(input.0) {
+            self.advance_revision();
+            Ok(Invalidation::Render)
+        } else {
+            Ok(Invalidation::None)
+        }
+    }
+
+    fn handle_command(
+        &mut self,
+        now_ms: u64,
+        command: Self::Command,
+        _snapshot: &Context,
+    ) -> Result<CommandResult<Self::Reply>, Self::Error> {
+        let (mut invalidation, advances_revision) = match command {
+            StandardCommand::SetOutputEnabled(enabled) => {
+                self.output_enabled = enabled;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::SetOutputBrightness(level) => {
+                self.output_brightness = level;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::SetBackground(state) => {
+                self.background.set_state(state);
+                (Invalidation::Render, true)
+            }
+            StandardCommand::PatchBackground(patch) => {
+                patch.apply_to(&mut self.background.state);
+                (Invalidation::Render, true)
+            }
+            StandardCommand::SetStateIfRevision {
+                expected_revision,
+                state,
+            } => {
+                self.check_revision(expected_revision)?;
+                self.set_mutable_state(state);
+                (Invalidation::Render, true)
+            }
+            StandardCommand::SetOverlay(cell) => {
+                let update = Self::overlay_update(now_ms, cell)?;
+                self.overlay.set(now_ms, update)?;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::SetOverlayIfRevision {
+                expected_revision,
+                cell,
+            } => {
+                self.check_revision(expected_revision)?;
+                let update = Self::overlay_update(now_ms, cell)?;
+                self.overlay.set(now_ms, update)?;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::UnsetOverlay(slot) => {
+                let changed = self.overlay.unset(slot);
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
+            StandardCommand::UnsetOverlayIfRevision {
+                expected_revision,
+                slot,
+            } => {
+                self.check_revision(expected_revision)?;
+                let changed = self.overlay.unset(slot);
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
+            StandardCommand::ClearOverlay => {
+                let changed = self.overlay.active_len() != 0;
+                self.overlay.clear();
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
+            StandardCommand::ClearOverlayIfRevision { expected_revision } => {
+                self.check_revision(expected_revision)?;
+                let changed = self.overlay.active_len() != 0;
+                self.overlay.clear();
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
+            StandardCommand::ReplaceOverlay(batch) => {
+                let mut updates = [OverlayUpdate {
+                    slot: LedSlot(0),
+                    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+                    expires_ms: None,
+                }; OVERLAY_CAP];
+                for (target, cell) in updates.iter_mut().zip(batch.as_slice().iter().copied()) {
+                    *target = Self::overlay_update(now_ms, cell)?;
+                }
+                self.overlay.replace(now_ms, &updates[..batch.as_slice().len()])?;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::ReplaceOverlayIfRevision {
+                expected_revision,
+                batch,
+            } => {
+                self.check_revision(expected_revision)?;
+                let mut updates = [OverlayUpdate {
+                    slot: LedSlot(0),
+                    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+                    expires_ms: None,
+                }; OVERLAY_CAP];
+                for (target, cell) in updates.iter_mut().zip(batch.as_slice().iter().copied()) {
+                    *target = Self::overlay_update(now_ms, cell)?;
+                }
+                self.overlay.replace(now_ms, &updates[..batch.as_slice().len()])?;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::ReadState => (Invalidation::None, false),
+        };
+        if advances_revision {
+            self.advance_revision();
+            if invalidation == Invalidation::None {
+                invalidation = Invalidation::StateChanged;
+            }
+        }
+        Ok(CommandResult::new(self.state(), invalidation))
+    }
+
+    fn render(
+        &mut self,
+        input: RenderInput<'_, Context>,
+        frame: &mut Self::Frame,
+    ) -> Result<RenderOutcome, Self::Error> {
+        let overlay_len = self.overlay.active_len();
+        self.overlay.prune_expired(input.now_ms);
+        let state_changed = self.overlay.active_len() != overlay_len;
+        if state_changed {
+            self.advance_revision();
+        }
+        let Self {
+            compositor,
+            background,
+            extension,
+            layers,
+            overlay,
+            status,
+            output_enabled,
+            output_brightness,
+            revision: _,
+        } = self;
+        let mut transaction = compositor.begin(input.now_ms, input.snapshot, Rgb8::BLACK, frame);
+        transaction.apply(priority::BACKGROUND, background)?;
+        transaction.apply(priority::EXTENSION, extension)?;
+        transaction.apply(priority::LAYER, layers)?;
+        transaction.apply(priority::HOST_OVERLAY, overlay)?;
+        transaction.apply(priority::STATUS, status)?;
+        let mut transform = BrightnessTransform::new(if *output_enabled { *output_brightness } else { 0 });
+        let result = transaction.finish_with(&mut transform);
+        let next_wake_in_ms = result.next_wake_ms.map(|deadline| {
+            let delay = deadline.saturating_sub(input.now_ms).clamp(1, u32::MAX as u64);
+            NonZeroU32::new(delay as u32).expect("clamped delay is nonzero")
+        });
+        Ok(RenderOutcome {
+            changed: result.changed,
+            state_changed,
+            next_wake_in_ms,
+        })
+    }
+
+    fn on_presented(&mut self, frame: &Self::Frame) {
+        self.compositor.commit(frame);
+    }
+}
+
+fn hsv(hue: u8, saturation: u8, value: u8) -> Rgb8 {
+    if saturation == 0 {
+        return Rgb8::new(value, value, value);
+    }
+    let region = hue / 43;
+    let remainder = (hue - region * 43) as u16 * 6;
+    let p = (value as u16 * (255 - saturation as u16) / 255) as u8;
+    let q = (value as u16 * (255 - (saturation as u16 * remainder / 255)) / 255) as u8;
+    let t = (value as u16 * (255 - (saturation as u16 * (255 - remainder) / 255)) / 255) as u8;
+    match region {
+        0 => Rgb8::new(value, t, p),
+        1 => Rgb8::new(q, value, p),
+        2 => Rgb8::new(p, value, t),
+        3 => Rgb8::new(p, q, value),
+        4 => Rgb8::new(t, p, value),
+        _ => Rgb8::new(value, p, q),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::lighting::source::SparseScene;
+    use crate::lighting::{LayerPolicy, LayerScene, LayerState, LightingContext, SceneCell};
+
+    const RED: Rgb8 = Rgb8::new(200, 0, 0);
+    const GREEN: Rgb8 = Rgb8::new(0, 200, 0);
+
+    type Engine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2>;
+
+    static LAYER_CELLS: [SceneCell<BuiltinEffect>; 1] = [SceneCell {
+        slot: LedSlot(0),
+        effect: BuiltinEffect::Solid { color: RED },
+    }];
+    static LAYERS: [LayerScene<'static, BuiltinEffect>; 1] = [LayerScene {
+        layer: 1,
+        cells: &LAYER_CELLS,
+    }];
+    static STATUS_CELLS: [SceneCell<BuiltinEffect>; 1] = [SceneCell {
+        slot: LedSlot(1),
+        effect: BuiltinEffect::Solid { color: GREEN },
+    }];
+
+    fn engine() -> Engine {
+        StandardLightingEngine::new(
+            BackgroundState {
+                value: 10,
+                ..BackgroundState::default()
+            },
+            LayerScenes {
+                scenes: &LAYERS,
+                policy: LayerPolicy::ActiveStack,
+            },
+            EmptySource,
+            EmptySource,
+        )
+    }
+
+    fn context(layer: u8) -> LightingContext {
+        LightingContext {
+            layers: LayerState::new(layer, 0, 1 | (1 << layer)),
+            indicators: Default::default(),
+        }
+    }
+
+    #[test]
+    fn background_patch_preserves_unmentioned_fields() {
+        let mut engine = engine();
+        let snapshot = context(0);
+        let before = engine.state();
+        let reply = engine
+            .handle_command(
+                0,
+                StandardCommand::PatchBackground(BackgroundPatch {
+                    value: Some(77),
+                    ..BackgroundPatch::default()
+                }),
+                &snapshot,
+            )
+            .unwrap()
+            .reply;
+
+        assert_eq!(reply.background.value, 77);
+        assert_eq!(reply.background.enabled, before.background.enabled);
+        assert_eq!(reply.background.hue, before.background.hue);
+        assert_eq!(reply.background.saturation, before.background.saturation);
+        assert_eq!(reply.background.speed, before.background.speed);
+        assert_eq!(reply.background.mode, before.background.mode);
+        assert_eq!(reply.output_enabled, before.output_enabled);
+        assert_eq!(reply.output_brightness, before.output_brightness);
+        assert_eq!(reply.revision, before.revision + 1);
+    }
+
+    #[test]
+    fn revision_checks_are_atomic_and_cover_inputs_and_expiry() {
+        let mut engine = engine();
+        let snapshot = context(0);
+        assert_eq!(engine.state().revision, 0);
+
+        engine
+            .handle_command(
+                10,
+                StandardCommand::PatchBackground(BackgroundPatch {
+                    value: Some(77),
+                    ..BackgroundPatch::default()
+                }),
+                &snapshot,
+            )
+            .unwrap();
+        assert_eq!(engine.state().revision, 1);
+
+        let desired = StandardMutableState {
+            output_enabled: false,
+            output_brightness: 12,
+            background: BackgroundState {
+                value: 99,
+                ..BackgroundState::default()
+            },
+        };
+        assert_eq!(
+            engine.handle_command(
+                10,
+                StandardCommand::SetStateIfRevision {
+                    expected_revision: 0,
+                    state: desired,
+                },
+                &snapshot,
+            ),
+            Err(StandardError::RevisionConflict {
+                expected: 0,
+                current: 1,
+            })
+        );
+        assert!(engine.state().output_enabled, "a stale update is all-or-nothing");
+
+        let reply = engine
+            .handle_command(
+                10,
+                StandardCommand::SetStateIfRevision {
+                    expected_revision: 1,
+                    state: desired,
+                },
+                &snapshot,
+            )
+            .unwrap()
+            .reply;
+        assert_eq!(reply.revision, 2);
+        assert!(!reply.output_enabled);
+
+        engine
+            .on_input(StandardInput(LightAction::BacklightOn), &snapshot)
+            .unwrap();
+        assert_eq!(engine.state().revision, 3);
+        assert_eq!(
+            engine.on_input(StandardInput(LightAction::RgbModeRainbow), &snapshot),
+            Ok(Invalidation::None)
+        );
+        assert_eq!(engine.state().revision, 3);
+
+        engine
+            .handle_command(
+                10,
+                StandardCommand::SetOverlayIfRevision {
+                    expected_revision: 3,
+                    cell: OverlayCell {
+                        slot: LedSlot(0),
+                        effect: BuiltinEffect::Solid { color: GREEN },
+                        ttl_ms: NonZeroU32::new(1),
+                    },
+                },
+                &snapshot,
+            )
+            .unwrap();
+        assert_eq!(engine.state().revision, 4);
+
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        let first_expiry = engine
+            .render(
+                RenderInput {
+                    now_ms: 11,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert!(first_expiry.state_changed);
+        assert_eq!(engine.state().revision, 5, "TTL expiry is authoritative state");
+        let second_expiry = engine
+            .render(
+                RenderInput {
+                    now_ms: 12,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert!(!second_expiry.state_changed);
+        assert_eq!(engine.state().revision, 5, "expiry advances exactly once");
+    }
+
+    #[test]
+    fn disabling_background_does_not_disable_layer_or_status_sources() {
+        type StatusEngine = StandardLightingEngine<'static, EmptySource, SparseScene<'static, BuiltinEffect>, 2, 2>;
+        let mut engine = StatusEngine::new(
+            BackgroundState {
+                value: 10,
+                ..BackgroundState::default()
+            },
+            LayerScenes {
+                scenes: &LAYERS,
+                policy: LayerPolicy::ActiveStack,
+            },
+            EmptySource,
+            SparseScene { cells: &STATUS_CELLS },
+        );
+        let snapshot = context(1);
+        let before = engine.state();
+        engine
+            .handle_command(
+                0,
+                StandardCommand::PatchBackground(BackgroundPatch {
+                    enabled: Some(false),
+                    ..BackgroundPatch::default()
+                }),
+                &snapshot,
+            )
+            .unwrap();
+
+        assert!(engine.state().output_enabled);
+        assert_eq!(engine.state().output_brightness, before.output_brightness);
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 0,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(frame.as_slice(), &[RED, GREEN]);
+    }
+
+    #[test]
+    fn standard_engine_composes_background_layer_and_expiring_overlay() {
+        let mut engine = engine();
+        let snapshot = context(1);
+        engine
+            .handle_command(
+                100,
+                StandardCommand::SetOverlay(OverlayCell {
+                    slot: LedSlot(1),
+                    effect: BuiltinEffect::Solid { color: GREEN },
+                    ttl_ms: NonZeroU32::new(10),
+                }),
+                &snapshot,
+            )
+            .unwrap();
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        let outcome = engine
+            .render(
+                RenderInput {
+                    now_ms: 100,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(frame.as_slice(), &[RED, GREEN]);
+        assert_eq!(outcome.next_wake_in_ms, NonZeroU32::new(10));
+        <Engine as LightingEngine<LightingContext>>::on_presented(&mut engine, &frame);
+
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 110,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(frame.as_slice(), &[RED, Rgb8::new(10, 10, 10)]);
+        assert_eq!(engine.state().overlay_len, 0);
+    }
+
+    #[test]
+    fn expired_overlay_capacity_is_reclaimed_and_light_actions_are_scoped() {
+        let mut engine = engine();
+        let snapshot = context(0);
+        for slot in [LedSlot(0), LedSlot(1)] {
+            engine
+                .handle_command(
+                    0,
+                    StandardCommand::SetOverlay(OverlayCell {
+                        slot,
+                        effect: BuiltinEffect::Solid { color: GREEN },
+                        ttl_ms: NonZeroU32::new(1),
+                    }),
+                    &snapshot,
+                )
+                .unwrap();
+        }
+        assert!(
+            engine
+                .handle_command(
+                    1,
+                    StandardCommand::SetOverlay(OverlayCell {
+                        slot: LedSlot(0),
+                        effect: BuiltinEffect::Solid { color: RED },
+                        ttl_ms: None,
+                    }),
+                    &snapshot,
+                )
+                .is_ok()
+        );
+
+        let before = engine.state();
+        assert_eq!(
+            engine.on_input(StandardInput(LightAction::RgbModeRainbow), &snapshot),
+            Ok(Invalidation::None)
+        );
+        assert_eq!(engine.state(), before);
+        assert_eq!(
+            engine.on_input(StandardInput(LightAction::BacklightOff), &snapshot),
+            Ok(Invalidation::Render)
+        );
+        assert!(!engine.state().output_enabled);
+    }
+}
diff --git a/rmk/src/lighting/topology.rs b/rmk/src/lighting/topology.rs
new file mode 100644
index 000000000..35b8be357
--- /dev/null
+++ b/rmk/src/lighting/topology.rs
@@ -0,0 +1,668 @@
+//! Allocation-free descriptions of logical lights and physical routing.
+
+use core::ops::{BitOr, BitOrAssign};
+
+pub use crate::physical_layout::{Coordinate as Coord, KeyPosition as MatrixPosition, PhysicalLayout, Point3};
+
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[repr(transparent)]
+pub struct LedId(pub u16);
+
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[repr(transparent)]
+pub struct LedSlot(pub u16);
+
+impl LedSlot {
+    pub const fn from_index(index: usize) -> Self {
+        assert!(index <= u16::MAX as usize, "LED slot exceeds u16 capacity");
+        Self(index as u16)
+    }
+
+    pub const fn index(self) -> usize {
+        self.0 as usize
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[repr(transparent)]
+pub struct ZoneId(pub u8);
+
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[repr(transparent)]
+pub struct LightingNodeId(pub u8);
+
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[repr(transparent)]
+pub struct OutputId(pub u8);
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct MatrixSize {
+    pub rows: u8,
+    pub cols: u8,
+}
+
+impl MatrixSize {
+    pub const fn new(rows: u8, cols: u8) -> Self {
+        Self { rows, cols }
+    }
+
+    pub const fn contains(self, position: MatrixPosition) -> bool {
+        position.row < self.rows && position.col < self.cols
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub struct ZoneSpan {
+    pub start: u16,
+    pub len: u8,
+}
+
+impl ZoneSpan {
+    pub const EMPTY: Self = Self { start: 0, len: 0 };
+
+    pub const fn new(start: u16, len: u8) -> Self {
+        Self { start, len }
+    }
+
+    fn range(self, total: usize) -> Option<core::ops::Range<usize>> {
+        let start = self.start as usize;
+        let end = start.checked_add(self.len as usize)?;
+        (end <= total).then_some(start..end)
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct ZoneMetadata<'a> {
+    pub id: ZoneId,
+    pub name: &'a str,
+}
+
+/// A semantic emitter. `key` records a real logical relationship; an explicit
+/// position overrides the associated key center for spatial effects.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LedMetadata {
+    pub id: LedId,
+    pub key: Option<MatrixPosition>,
+    pub position: Option<Point3>,
+    pub zones: ZoneSpan,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub struct LightingTopology<'a> {
+    pub matrix: MatrixSize,
+    pub keys: &'a [MatrixPosition],
+    pub physical_layout: PhysicalLayout<'a>,
+    pub leds: &'a [LedMetadata],
+    pub zones: &'a [ZoneMetadata<'a>],
+    pub zone_memberships: &'a [ZoneId],
+}
+
+impl<'a> LightingTopology<'a> {
+    pub const fn len(&self) -> usize {
+        self.leds.len()
+    }
+
+    pub const fn is_empty(&self) -> bool {
+        self.leds.is_empty()
+    }
+
+    pub fn slot(&self, id: LedId) -> Option<LedSlot> {
+        self.leds
+            .iter()
+            .position(|led| led.id == id)
+            .and_then(|index| u16::try_from(index).ok())
+            .map(LedSlot)
+    }
+
+    pub fn led(&self, slot: LedSlot) -> Option<&'a LedMetadata> {
+        self.leds.get(slot.index())
+    }
+
+    pub fn led_by_id(&self, id: LedId) -> Option<(LedSlot, &'a LedMetadata)> {
+        let slot = self.slot(id)?;
+        Some((slot, self.led(slot)?))
+    }
+
+    pub fn has_key(&self, matrix: MatrixPosition) -> bool {
+        self.keys.contains(&matrix)
+    }
+
+    pub fn effective_position(&self, slot: LedSlot) -> Option<Point3> {
+        let led = self.led(slot)?;
+        led.position.or_else(|| {
+            led.key
+                .and_then(|key| self.physical_layout.key(key))
+                .map(|key| key.center)
+        })
+    }
+
+    pub fn zones_for(&self, slot: LedSlot) -> Option<&'a [ZoneId]> {
+        let range = self.led(slot)?.zones.range(self.zone_memberships.len())?;
+        Some(&self.zone_memberships[range])
+    }
+
+    pub fn has_zone(&self, slot: LedSlot, zone: ZoneId) -> bool {
+        self.zones_for(slot).is_some_and(|zones| zones.contains(&zone))
+    }
+
+    pub fn leds_for_key(&'a self, key: MatrixPosition) -> impl Iterator<Item = (LedSlot, &'a LedMetadata)> + 'a {
+        self.leds.iter().enumerate().filter_map(move |(index, led)| {
+            if led.key != Some(key) {
+                return None;
+            }
+            Some((LedSlot(u16::try_from(index).ok()?), led))
+        })
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
+#[repr(transparent)]
+pub struct OutputCapabilities(u8);
+
+impl OutputCapabilities {
+    pub const NONE: Self = Self(0);
+    pub const BINARY: Self = Self(1 << 0);
+    pub const INTENSITY: Self = Self(1 << 1);
+    pub const RGB: Self = Self(1 << 2);
+    pub const WHITE: Self = Self(1 << 3);
+    pub const ADDRESSABLE: Self = Self(1 << 4);
+    pub const RGBW: Self = Self(Self::RGB.0 | Self::WHITE.0);
+    const KNOWN_BITS: u8 = Self::BINARY.0 | Self::INTENSITY.0 | Self::RGB.0 | Self::WHITE.0 | Self::ADDRESSABLE.0;
+    const COLOR_BITS: u8 = Self::BINARY.0 | Self::INTENSITY.0 | Self::RGB.0 | Self::WHITE.0;
+
+    pub const fn from_bits(bits: u8) -> Option<Self> {
+        if bits & !Self::KNOWN_BITS == 0 {
+            Some(Self(bits))
+        } else {
+            None
+        }
+    }
+
+    pub const fn bits(self) -> u8 {
+        self.0
+    }
+
+    pub const fn contains(self, required: Self) -> bool {
+        self.0 & required.0 == required.0
+    }
+
+    pub const fn intersects(self, other: Self) -> bool {
+        self.0 & other.0 != 0
+    }
+
+    pub const fn union(self, other: Self) -> Self {
+        Self(self.0 | other.0)
+    }
+
+    pub const fn has_color_capability(self) -> bool {
+        self.0 & Self::COLOR_BITS != 0
+    }
+}
+
+impl BitOr for OutputCapabilities {
+    type Output = Self;
+
+    fn bitor(self, rhs: Self) -> Self::Output {
+        self.union(rhs)
+    }
+}
+
+impl BitOrAssign for OutputCapabilities {
+    fn bitor_assign(&mut self, rhs: Self) {
+        *self = self.union(rhs);
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum OutputCoverage {
+    Complete,
+    Sparse,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct OutputMetadata {
+    pub node: LightingNodeId,
+    pub id: OutputId,
+    pub pixel_count: u16,
+    pub capabilities: OutputCapabilities,
+    pub coverage: OutputCoverage,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct PhysicalRoute {
+    pub slot: LedSlot,
+    pub node: LightingNodeId,
+    pub output: OutputId,
+    pub physical_index: u16,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub struct LightingRouting<'a> {
+    pub outputs: &'a [OutputMetadata],
+    pub routes: &'a [PhysicalRoute],
+}
+
+impl<'a> LightingRouting<'a> {
+    pub fn output(&self, node: LightingNodeId, id: OutputId) -> Option<&'a OutputMetadata> {
+        self.outputs
+            .iter()
+            .find(|output| output.node == node && output.id == id)
+    }
+
+    pub fn route(&self, slot: LedSlot) -> Option<&'a PhysicalRoute> {
+        self.routes.iter().find(|route| route.slot == slot)
+    }
+
+    pub fn capabilities_for(&self, slot: LedSlot) -> Option<OutputCapabilities> {
+        let route = self.route(slot)?;
+        Some(self.output(route.node, route.output)?.capabilities)
+    }
+}
+
+/// A precise topology or routing validation failure.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub enum ValidationError {
+    TooManyLeds {
+        count: usize,
+    },
+    TooManyZoneMemberships {
+        count: usize,
+    },
+    InvalidMatrixSize {
+        size: MatrixSize,
+    },
+    KeyOutOfBounds {
+        key_index: usize,
+        matrix: MatrixPosition,
+    },
+    DuplicateKey {
+        first_index: usize,
+        second_index: usize,
+        matrix: MatrixPosition,
+    },
+    UnknownPhysicalKey {
+        key_index: usize,
+        matrix: MatrixPosition,
+    },
+    DuplicatePhysicalKey {
+        first_index: usize,
+        second_index: usize,
+        matrix: MatrixPosition,
+    },
+    DuplicateLedId {
+        first_slot: LedSlot,
+        second_slot: LedSlot,
+        id: LedId,
+    },
+    UnknownKey {
+        slot: LedSlot,
+        matrix: MatrixPosition,
+    },
+    InvalidZoneSpan {
+        slot: LedSlot,
+        span: ZoneSpan,
+    },
+    EmptyZoneName {
+        zone_index: usize,
+        id: ZoneId,
+    },
+    DuplicateZoneId {
+        first_index: usize,
+        second_index: usize,
+        id: ZoneId,
+    },
+    DuplicateZoneName {
+        first_index: usize,
+        second_index: usize,
+    },
+    UnknownZone {
+        slot: LedSlot,
+        membership_index: usize,
+        id: ZoneId,
+    },
+    DuplicateLedZone {
+        slot: LedSlot,
+        id: ZoneId,
+    },
+    DuplicateOutputId {
+        first_index: usize,
+        second_index: usize,
+        node: LightingNodeId,
+        output: OutputId,
+    },
+    EmptyOutput {
+        output_index: usize,
+    },
+    OutputHasNoColorCapability {
+        output_index: usize,
+    },
+    RouteSlotOutOfBounds {
+        route_index: usize,
+        slot: LedSlot,
+    },
+    DuplicateRouteForSlot {
+        first_index: usize,
+        second_index: usize,
+        slot: LedSlot,
+    },
+    MissingRouteForSlot {
+        slot: LedSlot,
+    },
+    UnknownOutput {
+        route_index: usize,
+        node: LightingNodeId,
+        output: OutputId,
+    },
+    PhysicalIndexOutOfBounds {
+        route_index: usize,
+        physical_index: u16,
+        pixel_count: u16,
+    },
+    DuplicatePhysicalAddress {
+        first_index: usize,
+        second_index: usize,
+    },
+    MissingPhysicalRoute {
+        output_index: usize,
+        physical_index: u16,
+    },
+}
+
+/// Validate semantic identity, key/geometry references, zones, split/output
+/// ownership, and the logical-to-physical routing bijection.
+///
+/// This function allocates nothing. Its quadratic checks are deliberate: the
+/// topology is small static board data and validation normally runs at build
+/// time or once during initialization.
+pub fn validate(topology: &LightingTopology<'_>, routing: &LightingRouting<'_>) -> Result<(), ValidationError> {
+    if topology.leds.len() > u16::MAX as usize + 1 {
+        return Err(ValidationError::TooManyLeds {
+            count: topology.leds.len(),
+        });
+    }
+    if topology.zone_memberships.len() > u16::MAX as usize + 1 {
+        return Err(ValidationError::TooManyZoneMemberships {
+            count: topology.zone_memberships.len(),
+        });
+    }
+    if (topology.matrix.rows == 0) != (topology.matrix.cols == 0) {
+        return Err(ValidationError::InvalidMatrixSize { size: topology.matrix });
+    }
+
+    for (index, key) in topology.keys.iter().copied().enumerate() {
+        if !topology.matrix.contains(key) {
+            return Err(ValidationError::KeyOutOfBounds {
+                key_index: index,
+                matrix: key,
+            });
+        }
+        if let Some((first_index, _)) = topology.keys[..index]
+            .iter()
+            .enumerate()
+            .find(|(_, previous)| **previous == key)
+        {
+            return Err(ValidationError::DuplicateKey {
+                first_index,
+                second_index: index,
+                matrix: key,
+            });
+        }
+    }
+
+    for (index, key) in topology.physical_layout.keys.iter().enumerate() {
+        let matrix = key.matrix;
+        if !topology.matrix.contains(matrix) {
+            return Err(ValidationError::KeyOutOfBounds {
+                key_index: index,
+                matrix,
+            });
+        }
+        if !topology.has_key(matrix) {
+            return Err(ValidationError::UnknownPhysicalKey {
+                key_index: index,
+                matrix,
+            });
+        }
+        if let Some((first_index, _)) = topology.physical_layout.keys[..index]
+            .iter()
+            .enumerate()
+            .find(|(_, previous)| previous.matrix == matrix)
+        {
+            return Err(ValidationError::DuplicatePhysicalKey {
+                first_index,
+                second_index: index,
+                matrix,
+            });
+        }
+    }
+
+    for (index, zone) in topology.zones.iter().enumerate() {
+        if zone.name.is_empty() {
+            return Err(ValidationError::EmptyZoneName {
+                zone_index: index,
+                id: zone.id,
+            });
+        }
+        for (first_index, previous) in topology.zones[..index].iter().enumerate() {
+            if previous.id == zone.id {
+                return Err(ValidationError::DuplicateZoneId {
+                    first_index,
+                    second_index: index,
+                    id: zone.id,
+                });
+            }
+            if previous.name == zone.name {
+                return Err(ValidationError::DuplicateZoneName {
+                    first_index,
+                    second_index: index,
+                });
+            }
+        }
+    }
+
+    for (index, led) in topology.leds.iter().enumerate() {
+        let slot = LedSlot(index as u16);
+        if let Some((first, _)) = topology.leds[..index]
+            .iter()
+            .enumerate()
+            .find(|(_, previous)| previous.id == led.id)
+        {
+            return Err(ValidationError::DuplicateLedId {
+                first_slot: LedSlot(first as u16),
+                second_slot: slot,
+                id: led.id,
+            });
+        }
+        if let Some(matrix) = led.key
+            && !topology.has_key(matrix)
+        {
+            return Err(ValidationError::UnknownKey { slot, matrix });
+        }
+        let Some(range) = led.zones.range(topology.zone_memberships.len()) else {
+            return Err(ValidationError::InvalidZoneSpan { slot, span: led.zones });
+        };
+        for membership_index in range.clone() {
+            let id = topology.zone_memberships[membership_index];
+            if !topology.zones.iter().any(|zone| zone.id == id) {
+                return Err(ValidationError::UnknownZone {
+                    slot,
+                    membership_index,
+                    id,
+                });
+            }
+            if topology.zone_memberships[range.start..membership_index].contains(&id) {
+                return Err(ValidationError::DuplicateLedZone { slot, id });
+            }
+        }
+    }
+
+    for (index, output) in routing.outputs.iter().enumerate() {
+        if let Some((first_index, _)) = routing.outputs[..index]
+            .iter()
+            .enumerate()
+            .find(|(_, previous)| previous.node == output.node && previous.id == output.id)
+        {
+            return Err(ValidationError::DuplicateOutputId {
+                first_index,
+                second_index: index,
+                node: output.node,
+                output: output.id,
+            });
+        }
+        if output.pixel_count == 0 {
+            return Err(ValidationError::EmptyOutput { output_index: index });
+        }
+        if !output.capabilities.has_color_capability() {
+            return Err(ValidationError::OutputHasNoColorCapability { output_index: index });
+        }
+    }
+
+    for (index, route) in routing.routes.iter().enumerate() {
+        if route.slot.0 as usize >= topology.leds.len() {
+            return Err(ValidationError::RouteSlotOutOfBounds {
+                route_index: index,
+                slot: route.slot,
+            });
+        }
+        if let Some((first_index, _)) = routing.routes[..index]
+            .iter()
+            .enumerate()
+            .find(|(_, previous)| previous.slot == route.slot)
+        {
+            return Err(ValidationError::DuplicateRouteForSlot {
+                first_index,
+                second_index: index,
+                slot: route.slot,
+            });
+        }
+        let Some(output) = routing.output(route.node, route.output) else {
+            return Err(ValidationError::UnknownOutput {
+                route_index: index,
+                node: route.node,
+                output: route.output,
+            });
+        };
+        if route.physical_index >= output.pixel_count {
+            return Err(ValidationError::PhysicalIndexOutOfBounds {
+                route_index: index,
+                physical_index: route.physical_index,
+                pixel_count: output.pixel_count,
+            });
+        }
+        if let Some((first_index, _)) = routing.routes[..index].iter().enumerate().find(|(_, previous)| {
+            previous.node == route.node
+                && previous.output == route.output
+                && previous.physical_index == route.physical_index
+        }) {
+            return Err(ValidationError::DuplicatePhysicalAddress {
+                first_index,
+                second_index: index,
+            });
+        }
+    }
+
+    for slot in 0..topology.leds.len() {
+        let slot = LedSlot(slot as u16);
+        if routing.route(slot).is_none() {
+            return Err(ValidationError::MissingRouteForSlot { slot });
+        }
+    }
+
+    for (output_index, output) in routing.outputs.iter().enumerate() {
+        if output.coverage == OutputCoverage::Sparse {
+            continue;
+        }
+        for physical_index in 0..output.pixel_count {
+            if !routing.routes.iter().any(|route| {
+                route.node == output.node && route.output == output.id && route.physical_index == physical_index
+            }) {
+                return Err(ValidationError::MissingPhysicalRoute {
+                    output_index,
+                    physical_index,
+                });
+            }
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::physical_layout::*;
+
+    #[test]
+    fn keyed_emitter_falls_back_to_shared_key_center() {
+        let keys = [PhysicalKey {
+            matrix: KeyPosition::new(0, 0),
+            center: Point3::new(Coordinate::ONE, Coordinate::ZERO, Coordinate::ZERO),
+            size: KeySize::ONE,
+            rotation: Rotation::ZERO,
+        }];
+        let leds = [LedMetadata {
+            id: LedId(7),
+            key: Some(KeyPosition::new(0, 0)),
+            position: None,
+            zones: ZoneSpan::new(0, 0),
+        }];
+        let topology = LightingTopology {
+            matrix: MatrixSize::new(1, 1),
+            keys: &[KeyPosition::new(0, 0)],
+            physical_layout: PhysicalLayout::new(&keys),
+            leds: &leds,
+            zones: &[],
+            zone_memberships: &[],
+        };
+        assert_eq!(topology.effective_position(LedSlot(0)), Some(keys[0].center));
+    }
+
+    #[test]
+    fn validation_accepts_canonical_layout_and_semantic_route() {
+        let keys = [PhysicalKey {
+            matrix: KeyPosition::new(0, 0),
+            center: Point3::new(Coordinate::ONE, Coordinate::ZERO, Coordinate::ZERO),
+            size: KeySize::ONE,
+            rotation: Rotation::ZERO,
+        }];
+        let leds = [LedMetadata {
+            id: LedId(7),
+            key: Some(KeyPosition::new(0, 0)),
+            position: None,
+            zones: ZoneSpan::EMPTY,
+        }];
+        let topology = LightingTopology {
+            matrix: MatrixSize::new(1, 1),
+            keys: &[KeyPosition::new(0, 0)],
+            physical_layout: PhysicalLayout::new(&keys),
+            leds: &leds,
+            zones: &[],
+            zone_memberships: &[],
+        };
+        let outputs = [OutputMetadata {
+            node: LightingNodeId(0),
+            id: OutputId(0),
+            pixel_count: 1,
+            capabilities: OutputCapabilities::RGB.union(OutputCapabilities::ADDRESSABLE),
+            coverage: OutputCoverage::Complete,
+        }];
+        let routes = [PhysicalRoute {
+            slot: LedSlot(0),
+            node: LightingNodeId(0),
+            output: OutputId(0),
+            physical_index: 0,
+        }];
+
+        assert_eq!(
+            validate(
+                &topology,
+                &LightingRouting {
+                    outputs: &outputs,
+                    routes: &routes,
+                }
+            ),
+            Ok(())
+        );
+    }
+}
diff --git a/rmk/src/physical_layout.rs b/rmk/src/physical_layout.rs
new file mode 100644
index 000000000..3e3852ec7
--- /dev/null
+++ b/rmk/src/physical_layout.rs
@@ -0,0 +1,135 @@
+//! Allocation-free physical key geometry shared by lighting, display, and
+//! host-facing layout consumers.
+
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub struct KeyPosition {
+    pub row: u8,
+    pub col: u8,
+}
+
+impl KeyPosition {
+    pub const fn new(row: u8, col: u8) -> Self {
+        Self { row, col }
+    }
+}
+
+/// Signed Q8.8 coordinate measured in key-pitch units.
+#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[repr(transparent)]
+pub struct Coordinate(i16);
+
+impl Coordinate {
+    pub const ZERO: Self = Self(0);
+    pub const ONE: Self = Self(256);
+
+    pub const fn from_raw(raw: i16) -> Self {
+        Self(raw)
+    }
+
+    pub const fn raw(self) -> i16 {
+        self.0
+    }
+}
+
+/// Positive Q8.8 extent measured in key-pitch units.
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[repr(transparent)]
+pub struct Extent(u16);
+
+impl Extent {
+    pub const ONE: Self = Self(256);
+
+    pub const fn from_raw(raw: u16) -> Self {
+        Self(raw)
+    }
+
+    pub const fn raw(self) -> u16 {
+        self.0
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[repr(transparent)]
+pub struct Rotation(i16);
+
+impl Rotation {
+    pub const ZERO: Self = Self(0);
+
+    pub const fn from_centidegrees(value: i16) -> Self {
+        Self(value)
+    }
+
+    pub const fn centidegrees(self) -> i16 {
+        self.0
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
+pub struct Point3 {
+    pub x: Coordinate,
+    pub y: Coordinate,
+    pub z: Coordinate,
+}
+
+impl Point3 {
+    pub const fn new(x: Coordinate, y: Coordinate, z: Coordinate) -> Self {
+        Self { x, y, z }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub struct KeySize {
+    pub width: Extent,
+    pub height: Extent,
+}
+
+impl KeySize {
+    pub const ONE: Self = Self::new(Extent::ONE, Extent::ONE);
+
+    pub const fn new(width: Extent, height: Extent) -> Self {
+        Self { width, height }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct PhysicalKey {
+    pub matrix: KeyPosition,
+    pub center: Point3,
+    pub size: KeySize,
+    pub rotation: Rotation,
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+pub struct PhysicalLayout<'a> {
+    pub keys: &'a [PhysicalKey],
+}
+
+impl<'a> PhysicalLayout<'a> {
+    pub const EMPTY: Self = Self { keys: &[] };
+
+    pub const fn new(keys: &'a [PhysicalKey]) -> Self {
+        Self { keys }
+    }
+
+    pub fn key(&self, matrix: KeyPosition) -> Option<&'a PhysicalKey> {
+        self.keys.iter().find(|key| key.matrix == matrix)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn fixed_geometry_is_lossless() {
+        let key = PhysicalKey {
+            matrix: KeyPosition::new(1, 2),
+            center: Point3::new(Coordinate::from_raw(-128), Coordinate::ONE, Coordinate::ZERO),
+            size: KeySize::ONE,
+            rotation: Rotation::from_centidegrees(-750),
+        };
+        let layout = PhysicalLayout::new(core::slice::from_ref(&key));
+        assert_eq!(layout.key(KeyPosition::new(1, 2)).unwrap(), &key);
+        assert_eq!(key.center.x.raw(), -128);
+    }
+}
diff --git a/rmk/src/split/driver.rs b/rmk/src/split/driver.rs
index 7be44f26a..45622ec14 100644
--- a/rmk/src/split/driver.rs
+++ b/rmk/src/split/driver.rs
@@ -181,7 +181,7 @@ impl<T: SplitReader + SplitWriter> PeripheralManager<T> {
         let mut wpm_sub = crate::event::WpmUpdateEvent::subscriber();
         #[cfg(feature = "display")]
         let mut modifier_sub = crate::event::ModifierEvent::subscriber();
-        #[cfg(feature = "display")]
+        #[cfg(feature = "_render_state")]
         let mut sleep_sub = crate::event::SleepStateEvent::subscriber();
 
         // Expose the split-link state to the application. This
@@ -242,7 +242,7 @@ impl<T: SplitReader + SplitWriter> PeripheralManager<T> {
                     },
                     with_feature("display"): e = wpm_sub.next_event().fuse() => SplitMessage::Wpm(e.0),
                     with_feature("display"): e = modifier_sub.next_event().fuse() => SplitMessage::Modifier(e.modifier.into_bits()),
-                    with_feature("display"): e = sleep_sub.next_event().fuse() => SplitMessage::SleepState(e.0),
+                    with_feature("_render_state"): e = sleep_sub.next_event().fuse() => SplitMessage::SleepState(e.0),
                     // Application messages, deliberately the
                     // last (lowest-priority) outgoing arm; the read arm of the
                     // outer select still beats all outgoing traffic.
diff --git a/rmk/src/split/mod.rs b/rmk/src/split/mod.rs
index 20a525f0c..6c44bd781 100644
--- a/rmk/src/split/mod.rs
+++ b/rmk/src/split/mod.rs
@@ -61,7 +61,7 @@ pub(crate) enum SplitMessage {
     #[cfg(feature = "display")]
     Modifier(u8),
     /// Sleep state from central to peripheral
-    #[cfg(feature = "display")]
+    #[cfg(feature = "_render_state")]
     SleepState(bool),
     /// Battery status, from peripheral to central
     #[cfg(feature = "_ble")]
diff --git a/rmk/src/split/peripheral.rs b/rmk/src/split/peripheral.rs
index 6f465929c..947462faf 100644
--- a/rmk/src/split/peripheral.rs
+++ b/rmk/src/split/peripheral.rs
@@ -19,7 +19,7 @@ use crate::event::{
     KeyboardEvent, LayerChangeEvent, LedIndicatorEvent, PointingEvent, SubscribableEvent, publish_event,
 };
 #[cfg(feature = "display")]
-use crate::event::{ModifierEvent, SleepStateEvent, WpmUpdateEvent};
+use crate::event::{ModifierEvent, WpmUpdateEvent};
 #[cfg(not(feature = "_ble"))]
 use crate::split::serial::SerialSplitDriver;
 use crate::state::update_status;
@@ -181,9 +181,9 @@ impl<S: SplitWriter + SplitReader> SplitPeripheral<S> {
                             }
                             SplitMessage::KeyboardIndicator(indicator) => {
                                 // Publish KeyboardIndicator event
-                                publish_event(LedIndicatorEvent::new(
-                                    rmk_types::led_indicator::LedIndicator::from_bits(indicator),
-                                ));
+                                let indicator = rmk_types::led_indicator::LedIndicator::from_bits(indicator);
+                                crate::keyboard::set_current_led_indicator(indicator);
+                                publish_event(LedIndicatorEvent::new(indicator));
                             }
                             SplitMessage::Layer(layer) => {
                                 // Publish Layer event
@@ -197,9 +197,9 @@ impl<S: SplitWriter + SplitReader> SplitPeripheral<S> {
                                     modifier: rmk_types::modifier::ModifierCombination::from_bits(bits),
                                 });
                             }
-                            #[cfg(feature = "display")]
+                            #[cfg(feature = "_render_state")]
                             SplitMessage::SleepState(sleeping) => {
-                                publish_event(SleepStateEvent::new(sleeping));
+                                crate::state::set_sleeping(sleeping);
                             }
                             // --- dfu_split: firmware update handlers ---
                             #[cfg(feature = "dfu_split")]
diff --git a/rmk/src/state.rs b/rmk/src/state.rs
index c25340aea..02cb64af0 100644
--- a/rmk/src/state.rs
+++ b/rmk/src/state.rs
@@ -9,6 +9,31 @@ use rmk_types::connection::{ConnectionStatus, ConnectionType, UsbState};
 use crate::RawMutex;
 use crate::event::{ConnectionStatusChangeEvent, publish_event};
 
+/// Authoritative device sleep state shared by display, lighting, host
+/// readback, battery management, and split forwarding. Events invalidate this
+/// value; they are not a second owner of it.
+static SLEEPING: Mutex<RawMutex, Cell<bool>> = Mutex::new(Cell::new(false));
+
+pub(crate) fn current_sleeping() -> bool {
+    SLEEPING.lock(Cell::get)
+}
+
+/// Compatibility spelling used by the existing Rynk status handler.
+pub(crate) fn current_sleep_state() -> bool {
+    current_sleeping()
+}
+
+pub(crate) fn set_sleeping(sleeping: bool) {
+    let changed = SLEEPING.lock(|state| {
+        let changed = state.get() != sleeping;
+        state.set(sleeping);
+        changed
+    });
+    if changed {
+        publish_event(crate::event::SleepStateEvent::new(sleeping));
+    }
+}
+
 /// Single source of truth for transport state and routing. All writes go
 /// through the mutator helpers below so the active-output cascade runs and
 /// change events fire on every transition.
@@ -27,19 +52,6 @@ pub(crate) fn current_usb_state() -> UsbState {
     CONNECTION_STATUS.lock(|c| c.get().usb)
 }
 
-/// Current central sleep state for host polling. Sourced from the BLE sleep
-/// manager's `SLEEPING_STATE`; always `false` in builds without BLE.
-pub(crate) fn current_sleep_state() -> bool {
-    #[cfg(feature = "_ble")]
-    {
-        crate::ble::sleep::SLEEPING_STATE.load(core::sync::atomic::Ordering::Acquire)
-    }
-    #[cfg(not(feature = "_ble"))]
-    {
-        false
-    }
-}
-
 #[cfg(feature = "_ble")]
 pub(crate) fn current_ble_status() -> BleStatus {
     CONNECTION_STATUS.lock(|c| c.get().ble)

From 6dd5b85d0b858a57eafbf362f994b105e7a6e1cd Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 10:26:08 -0700
Subject: [PATCH 03/78] feat(rynk): add native lighting control

---
 .../main/docs/development/rynk_protocol.md    |  129 +-
 rmk-types/src/protocol/rynk/command.rs        |   49 +
 .../src/protocol/rynk/payload/lighting.rs     |  600 +++++++++
 rmk-types/src/protocol/rynk/payload/mod.rs    |    4 +
 rmk-types/src/protocol/rynk/payload/system.rs |    4 +-
 .../rynk/snapshots/lighting_wire_frames.snap  |   45 +
 .../protocol/rynk/snapshots/wire_values.snap  |    2 +-
 rmk-types/src/protocol/rynk/tests.rs          |  425 +++++++
 rmk/src/host/mod.rs                           |    5 +
 rmk/src/host/rynk/handlers/lighting.rs        | 1100 +++++++++++++++++
 rmk/src/host/rynk/handlers/mod.rs             |    2 +
 rmk/src/host/rynk/handlers/system.rs          |    5 +-
 rmk/src/host/rynk/lighting.rs                 |  568 +++++++++
 rmk/src/host/rynk/mod.rs                      |   85 +-
 rmk/src/host/rynk/topics.rs                   |    7 +
 rynk/Cargo.toml                               |    2 +-
 rynk/rynk-wasm/src/client.rs                  |   29 +-
 rynk/src/api.rs                               |  155 ++-
 rynk/src/driver.rs                            |    7 +-
 19 files changed, 3152 insertions(+), 71 deletions(-)
 create mode 100644 rmk-types/src/protocol/rynk/payload/lighting.rs
 create mode 100644 rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
 create mode 100644 rmk/src/host/rynk/handlers/lighting.rs
 create mode 100644 rmk/src/host/rynk/lighting.rs

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 4f765947a..d799c2ddd 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -4,7 +4,7 @@
 
 # Rynk Protocol Reference
 
-Current protocol version: **0.1**.
+Current protocol version: **0.2**.
 
 Every transport (USB CDC, BLE GATT, BLE HID) carries the same frame — a 3-byte header plus a [postcard](https://docs.rs/postcard)-encoded payload:
 
@@ -19,71 +19,90 @@ Every transport (USB CDC, BLE GATT, BLE HID) carries the same frame — a 3-byte
 On the wire the whole frame is COBS-encoded and terminated by a single `0x00` delimiter, so the byte stream is self-synchronizing.
 
 - **Requests** use CMD `0x0000..=0x7FFF`. The response echoes CMD and SEQ and wraps its payload in postcard `Result<T, RynkError>` (`T = ()` for `Set*`).
+- **Lighting responses** use a `Lighting*Result` as `T`, preserving domain-specific `LightingError` detail inside the outer Rynk result.
 - **Topics** use CMD `0x8000..=0xFFFF` (server → host push, SEQ `0`, bare payload).
 
 Which commands a firmware answers depends on the RMK Cargo features it was built with: a row with no **Feature** is present once `rynk` is on, and the rest need their feature (`_ble`, `split`, …) compiled in. A command the firmware wasn't built with answers `UnknownCmd`.
 
 ## Endpoints
 
-| CMD      | Name                  | Request                | Response                | Feature | Notes                                                                        |
-| -------- | --------------------- | ---------------------- | ----------------------- | ------- | ---------------------------------------------------------------------------- |
-| `0x0001` | `GetVersion`          | `()`                   | `ProtocolVersion`       |         |                                                                              |
-| `0x0002` | `GetCapabilities`     | `()`                   | `DeviceCapabilities`    |         |                                                                              |
-| `0x0003` | `Reboot`              | `()`                   | `()`                    |         |                                                                              |
-| `0x0004` | `BootloaderJump`      | `()`                   | `()`                    |         |                                                                              |
-| `0x0005` | `StorageReset`        | `StorageResetMode`     | `()`                    |         |                                                                              |
-| `0x0006` | `GetLockStatus`       | `()`                   | `LockStatus`            |         | Pure read of the current lock state — no side effects.                       |
-| `0x0007` | `UnlockPoll`          | `()`                   | `LockStatus`            |         | Arms/refreshes the unlock attempt and samples the held challenge keys.       |
-| `0x0008` | `Lock`                | `()`                   | `()`                    |         | Relock immediately.                                                          |
-| `0x0009` | `GetLayout`           | `u32`                  | `LayoutChunk`           |         | Get layout blob chunk. `u32` is the byte offset.                             |
-| `0x000A` | `GetDeviceInfo`       | `()`                   | `DeviceInfo`            |         | Identity strings and USB ids; feature gating stays in `GetCapabilities`.     |
-| `0x0101` | `GetKeyAction`        | `KeyPosition`          | `KeyAction`             |         |                                                                              |
-| `0x0102` | `SetKeyAction`        | `SetKeyRequest`        | `()`                    |         |                                                                              |
-| `0x0103` | `GetDefaultLayer`     | `()`                   | `u8`                    |         |                                                                              |
-| `0x0104` | `SetDefaultLayer`     | `u8`                   | `()`                    |         |                                                                              |
-| `0x0105` | `GetEncoderAction`    | `GetEncoderRequest`    | `EncoderAction`         |         |                                                                              |
-| `0x0106` | `SetEncoderAction`    | `SetEncoderRequest`    | `()`                    |         |                                                                              |
-| `0x0107` | `GetKeymapBulk`       | `GetKeymapBulkRequest` | `GetKeymapBulkResponse` |         |                                                                              |
-| `0x0108` | `SetKeymapBulk`       | `SetKeymapBulkRequest` | `()`                    |         |                                                                              |
-| `0x0201` | `GetMacro`            | `GetMacroRequest`      | `MacroData`             |         |                                                                              |
-| `0x0202` | `SetMacro`            | `SetMacroRequest`      | `()`                    |         |                                                                              |
-| `0x0301` | `GetCombo`            | `u8`                   | `Combo`                 |         |                                                                              |
-| `0x0302` | `SetCombo`            | `SetComboRequest`      | `()`                    |         |                                                                              |
-| `0x0303` | `GetComboBulk`        | `GetComboBulkRequest`  | `GetComboBulkResponse`  |         |                                                                              |
-| `0x0304` | `SetComboBulk`        | `SetComboBulkRequest`  | `()`                    |         |                                                                              |
-| `0x0401` | `GetMorse`            | `u8`                   | `Morse`                 |         |                                                                              |
-| `0x0402` | `SetMorse`            | `SetMorseRequest`      | `()`                    |         |                                                                              |
-| `0x0403` | `GetMorseBulk`        | `GetMorseBulkRequest`  | `GetMorseBulkResponse`  |         |                                                                              |
-| `0x0404` | `SetMorseBulk`        | `SetMorseBulkRequest`  | `()`                    |         |                                                                              |
-| `0x0501` | `GetFork`             | `u8`                   | `Fork`                  |         |                                                                              |
-| `0x0502` | `SetFork`             | `SetForkRequest`       | `()`                    |         |                                                                              |
-| `0x0601` | `GetBehaviorConfig`   | `()`                   | `BehaviorConfig`        |         |                                                                              |
-| `0x0602` | `SetBehaviorConfig`   | `BehaviorConfig`       | `()`                    |         |                                                                              |
-| `0x0701` | `GetConnectionType`   | `()`                   | `ConnectionType`        |         |                                                                              |
-| `0x0702` | `GetConnectionStatus` | `()`                   | `ConnectionStatus`      |         | Full `ConnectionStatus` snapshot.                                            |
-| `0x0703` | `GetBleStatus`        | `()`                   | `BleStatus`             | `_ble`  |                                                                              |
-| `0x0704` | `SwitchBleProfile`    | `u8`                   | `()`                    | `_ble`  |                                                                              |
-| `0x0705` | `ClearBleProfile`     | `u8`                   | `()`                    | `_ble`  |                                                                              |
-| `0x0801` | `GetCurrentLayer`     | `()`                   | `u8`                    |         |                                                                              |
-| `0x0802` | `GetMatrixState`      | `()`                   | `MatrixState`           |         |                                                                              |
-| `0x0803` | `GetBatteryStatus`    | `()`                   | `BatteryStatus`         | `_ble`  |                                                                              |
-| `0x0804` | `GetPeripheralStatus` | `u8`                   | `PeripheralStatus`      | `split` |                                                                              |
-| `0x0805` | `GetWpm`              | `()`                   | `u16`                   |         | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                     |
-| `0x0806` | `GetSleepState`       | `()`                   | `bool`                  |         | Latest sleep flag, sourced from the `SleepState` topic snapshot.             |
-| `0x0807` | `GetLedIndicator`     | `()`                   | `LedIndicator`          |         | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot. |
+| CMD      | Name                           | Request                               | Response                            | Feature    | Notes                                                                        |
+| -------- | ------------------------------ | ------------------------------------- | ----------------------------------- | ---------- | ---------------------------------------------------------------------------- |
+| `0x0001` | `GetVersion`                   | `()`                                  | `ProtocolVersion`                   |            |                                                                              |
+| `0x0002` | `GetCapabilities`              | `()`                                  | `DeviceCapabilities`                |            |                                                                              |
+| `0x0003` | `Reboot`                       | `()`                                  | `()`                                |            |                                                                              |
+| `0x0004` | `BootloaderJump`               | `()`                                  | `()`                                |            |                                                                              |
+| `0x0005` | `StorageReset`                 | `StorageResetMode`                    | `()`                                |            |                                                                              |
+| `0x0006` | `GetLockStatus`                | `()`                                  | `LockStatus`                        |            | Pure read of the current lock state — no side effects.                       |
+| `0x0007` | `UnlockPoll`                   | `()`                                  | `LockStatus`                        |            | Arms/refreshes the unlock attempt and samples the held challenge keys.       |
+| `0x0008` | `Lock`                         | `()`                                  | `()`                                |            | Relock immediately.                                                          |
+| `0x0009` | `GetLayout`                    | `u32`                                 | `LayoutChunk`                       |            | Get layout blob chunk. `u32` is the byte offset.                             |
+| `0x000A` | `GetDeviceInfo`                | `()`                                  | `DeviceInfo`                        |            | Identity strings and USB ids; feature gating stays in `GetCapabilities`.     |
+| `0x0101` | `GetKeyAction`                 | `KeyPosition`                         | `KeyAction`                         |            |                                                                              |
+| `0x0102` | `SetKeyAction`                 | `SetKeyRequest`                       | `()`                                |            |                                                                              |
+| `0x0103` | `GetDefaultLayer`              | `()`                                  | `u8`                                |            |                                                                              |
+| `0x0104` | `SetDefaultLayer`              | `u8`                                  | `()`                                |            |                                                                              |
+| `0x0105` | `GetEncoderAction`             | `GetEncoderRequest`                   | `EncoderAction`                     |            |                                                                              |
+| `0x0106` | `SetEncoderAction`             | `SetEncoderRequest`                   | `()`                                |            |                                                                              |
+| `0x0107` | `GetKeymapBulk`                | `GetKeymapBulkRequest`                | `GetKeymapBulkResponse`             |            |                                                                              |
+| `0x0108` | `SetKeymapBulk`                | `SetKeymapBulkRequest`                | `()`                                |            |                                                                              |
+| `0x0201` | `GetMacro`                     | `GetMacroRequest`                     | `MacroData`                         |            |                                                                              |
+| `0x0202` | `SetMacro`                     | `SetMacroRequest`                     | `()`                                |            |                                                                              |
+| `0x0301` | `GetCombo`                     | `u8`                                  | `Combo`                             |            |                                                                              |
+| `0x0302` | `SetCombo`                     | `SetComboRequest`                     | `()`                                |            |                                                                              |
+| `0x0303` | `GetComboBulk`                 | `GetComboBulkRequest`                 | `GetComboBulkResponse`              |            |                                                                              |
+| `0x0304` | `SetComboBulk`                 | `SetComboBulkRequest`                 | `()`                                |            |                                                                              |
+| `0x0401` | `GetMorse`                     | `u8`                                  | `Morse`                             |            |                                                                              |
+| `0x0402` | `SetMorse`                     | `SetMorseRequest`                     | `()`                                |            |                                                                              |
+| `0x0403` | `GetMorseBulk`                 | `GetMorseBulkRequest`                 | `GetMorseBulkResponse`              |            |                                                                              |
+| `0x0404` | `SetMorseBulk`                 | `SetMorseBulkRequest`                 | `()`                                |            |                                                                              |
+| `0x0501` | `GetFork`                      | `u8`                                  | `Fork`                              |            |                                                                              |
+| `0x0502` | `SetFork`                      | `SetForkRequest`                      | `()`                                |            |                                                                              |
+| `0x0601` | `GetBehaviorConfig`            | `()`                                  | `BehaviorConfig`                    |            |                                                                              |
+| `0x0602` | `SetBehaviorConfig`            | `BehaviorConfig`                      | `()`                                |            |                                                                              |
+| `0x0701` | `GetConnectionType`            | `()`                                  | `ConnectionType`                    |            |                                                                              |
+| `0x0702` | `GetConnectionStatus`          | `()`                                  | `ConnectionStatus`                  |            | Full `ConnectionStatus` snapshot.                                            |
+| `0x0703` | `GetBleStatus`                 | `()`                                  | `BleStatus`                         | `_ble`     |                                                                              |
+| `0x0704` | `SwitchBleProfile`             | `u8`                                  | `()`                                | `_ble`     |                                                                              |
+| `0x0705` | `ClearBleProfile`              | `u8`                                  | `()`                                | `_ble`     |                                                                              |
+| `0x0801` | `GetCurrentLayer`              | `()`                                  | `u8`                                |            |                                                                              |
+| `0x0802` | `GetMatrixState`               | `()`                                  | `MatrixState`                       |            |                                                                              |
+| `0x0803` | `GetBatteryStatus`             | `()`                                  | `BatteryStatus`                     | `_ble`     |                                                                              |
+| `0x0804` | `GetPeripheralStatus`          | `u8`                                  | `PeripheralStatus`                  | `split`    |                                                                              |
+| `0x0805` | `GetWpm`                       | `()`                                  | `u16`                               |            | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                     |
+| `0x0806` | `GetSleepState`                | `()`                                  | `bool`                              |            | Latest sleep flag, sourced from the `SleepState` topic snapshot.             |
+| `0x0807` | `GetLedIndicator`              | `()`                                  | `LedIndicator`                      |            | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot. |
+| `0x0901` | `GetLightingCapabilities`      | `()`                                  | `LightingCapabilitiesResult`        | `lighting` |                                                                              |
+| `0x0902` | `GetLightingState`             | `()`                                  | `LightingStateResult`               | `lighting` |                                                                              |
+| `0x0903` | `SetLightingState`             | `SetLightingStateRequest`             | `LightingStateResult`               | `lighting` |                                                                              |
+| `0x0904` | `GetLightingPhysicalKeys`      | `LightingPageRequest`                 | `LightingPhysicalKeysPageResult`    | `lighting` |                                                                              |
+| `0x0905` | `GetLightingLeds`              | `LightingPageRequest`                 | `LightingLedsPageResult`            | `lighting` |                                                                              |
+| `0x0906` | `GetLightingZones`             | `LightingPageRequest`                 | `LightingZonesPageResult`           | `lighting` |                                                                              |
+| `0x0907` | `GetLightingZoneMemberships`   | `LightingPageRequest`                 | `LightingZoneMembershipsPageResult` | `lighting` |                                                                              |
+| `0x0908` | `GetLightingOutputs`           | `LightingPageRequest`                 | `LightingOutputsPageResult`         | `lighting` |                                                                              |
+| `0x0909` | `GetLightingRoutes`            | `LightingPageRequest`                 | `LightingRoutesPageResult`          | `lighting` |                                                                              |
+| `0x090A` | `SetLightingOverlay`           | `SetLightingOverlayRequest`           | `LightingStateResult`               | `lighting` |                                                                              |
+| `0x090B` | `UnsetLightingOverlay`         | `UnsetLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                              |
+| `0x090C` | `ClearLightingOverlay`         | `ClearLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                              |
+| `0x090D` | `BeginLightingOverlayReplace`  | `BeginLightingOverlayReplaceRequest`  | `LightingOverlayTransactionResult`  | `lighting` |                                                                              |
+| `0x090E` | `PutLightingOverlayChunk`      | `PutLightingOverlayChunkRequest`      | `LightingUnitResult`                | `lighting` |                                                                              |
+| `0x090F` | `CommitLightingOverlayReplace` | `CommitLightingOverlayReplaceRequest` | `LightingStateResult`               | `lighting` |                                                                              |
+| `0x0910` | `AbortLightingOverlayReplace`  | `AbortLightingOverlayReplaceRequest`  | `LightingUnitResult`                | `lighting` |                                                                              |
+| `0x0911` | `GetLightingKeys`              | `LightingPageRequest`                 | `LightingKeysPageResult`            | `lighting` | Logical matrix keys are distinct from optional physical geometry.            |
 
 ## Topics
 
 Topics are best-effort pushes; the `Get*` endpoints above mirror their payloads so a host can recover a missed push.
 
-| CMD      | Name                  | Payload            | Feature | Notes |
-| -------- | --------------------- | ------------------ | ------- | ----- |
-| `0x8001` | `LayerChange`         | `u8`               |         |       |
-| `0x8002` | `WpmUpdate`           | `u16`              |         |       |
-| `0x8003` | `ConnectionChange`    | `ConnectionStatus` |         |       |
-| `0x8004` | `SleepState`          | `bool`             |         |       |
-| `0x8005` | `LedIndicatorChange`  | `LedIndicator`     |         |       |
-| `0x8006` | `BatteryStatusChange` | `BatteryStatus`    | `_ble`  |       |
+| CMD      | Name                  | Payload            | Feature    | Notes |
+| -------- | --------------------- | ------------------ | ---------- | ----- |
+| `0x8001` | `LayerChange`         | `u8`               |            |       |
+| `0x8002` | `WpmUpdate`           | `u16`              |            |       |
+| `0x8003` | `ConnectionChange`    | `ConnectionStatus` |            |       |
+| `0x8004` | `SleepState`          | `bool`             |            |       |
+| `0x8005` | `LedIndicatorChange`  | `LedIndicator`     |            |       |
+| `0x8006` | `BatteryStatusChange` | `BatteryStatus`    | `_ble`     |       |
+| `0x8007` | `LightingChange`      | `LightingChanged`  | `lighting` |       |
 
 ## Compatibility
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 270ed34aa..d2fd47095 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -32,6 +32,15 @@ use crate::led_indicator::LedIndicator;
 use crate::morse::Morse;
 #[cfg(feature = "split")]
 use crate::protocol::rynk::PeripheralStatus;
+#[cfg(feature = "lighting")]
+use crate::protocol::rynk::{
+    AbortLightingOverlayReplaceRequest, BeginLightingOverlayReplaceRequest, ClearLightingOverlayRequest,
+    CommitLightingOverlayReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingKeysPageResult,
+    LightingLedsPageResult, LightingOutputsPageResult, LightingOverlayTransactionResult, LightingPageRequest,
+    LightingPhysicalKeysPageResult, LightingRoutesPageResult, LightingStateResult, LightingUnitResult,
+    LightingZoneMembershipsPageResult, LightingZonesPageResult, PutLightingOverlayChunkRequest,
+    SetLightingOverlayRequest, SetLightingStateRequest, UnsetLightingOverlayRequest,
+};
 
 /// CMD high bit marking a topic (server → host push).
 const RYNK_TOPIC_BIT: u16 = 0x8000;
@@ -337,6 +346,44 @@ endpoints! {
     GetSleepState = 0x0806: () => bool;
     /// Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.
     GetLedIndicator = 0x0807: () => LedIndicator;
+
+    // Lighting (0x09xx). Lighting-domain errors are nested inside Rynk's
+    // outer protocol result so hosts retain precise rejection reasons.
+    #[cfg(feature = "lighting")]
+    GetLightingCapabilities = 0x0901: () => LightingCapabilitiesResult;
+    #[cfg(feature = "lighting")]
+    GetLightingState = 0x0902: () => LightingStateResult;
+    #[cfg(feature = "lighting")]
+    SetLightingState = 0x0903: SetLightingStateRequest => LightingStateResult;
+    #[cfg(feature = "lighting")]
+    GetLightingPhysicalKeys = 0x0904: LightingPageRequest => LightingPhysicalKeysPageResult;
+    #[cfg(feature = "lighting")]
+    GetLightingLeds = 0x0905: LightingPageRequest => LightingLedsPageResult;
+    #[cfg(feature = "lighting")]
+    GetLightingZones = 0x0906: LightingPageRequest => LightingZonesPageResult;
+    #[cfg(feature = "lighting")]
+    GetLightingZoneMemberships = 0x0907: LightingPageRequest => LightingZoneMembershipsPageResult;
+    #[cfg(feature = "lighting")]
+    GetLightingOutputs = 0x0908: LightingPageRequest => LightingOutputsPageResult;
+    #[cfg(feature = "lighting")]
+    GetLightingRoutes = 0x0909: LightingPageRequest => LightingRoutesPageResult;
+    #[cfg(feature = "lighting")]
+    SetLightingOverlay = 0x090A: SetLightingOverlayRequest => LightingStateResult;
+    #[cfg(feature = "lighting")]
+    UnsetLightingOverlay = 0x090B: UnsetLightingOverlayRequest => LightingStateResult;
+    #[cfg(feature = "lighting")]
+    ClearLightingOverlay = 0x090C: ClearLightingOverlayRequest => LightingStateResult;
+    #[cfg(feature = "lighting")]
+    BeginLightingOverlayReplace = 0x090D: BeginLightingOverlayReplaceRequest => LightingOverlayTransactionResult;
+    #[cfg(feature = "lighting")]
+    PutLightingOverlayChunk = 0x090E: PutLightingOverlayChunkRequest => LightingUnitResult;
+    #[cfg(feature = "lighting")]
+    CommitLightingOverlayReplace = 0x090F: CommitLightingOverlayReplaceRequest => LightingStateResult;
+    #[cfg(feature = "lighting")]
+    AbortLightingOverlayReplace = 0x0910: AbortLightingOverlayReplaceRequest => LightingUnitResult;
+    /// Logical matrix keys are distinct from optional physical geometry.
+    #[cfg(feature = "lighting")]
+    GetLightingKeys = 0x0911: LightingPageRequest => LightingKeysPageResult;
 }
 
 // Define topics: `Name = value: Payload;`
@@ -349,6 +396,8 @@ topics! {
     LedIndicatorChange = 0x8005: LedIndicator;
     #[cfg(feature = "_ble")]
     BatteryStatusChange = 0x8006: BatteryStatus;
+    #[cfg(feature = "lighting")]
+    LightingChange = 0x8007: LightingChanged;
 }
 
 /// The payload budget advertised to hosts must cover the largest payload
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
new file mode 100644
index 000000000..8dd116638
--- /dev/null
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -0,0 +1,600 @@
+//! Lighting protocol types.
+//!
+//! The wire model deliberately separates stable, board-visible identities
+//! from dense compositor slots and electrical chain order. Hosts address
+//! lights by [`LightingLedId`]; topology and routing readback explain key
+//! association, geometry, zones, split-node ownership, and physical outputs.
+
+use heapless::{String, Vec};
+use postcard::experimental::max_size::MaxSize;
+use serde::{Deserialize, Serialize};
+
+/// Maximum postcard payload admitted by this first lighting ICD.
+pub const LIGHTING_PAYLOAD_SIZE: usize = 256;
+/// Number of metadata records in one topology page.
+pub const LIGHTING_PAGE_SIZE: usize = 8;
+/// Number of overlay cells in one replacement chunk.
+pub const LIGHTING_OVERLAY_CHUNK_SIZE: usize = 8;
+/// Maximum UTF-8 byte length of a zone name.
+pub const LIGHTING_ZONE_NAME_SIZE: usize = 24;
+
+macro_rules! wire_type {
+    ($item:item) => {
+        #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, MaxSize)]
+        #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+        #[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+        #[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+        $item
+    };
+}
+
+wire_type! {
+    /// Stable, board-wide identity of one independently controllable light.
+    #[repr(transparent)]
+    pub struct LightingLedId(pub u16);
+}
+
+wire_type! {
+    /// Stable identity of one semantic lighting zone.
+    #[repr(transparent)]
+    pub struct LightingZoneId(pub u8);
+}
+
+wire_type! {
+    /// Identity of a lighting processor, such as one half of a split keyboard.
+    #[repr(transparent)]
+    pub struct LightingNodeId(pub u8);
+}
+
+wire_type! {
+    /// Identity of one physical output owned by a lighting node.
+    #[repr(transparent)]
+    pub struct LightingOutputId(pub u8);
+}
+
+wire_type! {
+    /// One real key in RMK's logical matrix. Matrix holes have no record.
+    pub struct LightingMatrixPosition {
+        pub row: u8,
+        pub col: u8,
+    }
+}
+
+wire_type! {
+    /// Board-global Q8.8 point in key-pitch units.
+    pub struct LightingPoint3 {
+        pub x: i16,
+        pub y: i16,
+        pub z: i16,
+    }
+}
+
+wire_type! {
+    /// Positive Q8.8 key dimensions in key-pitch units.
+    pub struct LightingKeySize {
+        pub width: u16,
+        pub height: u16,
+    }
+}
+
+wire_type! {
+    /// Shared physical-key geometry consumed by lighting, displays, and hosts.
+    pub struct LightingPhysicalKey {
+        pub matrix: LightingMatrixPosition,
+        pub center: LightingPoint3,
+        pub size: LightingKeySize,
+        /// Clockwise rotation in hundredths of one degree.
+        pub rotation: i16,
+    }
+}
+
+wire_type! {
+    /// One semantic light. It may have key association, explicit geometry,
+    /// both, or neither.
+    pub struct LightingLed {
+        pub id: LightingLedId,
+        pub key: Option<LightingMatrixPosition>,
+        pub position: Option<LightingPoint3>,
+        /// Span into the flat zone-membership table.
+        pub zone_start: u16,
+        pub zone_len: u8,
+    }
+}
+
+/// One named semantic zone.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LightingZone {
+    pub id: LightingZoneId,
+    #[cfg_attr(feature = "wasm", tsify(type = "string"))]
+    pub name: String<LIGHTING_ZONE_NAME_SIZE>,
+}
+
+impl MaxSize for LightingZone {
+    const POSTCARD_MAX_SIZE: usize =
+        LightingZoneId::POSTCARD_MAX_SIZE + crate::heapless_vec_max_size::<u8, LIGHTING_ZONE_NAME_SIZE>();
+}
+
+wire_type! {
+    /// Color and addressability capabilities of a physical output.
+    #[repr(transparent)]
+    pub struct LightingOutputCapabilities(pub u8);
+}
+
+impl LightingOutputCapabilities {
+    pub const BINARY: u8 = 1 << 0;
+    pub const INTENSITY: u8 = 1 << 1;
+    pub const RGB: u8 = 1 << 2;
+    pub const WHITE: u8 = 1 << 3;
+    pub const ADDRESSABLE: u8 = 1 << 4;
+
+    pub const fn contains(self, bits: u8) -> bool {
+        self.0 & bits == bits
+    }
+}
+
+wire_type! {
+    /// Whether all physical pixels of an output must have a logical route.
+    pub enum LightingOutputCoverage {
+        Complete,
+        Sparse,
+    }
+}
+
+wire_type! {
+    /// One concrete output on one lighting node.
+    pub struct LightingOutput {
+        pub node: LightingNodeId,
+        pub id: LightingOutputId,
+        pub pixel_count: u16,
+        pub capabilities: LightingOutputCapabilities,
+        pub coverage: LightingOutputCoverage,
+    }
+}
+
+wire_type! {
+    /// Stable-light to physical-address mapping. Dense compositor slots are
+    /// intentionally not part of the public protocol.
+    pub struct LightingRoute {
+        pub led_id: LightingLedId,
+        pub node: LightingNodeId,
+        pub output: LightingOutputId,
+        pub physical_index: u16,
+    }
+}
+
+wire_type! {
+    /// Optional capabilities beyond the mandatory state/topology surface.
+    #[repr(transparent)]
+    pub struct LightingFeatureFlags(pub u16);
+}
+
+impl LightingFeatureFlags {
+    pub const PHYSICAL_GEOMETRY: u16 = 1 << 0;
+    pub const ZONES: u16 = 1 << 1;
+    pub const ROUTING: u16 = 1 << 2;
+    pub const OVERLAY_TTL: u16 = 1 << 3;
+    pub const ATOMIC_OVERLAY_REPLACE: u16 = 1 << 4;
+    pub const LAYER_AWARE: u16 = 1 << 5;
+
+    pub const fn contains(self, bits: u16) -> bool {
+        self.0 & bits == bits
+    }
+}
+
+wire_type! {
+    /// Built-in effects accepted by this firmware.
+    #[repr(transparent)]
+    pub struct LightingEffectFlags(pub u8);
+}
+
+impl LightingEffectFlags {
+    pub const SOLID: u8 = 1 << 0;
+    pub const BLINK: u8 = 1 << 1;
+    pub const BREATHE: u8 = 1 << 2;
+
+    pub const fn contains(self, bits: u8) -> bool {
+        self.0 & bits == bits
+    }
+}
+
+wire_type! {
+    /// Static limits and topology identity for a lighting-enabled device.
+    pub struct LightingCapabilities {
+        pub topology_revision: u32,
+        /// Real logical matrix keys, including keys without measured geometry.
+        pub logical_key_count: u16,
+        pub physical_key_count: u16,
+        pub led_count: u16,
+        pub zone_count: u16,
+        pub zone_membership_count: u16,
+        pub output_count: u16,
+        pub route_count: u16,
+        pub overlay_capacity: u16,
+        pub page_capacity: u8,
+        pub overlay_chunk_capacity: u8,
+        pub features: LightingFeatureFlags,
+        pub effects: LightingEffectFlags,
+    }
+}
+
+wire_type! {
+    /// Revision-pinned request for one metadata page.
+    pub struct LightingPageRequest {
+        pub topology_revision: u32,
+        pub offset: u16,
+    }
+}
+
+macro_rules! page_type {
+    ($name:ident, $item:ty, $ts:literal) => {
+        #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+        #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+        #[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+        #[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+        pub struct $name {
+            pub topology_revision: u32,
+            pub total_count: u16,
+            #[cfg_attr(feature = "wasm", tsify(type = $ts))]
+            pub items: Vec<$item, LIGHTING_PAGE_SIZE>,
+        }
+
+        impl MaxSize for $name {
+            const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+                + u16::POSTCARD_MAX_SIZE
+                + crate::heapless_vec_max_size::<$item, LIGHTING_PAGE_SIZE>();
+        }
+    };
+}
+
+page_type!(LightingKeysPage, LightingMatrixPosition, "LightingMatrixPosition[]");
+page_type!(LightingPhysicalKeysPage, LightingPhysicalKey, "LightingPhysicalKey[]");
+page_type!(LightingLedsPage, LightingLed, "LightingLed[]");
+page_type!(LightingZonesPage, LightingZone, "LightingZone[]");
+page_type!(LightingZoneMembershipsPage, LightingZoneId, "LightingZoneId[]");
+page_type!(LightingOutputsPage, LightingOutput, "LightingOutput[]");
+page_type!(LightingRoutesPage, LightingRoute, "LightingRoute[]");
+
+wire_type! {
+    /// Device-independent linear RGB sample.
+    pub struct LightingRgb8 {
+        pub r: u8,
+        pub g: u8,
+        pub b: u8,
+    }
+}
+
+wire_type! {
+    /// Bounded set of standard effects understood by the RMK lighting engine.
+    pub enum LightingEffect {
+        Solid {
+            color: LightingRgb8,
+        },
+        Blink {
+            color: LightingRgb8,
+            period_ms: u32,
+            phase_ms: u32,
+            duty: u8,
+        },
+        Breathe {
+            color: LightingRgb8,
+            period_ms: u32,
+            phase_ms: u32,
+            step_ms: u16,
+        },
+    }
+}
+
+impl LightingEffect {
+    /// Validate parameters before adapting this wire value to the standard
+    /// engine. Invalid effects never partially mutate live lighting state.
+    pub const fn validate(&self) -> LightingResult<()> {
+        match *self {
+            Self::Solid { .. } => Ok(()),
+            Self::Blink { period_ms, duty, .. } if period_ms != 0 && duty <= 100 => Ok(()),
+            Self::Breathe { period_ms, step_ms, .. }
+                if period_ms >= 2 && step_ms != 0 && (step_ms as u32) < period_ms =>
+            {
+                Ok(())
+            }
+            _ => Err(LightingError::InvalidEffect),
+        }
+    }
+}
+
+wire_type! {
+    pub enum LightingBackgroundMode {
+        Solid,
+        Breathe,
+    }
+}
+
+wire_type! {
+    /// VIA-compatible designated background. It is only the lowest standard
+    /// source; disabling it does not disable layers, overlays, or status.
+    pub struct LightingBackgroundState {
+        pub enabled: bool,
+        pub hue: u8,
+        pub saturation: u8,
+        pub value: u8,
+        pub speed: u8,
+        pub mode: LightingBackgroundMode,
+    }
+}
+
+wire_type! {
+    pub struct LightingMutableState {
+        pub output_enabled: bool,
+        pub output_brightness: u8,
+        pub background: LightingBackgroundState,
+    }
+}
+
+wire_type! {
+    /// Authoritative mutable state and optimistic-concurrency revision.
+    pub struct LightingState {
+        pub revision: u32,
+        pub output_enabled: bool,
+        pub output_brightness: u8,
+        pub background: LightingBackgroundState,
+        pub overlay_len: u16,
+    }
+}
+
+wire_type! {
+    pub struct SetLightingStateRequest {
+        pub expected_revision: u32,
+        pub state: LightingMutableState,
+    }
+}
+
+wire_type! {
+    /// One transient overlay cell addressed by stable LED identity.
+    pub struct LightingOverlayCell {
+        pub led_id: LightingLedId,
+        pub effect: LightingEffect,
+        /// Relative lifetime. `None` lasts until unset, clear, or reboot;
+        /// `Some(0)` is invalid.
+        pub ttl_ms: Option<u32>,
+    }
+}
+
+impl LightingOverlayCell {
+    /// Validate the effect and relative lifetime. `None` is persistent and a
+    /// positive TTL expires in firmware time; zero is never ambiguous.
+    pub const fn validate(&self) -> LightingResult<()> {
+        if matches!(self.ttl_ms, Some(0)) {
+            return Err(LightingError::InvalidTtl);
+        }
+        self.effect.validate()
+    }
+}
+
+wire_type! {
+    pub struct SetLightingOverlayRequest {
+        pub expected_revision: u32,
+        pub cell: LightingOverlayCell,
+    }
+}
+
+wire_type! {
+    pub struct UnsetLightingOverlayRequest {
+        pub expected_revision: u32,
+        pub led_id: LightingLedId,
+    }
+}
+
+wire_type! {
+    pub struct ClearLightingOverlayRequest {
+        pub expected_revision: u32,
+    }
+}
+
+wire_type! {
+    /// Begin an atomic, multi-packet overlay replacement.
+    pub struct BeginLightingOverlayReplaceRequest {
+        pub expected_revision: u32,
+        pub cell_count: u16,
+    }
+}
+
+wire_type! {
+    /// Opaque transaction token allocated by the firmware.
+    pub struct LightingOverlayTransaction {
+        pub id: u32,
+        pub cell_count: u16,
+    }
+}
+
+/// One ordered transaction chunk. Chunks are applied only by commit.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct PutLightingOverlayChunkRequest {
+    pub transaction_id: u32,
+    pub offset: u16,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingOverlayCell[]"))]
+    pub cells: Vec<LightingOverlayCell, LIGHTING_OVERLAY_CHUNK_SIZE>,
+}
+
+impl MaxSize for PutLightingOverlayChunkRequest {
+    const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+        + u16::POSTCARD_MAX_SIZE
+        + crate::heapless_vec_max_size::<LightingOverlayCell, LIGHTING_OVERLAY_CHUNK_SIZE>();
+}
+
+wire_type! {
+    pub struct CommitLightingOverlayReplaceRequest {
+        pub transaction_id: u32,
+    }
+}
+
+wire_type! {
+    pub struct AbortLightingOverlayReplaceRequest {
+        pub transaction_id: u32,
+    }
+}
+
+wire_type! {
+    /// Lighting-domain rejection carried inside Rynk's outer protocol result.
+    pub enum LightingError {
+        Unsupported,
+        InvalidRequest,
+        InvalidEffect,
+        InvalidTtl,
+        TopologyRevisionConflict { expected: u32, current: u32 },
+        StateRevisionConflict { expected: u32, current: u32 },
+        UnknownLed { led_id: LightingLedId },
+        OverlayFull { capacity: u16 },
+        TransactionBusy,
+        InvalidTransaction,
+        TransactionExpired,
+        TransactionIncomplete { expected: u16, received: u16 },
+    }
+}
+
+/// Detailed lighting result nested inside Rynk's transport/protocol result.
+pub type LightingResult<T> = Result<T, LightingError>;
+pub type LightingCapabilitiesResult = LightingResult<LightingCapabilities>;
+pub type LightingStateResult = LightingResult<LightingState>;
+pub type LightingKeysPageResult = LightingResult<LightingKeysPage>;
+pub type LightingPhysicalKeysPageResult = LightingResult<LightingPhysicalKeysPage>;
+pub type LightingLedsPageResult = LightingResult<LightingLedsPage>;
+pub type LightingZonesPageResult = LightingResult<LightingZonesPage>;
+pub type LightingZoneMembershipsPageResult = LightingResult<LightingZoneMembershipsPage>;
+pub type LightingOutputsPageResult = LightingResult<LightingOutputsPage>;
+pub type LightingRoutesPageResult = LightingResult<LightingRoutesPage>;
+pub type LightingOverlayTransactionResult = LightingResult<LightingOverlayTransaction>;
+pub type LightingUnitResult = LightingResult<()>;
+
+wire_type! {
+    /// Best-effort invalidation marker. Hosts recover current authoritative
+    /// state with `GetLightingState`; events never carry a second state copy.
+    pub struct LightingChanged;
+}
+
+const _: () = {
+    use crate::protocol::rynk::RynkError;
+
+    macro_rules! assert_endpoint_fits {
+        ($req:ty, $resp:ty) => {
+            core::assert!(<$req as MaxSize>::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+            core::assert!(<Result<$resp, RynkError> as MaxSize>::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+        };
+    }
+
+    assert_endpoint_fits!((), LightingCapabilitiesResult);
+    assert_endpoint_fits!((), LightingStateResult);
+    assert_endpoint_fits!(SetLightingStateRequest, LightingStateResult);
+    assert_endpoint_fits!(LightingPageRequest, LightingKeysPageResult);
+    assert_endpoint_fits!(LightingPageRequest, LightingPhysicalKeysPageResult);
+    assert_endpoint_fits!(LightingPageRequest, LightingLedsPageResult);
+    assert_endpoint_fits!(LightingPageRequest, LightingZonesPageResult);
+    assert_endpoint_fits!(LightingPageRequest, LightingZoneMembershipsPageResult);
+    assert_endpoint_fits!(LightingPageRequest, LightingOutputsPageResult);
+    assert_endpoint_fits!(LightingPageRequest, LightingRoutesPageResult);
+    assert_endpoint_fits!(SetLightingOverlayRequest, LightingStateResult);
+    assert_endpoint_fits!(UnsetLightingOverlayRequest, LightingStateResult);
+    assert_endpoint_fits!(ClearLightingOverlayRequest, LightingStateResult);
+    assert_endpoint_fits!(BeginLightingOverlayReplaceRequest, LightingOverlayTransactionResult);
+    assert_endpoint_fits!(PutLightingOverlayChunkRequest, LightingUnitResult);
+    assert_endpoint_fits!(CommitLightingOverlayReplaceRequest, LightingStateResult);
+    assert_endpoint_fits!(AbortLightingOverlayReplaceRequest, LightingUnitResult);
+    core::assert!(LightingChanged::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+};
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::protocol::rynk::tests::{assert_max_size_bound, round_trip};
+
+    fn cell(id: u16) -> LightingOverlayCell {
+        LightingOverlayCell {
+            led_id: LightingLedId(id),
+            effect: LightingEffect::Blink {
+                color: LightingRgb8 { r: 1, g: 2, b: 3 },
+                period_ms: u32::MAX,
+                phase_ms: u32::MAX,
+                duty: 100,
+            },
+            ttl_ms: Some(u32::MAX),
+        }
+    }
+
+    #[test]
+    fn geometry_and_key_association_round_trip() {
+        round_trip(&LightingLed {
+            id: LightingLedId(42),
+            key: Some(LightingMatrixPosition { row: 3, col: 7 }),
+            position: Some(LightingPoint3 { x: -128, y: 256, z: 64 }),
+            zone_start: 2,
+            zone_len: 3,
+        });
+        round_trip(&LightingLed {
+            id: LightingLedId(1000),
+            key: None,
+            position: None,
+            zone_start: 0,
+            zone_len: 0,
+        });
+    }
+
+    #[test]
+    fn maximum_overlay_chunk_respects_bound() {
+        let mut cells = Vec::new();
+        for id in 0..LIGHTING_OVERLAY_CHUNK_SIZE as u16 {
+            cells.push(cell(id)).unwrap();
+        }
+        let request = PutLightingOverlayChunkRequest {
+            transaction_id: u32::MAX,
+            offset: u16::MAX,
+            cells,
+        };
+        round_trip(&request);
+        assert_max_size_bound(&request);
+        assert!(PutLightingOverlayChunkRequest::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+    }
+
+    #[test]
+    fn maximum_zone_page_respects_bound() {
+        let mut items = Vec::new();
+        for id in 0..LIGHTING_PAGE_SIZE as u8 {
+            let mut name = String::new();
+            for _ in 0..LIGHTING_ZONE_NAME_SIZE {
+                name.push('x').unwrap();
+            }
+            items
+                .push(LightingZone {
+                    id: LightingZoneId(id),
+                    name,
+                })
+                .unwrap();
+        }
+        let page = LightingZonesPage {
+            topology_revision: u32::MAX,
+            total_count: u16::MAX,
+            items,
+        };
+        round_trip(&page);
+        assert_max_size_bound(&page);
+    }
+
+    #[test]
+    fn effect_and_ttl_validation_is_explicit() {
+        let mut valid = cell(1);
+        assert_eq!(valid.validate(), Ok(()));
+        valid.ttl_ms = Some(0);
+        assert_eq!(valid.validate(), Err(LightingError::InvalidTtl));
+        valid.ttl_ms = None;
+        valid.effect = LightingEffect::Breathe {
+            color: LightingRgb8 { r: 1, g: 2, b: 3 },
+            period_ms: 100,
+            phase_ms: 0,
+            step_ms: 100,
+        };
+        assert_eq!(valid.validate(), Err(LightingError::InvalidEffect));
+    }
+}
diff --git a/rmk-types/src/protocol/rynk/payload/mod.rs b/rmk-types/src/protocol/rynk/payload/mod.rs
index f2f8ec5d0..283b01863 100644
--- a/rmk-types/src/protocol/rynk/payload/mod.rs
+++ b/rmk-types/src/protocol/rynk/payload/mod.rs
@@ -6,6 +6,8 @@ mod encoder;
 mod fork;
 mod keymap;
 mod layout;
+#[cfg(feature = "lighting")]
+mod lighting;
 mod macro_data;
 mod morse;
 mod status;
@@ -17,6 +19,8 @@ pub use self::encoder::*;
 pub use self::fork::*;
 pub use self::keymap::*;
 pub use self::layout::*;
+#[cfg(feature = "lighting")]
+pub use self::lighting::*;
 pub use self::macro_data::*;
 pub use self::morse::*;
 pub use self::status::*;
diff --git a/rmk-types/src/protocol/rynk/payload/system.rs b/rmk-types/src/protocol/rynk/payload/system.rs
index 112dbe664..9a37c2556 100644
--- a/rmk-types/src/protocol/rynk/payload/system.rs
+++ b/rmk-types/src/protocol/rynk/payload/system.rs
@@ -20,8 +20,8 @@ pub struct ProtocolVersion {
 
 impl ProtocolVersion {
     /// Current protocol version for this firmware release.
-    /// Now the protocol is still being developed, so the version is v0.1
-    pub const CURRENT: Self = Self { major: 0, minor: 1 };
+    /// The protocol is still under development; lighting endpoints were added in v0.2.
+    pub const CURRENT: Self = Self { major: 0, minor: 2 };
 }
 
 /// Device capabilities discovered during the connection handshake.
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
new file mode 100644
index 000000000..ef4d3c989
--- /dev/null
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -0,0 +1,45 @@
+# Lighting wire-format FRAME snapshot — DO NOT edit by hand.
+# File: snapshots/lighting_wire_frames.snap
+# Each entry is one complete feature-gated lighting Rynk frame. The nested
+# Ok/Err exemplars pin the outer Rynk result and inner lighting result.
+#   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk --features lighting lighting_wire_frames
+# Format: <label>  <hex bytes>
+
+AbortLightingOverlayReplace reply                      10 09 01 02 00 00 00
+AbortLightingOverlayReplace request                    10 09 01 01 00 0d
+BeginLightingOverlayReplace reply                      0d 09 01 04 00 00 00 0d 01
+BeginLightingOverlayReplace request                    0d 09 01 02 00 0c 01
+ClearLightingOverlay reply                             0c 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+ClearLightingOverlay request                           0c 09 01 01 00 0b
+CommitLightingOverlayReplace reply                     0f 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+CommitLightingOverlayReplace request                   0f 09 01 01 00 0d
+GetLightingCapabilities reply                          01 09 01 0f 00 00 00 01 02 03 04 05 06 07 08 09 08 08 3f 07
+GetLightingCapabilities request                        01 09 01 00 00
+GetLightingKeys reply                                  11 09 01 07 00 00 00 01 01 01 01 02
+GetLightingKeys request                                11 09 01 02 00 01 00
+GetLightingLeds reply                                  05 09 01 12 00 00 00 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01
+GetLightingLeds request                                05 09 01 02 00 01 00
+GetLightingOutputs reply                               08 09 01 0a 00 00 00 01 01 01 01 02 28 14 00
+GetLightingOutputs request                             08 09 01 02 00 01 00
+GetLightingPhysicalKeys reply                          04 09 01 13 00 00 00 01 01 01 01 02 ff 01 80 04 80 01 80 02 80 03 db 0b
+GetLightingPhysicalKeys request                        04 09 01 02 00 01 00
+GetLightingRoutes reply                                09 09 01 09 00 00 00 01 01 01 2a 01 02 07
+GetLightingRoutes request                              09 09 01 02 00 01 00
+GetLightingState reply                                 02 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+GetLightingState request                               02 09 01 00 00
+GetLightingZoneMemberships reply                       07 09 01 06 00 00 00 01 01 01 04
+GetLightingZoneMemberships request                     07 09 01 02 00 01 00
+GetLightingZones reply                                 06 09 01 0c 00 00 00 01 01 01 04 05 74 68 75 6d 62
+GetLightingZones request                               06 09 01 02 00 01 00
+LightingChange topic                                   07 80 00 00 00
+PutLightingOverlayChunk inner Err(TransactionExpired)  0e 09 01 03 00 00 01 0a
+PutLightingOverlayChunk reply                          0e 09 01 02 00 00 00
+PutLightingOverlayChunk request                        0e 09 01 10 00 0d 00 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27
+SetLightingOverlay inner Err(UnknownLed)               0a 09 01 05 00 00 01 06 e7 07
+SetLightingOverlay outer Err(Locked)                   0a 09 01 02 00 01 07
+SetLightingOverlay reply                               0a 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+SetLightingOverlay request                             0a 09 01 0e 00 09 2a 01 01 02 03 e8 07 fa 01 32 01 88 27
+SetLightingState reply                                 03 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+SetLightingState request                               03 09 01 09 00 08 01 c8 01 0a 14 1e 28 01
+UnsetLightingOverlay reply                             0b 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+UnsetLightingOverlay request                           0b 09 01 02 00 0a 2a
diff --git a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
index 073c10d80..257fc628e 100644
--- a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
@@ -64,7 +64,7 @@ ModifierCombination(LCtrl|RGui)           81
 MorseProfile(Normal,200,150)              c8 81 b0 89 0c
 Morse{TAP->Key(A)}                        00 01 02 01 00 04
 MouseButtons(B1|B8)                       81
-ProtocolVersion::CURRENT                  00 01
+ProtocolVersion::CURRENT                  00 02
 ProtocolVersion{1,0}                      01 00
 Result<(),RynkError>::Err(StorageFault)   01 02
 Result<(),RynkError>::Ok                  00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index e532712b9..74e28e11b 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -939,6 +939,430 @@ fn wire_frames_locked() {
     snapshot::assert_snapshot("snapshots/wire_frames.snap", actual);
 }
 
+/// Lighting has its own feature-gated golden file so the base Rynk snapshots
+/// remain identical for firmware builds that do not include lighting.
+#[cfg(feature = "lighting")]
+#[test]
+fn lighting_wire_frames_locked() {
+    const SEQ: u8 = 1;
+
+    fn one<T, const N: usize>(item: T) -> heapless::Vec<T, N> {
+        let mut items = heapless::Vec::new();
+        assert!(items.push(item).is_ok());
+        items
+    }
+
+    let matrix = LightingMatrixPosition { row: 1, col: 2 };
+    let point = LightingPoint3 { x: -128, y: 256, z: 64 };
+    let physical_key = LightingPhysicalKey {
+        matrix,
+        center: point,
+        size: LightingKeySize {
+            width: 256,
+            height: 384,
+        },
+        rotation: -750,
+    };
+    let led = LightingLed {
+        id: LightingLedId(42),
+        key: Some(matrix),
+        position: Some(point),
+        zone_start: 3,
+        zone_len: 1,
+    };
+    let zone = LightingZone {
+        id: LightingZoneId(4),
+        name: heapless::String::try_from("thumb").unwrap(),
+    };
+    let output = LightingOutput {
+        node: LightingNodeId(1),
+        id: LightingOutputId(2),
+        pixel_count: 40,
+        capabilities: LightingOutputCapabilities(
+            LightingOutputCapabilities::RGB | LightingOutputCapabilities::ADDRESSABLE,
+        ),
+        coverage: LightingOutputCoverage::Complete,
+    };
+    let route = LightingRoute {
+        led_id: led.id,
+        node: output.node,
+        output: output.id,
+        physical_index: 7,
+    };
+    let capabilities = LightingCapabilities {
+        topology_revision: 1,
+        logical_key_count: 2,
+        physical_key_count: 3,
+        led_count: 4,
+        zone_count: 5,
+        zone_membership_count: 6,
+        output_count: 7,
+        route_count: 8,
+        overlay_capacity: 9,
+        page_capacity: LIGHTING_PAGE_SIZE as u8,
+        overlay_chunk_capacity: LIGHTING_OVERLAY_CHUNK_SIZE as u8,
+        features: LightingFeatureFlags(
+            LightingFeatureFlags::PHYSICAL_GEOMETRY
+                | LightingFeatureFlags::ZONES
+                | LightingFeatureFlags::ROUTING
+                | LightingFeatureFlags::OVERLAY_TTL
+                | LightingFeatureFlags::ATOMIC_OVERLAY_REPLACE
+                | LightingFeatureFlags::LAYER_AWARE,
+        ),
+        effects: LightingEffectFlags(
+            LightingEffectFlags::SOLID | LightingEffectFlags::BLINK | LightingEffectFlags::BREATHE,
+        ),
+    };
+    let background = LightingBackgroundState {
+        enabled: true,
+        hue: 10,
+        saturation: 20,
+        value: 30,
+        speed: 40,
+        mode: LightingBackgroundMode::Breathe,
+    };
+    let state = LightingState {
+        revision: 9,
+        output_enabled: true,
+        output_brightness: 200,
+        background,
+        overlay_len: 1,
+    };
+    let mutable_state = LightingMutableState {
+        output_enabled: state.output_enabled,
+        output_brightness: state.output_brightness,
+        background,
+    };
+    let page_request = LightingPageRequest {
+        topology_revision: capabilities.topology_revision,
+        offset: 0,
+    };
+    let keys_page = LightingPhysicalKeysPage {
+        topology_revision: 1,
+        total_count: 1,
+        items: one(physical_key),
+    };
+    let logical_keys_page = LightingKeysPage {
+        topology_revision: 1,
+        total_count: 1,
+        items: one(matrix),
+    };
+    let leds_page = LightingLedsPage {
+        topology_revision: 1,
+        total_count: 1,
+        items: one(led),
+    };
+    let zones_page = LightingZonesPage {
+        topology_revision: 1,
+        total_count: 1,
+        items: one(zone),
+    };
+    let memberships_page = LightingZoneMembershipsPage {
+        topology_revision: 1,
+        total_count: 1,
+        items: one(LightingZoneId(4)),
+    };
+    let outputs_page = LightingOutputsPage {
+        topology_revision: 1,
+        total_count: 1,
+        items: one(output),
+    };
+    let routes_page = LightingRoutesPage {
+        topology_revision: 1,
+        total_count: 1,
+        items: one(route),
+    };
+    let overlay_cell = LightingOverlayCell {
+        led_id: led.id,
+        effect: LightingEffect::Blink {
+            color: LightingRgb8 { r: 1, g: 2, b: 3 },
+            period_ms: 1000,
+            phase_ms: 250,
+            duty: 50,
+        },
+        ttl_ms: Some(5000),
+    };
+    let set_state = SetLightingStateRequest {
+        expected_revision: 8,
+        state: mutable_state,
+    };
+    let set_overlay = SetLightingOverlayRequest {
+        expected_revision: 9,
+        cell: overlay_cell,
+    };
+    let unset_overlay = UnsetLightingOverlayRequest {
+        expected_revision: 10,
+        led_id: led.id,
+    };
+    let clear_overlay = ClearLightingOverlayRequest { expected_revision: 11 };
+    let begin = BeginLightingOverlayReplaceRequest {
+        expected_revision: 12,
+        cell_count: 1,
+    };
+    let transaction = LightingOverlayTransaction { id: 13, cell_count: 1 };
+    let put = PutLightingOverlayChunkRequest {
+        transaction_id: transaction.id,
+        offset: 0,
+        cells: one(overlay_cell),
+    };
+    let commit = CommitLightingOverlayReplaceRequest {
+        transaction_id: transaction.id,
+    };
+    let abort = AbortLightingOverlayReplaceRequest {
+        transaction_id: transaction.id,
+    };
+
+    let entries: alloc::vec::Vec<(&str, alloc::vec::Vec<u8>)> = alloc::vec![
+        (
+            "GetLightingCapabilities request",
+            encode_frame(Cmd::GetLightingCapabilities, SEQ, &())
+        ),
+        (
+            "GetLightingCapabilities reply",
+            encode_frame(
+                Cmd::GetLightingCapabilities,
+                SEQ,
+                &Ok::<LightingCapabilitiesResult, RynkError>(Ok(capabilities))
+            )
+        ),
+        (
+            "GetLightingState request",
+            encode_frame(Cmd::GetLightingState, SEQ, &())
+        ),
+        (
+            "GetLightingState reply",
+            encode_frame(
+                Cmd::GetLightingState,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "SetLightingState request",
+            encode_frame(Cmd::SetLightingState, SEQ, &set_state)
+        ),
+        (
+            "SetLightingState reply",
+            encode_frame(
+                Cmd::SetLightingState,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "GetLightingPhysicalKeys request",
+            encode_frame(Cmd::GetLightingPhysicalKeys, SEQ, &page_request)
+        ),
+        (
+            "GetLightingPhysicalKeys reply",
+            encode_frame(
+                Cmd::GetLightingPhysicalKeys,
+                SEQ,
+                &Ok::<LightingPhysicalKeysPageResult, RynkError>(Ok(keys_page))
+            )
+        ),
+        (
+            "GetLightingKeys request",
+            encode_frame(Cmd::GetLightingKeys, SEQ, &page_request)
+        ),
+        (
+            "GetLightingKeys reply",
+            encode_frame(
+                Cmd::GetLightingKeys,
+                SEQ,
+                &Ok::<LightingKeysPageResult, RynkError>(Ok(logical_keys_page))
+            )
+        ),
+        (
+            "GetLightingLeds request",
+            encode_frame(Cmd::GetLightingLeds, SEQ, &page_request)
+        ),
+        (
+            "GetLightingLeds reply",
+            encode_frame(
+                Cmd::GetLightingLeds,
+                SEQ,
+                &Ok::<LightingLedsPageResult, RynkError>(Ok(leds_page))
+            )
+        ),
+        (
+            "GetLightingZones request",
+            encode_frame(Cmd::GetLightingZones, SEQ, &page_request)
+        ),
+        (
+            "GetLightingZones reply",
+            encode_frame(
+                Cmd::GetLightingZones,
+                SEQ,
+                &Ok::<LightingZonesPageResult, RynkError>(Ok(zones_page))
+            )
+        ),
+        (
+            "GetLightingZoneMemberships request",
+            encode_frame(Cmd::GetLightingZoneMemberships, SEQ, &page_request)
+        ),
+        (
+            "GetLightingZoneMemberships reply",
+            encode_frame(
+                Cmd::GetLightingZoneMemberships,
+                SEQ,
+                &Ok::<LightingZoneMembershipsPageResult, RynkError>(Ok(memberships_page))
+            )
+        ),
+        (
+            "GetLightingOutputs request",
+            encode_frame(Cmd::GetLightingOutputs, SEQ, &page_request)
+        ),
+        (
+            "GetLightingOutputs reply",
+            encode_frame(
+                Cmd::GetLightingOutputs,
+                SEQ,
+                &Ok::<LightingOutputsPageResult, RynkError>(Ok(outputs_page))
+            )
+        ),
+        (
+            "GetLightingRoutes request",
+            encode_frame(Cmd::GetLightingRoutes, SEQ, &page_request)
+        ),
+        (
+            "GetLightingRoutes reply",
+            encode_frame(
+                Cmd::GetLightingRoutes,
+                SEQ,
+                &Ok::<LightingRoutesPageResult, RynkError>(Ok(routes_page))
+            )
+        ),
+        (
+            "SetLightingOverlay request",
+            encode_frame(Cmd::SetLightingOverlay, SEQ, &set_overlay)
+        ),
+        (
+            "SetLightingOverlay reply",
+            encode_frame(
+                Cmd::SetLightingOverlay,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "UnsetLightingOverlay request",
+            encode_frame(Cmd::UnsetLightingOverlay, SEQ, &unset_overlay)
+        ),
+        (
+            "UnsetLightingOverlay reply",
+            encode_frame(
+                Cmd::UnsetLightingOverlay,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "ClearLightingOverlay request",
+            encode_frame(Cmd::ClearLightingOverlay, SEQ, &clear_overlay)
+        ),
+        (
+            "ClearLightingOverlay reply",
+            encode_frame(
+                Cmd::ClearLightingOverlay,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "BeginLightingOverlayReplace request",
+            encode_frame(Cmd::BeginLightingOverlayReplace, SEQ, &begin)
+        ),
+        (
+            "BeginLightingOverlayReplace reply",
+            encode_frame(
+                Cmd::BeginLightingOverlayReplace,
+                SEQ,
+                &Ok::<LightingOverlayTransactionResult, RynkError>(Ok(transaction))
+            )
+        ),
+        (
+            "PutLightingOverlayChunk request",
+            encode_frame(Cmd::PutLightingOverlayChunk, SEQ, &put)
+        ),
+        (
+            "PutLightingOverlayChunk reply",
+            encode_frame(
+                Cmd::PutLightingOverlayChunk,
+                SEQ,
+                &Ok::<LightingUnitResult, RynkError>(Ok(()))
+            )
+        ),
+        (
+            "CommitLightingOverlayReplace request",
+            encode_frame(Cmd::CommitLightingOverlayReplace, SEQ, &commit)
+        ),
+        (
+            "CommitLightingOverlayReplace reply",
+            encode_frame(
+                Cmd::CommitLightingOverlayReplace,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "AbortLightingOverlayReplace request",
+            encode_frame(Cmd::AbortLightingOverlayReplace, SEQ, &abort)
+        ),
+        (
+            "AbortLightingOverlayReplace reply",
+            encode_frame(
+                Cmd::AbortLightingOverlayReplace,
+                SEQ,
+                &Ok::<LightingUnitResult, RynkError>(Ok(()))
+            )
+        ),
+        (
+            "SetLightingOverlay inner Err(UnknownLed)",
+            encode_frame(
+                Cmd::SetLightingOverlay,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Err(LightingError::UnknownLed {
+                    led_id: LightingLedId(999)
+                }))
+            )
+        ),
+        (
+            "SetLightingOverlay outer Err(Locked)",
+            encode_frame(
+                Cmd::SetLightingOverlay,
+                SEQ,
+                &Err::<LightingStateResult, RynkError>(RynkError::Locked)
+            )
+        ),
+        (
+            "PutLightingOverlayChunk inner Err(TransactionExpired)",
+            encode_frame(
+                Cmd::PutLightingOverlayChunk,
+                SEQ,
+                &Ok::<LightingUnitResult, RynkError>(Err(LightingError::TransactionExpired))
+            )
+        ),
+        (
+            "LightingChange topic",
+            encode_frame(Cmd::LightingChange, 0, &LightingChanged)
+        ),
+    ];
+    let view: alloc::vec::Vec<(&str, &[u8])> = entries
+        .iter()
+        .map(|(label, bytes)| (*label, bytes.as_slice()))
+        .collect();
+    let actual = snapshot::format_value_snapshot(
+        "snapshots/lighting_wire_frames.snap",
+        "Lighting wire-format FRAME snapshot",
+        "# Each entry is one complete feature-gated lighting Rynk frame. The nested\n\
+         # Ok/Err exemplars pin the outer Rynk result and inner lighting result.",
+        "--features lighting lighting_wire_frames",
+        &view,
+    );
+    snapshot::assert_snapshot("snapshots/lighting_wire_frames.snap", actual);
+}
+
 /// The human-readable protocol reference under `docs/`, rendered from the
 /// `ENDPOINT_META`/`TOPIC_META` tables. Those tables are not feature-gated, so
 /// every feature set renders identical output; a diff fails CI (regenerate with
@@ -1078,6 +1502,7 @@ mod protocol_reference {
              ```\n\n\
              On the wire the whole frame is COBS-encoded and terminated by a single `0x00` delimiter, so the byte stream is self-synchronizing.\n\n\
              - **Requests** use CMD `0x0000..=0x7FFF`. The response echoes CMD and SEQ and wraps its payload in postcard `Result<T, RynkError>` (`T = ()` for `Set*`).\n\
+             - **Lighting responses** use a `Lighting*Result` as `T`, preserving domain-specific `LightingError` detail inside the outer Rynk result.\n\
              - **Topics** use CMD `0x8000..=0xFFFF` (server → host push, SEQ `0`, bare payload).\n\n\
              Which commands a firmware answers depends on the RMK Cargo features it was built with: a row with no **Feature** is present once `rynk` is on, and the rest need their feature (`_ble`, `split`, …) compiled in. A command the firmware wasn't built with answers `UnknownCmd`.\n\n\
              ## Endpoints\n\n\
diff --git a/rmk/src/host/mod.rs b/rmk/src/host/mod.rs
index 568cbc5ab..167d5ab7a 100644
--- a/rmk/src/host/mod.rs
+++ b/rmk/src/host/mod.rs
@@ -23,5 +23,10 @@ pub(crate) mod via;
 /// two are mutually exclusive).
 #[cfg(feature = "rynk")]
 pub use rynk::RynkService as HostService;
+#[cfg(all(feature = "rynk", feature = "lighting"))]
+pub use rynk::{
+    RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
+    StandardRynkLightingAdapter,
+};
 #[cfg(feature = "vial")]
 pub use via::VialService as HostService;
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
new file mode 100644
index 000000000..9e94f241a
--- /dev/null
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -0,0 +1,1100 @@
+//! Native Rynk lighting handlers and bounded replacement transactions.
+
+use embassy_time::Instant;
+use heapless::{String, Vec};
+use rmk_types::protocol::rynk::command::{
+    ClearLightingOverlay, GetLightingCapabilities, GetLightingKeys, GetLightingLeds, GetLightingOutputs,
+    GetLightingPhysicalKeys, GetLightingRoutes, GetLightingState, GetLightingZoneMemberships, GetLightingZones,
+    SetLightingOverlay, SetLightingState, UnsetLightingOverlay,
+};
+use rmk_types::protocol::rynk::{
+    AbortLightingOverlayReplaceRequest, BeginLightingOverlayReplaceRequest, ClearLightingOverlayRequest,
+    CommitLightingOverlayReplaceRequest, LIGHTING_PAGE_SIZE, LIGHTING_ZONE_NAME_SIZE, LightingCapabilities,
+    LightingCapabilitiesResult, LightingEffectFlags, LightingError, LightingFeatureFlags, LightingKeysPage,
+    LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
+    LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage, LightingOutputsPage,
+    LightingOutputsPageResult, LightingOverlayCell, LightingOverlayTransaction, LightingOverlayTransactionResult,
+    LightingPageRequest, LightingPhysicalKey, LightingPhysicalKeysPage, LightingPhysicalKeysPageResult, LightingPoint3,
+    LightingResult, LightingRoute, LightingRoutesPage, LightingRoutesPageResult, LightingState, LightingStateResult,
+    LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage, LightingZoneMembershipsPageResult,
+    LightingZonesPage, LightingZonesPageResult, PutLightingOverlayChunkRequest, RynkError, RynkMessage,
+    SetLightingOverlayRequest, SetLightingStateRequest, UnsetLightingOverlayRequest,
+};
+
+use super::super::lighting::{RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingCommand, RynkLightingController};
+use super::super::{RynkService, RynkSession};
+use super::Handle;
+use crate::lighting::OutputCoverage;
+
+const TRANSACTION_TIMEOUT_MS: u64 = 5_000;
+
+fn controller<'a>(service: &RynkService<'a>) -> LightingResult<RynkLightingController<'a>> {
+    service.lighting.ok_or(LightingError::Unsupported)
+}
+
+impl Handle<GetLightingCapabilities> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LightingCapabilitiesResult, RynkError> {
+        Ok(controller(self).map(capabilities))
+    }
+}
+
+impl Handle<GetLightingState> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LightingStateResult, RynkError> {
+        Ok(match controller(self) {
+            Ok(controller) => controller.request(RynkLightingCommand::ReadState).await,
+            Err(error) => Err(error),
+        })
+    }
+}
+
+impl Handle<SetLightingState> for RynkService<'_> {
+    async fn handle(&self, req: SetLightingStateRequest) -> Result<LightingStateResult, RynkError> {
+        let result = match controller(self) {
+            Ok(controller) => {
+                controller
+                    .request(RynkLightingCommand::SetState {
+                        expected_revision: req.expected_revision,
+                        state: req.state,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<SetLightingOverlay> for RynkService<'_> {
+    async fn handle(&self, req: SetLightingOverlayRequest) -> Result<LightingStateResult, RynkError> {
+        if let Err(error) = req.cell.validate() {
+            return Ok(Err(error));
+        }
+        let result = match controller(self) {
+            Ok(controller) => {
+                controller
+                    .request(RynkLightingCommand::SetOverlay {
+                        expected_revision: req.expected_revision,
+                        cell: req.cell,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<UnsetLightingOverlay> for RynkService<'_> {
+    async fn handle(&self, req: UnsetLightingOverlayRequest) -> Result<LightingStateResult, RynkError> {
+        let result = match controller(self) {
+            Ok(controller) => {
+                controller
+                    .request(RynkLightingCommand::UnsetOverlay {
+                        expected_revision: req.expected_revision,
+                        led_id: req.led_id,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<ClearLightingOverlay> for RynkService<'_> {
+    async fn handle(&self, req: ClearLightingOverlayRequest) -> Result<LightingStateResult, RynkError> {
+        let result = match controller(self) {
+            Ok(controller) => {
+                controller
+                    .request(RynkLightingCommand::ClearOverlay {
+                        expected_revision: req.expected_revision,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<GetLightingKeys> for RynkService<'_> {
+    async fn handle(&self, req: LightingPageRequest) -> Result<LightingKeysPageResult, RynkError> {
+        Ok(controller(self).and_then(|binding| keys_page(binding, req)))
+    }
+}
+
+impl Handle<GetLightingPhysicalKeys> for RynkService<'_> {
+    async fn handle(&self, req: LightingPageRequest) -> Result<LightingPhysicalKeysPageResult, RynkError> {
+        Ok(controller(self).and_then(|binding| physical_keys_page(binding, req)))
+    }
+}
+
+impl Handle<GetLightingLeds> for RynkService<'_> {
+    async fn handle(&self, req: LightingPageRequest) -> Result<LightingLedsPageResult, RynkError> {
+        Ok(controller(self).and_then(|binding| leds_page(binding, req)))
+    }
+}
+
+impl Handle<GetLightingZones> for RynkService<'_> {
+    async fn handle(&self, req: LightingPageRequest) -> Result<LightingZonesPageResult, RynkError> {
+        Ok(controller(self).and_then(|binding| zones_page(binding, req)))
+    }
+}
+
+impl Handle<GetLightingZoneMemberships> for RynkService<'_> {
+    async fn handle(&self, req: LightingPageRequest) -> Result<LightingZoneMembershipsPageResult, RynkError> {
+        Ok(controller(self).and_then(|binding| zone_memberships_page(binding, req)))
+    }
+}
+
+impl Handle<GetLightingOutputs> for RynkService<'_> {
+    async fn handle(&self, req: LightingPageRequest) -> Result<LightingOutputsPageResult, RynkError> {
+        Ok(controller(self).and_then(|binding| outputs_page(binding, req)))
+    }
+}
+
+impl Handle<GetLightingRoutes> for RynkService<'_> {
+    async fn handle(&self, req: LightingPageRequest) -> Result<LightingRoutesPageResult, RynkError> {
+        Ok(controller(self).and_then(|binding| routes_page(binding, req)))
+    }
+}
+
+fn capabilities(binding: RynkLightingController<'_>) -> LightingCapabilities {
+    let descriptor = binding.descriptor;
+    let topology = descriptor.topology;
+    let routing = descriptor.routing;
+    let mut features = LightingFeatureFlags(
+        LightingFeatureFlags::OVERLAY_TTL
+            | LightingFeatureFlags::ATOMIC_OVERLAY_REPLACE
+            | LightingFeatureFlags::LAYER_AWARE,
+    );
+    if !topology.physical_layout.keys.is_empty() {
+        features.0 |= LightingFeatureFlags::PHYSICAL_GEOMETRY;
+    }
+    if !topology.zones.is_empty() {
+        features.0 |= LightingFeatureFlags::ZONES;
+    }
+    if !routing.routes.is_empty() || !routing.outputs.is_empty() {
+        features.0 |= LightingFeatureFlags::ROUTING;
+    }
+    LightingCapabilities {
+        topology_revision: descriptor.topology_revision,
+        logical_key_count: count(topology.keys.len()),
+        physical_key_count: count(topology.physical_layout.keys.len()),
+        led_count: count(topology.leds.len()),
+        zone_count: count(topology.zones.len()),
+        zone_membership_count: count(topology.zone_memberships.len()),
+        output_count: count(routing.outputs.len()),
+        route_count: count(routing.routes.len()),
+        overlay_capacity: binding.overlay_capacity,
+        page_capacity: LIGHTING_PAGE_SIZE as u8,
+        overlay_chunk_capacity: rmk_types::protocol::rynk::LIGHTING_OVERLAY_CHUNK_SIZE as u8,
+        features,
+        effects: LightingEffectFlags(
+            LightingEffectFlags::SOLID | LightingEffectFlags::BLINK | LightingEffectFlags::BREATHE,
+        ),
+    }
+}
+
+fn count(len: usize) -> u16 {
+    len.min(u16::MAX as usize) as u16
+}
+
+fn check_topology_revision(binding: RynkLightingController<'_>, expected: u32) -> LightingResult<()> {
+    let current = binding.descriptor.topology_revision;
+    if expected == current {
+        Ok(())
+    } else {
+        Err(LightingError::TopologyRevisionConflict { expected, current })
+    }
+}
+
+fn page_range(offset: u16, total: usize) -> core::ops::Range<usize> {
+    let start = (offset as usize).min(total);
+    start..(start + LIGHTING_PAGE_SIZE).min(total)
+}
+
+fn matrix(position: crate::physical_layout::KeyPosition) -> LightingMatrixPosition {
+    LightingMatrixPosition {
+        row: position.row,
+        col: position.col,
+    }
+}
+
+fn point(point: crate::physical_layout::Point3) -> LightingPoint3 {
+    LightingPoint3 {
+        x: point.x.raw(),
+        y: point.y.raw(),
+        z: point.z.raw(),
+    }
+}
+
+fn keys_page(binding: RynkLightingController<'_>, req: LightingPageRequest) -> LightingResult<LightingKeysPage> {
+    check_topology_revision(binding, req.topology_revision)?;
+    let values = binding.descriptor.topology.keys;
+    let mut items = Vec::new();
+    for value in &values[page_range(req.offset, values.len())] {
+        items.push(matrix(*value)).expect("page is bounded");
+    }
+    Ok(LightingKeysPage {
+        topology_revision: req.topology_revision,
+        total_count: count(values.len()),
+        items,
+    })
+}
+
+fn physical_keys_page(
+    binding: RynkLightingController<'_>,
+    req: LightingPageRequest,
+) -> LightingResult<LightingPhysicalKeysPage> {
+    check_topology_revision(binding, req.topology_revision)?;
+    let values = binding.descriptor.topology.physical_layout.keys;
+    let mut items = Vec::new();
+    for value in &values[page_range(req.offset, values.len())] {
+        items
+            .push(LightingPhysicalKey {
+                matrix: matrix(value.matrix),
+                center: point(value.center),
+                size: rmk_types::protocol::rynk::LightingKeySize {
+                    width: value.size.width.raw(),
+                    height: value.size.height.raw(),
+                },
+                rotation: value.rotation.centidegrees(),
+            })
+            .expect("page is bounded");
+    }
+    Ok(LightingPhysicalKeysPage {
+        topology_revision: req.topology_revision,
+        total_count: count(values.len()),
+        items,
+    })
+}
+
+fn leds_page(binding: RynkLightingController<'_>, req: LightingPageRequest) -> LightingResult<LightingLedsPage> {
+    check_topology_revision(binding, req.topology_revision)?;
+    let values = binding.descriptor.topology.leds;
+    let mut items = Vec::new();
+    for value in &values[page_range(req.offset, values.len())] {
+        items
+            .push(LightingLed {
+                id: LightingLedId(value.id.0),
+                key: value.key.map(matrix),
+                position: value.position.map(point),
+                zone_start: value.zones.start,
+                zone_len: value.zones.len,
+            })
+            .expect("page is bounded");
+    }
+    Ok(LightingLedsPage {
+        topology_revision: req.topology_revision,
+        total_count: count(values.len()),
+        items,
+    })
+}
+
+fn zones_page(binding: RynkLightingController<'_>, req: LightingPageRequest) -> LightingResult<LightingZonesPage> {
+    check_topology_revision(binding, req.topology_revision)?;
+    let values = binding.descriptor.topology.zones;
+    let mut items = Vec::new();
+    for value in &values[page_range(req.offset, values.len())] {
+        let mut name = String::<LIGHTING_ZONE_NAME_SIZE>::new();
+        for character in value.name.chars() {
+            if name.push(character).is_err() {
+                break;
+            }
+        }
+        items
+            .push(LightingZone {
+                id: LightingZoneId(value.id.0),
+                name,
+            })
+            .expect("page is bounded");
+    }
+    Ok(LightingZonesPage {
+        topology_revision: req.topology_revision,
+        total_count: count(values.len()),
+        items,
+    })
+}
+
+fn zone_memberships_page(
+    binding: RynkLightingController<'_>,
+    req: LightingPageRequest,
+) -> LightingResult<LightingZoneMembershipsPage> {
+    check_topology_revision(binding, req.topology_revision)?;
+    let values = binding.descriptor.topology.zone_memberships;
+    let mut items = Vec::new();
+    for value in &values[page_range(req.offset, values.len())] {
+        items.push(LightingZoneId(value.0)).expect("page is bounded");
+    }
+    Ok(LightingZoneMembershipsPage {
+        topology_revision: req.topology_revision,
+        total_count: count(values.len()),
+        items,
+    })
+}
+
+fn outputs_page(binding: RynkLightingController<'_>, req: LightingPageRequest) -> LightingResult<LightingOutputsPage> {
+    check_topology_revision(binding, req.topology_revision)?;
+    let values = binding.descriptor.routing.outputs;
+    let mut items = Vec::new();
+    for value in &values[page_range(req.offset, values.len())] {
+        items
+            .push(LightingOutput {
+                node: rmk_types::protocol::rynk::LightingNodeId(value.node.0),
+                id: rmk_types::protocol::rynk::LightingOutputId(value.id.0),
+                pixel_count: value.pixel_count,
+                capabilities: LightingOutputCapabilities(value.capabilities.bits()),
+                coverage: match value.coverage {
+                    OutputCoverage::Complete => LightingOutputCoverage::Complete,
+                    OutputCoverage::Sparse => LightingOutputCoverage::Sparse,
+                },
+            })
+            .expect("page is bounded");
+    }
+    Ok(LightingOutputsPage {
+        topology_revision: req.topology_revision,
+        total_count: count(values.len()),
+        items,
+    })
+}
+
+fn routes_page(binding: RynkLightingController<'_>, req: LightingPageRequest) -> LightingResult<LightingRoutesPage> {
+    check_topology_revision(binding, req.topology_revision)?;
+    let descriptor = binding.descriptor;
+    let values = descriptor.routing.routes;
+    let mut items = Vec::new();
+    for value in &values[page_range(req.offset, values.len())] {
+        let led = descriptor
+            .topology
+            .led(value.slot)
+            .ok_or(LightingError::InvalidRequest)?;
+        items
+            .push(LightingRoute {
+                led_id: LightingLedId(led.id.0),
+                node: rmk_types::protocol::rynk::LightingNodeId(value.node.0),
+                output: rmk_types::protocol::rynk::LightingOutputId(value.output.0),
+                physical_index: value.physical_index,
+            })
+            .expect("page is bounded");
+    }
+    Ok(LightingRoutesPage {
+        topology_revision: req.topology_revision,
+        total_count: count(values.len()),
+        items,
+    })
+}
+
+struct ActiveTransaction {
+    id: u32,
+    expected_revision: u32,
+    expected_count: u16,
+    cells: Vec<LightingOverlayCell, RYNK_LIGHTING_TRANSACTION_CAPACITY>,
+    last_activity_ms: u64,
+}
+
+#[derive(Clone, Copy)]
+struct CachedCommit {
+    id: u32,
+    state: LightingState,
+}
+
+pub(in crate::host::rynk) struct LightingTransactionState {
+    next_id: u32,
+    active: Option<ActiveTransaction>,
+    cached_commit: Option<CachedCommit>,
+    expired_id: Option<u32>,
+}
+
+impl LightingTransactionState {
+    pub(in crate::host::rynk) const fn new() -> Self {
+        Self {
+            next_id: 1,
+            active: None,
+            cached_commit: None,
+            expired_id: None,
+        }
+    }
+
+    fn expire(&mut self, now_ms: u64) {
+        if self
+            .active
+            .as_ref()
+            .is_some_and(|transaction| now_ms.saturating_sub(transaction.last_activity_ms) >= TRANSACTION_TIMEOUT_MS)
+        {
+            self.expired_id = self.active.as_ref().map(|transaction| transaction.id);
+            self.active = None;
+        }
+    }
+
+    fn transaction_error(&self, id: u32) -> LightingError {
+        if self.expired_id == Some(id) {
+            LightingError::TransactionExpired
+        } else {
+            LightingError::InvalidTransaction
+        }
+    }
+}
+
+pub(in crate::host::rynk) async fn serve_begin(
+    service: &RynkService<'_>,
+    session: &RynkSession,
+    msg: &mut RynkMessage<'_>,
+) -> Result<(), RynkError> {
+    let req = msg.decode_request::<BeginLightingOverlayReplaceRequest>()?;
+    let result = begin(service, session, req, Instant::now().as_millis()).await;
+    msg.encode_response(&result)
+}
+
+async fn begin(
+    service: &RynkService<'_>,
+    session: &RynkSession,
+    req: BeginLightingOverlayReplaceRequest,
+    now_ms: u64,
+) -> LightingOverlayTransactionResult {
+    let binding = controller(service)?;
+    let capacity = binding.overlay_capacity.min(RYNK_LIGHTING_TRANSACTION_CAPACITY as u16);
+    if req.cell_count > capacity {
+        return Err(LightingError::OverlayFull { capacity });
+    }
+    let mut state = session.lighting.lock().await;
+    state.expire(now_ms);
+    if state.active.is_some() {
+        return Err(LightingError::TransactionBusy);
+    }
+    let id = state.next_id;
+    state.next_id = state.next_id.wrapping_add(1).max(1);
+    state.expired_id = None;
+    state.active = Some(ActiveTransaction {
+        id,
+        expected_revision: req.expected_revision,
+        expected_count: req.cell_count,
+        cells: Vec::new(),
+        last_activity_ms: now_ms,
+    });
+    Ok(LightingOverlayTransaction {
+        id,
+        cell_count: req.cell_count,
+    })
+}
+
+pub(in crate::host::rynk) async fn serve_put(
+    service: &RynkService<'_>,
+    session: &RynkSession,
+    msg: &mut RynkMessage<'_>,
+) -> Result<(), RynkError> {
+    let req = msg.decode_request::<PutLightingOverlayChunkRequest>()?;
+    let result = put(service, session, req, Instant::now().as_millis()).await;
+    msg.encode_response(&result)
+}
+
+async fn put(
+    service: &RynkService<'_>,
+    session: &RynkSession,
+    req: PutLightingOverlayChunkRequest,
+    now_ms: u64,
+) -> LightingUnitResult {
+    controller(service)?;
+    for cell in &req.cells {
+        cell.validate()?;
+    }
+    let mut state = session.lighting.lock().await;
+    state.expire(now_ms);
+    let error = state.transaction_error(req.transaction_id);
+    let transaction = state
+        .active
+        .as_mut()
+        .filter(|transaction| transaction.id == req.transaction_id)
+        .ok_or(error)?;
+    if req.offset as usize != transaction.cells.len()
+        || transaction.cells.len() + req.cells.len() > transaction.expected_count as usize
+    {
+        return Err(LightingError::InvalidRequest);
+    }
+    transaction
+        .cells
+        .extend_from_slice(&req.cells)
+        .map_err(|_| LightingError::OverlayFull {
+            capacity: RYNK_LIGHTING_TRANSACTION_CAPACITY as u16,
+        })?;
+    transaction.last_activity_ms = now_ms;
+    Ok(())
+}
+
+pub(in crate::host::rynk) async fn serve_commit(
+    service: &RynkService<'_>,
+    session: &RynkSession,
+    msg: &mut RynkMessage<'_>,
+) -> Result<(), RynkError> {
+    let req = msg.decode_request::<CommitLightingOverlayReplaceRequest>()?;
+    let result = commit(service, session, req, Instant::now().as_millis()).await;
+    msg.encode_response(&result)
+}
+
+async fn commit(
+    service: &RynkService<'_>,
+    session: &RynkSession,
+    req: CommitLightingOverlayReplaceRequest,
+    now_ms: u64,
+) -> LightingStateResult {
+    let binding = controller(service)?;
+    let (expected_revision, cells) = {
+        let mut state = session.lighting.lock().await;
+        state.expire(now_ms);
+        if let Some(cached) = state.cached_commit.filter(|cached| cached.id == req.transaction_id) {
+            return Ok(cached.state);
+        }
+        let error = state.transaction_error(req.transaction_id);
+        let transaction = state
+            .active
+            .as_ref()
+            .filter(|transaction| transaction.id == req.transaction_id)
+            .ok_or(error)?;
+        if transaction.cells.len() != transaction.expected_count as usize {
+            return Err(LightingError::TransactionIncomplete {
+                expected: transaction.expected_count,
+                received: transaction.cells.len() as u16,
+            });
+        }
+        (transaction.expected_revision, transaction.cells.clone())
+    };
+
+    let result = binding.replace_overlay(expected_revision, &cells).await;
+    if let Ok(state_value) = result {
+        let mut state = session.lighting.lock().await;
+        if state
+            .active
+            .as_ref()
+            .is_some_and(|active| active.id == req.transaction_id)
+        {
+            state.active = None;
+            state.cached_commit = Some(CachedCommit {
+                id: req.transaction_id,
+                state: state_value,
+            });
+            state.expired_id = None;
+        }
+    }
+    result
+}
+
+pub(in crate::host::rynk) async fn serve_abort(
+    service: &RynkService<'_>,
+    session: &RynkSession,
+    msg: &mut RynkMessage<'_>,
+) -> Result<(), RynkError> {
+    let req = msg.decode_request::<AbortLightingOverlayReplaceRequest>()?;
+    let result = abort(service, session, req, Instant::now().as_millis()).await;
+    msg.encode_response(&result)
+}
+
+async fn abort(
+    service: &RynkService<'_>,
+    session: &RynkSession,
+    req: AbortLightingOverlayReplaceRequest,
+    now_ms: u64,
+) -> LightingUnitResult {
+    controller(service)?;
+    let mut state = session.lighting.lock().await;
+    state.expire(now_ms);
+    if state
+        .active
+        .as_ref()
+        .is_some_and(|active| active.id == req.transaction_id)
+    {
+        state.active = None;
+        return Ok(());
+    }
+    Err(state.transaction_error(req.transaction_id))
+}
+
+#[cfg(test)]
+mod tests {
+    extern crate alloc;
+
+    use alloc::boxed::Box;
+    use core::fmt::Debug;
+
+    use embassy_futures::join::join;
+    use rmk_types::action::KeyAction;
+    use rmk_types::protocol::rynk::command::{
+        BeginLightingOverlayReplace, CommitLightingOverlayReplace, GetCapabilities, GetLightingKeys, SetLightingState,
+    };
+    use rmk_types::protocol::rynk::endpoint::Endpoint;
+    use serde::Serialize;
+    use serde::de::DeserializeOwned;
+
+    use super::*;
+    use crate::config::{BehaviorConfig, PositionalConfig, RmkConfig};
+    use crate::host::RynkLightingMailbox;
+    use crate::keymap::{KeyMap, KeymapData};
+    use crate::lighting::{
+        LedId, LedMetadata, LightingNodeId as CoreNodeId, LightingRouting, LightingTopology, MatrixSize, OutputId,
+        OutputMetadata, PhysicalRoute, ZoneSpan,
+    };
+    use crate::physical_layout::{
+        Coordinate, Extent, KeyPosition, KeySize, PhysicalKey, PhysicalLayout, Point3, Rotation,
+    };
+    use crate::test_support::test_block_on as block_on;
+
+    static LOGICAL_KEYS: [KeyPosition; 2] = [KeyPosition::new(0, 0), KeyPosition::new(0, 2)];
+    static PHYSICAL_KEYS: [PhysicalKey; 1] = [PhysicalKey {
+        matrix: KeyPosition::new(0, 0),
+        center: Point3::new(Coordinate::ZERO, Coordinate::ONE, Coordinate::ZERO),
+        size: KeySize::new(Extent::ONE, Extent::ONE),
+        rotation: Rotation::ZERO,
+    }];
+    static LEDS: [LedMetadata; 2] = [
+        LedMetadata {
+            id: LedId(10),
+            key: Some(KeyPosition::new(0, 0)),
+            position: None,
+            zones: ZoneSpan::new(0, 0),
+        },
+        LedMetadata {
+            id: LedId(42),
+            key: None,
+            position: Some(Point3::new(Coordinate::ONE, Coordinate::ZERO, Coordinate::ZERO)),
+            zones: ZoneSpan::new(0, 0),
+        },
+    ];
+    static OUTPUTS: [OutputMetadata; 1] = [OutputMetadata {
+        node: CoreNodeId(0),
+        id: OutputId(0),
+        pixel_count: 2,
+        capabilities: crate::lighting::OutputCapabilities::RGB,
+        coverage: OutputCoverage::Complete,
+    }];
+    static ROUTES: [PhysicalRoute; 2] = [
+        PhysicalRoute {
+            slot: crate::lighting::LedSlot(1),
+            node: CoreNodeId(0),
+            output: OutputId(0),
+            physical_index: 0,
+        },
+        PhysicalRoute {
+            slot: crate::lighting::LedSlot(0),
+            node: CoreNodeId(0),
+            output: OutputId(0),
+            physical_index: 1,
+        },
+    ];
+
+    fn descriptor() -> super::super::super::lighting::RynkLightingDescriptor<'static> {
+        super::super::super::lighting::RynkLightingDescriptor {
+            topology_revision: 7,
+            topology: LightingTopology {
+                matrix: MatrixSize::new(1, 3),
+                keys: &LOGICAL_KEYS,
+                physical_layout: PhysicalLayout::new(&PHYSICAL_KEYS),
+                leds: &LEDS,
+                zones: &[],
+                zone_memberships: &[],
+            },
+            routing: LightingRouting {
+                outputs: &OUTPUTS,
+                routes: &ROUTES,
+            },
+        }
+    }
+
+    fn state(revision: u32, overlay_len: u16) -> LightingState {
+        LightingState {
+            revision,
+            output_enabled: true,
+            output_brightness: 200,
+            background: rmk_types::protocol::rynk::LightingBackgroundState {
+                enabled: true,
+                hue: 1,
+                saturation: 2,
+                value: 3,
+                speed: 4,
+                mode: rmk_types::protocol::rynk::LightingBackgroundMode::Solid,
+            },
+            overlay_len,
+        }
+    }
+
+    fn session() -> RynkSession {
+        RynkSession {
+            lighting: embassy_sync::mutex::Mutex::new(LightingTransactionState::new()),
+        }
+    }
+
+    async fn call<E>(
+        service: &RynkService<'_>,
+        session: &RynkSession,
+        request: &E::Request,
+    ) -> Result<E::Response, RynkError>
+    where
+        E: Endpoint,
+        E::Request: Serialize,
+        E::Response: DeserializeOwned + Debug,
+    {
+        let mut buffer = Box::new([0u8; rmk_types::constants::RYNK_BUFFER_SIZE]);
+        let mut message = RynkMessage::build(&mut buffer[..], E::CMD, 1, request).unwrap();
+        service.dispatch(session, &mut message).await;
+        postcard::from_bytes(message.payload()).unwrap()
+    }
+
+    fn overlay_cell(id: u16) -> LightingOverlayCell {
+        LightingOverlayCell {
+            led_id: LightingLedId(id),
+            effect: rmk_types::protocol::rynk::LightingEffect::Solid {
+                color: rmk_types::protocol::rynk::LightingRgb8 { r: 1, g: 2, b: 3 },
+            },
+            ttl_ms: None,
+        }
+    }
+
+    #[test]
+    fn page_range_clamps_and_preserves_empty_final_page() {
+        assert_eq!(page_range(0, 20), 0..8);
+        assert_eq!(page_range(16, 20), 16..20);
+        assert_eq!(page_range(99, 20), 20..20);
+    }
+
+    #[test]
+    fn transaction_expiry_is_remembered() {
+        let mut state = LightingTransactionState::new();
+        state.active = Some(ActiveTransaction {
+            id: 7,
+            expected_revision: 0,
+            expected_count: 0,
+            cells: Vec::new(),
+            last_activity_ms: 10,
+        });
+        state.expire(10 + TRANSACTION_TIMEOUT_MS);
+        assert!(state.active.is_none());
+        assert_eq!(state.transaction_error(7), LightingError::TransactionExpired);
+        assert_eq!(state.transaction_error(8), LightingError::InvalidTransaction);
+    }
+
+    #[test]
+    fn discovery_is_false_unbound_and_true_only_when_attached() {
+        block_on(async {
+            let mut behavior = BehaviorConfig::default();
+            let positional: PositionalConfig<1, 3> = PositionalConfig::default();
+            let mut data: KeymapData<1, 3, 1, 0> = KeymapData::new([[[KeyAction::No; 3]]]);
+            let keymap = KeyMap::new(&mut data, &mut behavior, &positional).await;
+            let mut config = RmkConfig::default();
+            config.lock_config.insecure = true;
+            let unbound = RynkService::new(&keymap, &config);
+            let unbound_session = session();
+            let device_caps = call::<GetCapabilities>(&unbound, &unbound_session, &()).await.unwrap();
+            assert!(!device_caps.lighting_enabled);
+            drop(unbound_session);
+
+            let mailbox = RynkLightingMailbox::new();
+            let bound = RynkService::new(&keymap, &config).with_lighting(RynkLightingController::new(
+                &mailbox,
+                descriptor(),
+                128,
+            ));
+            let bound_session = session();
+            let device_caps = call::<GetCapabilities>(&bound, &bound_session, &()).await.unwrap();
+            assert!(device_caps.lighting_enabled);
+            let lighting = capabilities(bound.lighting.unwrap());
+            assert_eq!(lighting.overlay_capacity, RYNK_LIGHTING_TRANSACTION_CAPACITY as u16);
+            assert_eq!(lighting.logical_key_count, 2);
+            assert_eq!(lighting.physical_key_count, 1);
+        });
+    }
+
+    #[test]
+    fn topology_pages_are_revision_pinned_and_keep_keys_separate_from_geometry() {
+        block_on(async {
+            let mut behavior = BehaviorConfig::default();
+            let positional: PositionalConfig<1, 3> = PositionalConfig::default();
+            let mut data: KeymapData<1, 3, 1, 0> = KeymapData::new([[[KeyAction::No; 3]]]);
+            let keymap = KeyMap::new(&mut data, &mut behavior, &positional).await;
+            let mut config = RmkConfig::default();
+            config.lock_config.insecure = true;
+            let mailbox = RynkLightingMailbox::new();
+            let service = RynkService::new(&keymap, &config).with_lighting(RynkLightingController::new(
+                &mailbox,
+                descriptor(),
+                8,
+            ));
+            let session = session();
+
+            let stale = call::<GetLightingKeys>(
+                &service,
+                &session,
+                &LightingPageRequest {
+                    topology_revision: 6,
+                    offset: 0,
+                },
+            )
+            .await
+            .unwrap();
+            assert_eq!(
+                stale,
+                Err(LightingError::TopologyRevisionConflict {
+                    expected: 6,
+                    current: 7
+                })
+            );
+
+            let page = call::<GetLightingKeys>(
+                &service,
+                &session,
+                &LightingPageRequest {
+                    topology_revision: 7,
+                    offset: 0,
+                },
+            )
+            .await
+            .unwrap()
+            .unwrap();
+            assert_eq!(page.total_count, 2);
+            assert_eq!(page.items[1], LightingMatrixPosition { row: 0, col: 2 });
+            assert_eq!(descriptor().topology.physical_layout.keys.len(), 1);
+        });
+    }
+
+    #[test]
+    fn stale_mutation_is_a_nested_domain_error() {
+        block_on(async {
+            let mut behavior = BehaviorConfig::default();
+            let positional: PositionalConfig<1, 3> = PositionalConfig::default();
+            let mut data: KeymapData<1, 3, 1, 0> = KeymapData::new([[[KeyAction::No; 3]]]);
+            let keymap = KeyMap::new(&mut data, &mut behavior, &positional).await;
+            let mut config = RmkConfig::default();
+            config.lock_config.insecure = true;
+            let mailbox = RynkLightingMailbox::new();
+            let service = RynkService::new(&keymap, &config).with_lighting(RynkLightingController::new(
+                &mailbox,
+                descriptor(),
+                8,
+            ));
+            let session = session();
+            let request = SetLightingStateRequest {
+                expected_revision: 3,
+                state: rmk_types::protocol::rynk::LightingMutableState {
+                    output_enabled: false,
+                    output_brightness: 9,
+                    background: state(0, 0).background,
+                },
+            };
+            let (response, ()) = join(call::<SetLightingState>(&service, &session, &request), async {
+                let pending = mailbox.receive().await;
+                assert!(matches!(
+                    pending.command,
+                    RynkLightingCommand::SetState {
+                        expected_revision: 3,
+                        ..
+                    }
+                ));
+                mailbox.reply(
+                    pending.id,
+                    Err(LightingError::StateRevisionConflict {
+                        expected: 3,
+                        current: 4,
+                    }),
+                );
+            })
+            .await;
+            assert_eq!(
+                response.unwrap(),
+                Err(LightingError::StateRevisionConflict {
+                    expected: 3,
+                    current: 4
+                })
+            );
+        });
+    }
+
+    #[test]
+    fn replacement_enforces_order_completion_expiry_and_idempotent_commit() {
+        block_on(async {
+            let mut behavior = BehaviorConfig::default();
+            let positional: PositionalConfig<1, 3> = PositionalConfig::default();
+            let mut data: KeymapData<1, 3, 1, 0> = KeymapData::new([[[KeyAction::No; 3]]]);
+            let keymap = KeyMap::new(&mut data, &mut behavior, &positional).await;
+            let mut config = RmkConfig::default();
+            config.lock_config.insecure = true;
+            let mailbox = RynkLightingMailbox::new();
+            let service = RynkService::new(&keymap, &config).with_lighting(RynkLightingController::new(
+                &mailbox,
+                descriptor(),
+                8,
+            ));
+            let session = session();
+
+            let transaction = begin(
+                &service,
+                &session,
+                BeginLightingOverlayReplaceRequest {
+                    expected_revision: 5,
+                    cell_count: 2,
+                },
+                10,
+            )
+            .await
+            .unwrap();
+            let mut out_of_order = Vec::new();
+            out_of_order.push(overlay_cell(10)).unwrap();
+            assert_eq!(
+                put(
+                    &service,
+                    &session,
+                    PutLightingOverlayChunkRequest {
+                        transaction_id: transaction.id,
+                        offset: 1,
+                        cells: out_of_order,
+                    },
+                    11,
+                )
+                .await,
+                Err(LightingError::InvalidRequest)
+            );
+            assert_eq!(
+                commit(
+                    &service,
+                    &session,
+                    CommitLightingOverlayReplaceRequest {
+                        transaction_id: transaction.id,
+                    },
+                    12,
+                )
+                .await,
+                Err(LightingError::TransactionIncomplete {
+                    expected: 2,
+                    received: 0
+                })
+            );
+
+            let mut cells = Vec::new();
+            cells.push(overlay_cell(10)).unwrap();
+            cells.push(overlay_cell(42)).unwrap();
+            put(
+                &service,
+                &session,
+                PutLightingOverlayChunkRequest {
+                    transaction_id: transaction.id,
+                    offset: 0,
+                    cells,
+                },
+                13,
+            )
+            .await
+            .unwrap();
+            let committed = state(6, 2);
+            let (response, ()) = join(
+                commit(
+                    &service,
+                    &session,
+                    CommitLightingOverlayReplaceRequest {
+                        transaction_id: transaction.id,
+                    },
+                    14,
+                ),
+                async {
+                    let pending = mailbox.receive().await;
+                    let staged = mailbox.take_replacement(pending.id).await;
+                    match pending.command {
+                        RynkLightingCommand::ReplaceOverlay { expected_revision } => {
+                            assert_eq!(expected_revision, 5);
+                            assert_eq!(staged.len(), 2);
+                        }
+                        _ => panic!("expected replacement"),
+                    }
+                    mailbox.reply(pending.id, Ok(committed));
+                },
+            )
+            .await;
+            assert_eq!(response, Ok(committed));
+            assert_eq!(
+                commit(
+                    &service,
+                    &session,
+                    CommitLightingOverlayReplaceRequest {
+                        transaction_id: transaction.id,
+                    },
+                    15,
+                )
+                .await,
+                Ok(committed),
+                "repeated successful commit is served from the cache"
+            );
+
+            let expiring = begin(
+                &service,
+                &session,
+                BeginLightingOverlayReplaceRequest {
+                    expected_revision: 6,
+                    cell_count: 0,
+                },
+                20,
+            )
+            .await
+            .unwrap();
+            assert_eq!(
+                abort(
+                    &service,
+                    &session,
+                    AbortLightingOverlayReplaceRequest {
+                        transaction_id: expiring.id,
+                    },
+                    20 + TRANSACTION_TIMEOUT_MS,
+                )
+                .await,
+                Err(LightingError::TransactionExpired)
+            );
+        });
+    }
+
+    #[test]
+    fn zero_cell_replacement_commits_as_one_atomic_empty_batch() {
+        block_on(async {
+            let mut behavior = BehaviorConfig::default();
+            let positional: PositionalConfig<1, 3> = PositionalConfig::default();
+            let mut data: KeymapData<1, 3, 1, 0> = KeymapData::new([[[KeyAction::No; 3]]]);
+            let keymap = KeyMap::new(&mut data, &mut behavior, &positional).await;
+            let mut config = RmkConfig::default();
+            config.lock_config.insecure = true;
+            let mailbox = RynkLightingMailbox::new();
+            let service = RynkService::new(&keymap, &config).with_lighting(RynkLightingController::new(
+                &mailbox,
+                descriptor(),
+                8,
+            ));
+            let session = session();
+            let transaction = call::<BeginLightingOverlayReplace>(
+                &service,
+                &session,
+                &BeginLightingOverlayReplaceRequest {
+                    expected_revision: 9,
+                    cell_count: 0,
+                },
+            )
+            .await
+            .unwrap()
+            .unwrap();
+            let cleared = state(10, 0);
+            let (response, ()) = join(
+                call::<CommitLightingOverlayReplace>(
+                    &service,
+                    &session,
+                    &CommitLightingOverlayReplaceRequest {
+                        transaction_id: transaction.id,
+                    },
+                ),
+                async {
+                    let pending = mailbox.receive().await;
+                    let staged = mailbox.take_replacement(pending.id).await;
+                    assert!(matches!(
+                        pending.command,
+                        RynkLightingCommand::ReplaceOverlay {
+                            expected_revision: 9,
+                        } if staged.is_empty()
+                    ));
+                    mailbox.reply(pending.id, Ok(cleared));
+                },
+            )
+            .await;
+            assert_eq!(response.unwrap(), Ok(cleared));
+        });
+    }
+}
diff --git a/rmk/src/host/rynk/handlers/mod.rs b/rmk/src/host/rynk/handlers/mod.rs
index 2d1635fff..bd3d09129 100644
--- a/rmk/src/host/rynk/handlers/mod.rs
+++ b/rmk/src/host/rynk/handlers/mod.rs
@@ -10,6 +10,8 @@ mod connection;
 mod fork;
 mod keymap;
 mod layout;
+#[cfg(feature = "lighting")]
+pub(super) mod lighting;
 mod macro_data;
 mod morse;
 mod status;
diff --git a/rmk/src/host/rynk/handlers/system.rs b/rmk/src/host/rynk/handlers/system.rs
index 2ac280f1c..9859cfd6c 100644
--- a/rmk/src/host/rynk/handlers/system.rs
+++ b/rmk/src/host/rynk/handlers/system.rs
@@ -60,7 +60,10 @@ impl Handle<GetCapabilities> for RynkService<'_> {
 
             // Feature flags
             storage_enabled: cfg!(feature = "storage"),
-            lighting_enabled: false, // TODO Phase 6: surface light_service
+            #[cfg(feature = "lighting")]
+            lighting_enabled: self.lighting.is_some(),
+            #[cfg(not(feature = "lighting"))]
+            lighting_enabled: false,
 
             // Connectivity
             is_split: cfg!(feature = "split"),
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
new file mode 100644
index 000000000..6b2bd30db
--- /dev/null
+++ b/rmk/src/host/rynk/lighting.rs
@@ -0,0 +1,568 @@
+//! Type-erased Rynk lighting binding and standard-engine mailbox bridge.
+//!
+//! `RynkService` deliberately stays non-generic so existing USB/BLE/UART
+//! orchestration does not acquire lighting-engine type parameters. A small
+//! protocol mailbox erases those parameters; [`StandardRynkLightingAdapter`]
+//! is the only bridge from that mailbox to the standard engine's authoritative
+//! mailbox.
+
+use core::cell::{Cell, RefCell};
+use core::num::NonZeroU32;
+
+use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
+use embassy_sync::channel::Channel;
+use embassy_sync::mutex::Mutex;
+use embassy_sync::signal::Signal;
+use heapless::Vec;
+use rmk_types::protocol::rynk::{
+    LightingBackgroundMode, LightingBackgroundState, LightingError, LightingMutableState, LightingOverlayCell,
+    LightingResult, LightingRgb8, LightingState,
+};
+
+use crate::RawMutex;
+use crate::core_traits::Runnable;
+use crate::lighting::{
+    BackgroundMode, BackgroundState, BuiltinEffect, LedId, LightingMailbox, LightingRouting, LightingTopology,
+    OverlayBatch, OverlayCell, OverlayError, Rgb8, StandardCommand, StandardError, StandardMutableState, StandardState,
+};
+
+/// Maximum number of cells staged by one Rynk overlay replacement.
+///
+/// A concrete engine may advertise a smaller capacity. Keeping the protocol
+/// staging bound independent of the engine's const generic avoids making the
+/// host service and every transport generic.
+pub const RYNK_LIGHTING_TRANSACTION_CAPACITY: usize = 64;
+
+const RYNK_LIGHTING_COMMAND_CAPACITY: usize = 4;
+
+#[derive(Clone, Copy)]
+pub struct RynkLightingDescriptor<'a> {
+    pub topology_revision: u32,
+    pub topology: LightingTopology<'a>,
+    pub routing: LightingRouting<'a>,
+}
+
+/// Concrete, type-erased lighting attachment carried by [`super::RynkService`].
+#[derive(Clone, Copy)]
+pub struct RynkLightingController<'a> {
+    pub(super) descriptor: RynkLightingDescriptor<'a>,
+    pub(super) overlay_capacity: u16,
+    mailbox: &'a RynkLightingMailbox,
+}
+
+impl<'a> RynkLightingController<'a> {
+    pub const fn new(
+        mailbox: &'a RynkLightingMailbox,
+        descriptor: RynkLightingDescriptor<'a>,
+        overlay_capacity: u16,
+    ) -> Self {
+        let staged_capacity = RYNK_LIGHTING_TRANSACTION_CAPACITY as u16;
+        Self {
+            descriptor,
+            // The single advertised limit must be valid for both incremental
+            // updates and atomic replacement.
+            overlay_capacity: if overlay_capacity < staged_capacity {
+                overlay_capacity
+            } else {
+                staged_capacity
+            },
+            mailbox,
+        }
+    }
+
+    pub const fn descriptor(&self) -> RynkLightingDescriptor<'a> {
+        self.descriptor
+    }
+
+    pub const fn overlay_capacity(&self) -> u16 {
+        self.overlay_capacity
+    }
+
+    pub(super) async fn request(&self, command: RynkLightingCommand) -> LightingResult<LightingState> {
+        self.mailbox.request(command).await
+    }
+
+    pub(super) async fn replace_overlay(
+        &self,
+        expected_revision: u32,
+        cells: &Vec<LightingOverlayCell, RYNK_LIGHTING_TRANSACTION_CAPACITY>,
+    ) -> LightingResult<LightingState> {
+        self.mailbox.request_replace(expected_revision, cells).await
+    }
+}
+
+/// Fixed protocol-facing mailbox. Its adapter forwards every request to the
+/// standard engine mailbox; it never owns renderer or compositor state.
+pub struct RynkLightingMailbox {
+    requests: Channel<RawMutex, MailboxRequest, RYNK_LIGHTING_COMMAND_CAPACITY>,
+    response: Signal<RawMutex, MailboxResponse>,
+    caller: Mutex<RawMutex, ()>,
+    next_id: BlockingMutex<RawMutex, Cell<u32>>,
+    replacement: BlockingMutex<RawMutex, RefCell<Option<StagedReplacement>>>,
+    replacement_ready: Signal<RawMutex, ()>,
+    replacement_available: Signal<RawMutex, ()>,
+}
+
+struct StagedReplacement {
+    id: u32,
+    cells: Vec<LightingOverlayCell, RYNK_LIGHTING_TRANSACTION_CAPACITY>,
+}
+
+pub(in crate::host::rynk) struct MailboxRequest {
+    pub(in crate::host::rynk) id: u32,
+    pub(in crate::host::rynk) command: RynkLightingCommand,
+}
+
+struct MailboxResponse {
+    id: u32,
+    result: LightingResult<LightingState>,
+}
+
+impl RynkLightingMailbox {
+    pub const fn new() -> Self {
+        Self {
+            requests: Channel::new(),
+            response: Signal::new(),
+            caller: Mutex::new(()),
+            next_id: BlockingMutex::new(Cell::new(0)),
+            replacement: BlockingMutex::new(RefCell::new(None)),
+            replacement_ready: Signal::new(),
+            replacement_available: Signal::new(),
+        }
+    }
+
+    async fn request(&self, command: RynkLightingCommand) -> LightingResult<LightingState> {
+        let _caller = self.caller.lock().await;
+        let id = self.allocate_id();
+        self.send_and_wait(id, command).await
+    }
+
+    async fn request_replace(
+        &self,
+        expected_revision: u32,
+        cells: &Vec<LightingOverlayCell, RYNK_LIGHTING_TRANSACTION_CAPACITY>,
+    ) -> LightingResult<LightingState> {
+        let _caller = self.caller.lock().await;
+        while self.replacement.lock(|replacement| replacement.borrow().is_some()) {
+            self.replacement_available.wait().await;
+        }
+
+        let id = self.allocate_id();
+        // Enqueue first. After this await, staging and its ready signal are
+        // synchronous, so cancellation cannot leave an orphaned stage without
+        // a matching command. The adapter may receive the token first and wait.
+        self.requests
+            .send(MailboxRequest {
+                id,
+                command: RynkLightingCommand::ReplaceOverlay { expected_revision },
+            })
+            .await;
+        self.replacement.lock(|replacement| {
+            let previous = replacement.borrow_mut().replace(StagedReplacement {
+                id,
+                cells: cells.clone(),
+            });
+            debug_assert!(previous.is_none(), "replacement slot was checked before enqueue");
+        });
+        self.replacement_ready.signal(());
+        self.wait_for_reply(id).await
+    }
+
+    fn allocate_id(&self) -> u32 {
+        self.next_id.lock(|next| {
+            let id = next.get();
+            next.set(id.wrapping_add(1));
+            id
+        })
+    }
+
+    async fn send_and_wait(&self, id: u32, command: RynkLightingCommand) -> LightingResult<LightingState> {
+        self.requests.send(MailboxRequest { id, command }).await;
+        self.wait_for_reply(id).await
+    }
+
+    async fn wait_for_reply(&self, id: u32) -> LightingResult<LightingState> {
+        loop {
+            let response = self.response.wait().await;
+            if response.id == id {
+                return response.result;
+            }
+        }
+    }
+
+    pub(in crate::host::rynk) async fn receive(&self) -> MailboxRequest {
+        self.requests.receive().await
+    }
+
+    pub(in crate::host::rynk) fn reply(&self, id: u32, result: LightingResult<LightingState>) {
+        self.response.signal(MailboxResponse { id, result });
+    }
+
+    pub(in crate::host::rynk) async fn take_replacement(
+        &self,
+        id: u32,
+    ) -> Vec<LightingOverlayCell, RYNK_LIGHTING_TRANSACTION_CAPACITY> {
+        loop {
+            let staged = self.replacement.lock(|replacement| {
+                let mut replacement = replacement.borrow_mut();
+                if replacement.as_ref().is_some_and(|staged| staged.id == id) {
+                    replacement.take()
+                } else {
+                    None
+                }
+            });
+            if let Some(staged) = staged {
+                self.replacement_available.signal(());
+                return staged.cells;
+            }
+            self.replacement_ready.wait().await;
+        }
+    }
+}
+
+impl Default for RynkLightingMailbox {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+pub(super) enum RynkLightingCommand {
+    ReadState,
+    SetState {
+        expected_revision: u32,
+        state: LightingMutableState,
+    },
+    SetOverlay {
+        expected_revision: u32,
+        cell: LightingOverlayCell,
+    },
+    UnsetOverlay {
+        expected_revision: u32,
+        led_id: rmk_types::protocol::rynk::LightingLedId,
+    },
+    ClearOverlay {
+        expected_revision: u32,
+    },
+    ReplaceOverlay {
+        expected_revision: u32,
+    },
+}
+
+/// Bridges type-erased Rynk commands into one concrete standard lighting
+/// mailbox. Boards spawn this alongside `LightingProcessor`.
+pub struct StandardRynkLightingAdapter<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize> {
+    protocol: &'a RynkLightingMailbox,
+    core: &'a LightingMailbox<StandardCommand<OVERLAY_CAPACITY>, StandardState, StandardError, CORE_COMMAND_CAPACITY>,
+    topology: LightingTopology<'a>,
+}
+
+impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize>
+    StandardRynkLightingAdapter<'a, OVERLAY_CAPACITY, CORE_COMMAND_CAPACITY>
+{
+    pub const fn new(
+        protocol: &'a RynkLightingMailbox,
+        core: &'a LightingMailbox<
+            StandardCommand<OVERLAY_CAPACITY>,
+            StandardState,
+            StandardError,
+            CORE_COMMAND_CAPACITY,
+        >,
+        topology: LightingTopology<'a>,
+    ) -> Self {
+        Self {
+            protocol,
+            core,
+            topology,
+        }
+    }
+
+    /// Process one protocol command. Exposed for board-specific executors and
+    /// deterministic tests; [`Runnable`] simply repeats it forever.
+    pub async fn process_next(&mut self) {
+        let request = self.protocol.receive().await;
+        let result = self.dispatch(request.id, request.command).await;
+        self.protocol.reply(request.id, result);
+    }
+
+    async fn dispatch(&self, request_id: u32, command: RynkLightingCommand) -> LightingResult<LightingState> {
+        let core_command = match command {
+            RynkLightingCommand::ReadState => StandardCommand::ReadState,
+            RynkLightingCommand::SetState {
+                expected_revision,
+                state,
+            } => StandardCommand::SetStateIfRevision {
+                expected_revision,
+                state: mutable_state_from_wire(state),
+            },
+            RynkLightingCommand::SetOverlay {
+                expected_revision,
+                cell,
+            } => StandardCommand::SetOverlayIfRevision {
+                expected_revision,
+                cell: self.overlay_cell(cell)?,
+            },
+            RynkLightingCommand::UnsetOverlay {
+                expected_revision,
+                led_id,
+            } => StandardCommand::UnsetOverlayIfRevision {
+                expected_revision,
+                slot: self
+                    .topology
+                    .slot(LedId(led_id.0))
+                    .ok_or(LightingError::UnknownLed { led_id })?,
+            },
+            RynkLightingCommand::ClearOverlay { expected_revision } => {
+                StandardCommand::ClearOverlayIfRevision { expected_revision }
+            }
+            RynkLightingCommand::ReplaceOverlay { expected_revision } => {
+                let cells = self.protocol.take_replacement(request_id).await;
+                let mut batch = OverlayBatch::new();
+                for cell in cells {
+                    let cell = self.overlay_cell(cell)?;
+                    if batch.as_slice().iter().any(|existing| existing.slot == cell.slot) {
+                        return Err(LightingError::InvalidRequest);
+                    }
+                    batch
+                        .push(cell)
+                        .map_err(|error| map_overlay_error(error, OVERLAY_CAPACITY))?;
+                }
+                StandardCommand::ReplaceOverlayIfRevision {
+                    expected_revision,
+                    batch,
+                }
+            }
+        };
+
+        self.core
+            .request(core_command)
+            .await
+            .map(state_to_wire)
+            .map_err(|error| map_standard_error(error, OVERLAY_CAPACITY))
+    }
+
+    fn overlay_cell(&self, cell: LightingOverlayCell) -> LightingResult<OverlayCell> {
+        cell.validate()?;
+        let slot = self
+            .topology
+            .slot(LedId(cell.led_id.0))
+            .ok_or(LightingError::UnknownLed { led_id: cell.led_id })?;
+        Ok(OverlayCell {
+            slot,
+            effect: effect_from_wire(cell.effect),
+            ttl_ms: cell.ttl_ms.and_then(NonZeroU32::new),
+        })
+    }
+}
+
+impl<const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize> Runnable
+    for StandardRynkLightingAdapter<'_, OVERLAY_CAPACITY, CORE_COMMAND_CAPACITY>
+{
+    async fn run(&mut self) -> ! {
+        loop {
+            self.process_next().await;
+        }
+    }
+}
+
+fn mutable_state_from_wire(state: LightingMutableState) -> StandardMutableState {
+    StandardMutableState {
+        output_enabled: state.output_enabled,
+        output_brightness: state.output_brightness,
+        background: BackgroundState {
+            enabled: state.background.enabled,
+            hue: state.background.hue,
+            saturation: state.background.saturation,
+            value: state.background.value,
+            speed: state.background.speed,
+            mode: match state.background.mode {
+                LightingBackgroundMode::Solid => BackgroundMode::Solid,
+                LightingBackgroundMode::Breathe => BackgroundMode::Breathe,
+            },
+        },
+    }
+}
+
+pub(super) fn state_to_wire(state: StandardState) -> LightingState {
+    LightingState {
+        revision: state.revision,
+        output_enabled: state.output_enabled,
+        output_brightness: state.output_brightness,
+        background: LightingBackgroundState {
+            enabled: state.background.enabled,
+            hue: state.background.hue,
+            saturation: state.background.saturation,
+            value: state.background.value,
+            speed: state.background.speed,
+            mode: match state.background.mode {
+                BackgroundMode::Solid => LightingBackgroundMode::Solid,
+                BackgroundMode::Breathe => LightingBackgroundMode::Breathe,
+            },
+        },
+        overlay_len: state.overlay_len.min(u16::MAX as usize) as u16,
+    }
+}
+
+fn effect_from_wire(effect: rmk_types::protocol::rynk::LightingEffect) -> BuiltinEffect {
+    use rmk_types::protocol::rynk::LightingEffect;
+
+    match effect {
+        LightingEffect::Solid { color } => BuiltinEffect::Solid {
+            color: rgb_from_wire(color),
+        },
+        LightingEffect::Blink {
+            color,
+            period_ms,
+            phase_ms,
+            duty,
+        } => BuiltinEffect::Blink {
+            color: rgb_from_wire(color),
+            period_ms,
+            phase_ms,
+            duty,
+        },
+        LightingEffect::Breathe {
+            color,
+            period_ms,
+            phase_ms,
+            step_ms,
+        } => BuiltinEffect::Breathe {
+            color: rgb_from_wire(color),
+            period_ms,
+            phase_ms,
+            step_ms,
+        },
+    }
+}
+
+const fn rgb_from_wire(color: LightingRgb8) -> Rgb8 {
+    Rgb8::new(color.r, color.g, color.b)
+}
+
+fn map_standard_error(error: StandardError, capacity: usize) -> LightingError {
+    match error {
+        StandardError::RevisionConflict { expected, current } => {
+            LightingError::StateRevisionConflict { expected, current }
+        }
+        StandardError::Overlay(error) => map_overlay_error(error, capacity),
+        StandardError::DeadlineOverflow => LightingError::InvalidTtl,
+        StandardError::Render(_) => LightingError::Unsupported,
+    }
+}
+
+fn map_overlay_error(error: OverlayError, capacity: usize) -> LightingError {
+    match error {
+        OverlayError::Full | OverlayError::TooManyEntries { .. } => LightingError::OverlayFull {
+            capacity: capacity.min(u16::MAX as usize) as u16,
+        },
+        OverlayError::DuplicateSlot { .. } => LightingError::InvalidRequest,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use embassy_futures::join::join;
+    use embassy_futures::select::{Either, select};
+    use embassy_futures::yield_now;
+    use rmk_types::protocol::rynk::{
+        LightingBackgroundMode, LightingBackgroundState, LightingEffect, LightingLedId, LightingOverlayCell,
+        LightingRgb8,
+    };
+
+    use super::*;
+    use crate::lighting::{LedMetadata, MatrixSize, ZoneSpan};
+    use crate::physical_layout::PhysicalLayout;
+    use crate::test_support::test_block_on as block_on;
+
+    static TEST_LEDS: [LedMetadata; 1] = [LedMetadata {
+        id: LedId(10),
+        key: None,
+        position: None,
+        zones: ZoneSpan::new(0, 0),
+    }];
+
+    fn topology() -> LightingTopology<'static> {
+        LightingTopology {
+            matrix: MatrixSize::new(0, 0),
+            keys: &[],
+            physical_layout: PhysicalLayout::EMPTY,
+            leds: &TEST_LEDS,
+            zones: &[],
+            zone_memberships: &[],
+        }
+    }
+
+    fn cell(id: u16) -> LightingOverlayCell {
+        LightingOverlayCell {
+            led_id: LightingLedId(id),
+            effect: LightingEffect::Solid {
+                color: LightingRgb8 { r: 1, g: 2, b: 3 },
+            },
+            ttl_ms: None,
+        }
+    }
+
+    fn state(revision: u32) -> LightingState {
+        LightingState {
+            revision,
+            output_enabled: true,
+            output_brightness: 255,
+            background: LightingBackgroundState {
+                enabled: true,
+                hue: 0,
+                saturation: 0,
+                value: 1,
+                speed: 0,
+                mode: LightingBackgroundMode::Solid,
+            },
+            overlay_len: 1,
+        }
+    }
+
+    #[test]
+    fn cancelled_replacement_cannot_be_overwritten_by_the_next_caller() {
+        let mailbox = RynkLightingMailbox::new();
+        let mut first = Vec::new();
+        first.push(cell(10)).unwrap();
+
+        let cancelled = block_on(select(mailbox.request_replace(0, &first), async {
+            yield_now().await;
+        }));
+        assert!(matches!(cancelled, Either::Second(())));
+
+        let mut second = Vec::new();
+        second.push(cell(20)).unwrap();
+        let (reply, ()) = block_on(join(mailbox.request_replace(1, &second), async {
+            let abandoned = mailbox.receive().await;
+            assert!(matches!(
+                abandoned.command,
+                RynkLightingCommand::ReplaceOverlay { expected_revision: 0 }
+            ));
+            let abandoned_cells = mailbox.take_replacement(abandoned.id).await;
+            assert_eq!(abandoned_cells.as_slice(), &[cell(10)]);
+            mailbox.reply(abandoned.id, Ok(state(1)));
+
+            let current = mailbox.receive().await;
+            assert!(matches!(
+                current.command,
+                RynkLightingCommand::ReplaceOverlay { expected_revision: 1 }
+            ));
+            let current_cells = mailbox.take_replacement(current.id).await;
+            assert_eq!(current_cells.as_slice(), &[cell(20)]);
+            mailbox.reply(current.id, Ok(state(2)));
+        }));
+        assert_eq!(reply, Ok(state(2)));
+    }
+
+    #[test]
+    fn replacement_rejects_duplicate_stable_ids_before_reaching_the_core() {
+        let protocol = RynkLightingMailbox::new();
+        let core = LightingMailbox::<StandardCommand<2>, StandardState, StandardError, 1>::new();
+        let mut adapter = StandardRynkLightingAdapter::new(&protocol, &core, topology());
+        let mut cells = Vec::new();
+        cells.push(cell(10)).unwrap();
+        cells.push(cell(10)).unwrap();
+
+        let (reply, ()) = block_on(join(protocol.request_replace(0, &cells), adapter.process_next()));
+        assert_eq!(reply, Err(LightingError::InvalidRequest));
+    }
+}
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 49196a062..6953c3da3 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -5,11 +5,18 @@
 //! ([`HostLock`]) and topic subscriptions, so transports never share either.
 
 mod handlers;
+#[cfg(feature = "lighting")]
+mod lighting;
 mod topics;
 
 use embassy_futures::select::{Either, select};
 use embedded_io_async::{Read, Write};
 use postcard::experimental::max_size::MaxSize;
+#[cfg(feature = "lighting")]
+pub use lighting::{
+    RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
+    StandardRynkLightingAdapter,
+};
 use rmk_types::constants::RYNK_BUFFER_SIZE;
 use rmk_types::protocol::rynk::{
     Cmd, Deframer, RYNK_HEADER_SIZE, RynkError, RynkMessage, command, encode_frame, max_wire_size,
@@ -32,8 +39,21 @@ pub struct RynkService<'a> {
     device: DeviceConfig<'static>,
     /// Policy copied into each session's authorization gate.
     lock_config: LockConfig,
+    #[cfg(feature = "lighting")]
+    lighting: Option<RynkLightingController<'a>>,
+}
+
+/// Per-session state that has to outlive a single dispatch. The authorization
+/// gate and the topic table are locals in [`RynkService::run_session`]; the
+/// lighting overlay transaction cannot be, because it spans the
+/// Begin/Put/Commit exchange.
+#[derive(Default)]
+struct RynkSession {
+    #[cfg(feature = "lighting")]
+    lighting: embassy_sync::mutex::Mutex<crate::RawMutex, handlers::lighting::LightingTransactionState>,
 }
 
+
 impl<'a> RynkService<'a> {
     pub fn new(keymap: &'a KeyMap<'a>, config: &RmkConfig<'static>) -> Self {
         let mut ctx = KeyboardContext::new(keymap);
@@ -43,9 +63,20 @@ impl<'a> RynkService<'a> {
             ctx,
             device: config.device_config,
             lock_config: config.lock_config,
+            #[cfg(feature = "lighting")]
+            lighting: None,
         }
     }
 
+    /// Attach a concrete lighting controller. Merely compiling the lighting
+    /// feature does not advertise support: discovery turns on only after this
+    /// binding is present and its bridge task is running.
+    #[cfg(feature = "lighting")]
+    pub fn with_lighting(mut self, lighting: RynkLightingController<'a>) -> Self {
+        self.lighting = Some(lighting);
+        self
+    }
+
     /// Whether `cmd` needs an unlocked device.
     fn requires_unlock(&self, cmd: Cmd) -> bool {
         match cmd {
@@ -64,13 +95,27 @@ impl<'a> RynkService<'a> {
             | Cmd::SetKeymapBulk
             | Cmd::SetComboBulk
             | Cmd::SetMorseBulk => self.lock_config.write_requires_unlock,
+            #[cfg(feature = "lighting")]
+            Cmd::SetLightingState
+            | Cmd::SetLightingOverlay
+            | Cmd::UnsetLightingOverlay
+            | Cmd::ClearLightingOverlay
+            | Cmd::BeginLightingOverlayReplace
+            | Cmd::PutLightingOverlayChunk
+            | Cmd::CommitLightingOverlayReplace
+            | Cmd::AbortLightingOverlayReplace => self.lock_config.write_requires_unlock,
             _ => false,
         }
     }
 
     /// Serve one inbound message: on success the reply frame replaces the
     /// payload in place; on error the caller answers with the error envelope.
-    async fn dispatch(&self, locker: &HostLock<'_>, msg: &mut RynkMessage<'_>) -> Result<(), RynkError> {
+    async fn dispatch(
+        &self,
+        locker: &HostLock<'_>,
+        session: &RynkSession,
+        msg: &mut RynkMessage<'_>,
+    ) -> Result<(), RynkError> {
         let cmd = msg.header().cmd;
 
         if self.requires_unlock(cmd) && !locker.is_unlocked() {
@@ -136,6 +181,41 @@ impl<'a> RynkService<'a> {
 
             Cmd::GetLayout => serve::<command::GetLayout, _>(self, msg).await,
 
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingCapabilities => Serve::<command::GetLightingCapabilities, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingState => Serve::<command::GetLightingState, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::SetLightingState => Serve::<command::SetLightingState, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingKeys => Serve::<command::GetLightingKeys, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingPhysicalKeys => Serve::<command::GetLightingPhysicalKeys, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingLeds => Serve::<command::GetLightingLeds, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingZones => Serve::<command::GetLightingZones, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingZoneMemberships => Serve::<command::GetLightingZoneMemberships, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingOutputs => Serve::<command::GetLightingOutputs, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingRoutes => Serve::<command::GetLightingRoutes, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::SetLightingOverlay => Serve::<command::SetLightingOverlay, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::UnsetLightingOverlay => Serve::<command::UnsetLightingOverlay, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::ClearLightingOverlay => Serve::<command::ClearLightingOverlay, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::BeginLightingOverlayReplace => handlers::lighting::serve_begin(self, session, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::PutLightingOverlayChunk => handlers::lighting::serve_put(self, session, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::CommitLightingOverlayReplace => handlers::lighting::serve_commit(self, session, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::AbortLightingOverlayReplace => handlers::lighting::serve_abort(self, session, msg).await,
+
             _ => Err(RynkError::UnknownCmd),
         }
     }
@@ -151,6 +231,7 @@ impl<'a> RynkService<'a> {
             RYNK_UNLOCK_WINDOW,
         );
         let mut topics = TopicSubscribers::new();
+        let session = RynkSession::default();
         let mut buf = [0u8; RYNK_BUFFER_SIZE];
         let mut df = Deframer::new();
         // Mute topics until the client completes the version handshake.
@@ -170,7 +251,7 @@ impl<'a> RynkService<'a> {
                     // Hosts never send topic-range cmds; drop without a reply.
                     warn!("Rynk: dropping topic-range request {:?}", cmd);
                 } else {
-                    let served = self.dispatch(&locker, &mut msg).await;
+                    let served = self.dispatch(&locker, &session, &mut msg).await;
                     // The version handshake completes on GetCapabilities.
                     handshaked |= cmd == Cmd::GetCapabilities;
                     let written = match served {
diff --git a/rmk/src/host/rynk/topics.rs b/rmk/src/host/rynk/topics.rs
index 7732f6fcb..499c294c0 100644
--- a/rmk/src/host/rynk/topics.rs
+++ b/rmk/src/host/rynk/topics.rs
@@ -10,6 +10,8 @@ use rmk_types::protocol::rynk::TopicEvent;
 
 #[cfg(feature = "_ble")]
 use crate::event::BatteryStatusEvent;
+#[cfg(feature = "lighting")]
+use crate::event::LightingChangedEvent;
 use crate::event::{
     ConnectionStatusChangeEvent, EventSubscriber, LayerChangeEvent, LedIndicatorEvent, SleepStateEvent,
     SubscribableEvent, WpmUpdateEvent,
@@ -23,6 +25,8 @@ pub(super) struct TopicSubscribers {
     led: <LedIndicatorEvent as SubscribableEvent>::Subscriber,
     #[cfg(feature = "_ble")]
     battery: <BatteryStatusEvent as SubscribableEvent>::Subscriber,
+    #[cfg(feature = "lighting")]
+    lighting: <LightingChangedEvent as SubscribableEvent>::Subscriber,
 }
 
 impl TopicSubscribers {
@@ -35,6 +39,8 @@ impl TopicSubscribers {
             led: LedIndicatorEvent::subscriber(),
             #[cfg(feature = "_ble")]
             battery: BatteryStatusEvent::subscriber(),
+            #[cfg(feature = "lighting")]
+            lighting: LightingChangedEvent::subscriber(),
         }
     }
 
@@ -49,6 +55,7 @@ impl TopicSubscribers {
             e = self.sleep.next_event().fuse() => TopicEvent::SleepState(*e),
             e = self.led.next_event().fuse() => TopicEvent::LedIndicatorChange(*e),
             with_feature("_ble"): e = self.battery.next_event().fuse() => TopicEvent::BatteryStatusChange(*e),
+            with_feature("lighting"): _ = self.lighting.next_event().fuse() => TopicEvent::LightingChange(rmk_types::protocol::rynk::LightingChanged),
         }
     }
 }
diff --git a/rynk/Cargo.toml b/rynk/Cargo.toml
index d83c5b728..f4a7f428d 100644
--- a/rynk/Cargo.toml
+++ b/rynk/Cargo.toml
@@ -13,7 +13,7 @@ keywords = ["keyboard", "firmware", "rmk", "protocol", "host"]
 [dependencies]
 # No `host` by default: a dongle binary links rmk (firmware) and rynk together, and
 # feature unification must not switch the firmware's bulk types to alloc Vec.
-rmk-types = { path = "../rmk-types", default-features = false, features = ["rynk", "_ble", "split", "steno"] }
+rmk-types = { path = "../rmk-types", default-features = false, features = ["rynk", "_ble", "split", "steno", "lighting"] }
 embedded-io-async.workspace = true
 embassy-sync.workspace = true
 embassy-futures = "0.1"
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index e1f472571..52425327e 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -22,9 +22,14 @@ use rynk::rmk_types::fork::Fork;
 use rynk::rmk_types::led_indicator::LedIndicator;
 use rynk::rmk_types::morse::Morse;
 use rynk::rmk_types::protocol::rynk::{
-    BehaviorConfig, DeviceCapabilities, DeviceInfo, GetComboBulkResponse, GetKeymapBulkResponse, GetMorseBulkResponse,
-    LockStatus, MacroData, MatrixState, PeripheralStatus, ProtocolVersion, SetComboBulkRequest, SetKeymapBulkRequest,
-    SetMorseBulkRequest, StorageResetMode,
+    AbortLightingOverlayReplaceRequest, BeginLightingOverlayReplaceRequest, BehaviorConfig,
+    ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest, DeviceCapabilities, DeviceInfo,
+    GetComboBulkResponse, GetKeymapBulkResponse, GetMorseBulkResponse, LightingCapabilities, LightingKeysPage,
+    LightingLedsPage, LightingOutputsPage, LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage,
+    LightingRoutesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus, MacroData,
+    MatrixState, PeripheralStatus, ProtocolVersion, PutLightingOverlayChunkRequest, SetComboBulkRequest,
+    SetKeymapBulkRequest, SetLightingOverlayRequest, SetLightingStateRequest, SetMorseBulkRequest, StorageResetMode,
+    UnsetLightingOverlayRequest,
 };
 use rynk::{Client, Driver, LayoutInfo, RynkDevice, RynkHostError, TopicEvent};
 use wasm_bindgen::prelude::*;
@@ -157,6 +162,24 @@ endpoints! {
     get_peripheral_status(slot: u8) -> PeripheralStatus,
     get_wpm() -> u16,
     get_sleep_state() -> bool,
+    // lighting
+    get_lighting_capabilities() -> LightingCapabilities,
+    get_lighting_state() -> LightingState,
+    set_lighting_state(request: SetLightingStateRequest) -> LightingState,
+    get_lighting_keys(request: LightingPageRequest) -> LightingKeysPage,
+    get_lighting_physical_keys(request: LightingPageRequest) -> LightingPhysicalKeysPage,
+    get_lighting_leds(request: LightingPageRequest) -> LightingLedsPage,
+    get_lighting_zones(request: LightingPageRequest) -> LightingZonesPage,
+    get_lighting_zone_memberships(request: LightingPageRequest) -> LightingZoneMembershipsPage,
+    get_lighting_outputs(request: LightingPageRequest) -> LightingOutputsPage,
+    get_lighting_routes(request: LightingPageRequest) -> LightingRoutesPage,
+    set_lighting_overlay(request: SetLightingOverlayRequest) -> LightingState,
+    unset_lighting_overlay(request: UnsetLightingOverlayRequest) -> LightingState,
+    clear_lighting_overlay(request: ClearLightingOverlayRequest) -> LightingState,
+    begin_lighting_overlay_replace(request: BeginLightingOverlayReplaceRequest) -> LightingOverlayTransaction,
+    put_lighting_overlay_chunk(request: PutLightingOverlayChunkRequest) -> (),
+    commit_lighting_overlay_replace(request: CommitLightingOverlayReplaceRequest) -> LightingState,
+    abort_lighting_overlay_replace(request: AbortLightingOverlayReplaceRequest) -> (),
     // connection
     get_connection_type() -> ConnectionType,
     get_connection_status() -> ConnectionStatus,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 5fca84082..bede325fa 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -21,11 +21,16 @@ use rmk_types::fork::Fork;
 use rmk_types::led_indicator::LedIndicator;
 use rmk_types::morse::Morse;
 use rmk_types::protocol::rynk::{
-    BehaviorConfig, Cmd, DeviceCapabilities, DeviceInfo, GetComboBulkRequest, GetComboBulkResponse, GetEncoderRequest,
-    GetKeymapBulkRequest, GetKeymapBulkResponse, GetMacroRequest, GetMorseBulkRequest, GetMorseBulkResponse,
-    KeyPosition, LockStatus, MacroData, MatrixState, PeripheralStatus, ProtocolVersion, SetComboBulkRequest,
-    SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest, SetMacroRequest,
-    SetMorseBulkRequest, SetMorseRequest, StorageResetMode, command,
+    AbortLightingOverlayReplaceRequest, BeginLightingOverlayReplaceRequest, BehaviorConfig,
+    ClearLightingOverlayRequest, Cmd, CommitLightingOverlayReplaceRequest, DeviceCapabilities, DeviceInfo,
+    GetComboBulkRequest, GetComboBulkResponse, GetEncoderRequest, GetKeymapBulkRequest, GetKeymapBulkResponse,
+    GetMacroRequest, GetMorseBulkRequest, GetMorseBulkResponse, KeyPosition, LightingCapabilities, LightingKeysPage,
+    LightingLedsPage, LightingOutputsPage, LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage,
+    LightingResult, LightingRoutesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus,
+    MacroData, MatrixState, PeripheralStatus, ProtocolVersion, PutLightingOverlayChunkRequest, SetComboBulkRequest,
+    SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest, SetLightingOverlayRequest,
+    SetLightingStateRequest, SetMacroRequest, SetMorseBulkRequest, SetMorseRequest, StorageResetMode,
+    UnsetLightingOverlayRequest, command,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -64,6 +69,20 @@ impl Client {
         }
     }
 
+    /// Reject a lighting command locally when the handshake says the firmware
+    /// has no lighting service.
+    fn require_lighting(&self, cmd: Cmd) -> Result<(), RynkHostError> {
+        if self.capabilities.lighting_enabled {
+            Ok(())
+        } else {
+            Err(RynkHostError::Unsupported(cmd, "lighting not enabled"))
+        }
+    }
+
+    fn flatten_lighting<T>(result: LightingResult<T>) -> Result<T, RynkHostError> {
+        result.map_err(RynkHostError::LightingRejected)
+    }
+
     /// Read the firmware's protocol version.
     pub async fn get_version(&self) -> Result<ProtocolVersion, RynkHostError> {
         self.request::<command::GetVersion>(&()).await
@@ -358,6 +377,132 @@ impl Client {
         self.request::<command::GetLedIndicator>(&()).await
     }
 
+    /// Read lighting limits, supported effects, and topology identity.
+    pub async fn get_lighting_capabilities(&self) -> Result<LightingCapabilities, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingCapabilities)?;
+        Self::flatten_lighting(self.request::<command::GetLightingCapabilities>(&()).await?)
+    }
+
+    /// Read authoritative standard lighting state and its concurrency revision.
+    pub async fn get_lighting_state(&self) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingState)?;
+        Self::flatten_lighting(self.request::<command::GetLightingState>(&()).await?)
+    }
+
+    /// Atomically replace standard mutable state when the revision still matches.
+    pub async fn set_lighting_state(&self, request: SetLightingStateRequest) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::SetLightingState)?;
+        Self::flatten_lighting(self.request::<command::SetLightingState>(&request).await?)
+    }
+
+    pub async fn get_lighting_physical_keys(
+        &self,
+        request: LightingPageRequest,
+    ) -> Result<LightingPhysicalKeysPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingPhysicalKeys)?;
+        Self::flatten_lighting(self.request::<command::GetLightingPhysicalKeys>(&request).await?)
+    }
+
+    /// Read real logical matrix keys, including keys with no measured geometry.
+    pub async fn get_lighting_keys(&self, request: LightingPageRequest) -> Result<LightingKeysPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingKeys)?;
+        Self::flatten_lighting(self.request::<command::GetLightingKeys>(&request).await?)
+    }
+
+    pub async fn get_lighting_leds(&self, request: LightingPageRequest) -> Result<LightingLedsPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingLeds)?;
+        Self::flatten_lighting(self.request::<command::GetLightingLeds>(&request).await?)
+    }
+
+    pub async fn get_lighting_zones(&self, request: LightingPageRequest) -> Result<LightingZonesPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingZones)?;
+        Self::flatten_lighting(self.request::<command::GetLightingZones>(&request).await?)
+    }
+
+    pub async fn get_lighting_zone_memberships(
+        &self,
+        request: LightingPageRequest,
+    ) -> Result<LightingZoneMembershipsPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingZoneMemberships)?;
+        Self::flatten_lighting(self.request::<command::GetLightingZoneMemberships>(&request).await?)
+    }
+
+    pub async fn get_lighting_outputs(
+        &self,
+        request: LightingPageRequest,
+    ) -> Result<LightingOutputsPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingOutputs)?;
+        Self::flatten_lighting(self.request::<command::GetLightingOutputs>(&request).await?)
+    }
+
+    pub async fn get_lighting_routes(&self, request: LightingPageRequest) -> Result<LightingRoutesPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingRoutes)?;
+        Self::flatten_lighting(self.request::<command::GetLightingRoutes>(&request).await?)
+    }
+
+    /// Set one transient overlay cell when the state revision matches.
+    pub async fn set_lighting_overlay(
+        &self,
+        request: SetLightingOverlayRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::SetLightingOverlay)?;
+        Self::flatten_lighting(self.request::<command::SetLightingOverlay>(&request).await?)
+    }
+
+    /// Remove one transient overlay cell when the state revision matches.
+    pub async fn unset_lighting_overlay(
+        &self,
+        request: UnsetLightingOverlayRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::UnsetLightingOverlay)?;
+        Self::flatten_lighting(self.request::<command::UnsetLightingOverlay>(&request).await?)
+    }
+
+    /// Clear the transient overlay when the state revision matches.
+    pub async fn clear_lighting_overlay(
+        &self,
+        request: ClearLightingOverlayRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::ClearLightingOverlay)?;
+        Self::flatten_lighting(self.request::<command::ClearLightingOverlay>(&request).await?)
+    }
+
+    /// Reserve a bounded staging transaction for atomic overlay replacement.
+    pub async fn begin_lighting_overlay_replace(
+        &self,
+        request: BeginLightingOverlayReplaceRequest,
+    ) -> Result<LightingOverlayTransaction, RynkHostError> {
+        self.require_lighting(Cmd::BeginLightingOverlayReplace)?;
+        Self::flatten_lighting(self.request::<command::BeginLightingOverlayReplace>(&request).await?)
+    }
+
+    /// Stage one ordered chunk. It does not mutate the live overlay.
+    pub async fn put_lighting_overlay_chunk(
+        &self,
+        request: PutLightingOverlayChunkRequest,
+    ) -> Result<(), RynkHostError> {
+        self.require_lighting(Cmd::PutLightingOverlayChunk)?;
+        Self::flatten_lighting(self.request::<command::PutLightingOverlayChunk>(&request).await?)
+    }
+
+    /// Atomically publish a complete staged overlay replacement.
+    pub async fn commit_lighting_overlay_replace(
+        &self,
+        request: CommitLightingOverlayReplaceRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::CommitLightingOverlayReplace)?;
+        Self::flatten_lighting(self.request::<command::CommitLightingOverlayReplace>(&request).await?)
+    }
+
+    /// Discard a staged overlay replacement without changing live state.
+    pub async fn abort_lighting_overlay_replace(
+        &self,
+        request: AbortLightingOverlayReplaceRequest,
+    ) -> Result<(), RynkHostError> {
+        self.require_lighting(Cmd::AbortLightingOverlayReplace)?;
+        Self::flatten_lighting(self.request::<command::AbortLightingOverlayReplace>(&request).await?)
+    }
+
     /// Read the active connection type (USB / BLE).
     pub async fn get_connection_type(&self) -> Result<ConnectionType, RynkHostError> {
         self.request::<command::GetConnectionType>(&()).await
diff --git a/rynk/src/driver.rs b/rynk/src/driver.rs
index 9d7ab3ab2..e0ff6cd6a 100644
--- a/rynk/src/driver.rs
+++ b/rynk/src/driver.rs
@@ -36,7 +36,7 @@ use embassy_sync::signal::Signal;
 use embedded_io_async::{Error as _, ErrorKind, Read, Write};
 use rmk_types::protocol::rynk::command::Endpoint;
 use rmk_types::protocol::rynk::{
-    Cmd, Deframer, DeviceCapabilities, RYNK_HEADER_SIZE, RynkError, RynkHeader, TopicEvent, encode_frame, max_wire_size,
+    Cmd, Deframer, DeviceCapabilities, LightingError, RYNK_HEADER_SIZE, RynkError, RynkHeader, TopicEvent, encode_frame, max_wire_size,
 };
 use serde::Serialize;
 use thiserror::Error;
@@ -87,6 +87,10 @@ pub enum RynkHostError {
     /// The firmware received the request but answered with an error.
     #[error("device rejected {0:?}")]
     Rejected(RynkError),
+    /// Rynk framing succeeded, but the lighting service rejected the command
+    /// with domain-specific detail.
+    #[error("lighting command rejected: {0:?}")]
+    LightingRejected(LightingError),
     /// The request failed to encode or exceeds the device's advertised
     /// `max_payload_size`.
     #[error("request {0:?} does not fit the device buffer (or failed to encode)")]
@@ -116,6 +120,7 @@ impl From<RynkHostError> for wasm_bindgen::JsValue {
             RynkHostError::Io(_) | RynkHostError::Transport(..) => "TransportError",
             RynkHostError::DeviceNotFound(_) => "DeviceNotFound",
             RynkHostError::Rejected(_) => "Rejected",
+            RynkHostError::LightingRejected(_) => "LightingRejected",
             RynkHostError::Unsupported(..) => "Unsupported",
             RynkHostError::VersionMismatch { .. } => "VersionMismatch",
             RynkHostError::Encode(_) => "RequestEncodeError",

From 66ed93a6b1c230261bbbf8681f51cd1f04623b53 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 10:26:52 -0700
Subject: [PATCH 04/78] feat(vial): add RGB Matrix lighting compatibility

---
 rmk-types/src/protocol/vial.rs |   4 +-
 rmk/src/host/via/mod.rs        |  83 +++++-
 rmk/src/host/via/rgb_matrix.rs | 486 +++++++++++++++++++++++++++++++++
 3 files changed, 558 insertions(+), 15 deletions(-)
 create mode 100644 rmk/src/host/via/rgb_matrix.rs

diff --git a/rmk-types/src/protocol/vial.rs b/rmk-types/src/protocol/vial.rs
index 77eb00315..04a7d8bef 100644
--- a/rmk-types/src/protocol/vial.rs
+++ b/rmk-types/src/protocol/vial.rs
@@ -2,7 +2,9 @@
 
 use strum::FromRepr;
 
-pub const VIA_PROTOCOL_VERSION: u16 = 0x0009;
+/// VIA Protocol 11 uses channel-qualified custom values, including the
+/// built-in RGB Matrix channel.
+pub const VIA_PROTOCOL_VERSION: u16 = 0x000B;
 pub const VIA_FIRMWARE_VERSION: u32 = 0x0001;
 
 pub const VIAL_PROTOCOL_VERSION: u32 = 6;
diff --git a/rmk/src/host/via/mod.rs b/rmk/src/host/via/mod.rs
index 1cbcbf8c9..3c1ef7ef9 100644
--- a/rmk/src/host/via/mod.rs
+++ b/rmk/src/host/via/mod.rs
@@ -12,20 +12,29 @@ use crate::keymap::KeyMap;
 use crate::{MACRO_SPACE_SIZE, boot};
 
 pub(crate) mod keycode_convert;
+pub mod rgb_matrix;
 mod vial;
 
-pub struct VialService<'a> {
+pub struct VialService<'a, RgbMatrix = rgb_matrix::Unsupported> {
     ctx: KeyboardContext<'a>,
     vial_config: VialConfig<'static>,
+    rgb_matrix: RgbMatrix,
     #[cfg(feature = "host_lock")]
     locker: crate::host::lock::HostLock<'a>,
 }
 
-impl<'a> VialService<'a> {
+impl<'a> VialService<'a, rgb_matrix::Unsupported> {
     pub fn new(keymap: &'a KeyMap<'a>, config: &RmkConfig<'static>) -> Self {
+        Self::new_with_rgb_matrix(keymap, config, rgb_matrix::Unsupported)
+    }
+}
+
+impl<'a, RgbMatrix> VialService<'a, RgbMatrix> {
+    pub fn new_with_rgb_matrix(keymap: &'a KeyMap<'a>, config: &RmkConfig<'static>, rgb_matrix: RgbMatrix) -> Self {
         Self {
             ctx: KeyboardContext::new(keymap),
             vial_config: config.vial_config,
+            rgb_matrix,
             // Vial's poll cadence is ~100 ms (`VialCommand::UnlockPoll`).
             #[cfg(feature = "host_lock")]
             locker: crate::host::lock::HostLock::new(
@@ -36,7 +45,30 @@ impl<'a> VialService<'a> {
             ),
         }
     }
+}
+
+#[cfg(feature = "lighting")]
+impl<'a, const OVERLAY_CAP: usize, const MAILBOX_CAP: usize>
+    VialService<'a, rgb_matrix::StandardControl<'a, OVERLAY_CAP, MAILBOX_CAP>>
+{
+    /// Explicitly bind VIA RGB Matrix controls to an already-running standard
+    /// lighting processor. Constructing the ordinary service does not create
+    /// an unserviced mailbox.
+    pub fn new_with_standard_lighting(
+        keymap: &'a KeyMap<'a>,
+        config: &RmkConfig<'static>,
+        mailbox: &'a crate::lighting::processor::LightingMailbox<
+            crate::lighting::standard::StandardCommand<OVERLAY_CAP>,
+            crate::lighting::standard::StandardState,
+            crate::lighting::standard::StandardError,
+            MAILBOX_CAP,
+        >,
+    ) -> Self {
+        Self::new_with_rgb_matrix(keymap, config, rgb_matrix::StandardControl::new(mailbox))
+    }
+}
 
+impl<RgbMatrix: rgb_matrix::ViaRgbMatrixControl> VialService<'_, RgbMatrix> {
     async fn process_via_packet(&self, report: &mut ViaReport) {
         let command_id = report.output_data[0];
 
@@ -126,17 +158,8 @@ impl<'a> VialService<'a> {
             ViaCommand::DynamicKeymapReset => {
                 warn!("Dynamic keymap reset -- not supported")
             }
-            ViaCommand::CustomSetValue => {
-                // backlight/rgblight/rgb matrix/led matrix/audio settings here
-                warn!("Custom set value -- not supported")
-            }
-            ViaCommand::CustomGetValue => {
-                // backlight/rgblight/rgb matrix/led matrix/audio settings here
-                warn!("Custom get value -- not supported")
-            }
-            ViaCommand::CustomSave => {
-                // backlight/rgblight/rgb matrix/led matrix/audio settings here
-                warn!("Custom get value -- not supported")
+            ViaCommand::CustomSetValue | ViaCommand::CustomGetValue | ViaCommand::CustomSave => {
+                rgb_matrix::process_packet(&self.rgb_matrix, &report.output_data, &mut report.input_data).await;
             }
             ViaCommand::EepromReset => {
                 warn!("Resetting storage..");
@@ -249,7 +272,7 @@ impl<'a> VialService<'a> {
     }
 }
 
-impl VialService<'_> {
+impl<RgbMatrix: rgb_matrix::ViaRgbMatrixControl> VialService<'_, RgbMatrix> {
     /// Drive one Vial session against `rx`/`tx` (32-byte request → 32-byte
     /// response, processed in place). Returns on any read/write error;
     /// transport-specific reconnect lives in the caller.
@@ -304,6 +327,38 @@ mod tests {
         }
     }
 
+    #[test]
+    fn advertises_channel_qualified_custom_value_protocol() {
+        with_service(|service| {
+            let mut output_data = [0u8; 32];
+            output_data[0] = ViaCommand::GetProtocolVersion as u8;
+            let mut report = ViaReport {
+                input_data: output_data,
+                output_data,
+            };
+            block_on(service.process_via_packet(&mut report));
+            assert_eq!(BigEndian::read_u16(&report.input_data[1..3]), 0x000B);
+        });
+    }
+
+    #[test]
+    fn unbound_service_does_not_claim_rgb_matrix_or_save_support() {
+        with_service(|service| {
+            for command in [ViaCommand::CustomGetValue, ViaCommand::CustomSave] {
+                let mut output_data = [0u8; 32];
+                output_data[0] = command as u8;
+                output_data[1] = rgb_matrix::CHANNEL;
+                output_data[2] = 1;
+                let mut report = ViaReport {
+                    input_data: output_data,
+                    output_data,
+                };
+                block_on(service.process_via_packet(&mut report));
+                assert_eq!(report.input_data[0], ViaCommand::Unhandled as u8);
+            }
+        });
+    }
+
     // `output_data` is [u8; 32], so the handler slices `output_data[4..4 + size]`.
     // size == 28 is the largest payload that fits (writes output_data[4..32]).
     #[test]
diff --git a/rmk/src/host/via/rgb_matrix.rs b/rmk/src/host/via/rgb_matrix.rs
new file mode 100644
index 000000000..c18dca989
--- /dev/null
+++ b/rmk/src/host/via/rgb_matrix.rs
@@ -0,0 +1,486 @@
+//! VIA Protocol 11 RGB Matrix compatibility over RMK's designated background.
+//!
+//! This is only a protocol adapter. It does not own a renderer or lighting
+//! state: live controls are translated into atomic commands sent to the
+//! authoritative lighting engine.
+
+pub const CHANNEL: u8 = 3;
+
+const COMMAND_SET: u8 = 0x07;
+const COMMAND_GET: u8 = 0x08;
+const COMMAND_SAVE: u8 = 0x09;
+const COMMAND_UNHANDLED: u8 = 0xFF;
+
+const VALUE_BRIGHTNESS: u8 = 1;
+const VALUE_EFFECT: u8 = 2;
+const VALUE_SPEED: u8 = 3;
+const VALUE_COLOR: u8 = 4;
+
+const EFFECT_OFF: u8 = 0;
+const EFFECT_SOLID: u8 = 1;
+const EFFECT_BREATHE: u8 = 5;
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum BackgroundMode {
+    Solid,
+    Breathe,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct BackgroundState {
+    pub enabled: bool,
+    pub hue: u8,
+    pub saturation: u8,
+    pub value: u8,
+    pub speed: u8,
+    pub mode: BackgroundMode,
+}
+
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct BackgroundPatch {
+    pub enabled: Option<bool>,
+    pub hue: Option<u8>,
+    pub saturation: Option<u8>,
+    pub value: Option<u8>,
+    pub speed: Option<u8>,
+    pub mode: Option<BackgroundMode>,
+}
+
+/// Authoritative control port used by the pure VIA packet adapter.
+///
+/// `patch_background` must apply the patch atomically. A save may report
+/// success only after a durable backend confirms the correlated operation.
+#[allow(async_fn_in_trait)]
+pub trait ViaRgbMatrixControl {
+    type Error;
+
+    async fn read_background(&self) -> Result<BackgroundState, Self::Error>;
+    async fn patch_background(&self, patch: BackgroundPatch) -> Result<BackgroundState, Self::Error>;
+    async fn save_background(&self) -> Result<(), Self::Error>;
+}
+
+/// Default for a Vial service that was not explicitly bound to lighting.
+#[derive(Copy, Clone, Debug, Default)]
+pub struct Unsupported;
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct UnsupportedError;
+
+impl ViaRgbMatrixControl for Unsupported {
+    type Error = UnsupportedError;
+
+    async fn read_background(&self) -> Result<BackgroundState, Self::Error> {
+        Err(UnsupportedError)
+    }
+
+    async fn patch_background(&self, _patch: BackgroundPatch) -> Result<BackgroundState, Self::Error> {
+        Err(UnsupportedError)
+    }
+
+    async fn save_background(&self) -> Result<(), Self::Error> {
+        Err(UnsupportedError)
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+enum Value {
+    Brightness,
+    Effect,
+    Speed,
+    Color,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+enum Operation {
+    Get(Value),
+    Patch(BackgroundPatch),
+    Save,
+}
+
+fn value(value: u8) -> Result<Value, ()> {
+    match value {
+        VALUE_BRIGHTNESS => Ok(Value::Brightness),
+        VALUE_EFFECT => Ok(Value::Effect),
+        VALUE_SPEED => Ok(Value::Speed),
+        VALUE_COLOR => Ok(Value::Color),
+        _ => Err(()),
+    }
+}
+
+fn parse(request: &[u8]) -> Result<Operation, ()> {
+    let command = *request.first().ok_or(())?;
+    if request.get(1).copied() != Some(CHANNEL) {
+        return Err(());
+    }
+
+    match command {
+        COMMAND_GET => Ok(Operation::Get(value(*request.get(2).ok_or(())?)?)),
+        COMMAND_SAVE => Ok(Operation::Save),
+        COMMAND_SET => {
+            let selected = value(*request.get(2).ok_or(())?)?;
+            let first = *request.get(3).ok_or(())?;
+            let patch = match selected {
+                Value::Brightness => BackgroundPatch {
+                    value: Some(first),
+                    ..BackgroundPatch::default()
+                },
+                Value::Effect => match first {
+                    EFFECT_OFF => BackgroundPatch {
+                        enabled: Some(false),
+                        ..BackgroundPatch::default()
+                    },
+                    EFFECT_SOLID => BackgroundPatch {
+                        enabled: Some(true),
+                        mode: Some(BackgroundMode::Solid),
+                        ..BackgroundPatch::default()
+                    },
+                    EFFECT_BREATHE => BackgroundPatch {
+                        enabled: Some(true),
+                        mode: Some(BackgroundMode::Breathe),
+                        ..BackgroundPatch::default()
+                    },
+                    _ => return Err(()),
+                },
+                Value::Speed => BackgroundPatch {
+                    speed: Some(first),
+                    ..BackgroundPatch::default()
+                },
+                Value::Color => BackgroundPatch {
+                    hue: Some(first),
+                    saturation: Some(*request.get(4).ok_or(())?),
+                    ..BackgroundPatch::default()
+                },
+            };
+            Ok(Operation::Patch(patch))
+        }
+        _ => Err(()),
+    }
+}
+
+fn write_value(response: &mut [u8], value: Value, state: BackgroundState) -> Result<(), ()> {
+    match value {
+        Value::Brightness => *response.get_mut(3).ok_or(())? = state.value,
+        Value::Effect => {
+            *response.get_mut(3).ok_or(())? = if !state.enabled {
+                EFFECT_OFF
+            } else {
+                match state.mode {
+                    BackgroundMode::Solid => EFFECT_SOLID,
+                    BackgroundMode::Breathe => EFFECT_BREATHE,
+                }
+            };
+        }
+        Value::Speed => *response.get_mut(3).ok_or(())? = state.speed,
+        Value::Color => {
+            let data = response.get_mut(3..5).ok_or(())?;
+            data[0] = state.hue;
+            data[1] = state.saturation;
+        }
+    }
+    Ok(())
+}
+
+async fn handle<C: ViaRgbMatrixControl>(control: &C, request: &[u8], response: &mut [u8]) -> Result<(), ()> {
+    match parse(request)? {
+        Operation::Get(value) => {
+            let state = control.read_background().await.map_err(|_| ())?;
+            write_value(response, value, state)
+        }
+        Operation::Patch(patch) => {
+            control.patch_background(patch).await.map_err(|_| ())?;
+            Ok(())
+        }
+        Operation::Save => control.save_background().await.map_err(|_| ()),
+    }
+}
+
+/// Process one custom-value packet. Unsupported operations and failed control
+/// requests return VIA's unhandled marker without an adapter-side fallback.
+pub async fn process_packet<C: ViaRgbMatrixControl>(control: &C, request: &[u8], response: &mut [u8]) {
+    if handle(control, request, response).await.is_err()
+        && let Some(command) = response.first_mut()
+    {
+        *command = COMMAND_UNHANDLED;
+    }
+}
+
+#[cfg(feature = "lighting")]
+mod standard_control {
+    use super::{
+        BackgroundMode as ViaMode, BackgroundPatch as ViaPatch, BackgroundState as ViaState, ViaRgbMatrixControl,
+    };
+    use crate::lighting::processor::LightingMailbox;
+    use crate::lighting::standard::{BackgroundMode, BackgroundPatch, StandardCommand, StandardError, StandardState};
+
+    /// Mailbox-backed live control. Persistence remains unavailable until RMK
+    /// has a correlated durable completion path.
+    pub struct StandardControl<'a, const OVERLAY_CAP: usize, const MAILBOX_CAP: usize> {
+        mailbox: &'a LightingMailbox<StandardCommand<OVERLAY_CAP>, StandardState, StandardError, MAILBOX_CAP>,
+    }
+
+    impl<'a, const OVERLAY_CAP: usize, const MAILBOX_CAP: usize> StandardControl<'a, OVERLAY_CAP, MAILBOX_CAP> {
+        pub const fn new(
+            mailbox: &'a LightingMailbox<StandardCommand<OVERLAY_CAP>, StandardState, StandardError, MAILBOX_CAP>,
+        ) -> Self {
+            Self { mailbox }
+        }
+    }
+
+    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
+    pub enum Error {
+        Lighting(StandardError),
+        PersistenceUnavailable,
+    }
+
+    fn state(state: StandardState) -> ViaState {
+        ViaState {
+            enabled: state.background.enabled,
+            hue: state.background.hue,
+            saturation: state.background.saturation,
+            value: state.background.value,
+            speed: state.background.speed,
+            mode: match state.background.mode {
+                BackgroundMode::Solid => ViaMode::Solid,
+                BackgroundMode::Breathe => ViaMode::Breathe,
+            },
+        }
+    }
+
+    fn patch(patch: ViaPatch) -> BackgroundPatch {
+        BackgroundPatch {
+            enabled: patch.enabled,
+            hue: patch.hue,
+            saturation: patch.saturation,
+            value: patch.value,
+            speed: patch.speed,
+            mode: patch.mode.map(|mode| match mode {
+                ViaMode::Solid => BackgroundMode::Solid,
+                ViaMode::Breathe => BackgroundMode::Breathe,
+            }),
+        }
+    }
+
+    impl<const OVERLAY_CAP: usize, const MAILBOX_CAP: usize> ViaRgbMatrixControl
+        for StandardControl<'_, OVERLAY_CAP, MAILBOX_CAP>
+    {
+        type Error = Error;
+
+        async fn read_background(&self) -> Result<ViaState, Self::Error> {
+            self.mailbox
+                .request(StandardCommand::ReadState)
+                .await
+                .map(state)
+                .map_err(Error::Lighting)
+        }
+
+        async fn patch_background(&self, update: ViaPatch) -> Result<ViaState, Self::Error> {
+            self.mailbox
+                .request(StandardCommand::PatchBackground(patch(update)))
+                .await
+                .map(state)
+                .map_err(Error::Lighting)
+        }
+
+        async fn save_background(&self) -> Result<(), Self::Error> {
+            Err(Error::PersistenceUnavailable)
+        }
+    }
+}
+
+#[cfg(feature = "lighting")]
+pub use standard_control::StandardControl;
+
+#[cfg(test)]
+mod tests {
+    use core::cell::{Cell, RefCell};
+
+    use embassy_futures::block_on;
+
+    use super::*;
+
+    struct FakeControl {
+        state: RefCell<BackgroundState>,
+        patches: Cell<u8>,
+        saves: Cell<u8>,
+        save_supported: bool,
+    }
+
+    impl FakeControl {
+        fn new(state: BackgroundState) -> Self {
+            Self {
+                state: RefCell::new(state),
+                patches: Cell::new(0),
+                saves: Cell::new(0),
+                save_supported: false,
+            }
+        }
+
+        fn with_save(mut self) -> Self {
+            self.save_supported = true;
+            self
+        }
+    }
+
+    fn apply(patch: BackgroundPatch, state: &mut BackgroundState) {
+        if let Some(value) = patch.enabled {
+            state.enabled = value;
+        }
+        if let Some(value) = patch.hue {
+            state.hue = value;
+        }
+        if let Some(value) = patch.saturation {
+            state.saturation = value;
+        }
+        if let Some(value) = patch.value {
+            state.value = value;
+        }
+        if let Some(value) = patch.speed {
+            state.speed = value;
+        }
+        if let Some(value) = patch.mode {
+            state.mode = value;
+        }
+    }
+
+    impl ViaRgbMatrixControl for FakeControl {
+        type Error = ();
+
+        async fn read_background(&self) -> Result<BackgroundState, Self::Error> {
+            Ok(*self.state.borrow())
+        }
+
+        async fn patch_background(&self, patch: BackgroundPatch) -> Result<BackgroundState, Self::Error> {
+            self.patches.set(self.patches.get() + 1);
+            apply(patch, &mut self.state.borrow_mut());
+            Ok(*self.state.borrow())
+        }
+
+        async fn save_background(&self) -> Result<(), Self::Error> {
+            if !self.save_supported {
+                return Err(());
+            }
+            self.saves.set(self.saves.get() + 1);
+            Ok(())
+        }
+    }
+
+    fn initial() -> BackgroundState {
+        BackgroundState {
+            enabled: true,
+            hue: 11,
+            saturation: 22,
+            value: 33,
+            speed: 44,
+            mode: BackgroundMode::Breathe,
+        }
+    }
+
+    fn packet(command: u8, value: u8, first: u8, second: u8) -> [u8; 32] {
+        let mut packet = [0; 32];
+        packet[..5].copy_from_slice(&[command, CHANNEL, value, first, second]);
+        packet
+    }
+
+    fn process(control: &impl ViaRgbMatrixControl, request: [u8; 32]) -> [u8; 32] {
+        let mut response = request;
+        block_on(process_packet(control, &request, &mut response));
+        response
+    }
+
+    #[test]
+    fn set_values_apply_atomic_patches_and_preserve_other_fields() {
+        let control = FakeControl::new(initial());
+        process(&control, packet(COMMAND_SET, VALUE_BRIGHTNESS, 99, 0));
+        process(&control, packet(COMMAND_SET, VALUE_SPEED, 88, 0));
+        process(&control, packet(COMMAND_SET, VALUE_COLOR, 77, 66));
+
+        assert_eq!(control.patches.get(), 3);
+        assert_eq!(
+            *control.state.borrow(),
+            BackgroundState {
+                enabled: true,
+                hue: 77,
+                saturation: 66,
+                value: 99,
+                speed: 88,
+                mode: BackgroundMode::Breathe,
+            }
+        );
+    }
+
+    #[test]
+    fn off_preserves_mode_and_supported_effects_enable_atomically() {
+        let control = FakeControl::new(initial());
+        process(&control, packet(COMMAND_SET, VALUE_EFFECT, EFFECT_OFF, 0));
+        assert!(!control.state.borrow().enabled);
+        assert_eq!(control.state.borrow().mode, BackgroundMode::Breathe);
+
+        process(&control, packet(COMMAND_SET, VALUE_EFFECT, EFFECT_SOLID, 0));
+        assert!(control.state.borrow().enabled);
+        assert_eq!(control.state.borrow().mode, BackgroundMode::Solid);
+
+        process(&control, packet(COMMAND_SET, VALUE_EFFECT, EFFECT_BREATHE, 0));
+        assert!(control.state.borrow().enabled);
+        assert_eq!(control.state.borrow().mode, BackgroundMode::Breathe);
+    }
+
+    #[test]
+    fn get_values_return_via_wire_ids_and_data() {
+        let control = FakeControl::new(initial());
+        assert_eq!(process(&control, packet(COMMAND_GET, VALUE_BRIGHTNESS, 0, 0))[3], 33);
+        assert_eq!(
+            process(&control, packet(COMMAND_GET, VALUE_EFFECT, 0, 0))[3],
+            EFFECT_BREATHE
+        );
+        assert_eq!(process(&control, packet(COMMAND_GET, VALUE_SPEED, 0, 0))[3], 44);
+        assert_eq!(
+            &process(&control, packet(COMMAND_GET, VALUE_COLOR, 0, 0))[3..5],
+            &[11, 22]
+        );
+    }
+
+    #[test]
+    fn unsupported_operations_are_unhandled_without_mutation() {
+        let control = FakeControl::new(initial());
+        let before = *control.state.borrow();
+        let mut wrong_channel = packet(COMMAND_SET, VALUE_BRIGHTNESS, 1, 0);
+        wrong_channel[1] = 2;
+        for request in [
+            wrong_channel,
+            packet(COMMAND_SET, 99, 1, 0),
+            packet(COMMAND_SET, VALUE_EFFECT, 2, 0),
+        ] {
+            assert_eq!(process(&control, request)[0], COMMAND_UNHANDLED);
+        }
+        assert_eq!(control.patches.get(), 0);
+        assert_eq!(*control.state.borrow(), before);
+    }
+
+    #[test]
+    fn save_is_honest_about_persistence_capability() {
+        let unsupported = FakeControl::new(initial());
+        assert_eq!(
+            process(&unsupported, packet(COMMAND_SAVE, 0, 0, 0))[0],
+            COMMAND_UNHANDLED
+        );
+        assert_eq!(unsupported.saves.get(), 0);
+
+        let supported = FakeControl::new(initial()).with_save();
+        assert_eq!(process(&supported, packet(COMMAND_SAVE, 0, 0, 0))[0], COMMAND_SAVE);
+        assert_eq!(supported.saves.get(), 1);
+    }
+
+    #[cfg(feature = "lighting")]
+    #[test]
+    fn standard_mailbox_control_does_not_claim_persistence() {
+        use crate::lighting::processor::LightingMailbox;
+        use crate::lighting::standard::{StandardCommand, StandardError, StandardState};
+
+        let mailbox = LightingMailbox::<StandardCommand<1>, StandardState, StandardError, 1>::new();
+        let control = StandardControl::new(&mailbox);
+        assert_eq!(
+            block_on(control.save_background()),
+            Err(standard_control::Error::PersistenceUnavailable)
+        );
+    }
+}

From 424213e0616afca02088694e0c440cc9c4c6505c Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 10:38:39 -0700
Subject: [PATCH 05/78] fix(lighting): reserve processor event subscriptions

---
 rmk-config/src/default_config/subscriber_default.toml | 10 ++++++++++
 rmk-config/src/resolved/build_constants.rs            |  5 +++--
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/rmk-config/src/default_config/subscriber_default.toml b/rmk-config/src/default_config/subscriber_default.toml
index e9182c264..857aabaff 100644
--- a/rmk-config/src/default_config/subscriber_default.toml
+++ b/rmk-config/src/default_config/subscriber_default.toml
@@ -95,6 +95,16 @@ events = [
     { name = "lighting_changed" },
 ]
 
+[[subscriber]]
+features = ["lighting"]
+events = [
+    # lighting/processor.rs: LightingProcessor subscribes to authoritative
+    # keyboard-state invalidations on every lighting-enabled board.
+    { name = "layer_change" },
+    { name = "led_indicator" },
+    { name = "sleep_state" },
+]
+
 # --- Split-gated internal subscribers ---
 
 [[subscriber]]
diff --git a/rmk-config/src/resolved/build_constants.rs b/rmk-config/src/resolved/build_constants.rs
index 3274333b9..bbeb024a2 100644
--- a/rmk-config/src/resolved/build_constants.rs
+++ b/rmk-config/src/resolved/build_constants.rs
@@ -277,8 +277,9 @@ mod tests {
             .find(|event| event.name == "led_indicator")
             .unwrap();
 
-        // Three indicator processors, the display, two split peripherals, and USB/BLE Rynk sessions.
-        assert_eq!(led_indicator.subs, 8);
+        // Three indicator processors, the display, two split peripherals,
+        // USB/BLE Rynk sessions, and the lighting processor.
+        assert_eq!(led_indicator.subs, 9);
 
         let lighting_changed = constants
             .events

From 1354e662e69de5b71c5844909dc84e4205d368e7 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 10:42:27 -0700
Subject: [PATCH 06/78] fix(lighting): use const-safe slot assertion

---
 rmk/src/lighting/topology.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rmk/src/lighting/topology.rs b/rmk/src/lighting/topology.rs
index 35b8be357..612daede3 100644
--- a/rmk/src/lighting/topology.rs
+++ b/rmk/src/lighting/topology.rs
@@ -14,7 +14,7 @@ pub struct LedSlot(pub u16);
 
 impl LedSlot {
     pub const fn from_index(index: usize) -> Self {
-        assert!(index <= u16::MAX as usize, "LED slot exceeds u16 capacity");
+        core::assert!(index <= u16::MAX as usize, "LED slot exceeds u16 capacity");
         Self(index as u16)
     }
 

From 21731f4f3d97fe43cad5e684083f5bf3f4ce1a33 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 15:12:25 -0700
Subject: [PATCH 07/78] style(lighting): apply repository formatting

---
 rmk-config/src/resolved/lighting.rs | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/rmk-config/src/resolved/lighting.rs b/rmk-config/src/resolved/lighting.rs
index 30f9a9eab..36c7c0c3f 100644
--- a/rmk-config/src/resolved/lighting.rs
+++ b/rmk-config/src/resolved/lighting.rs
@@ -1,9 +1,8 @@
 use std::collections::{HashMap, HashSet};
 
-use crate::{LightingBackgroundModeToml, LightingEffectTomlConfig, LightingTargetTomlConfig};
-
 use super::Keymap;
 use super::layout::{FixedPoint3, Layout};
+use crate::{LightingBackgroundModeToml, LightingEffectTomlConfig, LightingTargetTomlConfig};
 
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct LightingKey {

From 2a59f6b5d6dbf53743933dd998007ce4a1076da8 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 20:44:03 -0700
Subject: [PATCH 08/78] feat(lighting): support split renderer replicas

---
 rmk-macro/src/codegen/lighting.rs         |  67 +++--
 rmk-macro/src/codegen/split/peripheral.rs |  12 +
 rmk/src/host/rynk/lighting.rs             |   1 +
 rmk/src/lighting/mod.rs                   |   5 +-
 rmk/src/lighting/source.rs                |  13 +
 rmk/src/lighting/standard.rs              | 316 +++++++++++++++++++++-
 rmk/src/split/peripheral.rs               |   3 +
 rmk/src/split_app.rs                      |   7 +-
 8 files changed, 384 insertions(+), 40 deletions(-)

diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
index 74763cee2..9f829e60d 100644
--- a/rmk-macro/src/codegen/lighting.rs
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -128,6 +128,43 @@ pub(crate) fn expand_lighting_topology(lighting: Option<&Lighting>) -> TokenStre
         }
     });
     let route_count = lighting.routes.len();
+    let renderer_config = expand_lighting_renderer_config(Some(lighting));
+
+    quote! {
+        pub const LIGHTING_TOPOLOGY_REVISION: u32 = #revision;
+        pub const LIGHTING_LED_COUNT: usize = #led_count;
+        pub static LIGHTING_KEYS: [::rmk::lighting::topology::MatrixPosition; #key_count] = [#(#keys),*];
+        pub static LIGHTING_ZONES: [::rmk::lighting::topology::ZoneMetadata<'static>; #zone_count] = [#(#zones),*];
+        pub static LIGHTING_EMITTERS: [::rmk::lighting::topology::LedMetadata; #led_count] = [#(#emitters),*];
+        pub static LIGHTING_ZONE_MEMBERSHIPS: [::rmk::lighting::topology::ZoneId; #membership_count] = [#(#memberships),*];
+        pub static LIGHTING_OUTPUTS: [::rmk::lighting::topology::OutputMetadata; #output_count] = [#(#outputs),*];
+        pub static LIGHTING_ROUTES: [::rmk::lighting::topology::PhysicalRoute; #route_count] = [#(#routes),*];
+        pub const LIGHTING_TOPOLOGY: ::rmk::lighting::topology::LightingTopology<'static> =
+            ::rmk::lighting::topology::LightingTopology {
+                matrix: ::rmk::lighting::topology::MatrixSize::new(#rows, #cols),
+                keys: &LIGHTING_KEYS,
+                physical_layout: PHYSICAL_LAYOUT,
+                leds: &LIGHTING_EMITTERS,
+                zones: &LIGHTING_ZONES,
+                zone_memberships: &LIGHTING_ZONE_MEMBERSHIPS,
+            };
+        pub const LIGHTING_ROUTING: ::rmk::lighting::topology::LightingRouting<'static> =
+            ::rmk::lighting::topology::LightingRouting {
+                outputs: &LIGHTING_OUTPUTS,
+                routes: &LIGHTING_ROUTES,
+            };
+
+        #renderer_config
+    }
+}
+
+/// Generate the semantic configuration required by a local renderer. Split
+/// peripherals do not need the central's host-facing topology and routing,
+/// but they do need the same built-in scenes and background configuration.
+pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> TokenStream2 {
+    let Some(lighting) = lighting else {
+        return TokenStream2::new();
+    };
     let layer_scene_cells = lighting.layer_scenes.iter().enumerate().map(|(index, scene)| {
         let name = quote::format_ident!("LIGHTING_LAYER_SCENE_{index}_CELLS");
         let cells = scene.cells.iter().map(expand_scene_cell);
@@ -164,29 +201,6 @@ pub(crate) fn expand_lighting_topology(lighting: Option<&Lighting>) -> TokenStre
     };
 
     quote! {
-        pub const LIGHTING_TOPOLOGY_REVISION: u32 = #revision;
-        pub const LIGHTING_LED_COUNT: usize = #led_count;
-        pub static LIGHTING_KEYS: [::rmk::lighting::topology::MatrixPosition; #key_count] = [#(#keys),*];
-        pub static LIGHTING_ZONES: [::rmk::lighting::topology::ZoneMetadata<'static>; #zone_count] = [#(#zones),*];
-        pub static LIGHTING_EMITTERS: [::rmk::lighting::topology::LedMetadata; #led_count] = [#(#emitters),*];
-        pub static LIGHTING_ZONE_MEMBERSHIPS: [::rmk::lighting::topology::ZoneId; #membership_count] = [#(#memberships),*];
-        pub static LIGHTING_OUTPUTS: [::rmk::lighting::topology::OutputMetadata; #output_count] = [#(#outputs),*];
-        pub static LIGHTING_ROUTES: [::rmk::lighting::topology::PhysicalRoute; #route_count] = [#(#routes),*];
-        pub const LIGHTING_TOPOLOGY: ::rmk::lighting::topology::LightingTopology<'static> =
-            ::rmk::lighting::topology::LightingTopology {
-                matrix: ::rmk::lighting::topology::MatrixSize::new(#rows, #cols),
-                keys: &LIGHTING_KEYS,
-                physical_layout: PHYSICAL_LAYOUT,
-                leds: &LIGHTING_EMITTERS,
-                zones: &LIGHTING_ZONES,
-                zone_memberships: &LIGHTING_ZONE_MEMBERSHIPS,
-            };
-        pub const LIGHTING_ROUTING: ::rmk::lighting::topology::LightingRouting<'static> =
-            ::rmk::lighting::topology::LightingRouting {
-                outputs: &LIGHTING_OUTPUTS,
-                routes: &LIGHTING_ROUTES,
-            };
-
         #(#layer_scene_cells)*
         pub static LIGHTING_LAYER_SCENE_TABLE:
             [::rmk::lighting::LayerScene<'static, ::rmk::lighting::BuiltinEffect>; #layer_scene_count] =
@@ -396,10 +410,17 @@ mod tests {
         assert!(topology.contains("enabled : false"));
         assert!(topology.contains("hue : 11u8"));
         assert!(topology.contains("mode : :: rmk :: lighting :: BackgroundMode :: Breathe"));
+
+        let renderer = expand_lighting_renderer_config(Some(&lighting)).to_string();
+        assert!(renderer.contains("LIGHTING_LAYER_SCENES"));
+        assert!(renderer.contains("LIGHTING_BACKGROUND"));
+        assert!(!renderer.contains("LIGHTING_TOPOLOGY"));
+        assert!(!renderer.contains("LIGHTING_ROUTING"));
     }
 
     #[test]
     fn omits_all_lighting_symbols_without_resolved_lighting() {
         assert!(expand_lighting_topology(None).is_empty());
+        assert!(expand_lighting_renderer_config(None).is_empty());
     }
 }
diff --git a/rmk-macro/src/codegen/split/peripheral.rs b/rmk-macro/src/codegen/split/peripheral.rs
index 67f413a07..8da1f57a7 100644
--- a/rmk-macro/src/codegen/split/peripheral.rs
+++ b/rmk-macro/src/codegen/split/peripheral.rs
@@ -23,6 +23,7 @@ use crate::codegen::input_device::iqs5xx::{expand_iqs5xx_device, expand_iqs5xx_i
 use crate::codegen::input_device::pmw33xx::expand_pmw33xx_device;
 use crate::codegen::input_device::pmw3610::expand_pmw3610_device;
 use crate::codegen::keyboard_config::read_keyboard_toml_config;
+use crate::codegen::lighting::expand_lighting_renderer_config;
 use crate::codegen::matrix::{
     expand_bootmagic_check, expand_matrix_direct_pins, expand_matrix_input_output_pins,
 };
@@ -55,6 +56,16 @@ pub(crate) fn parse_split_peripheral_mod(
     let identity = toml_config
         .identity()
         .expect("failed to resolve identity config");
+    let keymap = toml_config
+        .keymap()
+        .expect("failed to resolve keymap config");
+    let layout = toml_config
+        .layout()
+        .expect("failed to resolve layout config");
+    let lighting = toml_config
+        .lighting(&layout, &keymap)
+        .expect("failed to resolve lighting config");
+    let lighting_renderer_config = expand_lighting_renderer_config(lighting.as_ref());
 
     let dfu_enabled =
         is_feature_enabled(&rmk_features, "dfu_rp") || is_feature_enabled(&rmk_features, "dfu_nrf");
@@ -108,6 +119,7 @@ pub(crate) fn parse_split_peripheral_mod(
 
     quote! {
         #device_config
+        #lighting_renderer_config
         #main_function_sig {
             // ::defmt::info!("RMK start!");
             #main_function
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 6b2bd30db..c9dd328d0 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -445,6 +445,7 @@ fn map_standard_error(error: StandardError, capacity: usize) -> LightingError {
         }
         StandardError::Overlay(error) => map_overlay_error(error, capacity),
         StandardError::DeadlineOverflow => LightingError::InvalidTtl,
+        StandardError::ReplicaSlot(_) => LightingError::Unsupported,
         StandardError::Render(_) => LightingError::Unsupported,
     }
 }
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index 79b4f5449..437762692 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -41,8 +41,9 @@ pub use source::{
     OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
 };
 pub use standard::{
-    BackgroundMode, BackgroundPatch, BackgroundState, EmptySource, OverlayBatch, OverlayCell, StandardCommand,
-    StandardError, StandardInput, StandardLightingEngine, StandardMutableState, StandardState, UniformBackground,
+    BackgroundMode, BackgroundPatch, BackgroundState, EmptySource, OverlayBatch, OverlayCell, ReplicaSlotError,
+    StandardCommand, StandardError, StandardInput, StandardLightingEngine, StandardMutableState, StandardReplicaSlot,
+    StandardReplicaState, StandardState, UniformBackground,
 };
 pub use topology::*;
 
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index 1a61d16dc..d958eb5f3 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -344,6 +344,19 @@ impl<E: Copy + Default, const CAP: usize> TtlOverlay<E, CAP> {
         self.entries.iter().filter(|entry| entry.active).count()
     }
 
+    /// Iterate the currently stored absolute updates in stable slot order.
+    ///
+    /// This is intentionally a read-only state boundary rather than an
+    /// encoding API. A board-level replication transport can take an atomic
+    /// engine snapshot, convert absolute expiries to remaining TTLs, and
+    /// choose its own bounded wire representation.
+    pub fn active_updates(&self) -> impl Iterator<Item = OverlayUpdate<E>> + '_ {
+        self.entries
+            .iter()
+            .filter(|entry| entry.active)
+            .map(|entry| entry.update)
+    }
+
     fn active_entry(&self, wanted: usize) -> &OverlayEntry<E> {
         self.entries
             .iter()
diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index 1e11a5552..02e2e2e70 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -5,11 +5,13 @@
 //! overlay, deterministic priority bands, output brightness, frame history,
 //! `LightAction` handling, and protocol-independent commands/readback.
 
+use core::cell::RefCell;
+use core::fmt;
 use core::num::NonZeroU32;
 
+use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
 use rmk_types::action::LightAction;
 
-use super::Rgb8;
 use super::compositor::{
     Compositor, Contribution, LightingSource, LogicalFrame, RenderError, RenderInput as SourceRenderInput,
 };
@@ -19,6 +21,8 @@ use super::output::BrightnessTransform;
 use super::service::{CommandResult, Invalidation, LightingEngine, RenderInput, RenderOutcome};
 use super::source::{LayerScenes, OverlayError, OverlayUpdate, TtlOverlay};
 use super::topology::LedSlot;
+use super::{LightingContext, Rgb8};
+use crate::RawMutex;
 
 /// Stable default priority bands. Equal-priority call order remains stable.
 pub mod priority {
@@ -248,6 +252,13 @@ pub enum StandardCommand<const OVERLAY_CAP: usize> {
         expected_revision: u32,
         batch: OverlayBatch<OVERLAY_CAP>,
     },
+    /// Atomically export all state needed by a renderer replica. The larger
+    /// snapshot moves through the referenced slot so it does not inflate
+    /// every element of the bounded command queue.
+    ExportReplica(&'static StandardReplicaSlot<OVERLAY_CAP>),
+    /// Atomically install a snapshot previously placed in the referenced
+    /// slot. Intended for a renderer replica, not a second authority.
+    ApplyReplica(&'static StandardReplicaSlot<OVERLAY_CAP>),
     ReadState,
 }
 
@@ -269,11 +280,87 @@ pub struct StandardState {
     pub overlay_len: usize,
 }
 
+/// Complete declarative state needed by a standard-engine renderer replica.
+///
+/// `sample_time_ms` is the authority's animation clock at snapshot time.
+/// Applying the snapshot anchors the replica's local monotonic clock to that
+/// value; subsequent animation frames are sampled locally without link
+/// traffic. Overlay TTLs are remaining lifetimes at the same instant.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct StandardReplicaState<const OVERLAY_CAP: usize> {
+    pub revision: u32,
+    pub mutable: StandardMutableState,
+    pub overlay: OverlayBatch<OVERLAY_CAP>,
+    pub context: LightingContext,
+    pub sample_time_ms: u64,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum ReplicaSlotError {
+    Busy,
+    Empty,
+}
+
+/// One statically allocated hand-off slot for a replica snapshot.
+///
+/// The lighting mailbox serializes access. Keeping the large snapshot out of
+/// [`StandardCommand`] prevents command-channel capacity from multiplying its
+/// RAM cost on small MCUs.
+pub struct StandardReplicaSlot<const OVERLAY_CAP: usize> {
+    value: BlockingMutex<RawMutex, RefCell<Option<StandardReplicaState<OVERLAY_CAP>>>>,
+}
+
+impl<const OVERLAY_CAP: usize> StandardReplicaSlot<OVERLAY_CAP> {
+    pub const fn new() -> Self {
+        Self {
+            value: BlockingMutex::new(RefCell::new(None)),
+        }
+    }
+
+    pub fn put(&self, state: StandardReplicaState<OVERLAY_CAP>) -> Result<(), ReplicaSlotError> {
+        self.value.lock(|value| {
+            let mut value = value.borrow_mut();
+            if value.is_some() {
+                Err(ReplicaSlotError::Busy)
+            } else {
+                *value = Some(state);
+                Ok(())
+            }
+        })
+    }
+
+    pub fn take(&self) -> Result<StandardReplicaState<OVERLAY_CAP>, ReplicaSlotError> {
+        self.value
+            .lock(|value| value.borrow_mut().take().ok_or(ReplicaSlotError::Empty))
+    }
+}
+
+impl<const OVERLAY_CAP: usize> Default for StandardReplicaSlot<OVERLAY_CAP> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<const OVERLAY_CAP: usize> fmt::Debug for StandardReplicaSlot<OVERLAY_CAP> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("StandardReplicaSlot").finish_non_exhaustive()
+    }
+}
+
+impl<const OVERLAY_CAP: usize> PartialEq for StandardReplicaSlot<OVERLAY_CAP> {
+    fn eq(&self, other: &Self) -> bool {
+        core::ptr::eq(self, other)
+    }
+}
+
+impl<const OVERLAY_CAP: usize> Eq for StandardReplicaSlot<OVERLAY_CAP> {}
+
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum StandardError {
     Render(RenderError),
     Overlay(OverlayError),
     DeadlineOverflow,
+    ReplicaSlot(ReplicaSlotError),
     RevisionConflict { expected: u32, current: u32 },
 }
 
@@ -289,6 +376,37 @@ impl From<OverlayError> for StandardError {
     }
 }
 
+impl From<ReplicaSlotError> for StandardError {
+    fn from(value: ReplicaSlotError) -> Self {
+        Self::ReplicaSlot(value)
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+struct AnimationClock {
+    local_anchor_ms: u64,
+    shared_anchor_ms: u64,
+}
+
+impl AnimationClock {
+    const fn local() -> Self {
+        Self {
+            local_anchor_ms: 0,
+            shared_anchor_ms: 0,
+        }
+    }
+
+    fn sample_time(self, local_now_ms: u64) -> u64 {
+        self.shared_anchor_ms
+            .saturating_add(local_now_ms.saturating_sub(self.local_anchor_ms))
+    }
+
+    fn anchor(&mut self, local_now_ms: u64, shared_now_ms: u64) {
+        self.local_anchor_ms = local_now_ms;
+        self.shared_anchor_ms = shared_now_ms;
+    }
+}
+
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct StandardInput(pub LightAction);
 
@@ -308,6 +426,7 @@ pub struct StandardLightingEngine<'scenes, Extension, Status, const N: usize, co
     layers: LayerScenes<'scenes, BuiltinEffect>,
     overlay: TtlOverlay<BuiltinEffect, OVERLAY_CAP>,
     status: Status,
+    animation_clock: AnimationClock,
     revision: u32,
     output_enabled: bool,
     output_brightness: u8,
@@ -329,6 +448,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize>
             layers,
             overlay: TtlOverlay::new(),
             status,
+            animation_clock: AnimationClock::local(),
             revision: 0,
             output_enabled: true,
             output_brightness: u8::MAX,
@@ -422,6 +542,75 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize>
         self.background.set_state(state.background);
     }
 
+    fn mutable_state(&self) -> StandardMutableState {
+        StandardMutableState {
+            output_enabled: self.output_enabled,
+            output_brightness: self.output_brightness,
+            background: self.background.state(),
+        }
+    }
+
+    fn replica_state<Context: LightingContextProvider>(
+        &self,
+        local_now_ms: u64,
+        context: &Context,
+    ) -> Result<StandardReplicaState<OVERLAY_CAP>, StandardError> {
+        let sample_time_ms = self.animation_clock.sample_time(local_now_ms);
+        let mut overlay = OverlayBatch::new();
+        for update in self.overlay.active_updates() {
+            let ttl_ms = match update.expires_ms {
+                Some(expires_ms) if expires_ms > sample_time_ms => {
+                    let remaining = expires_ms - sample_time_ms;
+                    Some(NonZeroU32::new(remaining.min(u32::MAX as u64) as u32).unwrap())
+                }
+                Some(_) => continue,
+                None => None,
+            };
+            overlay.push(OverlayCell {
+                slot: update.slot,
+                effect: update.effect,
+                ttl_ms,
+            })?;
+        }
+        Ok(StandardReplicaState {
+            revision: self.revision,
+            mutable: self.mutable_state(),
+            overlay,
+            context: *context.lighting_context(),
+            sample_time_ms,
+        })
+    }
+
+    fn apply_replica(
+        &mut self,
+        local_now_ms: u64,
+        replica: StandardReplicaState<OVERLAY_CAP>,
+    ) -> Result<(), StandardError> {
+        let mut updates = [OverlayUpdate {
+            slot: LedSlot(0),
+            effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+            expires_ms: None,
+        }; OVERLAY_CAP];
+        for (target, cell) in updates.iter_mut().zip(replica.overlay.as_slice().iter().copied()) {
+            *target = OverlayUpdate {
+                slot: cell.slot,
+                effect: cell.effect,
+                expires_ms: cell
+                    .ttl_ms
+                    .and_then(|ttl| replica.sample_time_ms.checked_add(ttl.get() as u64)),
+            };
+            if cell.ttl_ms.is_some() && target.expires_ms.is_none() {
+                return Err(StandardError::DeadlineOverflow);
+            }
+        }
+        self.overlay
+            .replace(replica.sample_time_ms, &updates[..replica.overlay.as_slice().len()])?;
+        self.set_mutable_state(replica.mutable);
+        self.revision = replica.revision;
+        self.animation_clock.anchor(local_now_ms, replica.sample_time_ms);
+        Ok(())
+    }
+
     fn expires_at(now_ms: u64, ttl_ms: Option<NonZeroU32>) -> Result<Option<u64>, StandardError> {
         ttl_ms
             .map(|ttl| {
@@ -467,8 +656,9 @@ where
         &mut self,
         now_ms: u64,
         command: Self::Command,
-        _snapshot: &Context,
+        snapshot: &Context,
     ) -> Result<CommandResult<Self::Reply>, Self::Error> {
+        let effect_now_ms = self.animation_clock.sample_time(now_ms);
         let (mut invalidation, advances_revision) = match command {
             StandardCommand::SetOutputEnabled(enabled) => {
                 self.output_enabled = enabled;
@@ -495,8 +685,8 @@ where
                 (Invalidation::Render, true)
             }
             StandardCommand::SetOverlay(cell) => {
-                let update = Self::overlay_update(now_ms, cell)?;
-                self.overlay.set(now_ms, update)?;
+                let update = Self::overlay_update(effect_now_ms, cell)?;
+                self.overlay.set(effect_now_ms, update)?;
                 (Invalidation::Render, true)
             }
             StandardCommand::SetOverlayIfRevision {
@@ -504,8 +694,8 @@ where
                 cell,
             } => {
                 self.check_revision(expected_revision)?;
-                let update = Self::overlay_update(now_ms, cell)?;
-                self.overlay.set(now_ms, update)?;
+                let update = Self::overlay_update(effect_now_ms, cell)?;
+                self.overlay.set(effect_now_ms, update)?;
                 (Invalidation::Render, true)
             }
             StandardCommand::UnsetOverlay(slot) => {
@@ -566,9 +756,10 @@ where
                     expires_ms: None,
                 }; OVERLAY_CAP];
                 for (target, cell) in updates.iter_mut().zip(batch.as_slice().iter().copied()) {
-                    *target = Self::overlay_update(now_ms, cell)?;
+                    *target = Self::overlay_update(effect_now_ms, cell)?;
                 }
-                self.overlay.replace(now_ms, &updates[..batch.as_slice().len()])?;
+                self.overlay
+                    .replace(effect_now_ms, &updates[..batch.as_slice().len()])?;
                 (Invalidation::Render, true)
             }
             StandardCommand::ReplaceOverlayIfRevision {
@@ -582,11 +773,20 @@ where
                     expires_ms: None,
                 }; OVERLAY_CAP];
                 for (target, cell) in updates.iter_mut().zip(batch.as_slice().iter().copied()) {
-                    *target = Self::overlay_update(now_ms, cell)?;
+                    *target = Self::overlay_update(effect_now_ms, cell)?;
                 }
-                self.overlay.replace(now_ms, &updates[..batch.as_slice().len()])?;
+                self.overlay
+                    .replace(effect_now_ms, &updates[..batch.as_slice().len()])?;
                 (Invalidation::Render, true)
             }
+            StandardCommand::ExportReplica(slot) => {
+                slot.put(self.replica_state(now_ms, snapshot)?)?;
+                (Invalidation::None, false)
+            }
+            StandardCommand::ApplyReplica(slot) => {
+                self.apply_replica(now_ms, slot.take()?)?;
+                (Invalidation::Render, false)
+            }
             StandardCommand::ReadState => (Invalidation::None, false),
         };
         if advances_revision {
@@ -603,8 +803,9 @@ where
         input: RenderInput<'_, Context>,
         frame: &mut Self::Frame,
     ) -> Result<RenderOutcome, Self::Error> {
+        let effect_now_ms = self.animation_clock.sample_time(input.now_ms);
         let overlay_len = self.overlay.active_len();
-        self.overlay.prune_expired(input.now_ms);
+        self.overlay.prune_expired(effect_now_ms);
         let state_changed = self.overlay.active_len() != overlay_len;
         if state_changed {
             self.advance_revision();
@@ -616,11 +817,12 @@ where
             layers,
             overlay,
             status,
+            animation_clock: _,
             output_enabled,
             output_brightness,
             revision: _,
         } = self;
-        let mut transaction = compositor.begin(input.now_ms, input.snapshot, Rgb8::BLACK, frame);
+        let mut transaction = compositor.begin(effect_now_ms, input.snapshot, Rgb8::BLACK, frame);
         transaction.apply(priority::BACKGROUND, background)?;
         transaction.apply(priority::EXTENSION, extension)?;
         transaction.apply(priority::LAYER, layers)?;
@@ -629,7 +831,7 @@ where
         let mut transform = BrightnessTransform::new(if *output_enabled { *output_brightness } else { 0 });
         let result = transaction.finish_with(&mut transform);
         let next_wake_in_ms = result.next_wake_ms.map(|deadline| {
-            let delay = deadline.saturating_sub(input.now_ms).clamp(1, u32::MAX as u64);
+            let delay = deadline.saturating_sub(effect_now_ms).clamp(1, u32::MAX as u64);
             NonZeroU32::new(delay as u32).expect("clamped delay is nonzero")
         });
         Ok(RenderOutcome {
@@ -709,6 +911,94 @@ mod tests {
         }
     }
 
+    #[test]
+    fn replica_snapshot_preserves_state_context_ttl_and_animation_phase() {
+        let mut authority = engine();
+        let authority_context = context(3);
+        authority
+            .handle_command(
+                100,
+                StandardCommand::SetBackground(BackgroundState {
+                    mode: BackgroundMode::Breathe,
+                    speed: 200,
+                    ..BackgroundState::default()
+                }),
+                &authority_context,
+            )
+            .unwrap();
+        authority
+            .handle_command(
+                100,
+                StandardCommand::SetOverlay(OverlayCell {
+                    slot: LedSlot(1),
+                    effect: BuiltinEffect::Solid { color: GREEN },
+                    ttl_ms: NonZeroU32::new(100),
+                }),
+                &authority_context,
+            )
+            .unwrap();
+
+        static EXPORT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+        authority
+            .handle_command(120, StandardCommand::ExportReplica(&EXPORT), &authority_context)
+            .unwrap();
+        let snapshot = EXPORT.take().unwrap();
+        assert_eq!(snapshot.context, authority_context);
+        assert_eq!(snapshot.sample_time_ms, 120);
+        assert_eq!(snapshot.overlay.as_slice()[0].ttl_ms, NonZeroU32::new(80));
+
+        let mut authority_frame = LogicalFrame::new(Rgb8::BLACK);
+        authority
+            .render(
+                RenderInput {
+                    now_ms: 136,
+                    snapshot: &authority_context,
+                },
+                &mut authority_frame,
+            )
+            .unwrap();
+
+        static APPLY: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+        APPLY.put(snapshot).unwrap();
+        let mut replica = engine();
+        replica
+            .handle_command(1_000, StandardCommand::ApplyReplica(&APPLY), &authority_context)
+            .unwrap();
+        let mut replica_frame = LogicalFrame::new(Rgb8::BLACK);
+        replica
+            .render(
+                RenderInput {
+                    now_ms: 1_016,
+                    snapshot: &snapshot.context,
+                },
+                &mut replica_frame,
+            )
+            .unwrap();
+
+        assert_eq!(replica.state().revision, snapshot.revision);
+        assert_eq!(replica_frame, authority_frame);
+    }
+
+    #[test]
+    fn replica_slot_rejects_overwrite_and_empty_take() {
+        let slot = StandardReplicaSlot::<2>::new();
+        let snapshot = StandardReplicaState {
+            revision: 1,
+            mutable: StandardMutableState {
+                output_enabled: true,
+                output_brightness: 42,
+                background: BackgroundState::default(),
+            },
+            overlay: OverlayBatch::new(),
+            context: context(0),
+            sample_time_ms: 9,
+        };
+        slot.put(snapshot).unwrap();
+        assert_eq!(slot.put(snapshot), Err(ReplicaSlotError::Busy));
+        assert_eq!(slot.take(), Ok(snapshot));
+        assert_eq!(slot.take(), Err(ReplicaSlotError::Empty));
+    }
+
     #[test]
     fn background_patch_preserves_unmentioned_fields() {
         let mut engine = engine();
diff --git a/rmk/src/split/peripheral.rs b/rmk/src/split/peripheral.rs
index 947462faf..9a839617b 100644
--- a/rmk/src/split/peripheral.rs
+++ b/rmk/src/split/peripheral.rs
@@ -15,6 +15,8 @@ use {
 
 use super::SplitMessage;
 use super::driver::{SplitReader, SplitWriter};
+#[cfg(feature = "_render_state")]
+use crate::event::SleepStateEvent;
 use crate::event::{
     KeyboardEvent, LayerChangeEvent, LedIndicatorEvent, PointingEvent, SubscribableEvent, publish_event,
 };
@@ -200,6 +202,7 @@ impl<S: SplitWriter + SplitReader> SplitPeripheral<S> {
                             #[cfg(feature = "_render_state")]
                             SplitMessage::SleepState(sleeping) => {
                                 crate::state::set_sleeping(sleeping);
+                                publish_event(SleepStateEvent::new(sleeping));
                             }
                             // --- dfu_split: firmware update handlers ---
                             #[cfg(feature = "dfu_split")]
diff --git a/rmk/src/split_app.rs b/rmk/src/split_app.rs
index 7dc37f3dd..4dcb5f95b 100644
--- a/rmk/src/split_app.rs
+++ b/rmk/src/split_app.rs
@@ -103,8 +103,11 @@ impl MaxSize for SplitAppData {
 
 /// Central → peripheral queue, drained by `PeripheralManager` while the link
 /// is up. Producers MUST use `try_send` (bounded, never block); capacity is
-/// sized so one full application resync burst fits with headroom.
-pub static SPLIT_APP_TX: Channel<RawMutex, SplitAppData, 26> = Channel::new();
+/// sized so one full application resync burst fits with headroom. Forty-eight
+/// entries admit a complete 40-cell semantic lighting snapshot (begin,
+/// context, one worst-case animated cell per packet, and commit). This is
+/// mutation/reconnect traffic, not rendered-frame streaming.
+pub static SPLIT_APP_TX: Channel<RawMutex, SplitAppData, 48> = Channel::new();
 
 /// This side's inbox of received application messages (peripheral: from the
 /// central's `SPLIT_APP_TX`; central: from the peripheral's

From 9d91e5ae0875492ab463effd49b66cebb339d55a Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Sun, 19 Jul 2026 22:23:20 -0700
Subject: [PATCH 09/78] fix(rynk): use HID for reliable USB transport

---
 rmk/src/host/mod.rs |   3 +-
 rmk/src/usb/rynk.rs | 171 ++++++++++++++++++++------------------------
 2 files changed, 78 insertions(+), 96 deletions(-)

diff --git a/rmk/src/host/mod.rs b/rmk/src/host/mod.rs
index 167d5ab7a..4eb4e70c6 100644
--- a/rmk/src/host/mod.rs
+++ b/rmk/src/host/mod.rs
@@ -7,11 +7,12 @@ pub(crate) mod lock;
 pub(crate) mod rynk;
 #[cfg(feature = "storage")]
 pub(crate) mod storage;
-// Shared transport-adapter error, used by the USB/BLE Vial and BLE Rynk
+// Shared transport-adapter error, used by the USB/BLE Vial and USB/BLE Rynk
 // adapters. Gated to exactly the feature combos that compile an adapter.
 #[cfg(any(
     all(feature = "vial", not(feature = "_no_usb")),
     all(feature = "vial", feature = "_ble"),
+    all(feature = "rynk", not(feature = "_no_usb")),
     all(feature = "rynk", feature = "_ble"),
 ))]
 pub(crate) mod transport;
diff --git a/rmk/src/usb/rynk.rs b/rmk/src/usb/rynk.rs
index 7b39ad216..5938c4de3 100644
--- a/rmk/src/usb/rynk.rs
+++ b/rmk/src/usb/rynk.rs
@@ -1,138 +1,119 @@
-//! Rynk over a vendor-specific USB bulk interface.
+//! Rynk over USB HID.
+//!
+//! Rynk frames are fragmented into the same fixed 32-byte reports used by
+//! Rynk's BLE WebHID transport. The frame header's length trims padding from
+//! the final report before the byte stream reaches `RynkService`.
 
-use embassy_usb::driver::{Driver, Endpoint, EndpointError, EndpointIn, EndpointOut};
-use embassy_usb::{Builder, msos};
+use embassy_usb::Builder;
+use embassy_usb::class::hid::{HidReader, HidWriter};
+use embassy_usb::driver::Driver;
 use embedded_io_async::{ErrorType, Read, Write};
-use rmk_types::protocol::rynk::{RYNK_USB_INTERFACE_CLASS, RYNK_USB_INTERFACE_PROTOCOL, RYNK_USB_INTERFACE_SUBCLASS};
+use rmk_types::protocol::rynk::{RYNK_HID_REPORT_SIZE, RynkHeader};
 
+use crate::hid::RynkHidReport;
 use crate::host::rynk::RynkService;
+use crate::host::transport::HostTransportError;
+use crate::usb::add_usb_reader_writer;
 
-#[cfg(feature = "_usb_high_speed")]
-const RYNK_USB_MAX_PACKET_SIZE: usize = 512;
-#[cfg(not(feature = "_usb_high_speed"))]
-const RYNK_USB_MAX_PACKET_SIZE: usize = 64;
+pub(crate) type HostUsbReader<D> = HidReader<'static, D, RYNK_HID_REPORT_SIZE>;
+pub(crate) type HostUsbWriter<D> = HidWriter<'static, D, RYNK_HID_REPORT_SIZE>;
 
-/// bRequest value Windows sends to fetch the MS OS 2.0 descriptor set.
-const MSOS_VENDOR_CODE: u8 = 0x52;
-
-/// GUID WinUSB registers the Rynk interface under; Windows hosts open the
-/// device node by it.
-const DEVICE_INTERFACE_GUID: &str = "{CE60F742-A8DB-43C4-8B97-7C41B43CD4AA}";
-
-pub(crate) struct HostUsbReader<D: Driver<'static>> {
-    ep: D::EndpointOut,
-    buf: [u8; RYNK_USB_MAX_PACKET_SIZE],
-    pos: usize,
-    len: usize,
-}
-
-/// Writer half of the Rynk USB transport.
-pub(crate) struct HostUsbWriter<D: Driver<'static>> {
-    ep: D::EndpointIn,
-}
-
-/// Build the Rynk vendor bulk interface and its WinUSB binding.
+/// Build the Rynk vendor-HID interface.
 pub fn build_host_usb<D: Driver<'static>>(builder: &mut Builder<'static, D>) -> (HostUsbReader<D>, HostUsbWriter<D>) {
-    builder.msos_descriptor(msos::windows_version::WIN8_1, MSOS_VENDOR_CODE);
-    let mut function = builder.function(
-        RYNK_USB_INTERFACE_CLASS,
-        RYNK_USB_INTERFACE_SUBCLASS,
-        RYNK_USB_INTERFACE_PROTOCOL,
-    );
-    function.msos_feature(msos::CompatibleIdFeatureDescriptor::new("WINUSB", ""));
-    function.msos_feature(msos::RegistryPropertyFeatureDescriptor::new(
-        "DeviceInterfaceGUIDs",
-        msos::PropertyData::RegMultiSz(&[DEVICE_INTERFACE_GUID]),
-    ));
-    let mut interface = function.interface();
-    let mut alt = interface.alt_setting(
-        RYNK_USB_INTERFACE_CLASS,
-        RYNK_USB_INTERFACE_SUBCLASS,
-        RYNK_USB_INTERFACE_PROTOCOL,
-        None,
-    );
-    let ep_out = alt.endpoint_bulk_out(None, RYNK_USB_MAX_PACKET_SIZE as u16);
-    let ep_in = alt.endpoint_bulk_in(None, RYNK_USB_MAX_PACKET_SIZE as u16);
-    (
-        HostUsbReader {
-            ep: ep_out,
-            buf: [0; RYNK_USB_MAX_PACKET_SIZE],
-            pos: 0,
-            len: 0,
-        },
-        HostUsbWriter { ep: ep_in },
-    )
+    add_usb_reader_writer!(builder, RynkHidReport, RYNK_HID_REPORT_SIZE, RYNK_HID_REPORT_SIZE, 32).split()
 }
 
-/// Rynk session loop
+/// Run one Rynk session for each USB connection.
 pub async fn run_host_usb<D: Driver<'static>>(
-    receiver: &mut HostUsbReader<D>,
-    sender: &mut HostUsbWriter<D>,
+    reader: &mut HostUsbReader<D>,
+    writer: &mut HostUsbWriter<D>,
     service: &RynkService<'_>,
 ) -> ! {
     loop {
-        receiver.ep.wait_enabled().await;
-        // A bus reset voids any half-consumed packet from the last session.
-        receiver.pos = 0;
-        receiver.len = 0;
-        service.run_session(receiver, sender).await;
+        reader.ready().await;
+        let mut rx = RynkUsbRx::new(&mut *reader);
+        let mut tx = RynkUsbTx { writer: &mut *writer };
+        service.run_session(&mut rx, &mut tx).await;
     }
 }
 
-impl<D: Driver<'static>> ErrorType for HostUsbReader<D> {
-    type Error = EndpointError;
+struct RynkUsbRx<'a, D: Driver<'static>> {
+    reader: &'a mut HostUsbReader<D>,
+    report: [u8; RYNK_HID_REPORT_SIZE],
+    pos: usize,
+    end: usize,
+    remaining: usize,
 }
 
-impl<D: Driver<'static>> Read for HostUsbReader<D> {
+impl<'a, D: Driver<'static>> RynkUsbRx<'a, D> {
+    fn new(reader: &'a mut HostUsbReader<D>) -> Self {
+        Self {
+            reader,
+            report: [0; RYNK_HID_REPORT_SIZE],
+            pos: 0,
+            end: 0,
+            remaining: 0,
+        }
+    }
+}
+
+impl<D: Driver<'static>> ErrorType for RynkUsbRx<'_, D> {
+    type Error = HostTransportError;
+}
+
+impl<D: Driver<'static>> Read for RynkUsbRx<'_, D> {
     async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error> {
         if buf.is_empty() {
             return Ok(0);
         }
         loop {
-            if self.pos < self.len {
-                let n = (self.len - self.pos).min(buf.len());
-                buf[..n].copy_from_slice(&self.buf[self.pos..self.pos + n]);
+            if self.pos < self.end {
+                let n = (self.end - self.pos).min(buf.len());
+                buf[..n].copy_from_slice(&self.report[self.pos..self.pos + n]);
                 self.pos += n;
                 return Ok(n);
             }
-            // Zero-length packets are transfer delimiters, not data — and not
-            // EOF, which is what returning `Ok(0)` would mean. Read on.
-            if buf.len() >= RYNK_USB_MAX_PACKET_SIZE {
-                let n = self.ep.read(buf).await?;
-                if n > 0 {
-                    return Ok(n);
-                }
-            } else {
-                self.pos = 0;
-                self.len = self.ep.read(&mut self.buf).await?;
+
+            let n = self
+                .reader
+                .read(&mut self.report)
+                .await
+                .map_err(|_| HostTransportError)?;
+            if self.remaining == 0 {
+                let Some(frame_len) = RynkHeader::peek_frame_len(&self.report[..n]) else {
+                    continue;
+                };
+                self.remaining = frame_len;
             }
+            self.pos = 0;
+            self.end = self.remaining.min(n);
+            self.remaining -= self.end;
         }
     }
 }
 
-impl<D: Driver<'static>> ErrorType for HostUsbWriter<D> {
-    type Error = EndpointError;
+struct RynkUsbTx<'a, D: Driver<'static>> {
+    writer: &'a mut HostUsbWriter<D>,
+}
+
+impl<D: Driver<'static>> ErrorType for RynkUsbTx<'_, D> {
+    type Error = HostTransportError;
 }
 
-/// Sends one frame per `write`, then a zero-length packet when the frame
-/// fills the last bulk-IN packet. A bulk IN transfer completes on the host
-/// only at a packet shorter than the max packet size, so a frame whose length
-/// is a multiple of it would otherwise hang the host read (hit at Full-Speed's
-/// 64-byte packets; masked at High-Speed's 512). `run_session` writes each
-/// frame with a single `write_all`, so `buf` is one whole frame.
-impl<D: Driver<'static>> Write for HostUsbWriter<D> {
+impl<D: Driver<'static>> Write for RynkUsbTx<'_, D> {
     async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error> {
-        for packet in buf.chunks(RYNK_USB_MAX_PACKET_SIZE) {
-            self.ep.write(packet).await?;
+        if buf.is_empty() {
+            return Ok(0);
         }
-        if !buf.is_empty() && buf.len().is_multiple_of(RYNK_USB_MAX_PACKET_SIZE) {
-            self.ep.write(&[]).await?;
+        for chunk in buf.chunks(RYNK_HID_REPORT_SIZE) {
+            let mut report = [0u8; RYNK_HID_REPORT_SIZE];
+            report[..chunk.len()].copy_from_slice(chunk);
+            self.writer.write(&report).await.map_err(|_| HostTransportError)?;
         }
         Ok(buf.len())
     }
 
     async fn flush(&mut self) -> Result<(), Self::Error> {
-        // `write` hands packets straight to the endpoint; nothing is buffered.
         Ok(())
     }
 }

From ddf9509a6fd3cc38178572ac9efb203683ba5284 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 16:08:42 -0700
Subject: [PATCH 10/78] feat(rynk): add application build info

---
 .../main/docs/development/rynk_protocol.md    | 47 +++++++++++
 rmk-types/src/protocol/rynk/command.rs        | 12 +--
 rmk-types/src/protocol/rynk/payload/system.rs | 33 +++++++-
 .../protocol/rynk/snapshots/wire_values.snap  |  1 +
 rmk-types/src/protocol/rynk/tests.rs          | 15 ++++
 rmk/src/host/mod.rs                           |  3 +
 rmk/src/host/rynk/handlers/system.rs          | 42 ++--------
 rmk/src/host/rynk/mod.rs                      | 81 +++++++++++++++----
 rynk/rynk-wasm/src/client.rs                  |  3 +-
 rynk/src/api.rs                               | 11 ++-
 10 files changed, 190 insertions(+), 58 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index d799c2ddd..a81fabea9 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -89,6 +89,53 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x090F` | `CommitLightingOverlayReplace` | `CommitLightingOverlayReplaceRequest` | `LightingStateResult`               | `lighting` |                                                                              |
 | `0x0910` | `AbortLightingOverlayReplace`  | `AbortLightingOverlayReplaceRequest`  | `LightingUnitResult`                | `lighting` |                                                                              |
 | `0x0911` | `GetLightingKeys`              | `LightingPageRequest`                 | `LightingKeysPageResult`            | `lighting` | Logical matrix keys are distinct from optional physical geometry.            |
+| CMD      | Name                  | Request                | Response                | Feature | Notes                                                                        |
+| -------- | --------------------- | ---------------------- | ----------------------- | ------- | ---------------------------------------------------------------------------- |
+| `0x0001` | `GetVersion`          | `()`                   | `ProtocolVersion`       |         |                                                                              |
+| `0x0002` | `GetCapabilities`     | `()`                   | `DeviceCapabilities`    |         |                                                                              |
+| `0x0003` | `Reboot`              | `()`                   | `()`                    |         |                                                                              |
+| `0x0004` | `BootloaderJump`      | `()`                   | `()`                    |         |                                                                              |
+| `0x0005` | `StorageReset`        | `StorageResetMode`     | `()`                    |         |                                                                              |
+| `0x0006` | `GetLockStatus`       | `()`                   | `LockStatus`            |         | Pure read of the current lock state — no side effects.                       |
+| `0x0007` | `UnlockPoll`          | `()`                   | `LockStatus`            |         | Arms/refreshes the unlock attempt and samples the held challenge keys.       |
+| `0x0008` | `Lock`                | `()`                   | `()`                    |         | Relock immediately.                                                          |
+| `0x0009` | `GetLayout`           | `u32`                  | `LayoutChunk`           |         | Get layout blob chunk. `u32` is the byte offset.                             |
+| `0x000A` | `GetDeviceInfo`       | `()`                   | `DeviceInfo`            |         | Identity strings and USB ids; feature gating stays in `GetCapabilities`.     |
+| `0x000B` | `GetBuildInfo`        | `()`                   | `BuildInfo`             |         | Application-defined diagnostic build label; never used for compatibility.    |
+| `0x0101` | `GetKeyAction`        | `KeyPosition`          | `KeyAction`             |         |                                                                              |
+| `0x0102` | `SetKeyAction`        | `SetKeyRequest`        | `()`                    |         |                                                                              |
+| `0x0103` | `GetDefaultLayer`     | `()`                   | `u8`                    |         |                                                                              |
+| `0x0104` | `SetDefaultLayer`     | `u8`                   | `()`                    |         |                                                                              |
+| `0x0105` | `GetEncoderAction`    | `GetEncoderRequest`    | `EncoderAction`         |         |                                                                              |
+| `0x0106` | `SetEncoderAction`    | `SetEncoderRequest`    | `()`                    |         |                                                                              |
+| `0x0107` | `GetKeymapBulk`       | `GetKeymapBulkRequest` | `GetKeymapBulkResponse` |         |                                                                              |
+| `0x0108` | `SetKeymapBulk`       | `SetKeymapBulkRequest` | `()`                    |         |                                                                              |
+| `0x0201` | `GetMacro`            | `GetMacroRequest`      | `MacroData`             |         |                                                                              |
+| `0x0202` | `SetMacro`            | `SetMacroRequest`      | `()`                    |         |                                                                              |
+| `0x0301` | `GetCombo`            | `u8`                   | `Combo`                 |         |                                                                              |
+| `0x0302` | `SetCombo`            | `SetComboRequest`      | `()`                    |         |                                                                              |
+| `0x0303` | `GetComboBulk`        | `GetComboBulkRequest`  | `GetComboBulkResponse`  |         |                                                                              |
+| `0x0304` | `SetComboBulk`        | `SetComboBulkRequest`  | `()`                    |         |                                                                              |
+| `0x0401` | `GetMorse`            | `u8`                   | `Morse`                 |         |                                                                              |
+| `0x0402` | `SetMorse`            | `SetMorseRequest`      | `()`                    |         |                                                                              |
+| `0x0403` | `GetMorseBulk`        | `GetMorseBulkRequest`  | `GetMorseBulkResponse`  |         |                                                                              |
+| `0x0404` | `SetMorseBulk`        | `SetMorseBulkRequest`  | `()`                    |         |                                                                              |
+| `0x0501` | `GetFork`             | `u8`                   | `Fork`                  |         |                                                                              |
+| `0x0502` | `SetFork`             | `SetForkRequest`       | `()`                    |         |                                                                              |
+| `0x0601` | `GetBehaviorConfig`   | `()`                   | `BehaviorConfig`        |         |                                                                              |
+| `0x0602` | `SetBehaviorConfig`   | `BehaviorConfig`       | `()`                    |         |                                                                              |
+| `0x0701` | `GetConnectionType`   | `()`                   | `ConnectionType`        |         |                                                                              |
+| `0x0702` | `GetConnectionStatus` | `()`                   | `ConnectionStatus`      |         | Full `ConnectionStatus` snapshot.                                            |
+| `0x0703` | `GetBleStatus`        | `()`                   | `BleStatus`             | `_ble`  |                                                                              |
+| `0x0704` | `SwitchBleProfile`    | `u8`                   | `()`                    | `_ble`  |                                                                              |
+| `0x0705` | `ClearBleProfile`     | `u8`                   | `()`                    | `_ble`  |                                                                              |
+| `0x0801` | `GetCurrentLayer`     | `()`                   | `u8`                    |         |                                                                              |
+| `0x0802` | `GetMatrixState`      | `()`                   | `MatrixState`           |         |                                                                              |
+| `0x0803` | `GetBatteryStatus`    | `()`                   | `BatteryStatus`         | `_ble`  |                                                                              |
+| `0x0804` | `GetPeripheralStatus` | `u8`                   | `PeripheralStatus`      | `split` |                                                                              |
+| `0x0805` | `GetWpm`              | `()`                   | `u16`                   |         | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                     |
+| `0x0806` | `GetSleepState`       | `()`                   | `bool`                  |         | Latest sleep flag, sourced from the `SleepState` topic snapshot.             |
+| `0x0807` | `GetLedIndicator`     | `()`                   | `LedIndicator`          |         | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot. |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index d2fd47095..99b400f4d 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -14,11 +14,11 @@ use serde::de::DeserializeOwned;
 
 use super::message::{RynkHeader, encode_frame};
 use super::{
-    BehaviorConfig, DeviceCapabilities, DeviceInfo, GetComboBulkRequest, GetComboBulkResponse, GetEncoderRequest,
-    GetKeymapBulkRequest, GetKeymapBulkResponse, GetMacroRequest, GetMorseBulkRequest, GetMorseBulkResponse,
-    KeyPosition, LayoutChunk, LockStatus, MacroData, MatrixState, ProtocolVersion, RynkError, SetComboBulkRequest,
-    SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest, SetMacroRequest,
-    SetMorseBulkRequest, SetMorseRequest, StorageResetMode,
+    BehaviorConfig, BuildInfo, DeviceCapabilities, DeviceInfo, GetComboBulkRequest, GetComboBulkResponse,
+    GetEncoderRequest, GetKeymapBulkRequest, GetKeymapBulkResponse, GetMacroRequest, GetMorseBulkRequest,
+    GetMorseBulkResponse, KeyPosition, LayoutChunk, LockStatus, MacroData, MatrixState, ProtocolVersion, RynkError,
+    SetComboBulkRequest, SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest,
+    SetMacroRequest, SetMorseBulkRequest, SetMorseRequest, StorageResetMode,
 };
 use crate::action::{EncoderAction, KeyAction};
 #[cfg(feature = "_ble")]
@@ -287,6 +287,8 @@ endpoints! {
     GetLayout = 0x0009: u32 => LayoutChunk;
     /// Identity strings and USB ids; feature gating stays in `GetCapabilities`.
     GetDeviceInfo = 0x000A: () => DeviceInfo;
+    /// Application-defined diagnostic build label; never used for compatibility.
+    GetBuildInfo = 0x000B: () => BuildInfo;
 
     // Keymap (0x01xx) — includes encoder.
     GetKeyAction = 0x0101: KeyPosition => KeyAction;
diff --git a/rmk-types/src/protocol/rynk/payload/system.rs b/rmk-types/src/protocol/rynk/payload/system.rs
index 9a37c2556..8d242be9d 100644
--- a/rmk-types/src/protocol/rynk/payload/system.rs
+++ b/rmk-types/src/protocol/rynk/payload/system.rs
@@ -9,6 +9,9 @@ use serde::{Deserialize, Serialize};
 /// Maximum byte length of each `DeviceInfo` string field.
 pub const DEVICE_INFO_STRING_SIZE: usize = 32;
 
+/// Maximum byte length of the application-defined build label.
+pub const BUILD_INFO_STRING_SIZE: usize = 128;
+
 /// Protocol version advertised during the connection handshake.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, MaxSize)]
 #[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
@@ -20,10 +23,29 @@ pub struct ProtocolVersion {
 
 impl ProtocolVersion {
     /// Current protocol version for this firmware release.
-    /// The protocol is still under development; lighting endpoints were added in v0.2.
+    /// The protocol is still under development; lighting endpoints and
+    /// build-info discovery were added in v0.2.
     pub const CURRENT: Self = Self { major: 0, minor: 2 };
 }
 
+/// Human-readable identity of the firmware build.
+///
+/// Unlike [`ProtocolVersion`], this label is deliberately application-defined:
+/// it is for diagnostics and display, never compatibility decisions. RMK
+/// supplies an RMK-only default and downstream firmware may replace it with a
+/// label containing its own package, source revision, or configuration name.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct BuildInfo {
+    #[cfg_attr(feature = "wasm", tsify(type = "string"))]
+    pub label: String<BUILD_INFO_STRING_SIZE>,
+}
+
+impl MaxSize for BuildInfo {
+    const POSTCARD_MAX_SIZE: usize = crate::heapless_vec_max_size::<u8, BUILD_INFO_STRING_SIZE>();
+}
+
 /// Device capabilities discovered during the connection handshake.
 ///
 /// The host reads this once after connecting to learn the firmware's layout,
@@ -240,6 +262,15 @@ mod tests {
         assert_max_size_bound(&info);
     }
 
+    #[test]
+    fn round_trip_build_info() {
+        let full: String<BUILD_INFO_STRING_SIZE> =
+            String::try_from("x".repeat(BUILD_INFO_STRING_SIZE).as_str()).unwrap();
+        let info = BuildInfo { label: full };
+        round_trip(&info);
+        assert_max_size_bound(&info);
+    }
+
     #[test]
     fn round_trip_lock_status() {
         // Locked, no attempt armed, challenge advertised.
diff --git a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
index 257fc628e..f73f018b3 100644
--- a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
@@ -33,6 +33,7 @@ BleState::Advertising                     00
 BleState::Connected                       01
 BleState::Inactive                        02
 BleStatus{2,Connected}                    02 01
+BuildInfo{my-firmware..}                  1f 6d 79 2d 66 69 72 6d 77 61 72 65 20 76 34 2e 35 2e 36 20 2f 20 52 4d 4b 20 76 31 2e 32 2e 33
 ChargeState::Charging                     00
 ChargeState::Discharging                  01
 ChargeState::Unknown                      02
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 74e28e11b..1b77cf5a8 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -204,6 +204,7 @@ struct Exemplars {
     matrix: MatrixState,
     capabilities: DeviceCapabilities,
     device_info: DeviceInfo,
+    build_info: BuildInfo,
     behavior: BehaviorConfig,
     connection: ConnectionStatus,
     state_bits: StateBits,
@@ -256,6 +257,9 @@ fn exemplars() -> Exemplars {
         product_name: heapless::String::try_from("RMK Keyboard").unwrap(),
         serial_number: heapless::String::try_from("rynk:0001").unwrap(),
     };
+    let build_info = BuildInfo {
+        label: heapless::String::try_from("my-firmware v4.5.6 / RMK v1.2.3").unwrap(),
+    };
     let behavior = BehaviorConfig {
         combo_timeout_ms: 50,
         oneshot_timeout_ms: 500,
@@ -308,6 +312,7 @@ fn exemplars() -> Exemplars {
         matrix,
         capabilities,
         device_info,
+        build_info,
         behavior,
         connection,
         state_bits,
@@ -464,6 +469,7 @@ fn wire_values_locked() {
         ("MatrixState{[0x05,0x00,0x20]}", encode(&ex.matrix)),
         ("DeviceCapabilities{1..16}", encode(&ex.capabilities)),
         ("DeviceInfo{1.2.3,4,5,RMK,..}", encode(&ex.device_info)),
+        ("BuildInfo{my-firmware..}", encode(&ex.build_info)),
         ("BehaviorConfig{50,500,200,20}", encode(&ex.behavior)),
         ("ConnectionStatus{Configured,{1,Adv},Ble}", encode(&ex.connection)),
         ("ProtocolVersion{1,0}", encode(&ProtocolVersion { major: 1, minor: 0 })),
@@ -674,6 +680,15 @@ fn wire_frames_locked() {
                 &Ok::<DeviceInfo, RynkError>(ex.device_info.clone())
             ),
         ),
+        ("GetBuildInfo request ()", encode_frame(Cmd::GetBuildInfo, SEQ, &())),
+        (
+            "GetBuildInfo reply Ok(BuildInfo{my-firmware..})",
+            encode_frame(
+                Cmd::GetBuildInfo,
+                SEQ,
+                &Ok::<BuildInfo, RynkError>(ex.build_info.clone())
+            ),
+        ),
         // Keymap / encoder (0x01xx).
         (
             "GetKeyAction request KeyPosition{0,5,13}",
diff --git a/rmk/src/host/mod.rs b/rmk/src/host/mod.rs
index 4eb4e70c6..4acf7c092 100644
--- a/rmk/src/host/mod.rs
+++ b/rmk/src/host/mod.rs
@@ -29,5 +29,8 @@ pub use rynk::{
     RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
     StandardRynkLightingAdapter,
 };
+/// RMK's semantic version, available to downstream firmware build labels.
+#[cfg(feature = "rynk")]
+pub use rynk::{RMK_VERSION, RMK_VERSION_STRING};
 #[cfg(feature = "vial")]
 pub use via::VialService as HostService;
diff --git a/rmk/src/host/rynk/handlers/system.rs b/rmk/src/host/rynk/handlers/system.rs
index 9859cfd6c..8b702469e 100644
--- a/rmk/src/host/rynk/handlers/system.rs
+++ b/rmk/src/host/rynk/handlers/system.rs
@@ -2,38 +2,18 @@
 
 use rmk_types::constants;
 use rmk_types::protocol::rynk::command::{
-    BootloaderJump, GetCapabilities, GetDeviceInfo, GetLockStatus, GetVersion, Lock, Reboot, StorageReset, UnlockPoll,
+    BootloaderJump, GetBuildInfo, GetCapabilities, GetDeviceInfo, GetLockStatus, GetVersion, Lock, Reboot,
+    StorageReset, UnlockPoll,
 };
 use rmk_types::protocol::rynk::{
-    DEVICE_INFO_STRING_SIZE, DeviceCapabilities, DeviceInfo, FirmwareVersion, LockStatus, MAX_BULK_ITEMS,
-    MAX_BULK_KEYS, ProtocolVersion, RYNK_MAX_PAYLOAD_SIZE, RynkError, StorageResetMode,
+    BuildInfo, DEVICE_INFO_STRING_SIZE, DeviceCapabilities, DeviceInfo, LockStatus, MAX_BULK_ITEMS, MAX_BULK_KEYS,
+    ProtocolVersion, RYNK_MAX_PAYLOAD_SIZE, RynkError, StorageResetMode,
 };
 
-use super::super::RynkService;
+use super::super::{RMK_VERSION, RynkService, truncated};
 use super::Handle;
 use crate::host::lock::HostLock;
 
-/// The `rmk` crate version baked into the firmware, so hosts can key
-/// version-specific behavior off the library release, not the user's app.
-const RMK_VERSION: FirmwareVersion = {
-    const fn component(s: &str) -> u8 {
-        let bytes = s.as_bytes();
-        let mut i = 0;
-        let mut value = 0u8;
-        while i < bytes.len() {
-            value = value * 10 + (bytes[i] - b'0');
-            i += 1;
-        }
-        value
-    }
-
-    FirmwareVersion {
-        major: component(env!("CARGO_PKG_VERSION_MAJOR")),
-        minor: component(env!("CARGO_PKG_VERSION_MINOR")),
-        patch: component(env!("CARGO_PKG_VERSION_PATCH")),
-    }
-};
-
 impl Handle<GetVersion> for RynkService<'_> {
     async fn handle(&self, _: ()) -> Result<ProtocolVersion, RynkError> {
         Ok(ProtocolVersion::CURRENT)
@@ -143,14 +123,8 @@ impl Handle<GetDeviceInfo> for RynkService<'_> {
     }
 }
 
-/// Copy `s` into the bounded wire string; over-long input is cut at the last
-/// whole char that fits, so multi-byte content can never panic or split.
-fn truncated(s: &str) -> heapless::String<DEVICE_INFO_STRING_SIZE> {
-    let mut out = heapless::String::new();
-    for c in s.chars() {
-        if out.push(c).is_err() {
-            break;
-        }
+impl Handle<GetBuildInfo> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<BuildInfo, RynkError> {
+        Ok(self.build_info.clone())
     }
-    out
 }
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 6953c3da3..ec627448f 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -19,7 +19,8 @@ pub use lighting::{
 };
 use rmk_types::constants::RYNK_BUFFER_SIZE;
 use rmk_types::protocol::rynk::{
-    Cmd, Deframer, RYNK_HEADER_SIZE, RynkError, RynkMessage, command, encode_frame, max_wire_size,
+    BuildInfo, Cmd, Deframer, FirmwareVersion, RYNK_HEADER_SIZE, RynkError, RynkMessage, command, encode_frame,
+    max_wire_size,
 };
 
 use self::handlers::{serve, serve_bulk};
@@ -32,6 +33,43 @@ use crate::keymap::KeyMap;
 /// Unlock attempts live long enough for BLE WebHID round trips.
 const RYNK_UNLOCK_WINDOW: embassy_time::Duration = embassy_time::Duration::from_millis(500);
 
+/// The `rmk` crate version baked into the firmware, so hosts can key
+/// version-specific behavior off the library release, not the user's app.
+pub const RMK_VERSION: FirmwareVersion = {
+    const fn component(s: &str) -> u8 {
+        let bytes = s.as_bytes();
+        let mut i = 0;
+        let mut value = 0u8;
+        while i < bytes.len() {
+            value = value * 10 + (bytes[i] - b'0');
+            i += 1;
+        }
+        value
+    }
+
+    FirmwareVersion {
+        major: component(env!("CARGO_PKG_VERSION_MAJOR")),
+        minor: component(env!("CARGO_PKG_VERSION_MINOR")),
+        patch: component(env!("CARGO_PKG_VERSION_PATCH")),
+    }
+};
+
+/// String form of [`RMK_VERSION`] for application-defined build labels.
+pub const RMK_VERSION_STRING: &str = env!("CARGO_PKG_VERSION");
+
+const DEFAULT_BUILD_LABEL: &str = concat!("RMK v", env!("CARGO_PKG_VERSION"));
+
+/// Copy a string into a bounded wire value without splitting UTF-8.
+fn truncated<const N: usize>(s: &str) -> heapless::String<N> {
+    let mut out = heapless::String::new();
+    for c in s.chars() {
+        if out.push(c).is_err() {
+            break;
+        }
+    }
+    out
+}
+
 /// Transport-agnostic Rynk service.
 pub struct RynkService<'a> {
     ctx: KeyboardContext<'a>,
@@ -41,6 +79,8 @@ pub struct RynkService<'a> {
     lock_config: LockConfig,
     #[cfg(feature = "lighting")]
     lighting: Option<RynkLightingController<'a>>,
+    /// Human-readable firmware identity served by `GetBuildInfo`.
+    build_info: BuildInfo,
 }
 
 /// Per-session state that has to outlive a single dispatch. The authorization
@@ -65,6 +105,9 @@ impl<'a> RynkService<'a> {
             lock_config: config.lock_config,
             #[cfg(feature = "lighting")]
             lighting: None,
+            build_info: BuildInfo {
+                label: truncated(DEFAULT_BUILD_LABEL),
+            },
         }
     }
 
@@ -77,6 +120,15 @@ impl<'a> RynkService<'a> {
         self
     }
 
+    /// Replace the diagnostic build label advertised by `GetBuildInfo`.
+    ///
+    /// The label is for display and support diagnostics only. Protocol
+    /// compatibility continues to use `GetVersion`.
+    pub fn with_build_label(mut self, label: &str) -> Self {
+        self.build_info.label = truncated(label);
+        self
+    }
+
     /// Whether `cmd` needs an unlocked device.
     fn requires_unlock(&self, cmd: Cmd) -> bool {
         match cmd {
@@ -132,6 +184,7 @@ impl<'a> RynkService<'a> {
             Cmd::UnlockPoll => serve::<command::UnlockPoll, _>(locker, msg).await,
             Cmd::Lock => serve::<command::Lock, _>(locker, msg).await,
             Cmd::GetDeviceInfo => serve::<command::GetDeviceInfo, _>(self, msg).await,
+            Cmd::GetBuildInfo => serve::<command::GetBuildInfo, _>(self, msg).await,
 
             Cmd::GetKeyAction => serve::<command::GetKeyAction, _>(self, msg).await,
             Cmd::SetKeyAction => serve::<command::SetKeyAction, _>(self, msg).await,
@@ -182,31 +235,31 @@ impl<'a> RynkService<'a> {
             Cmd::GetLayout => serve::<command::GetLayout, _>(self, msg).await,
 
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingCapabilities => Serve::<command::GetLightingCapabilities, _>::serve(self, msg).await,
+            Cmd::GetLightingCapabilities => serve::<command::GetLightingCapabilities, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingState => Serve::<command::GetLightingState, _>::serve(self, msg).await,
+            Cmd::GetLightingState => serve::<command::GetLightingState, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::SetLightingState => Serve::<command::SetLightingState, _>::serve(self, msg).await,
+            Cmd::SetLightingState => serve::<command::SetLightingState, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingKeys => Serve::<command::GetLightingKeys, _>::serve(self, msg).await,
+            Cmd::GetLightingKeys => serve::<command::GetLightingKeys, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingPhysicalKeys => Serve::<command::GetLightingPhysicalKeys, _>::serve(self, msg).await,
+            Cmd::GetLightingPhysicalKeys => serve::<command::GetLightingPhysicalKeys, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingLeds => Serve::<command::GetLightingLeds, _>::serve(self, msg).await,
+            Cmd::GetLightingLeds => serve::<command::GetLightingLeds, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingZones => Serve::<command::GetLightingZones, _>::serve(self, msg).await,
+            Cmd::GetLightingZones => serve::<command::GetLightingZones, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingZoneMemberships => Serve::<command::GetLightingZoneMemberships, _>::serve(self, msg).await,
+            Cmd::GetLightingZoneMemberships => serve::<command::GetLightingZoneMemberships, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingOutputs => Serve::<command::GetLightingOutputs, _>::serve(self, msg).await,
+            Cmd::GetLightingOutputs => serve::<command::GetLightingOutputs, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingRoutes => Serve::<command::GetLightingRoutes, _>::serve(self, msg).await,
+            Cmd::GetLightingRoutes => serve::<command::GetLightingRoutes, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::SetLightingOverlay => Serve::<command::SetLightingOverlay, _>::serve(self, msg).await,
+            Cmd::SetLightingOverlay => serve::<command::SetLightingOverlay, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::UnsetLightingOverlay => Serve::<command::UnsetLightingOverlay, _>::serve(self, msg).await,
+            Cmd::UnsetLightingOverlay => serve::<command::UnsetLightingOverlay, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::ClearLightingOverlay => Serve::<command::ClearLightingOverlay, _>::serve(self, msg).await,
+            Cmd::ClearLightingOverlay => serve::<command::ClearLightingOverlay, _>(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::BeginLightingOverlayReplace => handlers::lighting::serve_begin(self, session, msg).await,
             #[cfg(feature = "lighting")]
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index 52425327e..d9fbf54f8 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -29,7 +29,7 @@ use rynk::rmk_types::protocol::rynk::{
     LightingRoutesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus, MacroData,
     MatrixState, PeripheralStatus, ProtocolVersion, PutLightingOverlayChunkRequest, SetComboBulkRequest,
     SetKeymapBulkRequest, SetLightingOverlayRequest, SetLightingStateRequest, SetMorseBulkRequest, StorageResetMode,
-    UnsetLightingOverlayRequest,
+    UnsetLightingOverlayRequest, BuildInfo,
 };
 use rynk::{Client, Driver, LayoutInfo, RynkDevice, RynkHostError, TopicEvent};
 use wasm_bindgen::prelude::*;
@@ -114,6 +114,7 @@ endpoints! {
     get_version() -> ProtocolVersion,
     get_capabilities() -> DeviceCapabilities,
     get_device_info() -> DeviceInfo,
+    get_build_info() -> BuildInfo,
     reboot() -> (),
     bootloader_jump() -> (),
     storage_reset(mode: StorageResetMode) -> (),
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index bede325fa..fdcc0e53a 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -28,9 +28,9 @@ use rmk_types::protocol::rynk::{
     LightingLedsPage, LightingOutputsPage, LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage,
     LightingResult, LightingRoutesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus,
     MacroData, MatrixState, PeripheralStatus, ProtocolVersion, PutLightingOverlayChunkRequest, SetComboBulkRequest,
-    SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest, SetLightingOverlayRequest,
-    SetLightingStateRequest, SetMacroRequest, SetMorseBulkRequest, SetMorseRequest, StorageResetMode,
-    UnsetLightingOverlayRequest, command,
+    SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest,
+    SetLightingOverlayRequest, SetLightingStateRequest, SetMacroRequest, SetMorseBulkRequest, SetMorseRequest,
+    StorageResetMode, UnsetLightingOverlayRequest, command, BuildInfo,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -99,6 +99,11 @@ impl Client {
         self.request::<command::GetDeviceInfo>(&()).await
     }
 
+    /// Read the application-defined diagnostic build label.
+    pub async fn get_build_info(&self) -> Result<BuildInfo, RynkHostError> {
+        self.request::<command::GetBuildInfo>(&()).await
+    }
+
     /// Reboot the device. The firmware resets before it can reply, so `Ok(())` only
     /// means the request was queued — keep the driver running long enough to write it.
     pub async fn reboot(&self) -> Result<(), RynkHostError> {

From 757ceb91e8c13c5114a48a85e68e799d53fbf209 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 18:30:24 -0700
Subject: [PATCH 11/78] rynk: route split peripheral bootloader entry

---
 docs/docs/main/docs/development/rynk_protocol.md    |  3 +++
 rmk-types/src/protocol/rynk/command.rs              |  2 ++
 rmk-types/src/protocol/rynk/payload/system.rs       |  7 ++++---
 .../src/protocol/rynk/snapshots/wire_values.snap    |  2 +-
 rmk-types/src/protocol/rynk/tests.rs                |  8 ++++++++
 rmk/src/host/rynk/handlers/system.rs                | 10 ++++++++--
 rmk/src/host/rynk/mod.rs                            | 12 +++++++++++-
 rynk/rynk-wasm/src/client.rs                        |  1 +
 rynk/src/api.rs                                     | 13 +++++++++++++
 9 files changed, 51 insertions(+), 7 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index a81fabea9..f6df9549f 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -5,6 +5,7 @@
 # Rynk Protocol Reference
 
 Current protocol version: **0.2**.
+Current protocol version: **0.4**.
 
 Every transport (USB CDC, BLE GATT, BLE HID) carries the same frame — a 3-byte header plus a [postcard](https://docs.rs/postcard)-encoded payload:
 
@@ -38,6 +39,8 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x0008` | `Lock`                         | `()`                                  | `()`                                |            | Relock immediately.                                                          |
 | `0x0009` | `GetLayout`                    | `u32`                                 | `LayoutChunk`                       |            | Get layout blob chunk. `u32` is the byte offset.                             |
 | `0x000A` | `GetDeviceInfo`                | `()`                                  | `DeviceInfo`                        |            | Identity strings and USB ids; feature gating stays in `GetCapabilities`.     |
+| `0x000B` | `GetBuildInfo`                 | `()`                                  | `BuildInfo`                         |            | Application-defined diagnostic build label; never used for compatibility.    |
+| `0x000C` | `PeripheralBootloaderJump`     | `u8`                                  | `()`                                |            | Ask the application to route a bootloader jump to one split peripheral.      |
 | `0x0101` | `GetKeyAction`                 | `KeyPosition`                         | `KeyAction`                         |            |                                                                              |
 | `0x0102` | `SetKeyAction`                 | `SetKeyRequest`                       | `()`                                |            |                                                                              |
 | `0x0103` | `GetDefaultLayer`              | `()`                                  | `u8`                                |            |                                                                              |
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 99b400f4d..7976fb80d 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -289,6 +289,8 @@ endpoints! {
     GetDeviceInfo = 0x000A: () => DeviceInfo;
     /// Application-defined diagnostic build label; never used for compatibility.
     GetBuildInfo = 0x000B: () => BuildInfo;
+    /// Ask the application to route a bootloader jump to one split peripheral.
+    PeripheralBootloaderJump = 0x000C: u8 => ();
 
     // Keymap (0x01xx) — includes encoder.
     GetKeyAction = 0x0101: KeyPosition => KeyAction;
diff --git a/rmk-types/src/protocol/rynk/payload/system.rs b/rmk-types/src/protocol/rynk/payload/system.rs
index 8d242be9d..958d7ac59 100644
--- a/rmk-types/src/protocol/rynk/payload/system.rs
+++ b/rmk-types/src/protocol/rynk/payload/system.rs
@@ -23,9 +23,10 @@ pub struct ProtocolVersion {
 
 impl ProtocolVersion {
     /// Current protocol version for this firmware release.
-    /// The protocol is still under development; lighting endpoints and
-    /// build-info discovery were added in v0.2.
-    pub const CURRENT: Self = Self { major: 0, minor: 2 };
+    /// The protocol is still under development; lighting endpoints were added
+    /// in v0.2, build-info discovery in v0.3, and routed split bootloader
+    /// entry in v0.4.
+    pub const CURRENT: Self = Self { major: 0, minor: 4 };
 }
 
 /// Human-readable identity of the firmware build.
diff --git a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
index f73f018b3..bf9a130c7 100644
--- a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
@@ -65,7 +65,7 @@ ModifierCombination(LCtrl|RGui)           81
 MorseProfile(Normal,200,150)              c8 81 b0 89 0c
 Morse{TAP->Key(A)}                        00 01 02 01 00 04
 MouseButtons(B1|B8)                       81
-ProtocolVersion::CURRENT                  00 02
+ProtocolVersion::CURRENT                  00 04
 ProtocolVersion{1,0}                      01 00
 Result<(),RynkError>::Err(StorageFault)   01 02
 Result<(),RynkError>::Ok                  00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 1b77cf5a8..1e53a8f74 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -644,6 +644,14 @@ fn wire_frames_locked() {
             "BootloaderJump reply Ok(())",
             encode_frame(Cmd::BootloaderJump, SEQ, &Ok::<(), RynkError>(())),
         ),
+        (
+            "PeripheralBootloaderJump request slot 1",
+            encode_frame(Cmd::PeripheralBootloaderJump, SEQ, &1_u8),
+        ),
+        (
+            "PeripheralBootloaderJump reply Ok(())",
+            encode_frame(Cmd::PeripheralBootloaderJump, SEQ, &Ok::<(), RynkError>(()),),
+        ),
         (
             "StorageReset request StorageResetMode::Full",
             encode_frame(Cmd::StorageReset, SEQ, &StorageResetMode::Full)
diff --git a/rmk/src/host/rynk/handlers/system.rs b/rmk/src/host/rynk/handlers/system.rs
index 8b702469e..a3123165b 100644
--- a/rmk/src/host/rynk/handlers/system.rs
+++ b/rmk/src/host/rynk/handlers/system.rs
@@ -2,8 +2,8 @@
 
 use rmk_types::constants;
 use rmk_types::protocol::rynk::command::{
-    BootloaderJump, GetBuildInfo, GetCapabilities, GetDeviceInfo, GetLockStatus, GetVersion, Lock, Reboot,
-    StorageReset, UnlockPoll,
+    BootloaderJump, GetBuildInfo, GetCapabilities, GetDeviceInfo, GetLockStatus, GetVersion, Lock,
+    PeripheralBootloaderJump, Reboot, StorageReset, UnlockPoll,
 };
 use rmk_types::protocol::rynk::{
     BuildInfo, DEVICE_INFO_STRING_SIZE, DeviceCapabilities, DeviceInfo, LockStatus, MAX_BULK_ITEMS, MAX_BULK_KEYS,
@@ -77,6 +77,12 @@ impl Handle<BootloaderJump> for RynkService<'_> {
     }
 }
 
+impl Handle<PeripheralBootloaderJump> for RynkService<'_> {
+    async fn handle(&self, slot: u8) -> Result<(), RynkError> {
+        self.peripheral_bootloader.ok_or(RynkError::Unimplemented)?(slot)
+    }
+}
+
 impl Handle<StorageReset> for RynkService<'_> {
     async fn handle(&self, mode: StorageResetMode) -> Result<(), RynkError> {
         if mode != StorageResetMode::Full {
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index ec627448f..28f89834a 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -81,6 +81,8 @@ pub struct RynkService<'a> {
     lighting: Option<RynkLightingController<'a>>,
     /// Human-readable firmware identity served by `GetBuildInfo`.
     build_info: BuildInfo,
+    /// Optional board-specific route to a split peripheral's bootloader.
+    peripheral_bootloader: Option<fn(u8) -> Result<(), RynkError>>,
 }
 
 /// Per-session state that has to outlive a single dispatch. The authorization
@@ -108,6 +110,7 @@ impl<'a> RynkService<'a> {
             build_info: BuildInfo {
                 label: truncated(DEFAULT_BUILD_LABEL),
             },
+            peripheral_bootloader: None,
         }
     }
 
@@ -129,10 +132,16 @@ impl<'a> RynkService<'a> {
         self
     }
 
+    /// Attach a board-specific split-peripheral bootloader route.
+    pub fn with_peripheral_bootloader(mut self, route: fn(u8) -> Result<(), RynkError>) -> Self {
+        self.peripheral_bootloader = Some(route);
+        self
+    }
+
     /// Whether `cmd` needs an unlocked device.
     fn requires_unlock(&self, cmd: Cmd) -> bool {
         match cmd {
-            Cmd::BootloaderJump | Cmd::StorageReset | Cmd::GetMatrixState => true,
+            Cmd::BootloaderJump | Cmd::PeripheralBootloaderJump | Cmd::StorageReset | Cmd::GetMatrixState => true,
             // Deleting a bond opens a re-pair hijack window; BLE-only command.
             #[cfg(feature = "_ble")]
             Cmd::ClearBleProfile => true,
@@ -185,6 +194,7 @@ impl<'a> RynkService<'a> {
             Cmd::Lock => serve::<command::Lock, _>(locker, msg).await,
             Cmd::GetDeviceInfo => serve::<command::GetDeviceInfo, _>(self, msg).await,
             Cmd::GetBuildInfo => serve::<command::GetBuildInfo, _>(self, msg).await,
+            Cmd::PeripheralBootloaderJump => serve::<command::PeripheralBootloaderJump, _>(self, msg).await,
 
             Cmd::GetKeyAction => serve::<command::GetKeyAction, _>(self, msg).await,
             Cmd::SetKeyAction => serve::<command::SetKeyAction, _>(self, msg).await,
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index d9fbf54f8..e64d213d3 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -117,6 +117,7 @@ endpoints! {
     get_build_info() -> BuildInfo,
     reboot() -> (),
     bootloader_jump() -> (),
+    peripheral_bootloader_jump(slot: u8) -> (),
     storage_reset(mode: StorageResetMode) -> (),
     // lock gate
     get_lock_status() -> LockStatus,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index fdcc0e53a..bd50befc6 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -116,6 +116,19 @@ impl Client {
         self.send_no_reply::<command::BootloaderJump>(&()).await
     }
 
+    /// Ask the application to route a bootloader jump to one split peripheral.
+    /// Unlike the local jump, the central remains online and acknowledges
+    /// whether the board-specific route accepted the request.
+    pub async fn peripheral_bootloader_jump(&self, slot: u8) -> Result<(), RynkHostError> {
+        if !self.capabilities.is_split {
+            return Err(RynkHostError::Unsupported(
+                Cmd::PeripheralBootloaderJump,
+                "not a split keyboard",
+            ));
+        }
+        self.request::<command::PeripheralBootloaderJump>(&slot).await
+    }
+
     /// Reset persistent storage. Requires [`DeviceCapabilities::storage_enabled`]:
     /// without storage the wipe would silently do nothing, so nothing is sent.
     pub async fn storage_reset(&self, mode: StorageResetMode) -> Result<(), RynkHostError> {

From 087ff946afaaa072f44dcd3a0fc3b4b70c4e9b33 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 20:14:34 -0700
Subject: [PATCH 12/78] feat(rynk): make bootloader unlock policy configurable

---
 docs/docs/main/docs/configuration/appendix.md |  2 ++
 .../main/docs/configuration/host_config.md    |  5 +++++
 docs/docs/main/docs/features/rynk.md          | 19 +++++++++++++++----
 examples/use_rust/nrf54lm20_ble/src/main.rs   |  1 +
 examples/use_rust/qemu-riscv-rynk/src/main.rs |  1 +
 rmk-config/src/lib.rs                         |  5 +++++
 rmk-config/src/resolved/host.rs               |  2 ++
 rmk-macro/src/codegen/keyboard_config.rs      |  2 ++
 rmk/src/config/lock.rs                        | 17 ++++++++++++++++-
 rmk/src/host/rynk/mod.rs                      | 13 ++++++++++++-
 10 files changed, 61 insertions(+), 6 deletions(-)

diff --git a/docs/docs/main/docs/configuration/appendix.md b/docs/docs/main/docs/configuration/appendix.md
index e5ff9a54d..712c7ab1b 100644
--- a/docs/docs/main/docs/configuration/appendix.md
+++ b/docs/docs/main/docs/configuration/appendix.md
@@ -487,6 +487,8 @@ unlock_keys = [[0, 0], [0, 1]]
 insecure = false
 # Rynk only: move config writes into the locked tier (default: false).
 write_requires_unlock = false
+# Require physical unlock before central or split-peripheral bootloader entry.
+bootloader_requires_unlock = true
 
 # Chip-specific configuration
 # To use the default configuration, ignore this section completely
diff --git a/docs/docs/main/docs/configuration/host_config.md b/docs/docs/main/docs/configuration/host_config.md
index d2386401d..3f26ac622 100644
--- a/docs/docs/main/docs/configuration/host_config.md
+++ b/docs/docs/main/docs/configuration/host_config.md
@@ -33,6 +33,11 @@ insecure = false
 # Rynk only: move config writes (SetKeyAction, SetMacro, …) into the locked
 # tier so they also require unlock (default: false).
 write_requires_unlock = false
+
+# Rynk only: require physical unlock before central or split-peripheral
+# bootloader entry (default: true). Set false for host-managed deployment;
+# other dangerous operations remain gated.
+bootloader_requires_unlock = true
 ```
 
 ## Common Setups
diff --git a/docs/docs/main/docs/features/rynk.md b/docs/docs/main/docs/features/rynk.md
index fedc5e55a..7e1289437 100644
--- a/docs/docs/main/docs/features/rynk.md
+++ b/docs/docs/main/docs/features/rynk.md
@@ -100,10 +100,10 @@ There are three tiers:
 - **Open** — everything you normally reach for: read the keymap, change keys,
   layers, combos, macros, switch BLE profiles, reboot. These stay available so
   on-the-fly configuration is friction-free.
-- **Locked** — the dangerous ones, always gated: entering the bootloader,
-  resetting stored settings and bonds, reading the live key matrix (a keylogger
-  if left open), and clearing a BLE bond. A host tool gets a "locked" error
-  until you unlock.
+- **Locked** — the dangerous ones: entering the bootloader, resetting stored
+  settings and bonds, reading the live key matrix (a keylogger if left open),
+  and clearing a BLE bond. A host tool gets a "locked" error until you unlock.
+  Bootloader entry may be opted out separately for managed deployment setups.
 - **Config writes** — open by default, because on-the-fly configuration is the
   point. Set `write_requires_unlock = true` to move every write (keymap, macros,
   …) into the locked tier as well.
@@ -127,6 +127,17 @@ If you leave `unlock_keys` unset, the locked operations can never be unlocked 
 a safe default, but it means a fresh config can't enter the bootloader over Rynk
 or use the matrix tester until you add the keys.
 
+For a keyboard whose host is trusted to manage firmware deployment, allow only
+central and split-peripheral bootloader entry without the physical challenge:
+
+```toml title="keyboard.toml"
+[host]
+bootloader_requires_unlock = false
+```
+
+Storage reset, matrix-state reads, and BLE bond clearing remain gated. This is
+more narrowly scoped than `insecure = true`.
+
 For local development you can bypass the gate entirely:
 
 ```toml title="keyboard.toml"
diff --git a/examples/use_rust/nrf54lm20_ble/src/main.rs b/examples/use_rust/nrf54lm20_ble/src/main.rs
index 05ee9ff57..0665f27f2 100644
--- a/examples/use_rust/nrf54lm20_ble/src/main.rs
+++ b/examples/use_rust/nrf54lm20_ble/src/main.rs
@@ -194,6 +194,7 @@ async fn main(spawner: Spawner) {
             unlock_keys: RYNK_UNLOCK_KEYS,
             insecure: false,
             write_requires_unlock: false,
+            bootloader_requires_unlock: true,
         },
         storage_config,
         ..Default::default()
diff --git a/examples/use_rust/qemu-riscv-rynk/src/main.rs b/examples/use_rust/qemu-riscv-rynk/src/main.rs
index e1f8cb3cc..42a67f73e 100644
--- a/examples/use_rust/qemu-riscv-rynk/src/main.rs
+++ b/examples/use_rust/qemu-riscv-rynk/src/main.rs
@@ -122,6 +122,7 @@ async fn main(_spawner: Spawner) {
     let rmk_config = RMK_CONFIG.init(RmkConfig {
         lock_config: LockConfig {
             insecure: true,
+            bootloader_requires_unlock: true,
             ..Default::default()
         },
         ..Default::default()
diff --git a/rmk-config/src/lib.rs b/rmk-config/src/lib.rs
index 882e34790..07f5015fc 100644
--- a/rmk-config/src/lib.rs
+++ b/rmk-config/src/lib.rs
@@ -1227,6 +1227,10 @@ pub(crate) struct HostConfig {
     /// locked set, so writes also require unlock (default: false).
     #[serde_inline_default(false)]
     pub write_requires_unlock: bool,
+    /// Require the Rynk physical-presence unlock before entering either the
+    /// central or a split peripheral bootloader (default: true).
+    #[serde_inline_default(true)]
+    pub bootloader_requires_unlock: bool,
 }
 
 impl Default for HostConfig {
@@ -1237,6 +1241,7 @@ impl Default for HostConfig {
             unlock_keys: None,
             insecure: false,
             write_requires_unlock: false,
+            bootloader_requires_unlock: true,
         }
     }
 }
diff --git a/rmk-config/src/resolved/host.rs b/rmk-config/src/resolved/host.rs
index 7c7f35104..415eb956e 100644
--- a/rmk-config/src/resolved/host.rs
+++ b/rmk-config/src/resolved/host.rs
@@ -7,6 +7,7 @@ pub struct Host {
     pub unlock_keys: Vec<[u8; 2]>,
     pub insecure: bool,
     pub write_requires_unlock: bool,
+    pub bootloader_requires_unlock: bool,
 }
 
 impl crate::KeyboardTomlConfig {
@@ -24,6 +25,7 @@ impl crate::KeyboardTomlConfig {
             unlock_keys,
             insecure: host_toml.insecure,
             write_requires_unlock: host_toml.write_requires_unlock,
+            bootloader_requires_unlock: host_toml.bootloader_requires_unlock,
         }
     }
 }
diff --git a/rmk-macro/src/codegen/keyboard_config.rs b/rmk-macro/src/codegen/keyboard_config.rs
index e134a252e..25a662453 100644
--- a/rmk-macro/src/codegen/keyboard_config.rs
+++ b/rmk-macro/src/codegen/keyboard_config.rs
@@ -79,11 +79,13 @@ pub(crate) fn expand_lock_config(host: &Host) -> proc_macro2::TokenStream {
     let unlock_keys = unlock_keys_tokens(host);
     let insecure = host.insecure;
     let write_requires_unlock = host.write_requires_unlock;
+    let bootloader_requires_unlock = host.bootloader_requires_unlock;
     quote! {
         const LOCK_CONFIG: ::rmk::config::LockConfig = ::rmk::config::LockConfig {
             unlock_keys: #unlock_keys,
             insecure: #insecure,
             write_requires_unlock: #write_requires_unlock,
+            bootloader_requires_unlock: #bootloader_requires_unlock,
         };
     }
 }
diff --git a/rmk/src/config/lock.rs b/rmk/src/config/lock.rs
index 83923bc87..c5a7efc2f 100644
--- a/rmk/src/config/lock.rs
+++ b/rmk/src/config/lock.rs
@@ -1,6 +1,6 @@
 /// Rynk lock-gate configuration, emitted by the macro from `[host]` in
 /// keyboard.toml. `unlock_keys` empty ⇒ dangerous ops are permanently locked.
-#[derive(Clone, Copy, Debug, Default)]
+#[derive(Clone, Copy, Debug)]
 pub struct LockConfig {
     /// Physical `(row, col)` keys held simultaneously to unlock. Empty ⇒ no
     /// unlock possible.
@@ -10,4 +10,19 @@ pub struct LockConfig {
     /// Move the config-write tier (`SetKeyAction`, `SetMacro`, …) into the
     /// locked set.
     pub write_requires_unlock: bool,
+    /// Gate central and split-peripheral bootloader entry behind the physical
+    /// unlock challenge. Defaults to true; boards with a trusted host can opt
+    /// out without disabling the gate for storage reset or matrix reads.
+    pub bootloader_requires_unlock: bool,
+}
+
+impl Default for LockConfig {
+    fn default() -> Self {
+        Self {
+            unlock_keys: &[],
+            insecure: false,
+            write_requires_unlock: false,
+            bootloader_requires_unlock: true,
+        }
+    }
 }
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 28f89834a..0254786ca 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -141,7 +141,8 @@ impl<'a> RynkService<'a> {
     /// Whether `cmd` needs an unlocked device.
     fn requires_unlock(&self, cmd: Cmd) -> bool {
         match cmd {
-            Cmd::BootloaderJump | Cmd::PeripheralBootloaderJump | Cmd::StorageReset | Cmd::GetMatrixState => true,
+            Cmd::BootloaderJump | Cmd::PeripheralBootloaderJump => self.lock_config.bootloader_requires_unlock,
+            Cmd::StorageReset | Cmd::GetMatrixState => true,
             // Deleting a bond opens a re-pair hijack window; BLE-only command.
             #[cfg(feature = "_ble")]
             Cmd::ClearBleProfile => true,
@@ -499,8 +500,18 @@ mod tests {
                 write_requires_unlock: false,
             },
             ..Default::default()
+            bootloader_requires_unlock: true,
         };
         let service = RynkService::new(&keymap, &config);
+        assert!(service.requires_unlock(Cmd::BootloaderJump));
+        assert!(service.requires_unlock(Cmd::PeripheralBootloaderJump));
+
+        config.lock_config.bootloader_requires_unlock = false;
+        let deployment_service = RynkService::new(&keymap, &config);
+        assert!(!deployment_service.requires_unlock(Cmd::BootloaderJump));
+        assert!(!deployment_service.requires_unlock(Cmd::PeripheralBootloaderJump));
+        assert!(deployment_service.requires_unlock(Cmd::StorageReset));
+        assert!(deployment_service.requires_unlock(Cmd::GetMatrixState));
 
         // Hold the challenge key throughout, so only the session boundary can
         // account for the second session being locked.

From ef94863c45e0579d613d3acce4db15d68ba38988 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 21:19:43 -0700
Subject: [PATCH 13/78] feat(rynk): define the lighting scene wire surface

Add the protocol types for runtime-configurable per-layer scenes:
LightingSceneCell (layer + stable LED id + effect), LightingLayerPolicy,
a revision-pinned scenes page, single-cell set/unset requests, an atomic
Begin/Put/Commit/Abort replacement transaction, and SetLightingLayerPolicy.

Discovery deliberately leaves LightingCapabilities and LightingState
byte-identical: postcard is positional, so appending fields would break
new-host/old-firmware decode. Scenes are advertised through a new
LAYER_SCENES bit in the existing LightingFeatureFlags plus a dedicated
GetLightingSceneStatus endpoint carrying capacity, occupancy, and policy.
New LightingError variants (UnknownLayer, SceneFull) are appended, so
existing encodings are unchanged. Protocol version bumps to v0.3.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../main/docs/development/rynk_protocol.md    |  73 ++++++
 rmk-types/src/protocol/rynk/command.rs        |  32 ++-
 .../src/protocol/rynk/payload/lighting.rs     | 235 ++++++++++++++++++
 rmk-types/src/protocol/rynk/payload/system.rs |  23 +-
 .../rynk/snapshots/lighting_wire_frames.snap  |  20 ++
 rmk-types/src/protocol/rynk/tests.rs          | 176 +++++++++++++
 6 files changed, 534 insertions(+), 25 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index f6df9549f..ecb1d4303 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -6,6 +6,7 @@
 
 Current protocol version: **0.2**.
 Current protocol version: **0.4**.
+Current protocol version: **0.3**.
 
 Every transport (USB CDC, BLE GATT, BLE HID) carries the same frame — a 3-byte header plus a [postcard](https://docs.rs/postcard)-encoded payload:
 
@@ -139,6 +140,78 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x0805` | `GetWpm`              | `()`                   | `u16`                   |         | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                     |
 | `0x0806` | `GetSleepState`       | `()`                   | `bool`                  |         | Latest sleep flag, sourced from the `SleepState` topic snapshot.             |
 | `0x0807` | `GetLedIndicator`     | `()`                   | `LedIndicator`          |         | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot. |
+| CMD      | Name                           | Request                               | Response                            | Feature    | Notes                                                                                                                          |
+| -------- | ------------------------------ | ------------------------------------- | ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `0x0001` | `GetVersion`                   | `()`                                  | `ProtocolVersion`                   |            |                                                                                                                                |
+| `0x0002` | `GetCapabilities`              | `()`                                  | `DeviceCapabilities`                |            |                                                                                                                                |
+| `0x0003` | `Reboot`                       | `()`                                  | `()`                                |            |                                                                                                                                |
+| `0x0004` | `BootloaderJump`               | `()`                                  | `()`                                |            |                                                                                                                                |
+| `0x0005` | `StorageReset`                 | `StorageResetMode`                    | `()`                                |            |                                                                                                                                |
+| `0x0006` | `GetLockStatus`                | `()`                                  | `LockStatus`                        |            | Pure read of the current lock state — no side effects.                                                                         |
+| `0x0007` | `UnlockPoll`                   | `()`                                  | `LockStatus`                        |            | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                         |
+| `0x0008` | `Lock`                         | `()`                                  | `()`                                |            | Relock immediately.                                                                                                            |
+| `0x0009` | `GetLayout`                    | `u32`                                 | `LayoutChunk`                       |            | Get layout blob chunk. `u32` is the byte offset.                                                                               |
+| `0x000A` | `GetDeviceInfo`                | `()`                                  | `DeviceInfo`                        |            | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                       |
+| `0x0101` | `GetKeyAction`                 | `KeyPosition`                         | `KeyAction`                         |            |                                                                                                                                |
+| `0x0102` | `SetKeyAction`                 | `SetKeyRequest`                       | `()`                                |            |                                                                                                                                |
+| `0x0103` | `GetDefaultLayer`              | `()`                                  | `u8`                                |            |                                                                                                                                |
+| `0x0104` | `SetDefaultLayer`              | `u8`                                  | `()`                                |            |                                                                                                                                |
+| `0x0105` | `GetEncoderAction`             | `GetEncoderRequest`                   | `EncoderAction`                     |            |                                                                                                                                |
+| `0x0106` | `SetEncoderAction`             | `SetEncoderRequest`                   | `()`                                |            |                                                                                                                                |
+| `0x0107` | `GetKeymapBulk`                | `GetKeymapBulkRequest`                | `GetKeymapBulkResponse`             |            |                                                                                                                                |
+| `0x0108` | `SetKeymapBulk`                | `SetKeymapBulkRequest`                | `()`                                |            |                                                                                                                                |
+| `0x0201` | `GetMacro`                     | `GetMacroRequest`                     | `MacroData`                         |            |                                                                                                                                |
+| `0x0202` | `SetMacro`                     | `SetMacroRequest`                     | `()`                                |            |                                                                                                                                |
+| `0x0301` | `GetCombo`                     | `u8`                                  | `Combo`                             |            |                                                                                                                                |
+| `0x0302` | `SetCombo`                     | `SetComboRequest`                     | `()`                                |            |                                                                                                                                |
+| `0x0303` | `GetComboBulk`                 | `GetComboBulkRequest`                 | `GetComboBulkResponse`              |            |                                                                                                                                |
+| `0x0304` | `SetComboBulk`                 | `SetComboBulkRequest`                 | `()`                                |            |                                                                                                                                |
+| `0x0401` | `GetMorse`                     | `u8`                                  | `Morse`                             |            |                                                                                                                                |
+| `0x0402` | `SetMorse`                     | `SetMorseRequest`                     | `()`                                |            |                                                                                                                                |
+| `0x0403` | `GetMorseBulk`                 | `GetMorseBulkRequest`                 | `GetMorseBulkResponse`              |            |                                                                                                                                |
+| `0x0404` | `SetMorseBulk`                 | `SetMorseBulkRequest`                 | `()`                                |            |                                                                                                                                |
+| `0x0501` | `GetFork`                      | `u8`                                  | `Fork`                              |            |                                                                                                                                |
+| `0x0502` | `SetFork`                      | `SetForkRequest`                      | `()`                                |            |                                                                                                                                |
+| `0x0601` | `GetBehaviorConfig`            | `()`                                  | `BehaviorConfig`                    |            |                                                                                                                                |
+| `0x0602` | `SetBehaviorConfig`            | `BehaviorConfig`                      | `()`                                |            |                                                                                                                                |
+| `0x0701` | `GetConnectionType`            | `()`                                  | `ConnectionType`                    |            |                                                                                                                                |
+| `0x0702` | `GetConnectionStatus`          | `()`                                  | `ConnectionStatus`                  |            | Full `ConnectionStatus` snapshot.                                                                                              |
+| `0x0703` | `GetBleStatus`                 | `()`                                  | `BleStatus`                         | `_ble`     |                                                                                                                                |
+| `0x0704` | `SwitchBleProfile`             | `u8`                                  | `()`                                | `_ble`     |                                                                                                                                |
+| `0x0705` | `ClearBleProfile`              | `u8`                                  | `()`                                | `_ble`     |                                                                                                                                |
+| `0x0801` | `GetCurrentLayer`              | `()`                                  | `u8`                                |            |                                                                                                                                |
+| `0x0802` | `GetMatrixState`               | `()`                                  | `MatrixState`                       |            |                                                                                                                                |
+| `0x0803` | `GetBatteryStatus`             | `()`                                  | `BatteryStatus`                     | `_ble`     |                                                                                                                                |
+| `0x0804` | `GetPeripheralStatus`          | `u8`                                  | `PeripheralStatus`                  | `split`    |                                                                                                                                |
+| `0x0805` | `GetWpm`                       | `()`                                  | `u16`                               |            | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                       |
+| `0x0806` | `GetSleepState`                | `()`                                  | `bool`                              |            | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                               |
+| `0x0807` | `GetLedIndicator`              | `()`                                  | `LedIndicator`                      |            | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                   |
+| `0x0901` | `GetLightingCapabilities`      | `()`                                  | `LightingCapabilitiesResult`        | `lighting` |                                                                                                                                |
+| `0x0902` | `GetLightingState`             | `()`                                  | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0903` | `SetLightingState`             | `SetLightingStateRequest`             | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0904` | `GetLightingPhysicalKeys`      | `LightingPageRequest`                 | `LightingPhysicalKeysPageResult`    | `lighting` |                                                                                                                                |
+| `0x0905` | `GetLightingLeds`              | `LightingPageRequest`                 | `LightingLedsPageResult`            | `lighting` |                                                                                                                                |
+| `0x0906` | `GetLightingZones`             | `LightingPageRequest`                 | `LightingZonesPageResult`           | `lighting` |                                                                                                                                |
+| `0x0907` | `GetLightingZoneMemberships`   | `LightingPageRequest`                 | `LightingZoneMembershipsPageResult` | `lighting` |                                                                                                                                |
+| `0x0908` | `GetLightingOutputs`           | `LightingPageRequest`                 | `LightingOutputsPageResult`         | `lighting` |                                                                                                                                |
+| `0x0909` | `GetLightingRoutes`            | `LightingPageRequest`                 | `LightingRoutesPageResult`          | `lighting` |                                                                                                                                |
+| `0x090A` | `SetLightingOverlay`           | `SetLightingOverlayRequest`           | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x090B` | `UnsetLightingOverlay`         | `UnsetLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x090C` | `ClearLightingOverlay`         | `ClearLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x090D` | `BeginLightingOverlayReplace`  | `BeginLightingOverlayReplaceRequest`  | `LightingOverlayTransactionResult`  | `lighting` |                                                                                                                                |
+| `0x090E` | `PutLightingOverlayChunk`      | `PutLightingOverlayChunkRequest`      | `LightingUnitResult`                | `lighting` |                                                                                                                                |
+| `0x090F` | `CommitLightingOverlayReplace` | `CommitLightingOverlayReplaceRequest` | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0910` | `AbortLightingOverlayReplace`  | `AbortLightingOverlayReplaceRequest`  | `LightingUnitResult`                | `lighting` |                                                                                                                                |
+| `0x0911` | `GetLightingKeys`              | `LightingPageRequest`                 | `LightingKeysPageResult`            | `lighting` | Logical matrix keys are distinct from optional physical geometry.                                                              |
+| `0x0912` | `GetLightingSceneStatus`       | `()`                                  | `LightingSceneStatusResult`         | `lighting` | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts. |
+| `0x0913` | `GetLightingScenes`            | `LightingScenePageRequest`            | `LightingScenesPageResult`          | `lighting` | Scene pages are pinned to `LightingState.revision` for consistency.                                                            |
+| `0x0914` | `SetLightingSceneCell`         | `SetLightingSceneCellRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0915` | `UnsetLightingSceneCell`       | `UnsetLightingSceneCellRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0916` | `BeginLightingSceneReplace`    | `BeginLightingSceneReplaceRequest`    | `LightingSceneTransactionResult`    | `lighting` |                                                                                                                                |
+| `0x0917` | `PutLightingSceneChunk`        | `PutLightingSceneChunkRequest`        | `LightingUnitResult`                | `lighting` |                                                                                                                                |
+| `0x0918` | `CommitLightingSceneReplace`   | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0919` | `AbortLightingSceneReplace`    | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                | `lighting` |                                                                                                                                |
+| `0x091A` | `SetLightingLayerPolicy`       | `SetLightingLayerPolicyRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 7976fb80d..41b4a455b 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -34,12 +34,15 @@ use crate::morse::Morse;
 use crate::protocol::rynk::PeripheralStatus;
 #[cfg(feature = "lighting")]
 use crate::protocol::rynk::{
-    AbortLightingOverlayReplaceRequest, BeginLightingOverlayReplaceRequest, ClearLightingOverlayRequest,
-    CommitLightingOverlayReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingKeysPageResult,
+    AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
+    BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest,
+    CommitLightingSceneReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingKeysPageResult,
     LightingLedsPageResult, LightingOutputsPageResult, LightingOverlayTransactionResult, LightingPageRequest,
-    LightingPhysicalKeysPageResult, LightingRoutesPageResult, LightingStateResult, LightingUnitResult,
+    LightingPhysicalKeysPageResult, LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatusResult,
+    LightingSceneTransactionResult, LightingScenesPageResult, LightingStateResult, LightingUnitResult,
     LightingZoneMembershipsPageResult, LightingZonesPageResult, PutLightingOverlayChunkRequest,
-    SetLightingOverlayRequest, SetLightingStateRequest, UnsetLightingOverlayRequest,
+    PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
+    SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 
 /// CMD high bit marking a topic (server → host push).
@@ -388,6 +391,27 @@ endpoints! {
     /// Logical matrix keys are distinct from optional physical geometry.
     #[cfg(feature = "lighting")]
     GetLightingKeys = 0x0911: LightingPageRequest => LightingKeysPageResult;
+    /// Scene discovery lives outside `LightingCapabilities`/`LightingState`
+    /// so their postcard layout stays stable for existing hosts.
+    #[cfg(feature = "lighting")]
+    GetLightingSceneStatus = 0x0912: () => LightingSceneStatusResult;
+    /// Scene pages are pinned to `LightingState.revision` for consistency.
+    #[cfg(feature = "lighting")]
+    GetLightingScenes = 0x0913: LightingScenePageRequest => LightingScenesPageResult;
+    #[cfg(feature = "lighting")]
+    SetLightingSceneCell = 0x0914: SetLightingSceneCellRequest => LightingStateResult;
+    #[cfg(feature = "lighting")]
+    UnsetLightingSceneCell = 0x0915: UnsetLightingSceneCellRequest => LightingStateResult;
+    #[cfg(feature = "lighting")]
+    BeginLightingSceneReplace = 0x0916: BeginLightingSceneReplaceRequest => LightingSceneTransactionResult;
+    #[cfg(feature = "lighting")]
+    PutLightingSceneChunk = 0x0917: PutLightingSceneChunkRequest => LightingUnitResult;
+    #[cfg(feature = "lighting")]
+    CommitLightingSceneReplace = 0x0918: CommitLightingSceneReplaceRequest => LightingStateResult;
+    #[cfg(feature = "lighting")]
+    AbortLightingSceneReplace = 0x0919: AbortLightingSceneReplaceRequest => LightingUnitResult;
+    #[cfg(feature = "lighting")]
+    SetLightingLayerPolicy = 0x091A: SetLightingLayerPolicyRequest => LightingStateResult;
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 8dd116638..ff3821a3c 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -15,6 +15,8 @@ pub const LIGHTING_PAYLOAD_SIZE: usize = 256;
 pub const LIGHTING_PAGE_SIZE: usize = 8;
 /// Number of overlay cells in one replacement chunk.
 pub const LIGHTING_OVERLAY_CHUNK_SIZE: usize = 8;
+/// Number of scene cells in one scene page or replacement chunk.
+pub const LIGHTING_SCENE_CHUNK_SIZE: usize = 8;
 /// Maximum UTF-8 byte length of a zone name.
 pub const LIGHTING_ZONE_NAME_SIZE: usize = 24;
 
@@ -178,6 +180,8 @@ impl LightingFeatureFlags {
     pub const OVERLAY_TTL: u16 = 1 << 3;
     pub const ATOMIC_OVERLAY_REPLACE: u16 = 1 << 4;
     pub const LAYER_AWARE: u16 = 1 << 5;
+    /// Runtime-configurable per-layer scenes stored on the device.
+    pub const LAYER_SCENES: u16 = 1 << 6;
 
     pub const fn contains(self, bits: u16) -> bool {
         self.0 & bits == bits
@@ -438,6 +442,147 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Wire mirror of the engine's layer composition policy.
+    pub enum LightingLayerPolicy {
+        /// Only the effective layer contributes scene cells.
+        EffectiveOnly,
+        /// Default first, then the active set in ascending precedence, with
+        /// the effective layer last. Sparse cells fall through.
+        ActiveStack,
+    }
+}
+
+wire_type! {
+    /// One durable scene cell: an effect bound to a stable LED on one layer.
+    pub struct LightingSceneCell {
+        pub layer: u8,
+        pub led_id: LightingLedId,
+        pub effect: LightingEffect,
+    }
+}
+
+impl LightingSceneCell {
+    /// Validate the effect. Layer and LED bounds are checked against the
+    /// live keymap and topology by the firmware service.
+    pub const fn validate(&self) -> LightingResult<()> {
+        self.effect.validate()
+    }
+}
+
+wire_type! {
+    /// Scene limits and current occupancy. Kept out of
+    /// [`LightingCapabilities`]/[`LightingState`] so their postcard layout is
+    /// unchanged for existing hosts; discovery uses
+    /// [`LightingFeatureFlags::LAYER_SCENES`] plus this endpoint.
+    pub struct LightingSceneStatus {
+        /// Current [`LightingState::revision`]; scene mutations advance it.
+        pub revision: u32,
+        /// Maximum stored scene cells. `0` means scenes are absent.
+        pub capacity: u16,
+        pub scene_len: u16,
+        pub policy: LightingLayerPolicy,
+        /// Cells per `GetLightingScenes` page and per replacement chunk.
+        pub chunk_capacity: u8,
+    }
+}
+
+wire_type! {
+    /// Revision-pinned request for one scene page. `revision` is the expected
+    /// [`LightingState::revision`]; a stale read is rejected so multi-page
+    /// reads stay self-consistent.
+    pub struct LightingScenePageRequest {
+        pub revision: u32,
+        pub offset: u16,
+    }
+}
+
+/// One page of stored scene cells, echoing the pinned state revision.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LightingScenesPage {
+    pub revision: u32,
+    pub total_count: u16,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingSceneCell[]"))]
+    pub items: Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>,
+}
+
+impl MaxSize for LightingScenesPage {
+    const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+        + u16::POSTCARD_MAX_SIZE
+        + crate::heapless_vec_max_size::<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>();
+}
+
+wire_type! {
+    pub struct SetLightingSceneCellRequest {
+        pub expected_revision: u32,
+        pub cell: LightingSceneCell,
+    }
+}
+
+wire_type! {
+    pub struct UnsetLightingSceneCellRequest {
+        pub expected_revision: u32,
+        pub layer: u8,
+        pub led_id: LightingLedId,
+    }
+}
+
+wire_type! {
+    pub struct SetLightingLayerPolicyRequest {
+        pub expected_revision: u32,
+        pub policy: LightingLayerPolicy,
+    }
+}
+
+wire_type! {
+    /// Begin an atomic, multi-packet scene-table replacement.
+    pub struct BeginLightingSceneReplaceRequest {
+        pub expected_revision: u32,
+        pub cell_count: u16,
+    }
+}
+
+wire_type! {
+    /// Opaque scene transaction token allocated by the firmware.
+    pub struct LightingSceneTransaction {
+        pub id: u32,
+        pub cell_count: u16,
+    }
+}
+
+/// One ordered scene transaction chunk. Chunks are applied only by commit.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct PutLightingSceneChunkRequest {
+    pub transaction_id: u32,
+    pub offset: u16,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingSceneCell[]"))]
+    pub cells: Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>,
+}
+
+impl MaxSize for PutLightingSceneChunkRequest {
+    const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+        + u16::POSTCARD_MAX_SIZE
+        + crate::heapless_vec_max_size::<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>();
+}
+
+wire_type! {
+    pub struct CommitLightingSceneReplaceRequest {
+        pub transaction_id: u32,
+    }
+}
+
+wire_type! {
+    pub struct AbortLightingSceneReplaceRequest {
+        pub transaction_id: u32,
+    }
+}
+
 wire_type! {
     /// Lighting-domain rejection carried inside Rynk's outer protocol result.
     pub enum LightingError {
@@ -453,6 +598,10 @@ wire_type! {
         InvalidTransaction,
         TransactionExpired,
         TransactionIncomplete { expected: u16, received: u16 },
+        // Appended after the first lighting ICD; new variants only surface
+        // from the new scene endpoints, so older hosts never decode them.
+        UnknownLayer { layer: u8 },
+        SceneFull { capacity: u16 },
     }
 }
 
@@ -468,6 +617,9 @@ pub type LightingZoneMembershipsPageResult = LightingResult<LightingZoneMembersh
 pub type LightingOutputsPageResult = LightingResult<LightingOutputsPage>;
 pub type LightingRoutesPageResult = LightingResult<LightingRoutesPage>;
 pub type LightingOverlayTransactionResult = LightingResult<LightingOverlayTransaction>;
+pub type LightingSceneStatusResult = LightingResult<LightingSceneStatus>;
+pub type LightingScenesPageResult = LightingResult<LightingScenesPage>;
+pub type LightingSceneTransactionResult = LightingResult<LightingSceneTransaction>;
 pub type LightingUnitResult = LightingResult<()>;
 
 wire_type! {
@@ -503,6 +655,15 @@ const _: () = {
     assert_endpoint_fits!(PutLightingOverlayChunkRequest, LightingUnitResult);
     assert_endpoint_fits!(CommitLightingOverlayReplaceRequest, LightingStateResult);
     assert_endpoint_fits!(AbortLightingOverlayReplaceRequest, LightingUnitResult);
+    assert_endpoint_fits!((), LightingSceneStatusResult);
+    assert_endpoint_fits!(LightingScenePageRequest, LightingScenesPageResult);
+    assert_endpoint_fits!(SetLightingSceneCellRequest, LightingStateResult);
+    assert_endpoint_fits!(UnsetLightingSceneCellRequest, LightingStateResult);
+    assert_endpoint_fits!(SetLightingLayerPolicyRequest, LightingStateResult);
+    assert_endpoint_fits!(BeginLightingSceneReplaceRequest, LightingSceneTransactionResult);
+    assert_endpoint_fits!(PutLightingSceneChunkRequest, LightingUnitResult);
+    assert_endpoint_fits!(CommitLightingSceneReplaceRequest, LightingStateResult);
+    assert_endpoint_fits!(AbortLightingSceneReplaceRequest, LightingUnitResult);
     core::assert!(LightingChanged::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
 };
 
@@ -582,6 +743,80 @@ mod tests {
         assert_max_size_bound(&page);
     }
 
+    fn scene_cell(layer: u8, id: u16) -> LightingSceneCell {
+        LightingSceneCell {
+            layer,
+            led_id: LightingLedId(id),
+            effect: LightingEffect::Breathe {
+                color: LightingRgb8 { r: 4, g: 5, b: 6 },
+                period_ms: u32::MAX,
+                phase_ms: u32::MAX,
+                step_ms: u16::MAX - 1,
+            },
+        }
+    }
+
+    #[test]
+    fn scene_types_round_trip() {
+        round_trip(&LightingLayerPolicy::EffectiveOnly);
+        round_trip(&LightingLayerPolicy::ActiveStack);
+        round_trip(&scene_cell(3, 42));
+        round_trip(&LightingSceneStatus {
+            revision: u32::MAX,
+            capacity: 256,
+            scene_len: 12,
+            policy: LightingLayerPolicy::ActiveStack,
+            chunk_capacity: LIGHTING_SCENE_CHUNK_SIZE as u8,
+        });
+        round_trip(&LightingSceneTransaction {
+            id: u32::MAX,
+            cell_count: u16::MAX,
+        });
+        round_trip(&LightingError::UnknownLayer { layer: 9 });
+        round_trip(&LightingError::SceneFull { capacity: 256 });
+    }
+
+    #[test]
+    fn maximum_scene_chunk_and_page_respect_bounds() {
+        let mut cells = Vec::new();
+        for id in 0..LIGHTING_SCENE_CHUNK_SIZE as u16 {
+            cells.push(scene_cell(u8::MAX, id)).unwrap();
+        }
+        let request = PutLightingSceneChunkRequest {
+            transaction_id: u32::MAX,
+            offset: u16::MAX,
+            cells: cells.clone(),
+        };
+        round_trip(&request);
+        assert_max_size_bound(&request);
+        assert!(PutLightingSceneChunkRequest::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+
+        let page = LightingScenesPage {
+            revision: u32::MAX,
+            total_count: u16::MAX,
+            items: cells,
+        };
+        round_trip(&page);
+        assert_max_size_bound(&page);
+        assert!(LightingScenesPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+    }
+
+    #[test]
+    fn scene_cell_validation_is_effect_validation() {
+        assert_eq!(scene_cell(0, 1).validate(), Ok(()));
+        let invalid = LightingSceneCell {
+            layer: 0,
+            led_id: LightingLedId(1),
+            effect: LightingEffect::Blink {
+                color: LightingRgb8 { r: 1, g: 2, b: 3 },
+                period_ms: 0,
+                phase_ms: 0,
+                duty: 50,
+            },
+        };
+        assert_eq!(invalid.validate(), Err(LightingError::InvalidEffect));
+    }
+
     #[test]
     fn effect_and_ttl_validation_is_explicit() {
         let mut valid = cell(1);
diff --git a/rmk-types/src/protocol/rynk/payload/system.rs b/rmk-types/src/protocol/rynk/payload/system.rs
index 958d7ac59..f0ccdfce8 100644
--- a/rmk-types/src/protocol/rynk/payload/system.rs
+++ b/rmk-types/src/protocol/rynk/payload/system.rs
@@ -24,27 +24,8 @@ pub struct ProtocolVersion {
 impl ProtocolVersion {
     /// Current protocol version for this firmware release.
     /// The protocol is still under development; lighting endpoints were added
-    /// in v0.2, build-info discovery in v0.3, and routed split bootloader
-    /// entry in v0.4.
-    pub const CURRENT: Self = Self { major: 0, minor: 4 };
-}
-
-/// Human-readable identity of the firmware build.
-///
-/// Unlike [`ProtocolVersion`], this label is deliberately application-defined:
-/// it is for diagnostics and display, never compatibility decisions. RMK
-/// supplies an RMK-only default and downstream firmware may replace it with a
-/// label containing its own package, source revision, or configuration name.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
-#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
-pub struct BuildInfo {
-    #[cfg_attr(feature = "wasm", tsify(type = "string"))]
-    pub label: String<BUILD_INFO_STRING_SIZE>,
-}
-
-impl MaxSize for BuildInfo {
-    const POSTCARD_MAX_SIZE: usize = crate::heapless_vec_max_size::<u8, BUILD_INFO_STRING_SIZE>();
+    /// in v0.2 and lighting scene endpoints in v0.3.
+    pub const CURRENT: Self = Self { major: 0, minor: 3 };
 }
 
 /// Device capabilities discovered during the connection handshake.
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index ef4d3c989..f0fd64d8f 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -7,12 +7,18 @@
 
 AbortLightingOverlayReplace reply                      10 09 01 02 00 00 00
 AbortLightingOverlayReplace request                    10 09 01 01 00 0d
+AbortLightingSceneReplace reply                        19 09 01 02 00 00 00
+AbortLightingSceneReplace request                      19 09 01 01 00 15
 BeginLightingOverlayReplace reply                      0d 09 01 04 00 00 00 0d 01
 BeginLightingOverlayReplace request                    0d 09 01 02 00 0c 01
+BeginLightingSceneReplace reply                        16 09 01 04 00 00 00 15 01
+BeginLightingSceneReplace request                      16 09 01 02 00 0c 01
 ClearLightingOverlay reply                             0c 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 ClearLightingOverlay request                           0c 09 01 01 00 0b
 CommitLightingOverlayReplace reply                     0f 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 CommitLightingOverlayReplace request                   0f 09 01 01 00 0d
+CommitLightingSceneReplace reply                       18 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+CommitLightingSceneReplace request                     18 09 01 01 00 15
 GetLightingCapabilities reply                          01 09 01 0f 00 00 00 01 02 03 04 05 06 07 08 09 08 08 3f 07
 GetLightingCapabilities request                        01 09 01 00 00
 GetLightingKeys reply                                  11 09 01 07 00 00 00 01 01 01 01 02
@@ -25,6 +31,10 @@ GetLightingPhysicalKeys reply                          04 09 01 13 00 00 00 01 0
 GetLightingPhysicalKeys request                        04 09 01 02 00 01 00
 GetLightingRoutes reply                                09 09 01 09 00 00 00 01 01 01 2a 01 02 07
 GetLightingRoutes request                              09 09 01 02 00 01 00
+GetLightingSceneStatus reply                           12 09 01 08 00 00 00 09 80 02 01 01 08
+GetLightingSceneStatus request                         12 09 01 00 00
+GetLightingScenes reply                                13 09 01 0b 00 00 00 09 01 01 02 2a 00 07 08 09
+GetLightingScenes request                              13 09 01 02 00 09 00
 GetLightingState reply                                 02 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 GetLightingState request                               02 09 01 00 00
 GetLightingZoneMemberships reply                       07 09 01 06 00 00 00 01 01 01 04
@@ -35,11 +45,21 @@ LightingChange topic                                   07 80 00 00 00
 PutLightingOverlayChunk inner Err(TransactionExpired)  0e 09 01 03 00 00 01 0a
 PutLightingOverlayChunk reply                          0e 09 01 02 00 00 00
 PutLightingOverlayChunk request                        0e 09 01 10 00 0d 00 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27
+PutLightingSceneChunk reply                            17 09 01 02 00 00 00
+PutLightingSceneChunk request                          17 09 01 09 00 15 00 01 02 2a 00 07 08 09
+SetLightingLayerPolicy reply                           1a 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+SetLightingLayerPolicy request                         1a 09 01 02 00 0b 00
 SetLightingOverlay inner Err(UnknownLed)               0a 09 01 05 00 00 01 06 e7 07
 SetLightingOverlay outer Err(Locked)                   0a 09 01 02 00 01 07
 SetLightingOverlay reply                               0a 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 SetLightingOverlay request                             0a 09 01 0e 00 09 2a 01 01 02 03 e8 07 fa 01 32 01 88 27
+SetLightingSceneCell inner Err(SceneFull)              14 09 01 05 00 00 01 0d 80 02
+SetLightingSceneCell inner Err(UnknownLayer)           14 09 01 04 00 00 01 0c c8
+SetLightingSceneCell reply                             14 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+SetLightingSceneCell request                           14 09 01 07 00 09 02 2a 00 07 08 09
 SetLightingState reply                                 03 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 SetLightingState request                               03 09 01 09 00 08 01 c8 01 0a 14 1e 28 01
 UnsetLightingOverlay reply                             0b 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 UnsetLightingOverlay request                           0b 09 01 02 00 0a 2a
+UnsetLightingSceneCell reply                           15 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+UnsetLightingSceneCell request                         15 09 01 03 00 0a 02 2a
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 1e53a8f74..3046b6716 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1134,6 +1134,58 @@ fn lighting_wire_frames_locked() {
     let abort = AbortLightingOverlayReplaceRequest {
         transaction_id: transaction.id,
     };
+    let scene_cell = LightingSceneCell {
+        layer: 2,
+        led_id: led.id,
+        effect: LightingEffect::Solid {
+            color: LightingRgb8 { r: 7, g: 8, b: 9 },
+        },
+    };
+    let scene_status = LightingSceneStatus {
+        revision: state.revision,
+        capacity: 256,
+        scene_len: 1,
+        policy: LightingLayerPolicy::ActiveStack,
+        chunk_capacity: LIGHTING_SCENE_CHUNK_SIZE as u8,
+    };
+    let scene_page_request = LightingScenePageRequest {
+        revision: state.revision,
+        offset: 0,
+    };
+    let scenes_page = LightingScenesPage {
+        revision: state.revision,
+        total_count: 1,
+        items: one(scene_cell),
+    };
+    let set_scene_cell = SetLightingSceneCellRequest {
+        expected_revision: 9,
+        cell: scene_cell,
+    };
+    let unset_scene_cell = UnsetLightingSceneCellRequest {
+        expected_revision: 10,
+        layer: scene_cell.layer,
+        led_id: led.id,
+    };
+    let set_layer_policy = SetLightingLayerPolicyRequest {
+        expected_revision: 11,
+        policy: LightingLayerPolicy::EffectiveOnly,
+    };
+    let scene_begin = BeginLightingSceneReplaceRequest {
+        expected_revision: 12,
+        cell_count: 1,
+    };
+    let scene_transaction = LightingSceneTransaction { id: 21, cell_count: 1 };
+    let scene_put = PutLightingSceneChunkRequest {
+        transaction_id: scene_transaction.id,
+        offset: 0,
+        cells: one(scene_cell),
+    };
+    let scene_commit = CommitLightingSceneReplaceRequest {
+        transaction_id: scene_transaction.id,
+    };
+    let scene_abort = AbortLightingSceneReplaceRequest {
+        transaction_id: scene_transaction.id,
+    };
 
     let entries: alloc::vec::Vec<(&str, alloc::vec::Vec<u8>)> = alloc::vec![
         (
@@ -1366,6 +1418,130 @@ fn lighting_wire_frames_locked() {
                 &Ok::<LightingUnitResult, RynkError>(Err(LightingError::TransactionExpired))
             )
         ),
+        (
+            "GetLightingSceneStatus request",
+            encode_frame(Cmd::GetLightingSceneStatus, SEQ, &())
+        ),
+        (
+            "GetLightingSceneStatus reply",
+            encode_frame(
+                Cmd::GetLightingSceneStatus,
+                SEQ,
+                &Ok::<LightingSceneStatusResult, RynkError>(Ok(scene_status))
+            )
+        ),
+        (
+            "GetLightingScenes request",
+            encode_frame(Cmd::GetLightingScenes, SEQ, &scene_page_request)
+        ),
+        (
+            "GetLightingScenes reply",
+            encode_frame(
+                Cmd::GetLightingScenes,
+                SEQ,
+                &Ok::<LightingScenesPageResult, RynkError>(Ok(scenes_page))
+            )
+        ),
+        (
+            "SetLightingSceneCell request",
+            encode_frame(Cmd::SetLightingSceneCell, SEQ, &set_scene_cell)
+        ),
+        (
+            "SetLightingSceneCell reply",
+            encode_frame(
+                Cmd::SetLightingSceneCell,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "UnsetLightingSceneCell request",
+            encode_frame(Cmd::UnsetLightingSceneCell, SEQ, &unset_scene_cell)
+        ),
+        (
+            "UnsetLightingSceneCell reply",
+            encode_frame(
+                Cmd::UnsetLightingSceneCell,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "SetLightingLayerPolicy request",
+            encode_frame(Cmd::SetLightingLayerPolicy, SEQ, &set_layer_policy)
+        ),
+        (
+            "SetLightingLayerPolicy reply",
+            encode_frame(
+                Cmd::SetLightingLayerPolicy,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "BeginLightingSceneReplace request",
+            encode_frame(Cmd::BeginLightingSceneReplace, SEQ, &scene_begin)
+        ),
+        (
+            "BeginLightingSceneReplace reply",
+            encode_frame(
+                Cmd::BeginLightingSceneReplace,
+                SEQ,
+                &Ok::<LightingSceneTransactionResult, RynkError>(Ok(scene_transaction))
+            )
+        ),
+        (
+            "PutLightingSceneChunk request",
+            encode_frame(Cmd::PutLightingSceneChunk, SEQ, &scene_put)
+        ),
+        (
+            "PutLightingSceneChunk reply",
+            encode_frame(
+                Cmd::PutLightingSceneChunk,
+                SEQ,
+                &Ok::<LightingUnitResult, RynkError>(Ok(()))
+            )
+        ),
+        (
+            "CommitLightingSceneReplace request",
+            encode_frame(Cmd::CommitLightingSceneReplace, SEQ, &scene_commit)
+        ),
+        (
+            "CommitLightingSceneReplace reply",
+            encode_frame(
+                Cmd::CommitLightingSceneReplace,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "AbortLightingSceneReplace request",
+            encode_frame(Cmd::AbortLightingSceneReplace, SEQ, &scene_abort)
+        ),
+        (
+            "AbortLightingSceneReplace reply",
+            encode_frame(
+                Cmd::AbortLightingSceneReplace,
+                SEQ,
+                &Ok::<LightingUnitResult, RynkError>(Ok(()))
+            )
+        ),
+        (
+            "SetLightingSceneCell inner Err(UnknownLayer)",
+            encode_frame(
+                Cmd::SetLightingSceneCell,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Err(LightingError::UnknownLayer { layer: 200 }))
+            )
+        ),
+        (
+            "SetLightingSceneCell inner Err(SceneFull)",
+            encode_frame(
+                Cmd::SetLightingSceneCell,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Err(LightingError::SceneFull { capacity: 256 }))
+            )
+        ),
         (
             "LightingChange topic",
             encode_frame(Cmd::LightingChange, 0, &LightingChanged)

From 2e701ededda4c85f95b04fb00ea058f09d08661a Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 21:21:39 -0700
Subject: [PATCH 14/78] feat(lighting): add runtime-configurable per-layer
 scenes over Rynk
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Give the standard engine an owned, fixed-capacity SceneTable (new
SCENE_CAP const generic, default 0) holding per-layer, per-slot effects
with the same EffectiveOnly/ActiveStack composition semantics as the
static LayerScenes. The table composes in the layer band immediately
after the board's static scenes — a runtime cell overrides a static
default for the same slot — while the TTL overlay stays highest-priority.

Scene mutations are revision-checked commands; whole-table replacement
stages inside the engine via bounded chunks (Begin/Put/Commit/Abort)
with inactivity expiry and an idempotent commit. Staging engine-side
instead of reusing the host-side overlay staging keeps kilobyte-sized
scene batches off the bounded mailbox channels, whose payloads are
copied by value. Scene reads and transaction reservation need non-state
readback, so the engine's reply type becomes the StandardReply enum and
StandardState gains scene_len/scene_policy.

The Rynk service exposes the table through nine endpoints for status,
revision-pinned paged reads, single-cell set/unset, layer policy, and
the chunked replacement transaction. It validates effects, layer bounds
(against the live keymap), and stable LED ids (against the topology)
before anything reaches the engine; boards opt in by advertising a
capacity via RynkLightingController::with_scene_capacity, and scene
endpoints reject with Unsupported when none is wired. Scene writes
honor the same unlock gate as the other lighting writes.

Scene configuration is durable config like the keymap: after every
successful mutation the adapter reads the table back out of the engine
and persists it as one header record (len + policy) plus chunk-sized
shard records in wire (stable LED id) form. The storage task compares
before writing so unchanged shards cost no flash traffic; a storage
reset clears them. Boards load persisted scenes at boot with
Storage::read_lighting_scenes + install_lighting_scenes, which skips
cells whose LED id no longer resolves. Lighting featuresets join the
CI test/clippy matrix.

Composed with the split renderer replicas underneath: the runtime
scene table travels inside StandardReplicaState, so replica renderers
draw runtime scenes exactly like the authority without ever seeing the
incremental scene mutation commands. StandardReplicaState/-Slot and
StandardCommand gain a trailing SCENE_CAP const generic (default 0),
ExportReplica snapshots the table and ApplyReplica installs it, and the
replica round-trip test now covers a runtime scene cell.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .github/ci/_lib.sh                     |    3 +
 rmk/CHANGELOG.md                       |    1 +
 rmk/src/host/mod.rs                    |    2 +-
 rmk/src/host/rynk/handlers/lighting.rs |  604 ++++++++++++-
 rmk/src/host/rynk/lighting.rs          |  470 +++++++++-
 rmk/src/host/rynk/mod.rs               |   29 +-
 rmk/src/host/via/rgb_matrix.rs         |   22 +-
 rmk/src/lighting/mod.rs                |    5 +-
 rmk/src/lighting/processor.rs          |   13 +
 rmk/src/lighting/standard.rs           | 1153 +++++++++++++++++++++++-
 rmk/src/storage/mod.rs                 |   95 ++
 11 files changed, 2305 insertions(+), 92 deletions(-)

diff --git a/.github/ci/_lib.sh b/.github/ci/_lib.sh
index f465a4f62..9c26b289d 100644
--- a/.github/ci/_lib.sh
+++ b/.github/ci/_lib.sh
@@ -52,6 +52,8 @@ RMK_FEATURESETS=(
     "rynk,_ble,split,storage,async_matrix"
     "rynk,storage"
     "rynk"
+    "rynk,lighting"
+    "rynk,storage,lighting"
 )
 
 # Behavioral coverage only; RMK_FEATURESETS remains the compile/clippy matrix.
@@ -59,6 +61,7 @@ RMK_TEST_FEATURESETS=(
     ""
     "vial,host_lock,_no_usb,steno,passkey_entry"
     "rynk,_ble,split,async_matrix,storage"
+    "rynk,storage,lighting"
 )
 
 # Examples auto-discovery skiplist. Reasons:
diff --git a/rmk/CHANGELOG.md b/rmk/CHANGELOG.md
index fbcab0792..f58425ad5 100644
--- a/rmk/CHANGELOG.md
+++ b/rmk/CHANGELOG.md
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 - Add [Rynk](https://rmk.rs/docs/features/rynk), RMK's native host protocol for on-the-fly configuration over USB and BLE — an opt-in alternative to Vial that covers every RMK feature (keymap, layers, encoders, combos, forks, tap-dance/morse, macros, and behavior config), plus live status (current layer, matrix tester, WPM, HID indicators, battery, connection/BLE profile) and device management (reboot, bootloader, storage reset). Enable with the `rynk` Cargo feature and `[host] rynk_enabled = true`; it is mutually exclusive with Vial. Dangerous operations (bootloader, storage reset, matrix tester, clearing a BLE bond) are gated behind a physical-presence unlock (`[host].unlock_keys`). Host client crates live in the new `rynk/` workspace ([#962](https://github.com/rmk-rs/rmk/pull/962))
+- Add runtime-configurable per-layer lighting scenes over Rynk: hosts can store per-layer, per-LED effects on the keyboard (`GetLightingSceneStatus`/`GetLightingScenes`, `SetLightingSceneCell`/`UnsetLightingSceneCell`, an atomic `BeginLightingSceneReplace`/`PutLightingSceneChunk`/`CommitLightingSceneReplace`/`AbortLightingSceneReplace` transaction, and `SetLightingLayerPolicy`). Scene cells compose in the layer band — above the board's static layer scenes, below the transient TTL overlay — and persist via RMK storage, loading on boot and clearing with a storage reset. Boards opt in by choosing a scene capacity on the standard lighting engine and advertising it with `RynkLightingController::with_scene_capacity`
 - Add Azoteq IQS5xx (IQS550 / IQS572 / IQS525) trackpad driver, used by Azoteq's TPS43/TPS65 modules. Supports operation with or without an `RDY` pin and is configurable via `keyboard.toml` on nRF52 / RP2040; currently publishes single-finger relative cursor movement only ([#29](https://github.com/rmk-rs/rmk/issues/29))
 - Add PMW3360 / PMW3389 optical mouse sensor support
 - Add `report_hz` option for Pmw3610Device
diff --git a/rmk/src/host/mod.rs b/rmk/src/host/mod.rs
index 4acf7c092..7d23cc655 100644
--- a/rmk/src/host/mod.rs
+++ b/rmk/src/host/mod.rs
@@ -27,7 +27,7 @@ pub use rynk::RynkService as HostService;
 #[cfg(all(feature = "rynk", feature = "lighting"))]
 pub use rynk::{
     RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
-    StandardRynkLightingAdapter,
+    RynkLightingReadback, StandardRynkLightingAdapter, install_lighting_scenes,
 };
 /// RMK's semantic version, available to downstream firmware build labels.
 #[cfg(feature = "rynk")]
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 9e94f241a..7b2a631e6 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -4,24 +4,30 @@ use embassy_time::Instant;
 use heapless::{String, Vec};
 use rmk_types::protocol::rynk::command::{
     ClearLightingOverlay, GetLightingCapabilities, GetLightingKeys, GetLightingLeds, GetLightingOutputs,
-    GetLightingPhysicalKeys, GetLightingRoutes, GetLightingState, GetLightingZoneMemberships, GetLightingZones,
-    SetLightingOverlay, SetLightingState, UnsetLightingOverlay,
+    GetLightingPhysicalKeys, GetLightingRoutes, GetLightingSceneStatus, GetLightingScenes, GetLightingState,
+    GetLightingZoneMemberships, GetLightingZones, SetLightingLayerPolicy, SetLightingOverlay, SetLightingSceneCell,
+    SetLightingState, UnsetLightingOverlay, UnsetLightingSceneCell,
 };
 use rmk_types::protocol::rynk::{
-    AbortLightingOverlayReplaceRequest, BeginLightingOverlayReplaceRequest, ClearLightingOverlayRequest,
-    CommitLightingOverlayReplaceRequest, LIGHTING_PAGE_SIZE, LIGHTING_ZONE_NAME_SIZE, LightingCapabilities,
-    LightingCapabilitiesResult, LightingEffectFlags, LightingError, LightingFeatureFlags, LightingKeysPage,
-    LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
+    AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
+    BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest,
+    CommitLightingSceneReplaceRequest, LIGHTING_PAGE_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LIGHTING_ZONE_NAME_SIZE,
+    LightingCapabilities, LightingCapabilitiesResult, LightingEffectFlags, LightingError, LightingFeatureFlags,
+    LightingKeysPage, LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
     LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage, LightingOutputsPage,
     LightingOutputsPageResult, LightingOverlayCell, LightingOverlayTransaction, LightingOverlayTransactionResult,
     LightingPageRequest, LightingPhysicalKey, LightingPhysicalKeysPage, LightingPhysicalKeysPageResult, LightingPoint3,
-    LightingResult, LightingRoute, LightingRoutesPage, LightingRoutesPageResult, LightingState, LightingStateResult,
-    LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage, LightingZoneMembershipsPageResult,
-    LightingZonesPage, LightingZonesPageResult, PutLightingOverlayChunkRequest, RynkError, RynkMessage,
-    SetLightingOverlayRequest, SetLightingStateRequest, UnsetLightingOverlayRequest,
+    LightingResult, LightingRoute, LightingRoutesPage, LightingRoutesPageResult, LightingScenePageRequest,
+    LightingSceneStatus, LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult,
+    LightingState, LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage,
+    LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult, PutLightingOverlayChunkRequest,
+    PutLightingSceneChunkRequest, RynkError, RynkMessage, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
+    SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 
-use super::super::lighting::{RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingCommand, RynkLightingController};
+use super::super::lighting::{
+    RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingCommand, RynkLightingController, RynkLightingReadback,
+};
 use super::super::{RynkService, RynkSession};
 use super::Handle;
 use crate::lighting::OutputCoverage;
@@ -32,6 +38,16 @@ fn controller<'a>(service: &RynkService<'a>) -> LightingResult<RynkLightingContr
     service.lighting.ok_or(LightingError::Unsupported)
 }
 
+/// Scene endpoints require a board that wired a runtime scene table; a
+/// controller advertising `scene_capacity == 0` has none.
+fn scene_controller<'a>(service: &RynkService<'a>) -> LightingResult<RynkLightingController<'a>> {
+    let controller = controller(service)?;
+    if controller.scene_capacity == 0 {
+        return Err(LightingError::Unsupported);
+    }
+    Ok(controller)
+}
+
 impl Handle<GetLightingCapabilities> for RynkService<'_> {
     async fn handle(&self, _: ()) -> Result<LightingCapabilitiesResult, RynkError> {
         Ok(controller(self).map(capabilities))
@@ -41,7 +57,7 @@ impl Handle<GetLightingCapabilities> for RynkService<'_> {
 impl Handle<GetLightingState> for RynkService<'_> {
     async fn handle(&self, _: ()) -> Result<LightingStateResult, RynkError> {
         Ok(match controller(self) {
-            Ok(controller) => controller.request(RynkLightingCommand::ReadState).await,
+            Ok(controller) => controller.request_state(RynkLightingCommand::ReadState).await,
             Err(error) => Err(error),
         })
     }
@@ -52,7 +68,7 @@ impl Handle<SetLightingState> for RynkService<'_> {
         let result = match controller(self) {
             Ok(controller) => {
                 controller
-                    .request(RynkLightingCommand::SetState {
+                    .request_state(RynkLightingCommand::SetState {
                         expected_revision: req.expected_revision,
                         state: req.state,
                     })
@@ -72,7 +88,7 @@ impl Handle<SetLightingOverlay> for RynkService<'_> {
         let result = match controller(self) {
             Ok(controller) => {
                 controller
-                    .request(RynkLightingCommand::SetOverlay {
+                    .request_state(RynkLightingCommand::SetOverlay {
                         expected_revision: req.expected_revision,
                         cell: req.cell,
                     })
@@ -89,7 +105,7 @@ impl Handle<UnsetLightingOverlay> for RynkService<'_> {
         let result = match controller(self) {
             Ok(controller) => {
                 controller
-                    .request(RynkLightingCommand::UnsetOverlay {
+                    .request_state(RynkLightingCommand::UnsetOverlay {
                         expected_revision: req.expected_revision,
                         led_id: req.led_id,
                     })
@@ -106,7 +122,7 @@ impl Handle<ClearLightingOverlay> for RynkService<'_> {
         let result = match controller(self) {
             Ok(controller) => {
                 controller
-                    .request(RynkLightingCommand::ClearOverlay {
+                    .request_state(RynkLightingCommand::ClearOverlay {
                         expected_revision: req.expected_revision,
                     })
                     .await
@@ -117,6 +133,213 @@ impl Handle<ClearLightingOverlay> for RynkService<'_> {
     }
 }
 
+impl RynkService<'_> {
+    /// `UnknownLayer` for a scene layer outside the live keymap.
+    fn check_scene_layer(&self, layer: u8) -> LightingResult<()> {
+        let (_, _, num_layers) = self.ctx.keymap_dimensions();
+        if (layer as usize) < num_layers {
+            Ok(())
+        } else {
+            Err(LightingError::UnknownLayer { layer })
+        }
+    }
+}
+
+impl Handle<GetLightingSceneStatus> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LightingSceneStatusResult, RynkError> {
+        let result = match scene_controller(self) {
+            Ok(controller) => match controller.request(RynkLightingCommand::ReadSceneStatus).await {
+                Ok(RynkLightingReadback::SceneStatus {
+                    revision,
+                    scene_len,
+                    policy,
+                }) => Ok(LightingSceneStatus {
+                    revision,
+                    capacity: controller.scene_capacity,
+                    scene_len,
+                    policy,
+                    chunk_capacity: LIGHTING_SCENE_CHUNK_SIZE as u8,
+                }),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<GetLightingScenes> for RynkService<'_> {
+    async fn handle(&self, req: LightingScenePageRequest) -> Result<LightingScenesPageResult, RynkError> {
+        let result = match scene_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::ReadScenes {
+                    expected_revision: req.revision,
+                    offset: req.offset,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::ScenesPage(page)) => Ok(page),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<SetLightingSceneCell> for RynkService<'_> {
+    async fn handle(&self, req: SetLightingSceneCellRequest) -> Result<LightingStateResult, RynkError> {
+        if let Err(error) = req
+            .cell
+            .validate()
+            .and_then(|()| self.check_scene_layer(req.cell.layer))
+        {
+            return Ok(Err(error));
+        }
+        let result = match scene_controller(self) {
+            Ok(controller) => {
+                controller
+                    .request_state(RynkLightingCommand::SetSceneCell {
+                        expected_revision: req.expected_revision,
+                        cell: req.cell,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<UnsetLightingSceneCell> for RynkService<'_> {
+    async fn handle(&self, req: UnsetLightingSceneCellRequest) -> Result<LightingStateResult, RynkError> {
+        if let Err(error) = self.check_scene_layer(req.layer) {
+            return Ok(Err(error));
+        }
+        let result = match scene_controller(self) {
+            Ok(controller) => {
+                controller
+                    .request_state(RynkLightingCommand::UnsetSceneCell {
+                        expected_revision: req.expected_revision,
+                        layer: req.layer,
+                        led_id: req.led_id,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<SetLightingLayerPolicy> for RynkService<'_> {
+    async fn handle(&self, req: SetLightingLayerPolicyRequest) -> Result<LightingStateResult, RynkError> {
+        let result = match scene_controller(self) {
+            Ok(controller) => {
+                controller
+                    .request_state(RynkLightingCommand::SetLayerPolicy {
+                        expected_revision: req.expected_revision,
+                        policy: req.policy,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<rmk_types::protocol::rynk::command::BeginLightingSceneReplace> for RynkService<'_> {
+    async fn handle(&self, req: BeginLightingSceneReplaceRequest) -> Result<LightingSceneTransactionResult, RynkError> {
+        let result = match scene_controller(self) {
+            Ok(controller) => {
+                if req.cell_count > controller.scene_capacity {
+                    Err(LightingError::SceneFull {
+                        capacity: controller.scene_capacity,
+                    })
+                } else {
+                    match controller
+                        .request(RynkLightingCommand::BeginSceneReplace {
+                            expected_revision: req.expected_revision,
+                            cell_count: req.cell_count,
+                        })
+                        .await
+                    {
+                        Ok(RynkLightingReadback::SceneTransaction(transaction)) => Ok(transaction),
+                        Ok(_) => Err(LightingError::InvalidRequest),
+                        Err(error) => Err(error),
+                    }
+                }
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<rmk_types::protocol::rynk::command::PutLightingSceneChunk> for RynkService<'_> {
+    async fn handle(&self, req: PutLightingSceneChunkRequest) -> Result<LightingUnitResult, RynkError> {
+        for cell in &req.cells {
+            if let Err(error) = cell.validate().and_then(|()| self.check_scene_layer(cell.layer)) {
+                return Ok(Err(error));
+            }
+        }
+        let result = match scene_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::PutSceneChunk {
+                    transaction_id: req.transaction_id,
+                    offset: req.offset,
+                    cells: req.cells,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::Unit) => Ok(()),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<rmk_types::protocol::rynk::command::CommitLightingSceneReplace> for RynkService<'_> {
+    async fn handle(&self, req: CommitLightingSceneReplaceRequest) -> Result<LightingStateResult, RynkError> {
+        let result = match scene_controller(self) {
+            Ok(controller) => {
+                controller
+                    .request_state(RynkLightingCommand::CommitSceneReplace {
+                        transaction_id: req.transaction_id,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<rmk_types::protocol::rynk::command::AbortLightingSceneReplace> for RynkService<'_> {
+    async fn handle(&self, req: AbortLightingSceneReplaceRequest) -> Result<LightingUnitResult, RynkError> {
+        let result = match scene_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::AbortSceneReplace {
+                    transaction_id: req.transaction_id,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::Unit) => Ok(()),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
 impl Handle<GetLightingKeys> for RynkService<'_> {
     async fn handle(&self, req: LightingPageRequest) -> Result<LightingKeysPageResult, RynkError> {
         Ok(controller(self).and_then(|binding| keys_page(binding, req)))
@@ -177,6 +400,9 @@ fn capabilities(binding: RynkLightingController<'_>) -> LightingCapabilities {
     if !routing.routes.is_empty() || !routing.outputs.is_empty() {
         features.0 |= LightingFeatureFlags::ROUTING;
     }
+    if binding.scene_capacity > 0 {
+        features.0 |= LightingFeatureFlags::LAYER_SCENES;
+    }
     LightingCapabilities {
         topology_revision: descriptor.topology_revision,
         logical_key_count: count(topology.keys.len()),
@@ -1000,7 +1226,7 @@ mod tests {
                         }
                         _ => panic!("expected replacement"),
                     }
-                    mailbox.reply(pending.id, Ok(committed));
+                    mailbox.reply(pending.id, Ok(RynkLightingReadback::State(committed)));
                 },
             )
             .await;
@@ -1090,11 +1316,353 @@ mod tests {
                             expected_revision: 9,
                         } if staged.is_empty()
                     ));
-                    mailbox.reply(pending.id, Ok(cleared));
+                    mailbox.reply(pending.id, Ok(RynkLightingReadback::State(cleared)));
                 },
             )
             .await;
             assert_eq!(response.unwrap(), Ok(cleared));
         });
     }
+
+    fn wire_scene_cell(layer: u8, led: u16) -> rmk_types::protocol::rynk::LightingSceneCell {
+        rmk_types::protocol::rynk::LightingSceneCell {
+            layer,
+            led_id: LightingLedId(led),
+            effect: rmk_types::protocol::rynk::LightingEffect::Solid {
+                color: rmk_types::protocol::rynk::LightingRgb8 { r: 5, g: 6, b: 7 },
+            },
+        }
+    }
+
+    #[test]
+    fn scene_endpoints_reject_unsupported_without_a_scene_capacity() {
+        block_on(async {
+            let mut behavior = BehaviorConfig::default();
+            let positional: PositionalConfig<1, 3> = PositionalConfig::default();
+            let mut data: KeymapData<1, 3, 1, 0> = KeymapData::new([[[KeyAction::No; 3]]]);
+            let keymap = KeyMap::new(&mut data, &mut behavior, &positional).await;
+            let mut config = RmkConfig::default();
+            config.lock_config.insecure = true;
+            let mailbox = RynkLightingMailbox::new();
+            // Lighting is bound, but the board wired no runtime scene table.
+            let service = RynkService::new(&keymap, &config).with_lighting(RynkLightingController::new(
+                &mailbox,
+                descriptor(),
+                8,
+            ));
+            let session = session(&keymap, &config);
+
+            let lighting = capabilities(service.lighting.unwrap());
+            assert!(!lighting.features.contains(LightingFeatureFlags::LAYER_SCENES));
+
+            let status = call::<rmk_types::protocol::rynk::command::GetLightingSceneStatus>(&service, &session, &())
+                .await
+                .unwrap();
+            assert_eq!(status, Err(LightingError::Unsupported));
+            let set = call::<rmk_types::protocol::rynk::command::SetLightingSceneCell>(
+                &service,
+                &session,
+                &rmk_types::protocol::rynk::SetLightingSceneCellRequest {
+                    expected_revision: 0,
+                    cell: wire_scene_cell(0, 10),
+                },
+            )
+            .await
+            .unwrap();
+            assert_eq!(set, Err(LightingError::Unsupported));
+        });
+    }
+
+    /// Full stack: handler validation → protocol mailbox → adapter → engine,
+    /// with scene persistence observed on the flash channel.
+    #[test]
+    fn scene_endpoints_flow_through_adapter_and_engine() {
+        use embassy_futures::select::{Either3, select3};
+        use rmk_types::protocol::rynk::command::{
+            AbortLightingSceneReplace, BeginLightingSceneReplace, CommitLightingSceneReplace, GetLightingSceneStatus,
+            GetLightingScenes, PutLightingSceneChunk, SetLightingLayerPolicy, SetLightingSceneCell,
+            UnsetLightingSceneCell,
+        };
+        use rmk_types::protocol::rynk::{
+            BeginLightingSceneReplaceRequest, CommitLightingSceneReplaceRequest, LightingLayerPolicy,
+            LightingScenePageRequest, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest,
+            SetLightingSceneCellRequest, UnsetLightingSceneCellRequest,
+        };
+
+        use crate::lighting::{
+            BackgroundState, EmptySource, LayerPolicy, LayerScenes, LightingContext, LightingEngine, LightingMailbox,
+            StandardCommand, StandardError, StandardLightingEngine, StandardReply,
+        };
+
+        block_on(async {
+            let mut behavior = BehaviorConfig::default();
+            let positional: PositionalConfig<1, 3> = PositionalConfig::default();
+            let mut data: KeymapData<1, 3, 2, 0> = KeymapData::new([[[KeyAction::No; 3]]; 2]);
+            let keymap = KeyMap::new(&mut data, &mut behavior, &positional).await;
+            let mut config = RmkConfig::default();
+            config.lock_config.insecure = true;
+            let mailbox = RynkLightingMailbox::new();
+            let service = RynkService::new(&keymap, &config)
+                .with_lighting(RynkLightingController::new(&mailbox, descriptor(), 8).with_scene_capacity(4));
+            let session = session(&keymap, &config);
+
+            let core = LightingMailbox::<StandardCommand<2, 4>, StandardReply, StandardError, 1>::new();
+            let mut adapter = super::super::super::lighting::StandardRynkLightingAdapter::<2, 1, 4>::new(
+                &mailbox,
+                &core,
+                descriptor().topology,
+            );
+            let mut engine: StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2, 4> =
+                StandardLightingEngine::new(
+                    BackgroundState::default(),
+                    LayerScenes {
+                        scenes: &[],
+                        policy: LayerPolicy::ActiveStack,
+                    },
+                    EmptySource,
+                    EmptySource,
+                );
+
+            let lighting = capabilities(service.lighting.unwrap());
+            assert!(lighting.features.contains(LightingFeatureFlags::LAYER_SCENES));
+
+            let client = async {
+                let status = call::<GetLightingSceneStatus>(&service, &session, &())
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(status.capacity, 4);
+                assert_eq!(status.scene_len, 0);
+                assert_eq!(status.policy, LightingLayerPolicy::ActiveStack);
+                assert_eq!(
+                    status.chunk_capacity as usize,
+                    rmk_types::protocol::rynk::LIGHTING_SCENE_CHUNK_SIZE
+                );
+
+                // Handler-side bounds: an out-of-keymap layer and an unknown
+                // stable LED never reach the engine.
+                let bad_layer = call::<SetLightingSceneCell>(
+                    &service,
+                    &session,
+                    &SetLightingSceneCellRequest {
+                        expected_revision: 0,
+                        cell: wire_scene_cell(9, 10),
+                    },
+                )
+                .await
+                .unwrap();
+                assert_eq!(bad_layer, Err(LightingError::UnknownLayer { layer: 9 }));
+                let bad_led = call::<SetLightingSceneCell>(
+                    &service,
+                    &session,
+                    &SetLightingSceneCellRequest {
+                        expected_revision: 0,
+                        cell: wire_scene_cell(1, 7),
+                    },
+                )
+                .await
+                .unwrap();
+                assert_eq!(
+                    bad_led,
+                    Err(LightingError::UnknownLed {
+                        led_id: LightingLedId(7)
+                    })
+                );
+
+                let state = call::<SetLightingSceneCell>(
+                    &service,
+                    &session,
+                    &SetLightingSceneCellRequest {
+                        expected_revision: 0,
+                        cell: wire_scene_cell(1, 42),
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(state.revision, 1);
+
+                // Pinned page reads round-trip stable LED identity.
+                let page =
+                    call::<GetLightingScenes>(&service, &session, &LightingScenePageRequest { revision: 1, offset: 0 })
+                        .await
+                        .unwrap()
+                        .unwrap();
+                assert_eq!(page.total_count, 1);
+                assert_eq!(page.items[0], wire_scene_cell(1, 42));
+                let stale =
+                    call::<GetLightingScenes>(&service, &session, &LightingScenePageRequest { revision: 0, offset: 0 })
+                        .await
+                        .unwrap();
+                assert_eq!(
+                    stale,
+                    Err(LightingError::StateRevisionConflict {
+                        expected: 0,
+                        current: 1
+                    })
+                );
+
+                // A whole-table replacement above capacity fails locally.
+                let over = call::<BeginLightingSceneReplace>(
+                    &service,
+                    &session,
+                    &BeginLightingSceneReplaceRequest {
+                        expected_revision: 1,
+                        cell_count: 9,
+                    },
+                )
+                .await
+                .unwrap();
+                assert_eq!(over, Err(LightingError::SceneFull { capacity: 4 }));
+
+                let transaction = call::<BeginLightingSceneReplace>(
+                    &service,
+                    &session,
+                    &BeginLightingSceneReplaceRequest {
+                        expected_revision: 1,
+                        cell_count: 1,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                let mut cells = Vec::new();
+                cells.push(wire_scene_cell(0, 10)).unwrap();
+                call::<PutLightingSceneChunk>(
+                    &service,
+                    &session,
+                    &PutLightingSceneChunkRequest {
+                        transaction_id: transaction.id,
+                        offset: 0,
+                        cells,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                let committed = call::<CommitLightingSceneReplace>(
+                    &service,
+                    &session,
+                    &CommitLightingSceneReplaceRequest {
+                        transaction_id: transaction.id,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(committed.revision, 2);
+
+                // The pre-replace cell is gone; the replacement is visible.
+                let page =
+                    call::<GetLightingScenes>(&service, &session, &LightingScenePageRequest { revision: 2, offset: 0 })
+                        .await
+                        .unwrap()
+                        .unwrap();
+                assert_eq!(page.total_count, 1);
+                assert_eq!(page.items[0], wire_scene_cell(0, 10));
+
+                let state = call::<SetLightingLayerPolicy>(
+                    &service,
+                    &session,
+                    &SetLightingLayerPolicyRequest {
+                        expected_revision: 2,
+                        policy: LightingLayerPolicy::EffectiveOnly,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(state.revision, 3);
+                let status = call::<GetLightingSceneStatus>(&service, &session, &())
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(status.policy, LightingLayerPolicy::EffectiveOnly);
+                assert_eq!(status.scene_len, 1);
+
+                // Unset through stable identity, then abort of a dead
+                // transaction reports it as unknown.
+                let state = call::<UnsetLightingSceneCell>(
+                    &service,
+                    &session,
+                    &UnsetLightingSceneCellRequest {
+                        expected_revision: 3,
+                        layer: 0,
+                        led_id: LightingLedId(10),
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(state.revision, 4);
+                let aborted = call::<AbortLightingSceneReplace>(
+                    &service,
+                    &session,
+                    &rmk_types::protocol::rynk::AbortLightingSceneReplaceRequest { transaction_id: 999 },
+                )
+                .await
+                .unwrap();
+                assert_eq!(aborted, Err(LightingError::InvalidTransaction));
+            };
+
+            let adapter_loop = async {
+                loop {
+                    adapter.process_next().await;
+                }
+            };
+            let context = LightingContext::default();
+            let engine_loop = async {
+                loop {
+                    let (id, command) = core.receive_request().await;
+                    let result = engine.handle_command(0, command, &context).map(|outcome| outcome.reply);
+                    core.publish_reply(id, result);
+                }
+            };
+            #[cfg(feature = "storage")]
+            let persisted = core::cell::RefCell::new(alloc::vec::Vec::new());
+            let flash_drain = async {
+                #[cfg(feature = "storage")]
+                loop {
+                    persisted
+                        .borrow_mut()
+                        .push(crate::channel::FLASH_CHANNEL.receive().await);
+                }
+                #[cfg(not(feature = "storage"))]
+                core::future::pending::<()>().await
+            };
+
+            match select3(
+                client,
+                adapter_loop,
+                embassy_futures::join::join(engine_loop, flash_drain),
+            )
+            .await
+            {
+                Either3::First(()) => {}
+                _ => panic!("service loops must not finish"),
+            }
+
+            // Every scene mutation rewrote the durable table: the last
+            // header reflects the final one-cell removal and policy change.
+            #[cfg(feature = "storage")]
+            {
+                use crate::storage::FlashOperationMessage;
+                let persisted = persisted.into_inner();
+                assert!(!persisted.is_empty());
+                let last_table = persisted
+                    .iter()
+                    .rev()
+                    .find_map(|message| match message {
+                        FlashOperationMessage::LightingSceneTable { len, policy } => Some((*len, *policy)),
+                        _ => None,
+                    })
+                    .expect("scene mutations persist a table header");
+                assert_eq!(last_table, (0, LightingLayerPolicy::EffectiveOnly));
+                assert!(persisted.iter().any(|message| matches!(
+                    message,
+                    FlashOperationMessage::LightingSceneShard { index: 0, cells } if cells.len() == 1
+                )));
+            }
+        });
+    }
 }
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index c9dd328d0..99c2d8467 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -15,17 +15,24 @@ use embassy_sync::mutex::Mutex;
 use embassy_sync::signal::Signal;
 use heapless::Vec;
 use rmk_types::protocol::rynk::{
-    LightingBackgroundMode, LightingBackgroundState, LightingError, LightingMutableState, LightingOverlayCell,
-    LightingResult, LightingRgb8, LightingState,
+    LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState, LightingError, LightingLayerPolicy,
+    LightingMutableState, LightingOverlayCell, LightingResult, LightingRgb8, LightingSceneCell,
+    LightingSceneTransaction, LightingScenesPage, LightingState,
 };
 
 use crate::RawMutex;
 use crate::core_traits::Runnable;
 use crate::lighting::{
-    BackgroundMode, BackgroundState, BuiltinEffect, LedId, LightingMailbox, LightingRouting, LightingTopology,
-    OverlayBatch, OverlayCell, OverlayError, Rgb8, StandardCommand, StandardError, StandardMutableState, StandardState,
+    BackgroundMode, BackgroundState, BuiltinEffect, LayerPolicy, LedId, LightingMailbox, LightingRouting,
+    LightingTopology, OverlayBatch, OverlayCell, OverlayError, Rgb8, SceneChunk, SceneTableCell, StandardCommand,
+    StandardError, StandardLightingEngine, StandardMutableState, StandardReply, StandardState,
 };
 
+const _: () = core::assert!(
+    crate::lighting::SCENE_CHUNK_SIZE == LIGHTING_SCENE_CHUNK_SIZE,
+    "engine scene chunk must match the wire chunk so adapters forward chunks unmodified"
+);
+
 /// Maximum number of cells staged by one Rynk overlay replacement.
 ///
 /// A concrete engine may advertise a smaller capacity. Keeping the protocol
@@ -47,6 +54,10 @@ pub struct RynkLightingDescriptor<'a> {
 pub struct RynkLightingController<'a> {
     pub(super) descriptor: RynkLightingDescriptor<'a>,
     pub(super) overlay_capacity: u16,
+    /// Advertised runtime scene-cell capacity. `0` means the board did not
+    /// wire a scene table; hosts gate on it and every scene endpoint rejects
+    /// with `Unsupported`.
+    pub(super) scene_capacity: u16,
     mailbox: &'a RynkLightingMailbox,
 }
 
@@ -66,10 +77,18 @@ impl<'a> RynkLightingController<'a> {
             } else {
                 staged_capacity
             },
+            scene_capacity: 0,
             mailbox,
         }
     }
 
+    /// Advertise runtime scene support. Pass the engine's scene capacity;
+    /// boards without a scene table simply skip this call.
+    pub const fn with_scene_capacity(mut self, scene_capacity: u16) -> Self {
+        self.scene_capacity = scene_capacity;
+        self
+    }
+
     pub const fn descriptor(&self) -> RynkLightingDescriptor<'a> {
         self.descriptor
     }
@@ -78,16 +97,50 @@ impl<'a> RynkLightingController<'a> {
         self.overlay_capacity
     }
 
-    pub(super) async fn request(&self, command: RynkLightingCommand) -> LightingResult<LightingState> {
+    pub const fn scene_capacity(&self) -> u16 {
+        self.scene_capacity
+    }
+
+    pub(super) async fn request(&self, command: RynkLightingCommand) -> LightingResult<RynkLightingReadback> {
         self.mailbox.request(command).await
     }
 
+    /// Request expecting authoritative state readback.
+    pub(super) async fn request_state(&self, command: RynkLightingCommand) -> LightingResult<LightingState> {
+        expect_state(self.mailbox.request(command).await)
+    }
+
     pub(super) async fn replace_overlay(
         &self,
         expected_revision: u32,
         cells: &Vec<LightingOverlayCell, RYNK_LIGHTING_TRANSACTION_CAPACITY>,
     ) -> LightingResult<LightingState> {
-        self.mailbox.request_replace(expected_revision, cells).await
+        expect_state(self.mailbox.request_replace(expected_revision, cells).await)
+    }
+}
+
+/// Typed readback carried by the protocol mailbox. Most commands answer with
+/// wire state; scene reads and transaction reservation have their own shapes.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum RynkLightingReadback {
+    State(LightingState),
+    SceneStatus {
+        revision: u32,
+        scene_len: u16,
+        policy: LightingLayerPolicy,
+    },
+    ScenesPage(LightingScenesPage),
+    SceneTransaction(LightingSceneTransaction),
+    Unit,
+}
+
+fn expect_state(result: LightingResult<RynkLightingReadback>) -> LightingResult<LightingState> {
+    match result? {
+        RynkLightingReadback::State(state) => Ok(state),
+        _ => {
+            debug_assert!(false, "adapter answered a state command with a non-state readback");
+            Err(LightingError::InvalidRequest)
+        }
     }
 }
 
@@ -115,7 +168,7 @@ pub(in crate::host::rynk) struct MailboxRequest {
 
 struct MailboxResponse {
     id: u32,
-    result: LightingResult<LightingState>,
+    result: LightingResult<RynkLightingReadback>,
 }
 
 impl RynkLightingMailbox {
@@ -131,7 +184,7 @@ impl RynkLightingMailbox {
         }
     }
 
-    async fn request(&self, command: RynkLightingCommand) -> LightingResult<LightingState> {
+    async fn request(&self, command: RynkLightingCommand) -> LightingResult<RynkLightingReadback> {
         let _caller = self.caller.lock().await;
         let id = self.allocate_id();
         self.send_and_wait(id, command).await
@@ -141,7 +194,7 @@ impl RynkLightingMailbox {
         &self,
         expected_revision: u32,
         cells: &Vec<LightingOverlayCell, RYNK_LIGHTING_TRANSACTION_CAPACITY>,
-    ) -> LightingResult<LightingState> {
+    ) -> LightingResult<RynkLightingReadback> {
         let _caller = self.caller.lock().await;
         while self.replacement.lock(|replacement| replacement.borrow().is_some()) {
             self.replacement_available.wait().await;
@@ -176,12 +229,12 @@ impl RynkLightingMailbox {
         })
     }
 
-    async fn send_and_wait(&self, id: u32, command: RynkLightingCommand) -> LightingResult<LightingState> {
+    async fn send_and_wait(&self, id: u32, command: RynkLightingCommand) -> LightingResult<RynkLightingReadback> {
         self.requests.send(MailboxRequest { id, command }).await;
         self.wait_for_reply(id).await
     }
 
-    async fn wait_for_reply(&self, id: u32) -> LightingResult<LightingState> {
+    async fn wait_for_reply(&self, id: u32) -> LightingResult<RynkLightingReadback> {
         loop {
             let response = self.response.wait().await;
             if response.id == id {
@@ -194,7 +247,7 @@ impl RynkLightingMailbox {
         self.requests.receive().await
     }
 
-    pub(in crate::host::rynk) fn reply(&self, id: u32, result: LightingResult<LightingState>) {
+    pub(in crate::host::rynk) fn reply(&self, id: u32, result: LightingResult<RynkLightingReadback>) {
         self.response.signal(MailboxResponse { id, result });
     }
 
@@ -228,6 +281,39 @@ impl Default for RynkLightingMailbox {
 
 pub(super) enum RynkLightingCommand {
     ReadState,
+    ReadSceneStatus,
+    ReadScenes {
+        expected_revision: u32,
+        offset: u16,
+    },
+    SetSceneCell {
+        expected_revision: u32,
+        cell: LightingSceneCell,
+    },
+    UnsetSceneCell {
+        expected_revision: u32,
+        layer: u8,
+        led_id: rmk_types::protocol::rynk::LightingLedId,
+    },
+    SetLayerPolicy {
+        expected_revision: u32,
+        policy: LightingLayerPolicy,
+    },
+    BeginSceneReplace {
+        expected_revision: u32,
+        cell_count: u16,
+    },
+    PutSceneChunk {
+        transaction_id: u32,
+        offset: u16,
+        cells: Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>,
+    },
+    CommitSceneReplace {
+        transaction_id: u32,
+    },
+    AbortSceneReplace {
+        transaction_id: u32,
+    },
     SetState {
         expected_revision: u32,
         state: LightingMutableState,
@@ -250,20 +336,30 @@ pub(super) enum RynkLightingCommand {
 
 /// Bridges type-erased Rynk commands into one concrete standard lighting
 /// mailbox. Boards spawn this alongside `LightingProcessor`.
-pub struct StandardRynkLightingAdapter<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize> {
+pub struct StandardRynkLightingAdapter<
+    'a,
+    const OVERLAY_CAPACITY: usize,
+    const CORE_COMMAND_CAPACITY: usize,
+    const SCENE_CAP: usize = 0,
+> {
     protocol: &'a RynkLightingMailbox,
-    core: &'a LightingMailbox<StandardCommand<OVERLAY_CAPACITY>, StandardState, StandardError, CORE_COMMAND_CAPACITY>,
+    core: &'a LightingMailbox<
+        StandardCommand<OVERLAY_CAPACITY, SCENE_CAP>,
+        StandardReply,
+        StandardError,
+        CORE_COMMAND_CAPACITY,
+    >,
     topology: LightingTopology<'a>,
 }
 
-impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize>
-    StandardRynkLightingAdapter<'a, OVERLAY_CAPACITY, CORE_COMMAND_CAPACITY>
+impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, const SCENE_CAP: usize>
+    StandardRynkLightingAdapter<'a, OVERLAY_CAPACITY, CORE_COMMAND_CAPACITY, SCENE_CAP>
 {
     pub const fn new(
         protocol: &'a RynkLightingMailbox,
         core: &'a LightingMailbox<
-            StandardCommand<OVERLAY_CAPACITY>,
-            StandardState,
+            StandardCommand<OVERLAY_CAPACITY, SCENE_CAP>,
+            StandardReply,
             StandardError,
             CORE_COMMAND_CAPACITY,
         >,
@@ -284,9 +380,214 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize>
         self.protocol.reply(request.id, result);
     }
 
-    async fn dispatch(&self, request_id: u32, command: RynkLightingCommand) -> LightingResult<LightingState> {
+    async fn request_core(
+        &self,
+        command: StandardCommand<OVERLAY_CAPACITY, SCENE_CAP>,
+    ) -> LightingResult<StandardReply> {
+        self.core
+            .request(command)
+            .await
+            .map_err(|error| map_standard_error(error, OVERLAY_CAPACITY))
+    }
+
+    async fn request_core_state(
+        &self,
+        command: StandardCommand<OVERLAY_CAPACITY, SCENE_CAP>,
+    ) -> LightingResult<StandardState> {
+        match self.request_core(command).await? {
+            StandardReply::State(state) => Ok(state),
+            _ => Err(LightingError::InvalidRequest),
+        }
+    }
+
+    /// Run a scene mutation, then persist the whole authoritative scene
+    /// configuration. Persisting by readback keeps the engine the single
+    /// source of truth instead of mirroring its insertion algorithm here.
+    async fn scene_mutation(
+        &self,
+        command: StandardCommand<OVERLAY_CAPACITY, SCENE_CAP>,
+    ) -> LightingResult<StandardState> {
+        let state = self.request_core_state(command).await?;
+        self.persist_scenes(&state).await;
+        Ok(state)
+    }
+
+    #[cfg(feature = "storage")]
+    async fn persist_scenes(&self, state: &StandardState) {
+        use crate::channel::FLASH_CHANNEL;
+        use crate::storage::FlashOperationMessage;
+
+        let mut total = state.scene_len.min(u16::MAX as usize) as u16;
+        let mut offset: u16 = 0;
+        let mut shard: u8 = 0;
+        while offset < total {
+            let Ok(StandardReply::ScenesPage(page)) = self.request_core(StandardCommand::ReadScenes { offset }).await
+            else {
+                return;
+            };
+            let cells = page.cells.as_slice();
+            if cells.is_empty() {
+                break;
+            }
+            let mut wire_cells: Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE> = Vec::new();
+            for cell in cells {
+                let Some(wire) = self.scene_cell_to_wire(*cell) else {
+                    return;
+                };
+                let _ = wire_cells.push(wire);
+            }
+            FLASH_CHANNEL
+                .send(FlashOperationMessage::LightingSceneShard {
+                    index: shard,
+                    cells: wire_cells,
+                })
+                .await;
+            offset += cells.len() as u16;
+            shard = shard.saturating_add(1);
+            total = page.total;
+        }
+        FLASH_CHANNEL
+            .send(FlashOperationMessage::LightingSceneTable {
+                len: offset,
+                policy: policy_to_wire(state.scene_policy),
+            })
+            .await;
+    }
+
+    #[cfg(not(feature = "storage"))]
+    async fn persist_scenes(&self, _state: &StandardState) {}
+
+    async fn dispatch(&self, request_id: u32, command: RynkLightingCommand) -> LightingResult<RynkLightingReadback> {
         let core_command = match command {
             RynkLightingCommand::ReadState => StandardCommand::ReadState,
+            RynkLightingCommand::ReadSceneStatus => {
+                let state = self.request_core_state(StandardCommand::ReadState).await?;
+                return Ok(RynkLightingReadback::SceneStatus {
+                    revision: state.revision,
+                    scene_len: state.scene_len.min(u16::MAX as usize) as u16,
+                    policy: policy_to_wire(state.scene_policy),
+                });
+            }
+            RynkLightingCommand::ReadScenes {
+                expected_revision,
+                offset,
+            } => {
+                let page = match self.request_core(StandardCommand::ReadScenes { offset }).await? {
+                    StandardReply::ScenesPage(page) => page,
+                    _ => return Err(LightingError::InvalidRequest),
+                };
+                // The page is read atomically by the engine; pinning only has
+                // to compare the revision it was served under.
+                if page.revision != expected_revision {
+                    return Err(LightingError::StateRevisionConflict {
+                        expected: expected_revision,
+                        current: page.revision,
+                    });
+                }
+                let mut items: Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE> = Vec::new();
+                for cell in page.cells.as_slice() {
+                    let wire = self.scene_cell_to_wire(*cell).ok_or(LightingError::InvalidRequest)?;
+                    items.push(wire).map_err(|_| LightingError::InvalidRequest)?;
+                }
+                return Ok(RynkLightingReadback::ScenesPage(LightingScenesPage {
+                    revision: page.revision,
+                    total_count: page.total,
+                    items,
+                }));
+            }
+            RynkLightingCommand::SetSceneCell {
+                expected_revision,
+                cell,
+            } => {
+                let cell = self.scene_cell_from_wire(cell)?;
+                let state = self
+                    .scene_mutation(StandardCommand::SetSceneCellIfRevision {
+                        expected_revision,
+                        cell,
+                    })
+                    .await?;
+                return Ok(RynkLightingReadback::State(state_to_wire(state)));
+            }
+            RynkLightingCommand::UnsetSceneCell {
+                expected_revision,
+                layer,
+                led_id,
+            } => {
+                let slot = self
+                    .topology
+                    .slot(LedId(led_id.0))
+                    .ok_or(LightingError::UnknownLed { led_id })?;
+                let state = self
+                    .scene_mutation(StandardCommand::UnsetSceneCellIfRevision {
+                        expected_revision,
+                        layer,
+                        slot,
+                    })
+                    .await?;
+                return Ok(RynkLightingReadback::State(state_to_wire(state)));
+            }
+            RynkLightingCommand::SetLayerPolicy {
+                expected_revision,
+                policy,
+            } => {
+                let state = self
+                    .scene_mutation(StandardCommand::SetLayerPolicyIfRevision {
+                        expected_revision,
+                        policy: policy_from_wire(policy),
+                    })
+                    .await?;
+                return Ok(RynkLightingReadback::State(state_to_wire(state)));
+            }
+            RynkLightingCommand::BeginSceneReplace {
+                expected_revision,
+                cell_count,
+            } => {
+                let reply = self
+                    .request_core(StandardCommand::BeginSceneReplace {
+                        expected_revision,
+                        cell_count,
+                    })
+                    .await?;
+                return match reply {
+                    StandardReply::SceneTransaction { id, cell_count } => {
+                        Ok(RynkLightingReadback::SceneTransaction(LightingSceneTransaction {
+                            id,
+                            cell_count,
+                        }))
+                    }
+                    _ => Err(LightingError::InvalidRequest),
+                };
+            }
+            RynkLightingCommand::PutSceneChunk {
+                transaction_id,
+                offset,
+                cells,
+            } => {
+                let mut chunk = SceneChunk::new();
+                for cell in &cells {
+                    chunk
+                        .push(self.scene_cell_from_wire(*cell)?)
+                        .map_err(|error| map_standard_error(error, OVERLAY_CAPACITY))?;
+                }
+                self.request_core_state(StandardCommand::PutSceneChunk {
+                    transaction_id,
+                    offset,
+                    cells: chunk,
+                })
+                .await?;
+                return Ok(RynkLightingReadback::Unit);
+            }
+            RynkLightingCommand::CommitSceneReplace { transaction_id } => {
+                let state = self
+                    .scene_mutation(StandardCommand::CommitSceneReplace { transaction_id })
+                    .await?;
+                return Ok(RynkLightingReadback::State(state_to_wire(state)));
+            }
+            RynkLightingCommand::AbortSceneReplace { transaction_id } => {
+                self.request_core_state(StandardCommand::AbortSceneReplace { transaction_id })
+                    .await?;
+                return Ok(RynkLightingReadback::Unit);
+            }
             RynkLightingCommand::SetState {
                 expected_revision,
                 state,
@@ -333,11 +634,10 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize>
             }
         };
 
-        self.core
-            .request(core_command)
+        self.request_core_state(core_command)
             .await
             .map(state_to_wire)
-            .map_err(|error| map_standard_error(error, OVERLAY_CAPACITY))
+            .map(RynkLightingReadback::State)
     }
 
     fn overlay_cell(&self, cell: LightingOverlayCell) -> LightingResult<OverlayCell> {
@@ -352,10 +652,60 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize>
             ttl_ms: cell.ttl_ms.and_then(NonZeroU32::new),
         })
     }
+
+    fn scene_cell_from_wire(&self, cell: LightingSceneCell) -> LightingResult<SceneTableCell> {
+        cell.validate()?;
+        let slot = self
+            .topology
+            .slot(LedId(cell.led_id.0))
+            .ok_or(LightingError::UnknownLed { led_id: cell.led_id })?;
+        Ok(SceneTableCell {
+            layer: cell.layer,
+            slot,
+            effect: effect_from_wire(cell.effect),
+        })
+    }
+
+    fn scene_cell_to_wire(&self, cell: SceneTableCell) -> Option<LightingSceneCell> {
+        let led = self.topology.led(cell.slot)?;
+        Some(LightingSceneCell {
+            layer: cell.layer,
+            led_id: rmk_types::protocol::rynk::LightingLedId(led.id.0),
+            effect: effect_to_wire(cell.effect),
+        })
+    }
+}
+
+/// Install persisted scene configuration into a standard engine at startup,
+/// before the engine begins serving commands. Cells whose stable LED id no
+/// longer resolves against the current topology are skipped rather than
+/// failing the boot.
+pub fn install_lighting_scenes<Extension, Status, const N: usize, const OVERLAY_CAP: usize, const SCENE_CAP: usize>(
+    engine: &mut StandardLightingEngine<'_, Extension, Status, N, OVERLAY_CAP, SCENE_CAP>,
+    topology: &LightingTopology<'_>,
+    cells: &[LightingSceneCell],
+    policy: Option<LightingLayerPolicy>,
+) {
+    if let Some(policy) = policy {
+        engine.install_scene_policy(policy_from_wire(policy));
+    }
+    for cell in cells {
+        if cell.validate().is_err() {
+            continue;
+        }
+        let Some(slot) = topology.slot(LedId(cell.led_id.0)) else {
+            continue;
+        };
+        let _ = engine.install_scene_cell(SceneTableCell {
+            layer: cell.layer,
+            slot,
+            effect: effect_from_wire(cell.effect),
+        });
+    }
 }
 
-impl<const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize> Runnable
-    for StandardRynkLightingAdapter<'_, OVERLAY_CAPACITY, CORE_COMMAND_CAPACITY>
+impl<const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, const SCENE_CAP: usize> Runnable
+    for StandardRynkLightingAdapter<'_, OVERLAY_CAPACITY, CORE_COMMAND_CAPACITY, SCENE_CAP>
 {
     async fn run(&mut self) -> ! {
         loop {
@@ -438,6 +788,60 @@ const fn rgb_from_wire(color: LightingRgb8) -> Rgb8 {
     Rgb8::new(color.r, color.g, color.b)
 }
 
+const fn rgb_to_wire(color: Rgb8) -> LightingRgb8 {
+    LightingRgb8 {
+        r: color.r,
+        g: color.g,
+        b: color.b,
+    }
+}
+
+fn effect_to_wire(effect: BuiltinEffect) -> rmk_types::protocol::rynk::LightingEffect {
+    use rmk_types::protocol::rynk::LightingEffect;
+
+    match effect {
+        BuiltinEffect::Solid { color } => LightingEffect::Solid {
+            color: rgb_to_wire(color),
+        },
+        BuiltinEffect::Blink {
+            color,
+            period_ms,
+            phase_ms,
+            duty,
+        } => LightingEffect::Blink {
+            color: rgb_to_wire(color),
+            period_ms,
+            phase_ms,
+            duty,
+        },
+        BuiltinEffect::Breathe {
+            color,
+            period_ms,
+            phase_ms,
+            step_ms,
+        } => LightingEffect::Breathe {
+            color: rgb_to_wire(color),
+            period_ms,
+            phase_ms,
+            step_ms,
+        },
+    }
+}
+
+pub(super) const fn policy_from_wire(policy: LightingLayerPolicy) -> LayerPolicy {
+    match policy {
+        LightingLayerPolicy::EffectiveOnly => LayerPolicy::EffectiveOnly,
+        LightingLayerPolicy::ActiveStack => LayerPolicy::ActiveStack,
+    }
+}
+
+pub(super) const fn policy_to_wire(policy: LayerPolicy) -> LightingLayerPolicy {
+    match policy {
+        LayerPolicy::EffectiveOnly => LightingLayerPolicy::EffectiveOnly,
+        LayerPolicy::ActiveStack => LightingLayerPolicy::ActiveStack,
+    }
+}
+
 fn map_standard_error(error: StandardError, capacity: usize) -> LightingError {
     match error {
         StandardError::RevisionConflict { expected, current } => {
@@ -447,6 +851,16 @@ fn map_standard_error(error: StandardError, capacity: usize) -> LightingError {
         StandardError::DeadlineOverflow => LightingError::InvalidTtl,
         StandardError::ReplicaSlot(_) => LightingError::Unsupported,
         StandardError::Render(_) => LightingError::Unsupported,
+        StandardError::SceneFull { capacity } => LightingError::SceneFull {
+            capacity: capacity.min(u16::MAX as usize) as u16,
+        },
+        StandardError::SceneSlotOutOfRange { .. } | StandardError::InvalidSceneRequest => LightingError::InvalidRequest,
+        StandardError::SceneTransactionBusy => LightingError::TransactionBusy,
+        StandardError::InvalidSceneTransaction => LightingError::InvalidTransaction,
+        StandardError::SceneTransactionExpired => LightingError::TransactionExpired,
+        StandardError::SceneTransactionIncomplete { expected, received } => {
+            LightingError::TransactionIncomplete { expected, received }
+        }
     }
 }
 
@@ -540,7 +954,7 @@ mod tests {
             ));
             let abandoned_cells = mailbox.take_replacement(abandoned.id).await;
             assert_eq!(abandoned_cells.as_slice(), &[cell(10)]);
-            mailbox.reply(abandoned.id, Ok(state(1)));
+            mailbox.reply(abandoned.id, Ok(RynkLightingReadback::State(state(1))));
 
             let current = mailbox.receive().await;
             assert!(matches!(
@@ -549,15 +963,15 @@ mod tests {
             ));
             let current_cells = mailbox.take_replacement(current.id).await;
             assert_eq!(current_cells.as_slice(), &[cell(20)]);
-            mailbox.reply(current.id, Ok(state(2)));
+            mailbox.reply(current.id, Ok(RynkLightingReadback::State(state(2))));
         }));
-        assert_eq!(reply, Ok(state(2)));
+        assert_eq!(reply, Ok(RynkLightingReadback::State(state(2))));
     }
 
     #[test]
     fn replacement_rejects_duplicate_stable_ids_before_reaching_the_core() {
         let protocol = RynkLightingMailbox::new();
-        let core = LightingMailbox::<StandardCommand<2>, StandardState, StandardError, 1>::new();
+        let core = LightingMailbox::<StandardCommand<2>, StandardReply, StandardError, 1>::new();
         let mut adapter = StandardRynkLightingAdapter::new(&protocol, &core, topology());
         let mut cells = Vec::new();
         cells.push(cell(10)).unwrap();
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 0254786ca..fa6e6d9ed 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -15,7 +15,7 @@ use postcard::experimental::max_size::MaxSize;
 #[cfg(feature = "lighting")]
 pub use lighting::{
     RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
-    StandardRynkLightingAdapter,
+    RynkLightingReadback, StandardRynkLightingAdapter, install_lighting_scenes,
 };
 use rmk_types::constants::RYNK_BUFFER_SIZE;
 use rmk_types::protocol::rynk::{
@@ -165,7 +165,14 @@ impl<'a> RynkService<'a> {
             | Cmd::BeginLightingOverlayReplace
             | Cmd::PutLightingOverlayChunk
             | Cmd::CommitLightingOverlayReplace
-            | Cmd::AbortLightingOverlayReplace => self.lock_config.write_requires_unlock,
+            | Cmd::AbortLightingOverlayReplace
+            | Cmd::SetLightingSceneCell
+            | Cmd::UnsetLightingSceneCell
+            | Cmd::SetLightingLayerPolicy
+            | Cmd::BeginLightingSceneReplace
+            | Cmd::PutLightingSceneChunk
+            | Cmd::CommitLightingSceneReplace
+            | Cmd::AbortLightingSceneReplace => self.lock_config.write_requires_unlock,
             _ => false,
         }
     }
@@ -279,6 +286,24 @@ impl<'a> RynkService<'a> {
             Cmd::CommitLightingOverlayReplace => handlers::lighting::serve_commit(self, session, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::AbortLightingOverlayReplace => handlers::lighting::serve_abort(self, session, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingSceneStatus => Serve::<command::GetLightingSceneStatus, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingScenes => Serve::<command::GetLightingScenes, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::SetLightingSceneCell => Serve::<command::SetLightingSceneCell, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::UnsetLightingSceneCell => Serve::<command::UnsetLightingSceneCell, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::SetLightingLayerPolicy => Serve::<command::SetLightingLayerPolicy, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::BeginLightingSceneReplace => Serve::<command::BeginLightingSceneReplace, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::PutLightingSceneChunk => Serve::<command::PutLightingSceneChunk, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::CommitLightingSceneReplace => Serve::<command::CommitLightingSceneReplace, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::AbortLightingSceneReplace => Serve::<command::AbortLightingSceneReplace, _>::serve(self, msg).await,
 
             _ => Err(RynkError::UnknownCmd),
         }
diff --git a/rmk/src/host/via/rgb_matrix.rs b/rmk/src/host/via/rgb_matrix.rs
index c18dca989..56d0648ec 100644
--- a/rmk/src/host/via/rgb_matrix.rs
+++ b/rmk/src/host/via/rgb_matrix.rs
@@ -210,17 +210,19 @@ mod standard_control {
         BackgroundMode as ViaMode, BackgroundPatch as ViaPatch, BackgroundState as ViaState, ViaRgbMatrixControl,
     };
     use crate::lighting::processor::LightingMailbox;
-    use crate::lighting::standard::{BackgroundMode, BackgroundPatch, StandardCommand, StandardError, StandardState};
+    use crate::lighting::standard::{
+        BackgroundMode, BackgroundPatch, StandardCommand, StandardError, StandardReply, StandardState,
+    };
 
     /// Mailbox-backed live control. Persistence remains unavailable until RMK
     /// has a correlated durable completion path.
     pub struct StandardControl<'a, const OVERLAY_CAP: usize, const MAILBOX_CAP: usize> {
-        mailbox: &'a LightingMailbox<StandardCommand<OVERLAY_CAP>, StandardState, StandardError, MAILBOX_CAP>,
+        mailbox: &'a LightingMailbox<StandardCommand<OVERLAY_CAP>, StandardReply, StandardError, MAILBOX_CAP>,
     }
 
     impl<'a, const OVERLAY_CAP: usize, const MAILBOX_CAP: usize> StandardControl<'a, OVERLAY_CAP, MAILBOX_CAP> {
         pub const fn new(
-            mailbox: &'a LightingMailbox<StandardCommand<OVERLAY_CAP>, StandardState, StandardError, MAILBOX_CAP>,
+            mailbox: &'a LightingMailbox<StandardCommand<OVERLAY_CAP>, StandardReply, StandardError, MAILBOX_CAP>,
         ) -> Self {
             Self { mailbox }
         }
@@ -246,6 +248,10 @@ mod standard_control {
         }
     }
 
+    fn reply_state(reply: StandardReply) -> Result<StandardState, Error> {
+        reply.state().ok_or(Error::PersistenceUnavailable)
+    }
+
     fn patch(patch: ViaPatch) -> BackgroundPatch {
         BackgroundPatch {
             enabled: patch.enabled,
@@ -269,16 +275,18 @@ mod standard_control {
             self.mailbox
                 .request(StandardCommand::ReadState)
                 .await
-                .map(state)
                 .map_err(Error::Lighting)
+                .and_then(reply_state)
+                .map(state)
         }
 
         async fn patch_background(&self, update: ViaPatch) -> Result<ViaState, Self::Error> {
             self.mailbox
                 .request(StandardCommand::PatchBackground(patch(update)))
                 .await
-                .map(state)
                 .map_err(Error::Lighting)
+                .and_then(reply_state)
+                .map(state)
         }
 
         async fn save_background(&self) -> Result<(), Self::Error> {
@@ -474,9 +482,9 @@ mod tests {
     #[test]
     fn standard_mailbox_control_does_not_claim_persistence() {
         use crate::lighting::processor::LightingMailbox;
-        use crate::lighting::standard::{StandardCommand, StandardError, StandardState};
+        use crate::lighting::standard::{StandardCommand, StandardError, StandardReply};
 
-        let mailbox = LightingMailbox::<StandardCommand<1>, StandardState, StandardError, 1>::new();
+        let mailbox = LightingMailbox::<StandardCommand<1>, StandardReply, StandardError, 1>::new();
         let control = StandardControl::new(&mailbox);
         assert_eq!(
             block_on(control.save_background()),
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index 437762692..eefd00209 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -42,8 +42,9 @@ pub use source::{
 };
 pub use standard::{
     BackgroundMode, BackgroundPatch, BackgroundState, EmptySource, OverlayBatch, OverlayCell, ReplicaSlotError,
-    StandardCommand, StandardError, StandardInput, StandardLightingEngine, StandardMutableState, StandardReplicaSlot,
-    StandardReplicaState, StandardState, UniformBackground,
+    SCENE_CHUNK_SIZE, SCENE_TRANSACTION_TIMEOUT_MS, SceneChunk, ScenePage, SceneTable, SceneTableCell, StandardCommand,
+    StandardError, StandardInput, StandardLightingEngine, StandardMutableState, StandardReplicaSlot,
+    StandardReplicaState, StandardReply, StandardState, UniformBackground,
 };
 pub use topology::*;
 
diff --git a/rmk/src/lighting/processor.rs b/rmk/src/lighting/processor.rs
index a176ea667..2bbf649c8 100644
--- a/rmk/src/lighting/processor.rs
+++ b/rmk/src/lighting/processor.rs
@@ -75,6 +75,19 @@ impl<Command, Reply, Error, const CAPACITY: usize> LightingMailbox<Command, Repl
         self.retry_output.signal(());
     }
 
+    /// Service side: receive the next command. Normally only
+    /// [`LightingProcessor`] drives this; it is public for board-specific
+    /// executors and deterministic tests.
+    pub async fn receive_request(&self) -> (u32, Command) {
+        let request = self.requests.receive().await;
+        (request.id, request.command)
+    }
+
+    /// Service side: publish the reply for a previously received command.
+    pub fn publish_reply(&self, id: u32, result: Result<Reply, Error>) {
+        self.response.signal(MailboxResponse { id, result });
+    }
+
     async fn receive(&self) -> MailboxRequest<Command> {
         self.requests.receive().await
     }
diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index 02e2e2e70..db8f0906e 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -12,18 +12,25 @@ use core::num::NonZeroU32;
 use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
 use rmk_types::action::LightAction;
 
+use super::Rgb8;
 use super::compositor::{
     Compositor, Contribution, LightingSource, LogicalFrame, RenderError, RenderInput as SourceRenderInput,
 };
-use super::context::LightingContextProvider;
+use super::context::{LightingContext, LightingContextProvider};
 use super::effect::{BuiltinEffect, LightingEffect};
 use super::output::BrightnessTransform;
 use super::service::{CommandResult, Invalidation, LightingEngine, RenderInput, RenderOutcome};
-use super::source::{LayerScenes, OverlayError, OverlayUpdate, TtlOverlay};
+use super::source::{LayerPolicy, LayerScenes, OverlayError, OverlayUpdate, TtlOverlay};
 use super::topology::LedSlot;
-use super::{LightingContext, Rgb8};
 use crate::RawMutex;
 
+/// Cells per scene page/replacement chunk. Kept equal to the wire chunk size
+/// so protocol adapters can forward chunks without re-batching.
+pub const SCENE_CHUNK_SIZE: usize = 8;
+
+/// A staged scene replacement expires after this much command inactivity.
+pub const SCENE_TRANSACTION_TIMEOUT_MS: u64 = 5_000;
+
 /// Stable default priority bands. Equal-priority call order remains stable.
 pub mod priority {
     pub const BACKGROUND: u8 = 0;
@@ -223,8 +230,252 @@ impl<const CAP: usize> Default for OverlayBatch<CAP> {
     }
 }
 
+/// One durable scene cell: an effect bound to a local slot on one layer.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct SceneTableCell {
+    pub layer: u8,
+    pub slot: LedSlot,
+    pub effect: BuiltinEffect,
+}
+
+const EMPTY_SCENE_CELL: SceneTableCell = SceneTableCell {
+    layer: 0,
+    slot: LedSlot(0),
+    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+};
+
+/// Fixed-capacity, owned scene chunk suitable for a bounded async mailbox.
+/// One chunk is both a page of readback and a replacement-staging step.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct SceneChunk {
+    cells: [SceneTableCell; SCENE_CHUNK_SIZE],
+    len: usize,
+}
+
+impl Default for SceneChunk {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl SceneChunk {
+    pub const fn new() -> Self {
+        Self {
+            cells: [EMPTY_SCENE_CELL; SCENE_CHUNK_SIZE],
+            len: 0,
+        }
+    }
+
+    pub fn push(&mut self, cell: SceneTableCell) -> Result<(), StandardError> {
+        if self.len == SCENE_CHUNK_SIZE {
+            return Err(StandardError::InvalidSceneRequest);
+        }
+        self.cells[self.len] = cell;
+        self.len += 1;
+        Ok(())
+    }
+
+    pub fn as_slice(&self) -> &[SceneTableCell] {
+        &self.cells[..self.len]
+    }
+}
+
+/// Fixed-capacity runtime scene table with layer-aware composition.
+///
+/// Cells are unique per `(layer, slot)` and stored in insertion order; order
+/// is irrelevant to rendering because layer precedence comes from the policy
+/// and same-layer cells can never target the same slot.
+#[derive(Copy, Clone, Debug)]
+pub struct SceneTable<const CAP: usize> {
+    cells: [SceneTableCell; CAP],
+    len: usize,
+    policy: LayerPolicy,
+}
+
+impl<const CAP: usize> SceneTable<CAP> {
+    pub const fn new() -> Self {
+        Self {
+            cells: [EMPTY_SCENE_CELL; CAP],
+            len: 0,
+            policy: LayerPolicy::ActiveStack,
+        }
+    }
+
+    pub const fn len(&self) -> usize {
+        self.len
+    }
+
+    pub const fn is_empty(&self) -> bool {
+        self.len == 0
+    }
+
+    pub const fn policy(&self) -> LayerPolicy {
+        self.policy
+    }
+
+    pub fn set_policy(&mut self, policy: LayerPolicy) -> bool {
+        let changed = self.policy != policy;
+        self.policy = policy;
+        changed
+    }
+
+    pub fn as_slice(&self) -> &[SceneTableCell] {
+        &self.cells[..self.len]
+    }
+
+    /// Insert or update the cell addressed by `(layer, slot)`.
+    pub fn set(&mut self, cell: SceneTableCell) -> Result<(), StandardError> {
+        if let Some(existing) = self.cells[..self.len]
+            .iter_mut()
+            .find(|existing| existing.layer == cell.layer && existing.slot == cell.slot)
+        {
+            *existing = cell;
+            return Ok(());
+        }
+        if self.len == CAP {
+            return Err(StandardError::SceneFull { capacity: CAP });
+        }
+        self.cells[self.len] = cell;
+        self.len += 1;
+        Ok(())
+    }
+
+    /// Remove the cell addressed by `(layer, slot)`.
+    pub fn unset(&mut self, layer: u8, slot: LedSlot) -> bool {
+        if let Some(index) = self.cells[..self.len]
+            .iter()
+            .position(|cell| cell.layer == layer && cell.slot == slot)
+        {
+            self.len -= 1;
+            self.cells[index] = self.cells[self.len];
+            true
+        } else {
+            false
+        }
+    }
+
+    pub fn clear(&mut self) {
+        self.len = 0;
+    }
+
+    /// One readback page starting at `offset`, clamped at the table's end.
+    pub fn page(&self, offset: u16) -> SceneChunk {
+        let start = (offset as usize).min(self.len);
+        let end = (start + SCENE_CHUNK_SIZE).min(self.len);
+        let mut chunk = SceneChunk::new();
+        for cell in &self.cells[start..end] {
+            chunk.push(*cell).expect("page is chunk-bounded");
+        }
+        chunk
+    }
+
+    fn cell_for_layer(&self, layer: u8, wanted: &mut usize) -> Option<&SceneTableCell> {
+        for cell in self.cells[..self.len].iter().filter(|cell| cell.layer == layer) {
+            if *wanted == 0 {
+                return Some(cell);
+            }
+            *wanted -= 1;
+        }
+        None
+    }
+
+    fn cell_at(&self, context: &LightingContext, mut wanted: usize) -> &SceneTableCell {
+        let effective = context.layers.effective;
+        match self.policy {
+            LayerPolicy::EffectiveOnly => self.cell_for_layer(effective, &mut wanted),
+            LayerPolicy::ActiveStack => {
+                let default = context.layers.default;
+                if let Some(cell) = self.cell_for_layer(default, &mut wanted) {
+                    return cell;
+                }
+                for layer in 0..super::context::LayerState::CAPACITY {
+                    if layer != default
+                        && layer != effective
+                        && context.layers.is_active(layer)
+                        && let Some(cell) = self.cell_for_layer(layer, &mut wanted)
+                    {
+                        return cell;
+                    }
+                }
+                if effective != default {
+                    self.cell_for_layer(effective, &mut wanted)
+                } else {
+                    None
+                }
+            }
+        }
+        .expect("LightingSource index must be below len")
+    }
+
+    fn included_len(&self, context: &LightingContext) -> usize {
+        let effective = context.layers.effective;
+        self.cells[..self.len]
+            .iter()
+            .filter(|cell| match self.policy {
+                LayerPolicy::EffectiveOnly => cell.layer == effective,
+                LayerPolicy::ActiveStack => {
+                    cell.layer == context.layers.default
+                        || cell.layer == effective
+                        || context.layers.is_active(cell.layer)
+                }
+            })
+            .count()
+    }
+}
+
+impl<const CAP: usize> Default for SceneTable<CAP> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<const CAP: usize> PartialEq for SceneTable<CAP> {
+    fn eq(&self, other: &Self) -> bool {
+        // Cells past `len` are stale storage, not state.
+        self.policy == other.policy && self.as_slice() == other.as_slice()
+    }
+}
+
+impl<const CAP: usize> Eq for SceneTable<CAP> {}
+
+impl<Context, const CAP: usize> LightingSource<Rgb8, Context> for SceneTable<CAP>
+where
+    Context: LightingContextProvider,
+{
+    fn len(&self, input: &SourceRenderInput<'_, Context>) -> usize {
+        self.included_len(input.context.lighting_context())
+    }
+
+    fn slot(&self, index: usize, input: &SourceRenderInput<'_, Context>) -> LedSlot {
+        self.cell_at(input.context.lighting_context(), index).slot
+    }
+
+    fn contribution(&mut self, index: usize, input: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
+        Contribution::Opaque(
+            self.cell_at(input.context.lighting_context(), index)
+                .effect
+                .sample(input.now_ms),
+        )
+    }
+}
+
+/// One in-progress, chunk-staged atomic scene replacement.
+///
+/// The overlay replacement stages host-side because a whole overlay batch
+/// fits one mailbox command. A scene table is an order of magnitude larger,
+/// so its transaction stages inside the engine via bounded chunks instead of
+/// forcing kilobyte-sized command payloads through every mailbox.
+struct SceneReplace<const CAP: usize> {
+    id: u32,
+    expected_revision: u32,
+    expected_count: u16,
+    cells: [SceneTableCell; CAP],
+    len: usize,
+    last_activity_ms: u64,
+}
+
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub enum StandardCommand<const OVERLAY_CAP: usize> {
+pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
     SetOutputEnabled(bool),
     SetOutputBrightness(u8),
     SetBackground(BackgroundState),
@@ -255,11 +506,45 @@ pub enum StandardCommand<const OVERLAY_CAP: usize> {
     /// Atomically export all state needed by a renderer replica. The larger
     /// snapshot moves through the referenced slot so it does not inflate
     /// every element of the bounded command queue.
-    ExportReplica(&'static StandardReplicaSlot<OVERLAY_CAP>),
+    ExportReplica(&'static StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP>),
     /// Atomically install a snapshot previously placed in the referenced
     /// slot. Intended for a renderer replica, not a second authority.
-    ApplyReplica(&'static StandardReplicaSlot<OVERLAY_CAP>),
+    ApplyReplica(&'static StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP>),
     ReadState,
+    SetSceneCellIfRevision {
+        expected_revision: u32,
+        cell: SceneTableCell,
+    },
+    UnsetSceneCellIfRevision {
+        expected_revision: u32,
+        layer: u8,
+        slot: LedSlot,
+    },
+    SetLayerPolicyIfRevision {
+        expected_revision: u32,
+        policy: LayerPolicy,
+    },
+    /// Reserve the engine's single scene-staging transaction. The expected
+    /// revision is recorded here and enforced atomically at commit.
+    BeginSceneReplace {
+        expected_revision: u32,
+        cell_count: u16,
+    },
+    PutSceneChunk {
+        transaction_id: u32,
+        offset: u16,
+        cells: SceneChunk,
+    },
+    CommitSceneReplace {
+        transaction_id: u32,
+    },
+    AbortSceneReplace {
+        transaction_id: u32,
+    },
+    /// One page of the stored scene table starting at `offset`.
+    ReadScenes {
+        offset: u16,
+    },
 }
 
 /// Mutable standard state excluding the transient overlay contents and the
@@ -278,6 +563,36 @@ pub struct StandardState {
     pub output_brightness: u8,
     pub background: BackgroundState,
     pub overlay_len: usize,
+    pub scene_len: usize,
+    pub scene_policy: LayerPolicy,
+}
+
+/// One page of stored scene cells with the revision it was read under.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ScenePage {
+    pub revision: u32,
+    pub total: u16,
+    pub cells: SceneChunk,
+}
+
+/// Protocol-independent readback for [`StandardCommand`]s. Most commands
+/// answer with authoritative [`StandardState`]; scene reads and transaction
+/// reservation carry their own shapes.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum StandardReply {
+    State(StandardState),
+    ScenesPage(ScenePage),
+    SceneTransaction { id: u32, cell_count: u16 },
+}
+
+impl StandardReply {
+    /// The state readback carried by state-shaped replies.
+    pub const fn state(self) -> Option<StandardState> {
+        match self {
+            Self::State(state) => Some(state),
+            _ => None,
+        }
+    }
 }
 
 /// Complete declarative state needed by a standard-engine renderer replica.
@@ -286,11 +601,16 @@ pub struct StandardState {
 /// Applying the snapshot anchors the replica's local monotonic clock to that
 /// value; subsequent animation frames are sampled locally without link
 /// traffic. Overlay TTLs are remaining lifetimes at the same instant.
+///
+/// The runtime scene table travels with the snapshot: replicas must render
+/// host-configured per-layer scenes exactly like the authority, and they
+/// never receive the incremental scene mutation commands themselves.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct StandardReplicaState<const OVERLAY_CAP: usize> {
+pub struct StandardReplicaState<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
     pub revision: u32,
     pub mutable: StandardMutableState,
     pub overlay: OverlayBatch<OVERLAY_CAP>,
+    pub scenes: SceneTable<SCENE_CAP>,
     pub context: LightingContext,
     pub sample_time_ms: u64,
 }
@@ -306,18 +626,18 @@ pub enum ReplicaSlotError {
 /// The lighting mailbox serializes access. Keeping the large snapshot out of
 /// [`StandardCommand`] prevents command-channel capacity from multiplying its
 /// RAM cost on small MCUs.
-pub struct StandardReplicaSlot<const OVERLAY_CAP: usize> {
-    value: BlockingMutex<RawMutex, RefCell<Option<StandardReplicaState<OVERLAY_CAP>>>>,
+pub struct StandardReplicaSlot<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
+    value: BlockingMutex<RawMutex, RefCell<Option<StandardReplicaState<OVERLAY_CAP, SCENE_CAP>>>>,
 }
 
-impl<const OVERLAY_CAP: usize> StandardReplicaSlot<OVERLAY_CAP> {
+impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
     pub const fn new() -> Self {
         Self {
             value: BlockingMutex::new(RefCell::new(None)),
         }
     }
 
-    pub fn put(&self, state: StandardReplicaState<OVERLAY_CAP>) -> Result<(), ReplicaSlotError> {
+    pub fn put(&self, state: StandardReplicaState<OVERLAY_CAP, SCENE_CAP>) -> Result<(), ReplicaSlotError> {
         self.value.lock(|value| {
             let mut value = value.borrow_mut();
             if value.is_some() {
@@ -329,31 +649,31 @@ impl<const OVERLAY_CAP: usize> StandardReplicaSlot<OVERLAY_CAP> {
         })
     }
 
-    pub fn take(&self) -> Result<StandardReplicaState<OVERLAY_CAP>, ReplicaSlotError> {
+    pub fn take(&self) -> Result<StandardReplicaState<OVERLAY_CAP, SCENE_CAP>, ReplicaSlotError> {
         self.value
             .lock(|value| value.borrow_mut().take().ok_or(ReplicaSlotError::Empty))
     }
 }
 
-impl<const OVERLAY_CAP: usize> Default for StandardReplicaSlot<OVERLAY_CAP> {
+impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> Default for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
     fn default() -> Self {
         Self::new()
     }
 }
 
-impl<const OVERLAY_CAP: usize> fmt::Debug for StandardReplicaSlot<OVERLAY_CAP> {
+impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> fmt::Debug for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("StandardReplicaSlot").finish_non_exhaustive()
     }
 }
 
-impl<const OVERLAY_CAP: usize> PartialEq for StandardReplicaSlot<OVERLAY_CAP> {
+impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> PartialEq for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
     fn eq(&self, other: &Self) -> bool {
         core::ptr::eq(self, other)
     }
 }
 
-impl<const OVERLAY_CAP: usize> Eq for StandardReplicaSlot<OVERLAY_CAP> {}
+impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> Eq for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {}
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum StandardError {
@@ -361,7 +681,26 @@ pub enum StandardError {
     Overlay(OverlayError),
     DeadlineOverflow,
     ReplicaSlot(ReplicaSlotError),
-    RevisionConflict { expected: u32, current: u32 },
+    RevisionConflict {
+        expected: u32,
+        current: u32,
+    },
+    SceneFull {
+        capacity: usize,
+    },
+    SceneSlotOutOfRange {
+        slot: LedSlot,
+    },
+    /// Malformed scene request: bad chunk order, count overflow, or a
+    /// duplicate `(layer, slot)` within one staged replacement.
+    InvalidSceneRequest,
+    SceneTransactionBusy,
+    InvalidSceneTransaction,
+    SceneTransactionExpired,
+    SceneTransactionIncomplete {
+        expected: u16,
+        received: u16,
+    },
 }
 
 impl From<RenderError> for StandardError {
@@ -419,21 +758,38 @@ impl From<LightAction> for StandardInput {
 /// End-to-end standard engine. `Extension` composes above the designated
 /// background and below layers; `Status` composes last. Either can be an
 /// external stateful source, or [`EmptySource`].
-pub struct StandardLightingEngine<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize> {
+///
+/// Static board layer scenes and the runtime [`SceneTable`] share the layer
+/// band: runtime cells apply after the static defaults, so a host-configured
+/// cell overrides a board default for the same slot while the TTL overlay
+/// still wins above both.
+pub struct StandardLightingEngine<
+    'scenes,
+    Extension,
+    Status,
+    const N: usize,
+    const OVERLAY_CAP: usize,
+    const SCENE_CAP: usize = 0,
+> {
     compositor: Compositor<Rgb8, N>,
     background: UniformBackground<N>,
     extension: Extension,
     layers: LayerScenes<'scenes, BuiltinEffect>,
+    scenes: SceneTable<SCENE_CAP>,
     overlay: TtlOverlay<BuiltinEffect, OVERLAY_CAP>,
     status: Status,
     animation_clock: AnimationClock,
+    scene_replace: Option<SceneReplace<SCENE_CAP>>,
+    scene_next_transaction: u32,
+    scene_expired_transaction: Option<u32>,
+    scene_committed_transaction: Option<u32>,
     revision: u32,
     output_enabled: bool,
     output_brightness: u8,
 }
 
-impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize>
-    StandardLightingEngine<'scenes, Extension, Status, N, OVERLAY_CAP>
+impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const SCENE_CAP: usize>
+    StandardLightingEngine<'scenes, Extension, Status, N, OVERLAY_CAP, SCENE_CAP>
 {
     pub fn new(
         background: BackgroundState,
@@ -446,9 +802,14 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize>
             background: UniformBackground::new(background),
             extension,
             layers,
+            scenes: SceneTable::new(),
             overlay: TtlOverlay::new(),
             status,
             animation_clock: AnimationClock::local(),
+            scene_replace: None,
+            scene_next_transaction: 1,
+            scene_expired_transaction: None,
+            scene_committed_transaction: None,
             revision: 0,
             output_enabled: true,
             output_brightness: u8::MAX,
@@ -462,9 +823,31 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize>
             output_brightness: self.output_brightness,
             background: self.background.state(),
             overlay_len: self.overlay.active_len(),
+            scene_len: self.scenes.len(),
+            scene_policy: self.scenes.policy(),
         }
     }
 
+    pub const fn scene_capacity() -> usize {
+        SCENE_CAP
+    }
+
+    pub const fn scenes(&self) -> &SceneTable<SCENE_CAP> {
+        &self.scenes
+    }
+
+    /// Install one persisted scene cell during startup, before the engine is
+    /// serving commands. Does not advance the concurrency revision.
+    pub fn install_scene_cell(&mut self, cell: SceneTableCell) -> Result<(), StandardError> {
+        Self::check_scene_slot(cell.slot)?;
+        self.scenes.set(cell)
+    }
+
+    /// Install the persisted layer policy during startup.
+    pub fn install_scene_policy(&mut self, policy: LayerPolicy) {
+        self.scenes.set_policy(policy);
+    }
+
     pub const fn extension(&self) -> &Extension {
         &self.extension
     }
@@ -554,7 +937,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize>
         &self,
         local_now_ms: u64,
         context: &Context,
-    ) -> Result<StandardReplicaState<OVERLAY_CAP>, StandardError> {
+    ) -> Result<StandardReplicaState<OVERLAY_CAP, SCENE_CAP>, StandardError> {
         let sample_time_ms = self.animation_clock.sample_time(local_now_ms);
         let mut overlay = OverlayBatch::new();
         for update in self.overlay.active_updates() {
@@ -576,6 +959,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize>
             revision: self.revision,
             mutable: self.mutable_state(),
             overlay,
+            scenes: self.scenes,
             context: *context.lighting_context(),
             sample_time_ms,
         })
@@ -584,7 +968,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize>
     fn apply_replica(
         &mut self,
         local_now_ms: u64,
-        replica: StandardReplicaState<OVERLAY_CAP>,
+        replica: StandardReplicaState<OVERLAY_CAP, SCENE_CAP>,
     ) -> Result<(), StandardError> {
         let mut updates = [OverlayUpdate {
             slot: LedSlot(0),
@@ -606,6 +990,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize>
         self.overlay
             .replace(replica.sample_time_ms, &updates[..replica.overlay.as_slice().len()])?;
         self.set_mutable_state(replica.mutable);
+        self.scenes = replica.scenes;
         self.revision = replica.revision;
         self.animation_clock.anchor(local_now_ms, replica.sample_time_ms);
         Ok(())
@@ -628,10 +1013,142 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize>
             expires_ms: Self::expires_at(now_ms, cell.ttl_ms)?,
         })
     }
+
+    fn check_scene_slot(slot: LedSlot) -> Result<(), StandardError> {
+        if slot.index() < N {
+            Ok(())
+        } else {
+            Err(StandardError::SceneSlotOutOfRange { slot })
+        }
+    }
+
+    fn expire_scene_replace(&mut self, now_ms: u64) {
+        if self
+            .scene_replace
+            .as_ref()
+            .is_some_and(|replace| now_ms.saturating_sub(replace.last_activity_ms) >= SCENE_TRANSACTION_TIMEOUT_MS)
+        {
+            self.scene_expired_transaction = self.scene_replace.as_ref().map(|replace| replace.id);
+            self.scene_replace = None;
+        }
+    }
+
+    fn scene_transaction_error(&self, id: u32) -> StandardError {
+        if self.scene_expired_transaction == Some(id) {
+            StandardError::SceneTransactionExpired
+        } else {
+            StandardError::InvalidSceneTransaction
+        }
+    }
+
+    fn begin_scene_replace(
+        &mut self,
+        now_ms: u64,
+        expected_revision: u32,
+        cell_count: u16,
+    ) -> Result<u32, StandardError> {
+        self.expire_scene_replace(now_ms);
+        if self.scene_replace.is_some() {
+            return Err(StandardError::SceneTransactionBusy);
+        }
+        if cell_count as usize > SCENE_CAP {
+            return Err(StandardError::SceneFull { capacity: SCENE_CAP });
+        }
+        let id = self.scene_next_transaction;
+        self.scene_next_transaction = self.scene_next_transaction.wrapping_add(1).max(1);
+        self.scene_expired_transaction = None;
+        self.scene_replace = Some(SceneReplace {
+            id,
+            expected_revision,
+            expected_count: cell_count,
+            cells: [EMPTY_SCENE_CELL; SCENE_CAP],
+            len: 0,
+            last_activity_ms: now_ms,
+        });
+        Ok(id)
+    }
+
+    fn put_scene_chunk(
+        &mut self,
+        now_ms: u64,
+        transaction_id: u32,
+        offset: u16,
+        cells: &SceneChunk,
+    ) -> Result<(), StandardError> {
+        self.expire_scene_replace(now_ms);
+        for cell in cells.as_slice() {
+            Self::check_scene_slot(cell.slot)?;
+        }
+        let error = self.scene_transaction_error(transaction_id);
+        let replace = self
+            .scene_replace
+            .as_mut()
+            .filter(|replace| replace.id == transaction_id)
+            .ok_or(error)?;
+        if offset as usize != replace.len || replace.len + cells.as_slice().len() > replace.expected_count as usize {
+            return Err(StandardError::InvalidSceneRequest);
+        }
+        for cell in cells.as_slice() {
+            if replace.cells[..replace.len]
+                .iter()
+                .any(|staged| staged.layer == cell.layer && staged.slot == cell.slot)
+            {
+                return Err(StandardError::InvalidSceneRequest);
+            }
+            replace.cells[replace.len] = *cell;
+            replace.len += 1;
+        }
+        replace.last_activity_ms = now_ms;
+        Ok(())
+    }
+
+    /// Atomically publish a complete staged replacement. A repeated commit of
+    /// the transaction most recently committed answers idempotently with
+    /// `changed == false` so a retried commit over a lossy link converges.
+    fn commit_scene_replace(&mut self, now_ms: u64, transaction_id: u32) -> Result<bool, StandardError> {
+        self.expire_scene_replace(now_ms);
+        if self.scene_committed_transaction == Some(transaction_id) && self.scene_replace.is_none() {
+            return Ok(false);
+        }
+        let error = self.scene_transaction_error(transaction_id);
+        let replace = self
+            .scene_replace
+            .as_ref()
+            .filter(|replace| replace.id == transaction_id)
+            .ok_or(error)?;
+        if replace.len != replace.expected_count as usize {
+            return Err(StandardError::SceneTransactionIncomplete {
+                expected: replace.expected_count,
+                received: replace.len as u16,
+            });
+        }
+        self.check_revision(replace.expected_revision)?;
+        let replace = self.scene_replace.take().expect("checked above");
+        self.scenes.clear();
+        for cell in &replace.cells[..replace.len] {
+            self.scenes.set(*cell).expect("staged length is table-bounded");
+        }
+        self.scene_committed_transaction = Some(transaction_id);
+        self.scene_expired_transaction = None;
+        Ok(true)
+    }
+
+    fn abort_scene_replace(&mut self, now_ms: u64, transaction_id: u32) -> Result<(), StandardError> {
+        self.expire_scene_replace(now_ms);
+        if self
+            .scene_replace
+            .as_ref()
+            .is_some_and(|replace| replace.id == transaction_id)
+        {
+            self.scene_replace = None;
+            return Ok(());
+        }
+        Err(self.scene_transaction_error(transaction_id))
+    }
 }
 
-impl<'scenes, Context, Extension, Status, const N: usize, const OVERLAY_CAP: usize> LightingEngine<Context>
-    for StandardLightingEngine<'scenes, Extension, Status, N, OVERLAY_CAP>
+impl<'scenes, Context, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const SCENE_CAP: usize>
+    LightingEngine<Context> for StandardLightingEngine<'scenes, Extension, Status, N, OVERLAY_CAP, SCENE_CAP>
 where
     Context: LightingContextProvider,
     Extension: LightingSource<Rgb8, Context>,
@@ -639,8 +1156,8 @@ where
 {
     type Frame = LogicalFrame<Rgb8, N>;
     type Input = StandardInput;
-    type Command = StandardCommand<OVERLAY_CAP>;
-    type Reply = StandardState;
+    type Command = StandardCommand<OVERLAY_CAP, SCENE_CAP>;
+    type Reply = StandardReply;
     type Error = StandardError;
 
     fn on_input(&mut self, input: Self::Input, _snapshot: &Context) -> Result<Invalidation, Self::Error> {
@@ -659,6 +1176,55 @@ where
         snapshot: &Context,
     ) -> Result<CommandResult<Self::Reply>, Self::Error> {
         let effect_now_ms = self.animation_clock.sample_time(now_ms);
+        // Scene reads and transaction bookkeeping have non-state replies or
+        // bespoke revision behavior; everything else falls through to the
+        // uniform state-readback path below.
+        match command {
+            StandardCommand::ReadScenes { offset } => {
+                return Ok(CommandResult::unchanged(StandardReply::ScenesPage(ScenePage {
+                    revision: self.revision,
+                    total: self.scenes.len().min(u16::MAX as usize) as u16,
+                    cells: self.scenes.page(offset),
+                })));
+            }
+            StandardCommand::BeginSceneReplace {
+                expected_revision,
+                cell_count,
+            } => {
+                let id = self.begin_scene_replace(now_ms, expected_revision, cell_count)?;
+                return Ok(CommandResult::unchanged(StandardReply::SceneTransaction {
+                    id,
+                    cell_count,
+                }));
+            }
+            StandardCommand::PutSceneChunk {
+                transaction_id,
+                offset,
+                cells,
+            } => {
+                self.put_scene_chunk(now_ms, transaction_id, offset, &cells)?;
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
+            StandardCommand::CommitSceneReplace { transaction_id } => {
+                // A repeated commit of the last committed transaction is
+                // answered idempotently without advancing the revision.
+                let committed = self.commit_scene_replace(now_ms, transaction_id)?;
+                if committed {
+                    self.advance_revision();
+                    return Ok(CommandResult::new(
+                        StandardReply::State(self.state()),
+                        Invalidation::Render,
+                    ));
+                }
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
+            StandardCommand::AbortSceneReplace { transaction_id } => {
+                self.abort_scene_replace(now_ms, transaction_id)?;
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
+            _ => {}
+        }
+
         let (mut invalidation, advances_revision) = match command {
             StandardCommand::SetOutputEnabled(enabled) => {
                 self.output_enabled = enabled;
@@ -787,7 +1353,52 @@ where
                 self.apply_replica(now_ms, slot.take()?)?;
                 (Invalidation::Render, false)
             }
+            StandardCommand::SetSceneCellIfRevision {
+                expected_revision,
+                cell,
+            } => {
+                self.check_revision(expected_revision)?;
+                Self::check_scene_slot(cell.slot)?;
+                self.scenes.set(cell)?;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::UnsetSceneCellIfRevision {
+                expected_revision,
+                layer,
+                slot,
+            } => {
+                self.check_revision(expected_revision)?;
+                let changed = self.scenes.unset(layer, slot);
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
+            StandardCommand::SetLayerPolicyIfRevision {
+                expected_revision,
+                policy,
+            } => {
+                self.check_revision(expected_revision)?;
+                let changed = self.scenes.set_policy(policy);
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
             StandardCommand::ReadState => (Invalidation::None, false),
+            StandardCommand::ReadScenes { .. }
+            | StandardCommand::BeginSceneReplace { .. }
+            | StandardCommand::PutSceneChunk { .. }
+            | StandardCommand::CommitSceneReplace { .. }
+            | StandardCommand::AbortSceneReplace { .. } => unreachable!("handled above"),
         };
         if advances_revision {
             self.advance_revision();
@@ -795,7 +1406,7 @@ where
                 invalidation = Invalidation::StateChanged;
             }
         }
-        Ok(CommandResult::new(self.state(), invalidation))
+        Ok(CommandResult::new(StandardReply::State(self.state()), invalidation))
     }
 
     fn render(
@@ -815,17 +1426,24 @@ where
             background,
             extension,
             layers,
+            scenes,
             overlay,
             status,
             animation_clock: _,
             output_enabled,
             output_brightness,
+            scene_replace: _,
+            scene_next_transaction: _,
+            scene_expired_transaction: _,
+            scene_committed_transaction: _,
             revision: _,
         } = self;
         let mut transaction = compositor.begin(effect_now_ms, input.snapshot, Rgb8::BLACK, frame);
         transaction.apply(priority::BACKGROUND, background)?;
         transaction.apply(priority::EXTENSION, extension)?;
         transaction.apply(priority::LAYER, layers)?;
+        // Same band, later call: runtime cells override static defaults.
+        transaction.apply(priority::LAYER, scenes)?;
         transaction.apply(priority::HOST_OVERLAY, overlay)?;
         transaction.apply(priority::STATUS, status)?;
         let mut transform = BrightnessTransform::new(if *output_enabled { *output_brightness } else { 0 });
@@ -912,8 +1530,23 @@ mod tests {
     }
 
     #[test]
-    fn replica_snapshot_preserves_state_context_ttl_and_animation_phase() {
-        let mut authority = engine();
+    fn replica_snapshot_preserves_state_scenes_context_ttl_and_animation_phase() {
+        type SceneEngine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2, 4>;
+        fn scene_engine() -> SceneEngine {
+            SceneEngine::new(
+                BackgroundState {
+                    value: 10,
+                    ..BackgroundState::default()
+                },
+                LayerScenes {
+                    scenes: &LAYERS,
+                    policy: LayerPolicy::ActiveStack,
+                },
+                EmptySource,
+                EmptySource,
+            )
+        }
+        let mut authority = scene_engine();
         let authority_context = context(3);
         authority
             .handle_command(
@@ -937,8 +1570,23 @@ mod tests {
                 &authority_context,
             )
             .unwrap();
+        let scene_cell = SceneTableCell {
+            layer: 3,
+            slot: LedSlot(0),
+            effect: BuiltinEffect::Solid { color: RED },
+        };
+        authority
+            .handle_command(
+                100,
+                StandardCommand::SetSceneCellIfRevision {
+                    expected_revision: 2,
+                    cell: scene_cell,
+                },
+                &authority_context,
+            )
+            .unwrap();
 
-        static EXPORT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+        static EXPORT: StandardReplicaSlot<2, 4> = StandardReplicaSlot::new();
         authority
             .handle_command(120, StandardCommand::ExportReplica(&EXPORT), &authority_context)
             .unwrap();
@@ -946,6 +1594,7 @@ mod tests {
         assert_eq!(snapshot.context, authority_context);
         assert_eq!(snapshot.sample_time_ms, 120);
         assert_eq!(snapshot.overlay.as_slice()[0].ttl_ms, NonZeroU32::new(80));
+        assert_eq!(snapshot.scenes.as_slice(), &[scene_cell]);
 
         let mut authority_frame = LogicalFrame::new(Rgb8::BLACK);
         authority
@@ -958,9 +1607,9 @@ mod tests {
             )
             .unwrap();
 
-        static APPLY: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+        static APPLY: StandardReplicaSlot<2, 4> = StandardReplicaSlot::new();
         APPLY.put(snapshot).unwrap();
-        let mut replica = engine();
+        let mut replica = scene_engine();
         replica
             .handle_command(1_000, StandardCommand::ApplyReplica(&APPLY), &authority_context)
             .unwrap();
@@ -976,6 +1625,7 @@ mod tests {
             .unwrap();
 
         assert_eq!(replica.state().revision, snapshot.revision);
+        assert_eq!(replica.scenes().as_slice(), &[scene_cell]);
         assert_eq!(replica_frame, authority_frame);
     }
 
@@ -990,6 +1640,7 @@ mod tests {
                 background: BackgroundState::default(),
             },
             overlay: OverlayBatch::new(),
+            scenes: SceneTable::new(),
             context: context(0),
             sample_time_ms: 9,
         };
@@ -1014,7 +1665,9 @@ mod tests {
                 &snapshot,
             )
             .unwrap()
-            .reply;
+            .reply
+            .state()
+            .unwrap();
 
         assert_eq!(reply.background.value, 77);
         assert_eq!(reply.background.enabled, before.background.enabled);
@@ -1079,7 +1732,9 @@ mod tests {
                 &snapshot,
             )
             .unwrap()
-            .reply;
+            .reply
+            .state()
+            .unwrap();
         assert_eq!(reply.revision, 2);
         assert!(!reply.output_enabled);
 
@@ -1262,4 +1917,434 @@ mod tests {
         );
         assert!(!engine.state().output_enabled);
     }
+
+    const BLUE: Rgb8 = Rgb8::new(0, 0, 200);
+
+    type SceneEngine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2, 4>;
+
+    fn scene_engine() -> SceneEngine {
+        StandardLightingEngine::new(
+            BackgroundState {
+                value: 10,
+                ..BackgroundState::default()
+            },
+            LayerScenes {
+                scenes: &LAYERS,
+                policy: LayerPolicy::ActiveStack,
+            },
+            EmptySource,
+            EmptySource,
+        )
+    }
+
+    fn scene_cell(layer: u8, slot: u16, color: Rgb8) -> SceneTableCell {
+        SceneTableCell {
+            layer,
+            slot: LedSlot(slot),
+            effect: BuiltinEffect::Solid { color },
+        }
+    }
+
+    fn set_cell(engine: &mut SceneEngine, revision: u32, cell: SceneTableCell) -> StandardState {
+        engine
+            .handle_command(
+                0,
+                StandardCommand::SetSceneCellIfRevision {
+                    expected_revision: revision,
+                    cell,
+                },
+                &context(0),
+            )
+            .unwrap()
+            .reply
+            .state()
+            .unwrap()
+    }
+
+    fn scenes_page(engine: &mut SceneEngine, offset: u16) -> ScenePage {
+        match engine
+            .handle_command(0, StandardCommand::ReadScenes { offset }, &context(0))
+            .unwrap()
+            .reply
+        {
+            StandardReply::ScenesPage(page) => page,
+            other => panic!("expected page, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn scene_crud_is_revision_checked_and_keyed_by_layer_and_slot() {
+        let mut engine = scene_engine();
+        let snapshot = context(0);
+
+        let state = set_cell(&mut engine, 0, scene_cell(1, 0, GREEN));
+        assert_eq!(state.revision, 1);
+        assert_eq!(state.scene_len, 1);
+
+        // Same (layer, slot) updates in place; a new pair appends.
+        let state = set_cell(&mut engine, 1, scene_cell(1, 0, BLUE));
+        assert_eq!(state.scene_len, 1);
+        let state = set_cell(&mut engine, 2, scene_cell(2, 0, RED));
+        assert_eq!(state.scene_len, 2);
+
+        assert_eq!(
+            engine.handle_command(
+                0,
+                StandardCommand::SetSceneCellIfRevision {
+                    expected_revision: 0,
+                    cell: scene_cell(0, 1, RED),
+                },
+                &snapshot,
+            ),
+            Err(StandardError::RevisionConflict {
+                expected: 0,
+                current: 3
+            })
+        );
+        assert_eq!(engine.state().scene_len, 2, "a stale write is all-or-nothing");
+
+        // Out-of-range slots never reach the table.
+        assert_eq!(
+            engine.handle_command(
+                0,
+                StandardCommand::SetSceneCellIfRevision {
+                    expected_revision: 3,
+                    cell: scene_cell(0, 9, RED),
+                },
+                &snapshot,
+            ),
+            Err(StandardError::SceneSlotOutOfRange { slot: LedSlot(9) })
+        );
+
+        // Unset of a missing cell keeps the revision moving but not the frame.
+        let result = engine
+            .handle_command(
+                0,
+                StandardCommand::UnsetSceneCellIfRevision {
+                    expected_revision: 3,
+                    layer: 7,
+                    slot: LedSlot(0),
+                },
+                &snapshot,
+            )
+            .unwrap();
+        assert_eq!(result.invalidation, Invalidation::StateChanged);
+        let state = result.reply.state().unwrap();
+        assert_eq!(state.scene_len, 2);
+        assert_eq!(state.revision, 4);
+
+        let state = engine
+            .handle_command(
+                0,
+                StandardCommand::UnsetSceneCellIfRevision {
+                    expected_revision: 4,
+                    layer: 1,
+                    slot: LedSlot(0),
+                },
+                &snapshot,
+            )
+            .unwrap()
+            .reply
+            .state()
+            .unwrap();
+        assert_eq!(state.scene_len, 1);
+
+        // Capacity is enforced with the table's own limit.
+        for (revision, (layer, slot)) in [(5u32, (5u8, 0u16)), (6, (5, 1)), (7, (6, 0))] {
+            set_cell(&mut engine, revision, scene_cell(layer, slot, RED));
+        }
+        assert_eq!(
+            engine.handle_command(
+                0,
+                StandardCommand::SetSceneCellIfRevision {
+                    expected_revision: 8,
+                    cell: scene_cell(9, 1, RED),
+                },
+                &snapshot,
+            ),
+            Err(StandardError::SceneFull { capacity: 4 })
+        );
+    }
+
+    #[test]
+    fn scene_pages_echo_revision_and_clamp() {
+        let mut engine = scene_engine();
+        set_cell(&mut engine, 0, scene_cell(0, 0, RED));
+        set_cell(&mut engine, 1, scene_cell(0, 1, GREEN));
+
+        let page = scenes_page(&mut engine, 0);
+        assert_eq!(page.revision, 2);
+        assert_eq!(page.total, 2);
+        assert_eq!(page.cells.as_slice().len(), 2);
+        let tail = scenes_page(&mut engine, 99);
+        assert_eq!(tail.total, 2);
+        assert!(tail.cells.as_slice().is_empty());
+    }
+
+    #[test]
+    fn runtime_scene_overrides_static_layer_and_yields_to_overlay() {
+        let mut engine = scene_engine();
+        let snapshot = context(1);
+
+        // Static layer 1 paints slot 0 RED; runtime cell overrides to BLUE.
+        set_cell(&mut engine, 0, scene_cell(1, 0, BLUE));
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 0,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(frame.as_slice()[0], BLUE);
+
+        // The TTL overlay still wins above runtime scenes.
+        engine
+            .handle_command(
+                0,
+                StandardCommand::SetOverlay(OverlayCell {
+                    slot: LedSlot(0),
+                    effect: BuiltinEffect::Solid { color: GREEN },
+                    ttl_ms: None,
+                }),
+                &snapshot,
+            )
+            .unwrap();
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 1,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(frame.as_slice()[0], GREEN);
+    }
+
+    #[test]
+    fn layer_policy_switches_between_effective_only_and_active_stack() {
+        let mut engine = scene_engine();
+        // Base layer paints slot 1; effective layer paints slot 0.
+        set_cell(&mut engine, 0, scene_cell(0, 1, GREEN));
+        set_cell(&mut engine, 1, scene_cell(1, 0, BLUE));
+        let snapshot = context(1);
+
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 0,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(frame.as_slice(), &[BLUE, GREEN], "ActiveStack falls through sparsely");
+
+        let state = engine
+            .handle_command(
+                0,
+                StandardCommand::SetLayerPolicyIfRevision {
+                    expected_revision: 2,
+                    policy: LayerPolicy::EffectiveOnly,
+                },
+                &snapshot,
+            )
+            .unwrap()
+            .reply
+            .state()
+            .unwrap();
+        assert_eq!(state.scene_policy, LayerPolicy::EffectiveOnly);
+
+        let background = Rgb8::new(10, 10, 10);
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 1,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(
+            frame.as_slice(),
+            &[BLUE, background],
+            "EffectiveOnly hides base-layer cells"
+        );
+    }
+
+    #[test]
+    fn scene_replace_is_chunked_ordered_atomic_and_idempotent() {
+        let mut engine = scene_engine();
+        let snapshot = context(0);
+        set_cell(&mut engine, 0, scene_cell(3, 0, RED));
+
+        let (id, _) = match engine
+            .handle_command(
+                10,
+                StandardCommand::BeginSceneReplace {
+                    expected_revision: 1,
+                    cell_count: 2,
+                },
+                &snapshot,
+            )
+            .unwrap()
+            .reply
+        {
+            StandardReply::SceneTransaction { id, cell_count } => (id, cell_count),
+            other => panic!("expected transaction, got {other:?}"),
+        };
+
+        // A second begin while staged is busy; out-of-order chunks rejected.
+        assert_eq!(
+            engine.handle_command(
+                11,
+                StandardCommand::BeginSceneReplace {
+                    expected_revision: 1,
+                    cell_count: 0,
+                },
+                &snapshot,
+            ),
+            Err(StandardError::SceneTransactionBusy)
+        );
+        let mut chunk = SceneChunk::new();
+        chunk.push(scene_cell(0, 0, GREEN)).unwrap();
+        assert_eq!(
+            engine.handle_command(
+                12,
+                StandardCommand::PutSceneChunk {
+                    transaction_id: id,
+                    offset: 1,
+                    cells: chunk,
+                },
+                &snapshot,
+            ),
+            Err(StandardError::InvalidSceneRequest)
+        );
+        assert_eq!(
+            engine.handle_command(
+                13,
+                StandardCommand::CommitSceneReplace { transaction_id: id },
+                &snapshot,
+            ),
+            Err(StandardError::SceneTransactionIncomplete {
+                expected: 2,
+                received: 0
+            })
+        );
+
+        let mut chunk = SceneChunk::new();
+        chunk.push(scene_cell(0, 0, GREEN)).unwrap();
+        chunk.push(scene_cell(0, 1, BLUE)).unwrap();
+        engine
+            .handle_command(
+                14,
+                StandardCommand::PutSceneChunk {
+                    transaction_id: id,
+                    offset: 0,
+                    cells: chunk,
+                },
+                &snapshot,
+            )
+            .unwrap();
+
+        let committed = engine
+            .handle_command(
+                15,
+                StandardCommand::CommitSceneReplace { transaction_id: id },
+                &snapshot,
+            )
+            .unwrap();
+        assert_eq!(committed.invalidation, Invalidation::Render);
+        let state = committed.reply.state().unwrap();
+        assert_eq!(state.scene_len, 2, "replacement drops the previous table");
+        assert_eq!(state.revision, 2);
+
+        // Retried commit answers idempotently without another revision bump.
+        let retried = engine
+            .handle_command(
+                16,
+                StandardCommand::CommitSceneReplace { transaction_id: id },
+                &snapshot,
+            )
+            .unwrap();
+        assert_eq!(retried.invalidation, Invalidation::None);
+        assert_eq!(retried.reply.state().unwrap().revision, 2);
+
+        // A conflicting revision at commit leaves the table untouched.
+        let stale = match engine
+            .handle_command(
+                20,
+                StandardCommand::BeginSceneReplace {
+                    expected_revision: 0,
+                    cell_count: 0,
+                },
+                &snapshot,
+            )
+            .unwrap()
+            .reply
+        {
+            StandardReply::SceneTransaction { id, .. } => id,
+            other => panic!("expected transaction, got {other:?}"),
+        };
+        assert_eq!(
+            engine.handle_command(
+                21,
+                StandardCommand::CommitSceneReplace { transaction_id: stale },
+                &snapshot,
+            ),
+            Err(StandardError::RevisionConflict {
+                expected: 0,
+                current: 2
+            })
+        );
+        assert_eq!(engine.state().scene_len, 2);
+        engine
+            .handle_command(
+                22,
+                StandardCommand::AbortSceneReplace { transaction_id: stale },
+                &snapshot,
+            )
+            .unwrap();
+    }
+
+    #[test]
+    fn scene_transaction_expires_after_inactivity() {
+        let mut engine = scene_engine();
+        let snapshot = context(0);
+        let id = match engine
+            .handle_command(
+                0,
+                StandardCommand::BeginSceneReplace {
+                    expected_revision: 0,
+                    cell_count: 0,
+                },
+                &snapshot,
+            )
+            .unwrap()
+            .reply
+        {
+            StandardReply::SceneTransaction { id, .. } => id,
+            other => panic!("expected transaction, got {other:?}"),
+        };
+        assert_eq!(
+            engine.handle_command(
+                SCENE_TRANSACTION_TIMEOUT_MS,
+                StandardCommand::CommitSceneReplace { transaction_id: id },
+                &snapshot,
+            ),
+            Err(StandardError::SceneTransactionExpired)
+        );
+        assert_eq!(
+            engine.handle_command(
+                SCENE_TRANSACTION_TIMEOUT_MS,
+                StandardCommand::AbortSceneReplace { transaction_id: 999 },
+                &snapshot,
+            ),
+            Err(StandardError::InvalidSceneTransaction)
+        );
+    }
 }
diff --git a/rmk/src/storage/mod.rs b/rmk/src/storage/mod.rs
index dfd9a6db6..96ce5a1c0 100644
--- a/rmk/src/storage/mod.rs
+++ b/rmk/src/storage/mod.rs
@@ -8,6 +8,8 @@ use embedded_storage_async::nor_flash::NorFlash as AsyncNorFlash;
 use postcard::experimental::max_size::MaxSize;
 use rmk_types::connection::ConnectionType;
 use rmk_types::morse::MorseProfile;
+#[cfg(all(feature = "lighting", feature = "rynk"))]
+use rmk_types::protocol::rynk::{LIGHTING_SCENE_CHUNK_SIZE, LightingLayerPolicy, LightingSceneCell};
 use sequential_storage::Error as SSError;
 use sequential_storage::cache::{Cache, Uncached};
 use sequential_storage::map::{Key, MapConfig, MapStorage, PostcardValue, SerializationError};
@@ -152,6 +154,18 @@ pub(crate) enum FlashOperationMessage {
     PriorIdleTime(u16),
     // Default morse profile containing all morse/tap-hold settings (mode, timeouts, unilateral_tap)
     MorseDefaultProfile(MorseProfile),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    // Lighting scene-table header: authoritative cell count and layer policy
+    LightingSceneTable {
+        len: u16,
+        policy: LightingLayerPolicy,
+    },
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    // One shard of the lighting scene table, in wire (stable LED id) form
+    LightingSceneShard {
+        index: u8,
+        cells: heapless::Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>,
+    },
     #[cfg(feature = "_ble")]
     // Read bond info for the given slot; storage task replies via `BOND_INFO_RESPONSE`.
     ReadBleBondInfo(u8),
@@ -198,6 +212,10 @@ pub(crate) enum StorageKey {
     ActiveBleProfile,
     #[cfg(feature = "_ble")]
     BondInfo(u8),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingSceneTable,
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingSceneShard(u8),
 }
 
 impl StorageKey {
@@ -279,10 +297,24 @@ pub(crate) enum StorageData {
     BondInfo(ProfileInfo),
     #[cfg(feature = "_ble")]
     ActiveBleProfile(u8),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingSceneTable(LightingSceneTableRecord),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingSceneShard(heapless::Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>),
 }
 
 impl<'a> PostcardValue<'a> for StorageData {}
 
+/// Persisted lighting scene-table header. Shards beyond `len` are stale
+/// leftovers from a larger previous table and are ignored at load.
+#[cfg(all(feature = "lighting", feature = "rynk"))]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub(crate) struct LightingSceneTableRecord {
+    pub(crate) len: u16,
+    pub(crate) policy: LightingLayerPolicy,
+}
+
 #[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize, MaxSize)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub(crate) struct LocalStorageConfig {
@@ -524,6 +556,42 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
         Ok(())
     }
 
+    /// Read the persisted lighting scene configuration at startup, before the
+    /// storage task takes ownership. Returns the persisted layer policy, if
+    /// any, and appends up to `CAP` stored cells to `cells`.
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    pub async fn read_lighting_scenes<const CAP: usize>(
+        &mut self,
+        cells: &mut heapless::Vec<LightingSceneCell, CAP>,
+    ) -> Option<LightingLayerPolicy> {
+        let Some(StorageData::LightingSceneTable(record)) = self.fetch_data(StorageKey::LightingSceneTable).await
+        else {
+            return None;
+        };
+        let len = (record.len as usize).min(CAP);
+        let mut index: u8 = 0;
+        'shards: while cells.len() < len {
+            let Some(StorageData::LightingSceneShard(shard)) =
+                self.fetch_data(StorageKey::LightingSceneShard(index)).await
+            else {
+                break;
+            };
+            if shard.is_empty() {
+                break;
+            }
+            for cell in shard {
+                if cells.len() == len || cells.push(cell).is_err() {
+                    break 'shards;
+                }
+            }
+            let Some(next) = index.checked_add(1) else {
+                break;
+            };
+            index = next;
+        }
+        Some(record.policy)
+    }
+
     async fn initialize_storage_with_config(
         &mut self,
         #[cfg(feature = "host")] keymap: &[[[KeyAction; COL]; ROW]; NUM_LAYER],
@@ -804,6 +872,33 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
                 FlashOperationMessage::MorseDefaultProfile(morse_default_profile) => {
                     update_storage_field!(&mut self.flash, &mut self.buffer, BehaviorConfig, morse_default_profile)
                 }
+                #[cfg(all(feature = "lighting", feature = "rynk"))]
+                FlashOperationMessage::LightingSceneTable { len, policy } => {
+                    // Scene persistence rewrites the whole table on every
+                    // mutation; comparing before writing keeps unchanged
+                    // records from consuming flash on single-cell edits.
+                    let record = LightingSceneTableRecord { len, policy };
+                    match self.fetch_data(StorageKey::LightingSceneTable).await {
+                        Some(StorageData::LightingSceneTable(saved)) if saved == record => Ok(()),
+                        _ => {
+                            self.store_data(StorageKey::LightingSceneTable, &StorageData::LightingSceneTable(record))
+                                .await
+                        }
+                    }
+                }
+                #[cfg(all(feature = "lighting", feature = "rynk"))]
+                FlashOperationMessage::LightingSceneShard { index, cells } => {
+                    match self.fetch_data(StorageKey::LightingSceneShard(index)).await {
+                        Some(StorageData::LightingSceneShard(saved)) if saved == cells => Ok(()),
+                        _ => {
+                            self.store_data(
+                                StorageKey::LightingSceneShard(index),
+                                &StorageData::LightingSceneShard(cells),
+                            )
+                            .await
+                        }
+                    }
+                }
             };
 
             match write_result {

From 73eba27abae02b239d66d3bee48f0449edf58232 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 21:21:39 -0700
Subject: [PATCH 15/78] feat(rynk): mirror the scene endpoints in the host
 client and wasm bindings

Typed client methods for every scene endpoint, plus two alloc
conveniences: read_all_lighting_scenes pages the whole table under one
pinned revision and restarts on a concurrent-mutation conflict, and
replace_all_lighting_scenes drives the begin/put/commit transaction
with a best-effort abort on staging failure. The wasm client re-exports
the same surface, so the generated TypeScript picks up the scene types.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rynk/rynk-wasm/src/client.rs |  14 ++-
 rynk/src/api.rs              | 173 ++++++++++++++++++++++++++++++++++-
 2 files changed, 183 insertions(+), 4 deletions(-)

diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index e64d213d3..8bdecb7f9 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -29,7 +29,10 @@ use rynk::rmk_types::protocol::rynk::{
     LightingRoutesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus, MacroData,
     MatrixState, PeripheralStatus, ProtocolVersion, PutLightingOverlayChunkRequest, SetComboBulkRequest,
     SetKeymapBulkRequest, SetLightingOverlayRequest, SetLightingStateRequest, SetMorseBulkRequest, StorageResetMode,
-    UnsetLightingOverlayRequest, BuildInfo,
+    UnsetLightingOverlayRequest, BuildInfo, AbortLightingSceneReplaceRequest, BeginLightingSceneReplaceRequest,
+    CommitLightingSceneReplaceRequest, LightingScenePageRequest, LightingSceneStatus, LightingSceneTransaction,
+    LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingSceneCellRequest,
+    UnsetLightingSceneCellRequest,
 };
 use rynk::{Client, Driver, LayoutInfo, RynkDevice, RynkHostError, TopicEvent};
 use wasm_bindgen::prelude::*;
@@ -182,6 +185,15 @@ endpoints! {
     put_lighting_overlay_chunk(request: PutLightingOverlayChunkRequest) -> (),
     commit_lighting_overlay_replace(request: CommitLightingOverlayReplaceRequest) -> LightingState,
     abort_lighting_overlay_replace(request: AbortLightingOverlayReplaceRequest) -> (),
+    get_lighting_scene_status() -> LightingSceneStatus,
+    get_lighting_scenes(request: LightingScenePageRequest) -> LightingScenesPage,
+    set_lighting_scene_cell(request: SetLightingSceneCellRequest) -> LightingState,
+    unset_lighting_scene_cell(request: UnsetLightingSceneCellRequest) -> LightingState,
+    set_lighting_layer_policy(request: SetLightingLayerPolicyRequest) -> LightingState,
+    begin_lighting_scene_replace(request: BeginLightingSceneReplaceRequest) -> LightingSceneTransaction,
+    put_lighting_scene_chunk(request: PutLightingSceneChunkRequest) -> (),
+    commit_lighting_scene_replace(request: CommitLightingSceneReplaceRequest) -> LightingState,
+    abort_lighting_scene_replace(request: AbortLightingSceneReplaceRequest) -> (),
     // connection
     get_connection_type() -> ConnectionType,
     get_connection_status() -> ConnectionStatus,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index bd50befc6..e116b688c 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -21,8 +21,9 @@ use rmk_types::fork::Fork;
 use rmk_types::led_indicator::LedIndicator;
 use rmk_types::morse::Morse;
 use rmk_types::protocol::rynk::{
-    AbortLightingOverlayReplaceRequest, BeginLightingOverlayReplaceRequest, BehaviorConfig,
-    ClearLightingOverlayRequest, Cmd, CommitLightingOverlayReplaceRequest, DeviceCapabilities, DeviceInfo,
+    AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
+    BeginLightingSceneReplaceRequest, BehaviorConfig, ClearLightingOverlayRequest, Cmd,
+    CommitLightingOverlayReplaceRequest, CommitLightingSceneReplaceRequest, DeviceCapabilities, DeviceInfo,
     GetComboBulkRequest, GetComboBulkResponse, GetEncoderRequest, GetKeymapBulkRequest, GetKeymapBulkResponse,
     GetMacroRequest, GetMorseBulkRequest, GetMorseBulkResponse, KeyPosition, LightingCapabilities, LightingKeysPage,
     LightingLedsPage, LightingOutputsPage, LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage,
@@ -30,7 +31,9 @@ use rmk_types::protocol::rynk::{
     MacroData, MatrixState, PeripheralStatus, ProtocolVersion, PutLightingOverlayChunkRequest, SetComboBulkRequest,
     SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest,
     SetLightingOverlayRequest, SetLightingStateRequest, SetMacroRequest, SetMorseBulkRequest, SetMorseRequest,
-    StorageResetMode, UnsetLightingOverlayRequest, command, BuildInfo,
+    StorageResetMode, UnsetLightingOverlayRequest, command, BuildInfo, LightingScenePageRequest, LightingSceneStatus,
+    LightingSceneTransaction, LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest,
+    SetLightingSceneCellRequest, UnsetLightingSceneCellRequest,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -521,6 +524,83 @@ impl Client {
         Self::flatten_lighting(self.request::<command::AbortLightingOverlayReplace>(&request).await?)
     }
 
+    /// Read scene limits and occupancy. Scene support is discovered through
+    /// [`LightingCapabilities::features`] (`LAYER_SCENES`) plus this endpoint;
+    /// firmware without a scene table rejects it with `Unsupported`.
+    pub async fn get_lighting_scene_status(&self) -> Result<LightingSceneStatus, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingSceneStatus)?;
+        Self::flatten_lighting(self.request::<command::GetLightingSceneStatus>(&()).await?)
+    }
+
+    /// Read one page of stored scene cells, pinned to a state revision.
+    pub async fn get_lighting_scenes(
+        &self,
+        request: LightingScenePageRequest,
+    ) -> Result<LightingScenesPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingScenes)?;
+        Self::flatten_lighting(self.request::<command::GetLightingScenes>(&request).await?)
+    }
+
+    /// Insert or update one durable scene cell when the revision matches.
+    pub async fn set_lighting_scene_cell(
+        &self,
+        request: SetLightingSceneCellRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::SetLightingSceneCell)?;
+        Self::flatten_lighting(self.request::<command::SetLightingSceneCell>(&request).await?)
+    }
+
+    /// Remove one durable scene cell when the revision matches.
+    pub async fn unset_lighting_scene_cell(
+        &self,
+        request: UnsetLightingSceneCellRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::UnsetLightingSceneCell)?;
+        Self::flatten_lighting(self.request::<command::UnsetLightingSceneCell>(&request).await?)
+    }
+
+    /// Set the scene layer-composition policy when the revision matches.
+    pub async fn set_lighting_layer_policy(
+        &self,
+        request: SetLightingLayerPolicyRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::SetLightingLayerPolicy)?;
+        Self::flatten_lighting(self.request::<command::SetLightingLayerPolicy>(&request).await?)
+    }
+
+    /// Reserve the bounded staging transaction for atomic scene replacement.
+    pub async fn begin_lighting_scene_replace(
+        &self,
+        request: BeginLightingSceneReplaceRequest,
+    ) -> Result<LightingSceneTransaction, RynkHostError> {
+        self.require_lighting(Cmd::BeginLightingSceneReplace)?;
+        Self::flatten_lighting(self.request::<command::BeginLightingSceneReplace>(&request).await?)
+    }
+
+    /// Stage one ordered scene chunk. It does not mutate the live table.
+    pub async fn put_lighting_scene_chunk(&self, request: PutLightingSceneChunkRequest) -> Result<(), RynkHostError> {
+        self.require_lighting(Cmd::PutLightingSceneChunk)?;
+        Self::flatten_lighting(self.request::<command::PutLightingSceneChunk>(&request).await?)
+    }
+
+    /// Atomically publish a complete staged scene replacement.
+    pub async fn commit_lighting_scene_replace(
+        &self,
+        request: CommitLightingSceneReplaceRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::CommitLightingSceneReplace)?;
+        Self::flatten_lighting(self.request::<command::CommitLightingSceneReplace>(&request).await?)
+    }
+
+    /// Discard a staged scene replacement without changing live state.
+    pub async fn abort_lighting_scene_replace(
+        &self,
+        request: AbortLightingSceneReplaceRequest,
+    ) -> Result<(), RynkHostError> {
+        self.require_lighting(Cmd::AbortLightingSceneReplace)?;
+        Self::flatten_lighting(self.request::<command::AbortLightingSceneReplace>(&request).await?)
+    }
+
     /// Read the active connection type (USB / BLE).
     pub async fn get_connection_type(&self) -> Result<ConnectionType, RynkHostError> {
         self.request::<command::GetConnectionType>(&()).await
@@ -622,6 +702,93 @@ impl Client {
         .await
     }
 
+    /// Read the whole stored scene table by paging `GetLightingScenes` under
+    /// one pinned revision. A concurrent lighting mutation invalidates the
+    /// pin; the read restarts from a fresh status, bounded by a few attempts.
+    pub async fn read_all_lighting_scenes(
+        &self,
+    ) -> Result<(u32, Vec<rmk_types::protocol::rynk::LightingSceneCell>), RynkHostError> {
+        const ATTEMPTS: usize = 4;
+        let mut last_error = None;
+        for _ in 0..ATTEMPTS {
+            let status = self.get_lighting_scene_status().await?;
+            let mut cells = Vec::new();
+            let mut offset: u16 = 0;
+            let mut conflicted = false;
+            while offset < status.scene_len {
+                match self
+                    .get_lighting_scenes(LightingScenePageRequest {
+                        revision: status.revision,
+                        offset,
+                    })
+                    .await
+                {
+                    Ok(page) => {
+                        if page.items.is_empty() {
+                            break;
+                        }
+                        offset += page.items.len() as u16;
+                        cells.extend(page.items.iter().copied());
+                    }
+                    Err(
+                        error @ RynkHostError::LightingRejected(
+                            rmk_types::protocol::rynk::LightingError::StateRevisionConflict { .. },
+                        ),
+                    ) => {
+                        last_error = Some(error);
+                        conflicted = true;
+                        break;
+                    }
+                    Err(error) => return Err(error),
+                }
+            }
+            if !conflicted {
+                return Ok((status.revision, cells));
+            }
+        }
+        Err(last_error.expect("a retried read only exits with a recorded conflict"))
+    }
+
+    /// Atomically replace the whole stored scene table: begin, stage in
+    /// chunk-sized pages, and commit. A staging failure is followed by a
+    /// best-effort abort so the firmware transaction is not left dangling.
+    pub async fn replace_all_lighting_scenes(
+        &self,
+        expected_revision: u32,
+        cells: &[rmk_types::protocol::rynk::LightingSceneCell],
+    ) -> Result<LightingState, RynkHostError> {
+        let transaction = self
+            .begin_lighting_scene_replace(BeginLightingSceneReplaceRequest {
+                expected_revision,
+                cell_count: cells.len() as u16,
+            })
+            .await?;
+        let mut offset: u16 = 0;
+        for chunk in cells.chunks(rmk_types::protocol::rynk::LIGHTING_SCENE_CHUNK_SIZE) {
+            let mut request = PutLightingSceneChunkRequest {
+                transaction_id: transaction.id,
+                offset,
+                cells: Default::default(),
+            };
+            for cell in chunk {
+                request.cells.push(*cell).expect("chunks are chunk-size bounded");
+            }
+            if let Err(error) = self.put_lighting_scene_chunk(request).await {
+                let _ = self
+                    .abort_lighting_scene_replace(AbortLightingSceneReplaceRequest {
+                        transaction_id: transaction.id,
+                    })
+                    .await;
+                return Err(error);
+            }
+            offset += chunk.len() as u16;
+        }
+        self.commit_lighting_scene_replace(CommitLightingSceneReplaceRequest {
+            transaction_id: transaction.id,
+        })
+        .await
+    }
+
     /// Write every morse with concurrent paged writes, each page filled up to the
     /// device's payload limit. A failure leaves the earlier pages applied.
     pub async fn write_all_morses(&self, configs: Vec<Morse>) -> Result<(), RynkHostError> {

From b424445edec3dfdd40829184c1c19512df330316 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 22:26:35 -0700
Subject: [PATCH 16/78] feat(split): size application queue for scene snapshots

---
 rmk/src/split_app.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/rmk/src/split_app.rs b/rmk/src/split_app.rs
index 4dcb5f95b..d086ed061 100644
--- a/rmk/src/split_app.rs
+++ b/rmk/src/split_app.rs
@@ -103,11 +103,11 @@ impl MaxSize for SplitAppData {
 
 /// Central → peripheral queue, drained by `PeripheralManager` while the link
 /// is up. Producers MUST use `try_send` (bounded, never block); capacity is
-/// sized so one full application resync burst fits with headroom. Forty-eight
-/// entries admit a complete 40-cell semantic lighting snapshot (begin,
-/// context, one worst-case animated cell per packet, and commit). This is
+/// sized so one full application resync burst fits with headroom. One hundred
+/// and twelve entries admit a complete 40-cell overlay plus a 64-cell runtime
+/// scene table (begin, context, one cell per packet, and commit). This is
 /// mutation/reconnect traffic, not rendered-frame streaming.
-pub static SPLIT_APP_TX: Channel<RawMutex, SplitAppData, 48> = Channel::new();
+pub static SPLIT_APP_TX: Channel<RawMutex, SplitAppData, 112> = Channel::new();
 
 /// This side's inbox of received application messages (peripheral: from the
 /// central's `SPLIT_APP_TX`; central: from the peripheral's

From 831b0998f75f8fa7cf19bf7cc816cced1d21b40f Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 20 Jul 2026 22:26:42 -0700
Subject: [PATCH 17/78] rynk: stop minting protocol versions downstream
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ProtocolVersion numbers belong to upstream (HaoboGu/rmk feat/rynk); a
fork that bumps CURRENT will eventually collide with upstream reusing
the same minor for a different protocol. Revert CURRENT to the upstream
base's v0.1 and drop every fork-minted claim (v0.2 native lighting,
v0.3 build info, v0.4 routed split bootloader entry, v0.5 layer
scenes).

Downstream features are discoverable without version numbers, using the
protocol's existing negotiation machinery:

- lighting endpoints: `DeviceCapabilities.lighting_enabled` (declared
  by upstream v0.1), then `GetLightingCapabilities.features`
- layer scenes: `LightingFeatureFlags::LAYER_SCENES` (set iff the board
  advertises a scene capacity) plus `GetLightingSceneStatus.capacity`
- `GetBuildInfo` / `PeripheralBootloaderJump`: per-command probing —
  firmware without them answers `UnknownCmd`, which hosts already
  receive as `Rejected(UnknownCmd)`

No code ever gated on the minted minors (the handshake only rejects
`major` mismatches), so firmware already in the field reporting
v0.2–v0.5 stays compatible with reverted hosts and vice versa.

Regenerate the wire snapshots and the generated protocol reference, and
state the rule in the reference's Compatibility section and the
changelog.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../main/docs/development/rynk_protocol.md    |  2 ++
 rmk-types/src/protocol/rynk/payload/system.rs | 31 +++++++++++++++++--
 rmk-types/src/protocol/rynk/tests.rs          |  3 +-
 rmk/CHANGELOG.md                              |  2 +-
 4 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index ecb1d4303..f286afe19 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -7,6 +7,7 @@
 Current protocol version: **0.2**.
 Current protocol version: **0.4**.
 Current protocol version: **0.3**.
+Current protocol version: **0.1**.
 
 Every transport (USB CDC, BLE GATT, BLE HID) carries the same frame — a 3-byte header plus a [postcard](https://docs.rs/postcard)-encoded payload:
 
@@ -232,3 +233,4 @@ Topics are best-effort pushes; the `Get*` endpoints above mirror their payloads
 - `GetVersion` (`0x0001`) and its `Result<ProtocolVersion, RynkError>` reply are frozen across all versions.
 - Within a major version, adding a CMD or topic is a `minor` bump: old firmware answers `UnknownCmd`, old hosts ignore unknown topics.
 - Reshaping an existing request/response — including appending a field — is a `major` bump.
+- Version numbers are minted upstream only. Downstream extensions never bump `ProtocolVersion`; hosts discover them through capability surfaces (`DeviceCapabilities`, `LightingCapabilities.features`, `GetLightingSceneStatus`) and per-command probing (an unsupported command answers `UnknownCmd`), never by comparing `minor`.
diff --git a/rmk-types/src/protocol/rynk/payload/system.rs b/rmk-types/src/protocol/rynk/payload/system.rs
index f0ccdfce8..17d7c44a5 100644
--- a/rmk-types/src/protocol/rynk/payload/system.rs
+++ b/rmk-types/src/protocol/rynk/payload/system.rs
@@ -23,9 +23,34 @@ pub struct ProtocolVersion {
 
 impl ProtocolVersion {
     /// Current protocol version for this firmware release.
-    /// The protocol is still under development; lighting endpoints were added
-    /// in v0.2 and lighting scene endpoints in v0.3.
-    pub const CURRENT: Self = Self { major: 0, minor: 3 };
+    /// Now the protocol is still being developed, so the version is v0.1
+    ///
+    /// Version numbers are minted upstream (HaoboGu/rmk) only — downstream
+    /// extensions must never bump this constant, or the same number would
+    /// eventually name two different protocols. Extensions are discovered
+    /// through capability surfaces instead: [`DeviceCapabilities`] flags,
+    /// domain capability endpoints (e.g. `GetLightingCapabilities` /
+    /// `GetLightingSceneStatus`), and per-command probing — firmware answers
+    /// `UnknownCmd` for any command it does not implement.
+    pub const CURRENT: Self = Self { major: 0, minor: 1 };
+}
+
+/// Human-readable identity of the firmware build.
+///
+/// Unlike [`ProtocolVersion`], this label is deliberately application-defined:
+/// it is for diagnostics and display, never compatibility decisions. RMK
+/// supplies an RMK-only default and downstream firmware may replace it with a
+/// label containing its own package, source revision, or configuration name.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct BuildInfo {
+    #[cfg_attr(feature = "wasm", tsify(type = "string"))]
+    pub label: String<BUILD_INFO_STRING_SIZE>,
+}
+
+impl MaxSize for BuildInfo {
+    const POSTCARD_MAX_SIZE: usize = crate::heapless_vec_max_size::<u8, BUILD_INFO_STRING_SIZE>();
 }
 
 /// Device capabilities discovered during the connection handshake.
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 3046b6716..691db32a1 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1712,7 +1712,8 @@ mod protocol_reference {
              ## Compatibility\n\n\
              - `GetVersion` (`0x0001`) and its `Result<ProtocolVersion, RynkError>` reply are frozen across all versions.\n\
              - Within a major version, adding a CMD or topic is a `minor` bump: old firmware answers `UnknownCmd`, old hosts ignore unknown topics.\n\
-             - Reshaping an existing request/response — including appending a field — is a `major` bump.\n",
+             - Reshaping an existing request/response — including appending a field — is a `major` bump.\n\
+             - Version numbers are minted upstream only. Downstream extensions never bump `ProtocolVersion`; hosts discover them through capability surfaces (`DeviceCapabilities`, `LightingCapabilities.features`, `GetLightingSceneStatus`) and per-command probing (an unsupported command answers `UnknownCmd`), never by comparing `minor`.\n",
             header = "<!-- GENERATED — do not edit. Rendered from the `endpoints!`/`topics!` tables in\n     rmk-types/src/protocol/rynk/command.rs. Regenerate with:\n     UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk protocol_reference -->",
             major = v.major,
             minor = v.minor,
diff --git a/rmk/CHANGELOG.md b/rmk/CHANGELOG.md
index f58425ad5..83f474574 100644
--- a/rmk/CHANGELOG.md
+++ b/rmk/CHANGELOG.md
@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 - Add [Rynk](https://rmk.rs/docs/features/rynk), RMK's native host protocol for on-the-fly configuration over USB and BLE — an opt-in alternative to Vial that covers every RMK feature (keymap, layers, encoders, combos, forks, tap-dance/morse, macros, and behavior config), plus live status (current layer, matrix tester, WPM, HID indicators, battery, connection/BLE profile) and device management (reboot, bootloader, storage reset). Enable with the `rynk` Cargo feature and `[host] rynk_enabled = true`; it is mutually exclusive with Vial. Dangerous operations (bootloader, storage reset, matrix tester, clearing a BLE bond) are gated behind a physical-presence unlock (`[host].unlock_keys`). Host client crates live in the new `rynk/` workspace ([#962](https://github.com/rmk-rs/rmk/pull/962))
-- Add runtime-configurable per-layer lighting scenes over Rynk: hosts can store per-layer, per-LED effects on the keyboard (`GetLightingSceneStatus`/`GetLightingScenes`, `SetLightingSceneCell`/`UnsetLightingSceneCell`, an atomic `BeginLightingSceneReplace`/`PutLightingSceneChunk`/`CommitLightingSceneReplace`/`AbortLightingSceneReplace` transaction, and `SetLightingLayerPolicy`). Scene cells compose in the layer band — above the board's static layer scenes, below the transient TTL overlay — and persist via RMK storage, loading on boot and clearing with a storage reset. Boards opt in by choosing a scene capacity on the standard lighting engine and advertising it with `RynkLightingController::with_scene_capacity`
+- Add runtime-configurable per-layer lighting scenes over Rynk: hosts can store per-layer, per-LED effects on the keyboard (`GetLightingSceneStatus`/`GetLightingScenes`, `SetLightingSceneCell`/`UnsetLightingSceneCell`, an atomic `BeginLightingSceneReplace`/`PutLightingSceneChunk`/`CommitLightingSceneReplace`/`AbortLightingSceneReplace` transaction, and `SetLightingLayerPolicy`). Scene cells compose in the layer band — above the board's static layer scenes, below the transient TTL overlay — and persist via RMK storage, loading on boot and clearing with a storage reset. Boards opt in by choosing a scene capacity on the standard lighting engine and advertising it with `RynkLightingController::with_scene_capacity`. Scenes are a capability-gated extension, not a protocol-version entry: hosts discover them via `LightingFeatureFlags::LAYER_SCENES` and `GetLightingSceneStatus` (older firmware answers `UnknownCmd`); `ProtocolVersion` is unchanged — version numbers are minted upstream only, and downstream extensions (scenes, `GetBuildInfo`, `PeripheralBootloaderJump`, the lighting endpoints) are detected through capability surfaces and per-command probing. Firmware already in the field that reports a higher minor (v0.2–v0.5) remains compatible: hosts gate on capabilities, and the handshake only rejects `major` mismatches
 - Add Azoteq IQS5xx (IQS550 / IQS572 / IQS525) trackpad driver, used by Azoteq's TPS43/TPS65 modules. Supports operation with or without an `RDY` pin and is configurable via `keyboard.toml` on nRF52 / RP2040; currently publishes single-finger relative cursor movement only ([#29](https://github.com/rmk-rs/rmk/issues/29))
 - Add PMW3360 / PMW3389 optical mouse sensor support
 - Add `report_hz` option for Pmw3610Device

From 3f45cb6bf39a2cece102d41b6e1d4b5448e41ec5 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 02:58:45 -0700
Subject: [PATCH 18/78] feat(rynk): add complete lighting and layer readback

---
 .../main/docs/development/rynk_protocol.md    |  78 +++++++
 rmk-types/src/protocol/rynk/command.rs        |  22 +-
 .../src/protocol/rynk/payload/lighting.rs     | 105 ++++++++-
 rmk-types/src/protocol/rynk/payload/status.rs |  48 ++++
 .../rynk/snapshots/lighting_wire_frames.snap  |   8 +-
 rmk-types/src/protocol/rynk/tests.rs          |  74 +++++-
 rmk/src/host/context.rs                       |  65 ++++++
 rmk/src/host/rynk/handlers/lighting.rs        | 221 ++++++++++++++++--
 rmk/src/host/rynk/handlers/status.rs          |  12 +-
 rmk/src/host/rynk/lighting.rs                 |  97 +++++++-
 rmk/src/host/rynk/mod.rs                      |   9 +
 rmk/src/keymap.rs                             |  21 ++
 rmk/src/lighting/mod.rs                       |   8 +-
 rmk/src/lighting/source.rs                    |  13 ++
 rmk/src/lighting/standard.rs                  | 180 +++++++++++++-
 rynk/rynk-wasm/src/client.rs                  |   7 +-
 rynk/src/api.rs                               | 162 ++++++++++++-
 rynk/src/driver.rs                            |   6 +
 rynk/tests/loopback.rs                        |   5 +
 19 files changed, 1096 insertions(+), 45 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index f286afe19..b61642005 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -213,6 +213,84 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x0918` | `CommitLightingSceneReplace`   | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`               | `lighting` |                                                                                                                                |
 | `0x0919` | `AbortLightingSceneReplace`    | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                | `lighting` |                                                                                                                                |
 | `0x091A` | `SetLightingLayerPolicy`       | `SetLightingLayerPolicyRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| CMD      | Name                             | Request                               | Response                            | Feature    | Notes                                                                                                                          |
+| -------- | -------------------------------- | ------------------------------------- | ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `0x0001` | `GetVersion`                     | `()`                                  | `ProtocolVersion`                   |            |                                                                                                                                |
+| `0x0002` | `GetCapabilities`                | `()`                                  | `DeviceCapabilities`                |            |                                                                                                                                |
+| `0x0003` | `Reboot`                         | `()`                                  | `()`                                |            |                                                                                                                                |
+| `0x0004` | `BootloaderJump`                 | `()`                                  | `()`                                |            |                                                                                                                                |
+| `0x0005` | `StorageReset`                   | `StorageResetMode`                    | `()`                                |            |                                                                                                                                |
+| `0x0006` | `GetLockStatus`                  | `()`                                  | `LockStatus`                        |            | Pure read of the current lock state — no side effects.                                                                         |
+| `0x0007` | `UnlockPoll`                     | `()`                                  | `LockStatus`                        |            | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                         |
+| `0x0008` | `Lock`                           | `()`                                  | `()`                                |            | Relock immediately.                                                                                                            |
+| `0x0009` | `GetLayout`                      | `u32`                                 | `LayoutChunk`                       |            | Get layout blob chunk. `u32` is the byte offset.                                                                               |
+| `0x000A` | `GetDeviceInfo`                  | `()`                                  | `DeviceInfo`                        |            | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                       |
+| `0x000B` | `GetBuildInfo`                   | `()`                                  | `BuildInfo`                         |            | Application-defined diagnostic build label; never used for compatibility.                                                      |
+| `0x000C` | `PeripheralBootloaderJump`       | `u8`                                  | `()`                                |            | Ask the application to route a bootloader jump to one split peripheral.                                                        |
+| `0x0101` | `GetKeyAction`                   | `KeyPosition`                         | `KeyAction`                         |            |                                                                                                                                |
+| `0x0102` | `SetKeyAction`                   | `SetKeyRequest`                       | `()`                                |            |                                                                                                                                |
+| `0x0103` | `GetDefaultLayer`                | `()`                                  | `u8`                                |            |                                                                                                                                |
+| `0x0104` | `SetDefaultLayer`                | `u8`                                  | `()`                                |            |                                                                                                                                |
+| `0x0105` | `GetEncoderAction`               | `GetEncoderRequest`                   | `EncoderAction`                     |            |                                                                                                                                |
+| `0x0106` | `SetEncoderAction`               | `SetEncoderRequest`                   | `()`                                |            |                                                                                                                                |
+| `0x0107` | `GetKeymapBulk`                  | `GetKeymapBulkRequest`                | `GetKeymapBulkResponse`             |            |                                                                                                                                |
+| `0x0108` | `SetKeymapBulk`                  | `SetKeymapBulkRequest`                | `()`                                |            |                                                                                                                                |
+| `0x0201` | `GetMacro`                       | `GetMacroRequest`                     | `MacroData`                         |            |                                                                                                                                |
+| `0x0202` | `SetMacro`                       | `SetMacroRequest`                     | `()`                                |            |                                                                                                                                |
+| `0x0301` | `GetCombo`                       | `u8`                                  | `Combo`                             |            |                                                                                                                                |
+| `0x0302` | `SetCombo`                       | `SetComboRequest`                     | `()`                                |            |                                                                                                                                |
+| `0x0303` | `GetComboBulk`                   | `GetComboBulkRequest`                 | `GetComboBulkResponse`              |            |                                                                                                                                |
+| `0x0304` | `SetComboBulk`                   | `SetComboBulkRequest`                 | `()`                                |            |                                                                                                                                |
+| `0x0401` | `GetMorse`                       | `u8`                                  | `Morse`                             |            |                                                                                                                                |
+| `0x0402` | `SetMorse`                       | `SetMorseRequest`                     | `()`                                |            |                                                                                                                                |
+| `0x0403` | `GetMorseBulk`                   | `GetMorseBulkRequest`                 | `GetMorseBulkResponse`              |            |                                                                                                                                |
+| `0x0404` | `SetMorseBulk`                   | `SetMorseBulkRequest`                 | `()`                                |            |                                                                                                                                |
+| `0x0501` | `GetFork`                        | `u8`                                  | `Fork`                              |            |                                                                                                                                |
+| `0x0502` | `SetFork`                        | `SetForkRequest`                      | `()`                                |            |                                                                                                                                |
+| `0x0601` | `GetBehaviorConfig`              | `()`                                  | `BehaviorConfig`                    |            |                                                                                                                                |
+| `0x0602` | `SetBehaviorConfig`              | `BehaviorConfig`                      | `()`                                |            |                                                                                                                                |
+| `0x0701` | `GetConnectionType`              | `()`                                  | `ConnectionType`                    |            |                                                                                                                                |
+| `0x0702` | `GetConnectionStatus`            | `()`                                  | `ConnectionStatus`                  |            | Full `ConnectionStatus` snapshot.                                                                                              |
+| `0x0703` | `GetBleStatus`                   | `()`                                  | `BleStatus`                         | `_ble`     |                                                                                                                                |
+| `0x0704` | `SwitchBleProfile`               | `u8`                                  | `()`                                | `_ble`     |                                                                                                                                |
+| `0x0705` | `ClearBleProfile`                | `u8`                                  | `()`                                | `_ble`     |                                                                                                                                |
+| `0x0801` | `GetCurrentLayer`                | `()`                                  | `u8`                                |            |                                                                                                                                |
+| `0x0802` | `GetMatrixState`                 | `()`                                  | `MatrixState`                       |            |                                                                                                                                |
+| `0x0803` | `GetBatteryStatus`               | `()`                                  | `BatteryStatus`                     | `_ble`     |                                                                                                                                |
+| `0x0804` | `GetPeripheralStatus`            | `u8`                                  | `PeripheralStatus`                  | `split`    |                                                                                                                                |
+| `0x0805` | `GetWpm`                         | `()`                                  | `u16`                               |            | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                       |
+| `0x0806` | `GetSleepState`                  | `()`                                  | `bool`                              |            | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                               |
+| `0x0807` | `GetLedIndicator`                | `()`                                  | `LedIndicator`                      |            | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                   |
+| `0x0808` | `GetLayerState`                  | `()`                                  | `LayerState`                        |            | Default layer and complete active-layer bitmap.                                                                                |
+| `0x0901` | `GetLightingCapabilities`        | `()`                                  | `LightingCapabilitiesResult`        | `lighting` |                                                                                                                                |
+| `0x0902` | `GetLightingState`               | `()`                                  | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0903` | `SetLightingState`               | `SetLightingStateRequest`             | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0904` | `GetLightingPhysicalKeys`        | `LightingPageRequest`                 | `LightingPhysicalKeysPageResult`    | `lighting` |                                                                                                                                |
+| `0x0905` | `GetLightingLeds`                | `LightingPageRequest`                 | `LightingLedsPageResult`            | `lighting` |                                                                                                                                |
+| `0x0906` | `GetLightingZones`               | `LightingPageRequest`                 | `LightingZonesPageResult`           | `lighting` |                                                                                                                                |
+| `0x0907` | `GetLightingZoneMemberships`     | `LightingPageRequest`                 | `LightingZoneMembershipsPageResult` | `lighting` |                                                                                                                                |
+| `0x0908` | `GetLightingOutputs`             | `LightingPageRequest`                 | `LightingOutputsPageResult`         | `lighting` |                                                                                                                                |
+| `0x0909` | `GetLightingRoutes`              | `LightingPageRequest`                 | `LightingRoutesPageResult`          | `lighting` |                                                                                                                                |
+| `0x090A` | `SetLightingOverlay`             | `SetLightingOverlayRequest`           | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x090B` | `UnsetLightingOverlay`           | `UnsetLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x090C` | `ClearLightingOverlay`           | `ClearLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x090D` | `BeginLightingOverlayReplace`    | `BeginLightingOverlayReplaceRequest`  | `LightingOverlayTransactionResult`  | `lighting` |                                                                                                                                |
+| `0x090E` | `PutLightingOverlayChunk`        | `PutLightingOverlayChunkRequest`      | `LightingUnitResult`                | `lighting` |                                                                                                                                |
+| `0x090F` | `CommitLightingOverlayReplace`   | `CommitLightingOverlayReplaceRequest` | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0910` | `AbortLightingOverlayReplace`    | `AbortLightingOverlayReplaceRequest`  | `LightingUnitResult`                | `lighting` |                                                                                                                                |
+| `0x0911` | `GetLightingKeys`                | `LightingPageRequest`                 | `LightingKeysPageResult`            | `lighting` | Logical matrix keys are distinct from optional physical geometry.                                                              |
+| `0x0912` | `GetLightingSceneStatus`         | `()`                                  | `LightingSceneStatusResult`         | `lighting` | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts. |
+| `0x0913` | `GetLightingScenes`              | `LightingScenePageRequest`            | `LightingScenesPageResult`          | `lighting` | Scene pages are pinned to `LightingState.revision` for consistency.                                                            |
+| `0x0914` | `SetLightingSceneCell`           | `SetLightingSceneCellRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0915` | `UnsetLightingSceneCell`         | `UnsetLightingSceneCellRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0916` | `BeginLightingSceneReplace`      | `BeginLightingSceneReplaceRequest`    | `LightingSceneTransactionResult`    | `lighting` |                                                                                                                                |
+| `0x0917` | `PutLightingSceneChunk`          | `PutLightingSceneChunkRequest`        | `LightingUnitResult`                | `lighting` |                                                                                                                                |
+| `0x0918` | `CommitLightingSceneReplace`     | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x0919` | `AbortLightingSceneReplace`      | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                | `lighting` |                                                                                                                                |
+| `0x091A` | `SetLightingLayerPolicy`         | `SetLightingLayerPolicyRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
+| `0x091B` | `GetLightingOverlay`             | `LightingOverlayPageRequest`          | `LightingOverlayPageResult`         | `lighting` | Overlay pages are pinned to `LightingState.revision` for consistency.                                                          |
+| `0x091C` | `GetLightingCompiledSceneStatus` | `()`                                  | `LightingCompiledSceneStatusResult` | `lighting` | Discover the immutable board-compiled layer-scene source.                                                                      |
+| `0x091D` | `GetLightingCompiledScenes`      | `LightingPageRequest`                 | `LightingCompiledScenesPageResult`  | `lighting` | Compiled-scene pages are pinned to the firmware topology revision.                                                             |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 41b4a455b..8f96ea1b6 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -16,9 +16,9 @@ use super::message::{RynkHeader, encode_frame};
 use super::{
     BehaviorConfig, BuildInfo, DeviceCapabilities, DeviceInfo, GetComboBulkRequest, GetComboBulkResponse,
     GetEncoderRequest, GetKeymapBulkRequest, GetKeymapBulkResponse, GetMacroRequest, GetMorseBulkRequest,
-    GetMorseBulkResponse, KeyPosition, LayoutChunk, LockStatus, MacroData, MatrixState, ProtocolVersion, RynkError,
-    SetComboBulkRequest, SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest,
-    SetMacroRequest, SetMorseBulkRequest, SetMorseRequest, StorageResetMode,
+    GetMorseBulkResponse, KeyPosition, LayerState, LayoutChunk, LockStatus, MacroData, MatrixState, ProtocolVersion,
+    RynkError, SetComboBulkRequest, SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest,
+    SetKeymapBulkRequest, SetMacroRequest, SetMorseBulkRequest, SetMorseRequest, StorageResetMode,
 };
 use crate::action::{EncoderAction, KeyAction};
 #[cfg(feature = "_ble")]
@@ -36,8 +36,9 @@ use crate::protocol::rynk::PeripheralStatus;
 use crate::protocol::rynk::{
     AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
     BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest,
-    CommitLightingSceneReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingKeysPageResult,
-    LightingLedsPageResult, LightingOutputsPageResult, LightingOverlayTransactionResult, LightingPageRequest,
+    CommitLightingSceneReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingCompiledSceneStatusResult,
+    LightingCompiledScenesPageResult, LightingKeysPageResult, LightingLedsPageResult, LightingOutputsPageResult,
+    LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest,
     LightingPhysicalKeysPageResult, LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatusResult,
     LightingSceneTransactionResult, LightingScenesPageResult, LightingStateResult, LightingUnitResult,
     LightingZoneMembershipsPageResult, LightingZonesPageResult, PutLightingOverlayChunkRequest,
@@ -353,6 +354,8 @@ endpoints! {
     GetSleepState = 0x0806: () => bool;
     /// Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.
     GetLedIndicator = 0x0807: () => LedIndicator;
+    /// Default layer and complete active-layer bitmap.
+    GetLayerState = 0x0808: () => LayerState;
 
     // Lighting (0x09xx). Lighting-domain errors are nested inside Rynk's
     // outer protocol result so hosts retain precise rejection reasons.
@@ -412,6 +415,15 @@ endpoints! {
     AbortLightingSceneReplace = 0x0919: AbortLightingSceneReplaceRequest => LightingUnitResult;
     #[cfg(feature = "lighting")]
     SetLightingLayerPolicy = 0x091A: SetLightingLayerPolicyRequest => LightingStateResult;
+    /// Overlay pages are pinned to `LightingState.revision` for consistency.
+    #[cfg(feature = "lighting")]
+    GetLightingOverlay = 0x091B: LightingOverlayPageRequest => LightingOverlayPageResult;
+    /// Discover the immutable board-compiled layer-scene source.
+    #[cfg(feature = "lighting")]
+    GetLightingCompiledSceneStatus = 0x091C: () => LightingCompiledSceneStatusResult;
+    /// Compiled-scene pages are pinned to the firmware topology revision.
+    #[cfg(feature = "lighting")]
+    GetLightingCompiledScenes = 0x091D: LightingPageRequest => LightingCompiledScenesPageResult;
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index ff3821a3c..0802c6044 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -182,6 +182,10 @@ impl LightingFeatureFlags {
     pub const LAYER_AWARE: u16 = 1 << 5;
     /// Runtime-configurable per-layer scenes stored on the device.
     pub const LAYER_SCENES: u16 = 1 << 6;
+    /// Revision-pinned readback of the transient overlay.
+    pub const OVERLAY_READBACK: u16 = 1 << 7;
+    /// Read-only board-compiled layer scenes, separate from runtime scenes.
+    pub const COMPILED_LAYER_SCENES: u16 = 1 << 8;
 
     pub const fn contains(self, bits: u16) -> bool {
         self.0 & bits == bits
@@ -356,7 +360,7 @@ wire_type! {
 
 wire_type! {
     /// One transient overlay cell addressed by stable LED identity.
-    pub struct LightingOverlayCell {
+pub struct LightingOverlayCell {
         pub led_id: LightingLedId,
         pub effect: LightingEffect,
         /// Relative lifetime. `None` lasts until unset, clear, or reboot;
@@ -365,6 +369,34 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Revision-pinned request for one transient overlay page.
+    pub struct LightingOverlayPageRequest {
+        /// Expected [`LightingState::revision`].
+        pub revision: u32,
+        pub offset: u16,
+    }
+}
+
+/// One atomically sampled page of transient overlay cells. Cell TTLs are
+/// remaining relative lifetimes at the sample time, never firmware deadlines.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LightingOverlayPage {
+    pub revision: u32,
+    pub total_count: u16,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingOverlayCell[]"))]
+    pub items: Vec<LightingOverlayCell, LIGHTING_OVERLAY_CHUNK_SIZE>,
+}
+
+impl MaxSize for LightingOverlayPage {
+    const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+        + u16::POSTCARD_MAX_SIZE
+        + crate::heapless_vec_max_size::<LightingOverlayCell, LIGHTING_OVERLAY_CHUNK_SIZE>();
+}
+
 impl LightingOverlayCell {
     /// Validate the effect and relative lifetime. `None` is persistent and a
     /// positive TTL expires in firmware time; zero is never ambiguous.
@@ -475,7 +507,7 @@ wire_type! {
     /// [`LightingCapabilities`]/[`LightingState`] so their postcard layout is
     /// unchanged for existing hosts; discovery uses
     /// [`LightingFeatureFlags::LAYER_SCENES`] plus this endpoint.
-    pub struct LightingSceneStatus {
+pub struct LightingSceneStatus {
         /// Current [`LightingState::revision`]; scene mutations advance it.
         pub revision: u32,
         /// Maximum stored scene cells. `0` means scenes are absent.
@@ -487,6 +519,21 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Occupancy of the immutable board-compiled layer-scene source.
+    ///
+    /// This source is distinct from [`LightingSceneStatus`]'s mutable table
+    /// and is pinned to the topology revision for the firmware build.
+    pub struct LightingCompiledSceneStatus {
+        pub topology_revision: u32,
+        pub scene_len: u16,
+        /// Composition policy of the immutable compiled source. This is
+        /// independent from the mutable runtime scene table's policy.
+        pub policy: LightingLayerPolicy,
+        pub chunk_capacity: u8,
+    }
+}
+
 wire_type! {
     /// Revision-pinned request for one scene page. `revision` is the expected
     /// [`LightingState::revision`]; a stale read is rejected so multi-page
@@ -509,6 +556,24 @@ pub struct LightingScenesPage {
     pub items: Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>,
 }
 
+/// One page of immutable board-compiled layer scenes.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LightingCompiledScenesPage {
+    pub topology_revision: u32,
+    pub total_count: u16,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingSceneCell[]"))]
+    pub items: Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>,
+}
+
+impl MaxSize for LightingCompiledScenesPage {
+    const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+        + u16::POSTCARD_MAX_SIZE
+        + crate::heapless_vec_max_size::<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>();
+}
+
 impl MaxSize for LightingScenesPage {
     const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
         + u16::POSTCARD_MAX_SIZE
@@ -616,9 +681,12 @@ pub type LightingZonesPageResult = LightingResult<LightingZonesPage>;
 pub type LightingZoneMembershipsPageResult = LightingResult<LightingZoneMembershipsPage>;
 pub type LightingOutputsPageResult = LightingResult<LightingOutputsPage>;
 pub type LightingRoutesPageResult = LightingResult<LightingRoutesPage>;
+pub type LightingOverlayPageResult = LightingResult<LightingOverlayPage>;
 pub type LightingOverlayTransactionResult = LightingResult<LightingOverlayTransaction>;
 pub type LightingSceneStatusResult = LightingResult<LightingSceneStatus>;
 pub type LightingScenesPageResult = LightingResult<LightingScenesPage>;
+pub type LightingCompiledSceneStatusResult = LightingResult<LightingCompiledSceneStatus>;
+pub type LightingCompiledScenesPageResult = LightingResult<LightingCompiledScenesPage>;
 pub type LightingSceneTransactionResult = LightingResult<LightingSceneTransaction>;
 pub type LightingUnitResult = LightingResult<()>;
 
@@ -648,6 +716,7 @@ const _: () = {
     assert_endpoint_fits!(LightingPageRequest, LightingZoneMembershipsPageResult);
     assert_endpoint_fits!(LightingPageRequest, LightingOutputsPageResult);
     assert_endpoint_fits!(LightingPageRequest, LightingRoutesPageResult);
+    assert_endpoint_fits!(LightingOverlayPageRequest, LightingOverlayPageResult);
     assert_endpoint_fits!(SetLightingOverlayRequest, LightingStateResult);
     assert_endpoint_fits!(UnsetLightingOverlayRequest, LightingStateResult);
     assert_endpoint_fits!(ClearLightingOverlayRequest, LightingStateResult);
@@ -657,6 +726,8 @@ const _: () = {
     assert_endpoint_fits!(AbortLightingOverlayReplaceRequest, LightingUnitResult);
     assert_endpoint_fits!((), LightingSceneStatusResult);
     assert_endpoint_fits!(LightingScenePageRequest, LightingScenesPageResult);
+    assert_endpoint_fits!((), LightingCompiledSceneStatusResult);
+    assert_endpoint_fits!(LightingPageRequest, LightingCompiledScenesPageResult);
     assert_endpoint_fits!(SetLightingSceneCellRequest, LightingStateResult);
     assert_endpoint_fits!(UnsetLightingSceneCellRequest, LightingStateResult);
     assert_endpoint_fits!(SetLightingLayerPolicyRequest, LightingStateResult);
@@ -704,7 +775,7 @@ mod tests {
     }
 
     #[test]
-    fn maximum_overlay_chunk_respects_bound() {
+    fn maximum_overlay_chunk_and_page_respect_bound() {
         let mut cells = Vec::new();
         for id in 0..LIGHTING_OVERLAY_CHUNK_SIZE as u16 {
             cells.push(cell(id)).unwrap();
@@ -712,11 +783,20 @@ mod tests {
         let request = PutLightingOverlayChunkRequest {
             transaction_id: u32::MAX,
             offset: u16::MAX,
-            cells,
+            cells: cells.clone(),
         };
         round_trip(&request);
         assert_max_size_bound(&request);
         assert!(PutLightingOverlayChunkRequest::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+
+        let page = LightingOverlayPage {
+            revision: u32::MAX,
+            total_count: u16::MAX,
+            items: cells,
+        };
+        round_trip(&page);
+        assert_max_size_bound(&page);
+        assert!(LightingOverlayPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
     }
 
     #[test]
@@ -768,6 +848,12 @@ mod tests {
             policy: LightingLayerPolicy::ActiveStack,
             chunk_capacity: LIGHTING_SCENE_CHUNK_SIZE as u8,
         });
+        round_trip(&LightingCompiledSceneStatus {
+            topology_revision: u32::MAX,
+            scene_len: 12,
+            policy: LightingLayerPolicy::EffectiveOnly,
+            chunk_capacity: LIGHTING_SCENE_CHUNK_SIZE as u8,
+        });
         round_trip(&LightingSceneTransaction {
             id: u32::MAX,
             cell_count: u16::MAX,
@@ -794,11 +880,20 @@ mod tests {
         let page = LightingScenesPage {
             revision: u32::MAX,
             total_count: u16::MAX,
-            items: cells,
+            items: cells.clone(),
         };
         round_trip(&page);
         assert_max_size_bound(&page);
         assert!(LightingScenesPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+
+        let compiled_page = LightingCompiledScenesPage {
+            topology_revision: u32::MAX,
+            total_count: u16::MAX,
+            items: cells,
+        };
+        round_trip(&compiled_page);
+        assert_max_size_bound(&compiled_page);
+        assert!(LightingCompiledScenesPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
     }
 
     #[test]
diff --git a/rmk-types/src/protocol/rynk/payload/status.rs b/rmk-types/src/protocol/rynk/payload/status.rs
index b687b4b36..098047bb3 100644
--- a/rmk-types/src/protocol/rynk/payload/status.rs
+++ b/rmk-types/src/protocol/rynk/payload/status.rs
@@ -8,6 +8,35 @@ use serde::{Deserialize, Serialize};
 /// from DeviceCapabilities.
 pub const MATRIX_BITMAP_SIZE: usize = 32;
 
+/// Number of layers represented by [`LayerState`].
+pub const LAYER_STATE_CAPACITY: usize = 64;
+/// Serialized byte width of [`LayerState::active_bitmap`].
+pub const LAYER_STATE_BITMAP_SIZE: usize = LAYER_STATE_CAPACITY / 8;
+
+/// Authoritative snapshot of every layer participating in key resolution.
+///
+/// RMK stores the default layer separately from its mutable layer mask. The
+/// corresponding bit in `active_bitmap` is nevertheless always set by the
+/// firmware so callers can treat this as the complete active set. Bit `n`
+/// reports layer `n`, least-significant bit first within each byte.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, MaxSize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LayerState {
+    pub default_layer: u8,
+    #[cfg_attr(feature = "wasm", tsify(type = "number[]"))]
+    pub active_bitmap: [u8; LAYER_STATE_BITMAP_SIZE],
+}
+
+impl LayerState {
+    /// Whether `layer` participates in the sampled active layer stack.
+    pub const fn is_active(&self, layer: u8) -> bool {
+        let index = layer as usize;
+        index < LAYER_STATE_CAPACITY && self.active_bitmap[index / 8] & (1_u8 << (index % 8)) != 0
+    }
+}
+
 /// Current matrix key-press state as a bitmap.
 /// Bit ordering: row-major, bit 0 = col 0, bit 1 = col 1, etc.
 /// Total meaningful bytes = num_rows * ceil(num_cols / 8).
@@ -43,6 +72,25 @@ mod tests {
     use super::*;
     use crate::protocol::rynk::tests::{assert_max_size_bound, round_trip};
 
+    #[test]
+    fn round_trip_layer_state_covers_all_64_layers() {
+        let mut active_bitmap = [0; LAYER_STATE_BITMAP_SIZE];
+        active_bitmap[0] = 0b0010_0001;
+        active_bitmap[7] = 0b1000_0000;
+        let state = LayerState {
+            default_layer: 5,
+            active_bitmap,
+        };
+
+        round_trip(&state);
+        assert_max_size_bound(&state);
+        assert!(state.is_active(0));
+        assert!(state.is_active(5));
+        assert!(!state.is_active(6));
+        assert!(state.is_active(63));
+        assert!(!state.is_active(64));
+    }
+
     #[test]
     fn round_trip_matrix_state() {
         let mut bitmap = Vec::new();
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index f0fd64d8f..3e4975da6 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -19,14 +19,20 @@ CommitLightingOverlayReplace reply                     0f 09 01 0c 00 00 00 09 0
 CommitLightingOverlayReplace request                   0f 09 01 01 00 0d
 CommitLightingSceneReplace reply                       18 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 CommitLightingSceneReplace request                     18 09 01 01 00 15
-GetLightingCapabilities reply                          01 09 01 0f 00 00 00 01 02 03 04 05 06 07 08 09 08 08 3f 07
+GetLightingCapabilities reply                          01 09 01 10 00 00 00 01 02 03 04 05 06 07 08 09 08 08 bf 03 07
 GetLightingCapabilities request                        01 09 01 00 00
+GetLightingCompiledSceneStatus reply                   1c 09 01 06 00 00 00 01 01 00 08
+GetLightingCompiledSceneStatus request                 1c 09 01 00 00
+GetLightingCompiledScenes reply                        1d 09 01 0b 00 00 00 01 01 01 02 2a 00 07 08 09
+GetLightingCompiledScenes request                      1d 09 01 02 00 01 00
 GetLightingKeys reply                                  11 09 01 07 00 00 00 01 01 01 01 02
 GetLightingKeys request                                11 09 01 02 00 01 00
 GetLightingLeds reply                                  05 09 01 12 00 00 00 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01
 GetLightingLeds request                                05 09 01 02 00 01 00
 GetLightingOutputs reply                               08 09 01 0a 00 00 00 01 01 01 01 02 28 14 00
 GetLightingOutputs request                             08 09 01 02 00 01 00
+GetLightingOverlay reply                               1b 09 01 12 00 00 00 09 01 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27
+GetLightingOverlay request                             1b 09 01 02 00 09 00
 GetLightingPhysicalKeys reply                          04 09 01 13 00 00 00 01 01 01 01 02 ff 01 80 04 80 01 80 02 80 03 db 0b
 GetLightingPhysicalKeys request                        04 09 01 02 00 01 00
 GetLightingRoutes reply                                09 09 01 09 00 00 00 01 01 01 2a 01 02 07
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 691db32a1..48a87fda8 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -351,6 +351,10 @@ fn wire_values_locked() {
         remaining_keys: 2,
         key_positions: unlock_keys,
     };
+    let layer_state = LayerState {
+        default_layer: 2,
+        active_bitmap: [0x05, 0, 0, 0, 0, 0, 0, 0x80],
+    };
     let profile = MorseProfile::new(None, Some(MorseMode::Normal), Some(200), Some(150));
 
     let entries: alloc::vec::Vec<(&str, alloc::vec::Vec<u8>)> = alloc::vec![
@@ -467,6 +471,7 @@ fn wire_values_locked() {
         ("MacroData{[0x01,0x02,0x03]}", encode(&ex.macro_data)),
         // --- Status / system responses ---
         ("MatrixState{[0x05,0x00,0x20]}", encode(&ex.matrix)),
+        ("LayerState{default:2,active:[0x05,..,0x80]}", encode(&layer_state)),
         ("DeviceCapabilities{1..16}", encode(&ex.capabilities)),
         ("DeviceInfo{1.2.3,4,5,RMK,..}", encode(&ex.device_info)),
         ("BuildInfo{my-firmware..}", encode(&ex.build_info)),
@@ -610,6 +615,10 @@ fn wire_frames_locked() {
         remaining_keys: 2,
         key_positions: unlock_keys,
     };
+    let layer_state = LayerState {
+        default_layer: 2,
+        active_bitmap: [0x05, 0, 0, 0, 0, 0, 0, 0x80],
+    };
 
     let entries: alloc::vec::Vec<(&str, alloc::vec::Vec<u8>)> = alloc::vec![
         // System (0x00xx).
@@ -934,6 +943,11 @@ fn wire_frames_locked() {
             "GetLedIndicator reply Ok(LedIndicator(Num|Scroll))",
             encode_frame(Cmd::GetLedIndicator, SEQ, &Ok::<LedIndicator, RynkError>(led)),
         ),
+        ("GetLayerState request ()", encode_frame(Cmd::GetLayerState, SEQ, &())),
+        (
+            "GetLayerState reply Ok(LayerState{default:2,active:[0x05,..,0x80]})",
+            encode_frame(Cmd::GetLayerState, SEQ, &Ok::<LayerState, RynkError>(layer_state)),
+        ),
         // Topics (0x80xx, server→host push, SEQ 0).
         ("LayerChange topic 3", encode_frame(Cmd::LayerChange, 0, &3u8)),
         ("WpmUpdate topic 42", encode_frame(Cmd::WpmUpdate, 0, &42u16)),
@@ -1030,7 +1044,9 @@ fn lighting_wire_frames_locked() {
                 | LightingFeatureFlags::ROUTING
                 | LightingFeatureFlags::OVERLAY_TTL
                 | LightingFeatureFlags::ATOMIC_OVERLAY_REPLACE
-                | LightingFeatureFlags::LAYER_AWARE,
+                | LightingFeatureFlags::LAYER_AWARE
+                | LightingFeatureFlags::OVERLAY_READBACK
+                | LightingFeatureFlags::COMPILED_LAYER_SCENES,
         ),
         effects: LightingEffectFlags(
             LightingEffectFlags::SOLID | LightingEffectFlags::BLINK | LightingEffectFlags::BREATHE,
@@ -1105,6 +1121,15 @@ fn lighting_wire_frames_locked() {
         },
         ttl_ms: Some(5000),
     };
+    let overlay_page_request = LightingOverlayPageRequest {
+        revision: state.revision,
+        offset: 0,
+    };
+    let overlay_page = LightingOverlayPage {
+        revision: state.revision,
+        total_count: 1,
+        items: one(overlay_cell),
+    };
     let set_state = SetLightingStateRequest {
         expected_revision: 8,
         state: mutable_state,
@@ -1157,6 +1182,17 @@ fn lighting_wire_frames_locked() {
         total_count: 1,
         items: one(scene_cell),
     };
+    let compiled_scene_status = LightingCompiledSceneStatus {
+        topology_revision: capabilities.topology_revision,
+        scene_len: 1,
+        policy: LightingLayerPolicy::EffectiveOnly,
+        chunk_capacity: LIGHTING_SCENE_CHUNK_SIZE as u8,
+    };
+    let compiled_scenes_page = LightingCompiledScenesPage {
+        topology_revision: capabilities.topology_revision,
+        total_count: 1,
+        items: one(scene_cell),
+    };
     let set_scene_cell = SetLightingSceneCellRequest {
         expected_revision: 9,
         cell: scene_cell,
@@ -1308,6 +1344,18 @@ fn lighting_wire_frames_locked() {
                 &Ok::<LightingRoutesPageResult, RynkError>(Ok(routes_page))
             )
         ),
+        (
+            "GetLightingOverlay request",
+            encode_frame(Cmd::GetLightingOverlay, SEQ, &overlay_page_request)
+        ),
+        (
+            "GetLightingOverlay reply",
+            encode_frame(
+                Cmd::GetLightingOverlay,
+                SEQ,
+                &Ok::<LightingOverlayPageResult, RynkError>(Ok(overlay_page))
+            )
+        ),
         (
             "SetLightingOverlay request",
             encode_frame(Cmd::SetLightingOverlay, SEQ, &set_overlay)
@@ -1442,6 +1490,30 @@ fn lighting_wire_frames_locked() {
                 &Ok::<LightingScenesPageResult, RynkError>(Ok(scenes_page))
             )
         ),
+        (
+            "GetLightingCompiledSceneStatus request",
+            encode_frame(Cmd::GetLightingCompiledSceneStatus, SEQ, &())
+        ),
+        (
+            "GetLightingCompiledSceneStatus reply",
+            encode_frame(
+                Cmd::GetLightingCompiledSceneStatus,
+                SEQ,
+                &Ok::<LightingCompiledSceneStatusResult, RynkError>(Ok(compiled_scene_status))
+            )
+        ),
+        (
+            "GetLightingCompiledScenes request",
+            encode_frame(Cmd::GetLightingCompiledScenes, SEQ, &page_request)
+        ),
+        (
+            "GetLightingCompiledScenes reply",
+            encode_frame(
+                Cmd::GetLightingCompiledScenes,
+                SEQ,
+                &Ok::<LightingCompiledScenesPageResult, RynkError>(Ok(compiled_scenes_page))
+            )
+        ),
         (
             "SetLightingSceneCell request",
             encode_frame(Cmd::SetLightingSceneCell, SEQ, &set_scene_cell)
diff --git a/rmk/src/host/context.rs b/rmk/src/host/context.rs
index e13988c2f..95505163a 100644
--- a/rmk/src/host/context.rs
+++ b/rmk/src/host/context.rs
@@ -9,6 +9,7 @@ use rmk_types::connection::{ConnectionStatus, ConnectionType};
 use rmk_types::fork::Fork;
 use rmk_types::led_indicator::LedIndicator;
 use rmk_types::morse::{Morse, MorseProfile};
+use rmk_types::protocol::rynk::{LAYER_STATE_BITMAP_SIZE, LAYER_STATE_CAPACITY, LayerState};
 
 use crate::event::KeyboardEventPos;
 use crate::keyboard::combo::Combo;
@@ -308,6 +309,29 @@ impl<'a> KeyboardContext<'a> {
         self.keymap.active_layer()
     }
 
+    /// Snapshot the complete active-layer set for host consumers.
+    ///
+    /// The mutable keymap mask does not contain the default layer, so its bit
+    /// is added explicitly to make this snapshot authoritative.
+    pub fn layer_state(&self) -> LayerState {
+        let default_layer = self.keymap.get_default_layer();
+        let mut active_bitmap = [0; LAYER_STATE_BITMAP_SIZE];
+
+        if (default_layer as usize) < LAYER_STATE_CAPACITY {
+            active_bitmap[default_layer as usize / 8] |= 1_u8 << (default_layer as usize % 8);
+        }
+        for layer in 0..self.keymap.num_layer().min(LAYER_STATE_CAPACITY) {
+            if self.keymap.is_layer_active(layer as u8) {
+                active_bitmap[layer / 8] |= 1_u8 << (layer % 8);
+            }
+        }
+
+        LayerState {
+            default_layer,
+            active_bitmap,
+        }
+    }
+
     pub fn default_layer(&self) -> u8 {
         self.keymap.get_default_layer()
     }
@@ -351,3 +375,44 @@ impl<'a> KeyboardContext<'a> {
         self.keymap.read_matrix_state(target);
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use rmk_types::action::KeyAction;
+
+    use super::KeyboardContext;
+    use crate::config::{BehaviorConfig, PositionalConfig};
+    use crate::keymap::{KeyMap, KeymapData};
+    use crate::test_support::test_block_on as block_on;
+
+    #[test]
+    fn layer_state_includes_default_explicit_and_tri_layers() {
+        let mut data: KeymapData<1, 1, 64> = KeymapData::new([[[KeyAction::No]]; 64]);
+        let mut behavior = BehaviorConfig {
+            default_layer: 5,
+            tri_layer: Some([1, 2, 3]),
+            ..Default::default()
+        };
+        let positional = PositionalConfig::<1, 1>::default();
+        let keymap = block_on(KeyMap::new(&mut data, &mut behavior, &positional));
+        let context = KeyboardContext::new(&keymap);
+
+        let default_only = context.layer_state();
+        assert_eq!(default_only.default_layer, 5);
+        assert!(default_only.is_active(5));
+        assert!((0..64).all(|layer| layer == 5 || !default_only.is_active(layer)));
+
+        keymap.activate_layer(1);
+        keymap.activate_layer(2);
+        keymap.activate_layer(63);
+
+        let state = context.layer_state();
+        assert_eq!(state.default_layer, 5);
+        assert!(!state.is_active(0));
+        assert!(state.is_active(1));
+        assert!(state.is_active(2));
+        assert!(state.is_active(3));
+        assert!(state.is_active(5));
+        assert!(state.is_active(63));
+    }
+}
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 7b2a631e6..7365987d7 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -3,23 +3,26 @@
 use embassy_time::Instant;
 use heapless::{String, Vec};
 use rmk_types::protocol::rynk::command::{
-    ClearLightingOverlay, GetLightingCapabilities, GetLightingKeys, GetLightingLeds, GetLightingOutputs,
-    GetLightingPhysicalKeys, GetLightingRoutes, GetLightingSceneStatus, GetLightingScenes, GetLightingState,
-    GetLightingZoneMemberships, GetLightingZones, SetLightingLayerPolicy, SetLightingOverlay, SetLightingSceneCell,
-    SetLightingState, UnsetLightingOverlay, UnsetLightingSceneCell,
+    ClearLightingOverlay, GetLightingCapabilities, GetLightingCompiledSceneStatus, GetLightingCompiledScenes,
+    GetLightingKeys, GetLightingLeds, GetLightingOutputs, GetLightingOverlay, GetLightingPhysicalKeys,
+    GetLightingRoutes, GetLightingSceneStatus, GetLightingScenes, GetLightingState, GetLightingZoneMemberships,
+    GetLightingZones, SetLightingLayerPolicy, SetLightingOverlay, SetLightingSceneCell, SetLightingState,
+    UnsetLightingOverlay, UnsetLightingSceneCell,
 };
 use rmk_types::protocol::rynk::{
     AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
     BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest,
     CommitLightingSceneReplaceRequest, LIGHTING_PAGE_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LIGHTING_ZONE_NAME_SIZE,
-    LightingCapabilities, LightingCapabilitiesResult, LightingEffectFlags, LightingError, LightingFeatureFlags,
-    LightingKeysPage, LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
+    LightingCapabilities, LightingCapabilitiesResult, LightingCompiledSceneStatus, LightingCompiledSceneStatusResult,
+    LightingCompiledScenesPageResult, LightingEffectFlags, LightingError, LightingFeatureFlags, LightingKeysPage,
+    LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
     LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage, LightingOutputsPage,
-    LightingOutputsPageResult, LightingOverlayCell, LightingOverlayTransaction, LightingOverlayTransactionResult,
-    LightingPageRequest, LightingPhysicalKey, LightingPhysicalKeysPage, LightingPhysicalKeysPageResult, LightingPoint3,
-    LightingResult, LightingRoute, LightingRoutesPage, LightingRoutesPageResult, LightingScenePageRequest,
-    LightingSceneStatus, LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult,
-    LightingState, LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage,
+    LightingOutputsPageResult, LightingOverlayCell, LightingOverlayPageRequest, LightingOverlayPageResult,
+    LightingOverlayTransaction, LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKey,
+    LightingPhysicalKeysPage, LightingPhysicalKeysPageResult, LightingPoint3, LightingResult, LightingRoute,
+    LightingRoutesPage, LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatus,
+    LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult, LightingState,
+    LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage,
     LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult, PutLightingOverlayChunkRequest,
     PutLightingSceneChunkRequest, RynkError, RynkMessage, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
     SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
@@ -63,6 +66,26 @@ impl Handle<GetLightingState> for RynkService<'_> {
     }
 }
 
+impl Handle<GetLightingOverlay> for RynkService<'_> {
+    async fn handle(&self, req: LightingOverlayPageRequest) -> Result<LightingOverlayPageResult, RynkError> {
+        let result = match controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::ReadOverlay {
+                    expected_revision: req.revision,
+                    offset: req.offset,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::OverlayPage(page)) => Ok(page),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
 impl Handle<SetLightingState> for RynkService<'_> {
     async fn handle(&self, req: SetLightingStateRequest) -> Result<LightingStateResult, RynkError> {
         let result = match controller(self) {
@@ -189,6 +212,50 @@ impl Handle<GetLightingScenes> for RynkService<'_> {
     }
 }
 
+impl Handle<GetLightingCompiledSceneStatus> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LightingCompiledSceneStatusResult, RynkError> {
+        let result = match controller(self) {
+            Ok(controller) => match controller.request(RynkLightingCommand::ReadCompiledSceneStatus).await {
+                Ok(RynkLightingReadback::CompiledSceneStatus { scene_len, policy }) => {
+                    Ok(LightingCompiledSceneStatus {
+                        topology_revision: controller.descriptor.topology_revision,
+                        scene_len,
+                        policy,
+                        chunk_capacity: LIGHTING_SCENE_CHUNK_SIZE as u8,
+                    })
+                }
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<GetLightingCompiledScenes> for RynkService<'_> {
+    async fn handle(&self, req: LightingPageRequest) -> Result<LightingCompiledScenesPageResult, RynkError> {
+        let result = match controller(self).and_then(|controller| {
+            check_topology_revision(controller, req.topology_revision)?;
+            Ok(controller)
+        }) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::ReadCompiledScenes { offset: req.offset })
+                .await
+            {
+                Ok(RynkLightingReadback::CompiledScenesPage(mut page)) => {
+                    page.topology_revision = controller.descriptor.topology_revision;
+                    Ok(page)
+                }
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
 impl Handle<SetLightingSceneCell> for RynkService<'_> {
     async fn handle(&self, req: SetLightingSceneCellRequest) -> Result<LightingStateResult, RynkError> {
         if let Err(error) = req
@@ -389,7 +456,9 @@ fn capabilities(binding: RynkLightingController<'_>) -> LightingCapabilities {
     let mut features = LightingFeatureFlags(
         LightingFeatureFlags::OVERLAY_TTL
             | LightingFeatureFlags::ATOMIC_OVERLAY_REPLACE
-            | LightingFeatureFlags::LAYER_AWARE,
+            | LightingFeatureFlags::LAYER_AWARE
+            | LightingFeatureFlags::OVERLAY_READBACK
+            | LightingFeatureFlags::COMPILED_LAYER_SCENES,
     );
     if !topology.physical_layout.keys.is_empty() {
         features.0 |= LightingFeatureFlags::PHYSICAL_GEOMETRY;
@@ -855,8 +924,8 @@ mod tests {
     use crate::host::RynkLightingMailbox;
     use crate::keymap::{KeyMap, KeymapData};
     use crate::lighting::{
-        LedId, LedMetadata, LightingNodeId as CoreNodeId, LightingRouting, LightingTopology, MatrixSize, OutputId,
-        OutputMetadata, PhysicalRoute, ZoneSpan,
+        BuiltinEffect, LayerScene, LedId, LedMetadata, LightingNodeId as CoreNodeId, LightingRouting, LightingTopology,
+        MatrixSize, OutputId, OutputMetadata, PhysicalRoute, Rgb8, SceneCell, ZoneSpan,
     };
     use crate::physical_layout::{
         Coordinate, Extent, KeyPosition, KeySize, PhysicalKey, PhysicalLayout, Point3, Rotation,
@@ -905,6 +974,24 @@ mod tests {
             physical_index: 1,
         },
     ];
+    static COMPILED_CELLS: [SceneCell<BuiltinEffect>; 2] = [
+        SceneCell {
+            slot: crate::lighting::LedSlot(0),
+            effect: BuiltinEffect::Solid {
+                color: Rgb8::new(10, 20, 30),
+            },
+        },
+        SceneCell {
+            slot: crate::lighting::LedSlot(1),
+            effect: BuiltinEffect::Solid {
+                color: Rgb8::new(40, 50, 60),
+            },
+        },
+    ];
+    static COMPILED_LAYERS: [LayerScene<'static, BuiltinEffect>; 1] = [LayerScene {
+        layer: 0,
+        cells: &COMPILED_CELLS,
+    }];
 
     fn descriptor() -> super::super::super::lighting::RynkLightingDescriptor<'static> {
         super::super::super::lighting::RynkLightingDescriptor {
@@ -1354,6 +1441,10 @@ mod tests {
 
             let lighting = capabilities(service.lighting.unwrap());
             assert!(!lighting.features.contains(LightingFeatureFlags::LAYER_SCENES));
+            assert!(
+                lighting.features.contains(LightingFeatureFlags::COMPILED_LAYER_SCENES),
+                "compiled-scene readback is supported even when the source is empty"
+            );
 
             let status = call::<rmk_types::protocol::rynk::command::GetLightingSceneStatus>(&service, &session, &())
                 .await
@@ -1379,14 +1470,16 @@ mod tests {
     fn scene_endpoints_flow_through_adapter_and_engine() {
         use embassy_futures::select::{Either3, select3};
         use rmk_types::protocol::rynk::command::{
-            AbortLightingSceneReplace, BeginLightingSceneReplace, CommitLightingSceneReplace, GetLightingSceneStatus,
-            GetLightingScenes, PutLightingSceneChunk, SetLightingLayerPolicy, SetLightingSceneCell,
+            AbortLightingSceneReplace, BeginLightingSceneReplace, CommitLightingSceneReplace,
+            GetLightingCompiledSceneStatus, GetLightingCompiledScenes, GetLightingOverlay, GetLightingSceneStatus,
+            GetLightingScenes, PutLightingSceneChunk, SetLightingLayerPolicy, SetLightingOverlay, SetLightingSceneCell,
             UnsetLightingSceneCell,
         };
         use rmk_types::protocol::rynk::{
             BeginLightingSceneReplaceRequest, CommitLightingSceneReplaceRequest, LightingLayerPolicy,
-            LightingScenePageRequest, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest,
-            SetLightingSceneCellRequest, UnsetLightingSceneCellRequest,
+            LightingOverlayPageRequest, LightingPageRequest, LightingScenePageRequest, PutLightingSceneChunkRequest,
+            SetLightingLayerPolicyRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest,
+            UnsetLightingSceneCellRequest,
         };
 
         use crate::lighting::{
@@ -1416,7 +1509,7 @@ mod tests {
                 StandardLightingEngine::new(
                     BackgroundState::default(),
                     LayerScenes {
-                        scenes: &[],
+                        scenes: &COMPILED_LAYERS,
                         policy: LayerPolicy::ActiveStack,
                     },
                     EmptySource,
@@ -1425,8 +1518,50 @@ mod tests {
 
             let lighting = capabilities(service.lighting.unwrap());
             assert!(lighting.features.contains(LightingFeatureFlags::LAYER_SCENES));
+            assert!(lighting.features.contains(LightingFeatureFlags::OVERLAY_READBACK));
+            assert!(lighting.features.contains(LightingFeatureFlags::COMPILED_LAYER_SCENES));
 
             let client = async {
+                let compiled_status = call::<GetLightingCompiledSceneStatus>(&service, &session, &())
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(compiled_status.topology_revision, 7);
+                assert_eq!(compiled_status.scene_len, 2);
+                assert_eq!(compiled_status.policy, LightingLayerPolicy::ActiveStack);
+                let compiled = call::<GetLightingCompiledScenes>(
+                    &service,
+                    &session,
+                    &LightingPageRequest {
+                        topology_revision: 7,
+                        offset: 0,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(compiled.total_count, 2);
+                assert_eq!(compiled.items[0].layer, 0);
+                assert_eq!(compiled.items[0].led_id, LightingLedId(10));
+                assert_eq!(compiled.items[1].led_id, LightingLedId(42));
+                let stale_compiled = call::<GetLightingCompiledScenes>(
+                    &service,
+                    &session,
+                    &LightingPageRequest {
+                        topology_revision: 6,
+                        offset: 0,
+                    },
+                )
+                .await
+                .unwrap();
+                assert_eq!(
+                    stale_compiled,
+                    Err(LightingError::TopologyRevisionConflict {
+                        expected: 6,
+                        current: 7
+                    })
+                );
+
                 let status = call::<GetLightingSceneStatus>(&service, &session, &())
                     .await
                     .unwrap()
@@ -1579,6 +1714,15 @@ mod tests {
                     .unwrap();
                 assert_eq!(status.policy, LightingLayerPolicy::EffectiveOnly);
                 assert_eq!(status.scene_len, 1);
+                let compiled_status = call::<GetLightingCompiledSceneStatus>(&service, &session, &())
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(
+                    compiled_status.policy,
+                    LightingLayerPolicy::ActiveStack,
+                    "runtime policy mutations do not change the compiled source policy"
+                );
 
                 // Unset through stable identity, then abort of a dead
                 // transaction reports it as unknown.
@@ -1603,6 +1747,45 @@ mod tests {
                 .await
                 .unwrap();
                 assert_eq!(aborted, Err(LightingError::InvalidTransaction));
+
+                let mut transient = overlay_cell(42);
+                transient.ttl_ms = Some(5_000);
+                let state = call::<SetLightingOverlay>(
+                    &service,
+                    &session,
+                    &SetLightingOverlayRequest {
+                        expected_revision: 4,
+                        cell: transient,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(state.revision, 5);
+                let overlay = call::<GetLightingOverlay>(
+                    &service,
+                    &session,
+                    &LightingOverlayPageRequest { revision: 5, offset: 0 },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(overlay.total_count, 1);
+                assert_eq!(overlay.items[0], transient);
+                let stale_overlay = call::<GetLightingOverlay>(
+                    &service,
+                    &session,
+                    &LightingOverlayPageRequest { revision: 4, offset: 0 },
+                )
+                .await
+                .unwrap();
+                assert_eq!(
+                    stale_overlay,
+                    Err(LightingError::StateRevisionConflict {
+                        expected: 4,
+                        current: 5
+                    })
+                );
             };
 
             let adapter_loop = async {
diff --git a/rmk/src/host/rynk/handlers/status.rs b/rmk/src/host/rynk/handlers/status.rs
index 7017dd1f2..2dc8967c7 100644
--- a/rmk/src/host/rynk/handlers/status.rs
+++ b/rmk/src/host/rynk/handlers/status.rs
@@ -11,8 +11,10 @@ use rmk_types::protocol::rynk::PeripheralStatus;
 use rmk_types::protocol::rynk::command::GetBatteryStatus;
 #[cfg(feature = "split")]
 use rmk_types::protocol::rynk::command::GetPeripheralStatus;
-use rmk_types::protocol::rynk::command::{GetCurrentLayer, GetLedIndicator, GetMatrixState, GetSleepState, GetWpm};
-use rmk_types::protocol::rynk::{MATRIX_BITMAP_SIZE, MatrixState, RynkError};
+use rmk_types::protocol::rynk::command::{
+    GetCurrentLayer, GetLayerState, GetLedIndicator, GetMatrixState, GetSleepState, GetWpm,
+};
+use rmk_types::protocol::rynk::{LayerState, MATRIX_BITMAP_SIZE, MatrixState, RynkError};
 
 use super::super::RynkService;
 use super::Handle;
@@ -23,6 +25,12 @@ impl Handle<GetCurrentLayer> for RynkService<'_> {
     }
 }
 
+impl Handle<GetLayerState> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LayerState, RynkError> {
+        Ok(self.ctx.layer_state())
+    }
+}
+
 impl Handle<GetMatrixState> for RynkService<'_> {
     async fn handle(&self, _: ()) -> Result<MatrixState, RynkError> {
         // Sized for the maximum supported matrix — host slices it down
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 99c2d8467..4b18ac5ba 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -15,23 +15,28 @@ use embassy_sync::mutex::Mutex;
 use embassy_sync::signal::Signal;
 use heapless::Vec;
 use rmk_types::protocol::rynk::{
-    LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState, LightingError, LightingLayerPolicy,
-    LightingMutableState, LightingOverlayCell, LightingResult, LightingRgb8, LightingSceneCell,
-    LightingSceneTransaction, LightingScenesPage, LightingState,
+    LIGHTING_OVERLAY_CHUNK_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState,
+    LightingCompiledScenesPage, LightingError, LightingLayerPolicy, LightingMutableState, LightingOverlayCell,
+    LightingOverlayPage, LightingResult, LightingRgb8, LightingSceneCell, LightingSceneTransaction, LightingScenesPage,
+    LightingState,
 };
 
 use crate::RawMutex;
 use crate::core_traits::Runnable;
 use crate::lighting::{
     BackgroundMode, BackgroundState, BuiltinEffect, LayerPolicy, LedId, LightingMailbox, LightingRouting,
-    LightingTopology, OverlayBatch, OverlayCell, OverlayError, Rgb8, SceneChunk, SceneTableCell, StandardCommand,
-    StandardError, StandardLightingEngine, StandardMutableState, StandardReply, StandardState,
+    LightingTopology, OVERLAY_CHUNK_SIZE, OverlayBatch, OverlayCell, OverlayError, Rgb8, SceneChunk, SceneTableCell,
+    StandardCommand, StandardError, StandardLightingEngine, StandardMutableState, StandardReply, StandardState,
 };
 
 const _: () = core::assert!(
     crate::lighting::SCENE_CHUNK_SIZE == LIGHTING_SCENE_CHUNK_SIZE,
     "engine scene chunk must match the wire chunk so adapters forward chunks unmodified"
 );
+const _: () = core::assert!(
+    OVERLAY_CHUNK_SIZE == LIGHTING_OVERLAY_CHUNK_SIZE,
+    "engine overlay page must match the wire chunk so adapters forward pages unmodified"
+);
 
 /// Maximum number of cells staged by one Rynk overlay replacement.
 ///
@@ -124,12 +129,18 @@ impl<'a> RynkLightingController<'a> {
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum RynkLightingReadback {
     State(LightingState),
+    OverlayPage(LightingOverlayPage),
     SceneStatus {
         revision: u32,
         scene_len: u16,
         policy: LightingLayerPolicy,
     },
     ScenesPage(LightingScenesPage),
+    CompiledSceneStatus {
+        scene_len: u16,
+        policy: LightingLayerPolicy,
+    },
+    CompiledScenesPage(LightingCompiledScenesPage),
     SceneTransaction(LightingSceneTransaction),
     Unit,
 }
@@ -281,11 +292,19 @@ impl Default for RynkLightingMailbox {
 
 pub(super) enum RynkLightingCommand {
     ReadState,
+    ReadOverlay {
+        expected_revision: u32,
+        offset: u16,
+    },
     ReadSceneStatus,
     ReadScenes {
         expected_revision: u32,
         offset: u16,
     },
+    ReadCompiledSceneStatus,
+    ReadCompiledScenes {
+        offset: u16,
+    },
     SetSceneCell {
         expected_revision: u32,
         cell: LightingSceneCell,
@@ -460,6 +479,32 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
     async fn dispatch(&self, request_id: u32, command: RynkLightingCommand) -> LightingResult<RynkLightingReadback> {
         let core_command = match command {
             RynkLightingCommand::ReadState => StandardCommand::ReadState,
+            RynkLightingCommand::ReadOverlay {
+                expected_revision,
+                offset,
+            } => {
+                let page = match self.request_core(StandardCommand::ReadOverlay { offset }).await? {
+                    StandardReply::OverlayPage(page) => page,
+                    _ => return Err(LightingError::InvalidRequest),
+                };
+                if page.revision != expected_revision {
+                    return Err(LightingError::StateRevisionConflict {
+                        expected: expected_revision,
+                        current: page.revision,
+                    });
+                }
+                let mut items: Vec<LightingOverlayCell, LIGHTING_OVERLAY_CHUNK_SIZE> = Vec::new();
+                for cell in page.cells.as_slice() {
+                    items
+                        .push(self.overlay_cell_to_wire(*cell).ok_or(LightingError::InvalidRequest)?)
+                        .map_err(|_| LightingError::InvalidRequest)?;
+                }
+                return Ok(RynkLightingReadback::OverlayPage(LightingOverlayPage {
+                    revision: page.revision,
+                    total_count: page.total,
+                    items,
+                }));
+            }
             RynkLightingCommand::ReadSceneStatus => {
                 let state = self.request_core_state(StandardCommand::ReadState).await?;
                 return Ok(RynkLightingReadback::SceneStatus {
@@ -495,6 +540,39 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                     items,
                 }));
             }
+            RynkLightingCommand::ReadCompiledSceneStatus => {
+                let page = match self
+                    .request_core(StandardCommand::ReadCompiledScenes { offset: 0 })
+                    .await?
+                {
+                    StandardReply::CompiledScenesPage(page) => page,
+                    _ => return Err(LightingError::InvalidRequest),
+                };
+                return Ok(RynkLightingReadback::CompiledSceneStatus {
+                    scene_len: page.total,
+                    policy: policy_to_wire(page.policy),
+                });
+            }
+            RynkLightingCommand::ReadCompiledScenes { offset } => {
+                let page = match self
+                    .request_core(StandardCommand::ReadCompiledScenes { offset })
+                    .await?
+                {
+                    StandardReply::CompiledScenesPage(page) => page,
+                    _ => return Err(LightingError::InvalidRequest),
+                };
+                let mut items: Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE> = Vec::new();
+                for cell in page.cells.as_slice() {
+                    items
+                        .push(self.scene_cell_to_wire(*cell).ok_or(LightingError::InvalidRequest)?)
+                        .map_err(|_| LightingError::InvalidRequest)?;
+                }
+                return Ok(RynkLightingReadback::CompiledScenesPage(LightingCompiledScenesPage {
+                    topology_revision: 0,
+                    total_count: page.total,
+                    items,
+                }));
+            }
             RynkLightingCommand::SetSceneCell {
                 expected_revision,
                 cell,
@@ -653,6 +731,15 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
         })
     }
 
+    fn overlay_cell_to_wire(&self, cell: OverlayCell) -> Option<LightingOverlayCell> {
+        let led = self.topology.led(cell.slot)?;
+        Some(LightingOverlayCell {
+            led_id: rmk_types::protocol::rynk::LightingLedId(led.id.0),
+            effect: effect_to_wire(cell.effect),
+            ttl_ms: cell.ttl_ms.map(NonZeroU32::get),
+        })
+    }
+
     fn scene_cell_from_wire(&self, cell: LightingSceneCell) -> LightingResult<SceneTableCell> {
         cell.validate()?;
         let slot = self
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index fa6e6d9ed..baa4a13c1 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -249,6 +249,7 @@ impl<'a> RynkService<'a> {
             Cmd::GetWpm => serve::<command::GetWpm, _>(self, msg).await,
             Cmd::GetSleepState => serve::<command::GetSleepState, _>(self, msg).await,
             Cmd::GetLedIndicator => serve::<command::GetLedIndicator, _>(self, msg).await,
+            Cmd::GetLayerState => serve::<command::GetLayerState, _>(self, msg).await,
 
             Cmd::GetLayout => serve::<command::GetLayout, _>(self, msg).await,
 
@@ -258,6 +259,8 @@ impl<'a> RynkService<'a> {
             Cmd::GetLightingState => serve::<command::GetLightingState, _>(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::SetLightingState => serve::<command::SetLightingState, _>(self, msg).await,
+            Cmd::GetLightingOverlay => serve::<command::GetLightingOverlay, _>(self, msg).await,
+            #[cfg(feature = "lighting")]
             #[cfg(feature = "lighting")]
             Cmd::GetLightingKeys => serve::<command::GetLightingKeys, _>(self, msg).await,
             #[cfg(feature = "lighting")]
@@ -291,6 +294,12 @@ impl<'a> RynkService<'a> {
             #[cfg(feature = "lighting")]
             Cmd::GetLightingScenes => Serve::<command::GetLightingScenes, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
+            Cmd::GetLightingCompiledSceneStatus => {
+                Serve::<command::GetLightingCompiledSceneStatus, _>::serve(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingCompiledScenes => Serve::<command::GetLightingCompiledScenes, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
             Cmd::SetLightingSceneCell => Serve::<command::SetLightingSceneCell, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::UnsetLightingSceneCell => Serve::<command::UnsetLightingSceneCell, _>::serve(self, msg).await,
diff --git a/rmk/src/keymap.rs b/rmk/src/keymap.rs
index b20b55307..448f8d9c6 100644
--- a/rmk/src/keymap.rs
+++ b/rmk/src/keymap.rs
@@ -147,6 +147,9 @@ impl KeyMapInner<'_> {
             return;
         }
         let before = self.get_activated_layer();
+        if self.behavior.default_layer == layer_num {
+            return;
+        }
         self.behavior.default_layer = layer_num;
         let after = self.get_activated_layer();
         // With no layer key held, the activated layer follows the default; a
@@ -154,6 +157,7 @@ impl KeyMapInner<'_> {
         if before != after {
             publish_event(LayerChangeEvent::new(after));
         }
+        publish_event(LayerChangeEvent::new(self.get_activated_layer()));
     }
 
     fn get_action_at(&self, pos: KeyboardEventPos, layer_num: usize) -> KeyAction {
@@ -802,6 +806,7 @@ mod test {
     use rmk_types::fork::{Fork, StateBits};
     use rmk_types::modifier::ModifierCombination;
 
+    use crate::event::{LayerChangeEvent, SubscribableEvent};
     use crate::keyboard::combo::{Combo, ComboConfig};
     use crate::keymap::fill_vec;
     use crate::{COMBO_MAX_NUM, FORK_MAX_NUM, k};
@@ -889,4 +894,20 @@ mod test {
         keymap.deactivate_layer_if_active(2);
         assert!(self_activated && !keymap.is_layer_active(2));
     }
+
+    #[test]
+    fn changing_default_layer_publishes_layer_change() {
+        use crate::config::{BehaviorConfig, PositionalConfig};
+        use crate::keymap::{KeyMap, KeymapData};
+
+        let mut data = KeymapData::<1, 1, 2>::new([[[k!(A)]], [[k!(B)]]]);
+        let mut behavior = BehaviorConfig::default();
+        let positional = PositionalConfig::<1, 1>::default();
+        let keymap = KeyMap::build(&mut data, &mut behavior, &positional);
+        let mut subscriber = LayerChangeEvent::subscriber();
+
+        keymap.set_default_layer(1);
+
+        assert_eq!(subscriber.try_next_message_pure(), Some(LayerChangeEvent::new(1)));
+    }
 }
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index eefd00209..d180835ef 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -41,10 +41,10 @@ pub use source::{
     OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
 };
 pub use standard::{
-    BackgroundMode, BackgroundPatch, BackgroundState, EmptySource, OverlayBatch, OverlayCell, ReplicaSlotError,
-    SCENE_CHUNK_SIZE, SCENE_TRANSACTION_TIMEOUT_MS, SceneChunk, ScenePage, SceneTable, SceneTableCell, StandardCommand,
-    StandardError, StandardInput, StandardLightingEngine, StandardMutableState, StandardReplicaSlot,
-    StandardReplicaState, StandardReply, StandardState, UniformBackground,
+    BackgroundMode, BackgroundPatch, BackgroundState, CompiledScenePage, EmptySource, OVERLAY_CHUNK_SIZE, OverlayBatch,
+    OverlayCell, OverlayPage, ReplicaSlotError, SCENE_CHUNK_SIZE, SCENE_TRANSACTION_TIMEOUT_MS, SceneChunk, ScenePage,
+    SceneTable, SceneTableCell, StandardCommand, StandardError, StandardInput, StandardLightingEngine,
+    StandardMutableState, StandardReplicaSlot, StandardReplicaState, StandardReply, StandardState, UniformBackground,
 };
 pub use topology::*;
 
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index d958eb5f3..28ab7901c 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -57,6 +57,19 @@ pub struct LayerScenes<'a, E> {
 }
 
 impl<'a, E> LayerScenes<'a, E> {
+    /// Number of board-compiled cells across every configured layer.
+    pub fn cell_count(&self) -> usize {
+        self.scenes.iter().map(|scene| scene.cells.len()).sum()
+    }
+
+    /// Iterate every board-compiled cell in declaration order while retaining
+    /// the layer carried by its enclosing scene.
+    pub fn cells(&self) -> impl Iterator<Item = (u8, &'a SceneCell<E>)> + '_ {
+        self.scenes
+            .iter()
+            .flat_map(|scene| scene.cells.iter().map(move |cell| (scene.layer, cell)))
+    }
+
     fn cell_for_layer(&self, layer: u8, wanted: &mut usize) -> Option<&SceneCell<E>> {
         for scene in self.scenes.iter().filter(|scene| scene.layer == layer) {
             if *wanted < scene.cells.len() {
diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index db8f0906e..3113be918 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -24,6 +24,10 @@ use super::source::{LayerPolicy, LayerScenes, OverlayError, OverlayUpdate, TtlOv
 use super::topology::LedSlot;
 use crate::RawMutex;
 
+/// Cells per overlay readback page. Kept equal to the wire chunk size so
+/// protocol adapters can forward pages without re-batching.
+pub const OVERLAY_CHUNK_SIZE: usize = 8;
+
 /// Cells per scene page/replacement chunk. Kept equal to the wire chunk size
 /// so protocol adapters can forward chunks without re-batching.
 pub const SCENE_CHUNK_SIZE: usize = 8;
@@ -511,6 +515,10 @@ pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
     /// slot. Intended for a renderer replica, not a second authority.
     ApplyReplica(&'static StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP>),
     ReadState,
+    /// One atomically sampled page of the transient overlay.
+    ReadOverlay {
+        offset: u16,
+    },
     SetSceneCellIfRevision {
         expected_revision: u32,
         cell: SceneTableCell,
@@ -545,6 +553,10 @@ pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
     ReadScenes {
         offset: u16,
     },
+    /// One page of the immutable board-compiled layer scenes.
+    ReadCompiledScenes {
+        offset: u16,
+    },
 }
 
 /// Mutable standard state excluding the transient overlay contents and the
@@ -567,6 +579,14 @@ pub struct StandardState {
     pub scene_policy: LayerPolicy,
 }
 
+/// One page of transient overlay cells with remaining TTLs.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct OverlayPage {
+    pub revision: u32,
+    pub total: u16,
+    pub cells: OverlayBatch<OVERLAY_CHUNK_SIZE>,
+}
+
 /// One page of stored scene cells with the revision it was read under.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct ScenePage {
@@ -575,13 +595,23 @@ pub struct ScenePage {
     pub cells: SceneChunk,
 }
 
+/// One page of immutable board-compiled layer scenes.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct CompiledScenePage {
+    pub total: u16,
+    pub policy: LayerPolicy,
+    pub cells: SceneChunk,
+}
+
 /// Protocol-independent readback for [`StandardCommand`]s. Most commands
 /// answer with authoritative [`StandardState`]; scene reads and transaction
 /// reservation carry their own shapes.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum StandardReply {
     State(StandardState),
+    OverlayPage(OverlayPage),
     ScenesPage(ScenePage),
+    CompiledScenesPage(CompiledScenePage),
     SceneTransaction { id: u32, cell_count: u16 },
 }
 
@@ -1180,6 +1210,41 @@ where
         // bespoke revision behavior; everything else falls through to the
         // uniform state-readback path below.
         match command {
+            StandardCommand::ReadOverlay { offset } => {
+                let old_len = self.overlay.active_len();
+                self.overlay.prune_expired(effect_now_ms);
+                let expired = self.overlay.active_len() != old_len;
+                if expired {
+                    self.advance_revision();
+                }
+                let start = (offset as usize).min(self.overlay.active_len());
+                let mut cells = OverlayBatch::new();
+                for update in self.overlay.active_updates().skip(start).take(OVERLAY_CHUNK_SIZE) {
+                    let ttl_ms = update.expires_ms.map(|expires_ms| {
+                        let remaining = expires_ms.saturating_sub(effect_now_ms).min(u32::MAX as u64) as u32;
+                        NonZeroU32::new(remaining).expect("expired overlays were pruned")
+                    });
+                    cells
+                        .push(OverlayCell {
+                            slot: update.slot,
+                            effect: update.effect,
+                            ttl_ms,
+                        })
+                        .expect("overlay page is chunk-bounded");
+                }
+                return Ok(CommandResult::new(
+                    StandardReply::OverlayPage(OverlayPage {
+                        revision: self.revision,
+                        total: self.overlay.active_len().min(u16::MAX as usize) as u16,
+                        cells,
+                    }),
+                    if expired {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                ));
+            }
             StandardCommand::ReadScenes { offset } => {
                 return Ok(CommandResult::unchanged(StandardReply::ScenesPage(ScenePage {
                     revision: self.revision,
@@ -1187,6 +1252,25 @@ where
                     cells: self.scenes.page(offset),
                 })));
             }
+            StandardCommand::ReadCompiledScenes { offset } => {
+                let mut cells = SceneChunk::new();
+                for (layer, cell) in self.layers.cells().skip(offset as usize).take(SCENE_CHUNK_SIZE) {
+                    cells
+                        .push(SceneTableCell {
+                            layer,
+                            slot: cell.slot,
+                            effect: cell.effect,
+                        })
+                        .expect("compiled scene page is chunk-bounded");
+                }
+                return Ok(CommandResult::unchanged(StandardReply::CompiledScenesPage(
+                    CompiledScenePage {
+                        total: self.layers.cell_count().min(u16::MAX as usize) as u16,
+                        policy: self.layers.policy,
+                        cells,
+                    },
+                )));
+            }
             StandardCommand::BeginSceneReplace {
                 expected_revision,
                 cell_count,
@@ -1394,7 +1478,9 @@ where
                 )
             }
             StandardCommand::ReadState => (Invalidation::None, false),
-            StandardCommand::ReadScenes { .. }
+            StandardCommand::ReadOverlay { .. }
+            | StandardCommand::ReadScenes { .. }
+            | StandardCommand::ReadCompiledScenes { .. }
             | StandardCommand::BeginSceneReplace { .. }
             | StandardCommand::PutSceneChunk { .. }
             | StandardCommand::CommitSceneReplace { .. }
@@ -1789,6 +1875,98 @@ mod tests {
         assert_eq!(engine.state().revision, 5, "expiry advances exactly once");
     }
 
+    #[test]
+    fn overlay_pages_sample_remaining_ttl_and_prune_with_revision_advance() {
+        let mut engine = engine();
+        let snapshot = context(0);
+        engine
+            .handle_command(
+                100,
+                StandardCommand::SetOverlay(OverlayCell {
+                    slot: LedSlot(0),
+                    effect: BuiltinEffect::Solid { color: RED },
+                    ttl_ms: None,
+                }),
+                &snapshot,
+            )
+            .unwrap();
+        engine
+            .handle_command(
+                100,
+                StandardCommand::SetOverlay(OverlayCell {
+                    slot: LedSlot(1),
+                    effect: BuiltinEffect::Solid { color: GREEN },
+                    ttl_ms: NonZeroU32::new(50),
+                }),
+                &snapshot,
+            )
+            .unwrap();
+
+        let sampled = engine
+            .handle_command(120, StandardCommand::ReadOverlay { offset: 0 }, &snapshot)
+            .unwrap();
+        assert_eq!(sampled.invalidation, Invalidation::None);
+        let StandardReply::OverlayPage(page) = sampled.reply else {
+            panic!("expected overlay page")
+        };
+        assert_eq!(page.revision, 2);
+        assert_eq!(page.total, 2);
+        assert_eq!(page.cells.as_slice()[0].ttl_ms, None);
+        assert_eq!(page.cells.as_slice()[1].ttl_ms, NonZeroU32::new(30));
+
+        let pruned = engine
+            .handle_command(150, StandardCommand::ReadOverlay { offset: 0 }, &snapshot)
+            .unwrap();
+        assert_eq!(pruned.invalidation, Invalidation::Render);
+        let StandardReply::OverlayPage(page) = pruned.reply else {
+            panic!("expected overlay page")
+        };
+        assert_eq!(page.revision, 3);
+        assert_eq!(page.total, 1);
+        assert_eq!(page.cells.as_slice()[0].slot, LedSlot(0));
+    }
+
+    #[test]
+    fn compiled_scene_pages_preserve_layer_and_are_separate_from_runtime_scenes() {
+        let mut engine = scene_engine();
+        set_cell(&mut engine, 0, scene_cell(7, 1, GREEN));
+
+        let reply = engine
+            .handle_command(0, StandardCommand::ReadCompiledScenes { offset: 0 }, &context(0))
+            .unwrap()
+            .reply;
+        let StandardReply::CompiledScenesPage(page) = reply else {
+            panic!("expected compiled scene page")
+        };
+        assert_eq!(page.total, 1);
+        assert_eq!(page.policy, LayerPolicy::ActiveStack);
+        assert_eq!(page.cells.as_slice(), &[scene_cell(1, 0, RED)]);
+
+        let runtime = scenes_page(&mut engine, 0);
+        assert_eq!(runtime.total, 1);
+        assert_eq!(runtime.cells.as_slice(), &[scene_cell(7, 1, GREEN)]);
+
+        let mut empty: Engine = StandardLightingEngine::new(
+            BackgroundState::default(),
+            LayerScenes {
+                scenes: &[],
+                policy: LayerPolicy::ActiveStack,
+            },
+            EmptySource,
+            EmptySource,
+        );
+        let StandardReply::CompiledScenesPage(empty_page) = empty
+            .handle_command(0, StandardCommand::ReadCompiledScenes { offset: 0 }, &context(0))
+            .unwrap()
+            .reply
+        else {
+            panic!("expected compiled scene page")
+        };
+        assert_eq!(empty_page.total, 0);
+        assert_eq!(empty_page.policy, LayerPolicy::ActiveStack);
+        assert!(empty_page.cells.as_slice().is_empty());
+    }
+
     #[test]
     fn disabling_background_does_not_disable_layer_or_status_sources() {
         type StatusEngine = StandardLightingEngine<'static, EmptySource, SparseScene<'static, BuiltinEffect>, 2, 2>;
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index 8bdecb7f9..7a3da670d 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -32,7 +32,8 @@ use rynk::rmk_types::protocol::rynk::{
     UnsetLightingOverlayRequest, BuildInfo, AbortLightingSceneReplaceRequest, BeginLightingSceneReplaceRequest,
     CommitLightingSceneReplaceRequest, LightingScenePageRequest, LightingSceneStatus, LightingSceneTransaction,
     LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingSceneCellRequest,
-    UnsetLightingSceneCellRequest,
+    UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus, LightingCompiledScenesPage,
+    LightingOverlayPage, LightingOverlayPageRequest,
 };
 use rynk::{Client, Driver, LayoutInfo, RynkDevice, RynkHostError, TopicEvent};
 use wasm_bindgen::prelude::*;
@@ -161,6 +162,7 @@ endpoints! {
     set_behavior(config: BehaviorConfig) -> (),
     // status
     get_current_layer() -> u8,
+    get_layer_state() -> LayerState,
     get_matrix_state() -> MatrixState,
     get_battery_status() -> BatteryStatus,
     get_led_indicator() -> LedIndicator,
@@ -185,8 +187,11 @@ endpoints! {
     put_lighting_overlay_chunk(request: PutLightingOverlayChunkRequest) -> (),
     commit_lighting_overlay_replace(request: CommitLightingOverlayReplaceRequest) -> LightingState,
     abort_lighting_overlay_replace(request: AbortLightingOverlayReplaceRequest) -> (),
+    get_lighting_overlay(request: LightingOverlayPageRequest) -> LightingOverlayPage,
     get_lighting_scene_status() -> LightingSceneStatus,
     get_lighting_scenes(request: LightingScenePageRequest) -> LightingScenesPage,
+    get_lighting_compiled_scene_status() -> LightingCompiledSceneStatus,
+    get_lighting_compiled_scenes(request: LightingPageRequest) -> LightingCompiledScenesPage,
     set_lighting_scene_cell(request: SetLightingSceneCellRequest) -> LightingState,
     unset_lighting_scene_cell(request: UnsetLightingSceneCellRequest) -> LightingState,
     set_lighting_layer_policy(request: SetLightingLayerPolicyRequest) -> LightingState,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index e116b688c..31bef2981 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -33,7 +33,8 @@ use rmk_types::protocol::rynk::{
     SetLightingOverlayRequest, SetLightingStateRequest, SetMacroRequest, SetMorseBulkRequest, SetMorseRequest,
     StorageResetMode, UnsetLightingOverlayRequest, command, BuildInfo, LightingScenePageRequest, LightingSceneStatus,
     LightingSceneTransaction, LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest,
-    SetLightingSceneCellRequest, UnsetLightingSceneCellRequest,
+    SetLightingSceneCellRequest, UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus,
+    LightingCompiledScenesPage, LightingOverlayPage, LightingOverlayPageRequest,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -360,6 +361,11 @@ impl Client {
         self.request::<command::GetCurrentLayer>(&()).await
     }
 
+    /// Read the default layer and complete active-layer bitmap.
+    pub async fn get_layer_state(&self) -> Result<LayerState, RynkHostError> {
+        self.request::<command::GetLayerState>(&()).await
+    }
+
     /// Read the matrix state: a bitmap of which keys are physically pressed.
     pub async fn get_matrix_state(&self) -> Result<MatrixState, RynkHostError> {
         self.request::<command::GetMatrixState>(&()).await
@@ -524,6 +530,15 @@ impl Client {
         Self::flatten_lighting(self.request::<command::AbortLightingOverlayReplace>(&request).await?)
     }
 
+    /// Read one page of transient overlay cells, pinned to a state revision.
+    pub async fn get_lighting_overlay(
+        &self,
+        request: LightingOverlayPageRequest,
+    ) -> Result<LightingOverlayPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingOverlay)?;
+        Self::flatten_lighting(self.request::<command::GetLightingOverlay>(&request).await?)
+    }
+
     /// Read scene limits and occupancy. Scene support is discovered through
     /// [`LightingCapabilities::features`] (`LAYER_SCENES`) plus this endpoint;
     /// firmware without a scene table rejects it with `Unsupported`.
@@ -541,6 +556,21 @@ impl Client {
         Self::flatten_lighting(self.request::<command::GetLightingScenes>(&request).await?)
     }
 
+    /// Discover the immutable board-compiled scene source, including empty sources.
+    pub async fn get_lighting_compiled_scene_status(&self) -> Result<LightingCompiledSceneStatus, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingCompiledSceneStatus)?;
+        Self::flatten_lighting(self.request::<command::GetLightingCompiledSceneStatus>(&()).await?)
+    }
+
+    /// Read one topology-revision-pinned page of board-compiled scene cells.
+    pub async fn get_lighting_compiled_scenes(
+        &self,
+        request: LightingPageRequest,
+    ) -> Result<LightingCompiledScenesPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingCompiledScenes)?;
+        Self::flatten_lighting(self.request::<command::GetLightingCompiledScenes>(&request).await?)
+    }
+
     /// Insert or update one durable scene cell when the revision matches.
     pub async fn set_lighting_scene_cell(
         &self,
@@ -702,6 +732,136 @@ impl Client {
         .await
     }
 
+    /// Read the whole transient overlay under one state revision. Expiry or a
+    /// concurrent mutation restarts the snapshot, bounded to a few attempts.
+    pub async fn read_all_lighting_overlay(
+        &self,
+    ) -> Result<(u32, Vec<rmk_types::protocol::rynk::LightingOverlayCell>), RynkHostError> {
+        const ATTEMPTS: usize = 4;
+        let mut last_error = None;
+        for _ in 0..ATTEMPTS {
+            let state = self.get_lighting_state().await?;
+            let mut cells = Vec::new();
+            let mut offset: u16 = 0;
+            let mut first_page = true;
+            let mut conflicted = false;
+            while first_page || offset < state.overlay_len {
+                first_page = false;
+                match self
+                    .get_lighting_overlay(LightingOverlayPageRequest {
+                        revision: state.revision,
+                        offset,
+                    })
+                    .await
+                {
+                    Ok(page) => {
+                        if page.revision != state.revision || page.total_count != state.overlay_len {
+                            return Err(RynkHostError::InconsistentResponse {
+                                cmd: Cmd::GetLightingOverlay,
+                                reason: "page revision/count disagrees with the pinned state",
+                            });
+                        }
+                        if offset >= state.overlay_len {
+                            if !page.items.is_empty() {
+                                return Err(RynkHostError::InconsistentResponse {
+                                    cmd: Cmd::GetLightingOverlay,
+                                    reason: "empty snapshot returned unexpected cells",
+                                });
+                            }
+                            break;
+                        }
+                        if page.items.is_empty() || offset as usize + page.items.len() > state.overlay_len as usize {
+                            return Err(RynkHostError::InconsistentResponse {
+                                cmd: Cmd::GetLightingOverlay,
+                                reason: "page is empty or extends beyond the advertised count",
+                            });
+                        }
+                        offset += page.items.len() as u16;
+                        cells.extend(page.items.iter().copied());
+                    }
+                    Err(
+                        error @ RynkHostError::LightingRejected(
+                            rmk_types::protocol::rynk::LightingError::StateRevisionConflict { .. },
+                        ),
+                    ) => {
+                        last_error = Some(error);
+                        conflicted = true;
+                        break;
+                    }
+                    Err(error) => return Err(error),
+                }
+            }
+            if !conflicted {
+                if cells.len() != state.overlay_len as usize {
+                    return Err(RynkHostError::InconsistentResponse {
+                        cmd: Cmd::GetLightingOverlay,
+                        reason: "pagination ended before the advertised count",
+                    });
+                }
+                return Ok((state.revision, cells));
+            }
+        }
+        Err(last_error.expect("a retried read only exits with a recorded conflict"))
+    }
+
+    /// Read every immutable board-compiled scene cell under one topology revision.
+    pub async fn read_all_lighting_compiled_scenes(
+        &self,
+    ) -> Result<
+        (
+            LightingCompiledSceneStatus,
+            Vec<rmk_types::protocol::rynk::LightingSceneCell>,
+        ),
+        RynkHostError,
+    > {
+        let status = self.get_lighting_compiled_scene_status().await?;
+        let mut cells = Vec::new();
+        let mut offset: u16 = 0;
+        let mut first_page = true;
+        while first_page || offset < status.scene_len {
+            first_page = false;
+            let page = self
+                .get_lighting_compiled_scenes(LightingPageRequest {
+                    topology_revision: status.topology_revision,
+                    offset,
+                })
+                .await?;
+            if page.topology_revision != status.topology_revision || page.total_count != status.scene_len {
+                return Err(RynkHostError::InconsistentResponse {
+                    cmd: Cmd::GetLightingCompiledScenes,
+                    reason: "page topology revision/count disagrees with status",
+                });
+            }
+            if offset >= status.scene_len {
+                if !page.items.is_empty() {
+                    return Err(RynkHostError::InconsistentResponse {
+                        cmd: Cmd::GetLightingCompiledScenes,
+                        reason: "empty compiled source returned unexpected cells",
+                    });
+                }
+                break;
+            }
+            if page.items.is_empty()
+                || page.items.len() > status.chunk_capacity as usize
+                || offset as usize + page.items.len() > status.scene_len as usize
+            {
+                return Err(RynkHostError::InconsistentResponse {
+                    cmd: Cmd::GetLightingCompiledScenes,
+                    reason: "page is empty, oversized, or extends beyond the advertised count",
+                });
+            }
+            offset += page.items.len() as u16;
+            cells.extend(page.items.iter().copied());
+        }
+        if cells.len() != status.scene_len as usize {
+            return Err(RynkHostError::InconsistentResponse {
+                cmd: Cmd::GetLightingCompiledScenes,
+                reason: "pagination ended before the advertised count",
+            });
+        }
+        Ok((status, cells))
+    }
+
     /// Read the whole stored scene table by paging `GetLightingScenes` under
     /// one pinned revision. A concurrent lighting mutation invalidates the
     /// pin; the read restarts from a fresh status, bounded by a few attempts.
diff --git a/rynk/src/driver.rs b/rynk/src/driver.rs
index e0ff6cd6a..da9a691b5 100644
--- a/rynk/src/driver.rs
+++ b/rynk/src/driver.rs
@@ -103,6 +103,11 @@ pub enum RynkHostError {
     Layout(String),
     #[error("response for {cmd:?} had trailing bytes")]
     TrailingBytes { cmd: Cmd },
+    /// A typed response decoded successfully but its pagination metadata was
+    /// internally inconsistent, so returning a partial snapshot would be
+    /// unsafe.
+    #[error("inconsistent response for {cmd:?}: {reason}")]
+    InconsistentResponse { cmd: Cmd, reason: &'static str },
     #[error("response cmd mismatch: sent {sent:?}, got {got:?}")]
     CmdMismatch { sent: Cmd, got: Cmd },
     /// The device's capabilities lack this command, so nothing was sent.
@@ -127,6 +132,7 @@ impl From<RynkHostError> for wasm_bindgen::JsValue {
             RynkHostError::Deserialize { .. } => "ResponseDecodeError",
             RynkHostError::Layout(_) => "LayoutDecodeError",
             RynkHostError::TrailingBytes { .. } => "ResponseTrailingBytes",
+            RynkHostError::InconsistentResponse { .. } => "InconsistentResponse",
             RynkHostError::CmdMismatch { .. } => "ResponseCommandMismatch",
         };
         let err = js_sys::Error::new(&e.to_string());
diff --git a/rynk/tests/loopback.rs b/rynk/tests/loopback.rs
index 51e7ae17c..f2a81accd 100644
--- a/rynk/tests/loopback.rs
+++ b/rynk/tests/loopback.rs
@@ -141,6 +141,11 @@ async fn client_against_run_session() {
             matches!(ev, TopicEvent::LayerChange(1)),
             "expected LayerChange(1), got {ev:?}"
         );
+        let ev = client.next_topic().await;
+        assert!(
+            matches!(ev, TopicEvent::LayerChange(1)),
+            "default-layer changes publish LayerChange, got {ev:?}"
+        );
 
         // Round-trip representative remaining domains.
         client.set_key(0, 1, 1, KeyAction::Morse(2)).await.unwrap();

From e4a4d767527941a800ef0647f25f82ea7d1082b7 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 03:17:26 -0700
Subject: [PATCH 19/78] feat(lighting): support board snapshot invalidation

---
 rmk/src/event/state.rs        |  2 +-
 rmk/src/lighting/mod.rs       |  6 ++++-
 rmk/src/lighting/processor.rs | 51 ++++++++++++++++++++++++++++++-----
 3 files changed, 50 insertions(+), 9 deletions(-)

diff --git a/rmk/src/event/state.rs b/rmk/src/event/state.rs
index 8bf34389e..5d3bf1851 100644
--- a/rmk/src/event/state.rs
+++ b/rmk/src/event/state.rs
@@ -59,7 +59,7 @@ impl SleepStateEvent {
 
 impl_payload_wrapper!(SleepStateEvent, bool);
 
-/// Authoritative lighting state changed.
+/// Authoritative lighting state or application-owned render context changed.
 ///
 /// This is deliberately a unit invalidation: consumers read a fresh state
 /// snapshot from the lighting controller instead of trusting an event mirror.
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index d180835ef..91b3b2941 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -52,7 +52,11 @@ pub use topology::*;
 /// notifications may be coalesced, but brightness/toggle/mode presses may not.
 static LIGHT_ACTIONS: Channel<RawMutex, LightAction, 4> = Channel::new();
 
-pub(crate) async fn send_light_action(action: LightAction) {
+/// Deliver a lighting action to the active lighting processor.
+///
+/// This is public so board-specific user actions can reuse the same ordered,
+/// lossless path as keymap-native lighting actions.
+pub async fn send_light_action(action: LightAction) {
     LIGHT_ACTIONS.send(action).await;
 }
 
diff --git a/rmk/src/lighting/processor.rs b/rmk/src/lighting/processor.rs
index 2bbf649c8..0581a5389 100644
--- a/rmk/src/lighting/processor.rs
+++ b/rmk/src/lighting/processor.rs
@@ -3,7 +3,7 @@
 use core::cell::Cell;
 use core::num::NonZeroU32;
 
-use embassy_futures::select::{Either, Either3, Either4, select, select3, select4};
+use embassy_futures::select::{Either3, Either4, select3, select4};
 use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
 use embassy_sync::channel::Channel;
 use embassy_sync::mutex::Mutex;
@@ -28,6 +28,7 @@ pub struct LightingMailbox<Command, Reply, Error, const CAPACITY: usize> {
     requests: Channel<RawMutex, MailboxRequest<Command>, CAPACITY>,
     response: Signal<RawMutex, MailboxResponse<Reply, Error>>,
     retry_output: Signal<RawMutex, ()>,
+    snapshot_changed: Signal<RawMutex, ()>,
     caller: Mutex<RawMutex, ()>,
     next_id: BlockingMutex<RawMutex, Cell<u32>>,
 }
@@ -48,6 +49,7 @@ impl<Command, Reply, Error, const CAPACITY: usize> LightingMailbox<Command, Repl
             requests: Channel::new(),
             response: Signal::new(),
             retry_output: Signal::new(),
+            snapshot_changed: Signal::new(),
             caller: Mutex::new(()),
             next_id: BlockingMutex::new(Cell::new(0)),
         }
@@ -75,6 +77,15 @@ impl<Command, Reply, Error, const CAPACITY: usize> LightingMailbox<Command, Repl
         self.retry_output.signal(());
     }
 
+    /// Coalescing invalidation for application-owned snapshot fields.
+    ///
+    /// Boards use this after changing context outside the standard RMK
+    /// layer/indicator snapshots (for example battery or sensor state). The
+    /// processor takes a fresh snapshot, rerenders, and notifies replicas.
+    pub fn snapshot_changed(&self) {
+        self.snapshot_changed.signal(());
+    }
+
     /// Service side: receive the next command. Normally only
     /// [`LightingProcessor`] drives this; it is public for board-specific
     /// executors and deterministic tests.
@@ -279,39 +290,55 @@ where
                         Timer::at(Instant::from_millis(deadline)),
                         subscriber.next_event(),
                         self.mailbox.receive(),
-                        select(self.mailbox.retry_output.wait(), super::next_light_action()),
+                        select3(
+                            self.mailbox.retry_output.wait(),
+                            super::next_light_action(),
+                            self.mailbox.snapshot_changed.wait(),
+                        ),
                     )
                     .await
                     {
                         Either4::First(_) => {}
                         Either4::Second(event) => self.process(event).await,
                         Either4::Third(request) => self.handle_mailbox_command(request).await,
-                        Either4::Fourth(Either::First(())) => {
+                        Either4::Fourth(Either3::First(())) => {
                             let _ = self.service.retry_output_now();
                         }
-                        Either4::Fourth(Either::Second(action)) => {
+                        Either4::Fourth(Either3::Second(action)) => {
                             let _ = self.service.on_input(E::Input::from(action));
                             self.publish_pending_lighting_change();
                         }
+                        Either4::Fourth(Either3::Third(())) => {
+                            self.service.request_render();
+                            publish_event(LightingChangedEvent::new());
+                        }
                     }
                 }
                 None => {
                     match select3(
                         subscriber.next_event(),
                         self.mailbox.receive(),
-                        select(self.mailbox.retry_output.wait(), super::next_light_action()),
+                        select3(
+                            self.mailbox.retry_output.wait(),
+                            super::next_light_action(),
+                            self.mailbox.snapshot_changed.wait(),
+                        ),
                     )
                     .await
                     {
                         Either3::First(event) => self.process(event).await,
                         Either3::Second(request) => self.handle_mailbox_command(request).await,
-                        Either3::Third(Either::First(())) => {
+                        Either3::Third(Either3::First(())) => {
                             let _ = self.service.retry_output_now();
                         }
-                        Either3::Third(Either::Second(action)) => {
+                        Either3::Third(Either3::Second(action)) => {
                             let _ = self.service.on_input(E::Input::from(action));
                             self.publish_pending_lighting_change();
                         }
+                        Either3::Third(Either3::Third(())) => {
+                            self.service.request_render();
+                            publish_event(LightingChangedEvent::new());
+                        }
                     }
                 }
             }
@@ -347,6 +374,16 @@ mod tests {
         assert_eq!(reply, Err(9));
     }
 
+    #[test]
+    fn snapshot_change_notifications_coalesce() {
+        let mailbox = LightingMailbox::<(), (), (), 1>::new();
+        mailbox.snapshot_changed();
+        mailbox.snapshot_changed();
+
+        assert_eq!(mailbox.snapshot_changed.try_take(), Some(()));
+        assert_eq!(mailbox.snapshot_changed.try_take(), None);
+    }
+
     #[test]
     fn cancelled_request_reply_cannot_poison_the_next_caller() {
         use embassy_futures::select::{Either, select};

From 8a6aad7a8b12b23fb519d1f7e3bf3afa5469ac36 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 04:31:26 -0700
Subject: [PATCH 20/78] feat(rynk): expose resolved modifier state

---
 .../main/docs/development/rynk_protocol.md    | 20 ++++----
 .../default_config/subscriber_default.toml    |  2 +
 rmk-types/src/protocol/rynk/command.rs        |  5 ++
 rmk-types/src/protocol/rynk/tests.rs          | 17 +++++++
 rmk/src/event/input.rs                        |  6 ++-
 rmk/src/host/rynk/handlers/status.rs          |  9 +++-
 rmk/src/host/rynk/mod.rs                      |  1 +
 rmk/src/host/rynk/topics.rs                   | 27 +++++++++-
 rmk/src/keyboard.rs                           | 37 +++++++-------
 rmk/src/split/peripheral.rs                   | 10 ++--
 rmk/src/state.rs                              | 49 ++++++++++++++++++-
 rynk/rynk-wasm/src/client.rs                  |  2 +
 rynk/src/api.rs                               |  6 +++
 13 files changed, 152 insertions(+), 39 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index b61642005..0612e2570 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -262,6 +262,7 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x0806` | `GetSleepState`                  | `()`                                  | `bool`                              |            | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                               |
 | `0x0807` | `GetLedIndicator`                | `()`                                  | `LedIndicator`                      |            | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                   |
 | `0x0808` | `GetLayerState`                  | `()`                                  | `LayerState`                        |            | Default layer and complete active-layer bitmap.                                                                                |
+| `0x0809` | `GetModifierState`               | `()`                                  | `ModifierCombination`               |            | Final resolved modifier bitmap used by the HID keyboard report.                                                                |
 | `0x0901` | `GetLightingCapabilities`        | `()`                                  | `LightingCapabilitiesResult`        | `lighting` |                                                                                                                                |
 | `0x0902` | `GetLightingState`               | `()`                                  | `LightingStateResult`               | `lighting` |                                                                                                                                |
 | `0x0903` | `SetLightingState`               | `SetLightingStateRequest`             | `LightingStateResult`               | `lighting` |                                                                                                                                |
@@ -296,15 +297,16 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 
 Topics are best-effort pushes; the `Get*` endpoints above mirror their payloads so a host can recover a missed push.
 
-| CMD      | Name                  | Payload            | Feature    | Notes |
-| -------- | --------------------- | ------------------ | ---------- | ----- |
-| `0x8001` | `LayerChange`         | `u8`               |            |       |
-| `0x8002` | `WpmUpdate`           | `u16`              |            |       |
-| `0x8003` | `ConnectionChange`    | `ConnectionStatus` |            |       |
-| `0x8004` | `SleepState`          | `bool`             |            |       |
-| `0x8005` | `LedIndicatorChange`  | `LedIndicator`     |            |       |
-| `0x8006` | `BatteryStatusChange` | `BatteryStatus`    | `_ble`     |       |
-| `0x8007` | `LightingChange`      | `LightingChanged`  | `lighting` |       |
+| CMD      | Name                  | Payload               | Feature    | Notes                                   |
+| -------- | --------------------- | --------------------- | ---------- | --------------------------------------- |
+| `0x8001` | `LayerChange`         | `u8`                  |            |                                         |
+| `0x8002` | `WpmUpdate`           | `u16`                 |            |                                         |
+| `0x8003` | `ConnectionChange`    | `ConnectionStatus`    |            |                                         |
+| `0x8004` | `SleepState`          | `bool`                |            |                                         |
+| `0x8005` | `LedIndicatorChange`  | `LedIndicator`        |            |                                         |
+| `0x8006` | `BatteryStatusChange` | `BatteryStatus`       | `_ble`     |                                         |
+| `0x8007` | `LightingChange`      | `LightingChanged`     | `lighting` |                                         |
+| `0x8008` | `ModifierChange`      | `ModifierCombination` |            | Final resolved modifier bitmap changed. |
 
 ## Compatibility
 
diff --git a/rmk-config/src/default_config/subscriber_default.toml b/rmk-config/src/default_config/subscriber_default.toml
index 857aabaff..0785ff509 100644
--- a/rmk-config/src/default_config/subscriber_default.toml
+++ b/rmk-config/src/default_config/subscriber_default.toml
@@ -66,6 +66,7 @@ events = [
     { name = "connection_status_change" },
     { name = "sleep_state" },
     { name = "led_indicator" },
+    { name = "modifier" },
 ]
 
 [[subscriber]]
@@ -86,6 +87,7 @@ events = [
     { name = "connection_status_change" },
     { name = "sleep_state" },
     { name = "led_indicator" },
+    { name = "modifier" },
 ]
 
 [[subscriber]]
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 8f96ea1b6..db6a1bf83 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -29,6 +29,7 @@ use crate::combo::Combo;
 use crate::connection::{ConnectionStatus, ConnectionType};
 use crate::fork::Fork;
 use crate::led_indicator::LedIndicator;
+use crate::modifier::ModifierCombination;
 use crate::morse::Morse;
 #[cfg(feature = "split")]
 use crate::protocol::rynk::PeripheralStatus;
@@ -356,6 +357,8 @@ endpoints! {
     GetLedIndicator = 0x0807: () => LedIndicator;
     /// Default layer and complete active-layer bitmap.
     GetLayerState = 0x0808: () => LayerState;
+    /// Final resolved modifier bitmap used by the HID keyboard report.
+    GetModifierState = 0x0809: () => ModifierCombination;
 
     // Lighting (0x09xx). Lighting-domain errors are nested inside Rynk's
     // outer protocol result so hosts retain precise rejection reasons.
@@ -438,6 +441,8 @@ topics! {
     BatteryStatusChange = 0x8006: BatteryStatus;
     #[cfg(feature = "lighting")]
     LightingChange = 0x8007: LightingChanged;
+    // Final resolved modifier bitmap changed.
+    ModifierChange = 0x8008: ModifierCombination;
 }
 
 /// The payload budget advertised to hosts must cover the largest payload
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 48a87fda8..afb8f5cff 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -619,6 +619,7 @@ fn wire_frames_locked() {
         default_layer: 2,
         active_bitmap: [0x05, 0, 0, 0, 0, 0, 0, 0x80],
     };
+    let modifiers = ModifierCombination::LSHIFT | ModifierCombination::RALT;
 
     let entries: alloc::vec::Vec<(&str, alloc::vec::Vec<u8>)> = alloc::vec![
         // System (0x00xx).
@@ -948,6 +949,18 @@ fn wire_frames_locked() {
             "GetLayerState reply Ok(LayerState{default:2,active:[0x05,..,0x80]})",
             encode_frame(Cmd::GetLayerState, SEQ, &Ok::<LayerState, RynkError>(layer_state)),
         ),
+        (
+            "GetModifierState request ()",
+            encode_frame(Cmd::GetModifierState, SEQ, &())
+        ),
+        (
+            "GetModifierState reply Ok(ModifierCombination(LShift|RAlt))",
+            encode_frame(
+                Cmd::GetModifierState,
+                SEQ,
+                &Ok::<ModifierCombination, RynkError>(modifiers),
+            ),
+        ),
         // Topics (0x80xx, server→host push, SEQ 0).
         ("LayerChange topic 3", encode_frame(Cmd::LayerChange, 0, &3u8)),
         ("WpmUpdate topic 42", encode_frame(Cmd::WpmUpdate, 0, &42u16)),
@@ -960,6 +973,10 @@ fn wire_frames_locked() {
             "LedIndicatorChange topic LedIndicator(Num|Scroll)",
             encode_frame(Cmd::LedIndicatorChange, 0, &led)
         ),
+        (
+            "ModifierChange topic ModifierCombination(LShift|RAlt)",
+            encode_frame(Cmd::ModifierChange, 0, &modifiers),
+        ),
     ];
     let view: alloc::vec::Vec<(&str, &[u8])> = entries.iter().map(|(l, b)| (*l, b.as_slice())).collect();
 
diff --git a/rmk/src/event/input.rs b/rmk/src/event/input.rs
index 6d3a5a21f..16575e742 100644
--- a/rmk/src/event/input.rs
+++ b/rmk/src/event/input.rs
@@ -90,7 +90,11 @@ pub struct RotaryEncoderPos {
 // Modifier Events
 // ============================================================================
 
-/// Modifier keys combination changed event
+/// Final resolved HID modifier combination changed event.
+///
+/// This carries the modifier byte used by the keyboard report, including
+/// one-shot, macro, with-modifier, and fork effects. It is not merely the set
+/// of physically held modifier keys.
 #[event(channel_size = crate::MODIFIER_EVENT_CHANNEL_SIZE, pubs = crate::MODIFIER_EVENT_PUB_SIZE, subs = crate::MODIFIER_EVENT_SUB_SIZE)]
 #[derive(Clone, Copy, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
diff --git a/rmk/src/host/rynk/handlers/status.rs b/rmk/src/host/rynk/handlers/status.rs
index 2dc8967c7..8080a3128 100644
--- a/rmk/src/host/rynk/handlers/status.rs
+++ b/rmk/src/host/rynk/handlers/status.rs
@@ -5,6 +5,7 @@
 #[cfg(feature = "_ble")]
 use rmk_types::battery::BatteryStatus;
 use rmk_types::led_indicator::LedIndicator;
+use rmk_types::modifier::ModifierCombination;
 #[cfg(feature = "split")]
 use rmk_types::protocol::rynk::PeripheralStatus;
 #[cfg(feature = "_ble")]
@@ -12,7 +13,7 @@ use rmk_types::protocol::rynk::command::GetBatteryStatus;
 #[cfg(feature = "split")]
 use rmk_types::protocol::rynk::command::GetPeripheralStatus;
 use rmk_types::protocol::rynk::command::{
-    GetCurrentLayer, GetLayerState, GetLedIndicator, GetMatrixState, GetSleepState, GetWpm,
+    GetCurrentLayer, GetLayerState, GetLedIndicator, GetMatrixState, GetModifierState, GetSleepState, GetWpm,
 };
 use rmk_types::protocol::rynk::{LayerState, MATRIX_BITMAP_SIZE, MatrixState, RynkError};
 
@@ -31,6 +32,12 @@ impl Handle<GetLayerState> for RynkService<'_> {
     }
 }
 
+impl Handle<GetModifierState> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<ModifierCombination, RynkError> {
+        Ok(crate::state::current_modifier_state())
+    }
+}
+
 impl Handle<GetMatrixState> for RynkService<'_> {
     async fn handle(&self, _: ()) -> Result<MatrixState, RynkError> {
         // Sized for the maximum supported matrix — host slices it down
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index baa4a13c1..1c50f6118 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -250,6 +250,7 @@ impl<'a> RynkService<'a> {
             Cmd::GetSleepState => serve::<command::GetSleepState, _>(self, msg).await,
             Cmd::GetLedIndicator => serve::<command::GetLedIndicator, _>(self, msg).await,
             Cmd::GetLayerState => serve::<command::GetLayerState, _>(self, msg).await,
+            Cmd::GetModifierState => serve::<command::GetModifierState, _>(self, msg).await,
 
             Cmd::GetLayout => serve::<command::GetLayout, _>(self, msg).await,
 
diff --git a/rmk/src/host/rynk/topics.rs b/rmk/src/host/rynk/topics.rs
index 499c294c0..454564b1b 100644
--- a/rmk/src/host/rynk/topics.rs
+++ b/rmk/src/host/rynk/topics.rs
@@ -13,7 +13,7 @@ use crate::event::BatteryStatusEvent;
 #[cfg(feature = "lighting")]
 use crate::event::LightingChangedEvent;
 use crate::event::{
-    ConnectionStatusChangeEvent, EventSubscriber, LayerChangeEvent, LedIndicatorEvent, SleepStateEvent,
+    ConnectionStatusChangeEvent, EventSubscriber, LayerChangeEvent, LedIndicatorEvent, ModifierEvent, SleepStateEvent,
     SubscribableEvent, WpmUpdateEvent,
 };
 
@@ -23,6 +23,7 @@ pub(super) struct TopicSubscribers {
     conn: <ConnectionStatusChangeEvent as SubscribableEvent>::Subscriber,
     sleep: <SleepStateEvent as SubscribableEvent>::Subscriber,
     led: <LedIndicatorEvent as SubscribableEvent>::Subscriber,
+    modifier: <ModifierEvent as SubscribableEvent>::Subscriber,
     #[cfg(feature = "_ble")]
     battery: <BatteryStatusEvent as SubscribableEvent>::Subscriber,
     #[cfg(feature = "lighting")]
@@ -37,6 +38,7 @@ impl TopicSubscribers {
             conn: ConnectionStatusChangeEvent::subscriber(),
             sleep: SleepStateEvent::subscriber(),
             led: LedIndicatorEvent::subscriber(),
+            modifier: ModifierEvent::subscriber(),
             #[cfg(feature = "_ble")]
             battery: BatteryStatusEvent::subscriber(),
             #[cfg(feature = "lighting")]
@@ -54,8 +56,31 @@ impl TopicSubscribers {
             e = self.conn.next_event().fuse() => TopicEvent::ConnectionChange(*e),
             e = self.sleep.next_event().fuse() => TopicEvent::SleepState(*e),
             e = self.led.next_event().fuse() => TopicEvent::LedIndicatorChange(*e),
+            e = self.modifier.next_event().fuse() => TopicEvent::ModifierChange(e.modifier),
             with_feature("_ble"): e = self.battery.next_event().fuse() => TopicEvent::BatteryStatusChange(*e),
             with_feature("lighting"): _ = self.lighting.next_event().fuse() => TopicEvent::LightingChange(rmk_types::protocol::rynk::LightingChanged),
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use rmk_types::modifier::ModifierCombination;
+
+    use super::*;
+    use crate::event::{ModifierEvent, publish_event};
+    use crate::test_support::test_block_on as block_on;
+
+    #[test]
+    fn resolved_modifier_events_are_forwarded() {
+        let mut topics = TopicSubscribers::new();
+        let modifiers = ModifierCombination::LSHIFT | ModifierCombination::RALT;
+
+        publish_event(ModifierEvent { modifier: modifiers });
+
+        match block_on(topics.next_event()) {
+            TopicEvent::ModifierChange(actual) => assert_eq!(actual, modifiers),
+            other => panic!("expected ModifierChange, got {:?}", other.cmd()),
+        }
+    }
+}
diff --git a/rmk/src/keyboard.rs b/rmk/src/keyboard.rs
index 814357097..a13f2ae1b 100644
--- a/rmk/src/keyboard.rs
+++ b/rmk/src/keyboard.rs
@@ -20,11 +20,9 @@ use usbd_hid::descriptor::{MediaKeyboardReport, SystemControlReport};
 use crate::ble::sleep::report_activity;
 use crate::channel::send_hid_report;
 use crate::core_traits::Runnable;
+use crate::event::{ActionEvent, KeyboardEvent, KeyboardEventPos, SubscribableEvent, publish_event_async};
 #[cfg(all(feature = "split", feature = "_ble"))]
-use crate::event::ClearPeerEvent;
-use crate::event::{
-    ActionEvent, KeyboardEvent, KeyboardEventPos, ModifierEvent, SubscribableEvent, publish_event, publish_event_async,
-};
+use crate::event::{ClearPeerEvent, publish_event};
 use crate::hid::{KeyboardReport, Report};
 use crate::keyboard::combo::Combo;
 use crate::keyboard::fork::ActiveFork;
@@ -1857,6 +1855,7 @@ impl<'a> Keyboard<'a> {
     pub(crate) async fn send_keyboard_report_with_resolved_modifiers(&mut self, pressed: bool) {
         // all modifier related effects are combined here to be sent with the hid report:
         let modifiers = self.resolve_modifiers(pressed);
+        crate::state::set_modifier_state(modifiers);
         info!(
             "Sending keyboard report, modifiers: {:?}, keycodes: {:?}",
             modifiers, &self.held_keycodes,
@@ -1967,10 +1966,6 @@ impl<'a> Keyboard<'a> {
     fn register_modifier_key(&mut self, key: HidKeyCode) {
         self.held_modifiers |= key.to_hid_modifiers();
 
-        publish_event(ModifierEvent {
-            modifier: self.held_modifiers,
-        });
-
         // if a modifier key arrives after fork activation, it should be kept
         self.fork_keep_mask |= key.to_hid_modifiers();
     }
@@ -1978,20 +1973,12 @@ impl<'a> Keyboard<'a> {
     /// Unregister a modifier from hid report.
     fn unregister_modifier_key(&mut self, key: HidKeyCode) {
         self.held_modifiers &= !key.to_hid_modifiers();
-
-        publish_event(ModifierEvent {
-            modifier: self.held_modifiers,
-        });
     }
 
     /// Register a modifier combination to be sent in hid report.
     fn register_modifiers(&mut self, modifiers: ModifierCombination) {
         self.held_modifiers |= modifiers;
 
-        publish_event(ModifierEvent {
-            modifier: self.held_modifiers,
-        });
-
         // if a modifier key arrives after fork activation, it should be kept
         self.fork_keep_mask |= modifiers;
     }
@@ -1999,10 +1986,6 @@ impl<'a> Keyboard<'a> {
     /// Unregister a modifier combination from hid report.
     fn unregister_modifiers(&mut self, modifiers: ModifierCombination) {
         self.held_modifiers &= !modifiers;
-
-        publish_event(ModifierEvent {
-            modifier: self.held_modifiers,
-        });
     }
 }
 
@@ -2104,6 +2087,20 @@ mod test {
         create_test_keyboard_with_config(BehaviorConfig::default())
     }
 
+    #[test]
+    fn keyboard_report_snapshots_final_resolved_modifiers() {
+        let mut keyboard = create_test_keyboard();
+        keyboard.with_modifiers = ModifierCombination::LSHIFT | ModifierCombination::RALT;
+        crate::state::set_modifier_state(ModifierCombination::new());
+
+        block_on(keyboard.send_keyboard_report_with_resolved_modifiers(true));
+
+        assert_eq!(
+            crate::state::current_modifier_state(),
+            ModifierCombination::LSHIFT | ModifierCombination::RALT,
+        );
+    }
+
     async fn force_timeout_first_hold(keyboard: &mut Keyboard<'static>) {
         let key = keyboard.next_buffered_key().unwrap();
         keyboard.process_buffered_key(key).await;
diff --git a/rmk/src/split/peripheral.rs b/rmk/src/split/peripheral.rs
index 9a839617b..111516440 100644
--- a/rmk/src/split/peripheral.rs
+++ b/rmk/src/split/peripheral.rs
@@ -17,11 +17,11 @@ use super::SplitMessage;
 use super::driver::{SplitReader, SplitWriter};
 #[cfg(feature = "_render_state")]
 use crate::event::SleepStateEvent;
+#[cfg(feature = "display")]
+use crate::event::WpmUpdateEvent;
 use crate::event::{
     KeyboardEvent, LayerChangeEvent, LedIndicatorEvent, PointingEvent, SubscribableEvent, publish_event,
 };
-#[cfg(feature = "display")]
-use crate::event::{ModifierEvent, WpmUpdateEvent};
 #[cfg(not(feature = "_ble"))]
 use crate::split::serial::SerialSplitDriver;
 use crate::state::update_status;
@@ -195,9 +195,9 @@ impl<S: SplitWriter + SplitReader> SplitPeripheral<S> {
                             SplitMessage::Wpm(wpm) => publish_event(WpmUpdateEvent::new(wpm)),
                             #[cfg(feature = "display")]
                             SplitMessage::Modifier(bits) => {
-                                publish_event(ModifierEvent {
-                                    modifier: rmk_types::modifier::ModifierCombination::from_bits(bits),
-                                });
+                                crate::state::set_modifier_state(rmk_types::modifier::ModifierCombination::from_bits(
+                                    bits,
+                                ));
                             }
                             #[cfg(feature = "_render_state")]
                             SplitMessage::SleepState(sleeping) => {
diff --git a/rmk/src/state.rs b/rmk/src/state.rs
index 02cb64af0..d085839dd 100644
--- a/rmk/src/state.rs
+++ b/rmk/src/state.rs
@@ -5,10 +5,33 @@ use rmk_types::ble::BleState;
 #[cfg(feature = "_ble")]
 use rmk_types::ble::BleStatus;
 use rmk_types::connection::{ConnectionStatus, ConnectionType, UsbState};
+use rmk_types::modifier::ModifierCombination;
 
 use crate::RawMutex;
 use crate::event::{ConnectionStatusChangeEvent, publish_event};
 
+/// Final modifier bitmap used by the most recently resolved keyboard report.
+///
+/// This is intentionally distinct from `Keyboard::held_modifiers`: one-shot,
+/// macro, with-modifier, and fork processing all contribute to the value that
+/// is actually sent to the host.
+static MODIFIER_STATE: Mutex<RawMutex, Cell<ModifierCombination>> = Mutex::new(Cell::new(ModifierCombination::new()));
+
+pub(crate) fn current_modifier_state() -> ModifierCombination {
+    MODIFIER_STATE.lock(Cell::get)
+}
+
+pub(crate) fn set_modifier_state(modifiers: ModifierCombination) {
+    let changed = MODIFIER_STATE.lock(|state| {
+        let changed = state.get() != modifiers;
+        state.set(modifiers);
+        changed
+    });
+    if changed {
+        publish_event(crate::event::ModifierEvent { modifier: modifiers });
+    }
+}
+
 /// Authoritative device sleep state shared by display, lighting, host
 /// readback, battery management, and split forwarding. Events invalidate this
 /// value; they are not a second owner of it.
@@ -157,11 +180,13 @@ mod tests {
 
     use embassy_futures::select::{Either, select};
     use embassy_time::{Duration, Timer};
+    use rmk_types::modifier::ModifierCombination;
 
     use super::{
-        CONNECTION_STATUS, ConnectionStatus, ConnectionType, UsbState, set_preferred_connection, set_usb_state,
+        CONNECTION_STATUS, ConnectionStatus, ConnectionType, MODIFIER_STATE, UsbState, current_modifier_state,
+        set_modifier_state, set_preferred_connection, set_usb_state,
     };
-    use crate::event::{ConnectionStatusChangeEvent, EventSubscriber, SubscribableEvent};
+    use crate::event::{ConnectionStatusChangeEvent, EventSubscriber, ModifierEvent, SubscribableEvent};
     use crate::hid::{KeyboardReport, Report};
     use crate::test_support::test_block_on as block_on;
 
@@ -172,12 +197,32 @@ mod tests {
 
     fn reset_state() {
         CONNECTION_STATUS.lock(|c| c.set(ConnectionStatus::default()));
+        MODIFIER_STATE.lock(|state| state.set(ModifierCombination::new()));
         #[cfg(not(feature = "_no_usb"))]
         crate::channel::USB_REPORT_CHANNEL.clear();
         #[cfg(feature = "_ble")]
         crate::channel::BLE_REPORT_CHANNEL.clear();
     }
 
+    #[test]
+    fn resolved_modifier_state_is_snapshotted_and_published_once() {
+        let _guard = state_test_lock().lock().unwrap();
+        reset_state();
+        let mut sub = ModifierEvent::subscriber();
+        let modifiers = ModifierCombination::LSHIFT | ModifierCombination::RALT;
+
+        set_modifier_state(modifiers);
+
+        assert_eq!(current_modifier_state(), modifiers);
+        assert_eq!(block_on(sub.next_event()).modifier, modifiers);
+
+        set_modifier_state(modifiers);
+        match block_on(select(Timer::after(Duration::from_millis(1)), sub.next_event())) {
+            Either::First(_) => {}
+            Either::Second(event) => panic!("unexpected modifier event: {:?}", event),
+        }
+    }
+
     fn pressed_keyboard_report() -> Report {
         Report::KeyboardReport(KeyboardReport {
             modifier: 0x02,
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index 7a3da670d..c7183f400 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -21,6 +21,7 @@ use rynk::rmk_types::connection::{ConnectionStatus, ConnectionType};
 use rynk::rmk_types::fork::Fork;
 use rynk::rmk_types::led_indicator::LedIndicator;
 use rynk::rmk_types::morse::Morse;
+use rynk::rmk_types::modifier::ModifierCombination;
 use rynk::rmk_types::protocol::rynk::{
     AbortLightingOverlayReplaceRequest, BeginLightingOverlayReplaceRequest, BehaviorConfig,
     ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest, DeviceCapabilities, DeviceInfo,
@@ -163,6 +164,7 @@ endpoints! {
     // status
     get_current_layer() -> u8,
     get_layer_state() -> LayerState,
+    get_modifier_state() -> ModifierCombination,
     get_matrix_state() -> MatrixState,
     get_battery_status() -> BatteryStatus,
     get_led_indicator() -> LedIndicator,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 31bef2981..2e6b15966 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -19,6 +19,7 @@ use rmk_types::combo::Combo;
 use rmk_types::connection::{ConnectionStatus, ConnectionType};
 use rmk_types::fork::Fork;
 use rmk_types::led_indicator::LedIndicator;
+use rmk_types::modifier::ModifierCombination;
 use rmk_types::morse::Morse;
 use rmk_types::protocol::rynk::{
     AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
@@ -366,6 +367,11 @@ impl Client {
         self.request::<command::GetLayerState>(&()).await
     }
 
+    /// Read the final resolved modifier bitmap used by the HID report.
+    pub async fn get_modifier_state(&self) -> Result<ModifierCombination, RynkHostError> {
+        self.request::<command::GetModifierState>(&()).await
+    }
+
     /// Read the matrix state: a bitmap of which keys are physically pressed.
     pub async fn get_matrix_state(&self) -> Result<MatrixState, RynkHostError> {
         self.request::<command::GetMatrixState>(&()).await

From 64c06fdb7b2847a276a74e68f8603a77d4f4bd17 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 04:32:59 -0700
Subject: [PATCH 21/78] feat(split): make central latency runtime configurable

---
 docs/docs/main/docs/configuration/appendix.md |   3 +
 .../main/docs/configuration/rmk_config.md     |   4 +
 .../main/docs/development/rynk_protocol.md    | 180 +++++++++---------
 rmk-config/src/lib.rs                         |  50 +++++
 rmk-config/src/resolved/build_constants.rs    |   4 +
 rmk-types/build.rs                            |   8 +
 rmk-types/src/protocol/rynk/command.rs        |   8 +
 rmk-types/src/protocol/rynk/payload/system.rs |  40 ++++
 .../rynk/snapshots/split_ble_wire_frames.snap |  11 ++
 .../protocol/rynk/snapshots/wire_values.snap  |   2 +-
 rmk-types/src/protocol/rynk/tests.rs          | 115 +++++++++--
 rmk/src/host/rynk/handlers/connection.rs      |  52 +++++
 rmk/src/host/rynk/mod.rs                      |   6 +
 rmk/src/split/ble/central.rs                  | 148 +++++++++++++-
 rmk/src/state.rs                              |   5 +
 rynk/rynk-wasm/src/client.rs                  |   4 +-
 rynk/src/api.rs                               |  16 +-
 17 files changed, 544 insertions(+), 112 deletions(-)
 create mode 100644 rmk-types/src/protocol/rynk/snapshots/split_ble_wire_frames.snap

diff --git a/docs/docs/main/docs/configuration/appendix.md b/docs/docs/main/docs/configuration/appendix.md
index 712c7ab1b..01b09c1b1 100644
--- a/docs/docs/main/docs/configuration/appendix.md
+++ b/docs/docs/main/docs/configuration/appendix.md
@@ -353,6 +353,9 @@ split_peripherals_num = 0
 ble_profiles_num = 3
 # BLE Split Central sleep timeout in seconds (0 = disabled)
 split_central_sleep_timeout_seconds = 0
+# Maximum skipped split connection events while active (0 = lowest latency)
+split_central_max_latency_powered = 30
+split_central_max_latency_battery = 30
 # Maximum macro data bytes in one Rynk macro request or response
 protocol_macro_chunk_size = 64
 # Rynk RX/TX buffer size in bytes. 488 bytes = 2*BLE maximum packet size
diff --git a/docs/docs/main/docs/configuration/rmk_config.md b/docs/docs/main/docs/configuration/rmk_config.md
index 45bde3d13..aa9c7458d 100644
--- a/docs/docs/main/docs/configuration/rmk_config.md
+++ b/docs/docs/main/docs/configuration/rmk_config.md
@@ -38,6 +38,9 @@ split_peripherals_num = 0
 ble_profiles_num = 3
 # BLE Split Central sleep timeout in seconds (0 = disabled)
 split_central_sleep_timeout_seconds = 0
+# Maximum skipped 7.5 ms split connection events while active
+split_central_max_latency_powered = 30
+split_central_max_latency_battery = 30
 # Maximum macro data bytes in one Rynk macro request or response
 protocol_macro_chunk_size = 64
 # Maximum number of auto mouse layer entries (auto-derived from [[behavior.auto_mouse_layer]] if unset)
@@ -98,6 +101,7 @@ These tune the [Rynk](../features/rynk) protocol and rarely need changing.
 
 - `ble_profiles_num`: The number of available Bluetooth profiles, default value is 3. This parameter defines how many Bluetooth paired devices the keyboard can store.
 - `split_central_sleep_timeout_seconds`: Sleep timeout for BLE split central in seconds, default value is 0 (disabled). When set to a non-zero value, the split central will enter sleep mode after this many seconds of inactivity to save power. Set to 0 to disable automatic sleep.
+- `split_central_max_latency_powered` / `split_central_max_latency_battery`: Maximum number of BLE connection events the split peripheral may skip while active, selected by whether USB power is present. Both default to 30. Lower values reduce worst-case split input and central-to-peripheral update latency at the cost of more radio wakeups and peripheral battery use. Set to 0 for the lowest latency. Sleep mode uses its own low-power connection parameters. Rynk can replace these volatile values or force/clear a runtime override with `GetSplitCentralLatency` and `SetSplitCentralLatency`; reboot restores the build-time values.
 
 ### Auto Mouse Layer Configuration
 
diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 0612e2570..8c63e39e7 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -213,100 +213,102 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x0918` | `CommitLightingSceneReplace`   | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`               | `lighting` |                                                                                                                                |
 | `0x0919` | `AbortLightingSceneReplace`    | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                | `lighting` |                                                                                                                                |
 | `0x091A` | `SetLightingLayerPolicy`       | `SetLightingLayerPolicyRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| CMD      | Name                             | Request                               | Response                            | Feature    | Notes                                                                                                                          |
-| -------- | -------------------------------- | ------------------------------------- | ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `0x0001` | `GetVersion`                     | `()`                                  | `ProtocolVersion`                   |            |                                                                                                                                |
-| `0x0002` | `GetCapabilities`                | `()`                                  | `DeviceCapabilities`                |            |                                                                                                                                |
-| `0x0003` | `Reboot`                         | `()`                                  | `()`                                |            |                                                                                                                                |
-| `0x0004` | `BootloaderJump`                 | `()`                                  | `()`                                |            |                                                                                                                                |
-| `0x0005` | `StorageReset`                   | `StorageResetMode`                    | `()`                                |            |                                                                                                                                |
-| `0x0006` | `GetLockStatus`                  | `()`                                  | `LockStatus`                        |            | Pure read of the current lock state — no side effects.                                                                         |
-| `0x0007` | `UnlockPoll`                     | `()`                                  | `LockStatus`                        |            | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                         |
-| `0x0008` | `Lock`                           | `()`                                  | `()`                                |            | Relock immediately.                                                                                                            |
-| `0x0009` | `GetLayout`                      | `u32`                                 | `LayoutChunk`                       |            | Get layout blob chunk. `u32` is the byte offset.                                                                               |
-| `0x000A` | `GetDeviceInfo`                  | `()`                                  | `DeviceInfo`                        |            | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                       |
-| `0x000B` | `GetBuildInfo`                   | `()`                                  | `BuildInfo`                         |            | Application-defined diagnostic build label; never used for compatibility.                                                      |
-| `0x000C` | `PeripheralBootloaderJump`       | `u8`                                  | `()`                                |            | Ask the application to route a bootloader jump to one split peripheral.                                                        |
-| `0x0101` | `GetKeyAction`                   | `KeyPosition`                         | `KeyAction`                         |            |                                                                                                                                |
-| `0x0102` | `SetKeyAction`                   | `SetKeyRequest`                       | `()`                                |            |                                                                                                                                |
-| `0x0103` | `GetDefaultLayer`                | `()`                                  | `u8`                                |            |                                                                                                                                |
-| `0x0104` | `SetDefaultLayer`                | `u8`                                  | `()`                                |            |                                                                                                                                |
-| `0x0105` | `GetEncoderAction`               | `GetEncoderRequest`                   | `EncoderAction`                     |            |                                                                                                                                |
-| `0x0106` | `SetEncoderAction`               | `SetEncoderRequest`                   | `()`                                |            |                                                                                                                                |
-| `0x0107` | `GetKeymapBulk`                  | `GetKeymapBulkRequest`                | `GetKeymapBulkResponse`             |            |                                                                                                                                |
-| `0x0108` | `SetKeymapBulk`                  | `SetKeymapBulkRequest`                | `()`                                |            |                                                                                                                                |
-| `0x0201` | `GetMacro`                       | `GetMacroRequest`                     | `MacroData`                         |            |                                                                                                                                |
-| `0x0202` | `SetMacro`                       | `SetMacroRequest`                     | `()`                                |            |                                                                                                                                |
-| `0x0301` | `GetCombo`                       | `u8`                                  | `Combo`                             |            |                                                                                                                                |
-| `0x0302` | `SetCombo`                       | `SetComboRequest`                     | `()`                                |            |                                                                                                                                |
-| `0x0303` | `GetComboBulk`                   | `GetComboBulkRequest`                 | `GetComboBulkResponse`              |            |                                                                                                                                |
-| `0x0304` | `SetComboBulk`                   | `SetComboBulkRequest`                 | `()`                                |            |                                                                                                                                |
-| `0x0401` | `GetMorse`                       | `u8`                                  | `Morse`                             |            |                                                                                                                                |
-| `0x0402` | `SetMorse`                       | `SetMorseRequest`                     | `()`                                |            |                                                                                                                                |
-| `0x0403` | `GetMorseBulk`                   | `GetMorseBulkRequest`                 | `GetMorseBulkResponse`              |            |                                                                                                                                |
-| `0x0404` | `SetMorseBulk`                   | `SetMorseBulkRequest`                 | `()`                                |            |                                                                                                                                |
-| `0x0501` | `GetFork`                        | `u8`                                  | `Fork`                              |            |                                                                                                                                |
-| `0x0502` | `SetFork`                        | `SetForkRequest`                      | `()`                                |            |                                                                                                                                |
-| `0x0601` | `GetBehaviorConfig`              | `()`                                  | `BehaviorConfig`                    |            |                                                                                                                                |
-| `0x0602` | `SetBehaviorConfig`              | `BehaviorConfig`                      | `()`                                |            |                                                                                                                                |
-| `0x0701` | `GetConnectionType`              | `()`                                  | `ConnectionType`                    |            |                                                                                                                                |
-| `0x0702` | `GetConnectionStatus`            | `()`                                  | `ConnectionStatus`                  |            | Full `ConnectionStatus` snapshot.                                                                                              |
-| `0x0703` | `GetBleStatus`                   | `()`                                  | `BleStatus`                         | `_ble`     |                                                                                                                                |
-| `0x0704` | `SwitchBleProfile`               | `u8`                                  | `()`                                | `_ble`     |                                                                                                                                |
-| `0x0705` | `ClearBleProfile`                | `u8`                                  | `()`                                | `_ble`     |                                                                                                                                |
-| `0x0801` | `GetCurrentLayer`                | `()`                                  | `u8`                                |            |                                                                                                                                |
-| `0x0802` | `GetMatrixState`                 | `()`                                  | `MatrixState`                       |            |                                                                                                                                |
-| `0x0803` | `GetBatteryStatus`               | `()`                                  | `BatteryStatus`                     | `_ble`     |                                                                                                                                |
-| `0x0804` | `GetPeripheralStatus`            | `u8`                                  | `PeripheralStatus`                  | `split`    |                                                                                                                                |
-| `0x0805` | `GetWpm`                         | `()`                                  | `u16`                               |            | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                       |
-| `0x0806` | `GetSleepState`                  | `()`                                  | `bool`                              |            | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                               |
-| `0x0807` | `GetLedIndicator`                | `()`                                  | `LedIndicator`                      |            | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                   |
-| `0x0808` | `GetLayerState`                  | `()`                                  | `LayerState`                        |            | Default layer and complete active-layer bitmap.                                                                                |
-| `0x0809` | `GetModifierState`               | `()`                                  | `ModifierCombination`               |            | Final resolved modifier bitmap used by the HID keyboard report.                                                                |
-| `0x0901` | `GetLightingCapabilities`        | `()`                                  | `LightingCapabilitiesResult`        | `lighting` |                                                                                                                                |
-| `0x0902` | `GetLightingState`               | `()`                                  | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0903` | `SetLightingState`               | `SetLightingStateRequest`             | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0904` | `GetLightingPhysicalKeys`        | `LightingPageRequest`                 | `LightingPhysicalKeysPageResult`    | `lighting` |                                                                                                                                |
-| `0x0905` | `GetLightingLeds`                | `LightingPageRequest`                 | `LightingLedsPageResult`            | `lighting` |                                                                                                                                |
-| `0x0906` | `GetLightingZones`               | `LightingPageRequest`                 | `LightingZonesPageResult`           | `lighting` |                                                                                                                                |
-| `0x0907` | `GetLightingZoneMemberships`     | `LightingPageRequest`                 | `LightingZoneMembershipsPageResult` | `lighting` |                                                                                                                                |
-| `0x0908` | `GetLightingOutputs`             | `LightingPageRequest`                 | `LightingOutputsPageResult`         | `lighting` |                                                                                                                                |
-| `0x0909` | `GetLightingRoutes`              | `LightingPageRequest`                 | `LightingRoutesPageResult`          | `lighting` |                                                                                                                                |
-| `0x090A` | `SetLightingOverlay`             | `SetLightingOverlayRequest`           | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x090B` | `UnsetLightingOverlay`           | `UnsetLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x090C` | `ClearLightingOverlay`           | `ClearLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x090D` | `BeginLightingOverlayReplace`    | `BeginLightingOverlayReplaceRequest`  | `LightingOverlayTransactionResult`  | `lighting` |                                                                                                                                |
-| `0x090E` | `PutLightingOverlayChunk`        | `PutLightingOverlayChunkRequest`      | `LightingUnitResult`                | `lighting` |                                                                                                                                |
-| `0x090F` | `CommitLightingOverlayReplace`   | `CommitLightingOverlayReplaceRequest` | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0910` | `AbortLightingOverlayReplace`    | `AbortLightingOverlayReplaceRequest`  | `LightingUnitResult`                | `lighting` |                                                                                                                                |
-| `0x0911` | `GetLightingKeys`                | `LightingPageRequest`                 | `LightingKeysPageResult`            | `lighting` | Logical matrix keys are distinct from optional physical geometry.                                                              |
-| `0x0912` | `GetLightingSceneStatus`         | `()`                                  | `LightingSceneStatusResult`         | `lighting` | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts. |
-| `0x0913` | `GetLightingScenes`              | `LightingScenePageRequest`            | `LightingScenesPageResult`          | `lighting` | Scene pages are pinned to `LightingState.revision` for consistency.                                                            |
-| `0x0914` | `SetLightingSceneCell`           | `SetLightingSceneCellRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0915` | `UnsetLightingSceneCell`         | `UnsetLightingSceneCellRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0916` | `BeginLightingSceneReplace`      | `BeginLightingSceneReplaceRequest`    | `LightingSceneTransactionResult`    | `lighting` |                                                                                                                                |
-| `0x0917` | `PutLightingSceneChunk`          | `PutLightingSceneChunkRequest`        | `LightingUnitResult`                | `lighting` |                                                                                                                                |
-| `0x0918` | `CommitLightingSceneReplace`     | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0919` | `AbortLightingSceneReplace`      | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                | `lighting` |                                                                                                                                |
-| `0x091A` | `SetLightingLayerPolicy`         | `SetLightingLayerPolicyRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x091B` | `GetLightingOverlay`             | `LightingOverlayPageRequest`          | `LightingOverlayPageResult`         | `lighting` | Overlay pages are pinned to `LightingState.revision` for consistency.                                                          |
-| `0x091C` | `GetLightingCompiledSceneStatus` | `()`                                  | `LightingCompiledSceneStatusResult` | `lighting` | Discover the immutable board-compiled layer-scene source.                                                                      |
-| `0x091D` | `GetLightingCompiledScenes`      | `LightingPageRequest`                 | `LightingCompiledScenesPageResult`  | `lighting` | Compiled-scene pages are pinned to the firmware topology revision.                                                             |
+| CMD      | Name                             | Request                               | Response                            | Feature          | Notes                                                                                                                          |
+| -------- | -------------------------------- | ------------------------------------- | ----------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `0x0001` | `GetVersion`                     | `()`                                  | `ProtocolVersion`                   |                  |                                                                                                                                |
+| `0x0002` | `GetCapabilities`                | `()`                                  | `DeviceCapabilities`                |                  |                                                                                                                                |
+| `0x0003` | `Reboot`                         | `()`                                  | `()`                                |                  |                                                                                                                                |
+| `0x0004` | `BootloaderJump`                 | `()`                                  | `()`                                |                  |                                                                                                                                |
+| `0x0005` | `StorageReset`                   | `StorageResetMode`                    | `()`                                |                  |                                                                                                                                |
+| `0x0006` | `GetLockStatus`                  | `()`                                  | `LockStatus`                        |                  | Pure read of the current lock state — no side effects.                                                                         |
+| `0x0007` | `UnlockPoll`                     | `()`                                  | `LockStatus`                        |                  | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                         |
+| `0x0008` | `Lock`                           | `()`                                  | `()`                                |                  | Relock immediately.                                                                                                            |
+| `0x0009` | `GetLayout`                      | `u32`                                 | `LayoutChunk`                       |                  | Get layout blob chunk. `u32` is the byte offset.                                                                               |
+| `0x000A` | `GetDeviceInfo`                  | `()`                                  | `DeviceInfo`                        |                  | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                       |
+| `0x000B` | `GetBuildInfo`                   | `()`                                  | `BuildInfo`                         |                  | Application-defined diagnostic build label; never used for compatibility.                                                      |
+| `0x000C` | `PeripheralBootloaderJump`       | `u8`                                  | `()`                                |                  | Ask the application to route a bootloader jump to one split peripheral.                                                        |
+| `0x0101` | `GetKeyAction`                   | `KeyPosition`                         | `KeyAction`                         |                  |                                                                                                                                |
+| `0x0102` | `SetKeyAction`                   | `SetKeyRequest`                       | `()`                                |                  |                                                                                                                                |
+| `0x0103` | `GetDefaultLayer`                | `()`                                  | `u8`                                |                  |                                                                                                                                |
+| `0x0104` | `SetDefaultLayer`                | `u8`                                  | `()`                                |                  |                                                                                                                                |
+| `0x0105` | `GetEncoderAction`               | `GetEncoderRequest`                   | `EncoderAction`                     |                  |                                                                                                                                |
+| `0x0106` | `SetEncoderAction`               | `SetEncoderRequest`                   | `()`                                |                  |                                                                                                                                |
+| `0x0107` | `GetKeymapBulk`                  | `GetKeymapBulkRequest`                | `GetKeymapBulkResponse`             |                  |                                                                                                                                |
+| `0x0108` | `SetKeymapBulk`                  | `SetKeymapBulkRequest`                | `()`                                |                  |                                                                                                                                |
+| `0x0201` | `GetMacro`                       | `GetMacroRequest`                     | `MacroData`                         |                  |                                                                                                                                |
+| `0x0202` | `SetMacro`                       | `SetMacroRequest`                     | `()`                                |                  |                                                                                                                                |
+| `0x0301` | `GetCombo`                       | `u8`                                  | `Combo`                             |                  |                                                                                                                                |
+| `0x0302` | `SetCombo`                       | `SetComboRequest`                     | `()`                                |                  |                                                                                                                                |
+| `0x0303` | `GetComboBulk`                   | `GetComboBulkRequest`                 | `GetComboBulkResponse`              |                  |                                                                                                                                |
+| `0x0304` | `SetComboBulk`                   | `SetComboBulkRequest`                 | `()`                                |                  |                                                                                                                                |
+| `0x0401` | `GetMorse`                       | `u8`                                  | `Morse`                             |                  |                                                                                                                                |
+| `0x0402` | `SetMorse`                       | `SetMorseRequest`                     | `()`                                |                  |                                                                                                                                |
+| `0x0403` | `GetMorseBulk`                   | `GetMorseBulkRequest`                 | `GetMorseBulkResponse`              |                  |                                                                                                                                |
+| `0x0404` | `SetMorseBulk`                   | `SetMorseBulkRequest`                 | `()`                                |                  |                                                                                                                                |
+| `0x0501` | `GetFork`                        | `u8`                                  | `Fork`                              |                  |                                                                                                                                |
+| `0x0502` | `SetFork`                        | `SetForkRequest`                      | `()`                                |                  |                                                                                                                                |
+| `0x0601` | `GetBehaviorConfig`              | `()`                                  | `BehaviorConfig`                    |                  |                                                                                                                                |
+| `0x0602` | `SetBehaviorConfig`              | `BehaviorConfig`                      | `()`                                |                  |                                                                                                                                |
+| `0x0701` | `GetConnectionType`              | `()`                                  | `ConnectionType`                    |                  |                                                                                                                                |
+| `0x0702` | `GetConnectionStatus`            | `()`                                  | `ConnectionStatus`                  |                  | Full `ConnectionStatus` snapshot.                                                                                              |
+| `0x0703` | `GetBleStatus`                   | `()`                                  | `BleStatus`                         | `_ble`           |                                                                                                                                |
+| `0x0704` | `SwitchBleProfile`               | `u8`                                  | `()`                                | `_ble`           |                                                                                                                                |
+| `0x0705` | `ClearBleProfile`                | `u8`                                  | `()`                                | `_ble`           |                                                                                                                                |
+| `0x0706` | `GetSplitCentralLatency`         | `()`                                  | `SplitCentralLatencyState`          | `_ble` + `split` | Read the volatile active-mode policy, current USB-power selection, and effective value.                                        |
+| `0x0707` | `SetSplitCentralLatency`         | `SplitCentralLatencyPolicy`           | `SplitCentralLatencyState`          | `_ble` + `split` | Replace the volatile policy. Each connection-event count must be `0..=499`.                                                    |
+| `0x0801` | `GetCurrentLayer`                | `()`                                  | `u8`                                |                  |                                                                                                                                |
+| `0x0802` | `GetMatrixState`                 | `()`                                  | `MatrixState`                       |                  |                                                                                                                                |
+| `0x0803` | `GetBatteryStatus`               | `()`                                  | `BatteryStatus`                     | `_ble`           |                                                                                                                                |
+| `0x0804` | `GetPeripheralStatus`            | `u8`                                  | `PeripheralStatus`                  | `split`          |                                                                                                                                |
+| `0x0805` | `GetWpm`                         | `()`                                  | `u16`                               |                  | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                       |
+| `0x0806` | `GetSleepState`                  | `()`                                  | `bool`                              |                  | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                               |
+| `0x0807` | `GetLedIndicator`                | `()`                                  | `LedIndicator`                      |                  | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                   |
+| `0x0808` | `GetLayerState`                  | `()`                                  | `LayerState`                        |                  | Default layer and complete active-layer bitmap.                                                                                |
+| `0x0809` | `GetModifierState`               | `()`                                  | `ModifierCombination`               |                  | Final resolved modifier bitmap used by the HID keyboard report.                                                                |
+| `0x0901` | `GetLightingCapabilities`        | `()`                                  | `LightingCapabilitiesResult`        | `lighting`       |                                                                                                                                |
+| `0x0902` | `GetLightingState`               | `()`                                  | `LightingStateResult`               | `lighting`       |                                                                                                                                |
+| `0x0903` | `SetLightingState`               | `SetLightingStateRequest`             | `LightingStateResult`               | `lighting`       |                                                                                                                                |
+| `0x0904` | `GetLightingPhysicalKeys`        | `LightingPageRequest`                 | `LightingPhysicalKeysPageResult`    | `lighting`       |                                                                                                                                |
+| `0x0905` | `GetLightingLeds`                | `LightingPageRequest`                 | `LightingLedsPageResult`            | `lighting`       |                                                                                                                                |
+| `0x0906` | `GetLightingZones`               | `LightingPageRequest`                 | `LightingZonesPageResult`           | `lighting`       |                                                                                                                                |
+| `0x0907` | `GetLightingZoneMemberships`     | `LightingPageRequest`                 | `LightingZoneMembershipsPageResult` | `lighting`       |                                                                                                                                |
+| `0x0908` | `GetLightingOutputs`             | `LightingPageRequest`                 | `LightingOutputsPageResult`         | `lighting`       |                                                                                                                                |
+| `0x0909` | `GetLightingRoutes`              | `LightingPageRequest`                 | `LightingRoutesPageResult`          | `lighting`       |                                                                                                                                |
+| `0x090A` | `SetLightingOverlay`             | `SetLightingOverlayRequest`           | `LightingStateResult`               | `lighting`       |                                                                                                                                |
+| `0x090B` | `UnsetLightingOverlay`           | `UnsetLightingOverlayRequest`         | `LightingStateResult`               | `lighting`       |                                                                                                                                |
+| `0x090C` | `ClearLightingOverlay`           | `ClearLightingOverlayRequest`         | `LightingStateResult`               | `lighting`       |                                                                                                                                |
+| `0x090D` | `BeginLightingOverlayReplace`    | `BeginLightingOverlayReplaceRequest`  | `LightingOverlayTransactionResult`  | `lighting`       |                                                                                                                                |
+| `0x090E` | `PutLightingOverlayChunk`        | `PutLightingOverlayChunkRequest`      | `LightingUnitResult`                | `lighting`       |                                                                                                                                |
+| `0x090F` | `CommitLightingOverlayReplace`   | `CommitLightingOverlayReplaceRequest` | `LightingStateResult`               | `lighting`       |                                                                                                                                |
+| `0x0910` | `AbortLightingOverlayReplace`    | `AbortLightingOverlayReplaceRequest`  | `LightingUnitResult`                | `lighting`       |                                                                                                                                |
+| `0x0911` | `GetLightingKeys`                | `LightingPageRequest`                 | `LightingKeysPageResult`            | `lighting`       | Logical matrix keys are distinct from optional physical geometry.                                                              |
+| `0x0912` | `GetLightingSceneStatus`         | `()`                                  | `LightingSceneStatusResult`         | `lighting`       | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts. |
+| `0x0913` | `GetLightingScenes`              | `LightingScenePageRequest`            | `LightingScenesPageResult`          | `lighting`       | Scene pages are pinned to `LightingState.revision` for consistency.                                                            |
+| `0x0914` | `SetLightingSceneCell`           | `SetLightingSceneCellRequest`         | `LightingStateResult`               | `lighting`       |                                                                                                                                |
+| `0x0915` | `UnsetLightingSceneCell`         | `UnsetLightingSceneCellRequest`       | `LightingStateResult`               | `lighting`       |                                                                                                                                |
+| `0x0916` | `BeginLightingSceneReplace`      | `BeginLightingSceneReplaceRequest`    | `LightingSceneTransactionResult`    | `lighting`       |                                                                                                                                |
+| `0x0917` | `PutLightingSceneChunk`          | `PutLightingSceneChunkRequest`        | `LightingUnitResult`                | `lighting`       |                                                                                                                                |
+| `0x0918` | `CommitLightingSceneReplace`     | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`               | `lighting`       |                                                                                                                                |
+| `0x0919` | `AbortLightingSceneReplace`      | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                | `lighting`       |                                                                                                                                |
+| `0x091A` | `SetLightingLayerPolicy`         | `SetLightingLayerPolicyRequest`       | `LightingStateResult`               | `lighting`       |                                                                                                                                |
+| `0x091B` | `GetLightingOverlay`             | `LightingOverlayPageRequest`          | `LightingOverlayPageResult`         | `lighting`       | Overlay pages are pinned to `LightingState.revision` for consistency.                                                          |
+| `0x091C` | `GetLightingCompiledSceneStatus` | `()`                                  | `LightingCompiledSceneStatusResult` | `lighting`       | Discover the immutable board-compiled layer-scene source.                                                                      |
+| `0x091D` | `GetLightingCompiledScenes`      | `LightingPageRequest`                 | `LightingCompiledScenesPageResult`  | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                             |
 
 ## Topics
 
 Topics are best-effort pushes; the `Get*` endpoints above mirror their payloads so a host can recover a missed push.
 
-| CMD      | Name                  | Payload               | Feature    | Notes                                   |
-| -------- | --------------------- | --------------------- | ---------- | --------------------------------------- |
-| `0x8001` | `LayerChange`         | `u8`                  |            |                                         |
-| `0x8002` | `WpmUpdate`           | `u16`                 |            |                                         |
-| `0x8003` | `ConnectionChange`    | `ConnectionStatus`    |            |                                         |
-| `0x8004` | `SleepState`          | `bool`                |            |                                         |
-| `0x8005` | `LedIndicatorChange`  | `LedIndicator`        |            |                                         |
-| `0x8006` | `BatteryStatusChange` | `BatteryStatus`       | `_ble`     |                                         |
-| `0x8007` | `LightingChange`      | `LightingChanged`     | `lighting` |                                         |
-| `0x8008` | `ModifierChange`      | `ModifierCombination` |            | Final resolved modifier bitmap changed. |
+| CMD      | Name                  | Payload               | Feature    | Notes |
+| -------- | --------------------- | --------------------- | ---------- | ----- |
+| `0x8001` | `LayerChange`         | `u8`                  |            |       |
+| `0x8002` | `WpmUpdate`           | `u16`                 |            |       |
+| `0x8003` | `ConnectionChange`    | `ConnectionStatus`    |            |       |
+| `0x8004` | `SleepState`          | `bool`                |            |       |
+| `0x8005` | `LedIndicatorChange`  | `LedIndicator`        |            |       |
+| `0x8006` | `BatteryStatusChange` | `BatteryStatus`       | `_ble`     |       |
+| `0x8007` | `LightingChange`      | `LightingChanged`     | `lighting` |       |
+| `0x8008` | `ModifierChange`      | `ModifierCombination` |            |       |
 
 ## Compatibility
 
diff --git a/rmk-config/src/lib.rs b/rmk-config/src/lib.rs
index 07f5015fc..06fc5d234 100644
--- a/rmk-config/src/lib.rs
+++ b/rmk-config/src/lib.rs
@@ -301,6 +301,14 @@ pub(crate) struct RmkConstantsConfig {
     /// BLE Split Central sleep timeout in seconds (0 = disabled)
     #[serde_inline_default(0)]
     pub split_central_sleep_timeout_seconds: u32,
+    /// Maximum BLE peripheral latency on external power, in active connection events.
+    #[serde_inline_default(30)]
+    #[serde(deserialize_with = "check_split_central_max_latency")]
+    pub split_central_max_latency_powered: u16,
+    /// Maximum BLE peripheral latency on battery, in active connection events.
+    #[serde_inline_default(30)]
+    #[serde(deserialize_with = "check_split_central_max_latency")]
+    pub split_central_max_latency_battery: u16,
     /// Maximum macro data chunk size for protocol transfers (bytes).
     /// Smaller values reduce firmware RAM usage but require more round-trips.
     #[serde_inline_default(64)]
@@ -380,6 +388,19 @@ where
     Ok(value)
 }
 
+fn check_split_central_max_latency<'de, D>(deserializer: D) -> Result<u16, D::Error>
+where
+    D: de::Deserializer<'de>,
+{
+    let value = Deserialize::deserialize(deserializer)?;
+    if value >= 500 {
+        return Err(de::Error::custom(format!(
+            "split_central_max_latency must be between 0 and 499, got {value}"
+        )));
+    }
+    Ok(value)
+}
+
 /// This separate Default impl is needed when `[rmk]` section is not set in keyboard.toml
 impl Default for RmkConstantsConfig {
     fn default() -> Self {
@@ -400,6 +421,8 @@ impl Default for RmkConstantsConfig {
             split_peripherals_num: 0,
             ble_profiles_num: 3,
             split_central_sleep_timeout_seconds: 0,
+            split_central_max_latency_powered: 30,
+            split_central_max_latency_battery: 30,
             protocol_macro_chunk_size: 64,
             auto_mouse_layer_max_num: None,
             rynk_buffer_size: 488,
@@ -1643,6 +1666,33 @@ fork_max_num = 255
         }
     }
 
+    #[test]
+    fn split_central_max_latency_matches_ble_limit() {
+        let ok: KeyboardTomlConfig = toml::from_str(
+            r#"
+[rmk]
+split_central_max_latency_powered = 499
+split_central_max_latency_battery = 498
+"#,
+        )
+        .unwrap();
+        assert_eq!(ok.rmk.split_central_max_latency_powered, 499);
+        assert_eq!(ok.rmk.split_central_max_latency_battery, 498);
+
+        let err = toml::from_str::<KeyboardTomlConfig>(
+            r#"
+[rmk]
+split_central_max_latency_battery = 500
+"#,
+        )
+        .unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("split_central_max_latency must be between 0 and 499"),
+            "{err}"
+        );
+    }
+
     #[test]
     fn test_event_config_partial_override_with_event_defaults_loader() {
         let user_toml = r#"
diff --git a/rmk-config/src/resolved/build_constants.rs b/rmk-config/src/resolved/build_constants.rs
index bbeb024a2..f1718cd1a 100644
--- a/rmk-config/src/resolved/build_constants.rs
+++ b/rmk-config/src/resolved/build_constants.rs
@@ -47,6 +47,8 @@ pub struct BuildConstants {
     pub split_peripherals_num: usize,
     pub ble_profiles_num: usize,
     pub split_central_sleep_timeout_seconds: u32,
+    pub split_central_max_latency_powered: u16,
+    pub split_central_max_latency_battery: u16,
     pub protocol_macro_chunk_size: usize,
     pub auto_mouse_layer_max_num: usize,
     /// Rynk RX/TX buffer size (bytes).
@@ -197,6 +199,8 @@ impl crate::KeyboardTomlConfig {
             split_peripherals_num,
             ble_profiles_num: rmk.ble_profiles_num,
             split_central_sleep_timeout_seconds: rmk.split_central_sleep_timeout_seconds,
+            split_central_max_latency_powered: rmk.split_central_max_latency_powered,
+            split_central_max_latency_battery: rmk.split_central_max_latency_battery,
             protocol_macro_chunk_size: rmk.protocol_macro_chunk_size,
             auto_mouse_layer_max_num,
             rynk_buffer_size: rmk.rynk_buffer_size,
diff --git a/rmk-types/build.rs b/rmk-types/build.rs
index 697166c32..2074374f8 100644
--- a/rmk-types/build.rs
+++ b/rmk-types/build.rs
@@ -71,6 +71,14 @@ fn generate_constants(bc: &BuildConstants, config: &KeyboardTomlConfig) -> Strin
         "pub const SPLIT_CENTRAL_SLEEP_TIMEOUT_SECONDS: u32 = {};",
         bc.split_central_sleep_timeout_seconds
     ));
+    lines.push(format!(
+        "pub const SPLIT_CENTRAL_MAX_LATENCY_POWERED: u16 = {};",
+        bc.split_central_max_latency_powered
+    ));
+    lines.push(format!(
+        "pub const SPLIT_CENTRAL_MAX_LATENCY_BATTERY: u16 = {};",
+        bc.split_central_max_latency_battery
+    ));
     lines.push(format!("pub const MORSE_MAX_NUM: usize = {};", bc.morse_max_num));
     lines.push(format!(
         "pub const MORSE_PROFILE_MAX_NUM: usize = {};",
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index db6a1bf83..19e8a04e4 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -46,6 +46,8 @@ use crate::protocol::rynk::{
     PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
     SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
+#[cfg(all(feature = "_ble", feature = "split"))]
+use crate::protocol::rynk::{SplitCentralLatencyPolicy, SplitCentralLatencyState};
 
 /// CMD high bit marking a topic (server → host push).
 const RYNK_TOPIC_BIT: u16 = 0x8000;
@@ -341,6 +343,12 @@ endpoints! {
     SwitchBleProfile = 0x0704: u8 => ();
     #[cfg(feature = "_ble")]
     ClearBleProfile = 0x0705: u8 => ();
+    #[cfg(all(feature = "_ble", feature = "split"))]
+    /// Read the volatile active-mode policy, current USB-power selection, and effective value.
+    GetSplitCentralLatency = 0x0706: () => SplitCentralLatencyState;
+    #[cfg(all(feature = "_ble", feature = "split"))]
+    /// Replace the volatile policy. Each connection-event count must be `0..=499`.
+    SetSplitCentralLatency = 0x0707: SplitCentralLatencyPolicy => SplitCentralLatencyState;
 
     // Status (0x08xx).
     GetCurrentLayer = 0x0801: () => u8;
diff --git a/rmk-types/src/protocol/rynk/payload/system.rs b/rmk-types/src/protocol/rynk/payload/system.rs
index 17d7c44a5..d5f3e58cd 100644
--- a/rmk-types/src/protocol/rynk/payload/system.rs
+++ b/rmk-types/src/protocol/rynk/payload/system.rs
@@ -186,6 +186,31 @@ pub struct BehaviorConfig {
     pub tap_capslock_interval_ms: u16,
 }
 
+/// Active-mode split BLE latency policy. Values count connection events.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, MaxSize)]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct SplitCentralLatencyPolicy {
+    /// Maximum skipped connection events when USB power is present.
+    pub powered: u16,
+    /// Maximum skipped connection events when running on battery.
+    pub battery: u16,
+    /// Forced value for both power states; `None` restores automatic selection.
+    pub override_latency: Option<u16>,
+}
+
+/// Current split BLE latency selection and its policy inputs.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, MaxSize)]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct SplitCentralLatencyState {
+    pub policy: SplitCentralLatencyPolicy,
+    /// Whether USB power is currently present.
+    pub powered: bool,
+    /// Value currently requested for the active split connection.
+    pub effective: u16,
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -327,4 +352,19 @@ mod tests {
             tap_capslock_interval_ms: 20,
         });
     }
+
+    #[test]
+    fn round_trip_split_central_latency() {
+        let policy = SplitCentralLatencyPolicy {
+            powered: 0,
+            battery: 4,
+            override_latency: Some(2),
+        };
+        round_trip(&policy);
+        round_trip(&SplitCentralLatencyState {
+            policy,
+            powered: true,
+            effective: 2,
+        });
+    }
 }
diff --git a/rmk-types/src/protocol/rynk/snapshots/split_ble_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/split_ble_wire_frames.snap
new file mode 100644
index 000000000..bbac86a0d
--- /dev/null
+++ b/rmk-types/src/protocol/rynk/snapshots/split_ble_wire_frames.snap
@@ -0,0 +1,11 @@
+# Split BLE wire-format FRAME snapshot — DO NOT edit by hand.
+# File: snapshots/split_ble_wire_frames.snap
+# Each entry is one complete feature-gated split BLE latency-policy frame.
+#   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk --features "rynk _ble split" split_ble_wire_frames
+# Format: <label>  <hex bytes>
+
+GetSplitCentralLatency reply Ok(state)     06 07 01 07 00 00 00 04 01 02 01 02
+GetSplitCentralLatency request ()          06 07 01 00 00
+SetSplitCentralLatency reply Err(Invalid)  07 07 01 02 00 01 05
+SetSplitCentralLatency reply Ok(state)     07 07 01 07 00 00 00 04 01 02 01 02
+SetSplitCentralLatency request policy      07 07 01 04 00 00 04 01 02
diff --git a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
index bf9a130c7..957469293 100644
--- a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
@@ -2,7 +2,7 @@
 # File: snapshots/wire_values.snap
 # Each entry is the postcard byte encoding of one wire-type exemplar. A diff
 # here means a type's payload encoding changed (field reorder, variant
-# renumber, …). If intentional, bump ProtocolVersion::CURRENT and regenerate:
+# renumber, …). If intentional, regenerate and review compatibility:
 #   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk wire_values
 # Format: <label>  <hex bytes>
 
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index afb8f5cff..5389a19fc 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -5,8 +5,8 @@
 //! one postcard-encoded exemplar per wire type; `wire_frames.snap` holds one
 //! full frame (header + payload) per protocol message. Any field reorder /
 //! type change / variant renumber / CMD renumber flips the bytes and fails
-//! CI. If the change is intentional, bump `ProtocolVersion::CURRENT` and
-//! regenerate the snapshots.
+//! CI. If the change is intentional, regenerate the snapshots and review the
+//! compatibility impact. Protocol versions are minted upstream only.
 
 extern crate alloc;
 
@@ -159,7 +159,7 @@ mod snapshot {
                 "snapshot mismatch: {}\n\
                  --- expected ---\n{}\
                  --- actual ---\n{}\
-                 If intentional, regenerate with UPDATE_SNAPSHOTS=1 and bump ProtocolVersion::CURRENT.",
+                 If intentional, regenerate with UPDATE_SNAPSHOTS=1 and review protocol compatibility.",
                 path.display(),
                 expected,
                 actual,
@@ -326,7 +326,7 @@ fn exemplars() -> Exemplars {
 
 /// Lock down postcard's actual byte encoding for stability-critical
 /// values. A diff in this snapshot indicates wire-format drift; if
-/// intentional, regenerate the snapshot and bump `ProtocolVersion::CURRENT`.
+/// intentional, regenerate the snapshot and review protocol compatibility.
 ///
 /// One exemplar per Rynk wire type, plus every variant of the positional
 /// enums (`KeyAction`, `Action`, and the status enums) so a reordered or
@@ -356,6 +356,16 @@ fn wire_values_locked() {
         active_bitmap: [0x05, 0, 0, 0, 0, 0, 0, 0x80],
     };
     let profile = MorseProfile::new(None, Some(MorseMode::Normal), Some(200), Some(150));
+    let split_latency_policy = SplitCentralLatencyPolicy {
+        powered: 0,
+        battery: 4,
+        override_latency: Some(2),
+    };
+    let split_latency_state = SplitCentralLatencyState {
+        policy: split_latency_policy,
+        powered: true,
+        effective: 2,
+    };
 
     let entries: alloc::vec::Vec<(&str, alloc::vec::Vec<u8>)> = alloc::vec![
         // --- Response envelope + connection ---
@@ -476,6 +486,8 @@ fn wire_values_locked() {
         ("DeviceInfo{1.2.3,4,5,RMK,..}", encode(&ex.device_info)),
         ("BuildInfo{my-firmware..}", encode(&ex.build_info)),
         ("BehaviorConfig{50,500,200,20}", encode(&ex.behavior)),
+        ("SplitLatencyPolicy{0,4,Some(2)}", encode(&split_latency_policy),),
+        ("SplitLatencyState{policy,true,2}", encode(&split_latency_state),),
         ("ConnectionStatus{Configured,{1,Adv},Ble}", encode(&ex.connection)),
         ("ProtocolVersion{1,0}", encode(&ProtocolVersion { major: 1, minor: 0 })),
         ("ProtocolVersion::CURRENT", encode(&ProtocolVersion::CURRENT)),
@@ -571,7 +583,7 @@ fn wire_values_locked() {
         "Wire-format TYPE snapshot",
         "# Each entry is the postcard byte encoding of one wire-type exemplar. A diff\n\
          # here means a type's payload encoding changed (field reorder, variant\n\
-         # renumber, …). If intentional, bump ProtocolVersion::CURRENT and regenerate:",
+         # renumber, …). If intentional, regenerate and review compatibility:",
         "wire_values",
         &view,
     );
@@ -582,7 +594,7 @@ fn wire_values_locked() {
 /// COBS-encoded with a trailing `0x00` delimiter — one per feature-independent
 /// protocol message: every request, its `Ok` reply, a representative `Err`
 /// reply, and every topic push. A diff means the wire format changed; if
-/// intentional, regenerate and bump `ProtocolVersion::CURRENT`.
+/// intentional, regenerate and review protocol compatibility.
 ///
 /// Requests and replies use SEQ 1 (a reply echoes its request's SEQ); topics
 /// always use SEQ 0. The `GetVersion` probe and reply are frozen across all
@@ -986,13 +998,77 @@ fn wire_frames_locked() {
         "# Each entry is a full Rynk frame — a 3-byte header (CMD u16 LE + SEQ u8) + postcard\n\
          # payload, COBS-encoded with a trailing 0x00 delimiter — one per protocol message; the\n\
          # label names the decoded payload (`()` = empty). A diff means the header, a CMD number,\n\
-         # or a message frame changed. If intentional, bump ProtocolVersion::CURRENT and regenerate:",
+         # or a message frame changed. If intentional, regenerate and review protocol compatibility:",
         "wire_frames",
         &view,
     );
     snapshot::assert_snapshot("snapshots/wire_frames.snap", actual);
 }
 
+/// Split-BLE connection-policy commands have their own feature-gated golden
+/// file so the base snapshots remain identical for non-split builds.
+#[cfg(all(feature = "_ble", feature = "split"))]
+#[test]
+fn split_ble_wire_frames_locked() {
+    const SEQ: u8 = 1;
+    let policy = SplitCentralLatencyPolicy {
+        powered: 0,
+        battery: 4,
+        override_latency: Some(2),
+    };
+    let state = SplitCentralLatencyState {
+        policy,
+        powered: true,
+        effective: 2,
+    };
+    let entries: alloc::vec::Vec<(&str, alloc::vec::Vec<u8>)> = alloc::vec![
+        (
+            "GetSplitCentralLatency request ()",
+            encode_frame(Cmd::GetSplitCentralLatency, SEQ, &()),
+        ),
+        (
+            "GetSplitCentralLatency reply Ok(state)",
+            encode_frame(
+                Cmd::GetSplitCentralLatency,
+                SEQ,
+                &Ok::<SplitCentralLatencyState, RynkError>(state),
+            ),
+        ),
+        (
+            "SetSplitCentralLatency request policy",
+            encode_frame(Cmd::SetSplitCentralLatency, SEQ, &policy),
+        ),
+        (
+            "SetSplitCentralLatency reply Ok(state)",
+            encode_frame(
+                Cmd::SetSplitCentralLatency,
+                SEQ,
+                &Ok::<SplitCentralLatencyState, RynkError>(state),
+            ),
+        ),
+        (
+            "SetSplitCentralLatency reply Err(Invalid)",
+            encode_frame(
+                Cmd::SetSplitCentralLatency,
+                SEQ,
+                &Err::<SplitCentralLatencyState, RynkError>(RynkError::Invalid),
+            ),
+        ),
+    ];
+    let view: alloc::vec::Vec<(&str, &[u8])> = entries
+        .iter()
+        .map(|(label, bytes)| (*label, bytes.as_slice()))
+        .collect();
+    let actual = snapshot::format_value_snapshot(
+        "snapshots/split_ble_wire_frames.snap",
+        "Split BLE wire-format FRAME snapshot",
+        "# Each entry is one complete feature-gated split BLE latency-policy frame.",
+        "--features \"rynk _ble split\" split_ble_wire_frames",
+        &view,
+    );
+    snapshot::assert_snapshot("snapshots/split_ble_wire_frames.snap", actual);
+}
+
 /// Lighting has its own feature-gated golden file so the base Rynk snapshots
 /// remain identical for firmware builds that do not include lighting.
 #[cfg(feature = "lighting")]
@@ -1674,7 +1750,7 @@ mod protocol_reference {
     /// Pull the doc text (Notes) and `cfg` feature out of a row's stringified
     /// attributes. `///` docs stringify as raw strings `#[doc = r"…"]`, wrapping
     /// after `doc =` when long — hence the whitespace skip and raw-delimiter scan.
-    fn parse_attrs(attrs: &str) -> (String, Option<&str>) {
+    fn parse_attrs(attrs: &str) -> (String, Vec<String>) {
         let mut notes = String::new();
         let mut rest = attrs;
         while let Some(i) = rest.find("doc =") {
@@ -1694,11 +1770,20 @@ mod protocol_reference {
         }
         // Rustdoc intra-links render as broken md links; keep just the code span.
         let notes = notes.replace("[`", "`").replace("`]", "`");
-        let feature = attrs.find("feature = \"").and_then(|i| {
-            let s = &attrs[i + 11..];
-            s.find('"').map(|end| &s[..end])
-        });
-        (notes, feature)
+        let mut features = Vec::new();
+        let mut feature_attrs = attrs;
+        while let Some(i) = feature_attrs.find("feature = \"") {
+            let s = &feature_attrs[i + 11..];
+            let Some(end) = s.find('"') else {
+                break;
+            };
+            let feature = String::from(&s[..end]);
+            if !features.contains(&feature) {
+                features.push(feature);
+            }
+            feature_attrs = &s[end + 1..];
+        }
+        (notes, features)
     }
 
     /// Render `rows` as a column-aligned GFM table.
@@ -1737,7 +1822,7 @@ mod protocol_reference {
                      attrs,
                  }| {
                     let (notes, feature) = parse_attrs(attrs);
-                    let feature = feature.map(|f| format!("`{f}`")).unwrap_or_default();
+                    let feature = feature.iter().map(|f| format!("`{f}`")).collect::<Vec<_>>().join(" + ");
                     alloc::vec![
                         format!("`0x{cmd:04X}`"),
                         format!("`{name}`"),
@@ -1766,7 +1851,7 @@ mod protocol_reference {
                         format!("`0x{cmd:04X}`"),
                         format!("`{name}`"),
                         format!("`{payload}`"),
-                        feature.map(|f| format!("`{f}`")).unwrap_or_default(),
+                        feature.iter().map(|f| format!("`{f}`")).collect::<Vec<_>>().join(" + "),
                         notes,
                     ]
                 },
diff --git a/rmk/src/host/rynk/handlers/connection.rs b/rmk/src/host/rynk/handlers/connection.rs
index 2c7096a9d..56321e7b3 100644
--- a/rmk/src/host/rynk/handlers/connection.rs
+++ b/rmk/src/host/rynk/handlers/connection.rs
@@ -7,10 +7,47 @@ use rmk_types::protocol::rynk::RynkError;
 #[cfg(feature = "_ble")]
 use rmk_types::protocol::rynk::command::{ClearBleProfile, GetBleStatus, SwitchBleProfile};
 use rmk_types::protocol::rynk::command::{GetConnectionStatus, GetConnectionType};
+#[cfg(all(feature = "_ble", feature = "split"))]
+use rmk_types::protocol::rynk::command::{GetSplitCentralLatency, SetSplitCentralLatency};
+#[cfg(all(feature = "_ble", feature = "split"))]
+use rmk_types::protocol::rynk::{SplitCentralLatencyPolicy, SplitCentralLatencyState};
 
 use super::super::RynkService;
 use super::Handle;
 
+#[cfg(all(feature = "_ble", feature = "split"))]
+impl From<crate::split::ble::central::LatencyPolicy> for SplitCentralLatencyPolicy {
+    fn from(value: crate::split::ble::central::LatencyPolicy) -> Self {
+        Self {
+            powered: value.powered,
+            battery: value.battery,
+            override_latency: value.override_latency,
+        }
+    }
+}
+
+#[cfg(all(feature = "_ble", feature = "split"))]
+impl From<SplitCentralLatencyPolicy> for crate::split::ble::central::LatencyPolicy {
+    fn from(value: SplitCentralLatencyPolicy) -> Self {
+        Self {
+            powered: value.powered,
+            battery: value.battery,
+            override_latency: value.override_latency,
+        }
+    }
+}
+
+#[cfg(all(feature = "_ble", feature = "split"))]
+impl From<crate::split::ble::central::LatencyState> for SplitCentralLatencyState {
+    fn from(value: crate::split::ble::central::LatencyState) -> Self {
+        Self {
+            policy: value.policy.into(),
+            powered: value.powered,
+            effective: value.effective,
+        }
+    }
+}
+
 impl Handle<GetConnectionType> for RynkService<'_> {
     async fn handle(&self, _: ()) -> Result<ConnectionType, RynkError> {
         Ok(self.ctx.preferred_connection())
@@ -25,6 +62,21 @@ impl Handle<GetConnectionStatus> for RynkService<'_> {
     }
 }
 
+#[cfg(all(feature = "_ble", feature = "split"))]
+impl Handle<GetSplitCentralLatency> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<SplitCentralLatencyState, RynkError> {
+        Ok(crate::split::ble::central::latency_state().into())
+    }
+}
+
+#[cfg(all(feature = "_ble", feature = "split"))]
+impl Handle<SetSplitCentralLatency> for RynkService<'_> {
+    async fn handle(&self, policy: SplitCentralLatencyPolicy) -> Result<SplitCentralLatencyState, RynkError> {
+        crate::split::ble::central::set_latency_policy(policy.into()).map_err(|_| RynkError::Invalid)?;
+        Ok(crate::split::ble::central::latency_state().into())
+    }
+}
+
 #[cfg(feature = "_ble")]
 impl Handle<GetBleStatus> for RynkService<'_> {
     async fn handle(&self, _: ()) -> Result<BleStatus, RynkError> {
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 1c50f6118..818f6df69 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -146,6 +146,8 @@ impl<'a> RynkService<'a> {
             // Deleting a bond opens a re-pair hijack window; BLE-only command.
             #[cfg(feature = "_ble")]
             Cmd::ClearBleProfile => true,
+            #[cfg(all(feature = "_ble", feature = "split"))]
+            Cmd::SetSplitCentralLatency => self.lock_config.write_requires_unlock,
             Cmd::SetKeyAction
             | Cmd::SetDefaultLayer
             | Cmd::SetEncoderAction
@@ -239,6 +241,10 @@ impl<'a> RynkService<'a> {
             Cmd::SwitchBleProfile => serve::<command::SwitchBleProfile, _>(self, msg).await,
             #[cfg(feature = "_ble")]
             Cmd::ClearBleProfile => serve::<command::ClearBleProfile, _>(self, msg).await,
+            #[cfg(all(feature = "_ble", feature = "split"))]
+            Cmd::GetSplitCentralLatency => serve::<command::GetSplitCentralLatency, _>(self, msg).await,
+            #[cfg(all(feature = "_ble", feature = "split"))]
+            Cmd::SetSplitCentralLatency => serve::<command::SetSplitCentralLatency, _>(self, msg).await,
 
             Cmd::GetCurrentLayer => serve::<command::GetCurrentLayer, _>(self, msg).await,
             Cmd::GetMatrixState => serve::<command::GetMatrixState, _>(self, msg).await,
diff --git a/rmk/src/split/ble/central.rs b/rmk/src/split/ble/central.rs
index 3bc41408f..b1d249128 100644
--- a/rmk/src/split/ble/central.rs
+++ b/rmk/src/split/ble/central.rs
@@ -3,7 +3,9 @@ use core::cell::Cell;
 use bt_hci::cmd::le::{LeReadLocalSupportedFeatures, LeSetPhy, LeSetScanParams};
 use bt_hci::controller::{ControllerCmdAsync, ControllerCmdSync};
 use embassy_futures::select::{Either, Either3, select, select3};
+use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
 use embassy_sync::mutex::Mutex;
+use embassy_sync::pubsub::PubSubChannel;
 use embassy_sync::signal::Signal;
 use embassy_time::{Duration, Timer, with_timeout};
 use trouble_host::prelude::*;
@@ -17,6 +19,7 @@ use crate::split::ble::PeerAddress;
 use crate::split::driver::{PeripheralManager, SplitDriverError, SplitReader, SplitWriter, set_peripheral_connected};
 use crate::split::{PeripheralMatrixConfig, SPLIT_MESSAGE_MAX_SIZE, SplitMessage};
 use crate::storage::FlashOperationMessage;
+use crate::{SPLIT_CENTRAL_MAX_LATENCY_BATTERY, SPLIT_CENTRAL_MAX_LATENCY_POWERED};
 
 pub(crate) static STACK_STARTED: Signal<crate::RawMutex, bool> = Signal::new();
 static PERIPHERAL_FOUND: Signal<crate::RawMutex, (u8, BdAddr)> = Signal::new();
@@ -33,6 +36,126 @@ const SPLIT_SERVICE_UUID: [u8; 16] = [
     70u8, 153u8, 101u8, 152u8, 54u8, 53u8, 10u8, 191u8, 7u8, 75u8, 229u8, 24u8, 170u8, 251u8, 213u8, 77u8,
 ];
 
+/// Runtime active-mode split BLE latency policy.
+///
+/// Changes are volatile and take effect on connected peripherals immediately.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LatencyPolicy {
+    pub powered: u16,
+    pub battery: u16,
+    pub override_latency: Option<u16>,
+}
+
+/// Current policy inputs and selected active-mode latency.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LatencyState {
+    pub policy: LatencyPolicy,
+    pub powered: bool,
+    pub effective: u16,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct InvalidLatency;
+
+impl LatencyPolicy {
+    fn effective(self, powered: bool) -> u16 {
+        self.override_latency
+            .unwrap_or(if powered { self.powered } else { self.battery })
+    }
+
+    fn is_valid(self) -> bool {
+        self.powered < 500 && self.battery < 500 && self.override_latency.is_none_or(|value| value < 500)
+    }
+}
+
+static LATENCY_POLICY: BlockingMutex<crate::RawMutex, Cell<LatencyPolicy>> =
+    BlockingMutex::new(Cell::new(LatencyPolicy {
+        powered: SPLIT_CENTRAL_MAX_LATENCY_POWERED,
+        battery: SPLIT_CENTRAL_MAX_LATENCY_BATTERY,
+        override_latency: None,
+    }));
+static LATENCY_CHANGED: PubSubChannel<crate::RawMutex, (), 1, 8, 1> = PubSubChannel::new();
+
+fn externally_powered() -> bool {
+    crate::state::current_usb_state() != rmk_types::connection::UsbState::Disabled
+}
+
+pub fn latency_state() -> LatencyState {
+    let policy = LATENCY_POLICY.lock(Cell::get);
+    let powered = externally_powered();
+    let effective = policy.effective(powered);
+    LatencyState {
+        policy,
+        powered,
+        effective,
+    }
+}
+
+/// Replace the volatile latency policy and update live split connections.
+pub fn set_latency_policy(policy: LatencyPolicy) -> Result<(), InvalidLatency> {
+    if !policy.is_valid() {
+        return Err(InvalidLatency);
+    }
+    LATENCY_POLICY.lock(|current| current.set(policy));
+    LATENCY_CHANGED.immediate_publisher().publish_immediate(());
+    Ok(())
+}
+
+#[cfg(test)]
+mod latency_tests {
+    use super::*;
+
+    #[test]
+    fn policy_selects_power_source_unless_overridden() {
+        let policy = LatencyPolicy {
+            powered: 0,
+            battery: 4,
+            override_latency: None,
+        };
+        assert_eq!(policy.effective(true), 0);
+        assert_eq!(policy.effective(false), 4);
+        assert_eq!(
+            LatencyPolicy {
+                override_latency: Some(2),
+                ..policy
+            }
+            .effective(true),
+            2
+        );
+        assert_eq!(
+            LatencyPolicy {
+                override_latency: Some(2),
+                ..policy
+            }
+            .effective(false),
+            2
+        );
+    }
+
+    #[test]
+    fn policy_rejects_values_outside_the_ble_limit() {
+        let valid = LatencyPolicy {
+            powered: 499,
+            battery: 499,
+            override_latency: Some(499),
+        };
+        assert!(valid.is_valid());
+        assert!(!LatencyPolicy { powered: 500, ..valid }.is_valid());
+        assert!(!LatencyPolicy { battery: 500, ..valid }.is_valid());
+        assert!(
+            !LatencyPolicy {
+                override_latency: Some(500),
+                ..valid
+            }
+            .is_valid()
+        );
+    }
+}
+
+pub(crate) fn power_source_changed() {
+    LATENCY_CHANGED.immediate_publisher().publish_immediate(());
+}
+
 pub(crate) async fn scan_peripherals<
     C: Controller
         + ControllerCmdSync<LeSetScanParams>
@@ -220,7 +343,7 @@ fn default_central_conn_param() -> RequestedConnParams {
     RequestedConnParams {
         min_connection_interval: Duration::from_micros(7500),
         max_connection_interval: Duration::from_micros(7500),
-        max_latency: 10, // 75ms
+        max_latency: latency_state().effective,
         supervision_timeout: Duration::from_secs(5),
         ..Default::default()
     }
@@ -421,6 +544,12 @@ async fn follow_sleep_state<
     conn: &Connection<'b, P>,
 ) -> Result<(), BleHostError<C::Error>> {
     let mut sleep_events = SleepStateEvent::subscriber();
+    // Sleep management may be disabled entirely, in which case no sleep event
+    // ever arrives — but a runtime policy change or a USB-power transition
+    // still has to reach the live connection.
+    let mut latency_changes = LATENCY_CHANGED
+        .subscriber()
+        .expect("split latency policy supports eight peripheral managers");
 
     // A peripheral coming up is activity in its own right: it needs the fast
     // parameters for service discovery, and waking the whole keyboard keeps
@@ -433,10 +562,19 @@ async fn follow_sleep_state<
     // the wrong interval until it reconnects.
     let mut applied = false;
     loop {
-        let sleeping = sleep_events.next_event().await.0;
-        if sleeping == applied {
-            continue;
-        }
+        let sleeping = match select(sleep_events.next_event(), latency_changes.next_message_pure()).await {
+            Either::First(event) => {
+                let sleeping = event.0;
+                if sleeping == applied {
+                    continue;
+                }
+                sleeping
+            }
+            // The policy or the power source moved. Re-apply the parameters for
+            // the mode this link is already in, so a latency change reaches a
+            // connection that is not also changing sleep state.
+            Either::Second(()) => applied,
+        };
         let params = if sleeping {
             sleep_central_conn_param()
         } else {
diff --git a/rmk/src/state.rs b/rmk/src/state.rs
index d085839dd..6f021233b 100644
--- a/rmk/src/state.rs
+++ b/rmk/src/state.rs
@@ -107,6 +107,11 @@ pub(crate) fn update_status(f: impl FnOnce(&mut ConnectionStatus)) {
         crate::channel::clear_and_release_report_channel(prev_active);
     }
 
+    #[cfg(all(feature = "_ble", feature = "split"))]
+    if prev.usb != new.usb {
+        crate::split::ble::central::power_source_changed();
+    }
+
     publish_event(ConnectionStatusChangeEvent(new));
 }
 
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index c7183f400..89dc519f7 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -34,7 +34,7 @@ use rynk::rmk_types::protocol::rynk::{
     CommitLightingSceneReplaceRequest, LightingScenePageRequest, LightingSceneStatus, LightingSceneTransaction,
     LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingSceneCellRequest,
     UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus, LightingCompiledScenesPage,
-    LightingOverlayPage, LightingOverlayPageRequest,
+    LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy, SplitCentralLatencyState,
 };
 use rynk::{Client, Driver, LayoutInfo, RynkDevice, RynkHostError, TopicEvent};
 use wasm_bindgen::prelude::*;
@@ -161,6 +161,8 @@ endpoints! {
     // behavior
     get_behavior() -> BehaviorConfig,
     set_behavior(config: BehaviorConfig) -> (),
+    get_split_central_latency() -> SplitCentralLatencyState,
+    set_split_central_latency(policy: SplitCentralLatencyPolicy) -> SplitCentralLatencyState,
     // status
     get_current_layer() -> u8,
     get_layer_state() -> LayerState,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 2e6b15966..0d7d8a965 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -35,7 +35,8 @@ use rmk_types::protocol::rynk::{
     StorageResetMode, UnsetLightingOverlayRequest, command, BuildInfo, LightingScenePageRequest, LightingSceneStatus,
     LightingSceneTransaction, LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest,
     SetLightingSceneCellRequest, UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus,
-    LightingCompiledScenesPage, LightingOverlayPage, LightingOverlayPageRequest,
+    LightingCompiledScenesPage, LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy,
+    SplitCentralLatencyState,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -649,6 +650,19 @@ impl Client {
         self.request::<command::GetConnectionStatus>(&()).await
     }
 
+    /// Read active split BLE latency defaults, override, and effective value.
+    pub async fn get_split_central_latency(&self) -> Result<SplitCentralLatencyState, RynkHostError> {
+        self.request::<command::GetSplitCentralLatency>(&()).await
+    }
+
+    /// Replace the volatile active split BLE latency policy.
+    pub async fn set_split_central_latency(
+        &self,
+        policy: SplitCentralLatencyPolicy,
+    ) -> Result<SplitCentralLatencyState, RynkHostError> {
+        self.request::<command::SetSplitCentralLatency>(&policy).await
+    }
+
     /// Read BLE status (active profile, connection state). Requires
     /// [`DeviceCapabilities::ble_enabled`]; nothing is sent otherwise.
     pub async fn get_ble_status(&self) -> Result<BleStatus, RynkHostError> {

From 017ac307952dfbca6aaaaca33d63f89840b2f3e9 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 04:52:46 -0700
Subject: [PATCH 22/78] feat(lighting): add declarative conditional scenes

---
 .../main/docs/development/rynk_protocol.md    | 164 ++++++------
 rmk-config/src/lib.rs                         |  39 +++
 rmk-config/src/resolved/lighting.rs           | 242 +++++++++++++++---
 rmk-macro/src/codegen/lighting.rs             |  74 +++++-
 rmk-types/src/protocol/rynk/command.rs        |  21 +-
 .../src/protocol/rynk/payload/lighting.rs     | 114 +++++++++
 rmk/src/host/rynk/handlers/lighting.rs        | 126 +++++++--
 rmk/src/host/rynk/lighting.rs                 |  58 ++++-
 rmk/src/host/rynk/mod.rs                      |   8 +
 rmk/src/lighting/mod.rs                       |   5 +-
 rmk/src/lighting/source.rs                    | 212 +++++++++++++++
 rynk/rynk-wasm/src/client.rs                  |   5 +-
 rynk/src/api.rs                               |  75 +++++-
 13 files changed, 992 insertions(+), 151 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 8c63e39e7..612d2420a 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -213,87 +213,89 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x0918` | `CommitLightingSceneReplace`   | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`               | `lighting` |                                                                                                                                |
 | `0x0919` | `AbortLightingSceneReplace`    | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                | `lighting` |                                                                                                                                |
 | `0x091A` | `SetLightingLayerPolicy`       | `SetLightingLayerPolicyRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| CMD      | Name                             | Request                               | Response                            | Feature          | Notes                                                                                                                          |
-| -------- | -------------------------------- | ------------------------------------- | ----------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `0x0001` | `GetVersion`                     | `()`                                  | `ProtocolVersion`                   |                  |                                                                                                                                |
-| `0x0002` | `GetCapabilities`                | `()`                                  | `DeviceCapabilities`                |                  |                                                                                                                                |
-| `0x0003` | `Reboot`                         | `()`                                  | `()`                                |                  |                                                                                                                                |
-| `0x0004` | `BootloaderJump`                 | `()`                                  | `()`                                |                  |                                                                                                                                |
-| `0x0005` | `StorageReset`                   | `StorageResetMode`                    | `()`                                |                  |                                                                                                                                |
-| `0x0006` | `GetLockStatus`                  | `()`                                  | `LockStatus`                        |                  | Pure read of the current lock state — no side effects.                                                                         |
-| `0x0007` | `UnlockPoll`                     | `()`                                  | `LockStatus`                        |                  | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                         |
-| `0x0008` | `Lock`                           | `()`                                  | `()`                                |                  | Relock immediately.                                                                                                            |
-| `0x0009` | `GetLayout`                      | `u32`                                 | `LayoutChunk`                       |                  | Get layout blob chunk. `u32` is the byte offset.                                                                               |
-| `0x000A` | `GetDeviceInfo`                  | `()`                                  | `DeviceInfo`                        |                  | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                       |
-| `0x000B` | `GetBuildInfo`                   | `()`                                  | `BuildInfo`                         |                  | Application-defined diagnostic build label; never used for compatibility.                                                      |
-| `0x000C` | `PeripheralBootloaderJump`       | `u8`                                  | `()`                                |                  | Ask the application to route a bootloader jump to one split peripheral.                                                        |
-| `0x0101` | `GetKeyAction`                   | `KeyPosition`                         | `KeyAction`                         |                  |                                                                                                                                |
-| `0x0102` | `SetKeyAction`                   | `SetKeyRequest`                       | `()`                                |                  |                                                                                                                                |
-| `0x0103` | `GetDefaultLayer`                | `()`                                  | `u8`                                |                  |                                                                                                                                |
-| `0x0104` | `SetDefaultLayer`                | `u8`                                  | `()`                                |                  |                                                                                                                                |
-| `0x0105` | `GetEncoderAction`               | `GetEncoderRequest`                   | `EncoderAction`                     |                  |                                                                                                                                |
-| `0x0106` | `SetEncoderAction`               | `SetEncoderRequest`                   | `()`                                |                  |                                                                                                                                |
-| `0x0107` | `GetKeymapBulk`                  | `GetKeymapBulkRequest`                | `GetKeymapBulkResponse`             |                  |                                                                                                                                |
-| `0x0108` | `SetKeymapBulk`                  | `SetKeymapBulkRequest`                | `()`                                |                  |                                                                                                                                |
-| `0x0201` | `GetMacro`                       | `GetMacroRequest`                     | `MacroData`                         |                  |                                                                                                                                |
-| `0x0202` | `SetMacro`                       | `SetMacroRequest`                     | `()`                                |                  |                                                                                                                                |
-| `0x0301` | `GetCombo`                       | `u8`                                  | `Combo`                             |                  |                                                                                                                                |
-| `0x0302` | `SetCombo`                       | `SetComboRequest`                     | `()`                                |                  |                                                                                                                                |
-| `0x0303` | `GetComboBulk`                   | `GetComboBulkRequest`                 | `GetComboBulkResponse`              |                  |                                                                                                                                |
-| `0x0304` | `SetComboBulk`                   | `SetComboBulkRequest`                 | `()`                                |                  |                                                                                                                                |
-| `0x0401` | `GetMorse`                       | `u8`                                  | `Morse`                             |                  |                                                                                                                                |
-| `0x0402` | `SetMorse`                       | `SetMorseRequest`                     | `()`                                |                  |                                                                                                                                |
-| `0x0403` | `GetMorseBulk`                   | `GetMorseBulkRequest`                 | `GetMorseBulkResponse`              |                  |                                                                                                                                |
-| `0x0404` | `SetMorseBulk`                   | `SetMorseBulkRequest`                 | `()`                                |                  |                                                                                                                                |
-| `0x0501` | `GetFork`                        | `u8`                                  | `Fork`                              |                  |                                                                                                                                |
-| `0x0502` | `SetFork`                        | `SetForkRequest`                      | `()`                                |                  |                                                                                                                                |
-| `0x0601` | `GetBehaviorConfig`              | `()`                                  | `BehaviorConfig`                    |                  |                                                                                                                                |
-| `0x0602` | `SetBehaviorConfig`              | `BehaviorConfig`                      | `()`                                |                  |                                                                                                                                |
-| `0x0701` | `GetConnectionType`              | `()`                                  | `ConnectionType`                    |                  |                                                                                                                                |
-| `0x0702` | `GetConnectionStatus`            | `()`                                  | `ConnectionStatus`                  |                  | Full `ConnectionStatus` snapshot.                                                                                              |
-| `0x0703` | `GetBleStatus`                   | `()`                                  | `BleStatus`                         | `_ble`           |                                                                                                                                |
-| `0x0704` | `SwitchBleProfile`               | `u8`                                  | `()`                                | `_ble`           |                                                                                                                                |
-| `0x0705` | `ClearBleProfile`                | `u8`                                  | `()`                                | `_ble`           |                                                                                                                                |
-| `0x0706` | `GetSplitCentralLatency`         | `()`                                  | `SplitCentralLatencyState`          | `_ble` + `split` | Read the volatile active-mode policy, current USB-power selection, and effective value.                                        |
-| `0x0707` | `SetSplitCentralLatency`         | `SplitCentralLatencyPolicy`           | `SplitCentralLatencyState`          | `_ble` + `split` | Replace the volatile policy. Each connection-event count must be `0..=499`.                                                    |
-| `0x0801` | `GetCurrentLayer`                | `()`                                  | `u8`                                |                  |                                                                                                                                |
-| `0x0802` | `GetMatrixState`                 | `()`                                  | `MatrixState`                       |                  |                                                                                                                                |
-| `0x0803` | `GetBatteryStatus`               | `()`                                  | `BatteryStatus`                     | `_ble`           |                                                                                                                                |
-| `0x0804` | `GetPeripheralStatus`            | `u8`                                  | `PeripheralStatus`                  | `split`          |                                                                                                                                |
-| `0x0805` | `GetWpm`                         | `()`                                  | `u16`                               |                  | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                       |
-| `0x0806` | `GetSleepState`                  | `()`                                  | `bool`                              |                  | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                               |
-| `0x0807` | `GetLedIndicator`                | `()`                                  | `LedIndicator`                      |                  | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                   |
-| `0x0808` | `GetLayerState`                  | `()`                                  | `LayerState`                        |                  | Default layer and complete active-layer bitmap.                                                                                |
-| `0x0809` | `GetModifierState`               | `()`                                  | `ModifierCombination`               |                  | Final resolved modifier bitmap used by the HID keyboard report.                                                                |
-| `0x0901` | `GetLightingCapabilities`        | `()`                                  | `LightingCapabilitiesResult`        | `lighting`       |                                                                                                                                |
-| `0x0902` | `GetLightingState`               | `()`                                  | `LightingStateResult`               | `lighting`       |                                                                                                                                |
-| `0x0903` | `SetLightingState`               | `SetLightingStateRequest`             | `LightingStateResult`               | `lighting`       |                                                                                                                                |
-| `0x0904` | `GetLightingPhysicalKeys`        | `LightingPageRequest`                 | `LightingPhysicalKeysPageResult`    | `lighting`       |                                                                                                                                |
-| `0x0905` | `GetLightingLeds`                | `LightingPageRequest`                 | `LightingLedsPageResult`            | `lighting`       |                                                                                                                                |
-| `0x0906` | `GetLightingZones`               | `LightingPageRequest`                 | `LightingZonesPageResult`           | `lighting`       |                                                                                                                                |
-| `0x0907` | `GetLightingZoneMemberships`     | `LightingPageRequest`                 | `LightingZoneMembershipsPageResult` | `lighting`       |                                                                                                                                |
-| `0x0908` | `GetLightingOutputs`             | `LightingPageRequest`                 | `LightingOutputsPageResult`         | `lighting`       |                                                                                                                                |
-| `0x0909` | `GetLightingRoutes`              | `LightingPageRequest`                 | `LightingRoutesPageResult`          | `lighting`       |                                                                                                                                |
-| `0x090A` | `SetLightingOverlay`             | `SetLightingOverlayRequest`           | `LightingStateResult`               | `lighting`       |                                                                                                                                |
-| `0x090B` | `UnsetLightingOverlay`           | `UnsetLightingOverlayRequest`         | `LightingStateResult`               | `lighting`       |                                                                                                                                |
-| `0x090C` | `ClearLightingOverlay`           | `ClearLightingOverlayRequest`         | `LightingStateResult`               | `lighting`       |                                                                                                                                |
-| `0x090D` | `BeginLightingOverlayReplace`    | `BeginLightingOverlayReplaceRequest`  | `LightingOverlayTransactionResult`  | `lighting`       |                                                                                                                                |
-| `0x090E` | `PutLightingOverlayChunk`        | `PutLightingOverlayChunkRequest`      | `LightingUnitResult`                | `lighting`       |                                                                                                                                |
-| `0x090F` | `CommitLightingOverlayReplace`   | `CommitLightingOverlayReplaceRequest` | `LightingStateResult`               | `lighting`       |                                                                                                                                |
-| `0x0910` | `AbortLightingOverlayReplace`    | `AbortLightingOverlayReplaceRequest`  | `LightingUnitResult`                | `lighting`       |                                                                                                                                |
-| `0x0911` | `GetLightingKeys`                | `LightingPageRequest`                 | `LightingKeysPageResult`            | `lighting`       | Logical matrix keys are distinct from optional physical geometry.                                                              |
-| `0x0912` | `GetLightingSceneStatus`         | `()`                                  | `LightingSceneStatusResult`         | `lighting`       | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts. |
-| `0x0913` | `GetLightingScenes`              | `LightingScenePageRequest`            | `LightingScenesPageResult`          | `lighting`       | Scene pages are pinned to `LightingState.revision` for consistency.                                                            |
-| `0x0914` | `SetLightingSceneCell`           | `SetLightingSceneCellRequest`         | `LightingStateResult`               | `lighting`       |                                                                                                                                |
-| `0x0915` | `UnsetLightingSceneCell`         | `UnsetLightingSceneCellRequest`       | `LightingStateResult`               | `lighting`       |                                                                                                                                |
-| `0x0916` | `BeginLightingSceneReplace`      | `BeginLightingSceneReplaceRequest`    | `LightingSceneTransactionResult`    | `lighting`       |                                                                                                                                |
-| `0x0917` | `PutLightingSceneChunk`          | `PutLightingSceneChunkRequest`        | `LightingUnitResult`                | `lighting`       |                                                                                                                                |
-| `0x0918` | `CommitLightingSceneReplace`     | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`               | `lighting`       |                                                                                                                                |
-| `0x0919` | `AbortLightingSceneReplace`      | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                | `lighting`       |                                                                                                                                |
-| `0x091A` | `SetLightingLayerPolicy`         | `SetLightingLayerPolicyRequest`       | `LightingStateResult`               | `lighting`       |                                                                                                                                |
-| `0x091B` | `GetLightingOverlay`             | `LightingOverlayPageRequest`          | `LightingOverlayPageResult`         | `lighting`       | Overlay pages are pinned to `LightingState.revision` for consistency.                                                          |
-| `0x091C` | `GetLightingCompiledSceneStatus` | `()`                                  | `LightingCompiledSceneStatusResult` | `lighting`       | Discover the immutable board-compiled layer-scene source.                                                                      |
-| `0x091D` | `GetLightingCompiledScenes`      | `LightingPageRequest`                 | `LightingCompiledScenesPageResult`  | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                             |
+| CMD      | Name                                | Request                               | Response                               | Feature          | Notes                                                                                                                          |
+| -------- | ----------------------------------- | ------------------------------------- | -------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `0x0001` | `GetVersion`                        | `()`                                  | `ProtocolVersion`                      |                  |                                                                                                                                |
+| `0x0002` | `GetCapabilities`                   | `()`                                  | `DeviceCapabilities`                   |                  |                                                                                                                                |
+| `0x0003` | `Reboot`                            | `()`                                  | `()`                                   |                  |                                                                                                                                |
+| `0x0004` | `BootloaderJump`                    | `()`                                  | `()`                                   |                  |                                                                                                                                |
+| `0x0005` | `StorageReset`                      | `StorageResetMode`                    | `()`                                   |                  |                                                                                                                                |
+| `0x0006` | `GetLockStatus`                     | `()`                                  | `LockStatus`                           |                  | Pure read of the current lock state — no side effects.                                                                         |
+| `0x0007` | `UnlockPoll`                        | `()`                                  | `LockStatus`                           |                  | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                         |
+| `0x0008` | `Lock`                              | `()`                                  | `()`                                   |                  | Relock immediately.                                                                                                            |
+| `0x0009` | `GetLayout`                         | `u32`                                 | `LayoutChunk`                          |                  | Get layout blob chunk. `u32` is the byte offset.                                                                               |
+| `0x000A` | `GetDeviceInfo`                     | `()`                                  | `DeviceInfo`                           |                  | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                       |
+| `0x000B` | `GetBuildInfo`                      | `()`                                  | `BuildInfo`                            |                  | Application-defined diagnostic build label; never used for compatibility.                                                      |
+| `0x000C` | `PeripheralBootloaderJump`          | `u8`                                  | `()`                                   |                  | Ask the application to route a bootloader jump to one split peripheral.                                                        |
+| `0x0101` | `GetKeyAction`                      | `KeyPosition`                         | `KeyAction`                            |                  |                                                                                                                                |
+| `0x0102` | `SetKeyAction`                      | `SetKeyRequest`                       | `()`                                   |                  |                                                                                                                                |
+| `0x0103` | `GetDefaultLayer`                   | `()`                                  | `u8`                                   |                  |                                                                                                                                |
+| `0x0104` | `SetDefaultLayer`                   | `u8`                                  | `()`                                   |                  |                                                                                                                                |
+| `0x0105` | `GetEncoderAction`                  | `GetEncoderRequest`                   | `EncoderAction`                        |                  |                                                                                                                                |
+| `0x0106` | `SetEncoderAction`                  | `SetEncoderRequest`                   | `()`                                   |                  |                                                                                                                                |
+| `0x0107` | `GetKeymapBulk`                     | `GetKeymapBulkRequest`                | `GetKeymapBulkResponse`                |                  |                                                                                                                                |
+| `0x0108` | `SetKeymapBulk`                     | `SetKeymapBulkRequest`                | `()`                                   |                  |                                                                                                                                |
+| `0x0201` | `GetMacro`                          | `GetMacroRequest`                     | `MacroData`                            |                  |                                                                                                                                |
+| `0x0202` | `SetMacro`                          | `SetMacroRequest`                     | `()`                                   |                  |                                                                                                                                |
+| `0x0301` | `GetCombo`                          | `u8`                                  | `Combo`                                |                  |                                                                                                                                |
+| `0x0302` | `SetCombo`                          | `SetComboRequest`                     | `()`                                   |                  |                                                                                                                                |
+| `0x0303` | `GetComboBulk`                      | `GetComboBulkRequest`                 | `GetComboBulkResponse`                 |                  |                                                                                                                                |
+| `0x0304` | `SetComboBulk`                      | `SetComboBulkRequest`                 | `()`                                   |                  |                                                                                                                                |
+| `0x0401` | `GetMorse`                          | `u8`                                  | `Morse`                                |                  |                                                                                                                                |
+| `0x0402` | `SetMorse`                          | `SetMorseRequest`                     | `()`                                   |                  |                                                                                                                                |
+| `0x0403` | `GetMorseBulk`                      | `GetMorseBulkRequest`                 | `GetMorseBulkResponse`                 |                  |                                                                                                                                |
+| `0x0404` | `SetMorseBulk`                      | `SetMorseBulkRequest`                 | `()`                                   |                  |                                                                                                                                |
+| `0x0501` | `GetFork`                           | `u8`                                  | `Fork`                                 |                  |                                                                                                                                |
+| `0x0502` | `SetFork`                           | `SetForkRequest`                      | `()`                                   |                  |                                                                                                                                |
+| `0x0601` | `GetBehaviorConfig`                 | `()`                                  | `BehaviorConfig`                       |                  |                                                                                                                                |
+| `0x0602` | `SetBehaviorConfig`                 | `BehaviorConfig`                      | `()`                                   |                  |                                                                                                                                |
+| `0x0701` | `GetConnectionType`                 | `()`                                  | `ConnectionType`                       |                  |                                                                                                                                |
+| `0x0702` | `GetConnectionStatus`               | `()`                                  | `ConnectionStatus`                     |                  | Full `ConnectionStatus` snapshot.                                                                                              |
+| `0x0703` | `GetBleStatus`                      | `()`                                  | `BleStatus`                            | `_ble`           |                                                                                                                                |
+| `0x0704` | `SwitchBleProfile`                  | `u8`                                  | `()`                                   | `_ble`           |                                                                                                                                |
+| `0x0705` | `ClearBleProfile`                   | `u8`                                  | `()`                                   | `_ble`           |                                                                                                                                |
+| `0x0706` | `GetSplitCentralLatency`            | `()`                                  | `SplitCentralLatencyState`             | `_ble` + `split` | Read the volatile active-mode policy, current USB-power selection, and effective value.                                        |
+| `0x0707` | `SetSplitCentralLatency`            | `SplitCentralLatencyPolicy`           | `SplitCentralLatencyState`             | `_ble` + `split` | Replace the volatile policy. Each connection-event count must be `0..=499`.                                                    |
+| `0x0801` | `GetCurrentLayer`                   | `()`                                  | `u8`                                   |                  |                                                                                                                                |
+| `0x0802` | `GetMatrixState`                    | `()`                                  | `MatrixState`                          |                  |                                                                                                                                |
+| `0x0803` | `GetBatteryStatus`                  | `()`                                  | `BatteryStatus`                        | `_ble`           |                                                                                                                                |
+| `0x0804` | `GetPeripheralStatus`               | `u8`                                  | `PeripheralStatus`                     | `split`          |                                                                                                                                |
+| `0x0805` | `GetWpm`                            | `()`                                  | `u16`                                  |                  | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                       |
+| `0x0806` | `GetSleepState`                     | `()`                                  | `bool`                                 |                  | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                               |
+| `0x0807` | `GetLedIndicator`                   | `()`                                  | `LedIndicator`                         |                  | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                   |
+| `0x0808` | `GetLayerState`                     | `()`                                  | `LayerState`                           |                  | Default layer and complete active-layer bitmap.                                                                                |
+| `0x0809` | `GetModifierState`                  | `()`                                  | `ModifierCombination`                  |                  | Final resolved modifier bitmap used by the HID keyboard report.                                                                |
+| `0x0901` | `GetLightingCapabilities`           | `()`                                  | `LightingCapabilitiesResult`           | `lighting`       |                                                                                                                                |
+| `0x0902` | `GetLightingState`                  | `()`                                  | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
+| `0x0903` | `SetLightingState`                  | `SetLightingStateRequest`             | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
+| `0x0904` | `GetLightingPhysicalKeys`           | `LightingPageRequest`                 | `LightingPhysicalKeysPageResult`       | `lighting`       |                                                                                                                                |
+| `0x0905` | `GetLightingLeds`                   | `LightingPageRequest`                 | `LightingLedsPageResult`               | `lighting`       |                                                                                                                                |
+| `0x0906` | `GetLightingZones`                  | `LightingPageRequest`                 | `LightingZonesPageResult`              | `lighting`       |                                                                                                                                |
+| `0x0907` | `GetLightingZoneMemberships`        | `LightingPageRequest`                 | `LightingZoneMembershipsPageResult`    | `lighting`       |                                                                                                                                |
+| `0x0908` | `GetLightingOutputs`                | `LightingPageRequest`                 | `LightingOutputsPageResult`            | `lighting`       |                                                                                                                                |
+| `0x0909` | `GetLightingRoutes`                 | `LightingPageRequest`                 | `LightingRoutesPageResult`             | `lighting`       |                                                                                                                                |
+| `0x090A` | `SetLightingOverlay`                | `SetLightingOverlayRequest`           | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
+| `0x090B` | `UnsetLightingOverlay`              | `UnsetLightingOverlayRequest`         | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
+| `0x090C` | `ClearLightingOverlay`              | `ClearLightingOverlayRequest`         | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
+| `0x090D` | `BeginLightingOverlayReplace`       | `BeginLightingOverlayReplaceRequest`  | `LightingOverlayTransactionResult`     | `lighting`       |                                                                                                                                |
+| `0x090E` | `PutLightingOverlayChunk`           | `PutLightingOverlayChunkRequest`      | `LightingUnitResult`                   | `lighting`       |                                                                                                                                |
+| `0x090F` | `CommitLightingOverlayReplace`      | `CommitLightingOverlayReplaceRequest` | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
+| `0x0910` | `AbortLightingOverlayReplace`       | `AbortLightingOverlayReplaceRequest`  | `LightingUnitResult`                   | `lighting`       |                                                                                                                                |
+| `0x0911` | `GetLightingKeys`                   | `LightingPageRequest`                 | `LightingKeysPageResult`               | `lighting`       | Logical matrix keys are distinct from optional physical geometry.                                                              |
+| `0x0912` | `GetLightingSceneStatus`            | `()`                                  | `LightingSceneStatusResult`            | `lighting`       | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts. |
+| `0x0913` | `GetLightingScenes`                 | `LightingScenePageRequest`            | `LightingScenesPageResult`             | `lighting`       | Scene pages are pinned to `LightingState.revision` for consistency.                                                            |
+| `0x0914` | `SetLightingSceneCell`              | `SetLightingSceneCellRequest`         | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
+| `0x0915` | `UnsetLightingSceneCell`            | `UnsetLightingSceneCellRequest`       | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
+| `0x0916` | `BeginLightingSceneReplace`         | `BeginLightingSceneReplaceRequest`    | `LightingSceneTransactionResult`       | `lighting`       |                                                                                                                                |
+| `0x0917` | `PutLightingSceneChunk`             | `PutLightingSceneChunkRequest`        | `LightingUnitResult`                   | `lighting`       |                                                                                                                                |
+| `0x0918` | `CommitLightingSceneReplace`        | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
+| `0x0919` | `AbortLightingSceneReplace`         | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                   | `lighting`       |                                                                                                                                |
+| `0x091A` | `SetLightingLayerPolicy`            | `SetLightingLayerPolicyRequest`       | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
+| `0x091B` | `GetLightingOverlay`                | `LightingOverlayPageRequest`          | `LightingOverlayPageResult`            | `lighting`       | Overlay pages are pinned to `LightingState.revision` for consistency.                                                          |
+| `0x091C` | `GetLightingCompiledSceneStatus`    | `()`                                  | `LightingCompiledSceneStatusResult`    | `lighting`       | Discover the immutable board-compiled layer-scene source.                                                                      |
+| `0x091D` | `GetLightingCompiledScenes`         | `LightingPageRequest`                 | `LightingCompiledScenesPageResult`     | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                             |
+| `0x091E` | `GetLightingConditionalSceneStatus` | `()`                                  | `LightingConditionalSceneStatusResult` | `lighting`       | Discover immutable conditional lighting compiled from board config.                                                            |
+| `0x091F` | `GetLightingConditionalScenes`      | `LightingPageRequest`                 | `LightingConditionalScenesPageResult`  | `lighting`       | Conditional-scene pages are pinned to the firmware topology revision.                                                          |
 
 ## Topics
 
diff --git a/rmk-config/src/lib.rs b/rmk-config/src/lib.rs
index 06fc5d234..cbac9be06 100644
--- a/rmk-config/src/lib.rs
+++ b/rmk-config/src/lib.rs
@@ -566,6 +566,8 @@ pub(crate) struct LightingTomlConfig {
     pub emitters: Vec<LightingEmitterTomlConfig>,
     #[serde(default, rename = "layer_scene")]
     pub layer_scenes: Vec<LightingLayerSceneTomlConfig>,
+    #[serde(default, rename = "conditional_scene")]
+    pub conditional_scenes: Vec<LightingConditionalSceneTomlConfig>,
     pub background: Option<LightingBackgroundTomlConfig>,
 }
 
@@ -612,6 +614,43 @@ pub(crate) struct LightingLayerSceneTomlConfig {
     pub cells: Vec<LightingSceneCellTomlConfig>,
 }
 
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingConditionalSceneTomlConfig {
+    pub layer: Option<LightingLayerConditionTomlConfig>,
+    pub battery: Option<LightingBatteryConditionTomlConfig>,
+    #[serde(default, rename = "cell")]
+    pub cells: Vec<LightingSceneCellTomlConfig>,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingLayerConditionTomlConfig {
+    pub layer: u8,
+    #[serde(default = "default_true")]
+    pub active: bool,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingBatteryConditionTomlConfig {
+    pub node: u8,
+    pub min_level: Option<u8>,
+    pub max_level: Option<u8>,
+    #[serde(default)]
+    pub charge: LightingChargeConditionToml,
+}
+
+#[derive(Clone, Copy, Debug, Default, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum LightingChargeConditionToml {
+    #[default]
+    Any,
+    Charging,
+    Discharging,
+    Unknown,
+}
+
 #[derive(Clone, Debug, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub(crate) struct LightingSceneCellTomlConfig {
diff --git a/rmk-config/src/resolved/lighting.rs b/rmk-config/src/resolved/lighting.rs
index 36c7c0c3f..8509946e8 100644
--- a/rmk-config/src/resolved/lighting.rs
+++ b/rmk-config/src/resolved/lighting.rs
@@ -2,7 +2,9 @@ use std::collections::{HashMap, HashSet};
 
 use super::Keymap;
 use super::layout::{FixedPoint3, Layout};
-use crate::{LightingBackgroundModeToml, LightingEffectTomlConfig, LightingTargetTomlConfig};
+use crate::{
+    LightingBackgroundModeToml, LightingChargeConditionToml, LightingEffectTomlConfig, LightingTargetTomlConfig,
+};
 
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct LightingKey {
@@ -72,6 +74,41 @@ pub struct LightingLayerScene {
     pub cells: Vec<LightingSceneCell>,
 }
 
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LightingLayerCondition {
+    pub layer: u8,
+    pub active: bool,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum LightingChargeCondition {
+    Any,
+    Charging,
+    Discharging,
+    Unknown,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LightingBatteryCondition {
+    pub node: u8,
+    pub min_level: Option<u8>,
+    pub max_level: Option<u8>,
+    pub charge: LightingChargeCondition,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LightingConditionSet {
+    pub layer: Option<LightingLayerCondition>,
+    pub battery: Option<LightingBatteryCondition>,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LightingConditionalSceneCell {
+    pub conditions: LightingConditionSet,
+    pub slot: u16,
+    pub effect: LightingEffect,
+}
+
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum LightingBackgroundMode {
     Solid,
@@ -115,6 +152,7 @@ pub struct Lighting {
     pub outputs: Vec<LightingOutput>,
     pub routes: Vec<LightingRoute>,
     pub layer_scenes: Vec<LightingLayerScene>,
+    pub conditional_scene_cells: Vec<LightingConditionalSceneCell>,
     pub background: LightingBackground,
 }
 
@@ -198,6 +236,13 @@ impl crate::KeyboardTomlConfig {
             &zone_memberships,
             &zone_ids,
         )?;
+        let conditional_scene_cells = resolve_conditional_scenes(
+            keymap.layers,
+            &config.conditional_scenes,
+            &emitters,
+            &zone_memberships,
+            &zone_ids,
+        )?;
         let background = config
             .background
             .as_ref()
@@ -229,6 +274,7 @@ impl crate::KeyboardTomlConfig {
             outputs,
             routes,
             layer_scenes,
+            conditional_scene_cells,
             background,
         }))
     }
@@ -389,38 +435,7 @@ fn resolve_layer_scenes(
         }
         let mut cells = Vec::new();
         for cell in &scene.cells {
-            let slots: Vec<u16> = match cell.target {
-                LightingTargetTomlConfig::Led { led } => vec![
-                    *id_to_slot
-                        .get(&led)
-                        .ok_or_else(|| format!("lighting scene references unknown emitter id {led}"))?,
-                ],
-                LightingTargetTomlConfig::Key { key } => emitters
-                    .iter()
-                    .enumerate()
-                    .filter(|(_, emitter)| emitter.key == Some(key))
-                    .map(|(slot, _)| slot as u16)
-                    .collect(),
-                LightingTargetTomlConfig::Zone { zone } => {
-                    if !zone_ids.contains(&zone) {
-                        return Err(format!("lighting scene references unknown zone {zone}"));
-                    }
-                    emitters
-                        .iter()
-                        .enumerate()
-                        .filter(|(_, emitter)| {
-                            let start = emitter.zone_start as usize;
-                            let end = start + emitter.zone_len as usize;
-                            zone_memberships[start..end].contains(&zone)
-                        })
-                        .map(|(slot, _)| slot as u16)
-                        .collect()
-                }
-                LightingTargetTomlConfig::All { all: true } => (0..emitters.len() as u16).collect(),
-                LightingTargetTomlConfig::All { all: false } => {
-                    return Err("lighting target `{ all = false }` is invalid".into());
-                }
-            };
+            let slots = resolve_target_slots(&cell.target, &id_to_slot, emitters, zone_memberships, zone_ids)?;
             if slots.is_empty() {
                 return Err(format!(
                     "lighting layer scene {} target resolves to no emitters",
@@ -438,6 +453,122 @@ fn resolve_layer_scenes(
     Ok(scenes)
 }
 
+fn resolve_conditional_scenes(
+    layer_count: u8,
+    config: &[crate::LightingConditionalSceneTomlConfig],
+    emitters: &[LightingEmitter],
+    zone_memberships: &[u8],
+    zone_ids: &HashSet<u8>,
+) -> Result<Vec<LightingConditionalSceneCell>, String> {
+    let id_to_slot: HashMap<u16, u16> = emitters
+        .iter()
+        .enumerate()
+        .map(|(slot, emitter)| (emitter.id, slot as u16))
+        .collect();
+    let mut resolved = Vec::new();
+    for (index, scene) in config.iter().enumerate() {
+        if scene.cells.is_empty() {
+            return Err(format!("lighting conditional scene {index} has no cells"));
+        }
+        let layer = scene
+            .layer
+            .map(|condition| {
+                if condition.layer >= layer_count {
+                    return Err(format!(
+                        "lighting conditional scene {index} layer {} is outside configured layer count {layer_count}",
+                        condition.layer
+                    ));
+                }
+                Ok(LightingLayerCondition {
+                    layer: condition.layer,
+                    active: condition.active,
+                })
+            })
+            .transpose()?;
+        let battery = scene
+            .battery
+            .map(|condition| {
+                if condition.min_level.is_some_and(|level| level > 100)
+                    || condition.max_level.is_some_and(|level| level > 100)
+                    || matches!((condition.min_level, condition.max_level), (Some(min), Some(max)) if min > max)
+                {
+                    return Err(format!(
+                        "lighting conditional scene {index} has invalid battery level range"
+                    ));
+                }
+                Ok(LightingBatteryCondition {
+                    node: condition.node,
+                    min_level: condition.min_level,
+                    max_level: condition.max_level,
+                    charge: match condition.charge {
+                        LightingChargeConditionToml::Any => LightingChargeCondition::Any,
+                        LightingChargeConditionToml::Charging => LightingChargeCondition::Charging,
+                        LightingChargeConditionToml::Discharging => LightingChargeCondition::Discharging,
+                        LightingChargeConditionToml::Unknown => LightingChargeCondition::Unknown,
+                    },
+                })
+            })
+            .transpose()?;
+        let conditions = LightingConditionSet { layer, battery };
+        for cell in &scene.cells {
+            let slots = resolve_target_slots(&cell.target, &id_to_slot, emitters, zone_memberships, zone_ids)?;
+            if slots.is_empty() {
+                return Err(format!(
+                    "lighting conditional scene {index} target resolves to no emitters"
+                ));
+            }
+            let effect = resolve_effect(&cell.effect)?;
+            resolved.extend(slots.into_iter().map(|slot| LightingConditionalSceneCell {
+                conditions,
+                slot,
+                effect,
+            }));
+        }
+    }
+    Ok(resolved)
+}
+
+fn resolve_target_slots(
+    target: &LightingTargetTomlConfig,
+    id_to_slot: &HashMap<u16, u16>,
+    emitters: &[LightingEmitter],
+    zone_memberships: &[u8],
+    zone_ids: &HashSet<u8>,
+) -> Result<Vec<u16>, String> {
+    Ok(match *target {
+        LightingTargetTomlConfig::Led { led } => vec![
+            *id_to_slot
+                .get(&led)
+                .ok_or_else(|| format!("lighting scene references unknown emitter id {led}"))?,
+        ],
+        LightingTargetTomlConfig::Key { key } => emitters
+            .iter()
+            .enumerate()
+            .filter(|(_, emitter)| emitter.key == Some(key))
+            .map(|(slot, _)| slot as u16)
+            .collect(),
+        LightingTargetTomlConfig::Zone { zone } => {
+            if !zone_ids.contains(&zone) {
+                return Err(format!("lighting scene references unknown zone {zone}"));
+            }
+            emitters
+                .iter()
+                .enumerate()
+                .filter(|(_, emitter)| {
+                    let start = emitter.zone_start as usize;
+                    let end = start + emitter.zone_len as usize;
+                    zone_memberships[start..end].contains(&zone)
+                })
+                .map(|(slot, _)| slot as u16)
+                .collect()
+        }
+        LightingTargetTomlConfig::All { all: true } => (0..emitters.len() as u16).collect(),
+        LightingTargetTomlConfig::All { all: false } => {
+            return Err("lighting target `{ all = false }` is invalid".into());
+        }
+    })
+}
+
 fn resolve_effect(config: &LightingEffectTomlConfig) -> Result<LightingEffect, String> {
     Ok(match *config {
         LightingEffectTomlConfig::Solid { color } => LightingEffect::Solid { color },
@@ -596,6 +727,51 @@ hidden = ["(0,1)"]"#,
         assert_eq!(lighting.emitters[1].position.unwrap().z, 64);
     }
 
+    #[test]
+    fn resolves_conditional_layer_and_battery_scenes() {
+        let source = format!(
+            r#"{BASE}
+[[lighting.conditional_scene]]
+layer = {{ layer = 1, active = true }}
+battery = {{ node = 0, min_level = 21, max_level = 40, charge = "discharging" }}
+[[lighting.conditional_scene.cell]]
+target = {{ zone = 1 }}
+effect = {{ kind = "solid", color = [9, 8, 7] }}
+"#
+        );
+        let config = parse(&source);
+        let layout = config.layout().unwrap();
+        let keymap = config.keymap().unwrap();
+        let lighting = config.lighting(&layout, &keymap).unwrap().unwrap();
+        assert_eq!(lighting.conditional_scene_cells.len(), 2);
+        let conditions = lighting.conditional_scene_cells[0].conditions;
+        assert_eq!(conditions.layer.unwrap().layer, 1);
+        assert!(conditions.layer.unwrap().active);
+        let battery = conditions.battery.unwrap();
+        assert_eq!(battery.node, 0);
+        assert_eq!(battery.min_level, Some(21));
+        assert_eq!(battery.max_level, Some(40));
+        assert_eq!(battery.charge, super::LightingChargeCondition::Discharging);
+    }
+
+    #[test]
+    fn rejects_invalid_conditional_battery_range() {
+        let source = format!(
+            r#"{BASE}
+[[lighting.conditional_scene]]
+battery = {{ node = 0, min_level = 80, max_level = 20 }}
+[[lighting.conditional_scene.cell]]
+target = {{ led = 10 }}
+effect = {{ kind = "solid", color = [9, 8, 7] }}
+"#
+        );
+        let config = parse(&source);
+        let layout = config.layout().unwrap();
+        let keymap = config.keymap().unwrap();
+        let error = config.lighting(&layout, &keymap).unwrap_err();
+        assert!(error.contains("invalid battery level range"), "{error}");
+    }
+
     #[test]
     fn rejects_degenerate_animated_effects() {
         for (source, expected) in [
diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
index 9f829e60d..218b54abe 100644
--- a/rmk-macro/src/codegen/lighting.rs
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -3,7 +3,8 @@
 use proc_macro2::TokenStream as TokenStream2;
 use quote::quote;
 use rmk_config::resolved::lighting::{
-    Lighting, LightingBackgroundMode, LightingEffect, LightingSceneCell,
+    Lighting, LightingBackgroundMode, LightingChargeCondition, LightingConditionalSceneCell,
+    LightingEffect, LightingSceneCell,
 };
 use rmk_config::resolved::{FixedPoint3, PhysicalLayout};
 
@@ -189,6 +190,11 @@ pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> To
             }
         });
     let layer_scene_count = lighting.layer_scenes.len();
+    let conditional_cells = lighting
+        .conditional_scene_cells
+        .iter()
+        .map(expand_conditional_scene_cell);
+    let conditional_cell_count = lighting.conditional_scene_cells.len();
     let background = &lighting.background;
     let background_enabled = background.enabled;
     let background_hue = background.hue;
@@ -211,6 +217,9 @@ pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> To
                 scenes: &LIGHTING_LAYER_SCENE_TABLE,
                 policy: ::rmk::lighting::LayerPolicy::ActiveStack,
             };
+        pub static LIGHTING_CONDITIONAL_SCENE_CELLS:
+            [::rmk::lighting::ConditionalSceneCell<::rmk::lighting::BuiltinEffect>; #conditional_cell_count] =
+            [#(#conditional_cells),*];
         pub const LIGHTING_BACKGROUND: ::rmk::lighting::BackgroundState =
             ::rmk::lighting::BackgroundState {
                 enabled: #background_enabled,
@@ -223,6 +232,69 @@ pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> To
     }
 }
 
+fn expand_conditional_scene_cell(cell: &LightingConditionalSceneCell) -> TokenStream2 {
+    let slot = cell.slot;
+    let effect = expand_effect(cell.effect);
+    let layer = match cell.conditions.layer {
+        Some(condition) => {
+            let layer = condition.layer;
+            let active = condition.active;
+            quote! {
+                ::core::option::Option::Some(::rmk::lighting::LayerCondition {
+                    layer: #layer,
+                    active: #active,
+                })
+            }
+        }
+        None => quote! { ::core::option::Option::None },
+    };
+    let battery = match cell.conditions.battery {
+        Some(condition) => {
+            let node = condition.node;
+            let min_level = expand_option_u8(condition.min_level);
+            let max_level = expand_option_u8(condition.max_level);
+            let charge = match condition.charge {
+                LightingChargeCondition::Any => quote! { ::rmk::lighting::ChargeCondition::Any },
+                LightingChargeCondition::Charging => {
+                    quote! { ::rmk::lighting::ChargeCondition::Charging }
+                }
+                LightingChargeCondition::Discharging => {
+                    quote! { ::rmk::lighting::ChargeCondition::Discharging }
+                }
+                LightingChargeCondition::Unknown => {
+                    quote! { ::rmk::lighting::ChargeCondition::Unknown }
+                }
+            };
+            quote! {
+                ::core::option::Option::Some(::rmk::lighting::BatteryCondition {
+                    node: #node,
+                    min_level: #min_level,
+                    max_level: #max_level,
+                    charge: #charge,
+                })
+            }
+        }
+        None => quote! { ::core::option::Option::None },
+    };
+    quote! {
+        ::rmk::lighting::ConditionalSceneCell {
+            conditions: ::rmk::lighting::ConditionSet {
+                layer: #layer,
+                battery: #battery,
+            },
+            slot: ::rmk::lighting::LedSlot(#slot),
+            effect: #effect,
+        }
+    }
+}
+
+fn expand_option_u8(value: Option<u8>) -> TokenStream2 {
+    match value {
+        Some(value) => quote! { ::core::option::Option::Some(#value) },
+        None => quote! { ::core::option::Option::None },
+    }
+}
+
 fn expand_scene_cell(cell: &LightingSceneCell) -> TokenStream2 {
     let slot = cell.slot;
     let effect = expand_effect(cell.effect);
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 19e8a04e4..0e4ee3ab2 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -38,13 +38,14 @@ use crate::protocol::rynk::{
     AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
     BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest,
     CommitLightingSceneReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingCompiledSceneStatusResult,
-    LightingCompiledScenesPageResult, LightingKeysPageResult, LightingLedsPageResult, LightingOutputsPageResult,
-    LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest,
-    LightingPhysicalKeysPageResult, LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatusResult,
-    LightingSceneTransactionResult, LightingScenesPageResult, LightingStateResult, LightingUnitResult,
-    LightingZoneMembershipsPageResult, LightingZonesPageResult, PutLightingOverlayChunkRequest,
-    PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
-    SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
+    LightingCompiledScenesPageResult, LightingConditionalSceneStatusResult, LightingConditionalScenesPageResult,
+    LightingKeysPageResult, LightingLedsPageResult, LightingOutputsPageResult, LightingOverlayPageRequest,
+    LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKeysPageResult,
+    LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatusResult, LightingSceneTransactionResult,
+    LightingScenesPageResult, LightingStateResult, LightingUnitResult, LightingZoneMembershipsPageResult,
+    LightingZonesPageResult, PutLightingOverlayChunkRequest, PutLightingSceneChunkRequest,
+    SetLightingLayerPolicyRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
+    UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 #[cfg(all(feature = "_ble", feature = "split"))]
 use crate::protocol::rynk::{SplitCentralLatencyPolicy, SplitCentralLatencyState};
@@ -435,6 +436,12 @@ endpoints! {
     /// Compiled-scene pages are pinned to the firmware topology revision.
     #[cfg(feature = "lighting")]
     GetLightingCompiledScenes = 0x091D: LightingPageRequest => LightingCompiledScenesPageResult;
+    /// Discover immutable conditional lighting compiled from board config.
+    #[cfg(feature = "lighting")]
+    GetLightingConditionalSceneStatus = 0x091E: () => LightingConditionalSceneStatusResult;
+    /// Conditional-scene pages are pinned to the firmware topology revision.
+    #[cfg(feature = "lighting")]
+    GetLightingConditionalScenes = 0x091F: LightingPageRequest => LightingConditionalScenesPageResult;
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 0802c6044..4d8607317 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -17,6 +17,8 @@ pub const LIGHTING_PAGE_SIZE: usize = 8;
 pub const LIGHTING_OVERLAY_CHUNK_SIZE: usize = 8;
 /// Number of scene cells in one scene page or replacement chunk.
 pub const LIGHTING_SCENE_CHUNK_SIZE: usize = 8;
+/// Number of immutable conditional cells in one readback page.
+pub const LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 8;
 /// Maximum UTF-8 byte length of a zone name.
 pub const LIGHTING_ZONE_NAME_SIZE: usize = 24;
 
@@ -186,6 +188,8 @@ impl LightingFeatureFlags {
     pub const OVERLAY_READBACK: u16 = 1 << 7;
     /// Read-only board-compiled layer scenes, separate from runtime scenes.
     pub const COMPILED_LAYER_SCENES: u16 = 1 << 8;
+    /// Read-only board-compiled rules driven by layer and battery state.
+    pub const COMPILED_CONDITIONAL_SCENES: u16 = 1 << 9;
 
     pub const fn contains(self, bits: u16) -> bool {
         self.0 & bits == bits
@@ -574,6 +578,73 @@ impl MaxSize for LightingCompiledScenesPage {
         + crate::heapless_vec_max_size::<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>();
 }
 
+wire_type! {
+    pub struct LightingLayerCondition {
+        pub layer: u8,
+        pub active: bool,
+    }
+}
+
+wire_type! {
+    pub enum LightingChargeCondition {
+        Any,
+        Charging,
+        Discharging,
+        Unknown,
+    }
+}
+
+wire_type! {
+    pub struct LightingBatteryCondition {
+        pub node: LightingNodeId,
+        pub min_level: Option<u8>,
+        pub max_level: Option<u8>,
+        pub charge: LightingChargeCondition,
+    }
+}
+
+wire_type! {
+    /// A conjunction of optional layer and battery predicates.
+    pub struct LightingConditionSet {
+        pub layer: Option<LightingLayerCondition>,
+        pub battery: Option<LightingBatteryCondition>,
+    }
+}
+
+wire_type! {
+    /// One immutable conditional effect compiled from keyboard configuration.
+    pub struct LightingConditionalSceneCell {
+        pub conditions: LightingConditionSet,
+        pub led_id: LightingLedId,
+        pub effect: LightingEffect,
+    }
+}
+
+wire_type! {
+    pub struct LightingConditionalSceneStatus {
+        pub topology_revision: u32,
+        pub cell_len: u16,
+        pub chunk_capacity: u8,
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LightingConditionalScenesPage {
+    pub topology_revision: u32,
+    pub total_count: u16,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingConditionalSceneCell[]"))]
+    pub items: Vec<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>,
+}
+
+impl MaxSize for LightingConditionalScenesPage {
+    const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+        + u16::POSTCARD_MAX_SIZE
+        + crate::heapless_vec_max_size::<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>();
+}
+
 impl MaxSize for LightingScenesPage {
     const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
         + u16::POSTCARD_MAX_SIZE
@@ -687,6 +758,8 @@ pub type LightingSceneStatusResult = LightingResult<LightingSceneStatus>;
 pub type LightingScenesPageResult = LightingResult<LightingScenesPage>;
 pub type LightingCompiledSceneStatusResult = LightingResult<LightingCompiledSceneStatus>;
 pub type LightingCompiledScenesPageResult = LightingResult<LightingCompiledScenesPage>;
+pub type LightingConditionalSceneStatusResult = LightingResult<LightingConditionalSceneStatus>;
+pub type LightingConditionalScenesPageResult = LightingResult<LightingConditionalScenesPage>;
 pub type LightingSceneTransactionResult = LightingResult<LightingSceneTransaction>;
 pub type LightingUnitResult = LightingResult<()>;
 
@@ -728,6 +801,8 @@ const _: () = {
     assert_endpoint_fits!(LightingScenePageRequest, LightingScenesPageResult);
     assert_endpoint_fits!((), LightingCompiledSceneStatusResult);
     assert_endpoint_fits!(LightingPageRequest, LightingCompiledScenesPageResult);
+    assert_endpoint_fits!((), LightingConditionalSceneStatusResult);
+    assert_endpoint_fits!(LightingPageRequest, LightingConditionalScenesPageResult);
     assert_endpoint_fits!(SetLightingSceneCellRequest, LightingStateResult);
     assert_endpoint_fits!(UnsetLightingSceneCellRequest, LightingStateResult);
     assert_endpoint_fits!(SetLightingLayerPolicyRequest, LightingStateResult);
@@ -896,6 +971,45 @@ mod tests {
         assert!(LightingCompiledScenesPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
     }
 
+    #[test]
+    fn conditional_scene_page_round_trips_at_capacity() {
+        let mut items = Vec::new();
+        for id in 0..LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE as u16 {
+            items
+                .push(LightingConditionalSceneCell {
+                    conditions: LightingConditionSet {
+                        layer: Some(LightingLayerCondition {
+                            layer: u8::MAX,
+                            active: true,
+                        }),
+                        battery: Some(LightingBatteryCondition {
+                            node: LightingNodeId(u8::MAX),
+                            min_level: Some(1),
+                            max_level: Some(100),
+                            charge: LightingChargeCondition::Charging,
+                        }),
+                    },
+                    led_id: LightingLedId(id),
+                    effect: LightingEffect::Solid {
+                        color: LightingRgb8 {
+                            r: u8::MAX,
+                            g: u8::MAX,
+                            b: u8::MAX,
+                        },
+                    },
+                })
+                .unwrap();
+        }
+        let page = LightingConditionalScenesPage {
+            topology_revision: u32::MAX,
+            total_count: u16::MAX,
+            items,
+        };
+        round_trip(&page);
+        assert_max_size_bound(&page);
+        assert!(LightingConditionalScenesPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+    }
+
     #[test]
     fn scene_cell_validation_is_effect_validation() {
         assert_eq!(scene_cell(0, 1).validate(), Ok(()));
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 7365987d7..653559694 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -4,23 +4,25 @@ use embassy_time::Instant;
 use heapless::{String, Vec};
 use rmk_types::protocol::rynk::command::{
     ClearLightingOverlay, GetLightingCapabilities, GetLightingCompiledSceneStatus, GetLightingCompiledScenes,
-    GetLightingKeys, GetLightingLeds, GetLightingOutputs, GetLightingOverlay, GetLightingPhysicalKeys,
-    GetLightingRoutes, GetLightingSceneStatus, GetLightingScenes, GetLightingState, GetLightingZoneMemberships,
-    GetLightingZones, SetLightingLayerPolicy, SetLightingOverlay, SetLightingSceneCell, SetLightingState,
-    UnsetLightingOverlay, UnsetLightingSceneCell,
+    GetLightingConditionalSceneStatus, GetLightingConditionalScenes, GetLightingKeys, GetLightingLeds,
+    GetLightingOutputs, GetLightingOverlay, GetLightingPhysicalKeys, GetLightingRoutes, GetLightingSceneStatus,
+    GetLightingScenes, GetLightingState, GetLightingZoneMemberships, GetLightingZones, SetLightingLayerPolicy,
+    SetLightingOverlay, SetLightingSceneCell, SetLightingState, UnsetLightingOverlay, UnsetLightingSceneCell,
 };
 use rmk_types::protocol::rynk::{
     AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
     BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest,
-    CommitLightingSceneReplaceRequest, LIGHTING_PAGE_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LIGHTING_ZONE_NAME_SIZE,
-    LightingCapabilities, LightingCapabilitiesResult, LightingCompiledSceneStatus, LightingCompiledSceneStatusResult,
-    LightingCompiledScenesPageResult, LightingEffectFlags, LightingError, LightingFeatureFlags, LightingKeysPage,
-    LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
-    LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage, LightingOutputsPage,
-    LightingOutputsPageResult, LightingOverlayCell, LightingOverlayPageRequest, LightingOverlayPageResult,
-    LightingOverlayTransaction, LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKey,
-    LightingPhysicalKeysPage, LightingPhysicalKeysPageResult, LightingPoint3, LightingResult, LightingRoute,
-    LightingRoutesPage, LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatus,
+    CommitLightingSceneReplaceRequest, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE, LIGHTING_PAGE_SIZE,
+    LIGHTING_SCENE_CHUNK_SIZE, LIGHTING_ZONE_NAME_SIZE, LightingCapabilities, LightingCapabilitiesResult,
+    LightingCompiledSceneStatus, LightingCompiledSceneStatusResult, LightingCompiledScenesPageResult,
+    LightingConditionalSceneCell, LightingConditionalSceneStatus, LightingConditionalSceneStatusResult,
+    LightingConditionalScenesPage, LightingConditionalScenesPageResult, LightingEffectFlags, LightingError,
+    LightingFeatureFlags, LightingKeysPage, LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage,
+    LightingLedsPageResult, LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage,
+    LightingOutputsPage, LightingOutputsPageResult, LightingOverlayCell, LightingOverlayPageRequest,
+    LightingOverlayPageResult, LightingOverlayTransaction, LightingOverlayTransactionResult, LightingPageRequest,
+    LightingPhysicalKey, LightingPhysicalKeysPage, LightingPhysicalKeysPageResult, LightingPoint3, LightingResult,
+    LightingRoute, LightingRoutesPage, LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatus,
     LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult, LightingState,
     LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage,
     LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult, PutLightingOverlayChunkRequest,
@@ -256,6 +258,43 @@ impl Handle<GetLightingCompiledScenes> for RynkService<'_> {
     }
 }
 
+impl Handle<GetLightingConditionalSceneStatus> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LightingConditionalSceneStatusResult, RynkError> {
+        Ok(controller(self).map(|controller| LightingConditionalSceneStatus {
+            topology_revision: controller.descriptor.topology_revision,
+            cell_len: count(controller.conditional_scenes.len()),
+            chunk_capacity: LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE as u8,
+        }))
+    }
+}
+
+impl Handle<GetLightingConditionalScenes> for RynkService<'_> {
+    async fn handle(&self, req: LightingPageRequest) -> Result<LightingConditionalScenesPageResult, RynkError> {
+        let result = controller(self).and_then(|controller| {
+            check_topology_revision(controller, req.topology_revision)?;
+            let total_count = count(controller.conditional_scenes.len());
+            let start = (req.offset as usize).min(controller.conditional_scenes.len());
+            let end = (start + LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE).min(controller.conditional_scenes.len());
+            let mut items: Vec<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE> = Vec::new();
+            for cell in &controller.conditional_scenes[start..end] {
+                items
+                    .push(
+                        controller
+                            .conditional_scene_cell_to_wire(*cell)
+                            .ok_or(LightingError::InvalidRequest)?,
+                    )
+                    .map_err(|_| LightingError::InvalidRequest)?;
+            }
+            Ok(LightingConditionalScenesPage {
+                topology_revision: controller.descriptor.topology_revision,
+                total_count,
+                items,
+            })
+        });
+        Ok(result)
+    }
+}
+
 impl Handle<SetLightingSceneCell> for RynkService<'_> {
     async fn handle(&self, req: SetLightingSceneCellRequest) -> Result<LightingStateResult, RynkError> {
         if let Err(error) = req
@@ -472,6 +511,9 @@ fn capabilities(binding: RynkLightingController<'_>) -> LightingCapabilities {
     if binding.scene_capacity > 0 {
         features.0 |= LightingFeatureFlags::LAYER_SCENES;
     }
+    if !binding.conditional_scenes.is_empty() {
+        features.0 |= LightingFeatureFlags::COMPILED_CONDITIONAL_SCENES;
+    }
     LightingCapabilities {
         topology_revision: descriptor.topology_revision,
         logical_key_count: count(topology.keys.len()),
@@ -924,8 +966,9 @@ mod tests {
     use crate::host::RynkLightingMailbox;
     use crate::keymap::{KeyMap, KeymapData};
     use crate::lighting::{
-        BuiltinEffect, LayerScene, LedId, LedMetadata, LightingNodeId as CoreNodeId, LightingRouting, LightingTopology,
-        MatrixSize, OutputId, OutputMetadata, PhysicalRoute, Rgb8, SceneCell, ZoneSpan,
+        BatteryCondition, BuiltinEffect, ChargeCondition, ConditionSet, ConditionalSceneCell, LayerCondition,
+        LayerScene, LedId, LedMetadata, LightingNodeId as CoreNodeId, LightingRouting, LightingTopology, MatrixSize,
+        OutputId, OutputMetadata, PhysicalRoute, Rgb8, SceneCell, ZoneSpan,
     };
     use crate::physical_layout::{
         Coordinate, Extent, KeyPosition, KeySize, PhysicalKey, PhysicalLayout, Point3, Rotation,
@@ -992,6 +1035,21 @@ mod tests {
         layer: 0,
         cells: &COMPILED_CELLS,
     }];
+    static CONDITIONAL_CELLS: [ConditionalSceneCell<BuiltinEffect>; 1] = [ConditionalSceneCell {
+        conditions: ConditionSet {
+            layer: Some(LayerCondition { layer: 1, active: true }),
+            battery: Some(BatteryCondition {
+                node: 0,
+                min_level: Some(21),
+                max_level: Some(40),
+                charge: ChargeCondition::Discharging,
+            }),
+        },
+        slot: crate::lighting::LedSlot(0),
+        effect: BuiltinEffect::Solid {
+            color: Rgb8::new(9, 8, 7),
+        },
+    }];
 
     fn descriptor() -> super::super::super::lighting::RynkLightingDescriptor<'static> {
         super::super::super::lighting::RynkLightingDescriptor {
@@ -1471,8 +1529,9 @@ mod tests {
         use embassy_futures::select::{Either3, select3};
         use rmk_types::protocol::rynk::command::{
             AbortLightingSceneReplace, BeginLightingSceneReplace, CommitLightingSceneReplace,
-            GetLightingCompiledSceneStatus, GetLightingCompiledScenes, GetLightingOverlay, GetLightingSceneStatus,
-            GetLightingScenes, PutLightingSceneChunk, SetLightingLayerPolicy, SetLightingOverlay, SetLightingSceneCell,
+            GetLightingCompiledSceneStatus, GetLightingCompiledScenes, GetLightingConditionalSceneStatus,
+            GetLightingConditionalScenes, GetLightingOverlay, GetLightingSceneStatus, GetLightingScenes,
+            PutLightingSceneChunk, SetLightingLayerPolicy, SetLightingOverlay, SetLightingSceneCell,
             UnsetLightingSceneCell,
         };
         use rmk_types::protocol::rynk::{
@@ -1495,8 +1554,11 @@ mod tests {
             let mut config = RmkConfig::default();
             config.lock_config.insecure = true;
             let mailbox = RynkLightingMailbox::new();
-            let service = RynkService::new(&keymap, &config)
-                .with_lighting(RynkLightingController::new(&mailbox, descriptor(), 8).with_scene_capacity(4));
+            let service = RynkService::new(&keymap, &config).with_lighting(
+                RynkLightingController::new(&mailbox, descriptor(), 8)
+                    .with_scene_capacity(4)
+                    .with_conditional_scenes(&CONDITIONAL_CELLS),
+            );
             let session = session(&keymap, &config);
 
             let core = LightingMailbox::<StandardCommand<2, 4>, StandardReply, StandardError, 1>::new();
@@ -1520,6 +1582,11 @@ mod tests {
             assert!(lighting.features.contains(LightingFeatureFlags::LAYER_SCENES));
             assert!(lighting.features.contains(LightingFeatureFlags::OVERLAY_READBACK));
             assert!(lighting.features.contains(LightingFeatureFlags::COMPILED_LAYER_SCENES));
+            assert!(
+                lighting
+                    .features
+                    .contains(LightingFeatureFlags::COMPILED_CONDITIONAL_SCENES)
+            );
 
             let client = async {
                 let compiled_status = call::<GetLightingCompiledSceneStatus>(&service, &session, &())
@@ -1544,6 +1611,27 @@ mod tests {
                 assert_eq!(compiled.items[0].layer, 0);
                 assert_eq!(compiled.items[0].led_id, LightingLedId(10));
                 assert_eq!(compiled.items[1].led_id, LightingLedId(42));
+                let conditional_status = call::<GetLightingConditionalSceneStatus>(&service, &session, &())
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(conditional_status.topology_revision, 7);
+                assert_eq!(conditional_status.cell_len, 1);
+                let conditional = call::<GetLightingConditionalScenes>(
+                    &service,
+                    &session,
+                    &LightingPageRequest {
+                        topology_revision: 7,
+                        offset: 0,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(conditional.total_count, 1);
+                assert_eq!(conditional.items[0].led_id, LightingLedId(10));
+                assert_eq!(conditional.items[0].conditions.layer.unwrap().layer, 1);
+                assert_eq!(conditional.items[0].conditions.battery.unwrap().min_level, Some(21));
                 let stale_compiled = call::<GetLightingCompiledScenes>(
                     &service,
                     &session,
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 4b18ac5ba..9561d8b56 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -16,17 +16,18 @@ use embassy_sync::signal::Signal;
 use heapless::Vec;
 use rmk_types::protocol::rynk::{
     LIGHTING_OVERLAY_CHUNK_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState,
-    LightingCompiledScenesPage, LightingError, LightingLayerPolicy, LightingMutableState, LightingOverlayCell,
-    LightingOverlayPage, LightingResult, LightingRgb8, LightingSceneCell, LightingSceneTransaction, LightingScenesPage,
-    LightingState,
+    LightingCompiledScenesPage, LightingConditionalSceneCell as WireConditionalSceneCell, LightingError,
+    LightingLayerPolicy, LightingMutableState, LightingOverlayCell, LightingOverlayPage, LightingResult, LightingRgb8,
+    LightingSceneCell, LightingSceneTransaction, LightingScenesPage, LightingState,
 };
 
 use crate::RawMutex;
 use crate::core_traits::Runnable;
 use crate::lighting::{
-    BackgroundMode, BackgroundState, BuiltinEffect, LayerPolicy, LedId, LightingMailbox, LightingRouting,
-    LightingTopology, OVERLAY_CHUNK_SIZE, OverlayBatch, OverlayCell, OverlayError, Rgb8, SceneChunk, SceneTableCell,
-    StandardCommand, StandardError, StandardLightingEngine, StandardMutableState, StandardReply, StandardState,
+    BackgroundMode, BackgroundState, BuiltinEffect, ConditionalSceneCell, LayerPolicy, LedId, LightingMailbox,
+    LightingRouting, LightingTopology, OVERLAY_CHUNK_SIZE, OverlayBatch, OverlayCell, OverlayError, Rgb8, SceneChunk,
+    SceneTableCell, StandardCommand, StandardError, StandardLightingEngine, StandardMutableState, StandardReply,
+    StandardState,
 };
 
 const _: () = core::assert!(
@@ -63,6 +64,7 @@ pub struct RynkLightingController<'a> {
     /// wire a scene table; hosts gate on it and every scene endpoint rejects
     /// with `Unsupported`.
     pub(super) scene_capacity: u16,
+    pub(super) conditional_scenes: &'a [ConditionalSceneCell<BuiltinEffect>],
     mailbox: &'a RynkLightingMailbox,
 }
 
@@ -83,6 +85,7 @@ impl<'a> RynkLightingController<'a> {
                 staged_capacity
             },
             scene_capacity: 0,
+            conditional_scenes: &[],
             mailbox,
         }
     }
@@ -94,6 +97,12 @@ impl<'a> RynkLightingController<'a> {
         self
     }
 
+    /// Advertise immutable conditional scenes compiled from board config.
+    pub const fn with_conditional_scenes(mut self, scenes: &'a [ConditionalSceneCell<BuiltinEffect>]) -> Self {
+        self.conditional_scenes = scenes;
+        self
+    }
+
     pub const fn descriptor(&self) -> RynkLightingDescriptor<'a> {
         self.descriptor
     }
@@ -106,6 +115,18 @@ impl<'a> RynkLightingController<'a> {
         self.scene_capacity
     }
 
+    pub(super) fn conditional_scene_cell_to_wire(
+        &self,
+        cell: ConditionalSceneCell<BuiltinEffect>,
+    ) -> Option<WireConditionalSceneCell> {
+        let led = self.descriptor.topology.led(cell.slot)?;
+        Some(WireConditionalSceneCell {
+            conditions: condition_set_to_wire(cell.conditions),
+            led_id: rmk_types::protocol::rynk::LightingLedId(led.id.0),
+            effect: effect_to_wire(cell.effect),
+        })
+    }
+
     pub(super) async fn request(&self, command: RynkLightingCommand) -> LightingResult<RynkLightingReadback> {
         self.mailbox.request(command).await
     }
@@ -915,6 +936,31 @@ fn effect_to_wire(effect: BuiltinEffect) -> rmk_types::protocol::rynk::LightingE
     }
 }
 
+fn condition_set_to_wire(conditions: crate::lighting::ConditionSet) -> rmk_types::protocol::rynk::LightingConditionSet {
+    use crate::lighting::ChargeCondition;
+    use rmk_types::protocol::rynk::{
+        LightingBatteryCondition, LightingChargeCondition, LightingConditionSet, LightingLayerCondition, LightingNodeId,
+    };
+
+    LightingConditionSet {
+        layer: conditions.layer.map(|condition| LightingLayerCondition {
+            layer: condition.layer,
+            active: condition.active,
+        }),
+        battery: conditions.battery.map(|condition| LightingBatteryCondition {
+            node: LightingNodeId(condition.node),
+            min_level: condition.min_level,
+            max_level: condition.max_level,
+            charge: match condition.charge {
+                ChargeCondition::Any => LightingChargeCondition::Any,
+                ChargeCondition::Charging => LightingChargeCondition::Charging,
+                ChargeCondition::Discharging => LightingChargeCondition::Discharging,
+                ChargeCondition::Unknown => LightingChargeCondition::Unknown,
+            },
+        }),
+    }
+}
+
 pub(super) const fn policy_from_wire(policy: LightingLayerPolicy) -> LayerPolicy {
     match policy {
         LightingLayerPolicy::EffectiveOnly => LayerPolicy::EffectiveOnly,
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 818f6df69..2a6035eb5 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -307,6 +307,14 @@ impl<'a> RynkService<'a> {
             #[cfg(feature = "lighting")]
             Cmd::GetLightingCompiledScenes => Serve::<command::GetLightingCompiledScenes, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
+            Cmd::GetLightingConditionalSceneStatus => {
+                Serve::<command::GetLightingConditionalSceneStatus, _>::serve(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingConditionalScenes => {
+                Serve::<command::GetLightingConditionalScenes, _>::serve(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
             Cmd::SetLightingSceneCell => Serve::<command::SetLightingSceneCell, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::UnsetLightingSceneCell => Serve::<command::UnsetLightingSceneCell, _>::serve(self, msg).await,
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index 91b3b2941..09181f407 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -37,8 +37,9 @@ pub use service::{
     OutputState, PowerState, RenderOutcome, ServiceAction, SnapshotProvider,
 };
 pub use source::{
-    DenseSource, Indicator, IndicatorScene, IndicatorScenes, LayerPolicy, LayerScene, LayerScenes, OverlayError,
-    OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
+    BatteryCondition, BatteryStatusProvider, ChargeCondition, ConditionSet, ConditionalSceneCell, ConditionalScenes,
+    DenseSource, Indicator, IndicatorScene, IndicatorScenes, LayerCondition, LayerPolicy, LayerScene, LayerScenes,
+    OverlayError, OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
 };
 pub use standard::{
     BackgroundMode, BackgroundPatch, BackgroundState, CompiledScenePage, EmptySource, OVERLAY_CHUNK_SIZE, OverlayBatch,
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index 28ab7901c..bcbc5e344 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -2,6 +2,7 @@ use super::compositor::{Contribution, LightingSource, RenderInput};
 use super::context::{LightingContext, LightingContextProvider};
 use super::effect::{EffectSample, LightingEffect};
 use super::topology::LedSlot;
+use crate::types::battery::{BatteryStatus, ChargeState};
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct SceneCell<E> {
@@ -147,6 +148,144 @@ where
     }
 }
 
+/// Board-owned lookup used by declarative battery conditions. Node IDs match
+/// lighting topology node IDs, so a split board can expose each half without
+/// embedding board-specific left/right semantics in the renderer.
+pub trait BatteryStatusProvider {
+    fn battery_status(&self, node: u8) -> BatteryStatus;
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct LayerCondition {
+    pub layer: u8,
+    pub active: bool,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum ChargeCondition {
+    Any,
+    Charging,
+    Discharging,
+    Unknown,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct BatteryCondition {
+    pub node: u8,
+    pub min_level: Option<u8>,
+    pub max_level: Option<u8>,
+    pub charge: ChargeCondition,
+}
+
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct ConditionSet {
+    pub layer: Option<LayerCondition>,
+    pub battery: Option<BatteryCondition>,
+}
+
+impl ConditionSet {
+    fn matches<Context, Batteries>(&self, context: &Context, batteries: &Batteries) -> bool
+    where
+        Context: LightingContextProvider,
+        Batteries: BatteryStatusProvider + ?Sized,
+    {
+        if let Some(condition) = self.layer
+            && context.lighting_context().layers.is_active(condition.layer) != condition.active
+        {
+            return false;
+        }
+        let Some(condition) = self.battery else {
+            return true;
+        };
+        let BatteryStatus::Available { charge_state, level } = batteries.battery_status(condition.node) else {
+            return false;
+        };
+        if !matches!(
+            (condition.charge, charge_state),
+            (ChargeCondition::Any, _)
+                | (ChargeCondition::Charging, ChargeState::Charging)
+                | (ChargeCondition::Discharging, ChargeState::Discharging)
+                | (ChargeCondition::Unknown, ChargeState::Unknown)
+        ) {
+            return false;
+        }
+        if condition.min_level.is_none() && condition.max_level.is_none() {
+            return true;
+        }
+        let Some(level) = level else {
+            return false;
+        };
+        condition.min_level.is_none_or(|min| level >= min) && condition.max_level.is_none_or(|max| level <= max)
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ConditionalSceneCell<E> {
+    pub conditions: ConditionSet,
+    pub slot: LedSlot,
+    pub effect: E,
+}
+
+/// Immutable conditional cells compiled from `keyboard.toml`.
+///
+/// Matching cells compose in declaration order. This permits a broad rule to
+/// establish a default and a later, narrower rule to override the same LED.
+#[derive(Copy, Clone, Debug)]
+pub struct ConditionalScenes<'a, E, Batteries: ?Sized> {
+    pub cells: &'a [ConditionalSceneCell<E>],
+    pub batteries: &'a Batteries,
+}
+
+impl<'a, E, Batteries: ?Sized> ConditionalScenes<'a, E, Batteries> {
+    pub const fn new(cells: &'a [ConditionalSceneCell<E>], batteries: &'a Batteries) -> Self {
+        Self { cells, batteries }
+    }
+
+    pub const fn cell_count(&self) -> usize {
+        self.cells.len()
+    }
+
+    fn cell_at<Context>(&self, context: &Context, mut wanted: usize) -> &ConditionalSceneCell<E>
+    where
+        Context: LightingContextProvider,
+        Batteries: BatteryStatusProvider,
+    {
+        for cell in self
+            .cells
+            .iter()
+            .filter(|cell| cell.conditions.matches(context, self.batteries))
+        {
+            if wanted == 0 {
+                return cell;
+            }
+            wanted -= 1;
+        }
+        panic!("LightingSource index must be below len")
+    }
+}
+
+impl<C, Context, E, Batteries> LightingSource<C, Context> for ConditionalScenes<'_, E, Batteries>
+where
+    Context: LightingContextProvider,
+    E: LightingEffect<C>,
+    Batteries: BatteryStatusProvider + ?Sized,
+{
+    fn len(&self, input: &RenderInput<'_, Context>) -> usize {
+        self.cells
+            .iter()
+            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
+            .count()
+    }
+
+    fn slot(&self, index: usize, input: &RenderInput<'_, Context>) -> LedSlot {
+        self.cell_at(input.context, index).slot
+    }
+
+    fn contribution(&mut self, index: usize, input: &RenderInput<'_, Context>) -> Contribution<C> {
+        Contribution::Opaque(self.cell_at(input.context, index).effect.sample(input.now_ms))
+    }
+}
+
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum Indicator {
     NumLock,
@@ -421,6 +560,7 @@ fn earliest(left: Option<u64>, right: Option<u64>) -> Option<u64> {
 mod tests {
     use super::super::{BuiltinEffect, Compositor, LayerState, LogicalFrame, Rgb8};
     use super::*;
+    use crate::types::battery::{BatteryStatus, ChargeState};
 
     const RED: Rgb8 = Rgb8::new(10, 0, 0);
     const GREEN: Rgb8 = Rgb8::new(0, 10, 0);
@@ -519,6 +659,78 @@ mod tests {
         assert_eq!(frame.as_slice(), &[Rgb8::BLACK, GREEN]);
     }
 
+    #[test]
+    fn conditional_scenes_conjoin_live_layer_and_battery_state() {
+        struct Batteries;
+        impl BatteryStatusProvider for Batteries {
+            fn battery_status(&self, node: u8) -> BatteryStatus {
+                if node == 0 {
+                    BatteryStatus::Available {
+                        charge_state: ChargeState::Discharging,
+                        level: Some(35),
+                    }
+                } else {
+                    BatteryStatus::Unavailable
+                }
+            }
+        }
+        let layer = Some(LayerCondition { layer: 2, active: true });
+        let cells = [
+            ConditionalSceneCell {
+                conditions: ConditionSet {
+                    layer,
+                    battery: Some(BatteryCondition {
+                        node: 0,
+                        min_level: Some(1),
+                        max_level: None,
+                        charge: ChargeCondition::Any,
+                    }),
+                },
+                slot: LedSlot(0),
+                effect: BuiltinEffect::solid(GREEN),
+            },
+            ConditionalSceneCell {
+                conditions: ConditionSet {
+                    layer,
+                    battery: Some(BatteryCondition {
+                        node: 0,
+                        min_level: Some(41),
+                        max_level: None,
+                        charge: ChargeCondition::Any,
+                    }),
+                },
+                slot: LedSlot(1),
+                effect: BuiltinEffect::solid(BLUE),
+            },
+            // A later, narrower match overrides the broad green contribution.
+            ConditionalSceneCell {
+                conditions: ConditionSet {
+                    layer,
+                    battery: Some(BatteryCondition {
+                        node: 0,
+                        min_level: Some(1),
+                        max_level: Some(40),
+                        charge: ChargeCondition::Discharging,
+                    }),
+                },
+                slot: LedSlot(0),
+                effect: BuiltinEffect::solid(RED),
+            },
+        ];
+        let batteries = Batteries;
+        let mut source = ConditionalScenes::new(&cells, &batteries);
+        let context = LightingContext {
+            layers: LayerState::new(2, 0, 0b101),
+            indicators: Default::default(),
+        };
+        let compositor = Compositor::<Rgb8, 2>::new(Rgb8::BLACK);
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        let mut tx = compositor.begin(0, &context, Rgb8::BLACK, &mut frame);
+        tx.apply(0, &mut source).unwrap();
+        tx.finish();
+        assert_eq!(frame.as_slice(), &[RED, Rgb8::BLACK]);
+    }
+
     #[test]
     fn indicator_scenes_use_extended_context_provider() {
         #[derive(Default)]
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index 89dc519f7..5a0561e8d 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -20,8 +20,8 @@ use rynk::rmk_types::combo::Combo;
 use rynk::rmk_types::connection::{ConnectionStatus, ConnectionType};
 use rynk::rmk_types::fork::Fork;
 use rynk::rmk_types::led_indicator::LedIndicator;
-use rynk::rmk_types::morse::Morse;
 use rynk::rmk_types::modifier::ModifierCombination;
+use rynk::rmk_types::morse::Morse;
 use rynk::rmk_types::protocol::rynk::{
     AbortLightingOverlayReplaceRequest, BeginLightingOverlayReplaceRequest, BehaviorConfig,
     ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest, DeviceCapabilities, DeviceInfo,
@@ -35,6 +35,7 @@ use rynk::rmk_types::protocol::rynk::{
     LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingSceneCellRequest,
     UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus, LightingCompiledScenesPage,
     LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy, SplitCentralLatencyState,
+    LightingConditionalSceneStatus, LightingConditionalScenesPage,
 };
 use rynk::{Client, Driver, LayoutInfo, RynkDevice, RynkHostError, TopicEvent};
 use wasm_bindgen::prelude::*;
@@ -196,6 +197,8 @@ endpoints! {
     get_lighting_scenes(request: LightingScenePageRequest) -> LightingScenesPage,
     get_lighting_compiled_scene_status() -> LightingCompiledSceneStatus,
     get_lighting_compiled_scenes(request: LightingPageRequest) -> LightingCompiledScenesPage,
+    get_lighting_conditional_scene_status() -> LightingConditionalSceneStatus,
+    get_lighting_conditional_scenes(request: LightingPageRequest) -> LightingConditionalScenesPage,
     set_lighting_scene_cell(request: SetLightingSceneCellRequest) -> LightingState,
     unset_lighting_scene_cell(request: UnsetLightingSceneCellRequest) -> LightingState,
     set_lighting_layer_policy(request: SetLightingLayerPolicyRequest) -> LightingState,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 0d7d8a965..116415f71 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -36,7 +36,7 @@ use rmk_types::protocol::rynk::{
     LightingSceneTransaction, LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest,
     SetLightingSceneCellRequest, UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus,
     LightingCompiledScenesPage, LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy,
-    SplitCentralLatencyState,
+    SplitCentralLatencyState, LightingConditionalSceneStatus, LightingConditionalScenesPage,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -578,6 +578,21 @@ impl Client {
         Self::flatten_lighting(self.request::<command::GetLightingCompiledScenes>(&request).await?)
     }
 
+    /// Discover immutable conditional lighting compiled from board config.
+    pub async fn get_lighting_conditional_scene_status(&self) -> Result<LightingConditionalSceneStatus, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingConditionalSceneStatus)?;
+        Self::flatten_lighting(self.request::<command::GetLightingConditionalSceneStatus>(&()).await?)
+    }
+
+    /// Read one topology-revision-pinned conditional-scene page.
+    pub async fn get_lighting_conditional_scenes(
+        &self,
+        request: LightingPageRequest,
+    ) -> Result<LightingConditionalScenesPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingConditionalScenes)?;
+        Self::flatten_lighting(self.request::<command::GetLightingConditionalScenes>(&request).await?)
+    }
+
     /// Insert or update one durable scene cell when the revision matches.
     pub async fn set_lighting_scene_cell(
         &self,
@@ -882,6 +897,64 @@ impl Client {
         Ok((status, cells))
     }
 
+    /// Read every immutable conditional cell under one topology revision.
+    pub async fn read_all_lighting_conditional_scenes(
+        &self,
+    ) -> Result<
+        (
+            LightingConditionalSceneStatus,
+            Vec<rmk_types::protocol::rynk::LightingConditionalSceneCell>,
+        ),
+        RynkHostError,
+    > {
+        let status = self.get_lighting_conditional_scene_status().await?;
+        let mut cells = Vec::new();
+        let mut offset: u16 = 0;
+        let mut first_page = true;
+        while first_page || offset < status.cell_len {
+            first_page = false;
+            let page = self
+                .get_lighting_conditional_scenes(LightingPageRequest {
+                    topology_revision: status.topology_revision,
+                    offset,
+                })
+                .await?;
+            if page.topology_revision != status.topology_revision || page.total_count != status.cell_len {
+                return Err(RynkHostError::InconsistentResponse {
+                    cmd: Cmd::GetLightingConditionalScenes,
+                    reason: "conditional page topology revision/count disagrees with status",
+                });
+            }
+            if offset >= status.cell_len {
+                if !page.items.is_empty() {
+                    return Err(RynkHostError::InconsistentResponse {
+                        cmd: Cmd::GetLightingConditionalScenes,
+                        reason: "empty conditional source returned unexpected cells",
+                    });
+                }
+                break;
+            }
+            if page.items.is_empty()
+                || page.items.len() > status.chunk_capacity as usize
+                || offset as usize + page.items.len() > status.cell_len as usize
+            {
+                return Err(RynkHostError::InconsistentResponse {
+                    cmd: Cmd::GetLightingConditionalScenes,
+                    reason: "conditional page is empty, oversized, or exceeds advertised count",
+                });
+            }
+            offset += page.items.len() as u16;
+            cells.extend(page.items.iter().copied());
+        }
+        if cells.len() != status.cell_len as usize {
+            return Err(RynkHostError::InconsistentResponse {
+                cmd: Cmd::GetLightingConditionalScenes,
+                reason: "conditional pagination ended before advertised count",
+            });
+        }
+        Ok((status, cells))
+    }
+
     /// Read the whole stored scene table by paging `GetLightingScenes` under
     /// one pinned revision. A concurrent lighting mutation invalidates the
     /// pin; the read restarts from a fresh status, bounded by a few attempts.

From 9ccf189ac8a9c85ec560dc19ff7b4bffc9ab9aee Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 05:07:57 -0700
Subject: [PATCH 23/78] feat(lighting): configure board controls

---
 rmk-config/src/lib.rs                         |  8 ++++
 rmk-config/src/resolved/lighting.rs           | 43 +++++++++++++++++++
 rmk-macro/src/codegen/lighting.rs             | 13 ++++++
 .../src/protocol/rynk/payload/lighting.rs     |  9 ++++
 rmk/src/host/rynk/handlers/lighting.rs        | 13 ++++--
 rmk/src/host/rynk/lighting.rs                 | 32 +++++++++++---
 rmk/src/lighting/mod.rs                       |  2 +-
 rmk/src/lighting/source.rs                    |  7 +++
 8 files changed, 116 insertions(+), 11 deletions(-)

diff --git a/rmk-config/src/lib.rs b/rmk-config/src/lib.rs
index cbac9be06..91455ce32 100644
--- a/rmk-config/src/lib.rs
+++ b/rmk-config/src/lib.rs
@@ -568,9 +568,17 @@ pub(crate) struct LightingTomlConfig {
     pub layer_scenes: Vec<LightingLayerSceneTomlConfig>,
     #[serde(default, rename = "conditional_scene")]
     pub conditional_scenes: Vec<LightingConditionalSceneTomlConfig>,
+    pub controls: Option<LightingControlsTomlConfig>,
     pub background: Option<LightingBackgroundTomlConfig>,
 }
 
+#[derive(Clone, Copy, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingControlsTomlConfig {
+    pub output_toggle_user_action: Option<u8>,
+    pub wake_layer: Option<u8>,
+}
+
 fn default_topology_revision() -> u32 {
     1
 }
diff --git a/rmk-config/src/resolved/lighting.rs b/rmk-config/src/resolved/lighting.rs
index 8509946e8..7a46053cb 100644
--- a/rmk-config/src/resolved/lighting.rs
+++ b/rmk-config/src/resolved/lighting.rs
@@ -109,6 +109,12 @@ pub struct LightingConditionalSceneCell {
     pub effect: LightingEffect,
 }
 
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub struct LightingControls {
+    pub output_toggle_user_action: Option<u8>,
+    pub wake_layer: Option<u8>,
+}
+
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum LightingBackgroundMode {
     Solid,
@@ -153,6 +159,7 @@ pub struct Lighting {
     pub routes: Vec<LightingRoute>,
     pub layer_scenes: Vec<LightingLayerScene>,
     pub conditional_scene_cells: Vec<LightingConditionalSceneCell>,
+    pub controls: LightingControls,
     pub background: LightingBackground,
 }
 
@@ -243,6 +250,20 @@ impl crate::KeyboardTomlConfig {
             &zone_memberships,
             &zone_ids,
         )?;
+        let controls = config.controls.map_or(Ok(LightingControls::default()), |controls| {
+            if let Some(layer) = controls.wake_layer
+                && layer >= keymap.layers
+            {
+                return Err(format!(
+                    "lighting.controls wake_layer {} is outside keymap layer count {}",
+                    layer, keymap.layers
+                ));
+            }
+            Ok(LightingControls {
+                output_toggle_user_action: controls.output_toggle_user_action,
+                wake_layer: controls.wake_layer,
+            })
+        })?;
         let background = config
             .background
             .as_ref()
@@ -275,6 +296,7 @@ impl crate::KeyboardTomlConfig {
             routes,
             layer_scenes,
             conditional_scene_cells,
+            controls,
             background,
         }))
     }
@@ -754,6 +776,27 @@ effect = {{ kind = "solid", color = [9, 8, 7] }}
         assert_eq!(battery.charge, super::LightingChargeCondition::Discharging);
     }
 
+    #[test]
+    fn resolves_and_validates_lighting_controls() {
+        let source = format!(
+            r#"{BASE}
+[lighting.controls]
+output_toggle_user_action = 13
+wake_layer = 1
+"#
+        );
+        let config = parse(&source);
+        let layout = config.layout().unwrap();
+        let keymap = config.keymap().unwrap();
+        let lighting = config.lighting(&layout, &keymap).unwrap().unwrap();
+        assert_eq!(lighting.controls.output_toggle_user_action, Some(13));
+        assert_eq!(lighting.controls.wake_layer, Some(1));
+
+        let invalid = parse(&source.replace("wake_layer = 1", "wake_layer = 2"));
+        let error = invalid.lighting(&layout, &keymap).unwrap_err();
+        assert!(error.contains("outside keymap layer count"), "{error}");
+    }
+
     #[test]
     fn rejects_invalid_conditional_battery_range() {
         let source = format!(
diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
index 218b54abe..dfe928d5d 100644
--- a/rmk-macro/src/codegen/lighting.rs
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -195,6 +195,14 @@ pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> To
         .iter()
         .map(expand_conditional_scene_cell);
     let conditional_cell_count = lighting.conditional_scene_cells.len();
+    let output_toggle_user_action = match lighting.controls.output_toggle_user_action {
+        Some(action) => quote! { Some(#action) },
+        None => quote! { None },
+    };
+    let wake_layer = match lighting.controls.wake_layer {
+        Some(layer) => quote! { Some(#layer) },
+        None => quote! { None },
+    };
     let background = &lighting.background;
     let background_enabled = background.enabled;
     let background_hue = background.hue;
@@ -220,6 +228,11 @@ pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> To
         pub static LIGHTING_CONDITIONAL_SCENE_CELLS:
             [::rmk::lighting::ConditionalSceneCell<::rmk::lighting::BuiltinEffect>; #conditional_cell_count] =
             [#(#conditional_cells),*];
+        pub const LIGHTING_CONTROLS: ::rmk::lighting::LightingControls =
+            ::rmk::lighting::LightingControls {
+                output_toggle_user_action: #output_toggle_user_action,
+                wake_layer: #wake_layer,
+            };
         pub const LIGHTING_BACKGROUND: ::rmk::lighting::BackgroundState =
             ::rmk::lighting::BackgroundState {
                 enabled: #background_enabled,
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 4d8607317..54407962b 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -620,11 +620,20 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Key/layer controls that gate the configured lighting presentation.
+    pub struct LightingControls {
+        pub output_toggle_user_action: Option<u8>,
+        pub wake_layer: Option<u8>,
+    }
+}
+
 wire_type! {
     pub struct LightingConditionalSceneStatus {
         pub topology_revision: u32,
         pub cell_len: u16,
         pub chunk_capacity: u8,
+        pub controls: LightingControls,
     }
 }
 
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 653559694..2b733d997 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -264,6 +264,7 @@ impl Handle<GetLightingConditionalSceneStatus> for RynkService<'_> {
             topology_revision: controller.descriptor.topology_revision,
             cell_len: count(controller.conditional_scenes.len()),
             chunk_capacity: LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE as u8,
+            controls: controller.controls_to_wire(),
         }))
     }
 }
@@ -1542,8 +1543,8 @@ mod tests {
         };
 
         use crate::lighting::{
-            BackgroundState, EmptySource, LayerPolicy, LayerScenes, LightingContext, LightingEngine, LightingMailbox,
-            StandardCommand, StandardError, StandardLightingEngine, StandardReply,
+            BackgroundState, EmptySource, LayerPolicy, LayerScenes, LightingContext, LightingControls, LightingEngine,
+            LightingMailbox, StandardCommand, StandardError, StandardLightingEngine, StandardReply,
         };
 
         block_on(async {
@@ -1557,7 +1558,11 @@ mod tests {
             let service = RynkService::new(&keymap, &config).with_lighting(
                 RynkLightingController::new(&mailbox, descriptor(), 8)
                     .with_scene_capacity(4)
-                    .with_conditional_scenes(&CONDITIONAL_CELLS),
+                    .with_conditional_scenes(&CONDITIONAL_CELLS)
+                    .with_controls(LightingControls {
+                        output_toggle_user_action: Some(13),
+                        wake_layer: Some(2),
+                    }),
             );
             let session = session(&keymap, &config);
 
@@ -1617,6 +1622,8 @@ mod tests {
                     .unwrap();
                 assert_eq!(conditional_status.topology_revision, 7);
                 assert_eq!(conditional_status.cell_len, 1);
+                assert_eq!(conditional_status.controls.output_toggle_user_action, Some(13));
+                assert_eq!(conditional_status.controls.wake_layer, Some(2));
                 let conditional = call::<GetLightingConditionalScenes>(
                     &service,
                     &session,
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 9561d8b56..f93014fdc 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -16,18 +16,19 @@ use embassy_sync::signal::Signal;
 use heapless::Vec;
 use rmk_types::protocol::rynk::{
     LIGHTING_OVERLAY_CHUNK_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState,
-    LightingCompiledScenesPage, LightingConditionalSceneCell as WireConditionalSceneCell, LightingError,
-    LightingLayerPolicy, LightingMutableState, LightingOverlayCell, LightingOverlayPage, LightingResult, LightingRgb8,
-    LightingSceneCell, LightingSceneTransaction, LightingScenesPage, LightingState,
+    LightingCompiledScenesPage, LightingConditionalSceneCell as WireConditionalSceneCell,
+    LightingControls as WireLightingControls, LightingError, LightingLayerPolicy, LightingMutableState,
+    LightingOverlayCell, LightingOverlayPage, LightingResult, LightingRgb8, LightingSceneCell,
+    LightingSceneTransaction, LightingScenesPage, LightingState,
 };
 
 use crate::RawMutex;
 use crate::core_traits::Runnable;
 use crate::lighting::{
-    BackgroundMode, BackgroundState, BuiltinEffect, ConditionalSceneCell, LayerPolicy, LedId, LightingMailbox,
-    LightingRouting, LightingTopology, OVERLAY_CHUNK_SIZE, OverlayBatch, OverlayCell, OverlayError, Rgb8, SceneChunk,
-    SceneTableCell, StandardCommand, StandardError, StandardLightingEngine, StandardMutableState, StandardReply,
-    StandardState,
+    BackgroundMode, BackgroundState, BuiltinEffect, ConditionalSceneCell, LayerPolicy, LedId, LightingControls,
+    LightingMailbox, LightingRouting, LightingTopology, OVERLAY_CHUNK_SIZE, OverlayBatch, OverlayCell, OverlayError,
+    Rgb8, SceneChunk, SceneTableCell, StandardCommand, StandardError, StandardLightingEngine, StandardMutableState,
+    StandardReply, StandardState,
 };
 
 const _: () = core::assert!(
@@ -65,6 +66,7 @@ pub struct RynkLightingController<'a> {
     /// with `Unsupported`.
     pub(super) scene_capacity: u16,
     pub(super) conditional_scenes: &'a [ConditionalSceneCell<BuiltinEffect>],
+    pub(super) controls: LightingControls,
     mailbox: &'a RynkLightingMailbox,
 }
 
@@ -86,6 +88,10 @@ impl<'a> RynkLightingController<'a> {
             },
             scene_capacity: 0,
             conditional_scenes: &[],
+            controls: LightingControls {
+                output_toggle_user_action: None,
+                wake_layer: None,
+            },
             mailbox,
         }
     }
@@ -103,6 +109,18 @@ impl<'a> RynkLightingController<'a> {
         self
     }
 
+    pub const fn with_controls(mut self, controls: LightingControls) -> Self {
+        self.controls = controls;
+        self
+    }
+
+    pub(super) const fn controls_to_wire(&self) -> WireLightingControls {
+        WireLightingControls {
+            output_toggle_user_action: self.controls.output_toggle_user_action,
+            wake_layer: self.controls.wake_layer,
+        }
+    }
+
     pub const fn descriptor(&self) -> RynkLightingDescriptor<'a> {
         self.descriptor
     }
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index 09181f407..9939f803d 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -39,7 +39,7 @@ pub use service::{
 pub use source::{
     BatteryCondition, BatteryStatusProvider, ChargeCondition, ConditionSet, ConditionalSceneCell, ConditionalScenes,
     DenseSource, Indicator, IndicatorScene, IndicatorScenes, LayerCondition, LayerPolicy, LayerScene, LayerScenes,
-    OverlayError, OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
+    LightingControls, OverlayError, OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
 };
 pub use standard::{
     BackgroundMode, BackgroundPatch, BackgroundState, CompiledScenePage, EmptySource, OVERLAY_CHUNK_SIZE, OverlayBatch,
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index bcbc5e344..8e6cfb007 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -183,6 +183,13 @@ pub struct ConditionSet {
     pub battery: Option<BatteryCondition>,
 }
 
+/// Optional board controls compiled from `[lighting.controls]`.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct LightingControls {
+    pub output_toggle_user_action: Option<u8>,
+    pub wake_layer: Option<u8>,
+}
+
 impl ConditionSet {
     fn matches<Context, Batteries>(&self, context: &Context, batteries: &Batteries) -> bool
     where

From 8b20e3112e9bc7c599b06c76a9686211811d00e8 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 14:59:15 -0700
Subject: [PATCH 24/78] feat(lighting): add declarative output modes

---
 .../main/docs/development/rynk_protocol.md    |   1 +
 rmk-config/src/lib.rs                         |  24 +-
 rmk-config/src/resolved/lighting.rs           | 105 +++++++--
 rmk-macro/src/codegen/lighting.rs             |  31 ++-
 rmk-types/src/action/light.rs                 |   2 +
 rmk-types/src/connection.rs                   |   7 +
 rmk-types/src/protocol/rynk/command.rs        |  17 +-
 .../src/protocol/rynk/payload/lighting.rs     |  37 ++++
 .../rynk/snapshots/lighting_wire_frames.snap  |   4 +-
 rmk-types/src/protocol/rynk/tests.rs          |  35 ++-
 rmk/src/host/rynk/handlers/lighting.rs        |  89 ++++++--
 rmk/src/host/rynk/lighting.rs                 |  38 +++-
 rmk/src/host/rynk/mod.rs                      |   2 +
 rmk/src/lighting/context.rs                   |   2 +
 rmk/src/lighting/mod.rs                       |   2 +-
 rmk/src/lighting/processor.rs                 |   9 +-
 rmk/src/lighting/rmk_state.rs                 |   1 +
 rmk/src/lighting/source.rs                    |  44 +++-
 rmk/src/lighting/standard.rs                  | 205 ++++++++++++++++--
 rynk/rynk-wasm/src/client.rs                  |   3 +-
 rynk/src/api.rs                               |   8 +-
 21 files changed, 598 insertions(+), 68 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 612d2420a..63e8d6cca 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -296,6 +296,7 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x091D` | `GetLightingCompiledScenes`         | `LightingPageRequest`                 | `LightingCompiledScenesPageResult`     | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                             |
 | `0x091E` | `GetLightingConditionalSceneStatus` | `()`                                  | `LightingConditionalSceneStatusResult` | `lighting`       | Discover immutable conditional lighting compiled from board config.                                                            |
 | `0x091F` | `GetLightingConditionalScenes`      | `LightingPageRequest`                 | `LightingConditionalScenesPageResult`  | `lighting`       | Conditional-scene pages are pinned to the firmware topology revision.                                                          |
+| `0x0920` | `GetLightingOutputMode`             | `()`                                  | `LightingOutputModeStateResult`        | `lighting`       | Read the configured three-state output policy and its live state.                                                              |
 
 ## Topics
 
diff --git a/rmk-config/src/lib.rs b/rmk-config/src/lib.rs
index 91455ce32..b35d187b2 100644
--- a/rmk-config/src/lib.rs
+++ b/rmk-config/src/lib.rs
@@ -572,11 +572,33 @@ pub(crate) struct LightingTomlConfig {
     pub background: Option<LightingBackgroundTomlConfig>,
 }
 
-#[derive(Clone, Copy, Debug, Deserialize)]
+#[derive(Clone, Debug, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub(crate) struct LightingControlsTomlConfig {
     pub output_toggle_user_action: Option<u8>,
+    pub output_mode_cycle_user_action: Option<u8>,
     pub wake_layer: Option<u8>,
+    #[serde(default)]
+    pub initial_output_mode: LightingOutputModeToml,
+    pub output_mode_indicator: Option<LightingOutputModeIndicatorTomlConfig>,
+}
+
+#[derive(Clone, Copy, Debug, Default, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum LightingOutputModeToml {
+    #[default]
+    AlwaysOn,
+    AlwaysOff,
+    PoweredOnly,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct LightingOutputModeIndicatorTomlConfig {
+    pub target: LightingTargetTomlConfig,
+    pub always_on: LightingEffectTomlConfig,
+    pub always_off: LightingEffectTomlConfig,
+    pub powered_only: LightingEffectTomlConfig,
 }
 
 fn default_topology_revision() -> u32 {
diff --git a/rmk-config/src/resolved/lighting.rs b/rmk-config/src/resolved/lighting.rs
index 7a46053cb..0da898cec 100644
--- a/rmk-config/src/resolved/lighting.rs
+++ b/rmk-config/src/resolved/lighting.rs
@@ -3,7 +3,8 @@ use std::collections::{HashMap, HashSet};
 use super::Keymap;
 use super::layout::{FixedPoint3, Layout};
 use crate::{
-    LightingBackgroundModeToml, LightingChargeConditionToml, LightingEffectTomlConfig, LightingTargetTomlConfig,
+    LightingBackgroundModeToml, LightingChargeConditionToml, LightingEffectTomlConfig, LightingOutputModeToml,
+    LightingTargetTomlConfig,
 };
 
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -109,10 +110,34 @@ pub struct LightingConditionalSceneCell {
     pub effect: LightingEffect,
 }
 
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum LightingOutputMode {
+    AlwaysOn,
+    AlwaysOff,
+    PoweredOnly,
+}
+
+impl Default for LightingOutputMode {
+    fn default() -> Self {
+        Self::AlwaysOn
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LightingOutputModeIndicator {
+    pub slot: u16,
+    pub always_on: LightingEffect,
+    pub always_off: LightingEffect,
+    pub powered_only: LightingEffect,
+}
+
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 pub struct LightingControls {
     pub output_toggle_user_action: Option<u8>,
+    pub output_mode_cycle_user_action: Option<u8>,
     pub wake_layer: Option<u8>,
+    pub initial_output_mode: LightingOutputMode,
+    pub output_mode_indicator: Option<LightingOutputModeIndicator>,
 }
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -250,20 +275,59 @@ impl crate::KeyboardTomlConfig {
             &zone_memberships,
             &zone_ids,
         )?;
-        let controls = config.controls.map_or(Ok(LightingControls::default()), |controls| {
-            if let Some(layer) = controls.wake_layer
-                && layer >= keymap.layers
-            {
-                return Err(format!(
-                    "lighting.controls wake_layer {} is outside keymap layer count {}",
-                    layer, keymap.layers
-                ));
-            }
-            Ok(LightingControls {
-                output_toggle_user_action: controls.output_toggle_user_action,
-                wake_layer: controls.wake_layer,
-            })
-        })?;
+        let controls = config
+            .controls
+            .clone()
+            .map_or(Ok(LightingControls::default()), |controls| {
+                if let Some(layer) = controls.wake_layer
+                    && layer >= keymap.layers
+                {
+                    return Err(format!(
+                        "lighting.controls wake_layer {} is outside keymap layer count {}",
+                        layer, keymap.layers
+                    ));
+                }
+                Ok(LightingControls {
+                    output_toggle_user_action: controls.output_toggle_user_action,
+                    output_mode_cycle_user_action: controls.output_mode_cycle_user_action,
+                    wake_layer: controls.wake_layer,
+                    initial_output_mode: match controls.initial_output_mode {
+                        LightingOutputModeToml::AlwaysOn => LightingOutputMode::AlwaysOn,
+                        LightingOutputModeToml::AlwaysOff => LightingOutputMode::AlwaysOff,
+                        LightingOutputModeToml::PoweredOnly => LightingOutputMode::PoweredOnly,
+                    },
+                    output_mode_indicator: controls
+                        .output_mode_indicator
+                        .as_ref()
+                        .map(|indicator| {
+                            let id_to_slot: HashMap<u16, u16> = emitters
+                                .iter()
+                                .enumerate()
+                                .map(|(slot, emitter)| (emitter.id, slot as u16))
+                                .collect();
+                            let slots = resolve_target_slots(
+                                &indicator.target,
+                                &id_to_slot,
+                                &emitters,
+                                &zone_memberships,
+                                &zone_ids,
+                            )?;
+                            if slots.len() != 1 {
+                                return Err(
+                                    "lighting.controls output_mode_indicator must resolve to exactly one LED"
+                                        .to_owned(),
+                                );
+                            }
+                            Ok(LightingOutputModeIndicator {
+                                slot: slots[0],
+                                always_on: resolve_effect(&indicator.always_on)?,
+                                always_off: resolve_effect(&indicator.always_off)?,
+                                powered_only: resolve_effect(&indicator.powered_only)?,
+                            })
+                        })
+                        .transpose()?,
+                })
+            })?;
         let background = config
             .background
             .as_ref()
@@ -782,7 +846,15 @@ effect = {{ kind = "solid", color = [9, 8, 7] }}
             r#"{BASE}
 [lighting.controls]
 output_toggle_user_action = 13
+output_mode_cycle_user_action = 14
 wake_layer = 1
+initial_output_mode = "powered_only"
+
+[lighting.controls.output_mode_indicator]
+target = {{ led = 10 }}
+always_on = {{ kind = "solid", color = [0, 9, 0] }}
+always_off = {{ kind = "solid", color = [9, 0, 0] }}
+powered_only = {{ kind = "solid", color = [0, 0, 9] }}
 "#
         );
         let config = parse(&source);
@@ -790,7 +862,10 @@ wake_layer = 1
         let keymap = config.keymap().unwrap();
         let lighting = config.lighting(&layout, &keymap).unwrap().unwrap();
         assert_eq!(lighting.controls.output_toggle_user_action, Some(13));
+        assert_eq!(lighting.controls.output_mode_cycle_user_action, Some(14));
         assert_eq!(lighting.controls.wake_layer, Some(1));
+        assert_eq!(lighting.controls.initial_output_mode, LightingOutputMode::PoweredOnly);
+        assert_eq!(lighting.controls.output_mode_indicator.unwrap().slot, 0);
 
         let invalid = parse(&source.replace("wake_layer = 1", "wake_layer = 2"));
         let error = invalid.lighting(&layout, &keymap).unwrap_err();
diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
index dfe928d5d..7b8a0ce3f 100644
--- a/rmk-macro/src/codegen/lighting.rs
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -4,7 +4,7 @@ use proc_macro2::TokenStream as TokenStream2;
 use quote::quote;
 use rmk_config::resolved::lighting::{
     Lighting, LightingBackgroundMode, LightingChargeCondition, LightingConditionalSceneCell,
-    LightingEffect, LightingSceneCell,
+    LightingEffect, LightingOutputMode, LightingSceneCell,
 };
 use rmk_config::resolved::{FixedPoint3, PhysicalLayout};
 
@@ -199,10 +199,36 @@ pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> To
         Some(action) => quote! { Some(#action) },
         None => quote! { None },
     };
+    let output_mode_cycle_user_action = match lighting.controls.output_mode_cycle_user_action {
+        Some(action) => quote! { Some(#action) },
+        None => quote! { None },
+    };
     let wake_layer = match lighting.controls.wake_layer {
         Some(layer) => quote! { Some(#layer) },
         None => quote! { None },
     };
+    let initial_output_mode = match lighting.controls.initial_output_mode {
+        LightingOutputMode::AlwaysOn => quote! { ::rmk::lighting::OutputMode::AlwaysOn },
+        LightingOutputMode::AlwaysOff => quote! { ::rmk::lighting::OutputMode::AlwaysOff },
+        LightingOutputMode::PoweredOnly => quote! { ::rmk::lighting::OutputMode::PoweredOnly },
+    };
+    let output_mode_indicator = match lighting.controls.output_mode_indicator {
+        Some(indicator) => {
+            let slot = indicator.slot;
+            let always_on = expand_effect(indicator.always_on);
+            let always_off = expand_effect(indicator.always_off);
+            let powered_only = expand_effect(indicator.powered_only);
+            quote! {
+                Some(::rmk::lighting::OutputModeIndicator {
+                    slot: ::rmk::lighting::LedSlot(#slot),
+                    always_on: #always_on,
+                    always_off: #always_off,
+                    powered_only: #powered_only,
+                })
+            }
+        }
+        None => quote! { None },
+    };
     let background = &lighting.background;
     let background_enabled = background.enabled;
     let background_hue = background.hue;
@@ -231,7 +257,10 @@ pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> To
         pub const LIGHTING_CONTROLS: ::rmk::lighting::LightingControls =
             ::rmk::lighting::LightingControls {
                 output_toggle_user_action: #output_toggle_user_action,
+                output_mode_cycle_user_action: #output_mode_cycle_user_action,
                 wake_layer: #wake_layer,
+                initial_output_mode: #initial_output_mode,
+                output_mode_indicator: #output_mode_indicator,
             };
         pub const LIGHTING_BACKGROUND: ::rmk::lighting::BackgroundState =
             ::rmk::lighting::BackgroundState {
diff --git a/rmk-types/src/action/light.rs b/rmk-types/src/action/light.rs
index 5ea4b2c82..459b51721 100644
--- a/rmk-types/src/action/light.rs
+++ b/rmk-types/src/action/light.rs
@@ -40,4 +40,6 @@ pub enum LightAction {
     // Not in vial
     RgbModeRgbtest,
     RgbModeTwinkle,
+    /// Cycle standard lighting through always-on, always-off, and powered-only.
+    OutputModeCycle,
 }
diff --git a/rmk-types/src/connection.rs b/rmk-types/src/connection.rs
index 037a2cc2c..bdb379d82 100644
--- a/rmk-types/src/connection.rs
+++ b/rmk-types/src/connection.rs
@@ -31,6 +31,13 @@ pub enum UsbState {
     Suspended,
 }
 
+impl UsbState {
+    /// Whether VBUS is present, independent of enumeration or suspension.
+    pub const fn is_powered(self) -> bool {
+        !matches!(self, Self::Disabled)
+    }
+}
+
 /// Unified connection status: the single source of truth for transport
 /// availability and routing. The active transport is derived on demand via
 /// [`Self::decide_active`] from the input fields below.
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 0e4ee3ab2..3aa358669 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -39,13 +39,13 @@ use crate::protocol::rynk::{
     BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest,
     CommitLightingSceneReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingCompiledSceneStatusResult,
     LightingCompiledScenesPageResult, LightingConditionalSceneStatusResult, LightingConditionalScenesPageResult,
-    LightingKeysPageResult, LightingLedsPageResult, LightingOutputsPageResult, LightingOverlayPageRequest,
-    LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKeysPageResult,
-    LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatusResult, LightingSceneTransactionResult,
-    LightingScenesPageResult, LightingStateResult, LightingUnitResult, LightingZoneMembershipsPageResult,
-    LightingZonesPageResult, PutLightingOverlayChunkRequest, PutLightingSceneChunkRequest,
-    SetLightingLayerPolicyRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
-    UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
+    LightingKeysPageResult, LightingLedsPageResult, LightingOutputModeStateResult, LightingOutputsPageResult,
+    LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest,
+    LightingPhysicalKeysPageResult, LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatusResult,
+    LightingSceneTransactionResult, LightingScenesPageResult, LightingStateResult, LightingUnitResult,
+    LightingZoneMembershipsPageResult, LightingZonesPageResult, PutLightingOverlayChunkRequest,
+    PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
+    SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 #[cfg(all(feature = "_ble", feature = "split"))]
 use crate::protocol::rynk::{SplitCentralLatencyPolicy, SplitCentralLatencyState};
@@ -442,6 +442,9 @@ endpoints! {
     /// Conditional-scene pages are pinned to the firmware topology revision.
     #[cfg(feature = "lighting")]
     GetLightingConditionalScenes = 0x091F: LightingPageRequest => LightingConditionalScenesPageResult;
+    /// Read the configured three-state output policy and its live state.
+    #[cfg(feature = "lighting")]
+    GetLightingOutputMode = 0x0920: () => LightingOutputModeStateResult;
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 54407962b..35ce9de3b 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -190,6 +190,8 @@ impl LightingFeatureFlags {
     pub const COMPILED_LAYER_SCENES: u16 = 1 << 8;
     /// Read-only board-compiled rules driven by layer and battery state.
     pub const COMPILED_CONDITIONAL_SCENES: u16 = 1 << 9;
+    /// Declarative three-state output policy and live readback.
+    pub const OUTPUT_MODE: u16 = 1 << 10;
 
     pub const fn contains(self, bits: u16) -> bool {
         self.0 & bits == bits
@@ -628,6 +630,39 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Persistent policy selected by the board's configured cycle action.
+    pub enum LightingOutputMode {
+        AlwaysOn,
+        AlwaysOff,
+        PoweredOnly,
+    }
+}
+
+wire_type! {
+    /// Configured status LED and its mode-specific effects.
+    pub struct LightingOutputModeIndicator {
+        pub led_id: LightingLedId,
+        pub always_on: LightingEffect,
+        pub always_off: LightingEffect,
+        pub powered_only: LightingEffect,
+    }
+}
+
+wire_type! {
+    /// Authoritative output policy plus the inputs that determine whether the
+    /// LEDs are physically enabled right now.
+    pub struct LightingOutputModeState {
+        pub mode: LightingOutputMode,
+        pub powered: bool,
+        pub wake_active: bool,
+        pub effective_enabled: bool,
+        pub cycle_user_action: Option<u8>,
+        pub wake_layer: Option<u8>,
+        pub indicator: Option<LightingOutputModeIndicator>,
+    }
+}
+
 wire_type! {
     pub struct LightingConditionalSceneStatus {
         pub topology_revision: u32,
@@ -769,6 +804,7 @@ pub type LightingCompiledSceneStatusResult = LightingResult<LightingCompiledScen
 pub type LightingCompiledScenesPageResult = LightingResult<LightingCompiledScenesPage>;
 pub type LightingConditionalSceneStatusResult = LightingResult<LightingConditionalSceneStatus>;
 pub type LightingConditionalScenesPageResult = LightingResult<LightingConditionalScenesPage>;
+pub type LightingOutputModeStateResult = LightingResult<LightingOutputModeState>;
 pub type LightingSceneTransactionResult = LightingResult<LightingSceneTransaction>;
 pub type LightingUnitResult = LightingResult<()>;
 
@@ -812,6 +848,7 @@ const _: () = {
     assert_endpoint_fits!(LightingPageRequest, LightingCompiledScenesPageResult);
     assert_endpoint_fits!((), LightingConditionalSceneStatusResult);
     assert_endpoint_fits!(LightingPageRequest, LightingConditionalScenesPageResult);
+    assert_endpoint_fits!((), LightingOutputModeStateResult);
     assert_endpoint_fits!(SetLightingSceneCellRequest, LightingStateResult);
     assert_endpoint_fits!(UnsetLightingSceneCellRequest, LightingStateResult);
     assert_endpoint_fits!(SetLightingLayerPolicyRequest, LightingStateResult);
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index 3e4975da6..03f1fb48d 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -19,7 +19,7 @@ CommitLightingOverlayReplace reply                     0f 09 01 0c 00 00 00 09 0
 CommitLightingOverlayReplace request                   0f 09 01 01 00 0d
 CommitLightingSceneReplace reply                       18 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 CommitLightingSceneReplace request                     18 09 01 01 00 15
-GetLightingCapabilities reply                          01 09 01 10 00 00 00 01 02 03 04 05 06 07 08 09 08 08 bf 03 07
+GetLightingCapabilities reply                          01 09 01 10 00 00 00 01 02 03 04 05 06 07 08 09 08 08 bf 0b 07
 GetLightingCapabilities request                        01 09 01 00 00
 GetLightingCompiledSceneStatus reply                   1c 09 01 06 00 00 00 01 01 00 08
 GetLightingCompiledSceneStatus request                 1c 09 01 00 00
@@ -29,6 +29,8 @@ GetLightingKeys reply                                  11 09 01 07 00 00 00 01 0
 GetLightingKeys request                                11 09 01 02 00 01 00
 GetLightingLeds reply                                  05 09 01 12 00 00 00 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01
 GetLightingLeds request                                05 09 01 02 00 01 00
+GetLightingOutputMode reply                            20 09 01 18 00 00 00 02 01 00 01 01 0d 01 02 01 2a 00 00 09 00 00 09 00 00 00 00 00 09
+GetLightingOutputMode request                          20 09 01 00 00
 GetLightingOutputs reply                               08 09 01 0a 00 00 00 01 01 01 01 02 28 14 00
 GetLightingOutputs request                             08 09 01 02 00 01 00
 GetLightingOverlay reply                               1b 09 01 12 00 00 00 09 01 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 5389a19fc..a9c3752b4 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1139,7 +1139,8 @@ fn lighting_wire_frames_locked() {
                 | LightingFeatureFlags::ATOMIC_OVERLAY_REPLACE
                 | LightingFeatureFlags::LAYER_AWARE
                 | LightingFeatureFlags::OVERLAY_READBACK
-                | LightingFeatureFlags::COMPILED_LAYER_SCENES,
+                | LightingFeatureFlags::COMPILED_LAYER_SCENES
+                | LightingFeatureFlags::OUTPUT_MODE,
         ),
         effects: LightingEffectFlags(
             LightingEffectFlags::SOLID | LightingEffectFlags::BLINK | LightingEffectFlags::BREATHE,
@@ -1315,6 +1316,26 @@ fn lighting_wire_frames_locked() {
     let scene_abort = AbortLightingSceneReplaceRequest {
         transaction_id: scene_transaction.id,
     };
+    let output_mode = LightingOutputModeState {
+        mode: LightingOutputMode::PoweredOnly,
+        powered: true,
+        wake_active: false,
+        effective_enabled: true,
+        cycle_user_action: Some(13),
+        wake_layer: Some(2),
+        indicator: Some(LightingOutputModeIndicator {
+            led_id: led.id,
+            always_on: LightingEffect::Solid {
+                color: LightingRgb8 { r: 0, g: 9, b: 0 },
+            },
+            always_off: LightingEffect::Solid {
+                color: LightingRgb8 { r: 9, g: 0, b: 0 },
+            },
+            powered_only: LightingEffect::Solid {
+                color: LightingRgb8 { r: 0, g: 0, b: 9 },
+            },
+        }),
+    };
 
     let entries: alloc::vec::Vec<(&str, alloc::vec::Vec<u8>)> = alloc::vec![
         (
@@ -1353,6 +1374,18 @@ fn lighting_wire_frames_locked() {
                 &Ok::<LightingStateResult, RynkError>(Ok(state))
             )
         ),
+        (
+            "GetLightingOutputMode request",
+            encode_frame(Cmd::GetLightingOutputMode, SEQ, &())
+        ),
+        (
+            "GetLightingOutputMode reply",
+            encode_frame(
+                Cmd::GetLightingOutputMode,
+                SEQ,
+                &Ok::<LightingOutputModeStateResult, RynkError>(Ok(output_mode))
+            )
+        ),
         (
             "GetLightingPhysicalKeys request",
             encode_frame(Cmd::GetLightingPhysicalKeys, SEQ, &page_request)
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 2b733d997..c0bde3979 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -5,9 +5,10 @@ use heapless::{String, Vec};
 use rmk_types::protocol::rynk::command::{
     ClearLightingOverlay, GetLightingCapabilities, GetLightingCompiledSceneStatus, GetLightingCompiledScenes,
     GetLightingConditionalSceneStatus, GetLightingConditionalScenes, GetLightingKeys, GetLightingLeds,
-    GetLightingOutputs, GetLightingOverlay, GetLightingPhysicalKeys, GetLightingRoutes, GetLightingSceneStatus,
-    GetLightingScenes, GetLightingState, GetLightingZoneMemberships, GetLightingZones, SetLightingLayerPolicy,
-    SetLightingOverlay, SetLightingSceneCell, SetLightingState, UnsetLightingOverlay, UnsetLightingSceneCell,
+    GetLightingOutputMode, GetLightingOutputs, GetLightingOverlay, GetLightingPhysicalKeys, GetLightingRoutes,
+    GetLightingSceneStatus, GetLightingScenes, GetLightingState, GetLightingZoneMemberships, GetLightingZones,
+    SetLightingLayerPolicy, SetLightingOverlay, SetLightingSceneCell, SetLightingState, UnsetLightingOverlay,
+    UnsetLightingSceneCell,
 };
 use rmk_types::protocol::rynk::{
     AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
@@ -19,15 +20,16 @@ use rmk_types::protocol::rynk::{
     LightingConditionalScenesPage, LightingConditionalScenesPageResult, LightingEffectFlags, LightingError,
     LightingFeatureFlags, LightingKeysPage, LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage,
     LightingLedsPageResult, LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage,
-    LightingOutputsPage, LightingOutputsPageResult, LightingOverlayCell, LightingOverlayPageRequest,
-    LightingOverlayPageResult, LightingOverlayTransaction, LightingOverlayTransactionResult, LightingPageRequest,
-    LightingPhysicalKey, LightingPhysicalKeysPage, LightingPhysicalKeysPageResult, LightingPoint3, LightingResult,
-    LightingRoute, LightingRoutesPage, LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatus,
-    LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult, LightingState,
-    LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage,
-    LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult, PutLightingOverlayChunkRequest,
-    PutLightingSceneChunkRequest, RynkError, RynkMessage, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
-    SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
+    LightingOutputModeStateResult, LightingOutputsPage, LightingOutputsPageResult, LightingOverlayCell,
+    LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransaction,
+    LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKey, LightingPhysicalKeysPage,
+    LightingPhysicalKeysPageResult, LightingPoint3, LightingResult, LightingRoute, LightingRoutesPage,
+    LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatus, LightingSceneStatusResult,
+    LightingSceneTransactionResult, LightingScenesPageResult, LightingState, LightingStateResult, LightingUnitResult,
+    LightingZone, LightingZoneId, LightingZoneMembershipsPage, LightingZoneMembershipsPageResult, LightingZonesPage,
+    LightingZonesPageResult, PutLightingOverlayChunkRequest, PutLightingSceneChunkRequest, RynkError, RynkMessage,
+    SetLightingLayerPolicyRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
+    UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 
 use super::super::lighting::{
@@ -68,6 +70,23 @@ impl Handle<GetLightingState> for RynkService<'_> {
     }
 }
 
+impl Handle<GetLightingOutputMode> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LightingOutputModeStateResult, RynkError> {
+        Ok(match controller(self) {
+            Ok(controller) => {
+                controller
+                    .request(RynkLightingCommand::ReadOutputMode)
+                    .await
+                    .and_then(|reply| match reply {
+                        RynkLightingReadback::OutputMode(state) => Ok(controller.output_mode_to_wire(state)),
+                        _ => Err(LightingError::InvalidRequest),
+                    })
+            }
+            Err(error) => Err(error),
+        })
+    }
+}
+
 impl Handle<GetLightingOverlay> for RynkService<'_> {
     async fn handle(&self, req: LightingOverlayPageRequest) -> Result<LightingOverlayPageResult, RynkError> {
         let result = match controller(self) {
@@ -515,6 +534,9 @@ fn capabilities(binding: RynkLightingController<'_>) -> LightingCapabilities {
     if !binding.conditional_scenes.is_empty() {
         features.0 |= LightingFeatureFlags::COMPILED_CONDITIONAL_SCENES;
     }
+    if binding.controls.output_mode_cycle_user_action.is_some() {
+        features.0 |= LightingFeatureFlags::OUTPUT_MODE;
+    }
     LightingCapabilities {
         topology_revision: descriptor.topology_revision,
         logical_key_count: count(topology.keys.len()),
@@ -1531,8 +1553,8 @@ mod tests {
         use rmk_types::protocol::rynk::command::{
             AbortLightingSceneReplace, BeginLightingSceneReplace, CommitLightingSceneReplace,
             GetLightingCompiledSceneStatus, GetLightingCompiledScenes, GetLightingConditionalSceneStatus,
-            GetLightingConditionalScenes, GetLightingOverlay, GetLightingSceneStatus, GetLightingScenes,
-            PutLightingSceneChunk, SetLightingLayerPolicy, SetLightingOverlay, SetLightingSceneCell,
+            GetLightingConditionalScenes, GetLightingOutputMode, GetLightingOverlay, GetLightingSceneStatus,
+            GetLightingScenes, PutLightingSceneChunk, SetLightingLayerPolicy, SetLightingOverlay, SetLightingSceneCell,
             UnsetLightingSceneCell,
         };
         use rmk_types::protocol::rynk::{
@@ -1543,8 +1565,9 @@ mod tests {
         };
 
         use crate::lighting::{
-            BackgroundState, EmptySource, LayerPolicy, LayerScenes, LightingContext, LightingControls, LightingEngine,
-            LightingMailbox, StandardCommand, StandardError, StandardLightingEngine, StandardReply,
+            BackgroundState, BuiltinEffect, EmptySource, LayerPolicy, LayerScenes, LedSlot, LightingContext,
+            LightingControls, LightingEngine, LightingMailbox, OutputMode, OutputModeIndicator, Rgb8, StandardCommand,
+            StandardError, StandardLightingEngine, StandardReply,
         };
 
         block_on(async {
@@ -1555,14 +1578,23 @@ mod tests {
             let mut config = RmkConfig::default();
             config.lock_config.insecure = true;
             let mailbox = RynkLightingMailbox::new();
+            let controls = LightingControls {
+                output_toggle_user_action: Some(13),
+                output_mode_cycle_user_action: Some(14),
+                wake_layer: Some(1),
+                initial_output_mode: OutputMode::PoweredOnly,
+                output_mode_indicator: Some(OutputModeIndicator {
+                    slot: LedSlot(0),
+                    always_on: BuiltinEffect::solid(Rgb8::new(0, 9, 0)),
+                    always_off: BuiltinEffect::solid(Rgb8::new(9, 0, 0)),
+                    powered_only: BuiltinEffect::solid(Rgb8::new(0, 0, 9)),
+                }),
+            };
             let service = RynkService::new(&keymap, &config).with_lighting(
                 RynkLightingController::new(&mailbox, descriptor(), 8)
                     .with_scene_capacity(4)
                     .with_conditional_scenes(&CONDITIONAL_CELLS)
-                    .with_controls(LightingControls {
-                        output_toggle_user_action: Some(13),
-                        wake_layer: Some(2),
-                    }),
+                    .with_controls(controls),
             );
             let session = session(&keymap, &config);
 
@@ -1581,7 +1613,8 @@ mod tests {
                     },
                     EmptySource,
                     EmptySource,
-                );
+                )
+                .with_controls(controls);
 
             let lighting = capabilities(service.lighting.unwrap());
             assert!(lighting.features.contains(LightingFeatureFlags::LAYER_SCENES));
@@ -1592,6 +1625,7 @@ mod tests {
                     .features
                     .contains(LightingFeatureFlags::COMPILED_CONDITIONAL_SCENES)
             );
+            assert!(lighting.features.contains(LightingFeatureFlags::OUTPUT_MODE));
 
             let client = async {
                 let compiled_status = call::<GetLightingCompiledSceneStatus>(&service, &session, &())
@@ -1623,7 +1657,18 @@ mod tests {
                 assert_eq!(conditional_status.topology_revision, 7);
                 assert_eq!(conditional_status.cell_len, 1);
                 assert_eq!(conditional_status.controls.output_toggle_user_action, Some(13));
-                assert_eq!(conditional_status.controls.wake_layer, Some(2));
+                assert_eq!(conditional_status.controls.wake_layer, Some(1));
+                let output_mode = call::<GetLightingOutputMode>(&service, &session, &())
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(
+                    output_mode.mode,
+                    rmk_types::protocol::rynk::LightingOutputMode::PoweredOnly
+                );
+                assert_eq!(output_mode.cycle_user_action, Some(14));
+                assert_eq!(output_mode.wake_layer, Some(1));
+                assert_eq!(output_mode.indicator.unwrap().led_id, LightingLedId(10));
                 let conditional = call::<GetLightingConditionalScenes>(
                     &service,
                     &session,
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index f93014fdc..c92434f83 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -18,7 +18,8 @@ use rmk_types::protocol::rynk::{
     LIGHTING_OVERLAY_CHUNK_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState,
     LightingCompiledScenesPage, LightingConditionalSceneCell as WireConditionalSceneCell,
     LightingControls as WireLightingControls, LightingError, LightingLayerPolicy, LightingMutableState,
-    LightingOverlayCell, LightingOverlayPage, LightingResult, LightingRgb8, LightingSceneCell,
+    LightingOutputMode as WireLightingOutputMode, LightingOutputModeIndicator as WireLightingOutputModeIndicator,
+    LightingOutputModeState, LightingOverlayCell, LightingOverlayPage, LightingResult, LightingRgb8, LightingSceneCell,
     LightingSceneTransaction, LightingScenesPage, LightingState,
 };
 
@@ -90,7 +91,10 @@ impl<'a> RynkLightingController<'a> {
             conditional_scenes: &[],
             controls: LightingControls {
                 output_toggle_user_action: None,
+                output_mode_cycle_user_action: None,
                 wake_layer: None,
+                initial_output_mode: crate::lighting::OutputMode::AlwaysOn,
+                output_mode_indicator: None,
             },
             mailbox,
         }
@@ -121,6 +125,32 @@ impl<'a> RynkLightingController<'a> {
         }
     }
 
+    pub(super) fn output_mode_to_wire(&self, state: StandardState) -> LightingOutputModeState {
+        LightingOutputModeState {
+            mode: match state.output_mode {
+                crate::lighting::OutputMode::AlwaysOn => WireLightingOutputMode::AlwaysOn,
+                crate::lighting::OutputMode::AlwaysOff => WireLightingOutputMode::AlwaysOff,
+                crate::lighting::OutputMode::PoweredOnly => WireLightingOutputMode::PoweredOnly,
+            },
+            powered: state.powered,
+            wake_active: state.wake_active,
+            effective_enabled: state.output_enabled,
+            cycle_user_action: self.controls.output_mode_cycle_user_action,
+            wake_layer: self.controls.wake_layer,
+            indicator: self.controls.output_mode_indicator.and_then(|indicator| {
+                self.descriptor
+                    .topology
+                    .led(indicator.slot)
+                    .map(|led| WireLightingOutputModeIndicator {
+                        led_id: rmk_types::protocol::rynk::LightingLedId(led.id.0),
+                        always_on: effect_to_wire(indicator.always_on),
+                        always_off: effect_to_wire(indicator.always_off),
+                        powered_only: effect_to_wire(indicator.powered_only),
+                    })
+            }),
+        }
+    }
+
     pub const fn descriptor(&self) -> RynkLightingDescriptor<'a> {
         self.descriptor
     }
@@ -168,6 +198,7 @@ impl<'a> RynkLightingController<'a> {
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum RynkLightingReadback {
     State(LightingState),
+    OutputMode(StandardState),
     OverlayPage(LightingOverlayPage),
     SceneStatus {
         revision: u32,
@@ -331,6 +362,7 @@ impl Default for RynkLightingMailbox {
 
 pub(super) enum RynkLightingCommand {
     ReadState,
+    ReadOutputMode,
     ReadOverlay {
         expected_revision: u32,
         offset: u16,
@@ -518,6 +550,10 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
     async fn dispatch(&self, request_id: u32, command: RynkLightingCommand) -> LightingResult<RynkLightingReadback> {
         let core_command = match command {
             RynkLightingCommand::ReadState => StandardCommand::ReadState,
+            RynkLightingCommand::ReadOutputMode => {
+                let state = self.request_core_state(StandardCommand::ReadState).await?;
+                return Ok(RynkLightingReadback::OutputMode(state));
+            }
             RynkLightingCommand::ReadOverlay {
                 expected_revision,
                 offset,
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 2a6035eb5..18ac9e1af 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -315,6 +315,8 @@ impl<'a> RynkService<'a> {
                 Serve::<command::GetLightingConditionalScenes, _>::serve(self, msg).await
             }
             #[cfg(feature = "lighting")]
+            Cmd::GetLightingOutputMode => Serve::<command::GetLightingOutputMode, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
             Cmd::SetLightingSceneCell => Serve::<command::SetLightingSceneCell, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::UnsetLightingSceneCell => Serve::<command::UnsetLightingSceneCell, _>::serve(self, msg).await,
diff --git a/rmk/src/lighting/context.rs b/rmk/src/lighting/context.rs
index 594ac8f12..1a6e47d71 100644
--- a/rmk/src/lighting/context.rs
+++ b/rmk/src/lighting/context.rs
@@ -56,6 +56,8 @@ pub struct IndicatorState {
 pub struct LightingContext {
     pub layers: LayerState,
     pub indicators: IndicatorState,
+    /// USB/VBUS power is present. This remains true while USB is suspended.
+    pub powered: bool,
 }
 
 /// Access to RMK's standard lighting state from a board-extended snapshot.
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index 9939f803d..8c044c6c2 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -39,7 +39,7 @@ pub use service::{
 pub use source::{
     BatteryCondition, BatteryStatusProvider, ChargeCondition, ConditionSet, ConditionalSceneCell, ConditionalScenes,
     DenseSource, Indicator, IndicatorScene, IndicatorScenes, LayerCondition, LayerPolicy, LayerScene, LayerScenes,
-    LightingControls, OverlayError, OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
+    LightingControls, OutputMode, OutputModeIndicator, OverlayError, OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
 };
 pub use standard::{
     BackgroundMode, BackgroundPatch, BackgroundState, CompiledScenePage, EmptySource, OVERLAY_CHUNK_SIZE, OverlayBatch,
diff --git a/rmk/src/lighting/processor.rs b/rmk/src/lighting/processor.rs
index 0581a5389..00f6d80ed 100644
--- a/rmk/src/lighting/processor.rs
+++ b/rmk/src/lighting/processor.rs
@@ -18,7 +18,8 @@ use super::service::{
 use crate::RawMutex;
 use crate::core_traits::Runnable;
 use crate::event::{
-    EventSubscriber, LayerChangeEvent, LedIndicatorEvent, LightingChangedEvent, SleepStateEvent, publish_event,
+    ConnectionStatusChangeEvent, EventSubscriber, LayerChangeEvent, LedIndicatorEvent, LightingChangedEvent,
+    SleepStateEvent, publish_event,
 };
 use crate::processor::Processor;
 
@@ -119,7 +120,7 @@ impl<Command, Reply, Error, const CAPACITY: usize> Default for LightingMailbox<C
 /// State notifications invalidate a fresh authoritative snapshot. LightAction
 /// edges and mailbox commands remain reliable and ordered. The loop arms only
 /// the deadline returned by the service; static output has no timer.
-#[::rmk::macros::processor(subscribe = [LayerChangeEvent, LedIndicatorEvent, SleepStateEvent])]
+#[::rmk::macros::processor(subscribe = [LayerChangeEvent, LedIndicatorEvent, SleepStateEvent, ConnectionStatusChangeEvent])]
 #[::rmk::macros::runnable_generated]
 pub struct LightingProcessor<'mailbox, P, E, O, const COMMAND_CAPACITY: usize>
 where
@@ -256,6 +257,10 @@ where
         self.service.request_render();
     }
 
+    async fn on_connection_status_change_event(&mut self, _event: ConnectionStatusChangeEvent) {
+        self.service.request_render();
+    }
+
     async fn on_sleep_state_event(&mut self, event: SleepStateEvent) {
         let target = if event.0 {
             PowerState::Suspended
diff --git a/rmk/src/lighting/rmk_state.rs b/rmk/src/lighting/rmk_state.rs
index 48dd83769..42f931e6b 100644
--- a/rmk/src/lighting/rmk_state.rs
+++ b/rmk/src/lighting/rmk_state.rs
@@ -51,6 +51,7 @@ impl SnapshotProvider for KeymapLightingState<'_, '_> {
         LightingContext {
             layers: LayerState::new(effective, default, active),
             indicators: indicator_state(),
+            powered: crate::state::current_usb_state().is_powered(),
         }
     }
 }
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index 8e6cfb007..26fecf58a 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -1,6 +1,6 @@
 use super::compositor::{Contribution, LightingSource, RenderInput};
 use super::context::{LightingContext, LightingContextProvider};
-use super::effect::{EffectSample, LightingEffect};
+use super::effect::{BuiltinEffect, EffectSample, LightingEffect};
 use super::topology::LedSlot;
 use crate::types::battery::{BatteryStatus, ChargeState};
 
@@ -183,11 +183,51 @@ pub struct ConditionSet {
     pub battery: Option<BatteryCondition>,
 }
 
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub enum OutputMode {
+    #[default]
+    AlwaysOn,
+    AlwaysOff,
+    PoweredOnly,
+}
+
+impl OutputMode {
+    pub const fn next(self) -> Self {
+        match self {
+            Self::AlwaysOn => Self::AlwaysOff,
+            Self::AlwaysOff => Self::PoweredOnly,
+            Self::PoweredOnly => Self::AlwaysOn,
+        }
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct OutputModeIndicator {
+    pub slot: LedSlot,
+    pub always_on: BuiltinEffect,
+    pub always_off: BuiltinEffect,
+    pub powered_only: BuiltinEffect,
+}
+
+impl OutputModeIndicator {
+    pub const fn effect(self, mode: OutputMode) -> BuiltinEffect {
+        match mode {
+            OutputMode::AlwaysOn => self.always_on,
+            OutputMode::AlwaysOff => self.always_off,
+            OutputMode::PoweredOnly => self.powered_only,
+        }
+    }
+}
+
 /// Optional board controls compiled from `[lighting.controls]`.
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
 pub struct LightingControls {
+    /// Legacy two-state action retained for existing boards.
     pub output_toggle_user_action: Option<u8>,
+    pub output_mode_cycle_user_action: Option<u8>,
     pub wake_layer: Option<u8>,
+    pub initial_output_mode: OutputMode,
+    pub output_mode_indicator: Option<OutputModeIndicator>,
 }
 
 impl ConditionSet {
@@ -602,6 +642,7 @@ mod tests {
         let context = LightingContext {
             layers: LayerState::new(3, 0, 0b1101),
             indicators: Default::default(),
+            powered: false,
         };
         let compositor = Compositor::<Rgb8, 2>::new(Rgb8::BLACK);
         let mut frame = LogicalFrame::new(Rgb8::BLACK);
@@ -729,6 +770,7 @@ mod tests {
         let context = LightingContext {
             layers: LayerState::new(2, 0, 0b101),
             indicators: Default::default(),
+            powered: false,
         };
         let compositor = Compositor::<Rgb8, 2>::new(Rgb8::BLACK);
         let mut frame = LogicalFrame::new(Rgb8::BLACK);
diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index 3113be918..2c7794944 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -20,7 +20,10 @@ use super::context::{LightingContext, LightingContextProvider};
 use super::effect::{BuiltinEffect, LightingEffect};
 use super::output::BrightnessTransform;
 use super::service::{CommandResult, Invalidation, LightingEngine, RenderInput, RenderOutcome};
-use super::source::{LayerPolicy, LayerScenes, OverlayError, OverlayUpdate, TtlOverlay};
+use super::source::{
+    LayerPolicy, LayerScenes, LightingControls, OutputMode, OverlayError, OverlayUpdate, SceneCell, SparseScene,
+    TtlOverlay,
+};
 use super::topology::LedSlot;
 use crate::RawMutex;
 
@@ -572,6 +575,9 @@ pub struct StandardMutableState {
 pub struct StandardState {
     pub revision: u32,
     pub output_enabled: bool,
+    pub output_mode: OutputMode,
+    pub powered: bool,
+    pub wake_active: bool,
     pub output_brightness: u8,
     pub background: BackgroundState,
     pub overlay_len: usize,
@@ -639,6 +645,7 @@ impl StandardReply {
 pub struct StandardReplicaState<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
     pub revision: u32,
     pub mutable: StandardMutableState,
+    pub output_mode: OutputMode,
     pub overlay: OverlayBatch<OVERLAY_CAP>,
     pub scenes: SceneTable<SCENE_CAP>,
     pub context: LightingContext,
@@ -814,7 +821,11 @@ pub struct StandardLightingEngine<
     scene_expired_transaction: Option<u32>,
     scene_committed_transaction: Option<u32>,
     revision: u32,
-    output_enabled: bool,
+    controls: LightingControls,
+    output_mode: OutputMode,
+    powered: bool,
+    wake_active: bool,
+    effective_output_enabled: bool,
     output_brightness: u8,
 }
 
@@ -841,15 +852,49 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             scene_expired_transaction: None,
             scene_committed_transaction: None,
             revision: 0,
-            output_enabled: true,
+            controls: LightingControls::default(),
+            output_mode: OutputMode::AlwaysOn,
+            powered: false,
+            wake_active: false,
+            effective_output_enabled: true,
             output_brightness: u8::MAX,
         }
     }
 
+    /// Install the board's declarative lighting controls before the engine is
+    /// served. The configured initial mode becomes authoritative on boot.
+    pub const fn with_controls(mut self, controls: LightingControls) -> Self {
+        self.output_mode = controls.initial_output_mode;
+        self.effective_output_enabled = matches!(self.output_mode, OutputMode::AlwaysOn);
+        self.controls = controls;
+        self
+    }
+
+    pub const fn output_mode(&self) -> OutputMode {
+        self.output_mode
+    }
+
+    pub const fn powered(&self) -> bool {
+        self.powered
+    }
+
+    pub const fn wake_active(&self) -> bool {
+        self.wake_active
+    }
+
+    const fn effective_output(&self) -> bool {
+        self.wake_active
+            || matches!(self.output_mode, OutputMode::AlwaysOn)
+            || matches!(self.output_mode, OutputMode::PoweredOnly) && self.powered
+    }
+
     pub fn state(&self) -> StandardState {
         StandardState {
             revision: self.revision,
-            output_enabled: self.output_enabled,
+            output_enabled: self.effective_output(),
+            output_mode: self.output_mode,
+            powered: self.powered,
+            wake_active: self.wake_active,
             output_brightness: self.output_brightness,
             background: self.background.state(),
             overlay_len: self.overlay.active_len(),
@@ -898,9 +943,16 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
         const STEP: u8 = 17;
         let background = &mut self.background.state;
         match action {
-            LightAction::BacklightOn => self.output_enabled = true,
-            LightAction::BacklightOff => self.output_enabled = false,
-            LightAction::BacklightToggle => self.output_enabled = !self.output_enabled,
+            LightAction::BacklightOn => self.output_mode = OutputMode::AlwaysOn,
+            LightAction::BacklightOff => self.output_mode = OutputMode::AlwaysOff,
+            LightAction::BacklightToggle => {
+                self.output_mode = if matches!(self.output_mode, OutputMode::AlwaysOff) {
+                    OutputMode::AlwaysOn
+                } else {
+                    OutputMode::AlwaysOff
+                }
+            }
+            LightAction::OutputModeCycle => self.output_mode = self.output_mode.next(),
             LightAction::BacklightDown => self.output_brightness = self.output_brightness.saturating_sub(STEP),
             LightAction::BacklightUp => self.output_brightness = self.output_brightness.saturating_add(STEP),
             LightAction::BacklightStep => self.output_brightness = self.output_brightness.wrapping_add(STEP),
@@ -950,14 +1002,18 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
     }
 
     fn set_mutable_state(&mut self, state: StandardMutableState) {
-        self.output_enabled = state.output_enabled;
+        self.output_mode = if state.output_enabled {
+            OutputMode::AlwaysOn
+        } else {
+            OutputMode::AlwaysOff
+        };
         self.output_brightness = state.output_brightness;
         self.background.set_state(state.background);
     }
 
     fn mutable_state(&self) -> StandardMutableState {
         StandardMutableState {
-            output_enabled: self.output_enabled,
+            output_enabled: self.effective_output(),
             output_brightness: self.output_brightness,
             background: self.background.state(),
         }
@@ -988,6 +1044,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
         Ok(StandardReplicaState {
             revision: self.revision,
             mutable: self.mutable_state(),
+            output_mode: self.output_mode,
             overlay,
             scenes: self.scenes,
             context: *context.lighting_context(),
@@ -1020,6 +1077,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
         self.overlay
             .replace(replica.sample_time_ms, &updates[..replica.overlay.as_slice().len()])?;
         self.set_mutable_state(replica.mutable);
+        self.output_mode = replica.output_mode;
         self.scenes = replica.scenes;
         self.revision = replica.revision;
         self.animation_clock.anchor(local_now_ms, replica.sample_time_ms);
@@ -1311,7 +1369,11 @@ where
 
         let (mut invalidation, advances_revision) = match command {
             StandardCommand::SetOutputEnabled(enabled) => {
-                self.output_enabled = enabled;
+                self.output_mode = if enabled {
+                    OutputMode::AlwaysOn
+                } else {
+                    OutputMode::AlwaysOff
+                };
                 (Invalidation::Render, true)
             }
             StandardCommand::SetOutputBrightness(level) => {
@@ -1503,10 +1565,32 @@ where
         let effect_now_ms = self.animation_clock.sample_time(input.now_ms);
         let overlay_len = self.overlay.active_len();
         self.overlay.prune_expired(effect_now_ms);
-        let state_changed = self.overlay.active_len() != overlay_len;
+        let mut state_changed = self.overlay.active_len() != overlay_len;
         if state_changed {
             self.advance_revision();
         }
+        let context = input.snapshot.lighting_context();
+        let powered = context.powered;
+        let wake_active = self
+            .controls
+            .wake_layer
+            .is_some_and(|layer| context.layers.is_active(layer));
+        let effective_output_enabled = wake_active
+            || matches!(self.output_mode, OutputMode::AlwaysOn)
+            || matches!(self.output_mode, OutputMode::PoweredOnly) && powered;
+        if self.powered != powered
+            || self.wake_active != wake_active
+            || self.effective_output_enabled != effective_output_enabled
+        {
+            self.powered = powered;
+            self.wake_active = wake_active;
+            self.effective_output_enabled = effective_output_enabled;
+            state_changed = true;
+        }
+        let indicator_cell = self.controls.output_mode_indicator.map(|indicator| SceneCell {
+            slot: indicator.slot,
+            effect: indicator.effect(self.output_mode),
+        });
         let Self {
             compositor,
             background,
@@ -1516,7 +1600,11 @@ where
             overlay,
             status,
             animation_clock: _,
-            output_enabled,
+            controls: _,
+            output_mode: _,
+            powered: _,
+            wake_active: _,
+            effective_output_enabled,
             output_brightness,
             scene_replace: _,
             scene_next_transaction: _,
@@ -1532,7 +1620,17 @@ where
         transaction.apply(priority::LAYER, scenes)?;
         transaction.apply(priority::HOST_OVERLAY, overlay)?;
         transaction.apply(priority::STATUS, status)?;
-        let mut transform = BrightnessTransform::new(if *output_enabled { *output_brightness } else { 0 });
+        if wake_active && let Some(indicator_cell) = indicator_cell.as_ref() {
+            let mut indicator = SparseScene {
+                cells: core::slice::from_ref(indicator_cell),
+            };
+            transaction.apply(priority::STATUS, &mut indicator)?;
+        }
+        let mut transform = BrightnessTransform::new(if *effective_output_enabled {
+            *output_brightness
+        } else {
+            0
+        });
         let result = transaction.finish_with(&mut transform);
         let next_wake_in_ms = result.next_wake_ms.map(|deadline| {
             let delay = deadline.saturating_sub(effect_now_ms).clamp(1, u32::MAX as u64);
@@ -1612,6 +1710,7 @@ mod tests {
         LightingContext {
             layers: LayerState::new(layer, 0, 1 | (1 << layer)),
             indicators: Default::default(),
+            powered: false,
         }
     }
 
@@ -1725,6 +1824,7 @@ mod tests {
                 output_brightness: 42,
                 background: BackgroundState::default(),
             },
+            output_mode: OutputMode::AlwaysOn,
             overlay: OverlayBatch::new(),
             scenes: SceneTable::new(),
             context: context(0),
@@ -1736,6 +1836,85 @@ mod tests {
         assert_eq!(slot.take(), Err(ReplicaSlotError::Empty));
     }
 
+    #[test]
+    fn output_mode_cycles_and_wake_layer_temporarily_overrides_policy() {
+        let mut engine = engine().with_controls(LightingControls {
+            output_toggle_user_action: None,
+            output_mode_cycle_user_action: Some(13),
+            wake_layer: Some(2),
+            initial_output_mode: OutputMode::PoweredOnly,
+            output_mode_indicator: Some(super::super::source::OutputModeIndicator {
+                slot: LedSlot(1),
+                always_on: BuiltinEffect::Solid { color: GREEN },
+                always_off: BuiltinEffect::Solid { color: RED },
+                powered_only: BuiltinEffect::Solid {
+                    color: Rgb8::new(0, 0, 200),
+                },
+            }),
+        });
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        let battery_context = context(0);
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 0,
+                    snapshot: &battery_context,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(frame.as_slice(), &[Rgb8::BLACK, Rgb8::BLACK]);
+        assert!(!engine.state().output_enabled);
+
+        let mut powered_context = battery_context;
+        powered_context.powered = true;
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 1,
+                    snapshot: &powered_context,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert!(engine.state().output_enabled);
+
+        engine
+            .on_input(StandardInput(LightAction::OutputModeCycle), &powered_context)
+            .unwrap();
+        assert_eq!(engine.output_mode(), OutputMode::AlwaysOn);
+        engine
+            .on_input(StandardInput(LightAction::OutputModeCycle), &powered_context)
+            .unwrap();
+        assert_eq!(engine.output_mode(), OutputMode::AlwaysOff);
+
+        let magic_context = context(2);
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 2,
+                    snapshot: &magic_context,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert!(engine.state().wake_active);
+        assert!(engine.state().output_enabled);
+        assert_eq!(frame.as_slice()[1], RED);
+
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 3,
+                    snapshot: &battery_context,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(frame.as_slice(), &[Rgb8::BLACK, Rgb8::BLACK]);
+        assert_eq!(engine.output_mode(), OutputMode::AlwaysOff);
+    }
+
     #[test]
     fn background_patch_preserves_unmentioned_fields() {
         let mut engine = engine();
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index 5a0561e8d..ecd0bb5ed 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -35,7 +35,7 @@ use rynk::rmk_types::protocol::rynk::{
     LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingSceneCellRequest,
     UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus, LightingCompiledScenesPage,
     LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy, SplitCentralLatencyState,
-    LightingConditionalSceneStatus, LightingConditionalScenesPage,
+    LightingConditionalSceneStatus, LightingConditionalScenesPage, LightingOutputModeState,
 };
 use rynk::{Client, Driver, LayoutInfo, RynkDevice, RynkHostError, TopicEvent};
 use wasm_bindgen::prelude::*;
@@ -177,6 +177,7 @@ endpoints! {
     // lighting
     get_lighting_capabilities() -> LightingCapabilities,
     get_lighting_state() -> LightingState,
+    get_lighting_output_mode() -> LightingOutputModeState,
     set_lighting_state(request: SetLightingStateRequest) -> LightingState,
     get_lighting_keys(request: LightingPageRequest) -> LightingKeysPage,
     get_lighting_physical_keys(request: LightingPageRequest) -> LightingPhysicalKeysPage,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 116415f71..5b25501f3 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -36,7 +36,7 @@ use rmk_types::protocol::rynk::{
     LightingSceneTransaction, LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest,
     SetLightingSceneCellRequest, UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus,
     LightingCompiledScenesPage, LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy,
-    SplitCentralLatencyState, LightingConditionalSceneStatus, LightingConditionalScenesPage,
+    SplitCentralLatencyState, LightingConditionalSceneStatus, LightingConditionalScenesPage, LightingOutputModeState,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -423,6 +423,12 @@ impl Client {
         Self::flatten_lighting(self.request::<command::GetLightingState>(&()).await?)
     }
 
+    /// Read the configured three-state lighting output policy and its live inputs.
+    pub async fn get_lighting_output_mode(&self) -> Result<LightingOutputModeState, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingOutputMode)?;
+        Self::flatten_lighting(self.request::<command::GetLightingOutputMode>(&()).await?)
+    }
+
     /// Atomically replace standard mutable state when the revision still matches.
     pub async fn set_lighting_state(&self, request: SetLightingStateRequest) -> Result<LightingState, RynkHostError> {
         self.require_lighting(Cmd::SetLightingState)?;

From 31b00088b60dd38c6e87ddcd696c6f730c792870 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 15:44:32 -0700
Subject: [PATCH 25/78] feat(lighting): support local powered-only scope

---
 rmk-config/src/lib.rs                          | 10 ++++++++++
 rmk-config/src/resolved/lighting.rs            | 18 +++++++++++++++++-
 rmk-macro/src/codegen/lighting.rs              |  9 ++++++++-
 .../src/protocol/rynk/payload/lighting.rs      |  9 +++++++++
 .../rynk/snapshots/lighting_wire_frames.snap   |  2 +-
 rmk-types/src/protocol/rynk/tests.rs           |  1 +
 rmk/src/host/rynk/handlers/lighting.rs         |  1 +
 rmk/src/host/rynk/lighting.rs                  |  7 +++++++
 rmk/src/lighting/mod.rs                        |  3 ++-
 rmk/src/lighting/source.rs                     | 11 +++++++++++
 rmk/src/lighting/standard.rs                   |  1 +
 11 files changed, 68 insertions(+), 4 deletions(-)

diff --git a/rmk-config/src/lib.rs b/rmk-config/src/lib.rs
index b35d187b2..827afb4cc 100644
--- a/rmk-config/src/lib.rs
+++ b/rmk-config/src/lib.rs
@@ -580,9 +580,19 @@ pub(crate) struct LightingControlsTomlConfig {
     pub wake_layer: Option<u8>,
     #[serde(default)]
     pub initial_output_mode: LightingOutputModeToml,
+    #[serde(default)]
+    pub powered_only_scope: LightingPoweredOnlyScopeToml,
     pub output_mode_indicator: Option<LightingOutputModeIndicatorTomlConfig>,
 }
 
+#[derive(Clone, Copy, Debug, Default, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum LightingPoweredOnlyScopeToml {
+    #[default]
+    Authority,
+    Local,
+}
+
 #[derive(Clone, Copy, Debug, Default, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub(crate) enum LightingOutputModeToml {
diff --git a/rmk-config/src/resolved/lighting.rs b/rmk-config/src/resolved/lighting.rs
index 0da898cec..e42f06853 100644
--- a/rmk-config/src/resolved/lighting.rs
+++ b/rmk-config/src/resolved/lighting.rs
@@ -4,7 +4,7 @@ use super::Keymap;
 use super::layout::{FixedPoint3, Layout};
 use crate::{
     LightingBackgroundModeToml, LightingChargeConditionToml, LightingEffectTomlConfig, LightingOutputModeToml,
-    LightingTargetTomlConfig,
+    LightingPoweredOnlyScopeToml, LightingTargetTomlConfig,
 };
 
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -117,6 +117,13 @@ pub enum LightingOutputMode {
     PoweredOnly,
 }
 
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub enum LightingPoweredOnlyScope {
+    #[default]
+    Authority,
+    Local,
+}
+
 impl Default for LightingOutputMode {
     fn default() -> Self {
         Self::AlwaysOn
@@ -137,6 +144,7 @@ pub struct LightingControls {
     pub output_mode_cycle_user_action: Option<u8>,
     pub wake_layer: Option<u8>,
     pub initial_output_mode: LightingOutputMode,
+    pub powered_only_scope: LightingPoweredOnlyScope,
     pub output_mode_indicator: Option<LightingOutputModeIndicator>,
 }
 
@@ -296,6 +304,10 @@ impl crate::KeyboardTomlConfig {
                         LightingOutputModeToml::AlwaysOff => LightingOutputMode::AlwaysOff,
                         LightingOutputModeToml::PoweredOnly => LightingOutputMode::PoweredOnly,
                     },
+                    powered_only_scope: match controls.powered_only_scope {
+                        LightingPoweredOnlyScopeToml::Authority => LightingPoweredOnlyScope::Authority,
+                        LightingPoweredOnlyScopeToml::Local => LightingPoweredOnlyScope::Local,
+                    },
                     output_mode_indicator: controls
                         .output_mode_indicator
                         .as_ref()
@@ -703,6 +715,8 @@ fn resolve_effect(config: &LightingEffectTomlConfig) -> Result<LightingEffect, S
 
 #[cfg(test)]
 mod tests {
+    use super::{LightingOutputMode, LightingPoweredOnlyScope};
+
     fn parse(config: &str) -> crate::KeyboardTomlConfig {
         toml::from_str(config).unwrap()
     }
@@ -849,6 +863,7 @@ output_toggle_user_action = 13
 output_mode_cycle_user_action = 14
 wake_layer = 1
 initial_output_mode = "powered_only"
+powered_only_scope = "local"
 
 [lighting.controls.output_mode_indicator]
 target = {{ led = 10 }}
@@ -865,6 +880,7 @@ powered_only = {{ kind = "solid", color = [0, 0, 9] }}
         assert_eq!(lighting.controls.output_mode_cycle_user_action, Some(14));
         assert_eq!(lighting.controls.wake_layer, Some(1));
         assert_eq!(lighting.controls.initial_output_mode, LightingOutputMode::PoweredOnly);
+        assert_eq!(lighting.controls.powered_only_scope, LightingPoweredOnlyScope::Local);
         assert_eq!(lighting.controls.output_mode_indicator.unwrap().slot, 0);
 
         let invalid = parse(&source.replace("wake_layer = 1", "wake_layer = 2"));
diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
index 7b8a0ce3f..e0ee4b53b 100644
--- a/rmk-macro/src/codegen/lighting.rs
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -4,7 +4,7 @@ use proc_macro2::TokenStream as TokenStream2;
 use quote::quote;
 use rmk_config::resolved::lighting::{
     Lighting, LightingBackgroundMode, LightingChargeCondition, LightingConditionalSceneCell,
-    LightingEffect, LightingOutputMode, LightingSceneCell,
+    LightingEffect, LightingOutputMode, LightingPoweredOnlyScope, LightingSceneCell,
 };
 use rmk_config::resolved::{FixedPoint3, PhysicalLayout};
 
@@ -212,6 +212,12 @@ pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> To
         LightingOutputMode::AlwaysOff => quote! { ::rmk::lighting::OutputMode::AlwaysOff },
         LightingOutputMode::PoweredOnly => quote! { ::rmk::lighting::OutputMode::PoweredOnly },
     };
+    let powered_only_scope = match lighting.controls.powered_only_scope {
+        LightingPoweredOnlyScope::Authority => {
+            quote! { ::rmk::lighting::PoweredOnlyScope::Authority }
+        }
+        LightingPoweredOnlyScope::Local => quote! { ::rmk::lighting::PoweredOnlyScope::Local },
+    };
     let output_mode_indicator = match lighting.controls.output_mode_indicator {
         Some(indicator) => {
             let slot = indicator.slot;
@@ -260,6 +266,7 @@ pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> To
                 output_mode_cycle_user_action: #output_mode_cycle_user_action,
                 wake_layer: #wake_layer,
                 initial_output_mode: #initial_output_mode,
+                powered_only_scope: #powered_only_scope,
                 output_mode_indicator: #output_mode_indicator,
             };
         pub const LIGHTING_BACKGROUND: ::rmk::lighting::BackgroundState =
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 35ce9de3b..95eb64e2f 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -639,6 +639,14 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Power source used by split renderers in `PoweredOnly` mode.
+    pub enum LightingPoweredOnlyScope {
+        Authority,
+        Local,
+    }
+}
+
 wire_type! {
     /// Configured status LED and its mode-specific effects.
     pub struct LightingOutputModeIndicator {
@@ -657,6 +665,7 @@ wire_type! {
         pub powered: bool,
         pub wake_active: bool,
         pub effective_enabled: bool,
+        pub powered_only_scope: LightingPoweredOnlyScope,
         pub cycle_user_action: Option<u8>,
         pub wake_layer: Option<u8>,
         pub indicator: Option<LightingOutputModeIndicator>,
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index 03f1fb48d..6fd02b4ef 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -29,7 +29,7 @@ GetLightingKeys reply                                  11 09 01 07 00 00 00 01 0
 GetLightingKeys request                                11 09 01 02 00 01 00
 GetLightingLeds reply                                  05 09 01 12 00 00 00 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01
 GetLightingLeds request                                05 09 01 02 00 01 00
-GetLightingOutputMode reply                            20 09 01 18 00 00 00 02 01 00 01 01 0d 01 02 01 2a 00 00 09 00 00 09 00 00 00 00 00 09
+GetLightingOutputMode reply                            20 09 01 19 00 00 00 02 01 00 01 01 01 0d 01 02 01 2a 00 00 09 00 00 09 00 00 00 00 00 09
 GetLightingOutputMode request                          20 09 01 00 00
 GetLightingOutputs reply                               08 09 01 0a 00 00 00 01 01 01 01 02 28 14 00
 GetLightingOutputs request                             08 09 01 02 00 01 00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index a9c3752b4..e1ba397ea 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1321,6 +1321,7 @@ fn lighting_wire_frames_locked() {
         powered: true,
         wake_active: false,
         effective_enabled: true,
+        powered_only_scope: LightingPoweredOnlyScope::Local,
         cycle_user_action: Some(13),
         wake_layer: Some(2),
         indicator: Some(LightingOutputModeIndicator {
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index c0bde3979..323361aa9 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -1583,6 +1583,7 @@ mod tests {
                 output_mode_cycle_user_action: Some(14),
                 wake_layer: Some(1),
                 initial_output_mode: OutputMode::PoweredOnly,
+                powered_only_scope: crate::lighting::PoweredOnlyScope::Local,
                 output_mode_indicator: Some(OutputModeIndicator {
                     slot: LedSlot(0),
                     always_on: BuiltinEffect::solid(Rgb8::new(0, 9, 0)),
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index c92434f83..6f980aa1d 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -94,6 +94,7 @@ impl<'a> RynkLightingController<'a> {
                 output_mode_cycle_user_action: None,
                 wake_layer: None,
                 initial_output_mode: crate::lighting::OutputMode::AlwaysOn,
+                powered_only_scope: crate::lighting::PoweredOnlyScope::Authority,
                 output_mode_indicator: None,
             },
             mailbox,
@@ -135,6 +136,12 @@ impl<'a> RynkLightingController<'a> {
             powered: state.powered,
             wake_active: state.wake_active,
             effective_enabled: state.output_enabled,
+            powered_only_scope: match self.controls.powered_only_scope {
+                crate::lighting::PoweredOnlyScope::Authority => {
+                    rmk_types::protocol::rynk::LightingPoweredOnlyScope::Authority
+                }
+                crate::lighting::PoweredOnlyScope::Local => rmk_types::protocol::rynk::LightingPoweredOnlyScope::Local,
+            },
             cycle_user_action: self.controls.output_mode_cycle_user_action,
             wake_layer: self.controls.wake_layer,
             indicator: self.controls.output_mode_indicator.and_then(|indicator| {
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index 8c044c6c2..dac395726 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -39,7 +39,8 @@ pub use service::{
 pub use source::{
     BatteryCondition, BatteryStatusProvider, ChargeCondition, ConditionSet, ConditionalSceneCell, ConditionalScenes,
     DenseSource, Indicator, IndicatorScene, IndicatorScenes, LayerCondition, LayerPolicy, LayerScene, LayerScenes,
-    LightingControls, OutputMode, OutputModeIndicator, OverlayError, OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
+    LightingControls, OutputMode, OutputModeIndicator, OverlayError, OverlayUpdate, PoweredOnlyScope, SceneCell,
+    SparseScene, TtlOverlay,
 };
 pub use standard::{
     BackgroundMode, BackgroundPatch, BackgroundState, CompiledScenePage, EmptySource, OVERLAY_CHUNK_SIZE, OverlayBatch,
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index 26fecf58a..fe302318e 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -191,6 +191,16 @@ pub enum OutputMode {
     PoweredOnly,
 }
 
+/// Which power source a split renderer uses for `PoweredOnly`.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub enum PoweredOnlyScope {
+    /// Follow the authoritative renderer's power state on every node.
+    #[default]
+    Authority,
+    /// Let each renderer use its own node's local VBUS state.
+    Local,
+}
+
 impl OutputMode {
     pub const fn next(self) -> Self {
         match self {
@@ -227,6 +237,7 @@ pub struct LightingControls {
     pub output_mode_cycle_user_action: Option<u8>,
     pub wake_layer: Option<u8>,
     pub initial_output_mode: OutputMode,
+    pub powered_only_scope: PoweredOnlyScope,
     pub output_mode_indicator: Option<OutputModeIndicator>,
 }
 
diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index 2c7794944..0c1e9b1bb 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -1843,6 +1843,7 @@ mod tests {
             output_mode_cycle_user_action: Some(13),
             wake_layer: Some(2),
             initial_output_mode: OutputMode::PoweredOnly,
+            powered_only_scope: super::super::source::PoweredOnlyScope::Local,
             output_mode_indicator: Some(super::super::source::OutputModeIndicator {
                 slot: LedSlot(1),
                 always_on: BuiltinEffect::Solid { color: GREEN },

From 02f0a01e278ce7ba8ec23a7f34bde43a209ed9b4 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 16:04:02 -0700
Subject: [PATCH 26/78] feat(lighting): let extension sources claim light
 actions and add standalone config macro

Boards whose hardware cannot use the generated main (custom matrix
drivers, nonstandard USB bring-up) previously had no way to consume
`[lighting]` from keyboard.toml, and animated extension sources could
not own the RGB mode/value/speed keys: apply_light_action routed every
RGB action to the uniform background.

- LightingSource::handle_light_action (default: decline) lets the
  standard engine offer each LightAction to its extension source before
  the built-in background handling.
- rmk_lighting_config! emits the same flash-resident physical-layout
  and lighting statics as #[rmk_keyboard], resolved standalone so no
  [matrix]/[split] section is required; [keymap].layers alone provides
  the layer count for scene validation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk-config/src/resolved/layout.rs   | 22 +++++++++++
 rmk-config/src/resolved/lighting.rs | 22 +++++++++++
 rmk-macro/src/codegen/lighting.rs   | 21 ++++++++++
 rmk-macro/src/lib.rs                | 12 ++++++
 rmk/src/lighting/compositor.rs      | 12 ++++++
 rmk/src/lighting/standard.rs        | 60 ++++++++++++++++++++++++++++-
 6 files changed, 148 insertions(+), 1 deletion(-)

diff --git a/rmk-config/src/resolved/layout.rs b/rmk-config/src/resolved/layout.rs
index 0f860cfd4..150cda842 100644
--- a/rmk-config/src/resolved/layout.rs
+++ b/rmk-config/src/resolved/layout.rs
@@ -58,4 +58,26 @@ impl crate::KeyboardTomlConfig {
             physical,
         })
     }
+
+    /// Resolve the `[layout]` section without consulting the board config.
+    ///
+    /// Firmware that wires its scan hardware by hand has no `[matrix]` or
+    /// `[split]` section, so encoder counts cannot be validated against the
+    /// layout map; everything else resolves as in [`Self::layout`].
+    pub fn layout_standalone(&self) -> Result<Layout, String> {
+        let (blob, keys, physical, rows, cols) = match &self.layout {
+            Some(l) => {
+                let resolved = crate::layout::build_resolved_layout(l, None)?;
+                (resolved.blob, resolved.keys, resolved.physical, l.rows, l.cols)
+            }
+            None => (Vec::new(), Vec::new(), PhysicalLayout::default(), 0, 0),
+        };
+        Ok(Layout {
+            blob,
+            rows,
+            cols,
+            keys,
+            physical,
+        })
+    }
 }
diff --git a/rmk-config/src/resolved/lighting.rs b/rmk-config/src/resolved/lighting.rs
index e42f06853..ed8adb571 100644
--- a/rmk-config/src/resolved/lighting.rs
+++ b/rmk-config/src/resolved/lighting.rs
@@ -197,6 +197,28 @@ pub struct Lighting {
 }
 
 impl crate::KeyboardTomlConfig {
+    /// Resolve `[lighting]` without a resolved board keymap, for firmware
+    /// that defines its keymap in Rust instead of `[[keymap.layer]]`.
+    ///
+    /// The layer count for scene validation comes from `[keymap].layers`,
+    /// falling back to the number of `[[keymap.layer]]` blocks.
+    pub fn lighting_standalone(&self, layout: &Layout) -> Result<Option<Lighting>, String> {
+        let layers = match &self.keymap {
+            Some(k) => k.layers.unwrap_or(k.layer.len() as u8),
+            None => 0,
+        };
+        let keymap = Keymap {
+            rows: layout.rows,
+            cols: layout.cols,
+            layers,
+            keymap: Vec::new(),
+            encoder_map: Vec::new(),
+            key_info: Vec::new(),
+            num_encoder: 0,
+        };
+        self.lighting(layout, &keymap)
+    }
+
     pub fn lighting(&self, layout: &Layout, keymap: &Keymap) -> Result<Option<Lighting>, String> {
         let Some(config) = &self.lighting else {
             return Ok(None);
diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
index e0ee4b53b..e8c2e0632 100644
--- a/rmk-macro/src/codegen/lighting.rs
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -8,6 +8,27 @@ use rmk_config::resolved::lighting::{
 };
 use rmk_config::resolved::{FixedPoint3, PhysicalLayout};
 
+/// Statics for a hand-written main: resolve `[layout]` and `[lighting]`
+/// directly from `KEYBOARD_TOML_PATH` without the full `#[rmk_keyboard]`
+/// pipeline (which would require a `[matrix]` or `[split]` section).
+pub(crate) fn expand_standalone_lighting_config() -> TokenStream2 {
+    let config = crate::codegen::keyboard_config::read_keyboard_toml_config();
+    let layout = config
+        .layout_standalone()
+        .expect("failed to resolve layout config");
+    let lighting = config
+        .lighting_standalone(&layout)
+        .expect("failed to resolve lighting config");
+    let physical_layout = expand_physical_layout(&layout.physical);
+    let topology = expand_lighting_topology(lighting.as_ref());
+    let blob_lit = proc_macro2::Literal::byte_string(&layout.blob);
+    quote! {
+        #physical_layout
+        #topology
+        pub static LAYOUT_BLOB: &[u8] = #blob_lit;
+    }
+}
+
 pub(crate) fn expand_physical_layout(layout: &PhysicalLayout) -> TokenStream2 {
     let keys = layout.keys.iter().map(|key| {
         let [row, col] = key.matrix;
diff --git a/rmk-macro/src/lib.rs b/rmk-macro/src/lib.rs
index 84819c10a..9408dace3 100644
--- a/rmk-macro/src/lib.rs
+++ b/rmk-macro/src/lib.rs
@@ -62,6 +62,18 @@ pub fn rmk_peripheral(attr: TokenStream, item: TokenStream) -> TokenStream {
     parse_split_peripheral_mod(peripheral_id, attr, item_mod).into()
 }
 
+/// Emit the flash-resident physical layout and `[lighting]` statics from
+/// `KEYBOARD_TOML_PATH` for firmware with a hand-written main function.
+///
+/// `#[rmk_keyboard]` emits the same statics as part of full main generation;
+/// boards whose hardware does not fit the generated main (custom matrix
+/// drivers, nonstandard USB bring-up) invoke this at module scope instead and
+/// wire the lighting engine themselves.
+#[proc_macro]
+pub fn rmk_lighting_config(_item: TokenStream) -> TokenStream {
+    codegen::lighting::expand_standalone_lighting_config().into()
+}
+
 /// Marker attribute for coordinating Runnable generation between macros.
 /// Do not use directly.
 #[doc(hidden)]
diff --git a/rmk/src/lighting/compositor.rs b/rmk/src/lighting/compositor.rs
index 6ee8fa2b7..55cb78048 100644
--- a/rmk/src/lighting/compositor.rs
+++ b/rmk/src/lighting/compositor.rs
@@ -1,3 +1,5 @@
+use rmk_types::action::LightAction;
+
 use super::effect::EffectSample;
 use super::topology::LedSlot;
 
@@ -33,6 +35,16 @@ pub trait LightingSource<C, Context> {
     fn is_empty(&self, input: &RenderInput<'_, Context>) -> bool {
         self.len(input) == 0
     }
+
+    /// Claim a `LightAction` ahead of the engine's built-in handling.
+    ///
+    /// The standard engine offers each incoming action to its extension
+    /// source first, so animated sources can own the RGB mode/value/speed
+    /// keys instead of the uniform background. Return `true` to consume the
+    /// action; the engine then re-renders. The default declines everything.
+    fn handle_light_action(&mut self, _action: LightAction) -> bool {
+        false
+    }
 }
 
 /// User-level transform applied after composition but before changed
diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index 0c1e9b1bb..fbd924c32 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -1249,7 +1249,7 @@ where
     type Error = StandardError;
 
     fn on_input(&mut self, input: Self::Input, _snapshot: &Context) -> Result<Invalidation, Self::Error> {
-        if self.apply_light_action(input.0) {
+        if self.extension.handle_light_action(input.0) || self.apply_light_action(input.0) {
             self.advance_revision();
             Ok(Invalidation::Render)
         } else {
@@ -2705,4 +2705,62 @@ mod tests {
             Err(StandardError::InvalidSceneTransaction)
         );
     }
+
+    #[test]
+    fn extension_source_claims_light_actions_before_background() {
+        #[derive(Default)]
+        struct ClaimingSource;
+
+        impl<C, Context> LightingSource<C, Context> for ClaimingSource {
+            fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
+                0
+            }
+
+            fn slot(&self, _: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
+                unreachable!("ClaimingSource has no targets")
+            }
+
+            fn contribution(&mut self, _: usize, _: &SourceRenderInput<'_, Context>) -> Contribution<C> {
+                unreachable!("ClaimingSource has no samples")
+            }
+
+            fn handle_light_action(&mut self, action: LightAction) -> bool {
+                matches!(action, LightAction::RgbHui)
+            }
+        }
+
+        let mut engine: StandardLightingEngine<'static, ClaimingSource, EmptySource, 2, 2> =
+            StandardLightingEngine::new(
+                BackgroundState {
+                    value: 10,
+                    ..BackgroundState::default()
+                },
+                LayerScenes {
+                    scenes: &LAYERS,
+                    policy: LayerPolicy::ActiveStack,
+                },
+                ClaimingSource,
+                EmptySource,
+            );
+        let snapshot = context(0);
+        let hue_before = engine.state().background.hue;
+
+        assert_eq!(
+            engine.on_input(StandardInput(LightAction::RgbHui), &snapshot),
+            Ok(Invalidation::Render)
+        );
+        assert_eq!(engine.state().revision, 1);
+        assert_eq!(
+            engine.state().background.hue,
+            hue_before,
+            "a claimed action must bypass the built-in background handling"
+        );
+
+        engine.on_input(StandardInput(LightAction::RgbHud), &snapshot).unwrap();
+        assert_ne!(
+            engine.state().background.hue,
+            hue_before,
+            "unclaimed actions still fall through to the background"
+        );
+    }
 }

From 861b33601a7151fc36503afd599ba8dcadc7de1e Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 16:16:44 -0700
Subject: [PATCH 27/78] Validate standalone lighting expansion against the
 Voyager config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Exercise layout_standalone/lighting_standalone plus the geometry and
topology expansion on an exact copy of the rmk-zsa-voyager keyboard.toml:
52 emitters over two outputs, with { all = true } layer scenes expanding
to every slot.

The test caught that expand_standalone_lighting_config loaded the toml
through new_from_toml_path, which panics without [keyboard].chip — a
section hand-written-main firmware intentionally omits. Load with event
defaults only instead, as rmk-types' build.rs already does; the skipped
chip-default layer never touches [layout], [lighting], or [keymap].

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk-macro/src/codegen/lighting.rs | 565 +++++++++++++++++++++++++++++-
 1 file changed, 564 insertions(+), 1 deletion(-)

diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
index e8c2e0632..6c1245f41 100644
--- a/rmk-macro/src/codegen/lighting.rs
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -12,7 +12,13 @@ use rmk_config::resolved::{FixedPoint3, PhysicalLayout};
 /// directly from `KEYBOARD_TOML_PATH` without the full `#[rmk_keyboard]`
 /// pipeline (which would require a `[matrix]` or `[split]` section).
 pub(crate) fn expand_standalone_lighting_config() -> TokenStream2 {
-    let config = crate::codegen::keyboard_config::read_keyboard_toml_config();
+    // Load without the chip-default layer: it requires `[keyboard].chip` and
+    // only fills in sections ([storage], [ble], ...) that a hand-written main
+    // configures in Rust. rmk-types' build.rs treats such tomls the same way.
+    let config_toml_path = std::env::var("KEYBOARD_TOML_PATH")
+        .expect("[ERROR]: KEYBOARD_TOML_PATH should be set in `.cargo/config.toml`");
+    let config =
+        rmk_config::KeyboardTomlConfig::new_from_toml_path_with_event_defaults(&config_toml_path);
     let layout = config
         .layout_standalone()
         .expect("failed to resolve layout config");
@@ -525,6 +531,8 @@ mod tests {
                     ],
                 },
             ],
+            conditional_scene_cells: Vec::new(),
+            controls: Default::default(),
             background: LightingBackground {
                 enabled: false,
                 hue: 11,
@@ -565,4 +573,559 @@ mod tests {
         assert!(expand_lighting_topology(None).is_empty());
         assert!(expand_lighting_renderer_config(None).is_empty());
     }
+
+    // Exact copy of rmk-zsa-voyager/keyboard.toml: a board-wide 12x7 layout
+    // with 52 emitters split across two IS31FL3731 outputs on a single node.
+    const VOYAGER_TOML: &str = r#"# Consumed at build time by rmk-types (event channel sizing) and by the
+# `rmk_lighting_config!` macro in main.rs (physical layout + `[lighting]`
+# statics). The scan hardware and keymap stay in Rust: the left half is a
+# direct-GPIO matrix and the right half arrives over an MCP23018, which the
+# `#[rmk_keyboard]` generated main cannot express.
+
+# The logical 12x7 matrix. Rows 0-5 are the left half, rows 6-11 the right
+# half; see src/keymap.rs for the physical wiring behind this arrangement.
+[layout]
+rows = 12
+cols = 7
+map = """
+(0,1) (0,2) (0,3) (0,4) (0,5) (0,6)
+(1,1) (1,2) (1,3) (1,4) (1,5) (1,6)
+(2,1) (2,2) (2,3) (2,4) (2,5) (2,6)
+(3,1) (3,2) (3,3) (3,4) (3,5)
+(4,4)
+(5,0) (5,1)
+(6,0) (6,1) (6,2) (6,3) (6,4) (6,5)
+(7,0) (7,1) (7,2) (7,3) (7,4) (7,5)
+(8,0) (8,1) (8,2) (8,3) (8,4) (8,5)
+(9,1) (9,2) (9,3) (9,4) (9,5)
+(10,2)
+(11,5) (11,6)
+"""
+
+# Layer count only; the default keymap itself lives in src/keymap.rs.
+[keymap]
+layers = 3
+
+# Board-wide lighting topology: one node (the Voyager is not an RMK split),
+# two IS31FL3731 chips as separate outputs. Emitter ids 0-25 are the left
+# chip and 26-51 the right chip, in `LED_TABLE` order (src/is31fl3731.rs);
+# `physical_index` is the chip-relative index into that table.
+[lighting]
+topology_revision = 1
+
+[[lighting.zone]]
+id = 1
+name = "per-key"
+
+[[lighting.output]]
+node = 0
+id = 0
+pixel_count = 26
+capabilities = ["rgb", "addressable"]
+
+[[lighting.output]]
+node = 0
+id = 1
+pixel_count = 26
+capabilities = ["rgb", "addressable"]
+
+# The animated base-layer background comes from the rmk-palettefx extension
+# source, not the uniform background.
+[lighting.background]
+enabled = false
+hue = 0
+saturation = 0
+value = 0
+speed = 128
+mode = "solid"
+
+[lighting.controls]
+initial_output_mode = "always_on"
+
+# Non-base layers replace the animation with a solid wash, exactly covering
+# every emitter so the extension band sleeps while a layer is held.
+[[lighting.layer_scene]]
+layer = 1
+
+[[lighting.layer_scene.cell]]
+target = { all = true }
+effect = { kind = "solid", color = [0, 16, 64] } # symbols/F-keys: cool blue
+
+[[lighting.layer_scene]]
+layer = 2
+
+[[lighting.layer_scene.cell]]
+target = { all = true }
+effect = { kind = "solid", color = [48, 0, 48] } # media/nav: magenta
+
+# Left chip (0x74), LED_TABLE entries 0-25.
+[[lighting.emitter]]
+id = 0
+key = [0, 1]
+zones = [1]
+node = 0
+output = 0
+physical_index = 0
+
+[[lighting.emitter]]
+id = 1
+key = [0, 2]
+zones = [1]
+node = 0
+output = 0
+physical_index = 1
+
+[[lighting.emitter]]
+id = 2
+key = [0, 3]
+zones = [1]
+node = 0
+output = 0
+physical_index = 2
+
+[[lighting.emitter]]
+id = 3
+key = [0, 4]
+zones = [1]
+node = 0
+output = 0
+physical_index = 3
+
+[[lighting.emitter]]
+id = 4
+key = [0, 5]
+zones = [1]
+node = 0
+output = 0
+physical_index = 4
+
+[[lighting.emitter]]
+id = 5
+key = [0, 6]
+zones = [1]
+node = 0
+output = 0
+physical_index = 5
+
+[[lighting.emitter]]
+id = 6
+key = [1, 1]
+zones = [1]
+node = 0
+output = 0
+physical_index = 6
+
+[[lighting.emitter]]
+id = 7
+key = [1, 2]
+zones = [1]
+node = 0
+output = 0
+physical_index = 7
+
+[[lighting.emitter]]
+id = 8
+key = [1, 3]
+zones = [1]
+node = 0
+output = 0
+physical_index = 8
+
+[[lighting.emitter]]
+id = 9
+key = [1, 4]
+zones = [1]
+node = 0
+output = 0
+physical_index = 9
+
+[[lighting.emitter]]
+id = 10
+key = [1, 5]
+zones = [1]
+node = 0
+output = 0
+physical_index = 10
+
+[[lighting.emitter]]
+id = 11
+key = [1, 6]
+zones = [1]
+node = 0
+output = 0
+physical_index = 11
+
+[[lighting.emitter]]
+id = 12
+key = [2, 1]
+zones = [1]
+node = 0
+output = 0
+physical_index = 12
+
+[[lighting.emitter]]
+id = 13
+key = [2, 2]
+zones = [1]
+node = 0
+output = 0
+physical_index = 13
+
+[[lighting.emitter]]
+id = 14
+key = [2, 3]
+zones = [1]
+node = 0
+output = 0
+physical_index = 14
+
+[[lighting.emitter]]
+id = 15
+key = [2, 4]
+zones = [1]
+node = 0
+output = 0
+physical_index = 15
+
+[[lighting.emitter]]
+id = 16
+key = [2, 5]
+zones = [1]
+node = 0
+output = 0
+physical_index = 16
+
+[[lighting.emitter]]
+id = 17
+key = [2, 6]
+zones = [1]
+node = 0
+output = 0
+physical_index = 17
+
+[[lighting.emitter]]
+id = 18
+key = [3, 1]
+zones = [1]
+node = 0
+output = 0
+physical_index = 18
+
+[[lighting.emitter]]
+id = 19
+key = [3, 2]
+zones = [1]
+node = 0
+output = 0
+physical_index = 19
+
+[[lighting.emitter]]
+id = 20
+key = [3, 3]
+zones = [1]
+node = 0
+output = 0
+physical_index = 20
+
+[[lighting.emitter]]
+id = 21
+key = [3, 4]
+zones = [1]
+node = 0
+output = 0
+physical_index = 21
+
+[[lighting.emitter]]
+id = 22
+key = [3, 5]
+zones = [1]
+node = 0
+output = 0
+physical_index = 22
+
+[[lighting.emitter]]
+id = 23
+key = [4, 4]
+zones = [1]
+node = 0
+output = 0
+physical_index = 23
+
+[[lighting.emitter]]
+id = 24
+key = [5, 0]
+zones = [1]
+node = 0
+output = 0
+physical_index = 24
+
+[[lighting.emitter]]
+id = 25
+key = [5, 1]
+zones = [1]
+node = 0
+output = 0
+physical_index = 25
+
+# Right chip (0x77), LED_TABLE entries 26-51.
+[[lighting.emitter]]
+id = 26
+key = [6, 0]
+zones = [1]
+node = 0
+output = 1
+physical_index = 0
+
+[[lighting.emitter]]
+id = 27
+key = [6, 1]
+zones = [1]
+node = 0
+output = 1
+physical_index = 1
+
+[[lighting.emitter]]
+id = 28
+key = [6, 2]
+zones = [1]
+node = 0
+output = 1
+physical_index = 2
+
+[[lighting.emitter]]
+id = 29
+key = [6, 3]
+zones = [1]
+node = 0
+output = 1
+physical_index = 3
+
+[[lighting.emitter]]
+id = 30
+key = [6, 4]
+zones = [1]
+node = 0
+output = 1
+physical_index = 4
+
+[[lighting.emitter]]
+id = 31
+key = [6, 5]
+zones = [1]
+node = 0
+output = 1
+physical_index = 5
+
+[[lighting.emitter]]
+id = 32
+key = [7, 0]
+zones = [1]
+node = 0
+output = 1
+physical_index = 6
+
+[[lighting.emitter]]
+id = 33
+key = [7, 1]
+zones = [1]
+node = 0
+output = 1
+physical_index = 7
+
+[[lighting.emitter]]
+id = 34
+key = [7, 2]
+zones = [1]
+node = 0
+output = 1
+physical_index = 8
+
+[[lighting.emitter]]
+id = 35
+key = [7, 3]
+zones = [1]
+node = 0
+output = 1
+physical_index = 9
+
+[[lighting.emitter]]
+id = 36
+key = [7, 4]
+zones = [1]
+node = 0
+output = 1
+physical_index = 10
+
+[[lighting.emitter]]
+id = 37
+key = [7, 5]
+zones = [1]
+node = 0
+output = 1
+physical_index = 11
+
+[[lighting.emitter]]
+id = 38
+key = [8, 0]
+zones = [1]
+node = 0
+output = 1
+physical_index = 12
+
+[[lighting.emitter]]
+id = 39
+key = [8, 1]
+zones = [1]
+node = 0
+output = 1
+physical_index = 13
+
+[[lighting.emitter]]
+id = 40
+key = [8, 2]
+zones = [1]
+node = 0
+output = 1
+physical_index = 14
+
+[[lighting.emitter]]
+id = 41
+key = [8, 3]
+zones = [1]
+node = 0
+output = 1
+physical_index = 15
+
+[[lighting.emitter]]
+id = 42
+key = [8, 4]
+zones = [1]
+node = 0
+output = 1
+physical_index = 16
+
+[[lighting.emitter]]
+id = 43
+key = [8, 5]
+zones = [1]
+node = 0
+output = 1
+physical_index = 17
+
+[[lighting.emitter]]
+id = 44
+key = [10, 2]
+zones = [1]
+node = 0
+output = 1
+physical_index = 18
+
+[[lighting.emitter]]
+id = 45
+key = [9, 1]
+zones = [1]
+node = 0
+output = 1
+physical_index = 19
+
+[[lighting.emitter]]
+id = 46
+key = [9, 2]
+zones = [1]
+node = 0
+output = 1
+physical_index = 20
+
+[[lighting.emitter]]
+id = 47
+key = [9, 3]
+zones = [1]
+node = 0
+output = 1
+physical_index = 21
+
+[[lighting.emitter]]
+id = 48
+key = [9, 4]
+zones = [1]
+node = 0
+output = 1
+physical_index = 22
+
+[[lighting.emitter]]
+id = 49
+key = [9, 5]
+zones = [1]
+node = 0
+output = 1
+physical_index = 23
+
+[[lighting.emitter]]
+id = 50
+key = [11, 5]
+zones = [1]
+node = 0
+output = 1
+physical_index = 24
+
+[[lighting.emitter]]
+id = 51
+key = [11, 6]
+zones = [1]
+node = 0
+output = 1
+physical_index = 25
+
+# Event channel sizing beyond the defaults: the status-LED task and the
+# lighting processor both subscribe to layer changes.
+[event.layer_change]
+subs = 2
+"#;
+
+    #[test]
+    fn resolves_and_expands_the_voyager_keyboard_toml() {
+        let unique = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let path = std::env::temp_dir().join(format!(
+            "rmk-macro-voyager-{}-{unique}.toml",
+            std::process::id()
+        ));
+        std::fs::write(&path, VOYAGER_TOML).unwrap();
+        let config = rmk_config::KeyboardTomlConfig::new_from_toml_path_with_event_defaults(&path);
+        let _ = std::fs::remove_file(&path);
+
+        let layout = config.layout_standalone().unwrap();
+        assert_eq!(layout.keys.len(), 52);
+        let lighting = config.lighting_standalone(&layout).unwrap().unwrap();
+        assert_eq!(lighting.emitters.len(), 52);
+        assert_eq!(lighting.outputs.len(), 2);
+        assert_eq!(lighting.routes.len(), 52);
+        let scenes: Vec<_> = lighting
+            .layer_scenes
+            .iter()
+            .map(|scene| (scene.layer, scene.cells.len()))
+            .collect();
+        assert_eq!(
+            scenes,
+            vec![(1, 52), (2, 52)],
+            "target {{ all = true }} must expand to every emitter slot"
+        );
+
+        let geometry = expand_physical_layout(&layout.physical).to_string();
+        assert!(geometry.contains("PHYSICAL_LAYOUT"));
+
+        let topology = expand_lighting_topology(Some(&lighting)).to_string();
+        assert!(topology.contains("LIGHTING_LED_COUNT : usize = 52usize"));
+        for symbol in [
+            "LIGHTING_TOPOLOGY",
+            "LIGHTING_ROUTING",
+            "LIGHTING_LAYER_SCENES",
+            "LIGHTING_CONTROLS",
+            "LIGHTING_BACKGROUND",
+        ] {
+            assert!(topology.contains(symbol), "missing {symbol}");
+        }
+    }
 }

From 52f9e3c4ce8aa91657fa167e66efa9ed3232433a Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 18:31:20 -0700
Subject: [PATCH 28/78] feat(lighting): expose extension-source introspection
 to the engine

Extension sources gain three defaulted hooks: a descriptor (effect and
palette name lists), current-state readback, and host-driven state
application. The standard engine serves them through ReadExtension /
SetExtensionIfRevision, and replica snapshots carry the selection so
split renderer replicas track the authority's animated band.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/host/rynk/lighting.rs  |  1 +
 rmk/src/lighting/compositor.rs | 39 ++++++++++++++++++++++
 rmk/src/lighting/standard.rs   | 59 ++++++++++++++++++++++++++++++++--
 3 files changed, 96 insertions(+), 3 deletions(-)

diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 6f980aa1d..853c79056 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -1055,6 +1055,7 @@ fn map_standard_error(error: StandardError, capacity: usize) -> LightingError {
         StandardError::SceneTransactionIncomplete { expected, received } => {
             LightingError::TransactionIncomplete { expected, received }
         }
+        StandardError::ExtensionUnsupported => LightingError::Unsupported,
     }
 }
 
diff --git a/rmk/src/lighting/compositor.rs b/rmk/src/lighting/compositor.rs
index 55cb78048..3ff8d228e 100644
--- a/rmk/src/lighting/compositor.rs
+++ b/rmk/src/lighting/compositor.rs
@@ -45,6 +45,45 @@ pub trait LightingSource<C, Context> {
     fn handle_light_action(&mut self, _action: LightAction) -> bool {
         false
     }
+
+    /// Describe this source's selectable content, if any.
+    ///
+    /// An animated extension source (an effect pack) advertises its effect
+    /// and palette names here so hosts can render controls without
+    /// compiled-in assumptions. The default — and sources that are not
+    /// user-selectable — report nothing.
+    fn extension_descriptor(&self) -> Option<ExtensionDescriptor> {
+        None
+    }
+
+    /// Current selection and tuning, indexed against
+    /// [`Self::extension_descriptor`]'s name lists.
+    fn extension_state(&self) -> Option<ExtensionState> {
+        None
+    }
+
+    /// Apply a host-selected state. Return `true` if accepted; the engine
+    /// then re-renders and advances its revision. The default declines.
+    fn apply_extension_state(&mut self, _state: ExtensionState) -> bool {
+        false
+    }
+}
+
+/// Static description of an extension source's selectable content.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionDescriptor {
+    pub effects: &'static [&'static str],
+    pub palettes: &'static [&'static str],
+}
+
+/// Runtime-adjustable state of an extension source. `effect` and `palette`
+/// index into the descriptor's name lists; `value` and `speed` are 0-255.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionState {
+    pub effect: u8,
+    pub palette: u8,
+    pub value: u8,
+    pub speed: u8,
 }
 
 /// User-level transform applied after composition but before changed
diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index fbd924c32..39fd8aa96 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -13,7 +13,7 @@ use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
 use rmk_types::action::LightAction;
 
 use super::Rgb8;
-use super::compositor::{
+use super::compositor::{ExtensionDescriptor, ExtensionState, 
     Compositor, Contribution, LightingSource, LogicalFrame, RenderError, RenderInput as SourceRenderInput,
 };
 use super::context::{LightingContext, LightingContextProvider};
@@ -518,6 +518,12 @@ pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
     /// slot. Intended for a renderer replica, not a second authority.
     ApplyReplica(&'static StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP>),
     ReadState,
+    /// Descriptor and current selection of the extension source, if any.
+    ReadExtension,
+    SetExtensionIfRevision {
+        expected_revision: u32,
+        state: ExtensionState,
+    },
     /// One atomically sampled page of the transient overlay.
     ReadOverlay {
         offset: u16,
@@ -601,6 +607,16 @@ pub struct ScenePage {
     pub cells: SceneChunk,
 }
 
+/// Extension-source readback: selectable content plus current selection.
+/// `descriptor`/`state` are `None` when the engine's extension band is not
+/// user-selectable (e.g. `EmptySource`).
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionPage {
+    pub revision: u32,
+    pub descriptor: Option<ExtensionDescriptor>,
+    pub state: Option<ExtensionState>,
+}
+
 /// One page of immutable board-compiled layer scenes.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct CompiledScenePage {
@@ -619,6 +635,7 @@ pub enum StandardReply {
     ScenesPage(ScenePage),
     CompiledScenesPage(CompiledScenePage),
     SceneTransaction { id: u32, cell_count: u16 },
+    Extension(ExtensionPage),
 }
 
 impl StandardReply {
@@ -650,6 +667,10 @@ pub struct StandardReplicaState<const OVERLAY_CAP: usize, const SCENE_CAP: usize
     pub scenes: SceneTable<SCENE_CAP>,
     pub context: LightingContext,
     pub sample_time_ms: u64,
+    /// Extension-source selection, carried so split renderer replicas track
+    /// the authority's animated band. `None` when the authority has no
+    /// selectable extension.
+    pub extension: Option<ExtensionState>,
 }
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
@@ -731,6 +752,9 @@ pub enum StandardError {
     /// Malformed scene request: bad chunk order, count overflow, or a
     /// duplicate `(layer, slot)` within one staged replacement.
     InvalidSceneRequest,
+    /// The extension source declined the state (none installed, or an index
+    /// out of its descriptor's range).
+    ExtensionUnsupported,
     SceneTransactionBusy,
     InvalidSceneTransaction,
     SceneTransactionExpired,
@@ -1049,6 +1073,9 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             scenes: self.scenes,
             context: *context.lighting_context(),
             sample_time_ms,
+            // Filled by handle_command, where the LightingSource bound is
+            // available on the Extension parameter.
+            extension: None,
         })
     }
 
@@ -1492,11 +1519,19 @@ where
                 (Invalidation::Render, true)
             }
             StandardCommand::ExportReplica(slot) => {
-                slot.put(self.replica_state(now_ms, snapshot)?)?;
+                let mut replica = self.replica_state(now_ms, snapshot)?;
+                replica.extension = self.extension.extension_state();
+                slot.put(replica)?;
                 (Invalidation::None, false)
             }
             StandardCommand::ApplyReplica(slot) => {
-                self.apply_replica(now_ms, slot.take()?)?;
+                let replica = slot.take()?;
+                let extension = replica.extension;
+                self.apply_replica(now_ms, replica)?;
+                if let Some(extension) = extension {
+                    // A replica without a matching extension declines harmlessly.
+                    let _ = self.extension.apply_extension_state(extension);
+                }
                 (Invalidation::Render, false)
             }
             StandardCommand::SetSceneCellIfRevision {
@@ -1539,6 +1574,23 @@ where
                     true,
                 )
             }
+            StandardCommand::ReadExtension => {
+                return Ok(CommandResult::unchanged(StandardReply::Extension(ExtensionPage {
+                    revision: self.revision,
+                    descriptor: self.extension.extension_descriptor(),
+                    state: self.extension.extension_state(),
+                })));
+            }
+            StandardCommand::SetExtensionIfRevision {
+                expected_revision,
+                state,
+            } => {
+                self.check_revision(expected_revision)?;
+                if !self.extension.apply_extension_state(state) {
+                    return Err(StandardError::ExtensionUnsupported);
+                }
+                (Invalidation::Render, true)
+            }
             StandardCommand::ReadState => (Invalidation::None, false),
             StandardCommand::ReadOverlay { .. }
             | StandardCommand::ReadScenes { .. }
@@ -1829,6 +1881,7 @@ mod tests {
             scenes: SceneTable::new(),
             context: context(0),
             sample_time_ms: 9,
+            extension: None,
         };
         slot.put(snapshot).unwrap();
         assert_eq!(slot.put(snapshot), Err(ReplicaSlotError::Busy));

From 474b62c75a9c078324364c123d364416dffd7d24 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 18:52:02 -0700
Subject: [PATCH 29/78] feat(rynk): expose extension-effects discovery and
 control

Three new lighting endpoints surface the engine's animated extension
band (an effect pack) to hosts:

- GetLightingExtension (0x0921): name-list sizes plus the live
  effect/palette/value/speed selection, pinned to the state revision.
- GetLightingExtensionNames (0x0922): pages of effect or palette names,
  static per firmware build, truncated to 16 bytes on char boundaries.
- SetLightingExtensionState (0x0923): revision-guarded selection
  replacement answering with the uniform updated LightingState.

Discovery rides LightingFeatureFlags::EXTENSION_EFFECTS (1 << 11),
advertised only by boards that call the new
RynkLightingController::with_extension_effects() builder. The adapter
bridges to the existing StandardCommand::ReadExtension /
SetExtensionIfRevision engine surface; a non-selectable extension
(EmptySource) answers Unsupported. The host client gains typed methods
plus a read_all_lighting_extension_names pager, and the wasm client
mirrors the same surface.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../main/docs/development/rynk_protocol.md    |   3 +
 rmk-types/src/protocol/rynk/command.rs        |  22 +-
 .../src/protocol/rynk/payload/lighting.rs     | 127 +++++++
 .../rynk/snapshots/lighting_wire_frames.snap  |   7 +
 rmk-types/src/protocol/rynk/tests.rs          |  67 ++++
 rmk/src/host/rynk/handlers/lighting.rs        |  83 ++++-
 rmk/src/host/rynk/lighting.rs                 | 325 +++++++++++++++++-
 rmk/src/host/rynk/mod.rs                      |   9 +-
 rynk/rynk-wasm/src/client.rs                  |   6 +-
 rynk/src/api.rs                               |  62 ++++
 10 files changed, 689 insertions(+), 22 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 63e8d6cca..79e2ccab0 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -297,6 +297,9 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x091E` | `GetLightingConditionalSceneStatus` | `()`                                  | `LightingConditionalSceneStatusResult` | `lighting`       | Discover immutable conditional lighting compiled from board config.                                                            |
 | `0x091F` | `GetLightingConditionalScenes`      | `LightingPageRequest`                 | `LightingConditionalScenesPageResult`  | `lighting`       | Conditional-scene pages are pinned to the firmware topology revision.                                                          |
 | `0x0920` | `GetLightingOutputMode`             | `()`                                  | `LightingOutputModeStateResult`        | `lighting`       | Read the configured three-state output policy and its live state.                                                              |
+| `0x0921` | `GetLightingExtension`              | `()`                                  | `LightingExtensionResult`              | `lighting`       | Discover the animated extension band: name-list sizes and selection.                                                           |
+| `0x0922` | `GetLightingExtensionNames`         | `LightingExtensionNamesRequest`       | `LightingExtensionNamesPageResult`     | `lighting`       | Extension names are static per firmware build; page until `total`.                                                             |
+| `0x0923` | `SetLightingExtensionState`         | `SetLightingExtensionStateRequest`    | `LightingStateResult`                  | `lighting`       | Replace the extension selection when the state revision matches.                                                               |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 3aa358669..918fbc436 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -39,12 +39,13 @@ use crate::protocol::rynk::{
     BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest,
     CommitLightingSceneReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingCompiledSceneStatusResult,
     LightingCompiledScenesPageResult, LightingConditionalSceneStatusResult, LightingConditionalScenesPageResult,
-    LightingKeysPageResult, LightingLedsPageResult, LightingOutputModeStateResult, LightingOutputsPageResult,
-    LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest,
-    LightingPhysicalKeysPageResult, LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatusResult,
-    LightingSceneTransactionResult, LightingScenesPageResult, LightingStateResult, LightingUnitResult,
-    LightingZoneMembershipsPageResult, LightingZonesPageResult, PutLightingOverlayChunkRequest,
-    PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
+    LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionResult, LightingKeysPageResult,
+    LightingLedsPageResult, LightingOutputModeStateResult, LightingOutputsPageResult, LightingOverlayPageRequest,
+    LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKeysPageResult,
+    LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatusResult, LightingSceneTransactionResult,
+    LightingScenesPageResult, LightingStateResult, LightingUnitResult, LightingZoneMembershipsPageResult,
+    LightingZonesPageResult, PutLightingOverlayChunkRequest, PutLightingSceneChunkRequest,
+    SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
     SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 #[cfg(all(feature = "_ble", feature = "split"))]
@@ -445,6 +446,15 @@ endpoints! {
     /// Read the configured three-state output policy and its live state.
     #[cfg(feature = "lighting")]
     GetLightingOutputMode = 0x0920: () => LightingOutputModeStateResult;
+    /// Discover the animated extension band: name-list sizes and selection.
+    #[cfg(feature = "lighting")]
+    GetLightingExtension = 0x0921: () => LightingExtensionResult;
+    /// Extension names are static per firmware build; page until `total`.
+    #[cfg(feature = "lighting")]
+    GetLightingExtensionNames = 0x0922: LightingExtensionNamesRequest => LightingExtensionNamesPageResult;
+    /// Replace the extension selection when the state revision matches.
+    #[cfg(feature = "lighting")]
+    SetLightingExtensionState = 0x0923: SetLightingExtensionStateRequest => LightingStateResult;
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 95eb64e2f..46b8ee375 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -21,6 +21,10 @@ pub const LIGHTING_SCENE_CHUNK_SIZE: usize = 8;
 pub const LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 8;
 /// Maximum UTF-8 byte length of a zone name.
 pub const LIGHTING_ZONE_NAME_SIZE: usize = 24;
+/// Maximum UTF-8 byte length of one extension effect or palette name.
+pub const LIGHTING_EXTENSION_NAME_SIZE: usize = 16;
+/// Number of names in one extension-names page.
+pub const LIGHTING_EXTENSION_NAME_CHUNK: usize = 8;
 
 macro_rules! wire_type {
     ($item:item) => {
@@ -192,6 +196,8 @@ impl LightingFeatureFlags {
     pub const COMPILED_CONDITIONAL_SCENES: u16 = 1 << 9;
     /// Declarative three-state output policy and live readback.
     pub const OUTPUT_MODE: u16 = 1 << 10;
+    /// Host-selectable animated extension effects served by an effect pack.
+    pub const EXTENSION_EFFECTS: u16 = 1 << 11;
 
     pub const fn contains(self, bits: u16) -> bool {
         self.0 & bits == bits
@@ -672,6 +678,68 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Current selection of the firmware's animated extension band. Indices
+    /// address the name lists served by `GetLightingExtensionNames`.
+    pub struct LightingExtensionState {
+        pub effect: u8,
+        pub palette: u8,
+        pub value: u8,
+        pub speed: u8,
+    }
+}
+
+wire_type! {
+    /// Extension-effects discovery: name-list sizes plus the live selection,
+    /// revision-pinned like every other lighting mutation surface.
+    pub struct LightingExtension {
+        pub revision: u32,
+        pub effect_count: u8,
+        pub palette_count: u8,
+        pub state: LightingExtensionState,
+    }
+}
+
+wire_type! {
+    /// Which extension name list a page request addresses.
+    pub enum LightingExtensionNameKind {
+        Effects,
+        Palettes,
+    }
+}
+
+wire_type! {
+    pub struct LightingExtensionNamesRequest {
+        pub kind: LightingExtensionNameKind,
+        pub offset: u8,
+    }
+}
+
+/// One page of extension effect or palette names. Names are static for a
+/// firmware build, so pages carry no revision pin.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LightingExtensionNamesPage {
+    pub total: u8,
+    #[cfg_attr(feature = "wasm", tsify(type = "string[]"))]
+    pub items: Vec<String<LIGHTING_EXTENSION_NAME_SIZE>, LIGHTING_EXTENSION_NAME_CHUNK>,
+}
+
+impl MaxSize for LightingExtensionNamesPage {
+    const POSTCARD_MAX_SIZE: usize = u8::POSTCARD_MAX_SIZE
+        + crate::varint_max_size(LIGHTING_EXTENSION_NAME_CHUNK)
+        + LIGHTING_EXTENSION_NAME_CHUNK * crate::heapless_vec_max_size::<u8, LIGHTING_EXTENSION_NAME_SIZE>();
+}
+
+wire_type! {
+    pub struct SetLightingExtensionStateRequest {
+        pub expected_revision: u32,
+        pub state: LightingExtensionState,
+    }
+}
+
 wire_type! {
     pub struct LightingConditionalSceneStatus {
         pub topology_revision: u32,
@@ -814,6 +882,8 @@ pub type LightingCompiledScenesPageResult = LightingResult<LightingCompiledScene
 pub type LightingConditionalSceneStatusResult = LightingResult<LightingConditionalSceneStatus>;
 pub type LightingConditionalScenesPageResult = LightingResult<LightingConditionalScenesPage>;
 pub type LightingOutputModeStateResult = LightingResult<LightingOutputModeState>;
+pub type LightingExtensionResult = LightingResult<LightingExtension>;
+pub type LightingExtensionNamesPageResult = LightingResult<LightingExtensionNamesPage>;
 pub type LightingSceneTransactionResult = LightingResult<LightingSceneTransaction>;
 pub type LightingUnitResult = LightingResult<()>;
 
@@ -858,6 +928,9 @@ const _: () = {
     assert_endpoint_fits!((), LightingConditionalSceneStatusResult);
     assert_endpoint_fits!(LightingPageRequest, LightingConditionalScenesPageResult);
     assert_endpoint_fits!((), LightingOutputModeStateResult);
+    assert_endpoint_fits!((), LightingExtensionResult);
+    assert_endpoint_fits!(LightingExtensionNamesRequest, LightingExtensionNamesPageResult);
+    assert_endpoint_fits!(SetLightingExtensionStateRequest, LightingStateResult);
     assert_endpoint_fits!(SetLightingSceneCellRequest, LightingStateResult);
     assert_endpoint_fits!(UnsetLightingSceneCellRequest, LightingStateResult);
     assert_endpoint_fits!(SetLightingLayerPolicyRequest, LightingStateResult);
@@ -1065,6 +1138,60 @@ mod tests {
         assert!(LightingConditionalScenesPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
     }
 
+    #[test]
+    fn extension_types_round_trip() {
+        round_trip(&LightingExtensionState {
+            effect: 1,
+            palette: 2,
+            value: 3,
+            speed: 4,
+        });
+        round_trip(&LightingExtension {
+            revision: u32::MAX,
+            effect_count: 6,
+            palette_count: 16,
+            state: LightingExtensionState {
+                effect: 5,
+                palette: 15,
+                value: u8::MAX,
+                speed: 0,
+            },
+        });
+        round_trip(&LightingExtensionNamesRequest {
+            kind: LightingExtensionNameKind::Effects,
+            offset: 0,
+        });
+        round_trip(&LightingExtensionNamesRequest {
+            kind: LightingExtensionNameKind::Palettes,
+            offset: LIGHTING_EXTENSION_NAME_CHUNK as u8,
+        });
+        round_trip(&SetLightingExtensionStateRequest {
+            expected_revision: u32::MAX,
+            state: LightingExtensionState {
+                effect: 0,
+                palette: 1,
+                value: 2,
+                speed: 3,
+            },
+        });
+    }
+
+    #[test]
+    fn maximum_extension_names_page_respects_bound() {
+        let mut items = Vec::new();
+        for _ in 0..LIGHTING_EXTENSION_NAME_CHUNK {
+            let mut name = String::new();
+            for _ in 0..LIGHTING_EXTENSION_NAME_SIZE {
+                name.push('x').unwrap();
+            }
+            items.push(name).unwrap();
+        }
+        let page = LightingExtensionNamesPage { total: u8::MAX, items };
+        round_trip(&page);
+        assert_max_size_bound(&page);
+        assert!(LightingExtensionNamesPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+    }
+
     #[test]
     fn scene_cell_validation_is_effect_validation() {
         assert_eq!(scene_cell(0, 1).validate(), Ok(()));
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index 6fd02b4ef..35af6dc03 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -25,6 +25,11 @@ GetLightingCompiledSceneStatus reply                   1c 09 01 06 00 00 00 01 0
 GetLightingCompiledSceneStatus request                 1c 09 01 00 00
 GetLightingCompiledScenes reply                        1d 09 01 0b 00 00 00 01 01 01 02 2a 00 07 08 09
 GetLightingCompiledScenes request                      1d 09 01 02 00 01 00
+GetLightingExtension inner Err(Unsupported)            21 09 01 03 00 00 01 00
+GetLightingExtension reply                             21 09 01 09 00 00 00 09 06 10 01 02 03 04
+GetLightingExtension request                           21 09 01 00 00
+GetLightingExtensionNames reply                        22 09 01 0a 00 00 00 10 01 05 4f 63 65 61 6e
+GetLightingExtensionNames request                      22 09 01 02 00 01 08
 GetLightingKeys reply                                  11 09 01 07 00 00 00 01 01 01 01 02
 GetLightingKeys request                                11 09 01 02 00 01 00
 GetLightingLeds reply                                  05 09 01 12 00 00 00 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01
@@ -55,6 +60,8 @@ PutLightingOverlayChunk reply                          0e 09 01 02 00 00 00
 PutLightingOverlayChunk request                        0e 09 01 10 00 0d 00 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27
 PutLightingSceneChunk reply                            17 09 01 02 00 00 00
 PutLightingSceneChunk request                          17 09 01 09 00 15 00 01 02 2a 00 07 08 09
+SetLightingExtensionState reply                        23 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+SetLightingExtensionState request                      23 09 01 05 00 09 01 02 03 04
 SetLightingLayerPolicy reply                           1a 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 SetLightingLayerPolicy request                         1a 09 01 02 00 0b 00
 SetLightingOverlay inner Err(UnknownLed)               0a 09 01 05 00 00 01 06 e7 07
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index e1ba397ea..659eb34b8 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1316,6 +1316,29 @@ fn lighting_wire_frames_locked() {
     let scene_abort = AbortLightingSceneReplaceRequest {
         transaction_id: scene_transaction.id,
     };
+    let extension = LightingExtension {
+        revision: state.revision,
+        effect_count: 6,
+        palette_count: 16,
+        state: LightingExtensionState {
+            effect: 1,
+            palette: 2,
+            value: 3,
+            speed: 4,
+        },
+    };
+    let extension_names_request = LightingExtensionNamesRequest {
+        kind: LightingExtensionNameKind::Palettes,
+        offset: LIGHTING_EXTENSION_NAME_CHUNK as u8,
+    };
+    let extension_names_page = LightingExtensionNamesPage {
+        total: 16,
+        items: one(heapless::String::try_from("Ocean").unwrap()),
+    };
+    let set_extension_state = SetLightingExtensionStateRequest {
+        expected_revision: state.revision,
+        state: extension.state,
+    };
     let output_mode = LightingOutputModeState {
         mode: LightingOutputMode::PoweredOnly,
         powered: true,
@@ -1741,6 +1764,50 @@ fn lighting_wire_frames_locked() {
                 &Ok::<LightingStateResult, RynkError>(Err(LightingError::SceneFull { capacity: 256 }))
             )
         ),
+        (
+            "GetLightingExtension request",
+            encode_frame(Cmd::GetLightingExtension, SEQ, &())
+        ),
+        (
+            "GetLightingExtension reply",
+            encode_frame(
+                Cmd::GetLightingExtension,
+                SEQ,
+                &Ok::<LightingExtensionResult, RynkError>(Ok(extension))
+            )
+        ),
+        (
+            "GetLightingExtension inner Err(Unsupported)",
+            encode_frame(
+                Cmd::GetLightingExtension,
+                SEQ,
+                &Ok::<LightingExtensionResult, RynkError>(Err(LightingError::Unsupported))
+            )
+        ),
+        (
+            "GetLightingExtensionNames request",
+            encode_frame(Cmd::GetLightingExtensionNames, SEQ, &extension_names_request)
+        ),
+        (
+            "GetLightingExtensionNames reply",
+            encode_frame(
+                Cmd::GetLightingExtensionNames,
+                SEQ,
+                &Ok::<LightingExtensionNamesPageResult, RynkError>(Ok(extension_names_page))
+            )
+        ),
+        (
+            "SetLightingExtensionState request",
+            encode_frame(Cmd::SetLightingExtensionState, SEQ, &set_extension_state)
+        ),
+        (
+            "SetLightingExtensionState reply",
+            encode_frame(
+                Cmd::SetLightingExtensionState,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
         (
             "LightingChange topic",
             encode_frame(Cmd::LightingChange, 0, &LightingChanged)
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 323361aa9..76ece5400 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -4,11 +4,11 @@ use embassy_time::Instant;
 use heapless::{String, Vec};
 use rmk_types::protocol::rynk::command::{
     ClearLightingOverlay, GetLightingCapabilities, GetLightingCompiledSceneStatus, GetLightingCompiledScenes,
-    GetLightingConditionalSceneStatus, GetLightingConditionalScenes, GetLightingKeys, GetLightingLeds,
-    GetLightingOutputMode, GetLightingOutputs, GetLightingOverlay, GetLightingPhysicalKeys, GetLightingRoutes,
-    GetLightingSceneStatus, GetLightingScenes, GetLightingState, GetLightingZoneMemberships, GetLightingZones,
-    SetLightingLayerPolicy, SetLightingOverlay, SetLightingSceneCell, SetLightingState, UnsetLightingOverlay,
-    UnsetLightingSceneCell,
+    GetLightingConditionalSceneStatus, GetLightingConditionalScenes, GetLightingExtension, GetLightingExtensionNames,
+    GetLightingKeys, GetLightingLeds, GetLightingOutputMode, GetLightingOutputs, GetLightingOverlay,
+    GetLightingPhysicalKeys, GetLightingRoutes, GetLightingSceneStatus, GetLightingScenes, GetLightingState,
+    GetLightingZoneMemberships, GetLightingZones, SetLightingExtensionState, SetLightingLayerPolicy,
+    SetLightingOverlay, SetLightingSceneCell, SetLightingState, UnsetLightingOverlay, UnsetLightingSceneCell,
 };
 use rmk_types::protocol::rynk::{
     AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
@@ -18,8 +18,9 @@ use rmk_types::protocol::rynk::{
     LightingCompiledSceneStatus, LightingCompiledSceneStatusResult, LightingCompiledScenesPageResult,
     LightingConditionalSceneCell, LightingConditionalSceneStatus, LightingConditionalSceneStatusResult,
     LightingConditionalScenesPage, LightingConditionalScenesPageResult, LightingEffectFlags, LightingError,
-    LightingFeatureFlags, LightingKeysPage, LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage,
-    LightingLedsPageResult, LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage,
+    LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionResult, LightingFeatureFlags,
+    LightingKeysPage, LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
+    LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage,
     LightingOutputModeStateResult, LightingOutputsPage, LightingOutputsPageResult, LightingOverlayCell,
     LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransaction,
     LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKey, LightingPhysicalKeysPage,
@@ -28,8 +29,8 @@ use rmk_types::protocol::rynk::{
     LightingSceneTransactionResult, LightingScenesPageResult, LightingState, LightingStateResult, LightingUnitResult,
     LightingZone, LightingZoneId, LightingZoneMembershipsPage, LightingZoneMembershipsPageResult, LightingZonesPage,
     LightingZonesPageResult, PutLightingOverlayChunkRequest, PutLightingSceneChunkRequest, RynkError, RynkMessage,
-    SetLightingLayerPolicyRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
-    UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
+    SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
+    SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 
 use super::super::lighting::{
@@ -55,6 +56,16 @@ fn scene_controller<'a>(service: &RynkService<'a>) -> LightingResult<RynkLightin
     Ok(controller)
 }
 
+/// Extension endpoints require a board that advertised a host-selectable
+/// extension source via `with_extension_effects`.
+fn extension_controller<'a>(service: &RynkService<'a>) -> LightingResult<RynkLightingController<'a>> {
+    let controller = controller(service)?;
+    if !controller.extension_effects {
+        return Err(LightingError::Unsupported);
+    }
+    Ok(controller)
+}
+
 impl Handle<GetLightingCapabilities> for RynkService<'_> {
     async fn handle(&self, _: ()) -> Result<LightingCapabilitiesResult, RynkError> {
         Ok(controller(self).map(capabilities))
@@ -466,6 +477,57 @@ impl Handle<rmk_types::protocol::rynk::command::AbortLightingSceneReplace> for R
     }
 }
 
+impl Handle<GetLightingExtension> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LightingExtensionResult, RynkError> {
+        let result = match extension_controller(self) {
+            Ok(controller) => match controller.request(RynkLightingCommand::ReadExtension).await {
+                Ok(RynkLightingReadback::Extension(extension)) => Ok(extension),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<GetLightingExtensionNames> for RynkService<'_> {
+    async fn handle(&self, req: LightingExtensionNamesRequest) -> Result<LightingExtensionNamesPageResult, RynkError> {
+        let result = match extension_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::ReadExtensionNames {
+                    kind: req.kind,
+                    offset: req.offset,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::ExtensionNamesPage(page)) => Ok(page),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<SetLightingExtensionState> for RynkService<'_> {
+    async fn handle(&self, req: SetLightingExtensionStateRequest) -> Result<LightingStateResult, RynkError> {
+        let result = match extension_controller(self) {
+            Ok(controller) => {
+                controller
+                    .request_state(RynkLightingCommand::SetExtensionState {
+                        expected_revision: req.expected_revision,
+                        state: req.state,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
 impl Handle<GetLightingKeys> for RynkService<'_> {
     async fn handle(&self, req: LightingPageRequest) -> Result<LightingKeysPageResult, RynkError> {
         Ok(controller(self).and_then(|binding| keys_page(binding, req)))
@@ -537,6 +599,9 @@ fn capabilities(binding: RynkLightingController<'_>) -> LightingCapabilities {
     if binding.controls.output_mode_cycle_user_action.is_some() {
         features.0 |= LightingFeatureFlags::OUTPUT_MODE;
     }
+    if binding.extension_effects {
+        features.0 |= LightingFeatureFlags::EXTENSION_EFFECTS;
+    }
     LightingCapabilities {
         topology_revision: descriptor.topology_revision,
         logical_key_count: count(topology.keys.len()),
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 853c79056..f009a15e4 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -13,11 +13,13 @@ use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
 use embassy_sync::channel::Channel;
 use embassy_sync::mutex::Mutex;
 use embassy_sync::signal::Signal;
-use heapless::Vec;
+use heapless::{String, Vec};
 use rmk_types::protocol::rynk::{
-    LIGHTING_OVERLAY_CHUNK_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState,
-    LightingCompiledScenesPage, LightingConditionalSceneCell as WireConditionalSceneCell,
-    LightingControls as WireLightingControls, LightingError, LightingLayerPolicy, LightingMutableState,
+    LIGHTING_EXTENSION_NAME_CHUNK, LIGHTING_EXTENSION_NAME_SIZE, LIGHTING_OVERLAY_CHUNK_SIZE,
+    LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState, LightingCompiledScenesPage,
+    LightingConditionalSceneCell as WireConditionalSceneCell, LightingControls as WireLightingControls, LightingError,
+    LightingExtension, LightingExtensionNameKind, LightingExtensionNamesPage,
+    LightingExtensionState as WireExtensionState, LightingLayerPolicy, LightingMutableState,
     LightingOutputMode as WireLightingOutputMode, LightingOutputModeIndicator as WireLightingOutputModeIndicator,
     LightingOutputModeState, LightingOverlayCell, LightingOverlayPage, LightingResult, LightingRgb8, LightingSceneCell,
     LightingSceneTransaction, LightingScenesPage, LightingState,
@@ -68,6 +70,9 @@ pub struct RynkLightingController<'a> {
     pub(super) scene_capacity: u16,
     pub(super) conditional_scenes: &'a [ConditionalSceneCell<BuiltinEffect>],
     pub(super) controls: LightingControls,
+    /// Whether the board wired a host-selectable extension source; gates the
+    /// `EXTENSION_EFFECTS` capability bit and the extension endpoints.
+    pub(super) extension_effects: bool,
     mailbox: &'a RynkLightingMailbox,
 }
 
@@ -97,10 +102,18 @@ impl<'a> RynkLightingController<'a> {
                 powered_only_scope: crate::lighting::PoweredOnlyScope::Authority,
                 output_mode_indicator: None,
             },
+            extension_effects: false,
             mailbox,
         }
     }
 
+    /// Advertise the engine's host-selectable animated extension source.
+    /// Boards whose extension band is not user-selectable skip this call.
+    pub const fn with_extension_effects(mut self) -> Self {
+        self.extension_effects = true;
+        self
+    }
+
     /// Advertise runtime scene support. Pass the engine's scene capacity;
     /// boards without a scene table simply skip this call.
     pub const fn with_scene_capacity(mut self, scene_capacity: u16) -> Self {
@@ -219,6 +232,8 @@ pub enum RynkLightingReadback {
     },
     CompiledScenesPage(LightingCompiledScenesPage),
     SceneTransaction(LightingSceneTransaction),
+    Extension(LightingExtension),
+    ExtensionNamesPage(LightingExtensionNamesPage),
     Unit,
 }
 
@@ -383,6 +398,15 @@ pub(super) enum RynkLightingCommand {
     ReadCompiledScenes {
         offset: u16,
     },
+    ReadExtension,
+    ReadExtensionNames {
+        kind: LightingExtensionNameKind,
+        offset: u8,
+    },
+    SetExtensionState {
+        expected_revision: u32,
+        state: WireExtensionState,
+    },
     SetSceneCell {
         expected_revision: u32,
         cell: LightingSceneCell,
@@ -497,6 +521,15 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
         }
     }
 
+    /// Extension readback shared by discovery and name paging. `None`
+    /// descriptor/state (e.g. `EmptySource`) is not selectable → `Unsupported`.
+    async fn request_extension_page(&self) -> LightingResult<crate::lighting::standard::ExtensionPage> {
+        match self.request_core(StandardCommand::ReadExtension).await? {
+            StandardReply::Extension(page) => Ok(page),
+            _ => Err(LightingError::InvalidRequest),
+        }
+    }
+
     /// Run a scene mutation, then persist the whole authoritative scene
     /// configuration. Persisting by readback keeps the engine the single
     /// source of truth instead of mirroring its insertion algorithm here.
@@ -655,6 +688,55 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                     items,
                 }));
             }
+            RynkLightingCommand::ReadExtension => {
+                let page = self.request_extension_page().await?;
+                let (Some(descriptor), Some(state)) = (page.descriptor, page.state) else {
+                    return Err(LightingError::Unsupported);
+                };
+                return Ok(RynkLightingReadback::Extension(LightingExtension {
+                    revision: page.revision,
+                    effect_count: descriptor.effects.len().min(u8::MAX as usize) as u8,
+                    palette_count: descriptor.palettes.len().min(u8::MAX as usize) as u8,
+                    state: WireExtensionState {
+                        effect: state.effect,
+                        palette: state.palette,
+                        value: state.value,
+                        speed: state.speed,
+                    },
+                }));
+            }
+            RynkLightingCommand::ReadExtensionNames { kind, offset } => {
+                let page = self.request_extension_page().await?;
+                let Some(descriptor) = page.descriptor else {
+                    return Err(LightingError::Unsupported);
+                };
+                let names = match kind {
+                    LightingExtensionNameKind::Effects => descriptor.effects,
+                    LightingExtensionNameKind::Palettes => descriptor.palettes,
+                };
+                let start = (offset as usize).min(names.len());
+                let end = (start + LIGHTING_EXTENSION_NAME_CHUNK).min(names.len());
+                let mut items: Vec<String<LIGHTING_EXTENSION_NAME_SIZE>, LIGHTING_EXTENSION_NAME_CHUNK> = Vec::new();
+                for name in &names[start..end] {
+                    items.push(super::truncated(name)).expect("page is bounded");
+                }
+                return Ok(RynkLightingReadback::ExtensionNamesPage(LightingExtensionNamesPage {
+                    total: names.len().min(u8::MAX as usize) as u8,
+                    items,
+                }));
+            }
+            RynkLightingCommand::SetExtensionState {
+                expected_revision,
+                state,
+            } => StandardCommand::SetExtensionIfRevision {
+                expected_revision,
+                state: crate::lighting::compositor::ExtensionState {
+                    effect: state.effect,
+                    palette: state.palette,
+                    value: state.value,
+                    speed: state.speed,
+                },
+            },
             RynkLightingCommand::SetSceneCell {
                 expected_revision,
                 cell,
@@ -998,11 +1080,12 @@ fn effect_to_wire(effect: BuiltinEffect) -> rmk_types::protocol::rynk::LightingE
 }
 
 fn condition_set_to_wire(conditions: crate::lighting::ConditionSet) -> rmk_types::protocol::rynk::LightingConditionSet {
-    use crate::lighting::ChargeCondition;
     use rmk_types::protocol::rynk::{
         LightingBatteryCondition, LightingChargeCondition, LightingConditionSet, LightingLayerCondition, LightingNodeId,
     };
 
+    use crate::lighting::ChargeCondition;
+
     LightingConditionSet {
         layer: conditions.layer.map(|condition| LightingLayerCondition {
             layer: condition.layer,
@@ -1175,4 +1258,236 @@ mod tests {
         let (reply, ()) = block_on(join(protocol.request_replace(0, &cells), adapter.process_next()));
         assert_eq!(reply, Err(LightingError::InvalidRequest));
     }
+
+    static TEST_EFFECT_NAMES: &[&str] = &["Gradient", "Flow", "ABCDEFGHIJKLMNOé tail"];
+    static TEST_PALETTE_NAMES: &[&str] = &["P0", "P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8", "P9"];
+
+    /// Zero-target source whose only job is serving the extension hooks.
+    struct TestExtensionSource {
+        state: crate::lighting::compositor::ExtensionState,
+    }
+
+    impl<Context> crate::lighting::compositor::LightingSource<Rgb8, Context> for TestExtensionSource {
+        fn len(&self, _: &crate::lighting::compositor::RenderInput<'_, Context>) -> usize {
+            0
+        }
+
+        fn slot(
+            &self,
+            _: usize,
+            _: &crate::lighting::compositor::RenderInput<'_, Context>,
+        ) -> crate::lighting::LedSlot {
+            unreachable!("test extension source has no targets")
+        }
+
+        fn contribution(
+            &mut self,
+            _: usize,
+            _: &crate::lighting::compositor::RenderInput<'_, Context>,
+        ) -> crate::lighting::compositor::Contribution<Rgb8> {
+            unreachable!("test extension source has no samples")
+        }
+
+        fn extension_descriptor(&self) -> Option<crate::lighting::compositor::ExtensionDescriptor> {
+            Some(crate::lighting::compositor::ExtensionDescriptor {
+                effects: TEST_EFFECT_NAMES,
+                palettes: TEST_PALETTE_NAMES,
+            })
+        }
+
+        fn extension_state(&self) -> Option<crate::lighting::compositor::ExtensionState> {
+            Some(self.state)
+        }
+
+        fn apply_extension_state(&mut self, state: crate::lighting::compositor::ExtensionState) -> bool {
+            self.state = state;
+            true
+        }
+    }
+
+    /// Serve `client` against a live adapter + engine built around `extension`.
+    fn run_extension_flow<Extension, T>(extension: Extension, client: impl AsyncFnOnce(&RynkLightingMailbox) -> T) -> T
+    where
+        Extension: crate::lighting::compositor::LightingSource<Rgb8, crate::lighting::LightingContext>,
+    {
+        use embassy_futures::select::{Either3, select3};
+
+        use crate::lighting::{
+            BackgroundState, EmptySource, LayerPolicy, LayerScenes, LightingContext, LightingEngine,
+            StandardLightingEngine,
+        };
+
+        block_on(async {
+            let protocol = RynkLightingMailbox::new();
+            let core = LightingMailbox::<StandardCommand<2>, StandardReply, StandardError, 1>::new();
+            let mut adapter = StandardRynkLightingAdapter::<2, 1>::new(&protocol, &core, topology());
+            let mut engine: StandardLightingEngine<'static, Extension, EmptySource, 1, 2, 0> =
+                StandardLightingEngine::new(
+                    BackgroundState::default(),
+                    LayerScenes {
+                        scenes: &[],
+                        policy: LayerPolicy::EffectiveOnly,
+                    },
+                    extension,
+                    EmptySource,
+                );
+
+            let adapter_loop = async {
+                loop {
+                    adapter.process_next().await;
+                }
+            };
+            let context = LightingContext::default();
+            let engine_loop = async {
+                loop {
+                    let (id, command) = core.receive_request().await;
+                    let result = engine.handle_command(0, command, &context).map(|outcome| outcome.reply);
+                    core.publish_reply(id, result);
+                }
+            };
+            match select3(client(&protocol), adapter_loop, engine_loop).await {
+                Either3::First(value) => value,
+                _ => panic!("service loops must not finish"),
+            }
+        })
+    }
+
+    #[test]
+    fn extension_flow_reads_pages_truncates_and_guards_revision() {
+        run_extension_flow(
+            TestExtensionSource {
+                state: crate::lighting::compositor::ExtensionState {
+                    effect: 0,
+                    palette: 1,
+                    value: 128,
+                    speed: 20,
+                },
+            },
+            async |protocol| {
+                let extension = match protocol.request(RynkLightingCommand::ReadExtension).await {
+                    Ok(RynkLightingReadback::Extension(extension)) => extension,
+                    other => panic!("expected extension readback, got {other:?}"),
+                };
+                assert_eq!(extension.revision, 0);
+                assert_eq!(extension.effect_count, 3);
+                assert_eq!(extension.palette_count, 10);
+                assert_eq!(
+                    extension.state,
+                    WireExtensionState {
+                        effect: 0,
+                        palette: 1,
+                        value: 128,
+                        speed: 20,
+                    }
+                );
+
+                // Overlong names are truncated to the wire size on a char
+                // boundary: the multi-byte 'é' straddling byte 16 is dropped.
+                let effects = match protocol
+                    .request(RynkLightingCommand::ReadExtensionNames {
+                        kind: LightingExtensionNameKind::Effects,
+                        offset: 0,
+                    })
+                    .await
+                {
+                    Ok(RynkLightingReadback::ExtensionNamesPage(page)) => page,
+                    other => panic!("expected names page, got {other:?}"),
+                };
+                assert_eq!(effects.total, 3);
+                assert_eq!(effects.items.len(), 3);
+                assert_eq!(effects.items[0].as_str(), "Gradient");
+                assert_eq!(effects.items[2].as_str(), "ABCDEFGHIJKLMNO");
+
+                // Ten palettes page as one full chunk plus a two-name tail;
+                // an out-of-range offset yields an empty page, correct total.
+                for (offset, expected) in [
+                    (0u8, &TEST_PALETTE_NAMES[..8]),
+                    (8, &TEST_PALETTE_NAMES[8..]),
+                    (32, &[][..]),
+                ] {
+                    let page = match protocol
+                        .request(RynkLightingCommand::ReadExtensionNames {
+                            kind: LightingExtensionNameKind::Palettes,
+                            offset,
+                        })
+                        .await
+                    {
+                        Ok(RynkLightingReadback::ExtensionNamesPage(page)) => page,
+                        other => panic!("expected names page, got {other:?}"),
+                    };
+                    assert_eq!(page.total, 10);
+                    assert_eq!(page.items.len(), expected.len());
+                    for (item, name) in page.items.iter().zip(expected) {
+                        assert_eq!(item.as_str(), *name);
+                    }
+                }
+
+                let selected = WireExtensionState {
+                    effect: 2,
+                    palette: 9,
+                    value: 7,
+                    speed: 3,
+                };
+                let state = match protocol
+                    .request(RynkLightingCommand::SetExtensionState {
+                        expected_revision: 0,
+                        state: selected,
+                    })
+                    .await
+                {
+                    Ok(RynkLightingReadback::State(state)) => state,
+                    other => panic!("expected state readback, got {other:?}"),
+                };
+                assert_eq!(state.revision, 1);
+
+                let extension = match protocol.request(RynkLightingCommand::ReadExtension).await {
+                    Ok(RynkLightingReadback::Extension(extension)) => extension,
+                    other => panic!("expected extension readback, got {other:?}"),
+                };
+                assert_eq!(extension.revision, 1);
+                assert_eq!(extension.state, selected);
+
+                let stale = protocol
+                    .request(RynkLightingCommand::SetExtensionState {
+                        expected_revision: 0,
+                        state: selected,
+                    })
+                    .await;
+                assert_eq!(
+                    stale,
+                    Err(LightingError::StateRevisionConflict {
+                        expected: 0,
+                        current: 1,
+                    })
+                );
+            },
+        );
+    }
+
+    #[test]
+    fn extension_commands_are_unsupported_with_an_empty_source() {
+        run_extension_flow(crate::lighting::EmptySource, async |protocol| {
+            let read = protocol.request(RynkLightingCommand::ReadExtension).await;
+            assert_eq!(read, Err(LightingError::Unsupported));
+            let names = protocol
+                .request(RynkLightingCommand::ReadExtensionNames {
+                    kind: LightingExtensionNameKind::Effects,
+                    offset: 0,
+                })
+                .await;
+            assert_eq!(names, Err(LightingError::Unsupported));
+            let set = protocol
+                .request(RynkLightingCommand::SetExtensionState {
+                    expected_revision: 0,
+                    state: WireExtensionState {
+                        effect: 0,
+                        palette: 0,
+                        value: 0,
+                        speed: 0,
+                    },
+                })
+                .await;
+            assert_eq!(set, Err(LightingError::Unsupported));
+        });
+    }
 }
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 18ac9e1af..f0d770d70 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -174,7 +174,8 @@ impl<'a> RynkService<'a> {
             | Cmd::BeginLightingSceneReplace
             | Cmd::PutLightingSceneChunk
             | Cmd::CommitLightingSceneReplace
-            | Cmd::AbortLightingSceneReplace => self.lock_config.write_requires_unlock,
+            | Cmd::AbortLightingSceneReplace
+            | Cmd::SetLightingExtensionState => self.lock_config.write_requires_unlock,
             _ => false,
         }
     }
@@ -317,6 +318,12 @@ impl<'a> RynkService<'a> {
             #[cfg(feature = "lighting")]
             Cmd::GetLightingOutputMode => Serve::<command::GetLightingOutputMode, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
+            Cmd::GetLightingExtension => Serve::<command::GetLightingExtension, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingExtensionNames => Serve::<command::GetLightingExtensionNames, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::SetLightingExtensionState => Serve::<command::SetLightingExtensionState, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
             Cmd::SetLightingSceneCell => Serve::<command::SetLightingSceneCell, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::UnsetLightingSceneCell => Serve::<command::UnsetLightingSceneCell, _>::serve(self, msg).await,
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index ecd0bb5ed..bf24081df 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -35,7 +35,8 @@ use rynk::rmk_types::protocol::rynk::{
     LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingSceneCellRequest,
     UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus, LightingCompiledScenesPage,
     LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy, SplitCentralLatencyState,
-    LightingConditionalSceneStatus, LightingConditionalScenesPage, LightingOutputModeState,
+    LightingConditionalSceneStatus, LightingConditionalScenesPage, LightingOutputModeState, LightingExtension,
+    LightingExtensionNamesPage, LightingExtensionNamesRequest, SetLightingExtensionStateRequest,
 };
 use rynk::{Client, Driver, LayoutInfo, RynkDevice, RynkHostError, TopicEvent};
 use wasm_bindgen::prelude::*;
@@ -194,6 +195,9 @@ endpoints! {
     commit_lighting_overlay_replace(request: CommitLightingOverlayReplaceRequest) -> LightingState,
     abort_lighting_overlay_replace(request: AbortLightingOverlayReplaceRequest) -> (),
     get_lighting_overlay(request: LightingOverlayPageRequest) -> LightingOverlayPage,
+    get_lighting_extension() -> LightingExtension,
+    get_lighting_extension_names(request: LightingExtensionNamesRequest) -> LightingExtensionNamesPage,
+    set_lighting_extension_state(request: SetLightingExtensionStateRequest) -> LightingState,
     get_lighting_scene_status() -> LightingSceneStatus,
     get_lighting_scenes(request: LightingScenePageRequest) -> LightingScenesPage,
     get_lighting_compiled_scene_status() -> LightingCompiledSceneStatus,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 5b25501f3..614569a21 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -37,6 +37,8 @@ use rmk_types::protocol::rynk::{
     SetLightingSceneCellRequest, UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus,
     LightingCompiledScenesPage, LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy,
     SplitCentralLatencyState, LightingConditionalSceneStatus, LightingConditionalScenesPage, LightingOutputModeState,
+    LightingExtension, LightingExtensionNameKind, LightingExtensionNamesPage, LightingExtensionNamesRequest,
+    SetLightingExtensionStateRequest,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -599,6 +601,34 @@ impl Client {
         Self::flatten_lighting(self.request::<command::GetLightingConditionalScenes>(&request).await?)
     }
 
+    /// Discover the animated extension band: name-list sizes plus the live
+    /// selection. Extension support is discovered through
+    /// [`LightingCapabilities::features`] (`EXTENSION_EFFECTS`); firmware
+    /// without a selectable extension source rejects it with `Unsupported`.
+    pub async fn get_lighting_extension(&self) -> Result<LightingExtension, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingExtension)?;
+        Self::flatten_lighting(self.request::<command::GetLightingExtension>(&()).await?)
+    }
+
+    /// Read one page of extension effect or palette names. Names are static
+    /// per firmware build, so pages carry no revision pin.
+    pub async fn get_lighting_extension_names(
+        &self,
+        request: LightingExtensionNamesRequest,
+    ) -> Result<LightingExtensionNamesPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingExtensionNames)?;
+        Self::flatten_lighting(self.request::<command::GetLightingExtensionNames>(&request).await?)
+    }
+
+    /// Replace the extension selection when the state revision matches.
+    pub async fn set_lighting_extension_state(
+        &self,
+        request: SetLightingExtensionStateRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::SetLightingExtensionState)?;
+        Self::flatten_lighting(self.request::<command::SetLightingExtensionState>(&request).await?)
+    }
+
     /// Insert or update one durable scene cell when the revision matches.
     pub async fn set_lighting_scene_cell(
         &self,
@@ -1008,6 +1038,38 @@ impl Client {
         Err(last_error.expect("a retried read only exits with a recorded conflict"))
     }
 
+    /// Read every extension name of one kind by paging
+    /// `GetLightingExtensionNames`. Names are static per firmware build, so no
+    /// revision pin is needed: the read simply walks offsets until the
+    /// advertised total, and non-advancing pages are rejected so it is bounded.
+    pub async fn read_all_lighting_extension_names(
+        &self,
+        kind: LightingExtensionNameKind,
+    ) -> Result<Vec<heapless::String<{ rmk_types::protocol::rynk::LIGHTING_EXTENSION_NAME_SIZE }>>, RynkHostError> {
+        let mut names = Vec::new();
+        let mut offset: u8 = 0;
+        loop {
+            let page = self
+                .get_lighting_extension_names(LightingExtensionNamesRequest { kind, offset })
+                .await?;
+            if offset >= page.total {
+                break;
+            }
+            if page.items.is_empty() || offset as usize + page.items.len() > page.total as usize {
+                return Err(RynkHostError::InconsistentResponse {
+                    cmd: Cmd::GetLightingExtensionNames,
+                    reason: "names page is empty or extends beyond the advertised total",
+                });
+            }
+            offset += page.items.len() as u8;
+            names.extend(page.items.iter().cloned());
+            if offset >= page.total {
+                break;
+            }
+        }
+        Ok(names)
+    }
+
     /// Atomically replace the whole stored scene table: begin, stage in
     /// chunk-sized pages, and commit. A staging failure is followed by a
     /// best-effort abort so the firmware transaction is not left dangling.

From 0a59edf0b6d9a81a0c5ef178e99c852b49849ae5 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 21 Jul 2026 19:39:08 -0700
Subject: [PATCH 30/78] Make lighting extension replication atomic

---
 rmk/src/host/rynk/lighting.rs  |  77 +++++++++++++-
 rmk/src/lighting/compositor.rs |   6 +-
 rmk/src/lighting/standard.rs   | 186 ++++++++++++++++++++++++++++++---
 3 files changed, 250 insertions(+), 19 deletions(-)

diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index f009a15e4..49fdef269 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -693,10 +693,13 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                 let (Some(descriptor), Some(state)) = (page.descriptor, page.state) else {
                     return Err(LightingError::Unsupported);
                 };
+                if descriptor.effects.len() > u8::MAX as usize || descriptor.palettes.len() > u8::MAX as usize {
+                    return Err(LightingError::InvalidRequest);
+                }
                 return Ok(RynkLightingReadback::Extension(LightingExtension {
                     revision: page.revision,
-                    effect_count: descriptor.effects.len().min(u8::MAX as usize) as u8,
-                    palette_count: descriptor.palettes.len().min(u8::MAX as usize) as u8,
+                    effect_count: descriptor.effects.len() as u8,
+                    palette_count: descriptor.palettes.len() as u8,
                     state: WireExtensionState {
                         effect: state.effect,
                         palette: state.palette,
@@ -710,6 +713,9 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                 let Some(descriptor) = page.descriptor else {
                     return Err(LightingError::Unsupported);
                 };
+                if descriptor.effects.len() > u8::MAX as usize || descriptor.palettes.len() > u8::MAX as usize {
+                    return Err(LightingError::InvalidRequest);
+                }
                 let names = match kind {
                     LightingExtensionNameKind::Effects => descriptor.effects,
                     LightingExtensionNameKind::Palettes => descriptor.palettes,
@@ -721,7 +727,7 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                     items.push(super::truncated(name)).expect("page is bounded");
                 }
                 return Ok(RynkLightingReadback::ExtensionNamesPage(LightingExtensionNamesPage {
-                    total: names.len().min(u8::MAX as usize) as u8,
+                    total: names.len() as u8,
                     items,
                 }));
             }
@@ -1261,6 +1267,7 @@ mod tests {
 
     static TEST_EFFECT_NAMES: &[&str] = &["Gradient", "Flow", "ABCDEFGHIJKLMNOé tail"];
     static TEST_PALETTE_NAMES: &[&str] = &["P0", "P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8", "P9"];
+    static TOO_MANY_EFFECT_NAMES: [&str; 256] = ["Effect"; 256];
 
     /// Zero-target source whose only job is serving the extension hooks.
     struct TestExtensionSource {
@@ -1305,6 +1312,41 @@ mod tests {
         }
     }
 
+    struct TooManyNamesSource(TestExtensionSource);
+
+    impl<Context> crate::lighting::compositor::LightingSource<Rgb8, Context> for TooManyNamesSource {
+        fn len(&self, _: &crate::lighting::compositor::RenderInput<'_, Context>) -> usize {
+            0
+        }
+
+        fn slot(
+            &self,
+            _: usize,
+            _: &crate::lighting::compositor::RenderInput<'_, Context>,
+        ) -> crate::lighting::LedSlot {
+            unreachable!("test extension source has no targets")
+        }
+
+        fn contribution(
+            &mut self,
+            _: usize,
+            _: &crate::lighting::compositor::RenderInput<'_, Context>,
+        ) -> crate::lighting::compositor::Contribution<Rgb8> {
+            unreachable!("test extension source has no samples")
+        }
+
+        fn extension_descriptor(&self) -> Option<crate::lighting::compositor::ExtensionDescriptor> {
+            Some(crate::lighting::compositor::ExtensionDescriptor {
+                effects: &TOO_MANY_EFFECT_NAMES,
+                palettes: TEST_PALETTE_NAMES,
+            })
+        }
+
+        fn extension_state(&self) -> Option<crate::lighting::compositor::ExtensionState> {
+            Some(self.0.state)
+        }
+    }
+
     /// Serve `client` against a live adapter + engine built around `extension`.
     fn run_extension_flow<Extension, T>(extension: Extension, client: impl AsyncFnOnce(&RynkLightingMailbox) -> T) -> T
     where
@@ -1490,4 +1532,33 @@ mod tests {
             assert_eq!(set, Err(LightingError::Unsupported));
         });
     }
+
+    #[test]
+    fn extension_commands_reject_descriptors_that_exceed_wire_counts() {
+        run_extension_flow(
+            TooManyNamesSource(TestExtensionSource {
+                state: crate::lighting::compositor::ExtensionState {
+                    effect: 0,
+                    palette: 0,
+                    value: 128,
+                    speed: 20,
+                },
+            }),
+            async |protocol| {
+                assert_eq!(
+                    protocol.request(RynkLightingCommand::ReadExtension).await,
+                    Err(LightingError::InvalidRequest)
+                );
+                assert_eq!(
+                    protocol
+                        .request(RynkLightingCommand::ReadExtensionNames {
+                            kind: LightingExtensionNameKind::Effects,
+                            offset: 248,
+                        })
+                        .await,
+                    Err(LightingError::InvalidRequest)
+                );
+            },
+        );
+    }
 }
diff --git a/rmk/src/lighting/compositor.rs b/rmk/src/lighting/compositor.rs
index 3ff8d228e..b925d1f82 100644
--- a/rmk/src/lighting/compositor.rs
+++ b/rmk/src/lighting/compositor.rs
@@ -63,13 +63,17 @@ pub trait LightingSource<C, Context> {
     }
 
     /// Apply a host-selected state. Return `true` if accepted; the engine
-    /// then re-renders and advances its revision. The default declines.
+    /// then re-renders and advances its revision. Returning `false` must
+    /// leave the source unchanged so replica application can remain atomic.
+    /// The default declines.
     fn apply_extension_state(&mut self, _state: ExtensionState) -> bool {
         false
     }
 }
 
 /// Static description of an extension source's selectable content.
+///
+/// Each list is limited to 255 entries by the standard wire protocol.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct ExtensionDescriptor {
     pub effects: &'static [&'static str],
diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index 39fd8aa96..81a512a05 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -13,8 +13,9 @@ use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
 use rmk_types::action::LightAction;
 
 use super::Rgb8;
-use super::compositor::{ExtensionDescriptor, ExtensionState, 
-    Compositor, Contribution, LightingSource, LogicalFrame, RenderError, RenderInput as SourceRenderInput,
+use super::compositor::{
+    Compositor, Contribution, ExtensionDescriptor, ExtensionState, LightingSource, LogicalFrame, RenderError,
+    RenderInput as SourceRenderInput,
 };
 use super::context::{LightingContext, LightingContextProvider};
 use super::effect::{BuiltinEffect, LightingEffect};
@@ -1079,11 +1080,9 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
         })
     }
 
-    fn apply_replica(
-        &mut self,
-        local_now_ms: u64,
-        replica: StandardReplicaState<OVERLAY_CAP, SCENE_CAP>,
-    ) -> Result<(), StandardError> {
+    fn replica_overlay(
+        replica: &StandardReplicaState<OVERLAY_CAP, SCENE_CAP>,
+    ) -> Result<TtlOverlay<BuiltinEffect, OVERLAY_CAP>, StandardError> {
         let mut updates = [OverlayUpdate {
             slot: LedSlot(0),
             effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
@@ -1101,14 +1100,23 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
                 return Err(StandardError::DeadlineOverflow);
             }
         }
-        self.overlay
-            .replace(replica.sample_time_ms, &updates[..replica.overlay.as_slice().len()])?;
+        let mut overlay = TtlOverlay::new();
+        overlay.replace(replica.sample_time_ms, &updates[..replica.overlay.as_slice().len()])?;
+        Ok(overlay)
+    }
+
+    fn apply_replica(
+        &mut self,
+        local_now_ms: u64,
+        replica: StandardReplicaState<OVERLAY_CAP, SCENE_CAP>,
+        overlay: TtlOverlay<BuiltinEffect, OVERLAY_CAP>,
+    ) {
+        self.overlay = overlay;
         self.set_mutable_state(replica.mutable);
         self.output_mode = replica.output_mode;
         self.scenes = replica.scenes;
         self.revision = replica.revision;
         self.animation_clock.anchor(local_now_ms, replica.sample_time_ms);
-        Ok(())
     }
 
     fn expires_at(now_ms: u64, ttl_ms: Option<NonZeroU32>) -> Result<Option<u64>, StandardError> {
@@ -1526,12 +1534,13 @@ where
             }
             StandardCommand::ApplyReplica(slot) => {
                 let replica = slot.take()?;
-                let extension = replica.extension;
-                self.apply_replica(now_ms, replica)?;
-                if let Some(extension) = extension {
-                    // A replica without a matching extension declines harmlessly.
-                    let _ = self.extension.apply_extension_state(extension);
+                let overlay = Self::replica_overlay(&replica)?;
+                match (replica.extension, self.extension.extension_state()) {
+                    (None, None) => {}
+                    (Some(extension), Some(_)) if self.extension.apply_extension_state(extension) => {}
+                    _ => return Err(StandardError::ExtensionUnsupported),
                 }
+                self.apply_replica(now_ms, replica, overlay);
                 (Invalidation::Render, false)
             }
             StandardCommand::SetSceneCellIfRevision {
@@ -1730,6 +1739,38 @@ mod tests {
 
     type Engine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2>;
 
+    #[derive(Copy, Clone)]
+    struct ReplicaExtension {
+        state: ExtensionState,
+        accept: bool,
+    }
+
+    impl<Context> LightingSource<Rgb8, Context> for ReplicaExtension {
+        fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
+            0
+        }
+
+        fn slot(&self, _: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
+            unreachable!("replica test extension has no targets")
+        }
+
+        fn contribution(&mut self, _: usize, _: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
+            unreachable!("replica test extension has no samples")
+        }
+
+        fn extension_state(&self) -> Option<ExtensionState> {
+            Some(self.state)
+        }
+
+        fn apply_extension_state(&mut self, state: ExtensionState) -> bool {
+            if !self.accept {
+                return false;
+            }
+            self.state = state;
+            true
+        }
+    }
+
     static LAYER_CELLS: [SceneCell<BuiltinEffect>; 1] = [SceneCell {
         slot: LedSlot(0),
         effect: BuiltinEffect::Solid { color: RED },
@@ -1758,6 +1799,29 @@ mod tests {
         )
     }
 
+    fn replica_engine(accept: bool) -> StandardLightingEngine<'static, ReplicaExtension, EmptySource, 2, 2> {
+        StandardLightingEngine::new(
+            BackgroundState {
+                value: 10,
+                ..BackgroundState::default()
+            },
+            LayerScenes {
+                scenes: &LAYERS,
+                policy: LayerPolicy::ActiveStack,
+            },
+            ReplicaExtension {
+                state: ExtensionState {
+                    effect: 0,
+                    palette: 0,
+                    value: 10,
+                    speed: 20,
+                },
+                accept,
+            },
+            EmptySource,
+        )
+    }
+
     fn context(layer: u8) -> LightingContext {
         LightingContext {
             layers: LayerState::new(layer, 0, 1 | (1 << layer)),
@@ -1889,6 +1953,98 @@ mod tests {
         assert_eq!(slot.take(), Err(ReplicaSlotError::Empty));
     }
 
+    #[test]
+    fn replica_application_is_atomic_across_common_and_extension_state() {
+        let next_extension = ExtensionState {
+            effect: 1,
+            palette: 2,
+            value: 30,
+            speed: 40,
+        };
+        let snapshot = StandardReplicaState {
+            revision: 9,
+            mutable: StandardMutableState {
+                output_enabled: false,
+                output_brightness: 42,
+                background: BackgroundState {
+                    value: 99,
+                    ..BackgroundState::default()
+                },
+            },
+            output_mode: OutputMode::AlwaysOff,
+            overlay: OverlayBatch::new(),
+            scenes: SceneTable::new(),
+            context: context(0),
+            sample_time_ms: 50,
+            extension: Some(next_extension),
+        };
+
+        let mut declining = replica_engine(false);
+        let before = declining.state();
+        let before_extension = declining.extension().state;
+        static DECLINING_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+        DECLINING_SLOT.put(snapshot).unwrap();
+        assert_eq!(
+            declining.handle_command(100, StandardCommand::ApplyReplica(&DECLINING_SLOT), &context(0),),
+            Err(StandardError::ExtensionUnsupported)
+        );
+        assert_eq!(declining.state(), before);
+        assert_eq!(declining.extension().state, before_extension);
+
+        let mut accepting = replica_engine(true);
+        static ACCEPTING_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+        ACCEPTING_SLOT.put(snapshot).unwrap();
+        accepting
+            .handle_command(100, StandardCommand::ApplyReplica(&ACCEPTING_SLOT), &context(0))
+            .unwrap();
+        assert_eq!(accepting.state().revision, 9);
+        assert_eq!(accepting.state().output_brightness, 42);
+        assert_eq!(accepting.extension().state, next_extension);
+    }
+
+    #[test]
+    fn invalid_replica_common_state_does_not_mutate_extension() {
+        let mut overlay = OverlayBatch::new();
+        for _ in 0..2 {
+            overlay
+                .push(OverlayCell {
+                    slot: LedSlot(0),
+                    effect: BuiltinEffect::Solid { color: RED },
+                    ttl_ms: None,
+                })
+                .unwrap();
+        }
+        let snapshot = StandardReplicaState {
+            revision: 9,
+            mutable: StandardMutableState {
+                output_enabled: true,
+                output_brightness: 42,
+                background: BackgroundState::default(),
+            },
+            output_mode: OutputMode::AlwaysOn,
+            overlay,
+            scenes: SceneTable::new(),
+            context: context(0),
+            sample_time_ms: 50,
+            extension: Some(ExtensionState {
+                effect: 1,
+                palette: 2,
+                value: 30,
+                speed: 40,
+            }),
+        };
+        let mut engine = replica_engine(true);
+        let before = engine.extension().state;
+        static INVALID_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+        INVALID_SLOT.put(snapshot).unwrap();
+        assert_eq!(
+            engine.handle_command(100, StandardCommand::ApplyReplica(&INVALID_SLOT), &context(0),),
+            Err(StandardError::Overlay(OverlayError::DuplicateSlot { slot: LedSlot(0) }))
+        );
+        assert_eq!(engine.extension().state, before);
+        assert_eq!(engine.state().revision, 0);
+    }
+
     #[test]
     fn output_mode_cycles_and_wake_layer_temporarily_overrides_policy() {
         let mut engine = engine().with_controls(LightingControls {

From f5c3a186a044207c416d5082eda6201230b0853d Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 22 Jul 2026 04:49:31 -0700
Subject: [PATCH 31/78] feat(lighting): add runtime conditional scenes

---
 .../main/docs/development/rynk_protocol.md    | 181 +++---
 rmk-types/src/protocol/rynk/command.rs        |  36 +-
 .../src/protocol/rynk/payload/lighting.rs     | 118 ++++
 .../rynk/snapshots/lighting_wire_frames.snap  |  16 +-
 rmk-types/src/protocol/rynk/tests.rs          | 155 ++++-
 rmk/CHANGELOG.md                              |   1 +
 rmk/src/host/context.rs                       |   4 +-
 rmk/src/host/mod.rs                           |   3 +-
 rmk/src/host/rynk/handlers/lighting.rs        | 328 +++++++++-
 rmk/src/host/rynk/lighting.rs                 | 303 ++++++++-
 rmk/src/host/rynk/mod.rs                      |  35 +-
 rmk/src/lighting/mod.rs                       |   8 +-
 rmk/src/lighting/source.rs                    |   2 +-
 rmk/src/lighting/standard.rs                  | 579 +++++++++++++++++-
 rmk/src/storage/mod.rs                        |  88 ++-
 rynk/rynk-wasm/src/client.rs                  |  12 +
 rynk/src/api.rs                               |  78 ++-
 17 files changed, 1820 insertions(+), 127 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 79e2ccab0..df65c03d1 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -213,93 +213,100 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x0918` | `CommitLightingSceneReplace`   | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`               | `lighting` |                                                                                                                                |
 | `0x0919` | `AbortLightingSceneReplace`    | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                | `lighting` |                                                                                                                                |
 | `0x091A` | `SetLightingLayerPolicy`       | `SetLightingLayerPolicyRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| CMD      | Name                                | Request                               | Response                               | Feature          | Notes                                                                                                                          |
-| -------- | ----------------------------------- | ------------------------------------- | -------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `0x0001` | `GetVersion`                        | `()`                                  | `ProtocolVersion`                      |                  |                                                                                                                                |
-| `0x0002` | `GetCapabilities`                   | `()`                                  | `DeviceCapabilities`                   |                  |                                                                                                                                |
-| `0x0003` | `Reboot`                            | `()`                                  | `()`                                   |                  |                                                                                                                                |
-| `0x0004` | `BootloaderJump`                    | `()`                                  | `()`                                   |                  |                                                                                                                                |
-| `0x0005` | `StorageReset`                      | `StorageResetMode`                    | `()`                                   |                  |                                                                                                                                |
-| `0x0006` | `GetLockStatus`                     | `()`                                  | `LockStatus`                           |                  | Pure read of the current lock state — no side effects.                                                                         |
-| `0x0007` | `UnlockPoll`                        | `()`                                  | `LockStatus`                           |                  | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                         |
-| `0x0008` | `Lock`                              | `()`                                  | `()`                                   |                  | Relock immediately.                                                                                                            |
-| `0x0009` | `GetLayout`                         | `u32`                                 | `LayoutChunk`                          |                  | Get layout blob chunk. `u32` is the byte offset.                                                                               |
-| `0x000A` | `GetDeviceInfo`                     | `()`                                  | `DeviceInfo`                           |                  | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                       |
-| `0x000B` | `GetBuildInfo`                      | `()`                                  | `BuildInfo`                            |                  | Application-defined diagnostic build label; never used for compatibility.                                                      |
-| `0x000C` | `PeripheralBootloaderJump`          | `u8`                                  | `()`                                   |                  | Ask the application to route a bootloader jump to one split peripheral.                                                        |
-| `0x0101` | `GetKeyAction`                      | `KeyPosition`                         | `KeyAction`                            |                  |                                                                                                                                |
-| `0x0102` | `SetKeyAction`                      | `SetKeyRequest`                       | `()`                                   |                  |                                                                                                                                |
-| `0x0103` | `GetDefaultLayer`                   | `()`                                  | `u8`                                   |                  |                                                                                                                                |
-| `0x0104` | `SetDefaultLayer`                   | `u8`                                  | `()`                                   |                  |                                                                                                                                |
-| `0x0105` | `GetEncoderAction`                  | `GetEncoderRequest`                   | `EncoderAction`                        |                  |                                                                                                                                |
-| `0x0106` | `SetEncoderAction`                  | `SetEncoderRequest`                   | `()`                                   |                  |                                                                                                                                |
-| `0x0107` | `GetKeymapBulk`                     | `GetKeymapBulkRequest`                | `GetKeymapBulkResponse`                |                  |                                                                                                                                |
-| `0x0108` | `SetKeymapBulk`                     | `SetKeymapBulkRequest`                | `()`                                   |                  |                                                                                                                                |
-| `0x0201` | `GetMacro`                          | `GetMacroRequest`                     | `MacroData`                            |                  |                                                                                                                                |
-| `0x0202` | `SetMacro`                          | `SetMacroRequest`                     | `()`                                   |                  |                                                                                                                                |
-| `0x0301` | `GetCombo`                          | `u8`                                  | `Combo`                                |                  |                                                                                                                                |
-| `0x0302` | `SetCombo`                          | `SetComboRequest`                     | `()`                                   |                  |                                                                                                                                |
-| `0x0303` | `GetComboBulk`                      | `GetComboBulkRequest`                 | `GetComboBulkResponse`                 |                  |                                                                                                                                |
-| `0x0304` | `SetComboBulk`                      | `SetComboBulkRequest`                 | `()`                                   |                  |                                                                                                                                |
-| `0x0401` | `GetMorse`                          | `u8`                                  | `Morse`                                |                  |                                                                                                                                |
-| `0x0402` | `SetMorse`                          | `SetMorseRequest`                     | `()`                                   |                  |                                                                                                                                |
-| `0x0403` | `GetMorseBulk`                      | `GetMorseBulkRequest`                 | `GetMorseBulkResponse`                 |                  |                                                                                                                                |
-| `0x0404` | `SetMorseBulk`                      | `SetMorseBulkRequest`                 | `()`                                   |                  |                                                                                                                                |
-| `0x0501` | `GetFork`                           | `u8`                                  | `Fork`                                 |                  |                                                                                                                                |
-| `0x0502` | `SetFork`                           | `SetForkRequest`                      | `()`                                   |                  |                                                                                                                                |
-| `0x0601` | `GetBehaviorConfig`                 | `()`                                  | `BehaviorConfig`                       |                  |                                                                                                                                |
-| `0x0602` | `SetBehaviorConfig`                 | `BehaviorConfig`                      | `()`                                   |                  |                                                                                                                                |
-| `0x0701` | `GetConnectionType`                 | `()`                                  | `ConnectionType`                       |                  |                                                                                                                                |
-| `0x0702` | `GetConnectionStatus`               | `()`                                  | `ConnectionStatus`                     |                  | Full `ConnectionStatus` snapshot.                                                                                              |
-| `0x0703` | `GetBleStatus`                      | `()`                                  | `BleStatus`                            | `_ble`           |                                                                                                                                |
-| `0x0704` | `SwitchBleProfile`                  | `u8`                                  | `()`                                   | `_ble`           |                                                                                                                                |
-| `0x0705` | `ClearBleProfile`                   | `u8`                                  | `()`                                   | `_ble`           |                                                                                                                                |
-| `0x0706` | `GetSplitCentralLatency`            | `()`                                  | `SplitCentralLatencyState`             | `_ble` + `split` | Read the volatile active-mode policy, current USB-power selection, and effective value.                                        |
-| `0x0707` | `SetSplitCentralLatency`            | `SplitCentralLatencyPolicy`           | `SplitCentralLatencyState`             | `_ble` + `split` | Replace the volatile policy. Each connection-event count must be `0..=499`.                                                    |
-| `0x0801` | `GetCurrentLayer`                   | `()`                                  | `u8`                                   |                  |                                                                                                                                |
-| `0x0802` | `GetMatrixState`                    | `()`                                  | `MatrixState`                          |                  |                                                                                                                                |
-| `0x0803` | `GetBatteryStatus`                  | `()`                                  | `BatteryStatus`                        | `_ble`           |                                                                                                                                |
-| `0x0804` | `GetPeripheralStatus`               | `u8`                                  | `PeripheralStatus`                     | `split`          |                                                                                                                                |
-| `0x0805` | `GetWpm`                            | `()`                                  | `u16`                                  |                  | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                       |
-| `0x0806` | `GetSleepState`                     | `()`                                  | `bool`                                 |                  | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                               |
-| `0x0807` | `GetLedIndicator`                   | `()`                                  | `LedIndicator`                         |                  | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                   |
-| `0x0808` | `GetLayerState`                     | `()`                                  | `LayerState`                           |                  | Default layer and complete active-layer bitmap.                                                                                |
-| `0x0809` | `GetModifierState`                  | `()`                                  | `ModifierCombination`                  |                  | Final resolved modifier bitmap used by the HID keyboard report.                                                                |
-| `0x0901` | `GetLightingCapabilities`           | `()`                                  | `LightingCapabilitiesResult`           | `lighting`       |                                                                                                                                |
-| `0x0902` | `GetLightingState`                  | `()`                                  | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
-| `0x0903` | `SetLightingState`                  | `SetLightingStateRequest`             | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
-| `0x0904` | `GetLightingPhysicalKeys`           | `LightingPageRequest`                 | `LightingPhysicalKeysPageResult`       | `lighting`       |                                                                                                                                |
-| `0x0905` | `GetLightingLeds`                   | `LightingPageRequest`                 | `LightingLedsPageResult`               | `lighting`       |                                                                                                                                |
-| `0x0906` | `GetLightingZones`                  | `LightingPageRequest`                 | `LightingZonesPageResult`              | `lighting`       |                                                                                                                                |
-| `0x0907` | `GetLightingZoneMemberships`        | `LightingPageRequest`                 | `LightingZoneMembershipsPageResult`    | `lighting`       |                                                                                                                                |
-| `0x0908` | `GetLightingOutputs`                | `LightingPageRequest`                 | `LightingOutputsPageResult`            | `lighting`       |                                                                                                                                |
-| `0x0909` | `GetLightingRoutes`                 | `LightingPageRequest`                 | `LightingRoutesPageResult`             | `lighting`       |                                                                                                                                |
-| `0x090A` | `SetLightingOverlay`                | `SetLightingOverlayRequest`           | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
-| `0x090B` | `UnsetLightingOverlay`              | `UnsetLightingOverlayRequest`         | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
-| `0x090C` | `ClearLightingOverlay`              | `ClearLightingOverlayRequest`         | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
-| `0x090D` | `BeginLightingOverlayReplace`       | `BeginLightingOverlayReplaceRequest`  | `LightingOverlayTransactionResult`     | `lighting`       |                                                                                                                                |
-| `0x090E` | `PutLightingOverlayChunk`           | `PutLightingOverlayChunkRequest`      | `LightingUnitResult`                   | `lighting`       |                                                                                                                                |
-| `0x090F` | `CommitLightingOverlayReplace`      | `CommitLightingOverlayReplaceRequest` | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
-| `0x0910` | `AbortLightingOverlayReplace`       | `AbortLightingOverlayReplaceRequest`  | `LightingUnitResult`                   | `lighting`       |                                                                                                                                |
-| `0x0911` | `GetLightingKeys`                   | `LightingPageRequest`                 | `LightingKeysPageResult`               | `lighting`       | Logical matrix keys are distinct from optional physical geometry.                                                              |
-| `0x0912` | `GetLightingSceneStatus`            | `()`                                  | `LightingSceneStatusResult`            | `lighting`       | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts. |
-| `0x0913` | `GetLightingScenes`                 | `LightingScenePageRequest`            | `LightingScenesPageResult`             | `lighting`       | Scene pages are pinned to `LightingState.revision` for consistency.                                                            |
-| `0x0914` | `SetLightingSceneCell`              | `SetLightingSceneCellRequest`         | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
-| `0x0915` | `UnsetLightingSceneCell`            | `UnsetLightingSceneCellRequest`       | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
-| `0x0916` | `BeginLightingSceneReplace`         | `BeginLightingSceneReplaceRequest`    | `LightingSceneTransactionResult`       | `lighting`       |                                                                                                                                |
-| `0x0917` | `PutLightingSceneChunk`             | `PutLightingSceneChunkRequest`        | `LightingUnitResult`                   | `lighting`       |                                                                                                                                |
-| `0x0918` | `CommitLightingSceneReplace`        | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
-| `0x0919` | `AbortLightingSceneReplace`         | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                   | `lighting`       |                                                                                                                                |
-| `0x091A` | `SetLightingLayerPolicy`            | `SetLightingLayerPolicyRequest`       | `LightingStateResult`                  | `lighting`       |                                                                                                                                |
-| `0x091B` | `GetLightingOverlay`                | `LightingOverlayPageRequest`          | `LightingOverlayPageResult`            | `lighting`       | Overlay pages are pinned to `LightingState.revision` for consistency.                                                          |
-| `0x091C` | `GetLightingCompiledSceneStatus`    | `()`                                  | `LightingCompiledSceneStatusResult`    | `lighting`       | Discover the immutable board-compiled layer-scene source.                                                                      |
-| `0x091D` | `GetLightingCompiledScenes`         | `LightingPageRequest`                 | `LightingCompiledScenesPageResult`     | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                             |
-| `0x091E` | `GetLightingConditionalSceneStatus` | `()`                                  | `LightingConditionalSceneStatusResult` | `lighting`       | Discover immutable conditional lighting compiled from board config.                                                            |
-| `0x091F` | `GetLightingConditionalScenes`      | `LightingPageRequest`                 | `LightingConditionalScenesPageResult`  | `lighting`       | Conditional-scene pages are pinned to the firmware topology revision.                                                          |
-| `0x0920` | `GetLightingOutputMode`             | `()`                                  | `LightingOutputModeStateResult`        | `lighting`       | Read the configured three-state output policy and its live state.                                                              |
-| `0x0921` | `GetLightingExtension`              | `()`                                  | `LightingExtensionResult`              | `lighting`       | Discover the animated extension band: name-list sizes and selection.                                                           |
-| `0x0922` | `GetLightingExtensionNames`         | `LightingExtensionNamesRequest`       | `LightingExtensionNamesPageResult`     | `lighting`       | Extension names are static per firmware build; page until `total`.                                                             |
-| `0x0923` | `SetLightingExtensionState`         | `SetLightingExtensionStateRequest`    | `LightingStateResult`                  | `lighting`       | Replace the extension selection when the state revision matches.                                                               |
+| CMD      | Name                                           | Request                                               | Response                                           | Feature          | Notes                                                                                                                          |
+| -------- | ---------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `0x0001` | `GetVersion`                                   | `()`                                                  | `ProtocolVersion`                                  |                  |                                                                                                                                |
+| `0x0002` | `GetCapabilities`                              | `()`                                                  | `DeviceCapabilities`                               |                  |                                                                                                                                |
+| `0x0003` | `Reboot`                                       | `()`                                                  | `()`                                               |                  |                                                                                                                                |
+| `0x0004` | `BootloaderJump`                               | `()`                                                  | `()`                                               |                  |                                                                                                                                |
+| `0x0005` | `StorageReset`                                 | `StorageResetMode`                                    | `()`                                               |                  |                                                                                                                                |
+| `0x0006` | `GetLockStatus`                                | `()`                                                  | `LockStatus`                                       |                  | Pure read of the current lock state — no side effects.                                                                         |
+| `0x0007` | `UnlockPoll`                                   | `()`                                                  | `LockStatus`                                       |                  | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                         |
+| `0x0008` | `Lock`                                         | `()`                                                  | `()`                                               |                  | Relock immediately.                                                                                                            |
+| `0x0009` | `GetLayout`                                    | `u32`                                                 | `LayoutChunk`                                      |                  | Get layout blob chunk. `u32` is the byte offset.                                                                               |
+| `0x000A` | `GetDeviceInfo`                                | `()`                                                  | `DeviceInfo`                                       |                  | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                       |
+| `0x000B` | `GetBuildInfo`                                 | `()`                                                  | `BuildInfo`                                        |                  | Application-defined diagnostic build label; never used for compatibility.                                                      |
+| `0x000C` | `PeripheralBootloaderJump`                     | `u8`                                                  | `()`                                               |                  | Ask the application to route a bootloader jump to one split peripheral.                                                        |
+| `0x0101` | `GetKeyAction`                                 | `KeyPosition`                                         | `KeyAction`                                        |                  |                                                                                                                                |
+| `0x0102` | `SetKeyAction`                                 | `SetKeyRequest`                                       | `()`                                               |                  |                                                                                                                                |
+| `0x0103` | `GetDefaultLayer`                              | `()`                                                  | `u8`                                               |                  |                                                                                                                                |
+| `0x0104` | `SetDefaultLayer`                              | `u8`                                                  | `()`                                               |                  |                                                                                                                                |
+| `0x0105` | `GetEncoderAction`                             | `GetEncoderRequest`                                   | `EncoderAction`                                    |                  |                                                                                                                                |
+| `0x0106` | `SetEncoderAction`                             | `SetEncoderRequest`                                   | `()`                                               |                  |                                                                                                                                |
+| `0x0107` | `GetKeymapBulk`                                | `GetKeymapBulkRequest`                                | `GetKeymapBulkResponse`                            |                  |                                                                                                                                |
+| `0x0108` | `SetKeymapBulk`                                | `SetKeymapBulkRequest`                                | `()`                                               |                  |                                                                                                                                |
+| `0x0201` | `GetMacro`                                     | `GetMacroRequest`                                     | `MacroData`                                        |                  |                                                                                                                                |
+| `0x0202` | `SetMacro`                                     | `SetMacroRequest`                                     | `()`                                               |                  |                                                                                                                                |
+| `0x0301` | `GetCombo`                                     | `u8`                                                  | `Combo`                                            |                  |                                                                                                                                |
+| `0x0302` | `SetCombo`                                     | `SetComboRequest`                                     | `()`                                               |                  |                                                                                                                                |
+| `0x0303` | `GetComboBulk`                                 | `GetComboBulkRequest`                                 | `GetComboBulkResponse`                             |                  |                                                                                                                                |
+| `0x0304` | `SetComboBulk`                                 | `SetComboBulkRequest`                                 | `()`                                               |                  |                                                                                                                                |
+| `0x0401` | `GetMorse`                                     | `u8`                                                  | `Morse`                                            |                  |                                                                                                                                |
+| `0x0402` | `SetMorse`                                     | `SetMorseRequest`                                     | `()`                                               |                  |                                                                                                                                |
+| `0x0403` | `GetMorseBulk`                                 | `GetMorseBulkRequest`                                 | `GetMorseBulkResponse`                             |                  |                                                                                                                                |
+| `0x0404` | `SetMorseBulk`                                 | `SetMorseBulkRequest`                                 | `()`                                               |                  |                                                                                                                                |
+| `0x0501` | `GetFork`                                      | `u8`                                                  | `Fork`                                             |                  |                                                                                                                                |
+| `0x0502` | `SetFork`                                      | `SetForkRequest`                                      | `()`                                               |                  |                                                                                                                                |
+| `0x0601` | `GetBehaviorConfig`                            | `()`                                                  | `BehaviorConfig`                                   |                  |                                                                                                                                |
+| `0x0602` | `SetBehaviorConfig`                            | `BehaviorConfig`                                      | `()`                                               |                  |                                                                                                                                |
+| `0x0701` | `GetConnectionType`                            | `()`                                                  | `ConnectionType`                                   |                  |                                                                                                                                |
+| `0x0702` | `GetConnectionStatus`                          | `()`                                                  | `ConnectionStatus`                                 |                  | Full `ConnectionStatus` snapshot.                                                                                              |
+| `0x0703` | `GetBleStatus`                                 | `()`                                                  | `BleStatus`                                        | `_ble`           |                                                                                                                                |
+| `0x0704` | `SwitchBleProfile`                             | `u8`                                                  | `()`                                               | `_ble`           |                                                                                                                                |
+| `0x0705` | `ClearBleProfile`                              | `u8`                                                  | `()`                                               | `_ble`           |                                                                                                                                |
+| `0x0706` | `GetSplitCentralLatency`                       | `()`                                                  | `SplitCentralLatencyState`                         | `_ble` + `split` | Read the volatile active-mode policy, current USB-power selection, and effective value.                                        |
+| `0x0707` | `SetSplitCentralLatency`                       | `SplitCentralLatencyPolicy`                           | `SplitCentralLatencyState`                         | `_ble` + `split` | Replace the volatile policy. Each connection-event count must be `0..=499`.                                                    |
+| `0x0801` | `GetCurrentLayer`                              | `()`                                                  | `u8`                                               |                  |                                                                                                                                |
+| `0x0802` | `GetMatrixState`                               | `()`                                                  | `MatrixState`                                      |                  |                                                                                                                                |
+| `0x0803` | `GetBatteryStatus`                             | `()`                                                  | `BatteryStatus`                                    | `_ble`           |                                                                                                                                |
+| `0x0804` | `GetPeripheralStatus`                          | `u8`                                                  | `PeripheralStatus`                                 | `split`          |                                                                                                                                |
+| `0x0805` | `GetWpm`                                       | `()`                                                  | `u16`                                              |                  | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                       |
+| `0x0806` | `GetSleepState`                                | `()`                                                  | `bool`                                             |                  | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                               |
+| `0x0807` | `GetLedIndicator`                              | `()`                                                  | `LedIndicator`                                     |                  | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                   |
+| `0x0808` | `GetLayerState`                                | `()`                                                  | `LayerState`                                       |                  | Default layer and complete active-layer bitmap.                                                                                |
+| `0x0809` | `GetModifierState`                             | `()`                                                  | `ModifierCombination`                              |                  | Final resolved modifier bitmap used by the HID keyboard report.                                                                |
+| `0x0901` | `GetLightingCapabilities`                      | `()`                                                  | `LightingCapabilitiesResult`                       | `lighting`       |                                                                                                                                |
+| `0x0902` | `GetLightingState`                             | `()`                                                  | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
+| `0x0903` | `SetLightingState`                             | `SetLightingStateRequest`                             | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
+| `0x0904` | `GetLightingPhysicalKeys`                      | `LightingPageRequest`                                 | `LightingPhysicalKeysPageResult`                   | `lighting`       |                                                                                                                                |
+| `0x0905` | `GetLightingLeds`                              | `LightingPageRequest`                                 | `LightingLedsPageResult`                           | `lighting`       |                                                                                                                                |
+| `0x0906` | `GetLightingZones`                             | `LightingPageRequest`                                 | `LightingZonesPageResult`                          | `lighting`       |                                                                                                                                |
+| `0x0907` | `GetLightingZoneMemberships`                   | `LightingPageRequest`                                 | `LightingZoneMembershipsPageResult`                | `lighting`       |                                                                                                                                |
+| `0x0908` | `GetLightingOutputs`                           | `LightingPageRequest`                                 | `LightingOutputsPageResult`                        | `lighting`       |                                                                                                                                |
+| `0x0909` | `GetLightingRoutes`                            | `LightingPageRequest`                                 | `LightingRoutesPageResult`                         | `lighting`       |                                                                                                                                |
+| `0x090A` | `SetLightingOverlay`                           | `SetLightingOverlayRequest`                           | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
+| `0x090B` | `UnsetLightingOverlay`                         | `UnsetLightingOverlayRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
+| `0x090C` | `ClearLightingOverlay`                         | `ClearLightingOverlayRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
+| `0x090D` | `BeginLightingOverlayReplace`                  | `BeginLightingOverlayReplaceRequest`                  | `LightingOverlayTransactionResult`                 | `lighting`       |                                                                                                                                |
+| `0x090E` | `PutLightingOverlayChunk`                      | `PutLightingOverlayChunkRequest`                      | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
+| `0x090F` | `CommitLightingOverlayReplace`                 | `CommitLightingOverlayReplaceRequest`                 | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
+| `0x0910` | `AbortLightingOverlayReplace`                  | `AbortLightingOverlayReplaceRequest`                  | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
+| `0x0911` | `GetLightingKeys`                              | `LightingPageRequest`                                 | `LightingKeysPageResult`                           | `lighting`       | Logical matrix keys are distinct from optional physical geometry.                                                              |
+| `0x0912` | `GetLightingSceneStatus`                       | `()`                                                  | `LightingSceneStatusResult`                        | `lighting`       | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts. |
+| `0x0913` | `GetLightingScenes`                            | `LightingScenePageRequest`                            | `LightingScenesPageResult`                         | `lighting`       | Scene pages are pinned to `LightingState.revision` for consistency.                                                            |
+| `0x0914` | `SetLightingSceneCell`                         | `SetLightingSceneCellRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
+| `0x0915` | `UnsetLightingSceneCell`                       | `UnsetLightingSceneCellRequest`                       | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
+| `0x0916` | `BeginLightingSceneReplace`                    | `BeginLightingSceneReplaceRequest`                    | `LightingSceneTransactionResult`                   | `lighting`       |                                                                                                                                |
+| `0x0917` | `PutLightingSceneChunk`                        | `PutLightingSceneChunkRequest`                        | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
+| `0x0918` | `CommitLightingSceneReplace`                   | `CommitLightingSceneReplaceRequest`                   | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
+| `0x0919` | `AbortLightingSceneReplace`                    | `AbortLightingSceneReplaceRequest`                    | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
+| `0x091A` | `SetLightingLayerPolicy`                       | `SetLightingLayerPolicyRequest`                       | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
+| `0x091B` | `GetLightingOverlay`                           | `LightingOverlayPageRequest`                          | `LightingOverlayPageResult`                        | `lighting`       | Overlay pages are pinned to `LightingState.revision` for consistency.                                                          |
+| `0x091C` | `GetLightingCompiledSceneStatus`               | `()`                                                  | `LightingCompiledSceneStatusResult`                | `lighting`       | Discover the immutable board-compiled layer-scene source.                                                                      |
+| `0x091D` | `GetLightingCompiledScenes`                    | `LightingPageRequest`                                 | `LightingCompiledScenesPageResult`                 | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                             |
+| `0x091E` | `GetLightingConditionalSceneStatus`            | `()`                                                  | `LightingConditionalSceneStatusResult`             | `lighting`       | Discover immutable conditional lighting compiled from board config.                                                            |
+| `0x091F` | `GetLightingConditionalScenes`                 | `LightingPageRequest`                                 | `LightingConditionalScenesPageResult`              | `lighting`       | Conditional-scene pages are pinned to the firmware topology revision.                                                          |
+| `0x0920` | `GetLightingOutputMode`                        | `()`                                                  | `LightingOutputModeStateResult`                    | `lighting`       | Read the configured three-state output policy and its live state.                                                              |
+| `0x0921` | `GetLightingExtension`                         | `()`                                                  | `LightingExtensionResult`                          | `lighting`       | Discover the animated extension band: name-list sizes and selection.                                                           |
+| `0x0922` | `GetLightingExtensionNames`                    | `LightingExtensionNamesRequest`                       | `LightingExtensionNamesPageResult`                 | `lighting`       | Extension names are static per firmware build; page until `total`.                                                             |
+| `0x0923` | `SetLightingExtensionState`                    | `SetLightingExtensionStateRequest`                    | `LightingStateResult`                              | `lighting`       | Replace the extension selection when the state revision matches.                                                               |
+| `0x0924` | `SetLightingOutputMode`                        | `SetLightingOutputModeRequest`                        | `LightingOutputModeStateResult`                    | `lighting`       | Set the three-state output policy with optimistic concurrency.                                                                 |
+| `0x0925` | `GetLightingRuntimeConditionalSceneStatus`     | `()`                                                  | `LightingRuntimeConditionalSceneStatusResult`      | `lighting`       | Discover the mutable ordered conditional-scene table.                                                                          |
+| `0x0926` | `GetLightingRuntimeConditionalScenes`          | `LightingRuntimeConditionalScenePageRequest`          | `LightingRuntimeConditionalScenesPageResult`       | `lighting`       | Runtime conditional pages are pinned to `LightingState.revision`.                                                              |
+| `0x0927` | `BeginLightingRuntimeConditionalSceneReplace`  | `BeginLightingRuntimeConditionalSceneReplaceRequest`  | `LightingRuntimeConditionalSceneTransactionResult` | `lighting`       |                                                                                                                                |
+| `0x0928` | `PutLightingRuntimeConditionalSceneChunk`      | `PutLightingRuntimeConditionalSceneChunkRequest`      | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
+| `0x0929` | `CommitLightingRuntimeConditionalSceneReplace` | `CommitLightingRuntimeConditionalSceneReplaceRequest` | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
+| `0x092A` | `AbortLightingRuntimeConditionalSceneReplace`  | `AbortLightingRuntimeConditionalSceneReplaceRequest`  | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 918fbc436..c2f7bb31c 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -35,18 +35,23 @@ use crate::morse::Morse;
 use crate::protocol::rynk::PeripheralStatus;
 #[cfg(feature = "lighting")]
 use crate::protocol::rynk::{
-    AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
-    BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest,
+    AbortLightingOverlayReplaceRequest, AbortLightingRuntimeConditionalSceneReplaceRequest,
+    AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
+    BeginLightingRuntimeConditionalSceneReplaceRequest, BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest,
+    CommitLightingOverlayReplaceRequest, CommitLightingRuntimeConditionalSceneReplaceRequest,
     CommitLightingSceneReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingCompiledSceneStatusResult,
     LightingCompiledScenesPageResult, LightingConditionalSceneStatusResult, LightingConditionalScenesPageResult,
     LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionResult, LightingKeysPageResult,
     LightingLedsPageResult, LightingOutputModeStateResult, LightingOutputsPageResult, LightingOverlayPageRequest,
     LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKeysPageResult,
-    LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatusResult, LightingSceneTransactionResult,
-    LightingScenesPageResult, LightingStateResult, LightingUnitResult, LightingZoneMembershipsPageResult,
-    LightingZonesPageResult, PutLightingOverlayChunkRequest, PutLightingSceneChunkRequest,
-    SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
-    SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
+    LightingRoutesPageResult, LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatusResult,
+    LightingRuntimeConditionalSceneTransactionResult, LightingRuntimeConditionalScenesPageResult,
+    LightingScenePageRequest, LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult,
+    LightingStateResult, LightingUnitResult, LightingZoneMembershipsPageResult, LightingZonesPageResult,
+    PutLightingOverlayChunkRequest, PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest,
+    SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest, SetLightingOutputModeRequest,
+    SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest,
+    UnsetLightingSceneCellRequest,
 };
 #[cfg(all(feature = "_ble", feature = "split"))]
 use crate::protocol::rynk::{SplitCentralLatencyPolicy, SplitCentralLatencyState};
@@ -455,6 +460,23 @@ endpoints! {
     /// Replace the extension selection when the state revision matches.
     #[cfg(feature = "lighting")]
     SetLightingExtensionState = 0x0923: SetLightingExtensionStateRequest => LightingStateResult;
+    /// Set the three-state output policy with optimistic concurrency.
+    #[cfg(feature = "lighting")]
+    SetLightingOutputMode = 0x0924: SetLightingOutputModeRequest => LightingOutputModeStateResult;
+    /// Discover the mutable ordered conditional-scene table.
+    #[cfg(feature = "lighting")]
+    GetLightingRuntimeConditionalSceneStatus = 0x0925: () => LightingRuntimeConditionalSceneStatusResult;
+    /// Runtime conditional pages are pinned to `LightingState.revision`.
+    #[cfg(feature = "lighting")]
+    GetLightingRuntimeConditionalScenes = 0x0926: LightingRuntimeConditionalScenePageRequest => LightingRuntimeConditionalScenesPageResult;
+    #[cfg(feature = "lighting")]
+    BeginLightingRuntimeConditionalSceneReplace = 0x0927: BeginLightingRuntimeConditionalSceneReplaceRequest => LightingRuntimeConditionalSceneTransactionResult;
+    #[cfg(feature = "lighting")]
+    PutLightingRuntimeConditionalSceneChunk = 0x0928: PutLightingRuntimeConditionalSceneChunkRequest => LightingUnitResult;
+    #[cfg(feature = "lighting")]
+    CommitLightingRuntimeConditionalSceneReplace = 0x0929: CommitLightingRuntimeConditionalSceneReplaceRequest => LightingStateResult;
+    #[cfg(feature = "lighting")]
+    AbortLightingRuntimeConditionalSceneReplace = 0x092A: AbortLightingRuntimeConditionalSceneReplaceRequest => LightingUnitResult;
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 46b8ee375..766ea64db 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -198,6 +198,8 @@ impl LightingFeatureFlags {
     pub const OUTPUT_MODE: u16 = 1 << 10;
     /// Host-selectable animated extension effects served by an effect pack.
     pub const EXTENSION_EFFECTS: u16 = 1 << 11;
+    /// Persistent, ordered conditional rules authored at runtime.
+    pub const RUNTIME_CONDITIONAL_SCENES: u16 = 1 << 12;
 
     pub const fn contains(self, bits: u16) -> bool {
         self.0 & bits == bits
@@ -628,6 +630,20 @@ wire_type! {
     }
 }
 
+impl LightingConditionalSceneCell {
+    pub fn validate(&self) -> LightingResult<()> {
+        if let Some(battery) = self.conditions.battery {
+            if battery.min_level.is_some_and(|level| level > 100)
+                || battery.max_level.is_some_and(|level| level > 100)
+                || matches!((battery.min_level, battery.max_level), (Some(min), Some(max)) if min > max)
+            {
+                return Err(LightingError::InvalidRequest);
+            }
+        }
+        self.effect.validate()
+    }
+}
+
 wire_type! {
     /// Key/layer controls that gate the configured lighting presentation.
     pub struct LightingControls {
@@ -760,6 +776,91 @@ pub struct LightingConditionalScenesPage {
     pub items: Vec<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>,
 }
 
+wire_type! {
+    /// Mutable ordered conditional-table status. Unlike the compiled source,
+    /// this table participates in the lighting state revision.
+    pub struct LightingRuntimeConditionalSceneStatus {
+        pub revision: u32,
+        pub capacity: u16,
+        pub cell_len: u16,
+        pub chunk_capacity: u8,
+    }
+}
+
+wire_type! {
+    pub struct LightingRuntimeConditionalScenePageRequest {
+        pub revision: u32,
+        pub offset: u16,
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LightingRuntimeConditionalScenesPage {
+    pub revision: u32,
+    pub total_count: u16,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingConditionalSceneCell[]"))]
+    pub items: Vec<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>,
+}
+
+impl MaxSize for LightingRuntimeConditionalScenesPage {
+    const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+        + u16::POSTCARD_MAX_SIZE
+        + crate::heapless_vec_max_size::<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>();
+}
+
+wire_type! {
+    pub struct SetLightingOutputModeRequest {
+        pub expected_revision: u32,
+        pub mode: LightingOutputMode,
+    }
+}
+
+wire_type! {
+    pub struct BeginLightingRuntimeConditionalSceneReplaceRequest {
+        pub expected_revision: u32,
+        pub cell_count: u16,
+    }
+}
+
+wire_type! {
+    pub struct LightingRuntimeConditionalSceneTransaction {
+        pub id: u32,
+        pub cell_count: u16,
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct PutLightingRuntimeConditionalSceneChunkRequest {
+    pub transaction_id: u32,
+    pub offset: u16,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingConditionalSceneCell[]"))]
+    pub cells: Vec<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>,
+}
+
+impl MaxSize for PutLightingRuntimeConditionalSceneChunkRequest {
+    const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+        + u16::POSTCARD_MAX_SIZE
+        + crate::heapless_vec_max_size::<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>();
+}
+
+wire_type! {
+    pub struct CommitLightingRuntimeConditionalSceneReplaceRequest {
+        pub transaction_id: u32,
+    }
+}
+
+wire_type! {
+    pub struct AbortLightingRuntimeConditionalSceneReplaceRequest {
+        pub transaction_id: u32,
+    }
+}
+
 impl MaxSize for LightingConditionalScenesPage {
     const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
         + u16::POSTCARD_MAX_SIZE
@@ -859,6 +960,7 @@ wire_type! {
         // from the new scene endpoints, so older hosts never decode them.
         UnknownLayer { layer: u8 },
         SceneFull { capacity: u16 },
+        ConditionalSceneFull { capacity: u16 },
     }
 }
 
@@ -885,6 +987,9 @@ pub type LightingOutputModeStateResult = LightingResult<LightingOutputModeState>
 pub type LightingExtensionResult = LightingResult<LightingExtension>;
 pub type LightingExtensionNamesPageResult = LightingResult<LightingExtensionNamesPage>;
 pub type LightingSceneTransactionResult = LightingResult<LightingSceneTransaction>;
+pub type LightingRuntimeConditionalSceneStatusResult = LightingResult<LightingRuntimeConditionalSceneStatus>;
+pub type LightingRuntimeConditionalScenesPageResult = LightingResult<LightingRuntimeConditionalScenesPage>;
+pub type LightingRuntimeConditionalSceneTransactionResult = LightingResult<LightingRuntimeConditionalSceneTransaction>;
 pub type LightingUnitResult = LightingResult<()>;
 
 wire_type! {
@@ -931,6 +1036,19 @@ const _: () = {
     assert_endpoint_fits!((), LightingExtensionResult);
     assert_endpoint_fits!(LightingExtensionNamesRequest, LightingExtensionNamesPageResult);
     assert_endpoint_fits!(SetLightingExtensionStateRequest, LightingStateResult);
+    assert_endpoint_fits!(SetLightingOutputModeRequest, LightingOutputModeStateResult);
+    assert_endpoint_fits!((), LightingRuntimeConditionalSceneStatusResult);
+    assert_endpoint_fits!(
+        LightingRuntimeConditionalScenePageRequest,
+        LightingRuntimeConditionalScenesPageResult
+    );
+    assert_endpoint_fits!(
+        BeginLightingRuntimeConditionalSceneReplaceRequest,
+        LightingRuntimeConditionalSceneTransactionResult
+    );
+    assert_endpoint_fits!(PutLightingRuntimeConditionalSceneChunkRequest, LightingUnitResult);
+    assert_endpoint_fits!(CommitLightingRuntimeConditionalSceneReplaceRequest, LightingStateResult);
+    assert_endpoint_fits!(AbortLightingRuntimeConditionalSceneReplaceRequest, LightingUnitResult);
     assert_endpoint_fits!(SetLightingSceneCellRequest, LightingStateResult);
     assert_endpoint_fits!(UnsetLightingSceneCellRequest, LightingStateResult);
     assert_endpoint_fits!(SetLightingLayerPolicyRequest, LightingStateResult);
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index 35af6dc03..b8d4ddc38 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -7,19 +7,25 @@
 
 AbortLightingOverlayReplace reply                      10 09 01 02 00 00 00
 AbortLightingOverlayReplace request                    10 09 01 01 00 0d
+AbortLightingRuntimeConditionalSceneReplace reply      2a 09 01 02 00 00 00
+AbortLightingRuntimeConditionalSceneReplace request    2a 09 01 01 00 1f
 AbortLightingSceneReplace reply                        19 09 01 02 00 00 00
 AbortLightingSceneReplace request                      19 09 01 01 00 15
 BeginLightingOverlayReplace reply                      0d 09 01 04 00 00 00 0d 01
 BeginLightingOverlayReplace request                    0d 09 01 02 00 0c 01
+BeginLightingRuntimeConditionalSceneReplace reply      27 09 01 04 00 00 00 1f 01
+BeginLightingRuntimeConditionalSceneReplace request    27 09 01 02 00 09 01
 BeginLightingSceneReplace reply                        16 09 01 04 00 00 00 15 01
 BeginLightingSceneReplace request                      16 09 01 02 00 0c 01
 ClearLightingOverlay reply                             0c 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 ClearLightingOverlay request                           0c 09 01 01 00 0b
 CommitLightingOverlayReplace reply                     0f 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 CommitLightingOverlayReplace request                   0f 09 01 01 00 0d
+CommitLightingRuntimeConditionalSceneReplace reply     29 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
+CommitLightingRuntimeConditionalSceneReplace request   29 09 01 01 00 1f
 CommitLightingSceneReplace reply                       18 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 CommitLightingSceneReplace request                     18 09 01 01 00 15
-GetLightingCapabilities reply                          01 09 01 10 00 00 00 01 02 03 04 05 06 07 08 09 08 08 bf 0b 07
+GetLightingCapabilities reply                          01 09 01 10 00 00 00 01 02 03 04 05 06 07 08 09 08 08 bf 2b 07
 GetLightingCapabilities request                        01 09 01 00 00
 GetLightingCompiledSceneStatus reply                   1c 09 01 06 00 00 00 01 01 00 08
 GetLightingCompiledSceneStatus request                 1c 09 01 00 00
@@ -44,6 +50,10 @@ GetLightingPhysicalKeys reply                          04 09 01 13 00 00 00 01 0
 GetLightingPhysicalKeys request                        04 09 01 02 00 01 00
 GetLightingRoutes reply                                09 09 01 09 00 00 00 01 01 01 2a 01 02 07
 GetLightingRoutes request                              09 09 01 02 00 01 00
+GetLightingRuntimeConditionalSceneStatus reply         25 09 01 06 00 00 00 09 40 01 08
+GetLightingRuntimeConditionalSceneStatus request       25 09 01 00 00
+GetLightingRuntimeConditionalScenes reply              26 09 01 14 00 00 00 09 01 01 01 02 01 01 01 01 14 01 50 02 2a 00 07 08 09
+GetLightingRuntimeConditionalScenes request            26 09 01 02 00 09 00
 GetLightingSceneStatus reply                           12 09 01 08 00 00 00 09 80 02 01 01 08
 GetLightingSceneStatus request                         12 09 01 00 00
 GetLightingScenes reply                                13 09 01 0b 00 00 00 09 01 01 02 2a 00 07 08 09
@@ -58,12 +68,16 @@ LightingChange topic                                   07 80 00 00 00
 PutLightingOverlayChunk inner Err(TransactionExpired)  0e 09 01 03 00 00 01 0a
 PutLightingOverlayChunk reply                          0e 09 01 02 00 00 00
 PutLightingOverlayChunk request                        0e 09 01 10 00 0d 00 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27
+PutLightingRuntimeConditionalSceneChunk reply          28 09 01 02 00 00 00
+PutLightingRuntimeConditionalSceneChunk request        28 09 01 12 00 1f 00 01 01 02 01 01 01 01 14 01 50 02 2a 00 07 08 09
 PutLightingSceneChunk reply                            17 09 01 02 00 00 00
 PutLightingSceneChunk request                          17 09 01 09 00 15 00 01 02 2a 00 07 08 09
 SetLightingExtensionState reply                        23 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 SetLightingExtensionState request                      23 09 01 05 00 09 01 02 03 04
 SetLightingLayerPolicy reply                           1a 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
 SetLightingLayerPolicy request                         1a 09 01 02 00 0b 00
+SetLightingOutputMode reply                            24 09 01 19 00 00 00 02 01 00 01 01 01 0d 01 02 01 2a 00 00 09 00 00 09 00 00 00 00 00 09
+SetLightingOutputMode request                          24 09 01 02 00 09 01
 SetLightingOverlay inner Err(UnknownLed)               0a 09 01 05 00 00 01 06 e7 07
 SetLightingOverlay outer Err(Locked)                   0a 09 01 02 00 01 07
 SetLightingOverlay reply                               0a 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 659eb34b8..ed0906230 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1140,7 +1140,8 @@ fn lighting_wire_frames_locked() {
                 | LightingFeatureFlags::LAYER_AWARE
                 | LightingFeatureFlags::OVERLAY_READBACK
                 | LightingFeatureFlags::COMPILED_LAYER_SCENES
-                | LightingFeatureFlags::OUTPUT_MODE,
+                | LightingFeatureFlags::OUTPUT_MODE
+                | LightingFeatureFlags::RUNTIME_CONDITIONAL_SCENES,
         ),
         effects: LightingEffectFlags(
             LightingEffectFlags::SOLID | LightingEffectFlags::BLINK | LightingEffectFlags::BREATHE,
@@ -1360,6 +1361,54 @@ fn lighting_wire_frames_locked() {
             },
         }),
     };
+    let set_output_mode = SetLightingOutputModeRequest {
+        expected_revision: state.revision,
+        mode: LightingOutputMode::AlwaysOff,
+    };
+    let conditional_cell = LightingConditionalSceneCell {
+        conditions: LightingConditionSet {
+            layer: Some(LightingLayerCondition { layer: 2, active: true }),
+            battery: Some(LightingBatteryCondition {
+                node: LightingNodeId(1),
+                min_level: Some(20),
+                max_level: Some(80),
+                charge: LightingChargeCondition::Discharging,
+            }),
+        },
+        led_id: led.id,
+        effect: scene_cell.effect,
+    };
+    let runtime_conditional_status = LightingRuntimeConditionalSceneStatus {
+        revision: state.revision,
+        capacity: 64,
+        cell_len: 1,
+        chunk_capacity: LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE as u8,
+    };
+    let runtime_conditional_page_request = LightingRuntimeConditionalScenePageRequest {
+        revision: state.revision,
+        offset: 0,
+    };
+    let runtime_conditional_page = LightingRuntimeConditionalScenesPage {
+        revision: state.revision,
+        total_count: 1,
+        items: one(conditional_cell),
+    };
+    let runtime_conditional_begin = BeginLightingRuntimeConditionalSceneReplaceRequest {
+        expected_revision: state.revision,
+        cell_count: 1,
+    };
+    let runtime_conditional_transaction = LightingRuntimeConditionalSceneTransaction { id: 31, cell_count: 1 };
+    let runtime_conditional_put = PutLightingRuntimeConditionalSceneChunkRequest {
+        transaction_id: runtime_conditional_transaction.id,
+        offset: 0,
+        cells: one(conditional_cell),
+    };
+    let runtime_conditional_commit = CommitLightingRuntimeConditionalSceneReplaceRequest {
+        transaction_id: runtime_conditional_transaction.id,
+    };
+    let runtime_conditional_abort = AbortLightingRuntimeConditionalSceneReplaceRequest {
+        transaction_id: runtime_conditional_transaction.id,
+    };
 
     let entries: alloc::vec::Vec<(&str, alloc::vec::Vec<u8>)> = alloc::vec![
         (
@@ -1410,6 +1459,110 @@ fn lighting_wire_frames_locked() {
                 &Ok::<LightingOutputModeStateResult, RynkError>(Ok(output_mode))
             )
         ),
+        (
+            "SetLightingOutputMode request",
+            encode_frame(Cmd::SetLightingOutputMode, SEQ, &set_output_mode)
+        ),
+        (
+            "SetLightingOutputMode reply",
+            encode_frame(
+                Cmd::SetLightingOutputMode,
+                SEQ,
+                &Ok::<LightingOutputModeStateResult, RynkError>(Ok(output_mode))
+            )
+        ),
+        (
+            "GetLightingRuntimeConditionalSceneStatus request",
+            encode_frame(Cmd::GetLightingRuntimeConditionalSceneStatus, SEQ, &())
+        ),
+        (
+            "GetLightingRuntimeConditionalSceneStatus reply",
+            encode_frame(
+                Cmd::GetLightingRuntimeConditionalSceneStatus,
+                SEQ,
+                &Ok::<LightingRuntimeConditionalSceneStatusResult, RynkError>(Ok(runtime_conditional_status))
+            )
+        ),
+        (
+            "GetLightingRuntimeConditionalScenes request",
+            encode_frame(
+                Cmd::GetLightingRuntimeConditionalScenes,
+                SEQ,
+                &runtime_conditional_page_request
+            )
+        ),
+        (
+            "GetLightingRuntimeConditionalScenes reply",
+            encode_frame(
+                Cmd::GetLightingRuntimeConditionalScenes,
+                SEQ,
+                &Ok::<LightingRuntimeConditionalScenesPageResult, RynkError>(Ok(runtime_conditional_page))
+            )
+        ),
+        (
+            "BeginLightingRuntimeConditionalSceneReplace request",
+            encode_frame(
+                Cmd::BeginLightingRuntimeConditionalSceneReplace,
+                SEQ,
+                &runtime_conditional_begin
+            )
+        ),
+        (
+            "BeginLightingRuntimeConditionalSceneReplace reply",
+            encode_frame(
+                Cmd::BeginLightingRuntimeConditionalSceneReplace,
+                SEQ,
+                &Ok::<LightingRuntimeConditionalSceneTransactionResult, RynkError>(Ok(runtime_conditional_transaction))
+            )
+        ),
+        (
+            "PutLightingRuntimeConditionalSceneChunk request",
+            encode_frame(
+                Cmd::PutLightingRuntimeConditionalSceneChunk,
+                SEQ,
+                &runtime_conditional_put
+            )
+        ),
+        (
+            "PutLightingRuntimeConditionalSceneChunk reply",
+            encode_frame(
+                Cmd::PutLightingRuntimeConditionalSceneChunk,
+                SEQ,
+                &Ok::<LightingUnitResult, RynkError>(Ok(()))
+            )
+        ),
+        (
+            "CommitLightingRuntimeConditionalSceneReplace request",
+            encode_frame(
+                Cmd::CommitLightingRuntimeConditionalSceneReplace,
+                SEQ,
+                &runtime_conditional_commit
+            )
+        ),
+        (
+            "CommitLightingRuntimeConditionalSceneReplace reply",
+            encode_frame(
+                Cmd::CommitLightingRuntimeConditionalSceneReplace,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "AbortLightingRuntimeConditionalSceneReplace request",
+            encode_frame(
+                Cmd::AbortLightingRuntimeConditionalSceneReplace,
+                SEQ,
+                &runtime_conditional_abort
+            )
+        ),
+        (
+            "AbortLightingRuntimeConditionalSceneReplace reply",
+            encode_frame(
+                Cmd::AbortLightingRuntimeConditionalSceneReplace,
+                SEQ,
+                &Ok::<LightingUnitResult, RynkError>(Ok(()))
+            )
+        ),
         (
             "GetLightingPhysicalKeys request",
             encode_frame(Cmd::GetLightingPhysicalKeys, SEQ, &page_request)
diff --git a/rmk/CHANGELOG.md b/rmk/CHANGELOG.md
index 83f474574..97c0de71e 100644
--- a/rmk/CHANGELOG.md
+++ b/rmk/CHANGELOG.md
@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- Add runtime-authored conditional lighting without changing the immutable board-compiled source: hosts discover `RUNTIME_CONDITIONAL_SCENES`, read revision-pinned ordered pages, and atomically replace the persistent table with `0x0925..=0x092A`. Add revision-checked `SetLightingOutputMode = 0x0924` alongside the existing three-state readback. Both additions use capability/command probing and leave `ProtocolVersion` unchanged.
 - Add [Rynk](https://rmk.rs/docs/features/rynk), RMK's native host protocol for on-the-fly configuration over USB and BLE — an opt-in alternative to Vial that covers every RMK feature (keymap, layers, encoders, combos, forks, tap-dance/morse, macros, and behavior config), plus live status (current layer, matrix tester, WPM, HID indicators, battery, connection/BLE profile) and device management (reboot, bootloader, storage reset). Enable with the `rynk` Cargo feature and `[host] rynk_enabled = true`; it is mutually exclusive with Vial. Dangerous operations (bootloader, storage reset, matrix tester, clearing a BLE bond) are gated behind a physical-presence unlock (`[host].unlock_keys`). Host client crates live in the new `rynk/` workspace ([#962](https://github.com/rmk-rs/rmk/pull/962))
 - Add runtime-configurable per-layer lighting scenes over Rynk: hosts can store per-layer, per-LED effects on the keyboard (`GetLightingSceneStatus`/`GetLightingScenes`, `SetLightingSceneCell`/`UnsetLightingSceneCell`, an atomic `BeginLightingSceneReplace`/`PutLightingSceneChunk`/`CommitLightingSceneReplace`/`AbortLightingSceneReplace` transaction, and `SetLightingLayerPolicy`). Scene cells compose in the layer band — above the board's static layer scenes, below the transient TTL overlay — and persist via RMK storage, loading on boot and clearing with a storage reset. Boards opt in by choosing a scene capacity on the standard lighting engine and advertising it with `RynkLightingController::with_scene_capacity`. Scenes are a capability-gated extension, not a protocol-version entry: hosts discover them via `LightingFeatureFlags::LAYER_SCENES` and `GetLightingSceneStatus` (older firmware answers `UnknownCmd`); `ProtocolVersion` is unchanged — version numbers are minted upstream only, and downstream extensions (scenes, `GetBuildInfo`, `PeripheralBootloaderJump`, the lighting endpoints) are detected through capability surfaces and per-command probing. Firmware already in the field that reports a higher minor (v0.2–v0.5) remains compatible: hosts gate on capabilities, and the handshake only rejects `major` mismatches
 - Add Azoteq IQS5xx (IQS550 / IQS572 / IQS525) trackpad driver, used by Azoteq's TPS43/TPS65 modules. Supports operation with or without an `RDY` pin and is configurable via `keyboard.toml` on nRF52 / RP2040; currently publishes single-finger relative cursor movement only ([#29](https://github.com/rmk-rs/rmk/issues/29))
diff --git a/rmk/src/host/context.rs b/rmk/src/host/context.rs
index 95505163a..acbd8256f 100644
--- a/rmk/src/host/context.rs
+++ b/rmk/src/host/context.rs
@@ -9,6 +9,7 @@ use rmk_types::connection::{ConnectionStatus, ConnectionType};
 use rmk_types::fork::Fork;
 use rmk_types::led_indicator::LedIndicator;
 use rmk_types::morse::{Morse, MorseProfile};
+#[cfg(feature = "rynk")]
 use rmk_types::protocol::rynk::{LAYER_STATE_BITMAP_SIZE, LAYER_STATE_CAPACITY, LayerState};
 
 use crate::event::KeyboardEventPos;
@@ -313,6 +314,7 @@ impl<'a> KeyboardContext<'a> {
     ///
     /// The mutable keymap mask does not contain the default layer, so its bit
     /// is added explicitly to make this snapshot authoritative.
+    #[cfg(feature = "rynk")]
     pub fn layer_state(&self) -> LayerState {
         let default_layer = self.keymap.get_default_layer();
         let mut active_bitmap = [0; LAYER_STATE_BITMAP_SIZE];
@@ -376,7 +378,7 @@ impl<'a> KeyboardContext<'a> {
     }
 }
 
-#[cfg(test)]
+#[cfg(all(test, feature = "rynk"))]
 mod tests {
     use rmk_types::action::KeyAction;
 
diff --git a/rmk/src/host/mod.rs b/rmk/src/host/mod.rs
index 7d23cc655..19e2269a1 100644
--- a/rmk/src/host/mod.rs
+++ b/rmk/src/host/mod.rs
@@ -27,7 +27,8 @@ pub use rynk::RynkService as HostService;
 #[cfg(all(feature = "rynk", feature = "lighting"))]
 pub use rynk::{
     RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
-    RynkLightingReadback, StandardRynkLightingAdapter, install_lighting_scenes,
+    RynkLightingReadback, StandardRynkLightingAdapter, install_lighting_runtime_conditional_scenes,
+    install_lighting_scenes,
 };
 /// RMK's semantic version, available to downstream firmware build labels.
 #[cfg(feature = "rynk")]
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 76ece5400..75defd323 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -3,16 +3,21 @@
 use embassy_time::Instant;
 use heapless::{String, Vec};
 use rmk_types::protocol::rynk::command::{
-    ClearLightingOverlay, GetLightingCapabilities, GetLightingCompiledSceneStatus, GetLightingCompiledScenes,
-    GetLightingConditionalSceneStatus, GetLightingConditionalScenes, GetLightingExtension, GetLightingExtensionNames,
-    GetLightingKeys, GetLightingLeds, GetLightingOutputMode, GetLightingOutputs, GetLightingOverlay,
-    GetLightingPhysicalKeys, GetLightingRoutes, GetLightingSceneStatus, GetLightingScenes, GetLightingState,
-    GetLightingZoneMemberships, GetLightingZones, SetLightingExtensionState, SetLightingLayerPolicy,
-    SetLightingOverlay, SetLightingSceneCell, SetLightingState, UnsetLightingOverlay, UnsetLightingSceneCell,
+    AbortLightingRuntimeConditionalSceneReplace, BeginLightingRuntimeConditionalSceneReplace, ClearLightingOverlay,
+    CommitLightingRuntimeConditionalSceneReplace, GetLightingCapabilities, GetLightingCompiledSceneStatus,
+    GetLightingCompiledScenes, GetLightingConditionalSceneStatus, GetLightingConditionalScenes, GetLightingExtension,
+    GetLightingExtensionNames, GetLightingKeys, GetLightingLeds, GetLightingOutputMode, GetLightingOutputs,
+    GetLightingOverlay, GetLightingPhysicalKeys, GetLightingRoutes, GetLightingRuntimeConditionalSceneStatus,
+    GetLightingRuntimeConditionalScenes, GetLightingSceneStatus, GetLightingScenes, GetLightingState,
+    GetLightingZoneMemberships, GetLightingZones, PutLightingRuntimeConditionalSceneChunk, SetLightingExtensionState,
+    SetLightingLayerPolicy, SetLightingOutputMode, SetLightingOverlay, SetLightingSceneCell, SetLightingState,
+    UnsetLightingOverlay, UnsetLightingSceneCell,
 };
 use rmk_types::protocol::rynk::{
-    AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
-    BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest,
+    AbortLightingOverlayReplaceRequest, AbortLightingRuntimeConditionalSceneReplaceRequest,
+    AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
+    BeginLightingRuntimeConditionalSceneReplaceRequest, BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest,
+    CommitLightingOverlayReplaceRequest, CommitLightingRuntimeConditionalSceneReplaceRequest,
     CommitLightingSceneReplaceRequest, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE, LIGHTING_PAGE_SIZE,
     LIGHTING_SCENE_CHUNK_SIZE, LIGHTING_ZONE_NAME_SIZE, LightingCapabilities, LightingCapabilitiesResult,
     LightingCompiledSceneStatus, LightingCompiledSceneStatusResult, LightingCompiledScenesPageResult,
@@ -25,12 +30,16 @@ use rmk_types::protocol::rynk::{
     LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransaction,
     LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKey, LightingPhysicalKeysPage,
     LightingPhysicalKeysPageResult, LightingPoint3, LightingResult, LightingRoute, LightingRoutesPage,
-    LightingRoutesPageResult, LightingScenePageRequest, LightingSceneStatus, LightingSceneStatusResult,
-    LightingSceneTransactionResult, LightingScenesPageResult, LightingState, LightingStateResult, LightingUnitResult,
-    LightingZone, LightingZoneId, LightingZoneMembershipsPage, LightingZoneMembershipsPageResult, LightingZonesPage,
-    LightingZonesPageResult, PutLightingOverlayChunkRequest, PutLightingSceneChunkRequest, RynkError, RynkMessage,
-    SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest, SetLightingOverlayRequest,
-    SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
+    LightingRoutesPageResult, LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
+    LightingRuntimeConditionalSceneStatusResult, LightingRuntimeConditionalSceneTransactionResult,
+    LightingRuntimeConditionalScenesPageResult, LightingScenePageRequest, LightingSceneStatus,
+    LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult, LightingState,
+    LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage,
+    LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult, PutLightingOverlayChunkRequest,
+    PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, RynkError, RynkMessage,
+    SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest, SetLightingOutputModeRequest,
+    SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest,
+    UnsetLightingSceneCellRequest,
 };
 
 use super::super::lighting::{
@@ -66,6 +75,13 @@ fn extension_controller<'a>(service: &RynkService<'a>) -> LightingResult<RynkLig
     Ok(controller)
 }
 
+fn runtime_conditional_scene_controller<'a>(service: &RynkService<'a>) -> LightingResult<RynkLightingController<'a>> {
+    let controller = controller(service)?;
+    if controller.runtime_conditional_scene_capacity == 0 {
+        return Err(LightingError::Unsupported);
+    }
+    Ok(controller)
+}
 impl Handle<GetLightingCapabilities> for RynkService<'_> {
     async fn handle(&self, _: ()) -> Result<LightingCapabilitiesResult, RynkError> {
         Ok(controller(self).map(capabilities))
@@ -98,6 +114,24 @@ impl Handle<GetLightingOutputMode> for RynkService<'_> {
     }
 }
 
+impl Handle<SetLightingOutputMode> for RynkService<'_> {
+    async fn handle(&self, req: SetLightingOutputModeRequest) -> Result<LightingOutputModeStateResult, RynkError> {
+        Ok(match controller(self) {
+            Ok(controller) => controller
+                .request(RynkLightingCommand::SetOutputMode {
+                    expected_revision: req.expected_revision,
+                    mode: req.mode,
+                })
+                .await
+                .and_then(|reply| match reply {
+                    RynkLightingReadback::OutputMode(state) => Ok(controller.output_mode_to_wire(state)),
+                    _ => Err(LightingError::InvalidRequest),
+                }),
+            Err(error) => Err(error),
+        })
+    }
+}
+
 impl Handle<GetLightingOverlay> for RynkService<'_> {
     async fn handle(&self, req: LightingOverlayPageRequest) -> Result<LightingOverlayPageResult, RynkError> {
         let result = match controller(self) {
@@ -326,6 +360,161 @@ impl Handle<GetLightingConditionalScenes> for RynkService<'_> {
     }
 }
 
+impl Handle<GetLightingRuntimeConditionalSceneStatus> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LightingRuntimeConditionalSceneStatusResult, RynkError> {
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::ReadRuntimeConditionalSceneStatus)
+                .await
+            {
+                Ok(RynkLightingReadback::RuntimeConditionalSceneStatus { revision, cell_len }) => {
+                    Ok(LightingRuntimeConditionalSceneStatus {
+                        revision,
+                        capacity: controller.runtime_conditional_scene_capacity,
+                        cell_len,
+                        chunk_capacity: LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE as u8,
+                    })
+                }
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        })
+    }
+}
+
+impl Handle<GetLightingRuntimeConditionalScenes> for RynkService<'_> {
+    async fn handle(
+        &self,
+        req: LightingRuntimeConditionalScenePageRequest,
+    ) -> Result<LightingRuntimeConditionalScenesPageResult, RynkError> {
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::ReadRuntimeConditionalScenes {
+                    expected_revision: req.revision,
+                    offset: req.offset,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::RuntimeConditionalScenesPage(page)) => Ok(page),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        })
+    }
+}
+
+impl Handle<BeginLightingRuntimeConditionalSceneReplace> for RynkService<'_> {
+    async fn handle(
+        &self,
+        req: BeginLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<LightingRuntimeConditionalSceneTransactionResult, RynkError> {
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) if req.cell_count > controller.runtime_conditional_scene_capacity => {
+                Err(LightingError::ConditionalSceneFull {
+                    capacity: controller.runtime_conditional_scene_capacity,
+                })
+            }
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::BeginRuntimeConditionalSceneReplace {
+                    expected_revision: req.expected_revision,
+                    cell_count: req.cell_count,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::RuntimeConditionalSceneTransaction(transaction)) => Ok(transaction),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        })
+    }
+}
+
+impl Handle<PutLightingRuntimeConditionalSceneChunk> for RynkService<'_> {
+    async fn handle(
+        &self,
+        req: PutLightingRuntimeConditionalSceneChunkRequest,
+    ) -> Result<LightingUnitResult, RynkError> {
+        for cell in &req.cells {
+            if let Err(error) = cell.validate() {
+                return Ok(Err(error));
+            }
+            if let Some(layer) = cell.conditions.layer
+                && let Err(error) = self.check_scene_layer(layer.layer)
+            {
+                return Ok(Err(error));
+            }
+            if let Some(battery) = cell.conditions.battery
+                && let Ok(controller) = controller(self)
+                && !controller
+                    .descriptor
+                    .routing
+                    .outputs
+                    .iter()
+                    .any(|output| output.node.0 == battery.node.0)
+            {
+                return Ok(Err(LightingError::InvalidRequest));
+            }
+        }
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::PutRuntimeConditionalSceneChunk {
+                    transaction_id: req.transaction_id,
+                    offset: req.offset,
+                    cells: req.cells,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::Unit) => Ok(()),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        })
+    }
+}
+
+impl Handle<CommitLightingRuntimeConditionalSceneReplace> for RynkService<'_> {
+    async fn handle(
+        &self,
+        req: CommitLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<LightingStateResult, RynkError> {
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) => {
+                controller
+                    .request_state(RynkLightingCommand::CommitRuntimeConditionalSceneReplace {
+                        transaction_id: req.transaction_id,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        })
+    }
+}
+
+impl Handle<AbortLightingRuntimeConditionalSceneReplace> for RynkService<'_> {
+    async fn handle(
+        &self,
+        req: AbortLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<LightingUnitResult, RynkError> {
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::AbortRuntimeConditionalSceneReplace {
+                    transaction_id: req.transaction_id,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::Unit) => Ok(()),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        })
+    }
+}
+
 impl Handle<SetLightingSceneCell> for RynkService<'_> {
     async fn handle(&self, req: SetLightingSceneCellRequest) -> Result<LightingStateResult, RynkError> {
         if let Err(error) = req
@@ -596,6 +785,9 @@ fn capabilities(binding: RynkLightingController<'_>) -> LightingCapabilities {
     if !binding.conditional_scenes.is_empty() {
         features.0 |= LightingFeatureFlags::COMPILED_CONDITIONAL_SCENES;
     }
+    if binding.runtime_conditional_scene_capacity > 0 {
+        features.0 |= LightingFeatureFlags::RUNTIME_CONDITIONAL_SCENES;
+    }
     if binding.controls.output_mode_cycle_user_action.is_some() {
         features.0 |= LightingFeatureFlags::OUTPUT_MODE;
     }
@@ -1659,6 +1851,7 @@ mod tests {
             let service = RynkService::new(&keymap, &config).with_lighting(
                 RynkLightingController::new(&mailbox, descriptor(), 8)
                     .with_scene_capacity(4)
+                    .with_runtime_conditional_scene_capacity(4)
                     .with_conditional_scenes(&CONDITIONAL_CELLS)
                     .with_controls(controls),
             );
@@ -1692,6 +1885,11 @@ mod tests {
                     .contains(LightingFeatureFlags::COMPILED_CONDITIONAL_SCENES)
             );
             assert!(lighting.features.contains(LightingFeatureFlags::OUTPUT_MODE));
+            assert!(
+                lighting
+                    .features
+                    .contains(LightingFeatureFlags::RUNTIME_CONDITIONAL_SCENES)
+            );
 
             let client = async {
                 let compiled_status = call::<GetLightingCompiledSceneStatus>(&service, &session, &())
@@ -1992,6 +2190,104 @@ mod tests {
                         current: 5
                     })
                 );
+
+                let runtime_status = call::<GetLightingRuntimeConditionalSceneStatus>(&service, &session, &())
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(runtime_status.revision, 5);
+                assert_eq!(runtime_status.capacity, 4);
+                assert_eq!(runtime_status.cell_len, 0);
+                let transaction = call::<BeginLightingRuntimeConditionalSceneReplace>(
+                    &service,
+                    &session,
+                    &BeginLightingRuntimeConditionalSceneReplaceRequest {
+                        expected_revision: 5,
+                        cell_count: 1,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                let conditional_cell = LightingConditionalSceneCell {
+                    conditions: rmk_types::protocol::rynk::LightingConditionSet {
+                        layer: Some(rmk_types::protocol::rynk::LightingLayerCondition { layer: 1, active: true }),
+                        battery: None,
+                    },
+                    led_id: LightingLedId(42),
+                    effect: rmk_types::protocol::rynk::LightingEffect::Solid {
+                        color: rmk_types::protocol::rynk::LightingRgb8 { r: 3, g: 4, b: 5 },
+                    },
+                };
+                let mut conditional_cells = Vec::new();
+                conditional_cells.push(conditional_cell).unwrap();
+                call::<PutLightingRuntimeConditionalSceneChunk>(
+                    &service,
+                    &session,
+                    &PutLightingRuntimeConditionalSceneChunkRequest {
+                        transaction_id: transaction.id,
+                        offset: 0,
+                        cells: conditional_cells,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                let committed = call::<CommitLightingRuntimeConditionalSceneReplace>(
+                    &service,
+                    &session,
+                    &CommitLightingRuntimeConditionalSceneReplaceRequest {
+                        transaction_id: transaction.id,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(committed.revision, 6);
+                let runtime_page = call::<GetLightingRuntimeConditionalScenes>(
+                    &service,
+                    &session,
+                    &LightingRuntimeConditionalScenePageRequest { revision: 6, offset: 0 },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(runtime_page.items.as_slice(), &[conditional_cell]);
+
+                let output = call::<SetLightingOutputMode>(
+                    &service,
+                    &session,
+                    &SetLightingOutputModeRequest {
+                        expected_revision: 6,
+                        mode: rmk_types::protocol::rynk::LightingOutputMode::AlwaysOff,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(output.mode, rmk_types::protocol::rynk::LightingOutputMode::AlwaysOff);
+                let state = call::<GetLightingState>(&service, &session, &())
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(state.revision, 7);
+                let stale_output = call::<SetLightingOutputMode>(
+                    &service,
+                    &session,
+                    &SetLightingOutputModeRequest {
+                        expected_revision: 6,
+                        mode: rmk_types::protocol::rynk::LightingOutputMode::AlwaysOn,
+                    },
+                )
+                .await
+                .unwrap();
+                assert_eq!(
+                    stale_output,
+                    Err(LightingError::StateRevisionConflict {
+                        expected: 6,
+                        current: 7,
+                    })
+                );
             };
 
             let adapter_loop = async {
@@ -2051,6 +2347,10 @@ mod tests {
                     message,
                     FlashOperationMessage::LightingSceneShard { index: 0, cells } if cells.len() == 1
                 )));
+                assert!(persisted.iter().any(|message| matches!(
+                    message,
+                    FlashOperationMessage::LightingRuntimeConditionalSceneTable { len: 1 }
+                )));
             }
         });
     }
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 49fdef269..c55a51907 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -21,7 +21,8 @@ use rmk_types::protocol::rynk::{
     LightingExtension, LightingExtensionNameKind, LightingExtensionNamesPage,
     LightingExtensionState as WireExtensionState, LightingLayerPolicy, LightingMutableState,
     LightingOutputMode as WireLightingOutputMode, LightingOutputModeIndicator as WireLightingOutputModeIndicator,
-    LightingOutputModeState, LightingOverlayCell, LightingOverlayPage, LightingResult, LightingRgb8, LightingSceneCell,
+    LightingOutputModeState, LightingOverlayCell, LightingOverlayPage, LightingResult, LightingRgb8,
+    LightingRuntimeConditionalSceneTransaction, LightingRuntimeConditionalScenesPage, LightingSceneCell,
     LightingSceneTransaction, LightingScenesPage, LightingState,
 };
 
@@ -29,9 +30,9 @@ use crate::RawMutex;
 use crate::core_traits::Runnable;
 use crate::lighting::{
     BackgroundMode, BackgroundState, BuiltinEffect, ConditionalSceneCell, LayerPolicy, LedId, LightingControls,
-    LightingMailbox, LightingRouting, LightingTopology, OVERLAY_CHUNK_SIZE, OverlayBatch, OverlayCell, OverlayError,
-    Rgb8, SceneChunk, SceneTableCell, StandardCommand, StandardError, StandardLightingEngine, StandardMutableState,
-    StandardReply, StandardState,
+    LightingMailbox, LightingRouting, LightingTopology, OVERLAY_CHUNK_SIZE, OutputMode, OverlayBatch, OverlayCell,
+    OverlayError, Rgb8, RuntimeConditionalSceneCell, RuntimeConditionalSceneChunk, SceneChunk, SceneTableCell,
+    StandardCommand, StandardError, StandardLightingEngine, StandardMutableState, StandardReply, StandardState,
 };
 
 const _: () = core::assert!(
@@ -68,6 +69,7 @@ pub struct RynkLightingController<'a> {
     /// wire a scene table; hosts gate on it and every scene endpoint rejects
     /// with `Unsupported`.
     pub(super) scene_capacity: u16,
+    pub(super) runtime_conditional_scene_capacity: u16,
     pub(super) conditional_scenes: &'a [ConditionalSceneCell<BuiltinEffect>],
     pub(super) controls: LightingControls,
     /// Whether the board wired a host-selectable extension source; gates the
@@ -93,6 +95,7 @@ impl<'a> RynkLightingController<'a> {
                 staged_capacity
             },
             scene_capacity: 0,
+            runtime_conditional_scene_capacity: 0,
             conditional_scenes: &[],
             controls: LightingControls {
                 output_toggle_user_action: None,
@@ -121,6 +124,12 @@ impl<'a> RynkLightingController<'a> {
         self
     }
 
+    /// Advertise an ordered runtime conditional table.
+    pub const fn with_runtime_conditional_scene_capacity(mut self, capacity: u16) -> Self {
+        self.runtime_conditional_scene_capacity = capacity;
+        self
+    }
+
     /// Advertise immutable conditional scenes compiled from board config.
     pub const fn with_conditional_scenes(mut self, scenes: &'a [ConditionalSceneCell<BuiltinEffect>]) -> Self {
         self.conditional_scenes = scenes;
@@ -225,6 +234,10 @@ pub enum RynkLightingReadback {
         scene_len: u16,
         policy: LightingLayerPolicy,
     },
+    RuntimeConditionalSceneStatus {
+        revision: u32,
+        cell_len: u16,
+    },
     ScenesPage(LightingScenesPage),
     CompiledSceneStatus {
         scene_len: u16,
@@ -234,6 +247,8 @@ pub enum RynkLightingReadback {
     SceneTransaction(LightingSceneTransaction),
     Extension(LightingExtension),
     ExtensionNamesPage(LightingExtensionNamesPage),
+    RuntimeConditionalScenesPage(LightingRuntimeConditionalScenesPage),
+    RuntimeConditionalSceneTransaction(LightingRuntimeConditionalSceneTransaction),
     Unit,
 }
 
@@ -385,6 +400,10 @@ impl Default for RynkLightingMailbox {
 pub(super) enum RynkLightingCommand {
     ReadState,
     ReadOutputMode,
+    SetOutputMode {
+        expected_revision: u32,
+        mode: WireLightingOutputMode,
+    },
     ReadOverlay {
         expected_revision: u32,
         offset: u16,
@@ -407,6 +426,26 @@ pub(super) enum RynkLightingCommand {
         expected_revision: u32,
         state: WireExtensionState,
     },
+    ReadRuntimeConditionalSceneStatus,
+    ReadRuntimeConditionalScenes {
+        expected_revision: u32,
+        offset: u16,
+    },
+    BeginRuntimeConditionalSceneReplace {
+        expected_revision: u32,
+        cell_count: u16,
+    },
+    PutRuntimeConditionalSceneChunk {
+        transaction_id: u32,
+        offset: u16,
+        cells: Vec<WireConditionalSceneCell, { rmk_types::protocol::rynk::LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE }>,
+    },
+    CommitRuntimeConditionalSceneReplace {
+        transaction_id: u32,
+    },
+    AbortRuntimeConditionalSceneReplace {
+        transaction_id: u32,
+    },
     SetSceneCell {
         expected_revision: u32,
         cell: LightingSceneCell,
@@ -542,6 +581,15 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
         Ok(state)
     }
 
+    async fn runtime_conditional_scene_mutation(
+        &self,
+        command: StandardCommand<OVERLAY_CAPACITY, SCENE_CAP>,
+    ) -> LightingResult<StandardState> {
+        let state = self.request_core_state(command).await?;
+        self.persist_runtime_conditional_scenes(&state).await;
+        Ok(state)
+    }
+
     #[cfg(feature = "storage")]
     async fn persist_scenes(&self, state: &StandardState) {
         use crate::channel::FLASH_CHANNEL;
@@ -587,6 +635,50 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
     #[cfg(not(feature = "storage"))]
     async fn persist_scenes(&self, _state: &StandardState) {}
 
+    #[cfg(feature = "storage")]
+    async fn persist_runtime_conditional_scenes(&self, state: &StandardState) {
+        use crate::channel::FLASH_CHANNEL;
+        use crate::storage::FlashOperationMessage;
+
+        let mut total = state.runtime_conditional_scene_len.min(u16::MAX as usize) as u16;
+        let mut offset: u16 = 0;
+        let mut shard: u8 = 0;
+        while offset < total {
+            let Ok(StandardReply::RuntimeConditionalScenesPage(page)) = self
+                .request_core(StandardCommand::ReadRuntimeConditionalScenes { offset })
+                .await
+            else {
+                return;
+            };
+            let cells = page.cells.as_slice();
+            if cells.is_empty() {
+                break;
+            }
+            let mut wire_cells = Vec::new();
+            for cell in cells {
+                let Some(wire) = self.runtime_conditional_scene_cell_to_wire(*cell) else {
+                    return;
+                };
+                let _ = wire_cells.push(wire);
+            }
+            FLASH_CHANNEL
+                .send(FlashOperationMessage::LightingRuntimeConditionalSceneShard {
+                    index: shard,
+                    cells: wire_cells,
+                })
+                .await;
+            offset += cells.len() as u16;
+            shard = shard.saturating_add(1);
+            total = page.total;
+        }
+        FLASH_CHANNEL
+            .send(FlashOperationMessage::LightingRuntimeConditionalSceneTable { len: offset })
+            .await;
+    }
+
+    #[cfg(not(feature = "storage"))]
+    async fn persist_runtime_conditional_scenes(&self, _state: &StandardState) {}
+
     async fn dispatch(&self, request_id: u32, command: RynkLightingCommand) -> LightingResult<RynkLightingReadback> {
         let core_command = match command {
             RynkLightingCommand::ReadState => StandardCommand::ReadState,
@@ -594,6 +686,18 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                 let state = self.request_core_state(StandardCommand::ReadState).await?;
                 return Ok(RynkLightingReadback::OutputMode(state));
             }
+            RynkLightingCommand::SetOutputMode {
+                expected_revision,
+                mode,
+            } => {
+                let state = self
+                    .request_core_state(StandardCommand::SetOutputModeIfRevision {
+                        expected_revision,
+                        mode: output_mode_from_wire(mode),
+                    })
+                    .await?;
+                return Ok(RynkLightingReadback::OutputMode(state));
+            }
             RynkLightingCommand::ReadOverlay {
                 expected_revision,
                 offset,
@@ -743,6 +847,98 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                     speed: state.speed,
                 },
             },
+            RynkLightingCommand::ReadRuntimeConditionalSceneStatus => {
+                let state = self.request_core_state(StandardCommand::ReadState).await?;
+                return Ok(RynkLightingReadback::RuntimeConditionalSceneStatus {
+                    revision: state.revision,
+                    cell_len: state.runtime_conditional_scene_len.min(u16::MAX as usize) as u16,
+                });
+            }
+            RynkLightingCommand::ReadRuntimeConditionalScenes {
+                expected_revision,
+                offset,
+            } => {
+                let page = match self
+                    .request_core(StandardCommand::ReadRuntimeConditionalScenes { offset })
+                    .await?
+                {
+                    StandardReply::RuntimeConditionalScenesPage(page) => page,
+                    _ => return Err(LightingError::InvalidRequest),
+                };
+                if page.revision != expected_revision {
+                    return Err(LightingError::StateRevisionConflict {
+                        expected: expected_revision,
+                        current: page.revision,
+                    });
+                }
+                let mut items = Vec::new();
+                for cell in page.cells.as_slice() {
+                    items
+                        .push(
+                            self.runtime_conditional_scene_cell_to_wire(*cell)
+                                .ok_or(LightingError::InvalidRequest)?,
+                        )
+                        .map_err(|_| LightingError::InvalidRequest)?;
+                }
+                return Ok(RynkLightingReadback::RuntimeConditionalScenesPage(
+                    LightingRuntimeConditionalScenesPage {
+                        revision: page.revision,
+                        total_count: page.total,
+                        items,
+                    },
+                ));
+            }
+            RynkLightingCommand::BeginRuntimeConditionalSceneReplace {
+                expected_revision,
+                cell_count,
+            } => {
+                let reply = self
+                    .request_core(StandardCommand::BeginRuntimeConditionalSceneReplace {
+                        expected_revision,
+                        cell_count,
+                    })
+                    .await?;
+                return match reply {
+                    StandardReply::RuntimeConditionalSceneTransaction { id, cell_count } => {
+                        Ok(RynkLightingReadback::RuntimeConditionalSceneTransaction(
+                            LightingRuntimeConditionalSceneTransaction { id, cell_count },
+                        ))
+                    }
+                    _ => Err(LightingError::InvalidRequest),
+                };
+            }
+            RynkLightingCommand::PutRuntimeConditionalSceneChunk {
+                transaction_id,
+                offset,
+                cells,
+            } => {
+                let mut chunk = RuntimeConditionalSceneChunk::new();
+                for cell in &cells {
+                    chunk
+                        .push(self.runtime_conditional_scene_cell_from_wire(*cell)?)
+                        .map_err(|error| map_standard_error(error, OVERLAY_CAPACITY))?;
+                }
+                self.request_core_state(StandardCommand::PutRuntimeConditionalSceneChunk {
+                    transaction_id,
+                    offset,
+                    cells: chunk,
+                })
+                .await?;
+                return Ok(RynkLightingReadback::Unit);
+            }
+            RynkLightingCommand::CommitRuntimeConditionalSceneReplace { transaction_id } => {
+                let state = self
+                    .runtime_conditional_scene_mutation(StandardCommand::CommitRuntimeConditionalSceneReplace {
+                        transaction_id,
+                    })
+                    .await?;
+                return Ok(RynkLightingReadback::State(state_to_wire(state)));
+            }
+            RynkLightingCommand::AbortRuntimeConditionalSceneReplace { transaction_id } => {
+                self.request_core_state(StandardCommand::AbortRuntimeConditionalSceneReplace { transaction_id })
+                    .await?;
+                return Ok(RynkLightingReadback::Unit);
+            }
             RynkLightingCommand::SetSceneCell {
                 expected_revision,
                 cell,
@@ -931,6 +1127,34 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
             effect: effect_to_wire(cell.effect),
         })
     }
+
+    fn runtime_conditional_scene_cell_from_wire(
+        &self,
+        cell: WireConditionalSceneCell,
+    ) -> LightingResult<RuntimeConditionalSceneCell> {
+        cell.validate()?;
+        let slot = self
+            .topology
+            .slot(LedId(cell.led_id.0))
+            .ok_or(LightingError::UnknownLed { led_id: cell.led_id })?;
+        Ok(RuntimeConditionalSceneCell {
+            conditions: condition_set_from_wire(cell.conditions),
+            slot,
+            effect: effect_from_wire(cell.effect),
+        })
+    }
+
+    fn runtime_conditional_scene_cell_to_wire(
+        &self,
+        cell: RuntimeConditionalSceneCell,
+    ) -> Option<WireConditionalSceneCell> {
+        let led = self.topology.led(cell.slot)?;
+        Some(WireConditionalSceneCell {
+            conditions: condition_set_to_wire(cell.conditions),
+            led_id: rmk_types::protocol::rynk::LightingLedId(led.id.0),
+            effect: effect_to_wire(cell.effect),
+        })
+    }
 }
 
 /// Install persisted scene configuration into a standard engine at startup,
@@ -961,6 +1185,33 @@ pub fn install_lighting_scenes<Extension, Status, const N: usize, const OVERLAY_
     }
 }
 
+/// Install the persisted ordered runtime conditional source at startup.
+pub fn install_lighting_runtime_conditional_scenes<
+    Extension,
+    Status,
+    const N: usize,
+    const OVERLAY_CAP: usize,
+    const SCENE_CAP: usize,
+>(
+    engine: &mut StandardLightingEngine<'_, Extension, Status, N, OVERLAY_CAP, SCENE_CAP>,
+    topology: &LightingTopology<'_>,
+    cells: &[WireConditionalSceneCell],
+) {
+    for cell in cells {
+        if cell.validate().is_err() {
+            continue;
+        }
+        let Some(slot) = topology.slot(LedId(cell.led_id.0)) else {
+            continue;
+        };
+        let _ = engine.install_runtime_conditional_scene_cell(RuntimeConditionalSceneCell {
+            conditions: condition_set_from_wire(cell.conditions),
+            slot,
+            effect: effect_from_wire(cell.effect),
+        });
+    }
+}
+
 impl<const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, const SCENE_CAP: usize> Runnable
     for StandardRynkLightingAdapter<'_, OVERLAY_CAPACITY, CORE_COMMAND_CAPACITY, SCENE_CAP>
 {
@@ -1111,6 +1362,40 @@ fn condition_set_to_wire(conditions: crate::lighting::ConditionSet) -> rmk_types
     }
 }
 
+fn condition_set_from_wire(
+    conditions: rmk_types::protocol::rynk::LightingConditionSet,
+) -> crate::lighting::ConditionSet {
+    use rmk_types::protocol::rynk::LightingChargeCondition;
+
+    use crate::lighting::{BatteryCondition, ChargeCondition, ConditionSet, LayerCondition};
+
+    ConditionSet {
+        layer: conditions.layer.map(|condition| LayerCondition {
+            layer: condition.layer,
+            active: condition.active,
+        }),
+        battery: conditions.battery.map(|condition| BatteryCondition {
+            node: condition.node.0,
+            min_level: condition.min_level,
+            max_level: condition.max_level,
+            charge: match condition.charge {
+                LightingChargeCondition::Any => ChargeCondition::Any,
+                LightingChargeCondition::Charging => ChargeCondition::Charging,
+                LightingChargeCondition::Discharging => ChargeCondition::Discharging,
+                LightingChargeCondition::Unknown => ChargeCondition::Unknown,
+            },
+        }),
+    }
+}
+
+const fn output_mode_from_wire(mode: WireLightingOutputMode) -> OutputMode {
+    match mode {
+        WireLightingOutputMode::AlwaysOn => OutputMode::AlwaysOn,
+        WireLightingOutputMode::AlwaysOff => OutputMode::AlwaysOff,
+        WireLightingOutputMode::PoweredOnly => OutputMode::PoweredOnly,
+    }
+}
+
 pub(super) const fn policy_from_wire(policy: LightingLayerPolicy) -> LayerPolicy {
     match policy {
         LightingLayerPolicy::EffectiveOnly => LayerPolicy::EffectiveOnly,
@@ -1145,6 +1430,16 @@ fn map_standard_error(error: StandardError, capacity: usize) -> LightingError {
             LightingError::TransactionIncomplete { expected, received }
         }
         StandardError::ExtensionUnsupported => LightingError::Unsupported,
+        StandardError::ConditionalSceneFull { capacity } => LightingError::ConditionalSceneFull {
+            capacity: capacity.min(u16::MAX as usize) as u16,
+        },
+        StandardError::InvalidConditionalSceneRequest => LightingError::InvalidRequest,
+        StandardError::ConditionalSceneTransactionBusy => LightingError::TransactionBusy,
+        StandardError::InvalidConditionalSceneTransaction => LightingError::InvalidTransaction,
+        StandardError::ConditionalSceneTransactionExpired => LightingError::TransactionExpired,
+        StandardError::ConditionalSceneTransactionIncomplete { expected, received } => {
+            LightingError::TransactionIncomplete { expected, received }
+        }
     }
 }
 
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index f0d770d70..bfbc1a868 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -15,7 +15,8 @@ use postcard::experimental::max_size::MaxSize;
 #[cfg(feature = "lighting")]
 pub use lighting::{
     RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
-    RynkLightingReadback, StandardRynkLightingAdapter, install_lighting_scenes,
+    RynkLightingReadback, StandardRynkLightingAdapter, install_lighting_runtime_conditional_scenes,
+    install_lighting_scenes,
 };
 use rmk_types::constants::RYNK_BUFFER_SIZE;
 use rmk_types::protocol::rynk::{
@@ -175,7 +176,12 @@ impl<'a> RynkService<'a> {
             | Cmd::PutLightingSceneChunk
             | Cmd::CommitLightingSceneReplace
             | Cmd::AbortLightingSceneReplace
-            | Cmd::SetLightingExtensionState => self.lock_config.write_requires_unlock,
+            | Cmd::SetLightingExtensionState
+            | Cmd::SetLightingOutputMode
+            | Cmd::BeginLightingRuntimeConditionalSceneReplace
+            | Cmd::PutLightingRuntimeConditionalSceneChunk
+            | Cmd::CommitLightingRuntimeConditionalSceneReplace
+            | Cmd::AbortLightingRuntimeConditionalSceneReplace => self.lock_config.write_requires_unlock,
             _ => false,
         }
     }
@@ -323,6 +329,31 @@ impl<'a> RynkService<'a> {
             Cmd::GetLightingExtensionNames => Serve::<command::GetLightingExtensionNames, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::SetLightingExtensionState => Serve::<command::SetLightingExtensionState, _>::serve(self, msg).await,
+            Cmd::SetLightingOutputMode => Serve::<command::SetLightingOutputMode, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingRuntimeConditionalSceneStatus => {
+                Serve::<command::GetLightingRuntimeConditionalSceneStatus, _>::serve(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingRuntimeConditionalScenes => {
+                Serve::<command::GetLightingRuntimeConditionalScenes, _>::serve(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::BeginLightingRuntimeConditionalSceneReplace => {
+                Serve::<command::BeginLightingRuntimeConditionalSceneReplace, _>::serve(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::PutLightingRuntimeConditionalSceneChunk => {
+                Serve::<command::PutLightingRuntimeConditionalSceneChunk, _>::serve(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::CommitLightingRuntimeConditionalSceneReplace => {
+                Serve::<command::CommitLightingRuntimeConditionalSceneReplace, _>::serve(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::AbortLightingRuntimeConditionalSceneReplace => {
+                Serve::<command::AbortLightingRuntimeConditionalSceneReplace, _>::serve(self, msg).await
+            }
             #[cfg(feature = "lighting")]
             Cmd::SetLightingSceneCell => Serve::<command::SetLightingSceneCell, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index dac395726..aa4b706cc 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -44,9 +44,11 @@ pub use source::{
 };
 pub use standard::{
     BackgroundMode, BackgroundPatch, BackgroundState, CompiledScenePage, EmptySource, OVERLAY_CHUNK_SIZE, OverlayBatch,
-    OverlayCell, OverlayPage, ReplicaSlotError, SCENE_CHUNK_SIZE, SCENE_TRANSACTION_TIMEOUT_MS, SceneChunk, ScenePage,
-    SceneTable, SceneTableCell, StandardCommand, StandardError, StandardInput, StandardLightingEngine,
-    StandardMutableState, StandardReplicaSlot, StandardReplicaState, StandardReply, StandardState, UniformBackground,
+    OverlayCell, OverlayPage, ReplicaSlotError, RuntimeConditionalSceneCell, RuntimeConditionalSceneChunk,
+    RuntimeConditionalScenePage, RuntimeConditionalSceneTable, SCENE_CHUNK_SIZE, SCENE_TRANSACTION_TIMEOUT_MS,
+    SceneChunk, ScenePage, SceneTable, SceneTableCell, StandardCommand, StandardError, StandardInput,
+    StandardLightingEngine, StandardMutableState, StandardReplicaSlot, StandardReplicaState, StandardReply,
+    StandardState, UniformBackground,
 };
 pub use topology::*;
 
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index fe302318e..72207ffb3 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -242,7 +242,7 @@ pub struct LightingControls {
 }
 
 impl ConditionSet {
-    fn matches<Context, Batteries>(&self, context: &Context, batteries: &Batteries) -> bool
+    pub(crate) fn matches<Context, Batteries>(&self, context: &Context, batteries: &Batteries) -> bool
     where
         Context: LightingContextProvider,
         Batteries: BatteryStatusProvider + ?Sized,
diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index 81a512a05..c725c255a 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -22,8 +22,8 @@ use super::effect::{BuiltinEffect, LightingEffect};
 use super::output::BrightnessTransform;
 use super::service::{CommandResult, Invalidation, LightingEngine, RenderInput, RenderOutcome};
 use super::source::{
-    LayerPolicy, LayerScenes, LightingControls, OutputMode, OverlayError, OverlayUpdate, SceneCell, SparseScene,
-    TtlOverlay,
+    BatteryStatusProvider, ConditionSet, LayerPolicy, LayerScenes, LightingControls, OutputMode, OverlayError,
+    OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
 };
 use super::topology::LedSlot;
 use crate::RawMutex;
@@ -36,6 +36,9 @@ pub const OVERLAY_CHUNK_SIZE: usize = 8;
 /// so protocol adapters can forward chunks without re-batching.
 pub const SCENE_CHUNK_SIZE: usize = 8;
 
+/// Cells per runtime conditional-scene page/replacement chunk.
+pub const CONDITIONAL_SCENE_CHUNK_SIZE: usize = 8;
+
 /// A staged scene replacement expires after this much command inactivity.
 pub const SCENE_TRANSACTION_TIMEOUT_MS: u64 = 5_000;
 
@@ -467,6 +470,166 @@ where
     }
 }
 
+/// One ordered, runtime-authored conditional rule.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct RuntimeConditionalSceneCell {
+    pub conditions: ConditionSet,
+    pub slot: LedSlot,
+    pub effect: BuiltinEffect,
+}
+
+const EMPTY_CONDITIONAL_SCENE_CELL: RuntimeConditionalSceneCell = RuntimeConditionalSceneCell {
+    conditions: ConditionSet {
+        layer: None,
+        battery: None,
+    },
+    slot: LedSlot(0),
+    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+};
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct RuntimeConditionalSceneChunk {
+    cells: [RuntimeConditionalSceneCell; CONDITIONAL_SCENE_CHUNK_SIZE],
+    len: usize,
+}
+
+impl RuntimeConditionalSceneChunk {
+    pub const fn new() -> Self {
+        Self {
+            cells: [EMPTY_CONDITIONAL_SCENE_CELL; CONDITIONAL_SCENE_CHUNK_SIZE],
+            len: 0,
+        }
+    }
+
+    pub fn push(&mut self, cell: RuntimeConditionalSceneCell) -> Result<(), StandardError> {
+        if self.len == CONDITIONAL_SCENE_CHUNK_SIZE {
+            return Err(StandardError::InvalidConditionalSceneRequest);
+        }
+        self.cells[self.len] = cell;
+        self.len += 1;
+        Ok(())
+    }
+
+    pub fn as_slice(&self) -> &[RuntimeConditionalSceneCell] {
+        &self.cells[..self.len]
+    }
+}
+
+impl Default for RuntimeConditionalSceneChunk {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Fixed-capacity ordered conditional source. Order is semantic: later
+/// matching rules override earlier rules at the same compositor priority.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct RuntimeConditionalSceneTable<const CAP: usize> {
+    cells: [RuntimeConditionalSceneCell; CAP],
+    len: usize,
+}
+
+impl<const CAP: usize> RuntimeConditionalSceneTable<CAP> {
+    pub const fn new() -> Self {
+        Self {
+            cells: [EMPTY_CONDITIONAL_SCENE_CELL; CAP],
+            len: 0,
+        }
+    }
+
+    pub const fn len(&self) -> usize {
+        self.len
+    }
+
+    pub const fn is_empty(&self) -> bool {
+        self.len == 0
+    }
+
+    pub fn as_slice(&self) -> &[RuntimeConditionalSceneCell] {
+        &self.cells[..self.len]
+    }
+
+    pub fn push(&mut self, cell: RuntimeConditionalSceneCell) -> Result<(), StandardError> {
+        if self.len == CAP {
+            return Err(StandardError::ConditionalSceneFull { capacity: CAP });
+        }
+        self.cells[self.len] = cell;
+        self.len += 1;
+        Ok(())
+    }
+
+    pub fn clear(&mut self) {
+        self.len = 0;
+    }
+
+    pub fn page(&self, offset: u16) -> RuntimeConditionalSceneChunk {
+        let start = (offset as usize).min(self.len);
+        let end = (start + CONDITIONAL_SCENE_CHUNK_SIZE).min(self.len);
+        let mut chunk = RuntimeConditionalSceneChunk::new();
+        for cell in &self.cells[start..end] {
+            chunk.push(*cell).expect("page is chunk-bounded");
+        }
+        chunk
+    }
+}
+
+impl<const CAP: usize> Default for RuntimeConditionalSceneTable<CAP> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+struct RuntimeConditionalSource<'a, Batteries: ?Sized, const CAP: usize> {
+    table: &'a RuntimeConditionalSceneTable<CAP>,
+    batteries: &'a Batteries,
+}
+
+impl<Context, Batteries, const CAP: usize> LightingSource<Rgb8, Context>
+    for RuntimeConditionalSource<'_, Batteries, CAP>
+where
+    Context: LightingContextProvider,
+    Batteries: BatteryStatusProvider + ?Sized,
+{
+    fn len(&self, input: &SourceRenderInput<'_, Context>) -> usize {
+        self.table
+            .as_slice()
+            .iter()
+            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
+            .count()
+    }
+
+    fn slot(&self, index: usize, input: &SourceRenderInput<'_, Context>) -> LedSlot {
+        self.table
+            .as_slice()
+            .iter()
+            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
+            .nth(index)
+            .expect("LightingSource index must be below len")
+            .slot
+    }
+
+    fn contribution(&mut self, index: usize, input: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
+        let cell = self
+            .table
+            .as_slice()
+            .iter()
+            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
+            .nth(index)
+            .expect("LightingSource index must be below len");
+        Contribution::Opaque(cell.effect.sample(input.now_ms))
+    }
+}
+
+struct NoBatteryStatus;
+
+impl BatteryStatusProvider for NoBatteryStatus {
+    fn battery_status(&self, _node: u8) -> crate::types::battery::BatteryStatus {
+        crate::types::battery::BatteryStatus::Unavailable
+    }
+}
+
+static NO_BATTERY_STATUS: NoBatteryStatus = NoBatteryStatus;
+
 /// One in-progress, chunk-staged atomic scene replacement.
 ///
 /// The overlay replacement stages host-side because a whole overlay batch
@@ -482,9 +645,22 @@ struct SceneReplace<const CAP: usize> {
     last_activity_ms: u64,
 }
 
+struct RuntimeConditionalSceneReplace<const CAP: usize> {
+    id: u32,
+    expected_revision: u32,
+    expected_count: u16,
+    cells: [RuntimeConditionalSceneCell; CAP],
+    len: usize,
+    last_activity_ms: u64,
+}
+
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
     SetOutputEnabled(bool),
+    SetOutputModeIfRevision {
+        expected_revision: u32,
+        mode: OutputMode,
+    },
     SetOutputBrightness(u8),
     SetBackground(BackgroundState),
     PatchBackground(BackgroundPatch),
@@ -567,6 +743,24 @@ pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
     ReadCompiledScenes {
         offset: u16,
     },
+    ReadRuntimeConditionalScenes {
+        offset: u16,
+    },
+    BeginRuntimeConditionalSceneReplace {
+        expected_revision: u32,
+        cell_count: u16,
+    },
+    PutRuntimeConditionalSceneChunk {
+        transaction_id: u32,
+        offset: u16,
+        cells: RuntimeConditionalSceneChunk,
+    },
+    CommitRuntimeConditionalSceneReplace {
+        transaction_id: u32,
+    },
+    AbortRuntimeConditionalSceneReplace {
+        transaction_id: u32,
+    },
 }
 
 /// Mutable standard state excluding the transient overlay contents and the
@@ -590,6 +784,7 @@ pub struct StandardState {
     pub overlay_len: usize,
     pub scene_len: usize,
     pub scene_policy: LayerPolicy,
+    pub runtime_conditional_scene_len: usize,
 }
 
 /// One page of transient overlay cells with remaining TTLs.
@@ -626,6 +821,13 @@ pub struct CompiledScenePage {
     pub cells: SceneChunk,
 }
 
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct RuntimeConditionalScenePage {
+    pub revision: u32,
+    pub total: u16,
+    pub cells: RuntimeConditionalSceneChunk,
+}
+
 /// Protocol-independent readback for [`StandardCommand`]s. Most commands
 /// answer with authoritative [`StandardState`]; scene reads and transaction
 /// reservation carry their own shapes.
@@ -637,6 +839,8 @@ pub enum StandardReply {
     CompiledScenesPage(CompiledScenePage),
     SceneTransaction { id: u32, cell_count: u16 },
     Extension(ExtensionPage),
+    RuntimeConditionalScenesPage(RuntimeConditionalScenePage),
+    RuntimeConditionalSceneTransaction { id: u32, cell_count: u16 },
 }
 
 impl StandardReply {
@@ -666,6 +870,7 @@ pub struct StandardReplicaState<const OVERLAY_CAP: usize, const SCENE_CAP: usize
     pub output_mode: OutputMode,
     pub overlay: OverlayBatch<OVERLAY_CAP>,
     pub scenes: SceneTable<SCENE_CAP>,
+    pub runtime_conditional_scenes: RuntimeConditionalSceneTable<SCENE_CAP>,
     pub context: LightingContext,
     pub sample_time_ms: u64,
     /// Extension-source selection, carried so split renderer replicas track
@@ -763,6 +968,17 @@ pub enum StandardError {
         expected: u16,
         received: u16,
     },
+    ConditionalSceneFull {
+        capacity: usize,
+    },
+    InvalidConditionalSceneRequest,
+    ConditionalSceneTransactionBusy,
+    InvalidConditionalSceneTransaction,
+    ConditionalSceneTransactionExpired,
+    ConditionalSceneTransactionIncomplete {
+        expected: u16,
+        received: u16,
+    },
 }
 
 impl From<RenderError> for StandardError {
@@ -838,6 +1054,8 @@ pub struct StandardLightingEngine<
     extension: Extension,
     layers: LayerScenes<'scenes, BuiltinEffect>,
     scenes: SceneTable<SCENE_CAP>,
+    runtime_conditional_scenes: RuntimeConditionalSceneTable<SCENE_CAP>,
+    battery_status: &'scenes dyn BatteryStatusProvider,
     overlay: TtlOverlay<BuiltinEffect, OVERLAY_CAP>,
     status: Status,
     animation_clock: AnimationClock,
@@ -845,6 +1063,10 @@ pub struct StandardLightingEngine<
     scene_next_transaction: u32,
     scene_expired_transaction: Option<u32>,
     scene_committed_transaction: Option<u32>,
+    runtime_conditional_scene_replace: Option<RuntimeConditionalSceneReplace<SCENE_CAP>>,
+    runtime_conditional_scene_next_transaction: u32,
+    runtime_conditional_scene_expired_transaction: Option<u32>,
+    runtime_conditional_scene_committed_transaction: Option<u32>,
     revision: u32,
     controls: LightingControls,
     output_mode: OutputMode,
@@ -869,6 +1091,8 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             extension,
             layers,
             scenes: SceneTable::new(),
+            runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
+            battery_status: &NO_BATTERY_STATUS,
             overlay: TtlOverlay::new(),
             status,
             animation_clock: AnimationClock::local(),
@@ -876,6 +1100,10 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             scene_next_transaction: 1,
             scene_expired_transaction: None,
             scene_committed_transaction: None,
+            runtime_conditional_scene_replace: None,
+            runtime_conditional_scene_next_transaction: 1,
+            runtime_conditional_scene_expired_transaction: None,
+            runtime_conditional_scene_committed_transaction: None,
             revision: 0,
             controls: LightingControls::default(),
             output_mode: OutputMode::AlwaysOn,
@@ -895,6 +1123,12 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
         self
     }
 
+    /// Supply live board battery state for runtime conditional predicates.
+    pub const fn with_battery_status_provider(mut self, battery_status: &'scenes dyn BatteryStatusProvider) -> Self {
+        self.battery_status = battery_status;
+        self
+    }
+
     pub const fn output_mode(&self) -> OutputMode {
         self.output_mode
     }
@@ -925,6 +1159,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             overlay_len: self.overlay.active_len(),
             scene_len: self.scenes.len(),
             scene_policy: self.scenes.policy(),
+            runtime_conditional_scene_len: self.runtime_conditional_scenes.len(),
         }
     }
 
@@ -936,6 +1171,10 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
         &self.scenes
     }
 
+    pub const fn runtime_conditional_scenes(&self) -> &RuntimeConditionalSceneTable<SCENE_CAP> {
+        &self.runtime_conditional_scenes
+    }
+
     /// Install one persisted scene cell during startup, before the engine is
     /// serving commands. Does not advance the concurrency revision.
     pub fn install_scene_cell(&mut self, cell: SceneTableCell) -> Result<(), StandardError> {
@@ -948,6 +1187,15 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
         self.scenes.set_policy(policy);
     }
 
+    /// Install one persisted runtime conditional rule during startup.
+    pub fn install_runtime_conditional_scene_cell(
+        &mut self,
+        cell: RuntimeConditionalSceneCell,
+    ) -> Result<(), StandardError> {
+        Self::check_scene_slot(cell.slot)?;
+        self.runtime_conditional_scenes.push(cell)
+    }
+
     pub const fn extension(&self) -> &Extension {
         &self.extension
     }
@@ -1072,6 +1320,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             output_mode: self.output_mode,
             overlay,
             scenes: self.scenes,
+            runtime_conditional_scenes: self.runtime_conditional_scenes,
             context: *context.lighting_context(),
             sample_time_ms,
             // Filled by handle_command, where the LightingSource bound is
@@ -1115,6 +1364,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
         self.set_mutable_state(replica.mutable);
         self.output_mode = replica.output_mode;
         self.scenes = replica.scenes;
+        self.runtime_conditional_scenes = replica.runtime_conditional_scenes;
         self.revision = replica.revision;
         self.animation_clock.anchor(local_now_ms, replica.sample_time_ms);
     }
@@ -1268,6 +1518,137 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
         }
         Err(self.scene_transaction_error(transaction_id))
     }
+
+    fn expire_runtime_conditional_scene_replace(&mut self, now_ms: u64) {
+        if self
+            .runtime_conditional_scene_replace
+            .as_ref()
+            .is_some_and(|replace| now_ms.saturating_sub(replace.last_activity_ms) >= SCENE_TRANSACTION_TIMEOUT_MS)
+        {
+            self.runtime_conditional_scene_expired_transaction = self
+                .runtime_conditional_scene_replace
+                .as_ref()
+                .map(|replace| replace.id);
+            self.runtime_conditional_scene_replace = None;
+        }
+    }
+
+    fn runtime_conditional_scene_transaction_error(&self, id: u32) -> StandardError {
+        if self.runtime_conditional_scene_expired_transaction == Some(id) {
+            StandardError::ConditionalSceneTransactionExpired
+        } else {
+            StandardError::InvalidConditionalSceneTransaction
+        }
+    }
+
+    fn begin_runtime_conditional_scene_replace(
+        &mut self,
+        now_ms: u64,
+        expected_revision: u32,
+        cell_count: u16,
+    ) -> Result<u32, StandardError> {
+        self.expire_runtime_conditional_scene_replace(now_ms);
+        if self.runtime_conditional_scene_replace.is_some() {
+            return Err(StandardError::ConditionalSceneTransactionBusy);
+        }
+        if cell_count as usize > SCENE_CAP {
+            return Err(StandardError::ConditionalSceneFull { capacity: SCENE_CAP });
+        }
+        let id = self.runtime_conditional_scene_next_transaction;
+        self.runtime_conditional_scene_next_transaction =
+            self.runtime_conditional_scene_next_transaction.wrapping_add(1).max(1);
+        self.runtime_conditional_scene_expired_transaction = None;
+        self.runtime_conditional_scene_replace = Some(RuntimeConditionalSceneReplace {
+            id,
+            expected_revision,
+            expected_count: cell_count,
+            cells: [EMPTY_CONDITIONAL_SCENE_CELL; SCENE_CAP],
+            len: 0,
+            last_activity_ms: now_ms,
+        });
+        Ok(id)
+    }
+
+    fn put_runtime_conditional_scene_chunk(
+        &mut self,
+        now_ms: u64,
+        transaction_id: u32,
+        offset: u16,
+        cells: &RuntimeConditionalSceneChunk,
+    ) -> Result<(), StandardError> {
+        self.expire_runtime_conditional_scene_replace(now_ms);
+        for cell in cells.as_slice() {
+            Self::check_scene_slot(cell.slot)?;
+        }
+        let error = self.runtime_conditional_scene_transaction_error(transaction_id);
+        let replace = self
+            .runtime_conditional_scene_replace
+            .as_mut()
+            .filter(|replace| replace.id == transaction_id)
+            .ok_or(error)?;
+        if offset as usize != replace.len || replace.len + cells.as_slice().len() > replace.expected_count as usize {
+            return Err(StandardError::InvalidConditionalSceneRequest);
+        }
+        for cell in cells.as_slice() {
+            replace.cells[replace.len] = *cell;
+            replace.len += 1;
+        }
+        replace.last_activity_ms = now_ms;
+        Ok(())
+    }
+
+    fn commit_runtime_conditional_scene_replace(
+        &mut self,
+        now_ms: u64,
+        transaction_id: u32,
+    ) -> Result<bool, StandardError> {
+        self.expire_runtime_conditional_scene_replace(now_ms);
+        if self.runtime_conditional_scene_committed_transaction == Some(transaction_id)
+            && self.runtime_conditional_scene_replace.is_none()
+        {
+            return Ok(false);
+        }
+        let error = self.runtime_conditional_scene_transaction_error(transaction_id);
+        let replace = self
+            .runtime_conditional_scene_replace
+            .as_ref()
+            .filter(|replace| replace.id == transaction_id)
+            .ok_or(error)?;
+        if replace.len != replace.expected_count as usize {
+            return Err(StandardError::ConditionalSceneTransactionIncomplete {
+                expected: replace.expected_count,
+                received: replace.len as u16,
+            });
+        }
+        self.check_revision(replace.expected_revision)?;
+        let replace = self.runtime_conditional_scene_replace.take().expect("checked above");
+        self.runtime_conditional_scenes.clear();
+        for cell in &replace.cells[..replace.len] {
+            self.runtime_conditional_scenes
+                .push(*cell)
+                .expect("staged length is table-bounded");
+        }
+        self.runtime_conditional_scene_committed_transaction = Some(transaction_id);
+        self.runtime_conditional_scene_expired_transaction = None;
+        Ok(true)
+    }
+
+    fn abort_runtime_conditional_scene_replace(
+        &mut self,
+        now_ms: u64,
+        transaction_id: u32,
+    ) -> Result<(), StandardError> {
+        self.expire_runtime_conditional_scene_replace(now_ms);
+        if self
+            .runtime_conditional_scene_replace
+            .as_ref()
+            .is_some_and(|replace| replace.id == transaction_id)
+        {
+            self.runtime_conditional_scene_replace = None;
+            return Ok(());
+        }
+        Err(self.runtime_conditional_scene_transaction_error(transaction_id))
+    }
 }
 
 impl<'scenes, Context, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const SCENE_CAP: usize>
@@ -1364,6 +1745,15 @@ where
                     },
                 )));
             }
+            StandardCommand::ReadRuntimeConditionalScenes { offset } => {
+                return Ok(CommandResult::unchanged(StandardReply::RuntimeConditionalScenesPage(
+                    RuntimeConditionalScenePage {
+                        revision: self.revision,
+                        total: self.runtime_conditional_scenes.len().min(u16::MAX as usize) as u16,
+                        cells: self.runtime_conditional_scenes.page(offset),
+                    },
+                )));
+            }
             StandardCommand::BeginSceneReplace {
                 expected_revision,
                 cell_count,
@@ -1399,6 +1789,38 @@ where
                 self.abort_scene_replace(now_ms, transaction_id)?;
                 return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
             }
+            StandardCommand::BeginRuntimeConditionalSceneReplace {
+                expected_revision,
+                cell_count,
+            } => {
+                let id = self.begin_runtime_conditional_scene_replace(now_ms, expected_revision, cell_count)?;
+                return Ok(CommandResult::unchanged(
+                    StandardReply::RuntimeConditionalSceneTransaction { id, cell_count },
+                ));
+            }
+            StandardCommand::PutRuntimeConditionalSceneChunk {
+                transaction_id,
+                offset,
+                cells,
+            } => {
+                self.put_runtime_conditional_scene_chunk(now_ms, transaction_id, offset, &cells)?;
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
+            StandardCommand::CommitRuntimeConditionalSceneReplace { transaction_id } => {
+                let committed = self.commit_runtime_conditional_scene_replace(now_ms, transaction_id)?;
+                if committed {
+                    self.advance_revision();
+                    return Ok(CommandResult::new(
+                        StandardReply::State(self.state()),
+                        Invalidation::Render,
+                    ));
+                }
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
+            StandardCommand::AbortRuntimeConditionalSceneReplace { transaction_id } => {
+                self.abort_runtime_conditional_scene_replace(now_ms, transaction_id)?;
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
             _ => {}
         }
 
@@ -1411,6 +1833,14 @@ where
                 };
                 (Invalidation::Render, true)
             }
+            StandardCommand::SetOutputModeIfRevision {
+                expected_revision,
+                mode,
+            } => {
+                self.check_revision(expected_revision)?;
+                self.output_mode = mode;
+                (Invalidation::Render, true)
+            }
             StandardCommand::SetOutputBrightness(level) => {
                 self.output_brightness = level;
                 (Invalidation::Render, true)
@@ -1604,10 +2034,15 @@ where
             StandardCommand::ReadOverlay { .. }
             | StandardCommand::ReadScenes { .. }
             | StandardCommand::ReadCompiledScenes { .. }
+            | StandardCommand::ReadRuntimeConditionalScenes { .. }
             | StandardCommand::BeginSceneReplace { .. }
             | StandardCommand::PutSceneChunk { .. }
             | StandardCommand::CommitSceneReplace { .. }
             | StandardCommand::AbortSceneReplace { .. } => unreachable!("handled above"),
+            StandardCommand::BeginRuntimeConditionalSceneReplace { .. }
+            | StandardCommand::PutRuntimeConditionalSceneChunk { .. }
+            | StandardCommand::CommitRuntimeConditionalSceneReplace { .. }
+            | StandardCommand::AbortRuntimeConditionalSceneReplace { .. } => unreachable!("handled above"),
         };
         if advances_revision {
             self.advance_revision();
@@ -1658,6 +2093,8 @@ where
             extension,
             layers,
             scenes,
+            runtime_conditional_scenes,
+            battery_status,
             overlay,
             status,
             animation_clock: _,
@@ -1671,11 +2108,20 @@ where
             scene_next_transaction: _,
             scene_expired_transaction: _,
             scene_committed_transaction: _,
+            runtime_conditional_scene_replace: _,
+            runtime_conditional_scene_next_transaction: _,
+            runtime_conditional_scene_expired_transaction: _,
+            runtime_conditional_scene_committed_transaction: _,
             revision: _,
         } = self;
         let mut transaction = compositor.begin(effect_now_ms, input.snapshot, Rgb8::BLACK, frame);
         transaction.apply(priority::BACKGROUND, background)?;
         transaction.apply(priority::EXTENSION, extension)?;
+        let mut runtime_conditional_source = RuntimeConditionalSource {
+            table: runtime_conditional_scenes,
+            batteries: *battery_status,
+        };
+        transaction.apply(priority::EXTENSION, &mut runtime_conditional_source)?;
         transaction.apply(priority::LAYER, layers)?;
         // Same band, later call: runtime cells override static defaults.
         transaction.apply(priority::LAYER, scenes)?;
@@ -1943,6 +2389,7 @@ mod tests {
             output_mode: OutputMode::AlwaysOn,
             overlay: OverlayBatch::new(),
             scenes: SceneTable::new(),
+            runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
             context: context(0),
             sample_time_ms: 9,
             extension: None,
@@ -1974,6 +2421,7 @@ mod tests {
             output_mode: OutputMode::AlwaysOff,
             overlay: OverlayBatch::new(),
             scenes: SceneTable::new(),
+            runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
             context: context(0),
             sample_time_ms: 50,
             extension: Some(next_extension),
@@ -2024,6 +2472,7 @@ mod tests {
             output_mode: OutputMode::AlwaysOn,
             overlay,
             scenes: SceneTable::new(),
+            runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
             context: context(0),
             sample_time_ms: 50,
             extension: Some(ExtensionState {
@@ -2914,7 +3363,6 @@ mod tests {
             Err(StandardError::InvalidSceneTransaction)
         );
     }
-
     #[test]
     fn extension_source_claims_light_actions_before_background() {
         #[derive(Default)]
@@ -2972,4 +3420,129 @@ mod tests {
             "unclaimed actions still fall through to the background"
         );
     }
+
+    #[test]
+    fn runtime_conditional_replace_preserves_order_and_output_mode_is_revision_checked() {
+        use rmk_types::battery::{BatteryStatus, ChargeState};
+
+        use crate::lighting::{BatteryCondition, ChargeCondition, LayerCondition};
+
+        struct Batteries;
+        impl BatteryStatusProvider for Batteries {
+            fn battery_status(&self, node: u8) -> BatteryStatus {
+                if node == 1 {
+                    BatteryStatus::Available {
+                        charge_state: ChargeState::Discharging,
+                        level: Some(50),
+                    }
+                } else {
+                    BatteryStatus::Unavailable
+                }
+            }
+        }
+        static BATTERIES: Batteries = Batteries;
+
+        let mut engine = scene_engine().with_battery_status_provider(&BATTERIES);
+        let snapshot = context(0);
+        let transaction_id = match engine
+            .handle_command(
+                0,
+                StandardCommand::BeginRuntimeConditionalSceneReplace {
+                    expected_revision: 0,
+                    cell_count: 2,
+                },
+                &snapshot,
+            )
+            .unwrap()
+            .reply
+        {
+            StandardReply::RuntimeConditionalSceneTransaction { id, .. } => id,
+            other => panic!("expected runtime conditional transaction, got {other:?}"),
+        };
+        let mut cells = RuntimeConditionalSceneChunk::new();
+        cells
+            .push(RuntimeConditionalSceneCell {
+                conditions: ConditionSet {
+                    layer: None,
+                    battery: Some(BatteryCondition {
+                        node: 1,
+                        min_level: Some(25),
+                        max_level: Some(75),
+                        charge: ChargeCondition::Discharging,
+                    }),
+                },
+                slot: LedSlot(1),
+                effect: BuiltinEffect::Solid { color: RED },
+            })
+            .unwrap();
+        cells
+            .push(RuntimeConditionalSceneCell {
+                conditions: ConditionSet {
+                    layer: Some(LayerCondition { layer: 0, active: true }),
+                    battery: None,
+                },
+                slot: LedSlot(1),
+                effect: BuiltinEffect::Solid { color: GREEN },
+            })
+            .unwrap();
+        engine
+            .handle_command(
+                1,
+                StandardCommand::PutRuntimeConditionalSceneChunk {
+                    transaction_id,
+                    offset: 0,
+                    cells,
+                },
+                &snapshot,
+            )
+            .unwrap();
+        let committed = engine
+            .handle_command(
+                2,
+                StandardCommand::CommitRuntimeConditionalSceneReplace { transaction_id },
+                &snapshot,
+            )
+            .unwrap();
+        assert_eq!(committed.reply.state().unwrap().revision, 1);
+        assert_eq!(engine.runtime_conditional_scenes().as_slice(), cells.as_slice());
+
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 2,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(frame.as_slice()[1], GREEN, "later matching rules win");
+
+        assert_eq!(
+            engine.handle_command(
+                3,
+                StandardCommand::SetOutputModeIfRevision {
+                    expected_revision: 0,
+                    mode: OutputMode::PoweredOnly,
+                },
+                &snapshot,
+            ),
+            Err(StandardError::RevisionConflict {
+                expected: 0,
+                current: 1,
+            })
+        );
+        let set = engine
+            .handle_command(
+                3,
+                StandardCommand::SetOutputModeIfRevision {
+                    expected_revision: 1,
+                    mode: OutputMode::PoweredOnly,
+                },
+                &snapshot,
+            )
+            .unwrap();
+        assert_eq!(set.reply.state().unwrap().output_mode, OutputMode::PoweredOnly);
+        assert_eq!(set.reply.state().unwrap().revision, 2);
+    }
 }
diff --git a/rmk/src/storage/mod.rs b/rmk/src/storage/mod.rs
index 96ce5a1c0..7eee58c46 100644
--- a/rmk/src/storage/mod.rs
+++ b/rmk/src/storage/mod.rs
@@ -9,7 +9,10 @@ use postcard::experimental::max_size::MaxSize;
 use rmk_types::connection::ConnectionType;
 use rmk_types::morse::MorseProfile;
 #[cfg(all(feature = "lighting", feature = "rynk"))]
-use rmk_types::protocol::rynk::{LIGHTING_SCENE_CHUNK_SIZE, LightingLayerPolicy, LightingSceneCell};
+use rmk_types::protocol::rynk::{
+    LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LightingConditionalSceneCell,
+    LightingLayerPolicy, LightingSceneCell,
+};
 use sequential_storage::Error as SSError;
 use sequential_storage::cache::{Cache, Uncached};
 use sequential_storage::map::{Key, MapConfig, MapStorage, PostcardValue, SerializationError};
@@ -166,6 +169,15 @@ pub(crate) enum FlashOperationMessage {
         index: u8,
         cells: heapless::Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>,
     },
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingRuntimeConditionalSceneTable {
+        len: u16,
+    },
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingRuntimeConditionalSceneShard {
+        index: u8,
+        cells: heapless::Vec<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>,
+    },
     #[cfg(feature = "_ble")]
     // Read bond info for the given slot; storage task replies via `BOND_INFO_RESPONSE`.
     ReadBleBondInfo(u8),
@@ -216,6 +228,10 @@ pub(crate) enum StorageKey {
     LightingSceneTable,
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     LightingSceneShard(u8),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingRuntimeConditionalSceneTable,
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingRuntimeConditionalSceneShard(u8),
 }
 
 impl StorageKey {
@@ -301,6 +317,12 @@ pub(crate) enum StorageData {
     LightingSceneTable(LightingSceneTableRecord),
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     LightingSceneShard(heapless::Vec<LightingSceneCell, LIGHTING_SCENE_CHUNK_SIZE>),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingRuntimeConditionalSceneTable(u16),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingRuntimeConditionalSceneShard(
+        heapless::Vec<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>,
+    ),
 }
 
 impl<'a> PostcardValue<'a> for StorageData {}
@@ -592,6 +614,41 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
         Some(record.policy)
     }
 
+    /// Read the persisted ordered runtime conditional table at startup.
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    pub async fn read_lighting_runtime_conditional_scenes<const CAP: usize>(
+        &mut self,
+        cells: &mut heapless::Vec<LightingConditionalSceneCell, CAP>,
+    ) {
+        let Some(StorageData::LightingRuntimeConditionalSceneTable(saved_len)) =
+            self.fetch_data(StorageKey::LightingRuntimeConditionalSceneTable).await
+        else {
+            return;
+        };
+        let len = (saved_len as usize).min(CAP);
+        let mut index: u8 = 0;
+        'shards: while cells.len() < len {
+            let Some(StorageData::LightingRuntimeConditionalSceneShard(shard)) = self
+                .fetch_data(StorageKey::LightingRuntimeConditionalSceneShard(index))
+                .await
+            else {
+                break;
+            };
+            if shard.is_empty() {
+                break;
+            }
+            for cell in shard {
+                if cells.len() == len || cells.push(cell).is_err() {
+                    break 'shards;
+                }
+            }
+            let Some(next) = index.checked_add(1) else {
+                break;
+            };
+            index = next;
+        }
+    }
+
     async fn initialize_storage_with_config(
         &mut self,
         #[cfg(feature = "host")] keymap: &[[[KeyAction; COL]; ROW]; NUM_LAYER],
@@ -899,6 +956,35 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
                         }
                     }
                 }
+                #[cfg(all(feature = "lighting", feature = "rynk"))]
+                FlashOperationMessage::LightingRuntimeConditionalSceneTable { len } => {
+                    match self.fetch_data(StorageKey::LightingRuntimeConditionalSceneTable).await {
+                        Some(StorageData::LightingRuntimeConditionalSceneTable(saved)) if saved == len => Ok(()),
+                        _ => {
+                            self.store_data(
+                                StorageKey::LightingRuntimeConditionalSceneTable,
+                                &StorageData::LightingRuntimeConditionalSceneTable(len),
+                            )
+                            .await
+                        }
+                    }
+                }
+                #[cfg(all(feature = "lighting", feature = "rynk"))]
+                FlashOperationMessage::LightingRuntimeConditionalSceneShard { index, cells } => {
+                    match self
+                        .fetch_data(StorageKey::LightingRuntimeConditionalSceneShard(index))
+                        .await
+                    {
+                        Some(StorageData::LightingRuntimeConditionalSceneShard(saved)) if saved == cells => Ok(()),
+                        _ => {
+                            self.store_data(
+                                StorageKey::LightingRuntimeConditionalSceneShard(index),
+                                &StorageData::LightingRuntimeConditionalSceneShard(cells),
+                            )
+                            .await
+                        }
+                    }
+                }
             };
 
             match write_result {
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index bf24081df..c31668ec8 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -37,6 +37,11 @@ use rynk::rmk_types::protocol::rynk::{
     LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy, SplitCentralLatencyState,
     LightingConditionalSceneStatus, LightingConditionalScenesPage, LightingOutputModeState, LightingExtension,
     LightingExtensionNamesPage, LightingExtensionNamesRequest, SetLightingExtensionStateRequest,
+    AbortLightingRuntimeConditionalSceneReplaceRequest, BeginLightingRuntimeConditionalSceneReplaceRequest,
+    CommitLightingRuntimeConditionalSceneReplaceRequest, LightingRuntimeConditionalScenePageRequest,
+    LightingRuntimeConditionalSceneStatus, LightingRuntimeConditionalSceneTransaction,
+    LightingRuntimeConditionalScenesPage, PutLightingRuntimeConditionalSceneChunkRequest,
+    SetLightingOutputModeRequest,
 };
 use rynk::{Client, Driver, LayoutInfo, RynkDevice, RynkHostError, TopicEvent};
 use wasm_bindgen::prelude::*;
@@ -179,6 +184,7 @@ endpoints! {
     get_lighting_capabilities() -> LightingCapabilities,
     get_lighting_state() -> LightingState,
     get_lighting_output_mode() -> LightingOutputModeState,
+    set_lighting_output_mode(request: SetLightingOutputModeRequest) -> LightingOutputModeState,
     set_lighting_state(request: SetLightingStateRequest) -> LightingState,
     get_lighting_keys(request: LightingPageRequest) -> LightingKeysPage,
     get_lighting_physical_keys(request: LightingPageRequest) -> LightingPhysicalKeysPage,
@@ -204,6 +210,12 @@ endpoints! {
     get_lighting_compiled_scenes(request: LightingPageRequest) -> LightingCompiledScenesPage,
     get_lighting_conditional_scene_status() -> LightingConditionalSceneStatus,
     get_lighting_conditional_scenes(request: LightingPageRequest) -> LightingConditionalScenesPage,
+    get_lighting_runtime_conditional_scene_status() -> LightingRuntimeConditionalSceneStatus,
+    get_lighting_runtime_conditional_scenes(request: LightingRuntimeConditionalScenePageRequest) -> LightingRuntimeConditionalScenesPage,
+    begin_lighting_runtime_conditional_scene_replace(request: BeginLightingRuntimeConditionalSceneReplaceRequest) -> LightingRuntimeConditionalSceneTransaction,
+    put_lighting_runtime_conditional_scene_chunk(request: PutLightingRuntimeConditionalSceneChunkRequest) -> (),
+    commit_lighting_runtime_conditional_scene_replace(request: CommitLightingRuntimeConditionalSceneReplaceRequest) -> LightingState,
+    abort_lighting_runtime_conditional_scene_replace(request: AbortLightingRuntimeConditionalSceneReplaceRequest) -> (),
     set_lighting_scene_cell(request: SetLightingSceneCellRequest) -> LightingState,
     unset_lighting_scene_cell(request: UnsetLightingSceneCellRequest) -> LightingState,
     set_lighting_layer_policy(request: SetLightingLayerPolicyRequest) -> LightingState,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 614569a21..45761bb9c 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -38,7 +38,11 @@ use rmk_types::protocol::rynk::{
     LightingCompiledScenesPage, LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy,
     SplitCentralLatencyState, LightingConditionalSceneStatus, LightingConditionalScenesPage, LightingOutputModeState,
     LightingExtension, LightingExtensionNameKind, LightingExtensionNamesPage, LightingExtensionNamesRequest,
-    SetLightingExtensionStateRequest,
+    SetLightingExtensionStateRequest, AbortLightingRuntimeConditionalSceneReplaceRequest,
+    BeginLightingRuntimeConditionalSceneReplaceRequest, CommitLightingRuntimeConditionalSceneReplaceRequest,
+    LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
+    LightingRuntimeConditionalSceneTransaction, LightingRuntimeConditionalScenesPage,
+    PutLightingRuntimeConditionalSceneChunkRequest, SetLightingOutputModeRequest,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -431,6 +435,14 @@ impl Client {
         Self::flatten_lighting(self.request::<command::GetLightingOutputMode>(&()).await?)
     }
 
+    pub async fn set_lighting_output_mode(
+        &self,
+        request: SetLightingOutputModeRequest,
+    ) -> Result<LightingOutputModeState, RynkHostError> {
+        self.require_lighting(Cmd::SetLightingOutputMode)?;
+        Self::flatten_lighting(self.request::<command::SetLightingOutputMode>(&request).await?)
+    }
+
     /// Atomically replace standard mutable state when the revision still matches.
     pub async fn set_lighting_state(&self, request: SetLightingStateRequest) -> Result<LightingState, RynkHostError> {
         self.require_lighting(Cmd::SetLightingState)?;
@@ -629,6 +641,70 @@ impl Client {
         Self::flatten_lighting(self.request::<command::SetLightingExtensionState>(&request).await?)
     }
 
+    pub async fn get_lighting_runtime_conditional_scene_status(
+        &self,
+    ) -> Result<LightingRuntimeConditionalSceneStatus, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingRuntimeConditionalSceneStatus)?;
+        Self::flatten_lighting(
+            self.request::<command::GetLightingRuntimeConditionalSceneStatus>(&())
+                .await?,
+        )
+    }
+
+    pub async fn get_lighting_runtime_conditional_scenes(
+        &self,
+        request: LightingRuntimeConditionalScenePageRequest,
+    ) -> Result<LightingRuntimeConditionalScenesPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingRuntimeConditionalScenes)?;
+        Self::flatten_lighting(
+            self.request::<command::GetLightingRuntimeConditionalScenes>(&request)
+                .await?,
+        )
+    }
+
+    pub async fn begin_lighting_runtime_conditional_scene_replace(
+        &self,
+        request: BeginLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<LightingRuntimeConditionalSceneTransaction, RynkHostError> {
+        self.require_lighting(Cmd::BeginLightingRuntimeConditionalSceneReplace)?;
+        Self::flatten_lighting(
+            self.request::<command::BeginLightingRuntimeConditionalSceneReplace>(&request)
+                .await?,
+        )
+    }
+
+    pub async fn put_lighting_runtime_conditional_scene_chunk(
+        &self,
+        request: PutLightingRuntimeConditionalSceneChunkRequest,
+    ) -> Result<(), RynkHostError> {
+        self.require_lighting(Cmd::PutLightingRuntimeConditionalSceneChunk)?;
+        Self::flatten_lighting(
+            self.request::<command::PutLightingRuntimeConditionalSceneChunk>(&request)
+                .await?,
+        )
+    }
+
+    pub async fn commit_lighting_runtime_conditional_scene_replace(
+        &self,
+        request: CommitLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::CommitLightingRuntimeConditionalSceneReplace)?;
+        Self::flatten_lighting(
+            self.request::<command::CommitLightingRuntimeConditionalSceneReplace>(&request)
+                .await?,
+        )
+    }
+
+    pub async fn abort_lighting_runtime_conditional_scene_replace(
+        &self,
+        request: AbortLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<(), RynkHostError> {
+        self.require_lighting(Cmd::AbortLightingRuntimeConditionalSceneReplace)?;
+        Self::flatten_lighting(
+            self.request::<command::AbortLightingRuntimeConditionalSceneReplace>(&request)
+                .await?,
+        )
+    }
     /// Insert or update one durable scene cell when the revision matches.
     pub async fn set_lighting_scene_cell(
         &self,

From 610d8857dee15668d6d632dc15fb8b8559dfd9d1 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 22 Jul 2026 05:07:05 -0700
Subject: [PATCH 32/78] fix(rynk): gate output mode dispatch on lighting

---
 rmk/src/host/rynk/mod.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index bfbc1a868..f79b594a2 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -329,6 +329,7 @@ impl<'a> RynkService<'a> {
             Cmd::GetLightingExtensionNames => Serve::<command::GetLightingExtensionNames, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::SetLightingExtensionState => Serve::<command::SetLightingExtensionState, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
             Cmd::SetLightingOutputMode => Serve::<command::SetLightingOutputMode, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::GetLightingRuntimeConditionalSceneStatus => {

From d5ddf8a2ca89595059f78092b815e922d5dc23f8 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 22 Jul 2026 06:09:44 -0700
Subject: [PATCH 33/78] fix(split): detect a dead peripheral link within two
 seconds

A powered-off peripheral was only rediscovered after the central gave
up on the dead connection: a 5 s supervision timeout plus a 5 s
liveness poll. A quick off/on cycle of the peripheral therefore missed
its directed-advertising window and still took several seconds to
come back even with a connection request armed.

Derive the supervision timeout from the active latency policy with a
2 s floor and poll liveness every 500 ms.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/split/ble/central.rs | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/rmk/src/split/ble/central.rs b/rmk/src/split/ble/central.rs
index b1d249128..8d4116ca4 100644
--- a/rmk/src/split/ble/central.rs
+++ b/rmk/src/split/ble/central.rs
@@ -340,11 +340,18 @@ pub(crate) async fn run_ble_peripheral_manager<
 }
 
 fn default_central_conn_param() -> RequestedConnParams {
+    let max_latency = latency_state().effective;
+    // Supervision must exceed the longest legal radio silence,
+    // interval * (1 + latency). Keep three such periods of margin, with a 2 s
+    // floor: a powered-off peripheral is only rediscovered after the dead
+    // connection times out, so this bounds reconnect latency for fast
+    // off/on cycles.
+    let latency_period_us = 7_500 * (1 + max_latency as u64);
     RequestedConnParams {
         min_connection_interval: Duration::from_micros(7500),
         max_connection_interval: Duration::from_micros(7500),
-        max_latency: latency_state().effective,
-        supervision_timeout: Duration::from_secs(5),
+        max_latency,
+        supervision_timeout: Duration::from_micros((3 * latency_period_us).max(2_000_000)),
         ..Default::default()
     }
 }
@@ -411,10 +418,11 @@ async fn ble_central_task<'a, C: Controller + ControllerCmdAsync<LeSetPhy>, P: P
     client: &GattClient<'a, C, P, 10>,
     conn: &Connection<'a, P>,
 ) -> Result<(), BleHostError<C::Error>> {
-    // Simply monitor connection status
+    // Simply monitor connection status. Poll quickly: this bounds how long a
+    // dead link lingers before reconnection starts.
     let conn_check = async {
         while conn.is_connected() {
-            Timer::after_secs(5).await;
+            Timer::after_millis(500).await;
         }
     };
 

From defece43ed9d00da479a9f7fd64f9481d3f77d0f Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 28 Jul 2026 16:25:14 -0700
Subject: [PATCH 34/78] test: regenerate rynk wire snapshots and protocol
 reference

---
 .../main/docs/development/rynk_protocol.md    | 187 ------------------
 .../rynk/snapshots/lighting_wire_frames.snap  | 174 ++++++++--------
 .../rynk/snapshots/split_ble_wire_frames.snap |  10 +-
 .../protocol/rynk/snapshots/wire_frames.snap  |  11 +-
 .../protocol/rynk/snapshots/wire_values.snap  | 171 ++++++++--------
 5 files changed, 189 insertions(+), 364 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index df65c03d1..4136d7f82 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -4,9 +4,6 @@
 
 # Rynk Protocol Reference
 
-Current protocol version: **0.2**.
-Current protocol version: **0.4**.
-Current protocol version: **0.3**.
 Current protocol version: **0.1**.
 
 Every transport (USB CDC, BLE GATT, BLE HID) carries the same frame — a 3-byte header plus a [postcard](https://docs.rs/postcard)-encoded payload:
@@ -29,190 +26,6 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 
 ## Endpoints
 
-| CMD      | Name                           | Request                               | Response                            | Feature    | Notes                                                                        |
-| -------- | ------------------------------ | ------------------------------------- | ----------------------------------- | ---------- | ---------------------------------------------------------------------------- |
-| `0x0001` | `GetVersion`                   | `()`                                  | `ProtocolVersion`                   |            |                                                                              |
-| `0x0002` | `GetCapabilities`              | `()`                                  | `DeviceCapabilities`                |            |                                                                              |
-| `0x0003` | `Reboot`                       | `()`                                  | `()`                                |            |                                                                              |
-| `0x0004` | `BootloaderJump`               | `()`                                  | `()`                                |            |                                                                              |
-| `0x0005` | `StorageReset`                 | `StorageResetMode`                    | `()`                                |            |                                                                              |
-| `0x0006` | `GetLockStatus`                | `()`                                  | `LockStatus`                        |            | Pure read of the current lock state — no side effects.                       |
-| `0x0007` | `UnlockPoll`                   | `()`                                  | `LockStatus`                        |            | Arms/refreshes the unlock attempt and samples the held challenge keys.       |
-| `0x0008` | `Lock`                         | `()`                                  | `()`                                |            | Relock immediately.                                                          |
-| `0x0009` | `GetLayout`                    | `u32`                                 | `LayoutChunk`                       |            | Get layout blob chunk. `u32` is the byte offset.                             |
-| `0x000A` | `GetDeviceInfo`                | `()`                                  | `DeviceInfo`                        |            | Identity strings and USB ids; feature gating stays in `GetCapabilities`.     |
-| `0x000B` | `GetBuildInfo`                 | `()`                                  | `BuildInfo`                         |            | Application-defined diagnostic build label; never used for compatibility.    |
-| `0x000C` | `PeripheralBootloaderJump`     | `u8`                                  | `()`                                |            | Ask the application to route a bootloader jump to one split peripheral.      |
-| `0x0101` | `GetKeyAction`                 | `KeyPosition`                         | `KeyAction`                         |            |                                                                              |
-| `0x0102` | `SetKeyAction`                 | `SetKeyRequest`                       | `()`                                |            |                                                                              |
-| `0x0103` | `GetDefaultLayer`              | `()`                                  | `u8`                                |            |                                                                              |
-| `0x0104` | `SetDefaultLayer`              | `u8`                                  | `()`                                |            |                                                                              |
-| `0x0105` | `GetEncoderAction`             | `GetEncoderRequest`                   | `EncoderAction`                     |            |                                                                              |
-| `0x0106` | `SetEncoderAction`             | `SetEncoderRequest`                   | `()`                                |            |                                                                              |
-| `0x0107` | `GetKeymapBulk`                | `GetKeymapBulkRequest`                | `GetKeymapBulkResponse`             |            |                                                                              |
-| `0x0108` | `SetKeymapBulk`                | `SetKeymapBulkRequest`                | `()`                                |            |                                                                              |
-| `0x0201` | `GetMacro`                     | `GetMacroRequest`                     | `MacroData`                         |            |                                                                              |
-| `0x0202` | `SetMacro`                     | `SetMacroRequest`                     | `()`                                |            |                                                                              |
-| `0x0301` | `GetCombo`                     | `u8`                                  | `Combo`                             |            |                                                                              |
-| `0x0302` | `SetCombo`                     | `SetComboRequest`                     | `()`                                |            |                                                                              |
-| `0x0303` | `GetComboBulk`                 | `GetComboBulkRequest`                 | `GetComboBulkResponse`              |            |                                                                              |
-| `0x0304` | `SetComboBulk`                 | `SetComboBulkRequest`                 | `()`                                |            |                                                                              |
-| `0x0401` | `GetMorse`                     | `u8`                                  | `Morse`                             |            |                                                                              |
-| `0x0402` | `SetMorse`                     | `SetMorseRequest`                     | `()`                                |            |                                                                              |
-| `0x0403` | `GetMorseBulk`                 | `GetMorseBulkRequest`                 | `GetMorseBulkResponse`              |            |                                                                              |
-| `0x0404` | `SetMorseBulk`                 | `SetMorseBulkRequest`                 | `()`                                |            |                                                                              |
-| `0x0501` | `GetFork`                      | `u8`                                  | `Fork`                              |            |                                                                              |
-| `0x0502` | `SetFork`                      | `SetForkRequest`                      | `()`                                |            |                                                                              |
-| `0x0601` | `GetBehaviorConfig`            | `()`                                  | `BehaviorConfig`                    |            |                                                                              |
-| `0x0602` | `SetBehaviorConfig`            | `BehaviorConfig`                      | `()`                                |            |                                                                              |
-| `0x0701` | `GetConnectionType`            | `()`                                  | `ConnectionType`                    |            |                                                                              |
-| `0x0702` | `GetConnectionStatus`          | `()`                                  | `ConnectionStatus`                  |            | Full `ConnectionStatus` snapshot.                                            |
-| `0x0703` | `GetBleStatus`                 | `()`                                  | `BleStatus`                         | `_ble`     |                                                                              |
-| `0x0704` | `SwitchBleProfile`             | `u8`                                  | `()`                                | `_ble`     |                                                                              |
-| `0x0705` | `ClearBleProfile`              | `u8`                                  | `()`                                | `_ble`     |                                                                              |
-| `0x0801` | `GetCurrentLayer`              | `()`                                  | `u8`                                |            |                                                                              |
-| `0x0802` | `GetMatrixState`               | `()`                                  | `MatrixState`                       |            |                                                                              |
-| `0x0803` | `GetBatteryStatus`             | `()`                                  | `BatteryStatus`                     | `_ble`     |                                                                              |
-| `0x0804` | `GetPeripheralStatus`          | `u8`                                  | `PeripheralStatus`                  | `split`    |                                                                              |
-| `0x0805` | `GetWpm`                       | `()`                                  | `u16`                               |            | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                     |
-| `0x0806` | `GetSleepState`                | `()`                                  | `bool`                              |            | Latest sleep flag, sourced from the `SleepState` topic snapshot.             |
-| `0x0807` | `GetLedIndicator`              | `()`                                  | `LedIndicator`                      |            | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot. |
-| `0x0901` | `GetLightingCapabilities`      | `()`                                  | `LightingCapabilitiesResult`        | `lighting` |                                                                              |
-| `0x0902` | `GetLightingState`             | `()`                                  | `LightingStateResult`               | `lighting` |                                                                              |
-| `0x0903` | `SetLightingState`             | `SetLightingStateRequest`             | `LightingStateResult`               | `lighting` |                                                                              |
-| `0x0904` | `GetLightingPhysicalKeys`      | `LightingPageRequest`                 | `LightingPhysicalKeysPageResult`    | `lighting` |                                                                              |
-| `0x0905` | `GetLightingLeds`              | `LightingPageRequest`                 | `LightingLedsPageResult`            | `lighting` |                                                                              |
-| `0x0906` | `GetLightingZones`             | `LightingPageRequest`                 | `LightingZonesPageResult`           | `lighting` |                                                                              |
-| `0x0907` | `GetLightingZoneMemberships`   | `LightingPageRequest`                 | `LightingZoneMembershipsPageResult` | `lighting` |                                                                              |
-| `0x0908` | `GetLightingOutputs`           | `LightingPageRequest`                 | `LightingOutputsPageResult`         | `lighting` |                                                                              |
-| `0x0909` | `GetLightingRoutes`            | `LightingPageRequest`                 | `LightingRoutesPageResult`          | `lighting` |                                                                              |
-| `0x090A` | `SetLightingOverlay`           | `SetLightingOverlayRequest`           | `LightingStateResult`               | `lighting` |                                                                              |
-| `0x090B` | `UnsetLightingOverlay`         | `UnsetLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                              |
-| `0x090C` | `ClearLightingOverlay`         | `ClearLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                              |
-| `0x090D` | `BeginLightingOverlayReplace`  | `BeginLightingOverlayReplaceRequest`  | `LightingOverlayTransactionResult`  | `lighting` |                                                                              |
-| `0x090E` | `PutLightingOverlayChunk`      | `PutLightingOverlayChunkRequest`      | `LightingUnitResult`                | `lighting` |                                                                              |
-| `0x090F` | `CommitLightingOverlayReplace` | `CommitLightingOverlayReplaceRequest` | `LightingStateResult`               | `lighting` |                                                                              |
-| `0x0910` | `AbortLightingOverlayReplace`  | `AbortLightingOverlayReplaceRequest`  | `LightingUnitResult`                | `lighting` |                                                                              |
-| `0x0911` | `GetLightingKeys`              | `LightingPageRequest`                 | `LightingKeysPageResult`            | `lighting` | Logical matrix keys are distinct from optional physical geometry.            |
-| CMD      | Name                  | Request                | Response                | Feature | Notes                                                                        |
-| -------- | --------------------- | ---------------------- | ----------------------- | ------- | ---------------------------------------------------------------------------- |
-| `0x0001` | `GetVersion`          | `()`                   | `ProtocolVersion`       |         |                                                                              |
-| `0x0002` | `GetCapabilities`     | `()`                   | `DeviceCapabilities`    |         |                                                                              |
-| `0x0003` | `Reboot`              | `()`                   | `()`                    |         |                                                                              |
-| `0x0004` | `BootloaderJump`      | `()`                   | `()`                    |         |                                                                              |
-| `0x0005` | `StorageReset`        | `StorageResetMode`     | `()`                    |         |                                                                              |
-| `0x0006` | `GetLockStatus`       | `()`                   | `LockStatus`            |         | Pure read of the current lock state — no side effects.                       |
-| `0x0007` | `UnlockPoll`          | `()`                   | `LockStatus`            |         | Arms/refreshes the unlock attempt and samples the held challenge keys.       |
-| `0x0008` | `Lock`                | `()`                   | `()`                    |         | Relock immediately.                                                          |
-| `0x0009` | `GetLayout`           | `u32`                  | `LayoutChunk`           |         | Get layout blob chunk. `u32` is the byte offset.                             |
-| `0x000A` | `GetDeviceInfo`       | `()`                   | `DeviceInfo`            |         | Identity strings and USB ids; feature gating stays in `GetCapabilities`.     |
-| `0x000B` | `GetBuildInfo`        | `()`                   | `BuildInfo`             |         | Application-defined diagnostic build label; never used for compatibility.    |
-| `0x0101` | `GetKeyAction`        | `KeyPosition`          | `KeyAction`             |         |                                                                              |
-| `0x0102` | `SetKeyAction`        | `SetKeyRequest`        | `()`                    |         |                                                                              |
-| `0x0103` | `GetDefaultLayer`     | `()`                   | `u8`                    |         |                                                                              |
-| `0x0104` | `SetDefaultLayer`     | `u8`                   | `()`                    |         |                                                                              |
-| `0x0105` | `GetEncoderAction`    | `GetEncoderRequest`    | `EncoderAction`         |         |                                                                              |
-| `0x0106` | `SetEncoderAction`    | `SetEncoderRequest`    | `()`                    |         |                                                                              |
-| `0x0107` | `GetKeymapBulk`       | `GetKeymapBulkRequest` | `GetKeymapBulkResponse` |         |                                                                              |
-| `0x0108` | `SetKeymapBulk`       | `SetKeymapBulkRequest` | `()`                    |         |                                                                              |
-| `0x0201` | `GetMacro`            | `GetMacroRequest`      | `MacroData`             |         |                                                                              |
-| `0x0202` | `SetMacro`            | `SetMacroRequest`      | `()`                    |         |                                                                              |
-| `0x0301` | `GetCombo`            | `u8`                   | `Combo`                 |         |                                                                              |
-| `0x0302` | `SetCombo`            | `SetComboRequest`      | `()`                    |         |                                                                              |
-| `0x0303` | `GetComboBulk`        | `GetComboBulkRequest`  | `GetComboBulkResponse`  |         |                                                                              |
-| `0x0304` | `SetComboBulk`        | `SetComboBulkRequest`  | `()`                    |         |                                                                              |
-| `0x0401` | `GetMorse`            | `u8`                   | `Morse`                 |         |                                                                              |
-| `0x0402` | `SetMorse`            | `SetMorseRequest`      | `()`                    |         |                                                                              |
-| `0x0403` | `GetMorseBulk`        | `GetMorseBulkRequest`  | `GetMorseBulkResponse`  |         |                                                                              |
-| `0x0404` | `SetMorseBulk`        | `SetMorseBulkRequest`  | `()`                    |         |                                                                              |
-| `0x0501` | `GetFork`             | `u8`                   | `Fork`                  |         |                                                                              |
-| `0x0502` | `SetFork`             | `SetForkRequest`       | `()`                    |         |                                                                              |
-| `0x0601` | `GetBehaviorConfig`   | `()`                   | `BehaviorConfig`        |         |                                                                              |
-| `0x0602` | `SetBehaviorConfig`   | `BehaviorConfig`       | `()`                    |         |                                                                              |
-| `0x0701` | `GetConnectionType`   | `()`                   | `ConnectionType`        |         |                                                                              |
-| `0x0702` | `GetConnectionStatus` | `()`                   | `ConnectionStatus`      |         | Full `ConnectionStatus` snapshot.                                            |
-| `0x0703` | `GetBleStatus`        | `()`                   | `BleStatus`             | `_ble`  |                                                                              |
-| `0x0704` | `SwitchBleProfile`    | `u8`                   | `()`                    | `_ble`  |                                                                              |
-| `0x0705` | `ClearBleProfile`     | `u8`                   | `()`                    | `_ble`  |                                                                              |
-| `0x0801` | `GetCurrentLayer`     | `()`                   | `u8`                    |         |                                                                              |
-| `0x0802` | `GetMatrixState`      | `()`                   | `MatrixState`           |         |                                                                              |
-| `0x0803` | `GetBatteryStatus`    | `()`                   | `BatteryStatus`         | `_ble`  |                                                                              |
-| `0x0804` | `GetPeripheralStatus` | `u8`                   | `PeripheralStatus`      | `split` |                                                                              |
-| `0x0805` | `GetWpm`              | `()`                   | `u16`                   |         | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                     |
-| `0x0806` | `GetSleepState`       | `()`                   | `bool`                  |         | Latest sleep flag, sourced from the `SleepState` topic snapshot.             |
-| `0x0807` | `GetLedIndicator`     | `()`                   | `LedIndicator`          |         | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot. |
-| CMD      | Name                           | Request                               | Response                            | Feature    | Notes                                                                                                                          |
-| -------- | ------------------------------ | ------------------------------------- | ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `0x0001` | `GetVersion`                   | `()`                                  | `ProtocolVersion`                   |            |                                                                                                                                |
-| `0x0002` | `GetCapabilities`              | `()`                                  | `DeviceCapabilities`                |            |                                                                                                                                |
-| `0x0003` | `Reboot`                       | `()`                                  | `()`                                |            |                                                                                                                                |
-| `0x0004` | `BootloaderJump`               | `()`                                  | `()`                                |            |                                                                                                                                |
-| `0x0005` | `StorageReset`                 | `StorageResetMode`                    | `()`                                |            |                                                                                                                                |
-| `0x0006` | `GetLockStatus`                | `()`                                  | `LockStatus`                        |            | Pure read of the current lock state — no side effects.                                                                         |
-| `0x0007` | `UnlockPoll`                   | `()`                                  | `LockStatus`                        |            | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                         |
-| `0x0008` | `Lock`                         | `()`                                  | `()`                                |            | Relock immediately.                                                                                                            |
-| `0x0009` | `GetLayout`                    | `u32`                                 | `LayoutChunk`                       |            | Get layout blob chunk. `u32` is the byte offset.                                                                               |
-| `0x000A` | `GetDeviceInfo`                | `()`                                  | `DeviceInfo`                        |            | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                       |
-| `0x0101` | `GetKeyAction`                 | `KeyPosition`                         | `KeyAction`                         |            |                                                                                                                                |
-| `0x0102` | `SetKeyAction`                 | `SetKeyRequest`                       | `()`                                |            |                                                                                                                                |
-| `0x0103` | `GetDefaultLayer`              | `()`                                  | `u8`                                |            |                                                                                                                                |
-| `0x0104` | `SetDefaultLayer`              | `u8`                                  | `()`                                |            |                                                                                                                                |
-| `0x0105` | `GetEncoderAction`             | `GetEncoderRequest`                   | `EncoderAction`                     |            |                                                                                                                                |
-| `0x0106` | `SetEncoderAction`             | `SetEncoderRequest`                   | `()`                                |            |                                                                                                                                |
-| `0x0107` | `GetKeymapBulk`                | `GetKeymapBulkRequest`                | `GetKeymapBulkResponse`             |            |                                                                                                                                |
-| `0x0108` | `SetKeymapBulk`                | `SetKeymapBulkRequest`                | `()`                                |            |                                                                                                                                |
-| `0x0201` | `GetMacro`                     | `GetMacroRequest`                     | `MacroData`                         |            |                                                                                                                                |
-| `0x0202` | `SetMacro`                     | `SetMacroRequest`                     | `()`                                |            |                                                                                                                                |
-| `0x0301` | `GetCombo`                     | `u8`                                  | `Combo`                             |            |                                                                                                                                |
-| `0x0302` | `SetCombo`                     | `SetComboRequest`                     | `()`                                |            |                                                                                                                                |
-| `0x0303` | `GetComboBulk`                 | `GetComboBulkRequest`                 | `GetComboBulkResponse`              |            |                                                                                                                                |
-| `0x0304` | `SetComboBulk`                 | `SetComboBulkRequest`                 | `()`                                |            |                                                                                                                                |
-| `0x0401` | `GetMorse`                     | `u8`                                  | `Morse`                             |            |                                                                                                                                |
-| `0x0402` | `SetMorse`                     | `SetMorseRequest`                     | `()`                                |            |                                                                                                                                |
-| `0x0403` | `GetMorseBulk`                 | `GetMorseBulkRequest`                 | `GetMorseBulkResponse`              |            |                                                                                                                                |
-| `0x0404` | `SetMorseBulk`                 | `SetMorseBulkRequest`                 | `()`                                |            |                                                                                                                                |
-| `0x0501` | `GetFork`                      | `u8`                                  | `Fork`                              |            |                                                                                                                                |
-| `0x0502` | `SetFork`                      | `SetForkRequest`                      | `()`                                |            |                                                                                                                                |
-| `0x0601` | `GetBehaviorConfig`            | `()`                                  | `BehaviorConfig`                    |            |                                                                                                                                |
-| `0x0602` | `SetBehaviorConfig`            | `BehaviorConfig`                      | `()`                                |            |                                                                                                                                |
-| `0x0701` | `GetConnectionType`            | `()`                                  | `ConnectionType`                    |            |                                                                                                                                |
-| `0x0702` | `GetConnectionStatus`          | `()`                                  | `ConnectionStatus`                  |            | Full `ConnectionStatus` snapshot.                                                                                              |
-| `0x0703` | `GetBleStatus`                 | `()`                                  | `BleStatus`                         | `_ble`     |                                                                                                                                |
-| `0x0704` | `SwitchBleProfile`             | `u8`                                  | `()`                                | `_ble`     |                                                                                                                                |
-| `0x0705` | `ClearBleProfile`              | `u8`                                  | `()`                                | `_ble`     |                                                                                                                                |
-| `0x0801` | `GetCurrentLayer`              | `()`                                  | `u8`                                |            |                                                                                                                                |
-| `0x0802` | `GetMatrixState`               | `()`                                  | `MatrixState`                       |            |                                                                                                                                |
-| `0x0803` | `GetBatteryStatus`             | `()`                                  | `BatteryStatus`                     | `_ble`     |                                                                                                                                |
-| `0x0804` | `GetPeripheralStatus`          | `u8`                                  | `PeripheralStatus`                  | `split`    |                                                                                                                                |
-| `0x0805` | `GetWpm`                       | `()`                                  | `u16`                               |            | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                       |
-| `0x0806` | `GetSleepState`                | `()`                                  | `bool`                              |            | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                               |
-| `0x0807` | `GetLedIndicator`              | `()`                                  | `LedIndicator`                      |            | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                   |
-| `0x0901` | `GetLightingCapabilities`      | `()`                                  | `LightingCapabilitiesResult`        | `lighting` |                                                                                                                                |
-| `0x0902` | `GetLightingState`             | `()`                                  | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0903` | `SetLightingState`             | `SetLightingStateRequest`             | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0904` | `GetLightingPhysicalKeys`      | `LightingPageRequest`                 | `LightingPhysicalKeysPageResult`    | `lighting` |                                                                                                                                |
-| `0x0905` | `GetLightingLeds`              | `LightingPageRequest`                 | `LightingLedsPageResult`            | `lighting` |                                                                                                                                |
-| `0x0906` | `GetLightingZones`             | `LightingPageRequest`                 | `LightingZonesPageResult`           | `lighting` |                                                                                                                                |
-| `0x0907` | `GetLightingZoneMemberships`   | `LightingPageRequest`                 | `LightingZoneMembershipsPageResult` | `lighting` |                                                                                                                                |
-| `0x0908` | `GetLightingOutputs`           | `LightingPageRequest`                 | `LightingOutputsPageResult`         | `lighting` |                                                                                                                                |
-| `0x0909` | `GetLightingRoutes`            | `LightingPageRequest`                 | `LightingRoutesPageResult`          | `lighting` |                                                                                                                                |
-| `0x090A` | `SetLightingOverlay`           | `SetLightingOverlayRequest`           | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x090B` | `UnsetLightingOverlay`         | `UnsetLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x090C` | `ClearLightingOverlay`         | `ClearLightingOverlayRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x090D` | `BeginLightingOverlayReplace`  | `BeginLightingOverlayReplaceRequest`  | `LightingOverlayTransactionResult`  | `lighting` |                                                                                                                                |
-| `0x090E` | `PutLightingOverlayChunk`      | `PutLightingOverlayChunkRequest`      | `LightingUnitResult`                | `lighting` |                                                                                                                                |
-| `0x090F` | `CommitLightingOverlayReplace` | `CommitLightingOverlayReplaceRequest` | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0910` | `AbortLightingOverlayReplace`  | `AbortLightingOverlayReplaceRequest`  | `LightingUnitResult`                | `lighting` |                                                                                                                                |
-| `0x0911` | `GetLightingKeys`              | `LightingPageRequest`                 | `LightingKeysPageResult`            | `lighting` | Logical matrix keys are distinct from optional physical geometry.                                                              |
-| `0x0912` | `GetLightingSceneStatus`       | `()`                                  | `LightingSceneStatusResult`         | `lighting` | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts. |
-| `0x0913` | `GetLightingScenes`            | `LightingScenePageRequest`            | `LightingScenesPageResult`          | `lighting` | Scene pages are pinned to `LightingState.revision` for consistency.                                                            |
-| `0x0914` | `SetLightingSceneCell`         | `SetLightingSceneCellRequest`         | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0915` | `UnsetLightingSceneCell`       | `UnsetLightingSceneCellRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0916` | `BeginLightingSceneReplace`    | `BeginLightingSceneReplaceRequest`    | `LightingSceneTransactionResult`    | `lighting` |                                                                                                                                |
-| `0x0917` | `PutLightingSceneChunk`        | `PutLightingSceneChunkRequest`        | `LightingUnitResult`                | `lighting` |                                                                                                                                |
-| `0x0918` | `CommitLightingSceneReplace`   | `CommitLightingSceneReplaceRequest`   | `LightingStateResult`               | `lighting` |                                                                                                                                |
-| `0x0919` | `AbortLightingSceneReplace`    | `AbortLightingSceneReplaceRequest`    | `LightingUnitResult`                | `lighting` |                                                                                                                                |
-| `0x091A` | `SetLightingLayerPolicy`       | `SetLightingLayerPolicyRequest`       | `LightingStateResult`               | `lighting` |                                                                                                                                |
 | CMD      | Name                                           | Request                                               | Response                                           | Feature          | Notes                                                                                                                          |
 | -------- | ---------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | `0x0001` | `GetVersion`                                   | `()`                                                  | `ProtocolVersion`                                  |                  |                                                                                                                                |
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index b8d4ddc38..6f74f5825 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -5,90 +5,90 @@
 #   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk --features lighting lighting_wire_frames
 # Format: <label>  <hex bytes>
 
-AbortLightingOverlayReplace reply                      10 09 01 02 00 00 00
-AbortLightingOverlayReplace request                    10 09 01 01 00 0d
-AbortLightingRuntimeConditionalSceneReplace reply      2a 09 01 02 00 00 00
-AbortLightingRuntimeConditionalSceneReplace request    2a 09 01 01 00 1f
-AbortLightingSceneReplace reply                        19 09 01 02 00 00 00
-AbortLightingSceneReplace request                      19 09 01 01 00 15
-BeginLightingOverlayReplace reply                      0d 09 01 04 00 00 00 0d 01
-BeginLightingOverlayReplace request                    0d 09 01 02 00 0c 01
-BeginLightingRuntimeConditionalSceneReplace reply      27 09 01 04 00 00 00 1f 01
-BeginLightingRuntimeConditionalSceneReplace request    27 09 01 02 00 09 01
-BeginLightingSceneReplace reply                        16 09 01 04 00 00 00 15 01
-BeginLightingSceneReplace request                      16 09 01 02 00 0c 01
-ClearLightingOverlay reply                             0c 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-ClearLightingOverlay request                           0c 09 01 01 00 0b
-CommitLightingOverlayReplace reply                     0f 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-CommitLightingOverlayReplace request                   0f 09 01 01 00 0d
-CommitLightingRuntimeConditionalSceneReplace reply     29 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-CommitLightingRuntimeConditionalSceneReplace request   29 09 01 01 00 1f
-CommitLightingSceneReplace reply                       18 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-CommitLightingSceneReplace request                     18 09 01 01 00 15
-GetLightingCapabilities reply                          01 09 01 10 00 00 00 01 02 03 04 05 06 07 08 09 08 08 bf 2b 07
-GetLightingCapabilities request                        01 09 01 00 00
-GetLightingCompiledSceneStatus reply                   1c 09 01 06 00 00 00 01 01 00 08
-GetLightingCompiledSceneStatus request                 1c 09 01 00 00
-GetLightingCompiledScenes reply                        1d 09 01 0b 00 00 00 01 01 01 02 2a 00 07 08 09
-GetLightingCompiledScenes request                      1d 09 01 02 00 01 00
-GetLightingExtension inner Err(Unsupported)            21 09 01 03 00 00 01 00
-GetLightingExtension reply                             21 09 01 09 00 00 00 09 06 10 01 02 03 04
-GetLightingExtension request                           21 09 01 00 00
-GetLightingExtensionNames reply                        22 09 01 0a 00 00 00 10 01 05 4f 63 65 61 6e
-GetLightingExtensionNames request                      22 09 01 02 00 01 08
-GetLightingKeys reply                                  11 09 01 07 00 00 00 01 01 01 01 02
-GetLightingKeys request                                11 09 01 02 00 01 00
-GetLightingLeds reply                                  05 09 01 12 00 00 00 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01
-GetLightingLeds request                                05 09 01 02 00 01 00
-GetLightingOutputMode reply                            20 09 01 19 00 00 00 02 01 00 01 01 01 0d 01 02 01 2a 00 00 09 00 00 09 00 00 00 00 00 09
-GetLightingOutputMode request                          20 09 01 00 00
-GetLightingOutputs reply                               08 09 01 0a 00 00 00 01 01 01 01 02 28 14 00
-GetLightingOutputs request                             08 09 01 02 00 01 00
-GetLightingOverlay reply                               1b 09 01 12 00 00 00 09 01 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27
-GetLightingOverlay request                             1b 09 01 02 00 09 00
-GetLightingPhysicalKeys reply                          04 09 01 13 00 00 00 01 01 01 01 02 ff 01 80 04 80 01 80 02 80 03 db 0b
-GetLightingPhysicalKeys request                        04 09 01 02 00 01 00
-GetLightingRoutes reply                                09 09 01 09 00 00 00 01 01 01 2a 01 02 07
-GetLightingRoutes request                              09 09 01 02 00 01 00
-GetLightingRuntimeConditionalSceneStatus reply         25 09 01 06 00 00 00 09 40 01 08
-GetLightingRuntimeConditionalSceneStatus request       25 09 01 00 00
-GetLightingRuntimeConditionalScenes reply              26 09 01 14 00 00 00 09 01 01 01 02 01 01 01 01 14 01 50 02 2a 00 07 08 09
-GetLightingRuntimeConditionalScenes request            26 09 01 02 00 09 00
-GetLightingSceneStatus reply                           12 09 01 08 00 00 00 09 80 02 01 01 08
-GetLightingSceneStatus request                         12 09 01 00 00
-GetLightingScenes reply                                13 09 01 0b 00 00 00 09 01 01 02 2a 00 07 08 09
-GetLightingScenes request                              13 09 01 02 00 09 00
-GetLightingState reply                                 02 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-GetLightingState request                               02 09 01 00 00
-GetLightingZoneMemberships reply                       07 09 01 06 00 00 00 01 01 01 04
-GetLightingZoneMemberships request                     07 09 01 02 00 01 00
-GetLightingZones reply                                 06 09 01 0c 00 00 00 01 01 01 04 05 74 68 75 6d 62
-GetLightingZones request                               06 09 01 02 00 01 00
-LightingChange topic                                   07 80 00 00 00
-PutLightingOverlayChunk inner Err(TransactionExpired)  0e 09 01 03 00 00 01 0a
-PutLightingOverlayChunk reply                          0e 09 01 02 00 00 00
-PutLightingOverlayChunk request                        0e 09 01 10 00 0d 00 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27
-PutLightingRuntimeConditionalSceneChunk reply          28 09 01 02 00 00 00
-PutLightingRuntimeConditionalSceneChunk request        28 09 01 12 00 1f 00 01 01 02 01 01 01 01 14 01 50 02 2a 00 07 08 09
-PutLightingSceneChunk reply                            17 09 01 02 00 00 00
-PutLightingSceneChunk request                          17 09 01 09 00 15 00 01 02 2a 00 07 08 09
-SetLightingExtensionState reply                        23 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-SetLightingExtensionState request                      23 09 01 05 00 09 01 02 03 04
-SetLightingLayerPolicy reply                           1a 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-SetLightingLayerPolicy request                         1a 09 01 02 00 0b 00
-SetLightingOutputMode reply                            24 09 01 19 00 00 00 02 01 00 01 01 01 0d 01 02 01 2a 00 00 09 00 00 09 00 00 00 00 00 09
-SetLightingOutputMode request                          24 09 01 02 00 09 01
-SetLightingOverlay inner Err(UnknownLed)               0a 09 01 05 00 00 01 06 e7 07
-SetLightingOverlay outer Err(Locked)                   0a 09 01 02 00 01 07
-SetLightingOverlay reply                               0a 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-SetLightingOverlay request                             0a 09 01 0e 00 09 2a 01 01 02 03 e8 07 fa 01 32 01 88 27
-SetLightingSceneCell inner Err(SceneFull)              14 09 01 05 00 00 01 0d 80 02
-SetLightingSceneCell inner Err(UnknownLayer)           14 09 01 04 00 00 01 0c c8
-SetLightingSceneCell reply                             14 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-SetLightingSceneCell request                           14 09 01 07 00 09 02 2a 00 07 08 09
-SetLightingState reply                                 03 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-SetLightingState request                               03 09 01 09 00 08 01 c8 01 0a 14 1e 28 01
-UnsetLightingOverlay reply                             0b 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-UnsetLightingOverlay request                           0b 09 01 02 00 0a 2a
-UnsetLightingSceneCell reply                           15 09 01 0c 00 00 00 09 01 c8 01 0a 14 1e 28 01 01
-UnsetLightingSceneCell request                         15 09 01 03 00 0a 02 2a
+AbortLightingOverlayReplace reply                      04 10 09 01 01 01 00
+AbortLightingOverlayReplace request                    05 10 09 01 0d 00
+AbortLightingRuntimeConditionalSceneReplace reply      04 2a 09 01 01 01 00
+AbortLightingRuntimeConditionalSceneReplace request    05 2a 09 01 1f 00
+AbortLightingSceneReplace reply                        04 19 09 01 01 01 00
+AbortLightingSceneReplace request                      05 19 09 01 15 00
+BeginLightingOverlayReplace reply                      04 0d 09 01 01 03 0d 01 00
+BeginLightingOverlayReplace request                    06 0d 09 01 0c 01 00
+BeginLightingRuntimeConditionalSceneReplace reply      04 27 09 01 01 03 1f 01 00
+BeginLightingRuntimeConditionalSceneReplace request    06 27 09 01 09 01 00
+BeginLightingSceneReplace reply                        04 16 09 01 01 03 15 01 00
+BeginLightingSceneReplace request                      06 16 09 01 0c 01 00
+ClearLightingOverlay reply                             04 0c 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+ClearLightingOverlay request                           05 0c 09 01 0b 00
+CommitLightingOverlayReplace reply                     04 0f 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+CommitLightingOverlayReplace request                   05 0f 09 01 0d 00
+CommitLightingRuntimeConditionalSceneReplace reply     04 29 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+CommitLightingRuntimeConditionalSceneReplace request   05 29 09 01 1f 00
+CommitLightingSceneReplace reply                       04 18 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+CommitLightingSceneReplace request                     05 18 09 01 15 00
+GetLightingCapabilities reply                          04 01 09 01 01 0f 01 02 03 04 05 06 07 08 09 08 08 bf 2b 07 00
+GetLightingCapabilities request                        04 01 09 01 00
+GetLightingCompiledSceneStatus reply                   04 1c 09 01 01 03 01 01 02 08 00
+GetLightingCompiledSceneStatus request                 04 1c 09 01 00
+GetLightingCompiledScenes reply                        04 1d 09 01 01 06 01 01 01 02 2a 04 07 08 09 00
+GetLightingCompiledScenes request                      05 1d 09 01 01 01 00
+GetLightingExtension inner Err(Unsupported)            04 21 09 01 02 01 01 00
+GetLightingExtension reply                             04 21 09 01 01 08 09 06 10 01 02 03 04 00
+GetLightingExtension request                           04 21 09 01 00
+GetLightingExtensionNames reply                        04 22 09 01 01 09 10 01 05 4f 63 65 61 6e 00
+GetLightingExtensionNames request                      06 22 09 01 01 08 00
+GetLightingKeys reply                                  04 11 09 01 01 06 01 01 01 01 02 00
+GetLightingKeys request                                05 11 09 01 01 01 00
+GetLightingLeds reply                                  04 05 09 01 01 11 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01 00
+GetLightingLeds request                                05 05 09 01 01 01 00
+GetLightingOutputMode reply                            04 20 09 01 01 03 02 01 09 01 01 01 0d 01 02 01 2a 01 02 09 01 02 09 01 01 01 01 02 09 00
+GetLightingOutputMode request                          04 20 09 01 00
+GetLightingOutputs reply                               04 08 09 01 01 08 01 01 01 01 02 28 14 01 00
+GetLightingOutputs request                             05 08 09 01 01 01 00
+GetLightingOverlay reply                               04 1b 09 01 01 11 09 01 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
+GetLightingOverlay request                             05 1b 09 01 09 01 00
+GetLightingPhysicalKeys reply                          04 04 09 01 01 12 01 01 01 01 02 ff 01 80 04 80 01 80 02 80 03 db 0b 00
+GetLightingPhysicalKeys request                        05 04 09 01 01 01 00
+GetLightingRoutes reply                                04 09 09 01 01 08 01 01 01 2a 01 02 07 00
+GetLightingRoutes request                              05 09 09 01 01 01 00
+GetLightingRuntimeConditionalSceneStatus reply         04 25 09 01 01 05 09 40 01 08 00
+GetLightingRuntimeConditionalSceneStatus request       04 25 09 01 00
+GetLightingRuntimeConditionalScenes reply              04 26 09 01 01 0f 09 01 01 01 02 01 01 01 01 14 01 50 02 2a 04 07 08 09 00
+GetLightingRuntimeConditionalScenes request            05 26 09 01 09 01 00
+GetLightingSceneStatus reply                           04 12 09 01 01 07 09 80 02 01 01 08 00
+GetLightingSceneStatus request                         04 12 09 01 00
+GetLightingScenes reply                                04 13 09 01 01 06 09 01 01 02 2a 04 07 08 09 00
+GetLightingScenes request                              05 13 09 01 09 01 00
+GetLightingState reply                                 04 02 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+GetLightingState request                               04 02 09 01 00
+GetLightingZoneMemberships reply                       04 07 09 01 01 05 01 01 01 04 00
+GetLightingZoneMemberships request                     05 07 09 01 01 01 00
+GetLightingZones reply                                 04 06 09 01 01 0b 01 01 01 04 05 74 68 75 6d 62 00
+GetLightingZones request                               05 06 09 01 01 01 00
+LightingChange topic                                   03 07 80 01 00
+PutLightingOverlayChunk inner Err(TransactionExpired)  04 0e 09 01 03 01 0a 00
+PutLightingOverlayChunk reply                          04 0e 09 01 01 01 00
+PutLightingOverlayChunk request                        05 0e 09 01 0d 0f 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
+PutLightingRuntimeConditionalSceneChunk reply          04 28 09 01 01 01 00
+PutLightingRuntimeConditionalSceneChunk request        05 28 09 01 1f 0d 01 01 02 01 01 01 01 14 01 50 02 2a 04 07 08 09 00
+PutLightingSceneChunk reply                            04 17 09 01 01 01 00
+PutLightingSceneChunk request                          05 17 09 01 15 04 01 02 2a 04 07 08 09 00
+SetLightingExtensionState reply                        04 23 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingExtensionState request                      09 23 09 01 09 01 02 03 04 00
+SetLightingLayerPolicy reply                           04 1a 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingLayerPolicy request                         05 1a 09 01 0b 01 00
+SetLightingOutputMode reply                            04 24 09 01 01 03 02 01 09 01 01 01 0d 01 02 01 2a 01 02 09 01 02 09 01 01 01 01 02 09 00
+SetLightingOutputMode request                          06 24 09 01 09 01 00
+SetLightingOverlay inner Err(UnknownLed)               04 0a 09 01 05 01 06 e7 07 00
+SetLightingOverlay outer Err(Locked)                   06 0a 09 01 01 07 00
+SetLightingOverlay reply                               04 0a 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingOverlay request                             12 0a 09 01 09 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
+SetLightingSceneCell inner Err(SceneFull)              04 14 09 01 05 01 0d 80 02 00
+SetLightingSceneCell inner Err(UnknownLayer)           04 14 09 01 04 01 0c c8 00
+SetLightingSceneCell reply                             04 14 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingSceneCell request                           07 14 09 01 09 02 2a 04 07 08 09 00
+SetLightingState reply                                 04 03 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingState request                               0d 03 09 01 08 01 c8 01 0a 14 1e 28 01 00
+UnsetLightingOverlay reply                             04 0b 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+UnsetLightingOverlay request                           06 0b 09 01 0a 2a 00
+UnsetLightingSceneCell reply                           04 15 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+UnsetLightingSceneCell request                         07 15 09 01 0a 02 2a 00
diff --git a/rmk-types/src/protocol/rynk/snapshots/split_ble_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/split_ble_wire_frames.snap
index bbac86a0d..4571c29f9 100644
--- a/rmk-types/src/protocol/rynk/snapshots/split_ble_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/split_ble_wire_frames.snap
@@ -4,8 +4,8 @@
 #   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk --features "rynk _ble split" split_ble_wire_frames
 # Format: <label>  <hex bytes>
 
-GetSplitCentralLatency reply Ok(state)     06 07 01 07 00 00 00 04 01 02 01 02
-GetSplitCentralLatency request ()          06 07 01 00 00
-SetSplitCentralLatency reply Err(Invalid)  07 07 01 02 00 01 05
-SetSplitCentralLatency reply Ok(state)     07 07 01 07 00 00 00 04 01 02 01 02
-SetSplitCentralLatency request policy      07 07 01 04 00 00 04 01 02
+GetSplitCentralLatency reply Ok(state)     04 06 07 01 01 06 04 01 02 01 02 00
+GetSplitCentralLatency request ()          04 06 07 01 00
+SetSplitCentralLatency reply Err(Invalid)  06 07 07 01 01 05 00
+SetSplitCentralLatency reply Ok(state)     04 07 07 01 01 06 04 01 02 01 02 00
+SetSplitCentralLatency request policy      04 07 07 01 04 04 01 02 00
diff --git a/rmk-types/src/protocol/rynk/snapshots/wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/wire_frames.snap
index ff7ed6bdf..3372d7023 100644
--- a/rmk-types/src/protocol/rynk/snapshots/wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/wire_frames.snap
@@ -3,7 +3,7 @@
 # Each entry is a full Rynk frame — a 3-byte header (CMD u16 LE + SEQ u8) + postcard
 # payload, COBS-encoded with a trailing 0x00 delimiter — one per protocol message; the
 # label names the decoded payload (`()` = empty). A diff means the header, a CMD number,
-# or a message frame changed. If intentional, bump ProtocolVersion::CURRENT and regenerate:
+# or a message frame changed. If intentional, regenerate and review protocol compatibility:
 #   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk wire_frames
 # Format: <label>  <hex bytes>
 
@@ -12,6 +12,8 @@ BootloaderJump request ()                                               02 04 02
 ConnectionChange topic ConnectionStatus{Configured,{1,Adv},Ble}         03 03 80 03 02 01 02 01 00
 GetBehaviorConfig reply Ok(BehaviorConfig{50,500,200,20})               04 01 06 01 07 32 f4 03 c8 01 14 00
 GetBehaviorConfig request ()                                            04 01 06 01 00
+GetBuildInfo reply Ok(BuildInfo{my-firmware..})                         02 0b 02 01 21 1f 6d 79 2d 66 69 72 6d 77 61 72 65 20 76 34 2e 35 2e 36 20 2f 20 52 4d 4b 20 76 31 2e 32 2e 33 00
+GetBuildInfo request ()                                                 02 0b 02 01 00
 GetCapabilities reply Ok(DeviceCapabilities{1..16})                     02 02 02 01 0c 01 02 03 04 05 06 07 08 09 0a 01 03 01 0b 07 0c 0d 0e 0f 10 01 00
 GetCapabilities request ()                                              02 02 02 01 00
 GetCombo reply Ok(Combo{[Single(A)],Morse(1),L2})                       04 01 03 01 04 01 02 01 06 04 05 01 01 02 00
@@ -32,6 +34,8 @@ GetFork reply Ok(Fork{Single(A),No,Morse(2)})                           04 01 05
 GetFork request 2                                                       05 01 05 01 02 00
 GetKeyAction reply Ok(Morse(7))                                         04 01 01 01 03 05 07 00
 GetKeyAction request KeyPosition{0,5,13}                                04 01 01 01 03 05 0d 00
+GetLayerState reply Ok(LayerState{default:2,active:[0x05,..,0x80]})     04 08 08 01 03 02 05 01 01 01 01 01 02 80 00
+GetLayerState request ()                                                04 08 08 01 00
 GetLedIndicator reply Ok(LedIndicator(Num|Scroll))                      04 07 08 01 02 05 00
 GetLedIndicator request ()                                              04 07 08 01 00
 GetLockStatus reply Ok(LockStatus{true,false,2,[(1,2),(3,4)]})          02 06 02 01 02 01 07 02 02 01 02 03 04 00
@@ -40,6 +44,8 @@ GetMacro reply Ok(MacroData{[0x01,0x02,0x03]})                          04 01 02
 GetMacro request GetMacroRequest{256}                                   06 01 02 01 80 02 00
 GetMatrixState reply Ok(MatrixState{[0x05,0x00,0x20]})                  04 02 08 01 03 03 05 02 20 00
 GetMatrixState request ()                                               04 02 08 01 00
+GetModifierState reply Ok(ModifierCombination(LShift|RAlt))             04 09 08 01 02 42 00
+GetModifierState request ()                                             04 09 08 01 00
 GetMorse reply Ok(Morse{TAP->Key(A)})                                   04 01 04 01 01 04 01 02 01 02 04 00
 GetMorse request 0                                                      04 01 04 01 01 00
 GetSleepState reply Ok(true)                                            04 06 08 01 02 01 00
@@ -52,6 +58,9 @@ LayerChange topic 3                                                     03 01 80
 LedIndicatorChange topic LedIndicator(Num|Scroll)                       03 05 80 02 05 00
 Lock reply Ok(())                                                       02 08 02 01 01 00
 Lock request ()                                                         02 08 02 01 00
+ModifierChange topic ModifierCombination(LShift|RAlt)                   03 08 80 02 42 00
+PeripheralBootloaderJump reply Ok(())                                   02 0c 02 01 01 00
+PeripheralBootloaderJump request slot 1                                 02 0c 03 01 01 00
 Reboot reply Ok(())                                                     02 03 02 01 01 00
 Reboot request ()                                                       02 03 02 01 00
 SetBehaviorConfig reply Ok(())                                          04 02 06 01 01 00
diff --git a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
index 957469293..c166bcc08 100644
--- a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
@@ -6,87 +6,90 @@
 #   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk wire_values
 # Format: <label>  <hex bytes>
 
-Action::DefaultLayer(5)                   08 05
-Action::Key(Hid(A))                       01 00 04
-Action::KeyWithModifier(A,LShift)         03 04 02
-Action::KeyboardControl(Bootloader)       11 00
-Action::LayerOff(3)                       06 03
-Action::LayerOn(1)                        04 01
-Action::LayerOnWithModifier(2,LCtrl)      05 02 01
-Action::LayerToggle(4)                    07 04
-Action::LayerToggleOnly(6)                09 06
-Action::Light(RgbTog)                     10 07
-Action::Modifier(LCtrl)                   02 01
-Action::No                                00
-Action::OneShotKey(Hid(B))                0f 05
-Action::OneShotLayer(8)                   0d 08
-Action::OneShotModifier(LAlt)             0e 04
-Action::Special(GraveEscape)              12 00
-Action::TriLayerLower                     0a
-Action::TriLayerUpper                     0b
-Action::TriggerMacro(7)                   0c 07
-Action::User(9)                           13 09
-BatteryStatus::Available{Discharging,85}  01 01 01 55
-BatteryStatus::Unavailable                00
-BehaviorConfig{50,500,200,20}             32 f4 03 c8 01 14
-BleState::Advertising                     00
-BleState::Connected                       01
-BleState::Inactive                        02
-BleStatus{2,Connected}                    02 01
-BuildInfo{my-firmware..}                  1f 6d 79 2d 66 69 72 6d 77 61 72 65 20 76 34 2e 35 2e 36 20 2f 20 52 4d 4b 20 76 31 2e 32 2e 33
-ChargeState::Charging                     00
-ChargeState::Discharging                  01
-ChargeState::Unknown                      02
-Combo{[Single(A)],Morse(1),L2}            01 02 01 00 04 05 01 01 02
-ConnectionStatus{Configured,{1,Adv},Ble}  02 01 00 01
-ConnectionType::Ble                       01
-ConnectionType::Usb                       00
-DeviceCapabilities{1..16}                 01 02 03 04 05 06 07 08 09 0a 01 00 01 0b 00 0c 0d 0e 0f 10 01
-DeviceInfo{1.2.3,4,5,RMK,..}              01 02 03 04 05 03 52 4d 4b 0c 52 4d 4b 20 4b 65 79 62 6f 61 72 64 09 72 79 6e 6b 3a 30 30 30 31
-EncoderAction{Morse(3),No}                05 03 00
-Fork{Single(A),No,Morse(2)}               02 01 00 04 00 05 02 01 02 01 00 00 00 02 01
-GetEncoderRequest{1,2}                    01 02
-GetMacroRequest{256}                      80 02
-KeyAction::Morse(3)                       05 03
-KeyAction::No                             00
-KeyAction::Single(Action::Key(Hid(A)))    02 01 00 04
-KeyAction::Tap(Action::No)                03 00
-KeyAction::TapHold(Key(A),LayerOn(3))     04 01 00 04 04 03 ff
-KeyAction::Transparent                    01
-KeyCode::Consumer(VolumeIncrement)        01 12
-KeyCode::Hid(A)                           00 04
-KeyCode::SystemControl(Sleep)             02 02
-KeyPosition{layer:0,row:5,col:13}         00 05 0d
-LedIndicator(Num|Scroll)                  05
-LockStatus{true,false,2,[(1,2),(3,4)]}    01 00 02 02 01 02 03 04
-MacroData{[0x01,0x02,0x03]}               03 01 02 03
-MatrixState{[0x05,0x00,0x20]}             03 05 00 20
-ModifierCombination(LCtrl|RGui)           81
-MorseProfile(Normal,200,150)              c8 81 b0 89 0c
-Morse{TAP->Key(A)}                        00 01 02 01 00 04
-MouseButtons(B1|B8)                       81
-ProtocolVersion::CURRENT                  00 04
-ProtocolVersion{1,0}                      01 00
-Result<(),RynkError>::Err(StorageFault)   01 02
-Result<(),RynkError>::Ok                  00
-RynkError::Internal                       03
-RynkError::Invalid                        05
-RynkError::Locked                         07
-RynkError::Malformed                      00
-RynkError::NotReady                       01
-RynkError::StorageFault                   02
-RynkError::Unimplemented                  04
-RynkError::UnknownCmd                     06
-SetComboRequest{3,combo}                  03 01 02 01 00 04 05 01 01 02
-SetEncoderRequest{1,2,{Morse(3),No}}      01 02 05 03 00
-SetForkRequest{2,fork}                    02 02 01 00 04 00 05 02 01 02 01 00 00 00 02 01
-SetKeyRequest{{0,5,13},Morse(7)}          00 05 0d 05 07
-SetMacroRequest{2,[0x01,0x02,0x03]}       02 03 01 02 03
-SetMorseRequest{0,morse}                  00 00 01 02 01 00 04
-StateBits{LCtrl,Caps,B1}                  01 02 01
-StorageResetMode::Full                    00
-StorageResetMode::LayoutOnly              01
-UsbState::Configured                      02
-UsbState::Disabled                        00
-UsbState::Enabled                         01
-UsbState::Suspended                       03
+Action::DefaultLayer(5)                      08 05
+Action::Key(Hid(A))                          01 00 04
+Action::KeyWithModifier(A,LShift)            03 04 02
+Action::KeyboardControl(Bootloader)          11 00
+Action::LayerOff(3)                          06 03
+Action::LayerOn(1)                           04 01
+Action::LayerOnWithModifier(2,LCtrl)         05 02 01
+Action::LayerToggle(4)                       07 04
+Action::LayerToggleOnly(6)                   09 06
+Action::Light(RgbTog)                        10 07
+Action::Modifier(LCtrl)                      02 01
+Action::No                                   00
+Action::OneShotKey(Hid(B))                   0f 05
+Action::OneShotLayer(8)                      0d 08
+Action::OneShotModifier(LAlt)                0e 04
+Action::Special(GraveEscape)                 12 00
+Action::TriLayerLower                        0a
+Action::TriLayerUpper                        0b
+Action::TriggerMacro(7)                      0c 07
+Action::User(9)                              13 09
+BatteryStatus::Available{Discharging,85}     01 01 01 55
+BatteryStatus::Unavailable                   00
+BehaviorConfig{50,500,200,20}                32 f4 03 c8 01 14
+BleState::Advertising                        00
+BleState::Connected                          01
+BleState::Inactive                           02
+BleStatus{2,Connected}                       02 01
+BuildInfo{my-firmware..}                     1f 6d 79 2d 66 69 72 6d 77 61 72 65 20 76 34 2e 35 2e 36 20 2f 20 52 4d 4b 20 76 31 2e 32 2e 33
+ChargeState::Charging                        00
+ChargeState::Discharging                     01
+ChargeState::Unknown                         02
+Combo{[Single(A)],Morse(1),L2}               01 02 01 00 04 05 01 01 02
+ConnectionStatus{Configured,{1,Adv},Ble}     02 01 00 01
+ConnectionType::Ble                          01
+ConnectionType::Usb                          00
+DeviceCapabilities{1..16}                    01 02 03 04 05 06 07 08 09 0a 01 00 01 0b 00 0c 0d 0e 0f 10 01
+DeviceInfo{1.2.3,4,5,RMK,..}                 01 02 03 04 05 03 52 4d 4b 0c 52 4d 4b 20 4b 65 79 62 6f 61 72 64 09 72 79 6e 6b 3a 30 30 30 31
+EncoderAction{Morse(3),No}                   05 03 00
+Fork{Single(A),No,Morse(2)}                  02 01 00 04 00 05 02 01 02 01 00 00 00 02 01
+GetEncoderRequest{1,2}                       01 02
+GetMacroRequest{256}                         80 02
+KeyAction::Morse(3)                          05 03
+KeyAction::No                                00
+KeyAction::Single(Action::Key(Hid(A)))       02 01 00 04
+KeyAction::Tap(Action::No)                   03 00
+KeyAction::TapHold(Key(A),LayerOn(3))        04 01 00 04 04 03 ff
+KeyAction::Transparent                       01
+KeyCode::Consumer(VolumeIncrement)           01 12
+KeyCode::Hid(A)                              00 04
+KeyCode::SystemControl(Sleep)                02 02
+KeyPosition{layer:0,row:5,col:13}            00 05 0d
+LayerState{default:2,active:[0x05,..,0x80]}  02 05 00 00 00 00 00 00 80
+LedIndicator(Num|Scroll)                     05
+LockStatus{true,false,2,[(1,2),(3,4)]}       01 00 02 02 01 02 03 04
+MacroData{[0x01,0x02,0x03]}                  03 01 02 03
+MatrixState{[0x05,0x00,0x20]}                03 05 00 20
+ModifierCombination(LCtrl|RGui)              81
+MorseProfile(Normal,200,150)                 c8 81 b0 89 0c
+Morse{TAP->Key(A)}                           00 01 02 01 00 04
+MouseButtons(B1|B8)                          81
+ProtocolVersion::CURRENT                     00 01
+ProtocolVersion{1,0}                         01 00
+Result<(),RynkError>::Err(StorageFault)      01 02
+Result<(),RynkError>::Ok                     00
+RynkError::Internal                          03
+RynkError::Invalid                           05
+RynkError::Locked                            07
+RynkError::Malformed                         00
+RynkError::NotReady                          01
+RynkError::StorageFault                      02
+RynkError::Unimplemented                     04
+RynkError::UnknownCmd                        06
+SetComboRequest{3,combo}                     03 01 02 01 00 04 05 01 01 02
+SetEncoderRequest{1,2,{Morse(3),No}}         01 02 05 03 00
+SetForkRequest{2,fork}                       02 02 01 00 04 00 05 02 01 02 01 00 00 00 02 01
+SetKeyRequest{{0,5,13},Morse(7)}             00 05 0d 05 07
+SetMacroRequest{2,[0x01,0x02,0x03]}          02 03 01 02 03
+SetMorseRequest{0,morse}                     00 00 01 02 01 00 04
+SplitLatencyPolicy{0,4,Some(2)}              00 04 01 02
+SplitLatencyState{policy,true,2}             00 04 01 02 01 02
+StateBits{LCtrl,Caps,B1}                     01 02 01
+StorageResetMode::Full                       00
+StorageResetMode::LayoutOnly                 01
+UsbState::Configured                         02
+UsbState::Disabled                           00
+UsbState::Enabled                            01
+UsbState::Suspended                          03

From a8d58b8d2cb0abe4550bb9ee31eb241dfbe2e289 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 28 Jul 2026 16:33:16 -0700
Subject: [PATCH 35/78] fix: adapt glove80 rynk/lighting stack to COBS framing

The upstream COBS rework removed RynkMessage::build and header length
peeking. Route HID report bytes straight into the service (padding zeros
are inter-frame delimiters for the deframer), rebuild the lighting
handler test helper on from_decoded + Deframer, and dedupe merged
imports.
---
 rmk/src/host/rynk/handlers/lighting.rs | 20 +++++++++++++++++---
 rmk/src/host/rynk/handlers/system.rs   |  2 +-
 rmk/src/usb/rynk.rs                    | 17 ++++-------------
 3 files changed, 22 insertions(+), 17 deletions(-)

diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 75defd323..52921d097 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -1382,10 +1382,24 @@ mod tests {
         E::Request: Serialize,
         E::Response: DeserializeOwned + Debug,
     {
+        use rmk_types::protocol::rynk::{Deframer, RYNK_HEADER_SIZE, RynkHeader, RynkMessage};
+
         let mut buffer = Box::new([0u8; rmk_types::constants::RYNK_BUFFER_SIZE]);
-        let mut message = RynkMessage::build(&mut buffer[..], E::CMD, 1, request).unwrap();
-        service.dispatch(session, &mut message).await;
-        postcard::from_bytes(message.payload()).unwrap()
+        // Build the decoded logical frame the dispatcher expects: 3-byte
+        // header + postcard payload.
+        let header = RynkHeader { cmd: E::CMD, seq: 1 };
+        buffer[..RYNK_HEADER_SIZE].copy_from_slice(&header.to_bytes());
+        let payload_len = postcard::to_slice(request, &mut buffer[RYNK_HEADER_SIZE..]).unwrap().len();
+        let req_len = RYNK_HEADER_SIZE + payload_len;
+        let mut message = RynkMessage::from_decoded(&mut buffer[..], req_len);
+        service.dispatch(session, &mut message).await.unwrap();
+        // The reply is COBS-framed in place; deframe it back to [cmd, seq, payload].
+        let mut reply = message.frame().to_vec();
+        let framed_len = reply.len();
+        let mut deframer = Deframer::new();
+        deframer.commit(framed_len);
+        let decoded_len = deframer.next(&mut reply).expect("framed reply");
+        postcard::from_bytes(&reply[RYNK_HEADER_SIZE..decoded_len]).unwrap()
     }
 
     fn overlay_cell(id: u16) -> LightingOverlayCell {
diff --git a/rmk/src/host/rynk/handlers/system.rs b/rmk/src/host/rynk/handlers/system.rs
index a3123165b..3c7504181 100644
--- a/rmk/src/host/rynk/handlers/system.rs
+++ b/rmk/src/host/rynk/handlers/system.rs
@@ -6,7 +6,7 @@ use rmk_types::protocol::rynk::command::{
     PeripheralBootloaderJump, Reboot, StorageReset, UnlockPoll,
 };
 use rmk_types::protocol::rynk::{
-    BuildInfo, DEVICE_INFO_STRING_SIZE, DeviceCapabilities, DeviceInfo, LockStatus, MAX_BULK_ITEMS, MAX_BULK_KEYS,
+    BuildInfo, DeviceCapabilities, DeviceInfo, LockStatus, MAX_BULK_ITEMS, MAX_BULK_KEYS,
     ProtocolVersion, RYNK_MAX_PAYLOAD_SIZE, RynkError, StorageResetMode,
 };
 
diff --git a/rmk/src/usb/rynk.rs b/rmk/src/usb/rynk.rs
index 5938c4de3..3a8ba529c 100644
--- a/rmk/src/usb/rynk.rs
+++ b/rmk/src/usb/rynk.rs
@@ -1,14 +1,14 @@
 //! Rynk over USB HID.
 //!
 //! Rynk frames are fragmented into the same fixed 32-byte reports used by
-//! Rynk's BLE WebHID transport. The frame header's length trims padding from
-//! the final report before the byte stream reaches `RynkService`.
+//! Rynk's BLE WebHID transport. Report padding is zero bytes, which the COBS
+//! deframer inside `RynkService` treats as inter-frame delimiters.
 
 use embassy_usb::Builder;
 use embassy_usb::class::hid::{HidReader, HidWriter};
 use embassy_usb::driver::Driver;
 use embedded_io_async::{ErrorType, Read, Write};
-use rmk_types::protocol::rynk::{RYNK_HID_REPORT_SIZE, RynkHeader};
+use rmk_types::protocol::rynk::RYNK_HID_REPORT_SIZE;
 
 use crate::hid::RynkHidReport;
 use crate::host::rynk::RynkService;
@@ -42,7 +42,6 @@ struct RynkUsbRx<'a, D: Driver<'static>> {
     report: [u8; RYNK_HID_REPORT_SIZE],
     pos: usize,
     end: usize,
-    remaining: usize,
 }
 
 impl<'a, D: Driver<'static>> RynkUsbRx<'a, D> {
@@ -52,7 +51,6 @@ impl<'a, D: Driver<'static>> RynkUsbRx<'a, D> {
             report: [0; RYNK_HID_REPORT_SIZE],
             pos: 0,
             end: 0,
-            remaining: 0,
         }
     }
 }
@@ -79,15 +77,8 @@ impl<D: Driver<'static>> Read for RynkUsbRx<'_, D> {
                 .read(&mut self.report)
                 .await
                 .map_err(|_| HostTransportError)?;
-            if self.remaining == 0 {
-                let Some(frame_len) = RynkHeader::peek_frame_len(&self.report[..n]) else {
-                    continue;
-                };
-                self.remaining = frame_len;
-            }
             self.pos = 0;
-            self.end = self.remaining.min(n);
-            self.remaining -= self.end;
+            self.end = n;
         }
     }
 }

From 54c3b4bb2d82e8f1ce161468eba1c67af7645cd3 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 29 Jul 2026 01:06:16 -0700
Subject: [PATCH 36/78] feat(lighting): generic per-effect extension parameters
 over rynk

An animated extension source may now advertise, per effect, a small list
of named u8 parameters with min/max/default bounds. Hosts discover them
and render generic controls; nothing in rmk knows what any parameter
means.

Protocol (rmk-types):
- LightingExtensionParam pairs a parameter's static descriptor with the
  source's live value so one read populates a control.
- LightingExtensionParamsRequest/Page page an effect's list, revision-
  pinned like every other mutable lighting read.
- SetLightingExtensionParamRequest sets one ordinal with optimistic
  concurrency.
- GetLightingExtensionParams = 0x092B, SetLightingExtensionParam = 0x092C.

Engine (rmk):
- ExtensionDescriptor gains `params`, a per-effect slice indexed like
  `effects`; a shorter tail simply means "no parameters".
- LightingSource gains defaulted `extension_param` and
  `apply_extension_param`; declining leaves the source untouched, so a
  rejected set stays atomic.
- The standard engine validates the address and the spec's bounds before
  offering the value to the source, and advances the revision plus a
  re-render only on acceptance. Unknown effect/ordinal and out-of-range
  values decline exactly like an out-of-range extension state.

Parameters are addressed per effect, not per active effect: a host may
tune an effect it is not currently displaying.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../main/docs/development/rynk_protocol.md    |   2 +
 rmk-types/src/protocol/rynk/command.rs        |  22 +-
 .../src/protocol/rynk/payload/lighting.rs     | 122 +++++++++
 .../rynk/snapshots/lighting_wire_frames.snap  |   4 +
 rmk-types/src/protocol/rynk/tests.rs          |  42 +++
 rmk/src/host/rynk/handlers/lighting.rs        |  62 ++++-
 rmk/src/host/rynk/lighting.rs                 | 252 +++++++++++++++++-
 rmk/src/host/rynk/mod.rs                      |   5 +
 rmk/src/lighting/compositor.rs                |  43 +++
 rmk/src/lighting/standard.rs                  |  93 ++++++-
 10 files changed, 625 insertions(+), 22 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 4136d7f82..9f5f54624 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -120,6 +120,8 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x0928` | `PutLightingRuntimeConditionalSceneChunk`      | `PutLightingRuntimeConditionalSceneChunkRequest`      | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
 | `0x0929` | `CommitLightingRuntimeConditionalSceneReplace` | `CommitLightingRuntimeConditionalSceneReplaceRequest` | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
 | `0x092A` | `AbortLightingRuntimeConditionalSceneReplace`  | `AbortLightingRuntimeConditionalSceneReplaceRequest`  | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
+| `0x092B` | `GetLightingExtensionParams`                   | `LightingExtensionParamsRequest`                      | `LightingExtensionParamsPageResult`                | `lighting`       | Per-effect tunable parameters: descriptors plus live values, pinned to `LightingState.revision`. Page until `total`.           |
+| `0x092C` | `SetLightingExtensionParam`                    | `SetLightingExtensionParamRequest`                    | `LightingStateResult`                              | `lighting`       | Set one effect parameter when the state revision matches.                                                                      |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index c2f7bb31c..3e282ff89 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -41,17 +41,18 @@ use crate::protocol::rynk::{
     CommitLightingOverlayReplaceRequest, CommitLightingRuntimeConditionalSceneReplaceRequest,
     CommitLightingSceneReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingCompiledSceneStatusResult,
     LightingCompiledScenesPageResult, LightingConditionalSceneStatusResult, LightingConditionalScenesPageResult,
-    LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionResult, LightingKeysPageResult,
-    LightingLedsPageResult, LightingOutputModeStateResult, LightingOutputsPageResult, LightingOverlayPageRequest,
-    LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKeysPageResult,
-    LightingRoutesPageResult, LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatusResult,
+    LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionParamsPageResult,
+    LightingExtensionParamsRequest, LightingExtensionResult, LightingKeysPageResult, LightingLedsPageResult,
+    LightingOutputModeStateResult, LightingOutputsPageResult, LightingOverlayPageRequest, LightingOverlayPageResult,
+    LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKeysPageResult, LightingRoutesPageResult,
+    LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatusResult,
     LightingRuntimeConditionalSceneTransactionResult, LightingRuntimeConditionalScenesPageResult,
     LightingScenePageRequest, LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult,
     LightingStateResult, LightingUnitResult, LightingZoneMembershipsPageResult, LightingZonesPageResult,
     PutLightingOverlayChunkRequest, PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest,
-    SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest, SetLightingOutputModeRequest,
-    SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest,
-    UnsetLightingSceneCellRequest,
+    SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
+    SetLightingOutputModeRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
+    UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 #[cfg(all(feature = "_ble", feature = "split"))]
 use crate::protocol::rynk::{SplitCentralLatencyPolicy, SplitCentralLatencyState};
@@ -477,6 +478,13 @@ endpoints! {
     CommitLightingRuntimeConditionalSceneReplace = 0x0929: CommitLightingRuntimeConditionalSceneReplaceRequest => LightingStateResult;
     #[cfg(feature = "lighting")]
     AbortLightingRuntimeConditionalSceneReplace = 0x092A: AbortLightingRuntimeConditionalSceneReplaceRequest => LightingUnitResult;
+    /// Per-effect tunable parameters: descriptors plus live values, pinned to
+    /// `LightingState.revision`. Page until `total`.
+    #[cfg(feature = "lighting")]
+    GetLightingExtensionParams = 0x092B: LightingExtensionParamsRequest => LightingExtensionParamsPageResult;
+    /// Set one effect parameter when the state revision matches.
+    #[cfg(feature = "lighting")]
+    SetLightingExtensionParam = 0x092C: SetLightingExtensionParamRequest => LightingStateResult;
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 766ea64db..1cc826fac 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -25,6 +25,8 @@ pub const LIGHTING_ZONE_NAME_SIZE: usize = 24;
 pub const LIGHTING_EXTENSION_NAME_SIZE: usize = 16;
 /// Number of names in one extension-names page.
 pub const LIGHTING_EXTENSION_NAME_CHUNK: usize = 8;
+/// Number of per-effect parameter rows in one extension-params page.
+pub const LIGHTING_EXTENSION_PARAM_CHUNK: usize = 8;
 
 macro_rules! wire_type {
     ($item:item) => {
@@ -756,6 +758,73 @@ wire_type! {
     }
 }
 
+/// One tunable parameter advertised by an extension effect: its static
+/// descriptor plus the source's live value. Descriptor and value travel in
+/// one row so a host can render a control from a single read.
+///
+/// Parameters are generic: firmware names them, bounds them, and applies
+/// them; the protocol ascribes no meaning to any particular name.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LightingExtensionParam {
+    #[cfg_attr(feature = "wasm", tsify(type = "string"))]
+    pub name: String<LIGHTING_EXTENSION_NAME_SIZE>,
+    pub min: u8,
+    pub max: u8,
+    pub default: u8,
+    pub value: u8,
+}
+
+impl MaxSize for LightingExtensionParam {
+    const POSTCARD_MAX_SIZE: usize =
+        crate::heapless_vec_max_size::<u8, LIGHTING_EXTENSION_NAME_SIZE>() + 4 * u8::POSTCARD_MAX_SIZE;
+}
+
+wire_type! {
+    /// Which effect's parameter list a page request addresses. `effect`
+    /// indexes the effect-name list served by `GetLightingExtensionNames`;
+    /// it need not be the active effect.
+    pub struct LightingExtensionParamsRequest {
+        pub effect: u8,
+        pub offset: u8,
+    }
+}
+
+/// One page of an effect's parameters. Unlike name pages these carry live
+/// values, so they are pinned to `LightingState.revision` like every other
+/// mutable lighting read.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LightingExtensionParamsPage {
+    pub revision: u32,
+    pub total: u8,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingExtensionParam[]"))]
+    pub items: Vec<LightingExtensionParam, LIGHTING_EXTENSION_PARAM_CHUNK>,
+}
+
+impl MaxSize for LightingExtensionParamsPage {
+    const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+        + u8::POSTCARD_MAX_SIZE
+        + crate::varint_max_size(LIGHTING_EXTENSION_PARAM_CHUNK)
+        + LIGHTING_EXTENSION_PARAM_CHUNK * LightingExtensionParam::POSTCARD_MAX_SIZE;
+}
+
+wire_type! {
+    /// Set one parameter of one effect. `index` is the ordinal within that
+    /// effect's parameter list. Setting a parameter of an inactive effect is
+    /// allowed if the source accepts it.
+    pub struct SetLightingExtensionParamRequest {
+        pub expected_revision: u32,
+        pub effect: u8,
+        pub index: u8,
+        pub value: u8,
+    }
+}
+
 wire_type! {
     pub struct LightingConditionalSceneStatus {
         pub topology_revision: u32,
@@ -986,6 +1055,7 @@ pub type LightingConditionalScenesPageResult = LightingResult<LightingConditiona
 pub type LightingOutputModeStateResult = LightingResult<LightingOutputModeState>;
 pub type LightingExtensionResult = LightingResult<LightingExtension>;
 pub type LightingExtensionNamesPageResult = LightingResult<LightingExtensionNamesPage>;
+pub type LightingExtensionParamsPageResult = LightingResult<LightingExtensionParamsPage>;
 pub type LightingSceneTransactionResult = LightingResult<LightingSceneTransaction>;
 pub type LightingRuntimeConditionalSceneStatusResult = LightingResult<LightingRuntimeConditionalSceneStatus>;
 pub type LightingRuntimeConditionalScenesPageResult = LightingResult<LightingRuntimeConditionalScenesPage>;
@@ -1036,6 +1106,8 @@ const _: () = {
     assert_endpoint_fits!((), LightingExtensionResult);
     assert_endpoint_fits!(LightingExtensionNamesRequest, LightingExtensionNamesPageResult);
     assert_endpoint_fits!(SetLightingExtensionStateRequest, LightingStateResult);
+    assert_endpoint_fits!(LightingExtensionParamsRequest, LightingExtensionParamsPageResult);
+    assert_endpoint_fits!(SetLightingExtensionParamRequest, LightingStateResult);
     assert_endpoint_fits!(SetLightingOutputModeRequest, LightingOutputModeStateResult);
     assert_endpoint_fits!((), LightingRuntimeConditionalSceneStatusResult);
     assert_endpoint_fits!(
@@ -1294,6 +1366,56 @@ mod tests {
         });
     }
 
+    #[test]
+    fn extension_param_types_round_trip() {
+        round_trip(&LightingExtensionParam {
+            name: String::try_from("Density").unwrap(),
+            min: 1,
+            max: 8,
+            default: 3,
+            value: 5,
+        });
+        round_trip(&LightingExtensionParamsRequest { effect: 0, offset: 0 });
+        round_trip(&LightingExtensionParamsRequest {
+            effect: u8::MAX,
+            offset: LIGHTING_EXTENSION_PARAM_CHUNK as u8,
+        });
+        round_trip(&SetLightingExtensionParamRequest {
+            expected_revision: u32::MAX,
+            effect: 2,
+            index: 1,
+            value: u8::MAX,
+        });
+    }
+
+    #[test]
+    fn maximum_extension_params_page_respects_bound() {
+        let mut items = Vec::new();
+        for _ in 0..LIGHTING_EXTENSION_PARAM_CHUNK {
+            let mut name = String::new();
+            for _ in 0..LIGHTING_EXTENSION_NAME_SIZE {
+                name.push('x').unwrap();
+            }
+            items
+                .push(LightingExtensionParam {
+                    name,
+                    min: 0,
+                    max: u8::MAX,
+                    default: u8::MAX,
+                    value: u8::MAX,
+                })
+                .unwrap();
+        }
+        let page = LightingExtensionParamsPage {
+            revision: u32::MAX,
+            total: u8::MAX,
+            items,
+        };
+        round_trip(&page);
+        assert_max_size_bound(&page);
+        assert!(LightingExtensionParamsPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+    }
+
     #[test]
     fn maximum_extension_names_page_respects_bound() {
         let mut items = Vec::new();
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index 6f74f5825..f9b46c35c 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -36,6 +36,8 @@ GetLightingExtension reply                             04 21 09 01 01 08 09 06 1
 GetLightingExtension request                           04 21 09 01 00
 GetLightingExtensionNames reply                        04 22 09 01 01 09 10 01 05 4f 63 65 61 6e 00
 GetLightingExtensionNames request                      06 22 09 01 01 08 00
+GetLightingExtensionParams reply                       04 2b 09 01 01 10 09 02 01 07 44 65 6e 73 69 74 79 01 08 03 05 00
+GetLightingExtensionParams request                     05 2b 09 01 01 01 00
 GetLightingKeys reply                                  04 11 09 01 01 06 01 01 01 01 02 00
 GetLightingKeys request                                05 11 09 01 01 01 00
 GetLightingLeds reply                                  04 05 09 01 01 11 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01 00
@@ -72,6 +74,8 @@ PutLightingRuntimeConditionalSceneChunk reply          04 28 09 01 01 01 00
 PutLightingRuntimeConditionalSceneChunk request        05 28 09 01 1f 0d 01 01 02 01 01 01 01 14 01 50 02 2a 04 07 08 09 00
 PutLightingSceneChunk reply                            04 17 09 01 01 01 00
 PutLightingSceneChunk request                          05 17 09 01 15 04 01 02 2a 04 07 08 09 00
+SetLightingExtensionParam reply                        04 2c 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingExtensionParam request                      06 2c 09 01 09 01 02 05 00
 SetLightingExtensionState reply                        04 23 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
 SetLightingExtensionState request                      09 23 09 01 09 01 02 03 04 00
 SetLightingLayerPolicy reply                           04 1a 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index ed0906230..3af145aed 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1340,6 +1340,24 @@ fn lighting_wire_frames_locked() {
         expected_revision: state.revision,
         state: extension.state,
     };
+    let extension_params_request = LightingExtensionParamsRequest { effect: 1, offset: 0 };
+    let extension_params_page = LightingExtensionParamsPage {
+        revision: state.revision,
+        total: 2,
+        items: one(LightingExtensionParam {
+            name: heapless::String::try_from("Density").unwrap(),
+            min: 1,
+            max: 8,
+            default: 3,
+            value: 5,
+        }),
+    };
+    let set_extension_param = SetLightingExtensionParamRequest {
+        expected_revision: state.revision,
+        effect: 1,
+        index: 0,
+        value: 5,
+    };
     let output_mode = LightingOutputModeState {
         mode: LightingOutputMode::PoweredOnly,
         powered: true,
@@ -1961,6 +1979,30 @@ fn lighting_wire_frames_locked() {
                 &Ok::<LightingStateResult, RynkError>(Ok(state))
             )
         ),
+        (
+            "GetLightingExtensionParams request",
+            encode_frame(Cmd::GetLightingExtensionParams, SEQ, &extension_params_request)
+        ),
+        (
+            "GetLightingExtensionParams reply",
+            encode_frame(
+                Cmd::GetLightingExtensionParams,
+                SEQ,
+                &Ok::<LightingExtensionParamsPageResult, RynkError>(Ok(extension_params_page))
+            )
+        ),
+        (
+            "SetLightingExtensionParam request",
+            encode_frame(Cmd::SetLightingExtensionParam, SEQ, &set_extension_param)
+        ),
+        (
+            "SetLightingExtensionParam reply",
+            encode_frame(
+                Cmd::SetLightingExtensionParam,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
         (
             "LightingChange topic",
             encode_frame(Cmd::LightingChange, 0, &LightingChanged)
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 52921d097..1c7c6d28c 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -6,10 +6,11 @@ use rmk_types::protocol::rynk::command::{
     AbortLightingRuntimeConditionalSceneReplace, BeginLightingRuntimeConditionalSceneReplace, ClearLightingOverlay,
     CommitLightingRuntimeConditionalSceneReplace, GetLightingCapabilities, GetLightingCompiledSceneStatus,
     GetLightingCompiledScenes, GetLightingConditionalSceneStatus, GetLightingConditionalScenes, GetLightingExtension,
-    GetLightingExtensionNames, GetLightingKeys, GetLightingLeds, GetLightingOutputMode, GetLightingOutputs,
-    GetLightingOverlay, GetLightingPhysicalKeys, GetLightingRoutes, GetLightingRuntimeConditionalSceneStatus,
-    GetLightingRuntimeConditionalScenes, GetLightingSceneStatus, GetLightingScenes, GetLightingState,
-    GetLightingZoneMemberships, GetLightingZones, PutLightingRuntimeConditionalSceneChunk, SetLightingExtensionState,
+    GetLightingExtensionNames, GetLightingExtensionParams, GetLightingKeys, GetLightingLeds, GetLightingOutputMode,
+    GetLightingOutputs, GetLightingOverlay, GetLightingPhysicalKeys, GetLightingRoutes,
+    GetLightingRuntimeConditionalSceneStatus, GetLightingRuntimeConditionalScenes, GetLightingSceneStatus,
+    GetLightingScenes, GetLightingState, GetLightingZoneMemberships, GetLightingZones,
+    PutLightingRuntimeConditionalSceneChunk, SetLightingExtensionParam, SetLightingExtensionState,
     SetLightingLayerPolicy, SetLightingOutputMode, SetLightingOverlay, SetLightingSceneCell, SetLightingState,
     UnsetLightingOverlay, UnsetLightingSceneCell,
 };
@@ -23,8 +24,9 @@ use rmk_types::protocol::rynk::{
     LightingCompiledSceneStatus, LightingCompiledSceneStatusResult, LightingCompiledScenesPageResult,
     LightingConditionalSceneCell, LightingConditionalSceneStatus, LightingConditionalSceneStatusResult,
     LightingConditionalScenesPage, LightingConditionalScenesPageResult, LightingEffectFlags, LightingError,
-    LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionResult, LightingFeatureFlags,
-    LightingKeysPage, LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
+    LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionParamsPageResult,
+    LightingExtensionParamsRequest, LightingExtensionResult, LightingFeatureFlags, LightingKeysPage,
+    LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
     LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage,
     LightingOutputModeStateResult, LightingOutputsPage, LightingOutputsPageResult, LightingOverlayCell,
     LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransaction,
@@ -37,9 +39,9 @@ use rmk_types::protocol::rynk::{
     LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage,
     LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult, PutLightingOverlayChunkRequest,
     PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, RynkError, RynkMessage,
-    SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest, SetLightingOutputModeRequest,
-    SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest, UnsetLightingOverlayRequest,
-    UnsetLightingSceneCellRequest,
+    SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
+    SetLightingOutputModeRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
+    UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 
 use super::super::lighting::{
@@ -717,6 +719,48 @@ impl Handle<SetLightingExtensionState> for RynkService<'_> {
     }
 }
 
+impl Handle<GetLightingExtensionParams> for RynkService<'_> {
+    async fn handle(
+        &self,
+        req: LightingExtensionParamsRequest,
+    ) -> Result<LightingExtensionParamsPageResult, RynkError> {
+        let result = match extension_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::ReadExtensionParams {
+                    effect: req.effect,
+                    offset: req.offset,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::ExtensionParamsPage(page)) => Ok(page),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<SetLightingExtensionParam> for RynkService<'_> {
+    async fn handle(&self, req: SetLightingExtensionParamRequest) -> Result<LightingStateResult, RynkError> {
+        let result = match extension_controller(self) {
+            Ok(controller) => {
+                controller
+                    .request_state(RynkLightingCommand::SetExtensionParam {
+                        expected_revision: req.expected_revision,
+                        effect: req.effect,
+                        index: req.index,
+                        value: req.value,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
 impl Handle<GetLightingKeys> for RynkService<'_> {
     async fn handle(&self, req: LightingPageRequest) -> Result<LightingKeysPageResult, RynkError> {
         Ok(controller(self).and_then(|binding| keys_page(binding, req)))
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index c55a51907..47500b01a 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -15,10 +15,11 @@ use embassy_sync::mutex::Mutex;
 use embassy_sync::signal::Signal;
 use heapless::{String, Vec};
 use rmk_types::protocol::rynk::{
-    LIGHTING_EXTENSION_NAME_CHUNK, LIGHTING_EXTENSION_NAME_SIZE, LIGHTING_OVERLAY_CHUNK_SIZE,
-    LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState, LightingCompiledScenesPage,
-    LightingConditionalSceneCell as WireConditionalSceneCell, LightingControls as WireLightingControls, LightingError,
-    LightingExtension, LightingExtensionNameKind, LightingExtensionNamesPage,
+    LIGHTING_EXTENSION_NAME_CHUNK, LIGHTING_EXTENSION_NAME_SIZE, LIGHTING_EXTENSION_PARAM_CHUNK,
+    LIGHTING_OVERLAY_CHUNK_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState,
+    LightingCompiledScenesPage, LightingConditionalSceneCell as WireConditionalSceneCell,
+    LightingControls as WireLightingControls, LightingError, LightingExtension, LightingExtensionNameKind,
+    LightingExtensionNamesPage, LightingExtensionParam, LightingExtensionParamsPage,
     LightingExtensionState as WireExtensionState, LightingLayerPolicy, LightingMutableState,
     LightingOutputMode as WireLightingOutputMode, LightingOutputModeIndicator as WireLightingOutputModeIndicator,
     LightingOutputModeState, LightingOverlayCell, LightingOverlayPage, LightingResult, LightingRgb8,
@@ -43,6 +44,10 @@ const _: () = core::assert!(
     OVERLAY_CHUNK_SIZE == LIGHTING_OVERLAY_CHUNK_SIZE,
     "engine overlay page must match the wire chunk so adapters forward pages unmodified"
 );
+const _: () = core::assert!(
+    crate::lighting::standard::EXTENSION_PARAM_CHUNK == LIGHTING_EXTENSION_PARAM_CHUNK,
+    "engine extension-param page must match the wire chunk so adapters forward pages unmodified"
+);
 
 /// Maximum number of cells staged by one Rynk overlay replacement.
 ///
@@ -247,6 +252,7 @@ pub enum RynkLightingReadback {
     SceneTransaction(LightingSceneTransaction),
     Extension(LightingExtension),
     ExtensionNamesPage(LightingExtensionNamesPage),
+    ExtensionParamsPage(LightingExtensionParamsPage),
     RuntimeConditionalScenesPage(LightingRuntimeConditionalScenesPage),
     RuntimeConditionalSceneTransaction(LightingRuntimeConditionalSceneTransaction),
     Unit,
@@ -426,6 +432,16 @@ pub(super) enum RynkLightingCommand {
         expected_revision: u32,
         state: WireExtensionState,
     },
+    ReadExtensionParams {
+        effect: u8,
+        offset: u8,
+    },
+    SetExtensionParam {
+        expected_revision: u32,
+        effect: u8,
+        index: u8,
+        value: u8,
+    },
     ReadRuntimeConditionalSceneStatus,
     ReadRuntimeConditionalScenes {
         expected_revision: u32,
@@ -847,6 +863,43 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                     speed: state.speed,
                 },
             },
+            RynkLightingCommand::ReadExtensionParams { effect, offset } => {
+                let page = match self
+                    .request_core(StandardCommand::ReadExtensionParams { effect, offset })
+                    .await?
+                {
+                    StandardReply::ExtensionParams(page) => page,
+                    _ => return Err(LightingError::InvalidRequest),
+                };
+                let mut items: Vec<LightingExtensionParam, LIGHTING_EXTENSION_PARAM_CHUNK> = Vec::new();
+                for entry in page.items() {
+                    items
+                        .push(LightingExtensionParam {
+                            name: super::truncated(entry.spec.name),
+                            min: entry.spec.min,
+                            max: entry.spec.max,
+                            default: entry.spec.default,
+                            value: entry.value,
+                        })
+                        .map_err(|_| LightingError::InvalidRequest)?;
+                }
+                return Ok(RynkLightingReadback::ExtensionParamsPage(LightingExtensionParamsPage {
+                    revision: page.revision,
+                    total: page.total,
+                    items,
+                }));
+            }
+            RynkLightingCommand::SetExtensionParam {
+                expected_revision,
+                effect,
+                index,
+                value,
+            } => StandardCommand::SetExtensionParamIfRevision {
+                expected_revision,
+                effect,
+                index,
+                value,
+            },
             RynkLightingCommand::ReadRuntimeConditionalSceneStatus => {
                 let state = self.request_core_state(StandardCommand::ReadState).await?;
                 return Ok(RynkLightingReadback::RuntimeConditionalSceneStatus {
@@ -1563,10 +1616,28 @@ mod tests {
     static TEST_EFFECT_NAMES: &[&str] = &["Gradient", "Flow", "ABCDEFGHIJKLMNOé tail"];
     static TEST_PALETTE_NAMES: &[&str] = &["P0", "P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8", "P9"];
     static TOO_MANY_EFFECT_NAMES: [&str; 256] = ["Effect"; 256];
+    /// Effect 0 advertises parameters; the remaining effects do not, and the
+    /// outer slice is deliberately shorter than `TEST_EFFECT_NAMES` so the
+    /// "missing tail means no parameters" rule is exercised.
+    static TEST_EFFECT_PARAMS: &[&[crate::lighting::compositor::ExtensionParamSpec]] = &[&[
+        crate::lighting::compositor::ExtensionParamSpec {
+            name: "Density",
+            min: 1,
+            max: 8,
+            default: 3,
+        },
+        crate::lighting::compositor::ExtensionParamSpec {
+            name: "Fade",
+            min: 0,
+            max: 255,
+            default: 128,
+        },
+    ]];
 
     /// Zero-target source whose only job is serving the extension hooks.
     struct TestExtensionSource {
         state: crate::lighting::compositor::ExtensionState,
+        params: [u8; 2],
     }
 
     impl<Context> crate::lighting::compositor::LightingSource<Rgb8, Context> for TestExtensionSource {
@@ -1594,6 +1665,7 @@ mod tests {
             Some(crate::lighting::compositor::ExtensionDescriptor {
                 effects: TEST_EFFECT_NAMES,
                 palettes: TEST_PALETTE_NAMES,
+                params: TEST_EFFECT_PARAMS,
             })
         }
 
@@ -1605,6 +1677,26 @@ mod tests {
             self.state = state;
             true
         }
+
+        fn extension_param(&self, effect: u8, index: u8) -> Option<u8> {
+            if effect != 0 {
+                return None;
+            }
+            self.params.get(index as usize).copied()
+        }
+
+        fn apply_extension_param(&mut self, effect: u8, index: u8, value: u8) -> bool {
+            if effect != 0 {
+                return false;
+            }
+            match self.params.get_mut(index as usize) {
+                Some(slot) => {
+                    *slot = value;
+                    true
+                }
+                None => false,
+            }
+        }
     }
 
     struct TooManyNamesSource(TestExtensionSource);
@@ -1634,6 +1726,7 @@ mod tests {
             Some(crate::lighting::compositor::ExtensionDescriptor {
                 effects: &TOO_MANY_EFFECT_NAMES,
                 palettes: TEST_PALETTE_NAMES,
+                params: &[],
             })
         }
 
@@ -1699,6 +1792,7 @@ mod tests {
                     value: 128,
                     speed: 20,
                 },
+                params: [3, 128],
             },
             async |protocol| {
                 let extension = match protocol.request(RynkLightingCommand::ReadExtension).await {
@@ -1801,6 +1895,142 @@ mod tests {
         );
     }
 
+    #[test]
+    fn extension_param_flow_reads_pages_sets_values_and_rejects_bad_addresses() {
+        run_extension_flow(
+            TestExtensionSource {
+                state: crate::lighting::compositor::ExtensionState {
+                    effect: 0,
+                    palette: 1,
+                    value: 128,
+                    speed: 20,
+                },
+                params: [3, 128],
+            },
+            async |protocol| {
+                let page = match protocol
+                    .request(RynkLightingCommand::ReadExtensionParams { effect: 0, offset: 0 })
+                    .await
+                {
+                    Ok(RynkLightingReadback::ExtensionParamsPage(page)) => page,
+                    other => panic!("expected params readback, got {other:?}"),
+                };
+                assert_eq!(page.revision, 0);
+                assert_eq!(page.total, 2);
+                assert_eq!(page.items.len(), 2);
+                assert_eq!(page.items[0].name.as_str(), "Density");
+                assert_eq!((page.items[0].min, page.items[0].max, page.items[0].default), (1, 8, 3));
+                assert_eq!(page.items[0].value, 3);
+                assert_eq!(page.items[1].name.as_str(), "Fade");
+                assert_eq!(page.items[1].value, 128);
+
+                // Paging past the end yields an empty page, not an error.
+                let tail = match protocol
+                    .request(RynkLightingCommand::ReadExtensionParams { effect: 0, offset: 2 })
+                    .await
+                {
+                    Ok(RynkLightingReadback::ExtensionParamsPage(page)) => page,
+                    other => panic!("expected params readback, got {other:?}"),
+                };
+                assert_eq!(tail.total, 2);
+                assert!(tail.items.is_empty());
+
+                // An effect past the `params` tail simply has none.
+                let none = match protocol
+                    .request(RynkLightingCommand::ReadExtensionParams { effect: 1, offset: 0 })
+                    .await
+                {
+                    Ok(RynkLightingReadback::ExtensionParamsPage(page)) => page,
+                    other => panic!("expected params readback, got {other:?}"),
+                };
+                assert_eq!(none.total, 0);
+                assert!(none.items.is_empty());
+
+                // An unknown effect index is declined.
+                assert_eq!(
+                    protocol
+                        .request(RynkLightingCommand::ReadExtensionParams { effect: 9, offset: 0 })
+                        .await,
+                    Err(LightingError::Unsupported)
+                );
+
+                // A successful set advances the revision.
+                let state = match protocol
+                    .request(RynkLightingCommand::SetExtensionParam {
+                        expected_revision: 0,
+                        effect: 0,
+                        index: 0,
+                        value: 7,
+                    })
+                    .await
+                {
+                    Ok(RynkLightingReadback::State(state)) => state,
+                    other => panic!("expected state readback, got {other:?}"),
+                };
+                assert_eq!(state.revision, 1);
+
+                let page = match protocol
+                    .request(RynkLightingCommand::ReadExtensionParams { effect: 0, offset: 0 })
+                    .await
+                {
+                    Ok(RynkLightingReadback::ExtensionParamsPage(page)) => page,
+                    other => panic!("expected params readback, got {other:?}"),
+                };
+                assert_eq!(page.revision, 1);
+                assert_eq!(page.items[0].value, 7);
+
+                // Out-of-range values, unknown ordinals, and stale revisions
+                // are all declined without mutating the source.
+                assert_eq!(
+                    protocol
+                        .request(RynkLightingCommand::SetExtensionParam {
+                            expected_revision: 1,
+                            effect: 0,
+                            index: 0,
+                            value: 9,
+                        })
+                        .await,
+                    Err(LightingError::Unsupported)
+                );
+                assert_eq!(
+                    protocol
+                        .request(RynkLightingCommand::SetExtensionParam {
+                            expected_revision: 1,
+                            effect: 0,
+                            index: 5,
+                            value: 1,
+                        })
+                        .await,
+                    Err(LightingError::Unsupported)
+                );
+                assert_eq!(
+                    protocol
+                        .request(RynkLightingCommand::SetExtensionParam {
+                            expected_revision: 0,
+                            effect: 0,
+                            index: 0,
+                            value: 4,
+                        })
+                        .await,
+                    Err(LightingError::StateRevisionConflict {
+                        expected: 0,
+                        current: 1,
+                    })
+                );
+
+                let page = match protocol
+                    .request(RynkLightingCommand::ReadExtensionParams { effect: 0, offset: 0 })
+                    .await
+                {
+                    Ok(RynkLightingReadback::ExtensionParamsPage(page)) => page,
+                    other => panic!("expected params readback, got {other:?}"),
+                };
+                assert_eq!(page.revision, 1);
+                assert_eq!(page.items[0].value, 7);
+            },
+        );
+    }
+
     #[test]
     fn extension_commands_are_unsupported_with_an_empty_source() {
         run_extension_flow(crate::lighting::EmptySource, async |protocol| {
@@ -1825,6 +2055,19 @@ mod tests {
                 })
                 .await;
             assert_eq!(set, Err(LightingError::Unsupported));
+            let params = protocol
+                .request(RynkLightingCommand::ReadExtensionParams { effect: 0, offset: 0 })
+                .await;
+            assert_eq!(params, Err(LightingError::Unsupported));
+            let set_param = protocol
+                .request(RynkLightingCommand::SetExtensionParam {
+                    expected_revision: 0,
+                    effect: 0,
+                    index: 0,
+                    value: 0,
+                })
+                .await;
+            assert_eq!(set_param, Err(LightingError::Unsupported));
         });
     }
 
@@ -1838,6 +2081,7 @@ mod tests {
                     value: 128,
                     speed: 20,
                 },
+                params: [0, 0],
             }),
             async |protocol| {
                 assert_eq!(
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index f79b594a2..f653d9926 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -177,6 +177,7 @@ impl<'a> RynkService<'a> {
             | Cmd::CommitLightingSceneReplace
             | Cmd::AbortLightingSceneReplace
             | Cmd::SetLightingExtensionState
+            | Cmd::SetLightingExtensionParam
             | Cmd::SetLightingOutputMode
             | Cmd::BeginLightingRuntimeConditionalSceneReplace
             | Cmd::PutLightingRuntimeConditionalSceneChunk
@@ -330,6 +331,10 @@ impl<'a> RynkService<'a> {
             #[cfg(feature = "lighting")]
             Cmd::SetLightingExtensionState => Serve::<command::SetLightingExtensionState, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
+            Cmd::GetLightingExtensionParams => Serve::<command::GetLightingExtensionParams, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::SetLightingExtensionParam => Serve::<command::SetLightingExtensionParam, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
             Cmd::SetLightingOutputMode => Serve::<command::SetLightingOutputMode, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::GetLightingRuntimeConditionalSceneStatus => {
diff --git a/rmk/src/lighting/compositor.rs b/rmk/src/lighting/compositor.rs
index b925d1f82..85e4a3e44 100644
--- a/rmk/src/lighting/compositor.rs
+++ b/rmk/src/lighting/compositor.rs
@@ -69,6 +69,34 @@ pub trait LightingSource<C, Context> {
     fn apply_extension_state(&mut self, _state: ExtensionState) -> bool {
         false
     }
+
+    /// Live value of one per-effect parameter, addressed by the effect's
+    /// index in [`ExtensionDescriptor::effects`] and the parameter's ordinal
+    /// in that effect's [`ExtensionDescriptor::params`] row. `None` means the
+    /// source does not know that address.
+    fn extension_param(&self, _effect: u8, _index: u8) -> Option<u8> {
+        None
+    }
+
+    /// Apply one per-effect parameter. Return `true` if accepted; the engine
+    /// then re-renders and advances its revision. Returning `false` must
+    /// leave the source unchanged, matching the atomic-decline convention of
+    /// [`Self::apply_extension_state`]. The default declines.
+    fn apply_extension_param(&mut self, _effect: u8, _index: u8, _value: u8) -> bool {
+        false
+    }
+}
+
+/// One tunable parameter advertised by an extension effect.
+///
+/// Firmware owns the meaning entirely: the name is what a host renders, and
+/// the source is the sole judge of whether a value is acceptable.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionParamSpec {
+    pub name: &'static str,
+    pub min: u8,
+    pub max: u8,
+    pub default: u8,
 }
 
 /// Static description of an extension source's selectable content.
@@ -78,6 +106,21 @@ pub trait LightingSource<C, Context> {
 pub struct ExtensionDescriptor {
     pub effects: &'static [&'static str],
     pub palettes: &'static [&'static str],
+    /// Per-effect parameter lists, indexed identically to `effects`. A
+    /// shorter slice is legal: effects past its end have no parameters.
+    pub params: &'static [&'static [ExtensionParamSpec]],
+}
+
+impl ExtensionDescriptor {
+    /// Parameter specs advertised for `effect`, or `None` when `effect` is
+    /// not a valid effect index. A valid effect whose `params` row is absent
+    /// simply has no parameters.
+    pub fn effect_params(&self, effect: u8) -> Option<&'static [ExtensionParamSpec]> {
+        if effect as usize >= self.effects.len() {
+            return None;
+        }
+        Some(self.params.get(effect as usize).copied().unwrap_or(&[]))
+    }
 }
 
 /// Runtime-adjustable state of an extension source. `effect` and `palette`
diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index c725c255a..58d4ca02a 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -14,8 +14,8 @@ use rmk_types::action::LightAction;
 
 use super::Rgb8;
 use super::compositor::{
-    Compositor, Contribution, ExtensionDescriptor, ExtensionState, LightingSource, LogicalFrame, RenderError,
-    RenderInput as SourceRenderInput,
+    Compositor, Contribution, ExtensionDescriptor, ExtensionParamSpec, ExtensionState, LightingSource, LogicalFrame,
+    RenderError, RenderInput as SourceRenderInput,
 };
 use super::context::{LightingContext, LightingContextProvider};
 use super::effect::{BuiltinEffect, LightingEffect};
@@ -701,6 +701,18 @@ pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
         expected_revision: u32,
         state: ExtensionState,
     },
+    /// One page of the addressed effect's parameter specs paired with the
+    /// source's live values.
+    ReadExtensionParams {
+        effect: u8,
+        offset: u8,
+    },
+    SetExtensionParamIfRevision {
+        expected_revision: u32,
+        effect: u8,
+        index: u8,
+        value: u8,
+    },
     /// One atomically sampled page of the transient overlay.
     ReadOverlay {
         offset: u16,
@@ -813,6 +825,36 @@ pub struct ExtensionPage {
     pub state: Option<ExtensionState>,
 }
 
+/// Number of extension parameters carried by one [`ExtensionParamsPage`].
+pub const EXTENSION_PARAM_CHUNK: usize = 8;
+
+/// One extension parameter: its static spec plus the source's live value.
+/// The value falls back to the spec's default when the source does not
+/// report one.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionParamValue {
+    pub spec: ExtensionParamSpec,
+    pub value: u8,
+}
+
+/// One page of an extension effect's parameters. Pinned to the engine
+/// revision like every other mutable readback.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionParamsPage {
+    pub revision: u32,
+    /// Total parameters the addressed effect advertises.
+    pub total: u8,
+    /// Rows starting at the request's offset; trailing entries are `None`.
+    pub items: [Option<ExtensionParamValue>; EXTENSION_PARAM_CHUNK],
+}
+
+impl ExtensionParamsPage {
+    /// The populated rows, in order.
+    pub fn items(&self) -> impl Iterator<Item = ExtensionParamValue> + '_ {
+        self.items.iter().copied().flatten()
+    }
+}
+
 /// One page of immutable board-compiled layer scenes.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct CompiledScenePage {
@@ -839,6 +881,7 @@ pub enum StandardReply {
     CompiledScenesPage(CompiledScenePage),
     SceneTransaction { id: u32, cell_count: u16 },
     Extension(ExtensionPage),
+    ExtensionParams(ExtensionParamsPage),
     RuntimeConditionalScenesPage(RuntimeConditionalScenePage),
     RuntimeConditionalSceneTransaction { id: u32, cell_count: u16 },
 }
@@ -2030,6 +2073,52 @@ where
                 }
                 (Invalidation::Render, true)
             }
+            StandardCommand::ReadExtensionParams { effect, offset } => {
+                let specs = self
+                    .extension
+                    .extension_descriptor()
+                    .and_then(|descriptor| descriptor.effect_params(effect))
+                    .ok_or(StandardError::ExtensionUnsupported)?;
+                let start = (offset as usize).min(specs.len());
+                let end = (start + EXTENSION_PARAM_CHUNK).min(specs.len());
+                let mut items = [None; EXTENSION_PARAM_CHUNK];
+                for (item, (index, spec)) in items.iter_mut().zip((start..end).zip(&specs[start..end])) {
+                    let value = self
+                        .extension
+                        .extension_param(effect, index as u8)
+                        .unwrap_or(spec.default);
+                    *item = Some(ExtensionParamValue { spec: *spec, value });
+                }
+                return Ok(CommandResult::unchanged(StandardReply::ExtensionParams(
+                    ExtensionParamsPage {
+                        revision: self.revision,
+                        // The wire caps one effect's parameter list at 255.
+                        total: specs.len().min(u8::MAX as usize) as u8,
+                        items,
+                    },
+                )));
+            }
+            StandardCommand::SetExtensionParamIfRevision {
+                expected_revision,
+                effect,
+                index,
+                value,
+            } => {
+                self.check_revision(expected_revision)?;
+                let specs = self
+                    .extension
+                    .extension_descriptor()
+                    .and_then(|descriptor| descriptor.effect_params(effect))
+                    .ok_or(StandardError::ExtensionUnsupported)?;
+                let spec = specs.get(index as usize).ok_or(StandardError::ExtensionUnsupported)?;
+                if value < spec.min || value > spec.max {
+                    return Err(StandardError::ExtensionUnsupported);
+                }
+                if !self.extension.apply_extension_param(effect, index, value) {
+                    return Err(StandardError::ExtensionUnsupported);
+                }
+                (Invalidation::Render, true)
+            }
             StandardCommand::ReadState => (Invalidation::None, false),
             StandardCommand::ReadOverlay { .. }
             | StandardCommand::ReadScenes { .. }

From a14dec4b1b0f1127e2b2a0e6a0c7ec57a548cb50 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 29 Jul 2026 01:36:12 -0700
Subject: [PATCH 37/78] feat(lighting): host wrappers and replica carry
 extension parameters
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two gaps left by the parameter surface itself.

The host tooling now exposes the endpoints it already had wire types for:
`Client::get_lighting_extension_params` / `set_lighting_extension_param`
mirror the extension-names/state wrappers, and the wasm client re-exports
both through the same `endpoints!` macro, so the generated .d.ts carries
`LightingExtensionParam`, `LightingExtensionParamsPage/Request`, and
`SetLightingExtensionParamRequest` as ordinary tsify interfaces.

A split renderer replica also needs the authority's tuning, not just its
selection. `StandardReplicaState` gains `extension_params`, carrying the
ACTIVE effect's live values bounded at EXTENSION_PARAM_CHUNK so the
snapshot stays `Copy` with a fixed RAM cost. Only the active effect
travels because it is the only one a replica renders; tuning an inactive
effect rides along when it becomes active, since export always reads live
values.

ApplyReplica validates every value against the static descriptor before
applying anything, then installs them through the same checked path a host
set uses, skipping only the revision pin — so a malformed snapshot cannot
leave the selection updated and the tuning behind, the guarantee the
overlay already had. The set command and both replica paths now share
`check_extension_param` / `apply_extension_param_checked`, so nothing can
drift between what a host may set and what a replica may receive.

The board crate constructs `StandardReplicaState` by hand; adding the
field breaks that literal, which is the intended signal to add the
matching split message.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/lighting/standard.rs | 307 +++++++++++++++++++++++++++++++++--
 rynk/rynk-wasm/src/client.rs |   5 +-
 rynk/src/api.rs              |  22 +++
 3 files changed, 316 insertions(+), 18 deletions(-)

diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index 58d4ca02a..a01561e3e 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -855,6 +855,78 @@ impl ExtensionParamsPage {
     }
 }
 
+/// The active effect's live parameter values, carried in a replica snapshot
+/// so a split renderer tracks the authority's tuning.
+///
+/// Only the active effect travels: it is the only one a replica renders, and
+/// bounding the row at [`EXTENSION_PARAM_CHUNK`] keeps the snapshot `Copy`
+/// with a fixed RAM cost. Parameters of inactive effects ride along when
+/// that effect becomes active, since export always reads live values.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionReplicaParams {
+    pub effect: u8,
+    pub len: u8,
+    pub values: [u8; EXTENSION_PARAM_CHUNK],
+}
+
+impl ExtensionReplicaParams {
+    /// The populated values, in parameter order.
+    pub fn values(&self) -> &[u8] {
+        &self.values[..(self.len as usize).min(EXTENSION_PARAM_CHUNK)]
+    }
+}
+
+/// The parameter specs an extension source advertises for `effect`.
+///
+/// A free function because the callers live in the engine's `LightingEngine`
+/// impl, where `Context` is in scope but no inherent impl carries the
+/// [`LightingSource`] bound.
+fn extension_param_specs<C, Context, S>(source: &S, effect: u8) -> Result<&'static [ExtensionParamSpec], StandardError>
+where
+    S: LightingSource<C, Context> + ?Sized,
+{
+    source
+        .extension_descriptor()
+        .and_then(|descriptor| descriptor.effect_params(effect))
+        .ok_or(StandardError::ExtensionUnsupported)
+}
+
+/// Check one parameter's address and its spec's range without applying it.
+///
+/// Split from the apply so replica application can validate a whole batch
+/// before mutating anything, the way the overlay is validated first.
+fn check_extension_param<C, Context, S>(source: &S, effect: u8, index: u8, value: u8) -> Result<(), StandardError>
+where
+    S: LightingSource<C, Context> + ?Sized,
+{
+    let specs = extension_param_specs::<C, Context, S>(source, effect)?;
+    let spec = specs.get(index as usize).ok_or(StandardError::ExtensionUnsupported)?;
+    if value < spec.min || value > spec.max {
+        return Err(StandardError::ExtensionUnsupported);
+    }
+    Ok(())
+}
+
+/// Validate one parameter against its spec, then offer it to the source.
+///
+/// Shared by the host-facing set command and replica application so both
+/// reject the same addresses and the same out-of-range values.
+fn apply_extension_param_checked<C, Context, S>(
+    source: &mut S,
+    effect: u8,
+    index: u8,
+    value: u8,
+) -> Result<(), StandardError>
+where
+    S: LightingSource<C, Context> + ?Sized,
+{
+    check_extension_param::<C, Context, S>(source, effect, index, value)?;
+    if !source.apply_extension_param(effect, index, value) {
+        return Err(StandardError::ExtensionUnsupported);
+    }
+    Ok(())
+}
+
 /// One page of immutable board-compiled layer scenes.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct CompiledScenePage {
@@ -920,6 +992,9 @@ pub struct StandardReplicaState<const OVERLAY_CAP: usize, const SCENE_CAP: usize
     /// the authority's animated band. `None` when the authority has no
     /// selectable extension.
     pub extension: Option<ExtensionState>,
+    /// The active effect's live parameter values. `None` when the authority
+    /// has no selectable extension or the active effect has no parameters.
+    pub extension_params: Option<ExtensionReplicaParams>,
 }
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
@@ -1369,6 +1444,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             // Filled by handle_command, where the LightingSource bound is
             // available on the Extension parameter.
             extension: None,
+            extension_params: None,
         })
     }
 
@@ -2002,17 +2078,62 @@ where
             StandardCommand::ExportReplica(slot) => {
                 let mut replica = self.replica_state(now_ms, snapshot)?;
                 replica.extension = self.extension.extension_state();
+                replica.extension_params = replica.extension.and_then(|state| {
+                    // A source with no descriptor, an active effect the
+                    // descriptor does not know, or an effect without
+                    // parameters all export nothing to replicate.
+                    let specs = extension_param_specs::<Rgb8, Context, _>(&self.extension, state.effect).ok()?;
+                    let len = specs.len().min(EXTENSION_PARAM_CHUNK);
+                    if len == 0 {
+                        return None;
+                    }
+                    let mut values = [0u8; EXTENSION_PARAM_CHUNK];
+                    for (value, (index, spec)) in values.iter_mut().zip(specs[..len].iter().enumerate()) {
+                        *value = self
+                            .extension
+                            .extension_param(state.effect, index as u8)
+                            .unwrap_or(spec.default);
+                    }
+                    Some(ExtensionReplicaParams {
+                        effect: state.effect,
+                        len: len as u8,
+                        values,
+                    })
+                });
                 slot.put(replica)?;
                 (Invalidation::None, false)
             }
             StandardCommand::ApplyReplica(slot) => {
                 let replica = slot.take()?;
                 let overlay = Self::replica_overlay(&replica)?;
+                // Parameter addresses and ranges are checked against the
+                // static descriptor before anything is applied, so a
+                // malformed snapshot cannot leave the selection updated and
+                // the tuning behind -- the same guarantee the overlay gets.
+                if let Some(params) = replica.extension_params {
+                    for (index, value) in params.values().iter().copied().enumerate() {
+                        check_extension_param::<Rgb8, Context, _>(&self.extension, params.effect, index as u8, value)?;
+                    }
+                }
                 match (replica.extension, self.extension.extension_state()) {
                     (None, None) => {}
                     (Some(extension), Some(_)) if self.extension.apply_extension_state(extension) => {}
                     _ => return Err(StandardError::ExtensionUnsupported),
                 }
+                // Parameters follow the selection so the addressed effect is
+                // already active. Values go through the same validated path a
+                // host set uses; only the revision pin is skipped, matching
+                // how replica extension state is applied.
+                if let Some(params) = replica.extension_params {
+                    for (index, value) in params.values().iter().copied().enumerate() {
+                        apply_extension_param_checked::<Rgb8, Context, _>(
+                            &mut self.extension,
+                            params.effect,
+                            index as u8,
+                            value,
+                        )?;
+                    }
+                }
                 self.apply_replica(now_ms, replica, overlay);
                 (Invalidation::Render, false)
             }
@@ -2074,11 +2195,7 @@ where
                 (Invalidation::Render, true)
             }
             StandardCommand::ReadExtensionParams { effect, offset } => {
-                let specs = self
-                    .extension
-                    .extension_descriptor()
-                    .and_then(|descriptor| descriptor.effect_params(effect))
-                    .ok_or(StandardError::ExtensionUnsupported)?;
+                let specs = extension_param_specs::<Rgb8, Context, _>(&self.extension, effect)?;
                 let start = (offset as usize).min(specs.len());
                 let end = (start + EXTENSION_PARAM_CHUNK).min(specs.len());
                 let mut items = [None; EXTENSION_PARAM_CHUNK];
@@ -2105,18 +2222,7 @@ where
                 value,
             } => {
                 self.check_revision(expected_revision)?;
-                let specs = self
-                    .extension
-                    .extension_descriptor()
-                    .and_then(|descriptor| descriptor.effect_params(effect))
-                    .ok_or(StandardError::ExtensionUnsupported)?;
-                let spec = specs.get(index as usize).ok_or(StandardError::ExtensionUnsupported)?;
-                if value < spec.min || value > spec.max {
-                    return Err(StandardError::ExtensionUnsupported);
-                }
-                if !self.extension.apply_extension_param(effect, index, value) {
-                    return Err(StandardError::ExtensionUnsupported);
-                }
+                apply_extension_param_checked::<Rgb8, Context, _>(&mut self.extension, effect, index, value)?;
                 (Invalidation::Render, true)
             }
             StandardCommand::ReadState => (Invalidation::None, false),
@@ -2274,10 +2380,29 @@ mod tests {
 
     type Engine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2>;
 
+    /// Effect 0 advertises two parameters; effect 1 advertises none, so the
+    /// "active effect has nothing to replicate" path stays covered.
+    static REPLICA_EFFECT_NAMES: &[&str] = &["A", "B"];
+    static REPLICA_EFFECT_PARAMS: &[&[ExtensionParamSpec]] = &[&[
+        ExtensionParamSpec {
+            name: "Density",
+            min: 1,
+            max: 8,
+            default: 3,
+        },
+        ExtensionParamSpec {
+            name: "Fade",
+            min: 0,
+            max: 255,
+            default: 128,
+        },
+    ]];
+
     #[derive(Copy, Clone)]
     struct ReplicaExtension {
         state: ExtensionState,
         accept: bool,
+        params: [u8; 2],
     }
 
     impl<Context> LightingSource<Rgb8, Context> for ReplicaExtension {
@@ -2304,6 +2429,34 @@ mod tests {
             self.state = state;
             true
         }
+
+        fn extension_descriptor(&self) -> Option<ExtensionDescriptor> {
+            Some(ExtensionDescriptor {
+                effects: REPLICA_EFFECT_NAMES,
+                palettes: &[],
+                params: REPLICA_EFFECT_PARAMS,
+            })
+        }
+
+        fn extension_param(&self, effect: u8, index: u8) -> Option<u8> {
+            if effect != 0 {
+                return None;
+            }
+            self.params.get(index as usize).copied()
+        }
+
+        fn apply_extension_param(&mut self, effect: u8, index: u8, value: u8) -> bool {
+            if !self.accept || effect != 0 {
+                return false;
+            }
+            match self.params.get_mut(index as usize) {
+                Some(slot) => {
+                    *slot = value;
+                    true
+                }
+                None => false,
+            }
+        }
     }
 
     static LAYER_CELLS: [SceneCell<BuiltinEffect>; 1] = [SceneCell {
@@ -2352,6 +2505,7 @@ mod tests {
                     speed: 20,
                 },
                 accept,
+                params: [3, 128],
             },
             EmptySource,
         )
@@ -2482,6 +2636,7 @@ mod tests {
             context: context(0),
             sample_time_ms: 9,
             extension: None,
+            extension_params: None,
         };
         slot.put(snapshot).unwrap();
         assert_eq!(slot.put(snapshot), Err(ReplicaSlotError::Busy));
@@ -2514,6 +2669,7 @@ mod tests {
             context: context(0),
             sample_time_ms: 50,
             extension: Some(next_extension),
+            extension_params: None,
         };
 
         let mut declining = replica_engine(false);
@@ -2539,6 +2695,122 @@ mod tests {
         assert_eq!(accepting.extension().state, next_extension);
     }
 
+    #[test]
+    fn replica_export_carries_the_active_effect_parameters() {
+        let mut authority = replica_engine(true);
+        authority
+            .handle_command(
+                0,
+                StandardCommand::SetExtensionParamIfRevision {
+                    expected_revision: 0,
+                    effect: 0,
+                    index: 1,
+                    value: 200,
+                },
+                &context(0),
+            )
+            .unwrap();
+
+        static EXPORT_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+        authority
+            .handle_command(10, StandardCommand::ExportReplica(&EXPORT_SLOT), &context(0))
+            .unwrap();
+        let snapshot = EXPORT_SLOT.take().unwrap();
+        let params = snapshot.extension_params.expect("active effect has parameters");
+        assert_eq!(params.effect, 0);
+        assert_eq!(params.values(), &[3, 200]);
+
+        // An active effect without parameters exports nothing to replicate.
+        authority
+            .handle_command(
+                20,
+                StandardCommand::SetExtensionIfRevision {
+                    expected_revision: authority.state().revision,
+                    state: ExtensionState {
+                        effect: 1,
+                        palette: 0,
+                        value: 10,
+                        speed: 20,
+                    },
+                },
+                &context(0),
+            )
+            .unwrap();
+        authority
+            .handle_command(30, StandardCommand::ExportReplica(&EXPORT_SLOT), &context(0))
+            .unwrap();
+        assert_eq!(EXPORT_SLOT.take().unwrap().extension_params, None);
+    }
+
+    #[test]
+    fn replica_application_installs_exported_parameters() {
+        let mut authority = replica_engine(true);
+        authority
+            .handle_command(
+                0,
+                StandardCommand::SetExtensionParamIfRevision {
+                    expected_revision: 0,
+                    effect: 0,
+                    index: 0,
+                    value: 7,
+                },
+                &context(0),
+            )
+            .unwrap();
+        static ROUND_TRIP_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+        authority
+            .handle_command(10, StandardCommand::ExportReplica(&ROUND_TRIP_SLOT), &context(0))
+            .unwrap();
+        let snapshot = ROUND_TRIP_SLOT.take().unwrap();
+
+        let mut replica = replica_engine(true);
+        assert_eq!(replica.extension().params, [3, 128]);
+        ROUND_TRIP_SLOT.put(snapshot).unwrap();
+        replica
+            .handle_command(100, StandardCommand::ApplyReplica(&ROUND_TRIP_SLOT), &context(0))
+            .unwrap();
+        assert_eq!(replica.extension().params, [7, 128]);
+        assert_eq!(replica.state().revision, snapshot.revision);
+    }
+
+    #[test]
+    fn replica_parameters_are_validated_like_a_host_set() {
+        let mut authority = replica_engine(true);
+        static SEED_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+        authority
+            .handle_command(0, StandardCommand::ExportReplica(&SEED_SLOT), &context(0))
+            .unwrap();
+        let mut snapshot = SEED_SLOT.take().unwrap();
+        // A selection change that must not survive the rejected parameter.
+        snapshot.extension = Some(ExtensionState {
+            effect: 0,
+            palette: 7,
+            value: 77,
+            speed: 88,
+        });
+        // 9 is outside the "Density" spec's 1..=8 range.
+        snapshot.extension_params = Some(ExtensionReplicaParams {
+            effect: 0,
+            len: 1,
+            values: [9, 0, 0, 0, 0, 0, 0, 0],
+        });
+
+        let mut replica = replica_engine(true);
+        let before = replica.extension().params;
+        let before_state = replica.extension().state;
+        static INVALID_PARAM_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+        INVALID_PARAM_SLOT.put(snapshot).unwrap();
+        assert_eq!(
+            replica.handle_command(100, StandardCommand::ApplyReplica(&INVALID_PARAM_SLOT), &context(0)),
+            Err(StandardError::ExtensionUnsupported)
+        );
+        // The pre-apply check keeps the whole extension untouched, selection
+        // included, not just the parameter that failed.
+        assert_eq!(replica.extension().params, before);
+        assert_eq!(replica.extension().state, before_state);
+        assert_eq!(replica.state().revision, 0);
+    }
+
     #[test]
     fn invalid_replica_common_state_does_not_mutate_extension() {
         let mut overlay = OverlayBatch::new();
@@ -2570,6 +2842,7 @@ mod tests {
                 value: 30,
                 speed: 40,
             }),
+            extension_params: None,
         };
         let mut engine = replica_engine(true);
         let before = engine.extension().state;
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index c31668ec8..bbf1f7815 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -36,7 +36,8 @@ use rynk::rmk_types::protocol::rynk::{
     UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus, LightingCompiledScenesPage,
     LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy, SplitCentralLatencyState,
     LightingConditionalSceneStatus, LightingConditionalScenesPage, LightingOutputModeState, LightingExtension,
-    LightingExtensionNamesPage, LightingExtensionNamesRequest, SetLightingExtensionStateRequest,
+    LightingExtensionNamesPage, LightingExtensionNamesRequest, LightingExtensionParamsPage,
+    LightingExtensionParamsRequest, SetLightingExtensionParamRequest, SetLightingExtensionStateRequest,
     AbortLightingRuntimeConditionalSceneReplaceRequest, BeginLightingRuntimeConditionalSceneReplaceRequest,
     CommitLightingRuntimeConditionalSceneReplaceRequest, LightingRuntimeConditionalScenePageRequest,
     LightingRuntimeConditionalSceneStatus, LightingRuntimeConditionalSceneTransaction,
@@ -204,6 +205,8 @@ endpoints! {
     get_lighting_extension() -> LightingExtension,
     get_lighting_extension_names(request: LightingExtensionNamesRequest) -> LightingExtensionNamesPage,
     set_lighting_extension_state(request: SetLightingExtensionStateRequest) -> LightingState,
+    get_lighting_extension_params(request: LightingExtensionParamsRequest) -> LightingExtensionParamsPage,
+    set_lighting_extension_param(request: SetLightingExtensionParamRequest) -> LightingState,
     get_lighting_scene_status() -> LightingSceneStatus,
     get_lighting_scenes(request: LightingScenePageRequest) -> LightingScenesPage,
     get_lighting_compiled_scene_status() -> LightingCompiledSceneStatus,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 45761bb9c..7f7c27e88 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -38,6 +38,7 @@ use rmk_types::protocol::rynk::{
     LightingCompiledScenesPage, LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy,
     SplitCentralLatencyState, LightingConditionalSceneStatus, LightingConditionalScenesPage, LightingOutputModeState,
     LightingExtension, LightingExtensionNameKind, LightingExtensionNamesPage, LightingExtensionNamesRequest,
+    LightingExtensionParamsPage, LightingExtensionParamsRequest, SetLightingExtensionParamRequest,
     SetLightingExtensionStateRequest, AbortLightingRuntimeConditionalSceneReplaceRequest,
     BeginLightingRuntimeConditionalSceneReplaceRequest, CommitLightingRuntimeConditionalSceneReplaceRequest,
     LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
@@ -641,6 +642,27 @@ impl Client {
         Self::flatten_lighting(self.request::<command::SetLightingExtensionState>(&request).await?)
     }
 
+    /// Read one page of an extension effect's tunable parameters. Unlike name
+    /// pages these carry live values, so they are pinned to
+    /// `LightingState.revision`.
+    pub async fn get_lighting_extension_params(
+        &self,
+        request: LightingExtensionParamsRequest,
+    ) -> Result<LightingExtensionParamsPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingExtensionParams)?;
+        Self::flatten_lighting(self.request::<command::GetLightingExtensionParams>(&request).await?)
+    }
+
+    /// Set one effect parameter when the state revision matches. The effect
+    /// need not be the active one.
+    pub async fn set_lighting_extension_param(
+        &self,
+        request: SetLightingExtensionParamRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::SetLightingExtensionParam)?;
+        Self::flatten_lighting(self.request::<command::SetLightingExtensionParam>(&request).await?)
+    }
+
     pub async fn get_lighting_runtime_conditional_scene_status(
         &self,
     ) -> Result<LightingRuntimeConditionalSceneStatus, RynkHostError> {

From 2e567978b7763e72d0775bb302e09af91e567486 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 29 Jul 2026 14:21:01 -0700
Subject: [PATCH 38/78] feat(lighting): persist the animated extension
 selection

The extension band lived only in RAM, so every power cycle reverted to
whatever the board compiled in and changing the boot effect meant
rebuilding firmware. Scene tables were already durable; this gives the
selection the same treatment.

Extension mutations now persist by readback, storing effect, palette,
value, speed and the selected effect's parameter values in one
fixed-size record, guarded by the same write-if-changed check the scene
table uses so a repeated set costs no flash. The startup read is exposed
for boards to apply before the storage task takes ownership; callers
re-validate every index against their live descriptor, since inserting
an effect shifts every later index and a record from an older build
would otherwise name something else.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/host/rynk/lighting.rs | 164 ++++++++++++++++++++++++++++++----
 rmk/src/storage/mod.rs        |  68 +++++++++++++-
 2 files changed, 215 insertions(+), 17 deletions(-)

diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 47500b01a..945e786d4 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -597,6 +597,64 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
         Ok(state)
     }
 
+    /// Run an extension-band mutation and persist the resulting selection, so
+    /// the effect a user picked is what the board comes up on after a power
+    /// cycle instead of the compiled-in default.
+    async fn extension_mutation(
+        &self,
+        command: StandardCommand<OVERLAY_CAPACITY, SCENE_CAP>,
+    ) -> LightingResult<StandardState> {
+        let state = self.request_core_state(command).await?;
+        self.persist_extension().await;
+        Ok(state)
+    }
+
+    /// Persist by readback rather than from the request, so a mutation the
+    /// engine clamped or partially declined stores what actually took effect.
+    #[cfg(feature = "storage")]
+    async fn persist_extension(&self) {
+        use crate::channel::FLASH_CHANNEL;
+        use crate::storage::{FlashOperationMessage, LightingExtensionRecord};
+
+        let Ok(page) = self.request_extension_page().await else {
+            return;
+        };
+        let Some(state) = page.state else {
+            return;
+        };
+
+        // Only the selected effect's parameters are persisted; `record.effect`
+        // is what they belong to.
+        let mut params = [0u8; LIGHTING_EXTENSION_PARAM_CHUNK];
+        let mut param_len = 0u8;
+        if let Ok(StandardReply::ExtensionParams(page)) = self
+            .request_core(StandardCommand::ReadExtensionParams {
+                effect: state.effect,
+                offset: 0,
+            })
+            .await
+        {
+            for (slot, entry) in params.iter_mut().zip(page.items()) {
+                *slot = entry.value;
+                param_len += 1;
+            }
+        }
+
+        FLASH_CHANNEL
+            .send(FlashOperationMessage::LightingExtensionState(LightingExtensionRecord {
+                effect: state.effect,
+                palette: state.palette,
+                value: state.value,
+                speed: state.speed,
+                param_len,
+                params,
+            }))
+            .await;
+    }
+
+    #[cfg(not(feature = "storage"))]
+    async fn persist_extension(&self) {}
+
     async fn runtime_conditional_scene_mutation(
         &self,
         command: StandardCommand<OVERLAY_CAPACITY, SCENE_CAP>,
@@ -854,15 +912,20 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
             RynkLightingCommand::SetExtensionState {
                 expected_revision,
                 state,
-            } => StandardCommand::SetExtensionIfRevision {
-                expected_revision,
-                state: crate::lighting::compositor::ExtensionState {
-                    effect: state.effect,
-                    palette: state.palette,
-                    value: state.value,
-                    speed: state.speed,
-                },
-            },
+            } => {
+                let state = self
+                    .extension_mutation(StandardCommand::SetExtensionIfRevision {
+                        expected_revision,
+                        state: crate::lighting::compositor::ExtensionState {
+                            effect: state.effect,
+                            palette: state.palette,
+                            value: state.value,
+                            speed: state.speed,
+                        },
+                    })
+                    .await?;
+                return Ok(RynkLightingReadback::State(state_to_wire(state)));
+            }
             RynkLightingCommand::ReadExtensionParams { effect, offset } => {
                 let page = match self
                     .request_core(StandardCommand::ReadExtensionParams { effect, offset })
@@ -894,12 +957,17 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                 effect,
                 index,
                 value,
-            } => StandardCommand::SetExtensionParamIfRevision {
-                expected_revision,
-                effect,
-                index,
-                value,
-            },
+            } => {
+                let state = self
+                    .extension_mutation(StandardCommand::SetExtensionParamIfRevision {
+                        expected_revision,
+                        effect,
+                        index,
+                        value,
+                    })
+                    .await?;
+                return Ok(RynkLightingReadback::State(state_to_wire(state)));
+            }
             RynkLightingCommand::ReadRuntimeConditionalSceneStatus => {
                 let state = self.request_core_state(StandardCommand::ReadState).await?;
                 return Ok(RynkLightingReadback::RuntimeConditionalSceneStatus {
@@ -2031,6 +2099,72 @@ mod tests {
         );
     }
 
+    /// The selection has to outlive a power cycle: a board that forgets it
+    /// can only ever boot into its compiled-in default, which is what makes
+    /// changing the default a firmware rebuild.
+    #[cfg(feature = "storage")]
+    #[test]
+    fn extension_mutations_persist_the_selection_and_its_parameters() {
+        use crate::storage::FlashOperationMessage;
+
+        run_extension_flow(
+            TestExtensionSource {
+                state: crate::lighting::compositor::ExtensionState {
+                    effect: 0,
+                    palette: 1,
+                    value: 128,
+                    speed: 20,
+                },
+                params: [3, 128],
+            },
+            async |protocol| {
+                let revision = match protocol
+                    .request(RynkLightingCommand::SetExtensionState {
+                        expected_revision: 0,
+                        state: WireExtensionState {
+                            effect: 0,
+                            palette: 2,
+                            value: 200,
+                            speed: 40,
+                        },
+                    })
+                    .await
+                {
+                    Ok(RynkLightingReadback::State(state)) => state.revision,
+                    other => panic!("expected state readback, got {other:?}"),
+                };
+
+                match protocol
+                    .request(RynkLightingCommand::SetExtensionParam {
+                        expected_revision: revision,
+                        effect: 0,
+                        index: 1,
+                        value: 77,
+                    })
+                    .await
+                {
+                    Ok(RynkLightingReadback::State(_)) => {}
+                    other => panic!("expected state readback, got {other:?}"),
+                }
+            },
+        );
+
+        // Persisting by readback means the last record is the settled state,
+        // parameters included, no matter which command produced it.
+        let mut last = None;
+        while let Ok(message) = crate::channel::FLASH_CHANNEL.try_receive() {
+            if let FlashOperationMessage::LightingExtensionState(record) = message {
+                last = Some(record);
+            }
+        }
+        let record = last.expect("extension mutations persist a record");
+        assert_eq!(
+            (record.effect, record.palette, record.value, record.speed),
+            (0, 2, 200, 40)
+        );
+        assert_eq!(record.params(), &[3, 77]);
+    }
+
     #[test]
     fn extension_commands_are_unsupported_with_an_empty_source() {
         run_extension_flow(crate::lighting::EmptySource, async |protocol| {
diff --git a/rmk/src/storage/mod.rs b/rmk/src/storage/mod.rs
index 7eee58c46..0fb8cf615 100644
--- a/rmk/src/storage/mod.rs
+++ b/rmk/src/storage/mod.rs
@@ -10,8 +10,8 @@ use rmk_types::connection::ConnectionType;
 use rmk_types::morse::MorseProfile;
 #[cfg(all(feature = "lighting", feature = "rynk"))]
 use rmk_types::protocol::rynk::{
-    LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LightingConditionalSceneCell,
-    LightingLayerPolicy, LightingSceneCell,
+    LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE, LIGHTING_EXTENSION_PARAM_CHUNK, LIGHTING_SCENE_CHUNK_SIZE,
+    LightingConditionalSceneCell, LightingLayerPolicy, LightingSceneCell,
 };
 use sequential_storage::Error as SSError;
 use sequential_storage::cache::{Cache, Uncached};
@@ -178,6 +178,9 @@ pub(crate) enum FlashOperationMessage {
         index: u8,
         cells: heapless::Vec<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>,
     },
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    // Animated extension-band selection and the selected effect's parameters
+    LightingExtensionState(LightingExtensionRecord),
     #[cfg(feature = "_ble")]
     // Read bond info for the given slot; storage task replies via `BOND_INFO_RESPONSE`.
     ReadBleBondInfo(u8),
@@ -232,6 +235,8 @@ pub(crate) enum StorageKey {
     LightingRuntimeConditionalSceneTable,
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     LightingRuntimeConditionalSceneShard(u8),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingExtensionState,
 }
 
 impl StorageKey {
@@ -323,12 +328,44 @@ pub(crate) enum StorageData {
     LightingRuntimeConditionalSceneShard(
         heapless::Vec<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>,
     ),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingExtensionState(LightingExtensionRecord),
 }
 
 impl<'a> PostcardValue<'a> for StorageData {}
 
 /// Persisted lighting scene-table header. Shards beyond `len` are stale
 /// leftovers from a larger previous table and are ignored at load.
+/// Persisted animated-extension selection, plus the parameter values of the
+/// effect it names. Only the selected effect's parameters are kept: they are
+/// what a reboot has to reproduce, and a fixed-size record keeps the write
+/// cost of a single flash entry predictable.
+///
+/// Every index here is validated against the running firmware before it is
+/// applied. Effect and palette lists are compiled in, so inserting one effect
+/// shifts every later index; a record written by an older build would
+/// otherwise resurrect a selection that now names something else.
+#[cfg(all(feature = "lighting", feature = "rynk"))]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub struct LightingExtensionRecord {
+    pub effect: u8,
+    pub palette: u8,
+    pub value: u8,
+    pub speed: u8,
+    /// Valid entries in `params`; the remainder is padding.
+    pub param_len: u8,
+    pub params: [u8; LIGHTING_EXTENSION_PARAM_CHUNK],
+}
+
+#[cfg(all(feature = "lighting", feature = "rynk"))]
+impl LightingExtensionRecord {
+    /// The parameter values that belong to [`Self::effect`].
+    pub fn params(&self) -> &[u8] {
+        &self.params[..(self.param_len as usize).min(LIGHTING_EXTENSION_PARAM_CHUNK)]
+    }
+}
+
 #[cfg(all(feature = "lighting", feature = "rynk"))]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -578,6 +615,17 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
         Ok(())
     }
 
+    /// Read the persisted animated-extension selection at startup, before the
+    /// storage task takes ownership. The caller validates every index against
+    /// its own compiled effect/palette lists before applying it.
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    pub async fn read_lighting_extension_state(&mut self) -> Option<LightingExtensionRecord> {
+        match self.fetch_data(StorageKey::LightingExtensionState).await {
+            Some(StorageData::LightingExtensionState(record)) => Some(record),
+            _ => None,
+        }
+    }
+
     /// Read the persisted lighting scene configuration at startup, before the
     /// storage task takes ownership. Returns the persisted layer policy, if
     /// any, and appends up to `CAP` stored cells to `cells`.
@@ -930,6 +978,22 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
                     update_storage_field!(&mut self.flash, &mut self.buffer, BehaviorConfig, morse_default_profile)
                 }
                 #[cfg(all(feature = "lighting", feature = "rynk"))]
+                FlashOperationMessage::LightingExtensionState(record) => {
+                    // The selection changes on every RGB key press and every
+                    // host edit, so skip writes that would store what is
+                    // already there rather than spending a flash entry.
+                    match self.fetch_data(StorageKey::LightingExtensionState).await {
+                        Some(StorageData::LightingExtensionState(saved)) if saved == record => Ok(()),
+                        _ => {
+                            self.store_data(
+                                StorageKey::LightingExtensionState,
+                                &StorageData::LightingExtensionState(record),
+                            )
+                            .await
+                        }
+                    }
+                }
+                #[cfg(all(feature = "lighting", feature = "rynk"))]
                 FlashOperationMessage::LightingSceneTable { len, policy } => {
                     // Scene persistence rewrites the whole table on every
                     // mutation; comparing before writing keeps unchanged

From fb96f89ad12c1e12dc22e6ab7600ac0e9775557a Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 29 Jul 2026 17:28:52 -0700
Subject: [PATCH 39/78] feat(lighting): runtime conditional cells override
 compiled rules

A runtime conditional cell is the host's replacement for a compiled one,
so it has to reach the same altitude and win where the two address the
same slot. It was applying in the extension band, far below the compiled
status rules, which meant a host could add conditional lighting but never
replace what the board shipped with -- the compiled cell simply painted
over it. Move it into the status band, after the compiled table.

Also adds the host-side pager for the runtime conditional table, which
stitches pages in offset order under one pinned revision: matching rules
compose in table order, so sorting them would change what they mean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/lighting/standard.rs | 104 +++++++++++++++++++++++++++++++++--
 rynk/src/api.rs              |  94 +++++++++++++++++++++++++++++++
 2 files changed, 193 insertions(+), 5 deletions(-)

diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index a01561e3e..b8504a68d 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -2312,16 +2312,19 @@ where
         let mut transaction = compositor.begin(effect_now_ms, input.snapshot, Rgb8::BLACK, frame);
         transaction.apply(priority::BACKGROUND, background)?;
         transaction.apply(priority::EXTENSION, extension)?;
-        let mut runtime_conditional_source = RuntimeConditionalSource {
-            table: runtime_conditional_scenes,
-            batteries: *battery_status,
-        };
-        transaction.apply(priority::EXTENSION, &mut runtime_conditional_source)?;
         transaction.apply(priority::LAYER, layers)?;
         // Same band, later call: runtime cells override static defaults.
         transaction.apply(priority::LAYER, scenes)?;
         transaction.apply(priority::HOST_OVERLAY, overlay)?;
         transaction.apply(priority::STATUS, status)?;
+        // Status band, after the compiled rules: a runtime conditional cell is
+        // the host's replacement for a compiled one, so it must reach the same
+        // altitude and win on the slots the two share.
+        let mut runtime_conditional_source = RuntimeConditionalSource {
+            table: runtime_conditional_scenes,
+            batteries: *battery_status,
+        };
+        transaction.apply(priority::STATUS, &mut runtime_conditional_source)?;
         if wake_active && let Some(indicator_cell) = indicator_cell.as_ref() {
             let mut indicator = SparseScene {
                 cells: core::slice::from_ref(indicator_cell),
@@ -3907,4 +3910,95 @@ mod tests {
         assert_eq!(set.reply.state().unwrap().output_mode, OutputMode::PoweredOnly);
         assert_eq!(set.reply.state().unwrap().revision, 2);
     }
+
+    #[test]
+    fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules() {
+        use rmk_types::battery::BatteryStatus;
+
+        use crate::lighting::{ConditionalSceneCell, ConditionalScenes, LayerCondition};
+
+        struct NoBatteries;
+        impl BatteryStatusProvider for NoBatteries {
+            fn battery_status(&self, _node: u8) -> BatteryStatus {
+                BatteryStatus::Unavailable
+            }
+        }
+        static NO_BATTERIES: NoBatteries = NoBatteries;
+
+        // Slot 0 is contested three ways: a compiled layer scene paints it RED
+        // on layer 1, a compiled conditional rule paints it GREEN, and the
+        // runtime table paints it BLUE. Only the host's rule should survive.
+        static COMPILED_CONDITIONAL: [ConditionalSceneCell<BuiltinEffect>; 1] = [ConditionalSceneCell {
+            conditions: ConditionSet {
+                layer: Some(LayerCondition { layer: 1, active: true }),
+                battery: None,
+            },
+            slot: LedSlot(0),
+            effect: BuiltinEffect::Solid { color: GREEN },
+        }];
+
+        let mut engine: StandardLightingEngine<
+            'static,
+            EmptySource,
+            ConditionalScenes<'static, BuiltinEffect, NoBatteries>,
+            2,
+            2,
+            4,
+        > = StandardLightingEngine::new(
+            BackgroundState {
+                value: 10,
+                ..BackgroundState::default()
+            },
+            LayerScenes {
+                scenes: &LAYERS,
+                policy: LayerPolicy::ActiveStack,
+            },
+            EmptySource,
+            ConditionalScenes::new(&COMPILED_CONDITIONAL, &NO_BATTERIES),
+        )
+        .with_battery_status_provider(&NO_BATTERIES);
+
+        let snapshot = context(1);
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 0,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(
+            frame.as_slice()[0],
+            GREEN,
+            "compiled conditional rules outrank compiled layer scenes"
+        );
+
+        engine
+            .install_runtime_conditional_scene_cell(RuntimeConditionalSceneCell {
+                conditions: ConditionSet {
+                    layer: Some(LayerCondition { layer: 1, active: true }),
+                    battery: None,
+                },
+                slot: LedSlot(0),
+                effect: BuiltinEffect::Solid { color: BLUE },
+            })
+            .unwrap();
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 1,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        assert_eq!(
+            frame.as_slice()[0],
+            BLUE,
+            "a runtime conditional cell replaces the compiled rule on the same slot"
+        );
+    }
 }
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 7f7c27e88..e760a78e3 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -1168,6 +1168,100 @@ impl Client {
         Ok(names)
     }
 
+    /// Read the whole runtime conditional table by paging
+    /// `GetLightingRuntimeConditionalScenes` under one pinned revision. Order
+    /// is meaningful — matching rules compose in table order — so pages are
+    /// stitched in offset order and never sorted.
+    pub async fn read_all_lighting_runtime_conditional_scenes(
+        &self,
+    ) -> Result<(u32, Vec<rmk_types::protocol::rynk::LightingConditionalSceneCell>), RynkHostError> {
+        const ATTEMPTS: usize = 4;
+        let mut last_error = None;
+        for _ in 0..ATTEMPTS {
+            let status = self.get_lighting_runtime_conditional_scene_status().await?;
+            let mut cells = Vec::new();
+            let mut offset: u16 = 0;
+            let mut conflicted = false;
+            while offset < status.cell_len {
+                match self
+                    .get_lighting_runtime_conditional_scenes(LightingRuntimeConditionalScenePageRequest {
+                        revision: status.revision,
+                        offset,
+                    })
+                    .await
+                {
+                    Ok(page) => {
+                        if page.items.is_empty() {
+                            break;
+                        }
+                        offset += page.items.len() as u16;
+                        cells.extend(page.items.iter().cloned());
+                    }
+                    Err(
+                        error @ RynkHostError::LightingRejected(
+                            rmk_types::protocol::rynk::LightingError::StateRevisionConflict { .. },
+                        ),
+                    ) => {
+                        last_error = Some(error);
+                        conflicted = true;
+                        break;
+                    }
+                    Err(error) => return Err(error),
+                }
+            }
+            if !conflicted {
+                return Ok((status.revision, cells));
+            }
+        }
+        Err(last_error.expect("a retried read only exits with a recorded conflict"))
+    }
+
+    /// Atomically replace the whole runtime conditional table, in the order
+    /// given. Shaped like [`Self::replace_all_lighting_scenes`], including the
+    /// best-effort abort when staging fails.
+    pub async fn replace_all_lighting_runtime_conditional_scenes(
+        &self,
+        expected_revision: u32,
+        cells: &[rmk_types::protocol::rynk::LightingConditionalSceneCell],
+    ) -> Result<LightingState, RynkHostError> {
+        let transaction = self
+            .begin_lighting_runtime_conditional_scene_replace(
+                BeginLightingRuntimeConditionalSceneReplaceRequest {
+                    expected_revision,
+                    cell_count: cells.len() as u16,
+                },
+            )
+            .await?;
+        let mut offset: u16 = 0;
+        for chunk in cells.chunks(rmk_types::protocol::rynk::LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE) {
+            let mut request = PutLightingRuntimeConditionalSceneChunkRequest {
+                transaction_id: transaction.id,
+                offset,
+                cells: Default::default(),
+            };
+            for cell in chunk {
+                request.cells.push(cell.clone()).expect("chunks are chunk-size bounded");
+            }
+            if let Err(error) = self.put_lighting_runtime_conditional_scene_chunk(request).await {
+                let _ = self
+                    .abort_lighting_runtime_conditional_scene_replace(
+                        AbortLightingRuntimeConditionalSceneReplaceRequest {
+                            transaction_id: transaction.id,
+                        },
+                    )
+                    .await;
+                return Err(error);
+            }
+            offset += chunk.len() as u16;
+        }
+        self.commit_lighting_runtime_conditional_scene_replace(
+            CommitLightingRuntimeConditionalSceneReplaceRequest {
+                transaction_id: transaction.id,
+            },
+        )
+        .await
+    }
+
     /// Atomically replace the whole stored scene table: begin, stage in
     /// chunk-sized pages, and commit. A staging failure is followed by a
     /// best-effort abort so the firmware transaction is not left dangling.

From 8eb89111dbecb17eb598d9241c82249b382d593d Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 29 Jul 2026 19:42:31 -0700
Subject: [PATCH 40/78] feat(lighting): dense scene storage keyed by a style
 pool

Groundwork for replacing the sparse scene table. A sparse cell list costs
20 bytes per painted key and caps how many keys can be painted at all --
a cap this board already exceeds with its compiled lighting, and one that
cannot be raised much because the same constant is multiplied across the
live tables, the replace staging buffer, the replica snapshot and the
queued mailbox commands.

SceneStyles stores one style index per (layer, slot) against a pool
holding each distinct effect once. Cost then tracks the board rather than
how much of it is painted: 8 layers of 80 slots is 640 index bytes plus a
64-entry pool, so every key on every layer can carry an effect and the
only limit left is how many different effects are named -- which a
keyboard painted from a handful of colours never approaches. Effect type
stops mattering to storage, so blink and breathe need no separate table,
and lookup is a direct index rather than a scan the renderer repeats per
LED per frame.

Not yet wired into SceneTable: that means turning as_slice into an
iterator across its callers and the board's replica serialisation, which
is the bulk of the work and lands next.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/lighting/standard.rs | 216 +++++++++++++++++++++++++++++++++++
 1 file changed, 216 insertions(+)

diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index b8504a68d..394eac649 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -291,6 +291,148 @@ impl SceneChunk {
     }
 }
 
+/// Distinct effects one [`SceneStyles`] can name at once.
+///
+/// This replaces a per-cell capacity with a per-*style* one, which is the far
+/// looser limit: a keyboard paints many keys from a small set of colours, so a
+/// config with a hundred painted keys typically names a handful of effects.
+pub const SCENE_STYLE_CAP: usize = 64;
+
+/// Dense scene storage: one style index per (layer, slot), plus a pool holding
+/// each distinct effect once.
+///
+/// A sparse cell list costs 20 bytes per painted key and caps how many keys can
+/// be painted at all -- a cap this board already exceeds with its compiled
+/// lighting. Here the cost is proportional to the board (`LAYERS × SLOTS`
+/// index bytes plus the pool) rather than to how much of it is painted, so
+/// every key on every layer can carry an effect and the only limit left is how
+/// many *different* effects are in play. Lookup is also a direct index rather
+/// than a scan of the cell list, which the renderer does per LED per frame.
+///
+/// Index `0` means unset, so the pool is addressed from 1. Effect type does not
+/// affect storage: an animated effect costs one pool entry exactly like a solid
+/// one, so blink and breathe need no separate table.
+///
+/// Releasing a style is deliberately not reference counted. [`Self::unset`]
+/// leaves its pool entry in place, which is harmless -- an unreferenced entry
+/// only occupies a pool slot -- and [`Self::clear`] resets the pool, so the
+/// host's atomic replace rebuilds and re-dedupes it as a matter of course.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SceneStyles<const LAYERS: usize, const SLOTS: usize> {
+    styles: [BuiltinEffect; SCENE_STYLE_CAP],
+    style_len: usize,
+    /// Nested rather than `[u8; LAYERS * SLOTS]`, which needs const-generic
+    /// arithmetic that is not stable.
+    index: [[u8; SLOTS]; LAYERS],
+    assigned: usize,
+}
+
+impl<const LAYERS: usize, const SLOTS: usize> Default for SceneStyles<LAYERS, SLOTS> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<const LAYERS: usize, const SLOTS: usize> SceneStyles<LAYERS, SLOTS> {
+    pub const fn new() -> Self {
+        Self {
+            styles: [BuiltinEffect::Solid { color: Rgb8::BLACK }; SCENE_STYLE_CAP],
+            style_len: 0,
+            index: [[0; SLOTS]; LAYERS],
+            assigned: 0,
+        }
+    }
+
+    /// Painted (layer, slot) pairs, which is what readback pages over.
+    pub const fn len(&self) -> usize {
+        self.assigned
+    }
+
+    pub const fn is_empty(&self) -> bool {
+        self.assigned == 0
+    }
+
+    /// Distinct effects currently named. Bounded by [`SCENE_STYLE_CAP`].
+    pub const fn style_len(&self) -> usize {
+        self.style_len
+    }
+
+    /// Paint `(layer, slot)`, reusing a pool entry when the effect is already
+    /// named. Fails only when a *new* effect would overflow the pool, and then
+    /// leaves the table untouched.
+    pub fn set(&mut self, layer: u8, slot: LedSlot, effect: BuiltinEffect) -> Result<(), StandardError> {
+        let cursor = self.cursor(layer, slot).ok_or(StandardError::SceneFull {
+            capacity: LAYERS * SLOTS,
+        })?;
+        let style = match self.styles[..self.style_len].iter().position(|held| *held == effect) {
+            Some(existing) => existing,
+            None => {
+                if self.style_len == SCENE_STYLE_CAP {
+                    return Err(StandardError::SceneFull {
+                        capacity: SCENE_STYLE_CAP,
+                    });
+                }
+                self.styles[self.style_len] = effect;
+                self.style_len += 1;
+                self.style_len - 1
+            }
+        };
+        let (row, column) = cursor;
+        if self.index[row][column] == 0 {
+            self.assigned += 1;
+        }
+        self.index[row][column] = (style + 1) as u8;
+        Ok(())
+    }
+
+    /// Unpaint `(layer, slot)`, reporting whether it had been painted.
+    pub fn unset(&mut self, layer: u8, slot: LedSlot) -> bool {
+        let Some((row, column)) = self.cursor(layer, slot) else {
+            return false;
+        };
+        if self.index[row][column] == 0 {
+            return false;
+        }
+        self.index[row][column] = 0;
+        self.assigned -= 1;
+        true
+    }
+
+    /// Drop every assignment and release the whole style pool.
+    pub fn clear(&mut self) {
+        self.index = [[0; SLOTS]; LAYERS];
+        self.style_len = 0;
+        self.assigned = 0;
+    }
+
+    pub fn get(&self, layer: u8, slot: LedSlot) -> Option<BuiltinEffect> {
+        let (row, column) = self.cursor(layer, slot)?;
+        let style = self.index[row][column];
+        (style != 0).then(|| self.styles[style as usize - 1])
+    }
+
+    /// Painted cells in `(layer, slot)` order. Scene cells carry no meaningful
+    /// order of their own -- the sparse table swap-removes on unset -- so a
+    /// stable ordering here is a readback improvement rather than a change.
+    pub fn iter(&self) -> impl Iterator<Item = SceneTableCell> + '_ {
+        self.index.iter().enumerate().flat_map(move |(row, columns)| {
+            columns.iter().enumerate().filter_map(move |(column, &style)| {
+                (style != 0).then(|| SceneTableCell {
+                    layer: row as u8,
+                    slot: LedSlot(column as u16),
+                    effect: self.styles[style as usize - 1],
+                })
+            })
+        })
+    }
+
+    fn cursor(&self, layer: u8, slot: LedSlot) -> Option<(usize, usize)> {
+        let row = layer as usize;
+        let column = slot.0 as usize;
+        (row < LAYERS && column < SLOTS).then_some((row, column))
+    }
+}
+
 /// Fixed-capacity runtime scene table with layer-aware composition.
 ///
 /// Cells are unique per `(layer, slot)` and stored in insertion order; order
@@ -3911,6 +4053,80 @@ mod tests {
         assert_eq!(set.reply.state().unwrap().revision, 2);
     }
 
+    /// The point of the styles pool: cost tracks the board, not how much of it
+    /// is painted, so every key on every layer can carry an effect and the only
+    /// limit left is how many *distinct* effects are named.
+    #[test]
+    fn dense_scene_storage_paints_every_slot_from_a_shared_style_pool() {
+        let mut styles = SceneStyles::<8, 80>::new();
+        let blue = BuiltinEffect::solid(Rgb8::new(0, 0, 9));
+        let green = BuiltinEffect::solid(Rgb8::new(0, 9, 0));
+
+        // Fill the whole board -- 640 cells, ten times what the sparse table
+        // held -- from two styles.
+        for layer in 0..8u8 {
+            for slot in 0..80u16 {
+                let effect = if slot % 2 == 0 { blue } else { green };
+                styles.set(layer, LedSlot(slot), effect).unwrap();
+            }
+        }
+        assert_eq!(styles.len(), 640);
+        assert_eq!(styles.style_len(), 2, "identical effects share one entry");
+        assert_eq!(styles.get(3, LedSlot(4)), Some(blue));
+        assert_eq!(styles.get(3, LedSlot(5)), Some(green));
+        assert_eq!(styles.iter().count(), 640);
+
+        // Readback order is stable by (layer, slot).
+        let first = styles.iter().next().unwrap();
+        assert_eq!((first.layer, first.slot), (0, LedSlot(0)));
+    }
+
+    #[test]
+    fn dense_scene_storage_rejects_only_new_styles_past_the_pool() {
+        let mut styles = SceneStyles::<8, 80>::new();
+        for index in 0..SCENE_STYLE_CAP {
+            let shade = BuiltinEffect::solid(Rgb8::new(index as u8, 0, 0));
+            styles.set(0, LedSlot(index as u16), shade).unwrap();
+        }
+        assert_eq!(styles.style_len(), SCENE_STYLE_CAP);
+
+        // A style already in the pool still lands, however full it is.
+        let held = BuiltinEffect::solid(Rgb8::new(0, 0, 0));
+        assert!(styles.set(1, LedSlot(0), held).is_ok());
+
+        // A new one is declined, and declining leaves the table untouched.
+        let fresh = BuiltinEffect::solid(Rgb8::new(0, 1, 2));
+        let before = styles.clone();
+        assert!(matches!(
+            styles.set(2, LedSlot(0), fresh),
+            Err(StandardError::SceneFull { .. })
+        ));
+        assert_eq!(styles, before);
+
+        // Out-of-range addresses are declined the same way.
+        assert!(styles.set(8, LedSlot(0), held).is_err());
+        assert!(styles.set(0, LedSlot(80), held).is_err());
+    }
+
+    /// `unset` deliberately leaves the pool entry behind, and `clear` is what
+    /// releases it -- which is why the host's atomic replace re-dedupes.
+    #[test]
+    fn unset_keeps_the_pool_and_clear_releases_it() {
+        let mut styles = SceneStyles::<8, 80>::new();
+        let red = BuiltinEffect::solid(Rgb8::new(9, 0, 0));
+        styles.set(0, LedSlot(0), red).unwrap();
+        assert_eq!((styles.len(), styles.style_len()), (1, 1));
+
+        assert!(styles.unset(0, LedSlot(0)));
+        assert!(!styles.unset(0, LedSlot(0)), "already unpainted");
+        assert_eq!(styles.len(), 0);
+        assert_eq!(styles.style_len(), 1, "the entry outlives its last use");
+        assert!(styles.get(0, LedSlot(0)).is_none());
+
+        styles.clear();
+        assert_eq!((styles.len(), styles.style_len()), (0, 0));
+    }
+
     #[test]
     fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules() {
         use rmk_types::battery::BatteryStatus;

From 771d2192317a84dcd45d069c1138adbe9f7a274b Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 29 Jul 2026 19:58:59 -0700
Subject: [PATCH 41/78] feat(lighting): free scene styles by scanning, not
 counting

An entry was left behind when its last assignment went away, on the
assumption that the host's atomic replace would reset the pool. That is
the wrong assumption for the flow a configurator actually uses: painting
keys one at a time never issues a replace, so every repaint stranded an
entry and 64 of them exhausted the pool.

Freeing needs no counters. When an assignment drops or is overwritten,
the index is scanned for any remaining use of the old entry and it is
freed if there is none -- a few hundred byte comparisons on an operation
the host drives, never the renderer, and less state to keep correct than
a set of counts. Occupancy is a bitmask so a freed entry leaves a hole
the next allocation reuses, which keeps entries in place and means no
index ever needs rewriting.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/lighting/standard.rs | 114 ++++++++++++++++++++++++++---------
 1 file changed, 85 insertions(+), 29 deletions(-)

diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index 394eac649..2dfbde4e5 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -313,14 +313,20 @@ pub const SCENE_STYLE_CAP: usize = 64;
 /// affect storage: an animated effect costs one pool entry exactly like a solid
 /// one, so blink and breathe need no separate table.
 ///
-/// Releasing a style is deliberately not reference counted. [`Self::unset`]
-/// leaves its pool entry in place, which is harmless -- an unreferenced entry
-/// only occupies a pool slot -- and [`Self::clear`] resets the pool, so the
-/// host's atomic replace rebuilds and re-dedupes it as a matter of course.
+/// Releasing a style needs no reference counts. Whenever an assignment drops
+/// or is overwritten, the index table is scanned for any remaining use of the
+/// old entry and it is freed if there is none. The table is one byte per slot,
+/// so that is a few hundred byte comparisons on an operation the host drives --
+/// never the renderer -- which is cheaper to run than a set of counters is to
+/// keep correct. It also means a session that repaints keys one at a time,
+/// which is what painting in a configurator does, cannot slowly exhaust the
+/// pool the way waiting for an atomic replace to reset it would.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct SceneStyles<const LAYERS: usize, const SLOTS: usize> {
     styles: [BuiltinEffect; SCENE_STYLE_CAP],
-    style_len: usize,
+    /// Occupied pool entries. A freed entry leaves a hole that the next
+    /// allocation reuses, so entries never move and no index needs rewriting.
+    used: u64,
     /// Nested rather than `[u8; LAYERS * SLOTS]`, which needs const-generic
     /// arithmetic that is not stable.
     index: [[u8; SLOTS]; LAYERS],
@@ -337,7 +343,7 @@ impl<const LAYERS: usize, const SLOTS: usize> SceneStyles<LAYERS, SLOTS> {
     pub const fn new() -> Self {
         Self {
             styles: [BuiltinEffect::Solid { color: Rgb8::BLACK }; SCENE_STYLE_CAP],
-            style_len: 0,
+            used: 0,
             index: [[0; SLOTS]; LAYERS],
             assigned: 0,
         }
@@ -354,7 +360,7 @@ impl<const LAYERS: usize, const SLOTS: usize> SceneStyles<LAYERS, SLOTS> {
 
     /// Distinct effects currently named. Bounded by [`SCENE_STYLE_CAP`].
     pub const fn style_len(&self) -> usize {
-        self.style_len
+        self.used.count_ones() as usize
     }
 
     /// Paint `(layer, slot)`, reusing a pool entry when the effect is already
@@ -364,24 +370,22 @@ impl<const LAYERS: usize, const SLOTS: usize> SceneStyles<LAYERS, SLOTS> {
         let cursor = self.cursor(layer, slot).ok_or(StandardError::SceneFull {
             capacity: LAYERS * SLOTS,
         })?;
-        let style = match self.styles[..self.style_len].iter().position(|held| *held == effect) {
+        let style = match self.find(effect) {
             Some(existing) => existing,
-            None => {
-                if self.style_len == SCENE_STYLE_CAP {
-                    return Err(StandardError::SceneFull {
-                        capacity: SCENE_STYLE_CAP,
-                    });
-                }
-                self.styles[self.style_len] = effect;
-                self.style_len += 1;
-                self.style_len - 1
-            }
+            None => self.allocate(effect).ok_or(StandardError::SceneFull {
+                capacity: SCENE_STYLE_CAP,
+            })?,
         };
         let (row, column) = cursor;
-        if self.index[row][column] == 0 {
+        let previous = self.index[row][column];
+        if previous == 0 {
             self.assigned += 1;
         }
         self.index[row][column] = (style + 1) as u8;
+        // Overwriting can strand whatever was here before.
+        if previous != 0 && previous != style as u8 + 1 {
+            self.release_if_unused(previous);
+        }
         Ok(())
     }
 
@@ -390,18 +394,20 @@ impl<const LAYERS: usize, const SLOTS: usize> SceneStyles<LAYERS, SLOTS> {
         let Some((row, column)) = self.cursor(layer, slot) else {
             return false;
         };
-        if self.index[row][column] == 0 {
+        let previous = self.index[row][column];
+        if previous == 0 {
             return false;
         }
         self.index[row][column] = 0;
         self.assigned -= 1;
+        self.release_if_unused(previous);
         true
     }
 
     /// Drop every assignment and release the whole style pool.
     pub fn clear(&mut self) {
         self.index = [[0; SLOTS]; LAYERS];
-        self.style_len = 0;
+        self.used = 0;
         self.assigned = 0;
     }
 
@@ -426,6 +432,33 @@ impl<const LAYERS: usize, const SLOTS: usize> SceneStyles<LAYERS, SLOTS> {
         })
     }
 
+    fn find(&self, effect: BuiltinEffect) -> Option<usize> {
+        (0..SCENE_STYLE_CAP).find(|&index| self.holds(index) && self.styles[index] == effect)
+    }
+
+    fn allocate(&mut self, effect: BuiltinEffect) -> Option<usize> {
+        let index = (0..SCENE_STYLE_CAP).find(|&index| !self.holds(index))?;
+        self.styles[index] = effect;
+        self.used |= 1 << index;
+        Some(index)
+    }
+
+    const fn holds(&self, index: usize) -> bool {
+        self.used & (1 << index) != 0
+    }
+
+    /// Free the pool entry behind `style` (a one-based index) when no slot
+    /// still points at it.
+    fn release_if_unused(&mut self, style: u8) {
+        let referenced = self
+            .index
+            .iter()
+            .any(|columns| columns.iter().any(|&held| held == style));
+        if !referenced {
+            self.used &= !(1 << (style as usize - 1));
+        }
+    }
+
     fn cursor(&self, layer: u8, slot: LedSlot) -> Option<(usize, usize)> {
         let row = layer as usize;
         let column = slot.0 as usize;
@@ -4108,25 +4141,48 @@ mod tests {
         assert!(styles.set(0, LedSlot(80), held).is_err());
     }
 
-    /// `unset` deliberately leaves the pool entry behind, and `clear` is what
-    /// releases it -- which is why the host's atomic replace re-dedupes.
+    /// A style is freed as soon as nothing points at it, found by scanning the
+    /// index rather than by keeping counts. A style still in use elsewhere must
+    /// survive its other references going away.
     #[test]
-    fn unset_keeps_the_pool_and_clear_releases_it() {
+    fn dropping_the_last_reference_frees_the_style() {
         let mut styles = SceneStyles::<8, 80>::new();
         let red = BuiltinEffect::solid(Rgb8::new(9, 0, 0));
         styles.set(0, LedSlot(0), red).unwrap();
-        assert_eq!((styles.len(), styles.style_len()), (1, 1));
+        styles.set(0, LedSlot(1), red).unwrap();
+        assert_eq!((styles.len(), styles.style_len()), (2, 1));
 
+        // One of two references: the entry stays.
         assert!(styles.unset(0, LedSlot(0)));
-        assert!(!styles.unset(0, LedSlot(0)), "already unpainted");
-        assert_eq!(styles.len(), 0);
-        assert_eq!(styles.style_len(), 1, "the entry outlives its last use");
-        assert!(styles.get(0, LedSlot(0)).is_none());
+        assert_eq!(styles.style_len(), 1, "still referenced by the other slot");
+        assert_eq!(styles.get(0, LedSlot(1)), Some(red));
+
+        // The last one: the entry goes.
+        assert!(styles.unset(0, LedSlot(1)));
+        assert!(!styles.unset(0, LedSlot(1)), "already unpainted");
+        assert_eq!((styles.len(), styles.style_len()), (0, 0));
 
         styles.clear();
         assert_eq!((styles.len(), styles.style_len()), (0, 0));
     }
 
+    /// Repainting one key at a time is what a configurator does, and it must
+    /// not slowly exhaust the pool. Waiting for an atomic replace to reset it
+    /// would strand an entry per repaint and run out after 64.
+    #[test]
+    fn repainting_a_slot_does_not_strand_styles() {
+        let mut styles = SceneStyles::<8, 80>::new();
+        for shade in 0..(SCENE_STYLE_CAP as u8 * 3) {
+            let effect = BuiltinEffect::solid(Rgb8::new(shade, shade, shade));
+            styles
+                .set(0, LedSlot(0), effect)
+                .expect("overwriting one slot never needs a second entry");
+            assert_eq!(styles.style_len(), 1, "the previous shade was freed");
+            assert_eq!(styles.get(0, LedSlot(0)), Some(effect));
+        }
+        assert_eq!(styles.len(), 1);
+    }
+
     #[test]
     fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules() {
         use rmk_types::battery::BatteryStatus;

From 3528eb9b2cfaabd2dae35f87f0f1f705825fc226 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 29 Jul 2026 20:11:56 -0700
Subject: [PATCH 42/78] feat(lighting): intern scene effects to shrink the cell
 to 4 bytes

A scene cell carried its effect inline, and BuiltinEffect is 16 bytes
because blink and breathe each hold two millisecond timers -- so a solid
colour paid for animation fields it never used and every cell cost 20.
That is the constant behind the capacity problem: the same number sizes
the live table, the replace staging buffer, the replica snapshot and the
queued mailbox commands, so each wasted byte per cell is wasted about ten
times over. 320 cells came to 6.4 KB per copy, which is a large part of
why a 320-capacity build pushed static RAM to 174 KB and then hung before
USB came up.

The effect now lives once in a StylePool and the cell holds a one-byte
index: 4 bytes per cell, and 320 cells fit in 2,328 bytes rather than
6,400. Effect type stops mattering to the cell, so animated cells need no
separate table, and a keyboard painted from a handful of colours barely
touches the 64-entry pool -- the only capacity interning adds.

A dense index per (layer, slot) was the alternative and does not pay:
LayerState allows 64 layers, so covering them all would cost 8 KB of
index per copy. Interning keeps every layer addressable instead.

as_slice is gone, since a stored cell no longer holds a resolvable
effect; iter() resolves through the pool. Equality compares resolved
cells, because a style index is an allocation detail that two tables
holding the same effects can number differently.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/lighting/standard.rs | 403 +++++++++++++++--------------------
 1 file changed, 174 insertions(+), 229 deletions(-)

diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
index 2dfbde4e5..851a45196 100644
--- a/rmk/src/lighting/standard.rs
+++ b/rmk/src/lighting/standard.rs
@@ -291,181 +291,112 @@ impl SceneChunk {
     }
 }
 
-/// Distinct effects one [`SceneStyles`] can name at once.
+/// Distinct effects one [`StylePool`] can hold at once.
 ///
-/// This replaces a per-cell capacity with a per-*style* one, which is the far
-/// looser limit: a keyboard paints many keys from a small set of colours, so a
-/// config with a hundred painted keys typically names a handful of effects.
+/// This is the only capacity interning adds, and it is a far looser bound than
+/// a per-cell one: a keyboard paints many keys from a small set of colours, so
+/// a config with hundreds of painted keys typically names a handful of effects.
 pub const SCENE_STYLE_CAP: usize = 64;
 
-/// Dense scene storage: one style index per (layer, slot), plus a pool holding
-/// each distinct effect once.
+/// Effects held once and referenced by index, so a scene cell can carry one
+/// byte instead of a whole effect.
 ///
-/// A sparse cell list costs 20 bytes per painted key and caps how many keys can
-/// be painted at all -- a cap this board already exceeds with its compiled
-/// lighting. Here the cost is proportional to the board (`LAYERS × SLOTS`
-/// index bytes plus the pool) rather than to how much of it is painted, so
-/// every key on every layer can carry an effect and the only limit left is how
-/// many *different* effects are in play. Lookup is also a direct index rather
-/// than a scan of the cell list, which the renderer does per LED per frame.
+/// An inline [`BuiltinEffect`] is 16 bytes because blink and breathe each carry
+/// two millisecond timers, so a solid colour pays for animation fields it never
+/// uses and a cell costs 20 bytes. Interning moves the effect here and leaves
+/// the cell at 4, which matters more than it looks: the same capacity sizes the
+/// live tables, the replace staging buffer, the replica snapshot and the queued
+/// mailbox commands, so every byte saved per cell is saved several times over.
 ///
-/// Index `0` means unset, so the pool is addressed from 1. Effect type does not
-/// affect storage: an animated effect costs one pool entry exactly like a solid
-/// one, so blink and breathe need no separate table.
-///
-/// Releasing a style needs no reference counts. Whenever an assignment drops
-/// or is overwritten, the index table is scanned for any remaining use of the
-/// old entry and it is freed if there is none. The table is one byte per slot,
-/// so that is a few hundred byte comparisons on an operation the host drives --
-/// never the renderer -- which is cheaper to run than a set of counters is to
-/// keep correct. It also means a session that repaints keys one at a time,
-/// which is what painting in a configurator does, cannot slowly exhaust the
-/// pool the way waiting for an atomic replace to reset it would.
-#[derive(Clone, Debug, Eq, PartialEq)]
-pub struct SceneStyles<const LAYERS: usize, const SLOTS: usize> {
+/// Freeing needs no reference counts. When a reference drops or is overwritten
+/// the caller reports it, the table is scanned for any remaining use, and the
+/// entry is freed if there is none -- cheaper to run on a host-driven operation
+/// than a set of counters is to keep correct. Occupancy is a bitmask, so a
+/// freed entry leaves a hole the next allocation reuses and entries never move,
+/// which means no cell's index ever needs rewriting.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct StylePool {
     styles: [BuiltinEffect; SCENE_STYLE_CAP],
-    /// Occupied pool entries. A freed entry leaves a hole that the next
-    /// allocation reuses, so entries never move and no index needs rewriting.
     used: u64,
-    /// Nested rather than `[u8; LAYERS * SLOTS]`, which needs const-generic
-    /// arithmetic that is not stable.
-    index: [[u8; SLOTS]; LAYERS],
-    assigned: usize,
 }
 
-impl<const LAYERS: usize, const SLOTS: usize> Default for SceneStyles<LAYERS, SLOTS> {
+impl Default for StylePool {
     fn default() -> Self {
         Self::new()
     }
 }
 
-impl<const LAYERS: usize, const SLOTS: usize> SceneStyles<LAYERS, SLOTS> {
+impl StylePool {
     pub const fn new() -> Self {
         Self {
             styles: [BuiltinEffect::Solid { color: Rgb8::BLACK }; SCENE_STYLE_CAP],
             used: 0,
-            index: [[0; SLOTS]; LAYERS],
-            assigned: 0,
         }
     }
 
-    /// Painted (layer, slot) pairs, which is what readback pages over.
+    /// Distinct effects currently held. Bounded by [`SCENE_STYLE_CAP`].
     pub const fn len(&self) -> usize {
-        self.assigned
+        self.used.count_ones() as usize
     }
 
     pub const fn is_empty(&self) -> bool {
-        self.assigned == 0
+        self.used == 0
     }
 
-    /// Distinct effects currently named. Bounded by [`SCENE_STYLE_CAP`].
-    pub const fn style_len(&self) -> usize {
-        self.used.count_ones() as usize
+    /// Index for `effect`, reusing an entry when it is already held. `None`
+    /// only when a *new* effect would overflow, and then nothing is mutated.
+    pub fn intern(&mut self, effect: BuiltinEffect) -> Option<u8> {
+        if let Some(held) = self.find(effect) {
+            return Some(held);
+        }
+        let free = (0..SCENE_STYLE_CAP).find(|&index| !self.holds(index))?;
+        self.styles[free] = effect;
+        self.used |= 1 << free;
+        Some(free as u8)
     }
 
-    /// Paint `(layer, slot)`, reusing a pool entry when the effect is already
-    /// named. Fails only when a *new* effect would overflow the pool, and then
-    /// leaves the table untouched.
-    pub fn set(&mut self, layer: u8, slot: LedSlot, effect: BuiltinEffect) -> Result<(), StandardError> {
-        let cursor = self.cursor(layer, slot).ok_or(StandardError::SceneFull {
-            capacity: LAYERS * SLOTS,
-        })?;
-        let style = match self.find(effect) {
-            Some(existing) => existing,
-            None => self.allocate(effect).ok_or(StandardError::SceneFull {
-                capacity: SCENE_STYLE_CAP,
-            })?,
-        };
-        let (row, column) = cursor;
-        let previous = self.index[row][column];
-        if previous == 0 {
-            self.assigned += 1;
-        }
-        self.index[row][column] = (style + 1) as u8;
-        // Overwriting can strand whatever was here before.
-        if previous != 0 && previous != style as u8 + 1 {
-            self.release_if_unused(previous);
-        }
-        Ok(())
+    pub fn get(&self, style: u8) -> Option<BuiltinEffect> {
+        let index = style as usize;
+        (index < SCENE_STYLE_CAP && self.holds(index)).then(|| self.styles[index])
     }
 
-    /// Unpaint `(layer, slot)`, reporting whether it had been painted.
-    pub fn unset(&mut self, layer: u8, slot: LedSlot) -> bool {
-        let Some((row, column)) = self.cursor(layer, slot) else {
-            return false;
-        };
-        let previous = self.index[row][column];
-        if previous == 0 {
-            return false;
+    /// Free `style` unless it is still referenced. The caller does the check,
+    /// so the pool's borrow stays independent of whatever holds the references.
+    pub fn release(&mut self, style: u8, still_referenced: bool) {
+        if (style as usize) < SCENE_STYLE_CAP && !still_referenced {
+            self.used &= !(1 << style as usize);
         }
-        self.index[row][column] = 0;
-        self.assigned -= 1;
-        self.release_if_unused(previous);
-        true
     }
 
-    /// Drop every assignment and release the whole style pool.
     pub fn clear(&mut self) {
-        self.index = [[0; SLOTS]; LAYERS];
         self.used = 0;
-        self.assigned = 0;
-    }
-
-    pub fn get(&self, layer: u8, slot: LedSlot) -> Option<BuiltinEffect> {
-        let (row, column) = self.cursor(layer, slot)?;
-        let style = self.index[row][column];
-        (style != 0).then(|| self.styles[style as usize - 1])
     }
 
-    /// Painted cells in `(layer, slot)` order. Scene cells carry no meaningful
-    /// order of their own -- the sparse table swap-removes on unset -- so a
-    /// stable ordering here is a readback improvement rather than a change.
-    pub fn iter(&self) -> impl Iterator<Item = SceneTableCell> + '_ {
-        self.index.iter().enumerate().flat_map(move |(row, columns)| {
-            columns.iter().enumerate().filter_map(move |(column, &style)| {
-                (style != 0).then(|| SceneTableCell {
-                    layer: row as u8,
-                    slot: LedSlot(column as u16),
-                    effect: self.styles[style as usize - 1],
-                })
-            })
-        })
-    }
-
-    fn find(&self, effect: BuiltinEffect) -> Option<usize> {
-        (0..SCENE_STYLE_CAP).find(|&index| self.holds(index) && self.styles[index] == effect)
-    }
-
-    fn allocate(&mut self, effect: BuiltinEffect) -> Option<usize> {
-        let index = (0..SCENE_STYLE_CAP).find(|&index| !self.holds(index))?;
-        self.styles[index] = effect;
-        self.used |= 1 << index;
-        Some(index)
+    fn find(&self, effect: BuiltinEffect) -> Option<u8> {
+        (0..SCENE_STYLE_CAP)
+            .find(|&index| self.holds(index) && self.styles[index] == effect)
+            .map(|index| index as u8)
     }
 
     const fn holds(&self, index: usize) -> bool {
         self.used & (1 << index) != 0
     }
+}
 
-    /// Free the pool entry behind `style` (a one-based index) when no slot
-    /// still points at it.
-    fn release_if_unused(&mut self, style: u8) {
-        let referenced = self
-            .index
-            .iter()
-            .any(|columns| columns.iter().any(|&held| held == style));
-        if !referenced {
-            self.used &= !(1 << (style as usize - 1));
-        }
-    }
-
-    fn cursor(&self, layer: u8, slot: LedSlot) -> Option<(usize, usize)> {
-        let row = layer as usize;
-        let column = slot.0 as usize;
-        (row < LAYERS && column < SLOTS).then_some((row, column))
-    }
+/// A scene cell as stored: the effect lives in the table's [`StylePool`].
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+struct InternedSceneCell {
+    layer: u8,
+    slot: LedSlot,
+    style: u8,
 }
 
+const EMPTY_INTERNED_CELL: InternedSceneCell = InternedSceneCell {
+    layer: 0,
+    slot: LedSlot(0),
+    style: 0,
+};
+
 /// Fixed-capacity runtime scene table with layer-aware composition.
 ///
 /// Cells are unique per `(layer, slot)` and stored in insertion order; order
@@ -473,16 +404,18 @@ impl<const LAYERS: usize, const SLOTS: usize> SceneStyles<LAYERS, SLOTS> {
 /// and same-layer cells can never target the same slot.
 #[derive(Copy, Clone, Debug)]
 pub struct SceneTable<const CAP: usize> {
-    cells: [SceneTableCell; CAP],
+    cells: [InternedSceneCell; CAP],
     len: usize,
+    pool: StylePool,
     policy: LayerPolicy,
 }
 
 impl<const CAP: usize> SceneTable<CAP> {
     pub const fn new() -> Self {
         Self {
-            cells: [EMPTY_SCENE_CELL; CAP],
+            cells: [EMPTY_INTERNED_CELL; CAP],
             len: 0,
+            pool: StylePool::new(),
             policy: LayerPolicy::ActiveStack,
         }
     }
@@ -505,35 +438,67 @@ impl<const CAP: usize> SceneTable<CAP> {
         changed
     }
 
-    pub fn as_slice(&self) -> &[SceneTableCell] {
-        &self.cells[..self.len]
-    }
-
     /// Insert or update the cell addressed by `(layer, slot)`.
     pub fn set(&mut self, cell: SceneTableCell) -> Result<(), StandardError> {
-        if let Some(existing) = self.cells[..self.len]
-            .iter_mut()
-            .find(|existing| existing.layer == cell.layer && existing.slot == cell.slot)
-        {
-            *existing = cell;
-            return Ok(());
-        }
-        if self.len == CAP {
+        let occupied = self.cells[..self.len]
+            .iter()
+            .position(|held| held.layer == cell.layer && held.slot == cell.slot);
+        if occupied.is_none() && self.len == CAP {
             return Err(StandardError::SceneFull { capacity: CAP });
         }
-        self.cells[self.len] = cell;
-        self.len += 1;
+        // Interning first means a full pool declines before anything is
+        // mutated, so a rejected set leaves the table exactly as it was.
+        let style = self.pool.intern(cell.effect).ok_or(StandardError::SceneFull {
+            capacity: SCENE_STYLE_CAP,
+        })?;
+        let interned = InternedSceneCell {
+            layer: cell.layer,
+            slot: cell.slot,
+            style,
+        };
+        match occupied {
+            Some(index) => {
+                let replaced = self.cells[index].style;
+                self.cells[index] = interned;
+                if replaced != style {
+                    self.release(replaced);
+                }
+            }
+            None => {
+                self.cells[self.len] = interned;
+                self.len += 1;
+            }
+        }
         Ok(())
     }
 
+    /// Free a style that no cell references any more.
+    fn release(&mut self, style: u8) {
+        let referenced = self.cells[..self.len].iter().any(|held| held.style == style);
+        self.pool.release(style, referenced);
+    }
+
+    /// Painted cells, with their effects resolved out of the pool.
+    pub fn iter(&self) -> impl Iterator<Item = SceneTableCell> + '_ {
+        self.cells[..self.len].iter().filter_map(move |held| {
+            self.pool.get(held.style).map(|effect| SceneTableCell {
+                layer: held.layer,
+                slot: held.slot,
+                effect,
+            })
+        })
+    }
+
     /// Remove the cell addressed by `(layer, slot)`.
     pub fn unset(&mut self, layer: u8, slot: LedSlot) -> bool {
         if let Some(index) = self.cells[..self.len]
             .iter()
             .position(|cell| cell.layer == layer && cell.slot == slot)
         {
+            let removed = self.cells[index].style;
             self.len -= 1;
             self.cells[index] = self.cells[self.len];
+            self.release(removed);
             true
         } else {
             false
@@ -542,21 +507,20 @@ impl<const CAP: usize> SceneTable<CAP> {
 
     pub fn clear(&mut self) {
         self.len = 0;
+        self.pool.clear();
     }
 
     /// One readback page starting at `offset`, clamped at the table's end.
     pub fn page(&self, offset: u16) -> SceneChunk {
-        let start = (offset as usize).min(self.len);
-        let end = (start + SCENE_CHUNK_SIZE).min(self.len);
         let mut chunk = SceneChunk::new();
-        for cell in &self.cells[start..end] {
-            chunk.push(*cell).expect("page is chunk-bounded");
+        for cell in self.iter().skip(offset as usize).take(SCENE_CHUNK_SIZE) {
+            chunk.push(cell).expect("page is chunk-bounded");
         }
         chunk
     }
 
-    fn cell_for_layer(&self, layer: u8, wanted: &mut usize) -> Option<&SceneTableCell> {
-        for cell in self.cells[..self.len].iter().filter(|cell| cell.layer == layer) {
+    fn cell_for_layer(&self, layer: u8, wanted: &mut usize) -> Option<SceneTableCell> {
+        for cell in self.iter().filter(|cell| cell.layer == layer) {
             if *wanted == 0 {
                 return Some(cell);
             }
@@ -565,7 +529,7 @@ impl<const CAP: usize> SceneTable<CAP> {
         None
     }
 
-    fn cell_at(&self, context: &LightingContext, mut wanted: usize) -> &SceneTableCell {
+    fn cell_at(&self, context: &LightingContext, mut wanted: usize) -> SceneTableCell {
         let effective = context.layers.effective;
         match self.policy {
             LayerPolicy::EffectiveOnly => self.cell_for_layer(effective, &mut wanted),
@@ -617,8 +581,10 @@ impl<const CAP: usize> Default for SceneTable<CAP> {
 
 impl<const CAP: usize> PartialEq for SceneTable<CAP> {
     fn eq(&self, other: &Self) -> bool {
-        // Cells past `len` are stale storage, not state.
-        self.policy == other.policy && self.as_slice() == other.as_slice()
+        // Cells past `len` are stale storage, not state, and a style index is
+        // an allocation detail -- two tables holding the same effects can
+        // number them differently -- so this compares resolved cells.
+        self.policy == other.policy && self.iter().eq(other.iter())
     }
 }
 
@@ -2762,7 +2728,7 @@ mod tests {
         assert_eq!(snapshot.context, authority_context);
         assert_eq!(snapshot.sample_time_ms, 120);
         assert_eq!(snapshot.overlay.as_slice()[0].ttl_ms, NonZeroU32::new(80));
-        assert_eq!(snapshot.scenes.as_slice(), &[scene_cell]);
+        assert_eq!(snapshot.scenes.iter().collect::<heapless::Vec<_, 4>>(), &[scene_cell]);
 
         let mut authority_frame = LogicalFrame::new(Rgb8::BLACK);
         authority
@@ -2793,7 +2759,7 @@ mod tests {
             .unwrap();
 
         assert_eq!(replica.state().revision, snapshot.revision);
-        assert_eq!(replica.scenes().as_slice(), &[scene_cell]);
+        assert_eq!(replica.scenes().iter().collect::<heapless::Vec<_, 4>>(), &[scene_cell]);
         assert_eq!(replica_frame, authority_frame);
     }
 
@@ -4086,101 +4052,80 @@ mod tests {
         assert_eq!(set.reply.state().unwrap().revision, 2);
     }
 
-    /// The point of the styles pool: cost tracks the board, not how much of it
-    /// is painted, so every key on every layer can carry an effect and the only
-    /// limit left is how many *distinct* effects are named.
+    /// Interning is what shrinks a cell from 20 bytes to 4: many keys painted
+    /// from few colours share one entry, and the effect's type stops mattering
+    /// to the cell, so blink and breathe need no separate table.
     #[test]
-    fn dense_scene_storage_paints_every_slot_from_a_shared_style_pool() {
-        let mut styles = SceneStyles::<8, 80>::new();
+    fn interning_shares_one_entry_per_distinct_effect() {
+        let mut pool = StylePool::new();
         let blue = BuiltinEffect::solid(Rgb8::new(0, 0, 9));
         let green = BuiltinEffect::solid(Rgb8::new(0, 9, 0));
 
-        // Fill the whole board -- 640 cells, ten times what the sparse table
-        // held -- from two styles.
-        for layer in 0..8u8 {
-            for slot in 0..80u16 {
-                let effect = if slot % 2 == 0 { blue } else { green };
-                styles.set(layer, LedSlot(slot), effect).unwrap();
-            }
-        }
-        assert_eq!(styles.len(), 640);
-        assert_eq!(styles.style_len(), 2, "identical effects share one entry");
-        assert_eq!(styles.get(3, LedSlot(4)), Some(blue));
-        assert_eq!(styles.get(3, LedSlot(5)), Some(green));
-        assert_eq!(styles.iter().count(), 640);
-
-        // Readback order is stable by (layer, slot).
-        let first = styles.iter().next().unwrap();
-        assert_eq!((first.layer, first.slot), (0, LedSlot(0)));
+        let first = pool.intern(blue).unwrap();
+        assert_eq!(pool.intern(blue), Some(first), "same effect, same entry");
+        let other = pool.intern(green).unwrap();
+        assert_ne!(first, other);
+        assert_eq!(pool.len(), 2);
+        assert_eq!(pool.get(first), Some(blue));
+        assert_eq!(pool.get(other), Some(green));
     }
 
     #[test]
-    fn dense_scene_storage_rejects_only_new_styles_past_the_pool() {
-        let mut styles = SceneStyles::<8, 80>::new();
-        for index in 0..SCENE_STYLE_CAP {
-            let shade = BuiltinEffect::solid(Rgb8::new(index as u8, 0, 0));
-            styles.set(0, LedSlot(index as u16), shade).unwrap();
+    fn a_full_pool_declines_only_new_effects() {
+        let mut pool = StylePool::new();
+        for shade in 0..SCENE_STYLE_CAP {
+            pool.intern(BuiltinEffect::solid(Rgb8::new(shade as u8, 0, 0))).unwrap();
         }
-        assert_eq!(styles.style_len(), SCENE_STYLE_CAP);
+        assert_eq!(pool.len(), SCENE_STYLE_CAP);
 
-        // A style already in the pool still lands, however full it is.
+        // Already held: still fine, however full.
         let held = BuiltinEffect::solid(Rgb8::new(0, 0, 0));
-        assert!(styles.set(1, LedSlot(0), held).is_ok());
+        assert!(pool.intern(held).is_some());
 
-        // A new one is declined, and declining leaves the table untouched.
-        let fresh = BuiltinEffect::solid(Rgb8::new(0, 1, 2));
-        let before = styles.clone();
-        assert!(matches!(
-            styles.set(2, LedSlot(0), fresh),
-            Err(StandardError::SceneFull { .. })
-        ));
-        assert_eq!(styles, before);
-
-        // Out-of-range addresses are declined the same way.
-        assert!(styles.set(8, LedSlot(0), held).is_err());
-        assert!(styles.set(0, LedSlot(80), held).is_err());
+        // New: declined, and declining mutates nothing.
+        let before = pool;
+        assert_eq!(pool.intern(BuiltinEffect::solid(Rgb8::new(0, 1, 2))), None);
+        assert_eq!(pool, before);
     }
 
-    /// A style is freed as soon as nothing points at it, found by scanning the
-    /// index rather than by keeping counts. A style still in use elsewhere must
-    /// survive its other references going away.
+    /// A style goes when nothing points at it, found by scanning rather than by
+    /// keeping counts -- and it must survive while another cell still holds it.
     #[test]
-    fn dropping_the_last_reference_frees_the_style() {
-        let mut styles = SceneStyles::<8, 80>::new();
+    fn a_style_outlives_all_but_its_last_reference() {
+        let mut table = SceneTable::<4>::new();
         let red = BuiltinEffect::solid(Rgb8::new(9, 0, 0));
-        styles.set(0, LedSlot(0), red).unwrap();
-        styles.set(0, LedSlot(1), red).unwrap();
-        assert_eq!((styles.len(), styles.style_len()), (2, 1));
-
-        // One of two references: the entry stays.
-        assert!(styles.unset(0, LedSlot(0)));
-        assert_eq!(styles.style_len(), 1, "still referenced by the other slot");
-        assert_eq!(styles.get(0, LedSlot(1)), Some(red));
+        let cell = |slot| SceneTableCell {
+            layer: 0,
+            slot: LedSlot(slot),
+            effect: red,
+        };
+        table.set(cell(0)).unwrap();
+        table.set(cell(1)).unwrap();
+        assert_eq!((table.len(), table.pool.len()), (2, 1));
 
-        // The last one: the entry goes.
-        assert!(styles.unset(0, LedSlot(1)));
-        assert!(!styles.unset(0, LedSlot(1)), "already unpainted");
-        assert_eq!((styles.len(), styles.style_len()), (0, 0));
+        assert!(table.unset(0, LedSlot(0)));
+        assert_eq!(table.pool.len(), 1, "the other cell still holds it");
 
-        styles.clear();
-        assert_eq!((styles.len(), styles.style_len()), (0, 0));
+        assert!(table.unset(0, LedSlot(1)));
+        assert_eq!((table.len(), table.pool.len()), (0, 0));
     }
 
-    /// Repainting one key at a time is what a configurator does, and it must
-    /// not slowly exhaust the pool. Waiting for an atomic replace to reset it
-    /// would strand an entry per repaint and run out after 64.
+    /// Repainting one key is what painting in a configurator does, and it must
+    /// not strand an entry each time: 64 repaints would exhaust the pool.
     #[test]
-    fn repainting_a_slot_does_not_strand_styles() {
-        let mut styles = SceneStyles::<8, 80>::new();
+    fn repainting_a_cell_does_not_strand_styles() {
+        let mut table = SceneTable::<4>::new();
         for shade in 0..(SCENE_STYLE_CAP as u8 * 3) {
-            let effect = BuiltinEffect::solid(Rgb8::new(shade, shade, shade));
-            styles
-                .set(0, LedSlot(0), effect)
-                .expect("overwriting one slot never needs a second entry");
-            assert_eq!(styles.style_len(), 1, "the previous shade was freed");
-            assert_eq!(styles.get(0, LedSlot(0)), Some(effect));
+            table
+                .set(SceneTableCell {
+                    layer: 0,
+                    slot: LedSlot(0),
+                    effect: BuiltinEffect::solid(Rgb8::new(shade, shade, shade)),
+                })
+                .expect("overwriting one cell never needs a second entry");
+            assert_eq!(table.pool.len(), 1, "the previous shade was freed");
         }
-        assert_eq!(styles.len(), 1);
+        assert_eq!(table.len(), 1);
     }
 
     #[test]

From e35cad7f0f6840878059d279e9afebfe0a7f694b Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 29 Jul 2026 20:59:05 -0700
Subject: [PATCH 43/78] refactor(lighting): split standard.rs into a module
 directory

One file had grown to 4,200 lines holding six unrelated concerns and
their tests. Pure code motion into standard/{background, overlay,
scenes, conditional, command, engine, tests}, with mod.rs keeping the
docs, the chunk constants, the priority bands and glob re-exports, so
every external path is unchanged.

Items that were file-private and are now shared across the submodule
boundary carry pub(super); nothing gained crate visibility. Tests import
what they use instead of leaning on the parent's private imports.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/lighting/standard.rs             | 4221 ----------------------
 rmk/src/lighting/standard/background.rs  |  143 +
 rmk/src/lighting/standard/command.rs     |  509 +++
 rmk/src/lighting/standard/conditional.rs |  168 +
 rmk/src/lighting/standard/engine.rs      | 1272 +++++++
 rmk/src/lighting/standard/mod.rs         |   45 +
 rmk/src/lighting/standard/overlay.rs     |   61 +
 rmk/src/lighting/standard/scenes.rs      |  378 ++
 rmk/src/lighting/standard/tests.rs       | 1715 +++++++++
 9 files changed, 4291 insertions(+), 4221 deletions(-)
 delete mode 100644 rmk/src/lighting/standard.rs
 create mode 100644 rmk/src/lighting/standard/background.rs
 create mode 100644 rmk/src/lighting/standard/command.rs
 create mode 100644 rmk/src/lighting/standard/conditional.rs
 create mode 100644 rmk/src/lighting/standard/engine.rs
 create mode 100644 rmk/src/lighting/standard/mod.rs
 create mode 100644 rmk/src/lighting/standard/overlay.rs
 create mode 100644 rmk/src/lighting/standard/scenes.rs
 create mode 100644 rmk/src/lighting/standard/tests.rs

diff --git a/rmk/src/lighting/standard.rs b/rmk/src/lighting/standard.rs
deleted file mode 100644
index 851a45196..000000000
--- a/rmk/src/lighting/standard.rs
+++ /dev/null
@@ -1,4221 +0,0 @@
-//! Ready-to-use compositor engine for ordinary RMK lighting.
-//!
-//! Boards provide static layer scenes plus optional extension and status
-//! sources. The engine supplies a controllable uniform background, TTL host
-//! overlay, deterministic priority bands, output brightness, frame history,
-//! `LightAction` handling, and protocol-independent commands/readback.
-
-use core::cell::RefCell;
-use core::fmt;
-use core::num::NonZeroU32;
-
-use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
-use rmk_types::action::LightAction;
-
-use super::Rgb8;
-use super::compositor::{
-    Compositor, Contribution, ExtensionDescriptor, ExtensionParamSpec, ExtensionState, LightingSource, LogicalFrame,
-    RenderError, RenderInput as SourceRenderInput,
-};
-use super::context::{LightingContext, LightingContextProvider};
-use super::effect::{BuiltinEffect, LightingEffect};
-use super::output::BrightnessTransform;
-use super::service::{CommandResult, Invalidation, LightingEngine, RenderInput, RenderOutcome};
-use super::source::{
-    BatteryStatusProvider, ConditionSet, LayerPolicy, LayerScenes, LightingControls, OutputMode, OverlayError,
-    OverlayUpdate, SceneCell, SparseScene, TtlOverlay,
-};
-use super::topology::LedSlot;
-use crate::RawMutex;
-
-/// Cells per overlay readback page. Kept equal to the wire chunk size so
-/// protocol adapters can forward pages without re-batching.
-pub const OVERLAY_CHUNK_SIZE: usize = 8;
-
-/// Cells per scene page/replacement chunk. Kept equal to the wire chunk size
-/// so protocol adapters can forward chunks without re-batching.
-pub const SCENE_CHUNK_SIZE: usize = 8;
-
-/// Cells per runtime conditional-scene page/replacement chunk.
-pub const CONDITIONAL_SCENE_CHUNK_SIZE: usize = 8;
-
-/// A staged scene replacement expires after this much command inactivity.
-pub const SCENE_TRANSACTION_TIMEOUT_MS: u64 = 5_000;
-
-/// Stable default priority bands. Equal-priority call order remains stable.
-pub mod priority {
-    pub const BACKGROUND: u8 = 0;
-    pub const EXTENSION: u8 = 32;
-    pub const LAYER: u8 = 64;
-    pub const HOST_OVERLAY: u8 = 128;
-    pub const STATUS: u8 = 192;
-}
-
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub enum BackgroundMode {
-    Solid,
-    Breathe,
-}
-
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct BackgroundState {
-    pub enabled: bool,
-    pub hue: u8,
-    pub saturation: u8,
-    pub value: u8,
-    pub speed: u8,
-    pub mode: BackgroundMode,
-}
-
-impl Default for BackgroundState {
-    fn default() -> Self {
-        Self {
-            enabled: true,
-            hue: 0,
-            saturation: 0,
-            value: 32,
-            speed: 128,
-            mode: BackgroundMode::Solid,
-        }
-    }
-}
-
-/// Atomic partial update of the designated background.
-///
-/// Protocol adapters use this instead of a `ReadState` followed by
-/// `SetBackground`: the lighting engine remains the sole mutable owner and
-/// concurrent callers cannot overwrite fields changed between two mailbox
-/// requests.
-#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
-pub struct BackgroundPatch {
-    pub enabled: Option<bool>,
-    pub hue: Option<u8>,
-    pub saturation: Option<u8>,
-    pub value: Option<u8>,
-    pub speed: Option<u8>,
-    pub mode: Option<BackgroundMode>,
-}
-
-impl BackgroundPatch {
-    pub const fn apply_to(self, state: &mut BackgroundState) {
-        if let Some(enabled) = self.enabled {
-            state.enabled = enabled;
-        }
-        if let Some(hue) = self.hue {
-            state.hue = hue;
-        }
-        if let Some(saturation) = self.saturation {
-            state.saturation = saturation;
-        }
-        if let Some(value) = self.value {
-            state.value = value;
-        }
-        if let Some(speed) = self.speed {
-            state.speed = speed;
-        }
-        if let Some(mode) = self.mode {
-            state.mode = mode;
-        }
-    }
-}
-
-/// Built-in designated background controlled by RGB/Vial-compatible fields.
-#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
-pub struct UniformBackground<const N: usize> {
-    state: BackgroundState,
-}
-
-impl<const N: usize> UniformBackground<N> {
-    pub const fn new(state: BackgroundState) -> Self {
-        Self { state }
-    }
-
-    pub const fn state(&self) -> BackgroundState {
-        self.state
-    }
-
-    pub fn set_state(&mut self, state: BackgroundState) {
-        self.state = state;
-    }
-
-    fn effect(&self) -> BuiltinEffect {
-        let color = if self.state.enabled {
-            hsv(self.state.hue, self.state.saturation, self.state.value)
-        } else {
-            Rgb8::BLACK
-        };
-        match self.state.mode {
-            BackgroundMode::Solid => BuiltinEffect::Solid { color },
-            BackgroundMode::Breathe => BuiltinEffect::Breathe {
-                color,
-                period_ms: 250 + ((u8::MAX - self.state.speed) as u32 * 3_750 / 255),
-                phase_ms: 0,
-                step_ms: 16,
-            },
-        }
-    }
-}
-
-impl<Context, const N: usize> LightingSource<Rgb8, Context> for UniformBackground<N> {
-    fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
-        N
-    }
-
-    fn slot(&self, index: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
-        LedSlot::from_index(index)
-    }
-
-    fn contribution(&mut self, _: usize, input: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
-        Contribution::Opaque(self.effect().sample(input.now_ms))
-    }
-}
-
-/// Zero-sized source used when a board does not need an extension band.
-#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
-pub struct EmptySource;
-
-impl<C, Context> LightingSource<C, Context> for EmptySource {
-    fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
-        0
-    }
-
-    fn slot(&self, _: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
-        unreachable!("EmptySource has no targets")
-    }
-
-    fn contribution(&mut self, _: usize, _: &SourceRenderInput<'_, Context>) -> Contribution<C> {
-        unreachable!("EmptySource has no samples")
-    }
-}
-
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct OverlayCell {
-    pub slot: LedSlot,
-    pub effect: BuiltinEffect,
-    /// Relative lifetime from command application. `None` persists until an
-    /// explicit unset/clear or reboot.
-    pub ttl_ms: Option<NonZeroU32>,
-}
-
-const EMPTY_OVERLAY_CELL: OverlayCell = OverlayCell {
-    slot: LedSlot(0),
-    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
-    ttl_ms: None,
-};
-
-/// Fixed-capacity, owned batch suitable for a bounded async mailbox.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct OverlayBatch<const CAP: usize> {
-    cells: [OverlayCell; CAP],
-    len: usize,
-}
-
-impl<const CAP: usize> OverlayBatch<CAP> {
-    pub const fn new() -> Self {
-        Self {
-            cells: [EMPTY_OVERLAY_CELL; CAP],
-            len: 0,
-        }
-    }
-
-    pub fn push(&mut self, cell: OverlayCell) -> Result<(), OverlayError> {
-        if self.len == CAP {
-            return Err(OverlayError::TooManyEntries {
-                supplied: self.len + 1,
-                capacity: CAP,
-            });
-        }
-        self.cells[self.len] = cell;
-        self.len += 1;
-        Ok(())
-    }
-
-    pub fn as_slice(&self) -> &[OverlayCell] {
-        &self.cells[..self.len]
-    }
-}
-
-impl<const CAP: usize> Default for OverlayBatch<CAP> {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-/// One durable scene cell: an effect bound to a local slot on one layer.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct SceneTableCell {
-    pub layer: u8,
-    pub slot: LedSlot,
-    pub effect: BuiltinEffect,
-}
-
-const EMPTY_SCENE_CELL: SceneTableCell = SceneTableCell {
-    layer: 0,
-    slot: LedSlot(0),
-    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
-};
-
-/// Fixed-capacity, owned scene chunk suitable for a bounded async mailbox.
-/// One chunk is both a page of readback and a replacement-staging step.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct SceneChunk {
-    cells: [SceneTableCell; SCENE_CHUNK_SIZE],
-    len: usize,
-}
-
-impl Default for SceneChunk {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl SceneChunk {
-    pub const fn new() -> Self {
-        Self {
-            cells: [EMPTY_SCENE_CELL; SCENE_CHUNK_SIZE],
-            len: 0,
-        }
-    }
-
-    pub fn push(&mut self, cell: SceneTableCell) -> Result<(), StandardError> {
-        if self.len == SCENE_CHUNK_SIZE {
-            return Err(StandardError::InvalidSceneRequest);
-        }
-        self.cells[self.len] = cell;
-        self.len += 1;
-        Ok(())
-    }
-
-    pub fn as_slice(&self) -> &[SceneTableCell] {
-        &self.cells[..self.len]
-    }
-}
-
-/// Distinct effects one [`StylePool`] can hold at once.
-///
-/// This is the only capacity interning adds, and it is a far looser bound than
-/// a per-cell one: a keyboard paints many keys from a small set of colours, so
-/// a config with hundreds of painted keys typically names a handful of effects.
-pub const SCENE_STYLE_CAP: usize = 64;
-
-/// Effects held once and referenced by index, so a scene cell can carry one
-/// byte instead of a whole effect.
-///
-/// An inline [`BuiltinEffect`] is 16 bytes because blink and breathe each carry
-/// two millisecond timers, so a solid colour pays for animation fields it never
-/// uses and a cell costs 20 bytes. Interning moves the effect here and leaves
-/// the cell at 4, which matters more than it looks: the same capacity sizes the
-/// live tables, the replace staging buffer, the replica snapshot and the queued
-/// mailbox commands, so every byte saved per cell is saved several times over.
-///
-/// Freeing needs no reference counts. When a reference drops or is overwritten
-/// the caller reports it, the table is scanned for any remaining use, and the
-/// entry is freed if there is none -- cheaper to run on a host-driven operation
-/// than a set of counters is to keep correct. Occupancy is a bitmask, so a
-/// freed entry leaves a hole the next allocation reuses and entries never move,
-/// which means no cell's index ever needs rewriting.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct StylePool {
-    styles: [BuiltinEffect; SCENE_STYLE_CAP],
-    used: u64,
-}
-
-impl Default for StylePool {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl StylePool {
-    pub const fn new() -> Self {
-        Self {
-            styles: [BuiltinEffect::Solid { color: Rgb8::BLACK }; SCENE_STYLE_CAP],
-            used: 0,
-        }
-    }
-
-    /// Distinct effects currently held. Bounded by [`SCENE_STYLE_CAP`].
-    pub const fn len(&self) -> usize {
-        self.used.count_ones() as usize
-    }
-
-    pub const fn is_empty(&self) -> bool {
-        self.used == 0
-    }
-
-    /// Index for `effect`, reusing an entry when it is already held. `None`
-    /// only when a *new* effect would overflow, and then nothing is mutated.
-    pub fn intern(&mut self, effect: BuiltinEffect) -> Option<u8> {
-        if let Some(held) = self.find(effect) {
-            return Some(held);
-        }
-        let free = (0..SCENE_STYLE_CAP).find(|&index| !self.holds(index))?;
-        self.styles[free] = effect;
-        self.used |= 1 << free;
-        Some(free as u8)
-    }
-
-    pub fn get(&self, style: u8) -> Option<BuiltinEffect> {
-        let index = style as usize;
-        (index < SCENE_STYLE_CAP && self.holds(index)).then(|| self.styles[index])
-    }
-
-    /// Free `style` unless it is still referenced. The caller does the check,
-    /// so the pool's borrow stays independent of whatever holds the references.
-    pub fn release(&mut self, style: u8, still_referenced: bool) {
-        if (style as usize) < SCENE_STYLE_CAP && !still_referenced {
-            self.used &= !(1 << style as usize);
-        }
-    }
-
-    pub fn clear(&mut self) {
-        self.used = 0;
-    }
-
-    fn find(&self, effect: BuiltinEffect) -> Option<u8> {
-        (0..SCENE_STYLE_CAP)
-            .find(|&index| self.holds(index) && self.styles[index] == effect)
-            .map(|index| index as u8)
-    }
-
-    const fn holds(&self, index: usize) -> bool {
-        self.used & (1 << index) != 0
-    }
-}
-
-/// A scene cell as stored: the effect lives in the table's [`StylePool`].
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-struct InternedSceneCell {
-    layer: u8,
-    slot: LedSlot,
-    style: u8,
-}
-
-const EMPTY_INTERNED_CELL: InternedSceneCell = InternedSceneCell {
-    layer: 0,
-    slot: LedSlot(0),
-    style: 0,
-};
-
-/// Fixed-capacity runtime scene table with layer-aware composition.
-///
-/// Cells are unique per `(layer, slot)` and stored in insertion order; order
-/// is irrelevant to rendering because layer precedence comes from the policy
-/// and same-layer cells can never target the same slot.
-#[derive(Copy, Clone, Debug)]
-pub struct SceneTable<const CAP: usize> {
-    cells: [InternedSceneCell; CAP],
-    len: usize,
-    pool: StylePool,
-    policy: LayerPolicy,
-}
-
-impl<const CAP: usize> SceneTable<CAP> {
-    pub const fn new() -> Self {
-        Self {
-            cells: [EMPTY_INTERNED_CELL; CAP],
-            len: 0,
-            pool: StylePool::new(),
-            policy: LayerPolicy::ActiveStack,
-        }
-    }
-
-    pub const fn len(&self) -> usize {
-        self.len
-    }
-
-    pub const fn is_empty(&self) -> bool {
-        self.len == 0
-    }
-
-    pub const fn policy(&self) -> LayerPolicy {
-        self.policy
-    }
-
-    pub fn set_policy(&mut self, policy: LayerPolicy) -> bool {
-        let changed = self.policy != policy;
-        self.policy = policy;
-        changed
-    }
-
-    /// Insert or update the cell addressed by `(layer, slot)`.
-    pub fn set(&mut self, cell: SceneTableCell) -> Result<(), StandardError> {
-        let occupied = self.cells[..self.len]
-            .iter()
-            .position(|held| held.layer == cell.layer && held.slot == cell.slot);
-        if occupied.is_none() && self.len == CAP {
-            return Err(StandardError::SceneFull { capacity: CAP });
-        }
-        // Interning first means a full pool declines before anything is
-        // mutated, so a rejected set leaves the table exactly as it was.
-        let style = self.pool.intern(cell.effect).ok_or(StandardError::SceneFull {
-            capacity: SCENE_STYLE_CAP,
-        })?;
-        let interned = InternedSceneCell {
-            layer: cell.layer,
-            slot: cell.slot,
-            style,
-        };
-        match occupied {
-            Some(index) => {
-                let replaced = self.cells[index].style;
-                self.cells[index] = interned;
-                if replaced != style {
-                    self.release(replaced);
-                }
-            }
-            None => {
-                self.cells[self.len] = interned;
-                self.len += 1;
-            }
-        }
-        Ok(())
-    }
-
-    /// Free a style that no cell references any more.
-    fn release(&mut self, style: u8) {
-        let referenced = self.cells[..self.len].iter().any(|held| held.style == style);
-        self.pool.release(style, referenced);
-    }
-
-    /// Painted cells, with their effects resolved out of the pool.
-    pub fn iter(&self) -> impl Iterator<Item = SceneTableCell> + '_ {
-        self.cells[..self.len].iter().filter_map(move |held| {
-            self.pool.get(held.style).map(|effect| SceneTableCell {
-                layer: held.layer,
-                slot: held.slot,
-                effect,
-            })
-        })
-    }
-
-    /// Remove the cell addressed by `(layer, slot)`.
-    pub fn unset(&mut self, layer: u8, slot: LedSlot) -> bool {
-        if let Some(index) = self.cells[..self.len]
-            .iter()
-            .position(|cell| cell.layer == layer && cell.slot == slot)
-        {
-            let removed = self.cells[index].style;
-            self.len -= 1;
-            self.cells[index] = self.cells[self.len];
-            self.release(removed);
-            true
-        } else {
-            false
-        }
-    }
-
-    pub fn clear(&mut self) {
-        self.len = 0;
-        self.pool.clear();
-    }
-
-    /// One readback page starting at `offset`, clamped at the table's end.
-    pub fn page(&self, offset: u16) -> SceneChunk {
-        let mut chunk = SceneChunk::new();
-        for cell in self.iter().skip(offset as usize).take(SCENE_CHUNK_SIZE) {
-            chunk.push(cell).expect("page is chunk-bounded");
-        }
-        chunk
-    }
-
-    fn cell_for_layer(&self, layer: u8, wanted: &mut usize) -> Option<SceneTableCell> {
-        for cell in self.iter().filter(|cell| cell.layer == layer) {
-            if *wanted == 0 {
-                return Some(cell);
-            }
-            *wanted -= 1;
-        }
-        None
-    }
-
-    fn cell_at(&self, context: &LightingContext, mut wanted: usize) -> SceneTableCell {
-        let effective = context.layers.effective;
-        match self.policy {
-            LayerPolicy::EffectiveOnly => self.cell_for_layer(effective, &mut wanted),
-            LayerPolicy::ActiveStack => {
-                let default = context.layers.default;
-                if let Some(cell) = self.cell_for_layer(default, &mut wanted) {
-                    return cell;
-                }
-                for layer in 0..super::context::LayerState::CAPACITY {
-                    if layer != default
-                        && layer != effective
-                        && context.layers.is_active(layer)
-                        && let Some(cell) = self.cell_for_layer(layer, &mut wanted)
-                    {
-                        return cell;
-                    }
-                }
-                if effective != default {
-                    self.cell_for_layer(effective, &mut wanted)
-                } else {
-                    None
-                }
-            }
-        }
-        .expect("LightingSource index must be below len")
-    }
-
-    fn included_len(&self, context: &LightingContext) -> usize {
-        let effective = context.layers.effective;
-        self.cells[..self.len]
-            .iter()
-            .filter(|cell| match self.policy {
-                LayerPolicy::EffectiveOnly => cell.layer == effective,
-                LayerPolicy::ActiveStack => {
-                    cell.layer == context.layers.default
-                        || cell.layer == effective
-                        || context.layers.is_active(cell.layer)
-                }
-            })
-            .count()
-    }
-}
-
-impl<const CAP: usize> Default for SceneTable<CAP> {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl<const CAP: usize> PartialEq for SceneTable<CAP> {
-    fn eq(&self, other: &Self) -> bool {
-        // Cells past `len` are stale storage, not state, and a style index is
-        // an allocation detail -- two tables holding the same effects can
-        // number them differently -- so this compares resolved cells.
-        self.policy == other.policy && self.iter().eq(other.iter())
-    }
-}
-
-impl<const CAP: usize> Eq for SceneTable<CAP> {}
-
-impl<Context, const CAP: usize> LightingSource<Rgb8, Context> for SceneTable<CAP>
-where
-    Context: LightingContextProvider,
-{
-    fn len(&self, input: &SourceRenderInput<'_, Context>) -> usize {
-        self.included_len(input.context.lighting_context())
-    }
-
-    fn slot(&self, index: usize, input: &SourceRenderInput<'_, Context>) -> LedSlot {
-        self.cell_at(input.context.lighting_context(), index).slot
-    }
-
-    fn contribution(&mut self, index: usize, input: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
-        Contribution::Opaque(
-            self.cell_at(input.context.lighting_context(), index)
-                .effect
-                .sample(input.now_ms),
-        )
-    }
-}
-
-/// One ordered, runtime-authored conditional rule.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct RuntimeConditionalSceneCell {
-    pub conditions: ConditionSet,
-    pub slot: LedSlot,
-    pub effect: BuiltinEffect,
-}
-
-const EMPTY_CONDITIONAL_SCENE_CELL: RuntimeConditionalSceneCell = RuntimeConditionalSceneCell {
-    conditions: ConditionSet {
-        layer: None,
-        battery: None,
-    },
-    slot: LedSlot(0),
-    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
-};
-
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct RuntimeConditionalSceneChunk {
-    cells: [RuntimeConditionalSceneCell; CONDITIONAL_SCENE_CHUNK_SIZE],
-    len: usize,
-}
-
-impl RuntimeConditionalSceneChunk {
-    pub const fn new() -> Self {
-        Self {
-            cells: [EMPTY_CONDITIONAL_SCENE_CELL; CONDITIONAL_SCENE_CHUNK_SIZE],
-            len: 0,
-        }
-    }
-
-    pub fn push(&mut self, cell: RuntimeConditionalSceneCell) -> Result<(), StandardError> {
-        if self.len == CONDITIONAL_SCENE_CHUNK_SIZE {
-            return Err(StandardError::InvalidConditionalSceneRequest);
-        }
-        self.cells[self.len] = cell;
-        self.len += 1;
-        Ok(())
-    }
-
-    pub fn as_slice(&self) -> &[RuntimeConditionalSceneCell] {
-        &self.cells[..self.len]
-    }
-}
-
-impl Default for RuntimeConditionalSceneChunk {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-/// Fixed-capacity ordered conditional source. Order is semantic: later
-/// matching rules override earlier rules at the same compositor priority.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct RuntimeConditionalSceneTable<const CAP: usize> {
-    cells: [RuntimeConditionalSceneCell; CAP],
-    len: usize,
-}
-
-impl<const CAP: usize> RuntimeConditionalSceneTable<CAP> {
-    pub const fn new() -> Self {
-        Self {
-            cells: [EMPTY_CONDITIONAL_SCENE_CELL; CAP],
-            len: 0,
-        }
-    }
-
-    pub const fn len(&self) -> usize {
-        self.len
-    }
-
-    pub const fn is_empty(&self) -> bool {
-        self.len == 0
-    }
-
-    pub fn as_slice(&self) -> &[RuntimeConditionalSceneCell] {
-        &self.cells[..self.len]
-    }
-
-    pub fn push(&mut self, cell: RuntimeConditionalSceneCell) -> Result<(), StandardError> {
-        if self.len == CAP {
-            return Err(StandardError::ConditionalSceneFull { capacity: CAP });
-        }
-        self.cells[self.len] = cell;
-        self.len += 1;
-        Ok(())
-    }
-
-    pub fn clear(&mut self) {
-        self.len = 0;
-    }
-
-    pub fn page(&self, offset: u16) -> RuntimeConditionalSceneChunk {
-        let start = (offset as usize).min(self.len);
-        let end = (start + CONDITIONAL_SCENE_CHUNK_SIZE).min(self.len);
-        let mut chunk = RuntimeConditionalSceneChunk::new();
-        for cell in &self.cells[start..end] {
-            chunk.push(*cell).expect("page is chunk-bounded");
-        }
-        chunk
-    }
-}
-
-impl<const CAP: usize> Default for RuntimeConditionalSceneTable<CAP> {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-struct RuntimeConditionalSource<'a, Batteries: ?Sized, const CAP: usize> {
-    table: &'a RuntimeConditionalSceneTable<CAP>,
-    batteries: &'a Batteries,
-}
-
-impl<Context, Batteries, const CAP: usize> LightingSource<Rgb8, Context>
-    for RuntimeConditionalSource<'_, Batteries, CAP>
-where
-    Context: LightingContextProvider,
-    Batteries: BatteryStatusProvider + ?Sized,
-{
-    fn len(&self, input: &SourceRenderInput<'_, Context>) -> usize {
-        self.table
-            .as_slice()
-            .iter()
-            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
-            .count()
-    }
-
-    fn slot(&self, index: usize, input: &SourceRenderInput<'_, Context>) -> LedSlot {
-        self.table
-            .as_slice()
-            .iter()
-            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
-            .nth(index)
-            .expect("LightingSource index must be below len")
-            .slot
-    }
-
-    fn contribution(&mut self, index: usize, input: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
-        let cell = self
-            .table
-            .as_slice()
-            .iter()
-            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
-            .nth(index)
-            .expect("LightingSource index must be below len");
-        Contribution::Opaque(cell.effect.sample(input.now_ms))
-    }
-}
-
-struct NoBatteryStatus;
-
-impl BatteryStatusProvider for NoBatteryStatus {
-    fn battery_status(&self, _node: u8) -> crate::types::battery::BatteryStatus {
-        crate::types::battery::BatteryStatus::Unavailable
-    }
-}
-
-static NO_BATTERY_STATUS: NoBatteryStatus = NoBatteryStatus;
-
-/// One in-progress, chunk-staged atomic scene replacement.
-///
-/// The overlay replacement stages host-side because a whole overlay batch
-/// fits one mailbox command. A scene table is an order of magnitude larger,
-/// so its transaction stages inside the engine via bounded chunks instead of
-/// forcing kilobyte-sized command payloads through every mailbox.
-struct SceneReplace<const CAP: usize> {
-    id: u32,
-    expected_revision: u32,
-    expected_count: u16,
-    cells: [SceneTableCell; CAP],
-    len: usize,
-    last_activity_ms: u64,
-}
-
-struct RuntimeConditionalSceneReplace<const CAP: usize> {
-    id: u32,
-    expected_revision: u32,
-    expected_count: u16,
-    cells: [RuntimeConditionalSceneCell; CAP],
-    len: usize,
-    last_activity_ms: u64,
-}
-
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
-    SetOutputEnabled(bool),
-    SetOutputModeIfRevision {
-        expected_revision: u32,
-        mode: OutputMode,
-    },
-    SetOutputBrightness(u8),
-    SetBackground(BackgroundState),
-    PatchBackground(BackgroundPatch),
-    SetStateIfRevision {
-        expected_revision: u32,
-        state: StandardMutableState,
-    },
-    SetOverlay(OverlayCell),
-    SetOverlayIfRevision {
-        expected_revision: u32,
-        cell: OverlayCell,
-    },
-    UnsetOverlay(LedSlot),
-    UnsetOverlayIfRevision {
-        expected_revision: u32,
-        slot: LedSlot,
-    },
-    ClearOverlay,
-    ClearOverlayIfRevision {
-        expected_revision: u32,
-    },
-    ReplaceOverlay(OverlayBatch<OVERLAY_CAP>),
-    ReplaceOverlayIfRevision {
-        expected_revision: u32,
-        batch: OverlayBatch<OVERLAY_CAP>,
-    },
-    /// Atomically export all state needed by a renderer replica. The larger
-    /// snapshot moves through the referenced slot so it does not inflate
-    /// every element of the bounded command queue.
-    ExportReplica(&'static StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP>),
-    /// Atomically install a snapshot previously placed in the referenced
-    /// slot. Intended for a renderer replica, not a second authority.
-    ApplyReplica(&'static StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP>),
-    ReadState,
-    /// Descriptor and current selection of the extension source, if any.
-    ReadExtension,
-    SetExtensionIfRevision {
-        expected_revision: u32,
-        state: ExtensionState,
-    },
-    /// One page of the addressed effect's parameter specs paired with the
-    /// source's live values.
-    ReadExtensionParams {
-        effect: u8,
-        offset: u8,
-    },
-    SetExtensionParamIfRevision {
-        expected_revision: u32,
-        effect: u8,
-        index: u8,
-        value: u8,
-    },
-    /// One atomically sampled page of the transient overlay.
-    ReadOverlay {
-        offset: u16,
-    },
-    SetSceneCellIfRevision {
-        expected_revision: u32,
-        cell: SceneTableCell,
-    },
-    UnsetSceneCellIfRevision {
-        expected_revision: u32,
-        layer: u8,
-        slot: LedSlot,
-    },
-    SetLayerPolicyIfRevision {
-        expected_revision: u32,
-        policy: LayerPolicy,
-    },
-    /// Reserve the engine's single scene-staging transaction. The expected
-    /// revision is recorded here and enforced atomically at commit.
-    BeginSceneReplace {
-        expected_revision: u32,
-        cell_count: u16,
-    },
-    PutSceneChunk {
-        transaction_id: u32,
-        offset: u16,
-        cells: SceneChunk,
-    },
-    CommitSceneReplace {
-        transaction_id: u32,
-    },
-    AbortSceneReplace {
-        transaction_id: u32,
-    },
-    /// One page of the stored scene table starting at `offset`.
-    ReadScenes {
-        offset: u16,
-    },
-    /// One page of the immutable board-compiled layer scenes.
-    ReadCompiledScenes {
-        offset: u16,
-    },
-    ReadRuntimeConditionalScenes {
-        offset: u16,
-    },
-    BeginRuntimeConditionalSceneReplace {
-        expected_revision: u32,
-        cell_count: u16,
-    },
-    PutRuntimeConditionalSceneChunk {
-        transaction_id: u32,
-        offset: u16,
-        cells: RuntimeConditionalSceneChunk,
-    },
-    CommitRuntimeConditionalSceneReplace {
-        transaction_id: u32,
-    },
-    AbortRuntimeConditionalSceneReplace {
-        transaction_id: u32,
-    },
-}
-
-/// Mutable standard state excluding the transient overlay contents and the
-/// engine-owned optimistic-concurrency revision.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct StandardMutableState {
-    pub output_enabled: bool,
-    pub output_brightness: u8,
-    pub background: BackgroundState,
-}
-
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct StandardState {
-    pub revision: u32,
-    pub output_enabled: bool,
-    pub output_mode: OutputMode,
-    pub powered: bool,
-    pub wake_active: bool,
-    pub output_brightness: u8,
-    pub background: BackgroundState,
-    pub overlay_len: usize,
-    pub scene_len: usize,
-    pub scene_policy: LayerPolicy,
-    pub runtime_conditional_scene_len: usize,
-}
-
-/// One page of transient overlay cells with remaining TTLs.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct OverlayPage {
-    pub revision: u32,
-    pub total: u16,
-    pub cells: OverlayBatch<OVERLAY_CHUNK_SIZE>,
-}
-
-/// One page of stored scene cells with the revision it was read under.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct ScenePage {
-    pub revision: u32,
-    pub total: u16,
-    pub cells: SceneChunk,
-}
-
-/// Extension-source readback: selectable content plus current selection.
-/// `descriptor`/`state` are `None` when the engine's extension band is not
-/// user-selectable (e.g. `EmptySource`).
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct ExtensionPage {
-    pub revision: u32,
-    pub descriptor: Option<ExtensionDescriptor>,
-    pub state: Option<ExtensionState>,
-}
-
-/// Number of extension parameters carried by one [`ExtensionParamsPage`].
-pub const EXTENSION_PARAM_CHUNK: usize = 8;
-
-/// One extension parameter: its static spec plus the source's live value.
-/// The value falls back to the spec's default when the source does not
-/// report one.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct ExtensionParamValue {
-    pub spec: ExtensionParamSpec,
-    pub value: u8,
-}
-
-/// One page of an extension effect's parameters. Pinned to the engine
-/// revision like every other mutable readback.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct ExtensionParamsPage {
-    pub revision: u32,
-    /// Total parameters the addressed effect advertises.
-    pub total: u8,
-    /// Rows starting at the request's offset; trailing entries are `None`.
-    pub items: [Option<ExtensionParamValue>; EXTENSION_PARAM_CHUNK],
-}
-
-impl ExtensionParamsPage {
-    /// The populated rows, in order.
-    pub fn items(&self) -> impl Iterator<Item = ExtensionParamValue> + '_ {
-        self.items.iter().copied().flatten()
-    }
-}
-
-/// The active effect's live parameter values, carried in a replica snapshot
-/// so a split renderer tracks the authority's tuning.
-///
-/// Only the active effect travels: it is the only one a replica renders, and
-/// bounding the row at [`EXTENSION_PARAM_CHUNK`] keeps the snapshot `Copy`
-/// with a fixed RAM cost. Parameters of inactive effects ride along when
-/// that effect becomes active, since export always reads live values.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct ExtensionReplicaParams {
-    pub effect: u8,
-    pub len: u8,
-    pub values: [u8; EXTENSION_PARAM_CHUNK],
-}
-
-impl ExtensionReplicaParams {
-    /// The populated values, in parameter order.
-    pub fn values(&self) -> &[u8] {
-        &self.values[..(self.len as usize).min(EXTENSION_PARAM_CHUNK)]
-    }
-}
-
-/// The parameter specs an extension source advertises for `effect`.
-///
-/// A free function because the callers live in the engine's `LightingEngine`
-/// impl, where `Context` is in scope but no inherent impl carries the
-/// [`LightingSource`] bound.
-fn extension_param_specs<C, Context, S>(source: &S, effect: u8) -> Result<&'static [ExtensionParamSpec], StandardError>
-where
-    S: LightingSource<C, Context> + ?Sized,
-{
-    source
-        .extension_descriptor()
-        .and_then(|descriptor| descriptor.effect_params(effect))
-        .ok_or(StandardError::ExtensionUnsupported)
-}
-
-/// Check one parameter's address and its spec's range without applying it.
-///
-/// Split from the apply so replica application can validate a whole batch
-/// before mutating anything, the way the overlay is validated first.
-fn check_extension_param<C, Context, S>(source: &S, effect: u8, index: u8, value: u8) -> Result<(), StandardError>
-where
-    S: LightingSource<C, Context> + ?Sized,
-{
-    let specs = extension_param_specs::<C, Context, S>(source, effect)?;
-    let spec = specs.get(index as usize).ok_or(StandardError::ExtensionUnsupported)?;
-    if value < spec.min || value > spec.max {
-        return Err(StandardError::ExtensionUnsupported);
-    }
-    Ok(())
-}
-
-/// Validate one parameter against its spec, then offer it to the source.
-///
-/// Shared by the host-facing set command and replica application so both
-/// reject the same addresses and the same out-of-range values.
-fn apply_extension_param_checked<C, Context, S>(
-    source: &mut S,
-    effect: u8,
-    index: u8,
-    value: u8,
-) -> Result<(), StandardError>
-where
-    S: LightingSource<C, Context> + ?Sized,
-{
-    check_extension_param::<C, Context, S>(source, effect, index, value)?;
-    if !source.apply_extension_param(effect, index, value) {
-        return Err(StandardError::ExtensionUnsupported);
-    }
-    Ok(())
-}
-
-/// One page of immutable board-compiled layer scenes.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct CompiledScenePage {
-    pub total: u16,
-    pub policy: LayerPolicy,
-    pub cells: SceneChunk,
-}
-
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct RuntimeConditionalScenePage {
-    pub revision: u32,
-    pub total: u16,
-    pub cells: RuntimeConditionalSceneChunk,
-}
-
-/// Protocol-independent readback for [`StandardCommand`]s. Most commands
-/// answer with authoritative [`StandardState`]; scene reads and transaction
-/// reservation carry their own shapes.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub enum StandardReply {
-    State(StandardState),
-    OverlayPage(OverlayPage),
-    ScenesPage(ScenePage),
-    CompiledScenesPage(CompiledScenePage),
-    SceneTransaction { id: u32, cell_count: u16 },
-    Extension(ExtensionPage),
-    ExtensionParams(ExtensionParamsPage),
-    RuntimeConditionalScenesPage(RuntimeConditionalScenePage),
-    RuntimeConditionalSceneTransaction { id: u32, cell_count: u16 },
-}
-
-impl StandardReply {
-    /// The state readback carried by state-shaped replies.
-    pub const fn state(self) -> Option<StandardState> {
-        match self {
-            Self::State(state) => Some(state),
-            _ => None,
-        }
-    }
-}
-
-/// Complete declarative state needed by a standard-engine renderer replica.
-///
-/// `sample_time_ms` is the authority's animation clock at snapshot time.
-/// Applying the snapshot anchors the replica's local monotonic clock to that
-/// value; subsequent animation frames are sampled locally without link
-/// traffic. Overlay TTLs are remaining lifetimes at the same instant.
-///
-/// The runtime scene table travels with the snapshot: replicas must render
-/// host-configured per-layer scenes exactly like the authority, and they
-/// never receive the incremental scene mutation commands themselves.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct StandardReplicaState<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
-    pub revision: u32,
-    pub mutable: StandardMutableState,
-    pub output_mode: OutputMode,
-    pub overlay: OverlayBatch<OVERLAY_CAP>,
-    pub scenes: SceneTable<SCENE_CAP>,
-    pub runtime_conditional_scenes: RuntimeConditionalSceneTable<SCENE_CAP>,
-    pub context: LightingContext,
-    pub sample_time_ms: u64,
-    /// Extension-source selection, carried so split renderer replicas track
-    /// the authority's animated band. `None` when the authority has no
-    /// selectable extension.
-    pub extension: Option<ExtensionState>,
-    /// The active effect's live parameter values. `None` when the authority
-    /// has no selectable extension or the active effect has no parameters.
-    pub extension_params: Option<ExtensionReplicaParams>,
-}
-
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub enum ReplicaSlotError {
-    Busy,
-    Empty,
-}
-
-/// One statically allocated hand-off slot for a replica snapshot.
-///
-/// The lighting mailbox serializes access. Keeping the large snapshot out of
-/// [`StandardCommand`] prevents command-channel capacity from multiplying its
-/// RAM cost on small MCUs.
-pub struct StandardReplicaSlot<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
-    value: BlockingMutex<RawMutex, RefCell<Option<StandardReplicaState<OVERLAY_CAP, SCENE_CAP>>>>,
-}
-
-impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
-    pub const fn new() -> Self {
-        Self {
-            value: BlockingMutex::new(RefCell::new(None)),
-        }
-    }
-
-    pub fn put(&self, state: StandardReplicaState<OVERLAY_CAP, SCENE_CAP>) -> Result<(), ReplicaSlotError> {
-        self.value.lock(|value| {
-            let mut value = value.borrow_mut();
-            if value.is_some() {
-                Err(ReplicaSlotError::Busy)
-            } else {
-                *value = Some(state);
-                Ok(())
-            }
-        })
-    }
-
-    pub fn take(&self) -> Result<StandardReplicaState<OVERLAY_CAP, SCENE_CAP>, ReplicaSlotError> {
-        self.value
-            .lock(|value| value.borrow_mut().take().ok_or(ReplicaSlotError::Empty))
-    }
-}
-
-impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> Default for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> fmt::Debug for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.debug_struct("StandardReplicaSlot").finish_non_exhaustive()
-    }
-}
-
-impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> PartialEq for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
-    fn eq(&self, other: &Self) -> bool {
-        core::ptr::eq(self, other)
-    }
-}
-
-impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> Eq for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {}
-
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub enum StandardError {
-    Render(RenderError),
-    Overlay(OverlayError),
-    DeadlineOverflow,
-    ReplicaSlot(ReplicaSlotError),
-    RevisionConflict {
-        expected: u32,
-        current: u32,
-    },
-    SceneFull {
-        capacity: usize,
-    },
-    SceneSlotOutOfRange {
-        slot: LedSlot,
-    },
-    /// Malformed scene request: bad chunk order, count overflow, or a
-    /// duplicate `(layer, slot)` within one staged replacement.
-    InvalidSceneRequest,
-    /// The extension source declined the state (none installed, or an index
-    /// out of its descriptor's range).
-    ExtensionUnsupported,
-    SceneTransactionBusy,
-    InvalidSceneTransaction,
-    SceneTransactionExpired,
-    SceneTransactionIncomplete {
-        expected: u16,
-        received: u16,
-    },
-    ConditionalSceneFull {
-        capacity: usize,
-    },
-    InvalidConditionalSceneRequest,
-    ConditionalSceneTransactionBusy,
-    InvalidConditionalSceneTransaction,
-    ConditionalSceneTransactionExpired,
-    ConditionalSceneTransactionIncomplete {
-        expected: u16,
-        received: u16,
-    },
-}
-
-impl From<RenderError> for StandardError {
-    fn from(value: RenderError) -> Self {
-        Self::Render(value)
-    }
-}
-
-impl From<OverlayError> for StandardError {
-    fn from(value: OverlayError) -> Self {
-        Self::Overlay(value)
-    }
-}
-
-impl From<ReplicaSlotError> for StandardError {
-    fn from(value: ReplicaSlotError) -> Self {
-        Self::ReplicaSlot(value)
-    }
-}
-
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-struct AnimationClock {
-    local_anchor_ms: u64,
-    shared_anchor_ms: u64,
-}
-
-impl AnimationClock {
-    const fn local() -> Self {
-        Self {
-            local_anchor_ms: 0,
-            shared_anchor_ms: 0,
-        }
-    }
-
-    fn sample_time(self, local_now_ms: u64) -> u64 {
-        self.shared_anchor_ms
-            .saturating_add(local_now_ms.saturating_sub(self.local_anchor_ms))
-    }
-
-    fn anchor(&mut self, local_now_ms: u64, shared_now_ms: u64) {
-        self.local_anchor_ms = local_now_ms;
-        self.shared_anchor_ms = shared_now_ms;
-    }
-}
-
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct StandardInput(pub LightAction);
-
-impl From<LightAction> for StandardInput {
-    fn from(value: LightAction) -> Self {
-        Self(value)
-    }
-}
-
-/// End-to-end standard engine. `Extension` composes above the designated
-/// background and below layers; `Status` composes last. Either can be an
-/// external stateful source, or [`EmptySource`].
-///
-/// Static board layer scenes and the runtime [`SceneTable`] share the layer
-/// band: runtime cells apply after the static defaults, so a host-configured
-/// cell overrides a board default for the same slot while the TTL overlay
-/// still wins above both.
-pub struct StandardLightingEngine<
-    'scenes,
-    Extension,
-    Status,
-    const N: usize,
-    const OVERLAY_CAP: usize,
-    const SCENE_CAP: usize = 0,
-> {
-    compositor: Compositor<Rgb8, N>,
-    background: UniformBackground<N>,
-    extension: Extension,
-    layers: LayerScenes<'scenes, BuiltinEffect>,
-    scenes: SceneTable<SCENE_CAP>,
-    runtime_conditional_scenes: RuntimeConditionalSceneTable<SCENE_CAP>,
-    battery_status: &'scenes dyn BatteryStatusProvider,
-    overlay: TtlOverlay<BuiltinEffect, OVERLAY_CAP>,
-    status: Status,
-    animation_clock: AnimationClock,
-    scene_replace: Option<SceneReplace<SCENE_CAP>>,
-    scene_next_transaction: u32,
-    scene_expired_transaction: Option<u32>,
-    scene_committed_transaction: Option<u32>,
-    runtime_conditional_scene_replace: Option<RuntimeConditionalSceneReplace<SCENE_CAP>>,
-    runtime_conditional_scene_next_transaction: u32,
-    runtime_conditional_scene_expired_transaction: Option<u32>,
-    runtime_conditional_scene_committed_transaction: Option<u32>,
-    revision: u32,
-    controls: LightingControls,
-    output_mode: OutputMode,
-    powered: bool,
-    wake_active: bool,
-    effective_output_enabled: bool,
-    output_brightness: u8,
-}
-
-impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const SCENE_CAP: usize>
-    StandardLightingEngine<'scenes, Extension, Status, N, OVERLAY_CAP, SCENE_CAP>
-{
-    pub fn new(
-        background: BackgroundState,
-        layers: LayerScenes<'scenes, BuiltinEffect>,
-        extension: Extension,
-        status: Status,
-    ) -> Self {
-        Self {
-            compositor: Compositor::new(Rgb8::BLACK),
-            background: UniformBackground::new(background),
-            extension,
-            layers,
-            scenes: SceneTable::new(),
-            runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
-            battery_status: &NO_BATTERY_STATUS,
-            overlay: TtlOverlay::new(),
-            status,
-            animation_clock: AnimationClock::local(),
-            scene_replace: None,
-            scene_next_transaction: 1,
-            scene_expired_transaction: None,
-            scene_committed_transaction: None,
-            runtime_conditional_scene_replace: None,
-            runtime_conditional_scene_next_transaction: 1,
-            runtime_conditional_scene_expired_transaction: None,
-            runtime_conditional_scene_committed_transaction: None,
-            revision: 0,
-            controls: LightingControls::default(),
-            output_mode: OutputMode::AlwaysOn,
-            powered: false,
-            wake_active: false,
-            effective_output_enabled: true,
-            output_brightness: u8::MAX,
-        }
-    }
-
-    /// Install the board's declarative lighting controls before the engine is
-    /// served. The configured initial mode becomes authoritative on boot.
-    pub const fn with_controls(mut self, controls: LightingControls) -> Self {
-        self.output_mode = controls.initial_output_mode;
-        self.effective_output_enabled = matches!(self.output_mode, OutputMode::AlwaysOn);
-        self.controls = controls;
-        self
-    }
-
-    /// Supply live board battery state for runtime conditional predicates.
-    pub const fn with_battery_status_provider(mut self, battery_status: &'scenes dyn BatteryStatusProvider) -> Self {
-        self.battery_status = battery_status;
-        self
-    }
-
-    pub const fn output_mode(&self) -> OutputMode {
-        self.output_mode
-    }
-
-    pub const fn powered(&self) -> bool {
-        self.powered
-    }
-
-    pub const fn wake_active(&self) -> bool {
-        self.wake_active
-    }
-
-    const fn effective_output(&self) -> bool {
-        self.wake_active
-            || matches!(self.output_mode, OutputMode::AlwaysOn)
-            || matches!(self.output_mode, OutputMode::PoweredOnly) && self.powered
-    }
-
-    pub fn state(&self) -> StandardState {
-        StandardState {
-            revision: self.revision,
-            output_enabled: self.effective_output(),
-            output_mode: self.output_mode,
-            powered: self.powered,
-            wake_active: self.wake_active,
-            output_brightness: self.output_brightness,
-            background: self.background.state(),
-            overlay_len: self.overlay.active_len(),
-            scene_len: self.scenes.len(),
-            scene_policy: self.scenes.policy(),
-            runtime_conditional_scene_len: self.runtime_conditional_scenes.len(),
-        }
-    }
-
-    pub const fn scene_capacity() -> usize {
-        SCENE_CAP
-    }
-
-    pub const fn scenes(&self) -> &SceneTable<SCENE_CAP> {
-        &self.scenes
-    }
-
-    pub const fn runtime_conditional_scenes(&self) -> &RuntimeConditionalSceneTable<SCENE_CAP> {
-        &self.runtime_conditional_scenes
-    }
-
-    /// Install one persisted scene cell during startup, before the engine is
-    /// serving commands. Does not advance the concurrency revision.
-    pub fn install_scene_cell(&mut self, cell: SceneTableCell) -> Result<(), StandardError> {
-        Self::check_scene_slot(cell.slot)?;
-        self.scenes.set(cell)
-    }
-
-    /// Install the persisted layer policy during startup.
-    pub fn install_scene_policy(&mut self, policy: LayerPolicy) {
-        self.scenes.set_policy(policy);
-    }
-
-    /// Install one persisted runtime conditional rule during startup.
-    pub fn install_runtime_conditional_scene_cell(
-        &mut self,
-        cell: RuntimeConditionalSceneCell,
-    ) -> Result<(), StandardError> {
-        Self::check_scene_slot(cell.slot)?;
-        self.runtime_conditional_scenes.push(cell)
-    }
-
-    pub const fn extension(&self) -> &Extension {
-        &self.extension
-    }
-
-    pub fn extension_mut(&mut self) -> &mut Extension {
-        &mut self.extension
-    }
-
-    pub const fn status(&self) -> &Status {
-        &self.status
-    }
-
-    pub fn status_mut(&mut self) -> &mut Status {
-        &mut self.status
-    }
-
-    fn apply_light_action(&mut self, action: LightAction) -> bool {
-        const STEP: u8 = 17;
-        let background = &mut self.background.state;
-        match action {
-            LightAction::BacklightOn => self.output_mode = OutputMode::AlwaysOn,
-            LightAction::BacklightOff => self.output_mode = OutputMode::AlwaysOff,
-            LightAction::BacklightToggle => {
-                self.output_mode = if matches!(self.output_mode, OutputMode::AlwaysOff) {
-                    OutputMode::AlwaysOn
-                } else {
-                    OutputMode::AlwaysOff
-                }
-            }
-            LightAction::OutputModeCycle => self.output_mode = self.output_mode.next(),
-            LightAction::BacklightDown => self.output_brightness = self.output_brightness.saturating_sub(STEP),
-            LightAction::BacklightUp => self.output_brightness = self.output_brightness.saturating_add(STEP),
-            LightAction::BacklightStep => self.output_brightness = self.output_brightness.wrapping_add(STEP),
-            LightAction::BacklightToggleBreathing => {
-                background.mode = match background.mode {
-                    BackgroundMode::Solid => BackgroundMode::Breathe,
-                    BackgroundMode::Breathe => BackgroundMode::Solid,
-                }
-            }
-            LightAction::RgbTog => background.enabled = !background.enabled,
-            LightAction::RgbModeForward | LightAction::RgbModeReverse => {
-                background.mode = match background.mode {
-                    BackgroundMode::Solid => BackgroundMode::Breathe,
-                    BackgroundMode::Breathe => BackgroundMode::Solid,
-                }
-            }
-            LightAction::RgbHui => background.hue = background.hue.wrapping_add(STEP),
-            LightAction::RgbHud => background.hue = background.hue.wrapping_sub(STEP),
-            LightAction::RgbSai => background.saturation = background.saturation.saturating_add(STEP),
-            LightAction::RgbSad => background.saturation = background.saturation.saturating_sub(STEP),
-            LightAction::RgbVai => background.value = background.value.saturating_add(STEP),
-            LightAction::RgbVad => background.value = background.value.saturating_sub(STEP),
-            LightAction::RgbSpi => background.speed = background.speed.saturating_add(STEP),
-            LightAction::RgbSpd => background.speed = background.speed.saturating_sub(STEP),
-            LightAction::RgbModePlain => background.mode = BackgroundMode::Solid,
-            LightAction::RgbModeBreathe => background.mode = BackgroundMode::Breathe,
-            // The standard engine advertises only Solid and Breathe. Other
-            // named modes remain available to an extension source/command.
-            _ => return false,
-        }
-        true
-    }
-
-    fn check_revision(&self, expected: u32) -> Result<(), StandardError> {
-        if expected == self.revision {
-            Ok(())
-        } else {
-            Err(StandardError::RevisionConflict {
-                expected,
-                current: self.revision,
-            })
-        }
-    }
-
-    fn advance_revision(&mut self) {
-        self.revision = self.revision.wrapping_add(1);
-    }
-
-    fn set_mutable_state(&mut self, state: StandardMutableState) {
-        self.output_mode = if state.output_enabled {
-            OutputMode::AlwaysOn
-        } else {
-            OutputMode::AlwaysOff
-        };
-        self.output_brightness = state.output_brightness;
-        self.background.set_state(state.background);
-    }
-
-    fn mutable_state(&self) -> StandardMutableState {
-        StandardMutableState {
-            output_enabled: self.effective_output(),
-            output_brightness: self.output_brightness,
-            background: self.background.state(),
-        }
-    }
-
-    fn replica_state<Context: LightingContextProvider>(
-        &self,
-        local_now_ms: u64,
-        context: &Context,
-    ) -> Result<StandardReplicaState<OVERLAY_CAP, SCENE_CAP>, StandardError> {
-        let sample_time_ms = self.animation_clock.sample_time(local_now_ms);
-        let mut overlay = OverlayBatch::new();
-        for update in self.overlay.active_updates() {
-            let ttl_ms = match update.expires_ms {
-                Some(expires_ms) if expires_ms > sample_time_ms => {
-                    let remaining = expires_ms - sample_time_ms;
-                    Some(NonZeroU32::new(remaining.min(u32::MAX as u64) as u32).unwrap())
-                }
-                Some(_) => continue,
-                None => None,
-            };
-            overlay.push(OverlayCell {
-                slot: update.slot,
-                effect: update.effect,
-                ttl_ms,
-            })?;
-        }
-        Ok(StandardReplicaState {
-            revision: self.revision,
-            mutable: self.mutable_state(),
-            output_mode: self.output_mode,
-            overlay,
-            scenes: self.scenes,
-            runtime_conditional_scenes: self.runtime_conditional_scenes,
-            context: *context.lighting_context(),
-            sample_time_ms,
-            // Filled by handle_command, where the LightingSource bound is
-            // available on the Extension parameter.
-            extension: None,
-            extension_params: None,
-        })
-    }
-
-    fn replica_overlay(
-        replica: &StandardReplicaState<OVERLAY_CAP, SCENE_CAP>,
-    ) -> Result<TtlOverlay<BuiltinEffect, OVERLAY_CAP>, StandardError> {
-        let mut updates = [OverlayUpdate {
-            slot: LedSlot(0),
-            effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
-            expires_ms: None,
-        }; OVERLAY_CAP];
-        for (target, cell) in updates.iter_mut().zip(replica.overlay.as_slice().iter().copied()) {
-            *target = OverlayUpdate {
-                slot: cell.slot,
-                effect: cell.effect,
-                expires_ms: cell
-                    .ttl_ms
-                    .and_then(|ttl| replica.sample_time_ms.checked_add(ttl.get() as u64)),
-            };
-            if cell.ttl_ms.is_some() && target.expires_ms.is_none() {
-                return Err(StandardError::DeadlineOverflow);
-            }
-        }
-        let mut overlay = TtlOverlay::new();
-        overlay.replace(replica.sample_time_ms, &updates[..replica.overlay.as_slice().len()])?;
-        Ok(overlay)
-    }
-
-    fn apply_replica(
-        &mut self,
-        local_now_ms: u64,
-        replica: StandardReplicaState<OVERLAY_CAP, SCENE_CAP>,
-        overlay: TtlOverlay<BuiltinEffect, OVERLAY_CAP>,
-    ) {
-        self.overlay = overlay;
-        self.set_mutable_state(replica.mutable);
-        self.output_mode = replica.output_mode;
-        self.scenes = replica.scenes;
-        self.runtime_conditional_scenes = replica.runtime_conditional_scenes;
-        self.revision = replica.revision;
-        self.animation_clock.anchor(local_now_ms, replica.sample_time_ms);
-    }
-
-    fn expires_at(now_ms: u64, ttl_ms: Option<NonZeroU32>) -> Result<Option<u64>, StandardError> {
-        ttl_ms
-            .map(|ttl| {
-                now_ms
-                    .checked_add(ttl.get() as u64)
-                    .ok_or(StandardError::DeadlineOverflow)
-            })
-            .transpose()
-    }
-
-    fn overlay_update(now_ms: u64, cell: OverlayCell) -> Result<OverlayUpdate<BuiltinEffect>, StandardError> {
-        Ok(OverlayUpdate {
-            slot: cell.slot,
-            effect: cell.effect,
-            expires_ms: Self::expires_at(now_ms, cell.ttl_ms)?,
-        })
-    }
-
-    fn check_scene_slot(slot: LedSlot) -> Result<(), StandardError> {
-        if slot.index() < N {
-            Ok(())
-        } else {
-            Err(StandardError::SceneSlotOutOfRange { slot })
-        }
-    }
-
-    fn expire_scene_replace(&mut self, now_ms: u64) {
-        if self
-            .scene_replace
-            .as_ref()
-            .is_some_and(|replace| now_ms.saturating_sub(replace.last_activity_ms) >= SCENE_TRANSACTION_TIMEOUT_MS)
-        {
-            self.scene_expired_transaction = self.scene_replace.as_ref().map(|replace| replace.id);
-            self.scene_replace = None;
-        }
-    }
-
-    fn scene_transaction_error(&self, id: u32) -> StandardError {
-        if self.scene_expired_transaction == Some(id) {
-            StandardError::SceneTransactionExpired
-        } else {
-            StandardError::InvalidSceneTransaction
-        }
-    }
-
-    fn begin_scene_replace(
-        &mut self,
-        now_ms: u64,
-        expected_revision: u32,
-        cell_count: u16,
-    ) -> Result<u32, StandardError> {
-        self.expire_scene_replace(now_ms);
-        if self.scene_replace.is_some() {
-            return Err(StandardError::SceneTransactionBusy);
-        }
-        if cell_count as usize > SCENE_CAP {
-            return Err(StandardError::SceneFull { capacity: SCENE_CAP });
-        }
-        let id = self.scene_next_transaction;
-        self.scene_next_transaction = self.scene_next_transaction.wrapping_add(1).max(1);
-        self.scene_expired_transaction = None;
-        self.scene_replace = Some(SceneReplace {
-            id,
-            expected_revision,
-            expected_count: cell_count,
-            cells: [EMPTY_SCENE_CELL; SCENE_CAP],
-            len: 0,
-            last_activity_ms: now_ms,
-        });
-        Ok(id)
-    }
-
-    fn put_scene_chunk(
-        &mut self,
-        now_ms: u64,
-        transaction_id: u32,
-        offset: u16,
-        cells: &SceneChunk,
-    ) -> Result<(), StandardError> {
-        self.expire_scene_replace(now_ms);
-        for cell in cells.as_slice() {
-            Self::check_scene_slot(cell.slot)?;
-        }
-        let error = self.scene_transaction_error(transaction_id);
-        let replace = self
-            .scene_replace
-            .as_mut()
-            .filter(|replace| replace.id == transaction_id)
-            .ok_or(error)?;
-        if offset as usize != replace.len || replace.len + cells.as_slice().len() > replace.expected_count as usize {
-            return Err(StandardError::InvalidSceneRequest);
-        }
-        for cell in cells.as_slice() {
-            if replace.cells[..replace.len]
-                .iter()
-                .any(|staged| staged.layer == cell.layer && staged.slot == cell.slot)
-            {
-                return Err(StandardError::InvalidSceneRequest);
-            }
-            replace.cells[replace.len] = *cell;
-            replace.len += 1;
-        }
-        replace.last_activity_ms = now_ms;
-        Ok(())
-    }
-
-    /// Atomically publish a complete staged replacement. A repeated commit of
-    /// the transaction most recently committed answers idempotently with
-    /// `changed == false` so a retried commit over a lossy link converges.
-    fn commit_scene_replace(&mut self, now_ms: u64, transaction_id: u32) -> Result<bool, StandardError> {
-        self.expire_scene_replace(now_ms);
-        if self.scene_committed_transaction == Some(transaction_id) && self.scene_replace.is_none() {
-            return Ok(false);
-        }
-        let error = self.scene_transaction_error(transaction_id);
-        let replace = self
-            .scene_replace
-            .as_ref()
-            .filter(|replace| replace.id == transaction_id)
-            .ok_or(error)?;
-        if replace.len != replace.expected_count as usize {
-            return Err(StandardError::SceneTransactionIncomplete {
-                expected: replace.expected_count,
-                received: replace.len as u16,
-            });
-        }
-        self.check_revision(replace.expected_revision)?;
-        let replace = self.scene_replace.take().expect("checked above");
-        self.scenes.clear();
-        for cell in &replace.cells[..replace.len] {
-            self.scenes.set(*cell).expect("staged length is table-bounded");
-        }
-        self.scene_committed_transaction = Some(transaction_id);
-        self.scene_expired_transaction = None;
-        Ok(true)
-    }
-
-    fn abort_scene_replace(&mut self, now_ms: u64, transaction_id: u32) -> Result<(), StandardError> {
-        self.expire_scene_replace(now_ms);
-        if self
-            .scene_replace
-            .as_ref()
-            .is_some_and(|replace| replace.id == transaction_id)
-        {
-            self.scene_replace = None;
-            return Ok(());
-        }
-        Err(self.scene_transaction_error(transaction_id))
-    }
-
-    fn expire_runtime_conditional_scene_replace(&mut self, now_ms: u64) {
-        if self
-            .runtime_conditional_scene_replace
-            .as_ref()
-            .is_some_and(|replace| now_ms.saturating_sub(replace.last_activity_ms) >= SCENE_TRANSACTION_TIMEOUT_MS)
-        {
-            self.runtime_conditional_scene_expired_transaction = self
-                .runtime_conditional_scene_replace
-                .as_ref()
-                .map(|replace| replace.id);
-            self.runtime_conditional_scene_replace = None;
-        }
-    }
-
-    fn runtime_conditional_scene_transaction_error(&self, id: u32) -> StandardError {
-        if self.runtime_conditional_scene_expired_transaction == Some(id) {
-            StandardError::ConditionalSceneTransactionExpired
-        } else {
-            StandardError::InvalidConditionalSceneTransaction
-        }
-    }
-
-    fn begin_runtime_conditional_scene_replace(
-        &mut self,
-        now_ms: u64,
-        expected_revision: u32,
-        cell_count: u16,
-    ) -> Result<u32, StandardError> {
-        self.expire_runtime_conditional_scene_replace(now_ms);
-        if self.runtime_conditional_scene_replace.is_some() {
-            return Err(StandardError::ConditionalSceneTransactionBusy);
-        }
-        if cell_count as usize > SCENE_CAP {
-            return Err(StandardError::ConditionalSceneFull { capacity: SCENE_CAP });
-        }
-        let id = self.runtime_conditional_scene_next_transaction;
-        self.runtime_conditional_scene_next_transaction =
-            self.runtime_conditional_scene_next_transaction.wrapping_add(1).max(1);
-        self.runtime_conditional_scene_expired_transaction = None;
-        self.runtime_conditional_scene_replace = Some(RuntimeConditionalSceneReplace {
-            id,
-            expected_revision,
-            expected_count: cell_count,
-            cells: [EMPTY_CONDITIONAL_SCENE_CELL; SCENE_CAP],
-            len: 0,
-            last_activity_ms: now_ms,
-        });
-        Ok(id)
-    }
-
-    fn put_runtime_conditional_scene_chunk(
-        &mut self,
-        now_ms: u64,
-        transaction_id: u32,
-        offset: u16,
-        cells: &RuntimeConditionalSceneChunk,
-    ) -> Result<(), StandardError> {
-        self.expire_runtime_conditional_scene_replace(now_ms);
-        for cell in cells.as_slice() {
-            Self::check_scene_slot(cell.slot)?;
-        }
-        let error = self.runtime_conditional_scene_transaction_error(transaction_id);
-        let replace = self
-            .runtime_conditional_scene_replace
-            .as_mut()
-            .filter(|replace| replace.id == transaction_id)
-            .ok_or(error)?;
-        if offset as usize != replace.len || replace.len + cells.as_slice().len() > replace.expected_count as usize {
-            return Err(StandardError::InvalidConditionalSceneRequest);
-        }
-        for cell in cells.as_slice() {
-            replace.cells[replace.len] = *cell;
-            replace.len += 1;
-        }
-        replace.last_activity_ms = now_ms;
-        Ok(())
-    }
-
-    fn commit_runtime_conditional_scene_replace(
-        &mut self,
-        now_ms: u64,
-        transaction_id: u32,
-    ) -> Result<bool, StandardError> {
-        self.expire_runtime_conditional_scene_replace(now_ms);
-        if self.runtime_conditional_scene_committed_transaction == Some(transaction_id)
-            && self.runtime_conditional_scene_replace.is_none()
-        {
-            return Ok(false);
-        }
-        let error = self.runtime_conditional_scene_transaction_error(transaction_id);
-        let replace = self
-            .runtime_conditional_scene_replace
-            .as_ref()
-            .filter(|replace| replace.id == transaction_id)
-            .ok_or(error)?;
-        if replace.len != replace.expected_count as usize {
-            return Err(StandardError::ConditionalSceneTransactionIncomplete {
-                expected: replace.expected_count,
-                received: replace.len as u16,
-            });
-        }
-        self.check_revision(replace.expected_revision)?;
-        let replace = self.runtime_conditional_scene_replace.take().expect("checked above");
-        self.runtime_conditional_scenes.clear();
-        for cell in &replace.cells[..replace.len] {
-            self.runtime_conditional_scenes
-                .push(*cell)
-                .expect("staged length is table-bounded");
-        }
-        self.runtime_conditional_scene_committed_transaction = Some(transaction_id);
-        self.runtime_conditional_scene_expired_transaction = None;
-        Ok(true)
-    }
-
-    fn abort_runtime_conditional_scene_replace(
-        &mut self,
-        now_ms: u64,
-        transaction_id: u32,
-    ) -> Result<(), StandardError> {
-        self.expire_runtime_conditional_scene_replace(now_ms);
-        if self
-            .runtime_conditional_scene_replace
-            .as_ref()
-            .is_some_and(|replace| replace.id == transaction_id)
-        {
-            self.runtime_conditional_scene_replace = None;
-            return Ok(());
-        }
-        Err(self.runtime_conditional_scene_transaction_error(transaction_id))
-    }
-}
-
-impl<'scenes, Context, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const SCENE_CAP: usize>
-    LightingEngine<Context> for StandardLightingEngine<'scenes, Extension, Status, N, OVERLAY_CAP, SCENE_CAP>
-where
-    Context: LightingContextProvider,
-    Extension: LightingSource<Rgb8, Context>,
-    Status: LightingSource<Rgb8, Context>,
-{
-    type Frame = LogicalFrame<Rgb8, N>;
-    type Input = StandardInput;
-    type Command = StandardCommand<OVERLAY_CAP, SCENE_CAP>;
-    type Reply = StandardReply;
-    type Error = StandardError;
-
-    fn on_input(&mut self, input: Self::Input, _snapshot: &Context) -> Result<Invalidation, Self::Error> {
-        if self.extension.handle_light_action(input.0) || self.apply_light_action(input.0) {
-            self.advance_revision();
-            Ok(Invalidation::Render)
-        } else {
-            Ok(Invalidation::None)
-        }
-    }
-
-    fn handle_command(
-        &mut self,
-        now_ms: u64,
-        command: Self::Command,
-        snapshot: &Context,
-    ) -> Result<CommandResult<Self::Reply>, Self::Error> {
-        let effect_now_ms = self.animation_clock.sample_time(now_ms);
-        // Scene reads and transaction bookkeeping have non-state replies or
-        // bespoke revision behavior; everything else falls through to the
-        // uniform state-readback path below.
-        match command {
-            StandardCommand::ReadOverlay { offset } => {
-                let old_len = self.overlay.active_len();
-                self.overlay.prune_expired(effect_now_ms);
-                let expired = self.overlay.active_len() != old_len;
-                if expired {
-                    self.advance_revision();
-                }
-                let start = (offset as usize).min(self.overlay.active_len());
-                let mut cells = OverlayBatch::new();
-                for update in self.overlay.active_updates().skip(start).take(OVERLAY_CHUNK_SIZE) {
-                    let ttl_ms = update.expires_ms.map(|expires_ms| {
-                        let remaining = expires_ms.saturating_sub(effect_now_ms).min(u32::MAX as u64) as u32;
-                        NonZeroU32::new(remaining).expect("expired overlays were pruned")
-                    });
-                    cells
-                        .push(OverlayCell {
-                            slot: update.slot,
-                            effect: update.effect,
-                            ttl_ms,
-                        })
-                        .expect("overlay page is chunk-bounded");
-                }
-                return Ok(CommandResult::new(
-                    StandardReply::OverlayPage(OverlayPage {
-                        revision: self.revision,
-                        total: self.overlay.active_len().min(u16::MAX as usize) as u16,
-                        cells,
-                    }),
-                    if expired {
-                        Invalidation::Render
-                    } else {
-                        Invalidation::None
-                    },
-                ));
-            }
-            StandardCommand::ReadScenes { offset } => {
-                return Ok(CommandResult::unchanged(StandardReply::ScenesPage(ScenePage {
-                    revision: self.revision,
-                    total: self.scenes.len().min(u16::MAX as usize) as u16,
-                    cells: self.scenes.page(offset),
-                })));
-            }
-            StandardCommand::ReadCompiledScenes { offset } => {
-                let mut cells = SceneChunk::new();
-                for (layer, cell) in self.layers.cells().skip(offset as usize).take(SCENE_CHUNK_SIZE) {
-                    cells
-                        .push(SceneTableCell {
-                            layer,
-                            slot: cell.slot,
-                            effect: cell.effect,
-                        })
-                        .expect("compiled scene page is chunk-bounded");
-                }
-                return Ok(CommandResult::unchanged(StandardReply::CompiledScenesPage(
-                    CompiledScenePage {
-                        total: self.layers.cell_count().min(u16::MAX as usize) as u16,
-                        policy: self.layers.policy,
-                        cells,
-                    },
-                )));
-            }
-            StandardCommand::ReadRuntimeConditionalScenes { offset } => {
-                return Ok(CommandResult::unchanged(StandardReply::RuntimeConditionalScenesPage(
-                    RuntimeConditionalScenePage {
-                        revision: self.revision,
-                        total: self.runtime_conditional_scenes.len().min(u16::MAX as usize) as u16,
-                        cells: self.runtime_conditional_scenes.page(offset),
-                    },
-                )));
-            }
-            StandardCommand::BeginSceneReplace {
-                expected_revision,
-                cell_count,
-            } => {
-                let id = self.begin_scene_replace(now_ms, expected_revision, cell_count)?;
-                return Ok(CommandResult::unchanged(StandardReply::SceneTransaction {
-                    id,
-                    cell_count,
-                }));
-            }
-            StandardCommand::PutSceneChunk {
-                transaction_id,
-                offset,
-                cells,
-            } => {
-                self.put_scene_chunk(now_ms, transaction_id, offset, &cells)?;
-                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
-            }
-            StandardCommand::CommitSceneReplace { transaction_id } => {
-                // A repeated commit of the last committed transaction is
-                // answered idempotently without advancing the revision.
-                let committed = self.commit_scene_replace(now_ms, transaction_id)?;
-                if committed {
-                    self.advance_revision();
-                    return Ok(CommandResult::new(
-                        StandardReply::State(self.state()),
-                        Invalidation::Render,
-                    ));
-                }
-                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
-            }
-            StandardCommand::AbortSceneReplace { transaction_id } => {
-                self.abort_scene_replace(now_ms, transaction_id)?;
-                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
-            }
-            StandardCommand::BeginRuntimeConditionalSceneReplace {
-                expected_revision,
-                cell_count,
-            } => {
-                let id = self.begin_runtime_conditional_scene_replace(now_ms, expected_revision, cell_count)?;
-                return Ok(CommandResult::unchanged(
-                    StandardReply::RuntimeConditionalSceneTransaction { id, cell_count },
-                ));
-            }
-            StandardCommand::PutRuntimeConditionalSceneChunk {
-                transaction_id,
-                offset,
-                cells,
-            } => {
-                self.put_runtime_conditional_scene_chunk(now_ms, transaction_id, offset, &cells)?;
-                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
-            }
-            StandardCommand::CommitRuntimeConditionalSceneReplace { transaction_id } => {
-                let committed = self.commit_runtime_conditional_scene_replace(now_ms, transaction_id)?;
-                if committed {
-                    self.advance_revision();
-                    return Ok(CommandResult::new(
-                        StandardReply::State(self.state()),
-                        Invalidation::Render,
-                    ));
-                }
-                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
-            }
-            StandardCommand::AbortRuntimeConditionalSceneReplace { transaction_id } => {
-                self.abort_runtime_conditional_scene_replace(now_ms, transaction_id)?;
-                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
-            }
-            _ => {}
-        }
-
-        let (mut invalidation, advances_revision) = match command {
-            StandardCommand::SetOutputEnabled(enabled) => {
-                self.output_mode = if enabled {
-                    OutputMode::AlwaysOn
-                } else {
-                    OutputMode::AlwaysOff
-                };
-                (Invalidation::Render, true)
-            }
-            StandardCommand::SetOutputModeIfRevision {
-                expected_revision,
-                mode,
-            } => {
-                self.check_revision(expected_revision)?;
-                self.output_mode = mode;
-                (Invalidation::Render, true)
-            }
-            StandardCommand::SetOutputBrightness(level) => {
-                self.output_brightness = level;
-                (Invalidation::Render, true)
-            }
-            StandardCommand::SetBackground(state) => {
-                self.background.set_state(state);
-                (Invalidation::Render, true)
-            }
-            StandardCommand::PatchBackground(patch) => {
-                patch.apply_to(&mut self.background.state);
-                (Invalidation::Render, true)
-            }
-            StandardCommand::SetStateIfRevision {
-                expected_revision,
-                state,
-            } => {
-                self.check_revision(expected_revision)?;
-                self.set_mutable_state(state);
-                (Invalidation::Render, true)
-            }
-            StandardCommand::SetOverlay(cell) => {
-                let update = Self::overlay_update(effect_now_ms, cell)?;
-                self.overlay.set(effect_now_ms, update)?;
-                (Invalidation::Render, true)
-            }
-            StandardCommand::SetOverlayIfRevision {
-                expected_revision,
-                cell,
-            } => {
-                self.check_revision(expected_revision)?;
-                let update = Self::overlay_update(effect_now_ms, cell)?;
-                self.overlay.set(effect_now_ms, update)?;
-                (Invalidation::Render, true)
-            }
-            StandardCommand::UnsetOverlay(slot) => {
-                let changed = self.overlay.unset(slot);
-                (
-                    if changed {
-                        Invalidation::Render
-                    } else {
-                        Invalidation::None
-                    },
-                    true,
-                )
-            }
-            StandardCommand::UnsetOverlayIfRevision {
-                expected_revision,
-                slot,
-            } => {
-                self.check_revision(expected_revision)?;
-                let changed = self.overlay.unset(slot);
-                (
-                    if changed {
-                        Invalidation::Render
-                    } else {
-                        Invalidation::None
-                    },
-                    true,
-                )
-            }
-            StandardCommand::ClearOverlay => {
-                let changed = self.overlay.active_len() != 0;
-                self.overlay.clear();
-                (
-                    if changed {
-                        Invalidation::Render
-                    } else {
-                        Invalidation::None
-                    },
-                    true,
-                )
-            }
-            StandardCommand::ClearOverlayIfRevision { expected_revision } => {
-                self.check_revision(expected_revision)?;
-                let changed = self.overlay.active_len() != 0;
-                self.overlay.clear();
-                (
-                    if changed {
-                        Invalidation::Render
-                    } else {
-                        Invalidation::None
-                    },
-                    true,
-                )
-            }
-            StandardCommand::ReplaceOverlay(batch) => {
-                let mut updates = [OverlayUpdate {
-                    slot: LedSlot(0),
-                    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
-                    expires_ms: None,
-                }; OVERLAY_CAP];
-                for (target, cell) in updates.iter_mut().zip(batch.as_slice().iter().copied()) {
-                    *target = Self::overlay_update(effect_now_ms, cell)?;
-                }
-                self.overlay
-                    .replace(effect_now_ms, &updates[..batch.as_slice().len()])?;
-                (Invalidation::Render, true)
-            }
-            StandardCommand::ReplaceOverlayIfRevision {
-                expected_revision,
-                batch,
-            } => {
-                self.check_revision(expected_revision)?;
-                let mut updates = [OverlayUpdate {
-                    slot: LedSlot(0),
-                    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
-                    expires_ms: None,
-                }; OVERLAY_CAP];
-                for (target, cell) in updates.iter_mut().zip(batch.as_slice().iter().copied()) {
-                    *target = Self::overlay_update(effect_now_ms, cell)?;
-                }
-                self.overlay
-                    .replace(effect_now_ms, &updates[..batch.as_slice().len()])?;
-                (Invalidation::Render, true)
-            }
-            StandardCommand::ExportReplica(slot) => {
-                let mut replica = self.replica_state(now_ms, snapshot)?;
-                replica.extension = self.extension.extension_state();
-                replica.extension_params = replica.extension.and_then(|state| {
-                    // A source with no descriptor, an active effect the
-                    // descriptor does not know, or an effect without
-                    // parameters all export nothing to replicate.
-                    let specs = extension_param_specs::<Rgb8, Context, _>(&self.extension, state.effect).ok()?;
-                    let len = specs.len().min(EXTENSION_PARAM_CHUNK);
-                    if len == 0 {
-                        return None;
-                    }
-                    let mut values = [0u8; EXTENSION_PARAM_CHUNK];
-                    for (value, (index, spec)) in values.iter_mut().zip(specs[..len].iter().enumerate()) {
-                        *value = self
-                            .extension
-                            .extension_param(state.effect, index as u8)
-                            .unwrap_or(spec.default);
-                    }
-                    Some(ExtensionReplicaParams {
-                        effect: state.effect,
-                        len: len as u8,
-                        values,
-                    })
-                });
-                slot.put(replica)?;
-                (Invalidation::None, false)
-            }
-            StandardCommand::ApplyReplica(slot) => {
-                let replica = slot.take()?;
-                let overlay = Self::replica_overlay(&replica)?;
-                // Parameter addresses and ranges are checked against the
-                // static descriptor before anything is applied, so a
-                // malformed snapshot cannot leave the selection updated and
-                // the tuning behind -- the same guarantee the overlay gets.
-                if let Some(params) = replica.extension_params {
-                    for (index, value) in params.values().iter().copied().enumerate() {
-                        check_extension_param::<Rgb8, Context, _>(&self.extension, params.effect, index as u8, value)?;
-                    }
-                }
-                match (replica.extension, self.extension.extension_state()) {
-                    (None, None) => {}
-                    (Some(extension), Some(_)) if self.extension.apply_extension_state(extension) => {}
-                    _ => return Err(StandardError::ExtensionUnsupported),
-                }
-                // Parameters follow the selection so the addressed effect is
-                // already active. Values go through the same validated path a
-                // host set uses; only the revision pin is skipped, matching
-                // how replica extension state is applied.
-                if let Some(params) = replica.extension_params {
-                    for (index, value) in params.values().iter().copied().enumerate() {
-                        apply_extension_param_checked::<Rgb8, Context, _>(
-                            &mut self.extension,
-                            params.effect,
-                            index as u8,
-                            value,
-                        )?;
-                    }
-                }
-                self.apply_replica(now_ms, replica, overlay);
-                (Invalidation::Render, false)
-            }
-            StandardCommand::SetSceneCellIfRevision {
-                expected_revision,
-                cell,
-            } => {
-                self.check_revision(expected_revision)?;
-                Self::check_scene_slot(cell.slot)?;
-                self.scenes.set(cell)?;
-                (Invalidation::Render, true)
-            }
-            StandardCommand::UnsetSceneCellIfRevision {
-                expected_revision,
-                layer,
-                slot,
-            } => {
-                self.check_revision(expected_revision)?;
-                let changed = self.scenes.unset(layer, slot);
-                (
-                    if changed {
-                        Invalidation::Render
-                    } else {
-                        Invalidation::None
-                    },
-                    true,
-                )
-            }
-            StandardCommand::SetLayerPolicyIfRevision {
-                expected_revision,
-                policy,
-            } => {
-                self.check_revision(expected_revision)?;
-                let changed = self.scenes.set_policy(policy);
-                (
-                    if changed {
-                        Invalidation::Render
-                    } else {
-                        Invalidation::None
-                    },
-                    true,
-                )
-            }
-            StandardCommand::ReadExtension => {
-                return Ok(CommandResult::unchanged(StandardReply::Extension(ExtensionPage {
-                    revision: self.revision,
-                    descriptor: self.extension.extension_descriptor(),
-                    state: self.extension.extension_state(),
-                })));
-            }
-            StandardCommand::SetExtensionIfRevision {
-                expected_revision,
-                state,
-            } => {
-                self.check_revision(expected_revision)?;
-                if !self.extension.apply_extension_state(state) {
-                    return Err(StandardError::ExtensionUnsupported);
-                }
-                (Invalidation::Render, true)
-            }
-            StandardCommand::ReadExtensionParams { effect, offset } => {
-                let specs = extension_param_specs::<Rgb8, Context, _>(&self.extension, effect)?;
-                let start = (offset as usize).min(specs.len());
-                let end = (start + EXTENSION_PARAM_CHUNK).min(specs.len());
-                let mut items = [None; EXTENSION_PARAM_CHUNK];
-                for (item, (index, spec)) in items.iter_mut().zip((start..end).zip(&specs[start..end])) {
-                    let value = self
-                        .extension
-                        .extension_param(effect, index as u8)
-                        .unwrap_or(spec.default);
-                    *item = Some(ExtensionParamValue { spec: *spec, value });
-                }
-                return Ok(CommandResult::unchanged(StandardReply::ExtensionParams(
-                    ExtensionParamsPage {
-                        revision: self.revision,
-                        // The wire caps one effect's parameter list at 255.
-                        total: specs.len().min(u8::MAX as usize) as u8,
-                        items,
-                    },
-                )));
-            }
-            StandardCommand::SetExtensionParamIfRevision {
-                expected_revision,
-                effect,
-                index,
-                value,
-            } => {
-                self.check_revision(expected_revision)?;
-                apply_extension_param_checked::<Rgb8, Context, _>(&mut self.extension, effect, index, value)?;
-                (Invalidation::Render, true)
-            }
-            StandardCommand::ReadState => (Invalidation::None, false),
-            StandardCommand::ReadOverlay { .. }
-            | StandardCommand::ReadScenes { .. }
-            | StandardCommand::ReadCompiledScenes { .. }
-            | StandardCommand::ReadRuntimeConditionalScenes { .. }
-            | StandardCommand::BeginSceneReplace { .. }
-            | StandardCommand::PutSceneChunk { .. }
-            | StandardCommand::CommitSceneReplace { .. }
-            | StandardCommand::AbortSceneReplace { .. } => unreachable!("handled above"),
-            StandardCommand::BeginRuntimeConditionalSceneReplace { .. }
-            | StandardCommand::PutRuntimeConditionalSceneChunk { .. }
-            | StandardCommand::CommitRuntimeConditionalSceneReplace { .. }
-            | StandardCommand::AbortRuntimeConditionalSceneReplace { .. } => unreachable!("handled above"),
-        };
-        if advances_revision {
-            self.advance_revision();
-            if invalidation == Invalidation::None {
-                invalidation = Invalidation::StateChanged;
-            }
-        }
-        Ok(CommandResult::new(StandardReply::State(self.state()), invalidation))
-    }
-
-    fn render(
-        &mut self,
-        input: RenderInput<'_, Context>,
-        frame: &mut Self::Frame,
-    ) -> Result<RenderOutcome, Self::Error> {
-        let effect_now_ms = self.animation_clock.sample_time(input.now_ms);
-        let overlay_len = self.overlay.active_len();
-        self.overlay.prune_expired(effect_now_ms);
-        let mut state_changed = self.overlay.active_len() != overlay_len;
-        if state_changed {
-            self.advance_revision();
-        }
-        let context = input.snapshot.lighting_context();
-        let powered = context.powered;
-        let wake_active = self
-            .controls
-            .wake_layer
-            .is_some_and(|layer| context.layers.is_active(layer));
-        let effective_output_enabled = wake_active
-            || matches!(self.output_mode, OutputMode::AlwaysOn)
-            || matches!(self.output_mode, OutputMode::PoweredOnly) && powered;
-        if self.powered != powered
-            || self.wake_active != wake_active
-            || self.effective_output_enabled != effective_output_enabled
-        {
-            self.powered = powered;
-            self.wake_active = wake_active;
-            self.effective_output_enabled = effective_output_enabled;
-            state_changed = true;
-        }
-        let indicator_cell = self.controls.output_mode_indicator.map(|indicator| SceneCell {
-            slot: indicator.slot,
-            effect: indicator.effect(self.output_mode),
-        });
-        let Self {
-            compositor,
-            background,
-            extension,
-            layers,
-            scenes,
-            runtime_conditional_scenes,
-            battery_status,
-            overlay,
-            status,
-            animation_clock: _,
-            controls: _,
-            output_mode: _,
-            powered: _,
-            wake_active: _,
-            effective_output_enabled,
-            output_brightness,
-            scene_replace: _,
-            scene_next_transaction: _,
-            scene_expired_transaction: _,
-            scene_committed_transaction: _,
-            runtime_conditional_scene_replace: _,
-            runtime_conditional_scene_next_transaction: _,
-            runtime_conditional_scene_expired_transaction: _,
-            runtime_conditional_scene_committed_transaction: _,
-            revision: _,
-        } = self;
-        let mut transaction = compositor.begin(effect_now_ms, input.snapshot, Rgb8::BLACK, frame);
-        transaction.apply(priority::BACKGROUND, background)?;
-        transaction.apply(priority::EXTENSION, extension)?;
-        transaction.apply(priority::LAYER, layers)?;
-        // Same band, later call: runtime cells override static defaults.
-        transaction.apply(priority::LAYER, scenes)?;
-        transaction.apply(priority::HOST_OVERLAY, overlay)?;
-        transaction.apply(priority::STATUS, status)?;
-        // Status band, after the compiled rules: a runtime conditional cell is
-        // the host's replacement for a compiled one, so it must reach the same
-        // altitude and win on the slots the two share.
-        let mut runtime_conditional_source = RuntimeConditionalSource {
-            table: runtime_conditional_scenes,
-            batteries: *battery_status,
-        };
-        transaction.apply(priority::STATUS, &mut runtime_conditional_source)?;
-        if wake_active && let Some(indicator_cell) = indicator_cell.as_ref() {
-            let mut indicator = SparseScene {
-                cells: core::slice::from_ref(indicator_cell),
-            };
-            transaction.apply(priority::STATUS, &mut indicator)?;
-        }
-        let mut transform = BrightnessTransform::new(if *effective_output_enabled {
-            *output_brightness
-        } else {
-            0
-        });
-        let result = transaction.finish_with(&mut transform);
-        let next_wake_in_ms = result.next_wake_ms.map(|deadline| {
-            let delay = deadline.saturating_sub(effect_now_ms).clamp(1, u32::MAX as u64);
-            NonZeroU32::new(delay as u32).expect("clamped delay is nonzero")
-        });
-        Ok(RenderOutcome {
-            changed: result.changed,
-            state_changed,
-            next_wake_in_ms,
-        })
-    }
-
-    fn on_presented(&mut self, frame: &Self::Frame) {
-        self.compositor.commit(frame);
-    }
-}
-
-fn hsv(hue: u8, saturation: u8, value: u8) -> Rgb8 {
-    if saturation == 0 {
-        return Rgb8::new(value, value, value);
-    }
-    let region = hue / 43;
-    let remainder = (hue - region * 43) as u16 * 6;
-    let p = (value as u16 * (255 - saturation as u16) / 255) as u8;
-    let q = (value as u16 * (255 - (saturation as u16 * remainder / 255)) / 255) as u8;
-    let t = (value as u16 * (255 - (saturation as u16 * (255 - remainder) / 255)) / 255) as u8;
-    match region {
-        0 => Rgb8::new(value, t, p),
-        1 => Rgb8::new(q, value, p),
-        2 => Rgb8::new(p, value, t),
-        3 => Rgb8::new(p, q, value),
-        4 => Rgb8::new(t, p, value),
-        _ => Rgb8::new(value, p, q),
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::lighting::source::SparseScene;
-    use crate::lighting::{LayerPolicy, LayerScene, LayerState, LightingContext, SceneCell};
-
-    const RED: Rgb8 = Rgb8::new(200, 0, 0);
-    const GREEN: Rgb8 = Rgb8::new(0, 200, 0);
-
-    type Engine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2>;
-
-    /// Effect 0 advertises two parameters; effect 1 advertises none, so the
-    /// "active effect has nothing to replicate" path stays covered.
-    static REPLICA_EFFECT_NAMES: &[&str] = &["A", "B"];
-    static REPLICA_EFFECT_PARAMS: &[&[ExtensionParamSpec]] = &[&[
-        ExtensionParamSpec {
-            name: "Density",
-            min: 1,
-            max: 8,
-            default: 3,
-        },
-        ExtensionParamSpec {
-            name: "Fade",
-            min: 0,
-            max: 255,
-            default: 128,
-        },
-    ]];
-
-    #[derive(Copy, Clone)]
-    struct ReplicaExtension {
-        state: ExtensionState,
-        accept: bool,
-        params: [u8; 2],
-    }
-
-    impl<Context> LightingSource<Rgb8, Context> for ReplicaExtension {
-        fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
-            0
-        }
-
-        fn slot(&self, _: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
-            unreachable!("replica test extension has no targets")
-        }
-
-        fn contribution(&mut self, _: usize, _: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
-            unreachable!("replica test extension has no samples")
-        }
-
-        fn extension_state(&self) -> Option<ExtensionState> {
-            Some(self.state)
-        }
-
-        fn apply_extension_state(&mut self, state: ExtensionState) -> bool {
-            if !self.accept {
-                return false;
-            }
-            self.state = state;
-            true
-        }
-
-        fn extension_descriptor(&self) -> Option<ExtensionDescriptor> {
-            Some(ExtensionDescriptor {
-                effects: REPLICA_EFFECT_NAMES,
-                palettes: &[],
-                params: REPLICA_EFFECT_PARAMS,
-            })
-        }
-
-        fn extension_param(&self, effect: u8, index: u8) -> Option<u8> {
-            if effect != 0 {
-                return None;
-            }
-            self.params.get(index as usize).copied()
-        }
-
-        fn apply_extension_param(&mut self, effect: u8, index: u8, value: u8) -> bool {
-            if !self.accept || effect != 0 {
-                return false;
-            }
-            match self.params.get_mut(index as usize) {
-                Some(slot) => {
-                    *slot = value;
-                    true
-                }
-                None => false,
-            }
-        }
-    }
-
-    static LAYER_CELLS: [SceneCell<BuiltinEffect>; 1] = [SceneCell {
-        slot: LedSlot(0),
-        effect: BuiltinEffect::Solid { color: RED },
-    }];
-    static LAYERS: [LayerScene<'static, BuiltinEffect>; 1] = [LayerScene {
-        layer: 1,
-        cells: &LAYER_CELLS,
-    }];
-    static STATUS_CELLS: [SceneCell<BuiltinEffect>; 1] = [SceneCell {
-        slot: LedSlot(1),
-        effect: BuiltinEffect::Solid { color: GREEN },
-    }];
-
-    fn engine() -> Engine {
-        StandardLightingEngine::new(
-            BackgroundState {
-                value: 10,
-                ..BackgroundState::default()
-            },
-            LayerScenes {
-                scenes: &LAYERS,
-                policy: LayerPolicy::ActiveStack,
-            },
-            EmptySource,
-            EmptySource,
-        )
-    }
-
-    fn replica_engine(accept: bool) -> StandardLightingEngine<'static, ReplicaExtension, EmptySource, 2, 2> {
-        StandardLightingEngine::new(
-            BackgroundState {
-                value: 10,
-                ..BackgroundState::default()
-            },
-            LayerScenes {
-                scenes: &LAYERS,
-                policy: LayerPolicy::ActiveStack,
-            },
-            ReplicaExtension {
-                state: ExtensionState {
-                    effect: 0,
-                    palette: 0,
-                    value: 10,
-                    speed: 20,
-                },
-                accept,
-                params: [3, 128],
-            },
-            EmptySource,
-        )
-    }
-
-    fn context(layer: u8) -> LightingContext {
-        LightingContext {
-            layers: LayerState::new(layer, 0, 1 | (1 << layer)),
-            indicators: Default::default(),
-            powered: false,
-        }
-    }
-
-    #[test]
-    fn replica_snapshot_preserves_state_scenes_context_ttl_and_animation_phase() {
-        type SceneEngine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2, 4>;
-        fn scene_engine() -> SceneEngine {
-            SceneEngine::new(
-                BackgroundState {
-                    value: 10,
-                    ..BackgroundState::default()
-                },
-                LayerScenes {
-                    scenes: &LAYERS,
-                    policy: LayerPolicy::ActiveStack,
-                },
-                EmptySource,
-                EmptySource,
-            )
-        }
-        let mut authority = scene_engine();
-        let authority_context = context(3);
-        authority
-            .handle_command(
-                100,
-                StandardCommand::SetBackground(BackgroundState {
-                    mode: BackgroundMode::Breathe,
-                    speed: 200,
-                    ..BackgroundState::default()
-                }),
-                &authority_context,
-            )
-            .unwrap();
-        authority
-            .handle_command(
-                100,
-                StandardCommand::SetOverlay(OverlayCell {
-                    slot: LedSlot(1),
-                    effect: BuiltinEffect::Solid { color: GREEN },
-                    ttl_ms: NonZeroU32::new(100),
-                }),
-                &authority_context,
-            )
-            .unwrap();
-        let scene_cell = SceneTableCell {
-            layer: 3,
-            slot: LedSlot(0),
-            effect: BuiltinEffect::Solid { color: RED },
-        };
-        authority
-            .handle_command(
-                100,
-                StandardCommand::SetSceneCellIfRevision {
-                    expected_revision: 2,
-                    cell: scene_cell,
-                },
-                &authority_context,
-            )
-            .unwrap();
-
-        static EXPORT: StandardReplicaSlot<2, 4> = StandardReplicaSlot::new();
-        authority
-            .handle_command(120, StandardCommand::ExportReplica(&EXPORT), &authority_context)
-            .unwrap();
-        let snapshot = EXPORT.take().unwrap();
-        assert_eq!(snapshot.context, authority_context);
-        assert_eq!(snapshot.sample_time_ms, 120);
-        assert_eq!(snapshot.overlay.as_slice()[0].ttl_ms, NonZeroU32::new(80));
-        assert_eq!(snapshot.scenes.iter().collect::<heapless::Vec<_, 4>>(), &[scene_cell]);
-
-        let mut authority_frame = LogicalFrame::new(Rgb8::BLACK);
-        authority
-            .render(
-                RenderInput {
-                    now_ms: 136,
-                    snapshot: &authority_context,
-                },
-                &mut authority_frame,
-            )
-            .unwrap();
-
-        static APPLY: StandardReplicaSlot<2, 4> = StandardReplicaSlot::new();
-        APPLY.put(snapshot).unwrap();
-        let mut replica = scene_engine();
-        replica
-            .handle_command(1_000, StandardCommand::ApplyReplica(&APPLY), &authority_context)
-            .unwrap();
-        let mut replica_frame = LogicalFrame::new(Rgb8::BLACK);
-        replica
-            .render(
-                RenderInput {
-                    now_ms: 1_016,
-                    snapshot: &snapshot.context,
-                },
-                &mut replica_frame,
-            )
-            .unwrap();
-
-        assert_eq!(replica.state().revision, snapshot.revision);
-        assert_eq!(replica.scenes().iter().collect::<heapless::Vec<_, 4>>(), &[scene_cell]);
-        assert_eq!(replica_frame, authority_frame);
-    }
-
-    #[test]
-    fn replica_slot_rejects_overwrite_and_empty_take() {
-        let slot = StandardReplicaSlot::<2>::new();
-        let snapshot = StandardReplicaState {
-            revision: 1,
-            mutable: StandardMutableState {
-                output_enabled: true,
-                output_brightness: 42,
-                background: BackgroundState::default(),
-            },
-            output_mode: OutputMode::AlwaysOn,
-            overlay: OverlayBatch::new(),
-            scenes: SceneTable::new(),
-            runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
-            context: context(0),
-            sample_time_ms: 9,
-            extension: None,
-            extension_params: None,
-        };
-        slot.put(snapshot).unwrap();
-        assert_eq!(slot.put(snapshot), Err(ReplicaSlotError::Busy));
-        assert_eq!(slot.take(), Ok(snapshot));
-        assert_eq!(slot.take(), Err(ReplicaSlotError::Empty));
-    }
-
-    #[test]
-    fn replica_application_is_atomic_across_common_and_extension_state() {
-        let next_extension = ExtensionState {
-            effect: 1,
-            palette: 2,
-            value: 30,
-            speed: 40,
-        };
-        let snapshot = StandardReplicaState {
-            revision: 9,
-            mutable: StandardMutableState {
-                output_enabled: false,
-                output_brightness: 42,
-                background: BackgroundState {
-                    value: 99,
-                    ..BackgroundState::default()
-                },
-            },
-            output_mode: OutputMode::AlwaysOff,
-            overlay: OverlayBatch::new(),
-            scenes: SceneTable::new(),
-            runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
-            context: context(0),
-            sample_time_ms: 50,
-            extension: Some(next_extension),
-            extension_params: None,
-        };
-
-        let mut declining = replica_engine(false);
-        let before = declining.state();
-        let before_extension = declining.extension().state;
-        static DECLINING_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
-        DECLINING_SLOT.put(snapshot).unwrap();
-        assert_eq!(
-            declining.handle_command(100, StandardCommand::ApplyReplica(&DECLINING_SLOT), &context(0),),
-            Err(StandardError::ExtensionUnsupported)
-        );
-        assert_eq!(declining.state(), before);
-        assert_eq!(declining.extension().state, before_extension);
-
-        let mut accepting = replica_engine(true);
-        static ACCEPTING_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
-        ACCEPTING_SLOT.put(snapshot).unwrap();
-        accepting
-            .handle_command(100, StandardCommand::ApplyReplica(&ACCEPTING_SLOT), &context(0))
-            .unwrap();
-        assert_eq!(accepting.state().revision, 9);
-        assert_eq!(accepting.state().output_brightness, 42);
-        assert_eq!(accepting.extension().state, next_extension);
-    }
-
-    #[test]
-    fn replica_export_carries_the_active_effect_parameters() {
-        let mut authority = replica_engine(true);
-        authority
-            .handle_command(
-                0,
-                StandardCommand::SetExtensionParamIfRevision {
-                    expected_revision: 0,
-                    effect: 0,
-                    index: 1,
-                    value: 200,
-                },
-                &context(0),
-            )
-            .unwrap();
-
-        static EXPORT_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
-        authority
-            .handle_command(10, StandardCommand::ExportReplica(&EXPORT_SLOT), &context(0))
-            .unwrap();
-        let snapshot = EXPORT_SLOT.take().unwrap();
-        let params = snapshot.extension_params.expect("active effect has parameters");
-        assert_eq!(params.effect, 0);
-        assert_eq!(params.values(), &[3, 200]);
-
-        // An active effect without parameters exports nothing to replicate.
-        authority
-            .handle_command(
-                20,
-                StandardCommand::SetExtensionIfRevision {
-                    expected_revision: authority.state().revision,
-                    state: ExtensionState {
-                        effect: 1,
-                        palette: 0,
-                        value: 10,
-                        speed: 20,
-                    },
-                },
-                &context(0),
-            )
-            .unwrap();
-        authority
-            .handle_command(30, StandardCommand::ExportReplica(&EXPORT_SLOT), &context(0))
-            .unwrap();
-        assert_eq!(EXPORT_SLOT.take().unwrap().extension_params, None);
-    }
-
-    #[test]
-    fn replica_application_installs_exported_parameters() {
-        let mut authority = replica_engine(true);
-        authority
-            .handle_command(
-                0,
-                StandardCommand::SetExtensionParamIfRevision {
-                    expected_revision: 0,
-                    effect: 0,
-                    index: 0,
-                    value: 7,
-                },
-                &context(0),
-            )
-            .unwrap();
-        static ROUND_TRIP_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
-        authority
-            .handle_command(10, StandardCommand::ExportReplica(&ROUND_TRIP_SLOT), &context(0))
-            .unwrap();
-        let snapshot = ROUND_TRIP_SLOT.take().unwrap();
-
-        let mut replica = replica_engine(true);
-        assert_eq!(replica.extension().params, [3, 128]);
-        ROUND_TRIP_SLOT.put(snapshot).unwrap();
-        replica
-            .handle_command(100, StandardCommand::ApplyReplica(&ROUND_TRIP_SLOT), &context(0))
-            .unwrap();
-        assert_eq!(replica.extension().params, [7, 128]);
-        assert_eq!(replica.state().revision, snapshot.revision);
-    }
-
-    #[test]
-    fn replica_parameters_are_validated_like_a_host_set() {
-        let mut authority = replica_engine(true);
-        static SEED_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
-        authority
-            .handle_command(0, StandardCommand::ExportReplica(&SEED_SLOT), &context(0))
-            .unwrap();
-        let mut snapshot = SEED_SLOT.take().unwrap();
-        // A selection change that must not survive the rejected parameter.
-        snapshot.extension = Some(ExtensionState {
-            effect: 0,
-            palette: 7,
-            value: 77,
-            speed: 88,
-        });
-        // 9 is outside the "Density" spec's 1..=8 range.
-        snapshot.extension_params = Some(ExtensionReplicaParams {
-            effect: 0,
-            len: 1,
-            values: [9, 0, 0, 0, 0, 0, 0, 0],
-        });
-
-        let mut replica = replica_engine(true);
-        let before = replica.extension().params;
-        let before_state = replica.extension().state;
-        static INVALID_PARAM_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
-        INVALID_PARAM_SLOT.put(snapshot).unwrap();
-        assert_eq!(
-            replica.handle_command(100, StandardCommand::ApplyReplica(&INVALID_PARAM_SLOT), &context(0)),
-            Err(StandardError::ExtensionUnsupported)
-        );
-        // The pre-apply check keeps the whole extension untouched, selection
-        // included, not just the parameter that failed.
-        assert_eq!(replica.extension().params, before);
-        assert_eq!(replica.extension().state, before_state);
-        assert_eq!(replica.state().revision, 0);
-    }
-
-    #[test]
-    fn invalid_replica_common_state_does_not_mutate_extension() {
-        let mut overlay = OverlayBatch::new();
-        for _ in 0..2 {
-            overlay
-                .push(OverlayCell {
-                    slot: LedSlot(0),
-                    effect: BuiltinEffect::Solid { color: RED },
-                    ttl_ms: None,
-                })
-                .unwrap();
-        }
-        let snapshot = StandardReplicaState {
-            revision: 9,
-            mutable: StandardMutableState {
-                output_enabled: true,
-                output_brightness: 42,
-                background: BackgroundState::default(),
-            },
-            output_mode: OutputMode::AlwaysOn,
-            overlay,
-            scenes: SceneTable::new(),
-            runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
-            context: context(0),
-            sample_time_ms: 50,
-            extension: Some(ExtensionState {
-                effect: 1,
-                palette: 2,
-                value: 30,
-                speed: 40,
-            }),
-            extension_params: None,
-        };
-        let mut engine = replica_engine(true);
-        let before = engine.extension().state;
-        static INVALID_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
-        INVALID_SLOT.put(snapshot).unwrap();
-        assert_eq!(
-            engine.handle_command(100, StandardCommand::ApplyReplica(&INVALID_SLOT), &context(0),),
-            Err(StandardError::Overlay(OverlayError::DuplicateSlot { slot: LedSlot(0) }))
-        );
-        assert_eq!(engine.extension().state, before);
-        assert_eq!(engine.state().revision, 0);
-    }
-
-    #[test]
-    fn output_mode_cycles_and_wake_layer_temporarily_overrides_policy() {
-        let mut engine = engine().with_controls(LightingControls {
-            output_toggle_user_action: None,
-            output_mode_cycle_user_action: Some(13),
-            wake_layer: Some(2),
-            initial_output_mode: OutputMode::PoweredOnly,
-            powered_only_scope: super::super::source::PoweredOnlyScope::Local,
-            output_mode_indicator: Some(super::super::source::OutputModeIndicator {
-                slot: LedSlot(1),
-                always_on: BuiltinEffect::Solid { color: GREEN },
-                always_off: BuiltinEffect::Solid { color: RED },
-                powered_only: BuiltinEffect::Solid {
-                    color: Rgb8::new(0, 0, 200),
-                },
-            }),
-        });
-        let mut frame = LogicalFrame::new(Rgb8::BLACK);
-        let battery_context = context(0);
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 0,
-                    snapshot: &battery_context,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(frame.as_slice(), &[Rgb8::BLACK, Rgb8::BLACK]);
-        assert!(!engine.state().output_enabled);
-
-        let mut powered_context = battery_context;
-        powered_context.powered = true;
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 1,
-                    snapshot: &powered_context,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert!(engine.state().output_enabled);
-
-        engine
-            .on_input(StandardInput(LightAction::OutputModeCycle), &powered_context)
-            .unwrap();
-        assert_eq!(engine.output_mode(), OutputMode::AlwaysOn);
-        engine
-            .on_input(StandardInput(LightAction::OutputModeCycle), &powered_context)
-            .unwrap();
-        assert_eq!(engine.output_mode(), OutputMode::AlwaysOff);
-
-        let magic_context = context(2);
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 2,
-                    snapshot: &magic_context,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert!(engine.state().wake_active);
-        assert!(engine.state().output_enabled);
-        assert_eq!(frame.as_slice()[1], RED);
-
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 3,
-                    snapshot: &battery_context,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(frame.as_slice(), &[Rgb8::BLACK, Rgb8::BLACK]);
-        assert_eq!(engine.output_mode(), OutputMode::AlwaysOff);
-    }
-
-    #[test]
-    fn background_patch_preserves_unmentioned_fields() {
-        let mut engine = engine();
-        let snapshot = context(0);
-        let before = engine.state();
-        let reply = engine
-            .handle_command(
-                0,
-                StandardCommand::PatchBackground(BackgroundPatch {
-                    value: Some(77),
-                    ..BackgroundPatch::default()
-                }),
-                &snapshot,
-            )
-            .unwrap()
-            .reply
-            .state()
-            .unwrap();
-
-        assert_eq!(reply.background.value, 77);
-        assert_eq!(reply.background.enabled, before.background.enabled);
-        assert_eq!(reply.background.hue, before.background.hue);
-        assert_eq!(reply.background.saturation, before.background.saturation);
-        assert_eq!(reply.background.speed, before.background.speed);
-        assert_eq!(reply.background.mode, before.background.mode);
-        assert_eq!(reply.output_enabled, before.output_enabled);
-        assert_eq!(reply.output_brightness, before.output_brightness);
-        assert_eq!(reply.revision, before.revision + 1);
-    }
-
-    #[test]
-    fn revision_checks_are_atomic_and_cover_inputs_and_expiry() {
-        let mut engine = engine();
-        let snapshot = context(0);
-        assert_eq!(engine.state().revision, 0);
-
-        engine
-            .handle_command(
-                10,
-                StandardCommand::PatchBackground(BackgroundPatch {
-                    value: Some(77),
-                    ..BackgroundPatch::default()
-                }),
-                &snapshot,
-            )
-            .unwrap();
-        assert_eq!(engine.state().revision, 1);
-
-        let desired = StandardMutableState {
-            output_enabled: false,
-            output_brightness: 12,
-            background: BackgroundState {
-                value: 99,
-                ..BackgroundState::default()
-            },
-        };
-        assert_eq!(
-            engine.handle_command(
-                10,
-                StandardCommand::SetStateIfRevision {
-                    expected_revision: 0,
-                    state: desired,
-                },
-                &snapshot,
-            ),
-            Err(StandardError::RevisionConflict {
-                expected: 0,
-                current: 1,
-            })
-        );
-        assert!(engine.state().output_enabled, "a stale update is all-or-nothing");
-
-        let reply = engine
-            .handle_command(
-                10,
-                StandardCommand::SetStateIfRevision {
-                    expected_revision: 1,
-                    state: desired,
-                },
-                &snapshot,
-            )
-            .unwrap()
-            .reply
-            .state()
-            .unwrap();
-        assert_eq!(reply.revision, 2);
-        assert!(!reply.output_enabled);
-
-        engine
-            .on_input(StandardInput(LightAction::BacklightOn), &snapshot)
-            .unwrap();
-        assert_eq!(engine.state().revision, 3);
-        assert_eq!(
-            engine.on_input(StandardInput(LightAction::RgbModeRainbow), &snapshot),
-            Ok(Invalidation::None)
-        );
-        assert_eq!(engine.state().revision, 3);
-
-        engine
-            .handle_command(
-                10,
-                StandardCommand::SetOverlayIfRevision {
-                    expected_revision: 3,
-                    cell: OverlayCell {
-                        slot: LedSlot(0),
-                        effect: BuiltinEffect::Solid { color: GREEN },
-                        ttl_ms: NonZeroU32::new(1),
-                    },
-                },
-                &snapshot,
-            )
-            .unwrap();
-        assert_eq!(engine.state().revision, 4);
-
-        let mut frame = LogicalFrame::new(Rgb8::BLACK);
-        let first_expiry = engine
-            .render(
-                RenderInput {
-                    now_ms: 11,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert!(first_expiry.state_changed);
-        assert_eq!(engine.state().revision, 5, "TTL expiry is authoritative state");
-        let second_expiry = engine
-            .render(
-                RenderInput {
-                    now_ms: 12,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert!(!second_expiry.state_changed);
-        assert_eq!(engine.state().revision, 5, "expiry advances exactly once");
-    }
-
-    #[test]
-    fn overlay_pages_sample_remaining_ttl_and_prune_with_revision_advance() {
-        let mut engine = engine();
-        let snapshot = context(0);
-        engine
-            .handle_command(
-                100,
-                StandardCommand::SetOverlay(OverlayCell {
-                    slot: LedSlot(0),
-                    effect: BuiltinEffect::Solid { color: RED },
-                    ttl_ms: None,
-                }),
-                &snapshot,
-            )
-            .unwrap();
-        engine
-            .handle_command(
-                100,
-                StandardCommand::SetOverlay(OverlayCell {
-                    slot: LedSlot(1),
-                    effect: BuiltinEffect::Solid { color: GREEN },
-                    ttl_ms: NonZeroU32::new(50),
-                }),
-                &snapshot,
-            )
-            .unwrap();
-
-        let sampled = engine
-            .handle_command(120, StandardCommand::ReadOverlay { offset: 0 }, &snapshot)
-            .unwrap();
-        assert_eq!(sampled.invalidation, Invalidation::None);
-        let StandardReply::OverlayPage(page) = sampled.reply else {
-            panic!("expected overlay page")
-        };
-        assert_eq!(page.revision, 2);
-        assert_eq!(page.total, 2);
-        assert_eq!(page.cells.as_slice()[0].ttl_ms, None);
-        assert_eq!(page.cells.as_slice()[1].ttl_ms, NonZeroU32::new(30));
-
-        let pruned = engine
-            .handle_command(150, StandardCommand::ReadOverlay { offset: 0 }, &snapshot)
-            .unwrap();
-        assert_eq!(pruned.invalidation, Invalidation::Render);
-        let StandardReply::OverlayPage(page) = pruned.reply else {
-            panic!("expected overlay page")
-        };
-        assert_eq!(page.revision, 3);
-        assert_eq!(page.total, 1);
-        assert_eq!(page.cells.as_slice()[0].slot, LedSlot(0));
-    }
-
-    #[test]
-    fn compiled_scene_pages_preserve_layer_and_are_separate_from_runtime_scenes() {
-        let mut engine = scene_engine();
-        set_cell(&mut engine, 0, scene_cell(7, 1, GREEN));
-
-        let reply = engine
-            .handle_command(0, StandardCommand::ReadCompiledScenes { offset: 0 }, &context(0))
-            .unwrap()
-            .reply;
-        let StandardReply::CompiledScenesPage(page) = reply else {
-            panic!("expected compiled scene page")
-        };
-        assert_eq!(page.total, 1);
-        assert_eq!(page.policy, LayerPolicy::ActiveStack);
-        assert_eq!(page.cells.as_slice(), &[scene_cell(1, 0, RED)]);
-
-        let runtime = scenes_page(&mut engine, 0);
-        assert_eq!(runtime.total, 1);
-        assert_eq!(runtime.cells.as_slice(), &[scene_cell(7, 1, GREEN)]);
-
-        let mut empty: Engine = StandardLightingEngine::new(
-            BackgroundState::default(),
-            LayerScenes {
-                scenes: &[],
-                policy: LayerPolicy::ActiveStack,
-            },
-            EmptySource,
-            EmptySource,
-        );
-        let StandardReply::CompiledScenesPage(empty_page) = empty
-            .handle_command(0, StandardCommand::ReadCompiledScenes { offset: 0 }, &context(0))
-            .unwrap()
-            .reply
-        else {
-            panic!("expected compiled scene page")
-        };
-        assert_eq!(empty_page.total, 0);
-        assert_eq!(empty_page.policy, LayerPolicy::ActiveStack);
-        assert!(empty_page.cells.as_slice().is_empty());
-    }
-
-    #[test]
-    fn disabling_background_does_not_disable_layer_or_status_sources() {
-        type StatusEngine = StandardLightingEngine<'static, EmptySource, SparseScene<'static, BuiltinEffect>, 2, 2>;
-        let mut engine = StatusEngine::new(
-            BackgroundState {
-                value: 10,
-                ..BackgroundState::default()
-            },
-            LayerScenes {
-                scenes: &LAYERS,
-                policy: LayerPolicy::ActiveStack,
-            },
-            EmptySource,
-            SparseScene { cells: &STATUS_CELLS },
-        );
-        let snapshot = context(1);
-        let before = engine.state();
-        engine
-            .handle_command(
-                0,
-                StandardCommand::PatchBackground(BackgroundPatch {
-                    enabled: Some(false),
-                    ..BackgroundPatch::default()
-                }),
-                &snapshot,
-            )
-            .unwrap();
-
-        assert!(engine.state().output_enabled);
-        assert_eq!(engine.state().output_brightness, before.output_brightness);
-        let mut frame = LogicalFrame::new(Rgb8::BLACK);
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 0,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(frame.as_slice(), &[RED, GREEN]);
-    }
-
-    #[test]
-    fn standard_engine_composes_background_layer_and_expiring_overlay() {
-        let mut engine = engine();
-        let snapshot = context(1);
-        engine
-            .handle_command(
-                100,
-                StandardCommand::SetOverlay(OverlayCell {
-                    slot: LedSlot(1),
-                    effect: BuiltinEffect::Solid { color: GREEN },
-                    ttl_ms: NonZeroU32::new(10),
-                }),
-                &snapshot,
-            )
-            .unwrap();
-        let mut frame = LogicalFrame::new(Rgb8::BLACK);
-        let outcome = engine
-            .render(
-                RenderInput {
-                    now_ms: 100,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(frame.as_slice(), &[RED, GREEN]);
-        assert_eq!(outcome.next_wake_in_ms, NonZeroU32::new(10));
-        <Engine as LightingEngine<LightingContext>>::on_presented(&mut engine, &frame);
-
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 110,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(frame.as_slice(), &[RED, Rgb8::new(10, 10, 10)]);
-        assert_eq!(engine.state().overlay_len, 0);
-    }
-
-    #[test]
-    fn expired_overlay_capacity_is_reclaimed_and_light_actions_are_scoped() {
-        let mut engine = engine();
-        let snapshot = context(0);
-        for slot in [LedSlot(0), LedSlot(1)] {
-            engine
-                .handle_command(
-                    0,
-                    StandardCommand::SetOverlay(OverlayCell {
-                        slot,
-                        effect: BuiltinEffect::Solid { color: GREEN },
-                        ttl_ms: NonZeroU32::new(1),
-                    }),
-                    &snapshot,
-                )
-                .unwrap();
-        }
-        assert!(
-            engine
-                .handle_command(
-                    1,
-                    StandardCommand::SetOverlay(OverlayCell {
-                        slot: LedSlot(0),
-                        effect: BuiltinEffect::Solid { color: RED },
-                        ttl_ms: None,
-                    }),
-                    &snapshot,
-                )
-                .is_ok()
-        );
-
-        let before = engine.state();
-        assert_eq!(
-            engine.on_input(StandardInput(LightAction::RgbModeRainbow), &snapshot),
-            Ok(Invalidation::None)
-        );
-        assert_eq!(engine.state(), before);
-        assert_eq!(
-            engine.on_input(StandardInput(LightAction::BacklightOff), &snapshot),
-            Ok(Invalidation::Render)
-        );
-        assert!(!engine.state().output_enabled);
-    }
-
-    const BLUE: Rgb8 = Rgb8::new(0, 0, 200);
-
-    type SceneEngine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2, 4>;
-
-    fn scene_engine() -> SceneEngine {
-        StandardLightingEngine::new(
-            BackgroundState {
-                value: 10,
-                ..BackgroundState::default()
-            },
-            LayerScenes {
-                scenes: &LAYERS,
-                policy: LayerPolicy::ActiveStack,
-            },
-            EmptySource,
-            EmptySource,
-        )
-    }
-
-    fn scene_cell(layer: u8, slot: u16, color: Rgb8) -> SceneTableCell {
-        SceneTableCell {
-            layer,
-            slot: LedSlot(slot),
-            effect: BuiltinEffect::Solid { color },
-        }
-    }
-
-    fn set_cell(engine: &mut SceneEngine, revision: u32, cell: SceneTableCell) -> StandardState {
-        engine
-            .handle_command(
-                0,
-                StandardCommand::SetSceneCellIfRevision {
-                    expected_revision: revision,
-                    cell,
-                },
-                &context(0),
-            )
-            .unwrap()
-            .reply
-            .state()
-            .unwrap()
-    }
-
-    fn scenes_page(engine: &mut SceneEngine, offset: u16) -> ScenePage {
-        match engine
-            .handle_command(0, StandardCommand::ReadScenes { offset }, &context(0))
-            .unwrap()
-            .reply
-        {
-            StandardReply::ScenesPage(page) => page,
-            other => panic!("expected page, got {other:?}"),
-        }
-    }
-
-    #[test]
-    fn scene_crud_is_revision_checked_and_keyed_by_layer_and_slot() {
-        let mut engine = scene_engine();
-        let snapshot = context(0);
-
-        let state = set_cell(&mut engine, 0, scene_cell(1, 0, GREEN));
-        assert_eq!(state.revision, 1);
-        assert_eq!(state.scene_len, 1);
-
-        // Same (layer, slot) updates in place; a new pair appends.
-        let state = set_cell(&mut engine, 1, scene_cell(1, 0, BLUE));
-        assert_eq!(state.scene_len, 1);
-        let state = set_cell(&mut engine, 2, scene_cell(2, 0, RED));
-        assert_eq!(state.scene_len, 2);
-
-        assert_eq!(
-            engine.handle_command(
-                0,
-                StandardCommand::SetSceneCellIfRevision {
-                    expected_revision: 0,
-                    cell: scene_cell(0, 1, RED),
-                },
-                &snapshot,
-            ),
-            Err(StandardError::RevisionConflict {
-                expected: 0,
-                current: 3
-            })
-        );
-        assert_eq!(engine.state().scene_len, 2, "a stale write is all-or-nothing");
-
-        // Out-of-range slots never reach the table.
-        assert_eq!(
-            engine.handle_command(
-                0,
-                StandardCommand::SetSceneCellIfRevision {
-                    expected_revision: 3,
-                    cell: scene_cell(0, 9, RED),
-                },
-                &snapshot,
-            ),
-            Err(StandardError::SceneSlotOutOfRange { slot: LedSlot(9) })
-        );
-
-        // Unset of a missing cell keeps the revision moving but not the frame.
-        let result = engine
-            .handle_command(
-                0,
-                StandardCommand::UnsetSceneCellIfRevision {
-                    expected_revision: 3,
-                    layer: 7,
-                    slot: LedSlot(0),
-                },
-                &snapshot,
-            )
-            .unwrap();
-        assert_eq!(result.invalidation, Invalidation::StateChanged);
-        let state = result.reply.state().unwrap();
-        assert_eq!(state.scene_len, 2);
-        assert_eq!(state.revision, 4);
-
-        let state = engine
-            .handle_command(
-                0,
-                StandardCommand::UnsetSceneCellIfRevision {
-                    expected_revision: 4,
-                    layer: 1,
-                    slot: LedSlot(0),
-                },
-                &snapshot,
-            )
-            .unwrap()
-            .reply
-            .state()
-            .unwrap();
-        assert_eq!(state.scene_len, 1);
-
-        // Capacity is enforced with the table's own limit.
-        for (revision, (layer, slot)) in [(5u32, (5u8, 0u16)), (6, (5, 1)), (7, (6, 0))] {
-            set_cell(&mut engine, revision, scene_cell(layer, slot, RED));
-        }
-        assert_eq!(
-            engine.handle_command(
-                0,
-                StandardCommand::SetSceneCellIfRevision {
-                    expected_revision: 8,
-                    cell: scene_cell(9, 1, RED),
-                },
-                &snapshot,
-            ),
-            Err(StandardError::SceneFull { capacity: 4 })
-        );
-    }
-
-    #[test]
-    fn scene_pages_echo_revision_and_clamp() {
-        let mut engine = scene_engine();
-        set_cell(&mut engine, 0, scene_cell(0, 0, RED));
-        set_cell(&mut engine, 1, scene_cell(0, 1, GREEN));
-
-        let page = scenes_page(&mut engine, 0);
-        assert_eq!(page.revision, 2);
-        assert_eq!(page.total, 2);
-        assert_eq!(page.cells.as_slice().len(), 2);
-        let tail = scenes_page(&mut engine, 99);
-        assert_eq!(tail.total, 2);
-        assert!(tail.cells.as_slice().is_empty());
-    }
-
-    #[test]
-    fn runtime_scene_overrides_static_layer_and_yields_to_overlay() {
-        let mut engine = scene_engine();
-        let snapshot = context(1);
-
-        // Static layer 1 paints slot 0 RED; runtime cell overrides to BLUE.
-        set_cell(&mut engine, 0, scene_cell(1, 0, BLUE));
-        let mut frame = LogicalFrame::new(Rgb8::BLACK);
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 0,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(frame.as_slice()[0], BLUE);
-
-        // The TTL overlay still wins above runtime scenes.
-        engine
-            .handle_command(
-                0,
-                StandardCommand::SetOverlay(OverlayCell {
-                    slot: LedSlot(0),
-                    effect: BuiltinEffect::Solid { color: GREEN },
-                    ttl_ms: None,
-                }),
-                &snapshot,
-            )
-            .unwrap();
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 1,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(frame.as_slice()[0], GREEN);
-    }
-
-    #[test]
-    fn layer_policy_switches_between_effective_only_and_active_stack() {
-        let mut engine = scene_engine();
-        // Base layer paints slot 1; effective layer paints slot 0.
-        set_cell(&mut engine, 0, scene_cell(0, 1, GREEN));
-        set_cell(&mut engine, 1, scene_cell(1, 0, BLUE));
-        let snapshot = context(1);
-
-        let mut frame = LogicalFrame::new(Rgb8::BLACK);
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 0,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(frame.as_slice(), &[BLUE, GREEN], "ActiveStack falls through sparsely");
-
-        let state = engine
-            .handle_command(
-                0,
-                StandardCommand::SetLayerPolicyIfRevision {
-                    expected_revision: 2,
-                    policy: LayerPolicy::EffectiveOnly,
-                },
-                &snapshot,
-            )
-            .unwrap()
-            .reply
-            .state()
-            .unwrap();
-        assert_eq!(state.scene_policy, LayerPolicy::EffectiveOnly);
-
-        let background = Rgb8::new(10, 10, 10);
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 1,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(
-            frame.as_slice(),
-            &[BLUE, background],
-            "EffectiveOnly hides base-layer cells"
-        );
-    }
-
-    #[test]
-    fn scene_replace_is_chunked_ordered_atomic_and_idempotent() {
-        let mut engine = scene_engine();
-        let snapshot = context(0);
-        set_cell(&mut engine, 0, scene_cell(3, 0, RED));
-
-        let (id, _) = match engine
-            .handle_command(
-                10,
-                StandardCommand::BeginSceneReplace {
-                    expected_revision: 1,
-                    cell_count: 2,
-                },
-                &snapshot,
-            )
-            .unwrap()
-            .reply
-        {
-            StandardReply::SceneTransaction { id, cell_count } => (id, cell_count),
-            other => panic!("expected transaction, got {other:?}"),
-        };
-
-        // A second begin while staged is busy; out-of-order chunks rejected.
-        assert_eq!(
-            engine.handle_command(
-                11,
-                StandardCommand::BeginSceneReplace {
-                    expected_revision: 1,
-                    cell_count: 0,
-                },
-                &snapshot,
-            ),
-            Err(StandardError::SceneTransactionBusy)
-        );
-        let mut chunk = SceneChunk::new();
-        chunk.push(scene_cell(0, 0, GREEN)).unwrap();
-        assert_eq!(
-            engine.handle_command(
-                12,
-                StandardCommand::PutSceneChunk {
-                    transaction_id: id,
-                    offset: 1,
-                    cells: chunk,
-                },
-                &snapshot,
-            ),
-            Err(StandardError::InvalidSceneRequest)
-        );
-        assert_eq!(
-            engine.handle_command(
-                13,
-                StandardCommand::CommitSceneReplace { transaction_id: id },
-                &snapshot,
-            ),
-            Err(StandardError::SceneTransactionIncomplete {
-                expected: 2,
-                received: 0
-            })
-        );
-
-        let mut chunk = SceneChunk::new();
-        chunk.push(scene_cell(0, 0, GREEN)).unwrap();
-        chunk.push(scene_cell(0, 1, BLUE)).unwrap();
-        engine
-            .handle_command(
-                14,
-                StandardCommand::PutSceneChunk {
-                    transaction_id: id,
-                    offset: 0,
-                    cells: chunk,
-                },
-                &snapshot,
-            )
-            .unwrap();
-
-        let committed = engine
-            .handle_command(
-                15,
-                StandardCommand::CommitSceneReplace { transaction_id: id },
-                &snapshot,
-            )
-            .unwrap();
-        assert_eq!(committed.invalidation, Invalidation::Render);
-        let state = committed.reply.state().unwrap();
-        assert_eq!(state.scene_len, 2, "replacement drops the previous table");
-        assert_eq!(state.revision, 2);
-
-        // Retried commit answers idempotently without another revision bump.
-        let retried = engine
-            .handle_command(
-                16,
-                StandardCommand::CommitSceneReplace { transaction_id: id },
-                &snapshot,
-            )
-            .unwrap();
-        assert_eq!(retried.invalidation, Invalidation::None);
-        assert_eq!(retried.reply.state().unwrap().revision, 2);
-
-        // A conflicting revision at commit leaves the table untouched.
-        let stale = match engine
-            .handle_command(
-                20,
-                StandardCommand::BeginSceneReplace {
-                    expected_revision: 0,
-                    cell_count: 0,
-                },
-                &snapshot,
-            )
-            .unwrap()
-            .reply
-        {
-            StandardReply::SceneTransaction { id, .. } => id,
-            other => panic!("expected transaction, got {other:?}"),
-        };
-        assert_eq!(
-            engine.handle_command(
-                21,
-                StandardCommand::CommitSceneReplace { transaction_id: stale },
-                &snapshot,
-            ),
-            Err(StandardError::RevisionConflict {
-                expected: 0,
-                current: 2
-            })
-        );
-        assert_eq!(engine.state().scene_len, 2);
-        engine
-            .handle_command(
-                22,
-                StandardCommand::AbortSceneReplace { transaction_id: stale },
-                &snapshot,
-            )
-            .unwrap();
-    }
-
-    #[test]
-    fn scene_transaction_expires_after_inactivity() {
-        let mut engine = scene_engine();
-        let snapshot = context(0);
-        let id = match engine
-            .handle_command(
-                0,
-                StandardCommand::BeginSceneReplace {
-                    expected_revision: 0,
-                    cell_count: 0,
-                },
-                &snapshot,
-            )
-            .unwrap()
-            .reply
-        {
-            StandardReply::SceneTransaction { id, .. } => id,
-            other => panic!("expected transaction, got {other:?}"),
-        };
-        assert_eq!(
-            engine.handle_command(
-                SCENE_TRANSACTION_TIMEOUT_MS,
-                StandardCommand::CommitSceneReplace { transaction_id: id },
-                &snapshot,
-            ),
-            Err(StandardError::SceneTransactionExpired)
-        );
-        assert_eq!(
-            engine.handle_command(
-                SCENE_TRANSACTION_TIMEOUT_MS,
-                StandardCommand::AbortSceneReplace { transaction_id: 999 },
-                &snapshot,
-            ),
-            Err(StandardError::InvalidSceneTransaction)
-        );
-    }
-    #[test]
-    fn extension_source_claims_light_actions_before_background() {
-        #[derive(Default)]
-        struct ClaimingSource;
-
-        impl<C, Context> LightingSource<C, Context> for ClaimingSource {
-            fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
-                0
-            }
-
-            fn slot(&self, _: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
-                unreachable!("ClaimingSource has no targets")
-            }
-
-            fn contribution(&mut self, _: usize, _: &SourceRenderInput<'_, Context>) -> Contribution<C> {
-                unreachable!("ClaimingSource has no samples")
-            }
-
-            fn handle_light_action(&mut self, action: LightAction) -> bool {
-                matches!(action, LightAction::RgbHui)
-            }
-        }
-
-        let mut engine: StandardLightingEngine<'static, ClaimingSource, EmptySource, 2, 2> =
-            StandardLightingEngine::new(
-                BackgroundState {
-                    value: 10,
-                    ..BackgroundState::default()
-                },
-                LayerScenes {
-                    scenes: &LAYERS,
-                    policy: LayerPolicy::ActiveStack,
-                },
-                ClaimingSource,
-                EmptySource,
-            );
-        let snapshot = context(0);
-        let hue_before = engine.state().background.hue;
-
-        assert_eq!(
-            engine.on_input(StandardInput(LightAction::RgbHui), &snapshot),
-            Ok(Invalidation::Render)
-        );
-        assert_eq!(engine.state().revision, 1);
-        assert_eq!(
-            engine.state().background.hue,
-            hue_before,
-            "a claimed action must bypass the built-in background handling"
-        );
-
-        engine.on_input(StandardInput(LightAction::RgbHud), &snapshot).unwrap();
-        assert_ne!(
-            engine.state().background.hue,
-            hue_before,
-            "unclaimed actions still fall through to the background"
-        );
-    }
-
-    #[test]
-    fn runtime_conditional_replace_preserves_order_and_output_mode_is_revision_checked() {
-        use rmk_types::battery::{BatteryStatus, ChargeState};
-
-        use crate::lighting::{BatteryCondition, ChargeCondition, LayerCondition};
-
-        struct Batteries;
-        impl BatteryStatusProvider for Batteries {
-            fn battery_status(&self, node: u8) -> BatteryStatus {
-                if node == 1 {
-                    BatteryStatus::Available {
-                        charge_state: ChargeState::Discharging,
-                        level: Some(50),
-                    }
-                } else {
-                    BatteryStatus::Unavailable
-                }
-            }
-        }
-        static BATTERIES: Batteries = Batteries;
-
-        let mut engine = scene_engine().with_battery_status_provider(&BATTERIES);
-        let snapshot = context(0);
-        let transaction_id = match engine
-            .handle_command(
-                0,
-                StandardCommand::BeginRuntimeConditionalSceneReplace {
-                    expected_revision: 0,
-                    cell_count: 2,
-                },
-                &snapshot,
-            )
-            .unwrap()
-            .reply
-        {
-            StandardReply::RuntimeConditionalSceneTransaction { id, .. } => id,
-            other => panic!("expected runtime conditional transaction, got {other:?}"),
-        };
-        let mut cells = RuntimeConditionalSceneChunk::new();
-        cells
-            .push(RuntimeConditionalSceneCell {
-                conditions: ConditionSet {
-                    layer: None,
-                    battery: Some(BatteryCondition {
-                        node: 1,
-                        min_level: Some(25),
-                        max_level: Some(75),
-                        charge: ChargeCondition::Discharging,
-                    }),
-                },
-                slot: LedSlot(1),
-                effect: BuiltinEffect::Solid { color: RED },
-            })
-            .unwrap();
-        cells
-            .push(RuntimeConditionalSceneCell {
-                conditions: ConditionSet {
-                    layer: Some(LayerCondition { layer: 0, active: true }),
-                    battery: None,
-                },
-                slot: LedSlot(1),
-                effect: BuiltinEffect::Solid { color: GREEN },
-            })
-            .unwrap();
-        engine
-            .handle_command(
-                1,
-                StandardCommand::PutRuntimeConditionalSceneChunk {
-                    transaction_id,
-                    offset: 0,
-                    cells,
-                },
-                &snapshot,
-            )
-            .unwrap();
-        let committed = engine
-            .handle_command(
-                2,
-                StandardCommand::CommitRuntimeConditionalSceneReplace { transaction_id },
-                &snapshot,
-            )
-            .unwrap();
-        assert_eq!(committed.reply.state().unwrap().revision, 1);
-        assert_eq!(engine.runtime_conditional_scenes().as_slice(), cells.as_slice());
-
-        let mut frame = LogicalFrame::new(Rgb8::BLACK);
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 2,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(frame.as_slice()[1], GREEN, "later matching rules win");
-
-        assert_eq!(
-            engine.handle_command(
-                3,
-                StandardCommand::SetOutputModeIfRevision {
-                    expected_revision: 0,
-                    mode: OutputMode::PoweredOnly,
-                },
-                &snapshot,
-            ),
-            Err(StandardError::RevisionConflict {
-                expected: 0,
-                current: 1,
-            })
-        );
-        let set = engine
-            .handle_command(
-                3,
-                StandardCommand::SetOutputModeIfRevision {
-                    expected_revision: 1,
-                    mode: OutputMode::PoweredOnly,
-                },
-                &snapshot,
-            )
-            .unwrap();
-        assert_eq!(set.reply.state().unwrap().output_mode, OutputMode::PoweredOnly);
-        assert_eq!(set.reply.state().unwrap().revision, 2);
-    }
-
-    /// Interning is what shrinks a cell from 20 bytes to 4: many keys painted
-    /// from few colours share one entry, and the effect's type stops mattering
-    /// to the cell, so blink and breathe need no separate table.
-    #[test]
-    fn interning_shares_one_entry_per_distinct_effect() {
-        let mut pool = StylePool::new();
-        let blue = BuiltinEffect::solid(Rgb8::new(0, 0, 9));
-        let green = BuiltinEffect::solid(Rgb8::new(0, 9, 0));
-
-        let first = pool.intern(blue).unwrap();
-        assert_eq!(pool.intern(blue), Some(first), "same effect, same entry");
-        let other = pool.intern(green).unwrap();
-        assert_ne!(first, other);
-        assert_eq!(pool.len(), 2);
-        assert_eq!(pool.get(first), Some(blue));
-        assert_eq!(pool.get(other), Some(green));
-    }
-
-    #[test]
-    fn a_full_pool_declines_only_new_effects() {
-        let mut pool = StylePool::new();
-        for shade in 0..SCENE_STYLE_CAP {
-            pool.intern(BuiltinEffect::solid(Rgb8::new(shade as u8, 0, 0))).unwrap();
-        }
-        assert_eq!(pool.len(), SCENE_STYLE_CAP);
-
-        // Already held: still fine, however full.
-        let held = BuiltinEffect::solid(Rgb8::new(0, 0, 0));
-        assert!(pool.intern(held).is_some());
-
-        // New: declined, and declining mutates nothing.
-        let before = pool;
-        assert_eq!(pool.intern(BuiltinEffect::solid(Rgb8::new(0, 1, 2))), None);
-        assert_eq!(pool, before);
-    }
-
-    /// A style goes when nothing points at it, found by scanning rather than by
-    /// keeping counts -- and it must survive while another cell still holds it.
-    #[test]
-    fn a_style_outlives_all_but_its_last_reference() {
-        let mut table = SceneTable::<4>::new();
-        let red = BuiltinEffect::solid(Rgb8::new(9, 0, 0));
-        let cell = |slot| SceneTableCell {
-            layer: 0,
-            slot: LedSlot(slot),
-            effect: red,
-        };
-        table.set(cell(0)).unwrap();
-        table.set(cell(1)).unwrap();
-        assert_eq!((table.len(), table.pool.len()), (2, 1));
-
-        assert!(table.unset(0, LedSlot(0)));
-        assert_eq!(table.pool.len(), 1, "the other cell still holds it");
-
-        assert!(table.unset(0, LedSlot(1)));
-        assert_eq!((table.len(), table.pool.len()), (0, 0));
-    }
-
-    /// Repainting one key is what painting in a configurator does, and it must
-    /// not strand an entry each time: 64 repaints would exhaust the pool.
-    #[test]
-    fn repainting_a_cell_does_not_strand_styles() {
-        let mut table = SceneTable::<4>::new();
-        for shade in 0..(SCENE_STYLE_CAP as u8 * 3) {
-            table
-                .set(SceneTableCell {
-                    layer: 0,
-                    slot: LedSlot(0),
-                    effect: BuiltinEffect::solid(Rgb8::new(shade, shade, shade)),
-                })
-                .expect("overwriting one cell never needs a second entry");
-            assert_eq!(table.pool.len(), 1, "the previous shade was freed");
-        }
-        assert_eq!(table.len(), 1);
-    }
-
-    #[test]
-    fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules() {
-        use rmk_types::battery::BatteryStatus;
-
-        use crate::lighting::{ConditionalSceneCell, ConditionalScenes, LayerCondition};
-
-        struct NoBatteries;
-        impl BatteryStatusProvider for NoBatteries {
-            fn battery_status(&self, _node: u8) -> BatteryStatus {
-                BatteryStatus::Unavailable
-            }
-        }
-        static NO_BATTERIES: NoBatteries = NoBatteries;
-
-        // Slot 0 is contested three ways: a compiled layer scene paints it RED
-        // on layer 1, a compiled conditional rule paints it GREEN, and the
-        // runtime table paints it BLUE. Only the host's rule should survive.
-        static COMPILED_CONDITIONAL: [ConditionalSceneCell<BuiltinEffect>; 1] = [ConditionalSceneCell {
-            conditions: ConditionSet {
-                layer: Some(LayerCondition { layer: 1, active: true }),
-                battery: None,
-            },
-            slot: LedSlot(0),
-            effect: BuiltinEffect::Solid { color: GREEN },
-        }];
-
-        let mut engine: StandardLightingEngine<
-            'static,
-            EmptySource,
-            ConditionalScenes<'static, BuiltinEffect, NoBatteries>,
-            2,
-            2,
-            4,
-        > = StandardLightingEngine::new(
-            BackgroundState {
-                value: 10,
-                ..BackgroundState::default()
-            },
-            LayerScenes {
-                scenes: &LAYERS,
-                policy: LayerPolicy::ActiveStack,
-            },
-            EmptySource,
-            ConditionalScenes::new(&COMPILED_CONDITIONAL, &NO_BATTERIES),
-        )
-        .with_battery_status_provider(&NO_BATTERIES);
-
-        let snapshot = context(1);
-        let mut frame = LogicalFrame::new(Rgb8::BLACK);
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 0,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(
-            frame.as_slice()[0],
-            GREEN,
-            "compiled conditional rules outrank compiled layer scenes"
-        );
-
-        engine
-            .install_runtime_conditional_scene_cell(RuntimeConditionalSceneCell {
-                conditions: ConditionSet {
-                    layer: Some(LayerCondition { layer: 1, active: true }),
-                    battery: None,
-                },
-                slot: LedSlot(0),
-                effect: BuiltinEffect::Solid { color: BLUE },
-            })
-            .unwrap();
-        let mut frame = LogicalFrame::new(Rgb8::BLACK);
-        engine
-            .render(
-                RenderInput {
-                    now_ms: 1,
-                    snapshot: &snapshot,
-                },
-                &mut frame,
-            )
-            .unwrap();
-        assert_eq!(
-            frame.as_slice()[0],
-            BLUE,
-            "a runtime conditional cell replaces the compiled rule on the same slot"
-        );
-    }
-}
diff --git a/rmk/src/lighting/standard/background.rs b/rmk/src/lighting/standard/background.rs
new file mode 100644
index 000000000..fda509cc1
--- /dev/null
+++ b/rmk/src/lighting/standard/background.rs
@@ -0,0 +1,143 @@
+#[allow(unused_imports)]
+use super::*;
+use crate::lighting::Rgb8;
+use crate::lighting::compositor::{Contribution, LightingSource, RenderInput as SourceRenderInput};
+use crate::lighting::effect::{BuiltinEffect, LightingEffect};
+use crate::lighting::topology::LedSlot;
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum BackgroundMode {
+    Solid,
+    Breathe,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct BackgroundState {
+    pub enabled: bool,
+    pub hue: u8,
+    pub saturation: u8,
+    pub value: u8,
+    pub speed: u8,
+    pub mode: BackgroundMode,
+}
+
+impl Default for BackgroundState {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            hue: 0,
+            saturation: 0,
+            value: 32,
+            speed: 128,
+            mode: BackgroundMode::Solid,
+        }
+    }
+}
+
+/// Atomic partial update of the designated background.
+///
+/// Protocol adapters use this instead of a `ReadState` followed by
+/// `SetBackground`: the lighting engine remains the sole mutable owner and
+/// concurrent callers cannot overwrite fields changed between two mailbox
+/// requests.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct BackgroundPatch {
+    pub enabled: Option<bool>,
+    pub hue: Option<u8>,
+    pub saturation: Option<u8>,
+    pub value: Option<u8>,
+    pub speed: Option<u8>,
+    pub mode: Option<BackgroundMode>,
+}
+
+impl BackgroundPatch {
+    pub const fn apply_to(self, state: &mut BackgroundState) {
+        if let Some(enabled) = self.enabled {
+            state.enabled = enabled;
+        }
+        if let Some(hue) = self.hue {
+            state.hue = hue;
+        }
+        if let Some(saturation) = self.saturation {
+            state.saturation = saturation;
+        }
+        if let Some(value) = self.value {
+            state.value = value;
+        }
+        if let Some(speed) = self.speed {
+            state.speed = speed;
+        }
+        if let Some(mode) = self.mode {
+            state.mode = mode;
+        }
+    }
+}
+
+/// Built-in designated background controlled by RGB/Vial-compatible fields.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct UniformBackground<const N: usize> {
+    pub(super) state: BackgroundState,
+}
+
+impl<const N: usize> UniformBackground<N> {
+    pub const fn new(state: BackgroundState) -> Self {
+        Self { state }
+    }
+
+    pub const fn state(&self) -> BackgroundState {
+        self.state
+    }
+
+    pub fn set_state(&mut self, state: BackgroundState) {
+        self.state = state;
+    }
+
+    fn effect(&self) -> BuiltinEffect {
+        let color = if self.state.enabled {
+            hsv(self.state.hue, self.state.saturation, self.state.value)
+        } else {
+            Rgb8::BLACK
+        };
+        match self.state.mode {
+            BackgroundMode::Solid => BuiltinEffect::Solid { color },
+            BackgroundMode::Breathe => BuiltinEffect::Breathe {
+                color,
+                period_ms: 250 + ((u8::MAX - self.state.speed) as u32 * 3_750 / 255),
+                phase_ms: 0,
+                step_ms: 16,
+            },
+        }
+    }
+}
+
+impl<Context, const N: usize> LightingSource<Rgb8, Context> for UniformBackground<N> {
+    fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
+        N
+    }
+
+    fn slot(&self, index: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
+        LedSlot::from_index(index)
+    }
+
+    fn contribution(&mut self, _: usize, input: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
+        Contribution::Opaque(self.effect().sample(input.now_ms))
+    }
+}
+
+/// Zero-sized source used when a board does not need an extension band.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct EmptySource;
+
+impl<C, Context> LightingSource<C, Context> for EmptySource {
+    fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
+        0
+    }
+
+    fn slot(&self, _: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
+        unreachable!("EmptySource has no targets")
+    }
+
+    fn contribution(&mut self, _: usize, _: &SourceRenderInput<'_, Context>) -> Contribution<C> {
+        unreachable!("EmptySource has no samples")
+    }
+}
diff --git a/rmk/src/lighting/standard/command.rs b/rmk/src/lighting/standard/command.rs
new file mode 100644
index 000000000..6ba18bc66
--- /dev/null
+++ b/rmk/src/lighting/standard/command.rs
@@ -0,0 +1,509 @@
+use core::cell::RefCell;
+use core::fmt;
+
+use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
+
+#[allow(unused_imports)]
+use super::*;
+use crate::RawMutex;
+use crate::lighting::compositor::{
+    ExtensionDescriptor, ExtensionParamSpec, ExtensionState, LightingSource, RenderError,
+};
+use crate::lighting::context::LightingContext;
+use crate::lighting::source::{LayerPolicy, OutputMode, OverlayError};
+use crate::lighting::topology::LedSlot;
+
+/// One in-progress, chunk-staged atomic scene replacement.
+///
+/// The overlay replacement stages host-side because a whole overlay batch
+/// fits one mailbox command. A scene table is an order of magnitude larger,
+/// so its transaction stages inside the engine via bounded chunks instead of
+/// forcing kilobyte-sized command payloads through every mailbox.
+pub(super) struct SceneReplace<const CAP: usize> {
+    pub(super) id: u32,
+    pub(super) expected_revision: u32,
+    pub(super) expected_count: u16,
+    pub(super) cells: [SceneTableCell; CAP],
+    pub(super) len: usize,
+    pub(super) last_activity_ms: u64,
+}
+
+pub(super) struct RuntimeConditionalSceneReplace<const CAP: usize> {
+    pub(super) id: u32,
+    pub(super) expected_revision: u32,
+    pub(super) expected_count: u16,
+    pub(super) cells: [RuntimeConditionalSceneCell; CAP],
+    pub(super) len: usize,
+    pub(super) last_activity_ms: u64,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
+    SetOutputEnabled(bool),
+    SetOutputModeIfRevision {
+        expected_revision: u32,
+        mode: OutputMode,
+    },
+    SetOutputBrightness(u8),
+    SetBackground(BackgroundState),
+    PatchBackground(BackgroundPatch),
+    SetStateIfRevision {
+        expected_revision: u32,
+        state: StandardMutableState,
+    },
+    SetOverlay(OverlayCell),
+    SetOverlayIfRevision {
+        expected_revision: u32,
+        cell: OverlayCell,
+    },
+    UnsetOverlay(LedSlot),
+    UnsetOverlayIfRevision {
+        expected_revision: u32,
+        slot: LedSlot,
+    },
+    ClearOverlay,
+    ClearOverlayIfRevision {
+        expected_revision: u32,
+    },
+    ReplaceOverlay(OverlayBatch<OVERLAY_CAP>),
+    ReplaceOverlayIfRevision {
+        expected_revision: u32,
+        batch: OverlayBatch<OVERLAY_CAP>,
+    },
+    /// Atomically export all state needed by a renderer replica. The larger
+    /// snapshot moves through the referenced slot so it does not inflate
+    /// every element of the bounded command queue.
+    ExportReplica(&'static StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP>),
+    /// Atomically install a snapshot previously placed in the referenced
+    /// slot. Intended for a renderer replica, not a second authority.
+    ApplyReplica(&'static StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP>),
+    ReadState,
+    /// Descriptor and current selection of the extension source, if any.
+    ReadExtension,
+    SetExtensionIfRevision {
+        expected_revision: u32,
+        state: ExtensionState,
+    },
+    /// One page of the addressed effect's parameter specs paired with the
+    /// source's live values.
+    ReadExtensionParams {
+        effect: u8,
+        offset: u8,
+    },
+    SetExtensionParamIfRevision {
+        expected_revision: u32,
+        effect: u8,
+        index: u8,
+        value: u8,
+    },
+    /// One atomically sampled page of the transient overlay.
+    ReadOverlay {
+        offset: u16,
+    },
+    SetSceneCellIfRevision {
+        expected_revision: u32,
+        cell: SceneTableCell,
+    },
+    UnsetSceneCellIfRevision {
+        expected_revision: u32,
+        layer: u8,
+        slot: LedSlot,
+    },
+    SetLayerPolicyIfRevision {
+        expected_revision: u32,
+        policy: LayerPolicy,
+    },
+    /// Reserve the engine's single scene-staging transaction. The expected
+    /// revision is recorded here and enforced atomically at commit.
+    BeginSceneReplace {
+        expected_revision: u32,
+        cell_count: u16,
+    },
+    PutSceneChunk {
+        transaction_id: u32,
+        offset: u16,
+        cells: SceneChunk,
+    },
+    CommitSceneReplace {
+        transaction_id: u32,
+    },
+    AbortSceneReplace {
+        transaction_id: u32,
+    },
+    /// One page of the stored scene table starting at `offset`.
+    ReadScenes {
+        offset: u16,
+    },
+    /// One page of the immutable board-compiled layer scenes.
+    ReadCompiledScenes {
+        offset: u16,
+    },
+    ReadRuntimeConditionalScenes {
+        offset: u16,
+    },
+    BeginRuntimeConditionalSceneReplace {
+        expected_revision: u32,
+        cell_count: u16,
+    },
+    PutRuntimeConditionalSceneChunk {
+        transaction_id: u32,
+        offset: u16,
+        cells: RuntimeConditionalSceneChunk,
+    },
+    CommitRuntimeConditionalSceneReplace {
+        transaction_id: u32,
+    },
+    AbortRuntimeConditionalSceneReplace {
+        transaction_id: u32,
+    },
+}
+
+/// Mutable standard state excluding the transient overlay contents and the
+/// engine-owned optimistic-concurrency revision.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct StandardMutableState {
+    pub output_enabled: bool,
+    pub output_brightness: u8,
+    pub background: BackgroundState,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct StandardState {
+    pub revision: u32,
+    pub output_enabled: bool,
+    pub output_mode: OutputMode,
+    pub powered: bool,
+    pub wake_active: bool,
+    pub output_brightness: u8,
+    pub background: BackgroundState,
+    pub overlay_len: usize,
+    pub scene_len: usize,
+    pub scene_policy: LayerPolicy,
+    pub runtime_conditional_scene_len: usize,
+}
+
+/// One page of transient overlay cells with remaining TTLs.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct OverlayPage {
+    pub revision: u32,
+    pub total: u16,
+    pub cells: OverlayBatch<OVERLAY_CHUNK_SIZE>,
+}
+
+/// One page of stored scene cells with the revision it was read under.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ScenePage {
+    pub revision: u32,
+    pub total: u16,
+    pub cells: SceneChunk,
+}
+
+/// Extension-source readback: selectable content plus current selection.
+/// `descriptor`/`state` are `None` when the engine's extension band is not
+/// user-selectable (e.g. `EmptySource`).
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionPage {
+    pub revision: u32,
+    pub descriptor: Option<ExtensionDescriptor>,
+    pub state: Option<ExtensionState>,
+}
+
+/// Number of extension parameters carried by one [`ExtensionParamsPage`].
+pub const EXTENSION_PARAM_CHUNK: usize = 8;
+
+/// One extension parameter: its static spec plus the source's live value.
+/// The value falls back to the spec's default when the source does not
+/// report one.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionParamValue {
+    pub spec: ExtensionParamSpec,
+    pub value: u8,
+}
+
+/// One page of an extension effect's parameters. Pinned to the engine
+/// revision like every other mutable readback.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionParamsPage {
+    pub revision: u32,
+    /// Total parameters the addressed effect advertises.
+    pub total: u8,
+    /// Rows starting at the request's offset; trailing entries are `None`.
+    pub items: [Option<ExtensionParamValue>; EXTENSION_PARAM_CHUNK],
+}
+
+impl ExtensionParamsPage {
+    /// The populated rows, in order.
+    pub fn items(&self) -> impl Iterator<Item = ExtensionParamValue> + '_ {
+        self.items.iter().copied().flatten()
+    }
+}
+
+/// The active effect's live parameter values, carried in a replica snapshot
+/// so a split renderer tracks the authority's tuning.
+///
+/// Only the active effect travels: it is the only one a replica renders, and
+/// bounding the row at [`EXTENSION_PARAM_CHUNK`] keeps the snapshot `Copy`
+/// with a fixed RAM cost. Parameters of inactive effects ride along when
+/// that effect becomes active, since export always reads live values.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionReplicaParams {
+    pub effect: u8,
+    pub len: u8,
+    pub values: [u8; EXTENSION_PARAM_CHUNK],
+}
+
+impl ExtensionReplicaParams {
+    /// The populated values, in parameter order.
+    pub fn values(&self) -> &[u8] {
+        &self.values[..(self.len as usize).min(EXTENSION_PARAM_CHUNK)]
+    }
+}
+
+/// The parameter specs an extension source advertises for `effect`.
+///
+/// A free function because the callers live in the engine's `LightingEngine`
+/// impl, where `Context` is in scope but no inherent impl carries the
+/// [`LightingSource`] bound.
+pub(super) fn extension_param_specs<C, Context, S>(
+    source: &S,
+    effect: u8,
+) -> Result<&'static [ExtensionParamSpec], StandardError>
+where
+    S: LightingSource<C, Context> + ?Sized,
+{
+    source
+        .extension_descriptor()
+        .and_then(|descriptor| descriptor.effect_params(effect))
+        .ok_or(StandardError::ExtensionUnsupported)
+}
+
+/// Check one parameter's address and its spec's range without applying it.
+///
+/// Split from the apply so replica application can validate a whole batch
+/// before mutating anything, the way the overlay is validated first.
+pub(super) fn check_extension_param<C, Context, S>(
+    source: &S,
+    effect: u8,
+    index: u8,
+    value: u8,
+) -> Result<(), StandardError>
+where
+    S: LightingSource<C, Context> + ?Sized,
+{
+    let specs = extension_param_specs::<C, Context, S>(source, effect)?;
+    let spec = specs.get(index as usize).ok_or(StandardError::ExtensionUnsupported)?;
+    if value < spec.min || value > spec.max {
+        return Err(StandardError::ExtensionUnsupported);
+    }
+    Ok(())
+}
+
+/// Validate one parameter against its spec, then offer it to the source.
+///
+/// Shared by the host-facing set command and replica application so both
+/// reject the same addresses and the same out-of-range values.
+pub(super) fn apply_extension_param_checked<C, Context, S>(
+    source: &mut S,
+    effect: u8,
+    index: u8,
+    value: u8,
+) -> Result<(), StandardError>
+where
+    S: LightingSource<C, Context> + ?Sized,
+{
+    check_extension_param::<C, Context, S>(source, effect, index, value)?;
+    if !source.apply_extension_param(effect, index, value) {
+        return Err(StandardError::ExtensionUnsupported);
+    }
+    Ok(())
+}
+
+/// One page of immutable board-compiled layer scenes.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct CompiledScenePage {
+    pub total: u16,
+    pub policy: LayerPolicy,
+    pub cells: SceneChunk,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct RuntimeConditionalScenePage {
+    pub revision: u32,
+    pub total: u16,
+    pub cells: RuntimeConditionalSceneChunk,
+}
+
+/// Protocol-independent readback for [`StandardCommand`]s. Most commands
+/// answer with authoritative [`StandardState`]; scene reads and transaction
+/// reservation carry their own shapes.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum StandardReply {
+    State(StandardState),
+    OverlayPage(OverlayPage),
+    ScenesPage(ScenePage),
+    CompiledScenesPage(CompiledScenePage),
+    SceneTransaction { id: u32, cell_count: u16 },
+    Extension(ExtensionPage),
+    ExtensionParams(ExtensionParamsPage),
+    RuntimeConditionalScenesPage(RuntimeConditionalScenePage),
+    RuntimeConditionalSceneTransaction { id: u32, cell_count: u16 },
+}
+
+impl StandardReply {
+    /// The state readback carried by state-shaped replies.
+    pub const fn state(self) -> Option<StandardState> {
+        match self {
+            Self::State(state) => Some(state),
+            _ => None,
+        }
+    }
+}
+
+/// Complete declarative state needed by a standard-engine renderer replica.
+///
+/// `sample_time_ms` is the authority's animation clock at snapshot time.
+/// Applying the snapshot anchors the replica's local monotonic clock to that
+/// value; subsequent animation frames are sampled locally without link
+/// traffic. Overlay TTLs are remaining lifetimes at the same instant.
+///
+/// The runtime scene table travels with the snapshot: replicas must render
+/// host-configured per-layer scenes exactly like the authority, and they
+/// never receive the incremental scene mutation commands themselves.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct StandardReplicaState<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
+    pub revision: u32,
+    pub mutable: StandardMutableState,
+    pub output_mode: OutputMode,
+    pub overlay: OverlayBatch<OVERLAY_CAP>,
+    pub scenes: SceneTable<SCENE_CAP>,
+    pub runtime_conditional_scenes: RuntimeConditionalSceneTable<SCENE_CAP>,
+    pub context: LightingContext,
+    pub sample_time_ms: u64,
+    /// Extension-source selection, carried so split renderer replicas track
+    /// the authority's animated band. `None` when the authority has no
+    /// selectable extension.
+    pub extension: Option<ExtensionState>,
+    /// The active effect's live parameter values. `None` when the authority
+    /// has no selectable extension or the active effect has no parameters.
+    pub extension_params: Option<ExtensionReplicaParams>,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum ReplicaSlotError {
+    Busy,
+    Empty,
+}
+
+/// One statically allocated hand-off slot for a replica snapshot.
+///
+/// The lighting mailbox serializes access. Keeping the large snapshot out of
+/// [`StandardCommand`] prevents command-channel capacity from multiplying its
+/// RAM cost on small MCUs.
+pub struct StandardReplicaSlot<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
+    value: BlockingMutex<RawMutex, RefCell<Option<StandardReplicaState<OVERLAY_CAP, SCENE_CAP>>>>,
+}
+
+impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
+    pub const fn new() -> Self {
+        Self {
+            value: BlockingMutex::new(RefCell::new(None)),
+        }
+    }
+
+    pub fn put(&self, state: StandardReplicaState<OVERLAY_CAP, SCENE_CAP>) -> Result<(), ReplicaSlotError> {
+        self.value.lock(|value| {
+            let mut value = value.borrow_mut();
+            if value.is_some() {
+                Err(ReplicaSlotError::Busy)
+            } else {
+                *value = Some(state);
+                Ok(())
+            }
+        })
+    }
+
+    pub fn take(&self) -> Result<StandardReplicaState<OVERLAY_CAP, SCENE_CAP>, ReplicaSlotError> {
+        self.value
+            .lock(|value| value.borrow_mut().take().ok_or(ReplicaSlotError::Empty))
+    }
+}
+
+impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> Default for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> fmt::Debug for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("StandardReplicaSlot").finish_non_exhaustive()
+    }
+}
+
+impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> PartialEq for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {
+    fn eq(&self, other: &Self) -> bool {
+        core::ptr::eq(self, other)
+    }
+}
+
+impl<const OVERLAY_CAP: usize, const SCENE_CAP: usize> Eq for StandardReplicaSlot<OVERLAY_CAP, SCENE_CAP> {}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum StandardError {
+    Render(RenderError),
+    Overlay(OverlayError),
+    DeadlineOverflow,
+    ReplicaSlot(ReplicaSlotError),
+    RevisionConflict {
+        expected: u32,
+        current: u32,
+    },
+    SceneFull {
+        capacity: usize,
+    },
+    SceneSlotOutOfRange {
+        slot: LedSlot,
+    },
+    /// Malformed scene request: bad chunk order, count overflow, or a
+    /// duplicate `(layer, slot)` within one staged replacement.
+    InvalidSceneRequest,
+    /// The extension source declined the state (none installed, or an index
+    /// out of its descriptor's range).
+    ExtensionUnsupported,
+    SceneTransactionBusy,
+    InvalidSceneTransaction,
+    SceneTransactionExpired,
+    SceneTransactionIncomplete {
+        expected: u16,
+        received: u16,
+    },
+    ConditionalSceneFull {
+        capacity: usize,
+    },
+    InvalidConditionalSceneRequest,
+    ConditionalSceneTransactionBusy,
+    InvalidConditionalSceneTransaction,
+    ConditionalSceneTransactionExpired,
+    ConditionalSceneTransactionIncomplete {
+        expected: u16,
+        received: u16,
+    },
+}
+
+impl From<RenderError> for StandardError {
+    fn from(value: RenderError) -> Self {
+        Self::Render(value)
+    }
+}
+
+impl From<OverlayError> for StandardError {
+    fn from(value: OverlayError) -> Self {
+        Self::Overlay(value)
+    }
+}
+
+impl From<ReplicaSlotError> for StandardError {
+    fn from(value: ReplicaSlotError) -> Self {
+        Self::ReplicaSlot(value)
+    }
+}
diff --git a/rmk/src/lighting/standard/conditional.rs b/rmk/src/lighting/standard/conditional.rs
new file mode 100644
index 000000000..112337363
--- /dev/null
+++ b/rmk/src/lighting/standard/conditional.rs
@@ -0,0 +1,168 @@
+#[allow(unused_imports)]
+use super::*;
+use crate::lighting::Rgb8;
+use crate::lighting::compositor::{Contribution, LightingSource, RenderInput as SourceRenderInput};
+use crate::lighting::context::LightingContextProvider;
+use crate::lighting::effect::{BuiltinEffect, LightingEffect};
+use crate::lighting::source::{BatteryStatusProvider, ConditionSet};
+use crate::lighting::topology::LedSlot;
+
+/// One ordered, runtime-authored conditional rule.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct RuntimeConditionalSceneCell {
+    pub conditions: ConditionSet,
+    pub slot: LedSlot,
+    pub effect: BuiltinEffect,
+}
+
+pub(super) const EMPTY_CONDITIONAL_SCENE_CELL: RuntimeConditionalSceneCell = RuntimeConditionalSceneCell {
+    conditions: ConditionSet {
+        layer: None,
+        battery: None,
+    },
+    slot: LedSlot(0),
+    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+};
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct RuntimeConditionalSceneChunk {
+    cells: [RuntimeConditionalSceneCell; CONDITIONAL_SCENE_CHUNK_SIZE],
+    len: usize,
+}
+
+impl RuntimeConditionalSceneChunk {
+    pub const fn new() -> Self {
+        Self {
+            cells: [EMPTY_CONDITIONAL_SCENE_CELL; CONDITIONAL_SCENE_CHUNK_SIZE],
+            len: 0,
+        }
+    }
+
+    pub fn push(&mut self, cell: RuntimeConditionalSceneCell) -> Result<(), StandardError> {
+        if self.len == CONDITIONAL_SCENE_CHUNK_SIZE {
+            return Err(StandardError::InvalidConditionalSceneRequest);
+        }
+        self.cells[self.len] = cell;
+        self.len += 1;
+        Ok(())
+    }
+
+    pub fn as_slice(&self) -> &[RuntimeConditionalSceneCell] {
+        &self.cells[..self.len]
+    }
+}
+
+impl Default for RuntimeConditionalSceneChunk {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Fixed-capacity ordered conditional source. Order is semantic: later
+/// matching rules override earlier rules at the same compositor priority.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct RuntimeConditionalSceneTable<const CAP: usize> {
+    cells: [RuntimeConditionalSceneCell; CAP],
+    len: usize,
+}
+
+impl<const CAP: usize> RuntimeConditionalSceneTable<CAP> {
+    pub const fn new() -> Self {
+        Self {
+            cells: [EMPTY_CONDITIONAL_SCENE_CELL; CAP],
+            len: 0,
+        }
+    }
+
+    pub const fn len(&self) -> usize {
+        self.len
+    }
+
+    pub const fn is_empty(&self) -> bool {
+        self.len == 0
+    }
+
+    pub fn as_slice(&self) -> &[RuntimeConditionalSceneCell] {
+        &self.cells[..self.len]
+    }
+
+    pub fn push(&mut self, cell: RuntimeConditionalSceneCell) -> Result<(), StandardError> {
+        if self.len == CAP {
+            return Err(StandardError::ConditionalSceneFull { capacity: CAP });
+        }
+        self.cells[self.len] = cell;
+        self.len += 1;
+        Ok(())
+    }
+
+    pub fn clear(&mut self) {
+        self.len = 0;
+    }
+
+    pub fn page(&self, offset: u16) -> RuntimeConditionalSceneChunk {
+        let start = (offset as usize).min(self.len);
+        let end = (start + CONDITIONAL_SCENE_CHUNK_SIZE).min(self.len);
+        let mut chunk = RuntimeConditionalSceneChunk::new();
+        for cell in &self.cells[start..end] {
+            chunk.push(*cell).expect("page is chunk-bounded");
+        }
+        chunk
+    }
+}
+
+impl<const CAP: usize> Default for RuntimeConditionalSceneTable<CAP> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+pub(super) struct RuntimeConditionalSource<'a, Batteries: ?Sized, const CAP: usize> {
+    pub(super) table: &'a RuntimeConditionalSceneTable<CAP>,
+    pub(super) batteries: &'a Batteries,
+}
+
+impl<Context, Batteries, const CAP: usize> LightingSource<Rgb8, Context>
+    for RuntimeConditionalSource<'_, Batteries, CAP>
+where
+    Context: LightingContextProvider,
+    Batteries: BatteryStatusProvider + ?Sized,
+{
+    fn len(&self, input: &SourceRenderInput<'_, Context>) -> usize {
+        self.table
+            .as_slice()
+            .iter()
+            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
+            .count()
+    }
+
+    fn slot(&self, index: usize, input: &SourceRenderInput<'_, Context>) -> LedSlot {
+        self.table
+            .as_slice()
+            .iter()
+            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
+            .nth(index)
+            .expect("LightingSource index must be below len")
+            .slot
+    }
+
+    fn contribution(&mut self, index: usize, input: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
+        let cell = self
+            .table
+            .as_slice()
+            .iter()
+            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
+            .nth(index)
+            .expect("LightingSource index must be below len");
+        Contribution::Opaque(cell.effect.sample(input.now_ms))
+    }
+}
+
+pub(super) struct NoBatteryStatus;
+
+impl BatteryStatusProvider for NoBatteryStatus {
+    fn battery_status(&self, _node: u8) -> crate::types::battery::BatteryStatus {
+        crate::types::battery::BatteryStatus::Unavailable
+    }
+}
+
+pub(super) static NO_BATTERY_STATUS: NoBatteryStatus = NoBatteryStatus;
diff --git a/rmk/src/lighting/standard/engine.rs b/rmk/src/lighting/standard/engine.rs
new file mode 100644
index 000000000..ae104bddf
--- /dev/null
+++ b/rmk/src/lighting/standard/engine.rs
@@ -0,0 +1,1272 @@
+use core::num::NonZeroU32;
+
+use rmk_types::action::LightAction;
+
+#[allow(unused_imports)]
+use super::*;
+use crate::lighting::Rgb8;
+use crate::lighting::compositor::{Compositor, LightingSource, LogicalFrame};
+use crate::lighting::context::LightingContextProvider;
+use crate::lighting::effect::BuiltinEffect;
+use crate::lighting::output::BrightnessTransform;
+use crate::lighting::service::{CommandResult, Invalidation, LightingEngine, RenderInput, RenderOutcome};
+use crate::lighting::source::{
+    BatteryStatusProvider, LayerPolicy, LayerScenes, LightingControls, OutputMode, OverlayUpdate, SceneCell,
+    SparseScene, TtlOverlay,
+};
+use crate::lighting::topology::LedSlot;
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+struct AnimationClock {
+    local_anchor_ms: u64,
+    shared_anchor_ms: u64,
+}
+
+impl AnimationClock {
+    const fn local() -> Self {
+        Self {
+            local_anchor_ms: 0,
+            shared_anchor_ms: 0,
+        }
+    }
+
+    fn sample_time(self, local_now_ms: u64) -> u64 {
+        self.shared_anchor_ms
+            .saturating_add(local_now_ms.saturating_sub(self.local_anchor_ms))
+    }
+
+    fn anchor(&mut self, local_now_ms: u64, shared_now_ms: u64) {
+        self.local_anchor_ms = local_now_ms;
+        self.shared_anchor_ms = shared_now_ms;
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct StandardInput(pub LightAction);
+
+impl From<LightAction> for StandardInput {
+    fn from(value: LightAction) -> Self {
+        Self(value)
+    }
+}
+
+/// End-to-end standard engine. `Extension` composes above the designated
+/// background and below layers; `Status` composes last. Either can be an
+/// external stateful source, or [`EmptySource`].
+///
+/// Static board layer scenes and the runtime [`SceneTable`] share the layer
+/// band: runtime cells apply after the static defaults, so a host-configured
+/// cell overrides a board default for the same slot while the TTL overlay
+/// still wins above both.
+pub struct StandardLightingEngine<
+    'scenes,
+    Extension,
+    Status,
+    const N: usize,
+    const OVERLAY_CAP: usize,
+    const SCENE_CAP: usize = 0,
+> {
+    compositor: Compositor<Rgb8, N>,
+    background: UniformBackground<N>,
+    extension: Extension,
+    layers: LayerScenes<'scenes, BuiltinEffect>,
+    scenes: SceneTable<SCENE_CAP>,
+    runtime_conditional_scenes: RuntimeConditionalSceneTable<SCENE_CAP>,
+    battery_status: &'scenes dyn BatteryStatusProvider,
+    overlay: TtlOverlay<BuiltinEffect, OVERLAY_CAP>,
+    status: Status,
+    animation_clock: AnimationClock,
+    scene_replace: Option<SceneReplace<SCENE_CAP>>,
+    scene_next_transaction: u32,
+    scene_expired_transaction: Option<u32>,
+    scene_committed_transaction: Option<u32>,
+    runtime_conditional_scene_replace: Option<RuntimeConditionalSceneReplace<SCENE_CAP>>,
+    runtime_conditional_scene_next_transaction: u32,
+    runtime_conditional_scene_expired_transaction: Option<u32>,
+    runtime_conditional_scene_committed_transaction: Option<u32>,
+    revision: u32,
+    controls: LightingControls,
+    output_mode: OutputMode,
+    powered: bool,
+    wake_active: bool,
+    effective_output_enabled: bool,
+    output_brightness: u8,
+}
+
+impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const SCENE_CAP: usize>
+    StandardLightingEngine<'scenes, Extension, Status, N, OVERLAY_CAP, SCENE_CAP>
+{
+    pub fn new(
+        background: BackgroundState,
+        layers: LayerScenes<'scenes, BuiltinEffect>,
+        extension: Extension,
+        status: Status,
+    ) -> Self {
+        Self {
+            compositor: Compositor::new(Rgb8::BLACK),
+            background: UniformBackground::new(background),
+            extension,
+            layers,
+            scenes: SceneTable::new(),
+            runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
+            battery_status: &NO_BATTERY_STATUS,
+            overlay: TtlOverlay::new(),
+            status,
+            animation_clock: AnimationClock::local(),
+            scene_replace: None,
+            scene_next_transaction: 1,
+            scene_expired_transaction: None,
+            scene_committed_transaction: None,
+            runtime_conditional_scene_replace: None,
+            runtime_conditional_scene_next_transaction: 1,
+            runtime_conditional_scene_expired_transaction: None,
+            runtime_conditional_scene_committed_transaction: None,
+            revision: 0,
+            controls: LightingControls::default(),
+            output_mode: OutputMode::AlwaysOn,
+            powered: false,
+            wake_active: false,
+            effective_output_enabled: true,
+            output_brightness: u8::MAX,
+        }
+    }
+
+    /// Install the board's declarative lighting controls before the engine is
+    /// served. The configured initial mode becomes authoritative on boot.
+    pub const fn with_controls(mut self, controls: LightingControls) -> Self {
+        self.output_mode = controls.initial_output_mode;
+        self.effective_output_enabled = matches!(self.output_mode, OutputMode::AlwaysOn);
+        self.controls = controls;
+        self
+    }
+
+    /// Supply live board battery state for runtime conditional predicates.
+    pub const fn with_battery_status_provider(mut self, battery_status: &'scenes dyn BatteryStatusProvider) -> Self {
+        self.battery_status = battery_status;
+        self
+    }
+
+    pub const fn output_mode(&self) -> OutputMode {
+        self.output_mode
+    }
+
+    pub const fn powered(&self) -> bool {
+        self.powered
+    }
+
+    pub const fn wake_active(&self) -> bool {
+        self.wake_active
+    }
+
+    const fn effective_output(&self) -> bool {
+        self.wake_active
+            || matches!(self.output_mode, OutputMode::AlwaysOn)
+            || matches!(self.output_mode, OutputMode::PoweredOnly) && self.powered
+    }
+
+    pub fn state(&self) -> StandardState {
+        StandardState {
+            revision: self.revision,
+            output_enabled: self.effective_output(),
+            output_mode: self.output_mode,
+            powered: self.powered,
+            wake_active: self.wake_active,
+            output_brightness: self.output_brightness,
+            background: self.background.state(),
+            overlay_len: self.overlay.active_len(),
+            scene_len: self.scenes.len(),
+            scene_policy: self.scenes.policy(),
+            runtime_conditional_scene_len: self.runtime_conditional_scenes.len(),
+        }
+    }
+
+    pub const fn scene_capacity() -> usize {
+        SCENE_CAP
+    }
+
+    pub const fn scenes(&self) -> &SceneTable<SCENE_CAP> {
+        &self.scenes
+    }
+
+    pub const fn runtime_conditional_scenes(&self) -> &RuntimeConditionalSceneTable<SCENE_CAP> {
+        &self.runtime_conditional_scenes
+    }
+
+    /// Install one persisted scene cell during startup, before the engine is
+    /// serving commands. Does not advance the concurrency revision.
+    pub fn install_scene_cell(&mut self, cell: SceneTableCell) -> Result<(), StandardError> {
+        Self::check_scene_slot(cell.slot)?;
+        self.scenes.set(cell)
+    }
+
+    /// Install the persisted layer policy during startup.
+    pub fn install_scene_policy(&mut self, policy: LayerPolicy) {
+        self.scenes.set_policy(policy);
+    }
+
+    /// Install one persisted runtime conditional rule during startup.
+    pub fn install_runtime_conditional_scene_cell(
+        &mut self,
+        cell: RuntimeConditionalSceneCell,
+    ) -> Result<(), StandardError> {
+        Self::check_scene_slot(cell.slot)?;
+        self.runtime_conditional_scenes.push(cell)
+    }
+
+    pub const fn extension(&self) -> &Extension {
+        &self.extension
+    }
+
+    pub fn extension_mut(&mut self) -> &mut Extension {
+        &mut self.extension
+    }
+
+    pub const fn status(&self) -> &Status {
+        &self.status
+    }
+
+    pub fn status_mut(&mut self) -> &mut Status {
+        &mut self.status
+    }
+
+    fn apply_light_action(&mut self, action: LightAction) -> bool {
+        const STEP: u8 = 17;
+        let background = &mut self.background.state;
+        match action {
+            LightAction::BacklightOn => self.output_mode = OutputMode::AlwaysOn,
+            LightAction::BacklightOff => self.output_mode = OutputMode::AlwaysOff,
+            LightAction::BacklightToggle => {
+                self.output_mode = if matches!(self.output_mode, OutputMode::AlwaysOff) {
+                    OutputMode::AlwaysOn
+                } else {
+                    OutputMode::AlwaysOff
+                }
+            }
+            LightAction::OutputModeCycle => self.output_mode = self.output_mode.next(),
+            LightAction::BacklightDown => self.output_brightness = self.output_brightness.saturating_sub(STEP),
+            LightAction::BacklightUp => self.output_brightness = self.output_brightness.saturating_add(STEP),
+            LightAction::BacklightStep => self.output_brightness = self.output_brightness.wrapping_add(STEP),
+            LightAction::BacklightToggleBreathing => {
+                background.mode = match background.mode {
+                    BackgroundMode::Solid => BackgroundMode::Breathe,
+                    BackgroundMode::Breathe => BackgroundMode::Solid,
+                }
+            }
+            LightAction::RgbTog => background.enabled = !background.enabled,
+            LightAction::RgbModeForward | LightAction::RgbModeReverse => {
+                background.mode = match background.mode {
+                    BackgroundMode::Solid => BackgroundMode::Breathe,
+                    BackgroundMode::Breathe => BackgroundMode::Solid,
+                }
+            }
+            LightAction::RgbHui => background.hue = background.hue.wrapping_add(STEP),
+            LightAction::RgbHud => background.hue = background.hue.wrapping_sub(STEP),
+            LightAction::RgbSai => background.saturation = background.saturation.saturating_add(STEP),
+            LightAction::RgbSad => background.saturation = background.saturation.saturating_sub(STEP),
+            LightAction::RgbVai => background.value = background.value.saturating_add(STEP),
+            LightAction::RgbVad => background.value = background.value.saturating_sub(STEP),
+            LightAction::RgbSpi => background.speed = background.speed.saturating_add(STEP),
+            LightAction::RgbSpd => background.speed = background.speed.saturating_sub(STEP),
+            LightAction::RgbModePlain => background.mode = BackgroundMode::Solid,
+            LightAction::RgbModeBreathe => background.mode = BackgroundMode::Breathe,
+            // The standard engine advertises only Solid and Breathe. Other
+            // named modes remain available to an extension source/command.
+            _ => return false,
+        }
+        true
+    }
+
+    fn check_revision(&self, expected: u32) -> Result<(), StandardError> {
+        if expected == self.revision {
+            Ok(())
+        } else {
+            Err(StandardError::RevisionConflict {
+                expected,
+                current: self.revision,
+            })
+        }
+    }
+
+    fn advance_revision(&mut self) {
+        self.revision = self.revision.wrapping_add(1);
+    }
+
+    fn set_mutable_state(&mut self, state: StandardMutableState) {
+        self.output_mode = if state.output_enabled {
+            OutputMode::AlwaysOn
+        } else {
+            OutputMode::AlwaysOff
+        };
+        self.output_brightness = state.output_brightness;
+        self.background.set_state(state.background);
+    }
+
+    fn mutable_state(&self) -> StandardMutableState {
+        StandardMutableState {
+            output_enabled: self.effective_output(),
+            output_brightness: self.output_brightness,
+            background: self.background.state(),
+        }
+    }
+
+    fn replica_state<Context: LightingContextProvider>(
+        &self,
+        local_now_ms: u64,
+        context: &Context,
+    ) -> Result<StandardReplicaState<OVERLAY_CAP, SCENE_CAP>, StandardError> {
+        let sample_time_ms = self.animation_clock.sample_time(local_now_ms);
+        let mut overlay = OverlayBatch::new();
+        for update in self.overlay.active_updates() {
+            let ttl_ms = match update.expires_ms {
+                Some(expires_ms) if expires_ms > sample_time_ms => {
+                    let remaining = expires_ms - sample_time_ms;
+                    Some(NonZeroU32::new(remaining.min(u32::MAX as u64) as u32).unwrap())
+                }
+                Some(_) => continue,
+                None => None,
+            };
+            overlay.push(OverlayCell {
+                slot: update.slot,
+                effect: update.effect,
+                ttl_ms,
+            })?;
+        }
+        Ok(StandardReplicaState {
+            revision: self.revision,
+            mutable: self.mutable_state(),
+            output_mode: self.output_mode,
+            overlay,
+            scenes: self.scenes,
+            runtime_conditional_scenes: self.runtime_conditional_scenes,
+            context: *context.lighting_context(),
+            sample_time_ms,
+            // Filled by handle_command, where the LightingSource bound is
+            // available on the Extension parameter.
+            extension: None,
+            extension_params: None,
+        })
+    }
+
+    fn replica_overlay(
+        replica: &StandardReplicaState<OVERLAY_CAP, SCENE_CAP>,
+    ) -> Result<TtlOverlay<BuiltinEffect, OVERLAY_CAP>, StandardError> {
+        let mut updates = [OverlayUpdate {
+            slot: LedSlot(0),
+            effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+            expires_ms: None,
+        }; OVERLAY_CAP];
+        for (target, cell) in updates.iter_mut().zip(replica.overlay.as_slice().iter().copied()) {
+            *target = OverlayUpdate {
+                slot: cell.slot,
+                effect: cell.effect,
+                expires_ms: cell
+                    .ttl_ms
+                    .and_then(|ttl| replica.sample_time_ms.checked_add(ttl.get() as u64)),
+            };
+            if cell.ttl_ms.is_some() && target.expires_ms.is_none() {
+                return Err(StandardError::DeadlineOverflow);
+            }
+        }
+        let mut overlay = TtlOverlay::new();
+        overlay.replace(replica.sample_time_ms, &updates[..replica.overlay.as_slice().len()])?;
+        Ok(overlay)
+    }
+
+    fn apply_replica(
+        &mut self,
+        local_now_ms: u64,
+        replica: StandardReplicaState<OVERLAY_CAP, SCENE_CAP>,
+        overlay: TtlOverlay<BuiltinEffect, OVERLAY_CAP>,
+    ) {
+        self.overlay = overlay;
+        self.set_mutable_state(replica.mutable);
+        self.output_mode = replica.output_mode;
+        self.scenes = replica.scenes;
+        self.runtime_conditional_scenes = replica.runtime_conditional_scenes;
+        self.revision = replica.revision;
+        self.animation_clock.anchor(local_now_ms, replica.sample_time_ms);
+    }
+
+    fn expires_at(now_ms: u64, ttl_ms: Option<NonZeroU32>) -> Result<Option<u64>, StandardError> {
+        ttl_ms
+            .map(|ttl| {
+                now_ms
+                    .checked_add(ttl.get() as u64)
+                    .ok_or(StandardError::DeadlineOverflow)
+            })
+            .transpose()
+    }
+
+    fn overlay_update(now_ms: u64, cell: OverlayCell) -> Result<OverlayUpdate<BuiltinEffect>, StandardError> {
+        Ok(OverlayUpdate {
+            slot: cell.slot,
+            effect: cell.effect,
+            expires_ms: Self::expires_at(now_ms, cell.ttl_ms)?,
+        })
+    }
+
+    fn check_scene_slot(slot: LedSlot) -> Result<(), StandardError> {
+        if slot.index() < N {
+            Ok(())
+        } else {
+            Err(StandardError::SceneSlotOutOfRange { slot })
+        }
+    }
+
+    fn expire_scene_replace(&mut self, now_ms: u64) {
+        if self
+            .scene_replace
+            .as_ref()
+            .is_some_and(|replace| now_ms.saturating_sub(replace.last_activity_ms) >= SCENE_TRANSACTION_TIMEOUT_MS)
+        {
+            self.scene_expired_transaction = self.scene_replace.as_ref().map(|replace| replace.id);
+            self.scene_replace = None;
+        }
+    }
+
+    fn scene_transaction_error(&self, id: u32) -> StandardError {
+        if self.scene_expired_transaction == Some(id) {
+            StandardError::SceneTransactionExpired
+        } else {
+            StandardError::InvalidSceneTransaction
+        }
+    }
+
+    fn begin_scene_replace(
+        &mut self,
+        now_ms: u64,
+        expected_revision: u32,
+        cell_count: u16,
+    ) -> Result<u32, StandardError> {
+        self.expire_scene_replace(now_ms);
+        if self.scene_replace.is_some() {
+            return Err(StandardError::SceneTransactionBusy);
+        }
+        if cell_count as usize > SCENE_CAP {
+            return Err(StandardError::SceneFull { capacity: SCENE_CAP });
+        }
+        let id = self.scene_next_transaction;
+        self.scene_next_transaction = self.scene_next_transaction.wrapping_add(1).max(1);
+        self.scene_expired_transaction = None;
+        self.scene_replace = Some(SceneReplace {
+            id,
+            expected_revision,
+            expected_count: cell_count,
+            cells: [EMPTY_SCENE_CELL; SCENE_CAP],
+            len: 0,
+            last_activity_ms: now_ms,
+        });
+        Ok(id)
+    }
+
+    fn put_scene_chunk(
+        &mut self,
+        now_ms: u64,
+        transaction_id: u32,
+        offset: u16,
+        cells: &SceneChunk,
+    ) -> Result<(), StandardError> {
+        self.expire_scene_replace(now_ms);
+        for cell in cells.as_slice() {
+            Self::check_scene_slot(cell.slot)?;
+        }
+        let error = self.scene_transaction_error(transaction_id);
+        let replace = self
+            .scene_replace
+            .as_mut()
+            .filter(|replace| replace.id == transaction_id)
+            .ok_or(error)?;
+        if offset as usize != replace.len || replace.len + cells.as_slice().len() > replace.expected_count as usize {
+            return Err(StandardError::InvalidSceneRequest);
+        }
+        for cell in cells.as_slice() {
+            if replace.cells[..replace.len]
+                .iter()
+                .any(|staged| staged.layer == cell.layer && staged.slot == cell.slot)
+            {
+                return Err(StandardError::InvalidSceneRequest);
+            }
+            replace.cells[replace.len] = *cell;
+            replace.len += 1;
+        }
+        replace.last_activity_ms = now_ms;
+        Ok(())
+    }
+
+    /// Atomically publish a complete staged replacement. A repeated commit of
+    /// the transaction most recently committed answers idempotently with
+    /// `changed == false` so a retried commit over a lossy link converges.
+    fn commit_scene_replace(&mut self, now_ms: u64, transaction_id: u32) -> Result<bool, StandardError> {
+        self.expire_scene_replace(now_ms);
+        if self.scene_committed_transaction == Some(transaction_id) && self.scene_replace.is_none() {
+            return Ok(false);
+        }
+        let error = self.scene_transaction_error(transaction_id);
+        let replace = self
+            .scene_replace
+            .as_ref()
+            .filter(|replace| replace.id == transaction_id)
+            .ok_or(error)?;
+        if replace.len != replace.expected_count as usize {
+            return Err(StandardError::SceneTransactionIncomplete {
+                expected: replace.expected_count,
+                received: replace.len as u16,
+            });
+        }
+        self.check_revision(replace.expected_revision)?;
+        let replace = self.scene_replace.take().expect("checked above");
+        self.scenes.clear();
+        for cell in &replace.cells[..replace.len] {
+            self.scenes.set(*cell).expect("staged length is table-bounded");
+        }
+        self.scene_committed_transaction = Some(transaction_id);
+        self.scene_expired_transaction = None;
+        Ok(true)
+    }
+
+    fn abort_scene_replace(&mut self, now_ms: u64, transaction_id: u32) -> Result<(), StandardError> {
+        self.expire_scene_replace(now_ms);
+        if self
+            .scene_replace
+            .as_ref()
+            .is_some_and(|replace| replace.id == transaction_id)
+        {
+            self.scene_replace = None;
+            return Ok(());
+        }
+        Err(self.scene_transaction_error(transaction_id))
+    }
+
+    fn expire_runtime_conditional_scene_replace(&mut self, now_ms: u64) {
+        if self
+            .runtime_conditional_scene_replace
+            .as_ref()
+            .is_some_and(|replace| now_ms.saturating_sub(replace.last_activity_ms) >= SCENE_TRANSACTION_TIMEOUT_MS)
+        {
+            self.runtime_conditional_scene_expired_transaction = self
+                .runtime_conditional_scene_replace
+                .as_ref()
+                .map(|replace| replace.id);
+            self.runtime_conditional_scene_replace = None;
+        }
+    }
+
+    fn runtime_conditional_scene_transaction_error(&self, id: u32) -> StandardError {
+        if self.runtime_conditional_scene_expired_transaction == Some(id) {
+            StandardError::ConditionalSceneTransactionExpired
+        } else {
+            StandardError::InvalidConditionalSceneTransaction
+        }
+    }
+
+    fn begin_runtime_conditional_scene_replace(
+        &mut self,
+        now_ms: u64,
+        expected_revision: u32,
+        cell_count: u16,
+    ) -> Result<u32, StandardError> {
+        self.expire_runtime_conditional_scene_replace(now_ms);
+        if self.runtime_conditional_scene_replace.is_some() {
+            return Err(StandardError::ConditionalSceneTransactionBusy);
+        }
+        if cell_count as usize > SCENE_CAP {
+            return Err(StandardError::ConditionalSceneFull { capacity: SCENE_CAP });
+        }
+        let id = self.runtime_conditional_scene_next_transaction;
+        self.runtime_conditional_scene_next_transaction =
+            self.runtime_conditional_scene_next_transaction.wrapping_add(1).max(1);
+        self.runtime_conditional_scene_expired_transaction = None;
+        self.runtime_conditional_scene_replace = Some(RuntimeConditionalSceneReplace {
+            id,
+            expected_revision,
+            expected_count: cell_count,
+            cells: [EMPTY_CONDITIONAL_SCENE_CELL; SCENE_CAP],
+            len: 0,
+            last_activity_ms: now_ms,
+        });
+        Ok(id)
+    }
+
+    fn put_runtime_conditional_scene_chunk(
+        &mut self,
+        now_ms: u64,
+        transaction_id: u32,
+        offset: u16,
+        cells: &RuntimeConditionalSceneChunk,
+    ) -> Result<(), StandardError> {
+        self.expire_runtime_conditional_scene_replace(now_ms);
+        for cell in cells.as_slice() {
+            Self::check_scene_slot(cell.slot)?;
+        }
+        let error = self.runtime_conditional_scene_transaction_error(transaction_id);
+        let replace = self
+            .runtime_conditional_scene_replace
+            .as_mut()
+            .filter(|replace| replace.id == transaction_id)
+            .ok_or(error)?;
+        if offset as usize != replace.len || replace.len + cells.as_slice().len() > replace.expected_count as usize {
+            return Err(StandardError::InvalidConditionalSceneRequest);
+        }
+        for cell in cells.as_slice() {
+            replace.cells[replace.len] = *cell;
+            replace.len += 1;
+        }
+        replace.last_activity_ms = now_ms;
+        Ok(())
+    }
+
+    fn commit_runtime_conditional_scene_replace(
+        &mut self,
+        now_ms: u64,
+        transaction_id: u32,
+    ) -> Result<bool, StandardError> {
+        self.expire_runtime_conditional_scene_replace(now_ms);
+        if self.runtime_conditional_scene_committed_transaction == Some(transaction_id)
+            && self.runtime_conditional_scene_replace.is_none()
+        {
+            return Ok(false);
+        }
+        let error = self.runtime_conditional_scene_transaction_error(transaction_id);
+        let replace = self
+            .runtime_conditional_scene_replace
+            .as_ref()
+            .filter(|replace| replace.id == transaction_id)
+            .ok_or(error)?;
+        if replace.len != replace.expected_count as usize {
+            return Err(StandardError::ConditionalSceneTransactionIncomplete {
+                expected: replace.expected_count,
+                received: replace.len as u16,
+            });
+        }
+        self.check_revision(replace.expected_revision)?;
+        let replace = self.runtime_conditional_scene_replace.take().expect("checked above");
+        self.runtime_conditional_scenes.clear();
+        for cell in &replace.cells[..replace.len] {
+            self.runtime_conditional_scenes
+                .push(*cell)
+                .expect("staged length is table-bounded");
+        }
+        self.runtime_conditional_scene_committed_transaction = Some(transaction_id);
+        self.runtime_conditional_scene_expired_transaction = None;
+        Ok(true)
+    }
+
+    fn abort_runtime_conditional_scene_replace(
+        &mut self,
+        now_ms: u64,
+        transaction_id: u32,
+    ) -> Result<(), StandardError> {
+        self.expire_runtime_conditional_scene_replace(now_ms);
+        if self
+            .runtime_conditional_scene_replace
+            .as_ref()
+            .is_some_and(|replace| replace.id == transaction_id)
+        {
+            self.runtime_conditional_scene_replace = None;
+            return Ok(());
+        }
+        Err(self.runtime_conditional_scene_transaction_error(transaction_id))
+    }
+}
+
+impl<'scenes, Context, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const SCENE_CAP: usize>
+    LightingEngine<Context> for StandardLightingEngine<'scenes, Extension, Status, N, OVERLAY_CAP, SCENE_CAP>
+where
+    Context: LightingContextProvider,
+    Extension: LightingSource<Rgb8, Context>,
+    Status: LightingSource<Rgb8, Context>,
+{
+    type Frame = LogicalFrame<Rgb8, N>;
+    type Input = StandardInput;
+    type Command = StandardCommand<OVERLAY_CAP, SCENE_CAP>;
+    type Reply = StandardReply;
+    type Error = StandardError;
+
+    fn on_input(&mut self, input: Self::Input, _snapshot: &Context) -> Result<Invalidation, Self::Error> {
+        if self.extension.handle_light_action(input.0) || self.apply_light_action(input.0) {
+            self.advance_revision();
+            Ok(Invalidation::Render)
+        } else {
+            Ok(Invalidation::None)
+        }
+    }
+
+    fn handle_command(
+        &mut self,
+        now_ms: u64,
+        command: Self::Command,
+        snapshot: &Context,
+    ) -> Result<CommandResult<Self::Reply>, Self::Error> {
+        let effect_now_ms = self.animation_clock.sample_time(now_ms);
+        // Scene reads and transaction bookkeeping have non-state replies or
+        // bespoke revision behavior; everything else falls through to the
+        // uniform state-readback path below.
+        match command {
+            StandardCommand::ReadOverlay { offset } => {
+                let old_len = self.overlay.active_len();
+                self.overlay.prune_expired(effect_now_ms);
+                let expired = self.overlay.active_len() != old_len;
+                if expired {
+                    self.advance_revision();
+                }
+                let start = (offset as usize).min(self.overlay.active_len());
+                let mut cells = OverlayBatch::new();
+                for update in self.overlay.active_updates().skip(start).take(OVERLAY_CHUNK_SIZE) {
+                    let ttl_ms = update.expires_ms.map(|expires_ms| {
+                        let remaining = expires_ms.saturating_sub(effect_now_ms).min(u32::MAX as u64) as u32;
+                        NonZeroU32::new(remaining).expect("expired overlays were pruned")
+                    });
+                    cells
+                        .push(OverlayCell {
+                            slot: update.slot,
+                            effect: update.effect,
+                            ttl_ms,
+                        })
+                        .expect("overlay page is chunk-bounded");
+                }
+                return Ok(CommandResult::new(
+                    StandardReply::OverlayPage(OverlayPage {
+                        revision: self.revision,
+                        total: self.overlay.active_len().min(u16::MAX as usize) as u16,
+                        cells,
+                    }),
+                    if expired {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                ));
+            }
+            StandardCommand::ReadScenes { offset } => {
+                return Ok(CommandResult::unchanged(StandardReply::ScenesPage(ScenePage {
+                    revision: self.revision,
+                    total: self.scenes.len().min(u16::MAX as usize) as u16,
+                    cells: self.scenes.page(offset),
+                })));
+            }
+            StandardCommand::ReadCompiledScenes { offset } => {
+                let mut cells = SceneChunk::new();
+                for (layer, cell) in self.layers.cells().skip(offset as usize).take(SCENE_CHUNK_SIZE) {
+                    cells
+                        .push(SceneTableCell {
+                            layer,
+                            slot: cell.slot,
+                            effect: cell.effect,
+                        })
+                        .expect("compiled scene page is chunk-bounded");
+                }
+                return Ok(CommandResult::unchanged(StandardReply::CompiledScenesPage(
+                    CompiledScenePage {
+                        total: self.layers.cell_count().min(u16::MAX as usize) as u16,
+                        policy: self.layers.policy,
+                        cells,
+                    },
+                )));
+            }
+            StandardCommand::ReadRuntimeConditionalScenes { offset } => {
+                return Ok(CommandResult::unchanged(StandardReply::RuntimeConditionalScenesPage(
+                    RuntimeConditionalScenePage {
+                        revision: self.revision,
+                        total: self.runtime_conditional_scenes.len().min(u16::MAX as usize) as u16,
+                        cells: self.runtime_conditional_scenes.page(offset),
+                    },
+                )));
+            }
+            StandardCommand::BeginSceneReplace {
+                expected_revision,
+                cell_count,
+            } => {
+                let id = self.begin_scene_replace(now_ms, expected_revision, cell_count)?;
+                return Ok(CommandResult::unchanged(StandardReply::SceneTransaction {
+                    id,
+                    cell_count,
+                }));
+            }
+            StandardCommand::PutSceneChunk {
+                transaction_id,
+                offset,
+                cells,
+            } => {
+                self.put_scene_chunk(now_ms, transaction_id, offset, &cells)?;
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
+            StandardCommand::CommitSceneReplace { transaction_id } => {
+                // A repeated commit of the last committed transaction is
+                // answered idempotently without advancing the revision.
+                let committed = self.commit_scene_replace(now_ms, transaction_id)?;
+                if committed {
+                    self.advance_revision();
+                    return Ok(CommandResult::new(
+                        StandardReply::State(self.state()),
+                        Invalidation::Render,
+                    ));
+                }
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
+            StandardCommand::AbortSceneReplace { transaction_id } => {
+                self.abort_scene_replace(now_ms, transaction_id)?;
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
+            StandardCommand::BeginRuntimeConditionalSceneReplace {
+                expected_revision,
+                cell_count,
+            } => {
+                let id = self.begin_runtime_conditional_scene_replace(now_ms, expected_revision, cell_count)?;
+                return Ok(CommandResult::unchanged(
+                    StandardReply::RuntimeConditionalSceneTransaction { id, cell_count },
+                ));
+            }
+            StandardCommand::PutRuntimeConditionalSceneChunk {
+                transaction_id,
+                offset,
+                cells,
+            } => {
+                self.put_runtime_conditional_scene_chunk(now_ms, transaction_id, offset, &cells)?;
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
+            StandardCommand::CommitRuntimeConditionalSceneReplace { transaction_id } => {
+                let committed = self.commit_runtime_conditional_scene_replace(now_ms, transaction_id)?;
+                if committed {
+                    self.advance_revision();
+                    return Ok(CommandResult::new(
+                        StandardReply::State(self.state()),
+                        Invalidation::Render,
+                    ));
+                }
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
+            StandardCommand::AbortRuntimeConditionalSceneReplace { transaction_id } => {
+                self.abort_runtime_conditional_scene_replace(now_ms, transaction_id)?;
+                return Ok(CommandResult::unchanged(StandardReply::State(self.state())));
+            }
+            _ => {}
+        }
+
+        let (mut invalidation, advances_revision) = match command {
+            StandardCommand::SetOutputEnabled(enabled) => {
+                self.output_mode = if enabled {
+                    OutputMode::AlwaysOn
+                } else {
+                    OutputMode::AlwaysOff
+                };
+                (Invalidation::Render, true)
+            }
+            StandardCommand::SetOutputModeIfRevision {
+                expected_revision,
+                mode,
+            } => {
+                self.check_revision(expected_revision)?;
+                self.output_mode = mode;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::SetOutputBrightness(level) => {
+                self.output_brightness = level;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::SetBackground(state) => {
+                self.background.set_state(state);
+                (Invalidation::Render, true)
+            }
+            StandardCommand::PatchBackground(patch) => {
+                patch.apply_to(&mut self.background.state);
+                (Invalidation::Render, true)
+            }
+            StandardCommand::SetStateIfRevision {
+                expected_revision,
+                state,
+            } => {
+                self.check_revision(expected_revision)?;
+                self.set_mutable_state(state);
+                (Invalidation::Render, true)
+            }
+            StandardCommand::SetOverlay(cell) => {
+                let update = Self::overlay_update(effect_now_ms, cell)?;
+                self.overlay.set(effect_now_ms, update)?;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::SetOverlayIfRevision {
+                expected_revision,
+                cell,
+            } => {
+                self.check_revision(expected_revision)?;
+                let update = Self::overlay_update(effect_now_ms, cell)?;
+                self.overlay.set(effect_now_ms, update)?;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::UnsetOverlay(slot) => {
+                let changed = self.overlay.unset(slot);
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
+            StandardCommand::UnsetOverlayIfRevision {
+                expected_revision,
+                slot,
+            } => {
+                self.check_revision(expected_revision)?;
+                let changed = self.overlay.unset(slot);
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
+            StandardCommand::ClearOverlay => {
+                let changed = self.overlay.active_len() != 0;
+                self.overlay.clear();
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
+            StandardCommand::ClearOverlayIfRevision { expected_revision } => {
+                self.check_revision(expected_revision)?;
+                let changed = self.overlay.active_len() != 0;
+                self.overlay.clear();
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
+            StandardCommand::ReplaceOverlay(batch) => {
+                let mut updates = [OverlayUpdate {
+                    slot: LedSlot(0),
+                    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+                    expires_ms: None,
+                }; OVERLAY_CAP];
+                for (target, cell) in updates.iter_mut().zip(batch.as_slice().iter().copied()) {
+                    *target = Self::overlay_update(effect_now_ms, cell)?;
+                }
+                self.overlay
+                    .replace(effect_now_ms, &updates[..batch.as_slice().len()])?;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::ReplaceOverlayIfRevision {
+                expected_revision,
+                batch,
+            } => {
+                self.check_revision(expected_revision)?;
+                let mut updates = [OverlayUpdate {
+                    slot: LedSlot(0),
+                    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+                    expires_ms: None,
+                }; OVERLAY_CAP];
+                for (target, cell) in updates.iter_mut().zip(batch.as_slice().iter().copied()) {
+                    *target = Self::overlay_update(effect_now_ms, cell)?;
+                }
+                self.overlay
+                    .replace(effect_now_ms, &updates[..batch.as_slice().len()])?;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::ExportReplica(slot) => {
+                let mut replica = self.replica_state(now_ms, snapshot)?;
+                replica.extension = self.extension.extension_state();
+                replica.extension_params = replica.extension.and_then(|state| {
+                    // A source with no descriptor, an active effect the
+                    // descriptor does not know, or an effect without
+                    // parameters all export nothing to replicate.
+                    let specs = extension_param_specs::<Rgb8, Context, _>(&self.extension, state.effect).ok()?;
+                    let len = specs.len().min(EXTENSION_PARAM_CHUNK);
+                    if len == 0 {
+                        return None;
+                    }
+                    let mut values = [0u8; EXTENSION_PARAM_CHUNK];
+                    for (value, (index, spec)) in values.iter_mut().zip(specs[..len].iter().enumerate()) {
+                        *value = self
+                            .extension
+                            .extension_param(state.effect, index as u8)
+                            .unwrap_or(spec.default);
+                    }
+                    Some(ExtensionReplicaParams {
+                        effect: state.effect,
+                        len: len as u8,
+                        values,
+                    })
+                });
+                slot.put(replica)?;
+                (Invalidation::None, false)
+            }
+            StandardCommand::ApplyReplica(slot) => {
+                let replica = slot.take()?;
+                let overlay = Self::replica_overlay(&replica)?;
+                // Parameter addresses and ranges are checked against the
+                // static descriptor before anything is applied, so a
+                // malformed snapshot cannot leave the selection updated and
+                // the tuning behind -- the same guarantee the overlay gets.
+                if let Some(params) = replica.extension_params {
+                    for (index, value) in params.values().iter().copied().enumerate() {
+                        check_extension_param::<Rgb8, Context, _>(&self.extension, params.effect, index as u8, value)?;
+                    }
+                }
+                match (replica.extension, self.extension.extension_state()) {
+                    (None, None) => {}
+                    (Some(extension), Some(_)) if self.extension.apply_extension_state(extension) => {}
+                    _ => return Err(StandardError::ExtensionUnsupported),
+                }
+                // Parameters follow the selection so the addressed effect is
+                // already active. Values go through the same validated path a
+                // host set uses; only the revision pin is skipped, matching
+                // how replica extension state is applied.
+                if let Some(params) = replica.extension_params {
+                    for (index, value) in params.values().iter().copied().enumerate() {
+                        apply_extension_param_checked::<Rgb8, Context, _>(
+                            &mut self.extension,
+                            params.effect,
+                            index as u8,
+                            value,
+                        )?;
+                    }
+                }
+                self.apply_replica(now_ms, replica, overlay);
+                (Invalidation::Render, false)
+            }
+            StandardCommand::SetSceneCellIfRevision {
+                expected_revision,
+                cell,
+            } => {
+                self.check_revision(expected_revision)?;
+                Self::check_scene_slot(cell.slot)?;
+                self.scenes.set(cell)?;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::UnsetSceneCellIfRevision {
+                expected_revision,
+                layer,
+                slot,
+            } => {
+                self.check_revision(expected_revision)?;
+                let changed = self.scenes.unset(layer, slot);
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
+            StandardCommand::SetLayerPolicyIfRevision {
+                expected_revision,
+                policy,
+            } => {
+                self.check_revision(expected_revision)?;
+                let changed = self.scenes.set_policy(policy);
+                (
+                    if changed {
+                        Invalidation::Render
+                    } else {
+                        Invalidation::None
+                    },
+                    true,
+                )
+            }
+            StandardCommand::ReadExtension => {
+                return Ok(CommandResult::unchanged(StandardReply::Extension(ExtensionPage {
+                    revision: self.revision,
+                    descriptor: self.extension.extension_descriptor(),
+                    state: self.extension.extension_state(),
+                })));
+            }
+            StandardCommand::SetExtensionIfRevision {
+                expected_revision,
+                state,
+            } => {
+                self.check_revision(expected_revision)?;
+                if !self.extension.apply_extension_state(state) {
+                    return Err(StandardError::ExtensionUnsupported);
+                }
+                (Invalidation::Render, true)
+            }
+            StandardCommand::ReadExtensionParams { effect, offset } => {
+                let specs = extension_param_specs::<Rgb8, Context, _>(&self.extension, effect)?;
+                let start = (offset as usize).min(specs.len());
+                let end = (start + EXTENSION_PARAM_CHUNK).min(specs.len());
+                let mut items = [None; EXTENSION_PARAM_CHUNK];
+                for (item, (index, spec)) in items.iter_mut().zip((start..end).zip(&specs[start..end])) {
+                    let value = self
+                        .extension
+                        .extension_param(effect, index as u8)
+                        .unwrap_or(spec.default);
+                    *item = Some(ExtensionParamValue { spec: *spec, value });
+                }
+                return Ok(CommandResult::unchanged(StandardReply::ExtensionParams(
+                    ExtensionParamsPage {
+                        revision: self.revision,
+                        // The wire caps one effect's parameter list at 255.
+                        total: specs.len().min(u8::MAX as usize) as u8,
+                        items,
+                    },
+                )));
+            }
+            StandardCommand::SetExtensionParamIfRevision {
+                expected_revision,
+                effect,
+                index,
+                value,
+            } => {
+                self.check_revision(expected_revision)?;
+                apply_extension_param_checked::<Rgb8, Context, _>(&mut self.extension, effect, index, value)?;
+                (Invalidation::Render, true)
+            }
+            StandardCommand::ReadState => (Invalidation::None, false),
+            StandardCommand::ReadOverlay { .. }
+            | StandardCommand::ReadScenes { .. }
+            | StandardCommand::ReadCompiledScenes { .. }
+            | StandardCommand::ReadRuntimeConditionalScenes { .. }
+            | StandardCommand::BeginSceneReplace { .. }
+            | StandardCommand::PutSceneChunk { .. }
+            | StandardCommand::CommitSceneReplace { .. }
+            | StandardCommand::AbortSceneReplace { .. } => unreachable!("handled above"),
+            StandardCommand::BeginRuntimeConditionalSceneReplace { .. }
+            | StandardCommand::PutRuntimeConditionalSceneChunk { .. }
+            | StandardCommand::CommitRuntimeConditionalSceneReplace { .. }
+            | StandardCommand::AbortRuntimeConditionalSceneReplace { .. } => unreachable!("handled above"),
+        };
+        if advances_revision {
+            self.advance_revision();
+            if invalidation == Invalidation::None {
+                invalidation = Invalidation::StateChanged;
+            }
+        }
+        Ok(CommandResult::new(StandardReply::State(self.state()), invalidation))
+    }
+
+    fn render(
+        &mut self,
+        input: RenderInput<'_, Context>,
+        frame: &mut Self::Frame,
+    ) -> Result<RenderOutcome, Self::Error> {
+        let effect_now_ms = self.animation_clock.sample_time(input.now_ms);
+        let overlay_len = self.overlay.active_len();
+        self.overlay.prune_expired(effect_now_ms);
+        let mut state_changed = self.overlay.active_len() != overlay_len;
+        if state_changed {
+            self.advance_revision();
+        }
+        let context = input.snapshot.lighting_context();
+        let powered = context.powered;
+        let wake_active = self
+            .controls
+            .wake_layer
+            .is_some_and(|layer| context.layers.is_active(layer));
+        let effective_output_enabled = wake_active
+            || matches!(self.output_mode, OutputMode::AlwaysOn)
+            || matches!(self.output_mode, OutputMode::PoweredOnly) && powered;
+        if self.powered != powered
+            || self.wake_active != wake_active
+            || self.effective_output_enabled != effective_output_enabled
+        {
+            self.powered = powered;
+            self.wake_active = wake_active;
+            self.effective_output_enabled = effective_output_enabled;
+            state_changed = true;
+        }
+        let indicator_cell = self.controls.output_mode_indicator.map(|indicator| SceneCell {
+            slot: indicator.slot,
+            effect: indicator.effect(self.output_mode),
+        });
+        let Self {
+            compositor,
+            background,
+            extension,
+            layers,
+            scenes,
+            runtime_conditional_scenes,
+            battery_status,
+            overlay,
+            status,
+            animation_clock: _,
+            controls: _,
+            output_mode: _,
+            powered: _,
+            wake_active: _,
+            effective_output_enabled,
+            output_brightness,
+            scene_replace: _,
+            scene_next_transaction: _,
+            scene_expired_transaction: _,
+            scene_committed_transaction: _,
+            runtime_conditional_scene_replace: _,
+            runtime_conditional_scene_next_transaction: _,
+            runtime_conditional_scene_expired_transaction: _,
+            runtime_conditional_scene_committed_transaction: _,
+            revision: _,
+        } = self;
+        let mut transaction = compositor.begin(effect_now_ms, input.snapshot, Rgb8::BLACK, frame);
+        transaction.apply(priority::BACKGROUND, background)?;
+        transaction.apply(priority::EXTENSION, extension)?;
+        transaction.apply(priority::LAYER, layers)?;
+        // Same band, later call: runtime cells override static defaults.
+        transaction.apply(priority::LAYER, scenes)?;
+        transaction.apply(priority::HOST_OVERLAY, overlay)?;
+        transaction.apply(priority::STATUS, status)?;
+        // Status band, after the compiled rules: a runtime conditional cell is
+        // the host's replacement for a compiled one, so it must reach the same
+        // altitude and win on the slots the two share.
+        let mut runtime_conditional_source = RuntimeConditionalSource {
+            table: runtime_conditional_scenes,
+            batteries: *battery_status,
+        };
+        transaction.apply(priority::STATUS, &mut runtime_conditional_source)?;
+        if wake_active && let Some(indicator_cell) = indicator_cell.as_ref() {
+            let mut indicator = SparseScene {
+                cells: core::slice::from_ref(indicator_cell),
+            };
+            transaction.apply(priority::STATUS, &mut indicator)?;
+        }
+        let mut transform = BrightnessTransform::new(if *effective_output_enabled {
+            *output_brightness
+        } else {
+            0
+        });
+        let result = transaction.finish_with(&mut transform);
+        let next_wake_in_ms = result.next_wake_ms.map(|deadline| {
+            let delay = deadline.saturating_sub(effect_now_ms).clamp(1, u32::MAX as u64);
+            NonZeroU32::new(delay as u32).expect("clamped delay is nonzero")
+        });
+        Ok(RenderOutcome {
+            changed: result.changed,
+            state_changed,
+            next_wake_in_ms,
+        })
+    }
+
+    fn on_presented(&mut self, frame: &Self::Frame) {
+        self.compositor.commit(frame);
+    }
+}
+
+pub(super) fn hsv(hue: u8, saturation: u8, value: u8) -> Rgb8 {
+    if saturation == 0 {
+        return Rgb8::new(value, value, value);
+    }
+    let region = hue / 43;
+    let remainder = (hue - region * 43) as u16 * 6;
+    let p = (value as u16 * (255 - saturation as u16) / 255) as u8;
+    let q = (value as u16 * (255 - (saturation as u16 * remainder / 255)) / 255) as u8;
+    let t = (value as u16 * (255 - (saturation as u16 * (255 - remainder) / 255)) / 255) as u8;
+    match region {
+        0 => Rgb8::new(value, t, p),
+        1 => Rgb8::new(q, value, p),
+        2 => Rgb8::new(p, value, t),
+        3 => Rgb8::new(p, q, value),
+        4 => Rgb8::new(t, p, value),
+        _ => Rgb8::new(value, p, q),
+    }
+}
diff --git a/rmk/src/lighting/standard/mod.rs b/rmk/src/lighting/standard/mod.rs
new file mode 100644
index 000000000..261093425
--- /dev/null
+++ b/rmk/src/lighting/standard/mod.rs
@@ -0,0 +1,45 @@
+//! Ready-to-use compositor engine for ordinary RMK lighting.
+//!
+//! Boards provide static layer scenes plus optional extension and status
+//! sources. The engine supplies a controllable uniform background, TTL host
+//! overlay, deterministic priority bands, output brightness, frame history,
+//! `LightAction` handling, and protocol-independent commands/readback.
+
+/// Cells per overlay readback page. Kept equal to the wire chunk size so
+/// protocol adapters can forward pages without re-batching.
+pub const OVERLAY_CHUNK_SIZE: usize = 8;
+
+/// Cells per scene page/replacement chunk. Kept equal to the wire chunk size
+/// so protocol adapters can forward chunks without re-batching.
+pub const SCENE_CHUNK_SIZE: usize = 8;
+
+/// Cells per runtime conditional-scene page/replacement chunk.
+pub const CONDITIONAL_SCENE_CHUNK_SIZE: usize = 8;
+
+/// A staged scene replacement expires after this much command inactivity.
+pub const SCENE_TRANSACTION_TIMEOUT_MS: u64 = 5_000;
+
+/// Stable default priority bands. Equal-priority call order remains stable.
+pub mod priority {
+    pub const BACKGROUND: u8 = 0;
+    pub const EXTENSION: u8 = 32;
+    pub const LAYER: u8 = 64;
+    pub const HOST_OVERLAY: u8 = 128;
+    pub const STATUS: u8 = 192;
+}
+
+mod background;
+mod command;
+mod conditional;
+mod engine;
+mod overlay;
+mod scenes;
+#[cfg(test)]
+mod tests;
+
+pub use background::*;
+pub use command::*;
+pub use conditional::*;
+pub use engine::*;
+pub use overlay::*;
+pub use scenes::*;
diff --git a/rmk/src/lighting/standard/overlay.rs b/rmk/src/lighting/standard/overlay.rs
new file mode 100644
index 000000000..1db695422
--- /dev/null
+++ b/rmk/src/lighting/standard/overlay.rs
@@ -0,0 +1,61 @@
+use core::num::NonZeroU32;
+
+#[allow(unused_imports)]
+use super::*;
+use crate::lighting::Rgb8;
+use crate::lighting::effect::BuiltinEffect;
+use crate::lighting::source::OverlayError;
+use crate::lighting::topology::LedSlot;
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct OverlayCell {
+    pub slot: LedSlot,
+    pub effect: BuiltinEffect,
+    /// Relative lifetime from command application. `None` persists until an
+    /// explicit unset/clear or reboot.
+    pub ttl_ms: Option<NonZeroU32>,
+}
+
+const EMPTY_OVERLAY_CELL: OverlayCell = OverlayCell {
+    slot: LedSlot(0),
+    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+    ttl_ms: None,
+};
+
+/// Fixed-capacity, owned batch suitable for a bounded async mailbox.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct OverlayBatch<const CAP: usize> {
+    cells: [OverlayCell; CAP],
+    len: usize,
+}
+
+impl<const CAP: usize> OverlayBatch<CAP> {
+    pub const fn new() -> Self {
+        Self {
+            cells: [EMPTY_OVERLAY_CELL; CAP],
+            len: 0,
+        }
+    }
+
+    pub fn push(&mut self, cell: OverlayCell) -> Result<(), OverlayError> {
+        if self.len == CAP {
+            return Err(OverlayError::TooManyEntries {
+                supplied: self.len + 1,
+                capacity: CAP,
+            });
+        }
+        self.cells[self.len] = cell;
+        self.len += 1;
+        Ok(())
+    }
+
+    pub fn as_slice(&self) -> &[OverlayCell] {
+        &self.cells[..self.len]
+    }
+}
+
+impl<const CAP: usize> Default for OverlayBatch<CAP> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
diff --git a/rmk/src/lighting/standard/scenes.rs b/rmk/src/lighting/standard/scenes.rs
new file mode 100644
index 000000000..7fd574d2a
--- /dev/null
+++ b/rmk/src/lighting/standard/scenes.rs
@@ -0,0 +1,378 @@
+#[allow(unused_imports)]
+use super::*;
+use crate::lighting::Rgb8;
+use crate::lighting::compositor::{Contribution, LightingSource, RenderInput as SourceRenderInput};
+use crate::lighting::context::{LightingContext, LightingContextProvider};
+use crate::lighting::effect::{BuiltinEffect, LightingEffect};
+use crate::lighting::source::LayerPolicy;
+use crate::lighting::topology::LedSlot;
+
+/// One durable scene cell: an effect bound to a local slot on one layer.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct SceneTableCell {
+    pub layer: u8,
+    pub slot: LedSlot,
+    pub effect: BuiltinEffect,
+}
+
+pub(super) const EMPTY_SCENE_CELL: SceneTableCell = SceneTableCell {
+    layer: 0,
+    slot: LedSlot(0),
+    effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
+};
+
+/// Fixed-capacity, owned scene chunk suitable for a bounded async mailbox.
+/// One chunk is both a page of readback and a replacement-staging step.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct SceneChunk {
+    cells: [SceneTableCell; SCENE_CHUNK_SIZE],
+    len: usize,
+}
+
+impl Default for SceneChunk {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl SceneChunk {
+    pub const fn new() -> Self {
+        Self {
+            cells: [EMPTY_SCENE_CELL; SCENE_CHUNK_SIZE],
+            len: 0,
+        }
+    }
+
+    pub fn push(&mut self, cell: SceneTableCell) -> Result<(), StandardError> {
+        if self.len == SCENE_CHUNK_SIZE {
+            return Err(StandardError::InvalidSceneRequest);
+        }
+        self.cells[self.len] = cell;
+        self.len += 1;
+        Ok(())
+    }
+
+    pub fn as_slice(&self) -> &[SceneTableCell] {
+        &self.cells[..self.len]
+    }
+}
+
+/// Distinct effects one [`StylePool`] can hold at once.
+///
+/// This is the only capacity interning adds, and it is a far looser bound than
+/// a per-cell one: a keyboard paints many keys from a small set of colours, so
+/// a config with hundreds of painted keys typically names a handful of effects.
+pub const SCENE_STYLE_CAP: usize = 64;
+
+/// Effects held once and referenced by index, so a scene cell can carry one
+/// byte instead of a whole effect.
+///
+/// An inline [`BuiltinEffect`] is 16 bytes because blink and breathe each carry
+/// two millisecond timers, so a solid colour pays for animation fields it never
+/// uses and a cell costs 20 bytes. Interning moves the effect here and leaves
+/// the cell at 4, which matters more than it looks: the same capacity sizes the
+/// live tables, the replace staging buffer, the replica snapshot and the queued
+/// mailbox commands, so every byte saved per cell is saved several times over.
+///
+/// Freeing needs no reference counts. When a reference drops or is overwritten
+/// the caller reports it, the table is scanned for any remaining use, and the
+/// entry is freed if there is none -- cheaper to run on a host-driven operation
+/// than a set of counters is to keep correct. Occupancy is a bitmask, so a
+/// freed entry leaves a hole the next allocation reuses and entries never move,
+/// which means no cell's index ever needs rewriting.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct StylePool {
+    styles: [BuiltinEffect; SCENE_STYLE_CAP],
+    used: u64,
+}
+
+impl Default for StylePool {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl StylePool {
+    pub const fn new() -> Self {
+        Self {
+            styles: [BuiltinEffect::Solid { color: Rgb8::BLACK }; SCENE_STYLE_CAP],
+            used: 0,
+        }
+    }
+
+    /// Distinct effects currently held. Bounded by [`SCENE_STYLE_CAP`].
+    pub const fn len(&self) -> usize {
+        self.used.count_ones() as usize
+    }
+
+    pub const fn is_empty(&self) -> bool {
+        self.used == 0
+    }
+
+    /// Index for `effect`, reusing an entry when it is already held. `None`
+    /// only when a *new* effect would overflow, and then nothing is mutated.
+    pub fn intern(&mut self, effect: BuiltinEffect) -> Option<u8> {
+        if let Some(held) = self.find(effect) {
+            return Some(held);
+        }
+        let free = (0..SCENE_STYLE_CAP).find(|&index| !self.holds(index))?;
+        self.styles[free] = effect;
+        self.used |= 1 << free;
+        Some(free as u8)
+    }
+
+    pub fn get(&self, style: u8) -> Option<BuiltinEffect> {
+        let index = style as usize;
+        (index < SCENE_STYLE_CAP && self.holds(index)).then(|| self.styles[index])
+    }
+
+    /// Free `style` unless it is still referenced. The caller does the check,
+    /// so the pool's borrow stays independent of whatever holds the references.
+    pub fn release(&mut self, style: u8, still_referenced: bool) {
+        if (style as usize) < SCENE_STYLE_CAP && !still_referenced {
+            self.used &= !(1 << style as usize);
+        }
+    }
+
+    pub fn clear(&mut self) {
+        self.used = 0;
+    }
+
+    fn find(&self, effect: BuiltinEffect) -> Option<u8> {
+        (0..SCENE_STYLE_CAP)
+            .find(|&index| self.holds(index) && self.styles[index] == effect)
+            .map(|index| index as u8)
+    }
+
+    const fn holds(&self, index: usize) -> bool {
+        self.used & (1 << index) != 0
+    }
+}
+
+/// A scene cell as stored: the effect lives in the table's [`StylePool`].
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+struct InternedSceneCell {
+    layer: u8,
+    slot: LedSlot,
+    style: u8,
+}
+
+const EMPTY_INTERNED_CELL: InternedSceneCell = InternedSceneCell {
+    layer: 0,
+    slot: LedSlot(0),
+    style: 0,
+};
+
+/// Fixed-capacity runtime scene table with layer-aware composition.
+///
+/// Cells are unique per `(layer, slot)` and stored in insertion order; order
+/// is irrelevant to rendering because layer precedence comes from the policy
+/// and same-layer cells can never target the same slot.
+#[derive(Copy, Clone, Debug)]
+pub struct SceneTable<const CAP: usize> {
+    cells: [InternedSceneCell; CAP],
+    len: usize,
+    pub(super) pool: StylePool,
+    policy: LayerPolicy,
+}
+
+impl<const CAP: usize> SceneTable<CAP> {
+    pub const fn new() -> Self {
+        Self {
+            cells: [EMPTY_INTERNED_CELL; CAP],
+            len: 0,
+            pool: StylePool::new(),
+            policy: LayerPolicy::ActiveStack,
+        }
+    }
+
+    pub const fn len(&self) -> usize {
+        self.len
+    }
+
+    pub const fn is_empty(&self) -> bool {
+        self.len == 0
+    }
+
+    pub const fn policy(&self) -> LayerPolicy {
+        self.policy
+    }
+
+    pub fn set_policy(&mut self, policy: LayerPolicy) -> bool {
+        let changed = self.policy != policy;
+        self.policy = policy;
+        changed
+    }
+
+    /// Insert or update the cell addressed by `(layer, slot)`.
+    pub fn set(&mut self, cell: SceneTableCell) -> Result<(), StandardError> {
+        let occupied = self.cells[..self.len]
+            .iter()
+            .position(|held| held.layer == cell.layer && held.slot == cell.slot);
+        if occupied.is_none() && self.len == CAP {
+            return Err(StandardError::SceneFull { capacity: CAP });
+        }
+        // Interning first means a full pool declines before anything is
+        // mutated, so a rejected set leaves the table exactly as it was.
+        let style = self.pool.intern(cell.effect).ok_or(StandardError::SceneFull {
+            capacity: SCENE_STYLE_CAP,
+        })?;
+        let interned = InternedSceneCell {
+            layer: cell.layer,
+            slot: cell.slot,
+            style,
+        };
+        match occupied {
+            Some(index) => {
+                let replaced = self.cells[index].style;
+                self.cells[index] = interned;
+                if replaced != style {
+                    self.release(replaced);
+                }
+            }
+            None => {
+                self.cells[self.len] = interned;
+                self.len += 1;
+            }
+        }
+        Ok(())
+    }
+
+    /// Free a style that no cell references any more.
+    fn release(&mut self, style: u8) {
+        let referenced = self.cells[..self.len].iter().any(|held| held.style == style);
+        self.pool.release(style, referenced);
+    }
+
+    /// Painted cells, with their effects resolved out of the pool.
+    pub fn iter(&self) -> impl Iterator<Item = SceneTableCell> + '_ {
+        self.cells[..self.len].iter().filter_map(move |held| {
+            self.pool.get(held.style).map(|effect| SceneTableCell {
+                layer: held.layer,
+                slot: held.slot,
+                effect,
+            })
+        })
+    }
+
+    /// Remove the cell addressed by `(layer, slot)`.
+    pub fn unset(&mut self, layer: u8, slot: LedSlot) -> bool {
+        if let Some(index) = self.cells[..self.len]
+            .iter()
+            .position(|cell| cell.layer == layer && cell.slot == slot)
+        {
+            let removed = self.cells[index].style;
+            self.len -= 1;
+            self.cells[index] = self.cells[self.len];
+            self.release(removed);
+            true
+        } else {
+            false
+        }
+    }
+
+    pub fn clear(&mut self) {
+        self.len = 0;
+        self.pool.clear();
+    }
+
+    /// One readback page starting at `offset`, clamped at the table's end.
+    pub fn page(&self, offset: u16) -> SceneChunk {
+        let mut chunk = SceneChunk::new();
+        for cell in self.iter().skip(offset as usize).take(SCENE_CHUNK_SIZE) {
+            chunk.push(cell).expect("page is chunk-bounded");
+        }
+        chunk
+    }
+
+    fn cell_for_layer(&self, layer: u8, wanted: &mut usize) -> Option<SceneTableCell> {
+        for cell in self.iter().filter(|cell| cell.layer == layer) {
+            if *wanted == 0 {
+                return Some(cell);
+            }
+            *wanted -= 1;
+        }
+        None
+    }
+
+    fn cell_at(&self, context: &LightingContext, mut wanted: usize) -> SceneTableCell {
+        let effective = context.layers.effective;
+        match self.policy {
+            LayerPolicy::EffectiveOnly => self.cell_for_layer(effective, &mut wanted),
+            LayerPolicy::ActiveStack => {
+                let default = context.layers.default;
+                if let Some(cell) = self.cell_for_layer(default, &mut wanted) {
+                    return cell;
+                }
+                for layer in 0..crate::lighting::context::LayerState::CAPACITY {
+                    if layer != default
+                        && layer != effective
+                        && context.layers.is_active(layer)
+                        && let Some(cell) = self.cell_for_layer(layer, &mut wanted)
+                    {
+                        return cell;
+                    }
+                }
+                if effective != default {
+                    self.cell_for_layer(effective, &mut wanted)
+                } else {
+                    None
+                }
+            }
+        }
+        .expect("LightingSource index must be below len")
+    }
+
+    fn included_len(&self, context: &LightingContext) -> usize {
+        let effective = context.layers.effective;
+        self.cells[..self.len]
+            .iter()
+            .filter(|cell| match self.policy {
+                LayerPolicy::EffectiveOnly => cell.layer == effective,
+                LayerPolicy::ActiveStack => {
+                    cell.layer == context.layers.default
+                        || cell.layer == effective
+                        || context.layers.is_active(cell.layer)
+                }
+            })
+            .count()
+    }
+}
+
+impl<const CAP: usize> Default for SceneTable<CAP> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<const CAP: usize> PartialEq for SceneTable<CAP> {
+    fn eq(&self, other: &Self) -> bool {
+        // Cells past `len` are stale storage, not state, and a style index is
+        // an allocation detail -- two tables holding the same effects can
+        // number them differently -- so this compares resolved cells.
+        self.policy == other.policy && self.iter().eq(other.iter())
+    }
+}
+
+impl<const CAP: usize> Eq for SceneTable<CAP> {}
+
+impl<Context, const CAP: usize> LightingSource<Rgb8, Context> for SceneTable<CAP>
+where
+    Context: LightingContextProvider,
+{
+    fn len(&self, input: &SourceRenderInput<'_, Context>) -> usize {
+        self.included_len(input.context.lighting_context())
+    }
+
+    fn slot(&self, index: usize, input: &SourceRenderInput<'_, Context>) -> LedSlot {
+        self.cell_at(input.context.lighting_context(), index).slot
+    }
+
+    fn contribution(&mut self, index: usize, input: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
+        Contribution::Opaque(
+            self.cell_at(input.context.lighting_context(), index)
+                .effect
+                .sample(input.now_ms),
+        )
+    }
+}
diff --git a/rmk/src/lighting/standard/tests.rs b/rmk/src/lighting/standard/tests.rs
new file mode 100644
index 000000000..42be94fe6
--- /dev/null
+++ b/rmk/src/lighting/standard/tests.rs
@@ -0,0 +1,1715 @@
+use core::num::NonZeroU32;
+
+use rmk_types::action::LightAction;
+
+use super::*;
+use crate::lighting::compositor::{
+    Contribution, ExtensionDescriptor, ExtensionParamSpec, ExtensionState, LightingSource, LogicalFrame,
+    RenderInput as SourceRenderInput,
+};
+use crate::lighting::effect::BuiltinEffect;
+use crate::lighting::service::{Invalidation, LightingEngine, RenderInput};
+use crate::lighting::source::{
+    BatteryStatusProvider, ConditionSet, LayerScenes, LightingControls, OutputMode, OverlayError, SparseScene,
+};
+use crate::lighting::topology::LedSlot;
+use crate::lighting::{LayerPolicy, LayerScene, LayerState, LightingContext, Rgb8, SceneCell};
+
+const RED: Rgb8 = Rgb8::new(200, 0, 0);
+const GREEN: Rgb8 = Rgb8::new(0, 200, 0);
+
+type Engine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2>;
+
+/// Effect 0 advertises two parameters; effect 1 advertises none, so the
+/// "active effect has nothing to replicate" path stays covered.
+static REPLICA_EFFECT_NAMES: &[&str] = &["A", "B"];
+static REPLICA_EFFECT_PARAMS: &[&[ExtensionParamSpec]] = &[&[
+    ExtensionParamSpec {
+        name: "Density",
+        min: 1,
+        max: 8,
+        default: 3,
+    },
+    ExtensionParamSpec {
+        name: "Fade",
+        min: 0,
+        max: 255,
+        default: 128,
+    },
+]];
+
+#[derive(Copy, Clone)]
+struct ReplicaExtension {
+    state: ExtensionState,
+    accept: bool,
+    params: [u8; 2],
+}
+
+impl<Context> LightingSource<Rgb8, Context> for ReplicaExtension {
+    fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
+        0
+    }
+
+    fn slot(&self, _: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
+        unreachable!("replica test extension has no targets")
+    }
+
+    fn contribution(&mut self, _: usize, _: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
+        unreachable!("replica test extension has no samples")
+    }
+
+    fn extension_state(&self) -> Option<ExtensionState> {
+        Some(self.state)
+    }
+
+    fn apply_extension_state(&mut self, state: ExtensionState) -> bool {
+        if !self.accept {
+            return false;
+        }
+        self.state = state;
+        true
+    }
+
+    fn extension_descriptor(&self) -> Option<ExtensionDescriptor> {
+        Some(ExtensionDescriptor {
+            effects: REPLICA_EFFECT_NAMES,
+            palettes: &[],
+            params: REPLICA_EFFECT_PARAMS,
+        })
+    }
+
+    fn extension_param(&self, effect: u8, index: u8) -> Option<u8> {
+        if effect != 0 {
+            return None;
+        }
+        self.params.get(index as usize).copied()
+    }
+
+    fn apply_extension_param(&mut self, effect: u8, index: u8, value: u8) -> bool {
+        if !self.accept || effect != 0 {
+            return false;
+        }
+        match self.params.get_mut(index as usize) {
+            Some(slot) => {
+                *slot = value;
+                true
+            }
+            None => false,
+        }
+    }
+}
+
+static LAYER_CELLS: [SceneCell<BuiltinEffect>; 1] = [SceneCell {
+    slot: LedSlot(0),
+    effect: BuiltinEffect::Solid { color: RED },
+}];
+static LAYERS: [LayerScene<'static, BuiltinEffect>; 1] = [LayerScene {
+    layer: 1,
+    cells: &LAYER_CELLS,
+}];
+static STATUS_CELLS: [SceneCell<BuiltinEffect>; 1] = [SceneCell {
+    slot: LedSlot(1),
+    effect: BuiltinEffect::Solid { color: GREEN },
+}];
+
+fn engine() -> Engine {
+    StandardLightingEngine::new(
+        BackgroundState {
+            value: 10,
+            ..BackgroundState::default()
+        },
+        LayerScenes {
+            scenes: &LAYERS,
+            policy: LayerPolicy::ActiveStack,
+        },
+        EmptySource,
+        EmptySource,
+    )
+}
+
+fn replica_engine(accept: bool) -> StandardLightingEngine<'static, ReplicaExtension, EmptySource, 2, 2> {
+    StandardLightingEngine::new(
+        BackgroundState {
+            value: 10,
+            ..BackgroundState::default()
+        },
+        LayerScenes {
+            scenes: &LAYERS,
+            policy: LayerPolicy::ActiveStack,
+        },
+        ReplicaExtension {
+            state: ExtensionState {
+                effect: 0,
+                palette: 0,
+                value: 10,
+                speed: 20,
+            },
+            accept,
+            params: [3, 128],
+        },
+        EmptySource,
+    )
+}
+
+fn context(layer: u8) -> LightingContext {
+    LightingContext {
+        layers: LayerState::new(layer, 0, 1 | (1 << layer)),
+        indicators: Default::default(),
+        powered: false,
+    }
+}
+
+#[test]
+fn replica_snapshot_preserves_state_scenes_context_ttl_and_animation_phase() {
+    type SceneEngine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2, 4>;
+    fn scene_engine() -> SceneEngine {
+        SceneEngine::new(
+            BackgroundState {
+                value: 10,
+                ..BackgroundState::default()
+            },
+            LayerScenes {
+                scenes: &LAYERS,
+                policy: LayerPolicy::ActiveStack,
+            },
+            EmptySource,
+            EmptySource,
+        )
+    }
+    let mut authority = scene_engine();
+    let authority_context = context(3);
+    authority
+        .handle_command(
+            100,
+            StandardCommand::SetBackground(BackgroundState {
+                mode: BackgroundMode::Breathe,
+                speed: 200,
+                ..BackgroundState::default()
+            }),
+            &authority_context,
+        )
+        .unwrap();
+    authority
+        .handle_command(
+            100,
+            StandardCommand::SetOverlay(OverlayCell {
+                slot: LedSlot(1),
+                effect: BuiltinEffect::Solid { color: GREEN },
+                ttl_ms: NonZeroU32::new(100),
+            }),
+            &authority_context,
+        )
+        .unwrap();
+    let scene_cell = SceneTableCell {
+        layer: 3,
+        slot: LedSlot(0),
+        effect: BuiltinEffect::Solid { color: RED },
+    };
+    authority
+        .handle_command(
+            100,
+            StandardCommand::SetSceneCellIfRevision {
+                expected_revision: 2,
+                cell: scene_cell,
+            },
+            &authority_context,
+        )
+        .unwrap();
+
+    static EXPORT: StandardReplicaSlot<2, 4> = StandardReplicaSlot::new();
+    authority
+        .handle_command(120, StandardCommand::ExportReplica(&EXPORT), &authority_context)
+        .unwrap();
+    let snapshot = EXPORT.take().unwrap();
+    assert_eq!(snapshot.context, authority_context);
+    assert_eq!(snapshot.sample_time_ms, 120);
+    assert_eq!(snapshot.overlay.as_slice()[0].ttl_ms, NonZeroU32::new(80));
+    assert_eq!(snapshot.scenes.iter().collect::<heapless::Vec<_, 4>>(), &[scene_cell]);
+
+    let mut authority_frame = LogicalFrame::new(Rgb8::BLACK);
+    authority
+        .render(
+            RenderInput {
+                now_ms: 136,
+                snapshot: &authority_context,
+            },
+            &mut authority_frame,
+        )
+        .unwrap();
+
+    static APPLY: StandardReplicaSlot<2, 4> = StandardReplicaSlot::new();
+    APPLY.put(snapshot).unwrap();
+    let mut replica = scene_engine();
+    replica
+        .handle_command(1_000, StandardCommand::ApplyReplica(&APPLY), &authority_context)
+        .unwrap();
+    let mut replica_frame = LogicalFrame::new(Rgb8::BLACK);
+    replica
+        .render(
+            RenderInput {
+                now_ms: 1_016,
+                snapshot: &snapshot.context,
+            },
+            &mut replica_frame,
+        )
+        .unwrap();
+
+    assert_eq!(replica.state().revision, snapshot.revision);
+    assert_eq!(replica.scenes().iter().collect::<heapless::Vec<_, 4>>(), &[scene_cell]);
+    assert_eq!(replica_frame, authority_frame);
+}
+
+#[test]
+fn replica_slot_rejects_overwrite_and_empty_take() {
+    let slot = StandardReplicaSlot::<2>::new();
+    let snapshot = StandardReplicaState {
+        revision: 1,
+        mutable: StandardMutableState {
+            output_enabled: true,
+            output_brightness: 42,
+            background: BackgroundState::default(),
+        },
+        output_mode: OutputMode::AlwaysOn,
+        overlay: OverlayBatch::new(),
+        scenes: SceneTable::new(),
+        runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
+        context: context(0),
+        sample_time_ms: 9,
+        extension: None,
+        extension_params: None,
+    };
+    slot.put(snapshot).unwrap();
+    assert_eq!(slot.put(snapshot), Err(ReplicaSlotError::Busy));
+    assert_eq!(slot.take(), Ok(snapshot));
+    assert_eq!(slot.take(), Err(ReplicaSlotError::Empty));
+}
+
+#[test]
+fn replica_application_is_atomic_across_common_and_extension_state() {
+    let next_extension = ExtensionState {
+        effect: 1,
+        palette: 2,
+        value: 30,
+        speed: 40,
+    };
+    let snapshot = StandardReplicaState {
+        revision: 9,
+        mutable: StandardMutableState {
+            output_enabled: false,
+            output_brightness: 42,
+            background: BackgroundState {
+                value: 99,
+                ..BackgroundState::default()
+            },
+        },
+        output_mode: OutputMode::AlwaysOff,
+        overlay: OverlayBatch::new(),
+        scenes: SceneTable::new(),
+        runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
+        context: context(0),
+        sample_time_ms: 50,
+        extension: Some(next_extension),
+        extension_params: None,
+    };
+
+    let mut declining = replica_engine(false);
+    let before = declining.state();
+    let before_extension = declining.extension().state;
+    static DECLINING_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+    DECLINING_SLOT.put(snapshot).unwrap();
+    assert_eq!(
+        declining.handle_command(100, StandardCommand::ApplyReplica(&DECLINING_SLOT), &context(0),),
+        Err(StandardError::ExtensionUnsupported)
+    );
+    assert_eq!(declining.state(), before);
+    assert_eq!(declining.extension().state, before_extension);
+
+    let mut accepting = replica_engine(true);
+    static ACCEPTING_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+    ACCEPTING_SLOT.put(snapshot).unwrap();
+    accepting
+        .handle_command(100, StandardCommand::ApplyReplica(&ACCEPTING_SLOT), &context(0))
+        .unwrap();
+    assert_eq!(accepting.state().revision, 9);
+    assert_eq!(accepting.state().output_brightness, 42);
+    assert_eq!(accepting.extension().state, next_extension);
+}
+
+#[test]
+fn replica_export_carries_the_active_effect_parameters() {
+    let mut authority = replica_engine(true);
+    authority
+        .handle_command(
+            0,
+            StandardCommand::SetExtensionParamIfRevision {
+                expected_revision: 0,
+                effect: 0,
+                index: 1,
+                value: 200,
+            },
+            &context(0),
+        )
+        .unwrap();
+
+    static EXPORT_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+    authority
+        .handle_command(10, StandardCommand::ExportReplica(&EXPORT_SLOT), &context(0))
+        .unwrap();
+    let snapshot = EXPORT_SLOT.take().unwrap();
+    let params = snapshot.extension_params.expect("active effect has parameters");
+    assert_eq!(params.effect, 0);
+    assert_eq!(params.values(), &[3, 200]);
+
+    // An active effect without parameters exports nothing to replicate.
+    authority
+        .handle_command(
+            20,
+            StandardCommand::SetExtensionIfRevision {
+                expected_revision: authority.state().revision,
+                state: ExtensionState {
+                    effect: 1,
+                    palette: 0,
+                    value: 10,
+                    speed: 20,
+                },
+            },
+            &context(0),
+        )
+        .unwrap();
+    authority
+        .handle_command(30, StandardCommand::ExportReplica(&EXPORT_SLOT), &context(0))
+        .unwrap();
+    assert_eq!(EXPORT_SLOT.take().unwrap().extension_params, None);
+}
+
+#[test]
+fn replica_application_installs_exported_parameters() {
+    let mut authority = replica_engine(true);
+    authority
+        .handle_command(
+            0,
+            StandardCommand::SetExtensionParamIfRevision {
+                expected_revision: 0,
+                effect: 0,
+                index: 0,
+                value: 7,
+            },
+            &context(0),
+        )
+        .unwrap();
+    static ROUND_TRIP_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+    authority
+        .handle_command(10, StandardCommand::ExportReplica(&ROUND_TRIP_SLOT), &context(0))
+        .unwrap();
+    let snapshot = ROUND_TRIP_SLOT.take().unwrap();
+
+    let mut replica = replica_engine(true);
+    assert_eq!(replica.extension().params, [3, 128]);
+    ROUND_TRIP_SLOT.put(snapshot).unwrap();
+    replica
+        .handle_command(100, StandardCommand::ApplyReplica(&ROUND_TRIP_SLOT), &context(0))
+        .unwrap();
+    assert_eq!(replica.extension().params, [7, 128]);
+    assert_eq!(replica.state().revision, snapshot.revision);
+}
+
+#[test]
+fn replica_parameters_are_validated_like_a_host_set() {
+    let mut authority = replica_engine(true);
+    static SEED_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+    authority
+        .handle_command(0, StandardCommand::ExportReplica(&SEED_SLOT), &context(0))
+        .unwrap();
+    let mut snapshot = SEED_SLOT.take().unwrap();
+    // A selection change that must not survive the rejected parameter.
+    snapshot.extension = Some(ExtensionState {
+        effect: 0,
+        palette: 7,
+        value: 77,
+        speed: 88,
+    });
+    // 9 is outside the "Density" spec's 1..=8 range.
+    snapshot.extension_params = Some(ExtensionReplicaParams {
+        effect: 0,
+        len: 1,
+        values: [9, 0, 0, 0, 0, 0, 0, 0],
+    });
+
+    let mut replica = replica_engine(true);
+    let before = replica.extension().params;
+    let before_state = replica.extension().state;
+    static INVALID_PARAM_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+    INVALID_PARAM_SLOT.put(snapshot).unwrap();
+    assert_eq!(
+        replica.handle_command(100, StandardCommand::ApplyReplica(&INVALID_PARAM_SLOT), &context(0)),
+        Err(StandardError::ExtensionUnsupported)
+    );
+    // The pre-apply check keeps the whole extension untouched, selection
+    // included, not just the parameter that failed.
+    assert_eq!(replica.extension().params, before);
+    assert_eq!(replica.extension().state, before_state);
+    assert_eq!(replica.state().revision, 0);
+}
+
+#[test]
+fn invalid_replica_common_state_does_not_mutate_extension() {
+    let mut overlay = OverlayBatch::new();
+    for _ in 0..2 {
+        overlay
+            .push(OverlayCell {
+                slot: LedSlot(0),
+                effect: BuiltinEffect::Solid { color: RED },
+                ttl_ms: None,
+            })
+            .unwrap();
+    }
+    let snapshot = StandardReplicaState {
+        revision: 9,
+        mutable: StandardMutableState {
+            output_enabled: true,
+            output_brightness: 42,
+            background: BackgroundState::default(),
+        },
+        output_mode: OutputMode::AlwaysOn,
+        overlay,
+        scenes: SceneTable::new(),
+        runtime_conditional_scenes: RuntimeConditionalSceneTable::new(),
+        context: context(0),
+        sample_time_ms: 50,
+        extension: Some(ExtensionState {
+            effect: 1,
+            palette: 2,
+            value: 30,
+            speed: 40,
+        }),
+        extension_params: None,
+    };
+    let mut engine = replica_engine(true);
+    let before = engine.extension().state;
+    static INVALID_SLOT: StandardReplicaSlot<2> = StandardReplicaSlot::new();
+    INVALID_SLOT.put(snapshot).unwrap();
+    assert_eq!(
+        engine.handle_command(100, StandardCommand::ApplyReplica(&INVALID_SLOT), &context(0),),
+        Err(StandardError::Overlay(OverlayError::DuplicateSlot { slot: LedSlot(0) }))
+    );
+    assert_eq!(engine.extension().state, before);
+    assert_eq!(engine.state().revision, 0);
+}
+
+#[test]
+fn output_mode_cycles_and_wake_layer_temporarily_overrides_policy() {
+    let mut engine = engine().with_controls(LightingControls {
+        output_toggle_user_action: None,
+        output_mode_cycle_user_action: Some(13),
+        wake_layer: Some(2),
+        initial_output_mode: OutputMode::PoweredOnly,
+        powered_only_scope: super::super::source::PoweredOnlyScope::Local,
+        output_mode_indicator: Some(super::super::source::OutputModeIndicator {
+            slot: LedSlot(1),
+            always_on: BuiltinEffect::Solid { color: GREEN },
+            always_off: BuiltinEffect::Solid { color: RED },
+            powered_only: BuiltinEffect::Solid {
+                color: Rgb8::new(0, 0, 200),
+            },
+        }),
+    });
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    let battery_context = context(0);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 0,
+                snapshot: &battery_context,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(frame.as_slice(), &[Rgb8::BLACK, Rgb8::BLACK]);
+    assert!(!engine.state().output_enabled);
+
+    let mut powered_context = battery_context;
+    powered_context.powered = true;
+    engine
+        .render(
+            RenderInput {
+                now_ms: 1,
+                snapshot: &powered_context,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert!(engine.state().output_enabled);
+
+    engine
+        .on_input(StandardInput(LightAction::OutputModeCycle), &powered_context)
+        .unwrap();
+    assert_eq!(engine.output_mode(), OutputMode::AlwaysOn);
+    engine
+        .on_input(StandardInput(LightAction::OutputModeCycle), &powered_context)
+        .unwrap();
+    assert_eq!(engine.output_mode(), OutputMode::AlwaysOff);
+
+    let magic_context = context(2);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 2,
+                snapshot: &magic_context,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert!(engine.state().wake_active);
+    assert!(engine.state().output_enabled);
+    assert_eq!(frame.as_slice()[1], RED);
+
+    engine
+        .render(
+            RenderInput {
+                now_ms: 3,
+                snapshot: &battery_context,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(frame.as_slice(), &[Rgb8::BLACK, Rgb8::BLACK]);
+    assert_eq!(engine.output_mode(), OutputMode::AlwaysOff);
+}
+
+#[test]
+fn background_patch_preserves_unmentioned_fields() {
+    let mut engine = engine();
+    let snapshot = context(0);
+    let before = engine.state();
+    let reply = engine
+        .handle_command(
+            0,
+            StandardCommand::PatchBackground(BackgroundPatch {
+                value: Some(77),
+                ..BackgroundPatch::default()
+            }),
+            &snapshot,
+        )
+        .unwrap()
+        .reply
+        .state()
+        .unwrap();
+
+    assert_eq!(reply.background.value, 77);
+    assert_eq!(reply.background.enabled, before.background.enabled);
+    assert_eq!(reply.background.hue, before.background.hue);
+    assert_eq!(reply.background.saturation, before.background.saturation);
+    assert_eq!(reply.background.speed, before.background.speed);
+    assert_eq!(reply.background.mode, before.background.mode);
+    assert_eq!(reply.output_enabled, before.output_enabled);
+    assert_eq!(reply.output_brightness, before.output_brightness);
+    assert_eq!(reply.revision, before.revision + 1);
+}
+
+#[test]
+fn revision_checks_are_atomic_and_cover_inputs_and_expiry() {
+    let mut engine = engine();
+    let snapshot = context(0);
+    assert_eq!(engine.state().revision, 0);
+
+    engine
+        .handle_command(
+            10,
+            StandardCommand::PatchBackground(BackgroundPatch {
+                value: Some(77),
+                ..BackgroundPatch::default()
+            }),
+            &snapshot,
+        )
+        .unwrap();
+    assert_eq!(engine.state().revision, 1);
+
+    let desired = StandardMutableState {
+        output_enabled: false,
+        output_brightness: 12,
+        background: BackgroundState {
+            value: 99,
+            ..BackgroundState::default()
+        },
+    };
+    assert_eq!(
+        engine.handle_command(
+            10,
+            StandardCommand::SetStateIfRevision {
+                expected_revision: 0,
+                state: desired,
+            },
+            &snapshot,
+        ),
+        Err(StandardError::RevisionConflict {
+            expected: 0,
+            current: 1,
+        })
+    );
+    assert!(engine.state().output_enabled, "a stale update is all-or-nothing");
+
+    let reply = engine
+        .handle_command(
+            10,
+            StandardCommand::SetStateIfRevision {
+                expected_revision: 1,
+                state: desired,
+            },
+            &snapshot,
+        )
+        .unwrap()
+        .reply
+        .state()
+        .unwrap();
+    assert_eq!(reply.revision, 2);
+    assert!(!reply.output_enabled);
+
+    engine
+        .on_input(StandardInput(LightAction::BacklightOn), &snapshot)
+        .unwrap();
+    assert_eq!(engine.state().revision, 3);
+    assert_eq!(
+        engine.on_input(StandardInput(LightAction::RgbModeRainbow), &snapshot),
+        Ok(Invalidation::None)
+    );
+    assert_eq!(engine.state().revision, 3);
+
+    engine
+        .handle_command(
+            10,
+            StandardCommand::SetOverlayIfRevision {
+                expected_revision: 3,
+                cell: OverlayCell {
+                    slot: LedSlot(0),
+                    effect: BuiltinEffect::Solid { color: GREEN },
+                    ttl_ms: NonZeroU32::new(1),
+                },
+            },
+            &snapshot,
+        )
+        .unwrap();
+    assert_eq!(engine.state().revision, 4);
+
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    let first_expiry = engine
+        .render(
+            RenderInput {
+                now_ms: 11,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert!(first_expiry.state_changed);
+    assert_eq!(engine.state().revision, 5, "TTL expiry is authoritative state");
+    let second_expiry = engine
+        .render(
+            RenderInput {
+                now_ms: 12,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert!(!second_expiry.state_changed);
+    assert_eq!(engine.state().revision, 5, "expiry advances exactly once");
+}
+
+#[test]
+fn overlay_pages_sample_remaining_ttl_and_prune_with_revision_advance() {
+    let mut engine = engine();
+    let snapshot = context(0);
+    engine
+        .handle_command(
+            100,
+            StandardCommand::SetOverlay(OverlayCell {
+                slot: LedSlot(0),
+                effect: BuiltinEffect::Solid { color: RED },
+                ttl_ms: None,
+            }),
+            &snapshot,
+        )
+        .unwrap();
+    engine
+        .handle_command(
+            100,
+            StandardCommand::SetOverlay(OverlayCell {
+                slot: LedSlot(1),
+                effect: BuiltinEffect::Solid { color: GREEN },
+                ttl_ms: NonZeroU32::new(50),
+            }),
+            &snapshot,
+        )
+        .unwrap();
+
+    let sampled = engine
+        .handle_command(120, StandardCommand::ReadOverlay { offset: 0 }, &snapshot)
+        .unwrap();
+    assert_eq!(sampled.invalidation, Invalidation::None);
+    let StandardReply::OverlayPage(page) = sampled.reply else {
+        panic!("expected overlay page")
+    };
+    assert_eq!(page.revision, 2);
+    assert_eq!(page.total, 2);
+    assert_eq!(page.cells.as_slice()[0].ttl_ms, None);
+    assert_eq!(page.cells.as_slice()[1].ttl_ms, NonZeroU32::new(30));
+
+    let pruned = engine
+        .handle_command(150, StandardCommand::ReadOverlay { offset: 0 }, &snapshot)
+        .unwrap();
+    assert_eq!(pruned.invalidation, Invalidation::Render);
+    let StandardReply::OverlayPage(page) = pruned.reply else {
+        panic!("expected overlay page")
+    };
+    assert_eq!(page.revision, 3);
+    assert_eq!(page.total, 1);
+    assert_eq!(page.cells.as_slice()[0].slot, LedSlot(0));
+}
+
+#[test]
+fn compiled_scene_pages_preserve_layer_and_are_separate_from_runtime_scenes() {
+    let mut engine = scene_engine();
+    set_cell(&mut engine, 0, scene_cell(7, 1, GREEN));
+
+    let reply = engine
+        .handle_command(0, StandardCommand::ReadCompiledScenes { offset: 0 }, &context(0))
+        .unwrap()
+        .reply;
+    let StandardReply::CompiledScenesPage(page) = reply else {
+        panic!("expected compiled scene page")
+    };
+    assert_eq!(page.total, 1);
+    assert_eq!(page.policy, LayerPolicy::ActiveStack);
+    assert_eq!(page.cells.as_slice(), &[scene_cell(1, 0, RED)]);
+
+    let runtime = scenes_page(&mut engine, 0);
+    assert_eq!(runtime.total, 1);
+    assert_eq!(runtime.cells.as_slice(), &[scene_cell(7, 1, GREEN)]);
+
+    let mut empty: Engine = StandardLightingEngine::new(
+        BackgroundState::default(),
+        LayerScenes {
+            scenes: &[],
+            policy: LayerPolicy::ActiveStack,
+        },
+        EmptySource,
+        EmptySource,
+    );
+    let StandardReply::CompiledScenesPage(empty_page) = empty
+        .handle_command(0, StandardCommand::ReadCompiledScenes { offset: 0 }, &context(0))
+        .unwrap()
+        .reply
+    else {
+        panic!("expected compiled scene page")
+    };
+    assert_eq!(empty_page.total, 0);
+    assert_eq!(empty_page.policy, LayerPolicy::ActiveStack);
+    assert!(empty_page.cells.as_slice().is_empty());
+}
+
+#[test]
+fn disabling_background_does_not_disable_layer_or_status_sources() {
+    type StatusEngine = StandardLightingEngine<'static, EmptySource, SparseScene<'static, BuiltinEffect>, 2, 2>;
+    let mut engine = StatusEngine::new(
+        BackgroundState {
+            value: 10,
+            ..BackgroundState::default()
+        },
+        LayerScenes {
+            scenes: &LAYERS,
+            policy: LayerPolicy::ActiveStack,
+        },
+        EmptySource,
+        SparseScene { cells: &STATUS_CELLS },
+    );
+    let snapshot = context(1);
+    let before = engine.state();
+    engine
+        .handle_command(
+            0,
+            StandardCommand::PatchBackground(BackgroundPatch {
+                enabled: Some(false),
+                ..BackgroundPatch::default()
+            }),
+            &snapshot,
+        )
+        .unwrap();
+
+    assert!(engine.state().output_enabled);
+    assert_eq!(engine.state().output_brightness, before.output_brightness);
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 0,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(frame.as_slice(), &[RED, GREEN]);
+}
+
+#[test]
+fn standard_engine_composes_background_layer_and_expiring_overlay() {
+    let mut engine = engine();
+    let snapshot = context(1);
+    engine
+        .handle_command(
+            100,
+            StandardCommand::SetOverlay(OverlayCell {
+                slot: LedSlot(1),
+                effect: BuiltinEffect::Solid { color: GREEN },
+                ttl_ms: NonZeroU32::new(10),
+            }),
+            &snapshot,
+        )
+        .unwrap();
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    let outcome = engine
+        .render(
+            RenderInput {
+                now_ms: 100,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(frame.as_slice(), &[RED, GREEN]);
+    assert_eq!(outcome.next_wake_in_ms, NonZeroU32::new(10));
+    <Engine as LightingEngine<LightingContext>>::on_presented(&mut engine, &frame);
+
+    engine
+        .render(
+            RenderInput {
+                now_ms: 110,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(frame.as_slice(), &[RED, Rgb8::new(10, 10, 10)]);
+    assert_eq!(engine.state().overlay_len, 0);
+}
+
+#[test]
+fn expired_overlay_capacity_is_reclaimed_and_light_actions_are_scoped() {
+    let mut engine = engine();
+    let snapshot = context(0);
+    for slot in [LedSlot(0), LedSlot(1)] {
+        engine
+            .handle_command(
+                0,
+                StandardCommand::SetOverlay(OverlayCell {
+                    slot,
+                    effect: BuiltinEffect::Solid { color: GREEN },
+                    ttl_ms: NonZeroU32::new(1),
+                }),
+                &snapshot,
+            )
+            .unwrap();
+    }
+    assert!(
+        engine
+            .handle_command(
+                1,
+                StandardCommand::SetOverlay(OverlayCell {
+                    slot: LedSlot(0),
+                    effect: BuiltinEffect::Solid { color: RED },
+                    ttl_ms: None,
+                }),
+                &snapshot,
+            )
+            .is_ok()
+    );
+
+    let before = engine.state();
+    assert_eq!(
+        engine.on_input(StandardInput(LightAction::RgbModeRainbow), &snapshot),
+        Ok(Invalidation::None)
+    );
+    assert_eq!(engine.state(), before);
+    assert_eq!(
+        engine.on_input(StandardInput(LightAction::BacklightOff), &snapshot),
+        Ok(Invalidation::Render)
+    );
+    assert!(!engine.state().output_enabled);
+}
+
+const BLUE: Rgb8 = Rgb8::new(0, 0, 200);
+
+type SceneEngine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2, 4>;
+
+fn scene_engine() -> SceneEngine {
+    StandardLightingEngine::new(
+        BackgroundState {
+            value: 10,
+            ..BackgroundState::default()
+        },
+        LayerScenes {
+            scenes: &LAYERS,
+            policy: LayerPolicy::ActiveStack,
+        },
+        EmptySource,
+        EmptySource,
+    )
+}
+
+fn scene_cell(layer: u8, slot: u16, color: Rgb8) -> SceneTableCell {
+    SceneTableCell {
+        layer,
+        slot: LedSlot(slot),
+        effect: BuiltinEffect::Solid { color },
+    }
+}
+
+fn set_cell(engine: &mut SceneEngine, revision: u32, cell: SceneTableCell) -> StandardState {
+    engine
+        .handle_command(
+            0,
+            StandardCommand::SetSceneCellIfRevision {
+                expected_revision: revision,
+                cell,
+            },
+            &context(0),
+        )
+        .unwrap()
+        .reply
+        .state()
+        .unwrap()
+}
+
+fn scenes_page(engine: &mut SceneEngine, offset: u16) -> ScenePage {
+    match engine
+        .handle_command(0, StandardCommand::ReadScenes { offset }, &context(0))
+        .unwrap()
+        .reply
+    {
+        StandardReply::ScenesPage(page) => page,
+        other => panic!("expected page, got {other:?}"),
+    }
+}
+
+#[test]
+fn scene_crud_is_revision_checked_and_keyed_by_layer_and_slot() {
+    let mut engine = scene_engine();
+    let snapshot = context(0);
+
+    let state = set_cell(&mut engine, 0, scene_cell(1, 0, GREEN));
+    assert_eq!(state.revision, 1);
+    assert_eq!(state.scene_len, 1);
+
+    // Same (layer, slot) updates in place; a new pair appends.
+    let state = set_cell(&mut engine, 1, scene_cell(1, 0, BLUE));
+    assert_eq!(state.scene_len, 1);
+    let state = set_cell(&mut engine, 2, scene_cell(2, 0, RED));
+    assert_eq!(state.scene_len, 2);
+
+    assert_eq!(
+        engine.handle_command(
+            0,
+            StandardCommand::SetSceneCellIfRevision {
+                expected_revision: 0,
+                cell: scene_cell(0, 1, RED),
+            },
+            &snapshot,
+        ),
+        Err(StandardError::RevisionConflict {
+            expected: 0,
+            current: 3
+        })
+    );
+    assert_eq!(engine.state().scene_len, 2, "a stale write is all-or-nothing");
+
+    // Out-of-range slots never reach the table.
+    assert_eq!(
+        engine.handle_command(
+            0,
+            StandardCommand::SetSceneCellIfRevision {
+                expected_revision: 3,
+                cell: scene_cell(0, 9, RED),
+            },
+            &snapshot,
+        ),
+        Err(StandardError::SceneSlotOutOfRange { slot: LedSlot(9) })
+    );
+
+    // Unset of a missing cell keeps the revision moving but not the frame.
+    let result = engine
+        .handle_command(
+            0,
+            StandardCommand::UnsetSceneCellIfRevision {
+                expected_revision: 3,
+                layer: 7,
+                slot: LedSlot(0),
+            },
+            &snapshot,
+        )
+        .unwrap();
+    assert_eq!(result.invalidation, Invalidation::StateChanged);
+    let state = result.reply.state().unwrap();
+    assert_eq!(state.scene_len, 2);
+    assert_eq!(state.revision, 4);
+
+    let state = engine
+        .handle_command(
+            0,
+            StandardCommand::UnsetSceneCellIfRevision {
+                expected_revision: 4,
+                layer: 1,
+                slot: LedSlot(0),
+            },
+            &snapshot,
+        )
+        .unwrap()
+        .reply
+        .state()
+        .unwrap();
+    assert_eq!(state.scene_len, 1);
+
+    // Capacity is enforced with the table's own limit.
+    for (revision, (layer, slot)) in [(5u32, (5u8, 0u16)), (6, (5, 1)), (7, (6, 0))] {
+        set_cell(&mut engine, revision, scene_cell(layer, slot, RED));
+    }
+    assert_eq!(
+        engine.handle_command(
+            0,
+            StandardCommand::SetSceneCellIfRevision {
+                expected_revision: 8,
+                cell: scene_cell(9, 1, RED),
+            },
+            &snapshot,
+        ),
+        Err(StandardError::SceneFull { capacity: 4 })
+    );
+}
+
+#[test]
+fn scene_pages_echo_revision_and_clamp() {
+    let mut engine = scene_engine();
+    set_cell(&mut engine, 0, scene_cell(0, 0, RED));
+    set_cell(&mut engine, 1, scene_cell(0, 1, GREEN));
+
+    let page = scenes_page(&mut engine, 0);
+    assert_eq!(page.revision, 2);
+    assert_eq!(page.total, 2);
+    assert_eq!(page.cells.as_slice().len(), 2);
+    let tail = scenes_page(&mut engine, 99);
+    assert_eq!(tail.total, 2);
+    assert!(tail.cells.as_slice().is_empty());
+}
+
+#[test]
+fn runtime_scene_overrides_static_layer_and_yields_to_overlay() {
+    let mut engine = scene_engine();
+    let snapshot = context(1);
+
+    // Static layer 1 paints slot 0 RED; runtime cell overrides to BLUE.
+    set_cell(&mut engine, 0, scene_cell(1, 0, BLUE));
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 0,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(frame.as_slice()[0], BLUE);
+
+    // The TTL overlay still wins above runtime scenes.
+    engine
+        .handle_command(
+            0,
+            StandardCommand::SetOverlay(OverlayCell {
+                slot: LedSlot(0),
+                effect: BuiltinEffect::Solid { color: GREEN },
+                ttl_ms: None,
+            }),
+            &snapshot,
+        )
+        .unwrap();
+    engine
+        .render(
+            RenderInput {
+                now_ms: 1,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(frame.as_slice()[0], GREEN);
+}
+
+#[test]
+fn layer_policy_switches_between_effective_only_and_active_stack() {
+    let mut engine = scene_engine();
+    // Base layer paints slot 1; effective layer paints slot 0.
+    set_cell(&mut engine, 0, scene_cell(0, 1, GREEN));
+    set_cell(&mut engine, 1, scene_cell(1, 0, BLUE));
+    let snapshot = context(1);
+
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 0,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(frame.as_slice(), &[BLUE, GREEN], "ActiveStack falls through sparsely");
+
+    let state = engine
+        .handle_command(
+            0,
+            StandardCommand::SetLayerPolicyIfRevision {
+                expected_revision: 2,
+                policy: LayerPolicy::EffectiveOnly,
+            },
+            &snapshot,
+        )
+        .unwrap()
+        .reply
+        .state()
+        .unwrap();
+    assert_eq!(state.scene_policy, LayerPolicy::EffectiveOnly);
+
+    let background = Rgb8::new(10, 10, 10);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 1,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(
+        frame.as_slice(),
+        &[BLUE, background],
+        "EffectiveOnly hides base-layer cells"
+    );
+}
+
+#[test]
+fn scene_replace_is_chunked_ordered_atomic_and_idempotent() {
+    let mut engine = scene_engine();
+    let snapshot = context(0);
+    set_cell(&mut engine, 0, scene_cell(3, 0, RED));
+
+    let (id, _) = match engine
+        .handle_command(
+            10,
+            StandardCommand::BeginSceneReplace {
+                expected_revision: 1,
+                cell_count: 2,
+            },
+            &snapshot,
+        )
+        .unwrap()
+        .reply
+    {
+        StandardReply::SceneTransaction { id, cell_count } => (id, cell_count),
+        other => panic!("expected transaction, got {other:?}"),
+    };
+
+    // A second begin while staged is busy; out-of-order chunks rejected.
+    assert_eq!(
+        engine.handle_command(
+            11,
+            StandardCommand::BeginSceneReplace {
+                expected_revision: 1,
+                cell_count: 0,
+            },
+            &snapshot,
+        ),
+        Err(StandardError::SceneTransactionBusy)
+    );
+    let mut chunk = SceneChunk::new();
+    chunk.push(scene_cell(0, 0, GREEN)).unwrap();
+    assert_eq!(
+        engine.handle_command(
+            12,
+            StandardCommand::PutSceneChunk {
+                transaction_id: id,
+                offset: 1,
+                cells: chunk,
+            },
+            &snapshot,
+        ),
+        Err(StandardError::InvalidSceneRequest)
+    );
+    assert_eq!(
+        engine.handle_command(
+            13,
+            StandardCommand::CommitSceneReplace { transaction_id: id },
+            &snapshot,
+        ),
+        Err(StandardError::SceneTransactionIncomplete {
+            expected: 2,
+            received: 0
+        })
+    );
+
+    let mut chunk = SceneChunk::new();
+    chunk.push(scene_cell(0, 0, GREEN)).unwrap();
+    chunk.push(scene_cell(0, 1, BLUE)).unwrap();
+    engine
+        .handle_command(
+            14,
+            StandardCommand::PutSceneChunk {
+                transaction_id: id,
+                offset: 0,
+                cells: chunk,
+            },
+            &snapshot,
+        )
+        .unwrap();
+
+    let committed = engine
+        .handle_command(
+            15,
+            StandardCommand::CommitSceneReplace { transaction_id: id },
+            &snapshot,
+        )
+        .unwrap();
+    assert_eq!(committed.invalidation, Invalidation::Render);
+    let state = committed.reply.state().unwrap();
+    assert_eq!(state.scene_len, 2, "replacement drops the previous table");
+    assert_eq!(state.revision, 2);
+
+    // Retried commit answers idempotently without another revision bump.
+    let retried = engine
+        .handle_command(
+            16,
+            StandardCommand::CommitSceneReplace { transaction_id: id },
+            &snapshot,
+        )
+        .unwrap();
+    assert_eq!(retried.invalidation, Invalidation::None);
+    assert_eq!(retried.reply.state().unwrap().revision, 2);
+
+    // A conflicting revision at commit leaves the table untouched.
+    let stale = match engine
+        .handle_command(
+            20,
+            StandardCommand::BeginSceneReplace {
+                expected_revision: 0,
+                cell_count: 0,
+            },
+            &snapshot,
+        )
+        .unwrap()
+        .reply
+    {
+        StandardReply::SceneTransaction { id, .. } => id,
+        other => panic!("expected transaction, got {other:?}"),
+    };
+    assert_eq!(
+        engine.handle_command(
+            21,
+            StandardCommand::CommitSceneReplace { transaction_id: stale },
+            &snapshot,
+        ),
+        Err(StandardError::RevisionConflict {
+            expected: 0,
+            current: 2
+        })
+    );
+    assert_eq!(engine.state().scene_len, 2);
+    engine
+        .handle_command(
+            22,
+            StandardCommand::AbortSceneReplace { transaction_id: stale },
+            &snapshot,
+        )
+        .unwrap();
+}
+
+#[test]
+fn scene_transaction_expires_after_inactivity() {
+    let mut engine = scene_engine();
+    let snapshot = context(0);
+    let id = match engine
+        .handle_command(
+            0,
+            StandardCommand::BeginSceneReplace {
+                expected_revision: 0,
+                cell_count: 0,
+            },
+            &snapshot,
+        )
+        .unwrap()
+        .reply
+    {
+        StandardReply::SceneTransaction { id, .. } => id,
+        other => panic!("expected transaction, got {other:?}"),
+    };
+    assert_eq!(
+        engine.handle_command(
+            SCENE_TRANSACTION_TIMEOUT_MS,
+            StandardCommand::CommitSceneReplace { transaction_id: id },
+            &snapshot,
+        ),
+        Err(StandardError::SceneTransactionExpired)
+    );
+    assert_eq!(
+        engine.handle_command(
+            SCENE_TRANSACTION_TIMEOUT_MS,
+            StandardCommand::AbortSceneReplace { transaction_id: 999 },
+            &snapshot,
+        ),
+        Err(StandardError::InvalidSceneTransaction)
+    );
+}
+#[test]
+fn extension_source_claims_light_actions_before_background() {
+    #[derive(Default)]
+    struct ClaimingSource;
+
+    impl<C, Context> LightingSource<C, Context> for ClaimingSource {
+        fn len(&self, _: &SourceRenderInput<'_, Context>) -> usize {
+            0
+        }
+
+        fn slot(&self, _: usize, _: &SourceRenderInput<'_, Context>) -> LedSlot {
+            unreachable!("ClaimingSource has no targets")
+        }
+
+        fn contribution(&mut self, _: usize, _: &SourceRenderInput<'_, Context>) -> Contribution<C> {
+            unreachable!("ClaimingSource has no samples")
+        }
+
+        fn handle_light_action(&mut self, action: LightAction) -> bool {
+            matches!(action, LightAction::RgbHui)
+        }
+    }
+
+    let mut engine: StandardLightingEngine<'static, ClaimingSource, EmptySource, 2, 2> = StandardLightingEngine::new(
+        BackgroundState {
+            value: 10,
+            ..BackgroundState::default()
+        },
+        LayerScenes {
+            scenes: &LAYERS,
+            policy: LayerPolicy::ActiveStack,
+        },
+        ClaimingSource,
+        EmptySource,
+    );
+    let snapshot = context(0);
+    let hue_before = engine.state().background.hue;
+
+    assert_eq!(
+        engine.on_input(StandardInput(LightAction::RgbHui), &snapshot),
+        Ok(Invalidation::Render)
+    );
+    assert_eq!(engine.state().revision, 1);
+    assert_eq!(
+        engine.state().background.hue,
+        hue_before,
+        "a claimed action must bypass the built-in background handling"
+    );
+
+    engine.on_input(StandardInput(LightAction::RgbHud), &snapshot).unwrap();
+    assert_ne!(
+        engine.state().background.hue,
+        hue_before,
+        "unclaimed actions still fall through to the background"
+    );
+}
+
+#[test]
+fn runtime_conditional_replace_preserves_order_and_output_mode_is_revision_checked() {
+    use rmk_types::battery::{BatteryStatus, ChargeState};
+
+    use crate::lighting::{BatteryCondition, ChargeCondition, LayerCondition};
+
+    struct Batteries;
+    impl BatteryStatusProvider for Batteries {
+        fn battery_status(&self, node: u8) -> BatteryStatus {
+            if node == 1 {
+                BatteryStatus::Available {
+                    charge_state: ChargeState::Discharging,
+                    level: Some(50),
+                }
+            } else {
+                BatteryStatus::Unavailable
+            }
+        }
+    }
+    static BATTERIES: Batteries = Batteries;
+
+    let mut engine = scene_engine().with_battery_status_provider(&BATTERIES);
+    let snapshot = context(0);
+    let transaction_id = match engine
+        .handle_command(
+            0,
+            StandardCommand::BeginRuntimeConditionalSceneReplace {
+                expected_revision: 0,
+                cell_count: 2,
+            },
+            &snapshot,
+        )
+        .unwrap()
+        .reply
+    {
+        StandardReply::RuntimeConditionalSceneTransaction { id, .. } => id,
+        other => panic!("expected runtime conditional transaction, got {other:?}"),
+    };
+    let mut cells = RuntimeConditionalSceneChunk::new();
+    cells
+        .push(RuntimeConditionalSceneCell {
+            conditions: ConditionSet {
+                layer: None,
+                battery: Some(BatteryCondition {
+                    node: 1,
+                    min_level: Some(25),
+                    max_level: Some(75),
+                    charge: ChargeCondition::Discharging,
+                }),
+            },
+            slot: LedSlot(1),
+            effect: BuiltinEffect::Solid { color: RED },
+        })
+        .unwrap();
+    cells
+        .push(RuntimeConditionalSceneCell {
+            conditions: ConditionSet {
+                layer: Some(LayerCondition { layer: 0, active: true }),
+                battery: None,
+            },
+            slot: LedSlot(1),
+            effect: BuiltinEffect::Solid { color: GREEN },
+        })
+        .unwrap();
+    engine
+        .handle_command(
+            1,
+            StandardCommand::PutRuntimeConditionalSceneChunk {
+                transaction_id,
+                offset: 0,
+                cells,
+            },
+            &snapshot,
+        )
+        .unwrap();
+    let committed = engine
+        .handle_command(
+            2,
+            StandardCommand::CommitRuntimeConditionalSceneReplace { transaction_id },
+            &snapshot,
+        )
+        .unwrap();
+    assert_eq!(committed.reply.state().unwrap().revision, 1);
+    assert_eq!(engine.runtime_conditional_scenes().as_slice(), cells.as_slice());
+
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 2,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(frame.as_slice()[1], GREEN, "later matching rules win");
+
+    assert_eq!(
+        engine.handle_command(
+            3,
+            StandardCommand::SetOutputModeIfRevision {
+                expected_revision: 0,
+                mode: OutputMode::PoweredOnly,
+            },
+            &snapshot,
+        ),
+        Err(StandardError::RevisionConflict {
+            expected: 0,
+            current: 1,
+        })
+    );
+    let set = engine
+        .handle_command(
+            3,
+            StandardCommand::SetOutputModeIfRevision {
+                expected_revision: 1,
+                mode: OutputMode::PoweredOnly,
+            },
+            &snapshot,
+        )
+        .unwrap();
+    assert_eq!(set.reply.state().unwrap().output_mode, OutputMode::PoweredOnly);
+    assert_eq!(set.reply.state().unwrap().revision, 2);
+}
+
+/// Interning is what shrinks a cell from 20 bytes to 4: many keys painted
+/// from few colours share one entry, and the effect's type stops mattering
+/// to the cell, so blink and breathe need no separate table.
+#[test]
+fn interning_shares_one_entry_per_distinct_effect() {
+    let mut pool = StylePool::new();
+    let blue = BuiltinEffect::solid(Rgb8::new(0, 0, 9));
+    let green = BuiltinEffect::solid(Rgb8::new(0, 9, 0));
+
+    let first = pool.intern(blue).unwrap();
+    assert_eq!(pool.intern(blue), Some(first), "same effect, same entry");
+    let other = pool.intern(green).unwrap();
+    assert_ne!(first, other);
+    assert_eq!(pool.len(), 2);
+    assert_eq!(pool.get(first), Some(blue));
+    assert_eq!(pool.get(other), Some(green));
+}
+
+#[test]
+fn a_full_pool_declines_only_new_effects() {
+    let mut pool = StylePool::new();
+    for shade in 0..SCENE_STYLE_CAP {
+        pool.intern(BuiltinEffect::solid(Rgb8::new(shade as u8, 0, 0))).unwrap();
+    }
+    assert_eq!(pool.len(), SCENE_STYLE_CAP);
+
+    // Already held: still fine, however full.
+    let held = BuiltinEffect::solid(Rgb8::new(0, 0, 0));
+    assert!(pool.intern(held).is_some());
+
+    // New: declined, and declining mutates nothing.
+    let before = pool;
+    assert_eq!(pool.intern(BuiltinEffect::solid(Rgb8::new(0, 1, 2))), None);
+    assert_eq!(pool, before);
+}
+
+/// A style goes when nothing points at it, found by scanning rather than by
+/// keeping counts -- and it must survive while another cell still holds it.
+#[test]
+fn a_style_outlives_all_but_its_last_reference() {
+    let mut table = SceneTable::<4>::new();
+    let red = BuiltinEffect::solid(Rgb8::new(9, 0, 0));
+    let cell = |slot| SceneTableCell {
+        layer: 0,
+        slot: LedSlot(slot),
+        effect: red,
+    };
+    table.set(cell(0)).unwrap();
+    table.set(cell(1)).unwrap();
+    assert_eq!((table.len(), table.pool.len()), (2, 1));
+
+    assert!(table.unset(0, LedSlot(0)));
+    assert_eq!(table.pool.len(), 1, "the other cell still holds it");
+
+    assert!(table.unset(0, LedSlot(1)));
+    assert_eq!((table.len(), table.pool.len()), (0, 0));
+}
+
+/// Repainting one key is what painting in a configurator does, and it must
+/// not strand an entry each time: 64 repaints would exhaust the pool.
+#[test]
+fn repainting_a_cell_does_not_strand_styles() {
+    let mut table = SceneTable::<4>::new();
+    for shade in 0..(SCENE_STYLE_CAP as u8 * 3) {
+        table
+            .set(SceneTableCell {
+                layer: 0,
+                slot: LedSlot(0),
+                effect: BuiltinEffect::solid(Rgb8::new(shade, shade, shade)),
+            })
+            .expect("overwriting one cell never needs a second entry");
+        assert_eq!(table.pool.len(), 1, "the previous shade was freed");
+    }
+    assert_eq!(table.len(), 1);
+}
+
+#[test]
+fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules() {
+    use rmk_types::battery::BatteryStatus;
+
+    use crate::lighting::{ConditionalSceneCell, ConditionalScenes, LayerCondition};
+
+    struct NoBatteries;
+    impl BatteryStatusProvider for NoBatteries {
+        fn battery_status(&self, _node: u8) -> BatteryStatus {
+            BatteryStatus::Unavailable
+        }
+    }
+    static NO_BATTERIES: NoBatteries = NoBatteries;
+
+    // Slot 0 is contested three ways: a compiled layer scene paints it RED
+    // on layer 1, a compiled conditional rule paints it GREEN, and the
+    // runtime table paints it BLUE. Only the host's rule should survive.
+    static COMPILED_CONDITIONAL: [ConditionalSceneCell<BuiltinEffect>; 1] = [ConditionalSceneCell {
+        conditions: ConditionSet {
+            layer: Some(LayerCondition { layer: 1, active: true }),
+            battery: None,
+        },
+        slot: LedSlot(0),
+        effect: BuiltinEffect::Solid { color: GREEN },
+    }];
+
+    let mut engine: StandardLightingEngine<
+        'static,
+        EmptySource,
+        ConditionalScenes<'static, BuiltinEffect, NoBatteries>,
+        2,
+        2,
+        4,
+    > = StandardLightingEngine::new(
+        BackgroundState {
+            value: 10,
+            ..BackgroundState::default()
+        },
+        LayerScenes {
+            scenes: &LAYERS,
+            policy: LayerPolicy::ActiveStack,
+        },
+        EmptySource,
+        ConditionalScenes::new(&COMPILED_CONDITIONAL, &NO_BATTERIES),
+    )
+    .with_battery_status_provider(&NO_BATTERIES);
+
+    let snapshot = context(1);
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 0,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(
+        frame.as_slice()[0],
+        GREEN,
+        "compiled conditional rules outrank compiled layer scenes"
+    );
+
+    engine
+        .install_runtime_conditional_scene_cell(RuntimeConditionalSceneCell {
+            conditions: ConditionSet {
+                layer: Some(LayerCondition { layer: 1, active: true }),
+                battery: None,
+            },
+            slot: LedSlot(0),
+            effect: BuiltinEffect::Solid { color: BLUE },
+        })
+        .unwrap();
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 1,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    assert_eq!(
+        frame.as_slice()[0],
+        BLUE,
+        "a runtime conditional cell replaces the compiled rule on the same slot"
+    );
+}

From 4cf234166c1fc2593d7c2d691f994bb2343c04e5 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 00:40:38 -0700
Subject: [PATCH 44/78] feat(lighting): gate conditional rules on the output
 mode

The output-mode indicator was the last piece of actual lighting a board
had to compile in: three effects on one LED, chosen by policy, with no
runtime equivalent. Rather than add a command to set it, this makes the
policy a condition, so the indicator becomes three ordinary rules in the
runtime conditional table -- already host-editable, already persisted,
already atomic to replace.

Only the engine can evaluate it, since it owns the policy. The board's
compiled conditional source is passed None instead, which reads as
unsatisfiable rather than true, so a rule gated on the mode never fires
where the mode cannot be observed.

The extra field costs a byte per cell on the wire, which pushed the
conditional page past its frame budget, so the chunk drops from 8 cells
to 7. Pages are a paging detail, not a capacity, so nothing downstream
changes beyond doing one more round trip on a large table.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/protocol/rynk/payload/lighting.rs     |  9 ++-
 .../rynk/snapshots/lighting_wire_frames.snap  |  6 +-
 rmk-types/src/protocol/rynk/tests.rs          |  1 +
 rmk/src/host/rynk/handlers/lighting.rs        |  6 +-
 rmk/src/host/rynk/lighting.rs                 | 13 +++-
 rmk/src/lighting/source.rs                    | 23 +++++-
 rmk/src/lighting/standard/conditional.rs      | 21 +++++-
 rmk/src/lighting/standard/engine.rs           |  4 +
 rmk/src/lighting/standard/tests.rs            | 75 +++++++++++++++++++
 9 files changed, 144 insertions(+), 14 deletions(-)

diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 1cc826fac..20abe013d 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -18,7 +18,7 @@ pub const LIGHTING_OVERLAY_CHUNK_SIZE: usize = 8;
 /// Number of scene cells in one scene page or replacement chunk.
 pub const LIGHTING_SCENE_CHUNK_SIZE: usize = 8;
 /// Number of immutable conditional cells in one readback page.
-pub const LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 8;
+pub const LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 7;
 /// Maximum UTF-8 byte length of a zone name.
 pub const LIGHTING_ZONE_NAME_SIZE: usize = 24;
 /// Maximum UTF-8 byte length of one extension effect or palette name.
@@ -616,10 +616,14 @@ wire_type! {
 }
 
 wire_type! {
-    /// A conjunction of optional layer and battery predicates.
+    /// A conjunction of optional layer, battery and output-mode predicates.
     pub struct LightingConditionSet {
         pub layer: Option<LightingLayerCondition>,
         pub battery: Option<LightingBatteryCondition>,
+        /// Gate on the live output-mode policy. This is what lets the mode
+        /// indicator be an ordinary conditional rule a host can edit, rather
+        /// than something the board has to compile in.
+        pub output_mode: Option<LightingOutputMode>,
     }
 }
 
@@ -1306,6 +1310,7 @@ mod tests {
                             max_level: Some(100),
                             charge: LightingChargeCondition::Charging,
                         }),
+                        output_mode: None,
                     },
                     led_id: LightingLedId(id),
                     effect: LightingEffect::Solid {
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index f9b46c35c..db1fc255e 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -52,9 +52,9 @@ GetLightingPhysicalKeys reply                          04 04 09 01 01 12 01 01 0
 GetLightingPhysicalKeys request                        05 04 09 01 01 01 00
 GetLightingRoutes reply                                04 09 09 01 01 08 01 01 01 2a 01 02 07 00
 GetLightingRoutes request                              05 09 09 01 01 01 00
-GetLightingRuntimeConditionalSceneStatus reply         04 25 09 01 01 05 09 40 01 08 00
+GetLightingRuntimeConditionalSceneStatus reply         04 25 09 01 01 05 09 40 01 07 00
 GetLightingRuntimeConditionalSceneStatus request       04 25 09 01 00
-GetLightingRuntimeConditionalScenes reply              04 26 09 01 01 0f 09 01 01 01 02 01 01 01 01 14 01 50 02 2a 04 07 08 09 00
+GetLightingRuntimeConditionalScenes reply              04 26 09 01 01 0e 09 01 01 01 02 01 01 01 01 14 01 50 02 02 2a 04 07 08 09 00
 GetLightingRuntimeConditionalScenes request            05 26 09 01 09 01 00
 GetLightingSceneStatus reply                           04 12 09 01 01 07 09 80 02 01 01 08 00
 GetLightingSceneStatus request                         04 12 09 01 00
@@ -71,7 +71,7 @@ PutLightingOverlayChunk inner Err(TransactionExpired)  04 0e 09 01 03 01 0a 00
 PutLightingOverlayChunk reply                          04 0e 09 01 01 01 00
 PutLightingOverlayChunk request                        05 0e 09 01 0d 0f 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
 PutLightingRuntimeConditionalSceneChunk reply          04 28 09 01 01 01 00
-PutLightingRuntimeConditionalSceneChunk request        05 28 09 01 1f 0d 01 01 02 01 01 01 01 14 01 50 02 2a 04 07 08 09 00
+PutLightingRuntimeConditionalSceneChunk request        05 28 09 01 1f 0c 01 01 02 01 01 01 01 14 01 50 02 02 2a 04 07 08 09 00
 PutLightingSceneChunk reply                            04 17 09 01 01 01 00
 PutLightingSceneChunk request                          05 17 09 01 15 04 01 02 2a 04 07 08 09 00
 SetLightingExtensionParam reply                        04 2c 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 3af145aed..8b6466038 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1392,6 +1392,7 @@ fn lighting_wire_frames_locked() {
                 max_level: Some(80),
                 charge: LightingChargeCondition::Discharging,
             }),
+            output_mode: None,
         },
         led_id: led.id,
         effect: scene_cell.effect,
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 1c7c6d28c..00566f124 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -1368,6 +1368,7 @@ mod tests {
                 max_level: Some(40),
                 charge: ChargeCondition::Discharging,
             }),
+            output_mode: None,
         },
         slot: crate::lighting::LedSlot(0),
         effect: BuiltinEffect::Solid {
@@ -1433,7 +1434,9 @@ mod tests {
         // header + postcard payload.
         let header = RynkHeader { cmd: E::CMD, seq: 1 };
         buffer[..RYNK_HEADER_SIZE].copy_from_slice(&header.to_bytes());
-        let payload_len = postcard::to_slice(request, &mut buffer[RYNK_HEADER_SIZE..]).unwrap().len();
+        let payload_len = postcard::to_slice(request, &mut buffer[RYNK_HEADER_SIZE..])
+            .unwrap()
+            .len();
         let req_len = RYNK_HEADER_SIZE + payload_len;
         let mut message = RynkMessage::from_decoded(&mut buffer[..], req_len);
         service.dispatch(session, &mut message).await.unwrap();
@@ -2271,6 +2274,7 @@ mod tests {
                     conditions: rmk_types::protocol::rynk::LightingConditionSet {
                         layer: Some(rmk_types::protocol::rynk::LightingLayerCondition { layer: 1, active: true }),
                         battery: None,
+                        output_mode: None,
                     },
                     led_id: LightingLedId(42),
                     effect: rmk_types::protocol::rynk::LightingEffect::Solid {
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 945e786d4..ba43fd25c 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -1459,7 +1459,8 @@ fn effect_to_wire(effect: BuiltinEffect) -> rmk_types::protocol::rynk::LightingE
 
 fn condition_set_to_wire(conditions: crate::lighting::ConditionSet) -> rmk_types::protocol::rynk::LightingConditionSet {
     use rmk_types::protocol::rynk::{
-        LightingBatteryCondition, LightingChargeCondition, LightingConditionSet, LightingLayerCondition, LightingNodeId,
+        LightingBatteryCondition, LightingChargeCondition, LightingConditionSet, LightingLayerCondition,
+        LightingNodeId, LightingOutputMode,
     };
 
     use crate::lighting::ChargeCondition;
@@ -1480,6 +1481,11 @@ fn condition_set_to_wire(conditions: crate::lighting::ConditionSet) -> rmk_types
                 ChargeCondition::Unknown => LightingChargeCondition::Unknown,
             },
         }),
+        output_mode: conditions.output_mode.map(|mode| match mode {
+            crate::lighting::OutputMode::AlwaysOn => LightingOutputMode::AlwaysOn,
+            crate::lighting::OutputMode::AlwaysOff => LightingOutputMode::AlwaysOff,
+            crate::lighting::OutputMode::PoweredOnly => LightingOutputMode::PoweredOnly,
+        }),
     }
 }
 
@@ -1506,6 +1512,11 @@ fn condition_set_from_wire(
                 LightingChargeCondition::Unknown => ChargeCondition::Unknown,
             },
         }),
+        output_mode: conditions.output_mode.map(|mode| match mode {
+            rmk_types::protocol::rynk::LightingOutputMode::AlwaysOn => crate::lighting::OutputMode::AlwaysOn,
+            rmk_types::protocol::rynk::LightingOutputMode::AlwaysOff => crate::lighting::OutputMode::AlwaysOff,
+            rmk_types::protocol::rynk::LightingOutputMode::PoweredOnly => crate::lighting::OutputMode::PoweredOnly,
+        }),
     }
 }
 
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index 72207ffb3..1b030be6a 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -181,6 +181,10 @@ pub struct BatteryCondition {
 pub struct ConditionSet {
     pub layer: Option<LayerCondition>,
     pub battery: Option<BatteryCondition>,
+    /// Satisfied when the live output-mode policy equals this. Sources that
+    /// cannot observe the policy treat it as unsatisfiable rather than true,
+    /// so a rule gated on it never fires where it cannot be evaluated.
+    pub output_mode: Option<OutputMode>,
 }
 
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
@@ -242,11 +246,21 @@ pub struct LightingControls {
 }
 
 impl ConditionSet {
-    pub(crate) fn matches<Context, Batteries>(&self, context: &Context, batteries: &Batteries) -> bool
+    pub(crate) fn matches<Context, Batteries>(
+        &self,
+        context: &Context,
+        batteries: &Batteries,
+        output_mode: Option<OutputMode>,
+    ) -> bool
     where
         Context: LightingContextProvider,
         Batteries: BatteryStatusProvider + ?Sized,
     {
+        if let Some(wanted) = self.output_mode
+            && output_mode != Some(wanted)
+        {
+            return false;
+        }
         if let Some(condition) = self.layer
             && context.lighting_context().layers.is_active(condition.layer) != condition.active
         {
@@ -311,7 +325,7 @@ impl<'a, E, Batteries: ?Sized> ConditionalScenes<'a, E, Batteries> {
         for cell in self
             .cells
             .iter()
-            .filter(|cell| cell.conditions.matches(context, self.batteries))
+            .filter(|cell| cell.conditions.matches(context, self.batteries, None))
         {
             if wanted == 0 {
                 return cell;
@@ -331,7 +345,7 @@ where
     fn len(&self, input: &RenderInput<'_, Context>) -> usize {
         self.cells
             .iter()
-            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
+            .filter(|cell| cell.conditions.matches(input.context, self.batteries, None))
             .count()
     }
 
@@ -744,6 +758,7 @@ mod tests {
                         max_level: None,
                         charge: ChargeCondition::Any,
                     }),
+                    output_mode: None,
                 },
                 slot: LedSlot(0),
                 effect: BuiltinEffect::solid(GREEN),
@@ -757,6 +772,7 @@ mod tests {
                         max_level: None,
                         charge: ChargeCondition::Any,
                     }),
+                    output_mode: None,
                 },
                 slot: LedSlot(1),
                 effect: BuiltinEffect::solid(BLUE),
@@ -771,6 +787,7 @@ mod tests {
                         max_level: Some(40),
                         charge: ChargeCondition::Discharging,
                     }),
+                    output_mode: None,
                 },
                 slot: LedSlot(0),
                 effect: BuiltinEffect::solid(RED),
diff --git a/rmk/src/lighting/standard/conditional.rs b/rmk/src/lighting/standard/conditional.rs
index 112337363..359432af9 100644
--- a/rmk/src/lighting/standard/conditional.rs
+++ b/rmk/src/lighting/standard/conditional.rs
@@ -4,7 +4,7 @@ use crate::lighting::Rgb8;
 use crate::lighting::compositor::{Contribution, LightingSource, RenderInput as SourceRenderInput};
 use crate::lighting::context::LightingContextProvider;
 use crate::lighting::effect::{BuiltinEffect, LightingEffect};
-use crate::lighting::source::{BatteryStatusProvider, ConditionSet};
+use crate::lighting::source::{BatteryStatusProvider, ConditionSet, OutputMode};
 use crate::lighting::topology::LedSlot;
 
 /// One ordered, runtime-authored conditional rule.
@@ -19,6 +19,7 @@ pub(super) const EMPTY_CONDITIONAL_SCENE_CELL: RuntimeConditionalSceneCell = Run
     conditions: ConditionSet {
         layer: None,
         battery: None,
+        output_mode: None,
     },
     slot: LedSlot(0),
     effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
@@ -119,6 +120,9 @@ impl<const CAP: usize> Default for RuntimeConditionalSceneTable<CAP> {
 pub(super) struct RuntimeConditionalSource<'a, Batteries: ?Sized, const CAP: usize> {
     pub(super) table: &'a RuntimeConditionalSceneTable<CAP>,
     pub(super) batteries: &'a Batteries,
+    /// The engine owns the policy, so unlike the board's compiled source this
+    /// one can evaluate an output-mode condition.
+    pub(super) output_mode: OutputMode,
 }
 
 impl<Context, Batteries, const CAP: usize> LightingSource<Rgb8, Context>
@@ -131,7 +135,10 @@ where
         self.table
             .as_slice()
             .iter()
-            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
+            .filter(|cell| {
+                cell.conditions
+                    .matches(input.context, self.batteries, Some(self.output_mode))
+            })
             .count()
     }
 
@@ -139,7 +146,10 @@ where
         self.table
             .as_slice()
             .iter()
-            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
+            .filter(|cell| {
+                cell.conditions
+                    .matches(input.context, self.batteries, Some(self.output_mode))
+            })
             .nth(index)
             .expect("LightingSource index must be below len")
             .slot
@@ -150,7 +160,10 @@ where
             .table
             .as_slice()
             .iter()
-            .filter(|cell| cell.conditions.matches(input.context, self.batteries))
+            .filter(|cell| {
+                cell.conditions
+                    .matches(input.context, self.batteries, Some(self.output_mode))
+            })
             .nth(index)
             .expect("LightingSource index must be below len");
         Contribution::Opaque(cell.effect.sample(input.now_ms))
diff --git a/rmk/src/lighting/standard/engine.rs b/rmk/src/lighting/standard/engine.rs
index ae104bddf..cf00cd3f4 100644
--- a/rmk/src/lighting/standard/engine.rs
+++ b/rmk/src/lighting/standard/engine.rs
@@ -1181,6 +1181,9 @@ where
             slot: indicator.slot,
             effect: indicator.effect(self.output_mode),
         });
+        // Captured before the destructuring below borrows the rest of `self`;
+        // the runtime conditional source needs it to evaluate output-mode rules.
+        let output_mode = self.output_mode;
         let Self {
             compositor,
             background,
@@ -1222,6 +1225,7 @@ where
         let mut runtime_conditional_source = RuntimeConditionalSource {
             table: runtime_conditional_scenes,
             batteries: *battery_status,
+            output_mode,
         };
         transaction.apply(priority::STATUS, &mut runtime_conditional_source)?;
         if wake_active && let Some(indicator_cell) = indicator_cell.as_ref() {
diff --git a/rmk/src/lighting/standard/tests.rs b/rmk/src/lighting/standard/tests.rs
index 42be94fe6..9c0e2632a 100644
--- a/rmk/src/lighting/standard/tests.rs
+++ b/rmk/src/lighting/standard/tests.rs
@@ -1471,6 +1471,7 @@ fn runtime_conditional_replace_preserves_order_and_output_mode_is_revision_check
                     max_level: Some(75),
                     charge: ChargeCondition::Discharging,
                 }),
+                output_mode: None,
             },
             slot: LedSlot(1),
             effect: BuiltinEffect::Solid { color: RED },
@@ -1481,6 +1482,7 @@ fn runtime_conditional_replace_preserves_order_and_output_mode_is_revision_check
             conditions: ConditionSet {
                 layer: Some(LayerCondition { layer: 0, active: true }),
                 battery: None,
+                output_mode: None,
             },
             slot: LedSlot(1),
             effect: BuiltinEffect::Solid { color: GREEN },
@@ -1623,6 +1625,77 @@ fn repainting_a_cell_does_not_strand_styles() {
     assert_eq!(table.len(), 1);
 }
 
+/// The point of the output-mode condition: the mode indicator stops being
+/// something the board compiles in and becomes an ordinary runtime rule a host
+/// can edit. A rule gated on one policy lights only under that policy, and
+/// switching policy changes which rule is eligible without touching the table.
+#[test]
+fn output_mode_conditions_select_between_runtime_rules() {
+    let rule = |mode: OutputMode, color: Rgb8| RuntimeConditionalSceneCell {
+        conditions: ConditionSet {
+            layer: None,
+            battery: None,
+            output_mode: Some(mode),
+        },
+        slot: LedSlot(0),
+        effect: BuiltinEffect::Solid { color },
+    };
+
+    type ConditionalEngine = StandardLightingEngine<'static, EmptySource, EmptySource, 2, 2, 4>;
+    let mut engine: ConditionalEngine = StandardLightingEngine::new(
+        BackgroundState::default(),
+        LayerScenes {
+            scenes: &[],
+            policy: LayerPolicy::EffectiveOnly,
+        },
+        EmptySource,
+        EmptySource,
+    );
+    for cell in [rule(OutputMode::AlwaysOn, GREEN), rule(OutputMode::PoweredOnly, RED)] {
+        engine.install_runtime_conditional_scene_cell(cell).unwrap();
+    }
+
+    // Powered, so both AlwaysOn and PoweredOnly actually render; AlwaysOff
+    // would blank the frame outright and prove nothing about conditions.
+    let snapshot = LightingContext {
+        layers: LayerState::new(0, 0, 1),
+        indicators: Default::default(),
+        powered: true,
+    };
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    let mut render = |engine: &mut ConditionalEngine, frame: &mut LogicalFrame<Rgb8, 2>| {
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 0,
+                    snapshot: &snapshot,
+                },
+                frame,
+            )
+            .unwrap();
+    };
+
+    // AlwaysOn is the engine's starting policy, so only the green rule is
+    // eligible; the red one is filtered out rather than overpainted.
+    render(&mut engine, &mut frame);
+    assert_eq!(frame.as_slice()[0], GREEN);
+
+    // Flipping the policy swaps which rule matches, with no edit to the table.
+    let revision = engine.state().revision;
+    engine
+        .handle_command(
+            0,
+            StandardCommand::SetOutputModeIfRevision {
+                expected_revision: revision,
+                mode: OutputMode::PoweredOnly,
+            },
+            &snapshot,
+        )
+        .unwrap();
+    render(&mut engine, &mut frame);
+    assert_eq!(frame.as_slice()[0], RED);
+}
+
 #[test]
 fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules() {
     use rmk_types::battery::BatteryStatus;
@@ -1644,6 +1717,7 @@ fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules
         conditions: ConditionSet {
             layer: Some(LayerCondition { layer: 1, active: true }),
             battery: None,
+            output_mode: None,
         },
         slot: LedSlot(0),
         effect: BuiltinEffect::Solid { color: GREEN },
@@ -1692,6 +1766,7 @@ fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules
             conditions: ConditionSet {
                 layer: Some(LayerCondition { layer: 1, active: true }),
                 battery: None,
+                output_mode: None,
             },
             slot: LedSlot(0),
             effect: BuiltinEffect::Solid { color: BLUE },

From d4c370b15a0992a1d696408e6192e0a8b9a66e60 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 00:53:48 -0700
Subject: [PATCH 45/78] fix(lighting): tie the engine's conditional page size
 to the wire chunk

The engine paged 8 conditional cells into a wire Vec that holds 7 after the
output-mode field was added, so every readback of the runtime conditional
table was rejected outright. Nothing connected the two constants, which is
how they drifted; a const assertion now makes that drift a build error
instead of a protocol failure.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/lighting/standard/mod.rs | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/rmk/src/lighting/standard/mod.rs b/rmk/src/lighting/standard/mod.rs
index 261093425..ad49e35fc 100644
--- a/rmk/src/lighting/standard/mod.rs
+++ b/rmk/src/lighting/standard/mod.rs
@@ -14,7 +14,15 @@ pub const OVERLAY_CHUNK_SIZE: usize = 8;
 pub const SCENE_CHUNK_SIZE: usize = 8;
 
 /// Cells per runtime conditional-scene page/replacement chunk.
-pub const CONDITIONAL_SCENE_CHUNK_SIZE: usize = 8;
+pub const CONDITIONAL_SCENE_CHUNK_SIZE: usize = 7;
+
+/// The engine pages conditional cells into a wire-sized `Vec`, so paging more
+/// per page than the wire holds turns every readback into a rejected request.
+/// Nothing tied the two together before, which is exactly how that happened.
+const _: () = assert!(
+    CONDITIONAL_SCENE_CHUNK_SIZE == rmk_types::protocol::rynk::LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE,
+    "engine conditional page size must equal the wire chunk size"
+);
 
 /// A staged scene replacement expires after this much command inactivity.
 pub const SCENE_TRANSACTION_TIMEOUT_MS: u64 = 5_000;

From d6cf74c6960e8ee03ecc70380da431e142755353 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 00:55:21 -0700
Subject: [PATCH 46/78] fix(lighting): use core::assert in the const chunk-size
 check

With defmt enabled the bare macro resolves to defmt's assert, which is not
const-evaluable, so the firmware build failed where the host build passed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/lighting/standard/mod.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/rmk/src/lighting/standard/mod.rs b/rmk/src/lighting/standard/mod.rs
index ad49e35fc..6833ab5fb 100644
--- a/rmk/src/lighting/standard/mod.rs
+++ b/rmk/src/lighting/standard/mod.rs
@@ -19,7 +19,9 @@ pub const CONDITIONAL_SCENE_CHUNK_SIZE: usize = 7;
 /// The engine pages conditional cells into a wire-sized `Vec`, so paging more
 /// per page than the wire holds turns every readback into a rejected request.
 /// Nothing tied the two together before, which is exactly how that happened.
-const _: () = assert!(
+// `core::assert!` explicitly: with defmt enabled the bare macro resolves to
+// defmt's, which is not const-evaluable.
+const _: () = core::assert!(
     CONDITIONAL_SCENE_CHUNK_SIZE == rmk_types::protocol::rynk::LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE,
     "engine conditional page size must equal the wire chunk size"
 );

From 747c642e38d773d3003e5d13c065146e0df5e29b Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 01:37:18 -0700
Subject: [PATCH 47/78] feat(lighting): wake layers become a settable mask

Waking lighting was tied to one designated layer, compiled in as
Option<u8>, so 'hold Magic to see the board' could not be extended to any
other layer without rebuilding firmware.

It is a u64 mask now, which is both more general and cheaper: LayerState
already tracks active layers as a mask, so the check collapses to a single
AND instead of a per-layer test, and any combination of layers can wake.

SetLightingWakeLayers (0x092D) makes it dynamic, revision-pinned like the
other lighting mutations. Deliberately narrow rather than a general
controls setter: the wake mask is the field worth changing at runtime,
while the powered-only scope and the boot output mode are set once for a
board and stay compiled.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../main/docs/development/rynk_protocol.md    | 193 +++++++++---------
 rmk-types/src/protocol/rynk/command.rs        |   6 +-
 .../src/protocol/rynk/payload/lighting.rs     |  17 +-
 .../rynk/snapshots/lighting_wire_frames.snap  |   4 +-
 rmk-types/src/protocol/rynk/tests.rs          |   2 +-
 rmk/src/host/rynk/handlers/lighting.rs        |  28 ++-
 rmk/src/host/rynk/lighting.rs                 |  22 +-
 rmk/src/host/rynk/mod.rs                      |   4 +-
 rmk/src/lighting/source.rs                    |   7 +-
 rmk/src/lighting/standard/command.rs          |   5 +
 rmk/src/lighting/standard/engine.rs           |  13 +-
 rmk/src/lighting/standard/tests.rs            |  64 +++++-
 12 files changed, 247 insertions(+), 118 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 9f5f54624..7fd6ea176 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -26,102 +26,103 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 
 ## Endpoints
 
-| CMD      | Name                                           | Request                                               | Response                                           | Feature          | Notes                                                                                                                          |
-| -------- | ---------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `0x0001` | `GetVersion`                                   | `()`                                                  | `ProtocolVersion`                                  |                  |                                                                                                                                |
-| `0x0002` | `GetCapabilities`                              | `()`                                                  | `DeviceCapabilities`                               |                  |                                                                                                                                |
-| `0x0003` | `Reboot`                                       | `()`                                                  | `()`                                               |                  |                                                                                                                                |
-| `0x0004` | `BootloaderJump`                               | `()`                                                  | `()`                                               |                  |                                                                                                                                |
-| `0x0005` | `StorageReset`                                 | `StorageResetMode`                                    | `()`                                               |                  |                                                                                                                                |
-| `0x0006` | `GetLockStatus`                                | `()`                                                  | `LockStatus`                                       |                  | Pure read of the current lock state — no side effects.                                                                         |
-| `0x0007` | `UnlockPoll`                                   | `()`                                                  | `LockStatus`                                       |                  | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                         |
-| `0x0008` | `Lock`                                         | `()`                                                  | `()`                                               |                  | Relock immediately.                                                                                                            |
-| `0x0009` | `GetLayout`                                    | `u32`                                                 | `LayoutChunk`                                      |                  | Get layout blob chunk. `u32` is the byte offset.                                                                               |
-| `0x000A` | `GetDeviceInfo`                                | `()`                                                  | `DeviceInfo`                                       |                  | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                       |
-| `0x000B` | `GetBuildInfo`                                 | `()`                                                  | `BuildInfo`                                        |                  | Application-defined diagnostic build label; never used for compatibility.                                                      |
-| `0x000C` | `PeripheralBootloaderJump`                     | `u8`                                                  | `()`                                               |                  | Ask the application to route a bootloader jump to one split peripheral.                                                        |
-| `0x0101` | `GetKeyAction`                                 | `KeyPosition`                                         | `KeyAction`                                        |                  |                                                                                                                                |
-| `0x0102` | `SetKeyAction`                                 | `SetKeyRequest`                                       | `()`                                               |                  |                                                                                                                                |
-| `0x0103` | `GetDefaultLayer`                              | `()`                                                  | `u8`                                               |                  |                                                                                                                                |
-| `0x0104` | `SetDefaultLayer`                              | `u8`                                                  | `()`                                               |                  |                                                                                                                                |
-| `0x0105` | `GetEncoderAction`                             | `GetEncoderRequest`                                   | `EncoderAction`                                    |                  |                                                                                                                                |
-| `0x0106` | `SetEncoderAction`                             | `SetEncoderRequest`                                   | `()`                                               |                  |                                                                                                                                |
-| `0x0107` | `GetKeymapBulk`                                | `GetKeymapBulkRequest`                                | `GetKeymapBulkResponse`                            |                  |                                                                                                                                |
-| `0x0108` | `SetKeymapBulk`                                | `SetKeymapBulkRequest`                                | `()`                                               |                  |                                                                                                                                |
-| `0x0201` | `GetMacro`                                     | `GetMacroRequest`                                     | `MacroData`                                        |                  |                                                                                                                                |
-| `0x0202` | `SetMacro`                                     | `SetMacroRequest`                                     | `()`                                               |                  |                                                                                                                                |
-| `0x0301` | `GetCombo`                                     | `u8`                                                  | `Combo`                                            |                  |                                                                                                                                |
-| `0x0302` | `SetCombo`                                     | `SetComboRequest`                                     | `()`                                               |                  |                                                                                                                                |
-| `0x0303` | `GetComboBulk`                                 | `GetComboBulkRequest`                                 | `GetComboBulkResponse`                             |                  |                                                                                                                                |
-| `0x0304` | `SetComboBulk`                                 | `SetComboBulkRequest`                                 | `()`                                               |                  |                                                                                                                                |
-| `0x0401` | `GetMorse`                                     | `u8`                                                  | `Morse`                                            |                  |                                                                                                                                |
-| `0x0402` | `SetMorse`                                     | `SetMorseRequest`                                     | `()`                                               |                  |                                                                                                                                |
-| `0x0403` | `GetMorseBulk`                                 | `GetMorseBulkRequest`                                 | `GetMorseBulkResponse`                             |                  |                                                                                                                                |
-| `0x0404` | `SetMorseBulk`                                 | `SetMorseBulkRequest`                                 | `()`                                               |                  |                                                                                                                                |
-| `0x0501` | `GetFork`                                      | `u8`                                                  | `Fork`                                             |                  |                                                                                                                                |
-| `0x0502` | `SetFork`                                      | `SetForkRequest`                                      | `()`                                               |                  |                                                                                                                                |
-| `0x0601` | `GetBehaviorConfig`                            | `()`                                                  | `BehaviorConfig`                                   |                  |                                                                                                                                |
-| `0x0602` | `SetBehaviorConfig`                            | `BehaviorConfig`                                      | `()`                                               |                  |                                                                                                                                |
-| `0x0701` | `GetConnectionType`                            | `()`                                                  | `ConnectionType`                                   |                  |                                                                                                                                |
-| `0x0702` | `GetConnectionStatus`                          | `()`                                                  | `ConnectionStatus`                                 |                  | Full `ConnectionStatus` snapshot.                                                                                              |
-| `0x0703` | `GetBleStatus`                                 | `()`                                                  | `BleStatus`                                        | `_ble`           |                                                                                                                                |
-| `0x0704` | `SwitchBleProfile`                             | `u8`                                                  | `()`                                               | `_ble`           |                                                                                                                                |
-| `0x0705` | `ClearBleProfile`                              | `u8`                                                  | `()`                                               | `_ble`           |                                                                                                                                |
-| `0x0706` | `GetSplitCentralLatency`                       | `()`                                                  | `SplitCentralLatencyState`                         | `_ble` + `split` | Read the volatile active-mode policy, current USB-power selection, and effective value.                                        |
-| `0x0707` | `SetSplitCentralLatency`                       | `SplitCentralLatencyPolicy`                           | `SplitCentralLatencyState`                         | `_ble` + `split` | Replace the volatile policy. Each connection-event count must be `0..=499`.                                                    |
-| `0x0801` | `GetCurrentLayer`                              | `()`                                                  | `u8`                                               |                  |                                                                                                                                |
-| `0x0802` | `GetMatrixState`                               | `()`                                                  | `MatrixState`                                      |                  |                                                                                                                                |
-| `0x0803` | `GetBatteryStatus`                             | `()`                                                  | `BatteryStatus`                                    | `_ble`           |                                                                                                                                |
-| `0x0804` | `GetPeripheralStatus`                          | `u8`                                                  | `PeripheralStatus`                                 | `split`          |                                                                                                                                |
-| `0x0805` | `GetWpm`                                       | `()`                                                  | `u16`                                              |                  | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                       |
-| `0x0806` | `GetSleepState`                                | `()`                                                  | `bool`                                             |                  | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                               |
-| `0x0807` | `GetLedIndicator`                              | `()`                                                  | `LedIndicator`                                     |                  | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                   |
-| `0x0808` | `GetLayerState`                                | `()`                                                  | `LayerState`                                       |                  | Default layer and complete active-layer bitmap.                                                                                |
-| `0x0809` | `GetModifierState`                             | `()`                                                  | `ModifierCombination`                              |                  | Final resolved modifier bitmap used by the HID keyboard report.                                                                |
-| `0x0901` | `GetLightingCapabilities`                      | `()`                                                  | `LightingCapabilitiesResult`                       | `lighting`       |                                                                                                                                |
-| `0x0902` | `GetLightingState`                             | `()`                                                  | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
-| `0x0903` | `SetLightingState`                             | `SetLightingStateRequest`                             | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
-| `0x0904` | `GetLightingPhysicalKeys`                      | `LightingPageRequest`                                 | `LightingPhysicalKeysPageResult`                   | `lighting`       |                                                                                                                                |
-| `0x0905` | `GetLightingLeds`                              | `LightingPageRequest`                                 | `LightingLedsPageResult`                           | `lighting`       |                                                                                                                                |
-| `0x0906` | `GetLightingZones`                             | `LightingPageRequest`                                 | `LightingZonesPageResult`                          | `lighting`       |                                                                                                                                |
-| `0x0907` | `GetLightingZoneMemberships`                   | `LightingPageRequest`                                 | `LightingZoneMembershipsPageResult`                | `lighting`       |                                                                                                                                |
-| `0x0908` | `GetLightingOutputs`                           | `LightingPageRequest`                                 | `LightingOutputsPageResult`                        | `lighting`       |                                                                                                                                |
-| `0x0909` | `GetLightingRoutes`                            | `LightingPageRequest`                                 | `LightingRoutesPageResult`                         | `lighting`       |                                                                                                                                |
-| `0x090A` | `SetLightingOverlay`                           | `SetLightingOverlayRequest`                           | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
-| `0x090B` | `UnsetLightingOverlay`                         | `UnsetLightingOverlayRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
-| `0x090C` | `ClearLightingOverlay`                         | `ClearLightingOverlayRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
-| `0x090D` | `BeginLightingOverlayReplace`                  | `BeginLightingOverlayReplaceRequest`                  | `LightingOverlayTransactionResult`                 | `lighting`       |                                                                                                                                |
-| `0x090E` | `PutLightingOverlayChunk`                      | `PutLightingOverlayChunkRequest`                      | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
-| `0x090F` | `CommitLightingOverlayReplace`                 | `CommitLightingOverlayReplaceRequest`                 | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
-| `0x0910` | `AbortLightingOverlayReplace`                  | `AbortLightingOverlayReplaceRequest`                  | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
-| `0x0911` | `GetLightingKeys`                              | `LightingPageRequest`                                 | `LightingKeysPageResult`                           | `lighting`       | Logical matrix keys are distinct from optional physical geometry.                                                              |
-| `0x0912` | `GetLightingSceneStatus`                       | `()`                                                  | `LightingSceneStatusResult`                        | `lighting`       | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts. |
-| `0x0913` | `GetLightingScenes`                            | `LightingScenePageRequest`                            | `LightingScenesPageResult`                         | `lighting`       | Scene pages are pinned to `LightingState.revision` for consistency.                                                            |
-| `0x0914` | `SetLightingSceneCell`                         | `SetLightingSceneCellRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
-| `0x0915` | `UnsetLightingSceneCell`                       | `UnsetLightingSceneCellRequest`                       | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
-| `0x0916` | `BeginLightingSceneReplace`                    | `BeginLightingSceneReplaceRequest`                    | `LightingSceneTransactionResult`                   | `lighting`       |                                                                                                                                |
-| `0x0917` | `PutLightingSceneChunk`                        | `PutLightingSceneChunkRequest`                        | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
-| `0x0918` | `CommitLightingSceneReplace`                   | `CommitLightingSceneReplaceRequest`                   | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
-| `0x0919` | `AbortLightingSceneReplace`                    | `AbortLightingSceneReplaceRequest`                    | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
-| `0x091A` | `SetLightingLayerPolicy`                       | `SetLightingLayerPolicyRequest`                       | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
-| `0x091B` | `GetLightingOverlay`                           | `LightingOverlayPageRequest`                          | `LightingOverlayPageResult`                        | `lighting`       | Overlay pages are pinned to `LightingState.revision` for consistency.                                                          |
-| `0x091C` | `GetLightingCompiledSceneStatus`               | `()`                                                  | `LightingCompiledSceneStatusResult`                | `lighting`       | Discover the immutable board-compiled layer-scene source.                                                                      |
-| `0x091D` | `GetLightingCompiledScenes`                    | `LightingPageRequest`                                 | `LightingCompiledScenesPageResult`                 | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                             |
-| `0x091E` | `GetLightingConditionalSceneStatus`            | `()`                                                  | `LightingConditionalSceneStatusResult`             | `lighting`       | Discover immutable conditional lighting compiled from board config.                                                            |
-| `0x091F` | `GetLightingConditionalScenes`                 | `LightingPageRequest`                                 | `LightingConditionalScenesPageResult`              | `lighting`       | Conditional-scene pages are pinned to the firmware topology revision.                                                          |
-| `0x0920` | `GetLightingOutputMode`                        | `()`                                                  | `LightingOutputModeStateResult`                    | `lighting`       | Read the configured three-state output policy and its live state.                                                              |
-| `0x0921` | `GetLightingExtension`                         | `()`                                                  | `LightingExtensionResult`                          | `lighting`       | Discover the animated extension band: name-list sizes and selection.                                                           |
-| `0x0922` | `GetLightingExtensionNames`                    | `LightingExtensionNamesRequest`                       | `LightingExtensionNamesPageResult`                 | `lighting`       | Extension names are static per firmware build; page until `total`.                                                             |
-| `0x0923` | `SetLightingExtensionState`                    | `SetLightingExtensionStateRequest`                    | `LightingStateResult`                              | `lighting`       | Replace the extension selection when the state revision matches.                                                               |
-| `0x0924` | `SetLightingOutputMode`                        | `SetLightingOutputModeRequest`                        | `LightingOutputModeStateResult`                    | `lighting`       | Set the three-state output policy with optimistic concurrency.                                                                 |
-| `0x0925` | `GetLightingRuntimeConditionalSceneStatus`     | `()`                                                  | `LightingRuntimeConditionalSceneStatusResult`      | `lighting`       | Discover the mutable ordered conditional-scene table.                                                                          |
-| `0x0926` | `GetLightingRuntimeConditionalScenes`          | `LightingRuntimeConditionalScenePageRequest`          | `LightingRuntimeConditionalScenesPageResult`       | `lighting`       | Runtime conditional pages are pinned to `LightingState.revision`.                                                              |
-| `0x0927` | `BeginLightingRuntimeConditionalSceneReplace`  | `BeginLightingRuntimeConditionalSceneReplaceRequest`  | `LightingRuntimeConditionalSceneTransactionResult` | `lighting`       |                                                                                                                                |
-| `0x0928` | `PutLightingRuntimeConditionalSceneChunk`      | `PutLightingRuntimeConditionalSceneChunkRequest`      | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
-| `0x0929` | `CommitLightingRuntimeConditionalSceneReplace` | `CommitLightingRuntimeConditionalSceneReplaceRequest` | `LightingStateResult`                              | `lighting`       |                                                                                                                                |
-| `0x092A` | `AbortLightingRuntimeConditionalSceneReplace`  | `AbortLightingRuntimeConditionalSceneReplaceRequest`  | `LightingUnitResult`                               | `lighting`       |                                                                                                                                |
-| `0x092B` | `GetLightingExtensionParams`                   | `LightingExtensionParamsRequest`                      | `LightingExtensionParamsPageResult`                | `lighting`       | Per-effect tunable parameters: descriptors plus live values, pinned to `LightingState.revision`. Page until `total`.           |
-| `0x092C` | `SetLightingExtensionParam`                    | `SetLightingExtensionParamRequest`                    | `LightingStateResult`                              | `lighting`       | Set one effect parameter when the state revision matches.                                                                      |
+| CMD      | Name                                           | Request                                               | Response                                           | Feature          | Notes                                                                                                                                  |
+| -------- | ---------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `0x0001` | `GetVersion`                                   | `()`                                                  | `ProtocolVersion`                                  |                  |                                                                                                                                        |
+| `0x0002` | `GetCapabilities`                              | `()`                                                  | `DeviceCapabilities`                               |                  |                                                                                                                                        |
+| `0x0003` | `Reboot`                                       | `()`                                                  | `()`                                               |                  |                                                                                                                                        |
+| `0x0004` | `BootloaderJump`                               | `()`                                                  | `()`                                               |                  |                                                                                                                                        |
+| `0x0005` | `StorageReset`                                 | `StorageResetMode`                                    | `()`                                               |                  |                                                                                                                                        |
+| `0x0006` | `GetLockStatus`                                | `()`                                                  | `LockStatus`                                       |                  | Pure read of the current lock state — no side effects.                                                                                 |
+| `0x0007` | `UnlockPoll`                                   | `()`                                                  | `LockStatus`                                       |                  | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                                 |
+| `0x0008` | `Lock`                                         | `()`                                                  | `()`                                               |                  | Relock immediately.                                                                                                                    |
+| `0x0009` | `GetLayout`                                    | `u32`                                                 | `LayoutChunk`                                      |                  | Get layout blob chunk. `u32` is the byte offset.                                                                                       |
+| `0x000A` | `GetDeviceInfo`                                | `()`                                                  | `DeviceInfo`                                       |                  | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                               |
+| `0x000B` | `GetBuildInfo`                                 | `()`                                                  | `BuildInfo`                                        |                  | Application-defined diagnostic build label; never used for compatibility.                                                              |
+| `0x000C` | `PeripheralBootloaderJump`                     | `u8`                                                  | `()`                                               |                  | Ask the application to route a bootloader jump to one split peripheral.                                                                |
+| `0x0101` | `GetKeyAction`                                 | `KeyPosition`                                         | `KeyAction`                                        |                  |                                                                                                                                        |
+| `0x0102` | `SetKeyAction`                                 | `SetKeyRequest`                                       | `()`                                               |                  |                                                                                                                                        |
+| `0x0103` | `GetDefaultLayer`                              | `()`                                                  | `u8`                                               |                  |                                                                                                                                        |
+| `0x0104` | `SetDefaultLayer`                              | `u8`                                                  | `()`                                               |                  |                                                                                                                                        |
+| `0x0105` | `GetEncoderAction`                             | `GetEncoderRequest`                                   | `EncoderAction`                                    |                  |                                                                                                                                        |
+| `0x0106` | `SetEncoderAction`                             | `SetEncoderRequest`                                   | `()`                                               |                  |                                                                                                                                        |
+| `0x0107` | `GetKeymapBulk`                                | `GetKeymapBulkRequest`                                | `GetKeymapBulkResponse`                            |                  |                                                                                                                                        |
+| `0x0108` | `SetKeymapBulk`                                | `SetKeymapBulkRequest`                                | `()`                                               |                  |                                                                                                                                        |
+| `0x0201` | `GetMacro`                                     | `GetMacroRequest`                                     | `MacroData`                                        |                  |                                                                                                                                        |
+| `0x0202` | `SetMacro`                                     | `SetMacroRequest`                                     | `()`                                               |                  |                                                                                                                                        |
+| `0x0301` | `GetCombo`                                     | `u8`                                                  | `Combo`                                            |                  |                                                                                                                                        |
+| `0x0302` | `SetCombo`                                     | `SetComboRequest`                                     | `()`                                               |                  |                                                                                                                                        |
+| `0x0303` | `GetComboBulk`                                 | `GetComboBulkRequest`                                 | `GetComboBulkResponse`                             |                  |                                                                                                                                        |
+| `0x0304` | `SetComboBulk`                                 | `SetComboBulkRequest`                                 | `()`                                               |                  |                                                                                                                                        |
+| `0x0401` | `GetMorse`                                     | `u8`                                                  | `Morse`                                            |                  |                                                                                                                                        |
+| `0x0402` | `SetMorse`                                     | `SetMorseRequest`                                     | `()`                                               |                  |                                                                                                                                        |
+| `0x0403` | `GetMorseBulk`                                 | `GetMorseBulkRequest`                                 | `GetMorseBulkResponse`                             |                  |                                                                                                                                        |
+| `0x0404` | `SetMorseBulk`                                 | `SetMorseBulkRequest`                                 | `()`                                               |                  |                                                                                                                                        |
+| `0x0501` | `GetFork`                                      | `u8`                                                  | `Fork`                                             |                  |                                                                                                                                        |
+| `0x0502` | `SetFork`                                      | `SetForkRequest`                                      | `()`                                               |                  |                                                                                                                                        |
+| `0x0601` | `GetBehaviorConfig`                            | `()`                                                  | `BehaviorConfig`                                   |                  |                                                                                                                                        |
+| `0x0602` | `SetBehaviorConfig`                            | `BehaviorConfig`                                      | `()`                                               |                  |                                                                                                                                        |
+| `0x0701` | `GetConnectionType`                            | `()`                                                  | `ConnectionType`                                   |                  |                                                                                                                                        |
+| `0x0702` | `GetConnectionStatus`                          | `()`                                                  | `ConnectionStatus`                                 |                  | Full `ConnectionStatus` snapshot.                                                                                                      |
+| `0x0703` | `GetBleStatus`                                 | `()`                                                  | `BleStatus`                                        | `_ble`           |                                                                                                                                        |
+| `0x0704` | `SwitchBleProfile`                             | `u8`                                                  | `()`                                               | `_ble`           |                                                                                                                                        |
+| `0x0705` | `ClearBleProfile`                              | `u8`                                                  | `()`                                               | `_ble`           |                                                                                                                                        |
+| `0x0706` | `GetSplitCentralLatency`                       | `()`                                                  | `SplitCentralLatencyState`                         | `_ble` + `split` | Read the volatile active-mode policy, current USB-power selection, and effective value.                                                |
+| `0x0707` | `SetSplitCentralLatency`                       | `SplitCentralLatencyPolicy`                           | `SplitCentralLatencyState`                         | `_ble` + `split` | Replace the volatile policy. Each connection-event count must be `0..=499`.                                                            |
+| `0x0801` | `GetCurrentLayer`                              | `()`                                                  | `u8`                                               |                  |                                                                                                                                        |
+| `0x0802` | `GetMatrixState`                               | `()`                                                  | `MatrixState`                                      |                  |                                                                                                                                        |
+| `0x0803` | `GetBatteryStatus`                             | `()`                                                  | `BatteryStatus`                                    | `_ble`           |                                                                                                                                        |
+| `0x0804` | `GetPeripheralStatus`                          | `u8`                                                  | `PeripheralStatus`                                 | `split`          |                                                                                                                                        |
+| `0x0805` | `GetWpm`                                       | `()`                                                  | `u16`                                              |                  | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                               |
+| `0x0806` | `GetSleepState`                                | `()`                                                  | `bool`                                             |                  | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                                       |
+| `0x0807` | `GetLedIndicator`                              | `()`                                                  | `LedIndicator`                                     |                  | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                           |
+| `0x0808` | `GetLayerState`                                | `()`                                                  | `LayerState`                                       |                  | Default layer and complete active-layer bitmap.                                                                                        |
+| `0x0809` | `GetModifierState`                             | `()`                                                  | `ModifierCombination`                              |                  | Final resolved modifier bitmap used by the HID keyboard report.                                                                        |
+| `0x0901` | `GetLightingCapabilities`                      | `()`                                                  | `LightingCapabilitiesResult`                       | `lighting`       |                                                                                                                                        |
+| `0x0902` | `GetLightingState`                             | `()`                                                  | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
+| `0x0903` | `SetLightingState`                             | `SetLightingStateRequest`                             | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
+| `0x0904` | `GetLightingPhysicalKeys`                      | `LightingPageRequest`                                 | `LightingPhysicalKeysPageResult`                   | `lighting`       |                                                                                                                                        |
+| `0x0905` | `GetLightingLeds`                              | `LightingPageRequest`                                 | `LightingLedsPageResult`                           | `lighting`       |                                                                                                                                        |
+| `0x0906` | `GetLightingZones`                             | `LightingPageRequest`                                 | `LightingZonesPageResult`                          | `lighting`       |                                                                                                                                        |
+| `0x0907` | `GetLightingZoneMemberships`                   | `LightingPageRequest`                                 | `LightingZoneMembershipsPageResult`                | `lighting`       |                                                                                                                                        |
+| `0x0908` | `GetLightingOutputs`                           | `LightingPageRequest`                                 | `LightingOutputsPageResult`                        | `lighting`       |                                                                                                                                        |
+| `0x0909` | `GetLightingRoutes`                            | `LightingPageRequest`                                 | `LightingRoutesPageResult`                         | `lighting`       |                                                                                                                                        |
+| `0x090A` | `SetLightingOverlay`                           | `SetLightingOverlayRequest`                           | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
+| `0x090B` | `UnsetLightingOverlay`                         | `UnsetLightingOverlayRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
+| `0x090C` | `ClearLightingOverlay`                         | `ClearLightingOverlayRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
+| `0x090D` | `BeginLightingOverlayReplace`                  | `BeginLightingOverlayReplaceRequest`                  | `LightingOverlayTransactionResult`                 | `lighting`       |                                                                                                                                        |
+| `0x090E` | `PutLightingOverlayChunk`                      | `PutLightingOverlayChunkRequest`                      | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
+| `0x090F` | `CommitLightingOverlayReplace`                 | `CommitLightingOverlayReplaceRequest`                 | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
+| `0x0910` | `AbortLightingOverlayReplace`                  | `AbortLightingOverlayReplaceRequest`                  | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
+| `0x0911` | `GetLightingKeys`                              | `LightingPageRequest`                                 | `LightingKeysPageResult`                           | `lighting`       | Logical matrix keys are distinct from optional physical geometry.                                                                      |
+| `0x0912` | `GetLightingSceneStatus`                       | `()`                                                  | `LightingSceneStatusResult`                        | `lighting`       | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts.         |
+| `0x0913` | `GetLightingScenes`                            | `LightingScenePageRequest`                            | `LightingScenesPageResult`                         | `lighting`       | Scene pages are pinned to `LightingState.revision` for consistency.                                                                    |
+| `0x0914` | `SetLightingSceneCell`                         | `SetLightingSceneCellRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
+| `0x0915` | `UnsetLightingSceneCell`                       | `UnsetLightingSceneCellRequest`                       | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
+| `0x0916` | `BeginLightingSceneReplace`                    | `BeginLightingSceneReplaceRequest`                    | `LightingSceneTransactionResult`                   | `lighting`       |                                                                                                                                        |
+| `0x0917` | `PutLightingSceneChunk`                        | `PutLightingSceneChunkRequest`                        | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
+| `0x0918` | `CommitLightingSceneReplace`                   | `CommitLightingSceneReplaceRequest`                   | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
+| `0x0919` | `AbortLightingSceneReplace`                    | `AbortLightingSceneReplaceRequest`                    | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
+| `0x091A` | `SetLightingLayerPolicy`                       | `SetLightingLayerPolicyRequest`                       | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
+| `0x091B` | `GetLightingOverlay`                           | `LightingOverlayPageRequest`                          | `LightingOverlayPageResult`                        | `lighting`       | Overlay pages are pinned to `LightingState.revision` for consistency.                                                                  |
+| `0x091C` | `GetLightingCompiledSceneStatus`               | `()`                                                  | `LightingCompiledSceneStatusResult`                | `lighting`       | Discover the immutable board-compiled layer-scene source.                                                                              |
+| `0x091D` | `GetLightingCompiledScenes`                    | `LightingPageRequest`                                 | `LightingCompiledScenesPageResult`                 | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                                     |
+| `0x091E` | `GetLightingConditionalSceneStatus`            | `()`                                                  | `LightingConditionalSceneStatusResult`             | `lighting`       | Discover immutable conditional lighting compiled from board config.                                                                    |
+| `0x091F` | `GetLightingConditionalScenes`                 | `LightingPageRequest`                                 | `LightingConditionalScenesPageResult`              | `lighting`       | Conditional-scene pages are pinned to the firmware topology revision.                                                                  |
+| `0x0920` | `GetLightingOutputMode`                        | `()`                                                  | `LightingOutputModeStateResult`                    | `lighting`       | Read the configured three-state output policy and its live state.                                                                      |
+| `0x0921` | `GetLightingExtension`                         | `()`                                                  | `LightingExtensionResult`                          | `lighting`       | Discover the animated extension band: name-list sizes and selection.                                                                   |
+| `0x0922` | `GetLightingExtensionNames`                    | `LightingExtensionNamesRequest`                       | `LightingExtensionNamesPageResult`                 | `lighting`       | Extension names are static per firmware build; page until `total`.                                                                     |
+| `0x0923` | `SetLightingExtensionState`                    | `SetLightingExtensionStateRequest`                    | `LightingStateResult`                              | `lighting`       | Replace the extension selection when the state revision matches.                                                                       |
+| `0x0924` | `SetLightingOutputMode`                        | `SetLightingOutputModeRequest`                        | `LightingOutputModeStateResult`                    | `lighting`       | Set the three-state output policy with optimistic concurrency.                                                                         |
+| `0x0925` | `GetLightingRuntimeConditionalSceneStatus`     | `()`                                                  | `LightingRuntimeConditionalSceneStatusResult`      | `lighting`       | Discover the mutable ordered conditional-scene table.                                                                                  |
+| `0x0926` | `GetLightingRuntimeConditionalScenes`          | `LightingRuntimeConditionalScenePageRequest`          | `LightingRuntimeConditionalScenesPageResult`       | `lighting`       | Runtime conditional pages are pinned to `LightingState.revision`.                                                                      |
+| `0x0927` | `BeginLightingRuntimeConditionalSceneReplace`  | `BeginLightingRuntimeConditionalSceneReplaceRequest`  | `LightingRuntimeConditionalSceneTransactionResult` | `lighting`       |                                                                                                                                        |
+| `0x0928` | `PutLightingRuntimeConditionalSceneChunk`      | `PutLightingRuntimeConditionalSceneChunkRequest`      | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
+| `0x0929` | `CommitLightingRuntimeConditionalSceneReplace` | `CommitLightingRuntimeConditionalSceneReplaceRequest` | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
+| `0x092A` | `AbortLightingRuntimeConditionalSceneReplace`  | `AbortLightingRuntimeConditionalSceneReplaceRequest`  | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
+| `0x092B` | `GetLightingExtensionParams`                   | `LightingExtensionParamsRequest`                      | `LightingExtensionParamsPageResult`                | `lighting`       | Per-effect tunable parameters: descriptors plus live values, pinned to `LightingState.revision`. Page until `total`.                   |
+| `0x092C` | `SetLightingExtensionParam`                    | `SetLightingExtensionParamRequest`                    | `LightingStateResult`                              | `lighting`       | Set one effect parameter when the state revision matches.                                                                              |
+| `0x092D` | `SetLightingWakeLayers`                        | `SetLightingWakeLayersRequest`                        | `LightingOutputModeStateResult`                    | `lighting`       | Replace the wake-layer mask. Policy rather than lighting content, but dynamic so which layers wake lighting is not a firmware rebuild. |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 3e282ff89..028ea6f49 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -52,7 +52,7 @@ use crate::protocol::rynk::{
     PutLightingOverlayChunkRequest, PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest,
     SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
     SetLightingOutputModeRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
-    UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
+    SetLightingWakeLayersRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 #[cfg(all(feature = "_ble", feature = "split"))]
 use crate::protocol::rynk::{SplitCentralLatencyPolicy, SplitCentralLatencyState};
@@ -485,6 +485,10 @@ endpoints! {
     /// Set one effect parameter when the state revision matches.
     #[cfg(feature = "lighting")]
     SetLightingExtensionParam = 0x092C: SetLightingExtensionParamRequest => LightingStateResult;
+    /// Replace the wake-layer mask. Policy rather than lighting content, but
+    /// dynamic so which layers wake lighting is not a firmware rebuild.
+    #[cfg(feature = "lighting")]
+    SetLightingWakeLayers = 0x092D: SetLightingWakeLayersRequest => LightingOutputModeStateResult;
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 20abe013d..c5ca2d069 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -654,7 +654,9 @@ wire_type! {
     /// Key/layer controls that gate the configured lighting presentation.
     pub struct LightingControls {
         pub output_toggle_user_action: Option<u8>,
-        pub wake_layer: Option<u8>,
+        /// Layers that wake lighting while held, as a bitmask. A set rather
+        /// than a single layer so waking is not tied to one "magic" layer.
+        pub wake_layers: u64,
     }
 }
 
@@ -695,7 +697,9 @@ wire_type! {
         pub effective_enabled: bool,
         pub powered_only_scope: LightingPoweredOnlyScope,
         pub cycle_user_action: Option<u8>,
-        pub wake_layer: Option<u8>,
+        /// Layers that wake lighting while held, as a bitmask. A set rather
+        /// than a single layer so waking is not tied to one "magic" layer.
+        pub wake_layers: u64,
         pub indicator: Option<LightingOutputModeIndicator>,
     }
 }
@@ -891,6 +895,15 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Replace the set of layers that wake lighting while held. A mask, so any
+    /// combination of layers can wake it rather than one designated layer.
+    pub struct SetLightingWakeLayersRequest {
+        pub expected_revision: u32,
+        pub layers: u64,
+    }
+}
+
 wire_type! {
     pub struct BeginLightingRuntimeConditionalSceneReplaceRequest {
         pub expected_revision: u32,
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index db1fc255e..0fc123226 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -42,7 +42,7 @@ GetLightingKeys reply                                  04 11 09 01 01 06 01 01 0
 GetLightingKeys request                                05 11 09 01 01 01 00
 GetLightingLeds reply                                  04 05 09 01 01 11 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01 00
 GetLightingLeds request                                05 05 09 01 01 01 00
-GetLightingOutputMode reply                            04 20 09 01 01 03 02 01 09 01 01 01 0d 01 02 01 2a 01 02 09 01 02 09 01 01 01 01 02 09 00
+GetLightingOutputMode reply                            04 20 09 01 01 03 02 01 08 01 01 01 0d 04 01 2a 01 02 09 01 02 09 01 01 01 01 02 09 00
 GetLightingOutputMode request                          04 20 09 01 00
 GetLightingOutputs reply                               04 08 09 01 01 08 01 01 01 01 02 28 14 01 00
 GetLightingOutputs request                             05 08 09 01 01 01 00
@@ -80,7 +80,7 @@ SetLightingExtensionState reply                        04 23 09 01 01 0b 09 01 c
 SetLightingExtensionState request                      09 23 09 01 09 01 02 03 04 00
 SetLightingLayerPolicy reply                           04 1a 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
 SetLightingLayerPolicy request                         05 1a 09 01 0b 01 00
-SetLightingOutputMode reply                            04 24 09 01 01 03 02 01 09 01 01 01 0d 01 02 01 2a 01 02 09 01 02 09 01 01 01 01 02 09 00
+SetLightingOutputMode reply                            04 24 09 01 01 03 02 01 08 01 01 01 0d 04 01 2a 01 02 09 01 02 09 01 01 01 01 02 09 00
 SetLightingOutputMode request                          06 24 09 01 09 01 00
 SetLightingOverlay inner Err(UnknownLed)               04 0a 09 01 05 01 06 e7 07 00
 SetLightingOverlay outer Err(Locked)                   06 0a 09 01 01 07 00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 8b6466038..f7a52738b 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1365,7 +1365,7 @@ fn lighting_wire_frames_locked() {
         effective_enabled: true,
         powered_only_scope: LightingPoweredOnlyScope::Local,
         cycle_user_action: Some(13),
-        wake_layer: Some(2),
+        wake_layers: 1 << 2,
         indicator: Some(LightingOutputModeIndicator {
             led_id: led.id,
             always_on: LightingEffect::Solid {
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 00566f124..1e43e4810 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -12,7 +12,7 @@ use rmk_types::protocol::rynk::command::{
     GetLightingScenes, GetLightingState, GetLightingZoneMemberships, GetLightingZones,
     PutLightingRuntimeConditionalSceneChunk, SetLightingExtensionParam, SetLightingExtensionState,
     SetLightingLayerPolicy, SetLightingOutputMode, SetLightingOverlay, SetLightingSceneCell, SetLightingState,
-    UnsetLightingOverlay, UnsetLightingSceneCell,
+    SetLightingWakeLayers, UnsetLightingOverlay, UnsetLightingSceneCell,
 };
 use rmk_types::protocol::rynk::{
     AbortLightingOverlayReplaceRequest, AbortLightingRuntimeConditionalSceneReplaceRequest,
@@ -41,7 +41,7 @@ use rmk_types::protocol::rynk::{
     PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, RynkError, RynkMessage,
     SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
     SetLightingOutputModeRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
-    UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
+    SetLightingWakeLayersRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 
 use super::super::lighting::{
@@ -134,6 +134,24 @@ impl Handle<SetLightingOutputMode> for RynkService<'_> {
     }
 }
 
+impl Handle<SetLightingWakeLayers> for RynkService<'_> {
+    async fn handle(&self, req: SetLightingWakeLayersRequest) -> Result<LightingOutputModeStateResult, RynkError> {
+        Ok(match controller(self) {
+            Ok(controller) => controller
+                .request(RynkLightingCommand::SetWakeLayers {
+                    expected_revision: req.expected_revision,
+                    layers: req.layers,
+                })
+                .await
+                .and_then(|reply| match reply {
+                    RynkLightingReadback::OutputMode(state) => Ok(controller.output_mode_to_wire(state)),
+                    _ => Err(LightingError::InvalidRequest),
+                }),
+            Err(error) => Err(error),
+        })
+    }
+}
+
 impl Handle<GetLightingOverlay> for RynkService<'_> {
     async fn handle(&self, req: LightingOverlayPageRequest) -> Result<LightingOverlayPageResult, RynkError> {
         let result = match controller(self) {
@@ -1899,7 +1917,7 @@ mod tests {
             let controls = LightingControls {
                 output_toggle_user_action: Some(13),
                 output_mode_cycle_user_action: Some(14),
-                wake_layer: Some(1),
+                wake_layers: 1 << 1,
                 initial_output_mode: OutputMode::PoweredOnly,
                 powered_only_scope: crate::lighting::PoweredOnlyScope::Local,
                 output_mode_indicator: Some(OutputModeIndicator {
@@ -1982,7 +2000,7 @@ mod tests {
                 assert_eq!(conditional_status.topology_revision, 7);
                 assert_eq!(conditional_status.cell_len, 1);
                 assert_eq!(conditional_status.controls.output_toggle_user_action, Some(13));
-                assert_eq!(conditional_status.controls.wake_layer, Some(1));
+                assert_eq!(conditional_status.controls.wake_layers, 1 << 1);
                 let output_mode = call::<GetLightingOutputMode>(&service, &session, &())
                     .await
                     .unwrap()
@@ -1992,7 +2010,7 @@ mod tests {
                     rmk_types::protocol::rynk::LightingOutputMode::PoweredOnly
                 );
                 assert_eq!(output_mode.cycle_user_action, Some(14));
-                assert_eq!(output_mode.wake_layer, Some(1));
+                assert_eq!(output_mode.wake_layers, 1 << 1);
                 assert_eq!(output_mode.indicator.unwrap().led_id, LightingLedId(10));
                 let conditional = call::<GetLightingConditionalScenes>(
                     &service,
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index ba43fd25c..1e68a558f 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -105,7 +105,7 @@ impl<'a> RynkLightingController<'a> {
             controls: LightingControls {
                 output_toggle_user_action: None,
                 output_mode_cycle_user_action: None,
-                wake_layer: None,
+                wake_layers: 0,
                 initial_output_mode: crate::lighting::OutputMode::AlwaysOn,
                 powered_only_scope: crate::lighting::PoweredOnlyScope::Authority,
                 output_mode_indicator: None,
@@ -149,7 +149,7 @@ impl<'a> RynkLightingController<'a> {
     pub(super) const fn controls_to_wire(&self) -> WireLightingControls {
         WireLightingControls {
             output_toggle_user_action: self.controls.output_toggle_user_action,
-            wake_layer: self.controls.wake_layer,
+            wake_layers: self.controls.wake_layers,
         }
     }
 
@@ -170,7 +170,7 @@ impl<'a> RynkLightingController<'a> {
                 crate::lighting::PoweredOnlyScope::Local => rmk_types::protocol::rynk::LightingPoweredOnlyScope::Local,
             },
             cycle_user_action: self.controls.output_mode_cycle_user_action,
-            wake_layer: self.controls.wake_layer,
+            wake_layers: self.controls.wake_layers,
             indicator: self.controls.output_mode_indicator.and_then(|indicator| {
                 self.descriptor
                     .topology
@@ -410,6 +410,10 @@ pub(super) enum RynkLightingCommand {
         expected_revision: u32,
         mode: WireLightingOutputMode,
     },
+    SetWakeLayers {
+        expected_revision: u32,
+        layers: u64,
+    },
     ReadOverlay {
         expected_revision: u32,
         offset: u16,
@@ -772,6 +776,18 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                     .await?;
                 return Ok(RynkLightingReadback::OutputMode(state));
             }
+            RynkLightingCommand::SetWakeLayers {
+                expected_revision,
+                layers,
+            } => {
+                let state = self
+                    .request_core_state(StandardCommand::SetWakeLayersIfRevision {
+                        expected_revision,
+                        layers,
+                    })
+                    .await?;
+                return Ok(RynkLightingReadback::OutputMode(state));
+            }
             RynkLightingCommand::ReadOverlay {
                 expected_revision,
                 offset,
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index f653d9926..8e3863da8 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -11,13 +11,13 @@ mod topics;
 
 use embassy_futures::select::{Either, select};
 use embedded_io_async::{Read, Write};
-use postcard::experimental::max_size::MaxSize;
 #[cfg(feature = "lighting")]
 pub use lighting::{
     RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
     RynkLightingReadback, StandardRynkLightingAdapter, install_lighting_runtime_conditional_scenes,
     install_lighting_scenes,
 };
+use postcard::experimental::max_size::MaxSize;
 use rmk_types::constants::RYNK_BUFFER_SIZE;
 use rmk_types::protocol::rynk::{
     BuildInfo, Cmd, Deframer, FirmwareVersion, RYNK_HEADER_SIZE, RynkError, RynkMessage, command, encode_frame,
@@ -179,6 +179,7 @@ impl<'a> RynkService<'a> {
             | Cmd::SetLightingExtensionState
             | Cmd::SetLightingExtensionParam
             | Cmd::SetLightingOutputMode
+            | Cmd::SetLightingWakeLayers
             | Cmd::BeginLightingRuntimeConditionalSceneReplace
             | Cmd::PutLightingRuntimeConditionalSceneChunk
             | Cmd::CommitLightingRuntimeConditionalSceneReplace
@@ -336,6 +337,7 @@ impl<'a> RynkService<'a> {
             Cmd::SetLightingExtensionParam => Serve::<command::SetLightingExtensionParam, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::SetLightingOutputMode => Serve::<command::SetLightingOutputMode, _>::serve(self, msg).await,
+            Cmd::SetLightingWakeLayers => Serve::<command::SetLightingWakeLayers, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::GetLightingRuntimeConditionalSceneStatus => {
                 Serve::<command::GetLightingRuntimeConditionalSceneStatus, _>::serve(self, msg).await
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index 1b030be6a..4c9dcde34 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -239,7 +239,12 @@ pub struct LightingControls {
     /// Legacy two-state action retained for existing boards.
     pub output_toggle_user_action: Option<u8>,
     pub output_mode_cycle_user_action: Option<u8>,
-    pub wake_layer: Option<u8>,
+    /// Layers that temporarily wake lighting while held, as a bitmask over
+    /// [`LayerState`](crate::lighting::LayerState)'s layers. A set rather than
+    /// one layer, so waking is not limited to a single "magic" layer, and a
+    /// mask rather than a list because the active layers are already one --
+    /// the check is a single AND. Zero means no layer wakes lighting.
+    pub wake_layers: u64,
     pub initial_output_mode: OutputMode,
     pub powered_only_scope: PoweredOnlyScope,
     pub output_mode_indicator: Option<OutputModeIndicator>,
diff --git a/rmk/src/lighting/standard/command.rs b/rmk/src/lighting/standard/command.rs
index 6ba18bc66..07dcb555b 100644
--- a/rmk/src/lighting/standard/command.rs
+++ b/rmk/src/lighting/standard/command.rs
@@ -44,6 +44,11 @@ pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
         expected_revision: u32,
         mode: OutputMode,
     },
+    /// Replace the wake-layer mask; see [`LightingControls::wake_layers`].
+    SetWakeLayersIfRevision {
+        expected_revision: u32,
+        layers: u64,
+    },
     SetOutputBrightness(u8),
     SetBackground(BackgroundState),
     PatchBackground(BackgroundPatch),
diff --git a/rmk/src/lighting/standard/engine.rs b/rmk/src/lighting/standard/engine.rs
index cf00cd3f4..3e1124709 100644
--- a/rmk/src/lighting/standard/engine.rs
+++ b/rmk/src/lighting/standard/engine.rs
@@ -859,6 +859,14 @@ where
                 self.output_mode = mode;
                 (Invalidation::Render, true)
             }
+            StandardCommand::SetWakeLayersIfRevision {
+                expected_revision,
+                layers,
+            } => {
+                self.check_revision(expected_revision)?;
+                self.controls.wake_layers = layers;
+                (Invalidation::Render, true)
+            }
             StandardCommand::SetOutputBrightness(level) => {
                 self.output_brightness = level;
                 (Invalidation::Render, true)
@@ -1161,10 +1169,7 @@ where
         }
         let context = input.snapshot.lighting_context();
         let powered = context.powered;
-        let wake_active = self
-            .controls
-            .wake_layer
-            .is_some_and(|layer| context.layers.is_active(layer));
+        let wake_active = context.layers.active_bits() & self.controls.wake_layers != 0;
         let effective_output_enabled = wake_active
             || matches!(self.output_mode, OutputMode::AlwaysOn)
             || matches!(self.output_mode, OutputMode::PoweredOnly) && powered;
diff --git a/rmk/src/lighting/standard/tests.rs b/rmk/src/lighting/standard/tests.rs
index 9c0e2632a..432323138 100644
--- a/rmk/src/lighting/standard/tests.rs
+++ b/rmk/src/lighting/standard/tests.rs
@@ -501,7 +501,7 @@ fn output_mode_cycles_and_wake_layer_temporarily_overrides_policy() {
     let mut engine = engine().with_controls(LightingControls {
         output_toggle_user_action: None,
         output_mode_cycle_user_action: Some(13),
-        wake_layer: Some(2),
+        wake_layers: 1 << 2,
         initial_output_mode: OutputMode::PoweredOnly,
         powered_only_scope: super::super::source::PoweredOnlyScope::Local,
         output_mode_indicator: Some(super::super::source::OutputModeIndicator {
@@ -1625,6 +1625,66 @@ fn repainting_a_cell_does_not_strand_styles() {
     assert_eq!(table.len(), 1);
 }
 
+/// Waking is a mask over layers, not one designated layer, and it is settable
+/// at runtime -- which is what keeps "which layers wake lighting" out of the
+/// firmware image.
+#[test]
+fn wake_layers_accept_any_layer_set_and_are_settable() {
+    let mut engine: Engine = StandardLightingEngine::new(
+        BackgroundState {
+            value: 10,
+            ..BackgroundState::default()
+        },
+        LayerScenes {
+            scenes: &[],
+            policy: LayerPolicy::EffectiveOnly,
+        },
+        EmptySource,
+        EmptySource,
+    )
+    .with_controls(LightingControls {
+        // Off unless woken, so "is anything lit" answers "did a layer wake it".
+        initial_output_mode: OutputMode::AlwaysOff,
+        wake_layers: (1 << 2) | (1 << 5),
+        ..LightingControls::default()
+    });
+
+    let lit = |engine: &mut Engine, layer: u8| {
+        let snapshot = context(layer);
+        let mut frame = LogicalFrame::new(Rgb8::BLACK);
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 0,
+                    snapshot: &snapshot,
+                },
+                &mut frame,
+            )
+            .unwrap();
+        frame.as_slice()[0] != Rgb8::BLACK
+    };
+
+    // Either masked layer wakes it; an unmasked one does not.
+    assert!(lit(&mut engine, 2));
+    assert!(lit(&mut engine, 5), "a mask holds more than one layer");
+    assert!(!lit(&mut engine, 3));
+
+    // And the mask is replaceable at runtime, so this is not a compiled choice.
+    let revision = engine.state().revision;
+    engine
+        .handle_command(
+            0,
+            StandardCommand::SetWakeLayersIfRevision {
+                expected_revision: revision,
+                layers: 1 << 3,
+            },
+            &context(3),
+        )
+        .unwrap();
+    assert!(lit(&mut engine, 3));
+    assert!(!lit(&mut engine, 2), "the old mask no longer wakes");
+}
+
 /// The point of the output-mode condition: the mode indicator stops being
 /// something the board compiles in and becomes an ordinary runtime rule a host
 /// can edit. A rule gated on one policy lights only under that policy, and
@@ -1663,7 +1723,7 @@ fn output_mode_conditions_select_between_runtime_rules() {
         powered: true,
     };
     let mut frame = LogicalFrame::new(Rgb8::BLACK);
-    let mut render = |engine: &mut ConditionalEngine, frame: &mut LogicalFrame<Rgb8, 2>| {
+    let render = |engine: &mut ConditionalEngine, frame: &mut LogicalFrame<Rgb8, 2>| {
         engine
             .render(
                 RenderInput {

From bd2f32804ccc67d78ada69af5cf48c9f308b83ca Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 01:45:31 -0700
Subject: [PATCH 48/78] feat(config): wake layers are a list resolving to a
 mask

Board config takes any set of layers now instead of one, resolving to the
mask the engine uses, so the compiled value is a starting point the host can
replace rather than the only answer.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk-config/src/lib.rs               |  4 +++-
 rmk-config/src/resolved/lighting.rs | 26 ++++++++++++++------------
 rmk-macro/src/codegen/lighting.rs   |  7 ++-----
 3 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/rmk-config/src/lib.rs b/rmk-config/src/lib.rs
index 827afb4cc..3326bc3ee 100644
--- a/rmk-config/src/lib.rs
+++ b/rmk-config/src/lib.rs
@@ -577,7 +577,9 @@ pub(crate) struct LightingTomlConfig {
 pub(crate) struct LightingControlsTomlConfig {
     pub output_toggle_user_action: Option<u8>,
     pub output_mode_cycle_user_action: Option<u8>,
-    pub wake_layer: Option<u8>,
+    /// Layers that wake lighting while held. A list, since any set of layers
+    /// may wake it; the host can replace the resolved mask at runtime.
+    pub wake_layers: Option<Vec<u8>>,
     #[serde(default)]
     pub initial_output_mode: LightingOutputModeToml,
     #[serde(default)]
diff --git a/rmk-config/src/resolved/lighting.rs b/rmk-config/src/resolved/lighting.rs
index ed8adb571..abb14e70b 100644
--- a/rmk-config/src/resolved/lighting.rs
+++ b/rmk-config/src/resolved/lighting.rs
@@ -142,7 +142,7 @@ pub struct LightingOutputModeIndicator {
 pub struct LightingControls {
     pub output_toggle_user_action: Option<u8>,
     pub output_mode_cycle_user_action: Option<u8>,
-    pub wake_layer: Option<u8>,
+    pub wake_layers: u64,
     pub initial_output_mode: LightingOutputMode,
     pub powered_only_scope: LightingPoweredOnlyScope,
     pub output_mode_indicator: Option<LightingOutputModeIndicator>,
@@ -309,18 +309,20 @@ impl crate::KeyboardTomlConfig {
             .controls
             .clone()
             .map_or(Ok(LightingControls::default()), |controls| {
-                if let Some(layer) = controls.wake_layer
-                    && layer >= keymap.layers
-                {
-                    return Err(format!(
-                        "lighting.controls wake_layer {} is outside keymap layer count {}",
-                        layer, keymap.layers
-                    ));
+                let mut wake_layers = 0u64;
+                for layer in controls.wake_layers.clone().unwrap_or_default() {
+                    if layer >= keymap.layers {
+                        return Err(format!(
+                            "lighting.controls wake_layers {} is outside keymap layer count {}",
+                            layer, keymap.layers
+                        ));
+                    }
+                    wake_layers |= 1 << layer;
                 }
                 Ok(LightingControls {
                     output_toggle_user_action: controls.output_toggle_user_action,
                     output_mode_cycle_user_action: controls.output_mode_cycle_user_action,
-                    wake_layer: controls.wake_layer,
+                    wake_layers,
                     initial_output_mode: match controls.initial_output_mode {
                         LightingOutputModeToml::AlwaysOn => LightingOutputMode::AlwaysOn,
                         LightingOutputModeToml::AlwaysOff => LightingOutputMode::AlwaysOff,
@@ -883,7 +885,7 @@ effect = {{ kind = "solid", color = [9, 8, 7] }}
 [lighting.controls]
 output_toggle_user_action = 13
 output_mode_cycle_user_action = 14
-wake_layer = 1
+wake_layers = [1]
 initial_output_mode = "powered_only"
 powered_only_scope = "local"
 
@@ -900,12 +902,12 @@ powered_only = {{ kind = "solid", color = [0, 0, 9] }}
         let lighting = config.lighting(&layout, &keymap).unwrap().unwrap();
         assert_eq!(lighting.controls.output_toggle_user_action, Some(13));
         assert_eq!(lighting.controls.output_mode_cycle_user_action, Some(14));
-        assert_eq!(lighting.controls.wake_layer, Some(1));
+        assert_eq!(lighting.controls.wake_layers, 1 << 1);
         assert_eq!(lighting.controls.initial_output_mode, LightingOutputMode::PoweredOnly);
         assert_eq!(lighting.controls.powered_only_scope, LightingPoweredOnlyScope::Local);
         assert_eq!(lighting.controls.output_mode_indicator.unwrap().slot, 0);
 
-        let invalid = parse(&source.replace("wake_layer = 1", "wake_layer = 2"));
+        let invalid = parse(&source.replace("wake_layers = [1]", "wake_layers = [2]"));
         let error = invalid.lighting(&layout, &keymap).unwrap_err();
         assert!(error.contains("outside keymap layer count"), "{error}");
     }
diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
index 6c1245f41..f39d4e953 100644
--- a/rmk-macro/src/codegen/lighting.rs
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -230,10 +230,7 @@ pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> To
         Some(action) => quote! { Some(#action) },
         None => quote! { None },
     };
-    let wake_layer = match lighting.controls.wake_layer {
-        Some(layer) => quote! { Some(#layer) },
-        None => quote! { None },
-    };
+    let wake_layers = lighting.controls.wake_layers;
     let initial_output_mode = match lighting.controls.initial_output_mode {
         LightingOutputMode::AlwaysOn => quote! { ::rmk::lighting::OutputMode::AlwaysOn },
         LightingOutputMode::AlwaysOff => quote! { ::rmk::lighting::OutputMode::AlwaysOff },
@@ -291,7 +288,7 @@ pub(crate) fn expand_lighting_renderer_config(lighting: Option<&Lighting>) -> To
             ::rmk::lighting::LightingControls {
                 output_toggle_user_action: #output_toggle_user_action,
                 output_mode_cycle_user_action: #output_mode_cycle_user_action,
-                wake_layer: #wake_layer,
+                wake_layers: #wake_layers,
                 initial_output_mode: #initial_output_mode,
                 powered_only_scope: #powered_only_scope,
                 output_mode_indicator: #output_mode_indicator,

From 32c3afbf17d64fc1a8ba49b9a2cb3816c5b1c4d3 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 01:53:13 -0700
Subject: [PATCH 49/78] fix(lighting): advertise output-mode support from the
 engine

The capability was set only when a board bound a key to cycling the mode,
so replacing that binding with a real keycode withdrew the whole capability
-- hosts then stopped reading or writing the mode, and a config asking for
powered-only silently read back as always-on. The standard engine always
owns a policy, so the flag reflects that rather than the binding.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/host/rynk/handlers/lighting.rs | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 1e43e4810..cfb0979a1 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -850,9 +850,12 @@ fn capabilities(binding: RynkLightingController<'_>) -> LightingCapabilities {
     if binding.runtime_conditional_scene_capacity > 0 {
         features.0 |= LightingFeatureFlags::RUNTIME_CONDITIONAL_SCENES;
     }
-    if binding.controls.output_mode_cycle_user_action.is_some() {
-        features.0 |= LightingFeatureFlags::OUTPUT_MODE;
-    }
+    // The standard engine always owns an output-mode policy, so this advertises
+    // the engine's support rather than whether a board happened to bind a key to
+    // cycling it. Gating on the binding meant retiring that binding in favour of
+    // a real keycode silently withdrew the whole capability, and hosts stopped
+    // reading or writing the mode at all.
+    features.0 |= LightingFeatureFlags::OUTPUT_MODE;
     if binding.extension_effects {
         features.0 |= LightingFeatureFlags::EXTENSION_EFFECTS;
     }

From 45bb0e1a3745ef167807cdfcdfd2b310f4bc9b1f Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 13:38:58 -0700
Subject: [PATCH 50/78] fix(rynk): gate wake-layer dispatch on lighting

---
 rmk/src/host/rynk/mod.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 8e3863da8..91858b7c2 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -337,6 +337,7 @@ impl<'a> RynkService<'a> {
             Cmd::SetLightingExtensionParam => Serve::<command::SetLightingExtensionParam, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::SetLightingOutputMode => Serve::<command::SetLightingOutputMode, _>::serve(self, msg).await,
+            #[cfg(feature = "lighting")]
             Cmd::SetLightingWakeLayers => Serve::<command::SetLightingWakeLayers, _>::serve(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::GetLightingRuntimeConditionalSceneStatus => {

From aedbd87d098d2a70d73c17531d2eaabc89a5327a Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 13:38:58 -0700
Subject: [PATCH 51/78] feat(lighting): intern conditional rule styles

---
 rmk/src/lighting/standard/command.rs     |  3 +-
 rmk/src/lighting/standard/conditional.rs | 70 ++++++++++++++++---
 rmk/src/lighting/standard/engine.rs      | 21 +++---
 rmk/src/lighting/standard/tests.rs       | 85 +++++++++++++++++++++++-
 4 files changed, 152 insertions(+), 27 deletions(-)

diff --git a/rmk/src/lighting/standard/command.rs b/rmk/src/lighting/standard/command.rs
index 07dcb555b..5ca987aba 100644
--- a/rmk/src/lighting/standard/command.rs
+++ b/rmk/src/lighting/standard/command.rs
@@ -32,8 +32,7 @@ pub(super) struct RuntimeConditionalSceneReplace<const CAP: usize> {
     pub(super) id: u32,
     pub(super) expected_revision: u32,
     pub(super) expected_count: u16,
-    pub(super) cells: [RuntimeConditionalSceneCell; CAP],
-    pub(super) len: usize,
+    pub(super) table: RuntimeConditionalSceneTable<CAP>,
     pub(super) last_activity_ms: u64,
 }
 
diff --git a/rmk/src/lighting/standard/conditional.rs b/rmk/src/lighting/standard/conditional.rs
index 359432af9..e62e760d4 100644
--- a/rmk/src/lighting/standard/conditional.rs
+++ b/rmk/src/lighting/standard/conditional.rs
@@ -25,6 +25,26 @@ pub(super) const EMPTY_CONDITIONAL_SCENE_CELL: RuntimeConditionalSceneCell = Run
     effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
 };
 
+/// A conditional rule as stored: conditions and target stay with the rule,
+/// while the effect is interned in the table's [`StylePool`].
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+struct InternedRuntimeConditionalSceneCell {
+    conditions: ConditionSet,
+    slot: LedSlot,
+    style: u8,
+}
+
+const EMPTY_INTERNED_CONDITIONAL_SCENE_CELL: InternedRuntimeConditionalSceneCell =
+    InternedRuntimeConditionalSceneCell {
+        conditions: ConditionSet {
+            layer: None,
+            battery: None,
+            output_mode: None,
+        },
+        slot: LedSlot(0),
+        style: 0,
+    };
+
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct RuntimeConditionalSceneChunk {
     cells: [RuntimeConditionalSceneCell; CONDITIONAL_SCENE_CHUNK_SIZE],
@@ -61,17 +81,19 @@ impl Default for RuntimeConditionalSceneChunk {
 
 /// Fixed-capacity ordered conditional source. Order is semantic: later
 /// matching rules override earlier rules at the same compositor priority.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+#[derive(Copy, Clone, Debug)]
 pub struct RuntimeConditionalSceneTable<const CAP: usize> {
-    cells: [RuntimeConditionalSceneCell; CAP],
+    cells: [InternedRuntimeConditionalSceneCell; CAP],
     len: usize,
+    pub(super) pool: StylePool,
 }
 
 impl<const CAP: usize> RuntimeConditionalSceneTable<CAP> {
     pub const fn new() -> Self {
         Self {
-            cells: [EMPTY_CONDITIONAL_SCENE_CELL; CAP],
+            cells: [EMPTY_INTERNED_CONDITIONAL_SCENE_CELL; CAP],
             len: 0,
+            pool: StylePool::new(),
         }
     }
 
@@ -83,29 +105,48 @@ impl<const CAP: usize> RuntimeConditionalSceneTable<CAP> {
         self.len == 0
     }
 
-    pub fn as_slice(&self) -> &[RuntimeConditionalSceneCell] {
-        &self.cells[..self.len]
+    /// Installed rules in their semantic order, with effects resolved from the
+    /// pool. Style indices are an allocation detail and never escape the table.
+    pub fn iter(&self) -> impl Iterator<Item = RuntimeConditionalSceneCell> + '_ {
+        self.cells[..self.len].iter().filter_map(move |held| {
+            self.pool.get(held.style).map(|effect| RuntimeConditionalSceneCell {
+                conditions: held.conditions,
+                slot: held.slot,
+                effect,
+            })
+        })
     }
 
     pub fn push(&mut self, cell: RuntimeConditionalSceneCell) -> Result<(), StandardError> {
         if self.len == CAP {
             return Err(StandardError::ConditionalSceneFull { capacity: CAP });
         }
-        self.cells[self.len] = cell;
+        let style = self
+            .pool
+            .intern(cell.effect)
+            .ok_or(StandardError::ConditionalSceneFull {
+                capacity: SCENE_STYLE_CAP,
+            })?;
+        self.cells[self.len] = InternedRuntimeConditionalSceneCell {
+            conditions: cell.conditions,
+            slot: cell.slot,
+            style,
+        };
         self.len += 1;
         Ok(())
     }
 
     pub fn clear(&mut self) {
         self.len = 0;
+        self.pool.clear();
     }
 
     pub fn page(&self, offset: u16) -> RuntimeConditionalSceneChunk {
         let start = (offset as usize).min(self.len);
         let end = (start + CONDITIONAL_SCENE_CHUNK_SIZE).min(self.len);
         let mut chunk = RuntimeConditionalSceneChunk::new();
-        for cell in &self.cells[start..end] {
-            chunk.push(*cell).expect("page is chunk-bounded");
+        for cell in self.iter().skip(start).take(end - start) {
+            chunk.push(cell).expect("page is chunk-bounded");
         }
         chunk
     }
@@ -117,6 +158,16 @@ impl<const CAP: usize> Default for RuntimeConditionalSceneTable<CAP> {
     }
 }
 
+impl<const CAP: usize> PartialEq for RuntimeConditionalSceneTable<CAP> {
+    fn eq(&self, other: &Self) -> bool {
+        // Style indices may differ after independent replacement/replication;
+        // only the ordered resolved rules are semantic state.
+        self.iter().eq(other.iter())
+    }
+}
+
+impl<const CAP: usize> Eq for RuntimeConditionalSceneTable<CAP> {}
+
 pub(super) struct RuntimeConditionalSource<'a, Batteries: ?Sized, const CAP: usize> {
     pub(super) table: &'a RuntimeConditionalSceneTable<CAP>,
     pub(super) batteries: &'a Batteries,
@@ -133,7 +184,6 @@ where
 {
     fn len(&self, input: &SourceRenderInput<'_, Context>) -> usize {
         self.table
-            .as_slice()
             .iter()
             .filter(|cell| {
                 cell.conditions
@@ -144,7 +194,6 @@ where
 
     fn slot(&self, index: usize, input: &SourceRenderInput<'_, Context>) -> LedSlot {
         self.table
-            .as_slice()
             .iter()
             .filter(|cell| {
                 cell.conditions
@@ -158,7 +207,6 @@ where
     fn contribution(&mut self, index: usize, input: &SourceRenderInput<'_, Context>) -> Contribution<Rgb8> {
         let cell = self
             .table
-            .as_slice()
             .iter()
             .filter(|cell| {
                 cell.conditions
diff --git a/rmk/src/lighting/standard/engine.rs b/rmk/src/lighting/standard/engine.rs
index 3e1124709..14025cb75 100644
--- a/rmk/src/lighting/standard/engine.rs
+++ b/rmk/src/lighting/standard/engine.rs
@@ -580,8 +580,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             id,
             expected_revision,
             expected_count: cell_count,
-            cells: [EMPTY_CONDITIONAL_SCENE_CELL; SCENE_CAP],
-            len: 0,
+            table: RuntimeConditionalSceneTable::new(),
             last_activity_ms: now_ms,
         });
         Ok(id)
@@ -604,12 +603,13 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             .as_mut()
             .filter(|replace| replace.id == transaction_id)
             .ok_or(error)?;
-        if offset as usize != replace.len || replace.len + cells.as_slice().len() > replace.expected_count as usize {
+        if offset as usize != replace.table.len()
+            || replace.table.len() + cells.as_slice().len() > replace.expected_count as usize
+        {
             return Err(StandardError::InvalidConditionalSceneRequest);
         }
         for cell in cells.as_slice() {
-            replace.cells[replace.len] = *cell;
-            replace.len += 1;
+            replace.table.push(*cell)?;
         }
         replace.last_activity_ms = now_ms;
         Ok(())
@@ -632,20 +632,15 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             .as_ref()
             .filter(|replace| replace.id == transaction_id)
             .ok_or(error)?;
-        if replace.len != replace.expected_count as usize {
+        if replace.table.len() != replace.expected_count as usize {
             return Err(StandardError::ConditionalSceneTransactionIncomplete {
                 expected: replace.expected_count,
-                received: replace.len as u16,
+                received: replace.table.len() as u16,
             });
         }
         self.check_revision(replace.expected_revision)?;
         let replace = self.runtime_conditional_scene_replace.take().expect("checked above");
-        self.runtime_conditional_scenes.clear();
-        for cell in &replace.cells[..replace.len] {
-            self.runtime_conditional_scenes
-                .push(*cell)
-                .expect("staged length is table-bounded");
-        }
+        self.runtime_conditional_scenes = replace.table;
         self.runtime_conditional_scene_committed_transaction = Some(transaction_id);
         self.runtime_conditional_scene_expired_transaction = None;
         Ok(true)
diff --git a/rmk/src/lighting/standard/tests.rs b/rmk/src/lighting/standard/tests.rs
index 432323138..174625218 100644
--- a/rmk/src/lighting/standard/tests.rs
+++ b/rmk/src/lighting/standard/tests.rs
@@ -1507,7 +1507,12 @@ fn runtime_conditional_replace_preserves_order_and_output_mode_is_revision_check
         )
         .unwrap();
     assert_eq!(committed.reply.state().unwrap().revision, 1);
-    assert_eq!(engine.runtime_conditional_scenes().as_slice(), cells.as_slice());
+    assert!(
+        engine
+            .runtime_conditional_scenes()
+            .iter()
+            .eq(cells.as_slice().iter().copied())
+    );
 
     let mut frame = LogicalFrame::new(Rgb8::BLACK);
     engine
@@ -1625,6 +1630,84 @@ fn repainting_a_cell_does_not_strand_styles() {
     assert_eq!(table.len(), 1);
 }
 
+#[test]
+fn conditional_rules_share_styles_without_losing_order_or_conditions() {
+    let mut table = RuntimeConditionalSceneTable::<4>::new();
+    let effect = BuiltinEffect::solid(Rgb8::new(9, 8, 7));
+    let rules = [
+        RuntimeConditionalSceneCell {
+            conditions: ConditionSet {
+                layer: Some(crate::lighting::LayerCondition { layer: 2, active: true }),
+                battery: None,
+                output_mode: Some(OutputMode::AlwaysOn),
+            },
+            slot: LedSlot(3),
+            effect,
+        },
+        RuntimeConditionalSceneCell {
+            conditions: ConditionSet {
+                layer: Some(crate::lighting::LayerCondition { layer: 2, active: true }),
+                battery: None,
+                output_mode: Some(OutputMode::PoweredOnly),
+            },
+            slot: LedSlot(3),
+            effect,
+        },
+    ];
+    for rule in rules {
+        table.push(rule).unwrap();
+    }
+
+    assert_eq!(table.pool.len(), 1, "identical effects share one style");
+    assert!(table.iter().eq(rules));
+
+    table.clear();
+    assert!(table.is_empty());
+    assert!(table.pool.is_empty(), "clearing rules releases their styles");
+}
+
+#[test]
+fn conditional_style_capacity_rejects_only_a_new_effect() {
+    let mut table = RuntimeConditionalSceneTable::<{ SCENE_STYLE_CAP + 1 }>::new();
+    for shade in 0..SCENE_STYLE_CAP {
+        table
+            .push(RuntimeConditionalSceneCell {
+                conditions: ConditionSet::default(),
+                slot: LedSlot(shade as u16),
+                effect: BuiltinEffect::solid(Rgb8::new(shade as u8, 0, 0)),
+            })
+            .unwrap();
+    }
+    let held = RuntimeConditionalSceneCell {
+        conditions: ConditionSet::default(),
+        slot: LedSlot(SCENE_STYLE_CAP as u16),
+        effect: BuiltinEffect::solid(Rgb8::new(0, 0, 0)),
+    };
+    table.push(held).unwrap();
+
+    let mut full = RuntimeConditionalSceneTable::<{ SCENE_STYLE_CAP + 1 }>::new();
+    for shade in 0..SCENE_STYLE_CAP {
+        full.push(RuntimeConditionalSceneCell {
+            conditions: ConditionSet::default(),
+            slot: LedSlot(shade as u16),
+            effect: BuiltinEffect::solid(Rgb8::new(shade as u8, 0, 0)),
+        })
+        .unwrap();
+    }
+    let before = full;
+    assert_eq!(
+        full.push(RuntimeConditionalSceneCell {
+            conditions: ConditionSet::default(),
+            slot: LedSlot(SCENE_STYLE_CAP as u16),
+            effect: BuiltinEffect::solid(Rgb8::new(0, 1, 0)),
+        }),
+        Err(StandardError::ConditionalSceneFull {
+            capacity: SCENE_STYLE_CAP,
+        })
+    );
+    assert_eq!(full, before, "a rejected style leaves the staged table intact");
+}
+
 /// Waking is a mask over layers, not one designated layer, and it is settable
 /// at runtime -- which is what keeps "which layers wake lighting" out of the
 /// firmware image.

From 5a520fa832f48dc66933b3c94899057850d15b61 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 13:38:59 -0700
Subject: [PATCH 52/78] feat(config): support output-mode lighting conditions

---
 rmk-config/src/lib.rs               |  1 +
 rmk-config/src/resolved/lighting.rs | 16 ++++++++++++++--
 rmk-macro/src/codegen/lighting.rs   | 13 +++++++++++++
 3 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/rmk-config/src/lib.rs b/rmk-config/src/lib.rs
index 3326bc3ee..599fb74b8 100644
--- a/rmk-config/src/lib.rs
+++ b/rmk-config/src/lib.rs
@@ -661,6 +661,7 @@ pub(crate) struct LightingLayerSceneTomlConfig {
 pub(crate) struct LightingConditionalSceneTomlConfig {
     pub layer: Option<LightingLayerConditionTomlConfig>,
     pub battery: Option<LightingBatteryConditionTomlConfig>,
+    pub output_mode: Option<LightingOutputModeToml>,
     #[serde(default, rename = "cell")]
     pub cells: Vec<LightingSceneCellTomlConfig>,
 }
diff --git a/rmk-config/src/resolved/lighting.rs b/rmk-config/src/resolved/lighting.rs
index abb14e70b..563d3c1e1 100644
--- a/rmk-config/src/resolved/lighting.rs
+++ b/rmk-config/src/resolved/lighting.rs
@@ -101,6 +101,7 @@ pub struct LightingBatteryCondition {
 pub struct LightingConditionSet {
     pub layer: Option<LightingLayerCondition>,
     pub battery: Option<LightingBatteryCondition>,
+    pub output_mode: Option<LightingOutputMode>,
 }
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -631,7 +632,16 @@ fn resolve_conditional_scenes(
                 })
             })
             .transpose()?;
-        let conditions = LightingConditionSet { layer, battery };
+        let output_mode = scene.output_mode.map(|mode| match mode {
+            LightingOutputModeToml::AlwaysOn => LightingOutputMode::AlwaysOn,
+            LightingOutputModeToml::AlwaysOff => LightingOutputMode::AlwaysOff,
+            LightingOutputModeToml::PoweredOnly => LightingOutputMode::PoweredOnly,
+        });
+        let conditions = LightingConditionSet {
+            layer,
+            battery,
+            output_mode,
+        };
         for cell in &scene.cells {
             let slots = resolve_target_slots(&cell.target, &id_to_slot, emitters, zone_memberships, zone_ids)?;
             if slots.is_empty() {
@@ -852,12 +862,13 @@ hidden = ["(0,1)"]"#,
     }
 
     #[test]
-    fn resolves_conditional_layer_and_battery_scenes() {
+    fn resolves_conditional_layer_battery_and_output_mode_scenes() {
         let source = format!(
             r#"{BASE}
 [[lighting.conditional_scene]]
 layer = {{ layer = 1, active = true }}
 battery = {{ node = 0, min_level = 21, max_level = 40, charge = "discharging" }}
+output_mode = "powered_only"
 [[lighting.conditional_scene.cell]]
 target = {{ zone = 1 }}
 effect = {{ kind = "solid", color = [9, 8, 7] }}
@@ -876,6 +887,7 @@ effect = {{ kind = "solid", color = [9, 8, 7] }}
         assert_eq!(battery.min_level, Some(21));
         assert_eq!(battery.max_level, Some(40));
         assert_eq!(battery.charge, super::LightingChargeCondition::Discharging);
+        assert_eq!(conditions.output_mode, Some(LightingOutputMode::PoweredOnly));
     }
 
     #[test]
diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
index f39d4e953..703dc7b9d 100644
--- a/rmk-macro/src/codegen/lighting.rs
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -349,11 +349,24 @@ fn expand_conditional_scene_cell(cell: &LightingConditionalSceneCell) -> TokenSt
         }
         None => quote! { ::core::option::Option::None },
     };
+    let output_mode = match cell.conditions.output_mode {
+        Some(LightingOutputMode::AlwaysOn) => {
+            quote! { ::core::option::Option::Some(::rmk::lighting::OutputMode::AlwaysOn) }
+        }
+        Some(LightingOutputMode::AlwaysOff) => {
+            quote! { ::core::option::Option::Some(::rmk::lighting::OutputMode::AlwaysOff) }
+        }
+        Some(LightingOutputMode::PoweredOnly) => {
+            quote! { ::core::option::Option::Some(::rmk::lighting::OutputMode::PoweredOnly) }
+        }
+        None => quote! { ::core::option::Option::None },
+    };
     quote! {
         ::rmk::lighting::ConditionalSceneCell {
             conditions: ::rmk::lighting::ConditionSet {
                 layer: #layer,
                 battery: #battery,
+                output_mode: #output_mode,
             },
             slot: ::rmk::lighting::LedSlot(#slot),
             effect: #effect,

From 3926168d215829760a3365198514024e77bd196b Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 13:47:20 -0700
Subject: [PATCH 53/78] refactor(config): derive lighting output default

---
 rmk-config/src/resolved/lighting.rs | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/rmk-config/src/resolved/lighting.rs b/rmk-config/src/resolved/lighting.rs
index 563d3c1e1..e7c6b525c 100644
--- a/rmk-config/src/resolved/lighting.rs
+++ b/rmk-config/src/resolved/lighting.rs
@@ -111,8 +111,9 @@ pub struct LightingConditionalSceneCell {
     pub effect: LightingEffect,
 }
 
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 pub enum LightingOutputMode {
+    #[default]
     AlwaysOn,
     AlwaysOff,
     PoweredOnly,
@@ -125,12 +126,6 @@ pub enum LightingPoweredOnlyScope {
     Local,
 }
 
-impl Default for LightingOutputMode {
-    fn default() -> Self {
-        Self::AlwaysOn
-    }
-}
-
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub struct LightingOutputModeIndicator {
     pub slot: u16,

From a28314765f3589276f899f1b91d3cf49445d7ce0 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 13:48:39 -0700
Subject: [PATCH 54/78] fix(lighting): satisfy current clippy

---
 rmk-types/src/protocol/rynk/payload/lighting.rs | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index c5ca2d069..63a79ff34 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -638,13 +638,12 @@ wire_type! {
 
 impl LightingConditionalSceneCell {
     pub fn validate(&self) -> LightingResult<()> {
-        if let Some(battery) = self.conditions.battery {
-            if battery.min_level.is_some_and(|level| level > 100)
+        if let Some(battery) = self.conditions.battery
+            && (battery.min_level.is_some_and(|level| level > 100)
                 || battery.max_level.is_some_and(|level| level > 100)
-                || matches!((battery.min_level, battery.max_level), (Some(min), Some(max)) if min > max)
-            {
-                return Err(LightingError::InvalidRequest);
-            }
+                || matches!((battery.min_level, battery.max_level), (Some(min), Some(max)) if min > max))
+        {
+            return Err(LightingError::InvalidRequest);
         }
         self.effect.validate()
     }
@@ -1145,7 +1144,6 @@ const _: () = {
     assert_endpoint_fits!(PutLightingSceneChunkRequest, LightingUnitResult);
     assert_endpoint_fits!(CommitLightingSceneReplaceRequest, LightingStateResult);
     assert_endpoint_fits!(AbortLightingSceneReplaceRequest, LightingUnitResult);
-    core::assert!(LightingChanged::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
 };
 
 #[cfg(test)]

From b1aa796485cdcb6554cce92bdde0eb47c08a6b49 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 30 Jul 2026 13:51:05 -0700
Subject: [PATCH 55/78] fix(rynk): avoid cloning conditional cells

---
 rynk/src/api.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index e760a78e3..14f43f6a3 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -1240,7 +1240,7 @@ impl Client {
                 cells: Default::default(),
             };
             for cell in chunk {
-                request.cells.push(cell.clone()).expect("chunks are chunk-size bounded");
+                request.cells.push(*cell).expect("chunks are chunk-size bounded");
             }
             if let Err(error) = self.put_lighting_runtime_conditional_scene_chunk(request).await {
                 let _ = self

From db23f54b9c9ef426fd1a1f51a9f2af33383f3a52 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Fri, 31 Jul 2026 08:33:42 -0700
Subject: [PATCH 56/78] fix(rynk): adapt the lighting stack to upstream's
 rebased rynk

Upstream rebased feat/rynk before merging it, so this topic replays onto a
main whose rynk internals differ from the ones it was written against:

- `Serve::<E, _>::serve(x, msg)` became the free `serve::<E, _>(x, msg)`, and
  the lock endpoints take the session's `HostLock` rather than the session.
- `RynkSession` lost its `locker` and `topics` fields, which are now locals in
  `run_session`. It keeps only the lighting overlay transaction, which has to
  outlive a single dispatch because it spans Begin/Put/Commit.
- `RMK_VERSION` moved into `handlers::system`; it lives here again so it can be
  public alongside `RMK_VERSION_STRING` and the build-label helpers.
- `rynk::endpoint` folded into `rynk::command`, and `TopicEvent::cmd()` is gone.
- The new simulator codegen predates `bootloader_requires_unlock`, so the
  `run_tests!` scenarios could not build a `LockConfig`.

The lighting handler tests derive their gate from the service under test, the
way `run_session` does, now that the session no longer carries one.
---
 rmk-macro/src/codegen/simulator.rs     |  2 +
 rmk/src/host/mod.rs                    |  6 +--
 rmk/src/host/rynk/handlers/lighting.rs | 16 ++++--
 rmk/src/host/rynk/handlers/system.rs   |  4 +-
 rmk/src/host/rynk/mod.rs               | 75 +++++++++++++-------------
 rmk/src/host/rynk/topics.rs            |  2 +-
 6 files changed, 59 insertions(+), 46 deletions(-)

diff --git a/rmk-macro/src/codegen/simulator.rs b/rmk-macro/src/codegen/simulator.rs
index 0e98f6997..a9ba91173 100644
--- a/rmk-macro/src/codegen/simulator.rs
+++ b/rmk-macro/src/codegen/simulator.rs
@@ -317,6 +317,7 @@ fn expand_rmk_config(host: &Host, layout_blob: &[u8]) -> TokenStream2 {
         quote! { (#row, #col) }
     });
     let (insecure, write_requires_unlock) = (host.insecure, host.write_requires_unlock);
+    let bootloader_requires_unlock = host.bootloader_requires_unlock;
     let blob = proc_macro2::Literal::byte_string(layout_blob);
     quote! {
         .rmk_config(::rmk::config::RmkConfig {
@@ -324,6 +325,7 @@ fn expand_rmk_config(host: &Host, layout_blob: &[u8]) -> TokenStream2 {
                 unlock_keys: &[#(#keys),*],
                 insecure: #insecure,
                 write_requires_unlock: #write_requires_unlock,
+                bootloader_requires_unlock: #bootloader_requires_unlock,
             },
             layout_blob: #blob,
             ..Default::default()
diff --git a/rmk/src/host/mod.rs b/rmk/src/host/mod.rs
index 19e2269a1..5817c80fc 100644
--- a/rmk/src/host/mod.rs
+++ b/rmk/src/host/mod.rs
@@ -24,14 +24,14 @@ pub(crate) mod via;
 /// two are mutually exclusive).
 #[cfg(feature = "rynk")]
 pub use rynk::RynkService as HostService;
+/// RMK's semantic version, available to downstream firmware build labels.
+#[cfg(feature = "rynk")]
+pub use rynk::{RMK_VERSION, RMK_VERSION_STRING};
 #[cfg(all(feature = "rynk", feature = "lighting"))]
 pub use rynk::{
     RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
     RynkLightingReadback, StandardRynkLightingAdapter, install_lighting_runtime_conditional_scenes,
     install_lighting_scenes,
 };
-/// RMK's semantic version, available to downstream firmware build labels.
-#[cfg(feature = "rynk")]
-pub use rynk::{RMK_VERSION, RMK_VERSION_STRING};
 #[cfg(feature = "vial")]
 pub use via::VialService as HostService;
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index cfb0979a1..3fa5f0a1e 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -1299,10 +1299,10 @@ mod tests {
 
     use embassy_futures::join::join;
     use rmk_types::action::KeyAction;
+    use rmk_types::protocol::rynk::command::Endpoint;
     use rmk_types::protocol::rynk::command::{
         BeginLightingOverlayReplace, CommitLightingOverlayReplace, GetCapabilities, GetLightingKeys, SetLightingState,
     };
-    use rmk_types::protocol::rynk::endpoint::Endpoint;
     use serde::Serialize;
     use serde::de::DeserializeOwned;
 
@@ -1460,7 +1460,15 @@ mod tests {
             .len();
         let req_len = RYNK_HEADER_SIZE + payload_len;
         let mut message = RynkMessage::from_decoded(&mut buffer[..], req_len);
-        service.dispatch(session, &mut message).await.unwrap();
+        // Same gate `run_session` builds, derived from the service under test so
+        // the lock tier is exercised exactly as it is in production.
+        let locker = crate::host::lock::HostLock::new(
+            service.lock_config.unlock_keys,
+            service.ctx.keymap,
+            service.lock_config.insecure,
+            crate::host::rynk::RYNK_UNLOCK_WINDOW,
+        );
+        service.dispatch(&locker, session, &mut message).await.unwrap();
         // The reply is COBS-framed in place; deframe it back to [cmd, seq, payload].
         let mut reply = message.frame().to_vec();
         let framed_len = reply.len();
@@ -1857,7 +1865,7 @@ mod tests {
                 descriptor(),
                 8,
             ));
-            let session = session(&keymap, &config);
+            let session = session();
 
             let lighting = capabilities(service.lighting.unwrap());
             assert!(!lighting.features.contains(LightingFeatureFlags::LAYER_SCENES));
@@ -1937,7 +1945,7 @@ mod tests {
                     .with_conditional_scenes(&CONDITIONAL_CELLS)
                     .with_controls(controls),
             );
-            let session = session(&keymap, &config);
+            let session = session();
 
             let core = LightingMailbox::<StandardCommand<2, 4>, StandardReply, StandardError, 1>::new();
             let mut adapter = super::super::super::lighting::StandardRynkLightingAdapter::<2, 1, 4>::new(
diff --git a/rmk/src/host/rynk/handlers/system.rs b/rmk/src/host/rynk/handlers/system.rs
index 3c7504181..b0dd0f35a 100644
--- a/rmk/src/host/rynk/handlers/system.rs
+++ b/rmk/src/host/rynk/handlers/system.rs
@@ -6,8 +6,8 @@ use rmk_types::protocol::rynk::command::{
     PeripheralBootloaderJump, Reboot, StorageReset, UnlockPoll,
 };
 use rmk_types::protocol::rynk::{
-    BuildInfo, DeviceCapabilities, DeviceInfo, LockStatus, MAX_BULK_ITEMS, MAX_BULK_KEYS,
-    ProtocolVersion, RYNK_MAX_PAYLOAD_SIZE, RynkError, StorageResetMode,
+    BuildInfo, DeviceCapabilities, DeviceInfo, LockStatus, MAX_BULK_ITEMS, MAX_BULK_KEYS, ProtocolVersion,
+    RYNK_MAX_PAYLOAD_SIZE, RynkError, StorageResetMode,
 };
 
 use super::super::{RMK_VERSION, RynkService, truncated};
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 91858b7c2..a0d77c8bc 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -90,12 +90,19 @@ pub struct RynkService<'a> {
 /// gate and the topic table are locals in [`RynkService::run_session`]; the
 /// lighting overlay transaction cannot be, because it spans the
 /// Begin/Put/Commit exchange.
-#[derive(Default)]
 struct RynkSession {
     #[cfg(feature = "lighting")]
     lighting: embassy_sync::mutex::Mutex<crate::RawMutex, handlers::lighting::LightingTransactionState>,
 }
 
+impl RynkSession {
+    fn new() -> Self {
+        Self {
+            #[cfg(feature = "lighting")]
+            lighting: embassy_sync::mutex::Mutex::new(handlers::lighting::LightingTransactionState::new()),
+        }
+    }
+}
 
 impl<'a> RynkService<'a> {
     pub fn new(keymap: &'a KeyMap<'a>, config: &RmkConfig<'static>) -> Self {
@@ -275,8 +282,8 @@ impl<'a> RynkService<'a> {
             Cmd::GetLightingState => serve::<command::GetLightingState, _>(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::SetLightingState => serve::<command::SetLightingState, _>(self, msg).await,
-            Cmd::GetLightingOverlay => serve::<command::GetLightingOverlay, _>(self, msg).await,
             #[cfg(feature = "lighting")]
+            Cmd::GetLightingOverlay => serve::<command::GetLightingOverlay, _>(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::GetLightingKeys => serve::<command::GetLightingKeys, _>(self, msg).await,
             #[cfg(feature = "lighting")]
@@ -306,77 +313,73 @@ impl<'a> RynkService<'a> {
             #[cfg(feature = "lighting")]
             Cmd::AbortLightingOverlayReplace => handlers::lighting::serve_abort(self, session, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingSceneStatus => Serve::<command::GetLightingSceneStatus, _>::serve(self, msg).await,
+            Cmd::GetLightingSceneStatus => serve::<command::GetLightingSceneStatus, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingScenes => Serve::<command::GetLightingScenes, _>::serve(self, msg).await,
+            Cmd::GetLightingScenes => serve::<command::GetLightingScenes, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingCompiledSceneStatus => {
-                Serve::<command::GetLightingCompiledSceneStatus, _>::serve(self, msg).await
-            }
+            Cmd::GetLightingCompiledSceneStatus => serve::<command::GetLightingCompiledSceneStatus, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingCompiledScenes => Serve::<command::GetLightingCompiledScenes, _>::serve(self, msg).await,
+            Cmd::GetLightingCompiledScenes => serve::<command::GetLightingCompiledScenes, _>(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::GetLightingConditionalSceneStatus => {
-                Serve::<command::GetLightingConditionalSceneStatus, _>::serve(self, msg).await
+                serve::<command::GetLightingConditionalSceneStatus, _>(self, msg).await
             }
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingConditionalScenes => {
-                Serve::<command::GetLightingConditionalScenes, _>::serve(self, msg).await
-            }
+            Cmd::GetLightingConditionalScenes => serve::<command::GetLightingConditionalScenes, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingOutputMode => Serve::<command::GetLightingOutputMode, _>::serve(self, msg).await,
+            Cmd::GetLightingOutputMode => serve::<command::GetLightingOutputMode, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingExtension => Serve::<command::GetLightingExtension, _>::serve(self, msg).await,
+            Cmd::GetLightingExtension => serve::<command::GetLightingExtension, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingExtensionNames => Serve::<command::GetLightingExtensionNames, _>::serve(self, msg).await,
+            Cmd::GetLightingExtensionNames => serve::<command::GetLightingExtensionNames, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::SetLightingExtensionState => Serve::<command::SetLightingExtensionState, _>::serve(self, msg).await,
+            Cmd::SetLightingExtensionState => serve::<command::SetLightingExtensionState, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::GetLightingExtensionParams => Serve::<command::GetLightingExtensionParams, _>::serve(self, msg).await,
+            Cmd::GetLightingExtensionParams => serve::<command::GetLightingExtensionParams, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::SetLightingExtensionParam => Serve::<command::SetLightingExtensionParam, _>::serve(self, msg).await,
+            Cmd::SetLightingExtensionParam => serve::<command::SetLightingExtensionParam, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::SetLightingOutputMode => Serve::<command::SetLightingOutputMode, _>::serve(self, msg).await,
+            Cmd::SetLightingOutputMode => serve::<command::SetLightingOutputMode, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::SetLightingWakeLayers => Serve::<command::SetLightingWakeLayers, _>::serve(self, msg).await,
+            Cmd::SetLightingWakeLayers => serve::<command::SetLightingWakeLayers, _>(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::GetLightingRuntimeConditionalSceneStatus => {
-                Serve::<command::GetLightingRuntimeConditionalSceneStatus, _>::serve(self, msg).await
+                serve::<command::GetLightingRuntimeConditionalSceneStatus, _>(self, msg).await
             }
             #[cfg(feature = "lighting")]
             Cmd::GetLightingRuntimeConditionalScenes => {
-                Serve::<command::GetLightingRuntimeConditionalScenes, _>::serve(self, msg).await
+                serve::<command::GetLightingRuntimeConditionalScenes, _>(self, msg).await
             }
             #[cfg(feature = "lighting")]
             Cmd::BeginLightingRuntimeConditionalSceneReplace => {
-                Serve::<command::BeginLightingRuntimeConditionalSceneReplace, _>::serve(self, msg).await
+                serve::<command::BeginLightingRuntimeConditionalSceneReplace, _>(self, msg).await
             }
             #[cfg(feature = "lighting")]
             Cmd::PutLightingRuntimeConditionalSceneChunk => {
-                Serve::<command::PutLightingRuntimeConditionalSceneChunk, _>::serve(self, msg).await
+                serve::<command::PutLightingRuntimeConditionalSceneChunk, _>(self, msg).await
             }
             #[cfg(feature = "lighting")]
             Cmd::CommitLightingRuntimeConditionalSceneReplace => {
-                Serve::<command::CommitLightingRuntimeConditionalSceneReplace, _>::serve(self, msg).await
+                serve::<command::CommitLightingRuntimeConditionalSceneReplace, _>(self, msg).await
             }
             #[cfg(feature = "lighting")]
             Cmd::AbortLightingRuntimeConditionalSceneReplace => {
-                Serve::<command::AbortLightingRuntimeConditionalSceneReplace, _>::serve(self, msg).await
+                serve::<command::AbortLightingRuntimeConditionalSceneReplace, _>(self, msg).await
             }
             #[cfg(feature = "lighting")]
-            Cmd::SetLightingSceneCell => Serve::<command::SetLightingSceneCell, _>::serve(self, msg).await,
+            Cmd::SetLightingSceneCell => serve::<command::SetLightingSceneCell, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::UnsetLightingSceneCell => Serve::<command::UnsetLightingSceneCell, _>::serve(self, msg).await,
+            Cmd::UnsetLightingSceneCell => serve::<command::UnsetLightingSceneCell, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::SetLightingLayerPolicy => Serve::<command::SetLightingLayerPolicy, _>::serve(self, msg).await,
+            Cmd::SetLightingLayerPolicy => serve::<command::SetLightingLayerPolicy, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::BeginLightingSceneReplace => Serve::<command::BeginLightingSceneReplace, _>::serve(self, msg).await,
+            Cmd::BeginLightingSceneReplace => serve::<command::BeginLightingSceneReplace, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::PutLightingSceneChunk => Serve::<command::PutLightingSceneChunk, _>::serve(self, msg).await,
+            Cmd::PutLightingSceneChunk => serve::<command::PutLightingSceneChunk, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::CommitLightingSceneReplace => Serve::<command::CommitLightingSceneReplace, _>::serve(self, msg).await,
+            Cmd::CommitLightingSceneReplace => serve::<command::CommitLightingSceneReplace, _>(self, msg).await,
             #[cfg(feature = "lighting")]
-            Cmd::AbortLightingSceneReplace => Serve::<command::AbortLightingSceneReplace, _>::serve(self, msg).await,
+            Cmd::AbortLightingSceneReplace => serve::<command::AbortLightingSceneReplace, _>(self, msg).await,
 
             _ => Err(RynkError::UnknownCmd),
         }
@@ -393,7 +396,7 @@ impl<'a> RynkService<'a> {
             RYNK_UNLOCK_WINDOW,
         );
         let mut topics = TopicSubscribers::new();
-        let session = RynkSession::default();
+        let session = RynkSession::new();
         let mut buf = [0u8; RYNK_BUFFER_SIZE];
         let mut df = Deframer::new();
         // Mute topics until the client completes the version handshake.
@@ -591,14 +594,14 @@ mod tests {
         let keymap = block_on(KeyMap::new(&mut data, &mut behavior, &positional));
 
         const UNLOCK_KEYS: &[(u8, u8)] = &[(0, 0)];
-        let config = RmkConfig {
+        let mut config = RmkConfig {
             lock_config: LockConfig {
                 unlock_keys: UNLOCK_KEYS,
                 insecure: false,
                 write_requires_unlock: false,
+                bootloader_requires_unlock: true,
             },
             ..Default::default()
-            bootloader_requires_unlock: true,
         };
         let service = RynkService::new(&keymap, &config);
         assert!(service.requires_unlock(Cmd::BootloaderJump));
diff --git a/rmk/src/host/rynk/topics.rs b/rmk/src/host/rynk/topics.rs
index 454564b1b..58fa751ac 100644
--- a/rmk/src/host/rynk/topics.rs
+++ b/rmk/src/host/rynk/topics.rs
@@ -80,7 +80,7 @@ mod tests {
 
         match block_on(topics.next_event()) {
             TopicEvent::ModifierChange(actual) => assert_eq!(actual, modifiers),
-            other => panic!("expected ModifierChange, got {:?}", other.cmd()),
+            other => panic!("expected ModifierChange, got {other:?}"),
         }
     }
 }

From 85cb09a28751e8cc780106f12a2829627b67fe5f Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Fri, 31 Jul 2026 13:27:08 -0700
Subject: [PATCH 57/78] test(rynk): restore the lighting loopback cases on the
 new harness

Upstream replaced the hand-written loopback suite with a TOML-scenario
simulator, which these cases cannot use: the topology a lighting board
advertises is a compile-time fixture rather than a keymap, and the stateful
endpoints answer from an engine that has to be driven concurrently with the
request. Both are things a timeline has no vocabulary for, so they live beside
the other cases a scenario cannot express and play the host over the same
in-memory duplex `run_session` gets from a real transport.

Restores discovery with revision-pinned paging, the extension endpoints across
the full mailbox/adapter/engine path, and the lighting readback topic. The
Unsupported case is split out, since it is the one that needs no engine.

The host half is reimplemented rather than pulled from `rynk`: as a
dev-dependency it would unify `rmk-types/host` into every rmk test build, so a
lean feature row would compile `Cmd` variants whose dispatch arms are cfg'd
out. Both ends share `rmk-types` and decode with the same strictness instead.
---
 rmk/tests/integration/main.rs          |   2 +
 rmk/tests/integration/rynk_lighting.rs | 456 +++++++++++++++++++++++++
 2 files changed, 458 insertions(+)
 create mode 100644 rmk/tests/integration/rynk_lighting.rs

diff --git a/rmk/tests/integration/main.rs b/rmk/tests/integration/main.rs
index 9bc0d4764..1acdcc93b 100644
--- a/rmk/tests/integration/main.rs
+++ b/rmk/tests/integration/main.rs
@@ -14,6 +14,8 @@ mod simulator;
 
 #[cfg(feature = "rynk")]
 mod rynk;
+#[cfg(all(feature = "rynk", feature = "lighting"))]
+mod rynk_lighting;
 #[cfg(feature = "vial")]
 mod vial;
 
diff --git a/rmk/tests/integration/rynk_lighting.rs b/rmk/tests/integration/rynk_lighting.rs
new file mode 100644
index 000000000..e08cdb653
--- /dev/null
+++ b/rmk/tests/integration/rynk_lighting.rs
@@ -0,0 +1,456 @@
+//! Lighting endpoints across the full Rynk loopback.
+//!
+//! A scenario cannot reach these. The topology a lighting board advertises is a
+//! compile-time fixture rather than a keymap, and the stateful endpoints answer
+//! from a lighting engine that has to be driven concurrently with the request —
+//! two things a timeline has no vocabulary for. So these cases build a
+//! `RynkService` directly and play the host over an in-memory duplex, which is
+//! the same byte stream the USB and BLE adapters hand `run_session`.
+
+use embassy_futures::select::{Either, select};
+use embassy_sync::blocking_mutex::raw::NoopRawMutex;
+use embassy_sync::pipe::Pipe;
+use rmk::config::{BehaviorConfig, PositionalConfig, RmkConfig};
+use rmk::event::publish_event;
+use rmk::host::{HostService as RynkService, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox};
+use rmk::keymap::{KeyMap, KeymapData};
+use rmk::lighting::{LedId, LedMetadata, LightingRouting, LightingTopology, MatrixSize, ZoneSpan};
+use rmk::physical_layout::{Coordinate, KeyPosition, KeySize, PhysicalKey, PhysicalLayout, Point3, Rotation};
+use rmk::test_support::test_block_on;
+use rmk::types::action::KeyAction;
+use rmk_types::constants::RYNK_BUFFER_SIZE;
+use rmk_types::protocol::rynk::{
+    Cmd, Deframer, DeviceCapabilities, LightingChanged, LightingError, LightingKeysPageResult, LightingMatrixPosition,
+    LightingPageRequest, RYNK_HEADER_SIZE, RynkError, RynkHeader, encode_frame,
+};
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+
+/// One direction of the link, sized so any single legal frame fits and the
+/// writer never blocks on a reader that has not been polled yet.
+type Link = Pipe<NoopRawMutex, RYNK_BUFFER_SIZE>;
+
+/// Host end of the duplex. Encodes and decodes exactly as a real host does, so
+/// a drift between the two ends fails here rather than on a keyboard.
+struct Host<'p> {
+    rx: &'p Link,
+    tx: &'p Link,
+    df: Deframer,
+    rxbuf: [u8; RYNK_BUFFER_SIZE],
+}
+
+impl Host<'_> {
+    /// Round-trip one request and decode its `Result<Resp, RynkError>` envelope.
+    /// `seq` correlates the reply; topic pushes use seq 0, so request seqs must
+    /// be non-zero to stay unambiguous.
+    async fn request<Req: Serialize, Resp: DeserializeOwned>(
+        &mut self,
+        cmd: Cmd,
+        seq: u8,
+        req: &Req,
+    ) -> Result<Resp, RynkError> {
+        assert_ne!(seq, 0, "request seqs must not alias topic frames");
+        let mut buf = [0u8; RYNK_BUFFER_SIZE];
+        let n = encode_frame(&mut buf, RynkHeader { cmd, seq }, req).expect("build request frame");
+        self.tx.write_all(&buf[..n]).await;
+
+        loop {
+            let (header, payload) = self.recv().await;
+            if header.seq == 0 {
+                continue; // an unsolicited topic push raced the reply
+            }
+            assert_eq!(header.seq, seq, "reply must echo the request seq");
+            assert_eq!(header.cmd, cmd, "reply must echo the request cmd");
+            let (envelope, rest) = postcard::take_from_bytes::<Result<Resp, RynkError>>(&payload)
+                .expect("response payload must decode as an envelope");
+            assert!(rest.is_empty(), "response payload has {} trailing byte(s)", rest.len());
+            return envelope;
+        }
+    }
+
+    /// `run_session` mutes topic pushes until the client has asked for
+    /// capabilities, as every real host does at connect.
+    async fn handshake(&mut self) {
+        self.request::<(), DeviceCapabilities>(Cmd::GetCapabilities, 0x7E, &())
+            .await
+            .expect("handshake");
+    }
+
+    /// Await the next unsolicited topic push and decode its bare payload.
+    /// Stricter than the host's lenient topic decode on purpose: this pins the
+    /// same-version encoder's exact output, trailing bytes included.
+    async fn recv_topic<T: DeserializeOwned>(&mut self, cmd: Cmd) -> T {
+        let (header, payload) = self.recv().await;
+        assert_eq!(header.cmd, cmd, "unexpected topic");
+        assert_eq!(header.seq, 0, "topic frames use seq 0");
+        let (value, rest) = postcard::take_from_bytes::<T>(&payload).expect("topic payload must decode");
+        assert!(rest.is_empty(), "topic payload has {} trailing byte(s)", rest.len());
+        value
+    }
+
+    async fn recv(&mut self) -> (RynkHeader, Vec<u8>) {
+        loop {
+            if let Some(len) = self.df.next(&mut self.rxbuf) {
+                let frame = &self.rxbuf[..len];
+                let header = RynkHeader::parse(frame[..RYNK_HEADER_SIZE].try_into().unwrap());
+                return (header, frame[RYNK_HEADER_SIZE..].to_vec());
+            }
+            let n = self.rx.read(self.df.tail(&mut self.rxbuf)).await;
+            self.df.commit(n);
+        }
+    }
+}
+
+/// Play `script` against `service` over the duplex, running `background`
+/// alongside it for the cases that need a live lighting engine.
+///
+/// The pipes never signal EOF, so `run_session` would loop forever; it is
+/// dropped once the script returns. Its resolving first is a framing bug.
+fn loopback<T>(
+    service: &RynkService<'_>,
+    background: impl Future<Output = ()>,
+    script: impl AsyncFnOnce(&mut Host<'_>) -> T,
+) -> T {
+    let (h2d, d2h) = (Link::new(), Link::new());
+    let (mut dev_rx, mut dev_tx): (&Link, &Link) = (&h2d, &d2h);
+    let mut host = Host {
+        rx: &d2h,
+        tx: &h2d,
+        df: Deframer::new(),
+        rxbuf: [0u8; RYNK_BUFFER_SIZE],
+    };
+    test_block_on(async {
+        // Drain test flash writes so a storage handler cannot block the session.
+        let device = select(
+            select(service.run_session(&mut dev_rx, &mut dev_tx), background),
+            rmk::channel::drain_flash_channel_for_test(),
+        );
+        match select(device, script(&mut host)).await {
+            Either::First(_) => panic!("a service loop ended before the host script finished"),
+            Either::Second(value) => value,
+        }
+    })
+}
+
+static LIGHTING_KEYS: [KeyPosition; 2] = [KeyPosition::new(0, 0), KeyPosition::new(0, 2)];
+static LIGHTING_PHYSICAL_KEYS: [PhysicalKey; 1] = [PhysicalKey {
+    matrix: KeyPosition::new(0, 0),
+    center: Point3::new(Coordinate::ZERO, Coordinate::ONE, Coordinate::ZERO),
+    size: KeySize::ONE,
+    rotation: Rotation::ZERO,
+}];
+static LIGHTING_LEDS: [LedMetadata; 1] = [LedMetadata {
+    id: LedId(99),
+    key: Some(KeyPosition::new(0, 0)),
+    position: None,
+    zones: ZoneSpan::new(0, 0),
+}];
+
+/// A revision other than 0 or 1, so a page pinned to the wrong one is visibly
+/// wrong rather than coincidentally right.
+const TOPOLOGY_REVISION: u32 = 23;
+
+fn descriptor() -> RynkLightingDescriptor<'static> {
+    RynkLightingDescriptor {
+        topology_revision: TOPOLOGY_REVISION,
+        topology: LightingTopology {
+            matrix: MatrixSize::new(1, 3),
+            keys: &LIGHTING_KEYS,
+            physical_layout: PhysicalLayout::new(&LIGHTING_PHYSICAL_KEYS),
+            leds: &LIGHTING_LEDS,
+            zones: &[],
+            zone_memberships: &[],
+        },
+        routing: LightingRouting {
+            outputs: &[],
+            routes: &[],
+        },
+    }
+}
+
+/// A 1x3 service matching the descriptor's matrix, always unlocked so these
+/// cases exercise lighting rather than the lock gate.
+fn service_with(controller: RynkLightingController<'static>) -> RynkService<'static> {
+    let mut config = RmkConfig::default();
+    config.lock_config.insecure = true;
+    let config: &'static RmkConfig<'static> = Box::leak(Box::new(config));
+
+    let behavior: &'static mut BehaviorConfig = Box::leak(Box::new(BehaviorConfig::default()));
+    let positional: &'static PositionalConfig<1, 3> = Box::leak(Box::new(PositionalConfig::default()));
+    let data = Box::leak(Box::new(KeymapData::new([[[KeyAction::No; 3]; 1]])));
+    let keymap: &'static KeyMap<'static> = Box::leak(Box::new(test_block_on(KeyMap::new(data, behavior, positional))));
+
+    RynkService::new(keymap, config).with_lighting(controller)
+}
+
+/// Topology readback answers from the descriptor, so this needs no engine.
+fn descriptor_only_service() -> RynkService<'static> {
+    let mailbox: &'static RynkLightingMailbox = Box::leak(Box::new(RynkLightingMailbox::new()));
+    service_with(RynkLightingController::new(mailbox, descriptor(), 8))
+}
+
+#[test]
+fn lighting_discovery_and_revision_pinned_keys_cross_the_full_loopback() {
+    let service = descriptor_only_service();
+    loopback(&service, core::future::pending(), async |host| {
+        let caps = host
+            .request::<(), DeviceCapabilities>(Cmd::GetCapabilities, 0x71, &())
+            .await
+            .expect("outer capability envelope");
+        assert!(caps.lighting_enabled);
+
+        let keys = host
+            .request::<_, LightingKeysPageResult>(
+                Cmd::GetLightingKeys,
+                0x72,
+                &LightingPageRequest {
+                    topology_revision: TOPOLOGY_REVISION,
+                    offset: 0,
+                },
+            )
+            .await
+            .expect("outer keys envelope")
+            .expect("lighting keys page");
+        assert_eq!(keys.total_count, 2);
+        assert_eq!(keys.items[1], LightingMatrixPosition { row: 0, col: 2 });
+
+        // A page pinned to a topology the board no longer serves is refused
+        // rather than answered from the current one.
+        let stale = host
+            .request::<_, LightingKeysPageResult>(
+                Cmd::GetLightingKeys,
+                0x73,
+                &LightingPageRequest {
+                    topology_revision: TOPOLOGY_REVISION - 1,
+                    offset: 0,
+                },
+            )
+            .await
+            .expect("outer stale-page envelope");
+        assert_eq!(
+            stale,
+            Err(LightingError::TopologyRevisionConflict {
+                expected: TOPOLOGY_REVISION - 1,
+                current: TOPOLOGY_REVISION,
+            })
+        );
+    });
+}
+
+/// The lighting readback invalidation is a bare signal: hosts re-read rather
+/// than diff it, so the topic carries no state.
+#[test]
+fn topic_lighting_change_is_a_best_effort_readback_invalidation() {
+    let service = descriptor_only_service();
+    loopback(&service, core::future::pending(), async |host| {
+        host.handshake().await;
+        publish_event(rmk::event::LightingChangedEvent::new());
+        host.recv_topic::<LightingChanged>(Cmd::LightingChange).await;
+    });
+}
+
+/// Zero-target lighting source serving only the extension hooks, so the
+/// extension endpoints are exercised without a renderable board.
+struct ExtensionOnlySource {
+    state: rmk::lighting::compositor::ExtensionState,
+}
+
+impl<Context> rmk::lighting::compositor::LightingSource<rmk::lighting::Rgb8, Context> for ExtensionOnlySource {
+    fn len(&self, _: &rmk::lighting::compositor::RenderInput<'_, Context>) -> usize {
+        0
+    }
+
+    fn slot(&self, _: usize, _: &rmk::lighting::compositor::RenderInput<'_, Context>) -> rmk::lighting::LedSlot {
+        unreachable!("extension-only source has no targets")
+    }
+
+    fn contribution(
+        &mut self,
+        _: usize,
+        _: &rmk::lighting::compositor::RenderInput<'_, Context>,
+    ) -> rmk::lighting::compositor::Contribution<rmk::lighting::Rgb8> {
+        unreachable!("extension-only source has no samples")
+    }
+
+    fn extension_descriptor(&self) -> Option<rmk::lighting::compositor::ExtensionDescriptor> {
+        Some(rmk::lighting::compositor::ExtensionDescriptor {
+            effects: &["Gradient", "Flow"],
+            palettes: &["Lava", "Ocean", "Forest"],
+            params: &[],
+        })
+    }
+
+    fn extension_state(&self) -> Option<rmk::lighting::compositor::ExtensionState> {
+        Some(self.state)
+    }
+
+    fn apply_extension_state(&mut self, state: rmk::lighting::compositor::ExtensionState) -> bool {
+        self.state = state;
+        true
+    }
+}
+
+/// The whole stack for the extension endpoints: wire frames → dispatch →
+/// handler → protocol mailbox → adapter → standard engine, and back.
+#[test]
+fn lighting_extension_endpoints_cross_the_full_loopback() {
+    use rmk::host::StandardRynkLightingAdapter;
+    use rmk::lighting::compositor::ExtensionState;
+    use rmk::lighting::{
+        BackgroundState, EmptySource, LayerPolicy, LayerScenes, LightingContext, LightingEngine, LightingMailbox,
+        StandardCommand, StandardError, StandardLightingEngine, StandardReply,
+    };
+    use rmk_types::protocol::rynk::{
+        LightingCapabilitiesResult, LightingExtensionNameKind, LightingExtensionNamesPageResult,
+        LightingExtensionNamesRequest, LightingExtensionResult, LightingExtensionState, LightingFeatureFlags,
+        LightingStateResult, SetLightingExtensionStateRequest,
+    };
+
+    let mailbox: &'static RynkLightingMailbox = Box::leak(Box::new(RynkLightingMailbox::new()));
+    let service = service_with(RynkLightingController::new(mailbox, descriptor(), 8).with_extension_effects());
+
+    let core = LightingMailbox::<StandardCommand<2>, StandardReply, StandardError, 1>::new();
+    let mut adapter = StandardRynkLightingAdapter::<2, 1>::new(mailbox, &core, descriptor().topology);
+    let mut engine: StandardLightingEngine<'static, ExtensionOnlySource, EmptySource, 1, 2, 0> =
+        StandardLightingEngine::new(
+            BackgroundState::default(),
+            LayerScenes {
+                scenes: &[],
+                policy: LayerPolicy::EffectiveOnly,
+            },
+            ExtensionOnlySource {
+                state: ExtensionState {
+                    effect: 0,
+                    palette: 2,
+                    value: 200,
+                    speed: 40,
+                },
+            },
+            EmptySource,
+        );
+
+    let context = LightingContext::default();
+    let engine_and_adapter = async {
+        let adapter_loop = async {
+            loop {
+                adapter.process_next().await;
+            }
+        };
+        let engine_loop = async {
+            loop {
+                let (id, command) = core.receive_request().await;
+                let result = engine.handle_command(0, command, &context).map(|outcome| outcome.reply);
+                core.publish_reply(id, result);
+            }
+        };
+        select(adapter_loop, engine_loop).await;
+    };
+
+    loopback(&service, engine_and_adapter, async |host| {
+        let caps = host
+            .request::<(), LightingCapabilitiesResult>(Cmd::GetLightingCapabilities, 0x74, &())
+            .await
+            .expect("outer capabilities envelope")
+            .expect("lighting capabilities");
+        assert!(caps.features.contains(LightingFeatureFlags::EXTENSION_EFFECTS));
+
+        let extension = host
+            .request::<(), LightingExtensionResult>(Cmd::GetLightingExtension, 0x75, &())
+            .await
+            .expect("outer extension envelope")
+            .expect("extension discovery");
+        assert_eq!(extension.revision, 0);
+        assert_eq!(extension.effect_count, 2);
+        assert_eq!(extension.palette_count, 3);
+        assert_eq!(
+            extension.state,
+            LightingExtensionState {
+                effect: 0,
+                palette: 2,
+                value: 200,
+                speed: 40,
+            }
+        );
+
+        let palettes = host
+            .request::<_, LightingExtensionNamesPageResult>(
+                Cmd::GetLightingExtensionNames,
+                0x76,
+                &LightingExtensionNamesRequest {
+                    kind: LightingExtensionNameKind::Palettes,
+                    offset: 0,
+                },
+            )
+            .await
+            .expect("outer names envelope")
+            .expect("palette names page");
+        assert_eq!(palettes.total, 3);
+        assert_eq!(palettes.items.len(), 3);
+        assert_eq!(palettes.items[1].as_str(), "Ocean");
+
+        let selected = LightingExtensionState {
+            effect: 1,
+            palette: 0,
+            value: 9,
+            speed: 8,
+        };
+        let state = host
+            .request::<_, LightingStateResult>(
+                Cmd::SetLightingExtensionState,
+                0x77,
+                &SetLightingExtensionStateRequest {
+                    expected_revision: 0,
+                    state: selected,
+                },
+            )
+            .await
+            .expect("outer set envelope")
+            .expect("extension selection");
+        assert_eq!(state.revision, 1);
+
+        let extension = host
+            .request::<(), LightingExtensionResult>(Cmd::GetLightingExtension, 0x78, &())
+            .await
+            .expect("outer extension envelope")
+            .expect("extension readback");
+        assert_eq!(extension.revision, 1);
+        assert_eq!(extension.state, selected);
+
+        // The write bumped the revision, so replaying the same expectation is
+        // now a stale write rather than an idempotent one.
+        let stale = host
+            .request::<_, LightingStateResult>(
+                Cmd::SetLightingExtensionState,
+                0x79,
+                &SetLightingExtensionStateRequest {
+                    expected_revision: 0,
+                    state: selected,
+                },
+            )
+            .await
+            .expect("outer stale envelope");
+        assert_eq!(
+            stale,
+            Err(LightingError::StateRevisionConflict {
+                expected: 0,
+                current: 1,
+            })
+        );
+    });
+}
+
+/// A board that never advertised extension effects refuses the endpoint before
+/// it can reach any mailbox — which is why this needs no engine behind it.
+#[test]
+fn extension_endpoints_are_unsupported_until_a_board_advertises_them() {
+    use rmk_types::protocol::rynk::LightingExtensionResult;
+
+    let service = descriptor_only_service();
+    loopback(&service, core::future::pending(), async |host| {
+        let unsupported = host
+            .request::<(), LightingExtensionResult>(Cmd::GetLightingExtension, 0x7A, &())
+            .await
+            .expect("outer unsupported envelope");
+        assert_eq!(unsupported, Err(LightingError::Unsupported));
+    });
+}

From 24015892b6912437efae24b2c9a44d722664ab4f Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 03:01:14 -0700
Subject: [PATCH 58/78] feat(lighting): support an extension overlay layer

---
 .../main/docs/development/rynk_protocol.md    |  2 +
 rmk-types/src/protocol/rynk/command.rs        | 23 ++++--
 .../src/protocol/rynk/payload/lighting.rs     | 34 ++++++++
 .../rynk/snapshots/lighting_wire_frames.snap  |  4 +
 rmk-types/src/protocol/rynk/tests.rs          | 32 ++++++++
 rmk/src/host/rynk/handlers/lighting.rs        | 73 +++++++++++++----
 rmk/src/host/rynk/lighting.rs                 | 71 ++++++++++++++++-
 rmk/src/host/rynk/mod.rs                      |  5 ++
 rmk/src/lighting/compositor.rs                | 20 +++++
 rmk/src/lighting/standard/command.rs          | 18 ++++-
 rmk/src/lighting/standard/engine.rs           | 64 +++++++++++++++
 rmk/src/lighting/standard/tests.rs            | 70 ++++++++++++++++-
 rmk/src/storage/mod.rs                        | 46 +++++++++++
 rynk/rynk-wasm/src/client.rs                  | 43 +++++-----
 rynk/src/api.rs                               | 78 +++++++++++--------
 15 files changed, 501 insertions(+), 82 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 7fd6ea176..3e7be3ff2 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -123,6 +123,8 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x092B` | `GetLightingExtensionParams`                   | `LightingExtensionParamsRequest`                      | `LightingExtensionParamsPageResult`                | `lighting`       | Per-effect tunable parameters: descriptors plus live values, pinned to `LightingState.revision`. Page until `total`.                   |
 | `0x092C` | `SetLightingExtensionParam`                    | `SetLightingExtensionParamRequest`                    | `LightingStateResult`                              | `lighting`       | Set one effect parameter when the state revision matches.                                                                              |
 | `0x092D` | `SetLightingWakeLayers`                        | `SetLightingWakeLayersRequest`                        | `LightingOutputModeStateResult`                    | `lighting`       | Replace the wake-layer mask. Policy rather than lighting content, but dynamic so which layers wake lighting is not a firmware rebuild. |
+| `0x092E` | `GetLightingExtensionLayers`                   | `()`                                                  | `LightingExtensionLayersResult`                    | `lighting`       | Read the optional second effect layered over the primary extension.                                                                    |
+| `0x092F` | `SetLightingExtensionLayers`                   | `SetLightingExtensionLayersRequest`                   | `LightingStateResult`                              | `lighting`       | Replace the optional second effect when the state revision matches.                                                                    |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 028ea6f49..4cd86e3e0 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -41,18 +41,19 @@ use crate::protocol::rynk::{
     CommitLightingOverlayReplaceRequest, CommitLightingRuntimeConditionalSceneReplaceRequest,
     CommitLightingSceneReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingCompiledSceneStatusResult,
     LightingCompiledScenesPageResult, LightingConditionalSceneStatusResult, LightingConditionalScenesPageResult,
-    LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionParamsPageResult,
-    LightingExtensionParamsRequest, LightingExtensionResult, LightingKeysPageResult, LightingLedsPageResult,
-    LightingOutputModeStateResult, LightingOutputsPageResult, LightingOverlayPageRequest, LightingOverlayPageResult,
-    LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKeysPageResult, LightingRoutesPageResult,
-    LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatusResult,
+    LightingExtensionLayersResult, LightingExtensionNamesPageResult, LightingExtensionNamesRequest,
+    LightingExtensionParamsPageResult, LightingExtensionParamsRequest, LightingExtensionResult, LightingKeysPageResult,
+    LightingLedsPageResult, LightingOutputModeStateResult, LightingOutputsPageResult, LightingOverlayPageRequest,
+    LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKeysPageResult,
+    LightingRoutesPageResult, LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatusResult,
     LightingRuntimeConditionalSceneTransactionResult, LightingRuntimeConditionalScenesPageResult,
     LightingScenePageRequest, LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult,
     LightingStateResult, LightingUnitResult, LightingZoneMembershipsPageResult, LightingZonesPageResult,
     PutLightingOverlayChunkRequest, PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest,
-    SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
-    SetLightingOutputModeRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
-    SetLightingWakeLayersRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
+    SetLightingExtensionLayersRequest, SetLightingExtensionParamRequest, SetLightingExtensionStateRequest,
+    SetLightingLayerPolicyRequest, SetLightingOutputModeRequest, SetLightingOverlayRequest,
+    SetLightingSceneCellRequest, SetLightingStateRequest, SetLightingWakeLayersRequest, UnsetLightingOverlayRequest,
+    UnsetLightingSceneCellRequest,
 };
 #[cfg(all(feature = "_ble", feature = "split"))]
 use crate::protocol::rynk::{SplitCentralLatencyPolicy, SplitCentralLatencyState};
@@ -489,6 +490,12 @@ endpoints! {
     /// dynamic so which layers wake lighting is not a firmware rebuild.
     #[cfg(feature = "lighting")]
     SetLightingWakeLayers = 0x092D: SetLightingWakeLayersRequest => LightingOutputModeStateResult;
+    /// Read the optional second effect layered over the primary extension.
+    #[cfg(feature = "lighting")]
+    GetLightingExtensionLayers = 0x092E: () => LightingExtensionLayersResult;
+    /// Replace the optional second effect when the state revision matches.
+    #[cfg(feature = "lighting")]
+    SetLightingExtensionLayers = 0x092F: SetLightingExtensionLayersRequest => LightingStateResult;
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 63a79ff34..c0e9cda81 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -202,6 +202,9 @@ impl LightingFeatureFlags {
     pub const EXTENSION_EFFECTS: u16 = 1 << 11;
     /// Persistent, ordered conditional rules authored at runtime.
     pub const RUNTIME_CONDITIONAL_SCENES: u16 = 1 << 12;
+    /// A second effect from the extension's ordinary effect list can be
+    /// rendered over the primary effect.
+    pub const EXTENSION_LAYERING: u16 = 1 << 13;
 
     pub const fn contains(self, bits: u16) -> bool {
         self.0 & bits == bits
@@ -765,6 +768,22 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Optional second effect layered over the primary extension selection.
+    /// The effect indexes the same list as `LightingExtensionState.effect`.
+    pub struct LightingExtensionLayers {
+        pub revision: u32,
+        pub overlay: Option<u8>,
+    }
+}
+
+wire_type! {
+    pub struct SetLightingExtensionLayersRequest {
+        pub expected_revision: u32,
+        pub overlay: Option<u8>,
+    }
+}
+
 /// One tunable parameter advertised by an extension effect: its static
 /// descriptor plus the source's live value. Descriptor and value travel in
 /// one row so a host can render a control from a single read.
@@ -1070,6 +1089,7 @@ pub type LightingConditionalSceneStatusResult = LightingResult<LightingCondition
 pub type LightingConditionalScenesPageResult = LightingResult<LightingConditionalScenesPage>;
 pub type LightingOutputModeStateResult = LightingResult<LightingOutputModeState>;
 pub type LightingExtensionResult = LightingResult<LightingExtension>;
+pub type LightingExtensionLayersResult = LightingResult<LightingExtensionLayers>;
 pub type LightingExtensionNamesPageResult = LightingResult<LightingExtensionNamesPage>;
 pub type LightingExtensionParamsPageResult = LightingResult<LightingExtensionParamsPage>;
 pub type LightingSceneTransactionResult = LightingResult<LightingSceneTransaction>;
@@ -1122,6 +1142,8 @@ const _: () = {
     assert_endpoint_fits!((), LightingExtensionResult);
     assert_endpoint_fits!(LightingExtensionNamesRequest, LightingExtensionNamesPageResult);
     assert_endpoint_fits!(SetLightingExtensionStateRequest, LightingStateResult);
+    assert_endpoint_fits!((), LightingExtensionLayersResult);
+    assert_endpoint_fits!(SetLightingExtensionLayersRequest, LightingStateResult);
     assert_endpoint_fits!(LightingExtensionParamsRequest, LightingExtensionParamsPageResult);
     assert_endpoint_fits!(SetLightingExtensionParamRequest, LightingStateResult);
     assert_endpoint_fits!(SetLightingOutputModeRequest, LightingOutputModeStateResult);
@@ -1352,6 +1374,18 @@ mod tests {
             value: 3,
             speed: 4,
         });
+        round_trip(&LightingExtensionLayers {
+            revision: 5,
+            overlay: Some(6),
+        });
+        round_trip(&LightingExtensionLayers {
+            revision: 5,
+            overlay: None,
+        });
+        round_trip(&SetLightingExtensionLayersRequest {
+            expected_revision: 5,
+            overlay: Some(6),
+        });
         round_trip(&LightingExtension {
             revision: u32::MAX,
             effect_count: 6,
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index 0fc123226..3a3ea9d84 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -34,6 +34,8 @@ GetLightingCompiledScenes request                      05 1d 09 01 01 01 00
 GetLightingExtension inner Err(Unsupported)            04 21 09 01 02 01 01 00
 GetLightingExtension reply                             04 21 09 01 01 08 09 06 10 01 02 03 04 00
 GetLightingExtension request                           04 21 09 01 00
+GetLightingExtensionLayers reply                       04 2e 09 01 01 04 09 01 05 00
+GetLightingExtensionLayers request                     04 2e 09 01 00
 GetLightingExtensionNames reply                        04 22 09 01 01 09 10 01 05 4f 63 65 61 6e 00
 GetLightingExtensionNames request                      06 22 09 01 01 08 00
 GetLightingExtensionParams reply                       04 2b 09 01 01 10 09 02 01 07 44 65 6e 73 69 74 79 01 08 03 05 00
@@ -74,6 +76,8 @@ PutLightingRuntimeConditionalSceneChunk reply          04 28 09 01 01 01 00
 PutLightingRuntimeConditionalSceneChunk request        05 28 09 01 1f 0c 01 01 02 01 01 01 01 14 01 50 02 02 2a 04 07 08 09 00
 PutLightingSceneChunk reply                            04 17 09 01 01 01 00
 PutLightingSceneChunk request                          05 17 09 01 15 04 01 02 2a 04 07 08 09 00
+SetLightingExtensionLayers reply                       04 2f 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingExtensionLayers request                     07 2f 09 01 09 01 05 00
 SetLightingExtensionParam reply                        04 2c 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
 SetLightingExtensionParam request                      06 2c 09 01 09 01 02 05 00
 SetLightingExtensionState reply                        04 23 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index f7a52738b..c964550e1 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1340,6 +1340,14 @@ fn lighting_wire_frames_locked() {
         expected_revision: state.revision,
         state: extension.state,
     };
+    let extension_layers = LightingExtensionLayers {
+        revision: state.revision,
+        overlay: Some(5),
+    };
+    let set_extension_layers = SetLightingExtensionLayersRequest {
+        expected_revision: state.revision,
+        overlay: Some(5),
+    };
     let extension_params_request = LightingExtensionParamsRequest { effect: 1, offset: 0 };
     let extension_params_page = LightingExtensionParamsPage {
         revision: state.revision,
@@ -1980,6 +1988,30 @@ fn lighting_wire_frames_locked() {
                 &Ok::<LightingStateResult, RynkError>(Ok(state))
             )
         ),
+        (
+            "GetLightingExtensionLayers request",
+            encode_frame(Cmd::GetLightingExtensionLayers, SEQ, &())
+        ),
+        (
+            "GetLightingExtensionLayers reply",
+            encode_frame(
+                Cmd::GetLightingExtensionLayers,
+                SEQ,
+                &Ok::<LightingExtensionLayersResult, RynkError>(Ok(extension_layers))
+            )
+        ),
+        (
+            "SetLightingExtensionLayers request",
+            encode_frame(Cmd::SetLightingExtensionLayers, SEQ, &set_extension_layers)
+        ),
+        (
+            "SetLightingExtensionLayers reply",
+            encode_frame(
+                Cmd::SetLightingExtensionLayers,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
         (
             "GetLightingExtensionParams request",
             encode_frame(Cmd::GetLightingExtensionParams, SEQ, &extension_params_request)
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 3fa5f0a1e..1309c8c31 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -6,13 +6,13 @@ use rmk_types::protocol::rynk::command::{
     AbortLightingRuntimeConditionalSceneReplace, BeginLightingRuntimeConditionalSceneReplace, ClearLightingOverlay,
     CommitLightingRuntimeConditionalSceneReplace, GetLightingCapabilities, GetLightingCompiledSceneStatus,
     GetLightingCompiledScenes, GetLightingConditionalSceneStatus, GetLightingConditionalScenes, GetLightingExtension,
-    GetLightingExtensionNames, GetLightingExtensionParams, GetLightingKeys, GetLightingLeds, GetLightingOutputMode,
-    GetLightingOutputs, GetLightingOverlay, GetLightingPhysicalKeys, GetLightingRoutes,
-    GetLightingRuntimeConditionalSceneStatus, GetLightingRuntimeConditionalScenes, GetLightingSceneStatus,
-    GetLightingScenes, GetLightingState, GetLightingZoneMemberships, GetLightingZones,
-    PutLightingRuntimeConditionalSceneChunk, SetLightingExtensionParam, SetLightingExtensionState,
-    SetLightingLayerPolicy, SetLightingOutputMode, SetLightingOverlay, SetLightingSceneCell, SetLightingState,
-    SetLightingWakeLayers, UnsetLightingOverlay, UnsetLightingSceneCell,
+    GetLightingExtensionLayers, GetLightingExtensionNames, GetLightingExtensionParams, GetLightingKeys,
+    GetLightingLeds, GetLightingOutputMode, GetLightingOutputs, GetLightingOverlay, GetLightingPhysicalKeys,
+    GetLightingRoutes, GetLightingRuntimeConditionalSceneStatus, GetLightingRuntimeConditionalScenes,
+    GetLightingSceneStatus, GetLightingScenes, GetLightingState, GetLightingZoneMemberships, GetLightingZones,
+    PutLightingRuntimeConditionalSceneChunk, SetLightingExtensionLayers, SetLightingExtensionParam,
+    SetLightingExtensionState, SetLightingLayerPolicy, SetLightingOutputMode, SetLightingOverlay, SetLightingSceneCell,
+    SetLightingState, SetLightingWakeLayers, UnsetLightingOverlay, UnsetLightingSceneCell,
 };
 use rmk_types::protocol::rynk::{
     AbortLightingOverlayReplaceRequest, AbortLightingRuntimeConditionalSceneReplaceRequest,
@@ -24,9 +24,9 @@ use rmk_types::protocol::rynk::{
     LightingCompiledSceneStatus, LightingCompiledSceneStatusResult, LightingCompiledScenesPageResult,
     LightingConditionalSceneCell, LightingConditionalSceneStatus, LightingConditionalSceneStatusResult,
     LightingConditionalScenesPage, LightingConditionalScenesPageResult, LightingEffectFlags, LightingError,
-    LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionParamsPageResult,
-    LightingExtensionParamsRequest, LightingExtensionResult, LightingFeatureFlags, LightingKeysPage,
-    LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
+    LightingExtensionLayersResult, LightingExtensionNamesPageResult, LightingExtensionNamesRequest,
+    LightingExtensionParamsPageResult, LightingExtensionParamsRequest, LightingExtensionResult, LightingFeatureFlags,
+    LightingKeysPage, LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
     LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage,
     LightingOutputModeStateResult, LightingOutputsPage, LightingOutputsPageResult, LightingOverlayCell,
     LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransaction,
@@ -39,9 +39,10 @@ use rmk_types::protocol::rynk::{
     LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage,
     LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult, PutLightingOverlayChunkRequest,
     PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, RynkError, RynkMessage,
-    SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
-    SetLightingOutputModeRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
-    SetLightingWakeLayersRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
+    SetLightingExtensionLayersRequest, SetLightingExtensionParamRequest, SetLightingExtensionStateRequest,
+    SetLightingLayerPolicyRequest, SetLightingOutputModeRequest, SetLightingOverlayRequest,
+    SetLightingSceneCellRequest, SetLightingStateRequest, SetLightingWakeLayersRequest, UnsetLightingOverlayRequest,
+    UnsetLightingSceneCellRequest,
 };
 
 use super::super::lighting::{
@@ -77,6 +78,14 @@ fn extension_controller<'a>(service: &RynkService<'a>) -> LightingResult<RynkLig
     Ok(controller)
 }
 
+fn extension_layer_controller<'a>(service: &RynkService<'a>) -> LightingResult<RynkLightingController<'a>> {
+    let controller = extension_controller(service)?;
+    if !controller.extension_layering {
+        return Err(LightingError::Unsupported);
+    }
+    Ok(controller)
+}
+
 fn runtime_conditional_scene_controller<'a>(service: &RynkService<'a>) -> LightingResult<RynkLightingController<'a>> {
     let controller = controller(service)?;
     if controller.runtime_conditional_scene_capacity == 0 {
@@ -737,6 +746,37 @@ impl Handle<SetLightingExtensionState> for RynkService<'_> {
     }
 }
 
+impl Handle<GetLightingExtensionLayers> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LightingExtensionLayersResult, RynkError> {
+        let result = match extension_layer_controller(self) {
+            Ok(controller) => match controller.request(RynkLightingCommand::ReadExtensionLayers).await {
+                Ok(RynkLightingReadback::ExtensionLayers(layers)) => Ok(layers),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
+impl Handle<SetLightingExtensionLayers> for RynkService<'_> {
+    async fn handle(&self, req: SetLightingExtensionLayersRequest) -> Result<LightingStateResult, RynkError> {
+        let result = match extension_layer_controller(self) {
+            Ok(controller) => {
+                controller
+                    .request_state(RynkLightingCommand::SetExtensionLayers {
+                        expected_revision: req.expected_revision,
+                        overlay: req.overlay,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        };
+        Ok(result)
+    }
+}
+
 impl Handle<GetLightingExtensionParams> for RynkService<'_> {
     async fn handle(
         &self,
@@ -859,6 +899,9 @@ fn capabilities(binding: RynkLightingController<'_>) -> LightingCapabilities {
     if binding.extension_effects {
         features.0 |= LightingFeatureFlags::EXTENSION_EFFECTS;
     }
+    if binding.extension_layering {
+        features.0 |= LightingFeatureFlags::EXTENSION_LAYERING;
+    }
     LightingCapabilities {
         topology_revision: descriptor.topology_revision,
         logical_key_count: count(topology.keys.len()),
@@ -1299,9 +1342,9 @@ mod tests {
 
     use embassy_futures::join::join;
     use rmk_types::action::KeyAction;
-    use rmk_types::protocol::rynk::command::Endpoint;
     use rmk_types::protocol::rynk::command::{
-        BeginLightingOverlayReplace, CommitLightingOverlayReplace, GetCapabilities, GetLightingKeys, SetLightingState,
+        BeginLightingOverlayReplace, CommitLightingOverlayReplace, Endpoint, GetCapabilities, GetLightingKeys,
+        SetLightingState,
     };
     use serde::Serialize;
     use serde::de::DeserializeOwned;
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 1e68a558f..5e0d2539c 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -18,8 +18,8 @@ use rmk_types::protocol::rynk::{
     LIGHTING_EXTENSION_NAME_CHUNK, LIGHTING_EXTENSION_NAME_SIZE, LIGHTING_EXTENSION_PARAM_CHUNK,
     LIGHTING_OVERLAY_CHUNK_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState,
     LightingCompiledScenesPage, LightingConditionalSceneCell as WireConditionalSceneCell,
-    LightingControls as WireLightingControls, LightingError, LightingExtension, LightingExtensionNameKind,
-    LightingExtensionNamesPage, LightingExtensionParam, LightingExtensionParamsPage,
+    LightingControls as WireLightingControls, LightingError, LightingExtension, LightingExtensionLayers,
+    LightingExtensionNameKind, LightingExtensionNamesPage, LightingExtensionParam, LightingExtensionParamsPage,
     LightingExtensionState as WireExtensionState, LightingLayerPolicy, LightingMutableState,
     LightingOutputMode as WireLightingOutputMode, LightingOutputModeIndicator as WireLightingOutputModeIndicator,
     LightingOutputModeState, LightingOverlayCell, LightingOverlayPage, LightingResult, LightingRgb8,
@@ -80,6 +80,7 @@ pub struct RynkLightingController<'a> {
     /// Whether the board wired a host-selectable extension source; gates the
     /// `EXTENSION_EFFECTS` capability bit and the extension endpoints.
     pub(super) extension_effects: bool,
+    pub(super) extension_layering: bool,
     mailbox: &'a RynkLightingMailbox,
 }
 
@@ -111,6 +112,7 @@ impl<'a> RynkLightingController<'a> {
                 output_mode_indicator: None,
             },
             extension_effects: false,
+            extension_layering: false,
             mailbox,
         }
     }
@@ -122,6 +124,12 @@ impl<'a> RynkLightingController<'a> {
         self
     }
 
+    /// Advertise an optional second effect from the extension's same list.
+    pub const fn with_extension_layering(mut self) -> Self {
+        self.extension_layering = true;
+        self
+    }
+
     /// Advertise runtime scene support. Pass the engine's scene capacity;
     /// boards without a scene table simply skip this call.
     pub const fn with_scene_capacity(mut self, scene_capacity: u16) -> Self {
@@ -251,6 +259,7 @@ pub enum RynkLightingReadback {
     CompiledScenesPage(LightingCompiledScenesPage),
     SceneTransaction(LightingSceneTransaction),
     Extension(LightingExtension),
+    ExtensionLayers(LightingExtensionLayers),
     ExtensionNamesPage(LightingExtensionNamesPage),
     ExtensionParamsPage(LightingExtensionParamsPage),
     RuntimeConditionalScenesPage(LightingRuntimeConditionalScenesPage),
@@ -436,6 +445,11 @@ pub(super) enum RynkLightingCommand {
         expected_revision: u32,
         state: WireExtensionState,
     },
+    ReadExtensionLayers,
+    SetExtensionLayers {
+        expected_revision: u32,
+        overlay: Option<u8>,
+    },
     ReadExtensionParams {
         effect: u8,
         offset: u8,
@@ -618,7 +632,7 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
     #[cfg(feature = "storage")]
     async fn persist_extension(&self) {
         use crate::channel::FLASH_CHANNEL;
-        use crate::storage::{FlashOperationMessage, LightingExtensionRecord};
+        use crate::storage::{FlashOperationMessage, LightingExtensionOverlayRecord, LightingExtensionRecord};
 
         let Ok(page) = self.request_extension_page().await else {
             return;
@@ -654,6 +668,32 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                 params,
             }))
             .await;
+
+        let overlay = match self.request_core(StandardCommand::ReadExtensionLayers).await {
+            Ok(StandardReply::ExtensionLayers(page)) => page.state.and_then(|state| state.overlay),
+            _ => None,
+        };
+        let mut overlay_params = [0u8; LIGHTING_EXTENSION_PARAM_CHUNK];
+        let mut overlay_param_len = 0u8;
+        if let Some(effect) = overlay
+            && let Ok(StandardReply::ExtensionParams(page)) = self
+                .request_core(StandardCommand::ReadExtensionParams { effect, offset: 0 })
+                .await
+        {
+            for (slot, entry) in overlay_params.iter_mut().zip(page.items()) {
+                *slot = entry.value;
+                overlay_param_len += 1;
+            }
+        }
+        FLASH_CHANNEL
+            .send(FlashOperationMessage::LightingExtensionOverlay(
+                LightingExtensionOverlayRecord {
+                    effect: overlay,
+                    param_len: overlay_param_len,
+                    params: overlay_params,
+                },
+            ))
+            .await;
     }
 
     #[cfg(not(feature = "storage"))]
@@ -942,6 +982,31 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                     .await?;
                 return Ok(RynkLightingReadback::State(state_to_wire(state)));
             }
+            RynkLightingCommand::ReadExtensionLayers => {
+                let page = match self.request_core(StandardCommand::ReadExtensionLayers).await? {
+                    StandardReply::ExtensionLayers(page) => page,
+                    _ => return Err(LightingError::InvalidRequest),
+                };
+                let Some(state) = page.state else {
+                    return Err(LightingError::Unsupported);
+                };
+                return Ok(RynkLightingReadback::ExtensionLayers(LightingExtensionLayers {
+                    revision: page.revision,
+                    overlay: state.overlay,
+                }));
+            }
+            RynkLightingCommand::SetExtensionLayers {
+                expected_revision,
+                overlay,
+            } => {
+                let state = self
+                    .extension_mutation(StandardCommand::SetExtensionLayersIfRevision {
+                        expected_revision,
+                        state: crate::lighting::compositor::ExtensionLayerState { overlay },
+                    })
+                    .await?;
+                return Ok(RynkLightingReadback::State(state_to_wire(state)));
+            }
             RynkLightingCommand::ReadExtensionParams { effect, offset } => {
                 let page = match self
                     .request_core(StandardCommand::ReadExtensionParams { effect, offset })
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index a0d77c8bc..ffc7cd7df 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -184,6 +184,7 @@ impl<'a> RynkService<'a> {
             | Cmd::CommitLightingSceneReplace
             | Cmd::AbortLightingSceneReplace
             | Cmd::SetLightingExtensionState
+            | Cmd::SetLightingExtensionLayers
             | Cmd::SetLightingExtensionParam
             | Cmd::SetLightingOutputMode
             | Cmd::SetLightingWakeLayers
@@ -335,6 +336,10 @@ impl<'a> RynkService<'a> {
             #[cfg(feature = "lighting")]
             Cmd::SetLightingExtensionState => serve::<command::SetLightingExtensionState, _>(self, msg).await,
             #[cfg(feature = "lighting")]
+            Cmd::GetLightingExtensionLayers => serve::<command::GetLightingExtensionLayers, _>(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::SetLightingExtensionLayers => serve::<command::SetLightingExtensionLayers, _>(self, msg).await,
+            #[cfg(feature = "lighting")]
             Cmd::GetLightingExtensionParams => serve::<command::GetLightingExtensionParams, _>(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::SetLightingExtensionParam => serve::<command::SetLightingExtensionParam, _>(self, msg).await,
diff --git a/rmk/src/lighting/compositor.rs b/rmk/src/lighting/compositor.rs
index 85e4a3e44..2f12be923 100644
--- a/rmk/src/lighting/compositor.rs
+++ b/rmk/src/lighting/compositor.rs
@@ -70,6 +70,19 @@ pub trait LightingSource<C, Context> {
         false
     }
 
+    /// Optional second effect layered over [`Self::extension_state`]'s
+    /// primary effect. `None` means this source has no layering surface;
+    /// support with an empty overlay is `Some` with `overlay: None`.
+    fn extension_layer_state(&self) -> Option<ExtensionLayerState> {
+        None
+    }
+
+    /// Apply the optional second effect. A present effect indexes the same
+    /// descriptor list as the primary effect.
+    fn apply_extension_layer_state(&mut self, _state: ExtensionLayerState) -> bool {
+        false
+    }
+
     /// Live value of one per-effect parameter, addressed by the effect's
     /// index in [`ExtensionDescriptor::effects`] and the parameter's ordinal
     /// in that effect's [`ExtensionDescriptor::params`] row. `None` means the
@@ -133,6 +146,13 @@ pub struct ExtensionState {
     pub speed: u8,
 }
 
+/// Orthogonal layering state for an extension source. Kept separate from
+/// [`ExtensionState`] so its established wire representation stays stable.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionLayerState {
+    pub overlay: Option<u8>,
+}
+
 /// User-level transform applied after composition but before changed
 /// detection. Hard electrical limits remain the output driver's job.
 pub trait OutputTransform<C> {
diff --git a/rmk/src/lighting/standard/command.rs b/rmk/src/lighting/standard/command.rs
index 5ca987aba..589b1b89c 100644
--- a/rmk/src/lighting/standard/command.rs
+++ b/rmk/src/lighting/standard/command.rs
@@ -7,7 +7,7 @@ use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
 use super::*;
 use crate::RawMutex;
 use crate::lighting::compositor::{
-    ExtensionDescriptor, ExtensionParamSpec, ExtensionState, LightingSource, RenderError,
+    ExtensionDescriptor, ExtensionLayerState, ExtensionParamSpec, ExtensionState, LightingSource, RenderError,
 };
 use crate::lighting::context::LightingContext;
 use crate::lighting::source::{LayerPolicy, OutputMode, OverlayError};
@@ -88,6 +88,11 @@ pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
         expected_revision: u32,
         state: ExtensionState,
     },
+    ReadExtensionLayers,
+    SetExtensionLayersIfRevision {
+        expected_revision: u32,
+        state: ExtensionLayerState,
+    },
     /// One page of the addressed effect's parameter specs paired with the
     /// source's live values.
     ReadExtensionParams {
@@ -212,6 +217,12 @@ pub struct ExtensionPage {
     pub state: Option<ExtensionState>,
 }
 
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ExtensionLayersPage {
+    pub revision: u32,
+    pub state: Option<ExtensionLayerState>,
+}
+
 /// Number of extension parameters carried by one [`ExtensionParamsPage`].
 pub const EXTENSION_PARAM_CHUNK: usize = 8;
 
@@ -348,6 +359,7 @@ pub enum StandardReply {
     CompiledScenesPage(CompiledScenePage),
     SceneTransaction { id: u32, cell_count: u16 },
     Extension(ExtensionPage),
+    ExtensionLayers(ExtensionLayersPage),
     ExtensionParams(ExtensionParamsPage),
     RuntimeConditionalScenesPage(RuntimeConditionalScenePage),
     RuntimeConditionalSceneTransaction { id: u32, cell_count: u16 },
@@ -387,9 +399,13 @@ pub struct StandardReplicaState<const OVERLAY_CAP: usize, const SCENE_CAP: usize
     /// the authority's animated band. `None` when the authority has no
     /// selectable extension.
     pub extension: Option<ExtensionState>,
+    /// Optional second effect rendered over `extension`.
+    pub extension_layers: Option<ExtensionLayerState>,
     /// The active effect's live parameter values. `None` when the authority
     /// has no selectable extension or the active effect has no parameters.
     pub extension_params: Option<ExtensionReplicaParams>,
+    /// Overlay effect parameters when it has a distinct parameter row.
+    pub extension_overlay_params: Option<ExtensionReplicaParams>,
 }
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
diff --git a/rmk/src/lighting/standard/engine.rs b/rmk/src/lighting/standard/engine.rs
index 14025cb75..f5b66882a 100644
--- a/rmk/src/lighting/standard/engine.rs
+++ b/rmk/src/lighting/standard/engine.rs
@@ -343,7 +343,9 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             // Filled by handle_command, where the LightingSource bound is
             // available on the Extension parameter.
             extension: None,
+            extension_layers: None,
             extension_params: None,
+            extension_overlay_params: None,
         })
     }
 
@@ -980,6 +982,7 @@ where
             StandardCommand::ExportReplica(slot) => {
                 let mut replica = self.replica_state(now_ms, snapshot)?;
                 replica.extension = self.extension.extension_state();
+                replica.extension_layers = self.extension.extension_layer_state();
                 replica.extension_params = replica.extension.and_then(|state| {
                     // A source with no descriptor, an active effect the
                     // descriptor does not know, or an effect without
@@ -1002,6 +1005,29 @@ where
                         values,
                     })
                 });
+                replica.extension_overlay_params =
+                    replica
+                        .extension_layers
+                        .and_then(|layers| layers.overlay)
+                        .and_then(|effect| {
+                            let specs = extension_param_specs::<Rgb8, Context, _>(&self.extension, effect).ok()?;
+                            let len = specs.len().min(EXTENSION_PARAM_CHUNK);
+                            if len == 0 {
+                                return None;
+                            }
+                            let mut values = [0u8; EXTENSION_PARAM_CHUNK];
+                            for (value, (index, spec)) in values.iter_mut().zip(specs[..len].iter().enumerate()) {
+                                *value = self
+                                    .extension
+                                    .extension_param(effect, index as u8)
+                                    .unwrap_or(spec.default);
+                            }
+                            Some(ExtensionReplicaParams {
+                                effect,
+                                len: len as u8,
+                                values,
+                            })
+                        });
                 slot.put(replica)?;
                 (Invalidation::None, false)
             }
@@ -1017,11 +1043,21 @@ where
                         check_extension_param::<Rgb8, Context, _>(&self.extension, params.effect, index as u8, value)?;
                     }
                 }
+                if let Some(params) = replica.extension_overlay_params {
+                    for (index, value) in params.values().iter().copied().enumerate() {
+                        check_extension_param::<Rgb8, Context, _>(&self.extension, params.effect, index as u8, value)?;
+                    }
+                }
                 match (replica.extension, self.extension.extension_state()) {
                     (None, None) => {}
                     (Some(extension), Some(_)) if self.extension.apply_extension_state(extension) => {}
                     _ => return Err(StandardError::ExtensionUnsupported),
                 }
+                match (replica.extension_layers, self.extension.extension_layer_state()) {
+                    (None, None) => {}
+                    (Some(layers), Some(_)) if self.extension.apply_extension_layer_state(layers) => {}
+                    _ => return Err(StandardError::ExtensionUnsupported),
+                }
                 // Parameters follow the selection so the addressed effect is
                 // already active. Values go through the same validated path a
                 // host set uses; only the revision pin is skipped, matching
@@ -1036,6 +1072,16 @@ where
                         )?;
                     }
                 }
+                if let Some(params) = replica.extension_overlay_params {
+                    for (index, value) in params.values().iter().copied().enumerate() {
+                        apply_extension_param_checked::<Rgb8, Context, _>(
+                            &mut self.extension,
+                            params.effect,
+                            index as u8,
+                            value,
+                        )?;
+                    }
+                }
                 self.apply_replica(now_ms, replica, overlay);
                 (Invalidation::Render, false)
             }
@@ -1096,6 +1142,24 @@ where
                 }
                 (Invalidation::Render, true)
             }
+            StandardCommand::ReadExtensionLayers => {
+                return Ok(CommandResult::unchanged(StandardReply::ExtensionLayers(
+                    ExtensionLayersPage {
+                        revision: self.revision,
+                        state: self.extension.extension_layer_state(),
+                    },
+                )));
+            }
+            StandardCommand::SetExtensionLayersIfRevision {
+                expected_revision,
+                state,
+            } => {
+                self.check_revision(expected_revision)?;
+                if !self.extension.apply_extension_layer_state(state) {
+                    return Err(StandardError::ExtensionUnsupported);
+                }
+                (Invalidation::Render, true)
+            }
             StandardCommand::ReadExtensionParams { effect, offset } => {
                 let specs = extension_param_specs::<Rgb8, Context, _>(&self.extension, effect)?;
                 let start = (offset as usize).min(specs.len());
diff --git a/rmk/src/lighting/standard/tests.rs b/rmk/src/lighting/standard/tests.rs
index 174625218..f59482572 100644
--- a/rmk/src/lighting/standard/tests.rs
+++ b/rmk/src/lighting/standard/tests.rs
@@ -4,8 +4,8 @@ use rmk_types::action::LightAction;
 
 use super::*;
 use crate::lighting::compositor::{
-    Contribution, ExtensionDescriptor, ExtensionParamSpec, ExtensionState, LightingSource, LogicalFrame,
-    RenderInput as SourceRenderInput,
+    Contribution, ExtensionDescriptor, ExtensionLayerState, ExtensionParamSpec, ExtensionState, LightingSource,
+    LogicalFrame, RenderInput as SourceRenderInput,
 };
 use crate::lighting::effect::BuiltinEffect;
 use crate::lighting::service::{Invalidation, LightingEngine, RenderInput};
@@ -41,6 +41,7 @@ static REPLICA_EFFECT_PARAMS: &[&[ExtensionParamSpec]] = &[&[
 #[derive(Copy, Clone)]
 struct ReplicaExtension {
     state: ExtensionState,
+    overlay: Option<u8>,
     accept: bool,
     params: [u8; 2],
 }
@@ -70,6 +71,22 @@ impl<Context> LightingSource<Rgb8, Context> for ReplicaExtension {
         true
     }
 
+    fn extension_layer_state(&self) -> Option<ExtensionLayerState> {
+        Some(ExtensionLayerState { overlay: self.overlay })
+    }
+
+    fn apply_extension_layer_state(&mut self, state: ExtensionLayerState) -> bool {
+        if !self.accept
+            || state
+                .overlay
+                .is_some_and(|effect| effect >= REPLICA_EFFECT_NAMES.len() as u8)
+        {
+            return false;
+        }
+        self.overlay = state.overlay;
+        true
+    }
+
     fn extension_descriptor(&self) -> Option<ExtensionDescriptor> {
         Some(ExtensionDescriptor {
             effects: REPLICA_EFFECT_NAMES,
@@ -144,6 +161,7 @@ fn replica_engine(accept: bool) -> StandardLightingEngine<'static, ReplicaExtens
                 value: 10,
                 speed: 20,
             },
+            overlay: Some(1),
             accept,
             params: [3, 128],
         },
@@ -276,7 +294,9 @@ fn replica_slot_rejects_overwrite_and_empty_take() {
         context: context(0),
         sample_time_ms: 9,
         extension: None,
+        extension_layers: None,
         extension_params: None,
+        extension_overlay_params: None,
     };
     slot.put(snapshot).unwrap();
     assert_eq!(slot.put(snapshot), Err(ReplicaSlotError::Busy));
@@ -309,7 +329,9 @@ fn replica_application_is_atomic_across_common_and_extension_state() {
         context: context(0),
         sample_time_ms: 50,
         extension: Some(next_extension),
+        extension_layers: Some(ExtensionLayerState { overlay: Some(0) }),
         extension_params: None,
+        extension_overlay_params: None,
     };
 
     let mut declining = replica_engine(false);
@@ -333,6 +355,48 @@ fn replica_application_is_atomic_across_common_and_extension_state() {
     assert_eq!(accepting.state().revision, 9);
     assert_eq!(accepting.state().output_brightness, 42);
     assert_eq!(accepting.extension().state, next_extension);
+    assert_eq!(accepting.extension().overlay, Some(0));
+}
+
+#[test]
+fn extension_layer_commands_round_trip_and_validate_the_shared_effect_list() {
+    let mut engine = replica_engine(true);
+    let read = engine
+        .handle_command(0, StandardCommand::ReadExtensionLayers, &context(0))
+        .unwrap();
+    assert_eq!(
+        read.reply,
+        StandardReply::ExtensionLayers(ExtensionLayersPage {
+            revision: 0,
+            state: Some(ExtensionLayerState { overlay: Some(1) }),
+        })
+    );
+
+    engine
+        .handle_command(
+            0,
+            StandardCommand::SetExtensionLayersIfRevision {
+                expected_revision: 0,
+                state: ExtensionLayerState { overlay: Some(0) },
+            },
+            &context(0),
+        )
+        .unwrap();
+    assert_eq!(engine.extension().overlay, Some(0));
+    assert_eq!(engine.state().revision, 1);
+
+    assert_eq!(
+        engine.handle_command(
+            0,
+            StandardCommand::SetExtensionLayersIfRevision {
+                expected_revision: 1,
+                state: ExtensionLayerState { overlay: Some(2) },
+            },
+            &context(0),
+        ),
+        Err(StandardError::ExtensionUnsupported)
+    );
+    assert_eq!(engine.extension().overlay, Some(0));
 }
 
 #[test]
@@ -482,7 +546,9 @@ fn invalid_replica_common_state_does_not_mutate_extension() {
             value: 30,
             speed: 40,
         }),
+        extension_layers: Some(ExtensionLayerState { overlay: Some(1) }),
         extension_params: None,
+        extension_overlay_params: None,
     };
     let mut engine = replica_engine(true);
     let before = engine.extension().state;
diff --git a/rmk/src/storage/mod.rs b/rmk/src/storage/mod.rs
index 0fb8cf615..449ad0b21 100644
--- a/rmk/src/storage/mod.rs
+++ b/rmk/src/storage/mod.rs
@@ -193,6 +193,8 @@ pub(crate) enum FlashOperationMessage {
     #[cfg(feature = "_ble")]
     // Read the persisted active BLE profile number; storage task replies via `ACTIVE_BLE_PROFILE_RESPONSE`.
     ReadActiveBleProfile,
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingExtensionOverlay(LightingExtensionOverlayRecord),
 }
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
@@ -237,6 +239,8 @@ pub(crate) enum StorageKey {
     LightingRuntimeConditionalSceneShard(u8),
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     LightingExtensionState,
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingExtensionOverlay,
 }
 
 impl StorageKey {
@@ -330,6 +334,8 @@ pub(crate) enum StorageData {
     ),
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     LightingExtensionState(LightingExtensionRecord),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingExtensionOverlay(LightingExtensionOverlayRecord),
 }
 
 impl<'a> PostcardValue<'a> for StorageData {}
@@ -366,6 +372,25 @@ impl LightingExtensionRecord {
     }
 }
 
+/// Persisted optional second effect and the parameter row it uses. This is a
+/// separate key so the established primary-extension record remains readable
+/// across firmware upgrades.
+#[cfg(all(feature = "lighting", feature = "rynk"))]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub struct LightingExtensionOverlayRecord {
+    pub effect: Option<u8>,
+    pub param_len: u8,
+    pub params: [u8; LIGHTING_EXTENSION_PARAM_CHUNK],
+}
+
+#[cfg(all(feature = "lighting", feature = "rynk"))]
+impl LightingExtensionOverlayRecord {
+    pub fn params(&self) -> &[u8] {
+        &self.params[..(self.param_len as usize).min(LIGHTING_EXTENSION_PARAM_CHUNK)]
+    }
+}
+
 #[cfg(all(feature = "lighting", feature = "rynk"))]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -626,6 +651,14 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
         }
     }
 
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    pub async fn read_lighting_extension_overlay(&mut self) -> Option<LightingExtensionOverlayRecord> {
+        match self.fetch_data(StorageKey::LightingExtensionOverlay).await {
+            Some(StorageData::LightingExtensionOverlay(record)) => Some(record),
+            _ => None,
+        }
+    }
+
     /// Read the persisted lighting scene configuration at startup, before the
     /// storage task takes ownership. Returns the persisted layer policy, if
     /// any, and appends up to `CAP` stored cells to `cells`.
@@ -994,6 +1027,19 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
                     }
                 }
                 #[cfg(all(feature = "lighting", feature = "rynk"))]
+                FlashOperationMessage::LightingExtensionOverlay(record) => {
+                    match self.fetch_data(StorageKey::LightingExtensionOverlay).await {
+                        Some(StorageData::LightingExtensionOverlay(saved)) if saved == record => Ok(()),
+                        _ => {
+                            self.store_data(
+                                StorageKey::LightingExtensionOverlay,
+                                &StorageData::LightingExtensionOverlay(record),
+                            )
+                            .await
+                        }
+                    }
+                }
+                #[cfg(all(feature = "lighting", feature = "rynk"))]
                 FlashOperationMessage::LightingSceneTable { len, policy } => {
                     // Scene persistence rewrites the whole table on every
                     // mutation; comparing before writing keeps unchanged
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index bbf1f7815..f17ec040c 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -23,26 +23,27 @@ use rynk::rmk_types::led_indicator::LedIndicator;
 use rynk::rmk_types::modifier::ModifierCombination;
 use rynk::rmk_types::morse::Morse;
 use rynk::rmk_types::protocol::rynk::{
-    AbortLightingOverlayReplaceRequest, BeginLightingOverlayReplaceRequest, BehaviorConfig,
-    ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest, DeviceCapabilities, DeviceInfo,
-    GetComboBulkResponse, GetKeymapBulkResponse, GetMorseBulkResponse, LightingCapabilities, LightingKeysPage,
-    LightingLedsPage, LightingOutputsPage, LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage,
-    LightingRoutesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus, MacroData,
-    MatrixState, PeripheralStatus, ProtocolVersion, PutLightingOverlayChunkRequest, SetComboBulkRequest,
-    SetKeymapBulkRequest, SetLightingOverlayRequest, SetLightingStateRequest, SetMorseBulkRequest, StorageResetMode,
-    UnsetLightingOverlayRequest, BuildInfo, AbortLightingSceneReplaceRequest, BeginLightingSceneReplaceRequest,
-    CommitLightingSceneReplaceRequest, LightingScenePageRequest, LightingSceneStatus, LightingSceneTransaction,
-    LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest, SetLightingSceneCellRequest,
-    UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus, LightingCompiledScenesPage,
-    LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy, SplitCentralLatencyState,
-    LightingConditionalSceneStatus, LightingConditionalScenesPage, LightingOutputModeState, LightingExtension,
-    LightingExtensionNamesPage, LightingExtensionNamesRequest, LightingExtensionParamsPage,
-    LightingExtensionParamsRequest, SetLightingExtensionParamRequest, SetLightingExtensionStateRequest,
-    AbortLightingRuntimeConditionalSceneReplaceRequest, BeginLightingRuntimeConditionalSceneReplaceRequest,
-    CommitLightingRuntimeConditionalSceneReplaceRequest, LightingRuntimeConditionalScenePageRequest,
-    LightingRuntimeConditionalSceneStatus, LightingRuntimeConditionalSceneTransaction,
-    LightingRuntimeConditionalScenesPage, PutLightingRuntimeConditionalSceneChunkRequest,
-    SetLightingOutputModeRequest,
+    AbortLightingOverlayReplaceRequest, AbortLightingRuntimeConditionalSceneReplaceRequest,
+    AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
+    BeginLightingRuntimeConditionalSceneReplaceRequest, BeginLightingSceneReplaceRequest, BehaviorConfig, BuildInfo,
+    ClearLightingOverlayRequest, CommitLightingOverlayReplaceRequest,
+    CommitLightingRuntimeConditionalSceneReplaceRequest, CommitLightingSceneReplaceRequest, DeviceCapabilities,
+    DeviceInfo, GetComboBulkResponse, GetKeymapBulkResponse, GetMorseBulkResponse, LayerState, LightingCapabilities,
+    LightingCompiledSceneStatus, LightingCompiledScenesPage, LightingConditionalSceneStatus,
+    LightingConditionalScenesPage, LightingExtension, LightingExtensionLayers, LightingExtensionNamesPage,
+    LightingExtensionNamesRequest, LightingExtensionParamsPage, LightingExtensionParamsRequest, LightingKeysPage,
+    LightingLedsPage, LightingOutputModeState, LightingOutputsPage, LightingOverlayPage, LightingOverlayPageRequest,
+    LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage, LightingRoutesPage,
+    LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
+    LightingRuntimeConditionalSceneTransaction, LightingRuntimeConditionalScenesPage, LightingScenePageRequest,
+    LightingSceneStatus, LightingSceneTransaction, LightingScenesPage, LightingState, LightingZoneMembershipsPage,
+    LightingZonesPage, LockStatus, MacroData, MatrixState, PeripheralStatus, ProtocolVersion,
+    PutLightingOverlayChunkRequest, PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest,
+    SetComboBulkRequest, SetKeymapBulkRequest, SetLightingExtensionLayersRequest, SetLightingExtensionParamRequest,
+    SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest, SetLightingOutputModeRequest,
+    SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest, SetMorseBulkRequest,
+    SplitCentralLatencyPolicy, SplitCentralLatencyState, StorageResetMode, UnsetLightingOverlayRequest,
+    UnsetLightingSceneCellRequest,
 };
 use rynk::{Client, Driver, LayoutInfo, RynkDevice, RynkHostError, TopicEvent};
 use wasm_bindgen::prelude::*;
@@ -205,6 +206,8 @@ endpoints! {
     get_lighting_extension() -> LightingExtension,
     get_lighting_extension_names(request: LightingExtensionNamesRequest) -> LightingExtensionNamesPage,
     set_lighting_extension_state(request: SetLightingExtensionStateRequest) -> LightingState,
+    get_lighting_extension_layers() -> LightingExtensionLayers,
+    set_lighting_extension_layers(request: SetLightingExtensionLayersRequest) -> LightingState,
     get_lighting_extension_params(request: LightingExtensionParamsRequest) -> LightingExtensionParamsPage,
     set_lighting_extension_param(request: SetLightingExtensionParamRequest) -> LightingState,
     get_lighting_scene_status() -> LightingSceneStatus,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 14f43f6a3..95e596b86 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -22,28 +22,29 @@ use rmk_types::led_indicator::LedIndicator;
 use rmk_types::modifier::ModifierCombination;
 use rmk_types::morse::Morse;
 use rmk_types::protocol::rynk::{
-    AbortLightingOverlayReplaceRequest, AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
-    BeginLightingSceneReplaceRequest, BehaviorConfig, ClearLightingOverlayRequest, Cmd,
-    CommitLightingOverlayReplaceRequest, CommitLightingSceneReplaceRequest, DeviceCapabilities, DeviceInfo,
-    GetComboBulkRequest, GetComboBulkResponse, GetEncoderRequest, GetKeymapBulkRequest, GetKeymapBulkResponse,
-    GetMacroRequest, GetMorseBulkRequest, GetMorseBulkResponse, KeyPosition, LightingCapabilities, LightingKeysPage,
-    LightingLedsPage, LightingOutputsPage, LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage,
-    LightingResult, LightingRoutesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus,
-    MacroData, MatrixState, PeripheralStatus, ProtocolVersion, PutLightingOverlayChunkRequest, SetComboBulkRequest,
-    SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest,
-    SetLightingOverlayRequest, SetLightingStateRequest, SetMacroRequest, SetMorseBulkRequest, SetMorseRequest,
-    StorageResetMode, UnsetLightingOverlayRequest, command, BuildInfo, LightingScenePageRequest, LightingSceneStatus,
-    LightingSceneTransaction, LightingScenesPage, PutLightingSceneChunkRequest, SetLightingLayerPolicyRequest,
-    SetLightingSceneCellRequest, UnsetLightingSceneCellRequest, LayerState, LightingCompiledSceneStatus,
-    LightingCompiledScenesPage, LightingOverlayPage, LightingOverlayPageRequest, SplitCentralLatencyPolicy,
-    SplitCentralLatencyState, LightingConditionalSceneStatus, LightingConditionalScenesPage, LightingOutputModeState,
-    LightingExtension, LightingExtensionNameKind, LightingExtensionNamesPage, LightingExtensionNamesRequest,
-    LightingExtensionParamsPage, LightingExtensionParamsRequest, SetLightingExtensionParamRequest,
-    SetLightingExtensionStateRequest, AbortLightingRuntimeConditionalSceneReplaceRequest,
-    BeginLightingRuntimeConditionalSceneReplaceRequest, CommitLightingRuntimeConditionalSceneReplaceRequest,
-    LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
-    LightingRuntimeConditionalSceneTransaction, LightingRuntimeConditionalScenesPage,
-    PutLightingRuntimeConditionalSceneChunkRequest, SetLightingOutputModeRequest,
+    AbortLightingOverlayReplaceRequest, AbortLightingRuntimeConditionalSceneReplaceRequest,
+    AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
+    BeginLightingRuntimeConditionalSceneReplaceRequest, BeginLightingSceneReplaceRequest, BehaviorConfig, BuildInfo,
+    ClearLightingOverlayRequest, Cmd, CommitLightingOverlayReplaceRequest,
+    CommitLightingRuntimeConditionalSceneReplaceRequest, CommitLightingSceneReplaceRequest, DeviceCapabilities,
+    DeviceInfo, GetComboBulkRequest, GetComboBulkResponse, GetEncoderRequest, GetKeymapBulkRequest,
+    GetKeymapBulkResponse, GetMacroRequest, GetMorseBulkRequest, GetMorseBulkResponse, KeyPosition, LayerState,
+    LightingCapabilities, LightingCompiledSceneStatus, LightingCompiledScenesPage, LightingConditionalSceneStatus,
+    LightingConditionalScenesPage, LightingExtension, LightingExtensionLayers, LightingExtensionNameKind,
+    LightingExtensionNamesPage, LightingExtensionNamesRequest, LightingExtensionParamsPage,
+    LightingExtensionParamsRequest, LightingKeysPage, LightingLedsPage, LightingOutputModeState, LightingOutputsPage,
+    LightingOverlayPage, LightingOverlayPageRequest, LightingOverlayTransaction, LightingPageRequest,
+    LightingPhysicalKeysPage, LightingResult, LightingRoutesPage, LightingRuntimeConditionalScenePageRequest,
+    LightingRuntimeConditionalSceneStatus, LightingRuntimeConditionalSceneTransaction,
+    LightingRuntimeConditionalScenesPage, LightingScenePageRequest, LightingSceneStatus, LightingSceneTransaction,
+    LightingScenesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus, MacroData,
+    MatrixState, PeripheralStatus, ProtocolVersion, PutLightingOverlayChunkRequest,
+    PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, SetComboBulkRequest, SetComboRequest,
+    SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest, SetLightingExtensionLayersRequest,
+    SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
+    SetLightingOutputModeRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
+    SetMacroRequest, SetMorseBulkRequest, SetMorseRequest, SplitCentralLatencyPolicy, SplitCentralLatencyState,
+    StorageResetMode, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest, command,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -642,6 +643,21 @@ impl Client {
         Self::flatten_lighting(self.request::<command::SetLightingExtensionState>(&request).await?)
     }
 
+    /// Read the optional second effect layered over the primary extension.
+    pub async fn get_lighting_extension_layers(&self) -> Result<LightingExtensionLayers, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingExtensionLayers)?;
+        Self::flatten_lighting(self.request::<command::GetLightingExtensionLayers>(&()).await?)
+    }
+
+    /// Replace the optional second effect when the state revision matches.
+    pub async fn set_lighting_extension_layers(
+        &self,
+        request: SetLightingExtensionLayersRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::SetLightingExtensionLayers)?;
+        Self::flatten_lighting(self.request::<command::SetLightingExtensionLayers>(&request).await?)
+    }
+
     /// Read one page of an extension effect's tunable parameters. Unlike name
     /// pages these carry live values, so they are pinned to
     /// `LightingState.revision`.
@@ -1225,12 +1241,10 @@ impl Client {
         cells: &[rmk_types::protocol::rynk::LightingConditionalSceneCell],
     ) -> Result<LightingState, RynkHostError> {
         let transaction = self
-            .begin_lighting_runtime_conditional_scene_replace(
-                BeginLightingRuntimeConditionalSceneReplaceRequest {
-                    expected_revision,
-                    cell_count: cells.len() as u16,
-                },
-            )
+            .begin_lighting_runtime_conditional_scene_replace(BeginLightingRuntimeConditionalSceneReplaceRequest {
+                expected_revision,
+                cell_count: cells.len() as u16,
+            })
             .await?;
         let mut offset: u16 = 0;
         for chunk in cells.chunks(rmk_types::protocol::rynk::LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE) {
@@ -1254,11 +1268,9 @@ impl Client {
             }
             offset += chunk.len() as u16;
         }
-        self.commit_lighting_runtime_conditional_scene_replace(
-            CommitLightingRuntimeConditionalSceneReplaceRequest {
-                transaction_id: transaction.id,
-            },
-        )
+        self.commit_lighting_runtime_conditional_scene_replace(CommitLightingRuntimeConditionalSceneReplaceRequest {
+            transaction_id: transaction.id,
+        })
         .await
     }
 

From 13bb512502bba4042693a93bd929445d4af4aa85 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 16:25:59 -0700
Subject: [PATCH 59/78] perf(lighting): group scene cells by layer

Scene lookup scanned the whole table for every cell it resolved, so
composition cost grew with the total number of cells rather than with
the cells the active layers actually contribute. Keep cells grouped by
layer with a `layer_offsets` index instead, so a layer's run is a slice
and `included_len` is arithmetic over the active layers rather than a
filtered count. Insertion and removal shift within the array to hold
the grouping; layers past `LayerState::CAPACITY` fall back to a
partition point.

Also stop publishing a LightingChangedEvent when a board signals
`snapshot_changed`. That signal means "re-render from fresh context",
which every board raises on ordinary battery and sensor movement; the
event is a host readback invalidation and does not belong on that path.

Tests: 649 pass on the split,rynk,storage,async_matrix,_ble,lighting
row under nextest, including a new differential test that checks the
grouped table resolves identically to a naive scan.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 rmk/src/lighting/processor.rs       |   4 +-
 rmk/src/lighting/standard/scenes.rs |  98 +++++++---
 rmk/src/lighting/standard/tests.rs  | 265 +++++++++++++++++++++++++++-
 rynk/src/driver.rs                  |   3 +-
 4 files changed, 342 insertions(+), 28 deletions(-)

diff --git a/rmk/src/lighting/processor.rs b/rmk/src/lighting/processor.rs
index 00f6d80ed..b23a5723e 100644
--- a/rmk/src/lighting/processor.rs
+++ b/rmk/src/lighting/processor.rs
@@ -82,7 +82,7 @@ impl<Command, Reply, Error, const CAPACITY: usize> LightingMailbox<Command, Repl
     ///
     /// Boards use this after changing context outside the standard RMK
     /// layer/indicator snapshots (for example battery or sensor state). The
-    /// processor takes a fresh snapshot, rerenders, and notifies replicas.
+    /// processor takes a fresh snapshot and rerenders it.
     pub fn snapshot_changed(&self) {
         self.snapshot_changed.signal(());
     }
@@ -315,7 +315,6 @@ where
                         }
                         Either4::Fourth(Either3::Third(())) => {
                             self.service.request_render();
-                            publish_event(LightingChangedEvent::new());
                         }
                     }
                 }
@@ -342,7 +341,6 @@ where
                         }
                         Either3::Third(Either3::Third(())) => {
                             self.service.request_render();
-                            publish_event(LightingChangedEvent::new());
                         }
                     }
                 }
diff --git a/rmk/src/lighting/standard/scenes.rs b/rmk/src/lighting/standard/scenes.rs
index 7fd574d2a..b718caf34 100644
--- a/rmk/src/lighting/standard/scenes.rs
+++ b/rmk/src/lighting/standard/scenes.rs
@@ -2,7 +2,7 @@
 use super::*;
 use crate::lighting::Rgb8;
 use crate::lighting::compositor::{Contribution, LightingSource, RenderInput as SourceRenderInput};
-use crate::lighting::context::{LightingContext, LightingContextProvider};
+use crate::lighting::context::{LayerState, LightingContext, LightingContextProvider};
 use crate::lighting::effect::{BuiltinEffect, LightingEffect};
 use crate::lighting::source::LayerPolicy;
 use crate::lighting::topology::LedSlot;
@@ -165,13 +165,14 @@ const EMPTY_INTERNED_CELL: InternedSceneCell = InternedSceneCell {
 
 /// Fixed-capacity runtime scene table with layer-aware composition.
 ///
-/// Cells are unique per `(layer, slot)` and stored in insertion order; order
-/// is irrelevant to rendering because layer precedence comes from the policy
-/// and same-layer cells can never target the same slot.
+/// Cells are unique per `(layer, slot)` and grouped by layer. Order within a
+/// layer is irrelevant because same-layer cells can never target the same
+/// slot. `layer_offsets[layer]..layer_offsets[layer + 1]` is that layer's run.
 #[derive(Copy, Clone, Debug)]
 pub struct SceneTable<const CAP: usize> {
     cells: [InternedSceneCell; CAP],
     len: usize,
+    layer_offsets: [u16; LayerState::CAPACITY as usize + 1],
     pub(super) pool: StylePool,
     policy: LayerPolicy,
 }
@@ -181,6 +182,7 @@ impl<const CAP: usize> SceneTable<CAP> {
         Self {
             cells: [EMPTY_INTERNED_CELL; CAP],
             len: 0,
+            layer_offsets: [0; LayerState::CAPACITY as usize + 1],
             pool: StylePool::new(),
             policy: LayerPolicy::ActiveStack,
         }
@@ -231,8 +233,20 @@ impl<const CAP: usize> SceneTable<CAP> {
                 }
             }
             None => {
-                self.cells[self.len] = interned;
+                let layer = cell.layer as usize;
+                let insert_at = if layer < LayerState::CAPACITY as usize {
+                    self.layer_offsets[layer + 1] as usize
+                } else {
+                    self.cells[..self.len].partition_point(|held| held.layer <= cell.layer)
+                };
+                self.cells.copy_within(insert_at..self.len, insert_at + 1);
+                self.cells[insert_at] = interned;
                 self.len += 1;
+                if layer < LayerState::CAPACITY as usize {
+                    for offset in &mut self.layer_offsets[layer + 1..] {
+                        *offset += 1;
+                    }
+                }
             }
         }
         Ok(())
@@ -263,7 +277,12 @@ impl<const CAP: usize> SceneTable<CAP> {
         {
             let removed = self.cells[index].style;
             self.len -= 1;
-            self.cells[index] = self.cells[self.len];
+            self.cells.copy_within(index + 1..self.len + 1, index);
+            if (layer as usize) < LayerState::CAPACITY as usize {
+                for offset in &mut self.layer_offsets[layer as usize + 1..] {
+                    *offset -= 1;
+                }
+            }
             self.release(removed);
             true
         } else {
@@ -273,6 +292,7 @@ impl<const CAP: usize> SceneTable<CAP> {
 
     pub fn clear(&mut self) {
         self.len = 0;
+        self.layer_offsets.fill(0);
         self.pool.clear();
     }
 
@@ -285,14 +305,32 @@ impl<const CAP: usize> SceneTable<CAP> {
         chunk
     }
 
+    fn layer_bounds(&self, layer: u8) -> (usize, usize) {
+        let layer = layer as usize;
+        if layer < LayerState::CAPACITY as usize {
+            (
+                self.layer_offsets[layer] as usize,
+                self.layer_offsets[layer + 1] as usize,
+            )
+        } else {
+            let start = self.cells[..self.len].partition_point(|cell| cell.layer < layer as u8);
+            let end = self.cells[..self.len].partition_point(|cell| cell.layer <= layer as u8);
+            (start, end)
+        }
+    }
+
     fn cell_for_layer(&self, layer: u8, wanted: &mut usize) -> Option<SceneTableCell> {
-        for cell in self.iter().filter(|cell| cell.layer == layer) {
-            if *wanted == 0 {
-                return Some(cell);
-            }
-            *wanted -= 1;
+        let (start, end) = self.layer_bounds(layer);
+        if *wanted >= end - start {
+            *wanted -= end - start;
+            return None;
         }
-        None
+        let held = self.cells[start + *wanted];
+        self.pool.get(held.style).map(|effect| SceneTableCell {
+            layer: held.layer,
+            slot: held.slot,
+            effect,
+        })
     }
 
     fn cell_at(&self, context: &LightingContext, mut wanted: usize) -> SceneTableCell {
@@ -304,7 +342,7 @@ impl<const CAP: usize> SceneTable<CAP> {
                 if let Some(cell) = self.cell_for_layer(default, &mut wanted) {
                     return cell;
                 }
-                for layer in 0..crate::lighting::context::LayerState::CAPACITY {
+                for layer in 0..LayerState::CAPACITY {
                     if layer != default
                         && layer != effective
                         && context.layers.is_active(layer)
@@ -325,17 +363,31 @@ impl<const CAP: usize> SceneTable<CAP> {
 
     fn included_len(&self, context: &LightingContext) -> usize {
         let effective = context.layers.effective;
-        self.cells[..self.len]
-            .iter()
-            .filter(|cell| match self.policy {
-                LayerPolicy::EffectiveOnly => cell.layer == effective,
-                LayerPolicy::ActiveStack => {
-                    cell.layer == context.layers.default
-                        || cell.layer == effective
-                        || context.layers.is_active(cell.layer)
+        match self.policy {
+            LayerPolicy::EffectiveOnly => {
+                let (start, end) = self.layer_bounds(effective);
+                end - start
+            }
+            LayerPolicy::ActiveStack => {
+                let default = context.layers.default;
+                let mut included = 0;
+                for layer in 0..LayerState::CAPACITY {
+                    if layer == default || layer == effective || context.layers.is_active(layer) {
+                        let layer = layer as usize;
+                        included += self.layer_offsets[layer + 1] as usize - self.layer_offsets[layer] as usize;
+                    }
                 }
-            })
-            .count()
+                if default >= LayerState::CAPACITY {
+                    let (start, end) = self.layer_bounds(default);
+                    included += end - start;
+                }
+                if effective >= LayerState::CAPACITY && effective != default {
+                    let (start, end) = self.layer_bounds(effective);
+                    included += end - start;
+                }
+                included
+            }
+        }
     }
 }
 
diff --git a/rmk/src/lighting/standard/tests.rs b/rmk/src/lighting/standard/tests.rs
index f59482572..071d47c1b 100644
--- a/rmk/src/lighting/standard/tests.rs
+++ b/rmk/src/lighting/standard/tests.rs
@@ -7,7 +7,7 @@ use crate::lighting::compositor::{
     Contribution, ExtensionDescriptor, ExtensionLayerState, ExtensionParamSpec, ExtensionState, LightingSource,
     LogicalFrame, RenderInput as SourceRenderInput,
 };
-use crate::lighting::effect::BuiltinEffect;
+use crate::lighting::effect::{BuiltinEffect, LightingEffect};
 use crate::lighting::service::{Invalidation, LightingEngine, RenderInput};
 use crate::lighting::source::{
     BatteryStatusProvider, ConditionSet, LayerScenes, LightingControls, OutputMode, OverlayError, SparseScene,
@@ -1165,6 +1165,159 @@ fn scene_pages_echo_revision_and_clamp() {
     assert!(tail.cells.as_slice().is_empty());
 }
 
+fn naive_scene_set(cells: &mut std::vec::Vec<SceneTableCell>, cell: SceneTableCell) {
+    if let Some(held) = cells
+        .iter_mut()
+        .find(|held| held.layer == cell.layer && held.slot == cell.slot)
+    {
+        *held = cell;
+    } else {
+        cells.push(cell);
+    }
+}
+
+fn naive_scene_render(
+    cells: &[SceneTableCell],
+    policy: LayerPolicy,
+    context: &LightingContext,
+    now_ms: u64,
+) -> std::vec::Vec<(LedSlot, Rgb8)> {
+    let mut rendered = std::vec::Vec::new();
+    let mut append_layer = |layer| {
+        rendered.extend(
+            cells
+                .iter()
+                .filter(|cell| cell.layer == layer)
+                .map(|cell| (cell.slot, cell.effect.sample(now_ms).color)),
+        );
+    };
+    let effective = context.layers.effective;
+    match policy {
+        LayerPolicy::EffectiveOnly => append_layer(effective),
+        LayerPolicy::ActiveStack => {
+            let default = context.layers.default;
+            append_layer(default);
+            for layer in 0..LayerState::CAPACITY {
+                if layer != default && layer != effective && context.layers.is_active(layer) {
+                    append_layer(layer);
+                }
+            }
+            if effective != default {
+                append_layer(effective);
+            }
+        }
+    }
+    rendered
+}
+
+fn scene_table_render<const CAP: usize>(
+    table: &mut SceneTable<CAP>,
+    context: &LightingContext,
+    now_ms: u64,
+) -> std::vec::Vec<(LedSlot, Rgb8)> {
+    let input = SourceRenderInput { now_ms, context };
+    let len = <SceneTable<CAP> as LightingSource<Rgb8, LightingContext>>::len(table, &input);
+    let mut rendered = std::vec::Vec::with_capacity(len);
+    for index in 0..len {
+        let slot = <SceneTable<CAP> as LightingSource<Rgb8, LightingContext>>::slot(table, index, &input);
+        let Contribution::Opaque(sample) =
+            <SceneTable<CAP> as LightingSource<Rgb8, LightingContext>>::contribution(table, index, &input)
+        else {
+            panic!("scene cells are always opaque");
+        };
+        rendered.push((slot, sample.color));
+    }
+    rendered
+}
+
+fn pseudo_random(seed: &mut u64) -> u64 {
+    *seed ^= *seed << 13;
+    *seed ^= *seed >> 7;
+    *seed ^= *seed << 17;
+    *seed
+}
+
+fn varied_effect(value: u8) -> BuiltinEffect {
+    let color = Rgb8::new(value.wrapping_mul(29), value.wrapping_mul(47), value.wrapping_mul(71));
+    match value % 3 {
+        0 => BuiltinEffect::solid(color),
+        1 => BuiltinEffect::Blink {
+            color,
+            period_ms: 80 + (value as u32 % 5) * 20,
+            phase_ms: value as u32 * 7,
+            duty: 35,
+        },
+        _ => BuiltinEffect::Breathe {
+            color,
+            period_ms: 120 + (value as u32 % 5) * 20,
+            phase_ms: value as u32 * 11,
+            step_ms: 10,
+        },
+    }
+}
+
+#[test]
+fn grouped_scene_lookup_matches_naive_scan_resolution() {
+    const CAP: usize = 256;
+    const LAYERS: [u8; 12] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 32, 47, 63];
+    let mut seed = 0x4d59_5df4_d0f3_3173;
+
+    for table_index in 0..12 {
+        let mut table = SceneTable::<CAP>::new();
+        let mut naive = std::vec::Vec::new();
+        let dense_layer = LAYERS[table_index % LAYERS.len()];
+        for slot in 0..80 {
+            let cell = SceneTableCell {
+                layer: dense_layer,
+                slot: LedSlot(slot),
+                effect: varied_effect((slot as u8 + table_index as u8) % 18),
+            };
+            table.set(cell).unwrap();
+            naive_scene_set(&mut naive, cell);
+        }
+        for _ in 0..140 {
+            let layer = LAYERS[pseudo_random(&mut seed) as usize % LAYERS.len()];
+            let slot = (pseudo_random(&mut seed) % 112) as u16;
+            let effect = varied_effect((pseudo_random(&mut seed) % 18) as u8);
+            let cell = SceneTableCell {
+                layer,
+                slot: LedSlot(slot),
+                effect,
+            };
+            table.set(cell).unwrap();
+            naive_scene_set(&mut naive, cell);
+        }
+
+        for policy in [LayerPolicy::EffectiveOnly, LayerPolicy::ActiveStack] {
+            table.set_policy(policy);
+            for context_index in 0..10 {
+                let default = LAYERS[(table_index + context_index * 3) % LAYERS.len()];
+                let effective = if context_index % 3 == 0 {
+                    default
+                } else {
+                    LAYERS[(table_index * 5 + context_index * 7) % LAYERS.len()]
+                };
+                let mut active = (1_u64 << default) | (1_u64 << effective);
+                for layer in LAYERS {
+                    if pseudo_random(&mut seed) & 1 != 0 {
+                        active |= 1_u64 << layer;
+                    }
+                }
+                let context = LightingContext {
+                    layers: LayerState::new(effective, default, active),
+                    ..LightingContext::default()
+                };
+                let now_ms = pseudo_random(&mut seed) % 10_000;
+                assert_eq!(
+                    scene_table_render(&mut table, &context, now_ms),
+                    naive_scene_render(&naive, policy, &context, now_ms),
+                    "table {table_index}, context {context_index}, policy {policy:?}"
+                );
+            }
+        }
+    }
+}
+
 #[test]
 fn runtime_scene_overrides_static_layer_and_yields_to_overlay() {
     let mut engine = scene_engine();
@@ -1696,6 +1849,116 @@ fn repainting_a_cell_does_not_strand_styles() {
     assert_eq!(table.len(), 1);
 }
 
+#[test]
+fn scene_mutations_preserve_grouped_runs_and_release_overwritten_styles() {
+    let mut table = SceneTable::<8>::new();
+    for cell in [
+        scene_cell(5, 0, RED),
+        scene_cell(1, 0, RED),
+        scene_cell(5, 1, GREEN),
+        scene_cell(1, 1, GREEN),
+        scene_cell(0, 0, BLUE),
+        scene_cell(1, 2, RED),
+    ] {
+        table.set(cell).unwrap();
+    }
+    assert_eq!(
+        table
+            .iter()
+            .map(|cell| (cell.layer, cell.slot))
+            .collect::<std::vec::Vec<_>>(),
+        [
+            (0, LedSlot(0)),
+            (1, LedSlot(0)),
+            (1, LedSlot(1)),
+            (1, LedSlot(2)),
+            (5, LedSlot(0)),
+            (5, LedSlot(1)),
+        ]
+    );
+
+    table.set(scene_cell(1, 1, BLUE)).unwrap();
+    assert_eq!(table.len(), 6, "setting an existing address updates in place");
+    assert_eq!(table.iter().nth(2), Some(scene_cell(1, 1, BLUE)));
+    assert!(table.unset(1, LedSlot(1)), "remove the middle of layer 1's run");
+    assert_eq!(
+        table
+            .iter()
+            .map(|cell| (cell.layer, cell.slot))
+            .collect::<std::vec::Vec<_>>(),
+        [
+            (0, LedSlot(0)),
+            (1, LedSlot(0)),
+            (1, LedSlot(2)),
+            (5, LedSlot(0)),
+            (5, LedSlot(1)),
+        ]
+    );
+
+    let mut shared = SceneTable::<2>::new();
+    shared.set(scene_cell(0, 0, RED)).unwrap();
+    shared.set(scene_cell(0, 1, RED)).unwrap();
+    shared.set(scene_cell(0, 0, GREEN)).unwrap();
+    assert_eq!(shared.pool.len(), 2, "the other cell retains the overwritten style");
+    shared.set(scene_cell(0, 1, GREEN)).unwrap();
+    assert_eq!(shared.pool.len(), 1, "the last overwrite releases the old style");
+}
+
+#[test]
+fn rejected_scene_mutations_leave_capacity_and_pool_state_unchanged() {
+    let mut at_capacity = SceneTable::<2>::new();
+    at_capacity.set(scene_cell(3, 0, RED)).unwrap();
+    at_capacity.set(scene_cell(1, 0, GREEN)).unwrap();
+    let before_capacity = at_capacity;
+    assert_eq!(
+        at_capacity.set(scene_cell(2, 0, BLUE)),
+        Err(StandardError::SceneFull { capacity: 2 })
+    );
+    assert_eq!(at_capacity, before_capacity);
+    assert_eq!(at_capacity.pool, before_capacity.pool);
+
+    let mut at_pool_capacity = SceneTable::<{ SCENE_STYLE_CAP + 1 }>::new();
+    for shade in 0..SCENE_STYLE_CAP {
+        at_pool_capacity
+            .set(scene_cell(
+                (shade % LayerState::CAPACITY as usize) as u8,
+                shade as u16,
+                Rgb8::new(shade as u8, 0, 0),
+            ))
+            .unwrap();
+    }
+    let before_pool = at_pool_capacity;
+    assert_eq!(
+        at_pool_capacity.set(scene_cell(0, SCENE_STYLE_CAP as u16, Rgb8::new(0, 1, 0))),
+        Err(StandardError::SceneFull {
+            capacity: SCENE_STYLE_CAP,
+        })
+    );
+    assert_eq!(at_pool_capacity, before_pool);
+    assert_eq!(at_pool_capacity.pool, before_pool.pool);
+}
+
+#[test]
+fn scene_pages_cover_the_layer_grouped_table_without_gaps() {
+    let mut table = SceneTable::<20>::new();
+    for index in 0..19 {
+        table
+            .set(scene_cell(
+                [5, 1, 32, 0][index % 4],
+                index as u16,
+                Rgb8::new(index as u8, 0, 0),
+            ))
+            .unwrap();
+    }
+    let expected = table.iter().collect::<std::vec::Vec<_>>();
+    let mut paged = std::vec::Vec::new();
+    for offset in (0..table.len()).step_by(SCENE_CHUNK_SIZE) {
+        paged.extend_from_slice(table.page(offset as u16).as_slice());
+    }
+    assert_eq!(paged, expected);
+    assert!(table.page(table.len() as u16).as_slice().is_empty());
+}
+
 #[test]
 fn conditional_rules_share_styles_without_losing_order_or_conditions() {
     let mut table = RuntimeConditionalSceneTable::<4>::new();
diff --git a/rynk/src/driver.rs b/rynk/src/driver.rs
index da9a691b5..eccd06d0d 100644
--- a/rynk/src/driver.rs
+++ b/rynk/src/driver.rs
@@ -36,7 +36,8 @@ use embassy_sync::signal::Signal;
 use embedded_io_async::{Error as _, ErrorKind, Read, Write};
 use rmk_types::protocol::rynk::command::Endpoint;
 use rmk_types::protocol::rynk::{
-    Cmd, Deframer, DeviceCapabilities, LightingError, RYNK_HEADER_SIZE, RynkError, RynkHeader, TopicEvent, encode_frame, max_wire_size,
+    Cmd, Deframer, DeviceCapabilities, LightingError, RYNK_HEADER_SIZE, RynkError, RynkHeader, TopicEvent,
+    encode_frame, max_wire_size,
 };
 use serde::Serialize;
 use thiserror::Error;

From ed95206c8d0cee13b95ce149c80935b830f2565b Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 17:43:22 -0700
Subject: [PATCH 60/78] feat(lighting): match conditional scenes on connection
 state

---
 rmk/src/host/rynk/handlers/lighting.rs   |   1 +
 rmk/src/host/rynk/lighting.rs            |   1 +
 rmk/src/lighting/context.rs              |   6 +-
 rmk/src/lighting/mod.rs                  |   8 +-
 rmk/src/lighting/rmk_state.rs            |   4 +-
 rmk/src/lighting/source.rs               | 125 +++++++++++++++++++++++
 rmk/src/lighting/standard/conditional.rs |   2 +
 rmk/src/lighting/standard/tests.rs       |   9 ++
 8 files changed, 150 insertions(+), 6 deletions(-)

diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 1309c8c31..bc9151a4c 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -1432,6 +1432,7 @@ mod tests {
                 max_level: Some(40),
                 charge: ChargeCondition::Discharging,
             }),
+            connection: None,
             output_mode: None,
         },
         slot: crate::lighting::LedSlot(0),
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 5e0d2539c..85b60c9c7 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -1593,6 +1593,7 @@ fn condition_set_from_wire(
                 LightingChargeCondition::Unknown => ChargeCondition::Unknown,
             },
         }),
+        connection: None,
         output_mode: conditions.output_mode.map(|mode| match mode {
             rmk_types::protocol::rynk::LightingOutputMode::AlwaysOn => crate::lighting::OutputMode::AlwaysOn,
             rmk_types::protocol::rynk::LightingOutputMode::AlwaysOff => crate::lighting::OutputMode::AlwaysOff,
diff --git a/rmk/src/lighting/context.rs b/rmk/src/lighting/context.rs
index 1a6e47d71..0994bf7d2 100644
--- a/rmk/src/lighting/context.rs
+++ b/rmk/src/lighting/context.rs
@@ -1,3 +1,5 @@
+use rmk_types::connection::ConnectionStatus;
+
 /// Bounded snapshot of RMK's layer state.
 ///
 /// The complete active set is retained because the effective layer alone is
@@ -58,11 +60,13 @@ pub struct LightingContext {
     pub indicators: IndicatorState,
     /// USB/VBUS power is present. This remains true while USB is suspended.
     pub powered: bool,
+    /// Authoritative transport, BLE profile, and BLE lifecycle snapshot.
+    pub connection: ConnectionStatus,
 }
 
 /// Access to RMK's standard lighting state from a board-extended snapshot.
 ///
-/// A board may add battery, connection, or sensor fields to its snapshot and
+/// A board may add battery or sensor fields to its snapshot and
 /// still reuse built-in layer and indicator sources by implementing this
 /// trait. The compositor itself remains generic over the complete context.
 pub trait LightingContextProvider {
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index aa4b706cc..5348a44c2 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -37,10 +37,10 @@ pub use service::{
     OutputState, PowerState, RenderOutcome, ServiceAction, SnapshotProvider,
 };
 pub use source::{
-    BatteryCondition, BatteryStatusProvider, ChargeCondition, ConditionSet, ConditionalSceneCell, ConditionalScenes,
-    DenseSource, Indicator, IndicatorScene, IndicatorScenes, LayerCondition, LayerPolicy, LayerScene, LayerScenes,
-    LightingControls, OutputMode, OutputModeIndicator, OverlayError, OverlayUpdate, PoweredOnlyScope, SceneCell,
-    SparseScene, TtlOverlay,
+    ActiveTransport, BatteryCondition, BatteryStatusProvider, ChargeCondition, ConditionSet, ConditionalSceneCell,
+    ConditionalScenes, ConnectionCondition, DenseSource, Indicator, IndicatorScene, IndicatorScenes, LayerCondition,
+    LayerPolicy, LayerScene, LayerScenes, LightingControls, OutputMode, OutputModeIndicator, OverlayError,
+    OverlayUpdate, PoweredOnlyScope, SceneCell, SparseScene, TtlOverlay,
 };
 pub use standard::{
     BackgroundMode, BackgroundPatch, BackgroundState, CompiledScenePage, EmptySource, OVERLAY_CHUNK_SIZE, OverlayBatch,
diff --git a/rmk/src/lighting/rmk_state.rs b/rmk/src/lighting/rmk_state.rs
index 42f931e6b..b027d4e9c 100644
--- a/rmk/src/lighting/rmk_state.rs
+++ b/rmk/src/lighting/rmk_state.rs
@@ -48,10 +48,12 @@ impl SnapshotProvider for KeymapLightingState<'_, '_> {
                 active |= 1_u64 << layer;
             }
         }
+        let connection = crate::state::current_connection_status();
         LightingContext {
             layers: LayerState::new(effective, default, active),
             indicators: indicator_state(),
-            powered: crate::state::current_usb_state().is_powered(),
+            powered: connection.usb.is_powered(),
+            connection,
         }
     }
 }
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index 4c9dcde34..11b31d7c2 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -3,6 +3,8 @@ use super::context::{LightingContext, LightingContextProvider};
 use super::effect::{BuiltinEffect, EffectSample, LightingEffect};
 use super::topology::LedSlot;
 use crate::types::battery::{BatteryStatus, ChargeState};
+use rmk_types::ble::BleState;
+use rmk_types::connection::ConnectionType;
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct SceneCell<E> {
@@ -177,10 +179,25 @@ pub struct BatteryCondition {
     pub charge: ChargeCondition,
 }
 
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum ActiveTransport {
+    Usb,
+    Ble,
+    NoneActive,
+}
+
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct ConnectionCondition {
+    pub transport: Option<ActiveTransport>,
+    pub profile: Option<u8>,
+    pub ble_state: Option<BleState>,
+}
+
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
 pub struct ConditionSet {
     pub layer: Option<LayerCondition>,
     pub battery: Option<BatteryCondition>,
+    pub connection: Option<ConnectionCondition>,
     /// Satisfied when the live output-mode policy equals this. Sources that
     /// cannot observe the policy treat it as unsatisfiable rather than true,
     /// so a rule gated on it never fires where it cannot be evaluated.
@@ -271,6 +288,26 @@ impl ConditionSet {
         {
             return false;
         }
+        if let Some(condition) = self.connection {
+            let connection = context.lighting_context().connection;
+            if let Some(wanted) = condition.transport {
+                let active = match connection.decide_active() {
+                    Some(ConnectionType::Usb) => ActiveTransport::Usb,
+                    Some(ConnectionType::Ble) => ActiveTransport::Ble,
+                    None => ActiveTransport::NoneActive,
+                };
+                if active != wanted {
+                    return false;
+                }
+            }
+            if condition
+                .profile
+                .is_some_and(|profile| connection.ble.profile != profile)
+                || condition.ble_state.is_some_and(|state| connection.ble.state != state)
+            {
+                return false;
+            }
+        }
         let Some(condition) = self.battery else {
             return true;
         };
@@ -638,11 +675,94 @@ mod tests {
     use super::super::{BuiltinEffect, Compositor, LayerState, LogicalFrame, Rgb8};
     use super::*;
     use crate::types::battery::{BatteryStatus, ChargeState};
+    use rmk_types::ble::{BleState, BleStatus};
+    use rmk_types::connection::{ConnectionStatus, ConnectionType, UsbState};
 
     const RED: Rgb8 = Rgb8::new(10, 0, 0);
     const GREEN: Rgb8 = Rgb8::new(0, 10, 0);
     const BLUE: Rgb8 = Rgb8::new(0, 0, 10);
 
+    struct NoBatteries;
+
+    impl BatteryStatusProvider for NoBatteries {
+        fn battery_status(&self, _: u8) -> BatteryStatus {
+            BatteryStatus::Unavailable
+        }
+    }
+
+    #[test]
+    fn connection_conditions_conjoin_transport_profile_and_ble_state() {
+        let mut context = LightingContext {
+            connection: ConnectionStatus {
+                usb: UsbState::Configured,
+                ble: BleStatus {
+                    profile: 3,
+                    state: BleState::Connected,
+                },
+                preferred: ConnectionType::Ble,
+            },
+            ..LightingContext::default()
+        };
+        let conditions = ConditionSet {
+            connection: Some(ConnectionCondition {
+                transport: Some(ActiveTransport::Ble),
+                profile: Some(3),
+                ble_state: Some(BleState::Connected),
+            }),
+            ..ConditionSet::default()
+        };
+
+        assert!(conditions.matches(&context, &NoBatteries, None));
+        context.connection.preferred = ConnectionType::Usb;
+        assert!(!conditions.matches(&context, &NoBatteries, None));
+
+        let usb = ConditionSet {
+            connection: Some(ConnectionCondition {
+                transport: Some(ActiveTransport::Usb),
+                profile: Some(3),
+                ble_state: Some(BleState::Connected),
+            }),
+            ..ConditionSet::default()
+        };
+        assert!(usb.matches(&context, &NoBatteries, None));
+
+        context.connection.ble.profile = 4;
+        assert!(!usb.matches(&context, &NoBatteries, None));
+        context.connection.ble.profile = 3;
+        context.connection.ble.state = BleState::Advertising;
+        assert!(!usb.matches(&context, &NoBatteries, None));
+    }
+
+    #[test]
+    fn connection_condition_matches_none_active_and_empty_condition() {
+        let context = LightingContext {
+            connection: ConnectionStatus {
+                usb: UsbState::Enabled,
+                ble: BleStatus {
+                    profile: 2,
+                    state: BleState::Advertising,
+                },
+                preferred: ConnectionType::Usb,
+            },
+            ..LightingContext::default()
+        };
+        let none_active = ConditionSet {
+            connection: Some(ConnectionCondition {
+                transport: Some(ActiveTransport::NoneActive),
+                profile: Some(2),
+                ble_state: Some(BleState::Advertising),
+            }),
+            ..ConditionSet::default()
+        };
+        let empty = ConditionSet {
+            connection: Some(ConnectionCondition::default()),
+            ..ConditionSet::default()
+        };
+
+        assert!(none_active.matches(&context, &NoBatteries, None));
+        assert!(empty.matches(&context, &NoBatteries, None));
+    }
+
     #[test]
     fn layer_source_has_sparse_active_stack_fallthrough() {
         let base = [SceneCell {
@@ -673,6 +793,7 @@ mod tests {
             layers: LayerState::new(3, 0, 0b1101),
             indicators: Default::default(),
             powered: false,
+            connection: Default::default(),
         };
         let compositor = Compositor::<Rgb8, 2>::new(Rgb8::BLACK);
         let mut frame = LogicalFrame::new(Rgb8::BLACK);
@@ -763,6 +884,7 @@ mod tests {
                         max_level: None,
                         charge: ChargeCondition::Any,
                     }),
+                    connection: None,
                     output_mode: None,
                 },
                 slot: LedSlot(0),
@@ -777,6 +899,7 @@ mod tests {
                         max_level: None,
                         charge: ChargeCondition::Any,
                     }),
+                    connection: None,
                     output_mode: None,
                 },
                 slot: LedSlot(1),
@@ -792,6 +915,7 @@ mod tests {
                         max_level: Some(40),
                         charge: ChargeCondition::Discharging,
                     }),
+                    connection: None,
                     output_mode: None,
                 },
                 slot: LedSlot(0),
@@ -804,6 +928,7 @@ mod tests {
             layers: LayerState::new(2, 0, 0b101),
             indicators: Default::default(),
             powered: false,
+            connection: Default::default(),
         };
         let compositor = Compositor::<Rgb8, 2>::new(Rgb8::BLACK);
         let mut frame = LogicalFrame::new(Rgb8::BLACK);
diff --git a/rmk/src/lighting/standard/conditional.rs b/rmk/src/lighting/standard/conditional.rs
index e62e760d4..e6f720a53 100644
--- a/rmk/src/lighting/standard/conditional.rs
+++ b/rmk/src/lighting/standard/conditional.rs
@@ -19,6 +19,7 @@ pub(super) const EMPTY_CONDITIONAL_SCENE_CELL: RuntimeConditionalSceneCell = Run
     conditions: ConditionSet {
         layer: None,
         battery: None,
+        connection: None,
         output_mode: None,
     },
     slot: LedSlot(0),
@@ -39,6 +40,7 @@ const EMPTY_INTERNED_CONDITIONAL_SCENE_CELL: InternedRuntimeConditionalSceneCell
         conditions: ConditionSet {
             layer: None,
             battery: None,
+            connection: None,
             output_mode: None,
         },
         slot: LedSlot(0),
diff --git a/rmk/src/lighting/standard/tests.rs b/rmk/src/lighting/standard/tests.rs
index 071d47c1b..417e474a7 100644
--- a/rmk/src/lighting/standard/tests.rs
+++ b/rmk/src/lighting/standard/tests.rs
@@ -174,6 +174,7 @@ fn context(layer: u8) -> LightingContext {
         layers: LayerState::new(layer, 0, 1 | (1 << layer)),
         indicators: Default::default(),
         powered: false,
+        connection: Default::default(),
     }
 }
 
@@ -1690,6 +1691,7 @@ fn runtime_conditional_replace_preserves_order_and_output_mode_is_revision_check
                     max_level: Some(75),
                     charge: ChargeCondition::Discharging,
                 }),
+                connection: None,
                 output_mode: None,
             },
             slot: LedSlot(1),
@@ -1701,6 +1703,7 @@ fn runtime_conditional_replace_preserves_order_and_output_mode_is_revision_check
             conditions: ConditionSet {
                 layer: Some(LayerCondition { layer: 0, active: true }),
                 battery: None,
+                connection: None,
                 output_mode: None,
             },
             slot: LedSlot(1),
@@ -1968,6 +1971,7 @@ fn conditional_rules_share_styles_without_losing_order_or_conditions() {
             conditions: ConditionSet {
                 layer: Some(crate::lighting::LayerCondition { layer: 2, active: true }),
                 battery: None,
+                connection: None,
                 output_mode: Some(OutputMode::AlwaysOn),
             },
             slot: LedSlot(3),
@@ -1977,6 +1981,7 @@ fn conditional_rules_share_styles_without_losing_order_or_conditions() {
             conditions: ConditionSet {
                 layer: Some(crate::lighting::LayerCondition { layer: 2, active: true }),
                 battery: None,
+                connection: None,
                 output_mode: Some(OutputMode::PoweredOnly),
             },
             slot: LedSlot(3),
@@ -2107,6 +2112,7 @@ fn output_mode_conditions_select_between_runtime_rules() {
         conditions: ConditionSet {
             layer: None,
             battery: None,
+            connection: None,
             output_mode: Some(mode),
         },
         slot: LedSlot(0),
@@ -2133,6 +2139,7 @@ fn output_mode_conditions_select_between_runtime_rules() {
         layers: LayerState::new(0, 0, 1),
         indicators: Default::default(),
         powered: true,
+        connection: Default::default(),
     };
     let mut frame = LogicalFrame::new(Rgb8::BLACK);
     let render = |engine: &mut ConditionalEngine, frame: &mut LogicalFrame<Rgb8, 2>| {
@@ -2189,6 +2196,7 @@ fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules
         conditions: ConditionSet {
             layer: Some(LayerCondition { layer: 1, active: true }),
             battery: None,
+            connection: None,
             output_mode: None,
         },
         slot: LedSlot(0),
@@ -2238,6 +2246,7 @@ fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules
             conditions: ConditionSet {
                 layer: Some(LayerCondition { layer: 1, active: true }),
                 battery: None,
+                connection: None,
                 output_mode: None,
             },
             slot: LedSlot(0),

From 278838c5fc48240e46a83899304501dd4e61d74f Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 18:06:05 -0700
Subject: [PATCH 61/78] feat(rynk): add connection-aware lighting conditions

---
 .../main/docs/development/rynk_protocol.md    | 204 ++++++------
 rmk-types/src/protocol/rynk/command.rs        |  42 ++-
 .../src/protocol/rynk/payload/lighting.rs     | 142 +++++++++
 .../rynk/snapshots/lighting_wire_frames.snap  | 202 ++++++------
 rmk-types/src/protocol/rynk/tests.rs          | 119 ++++++-
 rmk/src/host/rynk/handlers/lighting.rs        | 301 ++++++++++++++++--
 rmk/src/host/rynk/lighting.rs                 | 168 ++++++++--
 rmk/src/host/rynk/mod.rs                      |  30 +-
 rmk/src/storage/mod.rs                        | 197 +++++++++++-
 rynk/rynk-wasm/src/client.rs                  |  23 +-
 rynk/src/api.rs                               | 186 ++++++++++-
 11 files changed, 1337 insertions(+), 277 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 3e7be3ff2..d21a78fdd 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -26,105 +26,111 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 
 ## Endpoints
 
-| CMD      | Name                                           | Request                                               | Response                                           | Feature          | Notes                                                                                                                                  |
-| -------- | ---------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `0x0001` | `GetVersion`                                   | `()`                                                  | `ProtocolVersion`                                  |                  |                                                                                                                                        |
-| `0x0002` | `GetCapabilities`                              | `()`                                                  | `DeviceCapabilities`                               |                  |                                                                                                                                        |
-| `0x0003` | `Reboot`                                       | `()`                                                  | `()`                                               |                  |                                                                                                                                        |
-| `0x0004` | `BootloaderJump`                               | `()`                                                  | `()`                                               |                  |                                                                                                                                        |
-| `0x0005` | `StorageReset`                                 | `StorageResetMode`                                    | `()`                                               |                  |                                                                                                                                        |
-| `0x0006` | `GetLockStatus`                                | `()`                                                  | `LockStatus`                                       |                  | Pure read of the current lock state — no side effects.                                                                                 |
-| `0x0007` | `UnlockPoll`                                   | `()`                                                  | `LockStatus`                                       |                  | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                                 |
-| `0x0008` | `Lock`                                         | `()`                                                  | `()`                                               |                  | Relock immediately.                                                                                                                    |
-| `0x0009` | `GetLayout`                                    | `u32`                                                 | `LayoutChunk`                                      |                  | Get layout blob chunk. `u32` is the byte offset.                                                                                       |
-| `0x000A` | `GetDeviceInfo`                                | `()`                                                  | `DeviceInfo`                                       |                  | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                               |
-| `0x000B` | `GetBuildInfo`                                 | `()`                                                  | `BuildInfo`                                        |                  | Application-defined diagnostic build label; never used for compatibility.                                                              |
-| `0x000C` | `PeripheralBootloaderJump`                     | `u8`                                                  | `()`                                               |                  | Ask the application to route a bootloader jump to one split peripheral.                                                                |
-| `0x0101` | `GetKeyAction`                                 | `KeyPosition`                                         | `KeyAction`                                        |                  |                                                                                                                                        |
-| `0x0102` | `SetKeyAction`                                 | `SetKeyRequest`                                       | `()`                                               |                  |                                                                                                                                        |
-| `0x0103` | `GetDefaultLayer`                              | `()`                                                  | `u8`                                               |                  |                                                                                                                                        |
-| `0x0104` | `SetDefaultLayer`                              | `u8`                                                  | `()`                                               |                  |                                                                                                                                        |
-| `0x0105` | `GetEncoderAction`                             | `GetEncoderRequest`                                   | `EncoderAction`                                    |                  |                                                                                                                                        |
-| `0x0106` | `SetEncoderAction`                             | `SetEncoderRequest`                                   | `()`                                               |                  |                                                                                                                                        |
-| `0x0107` | `GetKeymapBulk`                                | `GetKeymapBulkRequest`                                | `GetKeymapBulkResponse`                            |                  |                                                                                                                                        |
-| `0x0108` | `SetKeymapBulk`                                | `SetKeymapBulkRequest`                                | `()`                                               |                  |                                                                                                                                        |
-| `0x0201` | `GetMacro`                                     | `GetMacroRequest`                                     | `MacroData`                                        |                  |                                                                                                                                        |
-| `0x0202` | `SetMacro`                                     | `SetMacroRequest`                                     | `()`                                               |                  |                                                                                                                                        |
-| `0x0301` | `GetCombo`                                     | `u8`                                                  | `Combo`                                            |                  |                                                                                                                                        |
-| `0x0302` | `SetCombo`                                     | `SetComboRequest`                                     | `()`                                               |                  |                                                                                                                                        |
-| `0x0303` | `GetComboBulk`                                 | `GetComboBulkRequest`                                 | `GetComboBulkResponse`                             |                  |                                                                                                                                        |
-| `0x0304` | `SetComboBulk`                                 | `SetComboBulkRequest`                                 | `()`                                               |                  |                                                                                                                                        |
-| `0x0401` | `GetMorse`                                     | `u8`                                                  | `Morse`                                            |                  |                                                                                                                                        |
-| `0x0402` | `SetMorse`                                     | `SetMorseRequest`                                     | `()`                                               |                  |                                                                                                                                        |
-| `0x0403` | `GetMorseBulk`                                 | `GetMorseBulkRequest`                                 | `GetMorseBulkResponse`                             |                  |                                                                                                                                        |
-| `0x0404` | `SetMorseBulk`                                 | `SetMorseBulkRequest`                                 | `()`                                               |                  |                                                                                                                                        |
-| `0x0501` | `GetFork`                                      | `u8`                                                  | `Fork`                                             |                  |                                                                                                                                        |
-| `0x0502` | `SetFork`                                      | `SetForkRequest`                                      | `()`                                               |                  |                                                                                                                                        |
-| `0x0601` | `GetBehaviorConfig`                            | `()`                                                  | `BehaviorConfig`                                   |                  |                                                                                                                                        |
-| `0x0602` | `SetBehaviorConfig`                            | `BehaviorConfig`                                      | `()`                                               |                  |                                                                                                                                        |
-| `0x0701` | `GetConnectionType`                            | `()`                                                  | `ConnectionType`                                   |                  |                                                                                                                                        |
-| `0x0702` | `GetConnectionStatus`                          | `()`                                                  | `ConnectionStatus`                                 |                  | Full `ConnectionStatus` snapshot.                                                                                                      |
-| `0x0703` | `GetBleStatus`                                 | `()`                                                  | `BleStatus`                                        | `_ble`           |                                                                                                                                        |
-| `0x0704` | `SwitchBleProfile`                             | `u8`                                                  | `()`                                               | `_ble`           |                                                                                                                                        |
-| `0x0705` | `ClearBleProfile`                              | `u8`                                                  | `()`                                               | `_ble`           |                                                                                                                                        |
-| `0x0706` | `GetSplitCentralLatency`                       | `()`                                                  | `SplitCentralLatencyState`                         | `_ble` + `split` | Read the volatile active-mode policy, current USB-power selection, and effective value.                                                |
-| `0x0707` | `SetSplitCentralLatency`                       | `SplitCentralLatencyPolicy`                           | `SplitCentralLatencyState`                         | `_ble` + `split` | Replace the volatile policy. Each connection-event count must be `0..=499`.                                                            |
-| `0x0801` | `GetCurrentLayer`                              | `()`                                                  | `u8`                                               |                  |                                                                                                                                        |
-| `0x0802` | `GetMatrixState`                               | `()`                                                  | `MatrixState`                                      |                  |                                                                                                                                        |
-| `0x0803` | `GetBatteryStatus`                             | `()`                                                  | `BatteryStatus`                                    | `_ble`           |                                                                                                                                        |
-| `0x0804` | `GetPeripheralStatus`                          | `u8`                                                  | `PeripheralStatus`                                 | `split`          |                                                                                                                                        |
-| `0x0805` | `GetWpm`                                       | `()`                                                  | `u16`                                              |                  | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                               |
-| `0x0806` | `GetSleepState`                                | `()`                                                  | `bool`                                             |                  | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                                       |
-| `0x0807` | `GetLedIndicator`                              | `()`                                                  | `LedIndicator`                                     |                  | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                           |
-| `0x0808` | `GetLayerState`                                | `()`                                                  | `LayerState`                                       |                  | Default layer and complete active-layer bitmap.                                                                                        |
-| `0x0809` | `GetModifierState`                             | `()`                                                  | `ModifierCombination`                              |                  | Final resolved modifier bitmap used by the HID keyboard report.                                                                        |
-| `0x0901` | `GetLightingCapabilities`                      | `()`                                                  | `LightingCapabilitiesResult`                       | `lighting`       |                                                                                                                                        |
-| `0x0902` | `GetLightingState`                             | `()`                                                  | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
-| `0x0903` | `SetLightingState`                             | `SetLightingStateRequest`                             | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
-| `0x0904` | `GetLightingPhysicalKeys`                      | `LightingPageRequest`                                 | `LightingPhysicalKeysPageResult`                   | `lighting`       |                                                                                                                                        |
-| `0x0905` | `GetLightingLeds`                              | `LightingPageRequest`                                 | `LightingLedsPageResult`                           | `lighting`       |                                                                                                                                        |
-| `0x0906` | `GetLightingZones`                             | `LightingPageRequest`                                 | `LightingZonesPageResult`                          | `lighting`       |                                                                                                                                        |
-| `0x0907` | `GetLightingZoneMemberships`                   | `LightingPageRequest`                                 | `LightingZoneMembershipsPageResult`                | `lighting`       |                                                                                                                                        |
-| `0x0908` | `GetLightingOutputs`                           | `LightingPageRequest`                                 | `LightingOutputsPageResult`                        | `lighting`       |                                                                                                                                        |
-| `0x0909` | `GetLightingRoutes`                            | `LightingPageRequest`                                 | `LightingRoutesPageResult`                         | `lighting`       |                                                                                                                                        |
-| `0x090A` | `SetLightingOverlay`                           | `SetLightingOverlayRequest`                           | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
-| `0x090B` | `UnsetLightingOverlay`                         | `UnsetLightingOverlayRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
-| `0x090C` | `ClearLightingOverlay`                         | `ClearLightingOverlayRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
-| `0x090D` | `BeginLightingOverlayReplace`                  | `BeginLightingOverlayReplaceRequest`                  | `LightingOverlayTransactionResult`                 | `lighting`       |                                                                                                                                        |
-| `0x090E` | `PutLightingOverlayChunk`                      | `PutLightingOverlayChunkRequest`                      | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
-| `0x090F` | `CommitLightingOverlayReplace`                 | `CommitLightingOverlayReplaceRequest`                 | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
-| `0x0910` | `AbortLightingOverlayReplace`                  | `AbortLightingOverlayReplaceRequest`                  | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
-| `0x0911` | `GetLightingKeys`                              | `LightingPageRequest`                                 | `LightingKeysPageResult`                           | `lighting`       | Logical matrix keys are distinct from optional physical geometry.                                                                      |
-| `0x0912` | `GetLightingSceneStatus`                       | `()`                                                  | `LightingSceneStatusResult`                        | `lighting`       | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts.         |
-| `0x0913` | `GetLightingScenes`                            | `LightingScenePageRequest`                            | `LightingScenesPageResult`                         | `lighting`       | Scene pages are pinned to `LightingState.revision` for consistency.                                                                    |
-| `0x0914` | `SetLightingSceneCell`                         | `SetLightingSceneCellRequest`                         | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
-| `0x0915` | `UnsetLightingSceneCell`                       | `UnsetLightingSceneCellRequest`                       | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
-| `0x0916` | `BeginLightingSceneReplace`                    | `BeginLightingSceneReplaceRequest`                    | `LightingSceneTransactionResult`                   | `lighting`       |                                                                                                                                        |
-| `0x0917` | `PutLightingSceneChunk`                        | `PutLightingSceneChunkRequest`                        | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
-| `0x0918` | `CommitLightingSceneReplace`                   | `CommitLightingSceneReplaceRequest`                   | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
-| `0x0919` | `AbortLightingSceneReplace`                    | `AbortLightingSceneReplaceRequest`                    | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
-| `0x091A` | `SetLightingLayerPolicy`                       | `SetLightingLayerPolicyRequest`                       | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
-| `0x091B` | `GetLightingOverlay`                           | `LightingOverlayPageRequest`                          | `LightingOverlayPageResult`                        | `lighting`       | Overlay pages are pinned to `LightingState.revision` for consistency.                                                                  |
-| `0x091C` | `GetLightingCompiledSceneStatus`               | `()`                                                  | `LightingCompiledSceneStatusResult`                | `lighting`       | Discover the immutable board-compiled layer-scene source.                                                                              |
-| `0x091D` | `GetLightingCompiledScenes`                    | `LightingPageRequest`                                 | `LightingCompiledScenesPageResult`                 | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                                     |
-| `0x091E` | `GetLightingConditionalSceneStatus`            | `()`                                                  | `LightingConditionalSceneStatusResult`             | `lighting`       | Discover immutable conditional lighting compiled from board config.                                                                    |
-| `0x091F` | `GetLightingConditionalScenes`                 | `LightingPageRequest`                                 | `LightingConditionalScenesPageResult`              | `lighting`       | Conditional-scene pages are pinned to the firmware topology revision.                                                                  |
-| `0x0920` | `GetLightingOutputMode`                        | `()`                                                  | `LightingOutputModeStateResult`                    | `lighting`       | Read the configured three-state output policy and its live state.                                                                      |
-| `0x0921` | `GetLightingExtension`                         | `()`                                                  | `LightingExtensionResult`                          | `lighting`       | Discover the animated extension band: name-list sizes and selection.                                                                   |
-| `0x0922` | `GetLightingExtensionNames`                    | `LightingExtensionNamesRequest`                       | `LightingExtensionNamesPageResult`                 | `lighting`       | Extension names are static per firmware build; page until `total`.                                                                     |
-| `0x0923` | `SetLightingExtensionState`                    | `SetLightingExtensionStateRequest`                    | `LightingStateResult`                              | `lighting`       | Replace the extension selection when the state revision matches.                                                                       |
-| `0x0924` | `SetLightingOutputMode`                        | `SetLightingOutputModeRequest`                        | `LightingOutputModeStateResult`                    | `lighting`       | Set the three-state output policy with optimistic concurrency.                                                                         |
-| `0x0925` | `GetLightingRuntimeConditionalSceneStatus`     | `()`                                                  | `LightingRuntimeConditionalSceneStatusResult`      | `lighting`       | Discover the mutable ordered conditional-scene table.                                                                                  |
-| `0x0926` | `GetLightingRuntimeConditionalScenes`          | `LightingRuntimeConditionalScenePageRequest`          | `LightingRuntimeConditionalScenesPageResult`       | `lighting`       | Runtime conditional pages are pinned to `LightingState.revision`.                                                                      |
-| `0x0927` | `BeginLightingRuntimeConditionalSceneReplace`  | `BeginLightingRuntimeConditionalSceneReplaceRequest`  | `LightingRuntimeConditionalSceneTransactionResult` | `lighting`       |                                                                                                                                        |
-| `0x0928` | `PutLightingRuntimeConditionalSceneChunk`      | `PutLightingRuntimeConditionalSceneChunkRequest`      | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
-| `0x0929` | `CommitLightingRuntimeConditionalSceneReplace` | `CommitLightingRuntimeConditionalSceneReplaceRequest` | `LightingStateResult`                              | `lighting`       |                                                                                                                                        |
-| `0x092A` | `AbortLightingRuntimeConditionalSceneReplace`  | `AbortLightingRuntimeConditionalSceneReplaceRequest`  | `LightingUnitResult`                               | `lighting`       |                                                                                                                                        |
-| `0x092B` | `GetLightingExtensionParams`                   | `LightingExtensionParamsRequest`                      | `LightingExtensionParamsPageResult`                | `lighting`       | Per-effect tunable parameters: descriptors plus live values, pinned to `LightingState.revision`. Page until `total`.                   |
-| `0x092C` | `SetLightingExtensionParam`                    | `SetLightingExtensionParamRequest`                    | `LightingStateResult`                              | `lighting`       | Set one effect parameter when the state revision matches.                                                                              |
-| `0x092D` | `SetLightingWakeLayers`                        | `SetLightingWakeLayersRequest`                        | `LightingOutputModeStateResult`                    | `lighting`       | Replace the wake-layer mask. Policy rather than lighting content, but dynamic so which layers wake lighting is not a firmware rebuild. |
-| `0x092E` | `GetLightingExtensionLayers`                   | `()`                                                  | `LightingExtensionLayersResult`                    | `lighting`       | Read the optional second effect layered over the primary extension.                                                                    |
-| `0x092F` | `SetLightingExtensionLayers`                   | `SetLightingExtensionLayersRequest`                   | `LightingStateResult`                              | `lighting`       | Replace the optional second effect when the state revision matches.                                                                    |
+| CMD      | Name                                                   | Request                                                  | Response                                             | Feature          | Notes                                                                                                                                                                                  |
+| -------- | ------------------------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0x0001` | `GetVersion`                                           | `()`                                                     | `ProtocolVersion`                                    |                  |                                                                                                                                                                                        |
+| `0x0002` | `GetCapabilities`                                      | `()`                                                     | `DeviceCapabilities`                                 |                  |                                                                                                                                                                                        |
+| `0x0003` | `Reboot`                                               | `()`                                                     | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0004` | `BootloaderJump`                                       | `()`                                                     | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0005` | `StorageReset`                                         | `StorageResetMode`                                       | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0006` | `GetLockStatus`                                        | `()`                                                     | `LockStatus`                                         |                  | Pure read of the current lock state — no side effects.                                                                                                                                 |
+| `0x0007` | `UnlockPoll`                                           | `()`                                                     | `LockStatus`                                         |                  | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                                                                                 |
+| `0x0008` | `Lock`                                                 | `()`                                                     | `()`                                                 |                  | Relock immediately.                                                                                                                                                                    |
+| `0x0009` | `GetLayout`                                            | `u32`                                                    | `LayoutChunk`                                        |                  | Get layout blob chunk. `u32` is the byte offset.                                                                                                                                       |
+| `0x000A` | `GetDeviceInfo`                                        | `()`                                                     | `DeviceInfo`                                         |                  | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                                                                               |
+| `0x000B` | `GetBuildInfo`                                         | `()`                                                     | `BuildInfo`                                          |                  | Application-defined diagnostic build label; never used for compatibility.                                                                                                              |
+| `0x000C` | `PeripheralBootloaderJump`                             | `u8`                                                     | `()`                                                 |                  | Ask the application to route a bootloader jump to one split peripheral.                                                                                                                |
+| `0x0101` | `GetKeyAction`                                         | `KeyPosition`                                            | `KeyAction`                                          |                  |                                                                                                                                                                                        |
+| `0x0102` | `SetKeyAction`                                         | `SetKeyRequest`                                          | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0103` | `GetDefaultLayer`                                      | `()`                                                     | `u8`                                                 |                  |                                                                                                                                                                                        |
+| `0x0104` | `SetDefaultLayer`                                      | `u8`                                                     | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0105` | `GetEncoderAction`                                     | `GetEncoderRequest`                                      | `EncoderAction`                                      |                  |                                                                                                                                                                                        |
+| `0x0106` | `SetEncoderAction`                                     | `SetEncoderRequest`                                      | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0107` | `GetKeymapBulk`                                        | `GetKeymapBulkRequest`                                   | `GetKeymapBulkResponse`                              |                  |                                                                                                                                                                                        |
+| `0x0108` | `SetKeymapBulk`                                        | `SetKeymapBulkRequest`                                   | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0201` | `GetMacro`                                             | `GetMacroRequest`                                        | `MacroData`                                          |                  |                                                                                                                                                                                        |
+| `0x0202` | `SetMacro`                                             | `SetMacroRequest`                                        | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0301` | `GetCombo`                                             | `u8`                                                     | `Combo`                                              |                  |                                                                                                                                                                                        |
+| `0x0302` | `SetCombo`                                             | `SetComboRequest`                                        | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0303` | `GetComboBulk`                                         | `GetComboBulkRequest`                                    | `GetComboBulkResponse`                               |                  |                                                                                                                                                                                        |
+| `0x0304` | `SetComboBulk`                                         | `SetComboBulkRequest`                                    | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0401` | `GetMorse`                                             | `u8`                                                     | `Morse`                                              |                  |                                                                                                                                                                                        |
+| `0x0402` | `SetMorse`                                             | `SetMorseRequest`                                        | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0403` | `GetMorseBulk`                                         | `GetMorseBulkRequest`                                    | `GetMorseBulkResponse`                               |                  |                                                                                                                                                                                        |
+| `0x0404` | `SetMorseBulk`                                         | `SetMorseBulkRequest`                                    | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0501` | `GetFork`                                              | `u8`                                                     | `Fork`                                               |                  |                                                                                                                                                                                        |
+| `0x0502` | `SetFork`                                              | `SetForkRequest`                                         | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0601` | `GetBehaviorConfig`                                    | `()`                                                     | `BehaviorConfig`                                     |                  |                                                                                                                                                                                        |
+| `0x0602` | `SetBehaviorConfig`                                    | `BehaviorConfig`                                         | `()`                                                 |                  |                                                                                                                                                                                        |
+| `0x0701` | `GetConnectionType`                                    | `()`                                                     | `ConnectionType`                                     |                  |                                                                                                                                                                                        |
+| `0x0702` | `GetConnectionStatus`                                  | `()`                                                     | `ConnectionStatus`                                   |                  | Full `ConnectionStatus` snapshot.                                                                                                                                                      |
+| `0x0703` | `GetBleStatus`                                         | `()`                                                     | `BleStatus`                                          | `_ble`           |                                                                                                                                                                                        |
+| `0x0704` | `SwitchBleProfile`                                     | `u8`                                                     | `()`                                                 | `_ble`           |                                                                                                                                                                                        |
+| `0x0705` | `ClearBleProfile`                                      | `u8`                                                     | `()`                                                 | `_ble`           |                                                                                                                                                                                        |
+| `0x0706` | `GetSplitCentralLatency`                               | `()`                                                     | `SplitCentralLatencyState`                           | `_ble` + `split` | Read the volatile active-mode policy, current USB-power selection, and effective value.                                                                                                |
+| `0x0707` | `SetSplitCentralLatency`                               | `SplitCentralLatencyPolicy`                              | `SplitCentralLatencyState`                           | `_ble` + `split` | Replace the volatile policy. Each connection-event count must be `0..=499`.                                                                                                            |
+| `0x0801` | `GetCurrentLayer`                                      | `()`                                                     | `u8`                                                 |                  |                                                                                                                                                                                        |
+| `0x0802` | `GetMatrixState`                                       | `()`                                                     | `MatrixState`                                        |                  |                                                                                                                                                                                        |
+| `0x0803` | `GetBatteryStatus`                                     | `()`                                                     | `BatteryStatus`                                      | `_ble`           |                                                                                                                                                                                        |
+| `0x0804` | `GetPeripheralStatus`                                  | `u8`                                                     | `PeripheralStatus`                                   | `split`          |                                                                                                                                                                                        |
+| `0x0805` | `GetWpm`                                               | `()`                                                     | `u16`                                                |                  | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                                                                               |
+| `0x0806` | `GetSleepState`                                        | `()`                                                     | `bool`                                               |                  | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                                                                                       |
+| `0x0807` | `GetLedIndicator`                                      | `()`                                                     | `LedIndicator`                                       |                  | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                                                                           |
+| `0x0808` | `GetLayerState`                                        | `()`                                                     | `LayerState`                                         |                  | Default layer and complete active-layer bitmap.                                                                                                                                        |
+| `0x0809` | `GetModifierState`                                     | `()`                                                     | `ModifierCombination`                                |                  | Final resolved modifier bitmap used by the HID keyboard report.                                                                                                                        |
+| `0x0901` | `GetLightingCapabilities`                              | `()`                                                     | `LightingCapabilitiesResult`                         | `lighting`       |                                                                                                                                                                                        |
+| `0x0902` | `GetLightingState`                                     | `()`                                                     | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
+| `0x0903` | `SetLightingState`                                     | `SetLightingStateRequest`                                | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
+| `0x0904` | `GetLightingPhysicalKeys`                              | `LightingPageRequest`                                    | `LightingPhysicalKeysPageResult`                     | `lighting`       |                                                                                                                                                                                        |
+| `0x0905` | `GetLightingLeds`                                      | `LightingPageRequest`                                    | `LightingLedsPageResult`                             | `lighting`       |                                                                                                                                                                                        |
+| `0x0906` | `GetLightingZones`                                     | `LightingPageRequest`                                    | `LightingZonesPageResult`                            | `lighting`       |                                                                                                                                                                                        |
+| `0x0907` | `GetLightingZoneMemberships`                           | `LightingPageRequest`                                    | `LightingZoneMembershipsPageResult`                  | `lighting`       |                                                                                                                                                                                        |
+| `0x0908` | `GetLightingOutputs`                                   | `LightingPageRequest`                                    | `LightingOutputsPageResult`                          | `lighting`       |                                                                                                                                                                                        |
+| `0x0909` | `GetLightingRoutes`                                    | `LightingPageRequest`                                    | `LightingRoutesPageResult`                           | `lighting`       |                                                                                                                                                                                        |
+| `0x090A` | `SetLightingOverlay`                                   | `SetLightingOverlayRequest`                              | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
+| `0x090B` | `UnsetLightingOverlay`                                 | `UnsetLightingOverlayRequest`                            | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
+| `0x090C` | `ClearLightingOverlay`                                 | `ClearLightingOverlayRequest`                            | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
+| `0x090D` | `BeginLightingOverlayReplace`                          | `BeginLightingOverlayReplaceRequest`                     | `LightingOverlayTransactionResult`                   | `lighting`       |                                                                                                                                                                                        |
+| `0x090E` | `PutLightingOverlayChunk`                              | `PutLightingOverlayChunkRequest`                         | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                        |
+| `0x090F` | `CommitLightingOverlayReplace`                         | `CommitLightingOverlayReplaceRequest`                    | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
+| `0x0910` | `AbortLightingOverlayReplace`                          | `AbortLightingOverlayReplaceRequest`                     | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                        |
+| `0x0911` | `GetLightingKeys`                                      | `LightingPageRequest`                                    | `LightingKeysPageResult`                             | `lighting`       | Logical matrix keys are distinct from optional physical geometry.                                                                                                                      |
+| `0x0912` | `GetLightingSceneStatus`                               | `()`                                                     | `LightingSceneStatusResult`                          | `lighting`       | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts.                                                         |
+| `0x0913` | `GetLightingScenes`                                    | `LightingScenePageRequest`                               | `LightingScenesPageResult`                           | `lighting`       | Scene pages are pinned to `LightingState.revision` for consistency.                                                                                                                    |
+| `0x0914` | `SetLightingSceneCell`                                 | `SetLightingSceneCellRequest`                            | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
+| `0x0915` | `UnsetLightingSceneCell`                               | `UnsetLightingSceneCellRequest`                          | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
+| `0x0916` | `BeginLightingSceneReplace`                            | `BeginLightingSceneReplaceRequest`                       | `LightingSceneTransactionResult`                     | `lighting`       |                                                                                                                                                                                        |
+| `0x0917` | `PutLightingSceneChunk`                                | `PutLightingSceneChunkRequest`                           | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                        |
+| `0x0918` | `CommitLightingSceneReplace`                           | `CommitLightingSceneReplaceRequest`                      | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
+| `0x0919` | `AbortLightingSceneReplace`                            | `AbortLightingSceneReplaceRequest`                       | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                        |
+| `0x091A` | `SetLightingLayerPolicy`                               | `SetLightingLayerPolicyRequest`                          | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
+| `0x091B` | `GetLightingOverlay`                                   | `LightingOverlayPageRequest`                             | `LightingOverlayPageResult`                          | `lighting`       | Overlay pages are pinned to `LightingState.revision` for consistency.                                                                                                                  |
+| `0x091C` | `GetLightingCompiledSceneStatus`                       | `()`                                                     | `LightingCompiledSceneStatusResult`                  | `lighting`       | Discover the immutable board-compiled layer-scene source.                                                                                                                              |
+| `0x091D` | `GetLightingCompiledScenes`                            | `LightingPageRequest`                                    | `LightingCompiledScenesPageResult`                   | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                                                                                     |
+| `0x091E` | `GetLightingConditionalSceneStatus`                    | `()`                                                     | `LightingConditionalSceneStatusResult`               | `lighting`       | Discover immutable conditional lighting compiled from board config.                                                                                                                    |
+| `0x091F` | `GetLightingConditionalScenes`                         | `LightingPageRequest`                                    | `LightingConditionalScenesPageResult`                | `lighting`       | Conditional-scene pages are pinned to the firmware topology revision.                                                                                                                  |
+| `0x0920` | `GetLightingOutputMode`                                | `()`                                                     | `LightingOutputModeStateResult`                      | `lighting`       | Read the configured three-state output policy and its live state.                                                                                                                      |
+| `0x0921` | `GetLightingExtension`                                 | `()`                                                     | `LightingExtensionResult`                            | `lighting`       | Discover the animated extension band: name-list sizes and selection.                                                                                                                   |
+| `0x0922` | `GetLightingExtensionNames`                            | `LightingExtensionNamesRequest`                          | `LightingExtensionNamesPageResult`                   | `lighting`       | Extension names are static per firmware build; page until `total`.                                                                                                                     |
+| `0x0923` | `SetLightingExtensionState`                            | `SetLightingExtensionStateRequest`                       | `LightingStateResult`                                | `lighting`       | Replace the extension selection when the state revision matches.                                                                                                                       |
+| `0x0924` | `SetLightingOutputMode`                                | `SetLightingOutputModeRequest`                           | `LightingOutputModeStateResult`                      | `lighting`       | Set the three-state output policy with optimistic concurrency.                                                                                                                         |
+| `0x0925` | `GetLightingRuntimeConditionalSceneStatus`             | `()`                                                     | `LightingRuntimeConditionalSceneStatusResult`        | `lighting`       | Discover the mutable ordered conditional-scene table.                                                                                                                                  |
+| `0x0926` | `GetLightingRuntimeConditionalScenes`                  | `LightingRuntimeConditionalScenePageRequest`             | `LightingRuntimeConditionalScenesPageResult`         | `lighting`       | Runtime conditional pages are pinned to `LightingState.revision`. Connection predicates are omitted; use the extended read command when `RUNTIME_CONNECTION_CONDITIONS` is advertised. |
+| `0x0927` | `BeginLightingRuntimeConditionalSceneReplace`          | `BeginLightingRuntimeConditionalSceneReplaceRequest`     | `LightingRuntimeConditionalSceneTransactionResult`   | `lighting`       |                                                                                                                                                                                        |
+| `0x0928` | `PutLightingRuntimeConditionalSceneChunk`              | `PutLightingRuntimeConditionalSceneChunkRequest`         | `LightingUnitResult`                                 | `lighting`       | Cells written through this legacy endpoint have no connection predicate.                                                                                                               |
+| `0x0929` | `CommitLightingRuntimeConditionalSceneReplace`         | `CommitLightingRuntimeConditionalSceneReplaceRequest`    | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
+| `0x092A` | `AbortLightingRuntimeConditionalSceneReplace`          | `AbortLightingRuntimeConditionalSceneReplaceRequest`     | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                        |
+| `0x092B` | `GetLightingExtensionParams`                           | `LightingExtensionParamsRequest`                         | `LightingExtensionParamsPageResult`                  | `lighting`       | Per-effect tunable parameters: descriptors plus live values, pinned to `LightingState.revision`. Page until `total`.                                                                   |
+| `0x092C` | `SetLightingExtensionParam`                            | `SetLightingExtensionParamRequest`                       | `LightingStateResult`                                | `lighting`       | Set one effect parameter when the state revision matches.                                                                                                                              |
+| `0x092D` | `SetLightingWakeLayers`                                | `SetLightingWakeLayersRequest`                           | `LightingOutputModeStateResult`                      | `lighting`       | Replace the wake-layer mask. Policy rather than lighting content, but dynamic so which layers wake lighting is not a firmware rebuild.                                                 |
+| `0x092E` | `GetLightingExtensionLayers`                           | `()`                                                     | `LightingExtensionLayersResult`                      | `lighting`       | Read the optional second effect layered over the primary extension.                                                                                                                    |
+| `0x092F` | `SetLightingExtensionLayers`                           | `SetLightingExtensionLayersRequest`                      | `LightingStateResult`                                | `lighting`       | Replace the optional second effect when the state revision matches.                                                                                                                    |
+| `0x0930` | `GetLightingExtendedRuntimeConditionalSceneStatus`     | `()`                                                     | `LightingRuntimeConditionalSceneStatusResult`        | `lighting`       | Discover connection-aware runtime conditional limits and occupancy.                                                                                                                    |
+| `0x0931` | `GetLightingExtendedRuntimeConditionalScenes`          | `LightingRuntimeConditionalScenePageRequest`             | `LightingExtendedRuntimeConditionalScenesPageResult` | `lighting`       | Read connection-aware runtime conditional cells under a pinned state revision.                                                                                                         |
+| `0x0932` | `BeginLightingExtendedRuntimeConditionalSceneReplace`  | `BeginLightingRuntimeConditionalSceneReplaceRequest`     | `LightingRuntimeConditionalSceneTransactionResult`   | `lighting`       | Begin an atomic replacement using extended conditional cells.                                                                                                                          |
+| `0x0933` | `PutLightingExtendedRuntimeConditionalSceneChunk`      | `PutLightingExtendedRuntimeConditionalSceneChunkRequest` | `LightingUnitResult`                                 | `lighting`       | Stage connection-aware cells for an extended replacement.                                                                                                                              |
+| `0x0934` | `CommitLightingExtendedRuntimeConditionalSceneReplace` | `CommitLightingRuntimeConditionalSceneReplaceRequest`    | `LightingStateResult`                                | `lighting`       | Publish a complete extended conditional-table replacement.                                                                                                                             |
+| `0x0935` | `AbortLightingExtendedRuntimeConditionalSceneReplace`  | `AbortLightingRuntimeConditionalSceneReplaceRequest`     | `LightingUnitResult`                                 | `lighting`       | Discard an extended conditional-table replacement.                                                                                                                                     |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 4cd86e3e0..e801c0d99 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -41,19 +41,20 @@ use crate::protocol::rynk::{
     CommitLightingOverlayReplaceRequest, CommitLightingRuntimeConditionalSceneReplaceRequest,
     CommitLightingSceneReplaceRequest, LightingCapabilitiesResult, LightingChanged, LightingCompiledSceneStatusResult,
     LightingCompiledScenesPageResult, LightingConditionalSceneStatusResult, LightingConditionalScenesPageResult,
-    LightingExtensionLayersResult, LightingExtensionNamesPageResult, LightingExtensionNamesRequest,
-    LightingExtensionParamsPageResult, LightingExtensionParamsRequest, LightingExtensionResult, LightingKeysPageResult,
-    LightingLedsPageResult, LightingOutputModeStateResult, LightingOutputsPageResult, LightingOverlayPageRequest,
-    LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKeysPageResult,
-    LightingRoutesPageResult, LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatusResult,
+    LightingExtendedRuntimeConditionalScenesPageResult, LightingExtensionLayersResult,
+    LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionParamsPageResult,
+    LightingExtensionParamsRequest, LightingExtensionResult, LightingKeysPageResult, LightingLedsPageResult,
+    LightingOutputModeStateResult, LightingOutputsPageResult, LightingOverlayPageRequest, LightingOverlayPageResult,
+    LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKeysPageResult, LightingRoutesPageResult,
+    LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatusResult,
     LightingRuntimeConditionalSceneTransactionResult, LightingRuntimeConditionalScenesPageResult,
     LightingScenePageRequest, LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult,
     LightingStateResult, LightingUnitResult, LightingZoneMembershipsPageResult, LightingZonesPageResult,
-    PutLightingOverlayChunkRequest, PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest,
-    SetLightingExtensionLayersRequest, SetLightingExtensionParamRequest, SetLightingExtensionStateRequest,
-    SetLightingLayerPolicyRequest, SetLightingOutputModeRequest, SetLightingOverlayRequest,
-    SetLightingSceneCellRequest, SetLightingStateRequest, SetLightingWakeLayersRequest, UnsetLightingOverlayRequest,
-    UnsetLightingSceneCellRequest,
+    PutLightingExtendedRuntimeConditionalSceneChunkRequest, PutLightingOverlayChunkRequest,
+    PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, SetLightingExtensionLayersRequest,
+    SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
+    SetLightingOutputModeRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
+    SetLightingWakeLayersRequest, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest,
 };
 #[cfg(all(feature = "_ble", feature = "split"))]
 use crate::protocol::rynk::{SplitCentralLatencyPolicy, SplitCentralLatencyState};
@@ -469,11 +470,14 @@ endpoints! {
     #[cfg(feature = "lighting")]
     GetLightingRuntimeConditionalSceneStatus = 0x0925: () => LightingRuntimeConditionalSceneStatusResult;
     /// Runtime conditional pages are pinned to `LightingState.revision`.
+    /// Connection predicates are omitted; use the extended read command when
+    /// `RUNTIME_CONNECTION_CONDITIONS` is advertised.
     #[cfg(feature = "lighting")]
     GetLightingRuntimeConditionalScenes = 0x0926: LightingRuntimeConditionalScenePageRequest => LightingRuntimeConditionalScenesPageResult;
     #[cfg(feature = "lighting")]
     BeginLightingRuntimeConditionalSceneReplace = 0x0927: BeginLightingRuntimeConditionalSceneReplaceRequest => LightingRuntimeConditionalSceneTransactionResult;
     #[cfg(feature = "lighting")]
+    /// Cells written through this legacy endpoint have no connection predicate.
     PutLightingRuntimeConditionalSceneChunk = 0x0928: PutLightingRuntimeConditionalSceneChunkRequest => LightingUnitResult;
     #[cfg(feature = "lighting")]
     CommitLightingRuntimeConditionalSceneReplace = 0x0929: CommitLightingRuntimeConditionalSceneReplaceRequest => LightingStateResult;
@@ -496,6 +500,24 @@ endpoints! {
     /// Replace the optional second effect when the state revision matches.
     #[cfg(feature = "lighting")]
     SetLightingExtensionLayers = 0x092F: SetLightingExtensionLayersRequest => LightingStateResult;
+    /// Discover connection-aware runtime conditional limits and occupancy.
+    #[cfg(feature = "lighting")]
+    GetLightingExtendedRuntimeConditionalSceneStatus = 0x0930: () => LightingRuntimeConditionalSceneStatusResult;
+    /// Read connection-aware runtime conditional cells under a pinned state revision.
+    #[cfg(feature = "lighting")]
+    GetLightingExtendedRuntimeConditionalScenes = 0x0931: LightingRuntimeConditionalScenePageRequest => LightingExtendedRuntimeConditionalScenesPageResult;
+    /// Begin an atomic replacement using extended conditional cells.
+    #[cfg(feature = "lighting")]
+    BeginLightingExtendedRuntimeConditionalSceneReplace = 0x0932: BeginLightingRuntimeConditionalSceneReplaceRequest => LightingRuntimeConditionalSceneTransactionResult;
+    /// Stage connection-aware cells for an extended replacement.
+    #[cfg(feature = "lighting")]
+    PutLightingExtendedRuntimeConditionalSceneChunk = 0x0933: PutLightingExtendedRuntimeConditionalSceneChunkRequest => LightingUnitResult;
+    /// Publish a complete extended conditional-table replacement.
+    #[cfg(feature = "lighting")]
+    CommitLightingExtendedRuntimeConditionalSceneReplace = 0x0934: CommitLightingRuntimeConditionalSceneReplaceRequest => LightingStateResult;
+    /// Discard an extended conditional-table replacement.
+    #[cfg(feature = "lighting")]
+    AbortLightingExtendedRuntimeConditionalSceneReplace = 0x0935: AbortLightingRuntimeConditionalSceneReplaceRequest => LightingUnitResult;
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index c0e9cda81..5dc2f9b29 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -9,6 +9,8 @@ use heapless::{String, Vec};
 use postcard::experimental::max_size::MaxSize;
 use serde::{Deserialize, Serialize};
 
+use crate::ble::BleState;
+
 /// Maximum postcard payload admitted by this first lighting ICD.
 pub const LIGHTING_PAYLOAD_SIZE: usize = 256;
 /// Number of metadata records in one topology page.
@@ -19,6 +21,8 @@ pub const LIGHTING_OVERLAY_CHUNK_SIZE: usize = 8;
 pub const LIGHTING_SCENE_CHUNK_SIZE: usize = 8;
 /// Number of immutable conditional cells in one readback page.
 pub const LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 7;
+/// Number of connection-aware conditional cells in one extended page/chunk.
+pub const LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 6;
 /// Maximum UTF-8 byte length of a zone name.
 pub const LIGHTING_ZONE_NAME_SIZE: usize = 24;
 /// Maximum UTF-8 byte length of one extension effect or palette name.
@@ -205,6 +209,9 @@ impl LightingFeatureFlags {
     /// A second effect from the extension's ordinary effect list can be
     /// rendered over the primary effect.
     pub const EXTENSION_LAYERING: u16 = 1 << 13;
+    /// Runtime conditional rules can match transport and BLE connection state
+    /// through the extended conditional-scene endpoints.
+    pub const RUNTIME_CONNECTION_CONDITIONS: u16 = 1 << 14;
 
     pub const fn contains(self, bits: u16) -> bool {
         self.0 & bits == bits
@@ -652,6 +659,40 @@ impl LightingConditionalSceneCell {
     }
 }
 
+wire_type! {
+    /// Active transport selected by `ConnectionStatus::decide_active`.
+    pub enum LightingActiveTransport {
+        Usb,
+        Ble,
+        NoneActive,
+    }
+}
+
+wire_type! {
+    /// Optional connection predicates. Present fields form a conjunction; an
+    /// empty condition matches every connection state.
+    pub struct LightingConnectionCondition {
+        pub transport: Option<LightingActiveTransport>,
+        pub profile: Option<u8>,
+        pub ble_state: Option<BleState>,
+    }
+}
+
+wire_type! {
+    /// Additive runtime conditional cell used by the extended endpoints. The
+    /// nested legacy cell keeps its established postcard field order intact.
+    pub struct LightingExtendedConditionalSceneCell {
+        pub cell: LightingConditionalSceneCell,
+        pub connection: Option<LightingConnectionCondition>,
+    }
+}
+
+impl LightingExtendedConditionalSceneCell {
+    pub fn validate(&self) -> LightingResult<()> {
+        self.cell.validate()
+    }
+}
+
 wire_type! {
     /// Key/layer controls that gate the configured lighting presentation.
     pub struct LightingControls {
@@ -906,6 +947,26 @@ impl MaxSize for LightingRuntimeConditionalScenesPage {
         + crate::heapless_vec_max_size::<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>();
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LightingExtendedRuntimeConditionalScenesPage {
+    pub revision: u32,
+    pub total_count: u16,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingExtendedConditionalSceneCell[]"))]
+    pub items: Vec<LightingExtendedConditionalSceneCell, LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE>,
+}
+
+impl MaxSize for LightingExtendedRuntimeConditionalScenesPage {
+    const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+        + u16::POSTCARD_MAX_SIZE
+        + crate::heapless_vec_max_size::<
+            LightingExtendedConditionalSceneCell,
+            LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE,
+        >();
+}
+
 wire_type! {
     pub struct SetLightingOutputModeRequest {
         pub expected_revision: u32,
@@ -953,6 +1014,26 @@ impl MaxSize for PutLightingRuntimeConditionalSceneChunkRequest {
         + crate::heapless_vec_max_size::<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>();
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct PutLightingExtendedRuntimeConditionalSceneChunkRequest {
+    pub transaction_id: u32,
+    pub offset: u16,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingExtendedConditionalSceneCell[]"))]
+    pub cells: Vec<LightingExtendedConditionalSceneCell, LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE>,
+}
+
+impl MaxSize for PutLightingExtendedRuntimeConditionalSceneChunkRequest {
+    const POSTCARD_MAX_SIZE: usize = u32::POSTCARD_MAX_SIZE
+        + u16::POSTCARD_MAX_SIZE
+        + crate::heapless_vec_max_size::<
+            LightingExtendedConditionalSceneCell,
+            LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE,
+        >();
+}
+
 wire_type! {
     pub struct CommitLightingRuntimeConditionalSceneReplaceRequest {
         pub transaction_id: u32,
@@ -1095,6 +1176,8 @@ pub type LightingExtensionParamsPageResult = LightingResult<LightingExtensionPar
 pub type LightingSceneTransactionResult = LightingResult<LightingSceneTransaction>;
 pub type LightingRuntimeConditionalSceneStatusResult = LightingResult<LightingRuntimeConditionalSceneStatus>;
 pub type LightingRuntimeConditionalScenesPageResult = LightingResult<LightingRuntimeConditionalScenesPage>;
+pub type LightingExtendedRuntimeConditionalScenesPageResult =
+    LightingResult<LightingExtendedRuntimeConditionalScenesPage>;
 pub type LightingRuntimeConditionalSceneTransactionResult = LightingResult<LightingRuntimeConditionalSceneTransaction>;
 pub type LightingUnitResult = LightingResult<()>;
 
@@ -1157,6 +1240,14 @@ const _: () = {
         LightingRuntimeConditionalSceneTransactionResult
     );
     assert_endpoint_fits!(PutLightingRuntimeConditionalSceneChunkRequest, LightingUnitResult);
+    assert_endpoint_fits!(
+        PutLightingExtendedRuntimeConditionalSceneChunkRequest,
+        LightingUnitResult
+    );
+    assert_endpoint_fits!(
+        LightingRuntimeConditionalScenePageRequest,
+        LightingExtendedRuntimeConditionalScenesPageResult
+    );
     assert_endpoint_fits!(CommitLightingRuntimeConditionalSceneReplaceRequest, LightingStateResult);
     assert_endpoint_fits!(AbortLightingRuntimeConditionalSceneReplaceRequest, LightingUnitResult);
     assert_endpoint_fits!(SetLightingSceneCellRequest, LightingStateResult);
@@ -1366,6 +1457,57 @@ mod tests {
         assert!(LightingConditionalScenesPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
     }
 
+    #[test]
+    fn extended_conditional_scene_types_round_trip_at_capacity() {
+        let base = LightingConditionalSceneCell {
+            conditions: LightingConditionSet {
+                layer: Some(LightingLayerCondition { layer: 2, active: true }),
+                battery: Some(LightingBatteryCondition {
+                    node: LightingNodeId(1),
+                    min_level: Some(20),
+                    max_level: Some(80),
+                    charge: LightingChargeCondition::Discharging,
+                }),
+                output_mode: Some(LightingOutputMode::PoweredOnly),
+            },
+            led_id: LightingLedId(42),
+            effect: LightingEffect::Solid {
+                color: LightingRgb8 { r: 7, g: 8, b: 9 },
+            },
+        };
+        let cell = LightingExtendedConditionalSceneCell {
+            cell: base,
+            connection: Some(LightingConnectionCondition {
+                transport: Some(LightingActiveTransport::Ble),
+                profile: Some(3),
+                ble_state: Some(BleState::Connected),
+            }),
+        };
+        round_trip(&cell);
+
+        let mut cells = Vec::new();
+        for _ in 0..LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE {
+            cells.push(cell).unwrap();
+        }
+        let page = LightingExtendedRuntimeConditionalScenesPage {
+            revision: u32::MAX,
+            total_count: u16::MAX,
+            items: cells.clone(),
+        };
+        round_trip(&page);
+        assert_max_size_bound(&page);
+        assert!(LightingExtendedRuntimeConditionalScenesPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+
+        let request = PutLightingExtendedRuntimeConditionalSceneChunkRequest {
+            transaction_id: u32::MAX,
+            offset: u16::MAX,
+            cells,
+        };
+        round_trip(&request);
+        assert_max_size_bound(&request);
+        assert!(PutLightingExtendedRuntimeConditionalSceneChunkRequest::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+    }
+
     #[test]
     fn extension_types_round_trip() {
         round_trip(&LightingExtensionState {
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index 3a3ea9d84..10612fc20 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -5,98 +5,110 @@
 #   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk --features lighting lighting_wire_frames
 # Format: <label>  <hex bytes>
 
-AbortLightingOverlayReplace reply                      04 10 09 01 01 01 00
-AbortLightingOverlayReplace request                    05 10 09 01 0d 00
-AbortLightingRuntimeConditionalSceneReplace reply      04 2a 09 01 01 01 00
-AbortLightingRuntimeConditionalSceneReplace request    05 2a 09 01 1f 00
-AbortLightingSceneReplace reply                        04 19 09 01 01 01 00
-AbortLightingSceneReplace request                      05 19 09 01 15 00
-BeginLightingOverlayReplace reply                      04 0d 09 01 01 03 0d 01 00
-BeginLightingOverlayReplace request                    06 0d 09 01 0c 01 00
-BeginLightingRuntimeConditionalSceneReplace reply      04 27 09 01 01 03 1f 01 00
-BeginLightingRuntimeConditionalSceneReplace request    06 27 09 01 09 01 00
-BeginLightingSceneReplace reply                        04 16 09 01 01 03 15 01 00
-BeginLightingSceneReplace request                      06 16 09 01 0c 01 00
-ClearLightingOverlay reply                             04 0c 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-ClearLightingOverlay request                           05 0c 09 01 0b 00
-CommitLightingOverlayReplace reply                     04 0f 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-CommitLightingOverlayReplace request                   05 0f 09 01 0d 00
-CommitLightingRuntimeConditionalSceneReplace reply     04 29 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-CommitLightingRuntimeConditionalSceneReplace request   05 29 09 01 1f 00
-CommitLightingSceneReplace reply                       04 18 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-CommitLightingSceneReplace request                     05 18 09 01 15 00
-GetLightingCapabilities reply                          04 01 09 01 01 0f 01 02 03 04 05 06 07 08 09 08 08 bf 2b 07 00
-GetLightingCapabilities request                        04 01 09 01 00
-GetLightingCompiledSceneStatus reply                   04 1c 09 01 01 03 01 01 02 08 00
-GetLightingCompiledSceneStatus request                 04 1c 09 01 00
-GetLightingCompiledScenes reply                        04 1d 09 01 01 06 01 01 01 02 2a 04 07 08 09 00
-GetLightingCompiledScenes request                      05 1d 09 01 01 01 00
-GetLightingExtension inner Err(Unsupported)            04 21 09 01 02 01 01 00
-GetLightingExtension reply                             04 21 09 01 01 08 09 06 10 01 02 03 04 00
-GetLightingExtension request                           04 21 09 01 00
-GetLightingExtensionLayers reply                       04 2e 09 01 01 04 09 01 05 00
-GetLightingExtensionLayers request                     04 2e 09 01 00
-GetLightingExtensionNames reply                        04 22 09 01 01 09 10 01 05 4f 63 65 61 6e 00
-GetLightingExtensionNames request                      06 22 09 01 01 08 00
-GetLightingExtensionParams reply                       04 2b 09 01 01 10 09 02 01 07 44 65 6e 73 69 74 79 01 08 03 05 00
-GetLightingExtensionParams request                     05 2b 09 01 01 01 00
-GetLightingKeys reply                                  04 11 09 01 01 06 01 01 01 01 02 00
-GetLightingKeys request                                05 11 09 01 01 01 00
-GetLightingLeds reply                                  04 05 09 01 01 11 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01 00
-GetLightingLeds request                                05 05 09 01 01 01 00
-GetLightingOutputMode reply                            04 20 09 01 01 03 02 01 08 01 01 01 0d 04 01 2a 01 02 09 01 02 09 01 01 01 01 02 09 00
-GetLightingOutputMode request                          04 20 09 01 00
-GetLightingOutputs reply                               04 08 09 01 01 08 01 01 01 01 02 28 14 01 00
-GetLightingOutputs request                             05 08 09 01 01 01 00
-GetLightingOverlay reply                               04 1b 09 01 01 11 09 01 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
-GetLightingOverlay request                             05 1b 09 01 09 01 00
-GetLightingPhysicalKeys reply                          04 04 09 01 01 12 01 01 01 01 02 ff 01 80 04 80 01 80 02 80 03 db 0b 00
-GetLightingPhysicalKeys request                        05 04 09 01 01 01 00
-GetLightingRoutes reply                                04 09 09 01 01 08 01 01 01 2a 01 02 07 00
-GetLightingRoutes request                              05 09 09 01 01 01 00
-GetLightingRuntimeConditionalSceneStatus reply         04 25 09 01 01 05 09 40 01 07 00
-GetLightingRuntimeConditionalSceneStatus request       04 25 09 01 00
-GetLightingRuntimeConditionalScenes reply              04 26 09 01 01 0e 09 01 01 01 02 01 01 01 01 14 01 50 02 02 2a 04 07 08 09 00
-GetLightingRuntimeConditionalScenes request            05 26 09 01 09 01 00
-GetLightingSceneStatus reply                           04 12 09 01 01 07 09 80 02 01 01 08 00
-GetLightingSceneStatus request                         04 12 09 01 00
-GetLightingScenes reply                                04 13 09 01 01 06 09 01 01 02 2a 04 07 08 09 00
-GetLightingScenes request                              05 13 09 01 09 01 00
-GetLightingState reply                                 04 02 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-GetLightingState request                               04 02 09 01 00
-GetLightingZoneMemberships reply                       04 07 09 01 01 05 01 01 01 04 00
-GetLightingZoneMemberships request                     05 07 09 01 01 01 00
-GetLightingZones reply                                 04 06 09 01 01 0b 01 01 01 04 05 74 68 75 6d 62 00
-GetLightingZones request                               05 06 09 01 01 01 00
-LightingChange topic                                   03 07 80 01 00
-PutLightingOverlayChunk inner Err(TransactionExpired)  04 0e 09 01 03 01 0a 00
-PutLightingOverlayChunk reply                          04 0e 09 01 01 01 00
-PutLightingOverlayChunk request                        05 0e 09 01 0d 0f 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
-PutLightingRuntimeConditionalSceneChunk reply          04 28 09 01 01 01 00
-PutLightingRuntimeConditionalSceneChunk request        05 28 09 01 1f 0c 01 01 02 01 01 01 01 14 01 50 02 02 2a 04 07 08 09 00
-PutLightingSceneChunk reply                            04 17 09 01 01 01 00
-PutLightingSceneChunk request                          05 17 09 01 15 04 01 02 2a 04 07 08 09 00
-SetLightingExtensionLayers reply                       04 2f 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-SetLightingExtensionLayers request                     07 2f 09 01 09 01 05 00
-SetLightingExtensionParam reply                        04 2c 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-SetLightingExtensionParam request                      06 2c 09 01 09 01 02 05 00
-SetLightingExtensionState reply                        04 23 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-SetLightingExtensionState request                      09 23 09 01 09 01 02 03 04 00
-SetLightingLayerPolicy reply                           04 1a 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-SetLightingLayerPolicy request                         05 1a 09 01 0b 01 00
-SetLightingOutputMode reply                            04 24 09 01 01 03 02 01 08 01 01 01 0d 04 01 2a 01 02 09 01 02 09 01 01 01 01 02 09 00
-SetLightingOutputMode request                          06 24 09 01 09 01 00
-SetLightingOverlay inner Err(UnknownLed)               04 0a 09 01 05 01 06 e7 07 00
-SetLightingOverlay outer Err(Locked)                   06 0a 09 01 01 07 00
-SetLightingOverlay reply                               04 0a 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-SetLightingOverlay request                             12 0a 09 01 09 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
-SetLightingSceneCell inner Err(SceneFull)              04 14 09 01 05 01 0d 80 02 00
-SetLightingSceneCell inner Err(UnknownLayer)           04 14 09 01 04 01 0c c8 00
-SetLightingSceneCell reply                             04 14 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-SetLightingSceneCell request                           07 14 09 01 09 02 2a 04 07 08 09 00
-SetLightingState reply                                 04 03 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-SetLightingState request                               0d 03 09 01 08 01 c8 01 0a 14 1e 28 01 00
-UnsetLightingOverlay reply                             04 0b 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-UnsetLightingOverlay request                           06 0b 09 01 0a 2a 00
-UnsetLightingSceneCell reply                           04 15 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
-UnsetLightingSceneCell request                         07 15 09 01 0a 02 2a 00
+AbortLightingExtendedRuntimeConditionalSceneReplace reply     04 35 09 01 01 01 00
+AbortLightingExtendedRuntimeConditionalSceneReplace request   05 35 09 01 1f 00
+AbortLightingOverlayReplace reply                             04 10 09 01 01 01 00
+AbortLightingOverlayReplace request                           05 10 09 01 0d 00
+AbortLightingRuntimeConditionalSceneReplace reply             04 2a 09 01 01 01 00
+AbortLightingRuntimeConditionalSceneReplace request           05 2a 09 01 1f 00
+AbortLightingSceneReplace reply                               04 19 09 01 01 01 00
+AbortLightingSceneReplace request                             05 19 09 01 15 00
+BeginLightingExtendedRuntimeConditionalSceneReplace reply     04 32 09 01 01 03 1f 01 00
+BeginLightingExtendedRuntimeConditionalSceneReplace request   06 32 09 01 09 01 00
+BeginLightingOverlayReplace reply                             04 0d 09 01 01 03 0d 01 00
+BeginLightingOverlayReplace request                           06 0d 09 01 0c 01 00
+BeginLightingRuntimeConditionalSceneReplace reply             04 27 09 01 01 03 1f 01 00
+BeginLightingRuntimeConditionalSceneReplace request           06 27 09 01 09 01 00
+BeginLightingSceneReplace reply                               04 16 09 01 01 03 15 01 00
+BeginLightingSceneReplace request                             06 16 09 01 0c 01 00
+ClearLightingOverlay reply                                    04 0c 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+ClearLightingOverlay request                                  05 0c 09 01 0b 00
+CommitLightingExtendedRuntimeConditionalSceneReplace reply    04 34 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+CommitLightingExtendedRuntimeConditionalSceneReplace request  05 34 09 01 1f 00
+CommitLightingOverlayReplace reply                            04 0f 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+CommitLightingOverlayReplace request                          05 0f 09 01 0d 00
+CommitLightingRuntimeConditionalSceneReplace reply            04 29 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+CommitLightingRuntimeConditionalSceneReplace request          05 29 09 01 1f 00
+CommitLightingSceneReplace reply                              04 18 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+CommitLightingSceneReplace request                            05 18 09 01 15 00
+GetLightingCapabilities reply                                 04 01 09 01 01 10 01 02 03 04 05 06 07 08 09 08 08 bf ab 01 07 00
+GetLightingCapabilities request                               04 01 09 01 00
+GetLightingCompiledSceneStatus reply                          04 1c 09 01 01 03 01 01 02 08 00
+GetLightingCompiledSceneStatus request                        04 1c 09 01 00
+GetLightingCompiledScenes reply                               04 1d 09 01 01 06 01 01 01 02 2a 04 07 08 09 00
+GetLightingCompiledScenes request                             05 1d 09 01 01 01 00
+GetLightingExtendedRuntimeConditionalSceneStatus reply        04 30 09 01 01 05 09 40 01 06 00
+GetLightingExtendedRuntimeConditionalSceneStatus request      04 30 09 01 00
+GetLightingExtendedRuntimeConditionalScenes reply             04 31 09 01 01 0e 09 01 01 01 02 01 01 01 01 14 01 50 02 02 2a 0b 07 08 09 01 01 01 01 03 01 01 00
+GetLightingExtendedRuntimeConditionalScenes request           05 31 09 01 09 01 00
+GetLightingExtension inner Err(Unsupported)                   04 21 09 01 02 01 01 00
+GetLightingExtension reply                                    04 21 09 01 01 08 09 06 10 01 02 03 04 00
+GetLightingExtension request                                  04 21 09 01 00
+GetLightingExtensionLayers reply                              04 2e 09 01 01 04 09 01 05 00
+GetLightingExtensionLayers request                            04 2e 09 01 00
+GetLightingExtensionNames reply                               04 22 09 01 01 09 10 01 05 4f 63 65 61 6e 00
+GetLightingExtensionNames request                             06 22 09 01 01 08 00
+GetLightingExtensionParams reply                              04 2b 09 01 01 10 09 02 01 07 44 65 6e 73 69 74 79 01 08 03 05 00
+GetLightingExtensionParams request                            05 2b 09 01 01 01 00
+GetLightingKeys reply                                         04 11 09 01 01 06 01 01 01 01 02 00
+GetLightingKeys request                                       05 11 09 01 01 01 00
+GetLightingLeds reply                                         04 05 09 01 01 11 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01 00
+GetLightingLeds request                                       05 05 09 01 01 01 00
+GetLightingOutputMode reply                                   04 20 09 01 01 03 02 01 08 01 01 01 0d 04 01 2a 01 02 09 01 02 09 01 01 01 01 02 09 00
+GetLightingOutputMode request                                 04 20 09 01 00
+GetLightingOutputs reply                                      04 08 09 01 01 08 01 01 01 01 02 28 14 01 00
+GetLightingOutputs request                                    05 08 09 01 01 01 00
+GetLightingOverlay reply                                      04 1b 09 01 01 11 09 01 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
+GetLightingOverlay request                                    05 1b 09 01 09 01 00
+GetLightingPhysicalKeys reply                                 04 04 09 01 01 12 01 01 01 01 02 ff 01 80 04 80 01 80 02 80 03 db 0b 00
+GetLightingPhysicalKeys request                               05 04 09 01 01 01 00
+GetLightingRoutes reply                                       04 09 09 01 01 08 01 01 01 2a 01 02 07 00
+GetLightingRoutes request                                     05 09 09 01 01 01 00
+GetLightingRuntimeConditionalSceneStatus reply                04 25 09 01 01 05 09 40 01 07 00
+GetLightingRuntimeConditionalSceneStatus request              04 25 09 01 00
+GetLightingRuntimeConditionalScenes reply                     04 26 09 01 01 0e 09 01 01 01 02 01 01 01 01 14 01 50 02 02 2a 04 07 08 09 00
+GetLightingRuntimeConditionalScenes request                   05 26 09 01 09 01 00
+GetLightingSceneStatus reply                                  04 12 09 01 01 07 09 80 02 01 01 08 00
+GetLightingSceneStatus request                                04 12 09 01 00
+GetLightingScenes reply                                       04 13 09 01 01 06 09 01 01 02 2a 04 07 08 09 00
+GetLightingScenes request                                     05 13 09 01 09 01 00
+GetLightingState reply                                        04 02 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+GetLightingState request                                      04 02 09 01 00
+GetLightingZoneMemberships reply                              04 07 09 01 01 05 01 01 01 04 00
+GetLightingZoneMemberships request                            05 07 09 01 01 01 00
+GetLightingZones reply                                        04 06 09 01 01 0b 01 01 01 04 05 74 68 75 6d 62 00
+GetLightingZones request                                      05 06 09 01 01 01 00
+LightingChange topic                                          03 07 80 01 00
+PutLightingExtendedRuntimeConditionalSceneChunk reply         04 33 09 01 01 01 00
+PutLightingExtendedRuntimeConditionalSceneChunk request       05 33 09 01 1f 0c 01 01 02 01 01 01 01 14 01 50 02 02 2a 0b 07 08 09 01 01 01 01 03 01 01 00
+PutLightingOverlayChunk inner Err(TransactionExpired)         04 0e 09 01 03 01 0a 00
+PutLightingOverlayChunk reply                                 04 0e 09 01 01 01 00
+PutLightingOverlayChunk request                               05 0e 09 01 0d 0f 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
+PutLightingRuntimeConditionalSceneChunk reply                 04 28 09 01 01 01 00
+PutLightingRuntimeConditionalSceneChunk request               05 28 09 01 1f 0c 01 01 02 01 01 01 01 14 01 50 02 02 2a 04 07 08 09 00
+PutLightingSceneChunk reply                                   04 17 09 01 01 01 00
+PutLightingSceneChunk request                                 05 17 09 01 15 04 01 02 2a 04 07 08 09 00
+SetLightingExtensionLayers reply                              04 2f 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingExtensionLayers request                            07 2f 09 01 09 01 05 00
+SetLightingExtensionParam reply                               04 2c 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingExtensionParam request                             06 2c 09 01 09 01 02 05 00
+SetLightingExtensionState reply                               04 23 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingExtensionState request                             09 23 09 01 09 01 02 03 04 00
+SetLightingLayerPolicy reply                                  04 1a 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingLayerPolicy request                                05 1a 09 01 0b 01 00
+SetLightingOutputMode reply                                   04 24 09 01 01 03 02 01 08 01 01 01 0d 04 01 2a 01 02 09 01 02 09 01 01 01 01 02 09 00
+SetLightingOutputMode request                                 06 24 09 01 09 01 00
+SetLightingOverlay inner Err(UnknownLed)                      04 0a 09 01 05 01 06 e7 07 00
+SetLightingOverlay outer Err(Locked)                          06 0a 09 01 01 07 00
+SetLightingOverlay reply                                      04 0a 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingOverlay request                                    12 0a 09 01 09 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
+SetLightingSceneCell inner Err(SceneFull)                     04 14 09 01 05 01 0d 80 02 00
+SetLightingSceneCell inner Err(UnknownLayer)                  04 14 09 01 04 01 0c c8 00
+SetLightingSceneCell reply                                    04 14 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingSceneCell request                                  07 14 09 01 09 02 2a 04 07 08 09 00
+SetLightingState reply                                        04 03 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+SetLightingState request                                      0d 03 09 01 08 01 c8 01 0a 14 1e 28 01 00
+UnsetLightingOverlay reply                                    04 0b 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+UnsetLightingOverlay request                                  06 0b 09 01 0a 2a 00
+UnsetLightingSceneCell reply                                  04 15 09 01 01 0b 09 01 c8 01 0a 14 1e 28 01 01 00
+UnsetLightingSceneCell request                                07 15 09 01 0a 02 2a 00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index c964550e1..075ec423a 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1141,7 +1141,8 @@ fn lighting_wire_frames_locked() {
                 | LightingFeatureFlags::OVERLAY_READBACK
                 | LightingFeatureFlags::COMPILED_LAYER_SCENES
                 | LightingFeatureFlags::OUTPUT_MODE
-                | LightingFeatureFlags::RUNTIME_CONDITIONAL_SCENES,
+                | LightingFeatureFlags::RUNTIME_CONDITIONAL_SCENES
+                | LightingFeatureFlags::RUNTIME_CONNECTION_CONDITIONS,
         ),
         effects: LightingEffectFlags(
             LightingEffectFlags::SOLID | LightingEffectFlags::BLINK | LightingEffectFlags::BREATHE,
@@ -1436,6 +1437,28 @@ fn lighting_wire_frames_locked() {
     let runtime_conditional_abort = AbortLightingRuntimeConditionalSceneReplaceRequest {
         transaction_id: runtime_conditional_transaction.id,
     };
+    let extended_runtime_conditional_status = LightingRuntimeConditionalSceneStatus {
+        chunk_capacity: LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE as u8,
+        ..runtime_conditional_status
+    };
+    let extended_conditional_cell = LightingExtendedConditionalSceneCell {
+        cell: conditional_cell,
+        connection: Some(LightingConnectionCondition {
+            transport: Some(LightingActiveTransport::Ble),
+            profile: Some(3),
+            ble_state: Some(BleState::Connected),
+        }),
+    };
+    let extended_runtime_conditional_page = LightingExtendedRuntimeConditionalScenesPage {
+        revision: state.revision,
+        total_count: 1,
+        items: one(extended_conditional_cell),
+    };
+    let extended_runtime_conditional_put = PutLightingExtendedRuntimeConditionalSceneChunkRequest {
+        transaction_id: runtime_conditional_transaction.id,
+        offset: 0,
+        cells: one(extended_conditional_cell),
+    };
 
     let entries: alloc::vec::Vec<(&str, alloc::vec::Vec<u8>)> = alloc::vec![
         (
@@ -1590,6 +1613,100 @@ fn lighting_wire_frames_locked() {
                 &Ok::<LightingUnitResult, RynkError>(Ok(()))
             )
         ),
+        (
+            "GetLightingExtendedRuntimeConditionalSceneStatus request",
+            encode_frame(Cmd::GetLightingExtendedRuntimeConditionalSceneStatus, SEQ, &())
+        ),
+        (
+            "GetLightingExtendedRuntimeConditionalSceneStatus reply",
+            encode_frame(
+                Cmd::GetLightingExtendedRuntimeConditionalSceneStatus,
+                SEQ,
+                &Ok::<LightingRuntimeConditionalSceneStatusResult, RynkError>(Ok(extended_runtime_conditional_status))
+            )
+        ),
+        (
+            "GetLightingExtendedRuntimeConditionalScenes request",
+            encode_frame(
+                Cmd::GetLightingExtendedRuntimeConditionalScenes,
+                SEQ,
+                &runtime_conditional_page_request
+            )
+        ),
+        (
+            "GetLightingExtendedRuntimeConditionalScenes reply",
+            encode_frame(
+                Cmd::GetLightingExtendedRuntimeConditionalScenes,
+                SEQ,
+                &Ok::<LightingExtendedRuntimeConditionalScenesPageResult, RynkError>(Ok(
+                    extended_runtime_conditional_page
+                ))
+            )
+        ),
+        (
+            "BeginLightingExtendedRuntimeConditionalSceneReplace request",
+            encode_frame(
+                Cmd::BeginLightingExtendedRuntimeConditionalSceneReplace,
+                SEQ,
+                &runtime_conditional_begin
+            )
+        ),
+        (
+            "BeginLightingExtendedRuntimeConditionalSceneReplace reply",
+            encode_frame(
+                Cmd::BeginLightingExtendedRuntimeConditionalSceneReplace,
+                SEQ,
+                &Ok::<LightingRuntimeConditionalSceneTransactionResult, RynkError>(Ok(runtime_conditional_transaction))
+            )
+        ),
+        (
+            "PutLightingExtendedRuntimeConditionalSceneChunk request",
+            encode_frame(
+                Cmd::PutLightingExtendedRuntimeConditionalSceneChunk,
+                SEQ,
+                &extended_runtime_conditional_put
+            )
+        ),
+        (
+            "PutLightingExtendedRuntimeConditionalSceneChunk reply",
+            encode_frame(
+                Cmd::PutLightingExtendedRuntimeConditionalSceneChunk,
+                SEQ,
+                &Ok::<LightingUnitResult, RynkError>(Ok(()))
+            )
+        ),
+        (
+            "CommitLightingExtendedRuntimeConditionalSceneReplace request",
+            encode_frame(
+                Cmd::CommitLightingExtendedRuntimeConditionalSceneReplace,
+                SEQ,
+                &runtime_conditional_commit
+            )
+        ),
+        (
+            "CommitLightingExtendedRuntimeConditionalSceneReplace reply",
+            encode_frame(
+                Cmd::CommitLightingExtendedRuntimeConditionalSceneReplace,
+                SEQ,
+                &Ok::<LightingStateResult, RynkError>(Ok(state))
+            )
+        ),
+        (
+            "AbortLightingExtendedRuntimeConditionalSceneReplace request",
+            encode_frame(
+                Cmd::AbortLightingExtendedRuntimeConditionalSceneReplace,
+                SEQ,
+                &runtime_conditional_abort
+            )
+        ),
+        (
+            "AbortLightingExtendedRuntimeConditionalSceneReplace reply",
+            encode_frame(
+                Cmd::AbortLightingExtendedRuntimeConditionalSceneReplace,
+                SEQ,
+                &Ok::<LightingUnitResult, RynkError>(Ok(()))
+            )
+        ),
         (
             "GetLightingPhysicalKeys request",
             encode_frame(Cmd::GetLightingPhysicalKeys, SEQ, &page_request)
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index bc9151a4c..6222bee20 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -3,13 +3,17 @@
 use embassy_time::Instant;
 use heapless::{String, Vec};
 use rmk_types::protocol::rynk::command::{
-    AbortLightingRuntimeConditionalSceneReplace, BeginLightingRuntimeConditionalSceneReplace, ClearLightingOverlay,
+    AbortLightingExtendedRuntimeConditionalSceneReplace, AbortLightingRuntimeConditionalSceneReplace,
+    BeginLightingExtendedRuntimeConditionalSceneReplace, BeginLightingRuntimeConditionalSceneReplace,
+    ClearLightingOverlay, CommitLightingExtendedRuntimeConditionalSceneReplace,
     CommitLightingRuntimeConditionalSceneReplace, GetLightingCapabilities, GetLightingCompiledSceneStatus,
-    GetLightingCompiledScenes, GetLightingConditionalSceneStatus, GetLightingConditionalScenes, GetLightingExtension,
-    GetLightingExtensionLayers, GetLightingExtensionNames, GetLightingExtensionParams, GetLightingKeys,
-    GetLightingLeds, GetLightingOutputMode, GetLightingOutputs, GetLightingOverlay, GetLightingPhysicalKeys,
-    GetLightingRoutes, GetLightingRuntimeConditionalSceneStatus, GetLightingRuntimeConditionalScenes,
-    GetLightingSceneStatus, GetLightingScenes, GetLightingState, GetLightingZoneMemberships, GetLightingZones,
+    GetLightingCompiledScenes, GetLightingConditionalSceneStatus, GetLightingConditionalScenes,
+    GetLightingExtendedRuntimeConditionalSceneStatus, GetLightingExtendedRuntimeConditionalScenes,
+    GetLightingExtension, GetLightingExtensionLayers, GetLightingExtensionNames, GetLightingExtensionParams,
+    GetLightingKeys, GetLightingLeds, GetLightingOutputMode, GetLightingOutputs, GetLightingOverlay,
+    GetLightingPhysicalKeys, GetLightingRoutes, GetLightingRuntimeConditionalSceneStatus,
+    GetLightingRuntimeConditionalScenes, GetLightingSceneStatus, GetLightingScenes, GetLightingState,
+    GetLightingZoneMemberships, GetLightingZones, PutLightingExtendedRuntimeConditionalSceneChunk,
     PutLightingRuntimeConditionalSceneChunk, SetLightingExtensionLayers, SetLightingExtensionParam,
     SetLightingExtensionState, SetLightingLayerPolicy, SetLightingOutputMode, SetLightingOverlay, SetLightingSceneCell,
     SetLightingState, SetLightingWakeLayers, UnsetLightingOverlay, UnsetLightingSceneCell,
@@ -19,14 +23,16 @@ use rmk_types::protocol::rynk::{
     AbortLightingSceneReplaceRequest, BeginLightingOverlayReplaceRequest,
     BeginLightingRuntimeConditionalSceneReplaceRequest, BeginLightingSceneReplaceRequest, ClearLightingOverlayRequest,
     CommitLightingOverlayReplaceRequest, CommitLightingRuntimeConditionalSceneReplaceRequest,
-    CommitLightingSceneReplaceRequest, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE, LIGHTING_PAGE_SIZE,
-    LIGHTING_SCENE_CHUNK_SIZE, LIGHTING_ZONE_NAME_SIZE, LightingCapabilities, LightingCapabilitiesResult,
-    LightingCompiledSceneStatus, LightingCompiledSceneStatusResult, LightingCompiledScenesPageResult,
-    LightingConditionalSceneCell, LightingConditionalSceneStatus, LightingConditionalSceneStatusResult,
-    LightingConditionalScenesPage, LightingConditionalScenesPageResult, LightingEffectFlags, LightingError,
-    LightingExtensionLayersResult, LightingExtensionNamesPageResult, LightingExtensionNamesRequest,
-    LightingExtensionParamsPageResult, LightingExtensionParamsRequest, LightingExtensionResult, LightingFeatureFlags,
-    LightingKeysPage, LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
+    CommitLightingSceneReplaceRequest, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE,
+    LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE, LIGHTING_PAGE_SIZE, LIGHTING_SCENE_CHUNK_SIZE,
+    LIGHTING_ZONE_NAME_SIZE, LightingCapabilities, LightingCapabilitiesResult, LightingCompiledSceneStatus,
+    LightingCompiledSceneStatusResult, LightingCompiledScenesPageResult, LightingConditionalSceneCell,
+    LightingConditionalSceneStatus, LightingConditionalSceneStatusResult, LightingConditionalScenesPage,
+    LightingConditionalScenesPageResult, LightingEffectFlags, LightingError,
+    LightingExtendedRuntimeConditionalScenesPageResult, LightingExtensionLayersResult,
+    LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionParamsPageResult,
+    LightingExtensionParamsRequest, LightingExtensionResult, LightingFeatureFlags, LightingKeysPage,
+    LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
     LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage,
     LightingOutputModeStateResult, LightingOutputsPage, LightingOutputsPageResult, LightingOverlayCell,
     LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransaction,
@@ -37,7 +43,8 @@ use rmk_types::protocol::rynk::{
     LightingRuntimeConditionalScenesPageResult, LightingScenePageRequest, LightingSceneStatus,
     LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult, LightingState,
     LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage,
-    LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult, PutLightingOverlayChunkRequest,
+    LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult,
+    PutLightingExtendedRuntimeConditionalSceneChunkRequest, PutLightingOverlayChunkRequest,
     PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, RynkError, RynkMessage,
     SetLightingExtensionLayersRequest, SetLightingExtensionParamRequest, SetLightingExtensionStateRequest,
     SetLightingLayerPolicyRequest, SetLightingOutputModeRequest, SetLightingOverlayRequest,
@@ -412,6 +419,29 @@ impl Handle<GetLightingRuntimeConditionalSceneStatus> for RynkService<'_> {
     }
 }
 
+impl Handle<GetLightingExtendedRuntimeConditionalSceneStatus> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LightingRuntimeConditionalSceneStatusResult, RynkError> {
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::ReadRuntimeConditionalSceneStatus)
+                .await
+            {
+                Ok(RynkLightingReadback::RuntimeConditionalSceneStatus { revision, cell_len }) => {
+                    Ok(LightingRuntimeConditionalSceneStatus {
+                        revision,
+                        capacity: controller.runtime_conditional_scene_capacity,
+                        cell_len,
+                        chunk_capacity: LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE as u8,
+                    })
+                }
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        })
+    }
+}
+
 impl Handle<GetLightingRuntimeConditionalScenes> for RynkService<'_> {
     async fn handle(
         &self,
@@ -434,6 +464,28 @@ impl Handle<GetLightingRuntimeConditionalScenes> for RynkService<'_> {
     }
 }
 
+impl Handle<GetLightingExtendedRuntimeConditionalScenes> for RynkService<'_> {
+    async fn handle(
+        &self,
+        req: LightingRuntimeConditionalScenePageRequest,
+    ) -> Result<LightingExtendedRuntimeConditionalScenesPageResult, RynkError> {
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::ReadExtendedRuntimeConditionalScenes {
+                    expected_revision: req.revision,
+                    offset: req.offset,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::ExtendedRuntimeConditionalScenesPage(page)) => Ok(page),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        })
+    }
+}
+
 impl Handle<BeginLightingRuntimeConditionalSceneReplace> for RynkService<'_> {
     async fn handle(
         &self,
@@ -461,6 +513,33 @@ impl Handle<BeginLightingRuntimeConditionalSceneReplace> for RynkService<'_> {
     }
 }
 
+impl Handle<BeginLightingExtendedRuntimeConditionalSceneReplace> for RynkService<'_> {
+    async fn handle(
+        &self,
+        req: BeginLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<LightingRuntimeConditionalSceneTransactionResult, RynkError> {
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) if req.cell_count > controller.runtime_conditional_scene_capacity => {
+                Err(LightingError::ConditionalSceneFull {
+                    capacity: controller.runtime_conditional_scene_capacity,
+                })
+            }
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::BeginRuntimeConditionalSceneReplace {
+                    expected_revision: req.expected_revision,
+                    cell_count: req.cell_count,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::RuntimeConditionalSceneTransaction(transaction)) => Ok(transaction),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        })
+    }
+}
+
 impl Handle<PutLightingRuntimeConditionalSceneChunk> for RynkService<'_> {
     async fn handle(
         &self,
@@ -505,6 +584,50 @@ impl Handle<PutLightingRuntimeConditionalSceneChunk> for RynkService<'_> {
     }
 }
 
+impl Handle<PutLightingExtendedRuntimeConditionalSceneChunk> for RynkService<'_> {
+    async fn handle(
+        &self,
+        req: PutLightingExtendedRuntimeConditionalSceneChunkRequest,
+    ) -> Result<LightingUnitResult, RynkError> {
+        for cell in &req.cells {
+            if let Err(error) = cell.validate() {
+                return Ok(Err(error));
+            }
+            if let Some(layer) = cell.cell.conditions.layer
+                && let Err(error) = self.check_scene_layer(layer.layer)
+            {
+                return Ok(Err(error));
+            }
+            if let Some(battery) = cell.cell.conditions.battery
+                && let Ok(controller) = controller(self)
+                && !controller
+                    .descriptor
+                    .routing
+                    .outputs
+                    .iter()
+                    .any(|output| output.node.0 == battery.node.0)
+            {
+                return Ok(Err(LightingError::InvalidRequest));
+            }
+        }
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::PutExtendedRuntimeConditionalSceneChunk {
+                    transaction_id: req.transaction_id,
+                    offset: req.offset,
+                    cells: req.cells,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::Unit) => Ok(()),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        })
+    }
+}
+
 impl Handle<CommitLightingRuntimeConditionalSceneReplace> for RynkService<'_> {
     async fn handle(
         &self,
@@ -523,6 +646,24 @@ impl Handle<CommitLightingRuntimeConditionalSceneReplace> for RynkService<'_> {
     }
 }
 
+impl Handle<CommitLightingExtendedRuntimeConditionalSceneReplace> for RynkService<'_> {
+    async fn handle(
+        &self,
+        req: CommitLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<LightingStateResult, RynkError> {
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) => {
+                controller
+                    .request_state(RynkLightingCommand::CommitRuntimeConditionalSceneReplace {
+                        transaction_id: req.transaction_id,
+                    })
+                    .await
+            }
+            Err(error) => Err(error),
+        })
+    }
+}
+
 impl Handle<AbortLightingRuntimeConditionalSceneReplace> for RynkService<'_> {
     async fn handle(
         &self,
@@ -544,6 +685,27 @@ impl Handle<AbortLightingRuntimeConditionalSceneReplace> for RynkService<'_> {
     }
 }
 
+impl Handle<AbortLightingExtendedRuntimeConditionalSceneReplace> for RynkService<'_> {
+    async fn handle(
+        &self,
+        req: AbortLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<LightingUnitResult, RynkError> {
+        Ok(match runtime_conditional_scene_controller(self) {
+            Ok(controller) => match controller
+                .request(RynkLightingCommand::AbortRuntimeConditionalSceneReplace {
+                    transaction_id: req.transaction_id,
+                })
+                .await
+            {
+                Ok(RynkLightingReadback::Unit) => Ok(()),
+                Ok(_) => Err(LightingError::InvalidRequest),
+                Err(error) => Err(error),
+            },
+            Err(error) => Err(error),
+        })
+    }
+}
+
 impl Handle<SetLightingSceneCell> for RynkService<'_> {
     async fn handle(&self, req: SetLightingSceneCellRequest) -> Result<LightingStateResult, RynkError> {
         if let Err(error) = req
@@ -888,7 +1050,8 @@ fn capabilities(binding: RynkLightingController<'_>) -> LightingCapabilities {
         features.0 |= LightingFeatureFlags::COMPILED_CONDITIONAL_SCENES;
     }
     if binding.runtime_conditional_scene_capacity > 0 {
-        features.0 |= LightingFeatureFlags::RUNTIME_CONDITIONAL_SCENES;
+        features.0 |=
+            LightingFeatureFlags::RUNTIME_CONDITIONAL_SCENES | LightingFeatureFlags::RUNTIME_CONNECTION_CONDITIONS;
     }
     // The standard engine always owns an output-mode policy, so this advertises
     // the engine's support rather than whether a board happened to bind a key to
@@ -2024,6 +2187,11 @@ mod tests {
                     .features
                     .contains(LightingFeatureFlags::RUNTIME_CONDITIONAL_SCENES)
             );
+            assert!(
+                lighting
+                    .features
+                    .contains(LightingFeatureFlags::RUNTIME_CONNECTION_CONDITIONS)
+            );
 
             let client = async {
                 let compiled_status = call::<GetLightingCompiledSceneStatus>(&service, &session, &())
@@ -2332,6 +2500,15 @@ mod tests {
                 assert_eq!(runtime_status.revision, 5);
                 assert_eq!(runtime_status.capacity, 4);
                 assert_eq!(runtime_status.cell_len, 0);
+                let extended_status = call::<GetLightingExtendedRuntimeConditionalSceneStatus>(&service, &session, &())
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(extended_status.revision, runtime_status.revision);
+                assert_eq!(
+                    extended_status.chunk_capacity as usize,
+                    LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE
+                );
                 let transaction = call::<BeginLightingRuntimeConditionalSceneReplace>(
                     &service,
                     &session,
@@ -2388,12 +2565,94 @@ mod tests {
                 .unwrap()
                 .unwrap();
                 assert_eq!(runtime_page.items.as_slice(), &[conditional_cell]);
+                let extended_page = call::<GetLightingExtendedRuntimeConditionalScenes>(
+                    &service,
+                    &session,
+                    &LightingRuntimeConditionalScenePageRequest { revision: 6, offset: 0 },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(extended_page.items.len(), 1);
+                assert_eq!(extended_page.items[0].cell, conditional_cell);
+                assert_eq!(
+                    extended_page.items[0].connection, None,
+                    "legacy writes install no connection predicate"
+                );
+
+                let transaction = call::<BeginLightingExtendedRuntimeConditionalSceneReplace>(
+                    &service,
+                    &session,
+                    &BeginLightingRuntimeConditionalSceneReplaceRequest {
+                        expected_revision: 6,
+                        cell_count: 1,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                let connection = rmk_types::protocol::rynk::LightingConnectionCondition {
+                    transport: Some(rmk_types::protocol::rynk::LightingActiveTransport::Ble),
+                    profile: Some(3),
+                    ble_state: Some(rmk_types::ble::BleState::Connected),
+                };
+                let extended_cell = rmk_types::protocol::rynk::LightingExtendedConditionalSceneCell {
+                    cell: conditional_cell,
+                    connection: Some(connection),
+                };
+                let mut extended_cells = Vec::new();
+                extended_cells.push(extended_cell).unwrap();
+                call::<PutLightingExtendedRuntimeConditionalSceneChunk>(
+                    &service,
+                    &session,
+                    &PutLightingExtendedRuntimeConditionalSceneChunkRequest {
+                        transaction_id: transaction.id,
+                        offset: 0,
+                        cells: extended_cells,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                let committed = call::<CommitLightingExtendedRuntimeConditionalSceneReplace>(
+                    &service,
+                    &session,
+                    &CommitLightingRuntimeConditionalSceneReplaceRequest {
+                        transaction_id: transaction.id,
+                    },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(committed.revision, 7);
+                let extended_page = call::<GetLightingExtendedRuntimeConditionalScenes>(
+                    &service,
+                    &session,
+                    &LightingRuntimeConditionalScenePageRequest { revision: 7, offset: 0 },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(extended_page.items.as_slice(), &[extended_cell]);
+                let legacy_page = call::<GetLightingRuntimeConditionalScenes>(
+                    &service,
+                    &session,
+                    &LightingRuntimeConditionalScenePageRequest { revision: 7, offset: 0 },
+                )
+                .await
+                .unwrap()
+                .unwrap();
+                assert_eq!(
+                    legacy_page.items.as_slice(),
+                    &[conditional_cell],
+                    "legacy reads omit the connection predicate"
+                );
 
                 let output = call::<SetLightingOutputMode>(
                     &service,
                     &session,
                     &SetLightingOutputModeRequest {
-                        expected_revision: 6,
+                        expected_revision: 7,
                         mode: rmk_types::protocol::rynk::LightingOutputMode::AlwaysOff,
                     },
                 )
@@ -2405,12 +2664,12 @@ mod tests {
                     .await
                     .unwrap()
                     .unwrap();
-                assert_eq!(state.revision, 7);
+                assert_eq!(state.revision, 8);
                 let stale_output = call::<SetLightingOutputMode>(
                     &service,
                     &session,
                     &SetLightingOutputModeRequest {
-                        expected_revision: 6,
+                        expected_revision: 7,
                         mode: rmk_types::protocol::rynk::LightingOutputMode::AlwaysOn,
                     },
                 )
@@ -2419,8 +2678,8 @@ mod tests {
                 assert_eq!(
                     stale_output,
                     Err(LightingError::StateRevisionConflict {
-                        expected: 6,
-                        current: 7,
+                        expected: 7,
+                        current: 8,
                     })
                 );
             };
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 85b60c9c7..fb9523009 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -15,10 +15,12 @@ use embassy_sync::mutex::Mutex;
 use embassy_sync::signal::Signal;
 use heapless::{String, Vec};
 use rmk_types::protocol::rynk::{
-    LIGHTING_EXTENSION_NAME_CHUNK, LIGHTING_EXTENSION_NAME_SIZE, LIGHTING_EXTENSION_PARAM_CHUNK,
-    LIGHTING_OVERLAY_CHUNK_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode, LightingBackgroundState,
-    LightingCompiledScenesPage, LightingConditionalSceneCell as WireConditionalSceneCell,
-    LightingControls as WireLightingControls, LightingError, LightingExtension, LightingExtensionLayers,
+    LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE, LIGHTING_EXTENSION_NAME_CHUNK, LIGHTING_EXTENSION_NAME_SIZE,
+    LIGHTING_EXTENSION_PARAM_CHUNK, LIGHTING_OVERLAY_CHUNK_SIZE, LIGHTING_SCENE_CHUNK_SIZE, LightingBackgroundMode,
+    LightingBackgroundState, LightingCompiledScenesPage, LightingConditionalSceneCell as WireConditionalSceneCell,
+    LightingControls as WireLightingControls, LightingError,
+    LightingExtendedConditionalSceneCell as WireExtendedConditionalSceneCell,
+    LightingExtendedRuntimeConditionalScenesPage, LightingExtension, LightingExtensionLayers,
     LightingExtensionNameKind, LightingExtensionNamesPage, LightingExtensionParam, LightingExtensionParamsPage,
     LightingExtensionState as WireExtensionState, LightingLayerPolicy, LightingMutableState,
     LightingOutputMode as WireLightingOutputMode, LightingOutputModeIndicator as WireLightingOutputModeIndicator,
@@ -263,6 +265,7 @@ pub enum RynkLightingReadback {
     ExtensionNamesPage(LightingExtensionNamesPage),
     ExtensionParamsPage(LightingExtensionParamsPage),
     RuntimeConditionalScenesPage(LightingRuntimeConditionalScenesPage),
+    ExtendedRuntimeConditionalScenesPage(LightingExtendedRuntimeConditionalScenesPage),
     RuntimeConditionalSceneTransaction(LightingRuntimeConditionalSceneTransaction),
     Unit,
 }
@@ -465,6 +468,10 @@ pub(super) enum RynkLightingCommand {
         expected_revision: u32,
         offset: u16,
     },
+    ReadExtendedRuntimeConditionalScenes {
+        expected_revision: u32,
+        offset: u16,
+    },
     BeginRuntimeConditionalSceneReplace {
         expected_revision: u32,
         cell_count: u16,
@@ -474,6 +481,14 @@ pub(super) enum RynkLightingCommand {
         offset: u16,
         cells: Vec<WireConditionalSceneCell, { rmk_types::protocol::rynk::LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE }>,
     },
+    PutExtendedRuntimeConditionalSceneChunk {
+        transaction_id: u32,
+        offset: u16,
+        cells: Vec<
+            WireExtendedConditionalSceneCell,
+            { rmk_types::protocol::rynk::LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE },
+        >,
+    },
     CommitRuntimeConditionalSceneReplace {
         transaction_id: u32,
     },
@@ -768,13 +783,14 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
             else {
                 return;
             };
-            let cells = page.cells.as_slice();
+            let page_cells = page.cells.as_slice();
+            let cells = &page_cells[..page_cells.len().min(LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE)];
             if cells.is_empty() {
                 break;
             }
             let mut wire_cells = Vec::new();
             for cell in cells {
-                let Some(wire) = self.runtime_conditional_scene_cell_to_wire(*cell) else {
+                let Some(wire) = self.runtime_conditional_scene_cell_to_extended_wire(*cell) else {
                     return;
                 };
                 let _ = wire_cells.push(wire);
@@ -1090,6 +1106,45 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                     },
                 ));
             }
+            RynkLightingCommand::ReadExtendedRuntimeConditionalScenes {
+                expected_revision,
+                offset,
+            } => {
+                let page = match self
+                    .request_core(StandardCommand::ReadRuntimeConditionalScenes { offset })
+                    .await?
+                {
+                    StandardReply::RuntimeConditionalScenesPage(page) => page,
+                    _ => return Err(LightingError::InvalidRequest),
+                };
+                if page.revision != expected_revision {
+                    return Err(LightingError::StateRevisionConflict {
+                        expected: expected_revision,
+                        current: page.revision,
+                    });
+                }
+                let mut items = Vec::new();
+                for cell in page
+                    .cells
+                    .as_slice()
+                    .iter()
+                    .take(LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE)
+                {
+                    items
+                        .push(
+                            self.runtime_conditional_scene_cell_to_extended_wire(*cell)
+                                .ok_or(LightingError::InvalidRequest)?,
+                        )
+                        .map_err(|_| LightingError::InvalidRequest)?;
+                }
+                return Ok(RynkLightingReadback::ExtendedRuntimeConditionalScenesPage(
+                    LightingExtendedRuntimeConditionalScenesPage {
+                        revision: page.revision,
+                        total_count: page.total,
+                        items,
+                    },
+                ));
+            }
             RynkLightingCommand::BeginRuntimeConditionalSceneReplace {
                 expected_revision,
                 cell_count,
@@ -1128,6 +1183,25 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                 .await?;
                 return Ok(RynkLightingReadback::Unit);
             }
+            RynkLightingCommand::PutExtendedRuntimeConditionalSceneChunk {
+                transaction_id,
+                offset,
+                cells,
+            } => {
+                let mut chunk = RuntimeConditionalSceneChunk::new();
+                for cell in &cells {
+                    chunk
+                        .push(self.runtime_conditional_scene_cell_from_extended_wire(*cell)?)
+                        .map_err(|error| map_standard_error(error, OVERLAY_CAPACITY))?;
+                }
+                self.request_core_state(StandardCommand::PutRuntimeConditionalSceneChunk {
+                    transaction_id,
+                    offset,
+                    cells: chunk,
+                })
+                .await?;
+                return Ok(RynkLightingReadback::Unit);
+            }
             RynkLightingCommand::CommitRuntimeConditionalSceneReplace { transaction_id } => {
                 let state = self
                     .runtime_conditional_scene_mutation(StandardCommand::CommitRuntimeConditionalSceneReplace {
@@ -1333,16 +1407,30 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
     fn runtime_conditional_scene_cell_from_wire(
         &self,
         cell: WireConditionalSceneCell,
+    ) -> LightingResult<RuntimeConditionalSceneCell> {
+        self.runtime_conditional_scene_cell_from_extended_wire(WireExtendedConditionalSceneCell {
+            cell,
+            connection: None,
+        })
+    }
+
+    fn runtime_conditional_scene_cell_from_extended_wire(
+        &self,
+        cell: WireExtendedConditionalSceneCell,
     ) -> LightingResult<RuntimeConditionalSceneCell> {
         cell.validate()?;
         let slot = self
             .topology
-            .slot(LedId(cell.led_id.0))
-            .ok_or(LightingError::UnknownLed { led_id: cell.led_id })?;
+            .slot(LedId(cell.cell.led_id.0))
+            .ok_or(LightingError::UnknownLed {
+                led_id: cell.cell.led_id,
+            })?;
+        let mut conditions = condition_set_from_wire(cell.cell.conditions);
+        conditions.connection = cell.connection.map(connection_condition_from_wire);
         Ok(RuntimeConditionalSceneCell {
-            conditions: condition_set_from_wire(cell.conditions),
+            conditions,
             slot,
-            effect: effect_from_wire(cell.effect),
+            effect: effect_from_wire(cell.cell.effect),
         })
     }
 
@@ -1350,11 +1438,21 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
         &self,
         cell: RuntimeConditionalSceneCell,
     ) -> Option<WireConditionalSceneCell> {
+        Some(self.runtime_conditional_scene_cell_to_extended_wire(cell)?.cell)
+    }
+
+    fn runtime_conditional_scene_cell_to_extended_wire(
+        &self,
+        cell: RuntimeConditionalSceneCell,
+    ) -> Option<WireExtendedConditionalSceneCell> {
         let led = self.topology.led(cell.slot)?;
-        Some(WireConditionalSceneCell {
-            conditions: condition_set_to_wire(cell.conditions),
-            led_id: rmk_types::protocol::rynk::LightingLedId(led.id.0),
-            effect: effect_to_wire(cell.effect),
+        Some(WireExtendedConditionalSceneCell {
+            cell: WireConditionalSceneCell {
+                conditions: condition_set_to_wire(cell.conditions),
+                led_id: rmk_types::protocol::rynk::LightingLedId(led.id.0),
+                effect: effect_to_wire(cell.effect),
+            },
+            connection: cell.conditions.connection.map(connection_condition_to_wire),
         })
     }
 }
@@ -1397,19 +1495,21 @@ pub fn install_lighting_runtime_conditional_scenes<
 >(
     engine: &mut StandardLightingEngine<'_, Extension, Status, N, OVERLAY_CAP, SCENE_CAP>,
     topology: &LightingTopology<'_>,
-    cells: &[WireConditionalSceneCell],
+    cells: &[WireExtendedConditionalSceneCell],
 ) {
     for cell in cells {
         if cell.validate().is_err() {
             continue;
         }
-        let Some(slot) = topology.slot(LedId(cell.led_id.0)) else {
+        let Some(slot) = topology.slot(LedId(cell.cell.led_id.0)) else {
             continue;
         };
+        let mut conditions = condition_set_from_wire(cell.cell.conditions);
+        conditions.connection = cell.connection.map(connection_condition_from_wire);
         let _ = engine.install_runtime_conditional_scene_cell(RuntimeConditionalSceneCell {
-            conditions: condition_set_from_wire(cell.conditions),
+            conditions,
             slot,
-            effect: effect_from_wire(cell.effect),
+            effect: effect_from_wire(cell.cell.effect),
         });
     }
 }
@@ -1602,6 +1702,38 @@ fn condition_set_from_wire(
     }
 }
 
+fn connection_condition_to_wire(
+    condition: crate::lighting::ConnectionCondition,
+) -> rmk_types::protocol::rynk::LightingConnectionCondition {
+    use rmk_types::protocol::rynk::{LightingActiveTransport, LightingConnectionCondition};
+
+    LightingConnectionCondition {
+        transport: condition.transport.map(|transport| match transport {
+            crate::lighting::ActiveTransport::Usb => LightingActiveTransport::Usb,
+            crate::lighting::ActiveTransport::Ble => LightingActiveTransport::Ble,
+            crate::lighting::ActiveTransport::NoneActive => LightingActiveTransport::NoneActive,
+        }),
+        profile: condition.profile,
+        ble_state: condition.ble_state,
+    }
+}
+
+fn connection_condition_from_wire(
+    condition: rmk_types::protocol::rynk::LightingConnectionCondition,
+) -> crate::lighting::ConnectionCondition {
+    use rmk_types::protocol::rynk::LightingActiveTransport;
+
+    crate::lighting::ConnectionCondition {
+        transport: condition.transport.map(|transport| match transport {
+            LightingActiveTransport::Usb => crate::lighting::ActiveTransport::Usb,
+            LightingActiveTransport::Ble => crate::lighting::ActiveTransport::Ble,
+            LightingActiveTransport::NoneActive => crate::lighting::ActiveTransport::NoneActive,
+        }),
+        profile: condition.profile,
+        ble_state: condition.ble_state,
+    }
+}
+
 const fn output_mode_from_wire(mode: WireLightingOutputMode) -> OutputMode {
     match mode {
         WireLightingOutputMode::AlwaysOn => OutputMode::AlwaysOn,
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index ffc7cd7df..043464ce6 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -191,7 +191,11 @@ impl<'a> RynkService<'a> {
             | Cmd::BeginLightingRuntimeConditionalSceneReplace
             | Cmd::PutLightingRuntimeConditionalSceneChunk
             | Cmd::CommitLightingRuntimeConditionalSceneReplace
-            | Cmd::AbortLightingRuntimeConditionalSceneReplace => self.lock_config.write_requires_unlock,
+            | Cmd::AbortLightingRuntimeConditionalSceneReplace
+            | Cmd::BeginLightingExtendedRuntimeConditionalSceneReplace
+            | Cmd::PutLightingExtendedRuntimeConditionalSceneChunk
+            | Cmd::CommitLightingExtendedRuntimeConditionalSceneReplace
+            | Cmd::AbortLightingExtendedRuntimeConditionalSceneReplace => self.lock_config.write_requires_unlock,
             _ => false,
         }
     }
@@ -372,6 +376,30 @@ impl<'a> RynkService<'a> {
                 serve::<command::AbortLightingRuntimeConditionalSceneReplace, _>(self, msg).await
             }
             #[cfg(feature = "lighting")]
+            Cmd::GetLightingExtendedRuntimeConditionalSceneStatus => {
+                serve::<command::GetLightingExtendedRuntimeConditionalSceneStatus, _>(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingExtendedRuntimeConditionalScenes => {
+                serve::<command::GetLightingExtendedRuntimeConditionalScenes, _>(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::BeginLightingExtendedRuntimeConditionalSceneReplace => {
+                serve::<command::BeginLightingExtendedRuntimeConditionalSceneReplace, _>(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::PutLightingExtendedRuntimeConditionalSceneChunk => {
+                serve::<command::PutLightingExtendedRuntimeConditionalSceneChunk, _>(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::CommitLightingExtendedRuntimeConditionalSceneReplace => {
+                serve::<command::CommitLightingExtendedRuntimeConditionalSceneReplace, _>(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
+            Cmd::AbortLightingExtendedRuntimeConditionalSceneReplace => {
+                serve::<command::AbortLightingExtendedRuntimeConditionalSceneReplace, _>(self, msg).await
+            }
+            #[cfg(feature = "lighting")]
             Cmd::SetLightingSceneCell => serve::<command::SetLightingSceneCell, _>(self, msg).await,
             #[cfg(feature = "lighting")]
             Cmd::UnsetLightingSceneCell => serve::<command::UnsetLightingSceneCell, _>(self, msg).await,
diff --git a/rmk/src/storage/mod.rs b/rmk/src/storage/mod.rs
index 449ad0b21..9360722e1 100644
--- a/rmk/src/storage/mod.rs
+++ b/rmk/src/storage/mod.rs
@@ -10,8 +10,9 @@ use rmk_types::connection::ConnectionType;
 use rmk_types::morse::MorseProfile;
 #[cfg(all(feature = "lighting", feature = "rynk"))]
 use rmk_types::protocol::rynk::{
-    LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE, LIGHTING_EXTENSION_PARAM_CHUNK, LIGHTING_SCENE_CHUNK_SIZE,
-    LightingConditionalSceneCell, LightingLayerPolicy, LightingSceneCell,
+    LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE, LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE,
+    LIGHTING_EXTENSION_PARAM_CHUNK, LIGHTING_SCENE_CHUNK_SIZE, LightingConditionalSceneCell,
+    LightingExtendedConditionalSceneCell, LightingLayerPolicy, LightingSceneCell,
 };
 use sequential_storage::Error as SSError;
 use sequential_storage::cache::{Cache, Uncached};
@@ -176,7 +177,7 @@ pub(crate) enum FlashOperationMessage {
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     LightingRuntimeConditionalSceneShard {
         index: u8,
-        cells: heapless::Vec<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>,
+        cells: heapless::Vec<LightingExtendedConditionalSceneCell, LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE>,
     },
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     // Animated extension-band selection and the selected effect's parameters
@@ -241,6 +242,10 @@ pub(crate) enum StorageKey {
     LightingExtensionState,
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     LightingExtensionOverlay,
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingRuntimeConditionalSceneTableV2,
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingRuntimeConditionalSceneShardV2(u8),
 }
 
 impl StorageKey {
@@ -336,6 +341,12 @@ pub(crate) enum StorageData {
     LightingExtensionState(LightingExtensionRecord),
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     LightingExtensionOverlay(LightingExtensionOverlayRecord),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingRuntimeConditionalSceneTableV2(u16),
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    LightingRuntimeConditionalSceneShardV2(
+        heapless::Vec<LightingExtendedConditionalSceneCell, LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE>,
+    ),
 }
 
 impl<'a> PostcardValue<'a> for StorageData {}
@@ -699,8 +710,37 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     pub async fn read_lighting_runtime_conditional_scenes<const CAP: usize>(
         &mut self,
-        cells: &mut heapless::Vec<LightingConditionalSceneCell, CAP>,
+        cells: &mut heapless::Vec<LightingExtendedConditionalSceneCell, CAP>,
     ) {
+        if let Some(StorageData::LightingRuntimeConditionalSceneTableV2(saved_len)) = self
+            .fetch_data(StorageKey::LightingRuntimeConditionalSceneTableV2)
+            .await
+        {
+            let len = (saved_len as usize).min(CAP);
+            let mut index: u8 = 0;
+            'shards: while cells.len() < len {
+                let Some(StorageData::LightingRuntimeConditionalSceneShardV2(shard)) = self
+                    .fetch_data(StorageKey::LightingRuntimeConditionalSceneShardV2(index))
+                    .await
+                else {
+                    break;
+                };
+                if shard.is_empty() {
+                    break;
+                }
+                for cell in shard {
+                    if cells.len() == len || cells.push(cell).is_err() {
+                        break 'shards;
+                    }
+                }
+                let Some(next) = index.checked_add(1) else {
+                    break;
+                };
+                index = next;
+            }
+            return;
+        }
+
         let Some(StorageData::LightingRuntimeConditionalSceneTable(saved_len)) =
             self.fetch_data(StorageKey::LightingRuntimeConditionalSceneTable).await
         else {
@@ -708,7 +748,7 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
         };
         let len = (saved_len as usize).min(CAP);
         let mut index: u8 = 0;
-        'shards: while cells.len() < len {
+        'legacy_shards: while cells.len() < len {
             let Some(StorageData::LightingRuntimeConditionalSceneShard(shard)) = self
                 .fetch_data(StorageKey::LightingRuntimeConditionalSceneShard(index))
                 .await
@@ -719,8 +759,12 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
                 break;
             }
             for cell in shard {
-                if cells.len() == len || cells.push(cell).is_err() {
-                    break 'shards;
+                if cells.len() == len
+                    || cells
+                        .push(LightingExtendedConditionalSceneCell { cell, connection: None })
+                        .is_err()
+                {
+                    break 'legacy_shards;
                 }
             }
             let Some(next) = index.checked_add(1) else {
@@ -1068,12 +1112,15 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
                 }
                 #[cfg(all(feature = "lighting", feature = "rynk"))]
                 FlashOperationMessage::LightingRuntimeConditionalSceneTable { len } => {
-                    match self.fetch_data(StorageKey::LightingRuntimeConditionalSceneTable).await {
-                        Some(StorageData::LightingRuntimeConditionalSceneTable(saved)) if saved == len => Ok(()),
+                    match self
+                        .fetch_data(StorageKey::LightingRuntimeConditionalSceneTableV2)
+                        .await
+                    {
+                        Some(StorageData::LightingRuntimeConditionalSceneTableV2(saved)) if saved == len => Ok(()),
                         _ => {
                             self.store_data(
-                                StorageKey::LightingRuntimeConditionalSceneTable,
-                                &StorageData::LightingRuntimeConditionalSceneTable(len),
+                                StorageKey::LightingRuntimeConditionalSceneTableV2,
+                                &StorageData::LightingRuntimeConditionalSceneTableV2(len),
                             )
                             .await
                         }
@@ -1082,14 +1129,14 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
                 #[cfg(all(feature = "lighting", feature = "rynk"))]
                 FlashOperationMessage::LightingRuntimeConditionalSceneShard { index, cells } => {
                     match self
-                        .fetch_data(StorageKey::LightingRuntimeConditionalSceneShard(index))
+                        .fetch_data(StorageKey::LightingRuntimeConditionalSceneShardV2(index))
                         .await
                     {
-                        Some(StorageData::LightingRuntimeConditionalSceneShard(saved)) if saved == cells => Ok(()),
+                        Some(StorageData::LightingRuntimeConditionalSceneShardV2(saved)) if saved == cells => Ok(()),
                         _ => {
                             self.store_data(
-                                StorageKey::LightingRuntimeConditionalSceneShard(index),
-                                &StorageData::LightingRuntimeConditionalSceneShard(cells),
+                                StorageKey::LightingRuntimeConditionalSceneShardV2(index),
+                                &StorageData::LightingRuntimeConditionalSceneShardV2(cells),
                             )
                             .await
                         }
@@ -1274,6 +1321,22 @@ mod tests {
             StorageKey::ActiveBleProfile,
             #[cfg(feature = "_ble")]
             StorageKey::BondInfo(0),
+            #[cfg(all(feature = "lighting", feature = "rynk"))]
+            StorageKey::LightingSceneTable,
+            #[cfg(all(feature = "lighting", feature = "rynk"))]
+            StorageKey::LightingSceneShard(0),
+            #[cfg(all(feature = "lighting", feature = "rynk"))]
+            StorageKey::LightingRuntimeConditionalSceneTable,
+            #[cfg(all(feature = "lighting", feature = "rynk"))]
+            StorageKey::LightingRuntimeConditionalSceneShard(0),
+            #[cfg(all(feature = "lighting", feature = "rynk"))]
+            StorageKey::LightingExtensionState,
+            #[cfg(all(feature = "lighting", feature = "rynk"))]
+            StorageKey::LightingExtensionOverlay,
+            #[cfg(all(feature = "lighting", feature = "rynk"))]
+            StorageKey::LightingRuntimeConditionalSceneTableV2,
+            #[cfg(all(feature = "lighting", feature = "rynk"))]
+            StorageKey::LightingRuntimeConditionalSceneShardV2(0),
         ];
 
         let mut buffer = [0u8; 64];
@@ -1285,6 +1348,110 @@ mod tests {
         }
     }
 
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    #[test]
+    fn legacy_runtime_conditional_records_load_without_connection_condition() {
+        block_on(async {
+            type Flash = TestFlash<16_384, 4_096, 1>;
+
+            let storage_range = (16_384 - 2 * 4_096) as u32..16_384u32;
+            let mut map =
+                MapStorage::<StorageKey, _, _>::new(Flash::new(), MapConfig::new(storage_range), Cache::new_uncached());
+            let mut buffer = [0u8; get_buffer_size()];
+            let legacy = LightingConditionalSceneCell {
+                conditions: rmk_types::protocol::rynk::LightingConditionSet {
+                    layer: Some(rmk_types::protocol::rynk::LightingLayerCondition { layer: 2, active: true }),
+                    battery: None,
+                    output_mode: None,
+                },
+                led_id: rmk_types::protocol::rynk::LightingLedId(42),
+                effect: rmk_types::protocol::rynk::LightingEffect::Solid {
+                    color: rmk_types::protocol::rynk::LightingRgb8 { r: 1, g: 2, b: 3 },
+                },
+            };
+            let mut shard = heapless::Vec::<LightingConditionalSceneCell, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE>::new();
+            shard.push(legacy).unwrap();
+            map.store_item(
+                &mut buffer,
+                &StorageKey::LightingRuntimeConditionalSceneTable,
+                &StorageData::LightingRuntimeConditionalSceneTable(1),
+            )
+            .await
+            .unwrap();
+            map.store_item(
+                &mut buffer,
+                &StorageKey::LightingRuntimeConditionalSceneShard(0),
+                &StorageData::LightingRuntimeConditionalSceneShard(shard),
+            )
+            .await
+            .unwrap();
+
+            let mut storage = Storage::<Flash, 0, 0, 0, 0> { flash: map, buffer };
+            let mut loaded = heapless::Vec::<LightingExtendedConditionalSceneCell, 4>::new();
+            storage.read_lighting_runtime_conditional_scenes(&mut loaded).await;
+
+            assert_eq!(loaded.len(), 1);
+            assert_eq!(loaded[0].cell, legacy);
+            assert_eq!(loaded[0].connection, None);
+        });
+    }
+
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    #[test]
+    fn extended_runtime_conditional_records_preserve_connection_condition() {
+        block_on(async {
+            type Flash = TestFlash<16_384, 4_096, 1>;
+
+            let storage_range = (16_384 - 2 * 4_096) as u32..16_384u32;
+            let mut map =
+                MapStorage::<StorageKey, _, _>::new(Flash::new(), MapConfig::new(storage_range), Cache::new_uncached());
+            let mut buffer = [0u8; get_buffer_size()];
+            let cell = LightingExtendedConditionalSceneCell {
+                cell: LightingConditionalSceneCell {
+                    conditions: rmk_types::protocol::rynk::LightingConditionSet {
+                        layer: None,
+                        battery: None,
+                        output_mode: None,
+                    },
+                    led_id: rmk_types::protocol::rynk::LightingLedId(7),
+                    effect: rmk_types::protocol::rynk::LightingEffect::Solid {
+                        color: rmk_types::protocol::rynk::LightingRgb8 { r: 4, g: 5, b: 6 },
+                    },
+                },
+                connection: Some(rmk_types::protocol::rynk::LightingConnectionCondition {
+                    transport: Some(rmk_types::protocol::rynk::LightingActiveTransport::Ble),
+                    profile: Some(4),
+                    ble_state: Some(rmk_types::ble::BleState::Advertising),
+                }),
+            };
+            let mut shard = heapless::Vec::<
+                LightingExtendedConditionalSceneCell,
+                LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE,
+            >::new();
+            shard.push(cell).unwrap();
+            map.store_item(
+                &mut buffer,
+                &StorageKey::LightingRuntimeConditionalSceneTableV2,
+                &StorageData::LightingRuntimeConditionalSceneTableV2(1),
+            )
+            .await
+            .unwrap();
+            map.store_item(
+                &mut buffer,
+                &StorageKey::LightingRuntimeConditionalSceneShardV2(0),
+                &StorageData::LightingRuntimeConditionalSceneShardV2(shard),
+            )
+            .await
+            .unwrap();
+
+            let mut storage = Storage::<Flash, 0, 0, 0, 0> { flash: map, buffer };
+            let mut loaded = heapless::Vec::<LightingExtendedConditionalSceneCell, 4>::new();
+            storage.read_lighting_runtime_conditional_scenes(&mut loaded).await;
+
+            assert_eq!(loaded.as_slice(), &[cell]);
+        });
+    }
+
     #[test]
     fn build_hash_mismatch_reinitializes_storage() {
         block_on(async {
diff --git a/rynk/rynk-wasm/src/client.rs b/rynk/rynk-wasm/src/client.rs
index f17ec040c..eff4b34fb 100644
--- a/rynk/rynk-wasm/src/client.rs
+++ b/rynk/rynk-wasm/src/client.rs
@@ -30,14 +30,15 @@ use rynk::rmk_types::protocol::rynk::{
     CommitLightingRuntimeConditionalSceneReplaceRequest, CommitLightingSceneReplaceRequest, DeviceCapabilities,
     DeviceInfo, GetComboBulkResponse, GetKeymapBulkResponse, GetMorseBulkResponse, LayerState, LightingCapabilities,
     LightingCompiledSceneStatus, LightingCompiledScenesPage, LightingConditionalSceneStatus,
-    LightingConditionalScenesPage, LightingExtension, LightingExtensionLayers, LightingExtensionNamesPage,
-    LightingExtensionNamesRequest, LightingExtensionParamsPage, LightingExtensionParamsRequest, LightingKeysPage,
-    LightingLedsPage, LightingOutputModeState, LightingOutputsPage, LightingOverlayPage, LightingOverlayPageRequest,
-    LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage, LightingRoutesPage,
-    LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
-    LightingRuntimeConditionalSceneTransaction, LightingRuntimeConditionalScenesPage, LightingScenePageRequest,
-    LightingSceneStatus, LightingSceneTransaction, LightingScenesPage, LightingState, LightingZoneMembershipsPage,
-    LightingZonesPage, LockStatus, MacroData, MatrixState, PeripheralStatus, ProtocolVersion,
+    LightingConditionalScenesPage, LightingExtendedRuntimeConditionalScenesPage, LightingExtension,
+    LightingExtensionLayers, LightingExtensionNamesPage, LightingExtensionNamesRequest, LightingExtensionParamsPage,
+    LightingExtensionParamsRequest, LightingKeysPage, LightingLedsPage, LightingOutputModeState, LightingOutputsPage,
+    LightingOverlayPage, LightingOverlayPageRequest, LightingOverlayTransaction, LightingPageRequest,
+    LightingPhysicalKeysPage, LightingRoutesPage, LightingRuntimeConditionalScenePageRequest,
+    LightingRuntimeConditionalSceneStatus, LightingRuntimeConditionalSceneTransaction,
+    LightingRuntimeConditionalScenesPage, LightingScenePageRequest, LightingSceneStatus, LightingSceneTransaction,
+    LightingScenesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus, MacroData,
+    MatrixState, PeripheralStatus, ProtocolVersion, PutLightingExtendedRuntimeConditionalSceneChunkRequest,
     PutLightingOverlayChunkRequest, PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest,
     SetComboBulkRequest, SetKeymapBulkRequest, SetLightingExtensionLayersRequest, SetLightingExtensionParamRequest,
     SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest, SetLightingOutputModeRequest,
@@ -222,6 +223,12 @@ endpoints! {
     put_lighting_runtime_conditional_scene_chunk(request: PutLightingRuntimeConditionalSceneChunkRequest) -> (),
     commit_lighting_runtime_conditional_scene_replace(request: CommitLightingRuntimeConditionalSceneReplaceRequest) -> LightingState,
     abort_lighting_runtime_conditional_scene_replace(request: AbortLightingRuntimeConditionalSceneReplaceRequest) -> (),
+    get_lighting_extended_runtime_conditional_scene_status() -> LightingRuntimeConditionalSceneStatus,
+    get_lighting_extended_runtime_conditional_scenes(request: LightingRuntimeConditionalScenePageRequest) -> LightingExtendedRuntimeConditionalScenesPage,
+    begin_lighting_extended_runtime_conditional_scene_replace(request: BeginLightingRuntimeConditionalSceneReplaceRequest) -> LightingRuntimeConditionalSceneTransaction,
+    put_lighting_extended_runtime_conditional_scene_chunk(request: PutLightingExtendedRuntimeConditionalSceneChunkRequest) -> (),
+    commit_lighting_extended_runtime_conditional_scene_replace(request: CommitLightingRuntimeConditionalSceneReplaceRequest) -> LightingState,
+    abort_lighting_extended_runtime_conditional_scene_replace(request: AbortLightingRuntimeConditionalSceneReplaceRequest) -> (),
     set_lighting_scene_cell(request: SetLightingSceneCellRequest) -> LightingState,
     unset_lighting_scene_cell(request: UnsetLightingSceneCellRequest) -> LightingState,
     set_lighting_layer_policy(request: SetLightingLayerPolicyRequest) -> LightingState,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 95e596b86..cf6fad6f2 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -30,15 +30,16 @@ use rmk_types::protocol::rynk::{
     DeviceInfo, GetComboBulkRequest, GetComboBulkResponse, GetEncoderRequest, GetKeymapBulkRequest,
     GetKeymapBulkResponse, GetMacroRequest, GetMorseBulkRequest, GetMorseBulkResponse, KeyPosition, LayerState,
     LightingCapabilities, LightingCompiledSceneStatus, LightingCompiledScenesPage, LightingConditionalSceneStatus,
-    LightingConditionalScenesPage, LightingExtension, LightingExtensionLayers, LightingExtensionNameKind,
-    LightingExtensionNamesPage, LightingExtensionNamesRequest, LightingExtensionParamsPage,
-    LightingExtensionParamsRequest, LightingKeysPage, LightingLedsPage, LightingOutputModeState, LightingOutputsPage,
-    LightingOverlayPage, LightingOverlayPageRequest, LightingOverlayTransaction, LightingPageRequest,
-    LightingPhysicalKeysPage, LightingResult, LightingRoutesPage, LightingRuntimeConditionalScenePageRequest,
-    LightingRuntimeConditionalSceneStatus, LightingRuntimeConditionalSceneTransaction,
-    LightingRuntimeConditionalScenesPage, LightingScenePageRequest, LightingSceneStatus, LightingSceneTransaction,
-    LightingScenesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus, MacroData,
-    MatrixState, PeripheralStatus, ProtocolVersion, PutLightingOverlayChunkRequest,
+    LightingConditionalScenesPage, LightingExtendedRuntimeConditionalScenesPage, LightingExtension,
+    LightingExtensionLayers, LightingExtensionNameKind, LightingExtensionNamesPage, LightingExtensionNamesRequest,
+    LightingExtensionParamsPage, LightingExtensionParamsRequest, LightingKeysPage, LightingLedsPage,
+    LightingOutputModeState, LightingOutputsPage, LightingOverlayPage, LightingOverlayPageRequest,
+    LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage, LightingResult, LightingRoutesPage,
+    LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
+    LightingRuntimeConditionalSceneTransaction, LightingRuntimeConditionalScenesPage, LightingScenePageRequest,
+    LightingSceneStatus, LightingSceneTransaction, LightingScenesPage, LightingState, LightingZoneMembershipsPage,
+    LightingZonesPage, LockStatus, MacroData, MatrixState, PeripheralStatus, ProtocolVersion,
+    PutLightingExtendedRuntimeConditionalSceneChunkRequest, PutLightingOverlayChunkRequest,
     PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, SetComboBulkRequest, SetComboRequest,
     SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest, SetLightingExtensionLayersRequest,
     SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
@@ -743,6 +744,75 @@ impl Client {
                 .await?,
         )
     }
+
+    /// Read connection-aware runtime conditional cells. Callers should use
+    /// this only when lighting capabilities advertise
+    /// `RUNTIME_CONNECTION_CONDITIONS`.
+    pub async fn get_lighting_extended_runtime_conditional_scene_status(
+        &self,
+    ) -> Result<LightingRuntimeConditionalSceneStatus, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingExtendedRuntimeConditionalSceneStatus)?;
+        Self::flatten_lighting(
+            self.request::<command::GetLightingExtendedRuntimeConditionalSceneStatus>(&())
+                .await?,
+        )
+    }
+
+    pub async fn get_lighting_extended_runtime_conditional_scenes(
+        &self,
+        request: LightingRuntimeConditionalScenePageRequest,
+    ) -> Result<LightingExtendedRuntimeConditionalScenesPage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingExtendedRuntimeConditionalScenes)?;
+        Self::flatten_lighting(
+            self.request::<command::GetLightingExtendedRuntimeConditionalScenes>(&request)
+                .await?,
+        )
+    }
+
+    pub async fn begin_lighting_extended_runtime_conditional_scene_replace(
+        &self,
+        request: BeginLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<LightingRuntimeConditionalSceneTransaction, RynkHostError> {
+        self.require_lighting(Cmd::BeginLightingExtendedRuntimeConditionalSceneReplace)?;
+        Self::flatten_lighting(
+            self.request::<command::BeginLightingExtendedRuntimeConditionalSceneReplace>(&request)
+                .await?,
+        )
+    }
+
+    pub async fn put_lighting_extended_runtime_conditional_scene_chunk(
+        &self,
+        request: PutLightingExtendedRuntimeConditionalSceneChunkRequest,
+    ) -> Result<(), RynkHostError> {
+        self.require_lighting(Cmd::PutLightingExtendedRuntimeConditionalSceneChunk)?;
+        Self::flatten_lighting(
+            self.request::<command::PutLightingExtendedRuntimeConditionalSceneChunk>(&request)
+                .await?,
+        )
+    }
+
+    pub async fn commit_lighting_extended_runtime_conditional_scene_replace(
+        &self,
+        request: CommitLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<LightingState, RynkHostError> {
+        self.require_lighting(Cmd::CommitLightingExtendedRuntimeConditionalSceneReplace)?;
+        Self::flatten_lighting(
+            self.request::<command::CommitLightingExtendedRuntimeConditionalSceneReplace>(&request)
+                .await?,
+        )
+    }
+
+    pub async fn abort_lighting_extended_runtime_conditional_scene_replace(
+        &self,
+        request: AbortLightingRuntimeConditionalSceneReplaceRequest,
+    ) -> Result<(), RynkHostError> {
+        self.require_lighting(Cmd::AbortLightingExtendedRuntimeConditionalSceneReplace)?;
+        Self::flatten_lighting(
+            self.request::<command::AbortLightingExtendedRuntimeConditionalSceneReplace>(&request)
+                .await?,
+        )
+    }
+
     /// Insert or update one durable scene cell when the revision matches.
     pub async fn set_lighting_scene_cell(
         &self,
@@ -1274,6 +1344,104 @@ impl Client {
         .await
     }
 
+    /// Read the connection-aware runtime table under one pinned revision.
+    pub async fn read_all_lighting_extended_runtime_conditional_scenes(
+        &self,
+    ) -> Result<
+        (
+            u32,
+            Vec<rmk_types::protocol::rynk::LightingExtendedConditionalSceneCell>,
+        ),
+        RynkHostError,
+    > {
+        const ATTEMPTS: usize = 4;
+        let mut last_error = None;
+        for _ in 0..ATTEMPTS {
+            let status = self.get_lighting_extended_runtime_conditional_scene_status().await?;
+            let mut cells = Vec::new();
+            let mut offset: u16 = 0;
+            let mut conflicted = false;
+            while offset < status.cell_len {
+                match self
+                    .get_lighting_extended_runtime_conditional_scenes(LightingRuntimeConditionalScenePageRequest {
+                        revision: status.revision,
+                        offset,
+                    })
+                    .await
+                {
+                    Ok(page) => {
+                        if page.items.is_empty() {
+                            break;
+                        }
+                        offset += page.items.len() as u16;
+                        cells.extend(page.items.iter().copied());
+                    }
+                    Err(
+                        error @ RynkHostError::LightingRejected(
+                            rmk_types::protocol::rynk::LightingError::StateRevisionConflict { .. },
+                        ),
+                    ) => {
+                        last_error = Some(error);
+                        conflicted = true;
+                        break;
+                    }
+                    Err(error) => return Err(error),
+                }
+            }
+            if !conflicted {
+                return Ok((status.revision, cells));
+            }
+        }
+        Err(last_error.expect("a retried read only exits with a recorded conflict"))
+    }
+
+    /// Atomically replace the connection-aware runtime conditional table.
+    pub async fn replace_all_lighting_extended_runtime_conditional_scenes(
+        &self,
+        expected_revision: u32,
+        cells: &[rmk_types::protocol::rynk::LightingExtendedConditionalSceneCell],
+    ) -> Result<LightingState, RynkHostError> {
+        let transaction = self
+            .begin_lighting_extended_runtime_conditional_scene_replace(
+                BeginLightingRuntimeConditionalSceneReplaceRequest {
+                    expected_revision,
+                    cell_count: cells.len() as u16,
+                },
+            )
+            .await?;
+        let mut offset: u16 = 0;
+        for chunk in cells.chunks(rmk_types::protocol::rynk::LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE) {
+            let mut request = PutLightingExtendedRuntimeConditionalSceneChunkRequest {
+                transaction_id: transaction.id,
+                offset,
+                cells: Default::default(),
+            };
+            for cell in chunk {
+                request.cells.push(*cell).expect("chunks are chunk-size bounded");
+            }
+            if let Err(error) = self
+                .put_lighting_extended_runtime_conditional_scene_chunk(request)
+                .await
+            {
+                let _ = self
+                    .abort_lighting_extended_runtime_conditional_scene_replace(
+                        AbortLightingRuntimeConditionalSceneReplaceRequest {
+                            transaction_id: transaction.id,
+                        },
+                    )
+                    .await;
+                return Err(error);
+            }
+            offset += chunk.len() as u16;
+        }
+        self.commit_lighting_extended_runtime_conditional_scene_replace(
+            CommitLightingRuntimeConditionalSceneReplaceRequest {
+                transaction_id: transaction.id,
+            },
+        )
+        .await
+    }
+
     /// Atomically replace the whole stored scene table: begin, stage in
     /// chunk-sized pages, and commit. A staging failure is followed by a
     /// best-effort abort so the firmware transaction is not left dangling.

From 7716c7bc401db0ae0ec93ee2ee90ed8de89cd774 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 18:06:21 -0700
Subject: [PATCH 62/78] fix(config): account for lighting connection subscriber

---
 rmk-config/src/default_config/subscriber_default.toml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/rmk-config/src/default_config/subscriber_default.toml b/rmk-config/src/default_config/subscriber_default.toml
index 0785ff509..1973bb379 100644
--- a/rmk-config/src/default_config/subscriber_default.toml
+++ b/rmk-config/src/default_config/subscriber_default.toml
@@ -103,6 +103,7 @@ events = [
     # lighting/processor.rs: LightingProcessor subscribes to authoritative
     # keyboard-state invalidations on every lighting-enabled board.
     { name = "layer_change" },
+    { name = "connection_status_change" },
     { name = "led_indicator" },
     { name = "sleep_state" },
 ]

From e2a1c03070f4b23e489d407ef887195a5615cde5 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 19:07:12 -0700
Subject: [PATCH 63/78] fix(rynk): bound connection profiles and guard storage
 downgrade

Reject extended conditional-scene cells whose connection profile is past
NUM_BLE_PROFILE, empty the legacy conditional table whenever the V2 table
is written so a firmware downgrade cannot resurrect stale rules, and
document that legacy read-modify-write cycles drop connection predicates.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../main/docs/development/rynk_protocol.md    | 210 +++++++++---------
 rmk-types/src/protocol/rynk/command.rs        |   4 +-
 rmk/src/host/rynk/handlers/lighting.rs        |  61 +++++
 rmk/src/storage/mod.rs                        |  84 +++++--
 4 files changed, 240 insertions(+), 119 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index d21a78fdd..ca7a0bd5f 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -26,111 +26,111 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 
 ## Endpoints
 
-| CMD      | Name                                                   | Request                                                  | Response                                             | Feature          | Notes                                                                                                                                                                                  |
-| -------- | ------------------------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `0x0001` | `GetVersion`                                           | `()`                                                     | `ProtocolVersion`                                    |                  |                                                                                                                                                                                        |
-| `0x0002` | `GetCapabilities`                                      | `()`                                                     | `DeviceCapabilities`                                 |                  |                                                                                                                                                                                        |
-| `0x0003` | `Reboot`                                               | `()`                                                     | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0004` | `BootloaderJump`                                       | `()`                                                     | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0005` | `StorageReset`                                         | `StorageResetMode`                                       | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0006` | `GetLockStatus`                                        | `()`                                                     | `LockStatus`                                         |                  | Pure read of the current lock state — no side effects.                                                                                                                                 |
-| `0x0007` | `UnlockPoll`                                           | `()`                                                     | `LockStatus`                                         |                  | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                                                                                 |
-| `0x0008` | `Lock`                                                 | `()`                                                     | `()`                                                 |                  | Relock immediately.                                                                                                                                                                    |
-| `0x0009` | `GetLayout`                                            | `u32`                                                    | `LayoutChunk`                                        |                  | Get layout blob chunk. `u32` is the byte offset.                                                                                                                                       |
-| `0x000A` | `GetDeviceInfo`                                        | `()`                                                     | `DeviceInfo`                                         |                  | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                                                                               |
-| `0x000B` | `GetBuildInfo`                                         | `()`                                                     | `BuildInfo`                                          |                  | Application-defined diagnostic build label; never used for compatibility.                                                                                                              |
-| `0x000C` | `PeripheralBootloaderJump`                             | `u8`                                                     | `()`                                                 |                  | Ask the application to route a bootloader jump to one split peripheral.                                                                                                                |
-| `0x0101` | `GetKeyAction`                                         | `KeyPosition`                                            | `KeyAction`                                          |                  |                                                                                                                                                                                        |
-| `0x0102` | `SetKeyAction`                                         | `SetKeyRequest`                                          | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0103` | `GetDefaultLayer`                                      | `()`                                                     | `u8`                                                 |                  |                                                                                                                                                                                        |
-| `0x0104` | `SetDefaultLayer`                                      | `u8`                                                     | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0105` | `GetEncoderAction`                                     | `GetEncoderRequest`                                      | `EncoderAction`                                      |                  |                                                                                                                                                                                        |
-| `0x0106` | `SetEncoderAction`                                     | `SetEncoderRequest`                                      | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0107` | `GetKeymapBulk`                                        | `GetKeymapBulkRequest`                                   | `GetKeymapBulkResponse`                              |                  |                                                                                                                                                                                        |
-| `0x0108` | `SetKeymapBulk`                                        | `SetKeymapBulkRequest`                                   | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0201` | `GetMacro`                                             | `GetMacroRequest`                                        | `MacroData`                                          |                  |                                                                                                                                                                                        |
-| `0x0202` | `SetMacro`                                             | `SetMacroRequest`                                        | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0301` | `GetCombo`                                             | `u8`                                                     | `Combo`                                              |                  |                                                                                                                                                                                        |
-| `0x0302` | `SetCombo`                                             | `SetComboRequest`                                        | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0303` | `GetComboBulk`                                         | `GetComboBulkRequest`                                    | `GetComboBulkResponse`                               |                  |                                                                                                                                                                                        |
-| `0x0304` | `SetComboBulk`                                         | `SetComboBulkRequest`                                    | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0401` | `GetMorse`                                             | `u8`                                                     | `Morse`                                              |                  |                                                                                                                                                                                        |
-| `0x0402` | `SetMorse`                                             | `SetMorseRequest`                                        | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0403` | `GetMorseBulk`                                         | `GetMorseBulkRequest`                                    | `GetMorseBulkResponse`                               |                  |                                                                                                                                                                                        |
-| `0x0404` | `SetMorseBulk`                                         | `SetMorseBulkRequest`                                    | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0501` | `GetFork`                                              | `u8`                                                     | `Fork`                                               |                  |                                                                                                                                                                                        |
-| `0x0502` | `SetFork`                                              | `SetForkRequest`                                         | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0601` | `GetBehaviorConfig`                                    | `()`                                                     | `BehaviorConfig`                                     |                  |                                                                                                                                                                                        |
-| `0x0602` | `SetBehaviorConfig`                                    | `BehaviorConfig`                                         | `()`                                                 |                  |                                                                                                                                                                                        |
-| `0x0701` | `GetConnectionType`                                    | `()`                                                     | `ConnectionType`                                     |                  |                                                                                                                                                                                        |
-| `0x0702` | `GetConnectionStatus`                                  | `()`                                                     | `ConnectionStatus`                                   |                  | Full `ConnectionStatus` snapshot.                                                                                                                                                      |
-| `0x0703` | `GetBleStatus`                                         | `()`                                                     | `BleStatus`                                          | `_ble`           |                                                                                                                                                                                        |
-| `0x0704` | `SwitchBleProfile`                                     | `u8`                                                     | `()`                                                 | `_ble`           |                                                                                                                                                                                        |
-| `0x0705` | `ClearBleProfile`                                      | `u8`                                                     | `()`                                                 | `_ble`           |                                                                                                                                                                                        |
-| `0x0706` | `GetSplitCentralLatency`                               | `()`                                                     | `SplitCentralLatencyState`                           | `_ble` + `split` | Read the volatile active-mode policy, current USB-power selection, and effective value.                                                                                                |
-| `0x0707` | `SetSplitCentralLatency`                               | `SplitCentralLatencyPolicy`                              | `SplitCentralLatencyState`                           | `_ble` + `split` | Replace the volatile policy. Each connection-event count must be `0..=499`.                                                                                                            |
-| `0x0801` | `GetCurrentLayer`                                      | `()`                                                     | `u8`                                                 |                  |                                                                                                                                                                                        |
-| `0x0802` | `GetMatrixState`                                       | `()`                                                     | `MatrixState`                                        |                  |                                                                                                                                                                                        |
-| `0x0803` | `GetBatteryStatus`                                     | `()`                                                     | `BatteryStatus`                                      | `_ble`           |                                                                                                                                                                                        |
-| `0x0804` | `GetPeripheralStatus`                                  | `u8`                                                     | `PeripheralStatus`                                   | `split`          |                                                                                                                                                                                        |
-| `0x0805` | `GetWpm`                                               | `()`                                                     | `u16`                                                |                  | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                                                                               |
-| `0x0806` | `GetSleepState`                                        | `()`                                                     | `bool`                                               |                  | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                                                                                       |
-| `0x0807` | `GetLedIndicator`                                      | `()`                                                     | `LedIndicator`                                       |                  | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                                                                           |
-| `0x0808` | `GetLayerState`                                        | `()`                                                     | `LayerState`                                         |                  | Default layer and complete active-layer bitmap.                                                                                                                                        |
-| `0x0809` | `GetModifierState`                                     | `()`                                                     | `ModifierCombination`                                |                  | Final resolved modifier bitmap used by the HID keyboard report.                                                                                                                        |
-| `0x0901` | `GetLightingCapabilities`                              | `()`                                                     | `LightingCapabilitiesResult`                         | `lighting`       |                                                                                                                                                                                        |
-| `0x0902` | `GetLightingState`                                     | `()`                                                     | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
-| `0x0903` | `SetLightingState`                                     | `SetLightingStateRequest`                                | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
-| `0x0904` | `GetLightingPhysicalKeys`                              | `LightingPageRequest`                                    | `LightingPhysicalKeysPageResult`                     | `lighting`       |                                                                                                                                                                                        |
-| `0x0905` | `GetLightingLeds`                                      | `LightingPageRequest`                                    | `LightingLedsPageResult`                             | `lighting`       |                                                                                                                                                                                        |
-| `0x0906` | `GetLightingZones`                                     | `LightingPageRequest`                                    | `LightingZonesPageResult`                            | `lighting`       |                                                                                                                                                                                        |
-| `0x0907` | `GetLightingZoneMemberships`                           | `LightingPageRequest`                                    | `LightingZoneMembershipsPageResult`                  | `lighting`       |                                                                                                                                                                                        |
-| `0x0908` | `GetLightingOutputs`                                   | `LightingPageRequest`                                    | `LightingOutputsPageResult`                          | `lighting`       |                                                                                                                                                                                        |
-| `0x0909` | `GetLightingRoutes`                                    | `LightingPageRequest`                                    | `LightingRoutesPageResult`                           | `lighting`       |                                                                                                                                                                                        |
-| `0x090A` | `SetLightingOverlay`                                   | `SetLightingOverlayRequest`                              | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
-| `0x090B` | `UnsetLightingOverlay`                                 | `UnsetLightingOverlayRequest`                            | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
-| `0x090C` | `ClearLightingOverlay`                                 | `ClearLightingOverlayRequest`                            | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
-| `0x090D` | `BeginLightingOverlayReplace`                          | `BeginLightingOverlayReplaceRequest`                     | `LightingOverlayTransactionResult`                   | `lighting`       |                                                                                                                                                                                        |
-| `0x090E` | `PutLightingOverlayChunk`                              | `PutLightingOverlayChunkRequest`                         | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                        |
-| `0x090F` | `CommitLightingOverlayReplace`                         | `CommitLightingOverlayReplaceRequest`                    | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
-| `0x0910` | `AbortLightingOverlayReplace`                          | `AbortLightingOverlayReplaceRequest`                     | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                        |
-| `0x0911` | `GetLightingKeys`                                      | `LightingPageRequest`                                    | `LightingKeysPageResult`                             | `lighting`       | Logical matrix keys are distinct from optional physical geometry.                                                                                                                      |
-| `0x0912` | `GetLightingSceneStatus`                               | `()`                                                     | `LightingSceneStatusResult`                          | `lighting`       | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts.                                                         |
-| `0x0913` | `GetLightingScenes`                                    | `LightingScenePageRequest`                               | `LightingScenesPageResult`                           | `lighting`       | Scene pages are pinned to `LightingState.revision` for consistency.                                                                                                                    |
-| `0x0914` | `SetLightingSceneCell`                                 | `SetLightingSceneCellRequest`                            | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
-| `0x0915` | `UnsetLightingSceneCell`                               | `UnsetLightingSceneCellRequest`                          | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
-| `0x0916` | `BeginLightingSceneReplace`                            | `BeginLightingSceneReplaceRequest`                       | `LightingSceneTransactionResult`                     | `lighting`       |                                                                                                                                                                                        |
-| `0x0917` | `PutLightingSceneChunk`                                | `PutLightingSceneChunkRequest`                           | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                        |
-| `0x0918` | `CommitLightingSceneReplace`                           | `CommitLightingSceneReplaceRequest`                      | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
-| `0x0919` | `AbortLightingSceneReplace`                            | `AbortLightingSceneReplaceRequest`                       | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                        |
-| `0x091A` | `SetLightingLayerPolicy`                               | `SetLightingLayerPolicyRequest`                          | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
-| `0x091B` | `GetLightingOverlay`                                   | `LightingOverlayPageRequest`                             | `LightingOverlayPageResult`                          | `lighting`       | Overlay pages are pinned to `LightingState.revision` for consistency.                                                                                                                  |
-| `0x091C` | `GetLightingCompiledSceneStatus`                       | `()`                                                     | `LightingCompiledSceneStatusResult`                  | `lighting`       | Discover the immutable board-compiled layer-scene source.                                                                                                                              |
-| `0x091D` | `GetLightingCompiledScenes`                            | `LightingPageRequest`                                    | `LightingCompiledScenesPageResult`                   | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                                                                                     |
-| `0x091E` | `GetLightingConditionalSceneStatus`                    | `()`                                                     | `LightingConditionalSceneStatusResult`               | `lighting`       | Discover immutable conditional lighting compiled from board config.                                                                                                                    |
-| `0x091F` | `GetLightingConditionalScenes`                         | `LightingPageRequest`                                    | `LightingConditionalScenesPageResult`                | `lighting`       | Conditional-scene pages are pinned to the firmware topology revision.                                                                                                                  |
-| `0x0920` | `GetLightingOutputMode`                                | `()`                                                     | `LightingOutputModeStateResult`                      | `lighting`       | Read the configured three-state output policy and its live state.                                                                                                                      |
-| `0x0921` | `GetLightingExtension`                                 | `()`                                                     | `LightingExtensionResult`                            | `lighting`       | Discover the animated extension band: name-list sizes and selection.                                                                                                                   |
-| `0x0922` | `GetLightingExtensionNames`                            | `LightingExtensionNamesRequest`                          | `LightingExtensionNamesPageResult`                   | `lighting`       | Extension names are static per firmware build; page until `total`.                                                                                                                     |
-| `0x0923` | `SetLightingExtensionState`                            | `SetLightingExtensionStateRequest`                       | `LightingStateResult`                                | `lighting`       | Replace the extension selection when the state revision matches.                                                                                                                       |
-| `0x0924` | `SetLightingOutputMode`                                | `SetLightingOutputModeRequest`                           | `LightingOutputModeStateResult`                      | `lighting`       | Set the three-state output policy with optimistic concurrency.                                                                                                                         |
-| `0x0925` | `GetLightingRuntimeConditionalSceneStatus`             | `()`                                                     | `LightingRuntimeConditionalSceneStatusResult`        | `lighting`       | Discover the mutable ordered conditional-scene table.                                                                                                                                  |
-| `0x0926` | `GetLightingRuntimeConditionalScenes`                  | `LightingRuntimeConditionalScenePageRequest`             | `LightingRuntimeConditionalScenesPageResult`         | `lighting`       | Runtime conditional pages are pinned to `LightingState.revision`. Connection predicates are omitted; use the extended read command when `RUNTIME_CONNECTION_CONDITIONS` is advertised. |
-| `0x0927` | `BeginLightingRuntimeConditionalSceneReplace`          | `BeginLightingRuntimeConditionalSceneReplaceRequest`     | `LightingRuntimeConditionalSceneTransactionResult`   | `lighting`       |                                                                                                                                                                                        |
-| `0x0928` | `PutLightingRuntimeConditionalSceneChunk`              | `PutLightingRuntimeConditionalSceneChunkRequest`         | `LightingUnitResult`                                 | `lighting`       | Cells written through this legacy endpoint have no connection predicate.                                                                                                               |
-| `0x0929` | `CommitLightingRuntimeConditionalSceneReplace`         | `CommitLightingRuntimeConditionalSceneReplaceRequest`    | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                        |
-| `0x092A` | `AbortLightingRuntimeConditionalSceneReplace`          | `AbortLightingRuntimeConditionalSceneReplaceRequest`     | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                        |
-| `0x092B` | `GetLightingExtensionParams`                           | `LightingExtensionParamsRequest`                         | `LightingExtensionParamsPageResult`                  | `lighting`       | Per-effect tunable parameters: descriptors plus live values, pinned to `LightingState.revision`. Page until `total`.                                                                   |
-| `0x092C` | `SetLightingExtensionParam`                            | `SetLightingExtensionParamRequest`                       | `LightingStateResult`                                | `lighting`       | Set one effect parameter when the state revision matches.                                                                                                                              |
-| `0x092D` | `SetLightingWakeLayers`                                | `SetLightingWakeLayersRequest`                           | `LightingOutputModeStateResult`                      | `lighting`       | Replace the wake-layer mask. Policy rather than lighting content, but dynamic so which layers wake lighting is not a firmware rebuild.                                                 |
-| `0x092E` | `GetLightingExtensionLayers`                           | `()`                                                     | `LightingExtensionLayersResult`                      | `lighting`       | Read the optional second effect layered over the primary extension.                                                                                                                    |
-| `0x092F` | `SetLightingExtensionLayers`                           | `SetLightingExtensionLayersRequest`                      | `LightingStateResult`                                | `lighting`       | Replace the optional second effect when the state revision matches.                                                                                                                    |
-| `0x0930` | `GetLightingExtendedRuntimeConditionalSceneStatus`     | `()`                                                     | `LightingRuntimeConditionalSceneStatusResult`        | `lighting`       | Discover connection-aware runtime conditional limits and occupancy.                                                                                                                    |
-| `0x0931` | `GetLightingExtendedRuntimeConditionalScenes`          | `LightingRuntimeConditionalScenePageRequest`             | `LightingExtendedRuntimeConditionalScenesPageResult` | `lighting`       | Read connection-aware runtime conditional cells under a pinned state revision.                                                                                                         |
-| `0x0932` | `BeginLightingExtendedRuntimeConditionalSceneReplace`  | `BeginLightingRuntimeConditionalSceneReplaceRequest`     | `LightingRuntimeConditionalSceneTransactionResult`   | `lighting`       | Begin an atomic replacement using extended conditional cells.                                                                                                                          |
-| `0x0933` | `PutLightingExtendedRuntimeConditionalSceneChunk`      | `PutLightingExtendedRuntimeConditionalSceneChunkRequest` | `LightingUnitResult`                                 | `lighting`       | Stage connection-aware cells for an extended replacement.                                                                                                                              |
-| `0x0934` | `CommitLightingExtendedRuntimeConditionalSceneReplace` | `CommitLightingRuntimeConditionalSceneReplaceRequest`    | `LightingStateResult`                                | `lighting`       | Publish a complete extended conditional-table replacement.                                                                                                                             |
-| `0x0935` | `AbortLightingExtendedRuntimeConditionalSceneReplace`  | `AbortLightingRuntimeConditionalSceneReplaceRequest`     | `LightingUnitResult`                                 | `lighting`       | Discard an extended conditional-table replacement.                                                                                                                                     |
+| CMD      | Name                                                   | Request                                                  | Response                                             | Feature          | Notes                                                                                                                                                                                                                                                                                                              |
+| -------- | ------------------------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `0x0001` | `GetVersion`                                           | `()`                                                     | `ProtocolVersion`                                    |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0002` | `GetCapabilities`                                      | `()`                                                     | `DeviceCapabilities`                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0003` | `Reboot`                                               | `()`                                                     | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0004` | `BootloaderJump`                                       | `()`                                                     | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0005` | `StorageReset`                                         | `StorageResetMode`                                       | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0006` | `GetLockStatus`                                        | `()`                                                     | `LockStatus`                                         |                  | Pure read of the current lock state — no side effects.                                                                                                                                                                                                                                                             |
+| `0x0007` | `UnlockPoll`                                           | `()`                                                     | `LockStatus`                                         |                  | Arms/refreshes the unlock attempt and samples the held challenge keys.                                                                                                                                                                                                                                             |
+| `0x0008` | `Lock`                                                 | `()`                                                     | `()`                                                 |                  | Relock immediately.                                                                                                                                                                                                                                                                                                |
+| `0x0009` | `GetLayout`                                            | `u32`                                                    | `LayoutChunk`                                        |                  | Get layout blob chunk. `u32` is the byte offset.                                                                                                                                                                                                                                                                   |
+| `0x000A` | `GetDeviceInfo`                                        | `()`                                                     | `DeviceInfo`                                         |                  | Identity strings and USB ids; feature gating stays in `GetCapabilities`.                                                                                                                                                                                                                                           |
+| `0x000B` | `GetBuildInfo`                                         | `()`                                                     | `BuildInfo`                                          |                  | Application-defined diagnostic build label; never used for compatibility.                                                                                                                                                                                                                                          |
+| `0x000C` | `PeripheralBootloaderJump`                             | `u8`                                                     | `()`                                                 |                  | Ask the application to route a bootloader jump to one split peripheral.                                                                                                                                                                                                                                            |
+| `0x0101` | `GetKeyAction`                                         | `KeyPosition`                                            | `KeyAction`                                          |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0102` | `SetKeyAction`                                         | `SetKeyRequest`                                          | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0103` | `GetDefaultLayer`                                      | `()`                                                     | `u8`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0104` | `SetDefaultLayer`                                      | `u8`                                                     | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0105` | `GetEncoderAction`                                     | `GetEncoderRequest`                                      | `EncoderAction`                                      |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0106` | `SetEncoderAction`                                     | `SetEncoderRequest`                                      | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0107` | `GetKeymapBulk`                                        | `GetKeymapBulkRequest`                                   | `GetKeymapBulkResponse`                              |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0108` | `SetKeymapBulk`                                        | `SetKeymapBulkRequest`                                   | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0201` | `GetMacro`                                             | `GetMacroRequest`                                        | `MacroData`                                          |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0202` | `SetMacro`                                             | `SetMacroRequest`                                        | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0301` | `GetCombo`                                             | `u8`                                                     | `Combo`                                              |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0302` | `SetCombo`                                             | `SetComboRequest`                                        | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0303` | `GetComboBulk`                                         | `GetComboBulkRequest`                                    | `GetComboBulkResponse`                               |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0304` | `SetComboBulk`                                         | `SetComboBulkRequest`                                    | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0401` | `GetMorse`                                             | `u8`                                                     | `Morse`                                              |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0402` | `SetMorse`                                             | `SetMorseRequest`                                        | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0403` | `GetMorseBulk`                                         | `GetMorseBulkRequest`                                    | `GetMorseBulkResponse`                               |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0404` | `SetMorseBulk`                                         | `SetMorseBulkRequest`                                    | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0501` | `GetFork`                                              | `u8`                                                     | `Fork`                                               |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0502` | `SetFork`                                              | `SetForkRequest`                                         | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0601` | `GetBehaviorConfig`                                    | `()`                                                     | `BehaviorConfig`                                     |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0602` | `SetBehaviorConfig`                                    | `BehaviorConfig`                                         | `()`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0701` | `GetConnectionType`                                    | `()`                                                     | `ConnectionType`                                     |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0702` | `GetConnectionStatus`                                  | `()`                                                     | `ConnectionStatus`                                   |                  | Full `ConnectionStatus` snapshot.                                                                                                                                                                                                                                                                                  |
+| `0x0703` | `GetBleStatus`                                         | `()`                                                     | `BleStatus`                                          | `_ble`           |                                                                                                                                                                                                                                                                                                                    |
+| `0x0704` | `SwitchBleProfile`                                     | `u8`                                                     | `()`                                                 | `_ble`           |                                                                                                                                                                                                                                                                                                                    |
+| `0x0705` | `ClearBleProfile`                                      | `u8`                                                     | `()`                                                 | `_ble`           |                                                                                                                                                                                                                                                                                                                    |
+| `0x0706` | `GetSplitCentralLatency`                               | `()`                                                     | `SplitCentralLatencyState`                           | `_ble` + `split` | Read the volatile active-mode policy, current USB-power selection, and effective value.                                                                                                                                                                                                                            |
+| `0x0707` | `SetSplitCentralLatency`                               | `SplitCentralLatencyPolicy`                              | `SplitCentralLatencyState`                           | `_ble` + `split` | Replace the volatile policy. Each connection-event count must be `0..=499`.                                                                                                                                                                                                                                        |
+| `0x0801` | `GetCurrentLayer`                                      | `()`                                                     | `u8`                                                 |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0802` | `GetMatrixState`                                       | `()`                                                     | `MatrixState`                                        |                  |                                                                                                                                                                                                                                                                                                                    |
+| `0x0803` | `GetBatteryStatus`                                     | `()`                                                     | `BatteryStatus`                                      | `_ble`           |                                                                                                                                                                                                                                                                                                                    |
+| `0x0804` | `GetPeripheralStatus`                                  | `u8`                                                     | `PeripheralStatus`                                   | `split`          |                                                                                                                                                                                                                                                                                                                    |
+| `0x0805` | `GetWpm`                                               | `()`                                                     | `u16`                                                |                  | Latest WPM, sourced from the `WpmUpdate` topic snapshot.                                                                                                                                                                                                                                                           |
+| `0x0806` | `GetSleepState`                                        | `()`                                                     | `bool`                                               |                  | Latest sleep flag, sourced from the `SleepState` topic snapshot.                                                                                                                                                                                                                                                   |
+| `0x0807` | `GetLedIndicator`                                      | `()`                                                     | `LedIndicator`                                       |                  | Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.                                                                                                                                                                                                                                       |
+| `0x0808` | `GetLayerState`                                        | `()`                                                     | `LayerState`                                         |                  | Default layer and complete active-layer bitmap.                                                                                                                                                                                                                                                                    |
+| `0x0809` | `GetModifierState`                                     | `()`                                                     | `ModifierCombination`                                |                  | Final resolved modifier bitmap used by the HID keyboard report.                                                                                                                                                                                                                                                    |
+| `0x0901` | `GetLightingCapabilities`                              | `()`                                                     | `LightingCapabilitiesResult`                         | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0902` | `GetLightingState`                                     | `()`                                                     | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0903` | `SetLightingState`                                     | `SetLightingStateRequest`                                | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0904` | `GetLightingPhysicalKeys`                              | `LightingPageRequest`                                    | `LightingPhysicalKeysPageResult`                     | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0905` | `GetLightingLeds`                                      | `LightingPageRequest`                                    | `LightingLedsPageResult`                             | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0906` | `GetLightingZones`                                     | `LightingPageRequest`                                    | `LightingZonesPageResult`                            | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0907` | `GetLightingZoneMemberships`                           | `LightingPageRequest`                                    | `LightingZoneMembershipsPageResult`                  | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0908` | `GetLightingOutputs`                                   | `LightingPageRequest`                                    | `LightingOutputsPageResult`                          | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0909` | `GetLightingRoutes`                                    | `LightingPageRequest`                                    | `LightingRoutesPageResult`                           | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x090A` | `SetLightingOverlay`                                   | `SetLightingOverlayRequest`                              | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x090B` | `UnsetLightingOverlay`                                 | `UnsetLightingOverlayRequest`                            | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x090C` | `ClearLightingOverlay`                                 | `ClearLightingOverlayRequest`                            | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x090D` | `BeginLightingOverlayReplace`                          | `BeginLightingOverlayReplaceRequest`                     | `LightingOverlayTransactionResult`                   | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x090E` | `PutLightingOverlayChunk`                              | `PutLightingOverlayChunkRequest`                         | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x090F` | `CommitLightingOverlayReplace`                         | `CommitLightingOverlayReplaceRequest`                    | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0910` | `AbortLightingOverlayReplace`                          | `AbortLightingOverlayReplaceRequest`                     | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0911` | `GetLightingKeys`                                      | `LightingPageRequest`                                    | `LightingKeysPageResult`                             | `lighting`       | Logical matrix keys are distinct from optional physical geometry.                                                                                                                                                                                                                                                  |
+| `0x0912` | `GetLightingSceneStatus`                               | `()`                                                     | `LightingSceneStatusResult`                          | `lighting`       | Scene discovery lives outside `LightingCapabilities`/`LightingState` so their postcard layout stays stable for existing hosts.                                                                                                                                                                                     |
+| `0x0913` | `GetLightingScenes`                                    | `LightingScenePageRequest`                               | `LightingScenesPageResult`                           | `lighting`       | Scene pages are pinned to `LightingState.revision` for consistency.                                                                                                                                                                                                                                                |
+| `0x0914` | `SetLightingSceneCell`                                 | `SetLightingSceneCellRequest`                            | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0915` | `UnsetLightingSceneCell`                               | `UnsetLightingSceneCellRequest`                          | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0916` | `BeginLightingSceneReplace`                            | `BeginLightingSceneReplaceRequest`                       | `LightingSceneTransactionResult`                     | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0917` | `PutLightingSceneChunk`                                | `PutLightingSceneChunkRequest`                           | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0918` | `CommitLightingSceneReplace`                           | `CommitLightingSceneReplaceRequest`                      | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0919` | `AbortLightingSceneReplace`                            | `AbortLightingSceneReplaceRequest`                       | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x091A` | `SetLightingLayerPolicy`                               | `SetLightingLayerPolicyRequest`                          | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x091B` | `GetLightingOverlay`                                   | `LightingOverlayPageRequest`                             | `LightingOverlayPageResult`                          | `lighting`       | Overlay pages are pinned to `LightingState.revision` for consistency.                                                                                                                                                                                                                                              |
+| `0x091C` | `GetLightingCompiledSceneStatus`                       | `()`                                                     | `LightingCompiledSceneStatusResult`                  | `lighting`       | Discover the immutable board-compiled layer-scene source.                                                                                                                                                                                                                                                          |
+| `0x091D` | `GetLightingCompiledScenes`                            | `LightingPageRequest`                                    | `LightingCompiledScenesPageResult`                   | `lighting`       | Compiled-scene pages are pinned to the firmware topology revision.                                                                                                                                                                                                                                                 |
+| `0x091E` | `GetLightingConditionalSceneStatus`                    | `()`                                                     | `LightingConditionalSceneStatusResult`               | `lighting`       | Discover immutable conditional lighting compiled from board config.                                                                                                                                                                                                                                                |
+| `0x091F` | `GetLightingConditionalScenes`                         | `LightingPageRequest`                                    | `LightingConditionalScenesPageResult`                | `lighting`       | Conditional-scene pages are pinned to the firmware topology revision.                                                                                                                                                                                                                                              |
+| `0x0920` | `GetLightingOutputMode`                                | `()`                                                     | `LightingOutputModeStateResult`                      | `lighting`       | Read the configured three-state output policy and its live state.                                                                                                                                                                                                                                                  |
+| `0x0921` | `GetLightingExtension`                                 | `()`                                                     | `LightingExtensionResult`                            | `lighting`       | Discover the animated extension band: name-list sizes and selection.                                                                                                                                                                                                                                               |
+| `0x0922` | `GetLightingExtensionNames`                            | `LightingExtensionNamesRequest`                          | `LightingExtensionNamesPageResult`                   | `lighting`       | Extension names are static per firmware build; page until `total`.                                                                                                                                                                                                                                                 |
+| `0x0923` | `SetLightingExtensionState`                            | `SetLightingExtensionStateRequest`                       | `LightingStateResult`                                | `lighting`       | Replace the extension selection when the state revision matches.                                                                                                                                                                                                                                                   |
+| `0x0924` | `SetLightingOutputMode`                                | `SetLightingOutputModeRequest`                           | `LightingOutputModeStateResult`                      | `lighting`       | Set the three-state output policy with optimistic concurrency.                                                                                                                                                                                                                                                     |
+| `0x0925` | `GetLightingRuntimeConditionalSceneStatus`             | `()`                                                     | `LightingRuntimeConditionalSceneStatusResult`        | `lighting`       | Discover the mutable ordered conditional-scene table.                                                                                                                                                                                                                                                              |
+| `0x0926` | `GetLightingRuntimeConditionalScenes`                  | `LightingRuntimeConditionalScenePageRequest`             | `LightingRuntimeConditionalScenesPageResult`         | `lighting`       | Runtime conditional pages are pinned to `LightingState.revision`. Connection predicates are omitted; use the extended read command when `RUNTIME_CONNECTION_CONDITIONS` is advertised. A read-modify-write cycle performed entirely through the legacy commands therefore drops every stored connection predicate. |
+| `0x0927` | `BeginLightingRuntimeConditionalSceneReplace`          | `BeginLightingRuntimeConditionalSceneReplaceRequest`     | `LightingRuntimeConditionalSceneTransactionResult`   | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x0928` | `PutLightingRuntimeConditionalSceneChunk`              | `PutLightingRuntimeConditionalSceneChunkRequest`         | `LightingUnitResult`                                 | `lighting`       | Cells written through this legacy endpoint have no connection predicate.                                                                                                                                                                                                                                           |
+| `0x0929` | `CommitLightingRuntimeConditionalSceneReplace`         | `CommitLightingRuntimeConditionalSceneReplaceRequest`    | `LightingStateResult`                                | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x092A` | `AbortLightingRuntimeConditionalSceneReplace`          | `AbortLightingRuntimeConditionalSceneReplaceRequest`     | `LightingUnitResult`                                 | `lighting`       |                                                                                                                                                                                                                                                                                                                    |
+| `0x092B` | `GetLightingExtensionParams`                           | `LightingExtensionParamsRequest`                         | `LightingExtensionParamsPageResult`                  | `lighting`       | Per-effect tunable parameters: descriptors plus live values, pinned to `LightingState.revision`. Page until `total`.                                                                                                                                                                                               |
+| `0x092C` | `SetLightingExtensionParam`                            | `SetLightingExtensionParamRequest`                       | `LightingStateResult`                                | `lighting`       | Set one effect parameter when the state revision matches.                                                                                                                                                                                                                                                          |
+| `0x092D` | `SetLightingWakeLayers`                                | `SetLightingWakeLayersRequest`                           | `LightingOutputModeStateResult`                      | `lighting`       | Replace the wake-layer mask. Policy rather than lighting content, but dynamic so which layers wake lighting is not a firmware rebuild.                                                                                                                                                                             |
+| `0x092E` | `GetLightingExtensionLayers`                           | `()`                                                     | `LightingExtensionLayersResult`                      | `lighting`       | Read the optional second effect layered over the primary extension.                                                                                                                                                                                                                                                |
+| `0x092F` | `SetLightingExtensionLayers`                           | `SetLightingExtensionLayersRequest`                      | `LightingStateResult`                                | `lighting`       | Replace the optional second effect when the state revision matches.                                                                                                                                                                                                                                                |
+| `0x0930` | `GetLightingExtendedRuntimeConditionalSceneStatus`     | `()`                                                     | `LightingRuntimeConditionalSceneStatusResult`        | `lighting`       | Discover connection-aware runtime conditional limits and occupancy.                                                                                                                                                                                                                                                |
+| `0x0931` | `GetLightingExtendedRuntimeConditionalScenes`          | `LightingRuntimeConditionalScenePageRequest`             | `LightingExtendedRuntimeConditionalScenesPageResult` | `lighting`       | Read connection-aware runtime conditional cells under a pinned state revision.                                                                                                                                                                                                                                     |
+| `0x0932` | `BeginLightingExtendedRuntimeConditionalSceneReplace`  | `BeginLightingRuntimeConditionalSceneReplaceRequest`     | `LightingRuntimeConditionalSceneTransactionResult`   | `lighting`       | Begin an atomic replacement using extended conditional cells.                                                                                                                                                                                                                                                      |
+| `0x0933` | `PutLightingExtendedRuntimeConditionalSceneChunk`      | `PutLightingExtendedRuntimeConditionalSceneChunkRequest` | `LightingUnitResult`                                 | `lighting`       | Stage connection-aware cells for an extended replacement.                                                                                                                                                                                                                                                          |
+| `0x0934` | `CommitLightingExtendedRuntimeConditionalSceneReplace` | `CommitLightingRuntimeConditionalSceneReplaceRequest`    | `LightingStateResult`                                | `lighting`       | Publish a complete extended conditional-table replacement.                                                                                                                                                                                                                                                         |
+| `0x0935` | `AbortLightingExtendedRuntimeConditionalSceneReplace`  | `AbortLightingRuntimeConditionalSceneReplaceRequest`     | `LightingUnitResult`                                 | `lighting`       | Discard an extended conditional-table replacement.                                                                                                                                                                                                                                                                 |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index e801c0d99..86ee7a873 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -471,7 +471,9 @@ endpoints! {
     GetLightingRuntimeConditionalSceneStatus = 0x0925: () => LightingRuntimeConditionalSceneStatusResult;
     /// Runtime conditional pages are pinned to `LightingState.revision`.
     /// Connection predicates are omitted; use the extended read command when
-    /// `RUNTIME_CONNECTION_CONDITIONS` is advertised.
+    /// `RUNTIME_CONNECTION_CONDITIONS` is advertised. A read-modify-write
+    /// cycle performed entirely through the legacy commands therefore drops
+    /// every stored connection predicate.
     #[cfg(feature = "lighting")]
     GetLightingRuntimeConditionalScenes = 0x0926: LightingRuntimeConditionalScenePageRequest => LightingRuntimeConditionalScenesPageResult;
     #[cfg(feature = "lighting")]
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 6222bee20..66a582135 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -609,6 +609,13 @@ impl Handle<PutLightingExtendedRuntimeConditionalSceneChunk> for RynkService<'_>
             {
                 return Ok(Err(LightingError::InvalidRequest));
             }
+            #[cfg(feature = "_ble")]
+            if let Some(connection) = cell.connection
+                && let Some(profile) = connection.profile
+                && (profile as usize) >= crate::NUM_BLE_PROFILE
+            {
+                return Ok(Err(LightingError::InvalidRequest));
+            }
         }
         Ok(match runtime_conditional_scene_controller(self) {
             Ok(controller) => match controller
@@ -2046,6 +2053,60 @@ mod tests {
         });
     }
 
+    #[cfg(feature = "_ble")]
+    #[test]
+    fn extended_chunk_rejects_out_of_range_connection_profile() {
+        block_on(async {
+            let mut behavior = BehaviorConfig::default();
+            let positional: PositionalConfig<1, 3> = PositionalConfig::default();
+            let mut data: KeymapData<1, 3, 1, 0> = KeymapData::new([[[KeyAction::No; 3]]]);
+            let keymap = KeyMap::new(&mut data, &mut behavior, &positional).await;
+            let mut config = RmkConfig::default();
+            config.lock_config.insecure = true;
+            let mailbox = RynkLightingMailbox::new();
+            let service = RynkService::new(&keymap, &config).with_lighting(RynkLightingController::new(
+                &mailbox,
+                descriptor(),
+                8,
+            ));
+            let session = session();
+            let cell = rmk_types::protocol::rynk::LightingExtendedConditionalSceneCell {
+                cell: LightingConditionalSceneCell {
+                    conditions: rmk_types::protocol::rynk::LightingConditionSet {
+                        layer: None,
+                        battery: None,
+                        output_mode: None,
+                    },
+                    led_id: LightingLedId(42),
+                    effect: rmk_types::protocol::rynk::LightingEffect::Solid {
+                        color: rmk_types::protocol::rynk::LightingRgb8 { r: 3, g: 4, b: 5 },
+                    },
+                },
+                connection: Some(rmk_types::protocol::rynk::LightingConnectionCondition {
+                    transport: None,
+                    profile: Some(crate::NUM_BLE_PROFILE as u8),
+                    ble_state: None,
+                }),
+            };
+            let mut cells = Vec::new();
+            cells.push(cell).unwrap();
+            // Cell validation precedes transaction lookup, so the bogus
+            // transaction id proves rejection came from the profile check.
+            let response = call::<PutLightingExtendedRuntimeConditionalSceneChunk>(
+                &service,
+                &session,
+                &PutLightingExtendedRuntimeConditionalSceneChunkRequest {
+                    transaction_id: 999,
+                    offset: 0,
+                    cells,
+                },
+            )
+            .await
+            .unwrap();
+            assert_eq!(response, Err(LightingError::InvalidRequest));
+        });
+    }
+
     fn wire_scene_cell(layer: u8, led: u16) -> rmk_types::protocol::rynk::LightingSceneCell {
         rmk_types::protocol::rynk::LightingSceneCell {
             layer,
diff --git a/rmk/src/storage/mod.rs b/rmk/src/storage/mod.rs
index 9360722e1..514a0ad44 100644
--- a/rmk/src/storage/mod.rs
+++ b/rmk/src/storage/mod.rs
@@ -706,6 +706,37 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
         Some(record.policy)
     }
 
+    /// Persist the V2 runtime conditional table length, and empty the legacy
+    /// table alongside it so a firmware downgrade sees no rules rather than
+    /// stale pre-upgrade cells that were edited or deleted under V2.
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    async fn store_lighting_runtime_conditional_table(&mut self, len: u16) -> Result<(), SSError<F::Error>> {
+        match self
+            .fetch_data(StorageKey::LightingRuntimeConditionalSceneTableV2)
+            .await
+        {
+            Some(StorageData::LightingRuntimeConditionalSceneTableV2(saved)) if saved == len => (),
+            _ => {
+                self.store_data(
+                    StorageKey::LightingRuntimeConditionalSceneTableV2,
+                    &StorageData::LightingRuntimeConditionalSceneTableV2(len),
+                )
+                .await?
+            }
+        }
+        if let Some(StorageData::LightingRuntimeConditionalSceneTable(saved)) =
+            self.fetch_data(StorageKey::LightingRuntimeConditionalSceneTable).await
+            && saved != 0
+        {
+            self.store_data(
+                StorageKey::LightingRuntimeConditionalSceneTable,
+                &StorageData::LightingRuntimeConditionalSceneTable(0),
+            )
+            .await?
+        }
+        Ok(())
+    }
+
     /// Read the persisted ordered runtime conditional table at startup.
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     pub async fn read_lighting_runtime_conditional_scenes<const CAP: usize>(
@@ -1112,19 +1143,7 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
                 }
                 #[cfg(all(feature = "lighting", feature = "rynk"))]
                 FlashOperationMessage::LightingRuntimeConditionalSceneTable { len } => {
-                    match self
-                        .fetch_data(StorageKey::LightingRuntimeConditionalSceneTableV2)
-                        .await
-                    {
-                        Some(StorageData::LightingRuntimeConditionalSceneTableV2(saved)) if saved == len => Ok(()),
-                        _ => {
-                            self.store_data(
-                                StorageKey::LightingRuntimeConditionalSceneTableV2,
-                                &StorageData::LightingRuntimeConditionalSceneTableV2(len),
-                            )
-                            .await
-                        }
-                    }
+                    self.store_lighting_runtime_conditional_table(len).await
                 }
                 #[cfg(all(feature = "lighting", feature = "rynk"))]
                 FlashOperationMessage::LightingRuntimeConditionalSceneShard { index, cells } => {
@@ -1396,6 +1415,45 @@ mod tests {
         });
     }
 
+    #[cfg(all(feature = "lighting", feature = "rynk"))]
+    #[test]
+    fn v2_table_write_empties_the_legacy_table() {
+        block_on(async {
+            type Flash = TestFlash<16_384, 4_096, 1>;
+
+            let storage_range = (16_384 - 2 * 4_096) as u32..16_384u32;
+            let mut map =
+                MapStorage::<StorageKey, _, _>::new(Flash::new(), MapConfig::new(storage_range), Cache::new_uncached());
+            let mut buffer = [0u8; get_buffer_size()];
+            map.store_item(
+                &mut buffer,
+                &StorageKey::LightingRuntimeConditionalSceneTable,
+                &StorageData::LightingRuntimeConditionalSceneTable(3),
+            )
+            .await
+            .unwrap();
+
+            let mut storage = Storage::<Flash, 0, 0, 0, 0> { flash: map, buffer };
+            storage.store_lighting_runtime_conditional_table(1).await.unwrap();
+
+            assert!(matches!(
+                storage
+                    .fetch_data(StorageKey::LightingRuntimeConditionalSceneTableV2)
+                    .await,
+                Some(StorageData::LightingRuntimeConditionalSceneTableV2(1))
+            ));
+            assert!(
+                matches!(
+                    storage
+                        .fetch_data(StorageKey::LightingRuntimeConditionalSceneTable)
+                        .await,
+                    Some(StorageData::LightingRuntimeConditionalSceneTable(0))
+                ),
+                "a downgraded firmware must see an empty legacy table"
+            );
+        });
+    }
+
     #[cfg(all(feature = "lighting", feature = "rynk"))]
     #[test]
     fn extended_runtime_conditional_records_preserve_connection_condition() {

From b539e1258233d2f4f7d4d79c064e9d2092890962 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 19:11:16 -0700
Subject: [PATCH 64/78] fix(macro): emit the connection field in compiled
 condition sets

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk-macro/src/codegen/lighting.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
index 703dc7b9d..3920fd692 100644
--- a/rmk-macro/src/codegen/lighting.rs
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -367,6 +367,7 @@ fn expand_conditional_scene_cell(cell: &LightingConditionalSceneCell) -> TokenSt
                 layer: #layer,
                 battery: #battery,
                 output_mode: #output_mode,
+                connection: ::core::option::Option::None,
             },
             slot: ::rmk::lighting::LedSlot(#slot),
             effect: #effect,

From 7506bb457af86434172fd13ca428fe1dd8ba8f17 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 19:16:55 -0700
Subject: [PATCH 65/78] feat(lighting): expose last-rule condition amendment on
 the runtime table

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/lighting/standard/conditional.rs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/rmk/src/lighting/standard/conditional.rs b/rmk/src/lighting/standard/conditional.rs
index e6f720a53..167c76c3c 100644
--- a/rmk/src/lighting/standard/conditional.rs
+++ b/rmk/src/lighting/standard/conditional.rs
@@ -138,6 +138,14 @@ impl<const CAP: usize> RuntimeConditionalSceneTable<CAP> {
         Ok(())
     }
 
+    /// Mutable access to the most recently pushed rule's conditions, for
+    /// stream decoders that amend a cell after its base record arrives.
+    pub fn last_conditions_mut(&mut self) -> Option<&mut ConditionSet> {
+        self.len
+            .checked_sub(1)
+            .map(move |index| &mut self.cells[index].conditions)
+    }
+
     pub fn clear(&mut self) {
         self.len = 0;
         self.pool.clear();

From 7e7bc68db57e1ade5a39a569013f5a01dff1a06c Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 19:55:10 -0700
Subject: [PATCH 66/78] feat(lighting): gate conditional rules on the extension
 being on

An extension is enabled while its ExtensionState value is non-zero, which
is exactly what RgbTog flips. Nothing could observe that, so a key bound
to the toggle had no way to show its own state: its cell painted the same
colour whether effects were rendering or blanked.

Add an `effects` predicate to ConditionSet, answered from the extension
source the engine already holds. Compiled rules pass None and so stay
unsatisfiable, on the same grounds as output_mode: a source that cannot
observe the state must not let either polarity fire.

The predicate rides the extended conditional cell, which changes that
cell's encoding rather than merely adding a field to it. Firmware
advertising only RUNTIME_CONNECTION_CONDITIONS speaks the earlier cell,
so RUNTIME_EFFECTS_CONDITIONS describes the new encoding and a host that
cannot see it must fall back to the legacy endpoints. The added predicate
also costs a cell one byte, so an extended page now holds five.

Persisted V2 tables written by the earlier extended cell no longer parse
-- the shrunk chunk alone would have done that -- and fetch_data reports
a failed record as absent, so such a table boots empty and is restored by
the host's next apply rather than misparsed into stale rules.
---
 rmk-macro/src/codegen/lighting.rs             |  1 +
 .../src/protocol/rynk/payload/lighting.rs     | 22 ++++-
 .../rynk/snapshots/lighting_wire_frames.snap  |  6 +-
 rmk-types/src/protocol/rynk/tests.rs          |  1 +
 rmk/src/host/rynk/handlers/lighting.rs        |  8 +-
 rmk/src/host/rynk/lighting.rs                 | 14 +++
 rmk/src/lighting/mod.rs                       |  6 +-
 rmk/src/lighting/source.rs                    | 75 ++++++++++++---
 rmk/src/lighting/standard/conditional.rs      | 29 ++++--
 rmk/src/lighting/standard/engine.rs           |  6 +-
 rmk/src/lighting/standard/tests.rs            | 92 ++++++++++++++++++-
 rmk/src/storage/mod.rs                        |  7 +-
 rynk/src/api.rs                               |  8 +-
 13 files changed, 240 insertions(+), 35 deletions(-)

diff --git a/rmk-macro/src/codegen/lighting.rs b/rmk-macro/src/codegen/lighting.rs
index 3920fd692..aeeb94091 100644
--- a/rmk-macro/src/codegen/lighting.rs
+++ b/rmk-macro/src/codegen/lighting.rs
@@ -368,6 +368,7 @@ fn expand_conditional_scene_cell(cell: &LightingConditionalSceneCell) -> TokenSt
                 battery: #battery,
                 output_mode: #output_mode,
                 connection: ::core::option::Option::None,
+                effects: ::core::option::Option::None,
             },
             slot: ::rmk::lighting::LedSlot(#slot),
             effect: #effect,
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 5dc2f9b29..e95f6bc95 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -21,8 +21,10 @@ pub const LIGHTING_OVERLAY_CHUNK_SIZE: usize = 8;
 pub const LIGHTING_SCENE_CHUNK_SIZE: usize = 8;
 /// Number of immutable conditional cells in one readback page.
 pub const LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 7;
-/// Number of connection-aware conditional cells in one extended page/chunk.
-pub const LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 6;
+/// Number of connection- and effects-aware conditional cells in one extended
+/// page/chunk. Lower than the legacy chunk because each cell carries the two
+/// added predicates and the page still has to fit `LIGHTING_PAYLOAD_SIZE`.
+pub const LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 5;
 /// Maximum UTF-8 byte length of a zone name.
 pub const LIGHTING_ZONE_NAME_SIZE: usize = 24;
 /// Maximum UTF-8 byte length of one extension effect or palette name.
@@ -212,6 +214,12 @@ impl LightingFeatureFlags {
     /// Runtime conditional rules can match transport and BLE connection state
     /// through the extended conditional-scene endpoints.
     pub const RUNTIME_CONNECTION_CONDITIONS: u16 = 1 << 14;
+    /// The extended conditional-scene cell also carries an effects predicate.
+    /// This bit describes the cell's encoding, not just an added predicate:
+    /// firmware advertising only `RUNTIME_CONNECTION_CONDITIONS` speaks the
+    /// earlier extended cell, so a host that cannot see this bit must use the
+    /// legacy endpoints rather than risk a misparse.
+    pub const RUNTIME_EFFECTS_CONDITIONS: u16 = 1 << 15;
 
     pub const fn contains(self, bits: u16) -> bool {
         self.0 & bits == bits
@@ -678,12 +686,21 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Gate on whether the extension band is rendering. An extension is
+    /// enabled while its value is non-zero, so this tracks `RgbTog`.
+    pub struct LightingEffectsCondition {
+        pub enabled: bool,
+    }
+}
+
 wire_type! {
     /// Additive runtime conditional cell used by the extended endpoints. The
     /// nested legacy cell keeps its established postcard field order intact.
     pub struct LightingExtendedConditionalSceneCell {
         pub cell: LightingConditionalSceneCell,
         pub connection: Option<LightingConnectionCondition>,
+        pub effects: Option<LightingEffectsCondition>,
     }
 }
 
@@ -1482,6 +1499,7 @@ mod tests {
                 profile: Some(3),
                 ble_state: Some(BleState::Connected),
             }),
+            effects: Some(LightingEffectsCondition { enabled: true }),
         };
         round_trip(&cell);
 
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index 10612fc20..a275aa6bd 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -37,9 +37,9 @@ GetLightingCompiledSceneStatus reply                          04 1c 09 01 01 03
 GetLightingCompiledSceneStatus request                        04 1c 09 01 00
 GetLightingCompiledScenes reply                               04 1d 09 01 01 06 01 01 01 02 2a 04 07 08 09 00
 GetLightingCompiledScenes request                             05 1d 09 01 01 01 00
-GetLightingExtendedRuntimeConditionalSceneStatus reply        04 30 09 01 01 05 09 40 01 06 00
+GetLightingExtendedRuntimeConditionalSceneStatus reply        04 30 09 01 01 05 09 40 01 05 00
 GetLightingExtendedRuntimeConditionalSceneStatus request      04 30 09 01 00
-GetLightingExtendedRuntimeConditionalScenes reply             04 31 09 01 01 0e 09 01 01 01 02 01 01 01 01 14 01 50 02 02 2a 0b 07 08 09 01 01 01 01 03 01 01 00
+GetLightingExtendedRuntimeConditionalScenes reply             04 31 09 01 01 0e 09 01 01 01 02 01 01 01 01 14 01 50 02 02 2a 0d 07 08 09 01 01 01 01 03 01 01 01 01 00
 GetLightingExtendedRuntimeConditionalScenes request           05 31 09 01 09 01 00
 GetLightingExtension inner Err(Unsupported)                   04 21 09 01 02 01 01 00
 GetLightingExtension reply                                    04 21 09 01 01 08 09 06 10 01 02 03 04 00
@@ -80,7 +80,7 @@ GetLightingZones reply                                        04 06 09 01 01 0b
 GetLightingZones request                                      05 06 09 01 01 01 00
 LightingChange topic                                          03 07 80 01 00
 PutLightingExtendedRuntimeConditionalSceneChunk reply         04 33 09 01 01 01 00
-PutLightingExtendedRuntimeConditionalSceneChunk request       05 33 09 01 1f 0c 01 01 02 01 01 01 01 14 01 50 02 02 2a 0b 07 08 09 01 01 01 01 03 01 01 00
+PutLightingExtendedRuntimeConditionalSceneChunk request       05 33 09 01 1f 0c 01 01 02 01 01 01 01 14 01 50 02 02 2a 0d 07 08 09 01 01 01 01 03 01 01 01 01 00
 PutLightingOverlayChunk inner Err(TransactionExpired)         04 0e 09 01 03 01 0a 00
 PutLightingOverlayChunk reply                                 04 0e 09 01 01 01 00
 PutLightingOverlayChunk request                               05 0e 09 01 0d 0f 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 075ec423a..2fb033152 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1448,6 +1448,7 @@ fn lighting_wire_frames_locked() {
             profile: Some(3),
             ble_state: Some(BleState::Connected),
         }),
+        effects: Some(LightingEffectsCondition { enabled: true }),
     };
     let extended_runtime_conditional_page = LightingExtendedRuntimeConditionalScenesPage {
         revision: state.revision,
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 66a582135..325fd774b 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -1057,8 +1057,9 @@ fn capabilities(binding: RynkLightingController<'_>) -> LightingCapabilities {
         features.0 |= LightingFeatureFlags::COMPILED_CONDITIONAL_SCENES;
     }
     if binding.runtime_conditional_scene_capacity > 0 {
-        features.0 |=
-            LightingFeatureFlags::RUNTIME_CONDITIONAL_SCENES | LightingFeatureFlags::RUNTIME_CONNECTION_CONDITIONS;
+        features.0 |= LightingFeatureFlags::RUNTIME_CONDITIONAL_SCENES
+            | LightingFeatureFlags::RUNTIME_CONNECTION_CONDITIONS
+            | LightingFeatureFlags::RUNTIME_EFFECTS_CONDITIONS;
     }
     // The standard engine always owns an output-mode policy, so this advertises
     // the engine's support rather than whether a board happened to bind a key to
@@ -1604,6 +1605,7 @@ mod tests {
             }),
             connection: None,
             output_mode: None,
+            effects: None,
         },
         slot: crate::lighting::LedSlot(0),
         effect: BuiltinEffect::Solid {
@@ -2087,6 +2089,7 @@ mod tests {
                     profile: Some(crate::NUM_BLE_PROFILE as u8),
                     ble_state: None,
                 }),
+                effects: None,
             };
             let mut cells = Vec::new();
             cells.push(cell).unwrap();
@@ -2660,6 +2663,7 @@ mod tests {
                 let extended_cell = rmk_types::protocol::rynk::LightingExtendedConditionalSceneCell {
                     cell: conditional_cell,
                     connection: Some(connection),
+                    effects: None,
                 };
                 let mut extended_cells = Vec::new();
                 extended_cells.push(extended_cell).unwrap();
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index fb9523009..b4c26de6d 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -1411,6 +1411,7 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
         self.runtime_conditional_scene_cell_from_extended_wire(WireExtendedConditionalSceneCell {
             cell,
             connection: None,
+            effects: None,
         })
     }
 
@@ -1427,6 +1428,9 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
             })?;
         let mut conditions = condition_set_from_wire(cell.cell.conditions);
         conditions.connection = cell.connection.map(connection_condition_from_wire);
+        conditions.effects = cell.effects.map(|effects| crate::lighting::EffectsCondition {
+            enabled: effects.enabled,
+        });
         Ok(RuntimeConditionalSceneCell {
             conditions,
             slot,
@@ -1453,6 +1457,12 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                 effect: effect_to_wire(cell.effect),
             },
             connection: cell.conditions.connection.map(connection_condition_to_wire),
+            effects: cell
+                .conditions
+                .effects
+                .map(|effects| rmk_types::protocol::rynk::LightingEffectsCondition {
+                    enabled: effects.enabled,
+                }),
         })
     }
 }
@@ -1506,6 +1516,9 @@ pub fn install_lighting_runtime_conditional_scenes<
         };
         let mut conditions = condition_set_from_wire(cell.cell.conditions);
         conditions.connection = cell.connection.map(connection_condition_from_wire);
+        conditions.effects = cell.effects.map(|effects| crate::lighting::EffectsCondition {
+            enabled: effects.enabled,
+        });
         let _ = engine.install_runtime_conditional_scene_cell(RuntimeConditionalSceneCell {
             conditions,
             slot,
@@ -1694,6 +1707,7 @@ fn condition_set_from_wire(
             },
         }),
         connection: None,
+        effects: None,
         output_mode: conditions.output_mode.map(|mode| match mode {
             rmk_types::protocol::rynk::LightingOutputMode::AlwaysOn => crate::lighting::OutputMode::AlwaysOn,
             rmk_types::protocol::rynk::LightingOutputMode::AlwaysOff => crate::lighting::OutputMode::AlwaysOff,
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index 5348a44c2..3c2b8ff6b 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -38,9 +38,9 @@ pub use service::{
 };
 pub use source::{
     ActiveTransport, BatteryCondition, BatteryStatusProvider, ChargeCondition, ConditionSet, ConditionalSceneCell,
-    ConditionalScenes, ConnectionCondition, DenseSource, Indicator, IndicatorScene, IndicatorScenes, LayerCondition,
-    LayerPolicy, LayerScene, LayerScenes, LightingControls, OutputMode, OutputModeIndicator, OverlayError,
-    OverlayUpdate, PoweredOnlyScope, SceneCell, SparseScene, TtlOverlay,
+    ConditionalScenes, ConnectionCondition, DenseSource, EffectsCondition, Indicator, IndicatorScene, IndicatorScenes,
+    LayerCondition, LayerPolicy, LayerScene, LayerScenes, LightingControls, OutputMode, OutputModeIndicator,
+    OverlayError, OverlayUpdate, PoweredOnlyScope, SceneCell, SparseScene, TtlOverlay,
 };
 pub use standard::{
     BackgroundMode, BackgroundPatch, BackgroundState, CompiledScenePage, EmptySource, OVERLAY_CHUNK_SIZE, OverlayBatch,
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index 11b31d7c2..071d5b557 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -1,10 +1,11 @@
+use rmk_types::ble::BleState;
+use rmk_types::connection::ConnectionType;
+
 use super::compositor::{Contribution, LightingSource, RenderInput};
 use super::context::{LightingContext, LightingContextProvider};
 use super::effect::{BuiltinEffect, EffectSample, LightingEffect};
 use super::topology::LedSlot;
 use crate::types::battery::{BatteryStatus, ChargeState};
-use rmk_types::ble::BleState;
-use rmk_types::connection::ConnectionType;
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct SceneCell<E> {
@@ -193,6 +194,17 @@ pub struct ConnectionCondition {
     pub ble_state: Option<BleState>,
 }
 
+/// Satisfied when the extension band's enabled state equals `enabled`. An
+/// extension is enabled when its [`ExtensionState::value`] is non-zero, which
+/// is what `RgbTog` flips, so this is how a key can indicate whether effects
+/// are currently rendering.
+///
+/// [`ExtensionState::value`]: crate::lighting::ExtensionState::value
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct EffectsCondition {
+    pub enabled: bool,
+}
+
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
 pub struct ConditionSet {
     pub layer: Option<LayerCondition>,
@@ -202,6 +214,10 @@ pub struct ConditionSet {
     /// cannot observe the policy treat it as unsatisfiable rather than true,
     /// so a rule gated on it never fires where it cannot be evaluated.
     pub output_mode: Option<OutputMode>,
+    /// Satisfied when the extension band's enabled state matches. Sources
+    /// without a view of the extension treat it as unsatisfiable, on the same
+    /// grounds as `output_mode`.
+    pub effects: Option<EffectsCondition>,
 }
 
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
@@ -273,6 +289,7 @@ impl ConditionSet {
         context: &Context,
         batteries: &Batteries,
         output_mode: Option<OutputMode>,
+        effects_enabled: Option<bool>,
     ) -> bool
     where
         Context: LightingContextProvider,
@@ -283,6 +300,11 @@ impl ConditionSet {
         {
             return false;
         }
+        if let Some(wanted) = self.effects
+            && effects_enabled != Some(wanted.enabled)
+        {
+            return false;
+        }
         if let Some(condition) = self.layer
             && context.lighting_context().layers.is_active(condition.layer) != condition.active
         {
@@ -367,7 +389,7 @@ impl<'a, E, Batteries: ?Sized> ConditionalScenes<'a, E, Batteries> {
         for cell in self
             .cells
             .iter()
-            .filter(|cell| cell.conditions.matches(context, self.batteries, None))
+            .filter(|cell| cell.conditions.matches(context, self.batteries, None, None))
         {
             if wanted == 0 {
                 return cell;
@@ -387,7 +409,7 @@ where
     fn len(&self, input: &RenderInput<'_, Context>) -> usize {
         self.cells
             .iter()
-            .filter(|cell| cell.conditions.matches(input.context, self.batteries, None))
+            .filter(|cell| cell.conditions.matches(input.context, self.batteries, None, None))
             .count()
     }
 
@@ -672,11 +694,12 @@ fn earliest(left: Option<u64>, right: Option<u64>) -> Option<u64> {
 
 #[cfg(test)]
 mod tests {
+    use rmk_types::ble::{BleState, BleStatus};
+    use rmk_types::connection::{ConnectionStatus, ConnectionType, UsbState};
+
     use super::super::{BuiltinEffect, Compositor, LayerState, LogicalFrame, Rgb8};
     use super::*;
     use crate::types::battery::{BatteryStatus, ChargeState};
-    use rmk_types::ble::{BleState, BleStatus};
-    use rmk_types::connection::{ConnectionStatus, ConnectionType, UsbState};
 
     const RED: Rgb8 = Rgb8::new(10, 0, 0);
     const GREEN: Rgb8 = Rgb8::new(0, 10, 0);
@@ -712,9 +735,9 @@ mod tests {
             ..ConditionSet::default()
         };
 
-        assert!(conditions.matches(&context, &NoBatteries, None));
+        assert!(conditions.matches(&context, &NoBatteries, None, None));
         context.connection.preferred = ConnectionType::Usb;
-        assert!(!conditions.matches(&context, &NoBatteries, None));
+        assert!(!conditions.matches(&context, &NoBatteries, None, None));
 
         let usb = ConditionSet {
             connection: Some(ConnectionCondition {
@@ -724,13 +747,36 @@ mod tests {
             }),
             ..ConditionSet::default()
         };
-        assert!(usb.matches(&context, &NoBatteries, None));
+        assert!(usb.matches(&context, &NoBatteries, None, None));
 
         context.connection.ble.profile = 4;
-        assert!(!usb.matches(&context, &NoBatteries, None));
+        assert!(!usb.matches(&context, &NoBatteries, None, None));
         context.connection.ble.profile = 3;
         context.connection.ble.state = BleState::Advertising;
-        assert!(!usb.matches(&context, &NoBatteries, None));
+        assert!(!usb.matches(&context, &NoBatteries, None, None));
+    }
+
+    #[test]
+    fn effects_condition_needs_a_source_that_can_answer() {
+        let context = LightingContext::default();
+        let on = ConditionSet {
+            effects: Some(EffectsCondition { enabled: true }),
+            ..ConditionSet::default()
+        };
+        let off = ConditionSet {
+            effects: Some(EffectsCondition { enabled: false }),
+            ..ConditionSet::default()
+        };
+
+        assert!(on.matches(&context, &NoBatteries, None, Some(true)));
+        assert!(!on.matches(&context, &NoBatteries, None, Some(false)));
+        assert!(off.matches(&context, &NoBatteries, None, Some(false)));
+        assert!(!off.matches(&context, &NoBatteries, None, Some(true)));
+
+        // A source with no view of the extension leaves both unsatisfiable,
+        // rather than letting one of them fire wherever it cannot be judged.
+        assert!(!on.matches(&context, &NoBatteries, None, None));
+        assert!(!off.matches(&context, &NoBatteries, None, None));
     }
 
     #[test]
@@ -759,8 +805,8 @@ mod tests {
             ..ConditionSet::default()
         };
 
-        assert!(none_active.matches(&context, &NoBatteries, None));
-        assert!(empty.matches(&context, &NoBatteries, None));
+        assert!(none_active.matches(&context, &NoBatteries, None, None));
+        assert!(empty.matches(&context, &NoBatteries, None, None));
     }
 
     #[test]
@@ -886,6 +932,7 @@ mod tests {
                     }),
                     connection: None,
                     output_mode: None,
+                    effects: None,
                 },
                 slot: LedSlot(0),
                 effect: BuiltinEffect::solid(GREEN),
@@ -901,6 +948,7 @@ mod tests {
                     }),
                     connection: None,
                     output_mode: None,
+                    effects: None,
                 },
                 slot: LedSlot(1),
                 effect: BuiltinEffect::solid(BLUE),
@@ -917,6 +965,7 @@ mod tests {
                     }),
                     connection: None,
                     output_mode: None,
+                    effects: None,
                 },
                 slot: LedSlot(0),
                 effect: BuiltinEffect::solid(RED),
diff --git a/rmk/src/lighting/standard/conditional.rs b/rmk/src/lighting/standard/conditional.rs
index 167c76c3c..42aed79a7 100644
--- a/rmk/src/lighting/standard/conditional.rs
+++ b/rmk/src/lighting/standard/conditional.rs
@@ -21,6 +21,7 @@ pub(super) const EMPTY_CONDITIONAL_SCENE_CELL: RuntimeConditionalSceneCell = Run
         battery: None,
         connection: None,
         output_mode: None,
+        effects: None,
     },
     slot: LedSlot(0),
     effect: BuiltinEffect::Solid { color: Rgb8::BLACK },
@@ -42,6 +43,7 @@ const EMPTY_INTERNED_CONDITIONAL_SCENE_CELL: InternedRuntimeConditionalSceneCell
             battery: None,
             connection: None,
             output_mode: None,
+            effects: None,
         },
         slot: LedSlot(0),
         style: 0,
@@ -184,6 +186,9 @@ pub(super) struct RuntimeConditionalSource<'a, Batteries: ?Sized, const CAP: usi
     /// The engine owns the policy, so unlike the board's compiled source this
     /// one can evaluate an output-mode condition.
     pub(super) output_mode: OutputMode,
+    /// Whether the extension band is rendering, for the same reason: the
+    /// engine holds the extension source, so it can answer for it.
+    pub(super) effects_enabled: Option<bool>,
 }
 
 impl<Context, Batteries, const CAP: usize> LightingSource<Rgb8, Context>
@@ -196,8 +201,12 @@ where
         self.table
             .iter()
             .filter(|cell| {
-                cell.conditions
-                    .matches(input.context, self.batteries, Some(self.output_mode))
+                cell.conditions.matches(
+                    input.context,
+                    self.batteries,
+                    Some(self.output_mode),
+                    self.effects_enabled,
+                )
             })
             .count()
     }
@@ -206,8 +215,12 @@ where
         self.table
             .iter()
             .filter(|cell| {
-                cell.conditions
-                    .matches(input.context, self.batteries, Some(self.output_mode))
+                cell.conditions.matches(
+                    input.context,
+                    self.batteries,
+                    Some(self.output_mode),
+                    self.effects_enabled,
+                )
             })
             .nth(index)
             .expect("LightingSource index must be below len")
@@ -219,8 +232,12 @@ where
             .table
             .iter()
             .filter(|cell| {
-                cell.conditions
-                    .matches(input.context, self.batteries, Some(self.output_mode))
+                cell.conditions.matches(
+                    input.context,
+                    self.batteries,
+                    Some(self.output_mode),
+                    self.effects_enabled,
+                )
             })
             .nth(index)
             .expect("LightingSource index must be below len");
diff --git a/rmk/src/lighting/standard/engine.rs b/rmk/src/lighting/standard/engine.rs
index f5b66882a..c13d1fa9f 100644
--- a/rmk/src/lighting/standard/engine.rs
+++ b/rmk/src/lighting/standard/engine.rs
@@ -1246,8 +1246,11 @@ where
             effect: indicator.effect(self.output_mode),
         });
         // Captured before the destructuring below borrows the rest of `self`;
-        // the runtime conditional source needs it to evaluate output-mode rules.
+        // the runtime conditional source needs them to evaluate output-mode
+        // and effects rules. A source that reports no extension state cannot
+        // answer whether effects are on, so such rules stay unsatisfiable.
         let output_mode = self.output_mode;
+        let effects_enabled = self.extension.extension_state().map(|state| state.value != 0);
         let Self {
             compositor,
             background,
@@ -1290,6 +1293,7 @@ where
             table: runtime_conditional_scenes,
             batteries: *battery_status,
             output_mode,
+            effects_enabled,
         };
         transaction.apply(priority::STATUS, &mut runtime_conditional_source)?;
         if wake_active && let Some(indicator_cell) = indicator_cell.as_ref() {
diff --git a/rmk/src/lighting/standard/tests.rs b/rmk/src/lighting/standard/tests.rs
index 417e474a7..86e1e2926 100644
--- a/rmk/src/lighting/standard/tests.rs
+++ b/rmk/src/lighting/standard/tests.rs
@@ -10,7 +10,8 @@ use crate::lighting::compositor::{
 use crate::lighting::effect::{BuiltinEffect, LightingEffect};
 use crate::lighting::service::{Invalidation, LightingEngine, RenderInput};
 use crate::lighting::source::{
-    BatteryStatusProvider, ConditionSet, LayerScenes, LightingControls, OutputMode, OverlayError, SparseScene,
+    BatteryStatusProvider, ConditionSet, EffectsCondition, LayerScenes, LightingControls, OutputMode, OverlayError,
+    SparseScene,
 };
 use crate::lighting::topology::LedSlot;
 use crate::lighting::{LayerPolicy, LayerScene, LayerState, LightingContext, Rgb8, SceneCell};
@@ -1693,6 +1694,7 @@ fn runtime_conditional_replace_preserves_order_and_output_mode_is_revision_check
                 }),
                 connection: None,
                 output_mode: None,
+                effects: None,
             },
             slot: LedSlot(1),
             effect: BuiltinEffect::Solid { color: RED },
@@ -1705,6 +1707,7 @@ fn runtime_conditional_replace_preserves_order_and_output_mode_is_revision_check
                 battery: None,
                 connection: None,
                 output_mode: None,
+                effects: None,
             },
             slot: LedSlot(1),
             effect: BuiltinEffect::Solid { color: GREEN },
@@ -1973,6 +1976,7 @@ fn conditional_rules_share_styles_without_losing_order_or_conditions() {
                 battery: None,
                 connection: None,
                 output_mode: Some(OutputMode::AlwaysOn),
+                effects: None,
             },
             slot: LedSlot(3),
             effect,
@@ -1983,6 +1987,7 @@ fn conditional_rules_share_styles_without_losing_order_or_conditions() {
                 battery: None,
                 connection: None,
                 output_mode: Some(OutputMode::PoweredOnly),
+                effects: None,
             },
             slot: LedSlot(3),
             effect,
@@ -2114,6 +2119,7 @@ fn output_mode_conditions_select_between_runtime_rules() {
             battery: None,
             connection: None,
             output_mode: Some(mode),
+            effects: None,
         },
         slot: LedSlot(0),
         effect: BuiltinEffect::Solid { color },
@@ -2175,6 +2181,88 @@ fn output_mode_conditions_select_between_runtime_rules() {
     assert_eq!(frame.as_slice()[0], RED);
 }
 
+/// The effects condition exists so a key can report whether the extension band
+/// is rendering — the state `RgbTog` flips. Zeroing the extension's value is
+/// what "off" means, so the two rules trade places with no edit to the table.
+#[test]
+fn effects_conditions_follow_the_extension_value() {
+    let rule = |enabled: bool, color: Rgb8| RuntimeConditionalSceneCell {
+        conditions: ConditionSet {
+            layer: None,
+            battery: None,
+            connection: None,
+            output_mode: None,
+            effects: Some(EffectsCondition { enabled }),
+        },
+        slot: LedSlot(0),
+        effect: BuiltinEffect::Solid { color },
+    };
+
+    type ConditionalEngine = StandardLightingEngine<'static, ReplicaExtension, EmptySource, 2, 2, 4>;
+    let mut engine: ConditionalEngine = StandardLightingEngine::new(
+        BackgroundState::default(),
+        LayerScenes {
+            scenes: &[],
+            policy: LayerPolicy::EffectiveOnly,
+        },
+        ReplicaExtension {
+            state: ExtensionState {
+                effect: 0,
+                palette: 0,
+                value: 200,
+                speed: 0,
+            },
+            overlay: None,
+            accept: true,
+            params: [0, 0],
+        },
+        EmptySource,
+    );
+    for cell in [rule(true, GREEN), rule(false, RED)] {
+        engine.install_runtime_conditional_scene_cell(cell).unwrap();
+    }
+
+    let snapshot = LightingContext {
+        layers: LayerState::new(0, 0, 1),
+        indicators: Default::default(),
+        powered: true,
+        connection: Default::default(),
+    };
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    let render = |engine: &mut ConditionalEngine, frame: &mut LogicalFrame<Rgb8, 2>| {
+        engine
+            .render(
+                RenderInput {
+                    now_ms: 0,
+                    snapshot: &snapshot,
+                },
+                frame,
+            )
+            .unwrap();
+    };
+
+    render(&mut engine, &mut frame);
+    assert_eq!(frame.as_slice()[0], GREEN);
+
+    engine
+        .handle_command(
+            0,
+            StandardCommand::SetExtensionIfRevision {
+                expected_revision: engine.state().revision,
+                state: ExtensionState {
+                    effect: 0,
+                    palette: 0,
+                    value: 0,
+                    speed: 0,
+                },
+            },
+            &snapshot,
+        )
+        .unwrap();
+    render(&mut engine, &mut frame);
+    assert_eq!(frame.as_slice()[0], RED);
+}
+
 #[test]
 fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules() {
     use rmk_types::battery::BatteryStatus;
@@ -2198,6 +2286,7 @@ fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules
             battery: None,
             connection: None,
             output_mode: None,
+            effects: None,
         },
         slot: LedSlot(0),
         effect: BuiltinEffect::Solid { color: GREEN },
@@ -2248,6 +2337,7 @@ fn runtime_conditional_cells_outrank_layer_scenes_and_compiled_conditional_rules
                 battery: None,
                 connection: None,
                 output_mode: None,
+                effects: None,
             },
             slot: LedSlot(0),
             effect: BuiltinEffect::Solid { color: BLUE },
diff --git a/rmk/src/storage/mod.rs b/rmk/src/storage/mod.rs
index 514a0ad44..03fca30ac 100644
--- a/rmk/src/storage/mod.rs
+++ b/rmk/src/storage/mod.rs
@@ -792,7 +792,11 @@ impl<F: AsyncNorFlash, const ROW: usize, const COL: usize, const NUM_LAYER: usiz
             for cell in shard {
                 if cells.len() == len
                     || cells
-                        .push(LightingExtendedConditionalSceneCell { cell, connection: None })
+                        .push(LightingExtendedConditionalSceneCell {
+                            cell,
+                            connection: None,
+                            effects: None,
+                        })
                         .is_err()
                 {
                     break 'legacy_shards;
@@ -1481,6 +1485,7 @@ mod tests {
                     profile: Some(4),
                     ble_state: Some(rmk_types::ble::BleState::Advertising),
                 }),
+                effects: None,
             };
             let mut shard = heapless::Vec::<
                 LightingExtendedConditionalSceneCell,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index cf6fad6f2..869125591 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -745,9 +745,11 @@ impl Client {
         )
     }
 
-    /// Read connection-aware runtime conditional cells. Callers should use
-    /// this only when lighting capabilities advertise
-    /// `RUNTIME_CONNECTION_CONDITIONS`.
+    /// Read connection- and effects-aware runtime conditional cells. The
+    /// extended cell's encoding is described by
+    /// `RUNTIME_EFFECTS_CONDITIONS`, so callers that cannot see that bit
+    /// should use the legacy endpoints rather than risk a misparse against
+    /// firmware speaking the earlier extended cell.
     pub async fn get_lighting_extended_runtime_conditional_scene_status(
         &self,
     ) -> Result<LightingRuntimeConditionalSceneStatus, RynkHostError> {

From 3deec123e40a6a811f74f523e45320595ab7a65c Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 21:08:13 -0700
Subject: [PATCH 67/78] feat(ble): track which profile slots hold a bond

Maintain a bitmap alongside the profile manager's bonded-device list so
subscribers outside the BLE task can see every slot's paired-versus-empty
state at once, not just the active slot's.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk/src/ble/profile.rs | 21 +++++++++++++++++++++
 rmk/src/state.rs       | 18 ++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/rmk/src/ble/profile.rs b/rmk/src/ble/profile.rs
index 31d63e73f..06ca03313 100644
--- a/rmk/src/ble/profile.rs
+++ b/rmk/src/ble/profile.rs
@@ -128,6 +128,7 @@ where
             }
         }
         debug!("Loaded {} bond info", self.bonded_devices.len());
+        self.sync_bonded_slots();
 
         let profile = if let Some(profile) = read_active_ble_profile().await {
             debug!("Loaded active profile: {}", profile);
@@ -139,6 +140,24 @@ where
         set_ble_profile(profile);
     }
 
+    /// Recompute the bitmap of slots holding a bond and publish it for
+    /// lighting. Called from every point that mutates `bonded_devices`, so a
+    /// rule gated on "slot N is paired" is never left reading a stale mask.
+    ///
+    /// Slots at or beyond the mask's width are dropped rather than wrapped: a
+    /// board configured with more profiles than the mask can carry loses the
+    /// high slots' observability, which is preferable to reporting them under
+    /// some other slot's bit.
+    fn sync_bonded_slots(&self) {
+        let mut mask = 0u8;
+        for info in self.bonded_devices.iter() {
+            if !info.removed && info.slot_num < u8::BITS as u8 {
+                mask |= 1 << info.slot_num;
+            }
+        }
+        crate::state::set_bonded_slots(mask);
+    }
+
     /// Cached bond info for the currently active profile, cloned to free the
     /// caller from borrow conflicts with concurrent `update_profile()`.
     pub(crate) fn active_bond_info(&self) -> Option<ProfileInfo> {
@@ -190,6 +209,7 @@ where
         }
 
         self.update_stack_bonds();
+        self.sync_bonded_slots();
 
         #[cfg(feature = "storage")]
         // Send bonding information to the flash task for saving
@@ -241,6 +261,7 @@ where
 
         // Update the active bonding information in the stack
         self.update_stack_bonds();
+        self.sync_bonded_slots();
 
         #[cfg(feature = "storage")]
         // Send the clear slot message to the flash task
diff --git a/rmk/src/state.rs b/rmk/src/state.rs
index 6f021233b..7704f2202 100644
--- a/rmk/src/state.rs
+++ b/rmk/src/state.rs
@@ -63,6 +63,24 @@ pub(crate) fn set_sleeping(sleeping: bool) {
 pub(crate) static CONNECTION_STATUS: Mutex<RawMutex, Cell<ConnectionStatus>> =
     Mutex::new(Cell::new(ConnectionStatus::new()));
 
+/// Bitmap of BLE profile slots holding a stored bond, bit N = slot N.
+/// Maintained by `ProfileManager`; read by lighting so rules can show
+/// paired-versus-empty slots. Freshness rides on ordinary render triggers
+/// (bond changes coincide with connection or layer activity).
+#[cfg(feature = "_ble")]
+static BONDED_SLOTS: core::sync::atomic::AtomicU8 = core::sync::atomic::AtomicU8::new(0);
+
+/// Which BLE profile slots hold a stored bond, as a bitmap (bit N = slot N).
+#[cfg(feature = "_ble")]
+pub fn bonded_slots() -> u8 {
+    BONDED_SLOTS.load(core::sync::atomic::Ordering::Acquire)
+}
+
+#[cfg(feature = "_ble")]
+pub(crate) fn set_bonded_slots(mask: u8) {
+    BONDED_SLOTS.store(mask, core::sync::atomic::Ordering::Release);
+}
+
 pub(crate) fn active_transport() -> Option<ConnectionType> {
     CONNECTION_STATUS.lock(|c| c.get().decide_active())
 }

From 802b3cf91427c288c14d89213788c83939a660b2 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 21:08:13 -0700
Subject: [PATCH 68/78] feat(lighting): bonded-slot conditions on extended
 cells

Conditional rules gain connection.bonded = { slot, bonded }, matched
against the bond bitmap independently of the active profile, so one rule
per slot key can light paired and empty slots differently. The extended
wire cell grows accordingly (pre-release surface iterated in lockstep
with the in-tree hosts); pages now carry five cells. Stale stored V2
tables from the previous cell layout decode as absent and are restored
by the next host apply.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/protocol/rynk/payload/lighting.rs     | 16 ++++--
 rmk/src/host/rynk/handlers/lighting.rs        |  9 ++++
 rmk/src/host/rynk/lighting.rs                 | 12 ++++-
 rmk/src/lighting/context.rs                   |  7 +++
 rmk/src/lighting/mod.rs                       |  8 +--
 rmk/src/lighting/rmk_state.rs                 | 13 +++++
 rmk/src/lighting/source.rs                    | 54 +++++++++++++++++++
 rmk/src/lighting/standard/tests.rs            |  3 ++
 rmk/src/storage/mod.rs                        |  1 +
 9 files changed, 115 insertions(+), 8 deletions(-)

diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index e95f6bc95..c095d5fbb 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -21,9 +21,9 @@ pub const LIGHTING_OVERLAY_CHUNK_SIZE: usize = 8;
 pub const LIGHTING_SCENE_CHUNK_SIZE: usize = 8;
 /// Number of immutable conditional cells in one readback page.
 pub const LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 7;
-/// Number of connection- and effects-aware conditional cells in one extended
-/// page/chunk. Lower than the legacy chunk because each cell carries the two
-/// added predicates and the page still has to fit `LIGHTING_PAYLOAD_SIZE`.
+/// Number of extended conditional cells in one page/chunk. Lower than the
+/// legacy chunk because each cell carries the connection, bonded-slot, and
+/// effects predicates and the page still has to fit `LIGHTING_PAYLOAD_SIZE`.
 pub const LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 5;
 /// Maximum UTF-8 byte length of a zone name.
 pub const LIGHTING_ZONE_NAME_SIZE: usize = 24;
@@ -676,6 +676,15 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Gate on one slot holding (or not holding) a stored bond, regardless of
+    /// which profile is active.
+    pub struct LightingBondedSlotCondition {
+        pub slot: u8,
+        pub bonded: bool,
+    }
+}
+
 wire_type! {
     /// Optional connection predicates. Present fields form a conjunction; an
     /// empty condition matches every connection state.
@@ -683,6 +692,7 @@ wire_type! {
         pub transport: Option<LightingActiveTransport>,
         pub profile: Option<u8>,
         pub ble_state: Option<BleState>,
+        pub bonded: Option<LightingBondedSlotCondition>,
     }
 }
 
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 325fd774b..f9f2066ec 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -616,6 +616,13 @@ impl Handle<PutLightingExtendedRuntimeConditionalSceneChunk> for RynkService<'_>
             {
                 return Ok(Err(LightingError::InvalidRequest));
             }
+            #[cfg(feature = "_ble")]
+            if let Some(connection) = cell.connection
+                && let Some(bonded) = connection.bonded
+                && (bonded.slot as usize) >= crate::NUM_BLE_PROFILE
+            {
+                return Ok(Err(LightingError::InvalidRequest));
+            }
         }
         Ok(match runtime_conditional_scene_controller(self) {
             Ok(controller) => match controller
@@ -2088,6 +2095,7 @@ mod tests {
                     transport: None,
                     profile: Some(crate::NUM_BLE_PROFILE as u8),
                     ble_state: None,
+                    bonded: None,
                 }),
                 effects: None,
             };
@@ -2659,6 +2667,7 @@ mod tests {
                     transport: Some(rmk_types::protocol::rynk::LightingActiveTransport::Ble),
                     profile: Some(3),
                     ble_state: Some(rmk_types::ble::BleState::Connected),
+                    bonded: None,
                 };
                 let extended_cell = rmk_types::protocol::rynk::LightingExtendedConditionalSceneCell {
                     cell: conditional_cell,
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index b4c26de6d..d4ca848da 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -1719,7 +1719,9 @@ fn condition_set_from_wire(
 fn connection_condition_to_wire(
     condition: crate::lighting::ConnectionCondition,
 ) -> rmk_types::protocol::rynk::LightingConnectionCondition {
-    use rmk_types::protocol::rynk::{LightingActiveTransport, LightingConnectionCondition};
+    use rmk_types::protocol::rynk::{
+        LightingActiveTransport, LightingBondedSlotCondition, LightingConnectionCondition,
+    };
 
     LightingConnectionCondition {
         transport: condition.transport.map(|transport| match transport {
@@ -1729,6 +1731,10 @@ fn connection_condition_to_wire(
         }),
         profile: condition.profile,
         ble_state: condition.ble_state,
+        bonded: condition.bonded.map(|bonded| LightingBondedSlotCondition {
+            slot: bonded.slot,
+            bonded: bonded.bonded,
+        }),
     }
 }
 
@@ -1745,6 +1751,10 @@ fn connection_condition_from_wire(
         }),
         profile: condition.profile,
         ble_state: condition.ble_state,
+        bonded: condition.bonded.map(|bonded| crate::lighting::BondedSlotCondition {
+            slot: bonded.slot,
+            bonded: bonded.bonded,
+        }),
     }
 }
 
diff --git a/rmk/src/lighting/context.rs b/rmk/src/lighting/context.rs
index 0994bf7d2..bdb42edf0 100644
--- a/rmk/src/lighting/context.rs
+++ b/rmk/src/lighting/context.rs
@@ -62,6 +62,13 @@ pub struct LightingContext {
     pub powered: bool,
     /// Authoritative transport, BLE profile, and BLE lifecycle snapshot.
     pub connection: ConnectionStatus,
+    /// BLE profile slots holding a stored bond, as a bitmap (bit N = slot N).
+    ///
+    /// `connection` only describes the *active* profile, so on its own it can
+    /// never say whether some other slot is paired. This makes every slot's
+    /// paired-versus-empty state observable at once, which is what lets a
+    /// board light one indicator per slot key. Zero without `_ble`.
+    pub bonded_slots: u8,
 }
 
 /// Access to RMK's standard lighting state from a board-extended snapshot.
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index 3c2b8ff6b..f91173b4e 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -37,10 +37,10 @@ pub use service::{
     OutputState, PowerState, RenderOutcome, ServiceAction, SnapshotProvider,
 };
 pub use source::{
-    ActiveTransport, BatteryCondition, BatteryStatusProvider, ChargeCondition, ConditionSet, ConditionalSceneCell,
-    ConditionalScenes, ConnectionCondition, DenseSource, EffectsCondition, Indicator, IndicatorScene, IndicatorScenes,
-    LayerCondition, LayerPolicy, LayerScene, LayerScenes, LightingControls, OutputMode, OutputModeIndicator,
-    OverlayError, OverlayUpdate, PoweredOnlyScope, SceneCell, SparseScene, TtlOverlay,
+    ActiveTransport, BatteryCondition, BatteryStatusProvider, BondedSlotCondition, ChargeCondition, ConditionSet,
+    ConditionalSceneCell, ConditionalScenes, ConnectionCondition, DenseSource, EffectsCondition, Indicator,
+    IndicatorScene, IndicatorScenes, LayerCondition, LayerPolicy, LayerScene, LayerScenes, LightingControls,
+    OutputMode, OutputModeIndicator, OverlayError, OverlayUpdate, PoweredOnlyScope, SceneCell, SparseScene, TtlOverlay,
 };
 pub use standard::{
     BackgroundMode, BackgroundPatch, BackgroundState, CompiledScenePage, EmptySource, OVERLAY_CHUNK_SIZE, OverlayBatch,
diff --git a/rmk/src/lighting/rmk_state.rs b/rmk/src/lighting/rmk_state.rs
index b027d4e9c..53466e96e 100644
--- a/rmk/src/lighting/rmk_state.rs
+++ b/rmk/src/lighting/rmk_state.rs
@@ -54,10 +54,23 @@ impl SnapshotProvider for KeymapLightingState<'_, '_> {
             indicators: indicator_state(),
             powered: connection.usb.is_powered(),
             connection,
+            bonded_slots: bonded_slots(),
         }
     }
 }
 
+/// Bonded-slot bitmap, or zero on builds with no BLE stack to bond with.
+fn bonded_slots() -> u8 {
+    #[cfg(feature = "_ble")]
+    {
+        crate::state::bonded_slots()
+    }
+    #[cfg(not(feature = "_ble"))]
+    {
+        0
+    }
+}
+
 fn indicator_state() -> IndicatorState {
     let indicator = crate::keyboard::current_led_indicator();
     IndicatorState {
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index 071d5b557..37be63ede 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -192,6 +192,16 @@ pub struct ConnectionCondition {
     pub transport: Option<ActiveTransport>,
     pub profile: Option<u8>,
     pub ble_state: Option<BleState>,
+    /// Gate on a specific slot holding (or not holding) a stored bond,
+    /// independent of which profile is active. This is what lets one rule per
+    /// slot key say "paired" or "empty" for every slot at once.
+    pub bonded: Option<BondedSlotCondition>,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct BondedSlotCondition {
+    pub slot: u8,
+    pub bonded: bool,
 }
 
 /// Satisfied when the extension band's enabled state equals `enabled`. An
@@ -329,6 +339,12 @@ impl ConditionSet {
             {
                 return false;
             }
+            if let Some(wanted) = condition.bonded {
+                let bonded = (context.lighting_context().bonded_slots >> wanted.slot) & 1 == 1;
+                if bonded != wanted.bonded {
+                    return false;
+                }
+            }
         }
         let Some(condition) = self.battery else {
             return true;
@@ -731,6 +747,7 @@ mod tests {
                 transport: Some(ActiveTransport::Ble),
                 profile: Some(3),
                 ble_state: Some(BleState::Connected),
+                bonded: None,
             }),
             ..ConditionSet::default()
         };
@@ -744,6 +761,7 @@ mod tests {
                 transport: Some(ActiveTransport::Usb),
                 profile: Some(3),
                 ble_state: Some(BleState::Connected),
+                bonded: None,
             }),
             ..ConditionSet::default()
         };
@@ -779,6 +797,39 @@ mod tests {
         assert!(!off.matches(&context, &NoBatteries, None, None));
     }
 
+    #[test]
+    fn bonded_slot_condition_reads_the_bitmap_regardless_of_active_profile() {
+        let mut context = LightingContext {
+            bonded_slots: 0b101,
+            ..LightingContext::default()
+        };
+        let paired = |slot| ConditionSet {
+            connection: Some(ConnectionCondition {
+                bonded: Some(BondedSlotCondition { slot, bonded: true }),
+                ..ConnectionCondition::default()
+            }),
+            ..ConditionSet::default()
+        };
+        let empty = |slot| ConditionSet {
+            connection: Some(ConnectionCondition {
+                bonded: Some(BondedSlotCondition { slot, bonded: false }),
+                ..ConnectionCondition::default()
+            }),
+            ..ConditionSet::default()
+        };
+
+        assert!(paired(0).matches(&context, &NoBatteries, None, None));
+        assert!(empty(1).matches(&context, &NoBatteries, None, None));
+        assert!(paired(2).matches(&context, &NoBatteries, None, None));
+        assert!(!paired(1).matches(&context, &NoBatteries, None, None));
+        assert!(!empty(0).matches(&context, &NoBatteries, None, None));
+
+        // The active profile plays no part: switching it changes nothing.
+        context.connection.ble.profile = 1;
+        assert!(paired(0).matches(&context, &NoBatteries, None, None));
+        assert!(empty(1).matches(&context, &NoBatteries, None, None));
+    }
+
     #[test]
     fn connection_condition_matches_none_active_and_empty_condition() {
         let context = LightingContext {
@@ -797,6 +848,7 @@ mod tests {
                 transport: Some(ActiveTransport::NoneActive),
                 profile: Some(2),
                 ble_state: Some(BleState::Advertising),
+                bonded: None,
             }),
             ..ConditionSet::default()
         };
@@ -840,6 +892,7 @@ mod tests {
             indicators: Default::default(),
             powered: false,
             connection: Default::default(),
+            bonded_slots: 0,
         };
         let compositor = Compositor::<Rgb8, 2>::new(Rgb8::BLACK);
         let mut frame = LogicalFrame::new(Rgb8::BLACK);
@@ -978,6 +1031,7 @@ mod tests {
             indicators: Default::default(),
             powered: false,
             connection: Default::default(),
+            bonded_slots: 0,
         };
         let compositor = Compositor::<Rgb8, 2>::new(Rgb8::BLACK);
         let mut frame = LogicalFrame::new(Rgb8::BLACK);
diff --git a/rmk/src/lighting/standard/tests.rs b/rmk/src/lighting/standard/tests.rs
index 86e1e2926..818102374 100644
--- a/rmk/src/lighting/standard/tests.rs
+++ b/rmk/src/lighting/standard/tests.rs
@@ -176,6 +176,7 @@ fn context(layer: u8) -> LightingContext {
         indicators: Default::default(),
         powered: false,
         connection: Default::default(),
+        bonded_slots: 0,
     }
 }
 
@@ -2146,6 +2147,7 @@ fn output_mode_conditions_select_between_runtime_rules() {
         indicators: Default::default(),
         powered: true,
         connection: Default::default(),
+        bonded_slots: 0,
     };
     let mut frame = LogicalFrame::new(Rgb8::BLACK);
     let render = |engine: &mut ConditionalEngine, frame: &mut LogicalFrame<Rgb8, 2>| {
@@ -2227,6 +2229,7 @@ fn effects_conditions_follow_the_extension_value() {
         indicators: Default::default(),
         powered: true,
         connection: Default::default(),
+        bonded_slots: 0,
     };
     let mut frame = LogicalFrame::new(Rgb8::BLACK);
     let render = |engine: &mut ConditionalEngine, frame: &mut LogicalFrame<Rgb8, 2>| {
diff --git a/rmk/src/storage/mod.rs b/rmk/src/storage/mod.rs
index 03fca30ac..9566b2f7a 100644
--- a/rmk/src/storage/mod.rs
+++ b/rmk/src/storage/mod.rs
@@ -1484,6 +1484,7 @@ mod tests {
                     transport: Some(rmk_types::protocol::rynk::LightingActiveTransport::Ble),
                     profile: Some(4),
                     ble_state: Some(rmk_types::ble::BleState::Advertising),
+                    bonded: None,
                 }),
                 effects: None,
             };

From 082149a56871f5fb5d763dcc36e7321118a80349 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Mon, 3 Aug 2026 21:23:19 -0700
Subject: [PATCH 69/78] feat(lighting): usb-connected condition on extended
 cells
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rules can gate on USB being plugged and routable independently of the
active transport — the difference between a USB indicator shown ready
(plugged, typing elsewhere) and active (carrying typing). Wire cell
grows by the trailing option; five-cell pages still fit the payload
bound.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 rmk-types/src/connection.rs                   |  4 ++-
 .../src/protocol/rynk/payload/lighting.rs     |  3 ++
 rmk/src/host/rynk/handlers/lighting.rs        |  2 ++
 rmk/src/host/rynk/lighting.rs                 |  2 ++
 rmk/src/lighting/source.rs                    | 34 +++++++++++++++++++
 rmk/src/storage/mod.rs                        |  1 +
 6 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/rmk-types/src/connection.rs b/rmk-types/src/connection.rs
index bdb379d82..5e081caa1 100644
--- a/rmk-types/src/connection.rs
+++ b/rmk-types/src/connection.rs
@@ -72,7 +72,9 @@ impl Default for ConnectionStatus {
 }
 
 impl ConnectionStatus {
-    fn usb_ready(&self) -> bool {
+    /// Whether USB is plugged and routable (configured or suspended),
+    /// independent of whether it is the active transport.
+    pub fn usb_ready(&self) -> bool {
         matches!(self.usb, UsbState::Configured | UsbState::Suspended)
     }
 
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index c095d5fbb..3376bdab3 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -693,6 +693,9 @@ wire_type! {
         pub profile: Option<u8>,
         pub ble_state: Option<BleState>,
         pub bonded: Option<LightingBondedSlotCondition>,
+        /// Gate on USB being plugged and routable, whether or not it is the
+        /// active transport.
+        pub usb_connected: Option<bool>,
     }
 }
 
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index f9f2066ec..18e499066 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -2096,6 +2096,7 @@ mod tests {
                     profile: Some(crate::NUM_BLE_PROFILE as u8),
                     ble_state: None,
                     bonded: None,
+                    usb_connected: None,
                 }),
                 effects: None,
             };
@@ -2668,6 +2669,7 @@ mod tests {
                     profile: Some(3),
                     ble_state: Some(rmk_types::ble::BleState::Connected),
                     bonded: None,
+                    usb_connected: None,
                 };
                 let extended_cell = rmk_types::protocol::rynk::LightingExtendedConditionalSceneCell {
                     cell: conditional_cell,
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index d4ca848da..e34298ba9 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -1735,6 +1735,7 @@ fn connection_condition_to_wire(
             slot: bonded.slot,
             bonded: bonded.bonded,
         }),
+        usb_connected: condition.usb_connected,
     }
 }
 
@@ -1755,6 +1756,7 @@ fn connection_condition_from_wire(
             slot: bonded.slot,
             bonded: bonded.bonded,
         }),
+        usb_connected: condition.usb_connected,
     }
 }
 
diff --git a/rmk/src/lighting/source.rs b/rmk/src/lighting/source.rs
index 37be63ede..854dc5859 100644
--- a/rmk/src/lighting/source.rs
+++ b/rmk/src/lighting/source.rs
@@ -196,6 +196,9 @@ pub struct ConnectionCondition {
     /// independent of which profile is active. This is what lets one rule per
     /// slot key say "paired" or "empty" for every slot at once.
     pub bonded: Option<BondedSlotCondition>,
+    /// Gate on USB being plugged and routable, whether or not it carries
+    /// output — the difference between a USB key shown "ready" and "active".
+    pub usb_connected: Option<bool>,
 }
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
@@ -345,6 +348,12 @@ impl ConditionSet {
                     return false;
                 }
             }
+            if condition
+                .usb_connected
+                .is_some_and(|wanted| connection.usb_ready() != wanted)
+            {
+                return false;
+            }
         }
         let Some(condition) = self.battery else {
             return true;
@@ -748,6 +757,7 @@ mod tests {
                 profile: Some(3),
                 ble_state: Some(BleState::Connected),
                 bonded: None,
+                usb_connected: None,
             }),
             ..ConditionSet::default()
         };
@@ -762,6 +772,7 @@ mod tests {
                 profile: Some(3),
                 ble_state: Some(BleState::Connected),
                 bonded: None,
+                usb_connected: None,
             }),
             ..ConditionSet::default()
         };
@@ -830,6 +841,28 @@ mod tests {
         assert!(empty(1).matches(&context, &NoBatteries, None, None));
     }
 
+    #[test]
+    fn usb_connected_condition_tracks_readiness_not_active_transport() {
+        let mut context = LightingContext::default();
+        let plugged = |wanted| ConditionSet {
+            connection: Some(ConnectionCondition {
+                usb_connected: Some(wanted),
+                ..ConnectionCondition::default()
+            }),
+            ..ConditionSet::default()
+        };
+
+        assert!(plugged(false).matches(&context, &NoBatteries, None, None));
+        assert!(!plugged(true).matches(&context, &NoBatteries, None, None));
+
+        // Ready but not the active transport: still "connected".
+        context.connection.usb = UsbState::Configured;
+        context.connection.ble.state = BleState::Connected;
+        context.connection.preferred = ConnectionType::Ble;
+        assert!(plugged(true).matches(&context, &NoBatteries, None, None));
+        assert!(!plugged(false).matches(&context, &NoBatteries, None, None));
+    }
+
     #[test]
     fn connection_condition_matches_none_active_and_empty_condition() {
         let context = LightingContext {
@@ -849,6 +882,7 @@ mod tests {
                 profile: Some(2),
                 ble_state: Some(BleState::Advertising),
                 bonded: None,
+                usb_connected: None,
             }),
             ..ConditionSet::default()
         };
diff --git a/rmk/src/storage/mod.rs b/rmk/src/storage/mod.rs
index 9566b2f7a..dc6ac49a3 100644
--- a/rmk/src/storage/mod.rs
+++ b/rmk/src/storage/mod.rs
@@ -1485,6 +1485,7 @@ mod tests {
                     profile: Some(4),
                     ble_state: Some(rmk_types::ble::BleState::Advertising),
                     bonded: None,
+                    usb_connected: None,
                 }),
                 effects: None,
             };

From 4fd90489f6e84a3ee40cfb57e44de1cc9d657482 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 5 Aug 2026 00:42:16 -0700
Subject: [PATCH 70/78] test(rynk): cover the new connection condition fields

The extended conditional exemplars still built `LightingConnectionCondition`
without `bonded` and `usb_connected`, so the `host` feature build of
rmk-types failed to compile. Populate both and repin the frame snapshot.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 rmk-types/src/protocol/rynk/payload/lighting.rs               | 2 ++
 .../src/protocol/rynk/snapshots/lighting_wire_frames.snap     | 4 ++--
 rmk-types/src/protocol/rynk/tests.rs                          | 2 ++
 3 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 3376bdab3..b92be70ac 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -1511,6 +1511,8 @@ mod tests {
                 transport: Some(LightingActiveTransport::Ble),
                 profile: Some(3),
                 ble_state: Some(BleState::Connected),
+                bonded: Some(LightingBondedSlotCondition { slot: 2, bonded: true }),
+                usb_connected: Some(true),
             }),
             effects: Some(LightingEffectsCondition { enabled: true }),
         };
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index a275aa6bd..119cb1f67 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -39,7 +39,7 @@ GetLightingCompiledScenes reply                               04 1d 09 01 01 06
 GetLightingCompiledScenes request                             05 1d 09 01 01 01 00
 GetLightingExtendedRuntimeConditionalSceneStatus reply        04 30 09 01 01 05 09 40 01 05 00
 GetLightingExtendedRuntimeConditionalSceneStatus request      04 30 09 01 00
-GetLightingExtendedRuntimeConditionalScenes reply             04 31 09 01 01 0e 09 01 01 01 02 01 01 01 01 14 01 50 02 02 2a 0d 07 08 09 01 01 01 01 03 01 01 01 01 00
+GetLightingExtendedRuntimeConditionalScenes reply             04 31 09 01 01 0e 09 01 01 01 02 01 01 01 01 14 01 50 02 02 2a 12 07 08 09 01 01 01 01 03 01 01 01 02 01 01 01 01 01 00
 GetLightingExtendedRuntimeConditionalScenes request           05 31 09 01 09 01 00
 GetLightingExtension inner Err(Unsupported)                   04 21 09 01 02 01 01 00
 GetLightingExtension reply                                    04 21 09 01 01 08 09 06 10 01 02 03 04 00
@@ -80,7 +80,7 @@ GetLightingZones reply                                        04 06 09 01 01 0b
 GetLightingZones request                                      05 06 09 01 01 01 00
 LightingChange topic                                          03 07 80 01 00
 PutLightingExtendedRuntimeConditionalSceneChunk reply         04 33 09 01 01 01 00
-PutLightingExtendedRuntimeConditionalSceneChunk request       05 33 09 01 1f 0c 01 01 02 01 01 01 01 14 01 50 02 02 2a 0d 07 08 09 01 01 01 01 03 01 01 01 01 00
+PutLightingExtendedRuntimeConditionalSceneChunk request       05 33 09 01 1f 0c 01 01 02 01 01 01 01 14 01 50 02 02 2a 12 07 08 09 01 01 01 01 03 01 01 01 02 01 01 01 01 01 00
 PutLightingOverlayChunk inner Err(TransactionExpired)         04 0e 09 01 03 01 0a 00
 PutLightingOverlayChunk reply                                 04 0e 09 01 01 01 00
 PutLightingOverlayChunk request                               05 0e 09 01 0d 0f 01 2a 01 01 02 03 e8 07 fa 01 32 01 88 27 00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 2fb033152..eac5ae55d 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1447,6 +1447,8 @@ fn lighting_wire_frames_locked() {
             transport: Some(LightingActiveTransport::Ble),
             profile: Some(3),
             ble_state: Some(BleState::Connected),
+            bonded: Some(LightingBondedSlotCondition { slot: 2, bonded: true }),
+            usb_connected: Some(true),
         }),
         effects: Some(LightingEffectsCondition { enabled: true }),
     };

From 34217cf04429220ed12aaf23c68cc1348cac2044 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 5 Aug 2026 00:41:22 -0700
Subject: [PATCH 71/78] fix(rynk): silence unused session outside lighting
 builds

Only the lighting overlay handlers take the session, so `rynk` without
`lighting` tripped -D unused-variables in example builds.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 rmk/src/host/rynk/mod.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 043464ce6..5c47b6046 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -205,7 +205,7 @@ impl<'a> RynkService<'a> {
     async fn dispatch(
         &self,
         locker: &HostLock<'_>,
-        session: &RynkSession,
+        #[cfg_attr(not(feature = "lighting"), allow(unused_variables))] session: &RynkSession,
         msg: &mut RynkMessage<'_>,
     ) -> Result<(), RynkError> {
         let cmd = msg.header().cmd;

From f8bd8090c4e930629c8776b2e1a59e060b7700e0 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 6 Aug 2026 14:01:21 -0700
Subject: [PATCH 72/78] feat(lighting): read back the frame the output
 presented

The engine could report what it holds but never what the LEDs show. On a
split renderer replica those are different questions: the replica renders
from a snapshot that can go stale, and nothing observable distinguished a
stale replica from a correct one.

Record each render's revision and lighting context, promote it when the
output acknowledges the write, and page the committed frame back through
`ReadFrame`. The committed frame is post-`OutputTransform`, so what comes
back is what the driver was handed rather than the pre-brightness
composition.
---
 rmk/src/lighting/compositor.rs       |   8 +++
 rmk/src/lighting/mod.rs              |  12 ++--
 rmk/src/lighting/standard/command.rs |  54 ++++++++++++++
 rmk/src/lighting/standard/engine.rs  |  35 ++++++++-
 rmk/src/lighting/standard/tests.rs   | 103 +++++++++++++++++++++++++++
 5 files changed, 205 insertions(+), 7 deletions(-)

diff --git a/rmk/src/lighting/compositor.rs b/rmk/src/lighting/compositor.rs
index 2f12be923..7f8072b76 100644
--- a/rmk/src/lighting/compositor.rs
+++ b/rmk/src/lighting/compositor.rs
@@ -253,6 +253,14 @@ impl<C: Copy + Eq, const N: usize> Compositor<C, N> {
     pub fn has_committed(&self) -> bool {
         self.has_committed
     }
+
+    /// The last frame the output accepted — post-[`OutputTransform`], because
+    /// [`RenderTransaction::finish_with`] writes the transformed colors back
+    /// into the frame before it is presented and committed. It is therefore
+    /// what the driver was handed, not the pre-brightness composition.
+    pub const fn committed(&self) -> &LogicalFrame<C, N> {
+        &self.committed
+    }
 }
 
 pub struct RenderTransaction<'a, 'context, C, Context, const N: usize> {
diff --git a/rmk/src/lighting/mod.rs b/rmk/src/lighting/mod.rs
index f91173b4e..fb09a46a1 100644
--- a/rmk/src/lighting/mod.rs
+++ b/rmk/src/lighting/mod.rs
@@ -43,12 +43,12 @@ pub use source::{
     OutputMode, OutputModeIndicator, OverlayError, OverlayUpdate, PoweredOnlyScope, SceneCell, SparseScene, TtlOverlay,
 };
 pub use standard::{
-    BackgroundMode, BackgroundPatch, BackgroundState, CompiledScenePage, EmptySource, OVERLAY_CHUNK_SIZE, OverlayBatch,
-    OverlayCell, OverlayPage, ReplicaSlotError, RuntimeConditionalSceneCell, RuntimeConditionalSceneChunk,
-    RuntimeConditionalScenePage, RuntimeConditionalSceneTable, SCENE_CHUNK_SIZE, SCENE_TRANSACTION_TIMEOUT_MS,
-    SceneChunk, ScenePage, SceneTable, SceneTableCell, StandardCommand, StandardError, StandardInput,
-    StandardLightingEngine, StandardMutableState, StandardReplicaSlot, StandardReplicaState, StandardReply,
-    StandardState, UniformBackground,
+    BackgroundMode, BackgroundPatch, BackgroundState, CompiledScenePage, EmptySource, FRAME_CHUNK_SIZE, FramePage,
+    OVERLAY_CHUNK_SIZE, OverlayBatch, OverlayCell, OverlayPage, PresentedFrame, ReplicaSlotError,
+    RuntimeConditionalSceneCell, RuntimeConditionalSceneChunk, RuntimeConditionalScenePage,
+    RuntimeConditionalSceneTable, SCENE_CHUNK_SIZE, SCENE_TRANSACTION_TIMEOUT_MS, SceneChunk, ScenePage, SceneTable,
+    SceneTableCell, StandardCommand, StandardError, StandardInput, StandardLightingEngine, StandardMutableState,
+    StandardReplicaSlot, StandardReplicaState, StandardReply, StandardState, UniformBackground,
 };
 pub use topology::*;
 
diff --git a/rmk/src/lighting/standard/command.rs b/rmk/src/lighting/standard/command.rs
index 589b1b89c..e809cb7ee 100644
--- a/rmk/src/lighting/standard/command.rs
+++ b/rmk/src/lighting/standard/command.rs
@@ -6,6 +6,7 @@ use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
 #[allow(unused_imports)]
 use super::*;
 use crate::RawMutex;
+use crate::lighting::Rgb8;
 use crate::lighting::compositor::{
     ExtensionDescriptor, ExtensionLayerState, ExtensionParamSpec, ExtensionState, LightingSource, RenderError,
 };
@@ -109,6 +110,11 @@ pub enum StandardCommand<const OVERLAY_CAP: usize, const SCENE_CAP: usize = 0> {
     ReadOverlay {
         offset: u16,
     },
+    /// One page of the last frame the output presented. Paged because a whole
+    /// frame is `N` RGB triples, far past any single reply's size budget.
+    ReadFrame {
+        offset: u16,
+    },
     SetSceneCellIfRevision {
         expected_revision: u32,
         cell: SceneTableCell,
@@ -189,6 +195,53 @@ pub struct StandardState {
     pub scene_len: usize,
     pub scene_policy: LayerPolicy,
     pub runtime_conditional_scene_len: usize,
+    /// What the LEDs are currently showing. `None` until the output accepts
+    /// its first frame.
+    pub presented: Option<PresentedFrame>,
+}
+
+/// Provenance of one frame the output presented: the engine revision it was
+/// rendered at and the lighting context it was rendered from.
+///
+/// Recorded at render time and promoted when the output acknowledges the
+/// write, so it describes what the LEDs show rather than what the engine now
+/// holds. On a split renderer replica the context is the *replicated* one, so
+/// comparing it against the authority's is how a stale replica becomes
+/// visible instead of merely suspected.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct PresentedFrame {
+    pub revision: u32,
+    pub context: LightingContext,
+}
+
+/// Frame cells carried by one [`FramePage`]. Kept equal to the wire chunk
+/// size so protocol adapters forward pages without re-batching.
+pub const FRAME_CHUNK_SIZE: usize = 24;
+
+/// One page of the last presented frame's logical slots.
+///
+/// Slot order is the compositor's, which is meaningful only against a
+/// validated topology; routing readback maps each slot to its node, output,
+/// and physical index.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct FramePage {
+    /// Engine revision the presented frame was rendered at. `None` before the
+    /// output has presented anything, when `cells` is still the fill color.
+    pub revision: Option<u32>,
+    /// Slots in the engine's logical frame.
+    pub total: u16,
+    /// Index of `cells[0]` within that frame.
+    pub start: u16,
+    /// Populated entries of `cells`; the rest are padding.
+    pub len: u8,
+    pub cells: [Rgb8; FRAME_CHUNK_SIZE],
+}
+
+impl FramePage {
+    /// The populated cells, in slot order from [`Self::start`].
+    pub fn cells(&self) -> &[Rgb8] {
+        &self.cells[..(self.len as usize).min(FRAME_CHUNK_SIZE)]
+    }
 }
 
 /// One page of transient overlay cells with remaining TTLs.
@@ -355,6 +408,7 @@ pub struct RuntimeConditionalScenePage {
 pub enum StandardReply {
     State(StandardState),
     OverlayPage(OverlayPage),
+    FramePage(FramePage),
     ScenesPage(ScenePage),
     CompiledScenesPage(CompiledScenePage),
     SceneTransaction { id: u32, cell_count: u16 },
diff --git a/rmk/src/lighting/standard/engine.rs b/rmk/src/lighting/standard/engine.rs
index c13d1fa9f..402c3cc19 100644
--- a/rmk/src/lighting/standard/engine.rs
+++ b/rmk/src/lighting/standard/engine.rs
@@ -6,7 +6,7 @@ use rmk_types::action::LightAction;
 use super::*;
 use crate::lighting::Rgb8;
 use crate::lighting::compositor::{Compositor, LightingSource, LogicalFrame};
-use crate::lighting::context::LightingContextProvider;
+use crate::lighting::context::{LightingContext, LightingContextProvider};
 use crate::lighting::effect::BuiltinEffect;
 use crate::lighting::output::BrightnessTransform;
 use crate::lighting::service::{CommandResult, Invalidation, LightingEngine, RenderInput, RenderOutcome};
@@ -91,6 +91,12 @@ pub struct StandardLightingEngine<
     wake_active: bool,
     effective_output_enabled: bool,
     output_brightness: u8,
+    /// Provenance of the frame currently on the LEDs.
+    presented: Option<PresentedFrame>,
+    /// Provenance of the most recent render, promoted to `presented` once the
+    /// output acknowledges the write. A render that never reaches the driver
+    /// therefore never claims to be on the LEDs.
+    rendered: PresentedFrame,
 }
 
 impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const SCENE_CAP: usize>
@@ -128,6 +134,11 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             wake_active: false,
             effective_output_enabled: true,
             output_brightness: u8::MAX,
+            presented: None,
+            rendered: PresentedFrame {
+                revision: 0,
+                context: LightingContext::default(),
+            },
         }
     }
 
@@ -177,6 +188,7 @@ impl<'scenes, Extension, Status, const N: usize, const OVERLAY_CAP: usize, const
             scene_len: self.scenes.len(),
             scene_policy: self.scenes.policy(),
             runtime_conditional_scene_len: self.runtime_conditional_scenes.len(),
+            presented: self.presented,
         }
     }
 
@@ -734,6 +746,19 @@ where
                     },
                 ));
             }
+            StandardCommand::ReadFrame { offset } => {
+                let start = (offset as usize).min(N);
+                let end = (start + FRAME_CHUNK_SIZE).min(N);
+                let mut cells = [Rgb8::BLACK; FRAME_CHUNK_SIZE];
+                cells[..end - start].copy_from_slice(&self.compositor.committed().as_slice()[start..end]);
+                return Ok(CommandResult::unchanged(StandardReply::FramePage(FramePage {
+                    revision: self.presented.map(|presented| presented.revision),
+                    total: N.min(u16::MAX as usize) as u16,
+                    start: start as u16,
+                    len: (end - start) as u8,
+                    cells,
+                })));
+            }
             StandardCommand::ReadScenes { offset } => {
                 return Ok(CommandResult::unchanged(StandardReply::ScenesPage(ScenePage {
                     revision: self.revision,
@@ -1193,6 +1218,7 @@ where
             }
             StandardCommand::ReadState => (Invalidation::None, false),
             StandardCommand::ReadOverlay { .. }
+            | StandardCommand::ReadFrame { .. }
             | StandardCommand::ReadScenes { .. }
             | StandardCommand::ReadCompiledScenes { .. }
             | StandardCommand::ReadRuntimeConditionalScenes { .. }
@@ -1241,6 +1267,10 @@ where
             self.effective_output_enabled = effective_output_enabled;
             state_changed = true;
         }
+        self.rendered = PresentedFrame {
+            revision: self.revision,
+            context: *context,
+        };
         let indicator_cell = self.controls.output_mode_indicator.map(|indicator| SceneCell {
             slot: indicator.slot,
             effect: indicator.effect(self.output_mode),
@@ -1277,6 +1307,8 @@ where
             runtime_conditional_scene_expired_transaction: _,
             runtime_conditional_scene_committed_transaction: _,
             revision: _,
+            presented: _,
+            rendered: _,
         } = self;
         let mut transaction = compositor.begin(effect_now_ms, input.snapshot, Rgb8::BLACK, frame);
         transaction.apply(priority::BACKGROUND, background)?;
@@ -1321,6 +1353,7 @@ where
 
     fn on_presented(&mut self, frame: &Self::Frame) {
         self.compositor.commit(frame);
+        self.presented = Some(self.rendered);
     }
 }
 
diff --git a/rmk/src/lighting/standard/tests.rs b/rmk/src/lighting/standard/tests.rs
index 818102374..d53d1b741 100644
--- a/rmk/src/lighting/standard/tests.rs
+++ b/rmk/src/lighting/standard/tests.rs
@@ -919,6 +919,109 @@ fn disabling_background_does_not_disable_layer_or_status_sources() {
     assert_eq!(frame.as_slice(), &[RED, GREEN]);
 }
 
+#[test]
+fn read_frame_reports_the_presented_frame_and_its_provenance() {
+    let mut engine = engine();
+    let snapshot = context(1);
+
+    // Nothing presented yet: the page is the fill color with no provenance.
+    let StandardReply::FramePage(page) = engine
+        .handle_command(0, StandardCommand::ReadFrame { offset: 0 }, &snapshot)
+        .unwrap()
+        .reply
+    else {
+        panic!("ReadFrame answers with a frame page");
+    };
+    assert_eq!(page.revision, None);
+    assert_eq!((page.total, page.start), (2, 0));
+    assert_eq!(page.cells(), &[Rgb8::BLACK, Rgb8::BLACK]);
+    assert_eq!(engine.state().presented, None);
+
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 0,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    let rendered_revision = engine.state().revision;
+
+    // A render the output never acknowledged is not on the LEDs yet.
+    let StandardReply::FramePage(page) = engine
+        .handle_command(0, StandardCommand::ReadFrame { offset: 0 }, &snapshot)
+        .unwrap()
+        .reply
+    else {
+        panic!("ReadFrame answers with a frame page");
+    };
+    assert_eq!(page.revision, None);
+    assert_eq!(page.cells(), &[Rgb8::BLACK, Rgb8::BLACK]);
+
+    <Engine as LightingEngine<LightingContext>>::on_presented(&mut engine, &frame);
+    let StandardReply::FramePage(page) = engine
+        .handle_command(0, StandardCommand::ReadFrame { offset: 0 }, &snapshot)
+        .unwrap()
+        .reply
+    else {
+        panic!("ReadFrame answers with a frame page");
+    };
+    assert_eq!(page.revision, Some(rendered_revision));
+    assert_eq!(page.cells(), frame.as_slice());
+    assert_eq!(
+        engine.state().presented,
+        Some(PresentedFrame {
+            revision: rendered_revision,
+            context: snapshot,
+        }),
+    );
+
+    // Offsets past the frame are empty rather than an error, so a host can
+    // page to exhaustion without knowing the chunk size.
+    let StandardReply::FramePage(page) = engine
+        .handle_command(0, StandardCommand::ReadFrame { offset: 9 }, &snapshot)
+        .unwrap()
+        .reply
+    else {
+        panic!("ReadFrame answers with a frame page");
+    };
+    assert_eq!((page.start, page.len), (2, 0));
+    assert!(page.cells().is_empty());
+}
+
+/// Brightness is an `OutputTransform`, so the committed frame is what the
+/// driver was handed. Dimming the output must therefore change the readback.
+#[test]
+fn presented_frame_readback_carries_the_brightness_transform() {
+    let mut engine = engine();
+    let snapshot = context(1);
+    engine
+        .handle_command(0, StandardCommand::SetOutputBrightness(128), &snapshot)
+        .unwrap();
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 0,
+                snapshot: &snapshot,
+            },
+            &mut frame,
+        )
+        .unwrap();
+    <Engine as LightingEngine<LightingContext>>::on_presented(&mut engine, &frame);
+
+    let StandardReply::FramePage(page) = engine
+        .handle_command(0, StandardCommand::ReadFrame { offset: 0 }, &snapshot)
+        .unwrap()
+        .reply
+    else {
+        panic!("ReadFrame answers with a frame page");
+    };
+    assert_eq!(page.cells(), &[Rgb8::new(100, 0, 0), Rgb8::new(5, 5, 5)]);
+}
+
 #[test]
 fn standard_engine_composes_background_layer_and_expiring_overlay() {
     let mut engine = engine();

From 624f2c10854e7302d70d0703b9b9c459e41fa874 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 6 Aug 2026 14:04:43 -0700
Subject: [PATCH 73/78] feat(rynk): add lighting frame and replica-status
 readback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two new lighting endpoints for diagnosing a split renderer replica from
the host: `GetLightingFrame` pages back what one node last presented, and
`GetLightingReplicaStatus` returns both sides of the replication
handshake in one read.

`LightingFeatureFlags` is out of bits, so these are discovered by
probing — firmware without them answers `UnknownCmd`, which is the
documented downstream path anyway. Existing layouts and the upstream
protocol version are untouched.

A remote frame page has to be reassembled from split application packets,
whose queues are shallow and lossy, so the page holds 24 cells rather
than the ~80 the payload budget would allow. Availability is encoded
explicitly: `Option` for never-observed values, and two appended
`LightingError` variants separating "no such node" from "that node could
not answer".
---
 .../main/docs/development/rynk_protocol.md    |   2 +
 rmk-types/src/protocol/rynk/command.rs        |  16 +-
 .../src/protocol/rynk/payload/lighting.rs     | 243 ++++++++++++++++++
 .../rynk/snapshots/lighting_wire_frames.snap  |   5 +
 rmk-types/src/protocol/rynk/tests.rs          |  74 ++++++
 5 files changed, 337 insertions(+), 3 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index ca7a0bd5f..184008cb9 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -131,6 +131,8 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x0933` | `PutLightingExtendedRuntimeConditionalSceneChunk`      | `PutLightingExtendedRuntimeConditionalSceneChunkRequest` | `LightingUnitResult`                                 | `lighting`       | Stage connection-aware cells for an extended replacement.                                                                                                                                                                                                                                                          |
 | `0x0934` | `CommitLightingExtendedRuntimeConditionalSceneReplace` | `CommitLightingRuntimeConditionalSceneReplaceRequest`    | `LightingStateResult`                                | `lighting`       | Publish a complete extended conditional-table replacement.                                                                                                                                                                                                                                                         |
 | `0x0935` | `AbortLightingExtendedRuntimeConditionalSceneReplace`  | `AbortLightingRuntimeConditionalSceneReplaceRequest`     | `LightingUnitResult`                                 | `lighting`       | Discard an extended conditional-table replacement.                                                                                                                                                                                                                                                                 |
+| `0x0936` | `GetLightingFrame`                                     | `LightingFrameRequest`                                   | `LightingFramePageResult`                            | `lighting`       | Read back what one lighting node last presented to its LEDs, paged. `LightingFeatureFlags` has no bits left, so support is discovered by probing: firmware without it answers `UnknownCmd`.                                                                                                                        |
+| `0x0937` | `GetLightingReplicaStatus`                             | `()`                                                     | `LightingReplicaStatusResult`                        | `lighting`       | Read both sides of the split lighting replication handshake. Probed like `GetLightingFrame`.                                                                                                                                                                                                                       |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 86ee7a873..ad3109ebb 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -43,9 +43,10 @@ use crate::protocol::rynk::{
     LightingCompiledScenesPageResult, LightingConditionalSceneStatusResult, LightingConditionalScenesPageResult,
     LightingExtendedRuntimeConditionalScenesPageResult, LightingExtensionLayersResult,
     LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionParamsPageResult,
-    LightingExtensionParamsRequest, LightingExtensionResult, LightingKeysPageResult, LightingLedsPageResult,
-    LightingOutputModeStateResult, LightingOutputsPageResult, LightingOverlayPageRequest, LightingOverlayPageResult,
-    LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKeysPageResult, LightingRoutesPageResult,
+    LightingExtensionParamsRequest, LightingExtensionResult, LightingFramePageResult, LightingFrameRequest,
+    LightingKeysPageResult, LightingLedsPageResult, LightingOutputModeStateResult, LightingOutputsPageResult,
+    LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransactionResult, LightingPageRequest,
+    LightingPhysicalKeysPageResult, LightingReplicaStatusResult, LightingRoutesPageResult,
     LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatusResult,
     LightingRuntimeConditionalSceneTransactionResult, LightingRuntimeConditionalScenesPageResult,
     LightingScenePageRequest, LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult,
@@ -520,6 +521,15 @@ endpoints! {
     /// Discard an extended conditional-table replacement.
     #[cfg(feature = "lighting")]
     AbortLightingExtendedRuntimeConditionalSceneReplace = 0x0935: AbortLightingRuntimeConditionalSceneReplaceRequest => LightingUnitResult;
+    /// Read back what one lighting node last presented to its LEDs, paged.
+    /// `LightingFeatureFlags` has no bits left, so support is discovered by
+    /// probing: firmware without it answers `UnknownCmd`.
+    #[cfg(feature = "lighting")]
+    GetLightingFrame = 0x0936: LightingFrameRequest => LightingFramePageResult;
+    /// Read both sides of the split lighting replication handshake. Probed
+    /// like `GetLightingFrame`.
+    #[cfg(feature = "lighting")]
+    GetLightingReplicaStatus = 0x0937: () => LightingReplicaStatusResult;
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index b92be70ac..14e30f399 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -25,6 +25,13 @@ pub const LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 7;
 /// legacy chunk because each cell carries the connection, bonded-slot, and
 /// effects predicates and the page still has to fit `LIGHTING_PAYLOAD_SIZE`.
 pub const LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE: usize = 5;
+/// Number of RGB cells in one presented-frame page.
+///
+/// Deliberately far below what [`LIGHTING_PAYLOAD_SIZE`] would allow: a page
+/// for a remote split node has to be assembled from application packets on
+/// the split link, whose per-message ceiling and shallow, lossy queues make a
+/// large page a large number of chances to lose one.
+pub const LIGHTING_FRAME_CHUNK_SIZE: usize = 24;
 /// Maximum UTF-8 byte length of a zone name.
 pub const LIGHTING_ZONE_NAME_SIZE: usize = 24;
 /// Maximum UTF-8 byte length of one extension effect or palette name.
@@ -1156,6 +1163,137 @@ wire_type! {
     }
 }
 
+wire_type! {
+    /// Request one page of a lighting node's last presented frame.
+    ///
+    /// `offset` is the first logical frame slot wanted, matching every other
+    /// lighting page request; the reply echoes it as
+    /// [`LightingFramePage::start`]. Frames are not revision-pinned: a stale
+    /// page is the observation being made, not an error, and pinning would
+    /// make the frame unreadable exactly while it is changing.
+    pub struct LightingFrameRequest {
+        pub node: LightingNodeId,
+        pub offset: u16,
+    }
+}
+
+/// One page of the colors a lighting node last presented to its output.
+///
+/// Cells are the post-brightness logical frame: RMK applies output
+/// brightness as a frame transform before the frame is written and
+/// committed, so these are the values the driver received. Any further
+/// scaling a board's driver performs on the way to the wire is below this
+/// layer and is not reflected here.
+///
+/// Cell order is compositor slot order, meaningful only against a validated
+/// topology; `GetLightingRoutes` maps each LED to its node, output, and
+/// physical index.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
+#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
+pub struct LightingFramePage {
+    pub node: LightingNodeId,
+    /// Engine revision the frame was captured at. `None` when the node has
+    /// not presented a frame yet, when the cells are still its fill color.
+    pub revision: Option<u32>,
+    /// Slots in this node's logical frame.
+    pub total_leds: u16,
+    /// Index of `cells[0]` within that frame.
+    pub start: u16,
+    /// How long ago the capture happened. Always `0` for the node serving the
+    /// request; for a remote node it is the round-trip staleness of the
+    /// answer, which is what makes a frozen half distinguishable from a
+    /// correct one.
+    pub age_ms: u32,
+    #[cfg_attr(feature = "wasm", tsify(type = "LightingRgb8[]"))]
+    pub cells: Vec<LightingRgb8, LIGHTING_FRAME_CHUNK_SIZE>,
+}
+
+impl MaxSize for LightingFramePage {
+    const POSTCARD_MAX_SIZE: usize = LightingNodeId::POSTCARD_MAX_SIZE
+        + <Option<u32> as MaxSize>::POSTCARD_MAX_SIZE
+        + 2 * u16::POSTCARD_MAX_SIZE
+        + u32::POSTCARD_MAX_SIZE
+        + crate::heapless_vec_max_size::<LightingRgb8, LIGHTING_FRAME_CHUNK_SIZE>();
+}
+
+wire_type! {
+    /// The lighting authority's own state, as the central half sees it.
+    pub struct LightingCentralReplicaState {
+        /// Live engine revision — what the authority would replicate now.
+        pub revision: u32,
+        /// Engine revision of the last frame the central presented. `None`
+        /// before its output has accepted one.
+        pub presented_revision: Option<u32>,
+        /// Layer state the central's last presented frame was rendered from.
+        /// Zeroed before that first frame.
+        pub effective_layer: u8,
+        pub default_layer: u8,
+        pub active_bits: u64,
+        /// Live USB/VBUS power as the engine sees it.
+        pub powered: bool,
+    }
+}
+
+wire_type! {
+    /// Central-side replication machine, supplied by the board.
+    ///
+    /// This is the half of the handshake the protocol cannot infer: whether a
+    /// snapshot is outstanding, which revision was last acknowledged, and
+    /// whether the application link is up at all.
+    pub struct LightingReplicationMachine {
+        /// Last revision the peripheral acknowledged. `None` when it has
+        /// never acknowledged one since boot.
+        pub last_acked_revision: Option<u32>,
+        /// A snapshot is in flight and its acknowledgement is still pending.
+        pub awaiting_ack: bool,
+        /// Bumped whenever the central restarts replication, so a host can
+        /// tell a resend apart from a stuck retry.
+        pub generation: u8,
+        pub link_up: bool,
+    }
+}
+
+wire_type! {
+    /// Last state heard from a peripheral renderer.
+    ///
+    /// Deliberately stale-tolerant: the board answers from whatever it last
+    /// received rather than blocking on a round trip, and `age_ms` says how
+    /// old that is. A large age is itself the diagnosis.
+    pub struct LightingPeripheralReplicaState {
+        pub node: LightingNodeId,
+        /// Central revision whose snapshot the peripheral last applied.
+        /// `None` when it has applied none.
+        pub applied_revision: Option<u32>,
+        /// The peripheral engine's own revision, which advances locally as
+        /// well and so is not comparable to `applied_revision`.
+        pub engine_revision: u32,
+        /// Layer state the peripheral is rendering from — the replicated
+        /// context, which is where staleness shows up first.
+        pub effective_layer: u8,
+        pub default_layer: u8,
+        pub active_bits: u64,
+        pub powered: bool,
+        pub wake_active: bool,
+        pub effective_output_enabled: bool,
+        pub age_ms: u32,
+    }
+}
+
+wire_type! {
+    /// Both sides of the lighting replication handshake in one read.
+    pub struct LightingReplicaStatus {
+        pub central: LightingCentralReplicaState,
+        /// `None` when the board wired no replication machine, as an
+        /// unsplit build does.
+        pub replication: Option<LightingReplicationMachine>,
+        /// `None` when the board has heard nothing from the peripheral since
+        /// boot, which is distinct from having heard something stale.
+        pub peripheral: Option<LightingPeripheralReplicaState>,
+    }
+}
+
 wire_type! {
     /// Lighting-domain rejection carried inside Rynk's outer protocol result.
     pub enum LightingError {
@@ -1176,6 +1314,16 @@ wire_type! {
         UnknownLayer { layer: u8 },
         SceneFull { capacity: u16 },
         ConditionalSceneFull { capacity: u16 },
+        // Appended for the observability endpoints; only they can produce
+        // these, so older hosts never decode them.
+        /// No lighting node with this id exists in the device's routing.
+        UnknownNode { node: LightingNodeId },
+        /// The node exists but could not answer: the application link is
+        /// down, the reply timed out, or the board wired no source for it.
+        /// Distinct from `Unsupported`, which means the firmware never
+        /// answers this node — retrying is pointless there and reasonable
+        /// here.
+        NodeUnavailable { node: LightingNodeId },
     }
 }
 
@@ -1209,6 +1357,8 @@ pub type LightingRuntimeConditionalScenesPageResult = LightingResult<LightingRun
 pub type LightingExtendedRuntimeConditionalScenesPageResult =
     LightingResult<LightingExtendedRuntimeConditionalScenesPage>;
 pub type LightingRuntimeConditionalSceneTransactionResult = LightingResult<LightingRuntimeConditionalSceneTransaction>;
+pub type LightingFramePageResult = LightingResult<LightingFramePage>;
+pub type LightingReplicaStatusResult = LightingResult<LightingReplicaStatus>;
 pub type LightingUnitResult = LightingResult<()>;
 
 wire_type! {
@@ -1287,6 +1437,8 @@ const _: () = {
     assert_endpoint_fits!(PutLightingSceneChunkRequest, LightingUnitResult);
     assert_endpoint_fits!(CommitLightingSceneReplaceRequest, LightingStateResult);
     assert_endpoint_fits!(AbortLightingSceneReplaceRequest, LightingUnitResult);
+    assert_endpoint_fits!(LightingFrameRequest, LightingFramePageResult);
+    assert_endpoint_fits!((), LightingReplicaStatusResult);
 };
 
 #[cfg(test)]
@@ -1447,6 +1599,97 @@ mod tests {
         assert!(LightingCompiledScenesPage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
     }
 
+    #[test]
+    fn frame_page_round_trips_at_capacity() {
+        let mut cells = Vec::new();
+        for index in 0..LIGHTING_FRAME_CHUNK_SIZE as u8 {
+            cells
+                .push(LightingRgb8 {
+                    r: index,
+                    g: u8::MAX - index,
+                    b: u8::MAX,
+                })
+                .unwrap();
+        }
+        let page = LightingFramePage {
+            node: LightingNodeId(u8::MAX),
+            revision: Some(u32::MAX),
+            total_leds: u16::MAX,
+            start: u16::MAX,
+            age_ms: u32::MAX,
+            cells,
+        };
+        round_trip(&page);
+        assert_max_size_bound(&page);
+        assert!(LightingFramePage::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+
+        // The unpresented and empty-tail cases hosts hit while paging.
+        round_trip(&LightingFramePage {
+            revision: None,
+            cells: Vec::new(),
+            ..page
+        });
+        round_trip(&LightingFrameRequest {
+            node: LightingNodeId(1),
+            offset: u16::MAX,
+        });
+    }
+
+    #[test]
+    fn replica_status_round_trips_present_and_absent_sides() {
+        let full = LightingReplicaStatus {
+            central: LightingCentralReplicaState {
+                revision: u32::MAX,
+                presented_revision: Some(u32::MAX - 1),
+                effective_layer: 3,
+                default_layer: 1,
+                active_bits: u64::MAX,
+                powered: true,
+            },
+            replication: Some(LightingReplicationMachine {
+                last_acked_revision: Some(u32::MAX - 2),
+                awaiting_ack: true,
+                generation: u8::MAX,
+                link_up: true,
+            }),
+            peripheral: Some(LightingPeripheralReplicaState {
+                node: LightingNodeId(1),
+                applied_revision: Some(u32::MAX - 3),
+                engine_revision: u32::MAX - 4,
+                effective_layer: 2,
+                default_layer: 0,
+                active_bits: 1 << 63,
+                powered: false,
+                wake_active: true,
+                effective_output_enabled: false,
+                age_ms: u32::MAX,
+            }),
+        };
+        round_trip(&full);
+        assert_max_size_bound(&full);
+        assert!(LightingReplicaStatus::POSTCARD_MAX_SIZE <= LIGHTING_PAYLOAD_SIZE);
+
+        // Never-heard-from is encoded as absence, not as a zero snapshot.
+        round_trip(&LightingReplicaStatus {
+            replication: None,
+            peripheral: None,
+            central: LightingCentralReplicaState {
+                presented_revision: None,
+                ..full.central
+            },
+        });
+    }
+
+    #[test]
+    fn node_errors_round_trip() {
+        round_trip(&LightingError::UnknownNode {
+            node: LightingNodeId(u8::MAX),
+        });
+        round_trip(&LightingError::NodeUnavailable {
+            node: LightingNodeId(1),
+        });
+    }
+
     #[test]
     fn conditional_scene_page_round_trips_at_capacity() {
         let mut items = Vec::new();
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index 119cb1f67..9ce5429b0 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -50,6 +50,9 @@ GetLightingExtensionNames reply                               04 22 09 01 01 09
 GetLightingExtensionNames request                             06 22 09 01 01 08 00
 GetLightingExtensionParams reply                              04 2b 09 01 01 10 09 02 01 07 44 65 6e 73 69 74 79 01 08 03 05 00
 GetLightingExtensionParams request                            05 2b 09 01 01 01 00
+GetLightingFrame reply                                        04 36 09 01 01 0b 01 01 09 50 18 25 01 01 02 03 00
+GetLightingFrame reply Err(NodeUnavailable)                   04 36 09 01 04 01 10 01 00
+GetLightingFrame request                                      06 36 09 01 01 18 00
 GetLightingKeys reply                                         04 11 09 01 01 06 01 01 01 01 02 00
 GetLightingKeys request                                       05 11 09 01 01 01 00
 GetLightingLeds reply                                         04 05 09 01 01 11 01 01 01 2a 01 01 02 01 ff 01 80 04 80 01 03 01 00
@@ -62,6 +65,8 @@ GetLightingOverlay reply                                      04 1b 09 01 01 11
 GetLightingOverlay request                                    05 1b 09 01 09 01 00
 GetLightingPhysicalKeys reply                                 04 04 09 01 01 12 01 01 01 01 02 ff 01 80 04 80 01 80 02 80 03 db 0b 00
 GetLightingPhysicalKeys request                               05 04 09 01 01 01 00
+GetLightingReplicaStatus reply                                04 37 09 01 01 16 09 01 08 02 01 06 01 01 01 07 01 04 01 01 01 01 06 05 01 01 02 02 01 03 fa 01 00
+GetLightingReplicaStatus request                              04 37 09 01 00
 GetLightingRoutes reply                                       04 09 09 01 01 08 01 01 01 2a 01 02 07 00
 GetLightingRoutes request                                     05 09 09 01 01 01 00
 GetLightingRuntimeConditionalSceneStatus reply                04 25 09 01 01 05 09 40 01 07 00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index eac5ae55d..4ef5dbb60 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1462,6 +1462,46 @@ fn lighting_wire_frames_locked() {
         offset: 0,
         cells: one(extended_conditional_cell),
     };
+    let frame_request = LightingFrameRequest {
+        node: LightingNodeId(1),
+        offset: 24,
+    };
+    let frame_page = LightingFramePage {
+        node: frame_request.node,
+        revision: Some(state.revision),
+        total_leds: 80,
+        start: frame_request.offset,
+        age_ms: 37,
+        cells: one(LightingRgb8 { r: 1, g: 2, b: 3 }),
+    };
+    let replica_status = LightingReplicaStatus {
+        central: LightingCentralReplicaState {
+            revision: state.revision,
+            presented_revision: Some(state.revision - 1),
+            effective_layer: 2,
+            default_layer: 1,
+            active_bits: 0b110,
+            powered: true,
+        },
+        replication: Some(LightingReplicationMachine {
+            last_acked_revision: Some(state.revision - 2),
+            awaiting_ack: true,
+            generation: 4,
+            link_up: true,
+        }),
+        peripheral: Some(LightingPeripheralReplicaState {
+            node: frame_request.node,
+            applied_revision: Some(state.revision - 3),
+            engine_revision: 5,
+            effective_layer: 1,
+            default_layer: 1,
+            active_bits: 0b10,
+            powered: false,
+            wake_active: true,
+            effective_output_enabled: false,
+            age_ms: 250,
+        }),
+    };
 
     let entries: alloc::vec::Vec<(&str, alloc::vec::Vec<u8>)> = alloc::vec![
         (
@@ -2156,6 +2196,40 @@ fn lighting_wire_frames_locked() {
                 &Ok::<LightingStateResult, RynkError>(Ok(state))
             )
         ),
+        (
+            "GetLightingFrame request",
+            encode_frame(Cmd::GetLightingFrame, SEQ, &frame_request)
+        ),
+        (
+            "GetLightingFrame reply",
+            encode_frame(
+                Cmd::GetLightingFrame,
+                SEQ,
+                &Ok::<LightingFramePageResult, RynkError>(Ok(frame_page))
+            )
+        ),
+        (
+            "GetLightingFrame reply Err(NodeUnavailable)",
+            encode_frame(
+                Cmd::GetLightingFrame,
+                SEQ,
+                &Ok::<LightingFramePageResult, RynkError>(Err(LightingError::NodeUnavailable {
+                    node: frame_request.node
+                }))
+            )
+        ),
+        (
+            "GetLightingReplicaStatus request",
+            encode_frame(Cmd::GetLightingReplicaStatus, SEQ, &())
+        ),
+        (
+            "GetLightingReplicaStatus reply",
+            encode_frame(
+                Cmd::GetLightingReplicaStatus,
+                SEQ,
+                &Ok::<LightingReplicaStatusResult, RynkError>(Ok(replica_status))
+            )
+        ),
         (
             "LightingChange topic",
             encode_frame(Cmd::LightingChange, 0, &LightingChanged)

From 6077ff4fd8f184804578dba955ac82b528f7c59d Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 6 Aug 2026 16:05:50 -0700
Subject: [PATCH 74/78] feat(rynk): serve the frame and replica-status
 endpoints

Wires GetLightingFrame and GetLightingReplicaStatus through the host
service: the local half answers from its own engine, the peripheral
through the board-provided remote-frame and replication-status ports,
and the loopback integration tests drive both endpoints end to end.
Native rmk-types and rynk_lighting suites pass; the cross-feature
matrix and no_std target checks have not run yet.
---
 rmk/src/host/mod.rs                    |  13 +-
 rmk/src/host/rynk/handlers/lighting.rs | 136 +++++++--
 rmk/src/host/rynk/lighting.rs          | 377 ++++++++++++++++++++++++-
 rmk/src/host/rynk/mod.rs               |  15 +-
 rmk/src/lighting/standard/mod.rs       |   5 +
 rmk/tests/integration/rynk_lighting.rs | 237 +++++++++++++++-
 6 files changed, 748 insertions(+), 35 deletions(-)

diff --git a/rmk/src/host/mod.rs b/rmk/src/host/mod.rs
index 5817c80fc..122b7e291 100644
--- a/rmk/src/host/mod.rs
+++ b/rmk/src/host/mod.rs
@@ -24,14 +24,15 @@ pub(crate) mod via;
 /// two are mutually exclusive).
 #[cfg(feature = "rynk")]
 pub use rynk::RynkService as HostService;
-/// RMK's semantic version, available to downstream firmware build labels.
-#[cfg(feature = "rynk")]
-pub use rynk::{RMK_VERSION, RMK_VERSION_STRING};
 #[cfg(all(feature = "rynk", feature = "lighting"))]
 pub use rynk::{
-    RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
-    RynkLightingReadback, StandardRynkLightingAdapter, install_lighting_runtime_conditional_scenes,
-    install_lighting_scenes,
+    LightingReplicationStatus, PeripheralReplicaStatus, RYNK_LIGHTING_TRANSACTION_CAPACITY, RemoteFrame,
+    RemoteFramePort, RemoteFrameRequest, ReplicationMachineState, RynkLightingController, RynkLightingDescriptor,
+    RynkLightingMailbox, RynkLightingReadback, StandardRynkLightingAdapter,
+    install_lighting_runtime_conditional_scenes, install_lighting_scenes,
 };
+/// RMK's semantic version, available to downstream firmware build labels.
+#[cfg(feature = "rynk")]
+pub use rynk::{RMK_VERSION, RMK_VERSION_STRING};
 #[cfg(feature = "vial")]
 pub use via::VialService as HostService;
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 18e499066..58792af37 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -10,8 +10,8 @@ use rmk_types::protocol::rynk::command::{
     GetLightingCompiledScenes, GetLightingConditionalSceneStatus, GetLightingConditionalScenes,
     GetLightingExtendedRuntimeConditionalSceneStatus, GetLightingExtendedRuntimeConditionalScenes,
     GetLightingExtension, GetLightingExtensionLayers, GetLightingExtensionNames, GetLightingExtensionParams,
-    GetLightingKeys, GetLightingLeds, GetLightingOutputMode, GetLightingOutputs, GetLightingOverlay,
-    GetLightingPhysicalKeys, GetLightingRoutes, GetLightingRuntimeConditionalSceneStatus,
+    GetLightingFrame, GetLightingKeys, GetLightingLeds, GetLightingOutputMode, GetLightingOutputs, GetLightingOverlay,
+    GetLightingPhysicalKeys, GetLightingReplicaStatus, GetLightingRoutes, GetLightingRuntimeConditionalSceneStatus,
     GetLightingRuntimeConditionalScenes, GetLightingSceneStatus, GetLightingScenes, GetLightingState,
     GetLightingZoneMemberships, GetLightingZones, PutLightingExtendedRuntimeConditionalSceneChunk,
     PutLightingRuntimeConditionalSceneChunk, SetLightingExtensionLayers, SetLightingExtensionParam,
@@ -25,25 +25,26 @@ use rmk_types::protocol::rynk::{
     CommitLightingOverlayReplaceRequest, CommitLightingRuntimeConditionalSceneReplaceRequest,
     CommitLightingSceneReplaceRequest, LIGHTING_CONDITIONAL_SCENE_CHUNK_SIZE,
     LIGHTING_EXTENDED_CONDITIONAL_SCENE_CHUNK_SIZE, LIGHTING_PAGE_SIZE, LIGHTING_SCENE_CHUNK_SIZE,
-    LIGHTING_ZONE_NAME_SIZE, LightingCapabilities, LightingCapabilitiesResult, LightingCompiledSceneStatus,
-    LightingCompiledSceneStatusResult, LightingCompiledScenesPageResult, LightingConditionalSceneCell,
-    LightingConditionalSceneStatus, LightingConditionalSceneStatusResult, LightingConditionalScenesPage,
-    LightingConditionalScenesPageResult, LightingEffectFlags, LightingError,
+    LIGHTING_ZONE_NAME_SIZE, LightingCapabilities, LightingCapabilitiesResult, LightingCentralReplicaState,
+    LightingCompiledSceneStatus, LightingCompiledSceneStatusResult, LightingCompiledScenesPageResult,
+    LightingConditionalSceneCell, LightingConditionalSceneStatus, LightingConditionalSceneStatusResult,
+    LightingConditionalScenesPage, LightingConditionalScenesPageResult, LightingEffectFlags, LightingError,
     LightingExtendedRuntimeConditionalScenesPageResult, LightingExtensionLayersResult,
     LightingExtensionNamesPageResult, LightingExtensionNamesRequest, LightingExtensionParamsPageResult,
-    LightingExtensionParamsRequest, LightingExtensionResult, LightingFeatureFlags, LightingKeysPage,
-    LightingKeysPageResult, LightingLed, LightingLedId, LightingLedsPage, LightingLedsPageResult,
-    LightingMatrixPosition, LightingOutput, LightingOutputCapabilities, LightingOutputCoverage,
-    LightingOutputModeStateResult, LightingOutputsPage, LightingOutputsPageResult, LightingOverlayCell,
-    LightingOverlayPageRequest, LightingOverlayPageResult, LightingOverlayTransaction,
-    LightingOverlayTransactionResult, LightingPageRequest, LightingPhysicalKey, LightingPhysicalKeysPage,
-    LightingPhysicalKeysPageResult, LightingPoint3, LightingResult, LightingRoute, LightingRoutesPage,
-    LightingRoutesPageResult, LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
-    LightingRuntimeConditionalSceneStatusResult, LightingRuntimeConditionalSceneTransactionResult,
-    LightingRuntimeConditionalScenesPageResult, LightingScenePageRequest, LightingSceneStatus,
-    LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult, LightingState,
-    LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage,
-    LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult,
+    LightingExtensionParamsRequest, LightingExtensionResult, LightingFeatureFlags, LightingFramePage,
+    LightingFramePageResult, LightingFrameRequest, LightingKeysPage, LightingKeysPageResult, LightingLed,
+    LightingLedId, LightingLedsPage, LightingLedsPageResult, LightingMatrixPosition, LightingNodeId, LightingOutput,
+    LightingOutputCapabilities, LightingOutputCoverage, LightingOutputModeStateResult, LightingOutputsPage,
+    LightingOutputsPageResult, LightingOverlayCell, LightingOverlayPageRequest, LightingOverlayPageResult,
+    LightingOverlayTransaction, LightingOverlayTransactionResult, LightingPageRequest, LightingPeripheralReplicaState,
+    LightingPhysicalKey, LightingPhysicalKeysPage, LightingPhysicalKeysPageResult, LightingPoint3,
+    LightingReplicaStatus, LightingReplicaStatusResult, LightingReplicationMachine, LightingResult, LightingRgb8,
+    LightingRoute, LightingRoutesPage, LightingRoutesPageResult, LightingRuntimeConditionalScenePageRequest,
+    LightingRuntimeConditionalSceneStatus, LightingRuntimeConditionalSceneStatusResult,
+    LightingRuntimeConditionalSceneTransactionResult, LightingRuntimeConditionalScenesPageResult,
+    LightingScenePageRequest, LightingSceneStatus, LightingSceneStatusResult, LightingSceneTransactionResult,
+    LightingScenesPageResult, LightingState, LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId,
+    LightingZoneMembershipsPage, LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult,
     PutLightingExtendedRuntimeConditionalSceneChunkRequest, PutLightingOverlayChunkRequest,
     PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, RynkError, RynkMessage,
     SetLightingExtensionLayersRequest, SetLightingExtensionParamRequest, SetLightingExtensionStateRequest,
@@ -995,6 +996,103 @@ impl Handle<SetLightingExtensionParam> for RynkService<'_> {
     }
 }
 
+impl Handle<GetLightingFrame> for RynkService<'_> {
+    async fn handle(&self, req: LightingFrameRequest) -> Result<LightingFramePageResult, RynkError> {
+        Ok(match controller(self) {
+            Ok(controller) => frame_page(controller, req).await,
+            Err(error) => Err(error),
+        })
+    }
+}
+
+async fn frame_page(
+    controller: RynkLightingController<'_>,
+    req: LightingFrameRequest,
+) -> LightingResult<LightingFramePage> {
+    let (page, age_ms) = controller
+        .frame_page(crate::lighting::LightingNodeId(req.node.0), req.offset)
+        .await?;
+    let mut cells = Vec::new();
+    for cell in page.cells() {
+        cells
+            .push(LightingRgb8 {
+                r: cell.r,
+                g: cell.g,
+                b: cell.b,
+            })
+            .expect("engine and wire frame pages hold the same number of cells");
+    }
+    Ok(LightingFramePage {
+        node: req.node,
+        revision: page.revision,
+        total_leds: page.total,
+        start: page.start,
+        age_ms,
+        cells,
+    })
+}
+
+impl Handle<GetLightingReplicaStatus> for RynkService<'_> {
+    async fn handle(&self, _: ()) -> Result<LightingReplicaStatusResult, RynkError> {
+        Ok(match controller(self) {
+            Ok(controller) => replica_status(controller).await,
+            Err(error) => Err(error),
+        })
+    }
+}
+
+async fn replica_status(controller: RynkLightingController<'_>) -> LightingResult<LightingReplicaStatus> {
+    // `ReadOutputMode` is the mailbox's full `StandardState` readback; the
+    // name records its first caller, not its contents.
+    let state = match controller.request(RynkLightingCommand::ReadOutputMode).await? {
+        RynkLightingReadback::OutputMode(state) => state,
+        _ => return Err(LightingError::InvalidRequest),
+    };
+    let presented = state.presented;
+    let central = LightingCentralReplicaState {
+        revision: state.revision,
+        presented_revision: presented.map(|presented| presented.revision),
+        effective_layer: presented.map_or(0, |presented| presented.context.layers.effective),
+        default_layer: presented.map_or(0, |presented| presented.context.layers.default),
+        active_bits: presented.map_or(0, |presented| presented.context.layers.active_bits()),
+        powered: state.powered,
+    };
+
+    let Some(status) = controller.replication else {
+        return Ok(LightingReplicaStatus {
+            central,
+            replication: None,
+            peripheral: None,
+        });
+    };
+    let machine = status.central();
+    let peripheral = controller.peripheral_node().and_then(|node| {
+        let peripheral = status.peripheral(node)?;
+        Some(LightingPeripheralReplicaState {
+            node: LightingNodeId(node.0),
+            applied_revision: peripheral.applied_revision,
+            engine_revision: peripheral.engine_revision,
+            effective_layer: peripheral.layers.effective,
+            default_layer: peripheral.layers.default,
+            active_bits: peripheral.layers.active_bits(),
+            powered: peripheral.powered,
+            wake_active: peripheral.wake_active,
+            effective_output_enabled: peripheral.effective_output_enabled,
+            age_ms: peripheral.age_ms,
+        })
+    });
+    Ok(LightingReplicaStatus {
+        central,
+        replication: Some(LightingReplicationMachine {
+            last_acked_revision: machine.last_acked_revision,
+            awaiting_ack: machine.awaiting_ack,
+            generation: machine.generation,
+            link_up: machine.link_up,
+        }),
+        peripheral,
+    })
+}
+
 impl Handle<GetLightingKeys> for RynkService<'_> {
     async fn handle(&self, req: LightingPageRequest) -> Result<LightingKeysPageResult, RynkError> {
         Ok(controller(self).and_then(|binding| keys_page(binding, req)))
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index e34298ba9..810329d4a 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -32,10 +32,11 @@ use rmk_types::protocol::rynk::{
 use crate::RawMutex;
 use crate::core_traits::Runnable;
 use crate::lighting::{
-    BackgroundMode, BackgroundState, BuiltinEffect, ConditionalSceneCell, LayerPolicy, LedId, LightingControls,
-    LightingMailbox, LightingRouting, LightingTopology, OVERLAY_CHUNK_SIZE, OutputMode, OverlayBatch, OverlayCell,
-    OverlayError, Rgb8, RuntimeConditionalSceneCell, RuntimeConditionalSceneChunk, SceneChunk, SceneTableCell,
-    StandardCommand, StandardError, StandardLightingEngine, StandardMutableState, StandardReply, StandardState,
+    BackgroundMode, BackgroundState, BuiltinEffect, ConditionalSceneCell, FramePage, LayerPolicy, LayerState, LedId,
+    LightingControls, LightingMailbox, LightingNodeId, LightingRouting, LightingTopology, OVERLAY_CHUNK_SIZE,
+    OutputMode, OverlayBatch, OverlayCell, OverlayError, Rgb8, RuntimeConditionalSceneCell,
+    RuntimeConditionalSceneChunk, SceneChunk, SceneTableCell, StandardCommand, StandardError, StandardLightingEngine,
+    StandardMutableState, StandardReply, StandardState,
 };
 
 const _: () = core::assert!(
@@ -60,6 +61,154 @@ pub const RYNK_LIGHTING_TRANSACTION_CAPACITY: usize = 64;
 
 const RYNK_LIGHTING_COMMAND_CAPACITY: usize = 4;
 
+/// How long a remote-frame fetch waits before reporting the node unavailable.
+///
+/// Matched to the split lighting layer's own acknowledgement timeout: a
+/// round trip that has not landed by then is lost, not slow, and a host
+/// polling frames must not stall behind a half that is gone.
+const REMOTE_FRAME_TIMEOUT_MS: u64 = 500;
+
+/// One node's presented-frame page plus how stale it is.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct RemoteFrame {
+    /// The page as the remote node's engine reported it. `page.start` must
+    /// echo the request's offset; `page.total` is the remote frame's length,
+    /// which need not match the local one.
+    pub page: FramePage,
+    /// Milliseconds between the remote capture and this answer.
+    pub age_ms: u32,
+}
+
+/// One outstanding fetch on a [`RemoteFramePort`].
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct RemoteFrameRequest {
+    /// Correlation token. Answer with exactly this id: an answer to a fetch
+    /// that already timed out is then discarded rather than mistaken for the
+    /// answer to the next one.
+    pub id: u32,
+    pub node: LightingNodeId,
+    /// First logical frame slot wanted. Answering with fewer than
+    /// [`crate::lighting::FRAME_CHUNK_SIZE`] cells is fine; answering with a
+    /// different `start` is not.
+    pub offset: u16,
+}
+
+struct RemoteFrameResponse {
+    id: u32,
+    frame: Option<RemoteFrame>,
+}
+
+/// Board-provided source for another lighting node's presented frame.
+///
+/// RMK owns no split transport for frames, so the port is a rendezvous: the
+/// Rynk handler parks on it, a board task takes the request, performs
+/// whatever round trip its link needs, and answers. It is shaped like
+/// [`RynkLightingMailbox`] for the same reasons — it lives in a `static`, so
+/// an ordinary embassy task holds `&'static Self` with no allocation, and no
+/// generic parameter reaches [`super::RynkService`].
+pub struct RemoteFramePort {
+    request: Signal<RawMutex, RemoteFrameRequest>,
+    response: Signal<RawMutex, RemoteFrameResponse>,
+    caller: Mutex<RawMutex, ()>,
+    next_id: BlockingMutex<RawMutex, Cell<u32>>,
+}
+
+impl RemoteFramePort {
+    pub const fn new() -> Self {
+        Self {
+            request: Signal::new(),
+            response: Signal::new(),
+            caller: Mutex::new(()),
+            next_id: BlockingMutex::new(Cell::new(0)),
+        }
+    }
+
+    /// Board side: wait for the next fetch. Cancel-safe.
+    pub async fn receive(&self) -> RemoteFrameRequest {
+        self.request.wait().await
+    }
+
+    /// Board side: answer the fetch identified by `id`. `None` reports that
+    /// the node could not answer — link down, no reply, or a malformed one —
+    /// and surfaces to the host as `NodeUnavailable`. Answering late is safe;
+    /// the correlation token makes the stale answer inert.
+    pub fn reply(&self, id: u32, frame: Option<RemoteFrame>) {
+        self.response.signal(RemoteFrameResponse { id, frame });
+    }
+
+    /// Protocol side: fetch one page, or `None` on failure or timeout.
+    async fn fetch(&self, node: LightingNodeId, offset: u16) -> Option<RemoteFrame> {
+        let _caller = self.caller.lock().await;
+        let id = self.next_id.lock(|next| {
+            let id = next.get();
+            next.set(id.wrapping_add(1));
+            id
+        });
+        self.request.signal(RemoteFrameRequest { id, node, offset });
+        embassy_time::with_timeout(embassy_time::Duration::from_millis(REMOTE_FRAME_TIMEOUT_MS), async {
+            loop {
+                let response = self.response.wait().await;
+                if response.id == id {
+                    return response.frame;
+                }
+            }
+        })
+        .await
+        .ok()
+        .flatten()
+    }
+}
+
+impl Default for RemoteFramePort {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Central-side state of the split lighting replication machine.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct ReplicationMachineState {
+    /// Last revision a peripheral acknowledged, or `None` since boot.
+    pub last_acked_revision: Option<u32>,
+    /// A snapshot is in flight and unacknowledged.
+    pub awaiting_ack: bool,
+    /// Bumped whenever replication restarts, so a host can tell a resend
+    /// apart from a retry that is stuck.
+    pub generation: u8,
+    pub link_up: bool,
+}
+
+/// The last renderer state a peripheral reported.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct PeripheralReplicaStatus {
+    /// Central revision whose snapshot the peripheral last applied.
+    pub applied_revision: Option<u32>,
+    /// The peripheral engine's own revision, which also advances locally.
+    pub engine_revision: u32,
+    /// Layer state the peripheral is rendering from — the replicated
+    /// context, so a divergence from the central's is the stale-replica
+    /// symptom made visible.
+    pub layers: LayerState,
+    pub powered: bool,
+    pub wake_active: bool,
+    pub effective_output_enabled: bool,
+    /// Age of this report at the time it is read.
+    pub age_ms: u32,
+}
+
+/// Board-provided view of the split lighting replication handshake.
+///
+/// Synchronous on purpose: the board keeps this in a `static` its split
+/// tasks update, and reads answer from the last thing heard rather than
+/// blocking on the link. A read that blocked could not distinguish a slow
+/// link from a dead one, which is the distinction being debugged.
+pub trait LightingReplicationStatus {
+    fn central(&self) -> ReplicationMachineState;
+
+    /// The last status heard from `node`, or `None` if none ever arrived.
+    fn peripheral(&self, node: LightingNodeId) -> Option<PeripheralReplicaStatus>;
+}
+
 #[derive(Clone, Copy)]
 pub struct RynkLightingDescriptor<'a> {
     pub topology_revision: u32,
@@ -83,6 +232,10 @@ pub struct RynkLightingController<'a> {
     /// `EXTENSION_EFFECTS` capability bit and the extension endpoints.
     pub(super) extension_effects: bool,
     pub(super) extension_layering: bool,
+    /// Which routing node this half renders locally.
+    pub(super) local_node: LightingNodeId,
+    pub(super) remote_frames: Option<&'a RemoteFramePort>,
+    pub(super) replication: Option<&'a dyn LightingReplicationStatus>,
     mailbox: &'a RynkLightingMailbox,
 }
 
@@ -115,10 +268,68 @@ impl<'a> RynkLightingController<'a> {
             },
             extension_effects: false,
             extension_layering: false,
+            local_node: LightingNodeId(0),
+            remote_frames: None,
+            replication: None,
             mailbox,
         }
     }
 
+    /// Name the routing node this half renders. Frame reads for it are served
+    /// from the local engine; every other known node goes through
+    /// [`Self::with_remote_frames`]. Defaults to node `0`.
+    pub const fn with_local_node(mut self, node: LightingNodeId) -> Self {
+        self.local_node = node;
+        self
+    }
+
+    /// Wire a board source for other nodes' presented frames. Without it,
+    /// reading a remote node's frame answers `Unsupported`.
+    pub const fn with_remote_frames(mut self, port: &'a RemoteFramePort) -> Self {
+        self.remote_frames = Some(port);
+        self
+    }
+
+    /// Wire the board's view of the replication handshake. Without it, the
+    /// replica-status read still reports the central's own engine, and the
+    /// machine and peripheral halves are absent rather than fabricated.
+    pub const fn with_replication_status(mut self, status: &'a dyn LightingReplicationStatus) -> Self {
+        self.replication = Some(status);
+        self
+    }
+
+    /// Fetch one page of `node`'s presented frame, resolving local versus
+    /// remote. `age_ms` is `0` for the local node, which has no round trip.
+    pub(super) async fn frame_page(&self, node: LightingNodeId, offset: u16) -> LightingResult<(FramePage, u32)> {
+        if node == self.local_node {
+            return match self.request(RynkLightingCommand::ReadFrame { offset }).await? {
+                RynkLightingReadback::FramePage(page) => Ok((page, 0)),
+                _ => Err(LightingError::InvalidRequest),
+            };
+        }
+        let wire_node = rmk_types::protocol::rynk::LightingNodeId(node.0);
+        if !self.descriptor.routing.outputs.iter().any(|output| output.node == node) {
+            return Err(LightingError::UnknownNode { node: wire_node });
+        }
+        let port = self.remote_frames.ok_or(LightingError::Unsupported)?;
+        let remote = port
+            .fetch(node, offset)
+            .await
+            .ok_or(LightingError::NodeUnavailable { node: wire_node })?;
+        Ok((remote.page, remote.age_ms))
+    }
+
+    /// The first routing node that is not this half — the peripheral whose
+    /// replica status the handshake read reports.
+    pub(super) fn peripheral_node(&self) -> Option<LightingNodeId> {
+        self.descriptor
+            .routing
+            .outputs
+            .iter()
+            .map(|output| output.node)
+            .find(|node| *node != self.local_node)
+    }
+
     /// Advertise the engine's host-selectable animated extension source.
     /// Boards whose extension band is not user-selectable skip this call.
     pub const fn with_extension_effects(mut self) -> Self {
@@ -244,6 +455,9 @@ pub enum RynkLightingReadback {
     State(LightingState),
     OutputMode(StandardState),
     OverlayPage(LightingOverlayPage),
+    /// The engine's page of the frame it last presented, forwarded
+    /// unconverted so remote and local pages share one shape.
+    FramePage(FramePage),
     SceneStatus {
         revision: u32,
         scene_len: u16,
@@ -430,6 +644,9 @@ pub(super) enum RynkLightingCommand {
         expected_revision: u32,
         offset: u16,
     },
+    ReadFrame {
+        offset: u16,
+    },
     ReadSceneStatus,
     ReadScenes {
         expected_revision: u32,
@@ -870,6 +1087,15 @@ impl<'a, const OVERLAY_CAPACITY: usize, const CORE_COMMAND_CAPACITY: usize, cons
                     items,
                 }));
             }
+            RynkLightingCommand::ReadFrame { offset } => {
+                // Unpinned: a frame read observes whatever is on the LEDs,
+                // and rejecting a stale one would hide the very divergence
+                // this endpoint exists to show.
+                return match self.request_core(StandardCommand::ReadFrame { offset }).await? {
+                    StandardReply::FramePage(page) => Ok(RynkLightingReadback::FramePage(page)),
+                    _ => Err(LightingError::InvalidRequest),
+                };
+            }
             RynkLightingCommand::ReadSceneStatus => {
                 let state = self.request_core_state(StandardCommand::ReadState).await?;
                 return Ok(RynkLightingReadback::SceneStatus {
@@ -1835,7 +2061,7 @@ mod tests {
     };
 
     use super::*;
-    use crate::lighting::{LedMetadata, MatrixSize, ZoneSpan};
+    use crate::lighting::{FRAME_CHUNK_SIZE, LedMetadata, MatrixSize, ZoneSpan};
     use crate::physical_layout::PhysicalLayout;
     use crate::test_support::test_block_on as block_on;
 
@@ -1919,6 +2145,147 @@ mod tests {
         assert_eq!(reply, Ok(RynkLightingReadback::State(state(2))));
     }
 
+    static TEST_OUTPUTS: [crate::lighting::OutputMetadata; 2] = [
+        crate::lighting::OutputMetadata {
+            node: LightingNodeId(0),
+            id: crate::lighting::OutputId(0),
+            pixel_count: 1,
+            capabilities: crate::lighting::OutputCapabilities::RGB,
+            coverage: crate::lighting::OutputCoverage::Complete,
+        },
+        crate::lighting::OutputMetadata {
+            node: LightingNodeId(1),
+            id: crate::lighting::OutputId(0),
+            pixel_count: 1,
+            capabilities: crate::lighting::OutputCapabilities::RGB,
+            coverage: crate::lighting::OutputCoverage::Complete,
+        },
+    ];
+
+    fn controller<'a>(mailbox: &'a RynkLightingMailbox) -> RynkLightingController<'a> {
+        RynkLightingController::new(
+            mailbox,
+            RynkLightingDescriptor {
+                topology_revision: 1,
+                topology: topology(),
+                routing: LightingRouting {
+                    outputs: &TEST_OUTPUTS,
+                    routes: &[],
+                },
+            },
+            2,
+        )
+    }
+
+    fn frame_page(start: u16, red: u8) -> FramePage {
+        let mut cells = [Rgb8::BLACK; FRAME_CHUNK_SIZE];
+        cells[0] = Rgb8::new(red, 0, 0);
+        FramePage {
+            revision: Some(7),
+            total: 2,
+            start,
+            len: 1,
+            cells,
+        }
+    }
+
+    #[test]
+    fn local_frame_reads_come_from_the_engine_with_no_age() {
+        let mailbox = RynkLightingMailbox::new();
+        let controller = controller(&mailbox);
+        let (result, ()) = block_on(join(controller.frame_page(LightingNodeId(0), 24), async {
+            let request = mailbox.receive().await;
+            assert!(matches!(request.command, RynkLightingCommand::ReadFrame { offset: 24 }));
+            mailbox.reply(request.id, Ok(RynkLightingReadback::FramePage(frame_page(24, 5))));
+        }));
+        assert_eq!(result, Ok((frame_page(24, 5), 0)));
+    }
+
+    #[test]
+    fn remote_frame_reads_separate_unknown_unwired_and_unreachable_nodes() {
+        let mailbox = RynkLightingMailbox::new();
+        let bare = controller(&mailbox);
+
+        // A node with no output in routing does not exist at all.
+        assert_eq!(
+            block_on(bare.frame_page(LightingNodeId(9), 0)),
+            Err(LightingError::UnknownNode {
+                node: rmk_types::protocol::rynk::LightingNodeId(9)
+            }),
+        );
+        // A real node the board wired no source for is never answerable.
+        assert_eq!(
+            block_on(bare.frame_page(LightingNodeId(1), 0)),
+            Err(LightingError::Unsupported),
+        );
+
+        // A wired node that does not answer is unavailable, not unsupported:
+        // the distinction is whether retrying is worth anything.
+        let port = RemoteFramePort::new();
+        let wired = controller(&mailbox).with_remote_frames(&port);
+        let (result, ()) = block_on(join(wired.frame_page(LightingNodeId(1), 0), async {
+            let request = port.receive().await;
+            port.reply(request.id, None);
+        }));
+        assert_eq!(
+            result,
+            Err(LightingError::NodeUnavailable {
+                node: rmk_types::protocol::rynk::LightingNodeId(1)
+            }),
+        );
+
+        let (result, ()) = block_on(join(wired.frame_page(LightingNodeId(1), 24), async {
+            let request = port.receive().await;
+            assert_eq!((request.node, request.offset), (LightingNodeId(1), 24));
+            port.reply(
+                request.id,
+                Some(RemoteFrame {
+                    page: frame_page(24, 9),
+                    age_ms: 42,
+                }),
+            );
+        }));
+        assert_eq!(result, Ok((frame_page(24, 9), 42)));
+    }
+
+    #[test]
+    fn a_silent_remote_node_times_out_and_its_late_answer_is_inert() {
+        let port = RemoteFramePort::new();
+        // Nobody answers: the fetch must not park forever behind a dead half.
+        let (fetched, id) = block_on(join(port.fetch(LightingNodeId(1), 0), async {
+            port.receive().await.id
+        }));
+        assert_eq!(fetched, None);
+
+        // The abandoned answer arrives after the fact. The next fetch carries
+        // a fresh token, so it waits for its own answer instead of taking it.
+        port.reply(
+            id,
+            Some(RemoteFrame {
+                page: frame_page(0, 1),
+                age_ms: 0,
+            }),
+        );
+        let (fetched, ()) = block_on(join(port.fetch(LightingNodeId(1), 0), async {
+            let request = port.receive().await;
+            assert_ne!(request.id, id);
+            port.reply(
+                request.id,
+                Some(RemoteFrame {
+                    page: frame_page(0, 2),
+                    age_ms: 3,
+                }),
+            );
+        }));
+        assert_eq!(
+            fetched,
+            Some(RemoteFrame {
+                page: frame_page(0, 2),
+                age_ms: 3
+            }),
+        );
+    }
+
     #[test]
     fn replacement_rejects_duplicate_stable_ids_before_reaching_the_core() {
         let protocol = RynkLightingMailbox::new();
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index 5c47b6046..e8eee7334 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -13,9 +13,10 @@ use embassy_futures::select::{Either, select};
 use embedded_io_async::{Read, Write};
 #[cfg(feature = "lighting")]
 pub use lighting::{
-    RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
-    RynkLightingReadback, StandardRynkLightingAdapter, install_lighting_runtime_conditional_scenes,
-    install_lighting_scenes,
+    LightingReplicationStatus, PeripheralReplicaStatus, RYNK_LIGHTING_TRANSACTION_CAPACITY, RemoteFrame,
+    RemoteFramePort, RemoteFrameRequest, ReplicationMachineState, RynkLightingController, RynkLightingDescriptor,
+    RynkLightingMailbox, RynkLightingReadback, StandardRynkLightingAdapter,
+    install_lighting_runtime_conditional_scenes, install_lighting_scenes,
 };
 use postcard::experimental::max_size::MaxSize;
 use rmk_types::constants::RYNK_BUFFER_SIZE;
@@ -150,6 +151,10 @@ impl<'a> RynkService<'a> {
     fn requires_unlock(&self, cmd: Cmd) -> bool {
         match cmd {
             Cmd::BootloaderJump | Cmd::PeripheralBootloaderJump => self.lock_config.bootloader_requires_unlock,
+            // Reading raw LED colors can expose reactive per-key effects, and
+            // therefore keystrokes, exactly like the matrix snapshot does.
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingFrame => true,
             Cmd::StorageReset | Cmd::GetMatrixState => true,
             // Deleting a bond opens a re-pair hijack window; BLE-only command.
             #[cfg(feature = "_ble")]
@@ -384,6 +389,10 @@ impl<'a> RynkService<'a> {
                 serve::<command::GetLightingExtendedRuntimeConditionalScenes, _>(self, msg).await
             }
             #[cfg(feature = "lighting")]
+            Cmd::GetLightingFrame => serve::<command::GetLightingFrame, _>(self, msg).await,
+            #[cfg(feature = "lighting")]
+            Cmd::GetLightingReplicaStatus => serve::<command::GetLightingReplicaStatus, _>(self, msg).await,
+            #[cfg(feature = "lighting")]
             Cmd::BeginLightingExtendedRuntimeConditionalSceneReplace => {
                 serve::<command::BeginLightingExtendedRuntimeConditionalSceneReplace, _>(self, msg).await
             }
diff --git a/rmk/src/lighting/standard/mod.rs b/rmk/src/lighting/standard/mod.rs
index 6833ab5fb..94662da15 100644
--- a/rmk/src/lighting/standard/mod.rs
+++ b/rmk/src/lighting/standard/mod.rs
@@ -26,6 +26,11 @@ const _: () = core::assert!(
     "engine conditional page size must equal the wire chunk size"
 );
 
+const _: () = core::assert!(
+    command::FRAME_CHUNK_SIZE == rmk_types::protocol::rynk::LIGHTING_FRAME_CHUNK_SIZE,
+    "engine frame page size must equal the wire chunk size"
+);
+
 /// A staged scene replacement expires after this much command inactivity.
 pub const SCENE_TRANSACTION_TIMEOUT_MS: u64 = 5_000;
 
diff --git a/rmk/tests/integration/rynk_lighting.rs b/rmk/tests/integration/rynk_lighting.rs
index e08cdb653..e3d970962 100644
--- a/rmk/tests/integration/rynk_lighting.rs
+++ b/rmk/tests/integration/rynk_lighting.rs
@@ -12,9 +12,15 @@ use embassy_sync::blocking_mutex::raw::NoopRawMutex;
 use embassy_sync::pipe::Pipe;
 use rmk::config::{BehaviorConfig, PositionalConfig, RmkConfig};
 use rmk::event::publish_event;
-use rmk::host::{HostService as RynkService, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox};
+use rmk::host::{
+    HostService as RynkService, LightingReplicationStatus, PeripheralReplicaStatus, RemoteFrame, RemoteFramePort,
+    ReplicationMachineState, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
+};
 use rmk::keymap::{KeyMap, KeymapData};
-use rmk::lighting::{LedId, LedMetadata, LightingRouting, LightingTopology, MatrixSize, ZoneSpan};
+use rmk::lighting::{
+    LedId, LedMetadata, LightingRouting, LightingTopology, MatrixSize, OutputCapabilities, OutputCoverage, OutputId,
+    OutputMetadata, ZoneSpan,
+};
 use rmk::physical_layout::{Coordinate, KeyPosition, KeySize, PhysicalKey, PhysicalLayout, Point3, Rotation};
 use rmk::test_support::test_block_on;
 use rmk::types::action::KeyAction;
@@ -454,3 +460,230 @@ fn extension_endpoints_are_unsupported_until_a_board_advertises_them() {
         assert_eq!(unsupported, Err(LightingError::Unsupported));
     });
 }
+
+/// The right half's frame and the replication handshake reach a host over the
+/// same loopback, so a stale replica is observable rather than inferred.
+///
+/// Node 1 has no engine here — the split round trip is the board's, and RMK
+/// only owns the rendezvous — so a fake responder stands in for it.
+struct FakeReplication;
+
+impl LightingReplicationStatus for FakeReplication {
+    fn central(&self) -> ReplicationMachineState {
+        ReplicationMachineState {
+            last_acked_revision: Some(4),
+            awaiting_ack: true,
+            generation: 2,
+            link_up: true,
+        }
+    }
+
+    fn peripheral(&self, node: rmk::lighting::LightingNodeId) -> Option<PeripheralReplicaStatus> {
+        (node == rmk::lighting::LightingNodeId(1)).then_some(PeripheralReplicaStatus {
+            applied_revision: Some(4),
+            engine_revision: 11,
+            layers: rmk::lighting::LayerState::new(3, 1, 0b1010),
+            powered: false,
+            wake_active: true,
+            effective_output_enabled: false,
+            age_ms: 250,
+        })
+    }
+}
+
+static REPLICATION: FakeReplication = FakeReplication;
+static REMOTE_FRAMES: RemoteFramePort = RemoteFramePort::new();
+static OBSERVABILITY_OUTPUTS: [OutputMetadata; 2] = [
+    OutputMetadata {
+        node: rmk::lighting::LightingNodeId(0),
+        id: OutputId(0),
+        pixel_count: 1,
+        capabilities: OutputCapabilities::RGB,
+        coverage: OutputCoverage::Complete,
+    },
+    OutputMetadata {
+        node: rmk::lighting::LightingNodeId(1),
+        id: OutputId(0),
+        pixel_count: 1,
+        capabilities: OutputCapabilities::RGB,
+        coverage: OutputCoverage::Complete,
+    },
+];
+
+#[test]
+fn lighting_observability_endpoints_cross_the_full_loopback() {
+    use rmk::host::StandardRynkLightingAdapter;
+    use rmk::lighting::service::RenderInput;
+    use rmk::lighting::{
+        BackgroundState, EmptySource, FRAME_CHUNK_SIZE, FramePage, LayerPolicy, LayerScenes, LightingContext,
+        LightingEngine, LightingMailbox, LogicalFrame, Rgb8, StandardCommand, StandardError, StandardLightingEngine,
+        StandardReply,
+    };
+    use rmk_types::protocol::rynk::{
+        LightingFramePageResult, LightingFrameRequest, LightingNodeId, LightingReplicaStatusResult, LightingRgb8,
+    };
+
+    let descriptor = RynkLightingDescriptor {
+        routing: LightingRouting {
+            outputs: &OBSERVABILITY_OUTPUTS,
+            routes: &[],
+        },
+        ..descriptor()
+    };
+    let mailbox: &'static RynkLightingMailbox = Box::leak(Box::new(RynkLightingMailbox::new()));
+    let service = service_with(
+        RynkLightingController::new(mailbox, descriptor, 8)
+            .with_remote_frames(&REMOTE_FRAMES)
+            .with_replication_status(&REPLICATION),
+    );
+
+    let core = LightingMailbox::<StandardCommand<2>, StandardReply, StandardError, 1>::new();
+    let mut adapter = StandardRynkLightingAdapter::<2, 1>::new(mailbox, &core, descriptor.topology);
+    let mut engine: StandardLightingEngine<'static, EmptySource, EmptySource, 1, 2, 0> = StandardLightingEngine::new(
+        BackgroundState {
+            value: 40,
+            ..BackgroundState::default()
+        },
+        LayerScenes {
+            scenes: &[],
+            policy: LayerPolicy::EffectiveOnly,
+        },
+        EmptySource,
+        EmptySource,
+    );
+
+    // Present one frame up front: the endpoint reports what the output
+    // accepted, so without this there is nothing on the LEDs to report.
+    let context = LightingContext::default();
+    let mut frame = LogicalFrame::new(Rgb8::BLACK);
+    engine
+        .render(
+            RenderInput {
+                now_ms: 0,
+                snapshot: &context,
+            },
+            &mut frame,
+        )
+        .expect("render the initial frame");
+    <StandardLightingEngine<'static, EmptySource, EmptySource, 1, 2, 0> as LightingEngine<LightingContext>>::
+        on_presented(&mut engine, &frame);
+
+    let background = async {
+        let adapter_loop = async {
+            loop {
+                adapter.process_next().await;
+            }
+        };
+        let engine_loop = async {
+            loop {
+                let (id, command) = core.receive_request().await;
+                let result = engine.handle_command(0, command, &context).map(|outcome| outcome.reply);
+                core.publish_reply(id, result);
+            }
+        };
+        // Stand-in for the board's split round trip to the right half.
+        let remote_loop = async {
+            loop {
+                let request = REMOTE_FRAMES.receive().await;
+                let mut cells = [Rgb8::BLACK; FRAME_CHUNK_SIZE];
+                cells[0] = Rgb8::new(1, 2, 3);
+                REMOTE_FRAMES.reply(
+                    request.id,
+                    Some(RemoteFrame {
+                        page: FramePage {
+                            revision: Some(11),
+                            total: 1,
+                            start: request.offset,
+                            len: 1,
+                            cells,
+                        },
+                        age_ms: 250,
+                    }),
+                );
+            }
+        };
+        select(select(adapter_loop, engine_loop), remote_loop).await;
+    };
+
+    loopback(&service, background, async |host| {
+        let local = host
+            .request::<_, LightingFramePageResult>(
+                Cmd::GetLightingFrame,
+                0x7B,
+                &LightingFrameRequest {
+                    node: LightingNodeId(0),
+                    offset: 0,
+                },
+            )
+            .await
+            .expect("outer local frame envelope")
+            .expect("local frame page");
+        assert_eq!(local.node, LightingNodeId(0));
+        assert_eq!(local.revision, Some(0));
+        assert_eq!((local.total_leds, local.start), (1, 0));
+        assert_eq!(local.age_ms, 0, "the local half has no round trip to age");
+        assert_eq!(local.cells.as_slice(), &[LightingRgb8 { r: 40, g: 40, b: 40 }]);
+
+        let remote = host
+            .request::<_, LightingFramePageResult>(
+                Cmd::GetLightingFrame,
+                0x7C,
+                &LightingFrameRequest {
+                    node: LightingNodeId(1),
+                    offset: 0,
+                },
+            )
+            .await
+            .expect("outer remote frame envelope")
+            .expect("remote frame page");
+        assert_eq!(remote.node, LightingNodeId(1));
+        assert_eq!(remote.revision, Some(11));
+        assert_eq!(remote.age_ms, 250);
+        assert_eq!(remote.cells.as_slice(), &[LightingRgb8 { r: 1, g: 2, b: 3 }]);
+
+        // A node the board never routed is rejected without a round trip.
+        let unknown = host
+            .request::<_, LightingFramePageResult>(
+                Cmd::GetLightingFrame,
+                0x7D,
+                &LightingFrameRequest {
+                    node: LightingNodeId(7),
+                    offset: 0,
+                },
+            )
+            .await
+            .expect("outer unknown-node envelope");
+        assert_eq!(
+            unknown,
+            Err(LightingError::UnknownNode {
+                node: LightingNodeId(7)
+            })
+        );
+
+        let status = host
+            .request::<(), LightingReplicaStatusResult>(Cmd::GetLightingReplicaStatus, 0x6F, &())
+            .await
+            .expect("outer replica-status envelope")
+            .expect("replica status");
+        assert_eq!(status.central.revision, 0);
+        assert_eq!(status.central.presented_revision, Some(0));
+        let replication = status.replication.expect("the board wired a replication machine");
+        assert_eq!(replication.last_acked_revision, Some(4));
+        assert!(replication.awaiting_ack && replication.link_up);
+        assert_eq!(replication.generation, 2);
+        let peripheral = status.peripheral.expect("the board heard from the peripheral");
+        assert_eq!(peripheral.node, LightingNodeId(1));
+        assert_eq!(peripheral.applied_revision, Some(4));
+        assert_eq!(peripheral.engine_revision, 11);
+        assert_eq!(
+            (
+                peripheral.effective_layer,
+                peripheral.default_layer,
+                peripheral.active_bits
+            ),
+            (3, 1, 0b1010),
+        );
+        assert!(peripheral.wake_active && !peripheral.effective_output_enabled);
+        assert_eq!(peripheral.age_ms, 250);
+    });
+}

From da04121b119131ea6ee6ed7716f395dcce076bf8 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Thu, 6 Aug 2026 17:18:54 -0700
Subject: [PATCH 75/78] feat(rynk): expose lighting replica attestation status

---
 .../main/docs/development/rynk_protocol.md    |  2 +-
 rmk-types/src/protocol/rynk/command.rs        |  4 +-
 .../src/protocol/rynk/payload/lighting.rs     | 78 +++++++++++++++++++
 .../rynk/snapshots/lighting_wire_frames.snap  |  2 +-
 rmk-types/src/protocol/rynk/tests.rs          | 23 ++++++
 rmk/src/host/mod.rs                           |  6 +-
 rmk/src/host/rynk/handlers/lighting.rs        | 45 +++++++++--
 rmk/src/host/rynk/lighting.rs                 | 44 ++++++++++-
 rmk/src/host/rynk/mod.rs                      |  6 +-
 rmk/tests/integration/rynk_lighting.rs        | 39 +++++++++-
 rynk/src/api.rs                               | 41 ++++++----
 11 files changed, 253 insertions(+), 37 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 184008cb9..308e59837 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -132,7 +132,7 @@ Which commands a firmware answers depends on the RMK Cargo features it was built
 | `0x0934` | `CommitLightingExtendedRuntimeConditionalSceneReplace` | `CommitLightingRuntimeConditionalSceneReplaceRequest`    | `LightingStateResult`                                | `lighting`       | Publish a complete extended conditional-table replacement.                                                                                                                                                                                                                                                         |
 | `0x0935` | `AbortLightingExtendedRuntimeConditionalSceneReplace`  | `AbortLightingRuntimeConditionalSceneReplaceRequest`     | `LightingUnitResult`                                 | `lighting`       | Discard an extended conditional-table replacement.                                                                                                                                                                                                                                                                 |
 | `0x0936` | `GetLightingFrame`                                     | `LightingFrameRequest`                                   | `LightingFramePageResult`                            | `lighting`       | Read back what one lighting node last presented to its LEDs, paged. `LightingFeatureFlags` has no bits left, so support is discovered by probing: firmware without it answers `UnknownCmd`.                                                                                                                        |
-| `0x0937` | `GetLightingReplicaStatus`                             | `()`                                                     | `LightingReplicaStatusResult`                        | `lighting`       | Read both sides of the split lighting replication handshake. Probed like `GetLightingFrame`.                                                                                                                                                                                                                       |
+| `0x0937` | `GetLightingReplicaStatus`                             | `()`                                                     | `LightingReplicaStatusResult`                        | `lighting`       | Read both sides of the split lighting replication handshake. Probed like `GetLightingFrame`. Boards may use a read to trigger a coalesced background refresh; reread after one bounded link round trip when a fresh peripheral report is required.                                                                 |
 
 ## Topics
 
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index ad3109ebb..67b67e152 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -527,7 +527,9 @@ endpoints! {
     #[cfg(feature = "lighting")]
     GetLightingFrame = 0x0936: LightingFrameRequest => LightingFramePageResult;
     /// Read both sides of the split lighting replication handshake. Probed
-    /// like `GetLightingFrame`.
+    /// like `GetLightingFrame`. Boards may use a read to trigger a coalesced
+    /// background refresh; reread after one bounded link round trip when a
+    /// fresh peripheral report is required.
     #[cfg(feature = "lighting")]
     GetLightingReplicaStatus = 0x0937: () => LightingReplicaStatusResult;
 }
diff --git a/rmk-types/src/protocol/rynk/payload/lighting.rs b/rmk-types/src/protocol/rynk/payload/lighting.rs
index 14e30f399..93110494e 100644
--- a/rmk-types/src/protocol/rynk/payload/lighting.rs
+++ b/rmk-types/src/protocol/rynk/payload/lighting.rs
@@ -1218,6 +1218,42 @@ impl MaxSize for LightingFramePage {
         + crate::heapless_vec_max_size::<LightingRgb8, LIGHTING_FRAME_CHUNK_SIZE>();
 }
 
+/// Canonical digest schema implemented by the first lighting replica
+/// attestation protocol.
+pub const LIGHTING_REPLICA_DIGEST_SCHEMA_V1: u8 = 1;
+
+wire_type! {
+    /// FNV-1a-32 digests of the durable right-half projection at `revision`.
+    ///
+    /// Expiring-overlay lifetime and fast context such as layers, batteries,
+    /// connection state, and powered/wake state are deliberately excluded.
+    /// They are covered by sequence/revision freshness and direct status
+    /// comparison instead.
+    pub struct LightingReplicaDigests {
+        pub schema: u8,
+        pub revision: u32,
+        pub settings: u32,
+        pub overlay: u32,
+        pub scenes: u32,
+        pub conditional_scenes: u32,
+    }
+}
+
+wire_type! {
+    /// Board-reported state of the replication recovery machine.
+    ///
+    /// Hosts still derive `UNAVAILABLE` from link/report presence and
+    /// `UNATTESTED` from absent digest sets; neither is a recovery-machine
+    /// state in its own right.
+    pub enum LightingReplicationHealth {
+        Healthy,
+        Resynchronizing,
+        Stale,
+        Diverged,
+        Halted,
+    }
+}
+
 wire_type! {
     /// The lighting authority's own state, as the central half sees it.
     pub struct LightingCentralReplicaState {
@@ -1233,6 +1269,10 @@ wire_type! {
         pub active_bits: u64,
         /// Live USB/VBUS power as the engine sees it.
         pub powered: bool,
+        /// Whether a configured wake layer currently overrides output policy.
+        pub wake_active: bool,
+        /// Final live output decision after mode, power, and wake inputs.
+        pub effective_output_enabled: bool,
     }
 }
 
@@ -1252,6 +1292,21 @@ wire_type! {
         /// tell a resend apart from a stuck retry.
         pub generation: u8,
         pub link_up: bool,
+        /// Durable state changed but no full snapshot carrying it has yet
+        /// been acknowledged.
+        pub durable_dirty: bool,
+        /// Fast context changed but no matching update has yet been
+        /// acknowledged.
+        pub context_dirty: bool,
+        pub health: LightingReplicationHealth,
+        /// Digest set the central expects the peripheral to hold. `None`
+        /// means the board or peer does not support attestation yet.
+        pub expected_digests: Option<LightingReplicaDigests>,
+        /// Age of the last successful digest comparison. `None` means no
+        /// attestation has succeeded since boot.
+        pub last_attested_age_ms: Option<u32>,
+        /// Consecutive mismatches observed after a recovery snapshot.
+        pub mismatch_count: u8,
     }
 }
 
@@ -1278,6 +1333,9 @@ wire_type! {
         pub wake_active: bool,
         pub effective_output_enabled: bool,
         pub age_ms: u32,
+        /// Digest set recomputed from the state this renderer applied.
+        /// `None` distinguishes an older/unattested peer from a zero digest.
+        pub digests: Option<LightingReplicaDigests>,
     }
 }
 
@@ -1637,6 +1695,14 @@ mod tests {
 
     #[test]
     fn replica_status_round_trips_present_and_absent_sides() {
+        let digests = LightingReplicaDigests {
+            schema: LIGHTING_REPLICA_DIGEST_SCHEMA_V1,
+            revision: u32::MAX - 2,
+            settings: 1,
+            overlay: 2,
+            scenes: 3,
+            conditional_scenes: 4,
+        };
         let full = LightingReplicaStatus {
             central: LightingCentralReplicaState {
                 revision: u32::MAX,
@@ -1645,12 +1711,20 @@ mod tests {
                 default_layer: 1,
                 active_bits: u64::MAX,
                 powered: true,
+                wake_active: true,
+                effective_output_enabled: false,
             },
             replication: Some(LightingReplicationMachine {
                 last_acked_revision: Some(u32::MAX - 2),
                 awaiting_ack: true,
                 generation: u8::MAX,
                 link_up: true,
+                durable_dirty: true,
+                context_dirty: false,
+                health: LightingReplicationHealth::Resynchronizing,
+                expected_digests: Some(digests),
+                last_attested_age_ms: Some(u32::MAX),
+                mismatch_count: 1,
             }),
             peripheral: Some(LightingPeripheralReplicaState {
                 node: LightingNodeId(1),
@@ -1663,6 +1737,10 @@ mod tests {
                 wake_active: true,
                 effective_output_enabled: false,
                 age_ms: u32::MAX,
+                digests: Some(LightingReplicaDigests {
+                    revision: u32::MAX - 3,
+                    ..digests
+                }),
             }),
         };
         round_trip(&full);
diff --git a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
index 9ce5429b0..e4b31f39a 100644
--- a/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/lighting_wire_frames.snap
@@ -65,7 +65,7 @@ GetLightingOverlay reply                                      04 1b 09 01 01 11
 GetLightingOverlay request                                    05 1b 09 01 09 01 00
 GetLightingPhysicalKeys reply                                 04 04 09 01 01 12 01 01 01 01 02 ff 01 80 04 80 01 80 02 80 03 db 0b 00
 GetLightingPhysicalKeys request                               05 04 09 01 01 01 00
-GetLightingReplicaStatus reply                                04 37 09 01 01 16 09 01 08 02 01 06 01 01 01 07 01 04 01 01 01 01 06 05 01 01 02 02 01 03 fa 01 00
+GetLightingReplicaStatus reply                                04 37 09 01 01 08 09 01 08 02 01 06 01 09 01 01 01 07 01 04 01 01 14 01 01 01 07 0b 0c 0d 0e 01 7d 01 01 01 01 06 05 01 01 02 02 01 0a fa 01 01 01 06 15 16 17 18 00
 GetLightingReplicaStatus request                              04 37 09 01 00
 GetLightingRoutes reply                                       04 09 09 01 01 08 01 01 01 2a 01 02 07 00
 GetLightingRoutes request                                     05 09 09 01 01 01 00
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index 4ef5dbb60..84e183878 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -1482,12 +1482,27 @@ fn lighting_wire_frames_locked() {
             default_layer: 1,
             active_bits: 0b110,
             powered: true,
+            wake_active: false,
+            effective_output_enabled: true,
         },
         replication: Some(LightingReplicationMachine {
             last_acked_revision: Some(state.revision - 2),
             awaiting_ack: true,
             generation: 4,
             link_up: true,
+            durable_dirty: true,
+            context_dirty: false,
+            health: LightingReplicationHealth::Resynchronizing,
+            expected_digests: Some(LightingReplicaDigests {
+                schema: LIGHTING_REPLICA_DIGEST_SCHEMA_V1,
+                revision: state.revision - 2,
+                settings: 11,
+                overlay: 12,
+                scenes: 13,
+                conditional_scenes: 14,
+            }),
+            last_attested_age_ms: Some(125),
+            mismatch_count: 1,
         }),
         peripheral: Some(LightingPeripheralReplicaState {
             node: frame_request.node,
@@ -1500,6 +1515,14 @@ fn lighting_wire_frames_locked() {
             wake_active: true,
             effective_output_enabled: false,
             age_ms: 250,
+            digests: Some(LightingReplicaDigests {
+                schema: LIGHTING_REPLICA_DIGEST_SCHEMA_V1,
+                revision: state.revision - 3,
+                settings: 21,
+                overlay: 22,
+                scenes: 23,
+                conditional_scenes: 24,
+            }),
         }),
     };
 
diff --git a/rmk/src/host/mod.rs b/rmk/src/host/mod.rs
index 122b7e291..e77c36658 100644
--- a/rmk/src/host/mod.rs
+++ b/rmk/src/host/mod.rs
@@ -27,9 +27,9 @@ pub use rynk::RynkService as HostService;
 #[cfg(all(feature = "rynk", feature = "lighting"))]
 pub use rynk::{
     LightingReplicationStatus, PeripheralReplicaStatus, RYNK_LIGHTING_TRANSACTION_CAPACITY, RemoteFrame,
-    RemoteFramePort, RemoteFrameRequest, ReplicationMachineState, RynkLightingController, RynkLightingDescriptor,
-    RynkLightingMailbox, RynkLightingReadback, StandardRynkLightingAdapter,
-    install_lighting_runtime_conditional_scenes, install_lighting_scenes,
+    RemoteFramePort, RemoteFrameRequest, ReplicaDigests, ReplicationHealth, ReplicationMachineState,
+    RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox, RynkLightingReadback,
+    StandardRynkLightingAdapter, install_lighting_runtime_conditional_scenes, install_lighting_scenes,
 };
 /// RMK's semantic version, available to downstream firmware build labels.
 #[cfg(feature = "rynk")]
diff --git a/rmk/src/host/rynk/handlers/lighting.rs b/rmk/src/host/rynk/handlers/lighting.rs
index 58792af37..dd78f5235 100644
--- a/rmk/src/host/rynk/handlers/lighting.rs
+++ b/rmk/src/host/rynk/handlers/lighting.rs
@@ -38,13 +38,14 @@ use rmk_types::protocol::rynk::{
     LightingOutputsPageResult, LightingOverlayCell, LightingOverlayPageRequest, LightingOverlayPageResult,
     LightingOverlayTransaction, LightingOverlayTransactionResult, LightingPageRequest, LightingPeripheralReplicaState,
     LightingPhysicalKey, LightingPhysicalKeysPage, LightingPhysicalKeysPageResult, LightingPoint3,
-    LightingReplicaStatus, LightingReplicaStatusResult, LightingReplicationMachine, LightingResult, LightingRgb8,
-    LightingRoute, LightingRoutesPage, LightingRoutesPageResult, LightingRuntimeConditionalScenePageRequest,
-    LightingRuntimeConditionalSceneStatus, LightingRuntimeConditionalSceneStatusResult,
-    LightingRuntimeConditionalSceneTransactionResult, LightingRuntimeConditionalScenesPageResult,
-    LightingScenePageRequest, LightingSceneStatus, LightingSceneStatusResult, LightingSceneTransactionResult,
-    LightingScenesPageResult, LightingState, LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId,
-    LightingZoneMembershipsPage, LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult,
+    LightingReplicaDigests, LightingReplicaStatus, LightingReplicaStatusResult, LightingReplicationHealth,
+    LightingReplicationMachine, LightingResult, LightingRgb8, LightingRoute, LightingRoutesPage,
+    LightingRoutesPageResult, LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
+    LightingRuntimeConditionalSceneStatusResult, LightingRuntimeConditionalSceneTransactionResult,
+    LightingRuntimeConditionalScenesPageResult, LightingScenePageRequest, LightingSceneStatus,
+    LightingSceneStatusResult, LightingSceneTransactionResult, LightingScenesPageResult, LightingState,
+    LightingStateResult, LightingUnitResult, LightingZone, LightingZoneId, LightingZoneMembershipsPage,
+    LightingZoneMembershipsPageResult, LightingZonesPage, LightingZonesPageResult,
     PutLightingExtendedRuntimeConditionalSceneChunkRequest, PutLightingOverlayChunkRequest,
     PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, RynkError, RynkMessage,
     SetLightingExtensionLayersRequest, SetLightingExtensionParamRequest, SetLightingExtensionStateRequest,
@@ -54,7 +55,8 @@ use rmk_types::protocol::rynk::{
 };
 
 use super::super::lighting::{
-    RYNK_LIGHTING_TRANSACTION_CAPACITY, RynkLightingCommand, RynkLightingController, RynkLightingReadback,
+    RYNK_LIGHTING_TRANSACTION_CAPACITY, ReplicaDigests, ReplicationHealth, RynkLightingCommand, RynkLightingController,
+    RynkLightingReadback,
 };
 use super::super::{RynkService, RynkSession};
 use super::Handle;
@@ -1056,6 +1058,8 @@ async fn replica_status(controller: RynkLightingController<'_>) -> LightingResul
         default_layer: presented.map_or(0, |presented| presented.context.layers.default),
         active_bits: presented.map_or(0, |presented| presented.context.layers.active_bits()),
         powered: state.powered,
+        wake_active: state.wake_active,
+        effective_output_enabled: state.output_enabled,
     };
 
     let Some(status) = controller.replication else {
@@ -1065,6 +1069,7 @@ async fn replica_status(controller: RynkLightingController<'_>) -> LightingResul
             peripheral: None,
         });
     };
+    status.request_refresh();
     let machine = status.central();
     let peripheral = controller.peripheral_node().and_then(|node| {
         let peripheral = status.peripheral(node)?;
@@ -1079,6 +1084,7 @@ async fn replica_status(controller: RynkLightingController<'_>) -> LightingResul
             wake_active: peripheral.wake_active,
             effective_output_enabled: peripheral.effective_output_enabled,
             age_ms: peripheral.age_ms,
+            digests: peripheral.digests.map(replica_digests_to_wire),
         })
     });
     Ok(LightingReplicaStatus {
@@ -1088,11 +1094,34 @@ async fn replica_status(controller: RynkLightingController<'_>) -> LightingResul
             awaiting_ack: machine.awaiting_ack,
             generation: machine.generation,
             link_up: machine.link_up,
+            durable_dirty: machine.durable_dirty,
+            context_dirty: machine.context_dirty,
+            health: match machine.health {
+                ReplicationHealth::Healthy => LightingReplicationHealth::Healthy,
+                ReplicationHealth::Resynchronizing => LightingReplicationHealth::Resynchronizing,
+                ReplicationHealth::Stale => LightingReplicationHealth::Stale,
+                ReplicationHealth::Diverged => LightingReplicationHealth::Diverged,
+                ReplicationHealth::Halted => LightingReplicationHealth::Halted,
+            },
+            expected_digests: machine.expected_digests.map(replica_digests_to_wire),
+            last_attested_age_ms: machine.last_attested_age_ms,
+            mismatch_count: machine.mismatch_count,
         }),
         peripheral,
     })
 }
 
+fn replica_digests_to_wire(digests: ReplicaDigests) -> LightingReplicaDigests {
+    LightingReplicaDigests {
+        schema: digests.schema,
+        revision: digests.revision,
+        settings: digests.settings,
+        overlay: digests.overlay,
+        scenes: digests.scenes,
+        conditional_scenes: digests.conditional_scenes,
+    }
+}
+
 impl Handle<GetLightingKeys> for RynkService<'_> {
     async fn handle(&self, req: LightingPageRequest) -> Result<LightingKeysPageResult, RynkError> {
         Ok(controller(self).and_then(|binding| keys_page(binding, req)))
diff --git a/rmk/src/host/rynk/lighting.rs b/rmk/src/host/rynk/lighting.rs
index 810329d4a..6ac96269c 100644
--- a/rmk/src/host/rynk/lighting.rs
+++ b/rmk/src/host/rynk/lighting.rs
@@ -63,10 +63,10 @@ const RYNK_LIGHTING_COMMAND_CAPACITY: usize = 4;
 
 /// How long a remote-frame fetch waits before reporting the node unavailable.
 ///
-/// Matched to the split lighting layer's own acknowledgement timeout: a
-/// round trip that has not landed by then is lost, not slow, and a host
-/// polling frames must not stall behind a half that is gone.
-const REMOTE_FRAME_TIMEOUT_MS: u64 = 500;
+/// Boards may need several bounded split-packet round trips to assemble a
+/// page. Keep this outer deadline long enough for that recovery while still
+/// bounding a host request when the remote half is gone.
+const REMOTE_FRAME_TIMEOUT_MS: u64 = 1_000;
 
 /// One node's presented-frame page plus how stale it is.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
@@ -165,6 +165,28 @@ impl Default for RemoteFramePort {
     }
 }
 
+/// Canonical digests of one durable replica projection.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct ReplicaDigests {
+    pub schema: u8,
+    pub revision: u32,
+    pub settings: u32,
+    pub overlay: u32,
+    pub scenes: u32,
+    pub conditional_scenes: u32,
+}
+
+/// Recovery state reported by the board's replication machine.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub enum ReplicationHealth {
+    #[default]
+    Healthy,
+    Resynchronizing,
+    Stale,
+    Diverged,
+    Halted,
+}
+
 /// Central-side state of the split lighting replication machine.
 #[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
 pub struct ReplicationMachineState {
@@ -176,6 +198,12 @@ pub struct ReplicationMachineState {
     /// apart from a retry that is stuck.
     pub generation: u8,
     pub link_up: bool,
+    pub durable_dirty: bool,
+    pub context_dirty: bool,
+    pub health: ReplicationHealth,
+    pub expected_digests: Option<ReplicaDigests>,
+    pub last_attested_age_ms: Option<u32>,
+    pub mismatch_count: u8,
 }
 
 /// The last renderer state a peripheral reported.
@@ -194,6 +222,9 @@ pub struct PeripheralReplicaStatus {
     pub effective_output_enabled: bool,
     /// Age of this report at the time it is read.
     pub age_ms: u32,
+    /// Digests recomputed from the applied durable state. `None` means the
+    /// peer has not supplied attestation data.
+    pub digests: Option<ReplicaDigests>,
 }
 
 /// Board-provided view of the split lighting replication handshake.
@@ -203,6 +234,11 @@ pub struct PeripheralReplicaStatus {
 /// blocking on the link. A read that blocked could not distinguish a slow
 /// link from a dead one, which is the distinction being debugged.
 pub trait LightingReplicationStatus {
+    /// Ask the board to refresh its cached peripheral view without blocking
+    /// this protocol read. Implementations should coalesce requests; a host
+    /// that needs the freshest value can reread after one bounded round trip.
+    fn request_refresh(&self) {}
+
     fn central(&self) -> ReplicationMachineState;
 
     /// The last status heard from `node`, or `None` if none ever arrived.
diff --git a/rmk/src/host/rynk/mod.rs b/rmk/src/host/rynk/mod.rs
index e8eee7334..b08d9089f 100644
--- a/rmk/src/host/rynk/mod.rs
+++ b/rmk/src/host/rynk/mod.rs
@@ -14,9 +14,9 @@ use embedded_io_async::{Read, Write};
 #[cfg(feature = "lighting")]
 pub use lighting::{
     LightingReplicationStatus, PeripheralReplicaStatus, RYNK_LIGHTING_TRANSACTION_CAPACITY, RemoteFrame,
-    RemoteFramePort, RemoteFrameRequest, ReplicationMachineState, RynkLightingController, RynkLightingDescriptor,
-    RynkLightingMailbox, RynkLightingReadback, StandardRynkLightingAdapter,
-    install_lighting_runtime_conditional_scenes, install_lighting_scenes,
+    RemoteFramePort, RemoteFrameRequest, ReplicaDigests, ReplicationHealth, ReplicationMachineState,
+    RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox, RynkLightingReadback,
+    StandardRynkLightingAdapter, install_lighting_runtime_conditional_scenes, install_lighting_scenes,
 };
 use postcard::experimental::max_size::MaxSize;
 use rmk_types::constants::RYNK_BUFFER_SIZE;
diff --git a/rmk/tests/integration/rynk_lighting.rs b/rmk/tests/integration/rynk_lighting.rs
index e3d970962..11f4fa2e1 100644
--- a/rmk/tests/integration/rynk_lighting.rs
+++ b/rmk/tests/integration/rynk_lighting.rs
@@ -14,7 +14,8 @@ use rmk::config::{BehaviorConfig, PositionalConfig, RmkConfig};
 use rmk::event::publish_event;
 use rmk::host::{
     HostService as RynkService, LightingReplicationStatus, PeripheralReplicaStatus, RemoteFrame, RemoteFramePort,
-    ReplicationMachineState, RynkLightingController, RynkLightingDescriptor, RynkLightingMailbox,
+    ReplicaDigests, ReplicationHealth, ReplicationMachineState, RynkLightingController, RynkLightingDescriptor,
+    RynkLightingMailbox,
 };
 use rmk::keymap::{KeyMap, KeymapData};
 use rmk::lighting::{
@@ -468,13 +469,34 @@ fn extension_endpoints_are_unsupported_until_a_board_advertises_them() {
 /// only owns the rendezvous — so a fake responder stands in for it.
 struct FakeReplication;
 
+static REPLICATION_REFRESHES: core::sync::atomic::AtomicUsize = core::sync::atomic::AtomicUsize::new(0);
+
+const FAKE_DIGESTS: ReplicaDigests = ReplicaDigests {
+    schema: 1,
+    revision: 4,
+    settings: 11,
+    overlay: 12,
+    scenes: 13,
+    conditional_scenes: 14,
+};
+
 impl LightingReplicationStatus for FakeReplication {
+    fn request_refresh(&self) {
+        REPLICATION_REFRESHES.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
+    }
+
     fn central(&self) -> ReplicationMachineState {
         ReplicationMachineState {
             last_acked_revision: Some(4),
             awaiting_ack: true,
             generation: 2,
             link_up: true,
+            durable_dirty: true,
+            context_dirty: false,
+            health: ReplicationHealth::Resynchronizing,
+            expected_digests: Some(FAKE_DIGESTS),
+            last_attested_age_ms: Some(125),
+            mismatch_count: 1,
         }
     }
 
@@ -487,6 +509,7 @@ impl LightingReplicationStatus for FakeReplication {
             wake_active: true,
             effective_output_enabled: false,
             age_ms: 250,
+            digests: Some(FAKE_DIGESTS),
         })
     }
 }
@@ -520,9 +543,11 @@ fn lighting_observability_endpoints_cross_the_full_loopback() {
         StandardReply,
     };
     use rmk_types::protocol::rynk::{
-        LightingFramePageResult, LightingFrameRequest, LightingNodeId, LightingReplicaStatusResult, LightingRgb8,
+        LightingFramePageResult, LightingFrameRequest, LightingNodeId, LightingReplicaStatusResult,
+        LightingReplicationHealth, LightingRgb8,
     };
 
+    REPLICATION_REFRESHES.store(0, core::sync::atomic::Ordering::Relaxed);
     let descriptor = RynkLightingDescriptor {
         routing: LightingRouting {
             outputs: &OBSERVABILITY_OUTPUTS,
@@ -665,12 +690,21 @@ fn lighting_observability_endpoints_cross_the_full_loopback() {
             .await
             .expect("outer replica-status envelope")
             .expect("replica status");
+        assert_eq!(REPLICATION_REFRESHES.load(core::sync::atomic::Ordering::Relaxed), 1,);
         assert_eq!(status.central.revision, 0);
         assert_eq!(status.central.presented_revision, Some(0));
+        assert!(!status.central.wake_active);
+        assert!(status.central.effective_output_enabled);
         let replication = status.replication.expect("the board wired a replication machine");
         assert_eq!(replication.last_acked_revision, Some(4));
         assert!(replication.awaiting_ack && replication.link_up);
         assert_eq!(replication.generation, 2);
+        assert!(replication.durable_dirty && !replication.context_dirty);
+        assert_eq!(replication.health, LightingReplicationHealth::Resynchronizing);
+        assert_eq!(replication.last_attested_age_ms, Some(125));
+        assert_eq!(replication.mismatch_count, 1);
+        let expected = replication.expected_digests.expect("central digest set");
+        assert_eq!((expected.settings, expected.overlay), (11, 12));
         let peripheral = status.peripheral.expect("the board heard from the peripheral");
         assert_eq!(peripheral.node, LightingNodeId(1));
         assert_eq!(peripheral.applied_revision, Some(4));
@@ -685,5 +719,6 @@ fn lighting_observability_endpoints_cross_the_full_loopback() {
         );
         assert!(peripheral.wake_active && !peripheral.effective_output_enabled);
         assert_eq!(peripheral.age_ms, 250);
+        assert_eq!(peripheral.digests.expect("peripheral digest set").revision, 4);
     });
 }
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 869125591..123fdaacb 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -32,20 +32,21 @@ use rmk_types::protocol::rynk::{
     LightingCapabilities, LightingCompiledSceneStatus, LightingCompiledScenesPage, LightingConditionalSceneStatus,
     LightingConditionalScenesPage, LightingExtendedRuntimeConditionalScenesPage, LightingExtension,
     LightingExtensionLayers, LightingExtensionNameKind, LightingExtensionNamesPage, LightingExtensionNamesRequest,
-    LightingExtensionParamsPage, LightingExtensionParamsRequest, LightingKeysPage, LightingLedsPage,
-    LightingOutputModeState, LightingOutputsPage, LightingOverlayPage, LightingOverlayPageRequest,
-    LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage, LightingResult, LightingRoutesPage,
-    LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
-    LightingRuntimeConditionalSceneTransaction, LightingRuntimeConditionalScenesPage, LightingScenePageRequest,
-    LightingSceneStatus, LightingSceneTransaction, LightingScenesPage, LightingState, LightingZoneMembershipsPage,
-    LightingZonesPage, LockStatus, MacroData, MatrixState, PeripheralStatus, ProtocolVersion,
-    PutLightingExtendedRuntimeConditionalSceneChunkRequest, PutLightingOverlayChunkRequest,
-    PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, SetComboBulkRequest, SetComboRequest,
-    SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest, SetLightingExtensionLayersRequest,
-    SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
-    SetLightingOutputModeRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
-    SetMacroRequest, SetMorseBulkRequest, SetMorseRequest, SplitCentralLatencyPolicy, SplitCentralLatencyState,
-    StorageResetMode, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest, command,
+    LightingExtensionParamsPage, LightingExtensionParamsRequest, LightingFramePage, LightingFrameRequest,
+    LightingKeysPage, LightingLedsPage, LightingOutputModeState, LightingOutputsPage, LightingOverlayPage,
+    LightingOverlayPageRequest, LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage,
+    LightingReplicaStatus, LightingResult, LightingRoutesPage, LightingRuntimeConditionalScenePageRequest,
+    LightingRuntimeConditionalSceneStatus, LightingRuntimeConditionalSceneTransaction,
+    LightingRuntimeConditionalScenesPage, LightingScenePageRequest, LightingSceneStatus, LightingSceneTransaction,
+    LightingScenesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus, MacroData,
+    MatrixState, PeripheralStatus, ProtocolVersion, PutLightingExtendedRuntimeConditionalSceneChunkRequest,
+    PutLightingOverlayChunkRequest, PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest,
+    SetComboBulkRequest, SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest,
+    SetLightingExtensionLayersRequest, SetLightingExtensionParamRequest, SetLightingExtensionStateRequest,
+    SetLightingLayerPolicyRequest, SetLightingOutputModeRequest, SetLightingOverlayRequest,
+    SetLightingSceneCellRequest, SetLightingStateRequest, SetMacroRequest, SetMorseBulkRequest, SetMorseRequest,
+    SplitCentralLatencyPolicy, SplitCentralLatencyState, StorageResetMode, UnsetLightingOverlayRequest,
+    UnsetLightingSceneCellRequest, command,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -438,6 +439,18 @@ impl Client {
         Self::flatten_lighting(self.request::<command::GetLightingOutputMode>(&()).await?)
     }
 
+    /// Read one page of the frame a lighting output most recently accepted.
+    pub async fn get_lighting_frame(&self, request: LightingFrameRequest) -> Result<LightingFramePage, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingFrame)?;
+        Self::flatten_lighting(self.request::<command::GetLightingFrame>(&request).await?)
+    }
+
+    /// Read the board's cached view of split lighting replication.
+    pub async fn get_lighting_replica_status(&self) -> Result<LightingReplicaStatus, RynkHostError> {
+        self.require_lighting(Cmd::GetLightingReplicaStatus)?;
+        Self::flatten_lighting(self.request::<command::GetLightingReplicaStatus>(&()).await?)
+    }
+
     pub async fn set_lighting_output_mode(
         &self,
         request: SetLightingOutputModeRequest,

From f5202f3c7dff95753d8d9e868a81ab2abed49256 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Wed, 5 Aug 2026 00:41:22 -0700
Subject: [PATCH 76/78] fix(split): satisfy collapsible_match on the app inbox
 arm

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 rmk/src/split/peripheral.rs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/rmk/src/split/peripheral.rs b/rmk/src/split/peripheral.rs
index 111516440..963aea835 100644
--- a/rmk/src/split/peripheral.rs
+++ b/rmk/src/split/peripheral.rs
@@ -287,7 +287,8 @@ impl<S: SplitWriter + SplitReader> SplitPeripheral<S> {
                             // split read loop (the application resyncs on
                             // reconnect and must tolerate loss).
                             SplitMessage::Application(data) => {
-                                if crate::split_app::SPLIT_APP_RX.try_send(data).is_err() {
+                                let queued = crate::split_app::SPLIT_APP_RX.try_send(data);
+                                if queued.is_err() {
                                     warn!("split app message dropped (inbox full)");
                                 }
                             }

From 2511ab2ed87d4a1bda5b6c4db1bc5c87499607c2 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 11 Aug 2026 13:42:03 -0700
Subject: [PATCH 77/78] feat: resolve semantic key ids to lighting emitters

---
 rmk-config/src/lib.rs               |   1 +
 rmk-config/src/resolved/lighting.rs |  45 ++++++-
 rmk-types/src/key.rs                |   6 +
 rmk-types/src/lib.rs                |   1 +
 rmk/src/lighting/selector.rs        |  26 +++-
 rmk/src/lighting/topology.rs        |  26 +++-
 rmk/src/physical_layout.rs          |   2 +
 rynk/src/api.rs                     |  89 +++++++++++---
 rynk/src/key_topology.rs            | 176 ++++++++++++++++++++++++++++
 rynk/src/lib.rs                     |   4 +
 10 files changed, 358 insertions(+), 18 deletions(-)
 create mode 100644 rmk-types/src/key.rs
 create mode 100644 rynk/src/key_topology.rs

diff --git a/rmk-config/src/lib.rs b/rmk-config/src/lib.rs
index 599fb74b8..a478b215d 100644
--- a/rmk-config/src/lib.rs
+++ b/rmk-config/src/lib.rs
@@ -705,6 +705,7 @@ pub(crate) struct LightingSceneCellTomlConfig {
 #[serde(untagged)]
 pub(crate) enum LightingTargetTomlConfig {
     Led { led: u16 },
+    KeyId { key: u16 },
     Key { key: [u8; 2] },
     Zone { zone: u8 },
     All { all: bool },
diff --git a/rmk-config/src/resolved/lighting.rs b/rmk-config/src/resolved/lighting.rs
index e7c6b525c..409b8b79e 100644
--- a/rmk-config/src/resolved/lighting.rs
+++ b/rmk-config/src/resolved/lighting.rs
@@ -290,6 +290,7 @@ impl crate::KeyboardTomlConfig {
         let layer_scenes = resolve_layer_scenes(
             keymap.layers,
             &config.layer_scenes,
+            &layout.keys,
             &emitters,
             &zone_memberships,
             &zone_ids,
@@ -297,6 +298,7 @@ impl crate::KeyboardTomlConfig {
         let conditional_scene_cells = resolve_conditional_scenes(
             keymap.layers,
             &config.conditional_scenes,
+            &layout.keys,
             &emitters,
             &zone_memberships,
             &zone_ids,
@@ -340,6 +342,7 @@ impl crate::KeyboardTomlConfig {
                             let slots = resolve_target_slots(
                                 &indicator.target,
                                 &id_to_slot,
+                                &layout.keys,
                                 &emitters,
                                 &zone_memberships,
                                 &zone_ids,
@@ -531,6 +534,7 @@ fn validate_routes(outputs: &[LightingOutput], routes: &[LightingRoute]) -> Resu
 fn resolve_layer_scenes(
     layer_count: u8,
     config: &[crate::LightingLayerSceneTomlConfig],
+    keys: &[[u8; 2]],
     emitters: &[LightingEmitter],
     zone_memberships: &[u8],
     zone_ids: &HashSet<u8>,
@@ -553,7 +557,7 @@ fn resolve_layer_scenes(
         }
         let mut cells = Vec::new();
         for cell in &scene.cells {
-            let slots = resolve_target_slots(&cell.target, &id_to_slot, emitters, zone_memberships, zone_ids)?;
+            let slots = resolve_target_slots(&cell.target, &id_to_slot, keys, emitters, zone_memberships, zone_ids)?;
             if slots.is_empty() {
                 return Err(format!(
                     "lighting layer scene {} target resolves to no emitters",
@@ -574,6 +578,7 @@ fn resolve_layer_scenes(
 fn resolve_conditional_scenes(
     layer_count: u8,
     config: &[crate::LightingConditionalSceneTomlConfig],
+    keys: &[[u8; 2]],
     emitters: &[LightingEmitter],
     zone_memberships: &[u8],
     zone_ids: &HashSet<u8>,
@@ -638,7 +643,7 @@ fn resolve_conditional_scenes(
             output_mode,
         };
         for cell in &scene.cells {
-            let slots = resolve_target_slots(&cell.target, &id_to_slot, emitters, zone_memberships, zone_ids)?;
+            let slots = resolve_target_slots(&cell.target, &id_to_slot, keys, emitters, zone_memberships, zone_ids)?;
             if slots.is_empty() {
                 return Err(format!(
                     "lighting conditional scene {index} target resolves to no emitters"
@@ -658,6 +663,7 @@ fn resolve_conditional_scenes(
 fn resolve_target_slots(
     target: &LightingTargetTomlConfig,
     id_to_slot: &HashMap<u16, u16>,
+    keys: &[[u8; 2]],
     emitters: &[LightingEmitter],
     zone_memberships: &[u8],
     zone_ids: &HashSet<u8>,
@@ -668,6 +674,17 @@ fn resolve_target_slots(
                 .get(&led)
                 .ok_or_else(|| format!("lighting scene references unknown emitter id {led}"))?,
         ],
+        LightingTargetTomlConfig::KeyId { key: key_id } => {
+            let key = *keys
+                .get(key_id as usize)
+                .ok_or_else(|| format!("lighting scene references unknown logical key id {key_id}"))?;
+            emitters
+                .iter()
+                .enumerate()
+                .filter(|(_, emitter)| emitter.key == Some(key))
+                .map(|(slot, _)| slot as u16)
+                .collect()
+        }
         LightingTargetTomlConfig::Key { key } => emitters
             .iter()
             .enumerate()
@@ -817,6 +834,30 @@ effect = { kind = "solid", color = [1, 2, 3] }
         assert_eq!(lighting.layer_scenes[0].cells.len(), 2);
     }
 
+    #[test]
+    fn resolves_logical_key_ids_before_lowering_to_led_slots() {
+        let source = BASE.replace("target = { zone = 1 }", "target = { key = 0 }");
+        let config = parse(&source);
+        let layout = config.layout().unwrap();
+        let keymap = config.keymap().unwrap();
+        let lighting = config.lighting(&layout, &keymap).unwrap().unwrap();
+
+        assert_eq!(layout.keys[0], [0, 0]);
+        assert_eq!(lighting.layer_scenes[0].cells.len(), 1);
+        assert_eq!(lighting.layer_scenes[0].cells[0].slot, 0);
+    }
+
+    #[test]
+    fn rejects_unknown_logical_key_ids() {
+        let source = BASE.replace("target = { zone = 1 }", "target = { key = 2 }");
+        let config = parse(&source);
+        let layout = config.layout().unwrap();
+        let keymap = config.keymap().unwrap();
+        let error = config.lighting(&layout, &keymap).unwrap_err();
+
+        assert!(error.contains("unknown logical key id 2"), "{error}");
+    }
+
     #[test]
     fn rejects_emitter_key_that_is_only_inside_matrix_bounds() {
         let hole = BASE
diff --git a/rmk-types/src/key.rs b/rmk-types/src/key.rs
new file mode 100644
index 000000000..850ded1e6
--- /dev/null
+++ b/rmk-types/src/key.rs
@@ -0,0 +1,6 @@
+//! Stable semantic identities for physical keys.
+
+/// Stable identity of one logical key within a topology revision.
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[repr(transparent)]
+pub struct KeyId(pub u16);
diff --git a/rmk-types/src/lib.rs b/rmk-types/src/lib.rs
index a89065883..db7a6752c 100644
--- a/rmk-types/src/lib.rs
+++ b/rmk-types/src/lib.rs
@@ -45,6 +45,7 @@ pub mod constants;
 pub mod dfu;
 pub mod fmt;
 pub mod fork;
+pub mod key;
 pub mod keycode;
 pub mod led_indicator;
 pub mod modifier;
diff --git a/rmk/src/lighting/selector.rs b/rmk/src/lighting/selector.rs
index 8f09e0526..5d03e0d72 100644
--- a/rmk/src/lighting/selector.rs
+++ b/rmk/src/lighting/selector.rs
@@ -1,10 +1,11 @@
-use super::topology::{LedId, LedSlot, LightingTopology, MatrixPosition, ZoneId};
+use super::topology::{KeyId, LedId, LedSlot, LightingTopology, MatrixPosition, ZoneId};
 
 /// Stable configuration-level selector. None of these variants exposes a
 /// local frame slot or electrical chain index.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum LedSelector {
     Led(LedId),
+    KeyId(KeyId),
     Key(MatrixPosition),
     Zone(ZoneId),
     All,
@@ -15,6 +16,7 @@ pub enum ResolveError {
     EmptySelection,
     NoMatches(LedSelector),
     UnknownLed(LedId),
+    UnknownKeyId(KeyId),
     UnknownKey(MatrixPosition),
     UnknownZone(ZoneId),
     CapacityExceeded { capacity: usize },
@@ -49,6 +51,15 @@ impl<const CAP: usize> ResolvedTargets<CAP> {
                     matched = true;
                     resolved.insert(slot)?;
                 }
+                LedSelector::KeyId(id) => {
+                    if topology.key(id).is_none() {
+                        return Err(ResolveError::UnknownKeyId(id));
+                    }
+                    for (slot, _) in topology.leds_for_key_id(id) {
+                        matched = true;
+                        resolved.insert(slot)?;
+                    }
+                }
                 LedSelector::Key(key) => {
                     if !topology.has_key(key) {
                         return Err(ResolveError::UnknownKey(key));
@@ -165,6 +176,7 @@ mod tests {
             &topology(),
             &[
                 LedSelector::Led(LedId(10)),
+                LedSelector::KeyId(KeyId(0)),
                 LedSelector::Key(KEY),
                 LedSelector::Zone(ZoneId(7)),
             ],
@@ -173,6 +185,18 @@ mod tests {
         assert_eq!(targets.as_slice(), &[LedSlot(0), LedSlot(1)]);
     }
 
+    #[test]
+    fn key_ids_resolve_through_matrix_associations() {
+        let targets = ResolvedTargets::<3>::resolve(&topology(), &[LedSelector::KeyId(KeyId(0))]).unwrap();
+        assert_eq!(targets.as_slice(), &[LedSlot(0), LedSlot(1)]);
+        assert_eq!(topology().key(KeyId(0)), Some(KEY));
+        assert_eq!(topology().key_id(KEY), Some(KeyId(0)));
+        assert_eq!(
+            ResolvedTargets::<3>::resolve(&topology(), &[LedSelector::KeyId(KeyId(1))]),
+            Err(ResolveError::UnknownKeyId(KeyId(1)))
+        );
+    }
+
     #[test]
     fn resolution_failure_is_atomic() {
         assert_eq!(
diff --git a/rmk/src/lighting/topology.rs b/rmk/src/lighting/topology.rs
index 612daede3..940212a7e 100644
--- a/rmk/src/lighting/topology.rs
+++ b/rmk/src/lighting/topology.rs
@@ -2,7 +2,7 @@
 
 use core::ops::{BitOr, BitOrAssign};
 
-pub use crate::physical_layout::{Coordinate as Coord, KeyPosition as MatrixPosition, PhysicalLayout, Point3};
+pub use crate::physical_layout::{Coordinate as Coord, KeyId, KeyPosition as MatrixPosition, PhysicalLayout, Point3};
 
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 #[repr(transparent)]
@@ -127,6 +127,30 @@ impl<'a> LightingTopology<'a> {
         self.keys.contains(&matrix)
     }
 
+    /// Resolve a semantic key ID to its low-level matrix position.
+    pub fn key(&self, id: KeyId) -> Option<MatrixPosition> {
+        self.keys.get(id.0 as usize).copied()
+    }
+
+    /// Resolve a low-level matrix position to its semantic key ID.
+    pub fn key_id(&self, matrix: MatrixPosition) -> Option<KeyId> {
+        self.keys
+            .iter()
+            .position(|key| *key == matrix)
+            .and_then(|index| u16::try_from(index).ok())
+            .map(KeyId)
+    }
+
+    pub fn leds_for_key_id(&'a self, id: KeyId) -> impl Iterator<Item = (LedSlot, &'a LedMetadata)> + 'a {
+        let matrix = self.key(id);
+        self.leds.iter().enumerate().filter_map(move |(index, led)| {
+            if led.key != matrix || matrix.is_none() {
+                return None;
+            }
+            Some((LedSlot(u16::try_from(index).ok()?), led))
+        })
+    }
+
     pub fn effective_position(&self, slot: LedSlot) -> Option<Point3> {
         let led = self.led(slot)?;
         led.position.or_else(|| {
diff --git a/rmk/src/physical_layout.rs b/rmk/src/physical_layout.rs
index 3e3852ec7..daed4bdbb 100644
--- a/rmk/src/physical_layout.rs
+++ b/rmk/src/physical_layout.rs
@@ -1,6 +1,8 @@
 //! Allocation-free physical key geometry shared by lighting, display, and
 //! host-facing layout consumers.
 
+pub use rmk_types::key::KeyId;
+
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 pub struct KeyPosition {
     pub row: u8,
diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 123fdaacb..8727ba262 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -33,20 +33,20 @@ use rmk_types::protocol::rynk::{
     LightingConditionalScenesPage, LightingExtendedRuntimeConditionalScenesPage, LightingExtension,
     LightingExtensionLayers, LightingExtensionNameKind, LightingExtensionNamesPage, LightingExtensionNamesRequest,
     LightingExtensionParamsPage, LightingExtensionParamsRequest, LightingFramePage, LightingFrameRequest,
-    LightingKeysPage, LightingLedsPage, LightingOutputModeState, LightingOutputsPage, LightingOverlayPage,
-    LightingOverlayPageRequest, LightingOverlayTransaction, LightingPageRequest, LightingPhysicalKeysPage,
-    LightingReplicaStatus, LightingResult, LightingRoutesPage, LightingRuntimeConditionalScenePageRequest,
-    LightingRuntimeConditionalSceneStatus, LightingRuntimeConditionalSceneTransaction,
-    LightingRuntimeConditionalScenesPage, LightingScenePageRequest, LightingSceneStatus, LightingSceneTransaction,
-    LightingScenesPage, LightingState, LightingZoneMembershipsPage, LightingZonesPage, LockStatus, MacroData,
-    MatrixState, PeripheralStatus, ProtocolVersion, PutLightingExtendedRuntimeConditionalSceneChunkRequest,
-    PutLightingOverlayChunkRequest, PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest,
-    SetComboBulkRequest, SetComboRequest, SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest,
-    SetLightingExtensionLayersRequest, SetLightingExtensionParamRequest, SetLightingExtensionStateRequest,
-    SetLightingLayerPolicyRequest, SetLightingOutputModeRequest, SetLightingOverlayRequest,
-    SetLightingSceneCellRequest, SetLightingStateRequest, SetMacroRequest, SetMorseBulkRequest, SetMorseRequest,
-    SplitCentralLatencyPolicy, SplitCentralLatencyState, StorageResetMode, UnsetLightingOverlayRequest,
-    UnsetLightingSceneCellRequest, command,
+    LightingKeysPage, LightingLed, LightingLedsPage, LightingMatrixPosition, LightingOutputModeState,
+    LightingOutputsPage, LightingOverlayPage, LightingOverlayPageRequest, LightingOverlayTransaction,
+    LightingPageRequest, LightingPhysicalKeysPage, LightingReplicaStatus, LightingResult, LightingRoutesPage,
+    LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
+    LightingRuntimeConditionalSceneTransaction, LightingRuntimeConditionalScenesPage, LightingScenePageRequest,
+    LightingSceneStatus, LightingSceneTransaction, LightingScenesPage, LightingState, LightingZoneMembershipsPage,
+    LightingZonesPage, LockStatus, MacroData, MatrixState, PeripheralStatus, ProtocolVersion,
+    PutLightingExtendedRuntimeConditionalSceneChunkRequest, PutLightingOverlayChunkRequest,
+    PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, SetComboBulkRequest, SetComboRequest,
+    SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest, SetLightingExtensionLayersRequest,
+    SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
+    SetLightingOutputModeRequest, SetLightingOverlayRequest, SetLightingSceneCellRequest, SetLightingStateRequest,
+    SetMacroRequest, SetMorseBulkRequest, SetMorseRequest, SplitCentralLatencyPolicy, SplitCentralLatencyState,
+    StorageResetMode, UnsetLightingOverlayRequest, UnsetLightingSceneCellRequest, command,
 };
 #[cfg(feature = "alloc")]
 use rmk_types::protocol::rynk::{RYNK_HEADER_SIZE, RynkError, max_wire_size};
@@ -57,6 +57,8 @@ use serde::Serialize;
 use crate::driver::MAX_IN_FLIGHT;
 use crate::driver::{Client, RynkHostError};
 #[cfg(feature = "alloc")]
+use crate::key_topology::KeyTopology;
+#[cfg(feature = "alloc")]
 use crate::layout::LayoutInfo;
 
 /// A pipelined request parks in the firmware's shared frame buffer while another is served,
@@ -1002,6 +1004,65 @@ impl Client {
         .await
     }
 
+    /// Read and validate the semantic key-to-emitter topology under one
+    /// firmware topology revision. The existing paged wire endpoints stay
+    /// low-level; this assembles their relational view for host selectors.
+    pub async fn read_lighting_key_topology(&self) -> Result<KeyTopology, RynkHostError> {
+        let capabilities = self.get_lighting_capabilities().await?;
+        let revision = capabilities.topology_revision;
+
+        let mut keys: Vec<LightingMatrixPosition> = Vec::with_capacity(capabilities.logical_key_count as usize);
+        let mut offset = 0u16;
+        while offset < capabilities.logical_key_count {
+            let page = self
+                .get_lighting_keys(LightingPageRequest {
+                    topology_revision: revision,
+                    offset,
+                })
+                .await?;
+            if page.topology_revision != revision
+                || page.total_count != capabilities.logical_key_count
+                || page.items.is_empty()
+                || usize::from(offset) + page.items.len() > usize::from(page.total_count)
+            {
+                return Err(RynkHostError::InconsistentResponse {
+                    cmd: Cmd::GetLightingKeys,
+                    reason: "logical-key page does not match the pinned topology",
+                });
+            }
+            offset += page.items.len() as u16;
+            keys.extend(page.items.iter().copied());
+        }
+
+        let mut leds: Vec<LightingLed> = Vec::with_capacity(capabilities.led_count as usize);
+        let mut offset = 0u16;
+        while offset < capabilities.led_count {
+            let page = self
+                .get_lighting_leds(LightingPageRequest {
+                    topology_revision: revision,
+                    offset,
+                })
+                .await?;
+            if page.topology_revision != revision
+                || page.total_count != capabilities.led_count
+                || page.items.is_empty()
+                || usize::from(offset) + page.items.len() > usize::from(page.total_count)
+            {
+                return Err(RynkHostError::InconsistentResponse {
+                    cmd: Cmd::GetLightingLeds,
+                    reason: "LED page does not match the pinned topology",
+                });
+            }
+            offset += page.items.len() as u16;
+            leds.extend(page.items.iter().copied());
+        }
+
+        KeyTopology::new(revision, keys, leds).map_err(|_| RynkHostError::InconsistentResponse {
+            cmd: Cmd::GetLightingKeys,
+            reason: "key and LED metadata do not form a valid topology",
+        })
+    }
+
     /// Read the whole transient overlay under one state revision. Expiry or a
     /// concurrent mutation restarts the snapshot, bounded to a few attempts.
     pub async fn read_all_lighting_overlay(
diff --git a/rynk/src/key_topology.rs b/rynk/src/key_topology.rs
new file mode 100644
index 000000000..a7074ac6f
--- /dev/null
+++ b/rynk/src/key_topology.rs
@@ -0,0 +1,176 @@
+//! Host-side semantic key topology and lowering into lighting emitters.
+
+use alloc::vec::Vec;
+
+pub use rmk_types::key::KeyId;
+use rmk_types::protocol::rynk::{LightingLed, LightingLedId, LightingMatrixPosition};
+
+/// One canonical logical key. More semantic identifiers and attributes can be
+/// added here without changing the low-level matrix or LED protocols.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LogicalKey {
+    pub id: KeyId,
+    pub matrix: LightingMatrixPosition,
+}
+
+/// Anything that can select keys from the advertised topology.
+///
+/// The trait is deliberately open: board-aware tools can implement their own
+/// names, regions, or aliases and still lower the result through the common
+/// topology path.
+pub trait KeySelector {
+    fn matches(&self, key: &LogicalKey) -> bool;
+}
+
+impl KeySelector for KeyId {
+    fn matches(&self, key: &LogicalKey) -> bool {
+        *self == key.id
+    }
+}
+
+impl KeySelector for LightingMatrixPosition {
+    fn matches(&self, key: &LogicalKey) -> bool {
+        *self == key.matrix
+    }
+}
+
+impl<F> KeySelector for F
+where
+    F: Fn(&LogicalKey) -> bool,
+{
+    fn matches(&self, key: &LogicalKey) -> bool {
+        self(key)
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum TopologyError {
+    TooManyKeys,
+    DuplicateMatrix(LightingMatrixPosition),
+    DuplicateLed(LightingLedId),
+    UnknownLedKey(LightingMatrixPosition),
+}
+
+/// A revision-pinned semantic view assembled from Rynk's existing key and LED
+/// metadata pages.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct KeyTopology {
+    pub topology_revision: u32,
+    pub keys: Vec<LogicalKey>,
+    pub leds: Vec<LightingLed>,
+}
+
+impl KeyTopology {
+    pub fn new(
+        topology_revision: u32,
+        matrices: Vec<LightingMatrixPosition>,
+        leds: Vec<LightingLed>,
+    ) -> Result<Self, TopologyError> {
+        let mut keys = Vec::with_capacity(matrices.len());
+        for (index, matrix) in matrices.into_iter().enumerate() {
+            let id = u16::try_from(index).map_err(|_| TopologyError::TooManyKeys)?;
+            if keys.iter().any(|key: &LogicalKey| key.matrix == matrix) {
+                return Err(TopologyError::DuplicateMatrix(matrix));
+            }
+            keys.push(LogicalKey { id: KeyId(id), matrix });
+        }
+        for (index, led) in leds.iter().enumerate() {
+            if leds[..index].iter().any(|previous| previous.id == led.id) {
+                return Err(TopologyError::DuplicateLed(led.id));
+            }
+            if let Some(matrix) = led.key
+                && !keys.iter().any(|key| key.matrix == matrix)
+            {
+                return Err(TopologyError::UnknownLedKey(matrix));
+            }
+        }
+        Ok(Self {
+            topology_revision,
+            keys,
+            leds,
+        })
+    }
+
+    pub fn select<'a, S>(&'a self, selector: &'a S) -> impl Iterator<Item = &'a LogicalKey> + 'a
+    where
+        S: KeySelector + ?Sized,
+    {
+        self.keys.iter().filter(move |key| selector.matches(key))
+    }
+
+    /// Lower every selected key to all associated semantic LED IDs.
+    pub fn resolve_leds<S>(&self, selector: &S) -> Vec<LightingLedId>
+    where
+        S: KeySelector + ?Sized,
+    {
+        let mut resolved = Vec::new();
+        for key in self.select(selector) {
+            for led in &self.leds {
+                if led.key == Some(key.matrix) && !resolved.contains(&led.id) {
+                    resolved.push(led.id);
+                }
+            }
+        }
+        resolved
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn matrix(row: u8, col: u8) -> LightingMatrixPosition {
+        LightingMatrixPosition { row, col }
+    }
+
+    fn led(id: u16, key: Option<LightingMatrixPosition>) -> LightingLed {
+        LightingLed {
+            id: LightingLedId(id),
+            key,
+            position: None,
+            zone_start: 0,
+            zone_len: 0,
+        }
+    }
+
+    #[test]
+    fn resolves_ids_matrix_positions_and_open_selectors_to_emitters() {
+        let topology = KeyTopology::new(
+            7,
+            vec![matrix(0, 0), matrix(0, 2)],
+            vec![
+                led(34, Some(matrix(0, 0))),
+                led(80, Some(matrix(0, 0))),
+                led(22, Some(matrix(0, 2))),
+                led(99, None),
+            ],
+        )
+        .unwrap();
+
+        assert_eq!(
+            topology.resolve_leds(&KeyId(0)),
+            vec![LightingLedId(34), LightingLedId(80)]
+        );
+        assert_eq!(topology.resolve_leds(&matrix(0, 2)), vec![LightingLedId(22)]);
+        assert_eq!(
+            topology.resolve_leds(&|key: &LogicalKey| key.matrix.col >= 1),
+            vec![LightingLedId(22)]
+        );
+    }
+
+    #[test]
+    fn validates_relational_metadata() {
+        assert_eq!(
+            KeyTopology::new(1, vec![matrix(0, 0), matrix(0, 0)], vec![]),
+            Err(TopologyError::DuplicateMatrix(matrix(0, 0)))
+        );
+        assert_eq!(
+            KeyTopology::new(1, vec![matrix(0, 0)], vec![led(1, None), led(1, None)]),
+            Err(TopologyError::DuplicateLed(LightingLedId(1)))
+        );
+        assert_eq!(
+            KeyTopology::new(1, vec![matrix(0, 0)], vec![led(1, Some(matrix(1, 0)))]),
+            Err(TopologyError::UnknownLedKey(matrix(1, 0)))
+        );
+    }
+}
diff --git a/rynk/src/lib.rs b/rynk/src/lib.rs
index 6a0284542..5c66333e5 100644
--- a/rynk/src/lib.rs
+++ b/rynk/src/lib.rs
@@ -96,12 +96,16 @@ mod api;
 mod device;
 mod driver;
 #[cfg(feature = "alloc")]
+pub mod key_topology;
+#[cfg(feature = "alloc")]
 pub mod layout;
 
 pub use device::RynkDevice;
 pub use driver::{Client, Driver, RynkHostError};
 pub use embedded_io_async as io;
 #[cfg(feature = "alloc")]
+pub use key_topology::{KeyId, KeySelector, KeyTopology, LogicalKey, TopologyError};
+#[cfg(feature = "alloc")]
 pub use layout::LayoutInfo;
 pub use rmk_types;
 /// The decoded topic union returned by [`Client::next_topic`]

From c5dfce7a777d4cffc9771fd9dc398e6ec1b20244 Mon Sep 17 00:00:00 2001
From: Ivan Malison <IvanMalison@gmail.com>
Date: Tue, 11 Aug 2026 15:54:36 -0700
Subject: [PATCH 78/78] feat: include lighting zones in semantic topology

---
 rynk/src/api.rs          |  60 ++++++++++++++++++++---
 rynk/src/key_topology.rs | 103 +++++++++++++++++++++++++++++++++++++--
 2 files changed, 153 insertions(+), 10 deletions(-)

diff --git a/rynk/src/api.rs b/rynk/src/api.rs
index 8727ba262..661a84c9d 100644
--- a/rynk/src/api.rs
+++ b/rynk/src/api.rs
@@ -38,9 +38,9 @@ use rmk_types::protocol::rynk::{
     LightingPageRequest, LightingPhysicalKeysPage, LightingReplicaStatus, LightingResult, LightingRoutesPage,
     LightingRuntimeConditionalScenePageRequest, LightingRuntimeConditionalSceneStatus,
     LightingRuntimeConditionalSceneTransaction, LightingRuntimeConditionalScenesPage, LightingScenePageRequest,
-    LightingSceneStatus, LightingSceneTransaction, LightingScenesPage, LightingState, LightingZoneMembershipsPage,
-    LightingZonesPage, LockStatus, MacroData, MatrixState, PeripheralStatus, ProtocolVersion,
-    PutLightingExtendedRuntimeConditionalSceneChunkRequest, PutLightingOverlayChunkRequest,
+    LightingSceneStatus, LightingSceneTransaction, LightingScenesPage, LightingState, LightingZone, LightingZoneId,
+    LightingZoneMembershipsPage, LightingZonesPage, LockStatus, MacroData, MatrixState, PeripheralStatus,
+    ProtocolVersion, PutLightingExtendedRuntimeConditionalSceneChunkRequest, PutLightingOverlayChunkRequest,
     PutLightingRuntimeConditionalSceneChunkRequest, PutLightingSceneChunkRequest, SetComboBulkRequest, SetComboRequest,
     SetEncoderRequest, SetForkRequest, SetKeyRequest, SetKeymapBulkRequest, SetLightingExtensionLayersRequest,
     SetLightingExtensionParamRequest, SetLightingExtensionStateRequest, SetLightingLayerPolicyRequest,
@@ -1057,9 +1057,57 @@ impl Client {
             leds.extend(page.items.iter().copied());
         }
 
-        KeyTopology::new(revision, keys, leds).map_err(|_| RynkHostError::InconsistentResponse {
-            cmd: Cmd::GetLightingKeys,
-            reason: "key and LED metadata do not form a valid topology",
+        let mut zones: Vec<LightingZone> = Vec::with_capacity(capabilities.zone_count as usize);
+        let mut offset = 0u16;
+        while offset < capabilities.zone_count {
+            let page = self
+                .get_lighting_zones(LightingPageRequest {
+                    topology_revision: revision,
+                    offset,
+                })
+                .await?;
+            if page.topology_revision != revision
+                || page.total_count != capabilities.zone_count
+                || page.items.is_empty()
+                || usize::from(offset) + page.items.len() > usize::from(page.total_count)
+            {
+                return Err(RynkHostError::InconsistentResponse {
+                    cmd: Cmd::GetLightingZones,
+                    reason: "zone page does not match the pinned topology",
+                });
+            }
+            offset += page.items.len() as u16;
+            zones.extend(page.items.iter().cloned());
+        }
+
+        let mut zone_memberships: Vec<LightingZoneId> = Vec::with_capacity(capabilities.zone_membership_count as usize);
+        let mut offset = 0u16;
+        while offset < capabilities.zone_membership_count {
+            let page = self
+                .get_lighting_zone_memberships(LightingPageRequest {
+                    topology_revision: revision,
+                    offset,
+                })
+                .await?;
+            if page.topology_revision != revision
+                || page.total_count != capabilities.zone_membership_count
+                || page.items.is_empty()
+                || usize::from(offset) + page.items.len() > usize::from(page.total_count)
+            {
+                return Err(RynkHostError::InconsistentResponse {
+                    cmd: Cmd::GetLightingZoneMemberships,
+                    reason: "zone-membership page does not match the pinned topology",
+                });
+            }
+            offset += page.items.len() as u16;
+            zone_memberships.extend(page.items.iter().copied());
+        }
+
+        KeyTopology::new(revision, keys, leds, zones, zone_memberships).map_err(|_| {
+            RynkHostError::InconsistentResponse {
+                cmd: Cmd::GetLightingKeys,
+                reason: "key, LED, and zone metadata do not form a valid topology",
+            }
         })
     }
 
diff --git a/rynk/src/key_topology.rs b/rynk/src/key_topology.rs
index a7074ac6f..9d43928b0 100644
--- a/rynk/src/key_topology.rs
+++ b/rynk/src/key_topology.rs
@@ -3,7 +3,7 @@
 use alloc::vec::Vec;
 
 pub use rmk_types::key::KeyId;
-use rmk_types::protocol::rynk::{LightingLed, LightingLedId, LightingMatrixPosition};
+use rmk_types::protocol::rynk::{LightingLed, LightingLedId, LightingMatrixPosition, LightingZone, LightingZoneId};
 
 /// One canonical logical key. More semantic identifiers and attributes can be
 /// added here without changing the low-level matrix or LED protocols.
@@ -49,6 +49,9 @@ pub enum TopologyError {
     DuplicateMatrix(LightingMatrixPosition),
     DuplicateLed(LightingLedId),
     UnknownLedKey(LightingMatrixPosition),
+    DuplicateZone(LightingZoneId),
+    InvalidZoneSpan(LightingLedId),
+    UnknownZoneMembership(LightingZoneId),
 }
 
 /// A revision-pinned semantic view assembled from Rynk's existing key and LED
@@ -58,6 +61,8 @@ pub struct KeyTopology {
     pub topology_revision: u32,
     pub keys: Vec<LogicalKey>,
     pub leds: Vec<LightingLed>,
+    pub zones: Vec<LightingZone>,
+    pub zone_memberships: Vec<LightingZoneId>,
 }
 
 impl KeyTopology {
@@ -65,6 +70,8 @@ impl KeyTopology {
         topology_revision: u32,
         matrices: Vec<LightingMatrixPosition>,
         leds: Vec<LightingLed>,
+        zones: Vec<LightingZone>,
+        zone_memberships: Vec<LightingZoneId>,
     ) -> Result<Self, TopologyError> {
         let mut keys = Vec::with_capacity(matrices.len());
         for (index, matrix) in matrices.into_iter().enumerate() {
@@ -83,11 +90,29 @@ impl KeyTopology {
             {
                 return Err(TopologyError::UnknownLedKey(matrix));
             }
+            let zone_end = usize::from(led.zone_start)
+                .checked_add(usize::from(led.zone_len))
+                .ok_or(TopologyError::InvalidZoneSpan(led.id))?;
+            if zone_end > zone_memberships.len() {
+                return Err(TopologyError::InvalidZoneSpan(led.id));
+            }
+        }
+        for (index, zone) in zones.iter().enumerate() {
+            if zones[..index].iter().any(|previous| previous.id == zone.id) {
+                return Err(TopologyError::DuplicateZone(zone.id));
+            }
+        }
+        for zone in &zone_memberships {
+            if !zones.iter().any(|candidate| candidate.id == *zone) {
+                return Err(TopologyError::UnknownZoneMembership(*zone));
+            }
         }
         Ok(Self {
             topology_revision,
             keys,
             leds,
+            zones,
+            zone_memberships,
         })
     }
 
@@ -113,6 +138,28 @@ impl KeyTopology {
         }
         resolved
     }
+
+    pub fn has_zone(&self, zone: LightingZoneId) -> bool {
+        self.zones.iter().any(|candidate| candidate.id == zone)
+    }
+
+    pub fn resolve_zone_leds(&self, zone: LightingZoneId) -> Vec<LightingLedId> {
+        self.leds
+            .iter()
+            .filter(|led| {
+                let start = usize::from(led.zone_start);
+                let end = start + usize::from(led.zone_len);
+                self.zone_memberships
+                    .get(start..end)
+                    .is_some_and(|memberships| memberships.contains(&zone))
+            })
+            .map(|led| led.id)
+            .collect()
+    }
+
+    pub fn all_leds(&self) -> Vec<LightingLedId> {
+        self.leds.iter().map(|led| led.id).collect()
+    }
 }
 
 #[cfg(test)]
@@ -133,6 +180,13 @@ mod tests {
         }
     }
 
+    fn zone(id: u8, name: &str) -> LightingZone {
+        LightingZone {
+            id: LightingZoneId(id),
+            name: name.try_into().unwrap(),
+        }
+    }
+
     #[test]
     fn resolves_ids_matrix_positions_and_open_selectors_to_emitters() {
         let topology = KeyTopology::new(
@@ -144,6 +198,8 @@ mod tests {
                 led(22, Some(matrix(0, 2))),
                 led(99, None),
             ],
+            vec![],
+            vec![],
         )
         .unwrap();
 
@@ -161,16 +217,55 @@ mod tests {
     #[test]
     fn validates_relational_metadata() {
         assert_eq!(
-            KeyTopology::new(1, vec![matrix(0, 0), matrix(0, 0)], vec![]),
+            KeyTopology::new(1, vec![matrix(0, 0), matrix(0, 0)], vec![], vec![], vec![]),
             Err(TopologyError::DuplicateMatrix(matrix(0, 0)))
         );
         assert_eq!(
-            KeyTopology::new(1, vec![matrix(0, 0)], vec![led(1, None), led(1, None)]),
+            KeyTopology::new(1, vec![matrix(0, 0)], vec![led(1, None), led(1, None)], vec![], vec![],),
             Err(TopologyError::DuplicateLed(LightingLedId(1)))
         );
         assert_eq!(
-            KeyTopology::new(1, vec![matrix(0, 0)], vec![led(1, Some(matrix(1, 0)))]),
+            KeyTopology::new(1, vec![matrix(0, 0)], vec![led(1, Some(matrix(1, 0)))], vec![], vec![],),
             Err(TopologyError::UnknownLedKey(matrix(1, 0)))
         );
     }
+
+    #[test]
+    fn resolves_zones_and_all_emitters() {
+        let mut first = led(34, Some(matrix(0, 0)));
+        first.zone_len = 1;
+        let mut second = led(99, None);
+        second.zone_start = 1;
+        second.zone_len = 1;
+        let topology = KeyTopology::new(
+            7,
+            vec![matrix(0, 0)],
+            vec![first, second],
+            vec![zone(1, "keys"), zone(2, "status")],
+            vec![LightingZoneId(1), LightingZoneId(2)],
+        )
+        .unwrap();
+
+        assert!(topology.has_zone(LightingZoneId(1)));
+        assert_eq!(topology.resolve_zone_leds(LightingZoneId(2)), vec![LightingLedId(99)]);
+        assert_eq!(topology.all_leds(), vec![LightingLedId(34), LightingLedId(99)]);
+    }
+
+    #[test]
+    fn validates_zone_metadata() {
+        let mut invalid_span = led(1, None);
+        invalid_span.zone_len = 1;
+        assert_eq!(
+            KeyTopology::new(1, vec![], vec![invalid_span], vec![], vec![]),
+            Err(TopologyError::InvalidZoneSpan(LightingLedId(1)))
+        );
+        assert_eq!(
+            KeyTopology::new(1, vec![], vec![], vec![zone(1, "one"), zone(1, "duplicate")], vec![],),
+            Err(TopologyError::DuplicateZone(LightingZoneId(1)))
+        );
+        assert_eq!(
+            KeyTopology::new(1, vec![], vec![], vec![], vec![LightingZoneId(1)]),
+            Err(TopologyError::UnknownZoneMembership(LightingZoneId(1)))
+        );
+    }
 }