node-red-contrib-dmx-for-ha 0.1.0

package/subflow/dmx_node_v0.5.9.js

@@ -0,0 +1,1994 @@
+// TRANSITIONS — HA MQTT DMX NODE — HOME ASSISTANT in NODE-RED
+// Discord: @deswaggy  |  Version: 0.5.9
+// Extensions: "BETTER COMMENTS", "TODO TREE"
+
+//! BIG & BRIGHT
+//@ Topic Headers
+//# Description / Explanations
+//$ Logic
+//^ Debug Comments
+//? Breaks / Headers
+
+// Naming conventions:
+//   <env_var>      = Sub-flow environmental  (Edit subflow template)
+//   <<flow_var>>   = RAM flow memory         (flow.set / flow.get, "memory")
+//   <<D_flow_var>> = Disk flow memory        (flow.set / flow.get, "disk_values")
+//   <<<flow_env>>> = Flow-level environmental (Tab → gear → flow envs)
+
+// Context stores:
+//   memory      = fast, lost on reboot  → used during live operation
+//   disk_values = persistent            → written after a debounce delay
+
+// ─────────────────────────────────────────────────────────────────────────────
+//!@ CONFIG — all env reads in one place
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CFG = {
+    //@ HA identity
+    discoveryPrefix:    env.get("<HA_discovery_prefix>"),
+    siteId:             env.get("<HA_site_unique_id>"),
+    component:          env.get("<HA_component>"),
+    uidPrefix:          env.get("<HA_unique_id_prefix>"),
+    uid:                env.get("<HA_unique_id>"),
+    uidPostfix:         env.get("<HA_unique_id_postfix>"),
+
+    //@ MQTT
+    retain:             env.get("<HA_MQTT_retain_flag>"),
+    qos:                env.get("<HA_MQTT_QOS>"),
+    configTopic:        env.get("<HA_config_topic>"),
+    commandTopic:       env.get("<HA_command_topic>"),
+    stateTopic:         env.get("<HA_state_topic>"),
+
+    //@ HA features
+    schema:             env.get("<HA_schema>"),
+    optimistic:         env.get("<HA_optimistic>"),
+    enabledByDefault:   env.get("<HA_enabled_by_default>"),
+    icon:               env.get("<HA_icon>"),
+    colorModes:         env.get("<HA_supported_color_modes>"),   //^ string, split only when needed
+    brightness:         env.get("<HA_brightness>"),
+    dmxLimiter:         env.get("<HA_brightness_scale_and_dmx_limiter>")
+                            || node.error("No DMX Brightness Scale — check Node Menu"),
+    //^ Minimum DMX output value when the fixture state is ON.
+    //^ Prevents the gamma curve collapsing low brightness values to zero,
+    //^ which would cause the fixture to appear off while the HA slider is above 0%.
+    //^ Default: 1 — guarantees something visible at any brightness above 0%.
+    //^ Set to 0 to disable (pure gamma — recommended for lighting designers who
+    //^ want mathematically correct perceptual response and understand the behaviour).
+    //^ Note: this floor is only applied when state is ON. OFF always sends true 0.
+    dmxMinOutput:       (() => {
+        const raw = parseInt(env.get("<DMX_min_output>"));
+        return isNaN(raw) ? 1 : raw;
+    })(),
+    runTransitions:     env.get("<HA_run_Transitions>"),
+    transitionsEnabled: env.get("<HA_Transitions_Enabled>") ?? true,
+    effects:            env.get("<HA_effects>"),
+    //^ <HA_effects_list> — comma-separated list of effects to advertise to HA.
+    //^ Set this in the subflow env menu as a "str" type (comma-separated, no spaces).
+    //^ Recommended values per color mode:
+    //#
+    //^  onoff:
+    //#      flash_short,flash_long,strobe
+    //#
+    //^  brightness / white:
+    //#      flash_short,flash_long,strobe,flicker,relaxing,sleep_transition
+    //#
+    //^  rgb:
+    //#      flash_short,flash_long,strobe,rainbow,fire,flicker,twinkle,
+    //#      color_chase,scan,random,police,christmas,halloween,calaveras,
+    //#      party,fireworks,temperature_transition,sleep_transition
+    //#
+    //^  rgbw:
+    //#      flash_short,flash_long,strobe,rainbow,rainbow_rgbw,fire,flicker,twinkle,
+    //#      color_chase,scan,random,police,christmas,halloween,calaveras,
+    //#      party,fireworks,temperature_transition,sleep_transition
+    //#      (rainbow_rgbw modulates the white channel for a fuller colour spectrum)
+    //#
+    //^  rgbww:
+    //#      same as rgbw
+    //#
+    //^  color_temp:
+    //#      flash_short,flash_long,strobe,relaxing,sleep_transition,temperature_transition
+    //#
+    effectsList:        env.get("<HA_effects_list>").split(','),
+    flashShort:         env.get("<HA_effects_flash_time_Short_(seconds)>"),
+    flashLong:          env.get("<HA_effects_flash_time_Long_(seconds)>"),
+    //^ ADVANCED — LIGHT EFFECTS
+    //^ effectsGroupControlled: true  = effects only accepted via AUX from a parent Group Node (synced siblings)
+    //^                         false = this fixture handles effects directly from HA payload (independent)
+    //^ Default: true — synced effects are almost always correct in a grouped deployment.
+    //^ Set to false only for standalone fixtures with no Group Node parent.
+    effectsGroupControlled: env.get("<DMX_Effects_Group_Controlled>") !== "false",
+
+    //@ DMX
+    dmxZone:            env.get("<CONTROLLER_zone>"),
+    dmxChannel:         "dmx",
+    dmxUniverse:        env.get("<DMX_universe>"),
+    dmxControllerFw:    env.get("<CONTROLLER_fw_v>"),
+
+    //@ Channels
+    ch: {
+        red:       env.get("<DMX_ch_red>"),
+        green:     env.get("<DMX_ch_green>"),
+        blue:      env.get("<DMX_ch_blue>"),
+        white:     env.get("<DMX_ch_white>"),
+        warmWhite: env.get("<DMX_ch_warm_white>"),   //^ used by rgbww and color_temp warm channel
+        colorTemp: env.get("<DMX_ch_color_temp>"),   //^ dedicated CT channel if fixture has one
+    },
+
+    //@ Default ON values
+    defaultOn: {
+        //^ Fallback to 255 if env vars not set — prevents undefined reaching buildDmxPayload
+        brightness:   env.get("<DMX_default_on_v_brightness>") ?? 255,
+        red:          env.get("<DMX_default_on_v_red>")        ?? 255,
+        green:        env.get("<DMX_default_on_v_green>")      ?? 255,
+        blue:         env.get("<DMX_default_on_v_blue>")       ?? 255,
+        white:        env.get("<DMX_default_on_v_white>")      ?? 255,
+        warmWhite:    env.get("<DMX_default_on_v_warm_white>") ?? 0,
+        colorTemp:    env.get("<DMX_default_on_v_color_temp>") ?? 128,  //^ midpoint in mireds range
+        //^ Initial brightness bump sent instantly before a transition begins when coming from OFF.
+        //^ Gives the room immediate usable light even during a slow fade-in (0 = disabled).
+        initialBump:  env.get("<DMX_Brightness_Initial_on_value>") || 50,
+    },
+
+    //@ Default OFF values
+    defaultOff: {
+        red:       env.get("<DMX_default_off_v_red>")   ?? 0,
+        green:     env.get("<DMX_default_off_v_green>") ?? 0,
+        blue:      env.get("<DMX_default_off_v_blue>")  ?? 0,
+        white:     env.get("<DMX_off_v_white>")         ?? 0,
+        warmWhite: 0,
+    },
+
+    //@ Color temperature range (mireds) — set to match your fixture's spec
+    //^ HA sends mireds; we map linearly: minMireds → full cold white, maxMireds → full warm white
+    minMireds: env.get("<DMX_ct_min_mireds>") || 153,   //^ ~6500K cool
+    maxMireds: env.get("<DMX_ct_max_mireds>") || 500,   //^ ~2000K warm
+
+    //@ Transition — flow-level globals (<<<...>>>)
+    //^ Rate multiplier: 1 = normal, 2 = double speed, 0.5 = half speed
+    transitionRateLimit: env.get("<<<DMX_NODE_FLOW_Transition_Rate_Limit>>>") || 1,
+    //^ Default transition duration used when HA UI doesn't specify one (seconds)
+    transitionDefaultSecs: env.get("<<<DMX_NODE_FLOW_Transition_HA_UI_Time_(seconds)>>>") || 1,
+    //^ Steps per second for transition interpolation — node-level subflow env only.
+    //^ 31 ticks/s is a safe default (roughly matches DMX refresh at low-to-mid fixture counts).
+    transitionTicksPerSec: env.get("<DMX_transition_ticks_ps>") || 31,
+
+    //@ Device metadata
+    device: {
+        type:        env.get("<DEVICE_Type>"),
+        situation:   env.get("<DEVICE_situation>"),
+        area:        env.get("<DEVICE_area>"),
+        subLocation: env.get("<DEVICE_Sub_Location>"),
+    },
+
+    //@ Node metadata
+    nodeCode:    env.get("<NODE_code>"),
+    nodeSw:      env.get("<NODE_sw_v>"),
+
+    //@ Persistence
+    diskDelay:    env.get("<CONTEXT_STORE_values_to_disk_delay_in_seconds>"),
+    defaultState: env.get("<FIXTURE_Default_State>"),
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ TOPIC BUILDERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The base topic path for this fixture. */
+const fixtureTopic = `${CFG.discoveryPrefix}/${CFG.component}/${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`;
+
+/** The DMX controller MQTT topic. */
+const dmxTopic = `${CFG.siteId}/${CFG.dmxZone}/${CFG.dmxChannel}/${CFG.dmxUniverse}`;
+
+/** Short fixture identifier used in NR node status messages for quick visual feedback.
+ *  e.g. "L-991" — lets you instantly see which fixture a status belongs to on the canvas. */
+const fixtureId = `${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`;
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ MEMORY HELPERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Read a value from RAM → disk → env fallback, in that priority order.
+ * @param {string} ramKey   - flow memory key (e.g. "<<bright>>")
+ * @param {string} diskKey  - disk memory key (e.g. "<<D_bright>>")
+ * @param {*}      fallback - env default value
+ */
+function recall(ramKey, diskKey, fallback) {
+    return flow.get(ramKey, "memory") || flow.get(diskKey, "disk_values") || fallback;
+}
+
+/**
+ * Write a key/value map to RAM memory in one call.
+ * @param {Object} values - e.g. { "<<bright>>": 200, "<<white>>": 255 }
+ */
+function rememberRam(values) {
+    Object.entries(values).forEach(([key, val]) => flow.set(key, val, "memory"));
+}
+
+/**
+ * Write a key/value map to disk memory in one call.
+ * @param {Object} values - e.g. { "<<D_bright>>": 200 }
+ */
+function rememberDisk(values) {
+    Object.entries(values).forEach(([key, val]) => flow.set(key, val, "disk_values"));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ DMX HELPERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+//$  GAMMA CORRECTION
+//# Human vision is logarithmic, not linear. A raw DMX value of 128 (50%) looks
+//# roughly 73% as bright as 255, not 50%. Applying a gamma curve redistributes
+//# the 256 steps so equal DMX increments produce equal perceived brightness steps.
+//#
+//# GAMMA 2.2 = standard display/sRGB gamma — good baseline for most LED fixtures.
+//# Tune upward (2.5–2.8) if dim transitions still feel uneven on your hardware:
+//#   - Fade a fixture slowly from full to zero in a dark room.
+//#   - If the bottom quarter barely moves, increase GAMMA.
+//#   - If the top quarter jumps too fast, decrease GAMMA.
+//#
+//# The table is computed once at startup (256 entries) so Math.pow is never
+//# called during a live transition — important when 200–300 subflows are ticking.
+const GAMMA = 2.2;
+const GAMMA_TABLE = Object.freeze(
+    Array.from({ length: 256 }, (_, i) => {
+        if (i === 0) return 0;   //# i=0 must always be true zero
+        const scaled = Math.pow(i / 255, GAMMA) * CFG.dmxLimiter;
+        //# Clamp sub-0.5 results to 0 — prevents gamma rounding pushing 0 to 1,
+        //# which caused the HA colour picker white channel to never reach true off.
+        return scaled < 0.5 ? 0 : Math.round(scaled);
+    })
+);
+
+/**
+ * Scale a 0–255 color value with brightness, then apply gamma correction
+ * via the pre-computed lookup table. Returns an integer 0–dmxLimiter.
+ *
+ * When the input is non-zero, the result is floored to CFG.dmxMinOutput to
+ * prevent the gamma curve collapsing visible brightness levels to DMX zero.
+ * This ensures the fixture always produces something perceptible when the HA
+ * slider is above 0%, regardless of gamma compression at the low end.
+ *
+ * Set <DMX_min_output> = 0 to disable the floor for pure gamma behaviour.
+ *
+ * @param {number} colorValue       - raw 0–255 color channel value
+ * @param {number} [brightness=255] - 0–255 brightness multiplier
+ */
+function scaleToDmx(colorValue, brightness = 255) {
+    const linear = Math.round(colorValue * brightness / 255);
+    const gamma  = GAMMA_TABLE[Math.min(255, Math.max(0, linear))];
+    //# Only apply the floor when the input is genuinely non-zero.
+    //# A zero input means the channel is intentionally off — floor must not apply.
+    if (gamma === 0 && linear > 0 && CFG.dmxMinOutput > 0) {
+        return CFG.dmxMinOutput;
+    }
+    return gamma;
+}
+
+/**
+ * Build the "CCCVVV" string payload expected by the DMX controller.
+ * @param {number} channel
+ * @param {number} value
+ */
+function buildDmxPayload(channel, value) {
+    //# Guard: if channel or value is undefined/null, skip rather than send garbage
+    if (channel == null || value == null) {
+        node.warn(`buildDmxPayload — skipped: channel=${channel} value=${value}`);
+        return null;
+    }
+    return String(channel).padStart(3, '0') + String(value).padStart(3, '0');
+}
+
+/**
+ * Send one or more DMX channel updates in a single node.send call.
+ * @param {Array<[number, number]>} channels - array of [channel, scaledValue] pairs
+ */
+function sendDmxChannels(channels) {
+    channels.forEach(([ch, val]) => {
+        const payload = buildDmxPayload(ch, val);
+        if (payload === null) return; //# skip undefined channels
+        node.send([{
+            retain:  CFG.retain,
+            qos:     CFG.qos,
+            topic:   dmxTopic,
+            payload: payload,
+        }, null, null, null, null, null, null]);
+    });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ MQTT SEND HELPERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Report fixture state back to HA on output 1. */
+function sendState(payloadObj) {
+    node.send([{
+        retain:  CFG.retain,
+        qos:     CFG.qos,
+        topic:   `${fixtureTopic}/${CFG.stateTopic}`,
+        payload: payloadObj,
+    }, null, null, null, null, null, null]);
+}
+
+/** Send a Node-RED status message on output 3. */
+function sendStatus(fill, shape, text) {
+    node.send([null, null, {
+        debug:  { timers: text },
+        status: { fill, shape, text },
+    }, null, null, null, null]);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ DISK-SAVE TIMER
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Debounced disk-write timer.
+ * Resets any existing countdown and starts a fresh one.
+ * Calls `onComplete` once the delay has elapsed.
+ * @param {Function} onComplete - called when the timer expires
+ */
+function startDiskSaveTimer(onComplete) {
+    const existing = context.get('timer_diskSave');
+    if (existing) {
+        clearInterval(existing);
+        context.set('timer_diskSave', null);
+        context.set('timer_diskSave_count', 0);
+        console.log("Disk-save timer reset by new input.");
+    }
+
+    const maxLoops = CFG.diskDelay;
+    let count = 0;
+    sendStatus("green", "ring", `${fixtureId} disk-save timer running`);
+    console.log(`Disk-save timer started — ${maxLoops}s delay`);
+
+    const timer = setInterval(() => {
+        count++;
+        if (count >= maxLoops) {
+            clearInterval(timer);
+            context.set('timer_diskSave', null);
+            context.set('timer_diskSave_count', 0);
+            onComplete();
+            sendStatus("yellow", "ring", `${fixtureId} disk-save complete — awaiting next HA command`);
+        } else {
+            context.set('timer_diskSave_count', count);
+        }
+    }, 1000);
+
+    context.set('timer_diskSave', timer);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ COLOR CHANNEL RESOLVERS
+// ─────────────────────────────────────────────────────────────────────────────
+//# Each resolver reads: incoming payload → RAM → disk → env default
+//# Returns a plain object with the resolved color values for the mode.
+
+function resolveWhite() {
+    return {
+        white: recall("<<white>>", "<<D_white>>", CFG.defaultOn.white),
+    };
+}
+
+function resolveBrightness(payload) {
+    const prev = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    return {
+        brightness: payload?.brightness || prev,
+        white:      recall("<<white>>", "<<D_white>>", CFG.defaultOn.white),
+    };
+}
+
+function resolveRgb(payload) {
+    const prev = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    return {
+        brightness: payload?.brightness || prev,
+        red:        payload?.color?.r || recall("<<red>>",   "<<D_red>>",   CFG.defaultOn.red),
+        green:      payload?.color?.g || recall("<<green>>", "<<D_green>>", CFG.defaultOn.green),
+        blue:       payload?.color?.b || recall("<<blue>>",  "<<D_blue>>",  CFG.defaultOn.blue),
+    };
+}
+
+function resolveRgbw(payload) {
+    const prev = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    return {
+        brightness: payload?.brightness || prev,
+        red:        payload?.color?.r || recall("<<red>>",   "<<D_red>>",   CFG.defaultOn.red),
+        green:      payload?.color?.g || recall("<<green>>", "<<D_green>>", CFG.defaultOn.green),
+        blue:       payload?.color?.b || recall("<<blue>>",  "<<D_blue>>",  CFG.defaultOn.blue),
+        white:      payload?.color?.w || recall("<<white>>", "<<D_white>>", CFG.defaultOn.white),
+    };
+}
+
+function resolveRgbww(payload) {
+    const prev = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    return {
+        brightness: payload?.brightness  || prev,
+        red:        payload?.color?.r    || recall("<<red>>",       "<<D_red>>",       CFG.defaultOn.red),
+        green:      payload?.color?.g    || recall("<<green>>",     "<<D_green>>",     CFG.defaultOn.green),
+        blue:       payload?.color?.b    || recall("<<blue>>",      "<<D_blue>>",      CFG.defaultOn.blue),
+        white:      payload?.color?.w    || recall("<<white>>",     "<<D_white>>",     CFG.defaultOn.white),
+        warmWhite:  payload?.color?.ww   || recall("<<warmWhite>>", "<<D_warmWhite>>", CFG.defaultOn.warmWhite),
+    };
+}
+
+/**
+ * Convert a mireds value to cold/warm white levels (0–255 each).
+ * minMireds (cool) → coldWhite=255, warmWhite=0
+ * maxMireds (warm) → coldWhite=0,   warmWhite=255
+ *
+ * A square-root curve is applied to the crossfade ratio so the perceptual
+ * shift from cool to warm feels linear rather than clustering at the extremes.
+ * The resulting cold/warm values are then run through scaleToDmx (gamma) when
+ * sent to the controller, so colour temperature transitions are doubly correct.
+ */
+function miredsToWhiteSplit(mireds) {
+    const clamped    = Math.max(CFG.minMireds, Math.min(CFG.maxMireds, mireds));
+    const linearRatio = (clamped - CFG.minMireds) / (CFG.maxMireds - CFG.minMireds);
+    const warmRatio   = Math.sqrt(linearRatio);   //# perceptual correction
+    return {
+        coldWhite: Math.round(255 * (1 - warmRatio)),
+        warmWhite: Math.round(255 * warmRatio),
+    };
+}
+
+function resolveColorTemp(payload) {
+    const prev   = recall("<<bright>>",    "<<D_bright>>",    CFG.defaultOn.brightness);
+    const prevCt = recall("<<colorTemp>>", "<<D_colorTemp>>", CFG.defaultOn.colorTemp);
+    return {
+        brightness: payload?.brightness || prev,
+        colorTemp:  payload?.color_temp || prevCt,   //^ HA sends mireds in color_temp field
+    };
+}
+
+function resolveWhiteMode(payload) {
+    const prev = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    return {
+        brightness: payload?.brightness || prev,
+        white:      recall("<<white>>", "<<D_white>>", CFG.defaultOn.white),
+    };
+}
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ TRANSITION ENGINE
+// ─────────────────────────────────────────────────────────────────────────────
+//# Generic linear interpolation stepper used by all transition handlers.
+//# fromChannels and toChannels are arrays of { ch, val } in the same order.
+//# Each tick sends one DMX update per channel at the interpolated value,
+//# respecting the global rate multiplier from CFG.transitionRateLimit.
+
+/**
+ * Run a linear DMX transition across one or more channels.
+ * @param {Array<{ch:number, from:number, to:number}>} channels - channels to interpolate
+ * @param {number}   durationSecs - total transition time in seconds
+ * @param {Function} onComplete   - called with final channel values when done
+ */
+function runTransition(channels, durationSecs, onComplete) {
+    //# Cancel any active transition before starting a new one
+    const existingTransition = context.get('timer_transition');
+    if (existingTransition) {
+        clearInterval(existingTransition);
+        context.set('timer_transition', null);
+        console.log("Transition timer cancelled by new command.");
+    }
+
+    //# transitionTicksPerSec — how often this node's DMX value advances per second (node-level env)
+    //# transitionRateLimit    — global speed multiplier across ALL subflow nodes (flow-level env)
+    //#
+    //# rateLimit=0.1 → potato/limp mode  (very slow, minimal network load)
+    //# rateLimit=0.5 → half speed
+    //# rateLimit=1   → normal speed      (default, no change to ticksPerSec)
+    //# rateLimit=2   → double speed      (overclocked)
+    //#
+    //# Lower = slower across every node. Higher = faster across every node.
+    //# Use it to manage total network/controller load when many fixtures
+    //# are transitioning simultaneously without touching individual node settings.
+    //#
+    //# Example: ticksPerSec=3, rateLimit=2, duration=2s
+    //#   → effectiveTicks = 3 × 2 = 6 ticks/s   (node running at double speed)
+    //#   → intervalMs     = 1000 / 6 ≈ 167ms     (one DMX update every ~167ms)
+    //#   → totalTicks     = 2 × 6 = 12           (12 unique DMX steps over the run)
+    //#
+    //# Example: ticksPerSec=3, rateLimit=0.5, duration=2s
+    //#   → effectiveTicks = 3 × 0.5 = 1.5 ticks/s
+    //#   → intervalMs     = 1000 / 1.5 ≈ 667ms
+    //#   → totalTicks     = 2 × 1.5 = 3
+
+    const rateLimit       = Math.max(0.1, CFG.transitionRateLimit);                //# floor at 0.1 — prevents division by zero (limp mode minimum)
+    const effectiveTicks  = CFG.transitionTicksPerSec * rateLimit;                 //# actual steps/s this node runs at
+    const intervalMs      = Math.round(1000 / effectiveTicks);                     //# ms between each DMX send
+    const totalTicks      = Math.max(1, Math.round(durationSecs * effectiveTicks));//# total DMX steps over the duration
+    let   tick            = 0;
+
+    console.log(
+        `Transition start — duration:${durationSecs}s  ` +
+        `ticksPerSec:${CFG.transitionTicksPerSec}  rateLimit:${rateLimit}  ` +
+        `effectiveTicks:${effectiveTicks.toFixed(2)}  intervalMs:${intervalMs}  totalTicks:${totalTicks}`
+    );
+    sendStatus("blue", "ring", `${fixtureId} transition running — ${durationSecs}s`);
+
+    const timer = setInterval(() => {
+        tick++;
+        const progress      = Math.min(tick / totalTicks, 1);
+        const currentValues = channels.map(({ ch, from, to }) => ({
+            ch,
+            val: Math.round(from + (to - from) * progress),
+        }));
+        sendDmxChannels(currentValues.map(({ ch, val }) => [ch, val]));
+
+        if (tick >= totalTicks) {
+            clearInterval(timer);
+            context.set('timer_transition', null);
+            sendStatus("yellow", "ring", `${fixtureId} transition complete — awaiting HA command`);
+            console.log("Transition complete.");
+            onComplete(currentValues);
+        }
+    }, intervalMs);
+
+    context.set('timer_transition', timer);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ STATE HANDLERS
+// ─────────────────────────────────────────────────────────────────────────────
+//# Each handler: resolves colors → sends DMX → reports state to HA → saves to RAM → queues disk save.
+//# Keyed by color mode, looked up via COLOR_MODE_HANDLERS[state][colorMode].
+
+const COLOR_MODE_HANDLERS = {
+
+    ON: {
+
+        onoff(payload) {
+            const { white } = resolveWhite();
+            sendDmxChannels([[CFG.ch.white, scaleToDmx(white)]]);
+            sendState({ state: "ON", color: { w: white }, color_mode: "onoff" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<white>>": white });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_white>>": white });
+                console.log(`Disk saved — state:ON  white:${white}`);
+            });
+        },
+
+        brightness(payload) {
+            const { brightness, white } = resolveBrightness(payload);
+            const whiteDmx = scaleToDmx(white, brightness);
+            sendDmxChannels([[CFG.ch.white, whiteDmx]]);
+            sendState({ state: "ON", brightness: whiteDmx, color: { w: white }, color_mode: "brightness" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<white>>": white, "<<bright>>": brightness });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_white>>": white, "<<D_bright>>": brightness });
+                console.log(`Disk saved — state:ON  white:${white}  bright:${brightness}`);
+            });
+        },
+
+        rgb(payload) {
+            const { brightness, red, green, blue } = resolveRgb(payload);
+            sendDmxChannels([
+                [CFG.ch.red,   scaleToDmx(red,   brightness)],
+                [CFG.ch.green, scaleToDmx(green, brightness)],
+                [CFG.ch.blue,  scaleToDmx(blue,  brightness)],
+            ]);
+            sendState({ state: "ON", brightness, color: { r: red, g: green, b: blue }, color_mode: "rgb" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<bright>>": brightness, "<<red>>": red, "<<green>>": green, "<<blue>>": blue });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_bright>>": brightness, "<<D_red>>": red, "<<D_green>>": green, "<<D_blue>>": blue });
+                console.log(`Disk saved — R:${red} G:${green} B:${blue} bright:${brightness}`);
+            });
+        },
+
+        rgbw(payload) {
+            const { brightness, red, green, blue, white } = resolveRgbw(payload);
+            const redDmx   = scaleToDmx(red,   brightness);
+            const greenDmx = scaleToDmx(green, brightness);
+            const blueDmx  = scaleToDmx(blue,  brightness);
+            const whiteDmx = scaleToDmx(white, brightness);
+            sendDmxChannels([
+                [CFG.ch.red,   redDmx],
+                [CFG.ch.green, greenDmx],
+                [CFG.ch.blue,  blueDmx],
+                [CFG.ch.white, whiteDmx],
+            ]);
+            sendState({ state: "ON", brightness, color: { r: red, g: green, b: blue, w: white }, color_mode: "rgbw" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<bright>>": brightness, "<<red>>": red, "<<green>>": green, "<<blue>>": blue, "<<white>>": white });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_bright>>": brightness, "<<D_red>>": red, "<<D_green>>": green, "<<D_blue>>": blue, "<<D_white>>": white });
+                console.log(`Disk saved — R:${red} G:${green} B:${blue} W:${white} bright:${brightness}`);
+            });
+        },
+
+        rgbww(payload) {
+            const { brightness, red, green, blue, white, warmWhite } = resolveRgbww(payload);
+            const redDmx       = scaleToDmx(red,       brightness);
+            const greenDmx     = scaleToDmx(green,     brightness);
+            const blueDmx      = scaleToDmx(blue,      brightness);
+            const whiteDmx     = scaleToDmx(white,     brightness);
+            const warmWhiteDmx = scaleToDmx(warmWhite, brightness);
+            sendDmxChannels([
+                [CFG.ch.red,       redDmx],
+                [CFG.ch.green,     greenDmx],
+                [CFG.ch.blue,      blueDmx],
+                [CFG.ch.white,     whiteDmx],
+                [CFG.ch.warmWhite, warmWhiteDmx],
+            ]);
+            sendState({ state: "ON", brightness, color: { r: red, g: green, b: blue, w: white, ww: warmWhite }, color_mode: "rgbww" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<bright>>": brightness, "<<red>>": red, "<<green>>": green, "<<blue>>": blue, "<<white>>": white, "<<warmWhite>>": warmWhite });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_bright>>": brightness, "<<D_red>>": red, "<<D_green>>": green, "<<D_blue>>": blue, "<<D_white>>": white, "<<D_warmWhite>>": warmWhite });
+                console.log(`Disk saved — R:${red} G:${green} B:${blue} W:${white} WW:${warmWhite} bright:${brightness}`);
+            });
+        },
+
+        color_temp(payload) {
+            //# Map mireds → cold/warm white split, then scale by brightness
+            const { brightness, colorTemp } = resolveColorTemp(payload);
+            const { coldWhite, warmWhite }  = miredsToWhiteSplit(colorTemp);
+            const coldDmx = scaleToDmx(coldWhite, brightness);
+            const warmDmx = scaleToDmx(warmWhite, brightness);
+            sendDmxChannels([
+                [CFG.ch.white,     coldDmx],
+                [CFG.ch.warmWhite, warmDmx],
+            ]);
+            sendState({ state: "ON", brightness, color_temp: colorTemp, color_mode: "color_temp" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<bright>>": brightness, "<<colorTemp>>": colorTemp });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_bright>>": brightness, "<<D_colorTemp>>": colorTemp });
+                console.log(`Disk saved — state:ON  colorTemp:${colorTemp}  bright:${brightness}`);
+            });
+        },
+
+        "rgb,color_temp"(payload) {
+            //# HA uses color_mode field to tell us which sub-mode is active this command
+            if (payload.color_mode === "color_temp") {
+                COLOR_MODE_HANDLERS.ON.color_temp(payload);
+            } else {
+                COLOR_MODE_HANDLERS.ON.rgb(payload);
+            }
+        },
+
+        "rgbw,color_temp"(payload) {
+            if (payload.color_mode === "color_temp") {
+                COLOR_MODE_HANDLERS.ON.color_temp(payload);
+            } else {
+                COLOR_MODE_HANDLERS.ON.rgbw(payload);
+            }
+        },
+
+        "rgbww,color_temp"(payload) {
+            if (payload.color_mode === "color_temp") {
+                COLOR_MODE_HANDLERS.ON.color_temp(payload);
+            } else {
+                COLOR_MODE_HANDLERS.ON.rgbww(payload);
+            }
+        },
+
+        white(payload) {
+            //# "white" mode — brightness only, drives the white channel
+            const { brightness, white } = resolveWhiteMode(payload);
+            const whiteDmx = scaleToDmx(white, brightness);
+            sendDmxChannels([[CFG.ch.white, whiteDmx]]);
+            sendState({ state: "ON", brightness: whiteDmx, color_mode: "white" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<bright>>": brightness, "<<white>>": white });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_bright>>": brightness, "<<D_white>>": white });
+                console.log(`Disk saved — state:ON  white:${white}  bright:${brightness}`);
+            });
+        },
+    },
+
+    OFF: {
+
+        onoff(payload) {
+            const white = CFG.defaultOff.white;
+            sendDmxChannels([[CFG.ch.white, scaleToDmx(white)]]);
+            sendState({ state: "OFF", color: { w: white }, color_mode: "onoff" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF", "<<white>>": white });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" });
+                console.log("Disk saved — state:OFF");
+            });
+        },
+
+        brightness(payload) {
+            const white = CFG.defaultOff.white;
+            sendDmxChannels([[CFG.ch.white, scaleToDmx(white)]]);
+            sendState({ state: "OFF", color: { w: white }, color_mode: "brightness" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" });
+                console.log("Disk saved — state:OFF");
+            });
+        },
+
+        rgb(payload) {
+            const { red, green, blue } = CFG.defaultOff;
+            const redDmx   = scaleToDmx(red);
+            const greenDmx = scaleToDmx(green);
+            const blueDmx  = scaleToDmx(blue);
+            sendDmxChannels([
+                [CFG.ch.red,   redDmx],
+                [CFG.ch.green, greenDmx],
+                [CFG.ch.blue,  blueDmx],
+            ]);
+            sendState({ state: "OFF", color: { r: red, g: green, b: blue }, color_mode: "rgb" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" });
+                console.log("Disk saved — state:OFF");
+            });
+        },
+
+        rgbw(payload) {
+            sendDmxChannels([
+                [CFG.ch.red,   0],
+                [CFG.ch.green, 0],
+                [CFG.ch.blue,  0],
+                [CFG.ch.white, 0],
+            ]);
+            sendState({ state: "OFF", color: { r: 0, g: 0, b: 0, w: 0 }, color_mode: "rgbw" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" });
+                console.log("Disk saved — state:OFF");
+            });
+        },
+
+        rgbww(payload) {
+            sendDmxChannels([
+                [CFG.ch.red,       0],
+                [CFG.ch.green,     0],
+                [CFG.ch.blue,      0],
+                [CFG.ch.white,     0],
+                [CFG.ch.warmWhite, 0],
+            ]);
+            sendState({ state: "OFF", color: { r: 0, g: 0, b: 0, w: 0, ww: 0 }, color_mode: "rgbww" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" });
+                console.log("Disk saved — state:OFF");
+            });
+        },
+
+        color_temp(payload) {
+            sendDmxChannels([
+                [CFG.ch.white,     0],
+                [CFG.ch.warmWhite, 0],
+            ]);
+            sendState({ state: "OFF", color_mode: "color_temp" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" });
+                console.log("Disk saved — state:OFF");
+            });
+        },
+
+        "rgb,color_temp"(payload) {
+            COLOR_MODE_HANDLERS.OFF.rgb(payload);
+            sendDmxChannels([[CFG.ch.white, 0], [CFG.ch.warmWhite, 0]]);
+        },
+
+        "rgbw,color_temp"(payload) {
+            COLOR_MODE_HANDLERS.OFF.rgbw(payload);
+            sendDmxChannels([[CFG.ch.warmWhite, 0]]);
+        },
+
+        "rgbww,color_temp"(payload) {
+            COLOR_MODE_HANDLERS.OFF.rgbww(payload);
+        },
+
+        white(payload) {
+            sendDmxChannels([[CFG.ch.white, 0]]);
+            sendState({ state: "OFF", color_mode: "white" });
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+            startDiskSaveTimer(() => {
+                rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" });
+                console.log("Disk saved — state:OFF");
+            });
+        },
+    },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ TRANSITION HANDLERS
+// ─────────────────────────────────────────────────────────────────────────────
+//# onoff has no meaningful transition — falls through to instant handler.
+//# All other modes interpolate from last-known values to target values
+//# using runTransition(), then save state to RAM/disk on completion.
+
+const TRANSITION_HANDLERS = {
+
+    ON: {
+
+        onoff(payload) {
+            COLOR_MODE_HANDLERS.ON.onoff(payload);
+        },
+
+        brightness(payload) {
+            const { brightness: targetBright, white } = resolveBrightness(payload);
+            const prevBright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+            const channels    = [{ ch: CFG.ch.white, to: scaleToDmx(white, targetBright) }];
+            const bumpFrom    = sendInitialBump(channels);
+
+            console.log(`Transition ON/brightness — from:${prevBright} to:${targetBright}  ${durationSec}s  bump:${bumpFrom}`);
+
+            runTransition([
+                { ch: CFG.ch.white, from: bumpFrom || scaleToDmx(white, prevBright), to: scaleToDmx(white, targetBright) },
+            ], durationSec, () => {
+                sendState({ state: "ON", brightness: scaleToDmx(white, targetBright), color: { w: white }, color_mode: "brightness" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<white>>": white, "<<bright>>": targetBright });
+                startDiskSaveTimer(() => {
+                    rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_white>>": white, "<<D_bright>>": targetBright });
+                    console.log(`Disk saved — state:ON  white:${white}  bright:${targetBright}`);
+                });
+            });
+        },
+
+        rgb(payload) {
+            const { brightness: targetBright, red: toR, green: toG, blue: toB } = resolveRgb(payload);
+            const prevBright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+            const toChannels  = [
+                { ch: CFG.ch.red,   to: scaleToDmx(toR, targetBright) },
+                { ch: CFG.ch.green, to: scaleToDmx(toG, targetBright) },
+                { ch: CFG.ch.blue,  to: scaleToDmx(toB, targetBright) },
+            ];
+            const bumpFrom = sendInitialBump(toChannels);
+            const fromR    = bumpFrom || scaleToDmx(recall("<<red>>",   "<<D_red>>",   CFG.defaultOn.red),   prevBright);
+            const fromG    = bumpFrom || scaleToDmx(recall("<<green>>", "<<D_green>>", CFG.defaultOn.green), prevBright);
+            const fromB    = bumpFrom || scaleToDmx(recall("<<blue>>",  "<<D_blue>>",  CFG.defaultOn.blue),  prevBright);
+
+            runTransition([
+                { ch: CFG.ch.red,   from: fromR, to: scaleToDmx(toR, targetBright) },
+                { ch: CFG.ch.green, from: fromG, to: scaleToDmx(toG, targetBright) },
+                { ch: CFG.ch.blue,  from: fromB, to: scaleToDmx(toB, targetBright) },
+            ], durationSec, () => {
+                sendState({ state: "ON", brightness: targetBright, color: { r: toR, g: toG, b: toB }, color_mode: "rgb" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<bright>>": targetBright, "<<red>>": toR, "<<green>>": toG, "<<blue>>": toB });
+                startDiskSaveTimer(() => {
+                    rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_bright>>": targetBright, "<<D_red>>": toR, "<<D_green>>": toG, "<<D_blue>>": toB });
+                });
+            });
+        },
+
+        rgbw(payload) {
+            const { brightness: targetBright, red: toR, green: toG, blue: toB, white: toW } = resolveRgbw(payload);
+            const prevBright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+            const toChannels  = [
+                { ch: CFG.ch.red,   to: scaleToDmx(toR, targetBright) },
+                { ch: CFG.ch.green, to: scaleToDmx(toG, targetBright) },
+                { ch: CFG.ch.blue,  to: scaleToDmx(toB, targetBright) },
+                { ch: CFG.ch.white, to: scaleToDmx(toW, targetBright) },
+            ];
+            const bumpFrom = sendInitialBump(toChannels);
+            const fromR    = bumpFrom || scaleToDmx(recall("<<red>>",   "<<D_red>>",   CFG.defaultOn.red),   prevBright);
+            const fromG    = bumpFrom || scaleToDmx(recall("<<green>>", "<<D_green>>", CFG.defaultOn.green), prevBright);
+            const fromB    = bumpFrom || scaleToDmx(recall("<<blue>>",  "<<D_blue>>",  CFG.defaultOn.blue),  prevBright);
+            const fromW    = bumpFrom || scaleToDmx(recall("<<white>>", "<<D_white>>", CFG.defaultOn.white), prevBright);
+
+            runTransition([
+                { ch: CFG.ch.red,   from: fromR, to: scaleToDmx(toR, targetBright) },
+                { ch: CFG.ch.green, from: fromG, to: scaleToDmx(toG, targetBright) },
+                { ch: CFG.ch.blue,  from: fromB, to: scaleToDmx(toB, targetBright) },
+                { ch: CFG.ch.white, from: fromW, to: scaleToDmx(toW, targetBright) },
+            ], durationSec, () => {
+                sendState({ state: "ON", brightness: targetBright, color: { r: toR, g: toG, b: toB, w: toW }, color_mode: "rgbw" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<bright>>": targetBright, "<<red>>": toR, "<<green>>": toG, "<<blue>>": toB, "<<white>>": toW });
+                startDiskSaveTimer(() => {
+                    rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_bright>>": targetBright, "<<D_red>>": toR, "<<D_green>>": toG, "<<D_blue>>": toB, "<<D_white>>": toW });
+                });
+            });
+        },
+
+        rgbww(payload) {
+            const { brightness: targetBright, red: toR, green: toG, blue: toB, white: toW, warmWhite: toWW } = resolveRgbww(payload);
+            const prevBright  = recall("<<bright>>",    "<<D_bright>>",    CFG.defaultOn.brightness);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+            const toChannels  = [
+                { ch: CFG.ch.red,       to: scaleToDmx(toR,  targetBright) },
+                { ch: CFG.ch.green,     to: scaleToDmx(toG,  targetBright) },
+                { ch: CFG.ch.blue,      to: scaleToDmx(toB,  targetBright) },
+                { ch: CFG.ch.white,     to: scaleToDmx(toW,  targetBright) },
+                { ch: CFG.ch.warmWhite, to: scaleToDmx(toWW, targetBright) },
+            ];
+            const bumpFrom = sendInitialBump(toChannels);
+            const fromR    = bumpFrom || scaleToDmx(recall("<<red>>",       "<<D_red>>",       CFG.defaultOn.red),       prevBright);
+            const fromG    = bumpFrom || scaleToDmx(recall("<<green>>",     "<<D_green>>",     CFG.defaultOn.green),     prevBright);
+            const fromB    = bumpFrom || scaleToDmx(recall("<<blue>>",      "<<D_blue>>",      CFG.defaultOn.blue),      prevBright);
+            const fromW    = bumpFrom || scaleToDmx(recall("<<white>>",     "<<D_white>>",     CFG.defaultOn.white),     prevBright);
+            const fromWW   = bumpFrom || scaleToDmx(recall("<<warmWhite>>", "<<D_warmWhite>>", CFG.defaultOn.warmWhite), prevBright);
+
+            runTransition([
+                { ch: CFG.ch.red,       from: fromR,  to: scaleToDmx(toR,  targetBright) },
+                { ch: CFG.ch.green,     from: fromG,  to: scaleToDmx(toG,  targetBright) },
+                { ch: CFG.ch.blue,      from: fromB,  to: scaleToDmx(toB,  targetBright) },
+                { ch: CFG.ch.white,     from: fromW,  to: scaleToDmx(toW,  targetBright) },
+                { ch: CFG.ch.warmWhite, from: fromWW, to: scaleToDmx(toWW, targetBright) },
+            ], durationSec, () => {
+                sendState({ state: "ON", brightness: targetBright, color: { r: toR, g: toG, b: toB, w: toW, ww: toWW }, color_mode: "rgbww" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<bright>>": targetBright, "<<red>>": toR, "<<green>>": toG, "<<blue>>": toB, "<<white>>": toW, "<<warmWhite>>": toWW });
+                startDiskSaveTimer(() => {
+                    rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_bright>>": targetBright, "<<D_red>>": toR, "<<D_green>>": toG, "<<D_blue>>": toB, "<<D_white>>": toW, "<<D_warmWhite>>": toWW });
+                });
+            });
+        },
+
+        color_temp(payload) {
+            const { brightness: targetBright, colorTemp: targetCt } = resolveColorTemp(payload);
+            const prevBright = recall("<<bright>>",    "<<D_bright>>",    CFG.defaultOn.brightness);
+            const prevCt     = recall("<<colorTemp>>", "<<D_colorTemp>>", CFG.defaultOn.colorTemp);
+            const { coldWhite: fromCold, warmWhite: fromWarm } = miredsToWhiteSplit(prevCt);
+            const { coldWhite: toCold,  warmWhite: toWarm  }  = miredsToWhiteSplit(targetCt);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+            const toChannels  = [
+                { ch: CFG.ch.white,     to: scaleToDmx(toCold, targetBright) },
+                { ch: CFG.ch.warmWhite, to: scaleToDmx(toWarm, targetBright) },
+            ];
+            const bumpFrom = sendInitialBump(toChannels);
+
+            runTransition([
+                { ch: CFG.ch.white,     from: bumpFrom || scaleToDmx(fromCold, prevBright), to: scaleToDmx(toCold, targetBright) },
+                { ch: CFG.ch.warmWhite, from: bumpFrom || scaleToDmx(fromWarm, prevBright), to: scaleToDmx(toWarm, targetBright) },
+            ], durationSec, () => {
+                sendState({ state: "ON", brightness: targetBright, color_temp: targetCt, color_mode: "color_temp" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<bright>>": targetBright, "<<colorTemp>>": targetCt });
+                startDiskSaveTimer(() => {
+                    rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_bright>>": targetBright, "<<D_colorTemp>>": targetCt });
+                });
+            });
+        },
+
+        "rgb,color_temp"(payload) {
+            if (payload.color_mode === "color_temp") {
+                TRANSITION_HANDLERS.ON.color_temp(payload);
+            } else {
+                TRANSITION_HANDLERS.ON.rgb(payload);
+            }
+        },
+
+        "rgbw,color_temp"(payload) {
+            if (payload.color_mode === "color_temp") {
+                TRANSITION_HANDLERS.ON.color_temp(payload);
+            } else {
+                TRANSITION_HANDLERS.ON.rgbw(payload);
+            }
+        },
+
+        "rgbww,color_temp"(payload) {
+            if (payload.color_mode === "color_temp") {
+                TRANSITION_HANDLERS.ON.color_temp(payload);
+            } else {
+                TRANSITION_HANDLERS.ON.rgbww(payload);
+            }
+        },
+
+        white(payload) {
+            const { brightness: targetBright, white } = resolveWhiteMode(payload);
+            const prevBright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+            const toChannels  = [{ ch: CFG.ch.white, to: scaleToDmx(white, targetBright) }];
+            const bumpFrom    = sendInitialBump(toChannels);
+
+            runTransition([
+                { ch: CFG.ch.white, from: bumpFrom || scaleToDmx(white, prevBright), to: scaleToDmx(white, targetBright) },
+            ], durationSec, () => {
+                sendState({ state: "ON", brightness: scaleToDmx(white, targetBright), color_mode: "white" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "ON", "<<bright>>": targetBright, "<<white>>": white });
+                startDiskSaveTimer(() => {
+                    rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "ON", "<<D_bright>>": targetBright, "<<D_white>>": white });
+                });
+            });
+        },
+    },
+
+    OFF: {
+
+        onoff(payload) {
+            COLOR_MODE_HANDLERS.OFF.onoff(payload);
+        },
+
+        //# Fade to zero from current brightness
+        brightness(payload) {
+            const white       = recall("<<white>>", "<<D_white>>", CFG.defaultOn.white);
+            const prevBright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+
+            runTransition([
+                { ch: CFG.ch.white, from: scaleToDmx(white, prevBright), to: 0 },
+            ], durationSec, () => {
+                sendState({ state: "OFF", color_mode: "brightness" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+                startDiskSaveTimer(() => { rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" }); });
+            });
+        },
+
+        rgb(payload) {
+            const prevBright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+            const fromR       = scaleToDmx(recall("<<red>>",   "<<D_red>>",   CFG.defaultOn.red),   prevBright);
+            const fromG       = scaleToDmx(recall("<<green>>", "<<D_green>>", CFG.defaultOn.green), prevBright);
+            const fromB       = scaleToDmx(recall("<<blue>>",  "<<D_blue>>",  CFG.defaultOn.blue),  prevBright);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+
+            runTransition([
+                { ch: CFG.ch.red,   from: fromR, to: 0 },
+                { ch: CFG.ch.green, from: fromG, to: 0 },
+                { ch: CFG.ch.blue,  from: fromB, to: 0 },
+            ], durationSec, () => {
+                sendState({ state: "OFF", color: { r: 0, g: 0, b: 0 }, color_mode: "rgb" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+                startDiskSaveTimer(() => { rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" }); });
+            });
+        },
+
+        rgbw(payload) {
+            const prevBright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+            const fromR       = scaleToDmx(recall("<<red>>",   "<<D_red>>",   CFG.defaultOn.red),   prevBright);
+            const fromG       = scaleToDmx(recall("<<green>>", "<<D_green>>", CFG.defaultOn.green), prevBright);
+            const fromB       = scaleToDmx(recall("<<blue>>",  "<<D_blue>>",  CFG.defaultOn.blue),  prevBright);
+            const fromW       = scaleToDmx(recall("<<white>>", "<<D_white>>", CFG.defaultOn.white), prevBright);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+
+            runTransition([
+                { ch: CFG.ch.red,   from: fromR, to: 0 },
+                { ch: CFG.ch.green, from: fromG, to: 0 },
+                { ch: CFG.ch.blue,  from: fromB, to: 0 },
+                { ch: CFG.ch.white, from: fromW, to: 0 },
+            ], durationSec, () => {
+                sendState({ state: "OFF", color: { r: 0, g: 0, b: 0, w: 0 }, color_mode: "rgbw" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+                startDiskSaveTimer(() => { rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" }); });
+            });
+        },
+
+        rgbww(payload) {
+            const prevBright  = recall("<<bright>>",    "<<D_bright>>",    CFG.defaultOn.brightness);
+            const fromR       = scaleToDmx(recall("<<red>>",       "<<D_red>>",       CFG.defaultOn.red),       prevBright);
+            const fromG       = scaleToDmx(recall("<<green>>",     "<<D_green>>",     CFG.defaultOn.green),     prevBright);
+            const fromB       = scaleToDmx(recall("<<blue>>",      "<<D_blue>>",      CFG.defaultOn.blue),      prevBright);
+            const fromW       = scaleToDmx(recall("<<white>>",     "<<D_white>>",     CFG.defaultOn.white),     prevBright);
+            const fromWW      = scaleToDmx(recall("<<warmWhite>>", "<<D_warmWhite>>", CFG.defaultOn.warmWhite), prevBright);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+
+            runTransition([
+                { ch: CFG.ch.red,       from: fromR,  to: 0 },
+                { ch: CFG.ch.green,     from: fromG,  to: 0 },
+                { ch: CFG.ch.blue,      from: fromB,  to: 0 },
+                { ch: CFG.ch.white,     from: fromW,  to: 0 },
+                { ch: CFG.ch.warmWhite, from: fromWW, to: 0 },
+            ], durationSec, () => {
+                sendState({ state: "OFF", color: { r: 0, g: 0, b: 0, w: 0, ww: 0 }, color_mode: "rgbww" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+                startDiskSaveTimer(() => { rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" }); });
+            });
+        },
+
+        color_temp(payload) {
+            const prevBright  = recall("<<bright>>",    "<<D_bright>>",    CFG.defaultOn.brightness);
+            const prevCt      = recall("<<colorTemp>>", "<<D_colorTemp>>", CFG.defaultOn.colorTemp);
+            const { coldWhite, warmWhite } = miredsToWhiteSplit(prevCt);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+
+            runTransition([
+                { ch: CFG.ch.white,     from: scaleToDmx(coldWhite, prevBright), to: 0 },
+                { ch: CFG.ch.warmWhite, from: scaleToDmx(warmWhite, prevBright), to: 0 },
+            ], durationSec, () => {
+                sendState({ state: "OFF", color_mode: "color_temp" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+                startDiskSaveTimer(() => { rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" }); });
+            });
+        },
+
+        "rgb,color_temp"(payload) {
+            TRANSITION_HANDLERS.OFF.rgb(payload);
+        },
+
+        "rgbw,color_temp"(payload) {
+            TRANSITION_HANDLERS.OFF.rgbw(payload);
+        },
+
+        "rgbww,color_temp"(payload) {
+            TRANSITION_HANDLERS.OFF.rgbww(payload);
+        },
+
+        white(payload) {
+            const white       = recall("<<white>>", "<<D_white>>", CFG.defaultOn.white);
+            const prevBright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+            const durationSec = payload.transition || CFG.transitionDefaultSecs;
+
+            runTransition([
+                { ch: CFG.ch.white, from: scaleToDmx(white, prevBright), to: 0 },
+            ], durationSec, () => {
+                sendState({ state: "OFF", color_mode: "white" });
+                rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+                startDiskSaveTimer(() => { rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" }); });
+            });
+        },
+    },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ EFFECTS
+// ─────────────────────────────────────────────────────────────────────────────
+//# All effects share the same lifecycle:
+//#   1. stopEffect()       — cancel any running effect timer
+//#   2. run the effect loop via setInterval stored in context('timer_effect')
+//#   3. restoreAfterEffect() — on natural end, send fixture back to last known state
+//#
+//# Effects run indefinitely (durationSecs = 0) until the next HA command cancels them.
+//# A non-zero durationSecs makes the effect self-terminate.
+//#
+//# Color helpers used throughout:
+//#   hsvToRgb(h, s, v)  — h:0–360, s/v:0–1, returns [r,g,b] 0–255
+//#   sendRgb(r,g,b,bright) — scales through gamma and sends R/G/B channels
+//#   sendWhites(cold,warm,bright) — scales through gamma and sends white channels
+
+/** Cancel any currently running effect timer. */
+function stopEffect() {
+    const t = context.get('timer_effect');
+    if (t) {
+        clearInterval(t);
+        context.set('timer_effect', null);
+    }
+}
+
+/**
+ * Restore fixture to its last known RAM state after an effect ends naturally.
+ * Reads current RAM values and re-sends the appropriate DMX channels.
+ */
+function restoreAfterEffect() {
+    const state  = recall("<<FIXTURE_RAM_Memory_State>>", "<<FIXTURE_Disk_Memory_State>>", CFG.defaultState);
+    const bright = state === "ON" ? recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness) : 0;
+    const r = recall("<<red>>",       "<<D_red>>",       CFG.defaultOn.red);
+    const g = recall("<<green>>",     "<<D_green>>",     CFG.defaultOn.green);
+    const b = recall("<<blue>>",      "<<D_blue>>",      CFG.defaultOn.blue);
+    const w = recall("<<white>>",     "<<D_white>>",     CFG.defaultOn.white);
+    const ww = recall("<<warmWhite>>","<<D_warmWhite>>",  CFG.defaultOn.warmWhite);
+    sendDmxChannels([
+        [CFG.ch.red,       scaleToDmx(r,  bright)],
+        [CFG.ch.green,     scaleToDmx(g,  bright)],
+        [CFG.ch.blue,      scaleToDmx(b,  bright)],
+        [CFG.ch.white,     scaleToDmx(w,  bright)],
+        [CFG.ch.warmWhite, scaleToDmx(ww, bright)],
+    ]);
+    sendStatus("yellow", "ring", `${fixtureId} effect complete — awaiting HA command`);
+}
+
+/**
+ * Convert HSV to RGB.
+ * @param {number} h - hue 0–360
+ * @param {number} s - saturation 0–1
+ * @param {number} v - value 0–1
+ * @returns {[number, number, number]} [r, g, b] each 0–255
+ */
+function hsvToRgb(h, s, v) {
+    const i = Math.floor(h / 60) % 6;
+    const f = (h / 60) - Math.floor(h / 60);
+    const p = Math.round(255 * v * (1 - s));
+    const q = Math.round(255 * v * (1 - f * s));
+    const t = Math.round(255 * v * (1 - (1 - f) * s));
+    const V = Math.round(255 * v);
+    return [[V,t,p],[q,V,p],[p,V,t],[p,q,V],[t,p,V],[V,p,q]][i];
+}
+
+/** Send R/G/B channels scaled through brightness and gamma. */
+function sendRgb(r, g, b, bright) {
+    sendDmxChannels([
+        [CFG.ch.red,   scaleToDmx(r, bright)],
+        [CFG.ch.green, scaleToDmx(g, bright)],
+        [CFG.ch.blue,  scaleToDmx(b, bright)],
+    ]);
+}
+
+/** Send cold/warm white channels scaled through brightness and gamma. */
+function sendWhites(cold, warm, bright) {
+    sendDmxChannels([
+        [CFG.ch.white,     scaleToDmx(cold, bright)],
+        [CFG.ch.warmWhite, scaleToDmx(warm, bright)],
+    ]);
+}
+
+/**
+ * Send an instant brightness bump on all active channels before a transition begins.
+ * Only fires when the fixture is currently OFF (prevBright === 0 or state is OFF).
+ * This gives the room immediate usable light even during a slow fade-in.
+ *
+ * @param {Array<{ch:number, to:number}>} channels - the transition target channels
+ * @returns {number} the bump DMX value used as the new `from` for the transition,
+ *                   or 0 if the fixture was already ON (no bump needed).
+ */
+function sendInitialBump(channels) {
+    const prevState = recall("<<FIXTURE_RAM_Memory_State>>", "<<FIXTURE_Disk_Memory_State>>", CFG.defaultState);
+
+    //# Only bump when coming from OFF — brightness=0 while ON is not a real-world state
+    if (prevState !== "OFF") return 0;
+
+    const bumpValue = CFG.defaultOn.initialBump;
+    if (!bumpValue || bumpValue <= 0) return 0;   //# disabled — env set to 0
+
+    //# Scale bump proportionally to each channel's target so colour balance is preserved
+    const bumpDmx = scaleToDmx(bumpValue);
+    channels.forEach(({ ch, to }) => {
+        if (to > 0) {
+            //# Bump proportional to how bright this channel will end up
+            const channelBump = Math.min(bumpDmx, to);
+            sendDmxChannels([[ch, channelBump]]);
+        }
+    });
+
+    console.log(`Initial bump sent — bumpValue:${bumpValue}  bumpDmx:${bumpDmx}`);
+    return bumpDmx;
+}
+
+/** Start an effect interval, storing the timer in context. */
+function startEffect(label, intervalMs, tickFn, durationSecs = 0) {
+    stopEffect();
+    sendStatus("blue", "dot", `${fixtureId} effect: ${label}`);
+    const endTime = durationSecs > 0 ? Date.now() + durationSecs * 1000 : Infinity;
+    const timer = setInterval(() => {
+        tickFn();
+        if (Date.now() >= endTime) {
+            stopEffect();
+            restoreAfterEffect();
+        }
+    }, intervalMs);
+    context.set('timer_effect', timer);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ EFFECT IMPLEMENTATIONS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * FLASH — toggle on/off at 2 Hz.
+ * Works on any color mode; uses last-known white/RGB values.
+ */
+function effectFlash(durationSecs) {
+    const bright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    const w       = recall("<<white>>",  "<<D_white>>",  CFG.defaultOn.white);
+    const onW     = scaleToDmx(w, bright);
+    const r = recall("<<red>>",   "<<D_red>>",   CFG.defaultOn.red);
+    const g = recall("<<green>>", "<<D_green>>", CFG.defaultOn.green);
+    const b = recall("<<blue>>",  "<<D_blue>>",  CFG.defaultOn.blue);
+    let isOn = false;
+    startEffect("Flash", 500, () => {
+        isOn = !isOn;
+        const v = isOn ? bright : 0;
+        sendDmxChannels([
+            [CFG.ch.white, isOn ? onW : 0],
+            [CFG.ch.red,   scaleToDmx(r, v)],
+            [CFG.ch.green, scaleToDmx(g, v)],
+            [CFG.ch.blue,  scaleToDmx(b, v)],
+        ]);
+    }, durationSecs);
+}
+
+/**
+ * STROBE — rapid on/off, up to ~20 Hz.
+ * Harsher than flash; useful for DJ/stage looks.
+ * Rate is configurable 1–20 Hz via strobeHz param (default 10).
+ */
+function effectStrobe(durationSecs, strobeHz = 10) {
+    const bright = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    const w      = scaleToDmx(recall("<<white>>", "<<D_white>>", CFG.defaultOn.white), bright);
+    const r      = recall("<<red>>",   "<<D_red>>",   CFG.defaultOn.red);
+    const g      = recall("<<green>>", "<<D_green>>", CFG.defaultOn.green);
+    const b      = recall("<<blue>>",  "<<D_blue>>",  CFG.defaultOn.blue);
+    const hz     = Math.min(20, Math.max(1, strobeHz));
+    let isOn = false;
+    startEffect("Strobe", Math.round(1000 / (hz * 2)), () => {
+        isOn = !isOn;
+        const v = isOn ? bright : 0;
+        sendDmxChannels([
+            [CFG.ch.white, isOn ? w : 0],
+            [CFG.ch.red,   scaleToDmx(r, v)],
+            [CFG.ch.green, scaleToDmx(g, v)],
+            [CFG.ch.blue,  scaleToDmx(b, v)],
+        ]);
+    }, durationSecs);
+}
+
+/**
+ * RAINBOW — full HSV hue cycle. Full cycle ~3 seconds.
+ * RGB fixtures only.
+ */
+function effectRainbow(durationSecs) {
+    const bright   = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    const stepDeg  = 360 / (CFG.transitionTicksPerSec * 3);
+    let   hue      = 0;
+    startEffect("Rainbow", Math.round(1000 / CFG.transitionTicksPerSec), () => {
+        const [r, g, b] = hsvToRgb(hue, 1, 1);
+        sendRgb(r, g, b, bright);
+        hue = (hue + stepDeg) % 360;
+    }, durationSecs);
+}
+
+/**
+ * RAINBOW RGBW — full hue cycle with white channel modulation for RGBW fixtures.
+ * White is driven inversely to the dominant RGB channel so it fills the gaps
+ * between primaries with a warm ambient lift, giving a fuller colour spectrum
+ * than RGB rainbow alone. White = 0 at pure primaries, peaks softly between them.
+ */
+function effectRainbowRgbw(durationSecs) {
+    const bright   = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    const stepDeg  = 360 / (CFG.transitionTicksPerSec * 3);
+    let   hue      = 0;
+    startEffect("Rainbow RGBW", Math.round(1000 / CFG.transitionTicksPerSec), () => {
+        const [r, g, b] = hsvToRgb(hue, 1, 1);
+        //# White inversely proportional to the dominant channel — warm glow between primaries
+        const dominant = Math.max(r, g, b);
+        const white    = Math.round(60 * (1 - dominant / 255));
+        sendRgb(r, g, b, bright);
+        sendDmxChannels([[CFG.ch.white, scaleToDmx(white, bright)]]);
+        hue = (hue + stepDeg) % 360;
+    }, durationSecs);
+}
+
+/**
+ * FIRE — warm flickering between deep orange and bright yellow-white.
+ * Uses white + warm white channels if available, falls back to RGB.
+ * Random intensity bursts with a warm bias.
+ */
+function effectFire(durationSecs) {
+    const bright = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    startEffect("Fire", 60, () => {
+        //# Flicker: base warm glow + random burst of heat
+        const flicker  = 0.6 + Math.random() * 0.4;          //# 60–100% intensity
+        const heat     = 0.7 + Math.random() * 0.3;           //# warm bias 70–100%
+        const r = Math.round(255 * flicker);
+        const g = Math.round(80  * flicker * (1 - heat * 0.4));
+        const b = 0;
+        sendRgb(r, g, b, bright);
+        //# Also drive warm white if the fixture has it
+        sendWhites(Math.round(80 * flicker * (1 - heat)), Math.round(255 * flicker * heat), bright);
+    }, durationSecs);
+}
+
+/**
+ * FLICKER — soft candlelight. Gentler and slower than fire.
+ * Stays in the warm amber zone with subtle random dips.
+ */
+function effectFlicker(durationSecs) {
+    const bright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    let   phase   = 0;
+    startEffect("Flicker", 80, () => {
+        //# Slow sine wave base with a small random offset for organic feel
+        phase += 0.15 + Math.random() * 0.05;
+        const sineBase  = 0.75 + 0.15 * Math.sin(phase);
+        const noise     = (Math.random() - 0.5) * 0.12;
+        const intensity = Math.min(1, Math.max(0.4, sineBase + noise));
+        const r = Math.round(255 * intensity);
+        const g = Math.round(100 * intensity * 0.7);
+        const b = 0;
+        sendRgb(r, g, b, bright);
+        sendWhites(Math.round(40 * intensity), Math.round(220 * intensity), bright);
+    }, durationSecs);
+}
+
+/**
+ * TWINKLE — random channels randomly spike to full brightness briefly then fade.
+ * Simulates a starfield or twinkling fairy lights.
+ * Works best on RGB or RGBW fixtures.
+ */
+function effectTwinkle(durationSecs) {
+    const bright   = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    const CHANNELS = [CFG.ch.red, CFG.ch.green, CFG.ch.blue, CFG.ch.white];
+    //# Each channel has an independent brightness level that decays each tick
+    const levels   = [0, 0, 0, 0];
+    startEffect("Twinkle", 60, () => {
+        //# Randomly trigger a sparkle on one channel
+        if (Math.random() < 0.3) {
+            const idx = Math.floor(Math.random() * CHANNELS.length);
+            levels[idx] = 255;
+        }
+        //# Decay all channels
+        for (let i = 0; i < levels.length; i++) {
+            levels[i] = Math.max(0, levels[i] - 20 - Math.round(Math.random() * 20));
+            sendDmxChannels([[CHANNELS[i], scaleToDmx(levels[i], bright)]]);
+        }
+    }, durationSecs);
+}
+
+/**
+ * COLOR CHASE — one colour at a time, cycling R → G → B → W.
+ * Each colour holds for ~1 second then crossfades to the next.
+ */
+function effectColorChase(durationSecs) {
+    const bright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    const COLORS  = [
+        [255, 0,   0,   0],   //# Red
+        [0,   255, 0,   0],   //# Green
+        [0,   0,   255, 0],   //# Blue
+        [0,   0,   0,   255], //# White
+    ];
+    let   colorIdx = 0;
+    let   step     = 0;
+    const stepsPerColor = CFG.transitionTicksPerSec; //# ~1 second per colour
+    startEffect("Color Chase", Math.round(1000 / CFG.transitionTicksPerSec), () => {
+        const from = COLORS[colorIdx % COLORS.length];
+        const to   = COLORS[(colorIdx + 1) % COLORS.length];
+        const t    = step / stepsPerColor;
+        const cur  = from.map((f, i) => Math.round(f + (to[i] - f) * t));
+        sendDmxChannels([
+            [CFG.ch.red,   scaleToDmx(cur[0], bright)],
+            [CFG.ch.green, scaleToDmx(cur[1], bright)],
+            [CFG.ch.blue,  scaleToDmx(cur[2], bright)],
+            [CFG.ch.white, scaleToDmx(cur[3], bright)],
+        ]);
+        step++;
+        if (step > stepsPerColor) { step = 0; colorIdx++; }
+    }, durationSecs);
+}
+
+/**
+ * SCAN — brightness ramps up on one channel then another, like a moving spotlight.
+ * Cycles R → G → B → W, each doing a full 0→255→0 sweep.
+ */
+function effectScan(durationSecs) {
+    const bright   = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    const CHANNELS = [CFG.ch.red, CFG.ch.green, CFG.ch.blue, CFG.ch.white];
+    let   chIdx    = 0;
+    let   phase    = 0;                         //# 0 → 2π = one sweep
+    const phaseStep = Math.PI / (CFG.transitionTicksPerSec * 1.5);
+    startEffect("Scan", Math.round(1000 / CFG.transitionTicksPerSec), () => {
+        const val = Math.round(255 * Math.sin(phase));
+        //# Zero all channels then set the active one
+        CHANNELS.forEach(ch => sendDmxChannels([[ch, 0]]));
+        sendDmxChannels([[CHANNELS[chIdx], scaleToDmx(val, bright)]]);
+        phase += phaseStep;
+        if (phase >= Math.PI) { phase = 0; chIdx = (chIdx + 1) % CHANNELS.length; }
+    }, durationSecs);
+}
+
+/**
+ * RANDOM — each tick picks a random fully-saturated hue.
+ * Chaotic, best at lower tick rates.
+ */
+function effectRandom(durationSecs) {
+    const bright = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    startEffect("Random", 200, () => {
+        const [r, g, b] = hsvToRgb(Math.random() * 360, 1, 1);
+        sendRgb(r, g, b, bright);
+    }, durationSecs);
+}
+
+/**
+ * POLICE — alternating red/blue strobe at ~2 Hz per side.
+ * Each side flashes twice before switching (like real emergency lights).
+ */
+function effectPolice(durationSecs) {
+    const bright = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    let   phase  = 0;   //# 0–7: 0–3 = red side, 4–7 = blue side
+    startEffect("Police", 120, () => {
+        const isRed  = phase < 4;
+        const isFlashOn = phase % 2 === 0;
+        const r = isRed  && isFlashOn ? 255 : 0;
+        const b = !isRed && isFlashOn ? 255 : 0;
+        sendRgb(r, 0, b, bright);
+        phase = (phase + 1) % 8;
+    }, durationSecs);
+}
+
+/**
+ * CHRISTMAS — alternating slow red/green pulses with a brief white sparkle.
+ */
+function effectChristmas(durationSecs) {
+    const bright = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    let   tick   = 0;
+    const PERIOD = CFG.transitionTicksPerSec * 2; //# 2 second full cycle
+    startEffect("Christmas", Math.round(1000 / CFG.transitionTicksPerSec), () => {
+        const t = (tick % PERIOD) / PERIOD;          //# 0→1 per cycle
+        //# First half: fade red in/out; second half: fade green in/out
+        const r = t < 0.5  ? Math.round(255 * Math.sin(t * Math.PI * 2)) : 0;
+        const g = t >= 0.5 ? Math.round(255 * Math.sin((t - 0.5) * Math.PI * 2)) : 0;
+        //# Brief white sparkle near the crossover points
+        const w = (t > 0.45 && t < 0.55) ? Math.round(180 * Math.sin((t - 0.45) * Math.PI / 0.1)) : 0;
+        sendDmxChannels([
+            [CFG.ch.red,   scaleToDmx(r, bright)],
+            [CFG.ch.green, scaleToDmx(g, bright)],
+            [CFG.ch.blue,  0],
+            [CFG.ch.white, scaleToDmx(w, bright)],
+        ]);
+        tick++;
+    }, durationSecs);
+}
+
+/**
+ * HALLOWEEN — slow alternating orange/purple pulses.
+ */
+function effectHalloween(durationSecs) {
+    const bright = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    let   tick   = 0;
+    const PERIOD = CFG.transitionTicksPerSec * 3;
+    startEffect("Halloween", Math.round(1000 / CFG.transitionTicksPerSec), () => {
+        const t = (tick % PERIOD) / PERIOD;
+        //# Orange (255, 80, 0) ↔ Purple (128, 0, 255)
+        const blend  = 0.5 + 0.5 * Math.sin(t * Math.PI * 2);
+        const r = Math.round(255 * blend + 128 * (1 - blend));
+        const g = Math.round(80  * blend);
+        const b = Math.round(255 * (1 - blend));
+        sendRgb(r, g, b, bright);
+        tick++;
+    }, durationSecs);
+}
+
+/**
+ * CALAVERAS (Day of the Dead) — cycling magenta → cyan → yellow pulses.
+ */
+function effectCalaveras(durationSecs) {
+    const bright  = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    const PALETTE = [
+        [255, 0,   255],  //# Magenta
+        [0,   255, 255],  //# Cyan
+        [255, 255, 0],    //# Yellow
+        [255, 100, 200],  //# Hot pink
+    ];
+    let   idx  = 0;
+    let   step = 0;
+    const stepsPerColor = CFG.transitionTicksPerSec * 2;
+    startEffect("Calaveras", Math.round(1000 / CFG.transitionTicksPerSec), () => {
+        const from = PALETTE[idx % PALETTE.length];
+        const to   = PALETTE[(idx + 1) % PALETTE.length];
+        const t    = step / stepsPerColor;
+        const [r, g, b] = from.map((f, i) => Math.round(f + (to[i] - f) * t));
+        sendRgb(r, g, b, bright);
+        step++;
+        if (step > stepsPerColor) { step = 0; idx++; }
+    }, durationSecs);
+}
+
+/**
+ * PARTY — rapid random hue pops, high energy.
+ */
+function effectParty(durationSecs) {
+    const bright = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    startEffect("Party", 80, () => {
+        const [r, g, b] = hsvToRgb(Math.random() * 360, 1, 1);
+        sendRgb(r, g, b, bright);
+    }, durationSecs);
+}
+
+/**
+ * RELAXING — very slow warm white breathing. A single breath cycle ~8 seconds.
+ */
+function effectRelaxing(durationSecs) {
+    const bright   = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    let   phase    = 0;
+    const phaseStep = (2 * Math.PI) / (CFG.transitionTicksPerSec * 8); //# 8s per breath
+    startEffect("Relaxing", Math.round(1000 / CFG.transitionTicksPerSec), () => {
+        //# Sine wave from 20% to 100% brightness — never fully off
+        const intensity = 0.2 + 0.8 * (0.5 + 0.5 * Math.sin(phase));
+        const warm = Math.round(255 * intensity);
+        const cold = Math.round(80  * intensity);
+        sendWhites(cold, warm, bright);
+        //# Soft warm RGB glow alongside
+        sendRgb(Math.round(220 * intensity), Math.round(120 * intensity), Math.round(40 * intensity), bright);
+        phase += phaseStep;
+    }, durationSecs);
+}
+
+/**
+ * TEMPERATURE TRANSITION — slow drift from cool white to warm white and back.
+ * Full cycle ~60 seconds by default. Great for morning/evening ambience.
+ */
+function effectTemperatureTransition(durationSecs) {
+    const bright    = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    let   phase     = 0;
+    const phaseStep = (2 * Math.PI) / (CFG.transitionTicksPerSec * 60);
+    startEffect("Temp Transition", Math.round(1000 / CFG.transitionTicksPerSec), () => {
+        //# 0 = full cool, 1 = full warm; sine wave between them
+        const warmRatio = 0.5 + 0.5 * Math.sin(phase);
+        const cold = Math.round(255 * (1 - warmRatio));
+        const warm = Math.round(255 * warmRatio);
+        sendWhites(cold, warm, bright);
+        phase += phaseStep;
+    }, durationSecs);
+}
+
+/**
+ * SLEEP TRANSITION — slowly dims from current brightness to zero over durationSecs.
+ * Defaults to 30 minutes if no duration given. Does not loop — ends once dark.
+ */
+function effectSleepTransition(durationSecs = 1800) {
+    const startBright = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    const w  = recall("<<white>>",     "<<D_white>>",     CFG.defaultOn.white);
+    const ww = recall("<<warmWhite>>", "<<D_warmWhite>>", CFG.defaultOn.warmWhite);
+    const r  = recall("<<red>>",   "<<D_red>>",   CFG.defaultOn.red);
+    const g  = recall("<<green>>", "<<D_green>>", CFG.defaultOn.green);
+    const b  = recall("<<blue>>",  "<<D_blue>>",  CFG.defaultOn.blue);
+    const totalTicks = durationSecs * CFG.transitionTicksPerSec;
+    let   tick = 0;
+    //# Force a fixed duration — sleep transition should always self-terminate
+    stopEffect();
+    sendStatus("blue", "dot", `Sleep transition — ${Math.round(durationSecs / 60)} min`);
+    const timer = setInterval(() => {
+        tick++;
+        const progress = Math.min(1, tick / totalTicks);
+        //# Ease out: square root gives a gentle initial fade then holds longer at low end
+        const bright = Math.round(startBright * (1 - Math.sqrt(progress)));
+        sendDmxChannels([
+            [CFG.ch.white,     scaleToDmx(w,  bright)],
+            [CFG.ch.warmWhite, scaleToDmx(ww, bright)],
+            [CFG.ch.red,       scaleToDmx(r,  bright)],
+            [CFG.ch.green,     scaleToDmx(g,  bright)],
+            [CFG.ch.blue,      scaleToDmx(b,  bright)],
+        ]);
+        if (tick >= totalTicks) {
+            clearInterval(timer);
+            context.set('timer_effect', null);
+            rememberRam({ "<<FIXTURE_RAM_Memory_State>>": "OFF" });
+            startDiskSaveTimer(() => { rememberDisk({ "<<FIXTURE_Disk_Memory_State>>": "OFF" }); });
+            sendStatus("yellow", "ring", "Sleep transition complete — lights off");
+        }
+    }, Math.round(1000 / CFG.transitionTicksPerSec));
+    context.set('timer_effect', timer);
+}
+
+/**
+ * FIREWORKS — random bright colour bursts that decay quickly, on a dark background.
+ * Multiple simultaneous "shells" each with an independent decay.
+ */
+function effectFireworks(durationSecs) {
+    const bright   = recall("<<bright>>", "<<D_bright>>", CFG.defaultOn.brightness);
+    const SHELLS   = 3;
+    //# Each shell: { h: hue, decay: 0–1 }
+    const shells   = Array.from({ length: SHELLS }, () => ({ h: Math.random() * 360, level: 0 }));
+    startEffect("Fireworks", 40, () => {
+        //# Randomly launch a new shell
+        if (Math.random() < 0.05) {
+            const s = shells[Math.floor(Math.random() * SHELLS)];
+            s.h     = Math.random() * 360;
+            s.level = 1;
+        }
+        //# Mix all shells and decay
+        let rSum = 0, gSum = 0, bSum = 0;
+        shells.forEach(s => {
+            if (s.level > 0) {
+                const [r, g, b] = hsvToRgb(s.h, 1, s.level);
+                rSum += r; gSum += g; bSum += b;
+                s.level = Math.max(0, s.level - 0.04 - Math.random() * 0.03);
+            }
+        });
+        sendRgb(Math.min(255, rSum), Math.min(255, gSum), Math.min(255, bSum), bright);
+    }, durationSecs);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ EFFECT DISPATCH
+// ─────────────────────────────────────────────────────────────────────────────
+//# Maps the HA effect name string (from payload.effect / CFG.effectsList)
+//# to the implementation function. Add new effects here and to CFG.effectsList.
+
+const EFFECT_MAP = {
+    //# "none" — stop any running effect and restore last known state gracefully
+    "none":                     () => { stopEffect(); restoreAfterEffect(); },
+    "flash_short":              () => effectFlash(CFG.flashShort),
+    "flash_long":               () => effectFlash(CFG.flashLong),
+    "strobe":                   () => effectStrobe(0),
+    "rainbow":                  () => effectRainbow(0),
+    "rainbow_rgbw":             () => effectRainbowRgbw(0),
+    "fire":                     () => effectFire(0),
+    "flicker":                  () => effectFlicker(0),
+    "twinkle":                  () => effectTwinkle(0),
+    "color_chase":              () => effectColorChase(0),
+    "scan":                     () => effectScan(0),
+    "random":                   () => effectRandom(0),
+    "police":                   () => effectPolice(0),
+    "christmas":                () => effectChristmas(0),
+    "halloween":                () => effectHalloween(0),
+    "calaveras":                () => effectCalaveras(0),
+    "party":                    () => effectParty(0),
+    "relaxing":                 () => effectRelaxing(0),
+    "temperature_transition":   () => effectTemperatureTransition(0),
+    "sleep_transition":         () => effectSleepTransition(1800),
+    "fireworks":                () => effectFireworks(0),
+};
+
+/**
+ * Run an effect by name.
+ * @param {string} effectName - must match a key in EFFECT_MAP / CFG.effectsList
+ */
+function runEffect(effectName) {
+    const fn = EFFECT_MAP[effectName];
+    if (fn) {
+        console.log(`Running effect: "${effectName}"`);
+        fn();
+    } else {
+        node.warn(`Unknown effect: "${effectName}"`);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ DISPATCH
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Look up and invoke the right handler for a given state + color mode.
+ * @param {Object} handlerMap - COLOR_MODE_HANDLERS or TRANSITION_HANDLERS
+ * @param {string} state      - "ON" or "OFF"
+ * @param {Object} payload    - msg.payload
+ */
+function dispatch(handlerMap, state, payload) {
+    const stateHandlers = handlerMap[state];
+    if (!stateHandlers) {
+        node.warn(`dispatch: unknown state "${state}" — must be ON or OFF`);
+        return;
+    }
+    const handler = stateHandlers[CFG.colorModes];
+    if (handler === undefined) {
+        node.warn(`dispatch: unknown color mode "${CFG.colorModes}" for state "${state}"`);
+        return;
+    }
+    handler(payload);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//@ DEVICE REQUEST HANDLERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Write default/recovered values into RAM on startup so recall() always finds something.
+ * Called immediately on device add before any HA command arrives.
+ */
+function initDefaultMemory() {
+    const existingState = flow.get("<<FIXTURE_RAM_Memory_State>>", "memory")
+                       || flow.get("<<FIXTURE_Disk_Memory_State>>", "disk_values");
+    if (existingState) {
+        console.log("initDefaultMemory: existing state found in memory, skipping defaults.");
+        return;
+    }
+    rememberRam({
+        "<<FIXTURE_RAM_Memory_State>>": CFG.defaultState,
+        "<<bright>>":    CFG.defaultOn.brightness,
+        "<<red>>":       CFG.defaultOn.red,
+        "<<green>>":     CFG.defaultOn.green,
+        "<<blue>>":      CFG.defaultOn.blue,
+        "<<white>>":     CFG.defaultOn.white,
+        "<<warmWhite>>": CFG.defaultOn.warmWhite,
+        "<<colorTemp>>": CFG.defaultOn.colorTemp,
+    });
+    console.log("initDefaultMemory: defaults written to RAM.");
+}
+
+/**
+ * Clear all RAM and disk memory keys for this fixture.
+ * Called on device remove.
+ */
+function clearAllMemory() {
+    const ramKeys  = ["<<FIXTURE_RAM_Memory_State>>",  "<<bright>>", "<<red>>", "<<green>>", "<<blue>>", "<<white>>", "<<warmWhite>>", "<<colorTemp>>"];
+    const diskKeys = ["<<FIXTURE_Disk_Memory_State>>", "<<D_bright>>", "<<D_red>>", "<<D_green>>", "<<D_blue>>", "<<D_white>>", "<<D_warmWhite>>", "<<D_colorTemp>>"];
+    ramKeys.forEach(k  => flow.set(k, null, "memory"));
+    diskKeys.forEach(k => flow.set(k, null, "disk_values"));
+    console.log("clearAllMemory: all fixture memory cleared.");
+}
+
+/**
+ * Build the HA state recovery payload for the current color mode.
+ * Sends the last known state back to HA after a reboot/rediscovery
+ * so the dashboard never shows "unknown".
+ */
+function buildRecoveryStatePayload() {
+    const state     = recall("<<FIXTURE_RAM_Memory_State>>", "<<FIXTURE_Disk_Memory_State>>", CFG.defaultState);
+    const brightness = recall("<<bright>>",    "<<D_bright>>",    CFG.defaultOn.brightness);
+    const red        = recall("<<red>>",       "<<D_red>>",       CFG.defaultOn.red);
+    const green      = recall("<<green>>",     "<<D_green>>",     CFG.defaultOn.green);
+    const blue       = recall("<<blue>>",      "<<D_blue>>",      CFG.defaultOn.blue);
+    const white      = recall("<<white>>",     "<<D_white>>",     CFG.defaultOn.white);
+    const warmWhite  = recall("<<warmWhite>>", "<<D_warmWhite>>", CFG.defaultOn.warmWhite);
+    const colorTemp  = recall("<<colorTemp>>", "<<D_colorTemp>>", CFG.defaultOn.colorTemp);
+
+    console.log(`Recovery — state:${state}  bright:${brightness}  R:${red} G:${green} B:${blue} W:${white} WW:${warmWhite} CT:${colorTemp}`);
+
+    const rgb  = { r: red, g: green, b: blue };
+    const rgbw = { ...rgb, w: white };
+    const rgbww = { ...rgbw, ww: warmWhite };
+
+    const map = {
+        "onoff":              { state, brightness, color: rgb,   color_mode: "onoff" },
+        "brightness":         { state, brightness, color: rgb,   color_mode: "brightness" },
+        "rgb":                { state, brightness, color: rgb,   color_mode: "rgb" },
+        "rgbw":               { state, brightness, color: rgbw,  color_mode: "rgbw" },
+        "rgbww":              { state, brightness, color: rgbww, color_mode: "rgbww" },
+        "color_temp":         { state, brightness, color_temp: colorTemp, color_mode: "color_temp" },
+        "white":              { state, brightness, color_mode: "white" },
+        "rgb,color_temp":     { state, brightness, color: rgb,  color_mode: "rgb" },
+        "rgbw,color_temp":    { state, brightness, color: rgbw, color_mode: "rgbw" },
+        "rgbww,color_temp":   { state, brightness, color: rgbww, color_mode: "rgbww" },
+    };
+
+    return map[CFG.colorModes] ?? null;
+}
+
+function handleDeviceAdd() {
+    initDefaultMemory();
+
+    const colorModesArray = CFG.colorModes.split(',');
+    const cmdTopic        = `${fixtureTopic}/${CFG.commandTopic}`;
+    const statTopic       = `${fixtureTopic}/${CFG.stateTopic}`;
+    const cfgTopic        = `${fixtureTopic}/${CFG.configTopic}`;
+    const { device: dev } = CFG;
+
+    const discoveryPayload = {
+        retain:  CFG.retain,
+        qos:     CFG.qos,
+        topic:   cfgTopic,
+        payload: {
+            unique_id:             `${dev.type}(${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix})`,
+            schema:                CFG.schema,
+            //^ object_id locks the HA entity_id to the plan ID: light.l_991 or light.l_176_a
+            //^ Survives user renaming the friendly name in the HA frontend.
+            //^ WARNING: changing this on a deployed node changes the entity_id in HA —
+            //^ update any automations referencing the old entity_id after re-discovery.
+            object_id:             `${CFG.uidPrefix}_${CFG.uid}${CFG.uidPostfix}`.toLowerCase().replace(/[^a-z0-9]/g, '_').replace(/__+/g, '_'),
+            name:                  `${dev.type} ${dev.situation} the ${CFG.dmxZone} ${dev.area} ${dev.subLocation}`,
+            cmd_t:                 cmdTopic,
+            stat_t:                statTopic,
+            optimistic:            CFG.optimistic,
+            enabled_by_default:    CFG.enabledByDefault,
+            icon:                  CFG.icon,
+            supported_color_modes: colorModesArray,
+            brightness:            CFG.brightness,
+            brightness_scale:      CFG.dmxLimiter,
+            transition:            CFG.transitionsEnabled,
+            effect:                CFG.effects,
+            effect_list:           CFG.effectsList,
+            flash_time_short:      CFG.flashShort,
+            flash_time_long:       CFG.flashLong,
+            min_mireds:            CFG.minMireds,
+            max_mireds:            CFG.maxMireds,
+            device: {
+                identifiers:    `${CFG.component}-${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`,
+                name:           `(${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}) - ${dev.type}/s ${dev.situation} the ${CFG.dmxZone} - ${dev.area} - ${dev.subLocation}`,
+                model:          `${colorModesArray} ${dev.type}/s located ${dev.situation} the ${CFG.dmxZone}-${dev.area} - ${dev.subLocation}`,
+                model_id:       `referenced on plan as: (${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}`,
+                suggested_area: `${CFG.dmxZone} ${dev.area} ${dev.subLocation}`,
+                hw_version:     `DMX Controller in ${CFG.dmxZone} Server Rack, firmware: ${CFG.dmxControllerFw}. MQTT: ${dmxTopic}/#`,
+                serial_number:  `(${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix}) See ⓘ MQTT Info below.`,
+                sw_version:     `${CFG.nodeCode}: ${CFG.nodeSw}`,
+                manufacturer:   "DeSwaggy — Discord: @deswaggy",
+            },
+        },
+    };
+
+    node.send([
+        discoveryPayload,
+        { retain: CFG.retain, qos: CFG.qos, topic: cmdTopic, action: "subscribe" },
+        { status: { fill: "green", shape: "ring", text: `${fixtureId} discovery sent — awaiting HA` } },
+        null, null, null,
+    ]);
+    console.log(`Device added: ${dev.type}(${CFG.uidPrefix}-${CFG.uid}${CFG.uidPostfix})`);
+
+    //# Wait briefly before pushing recovery state — gives HA time to register
+    //# the discovery before we report the last-known state.
+    //# Simple setTimeout is correct here — not writing to disk, just reporting
+    //# state to HA. The disk save timer is reserved for command handling only.
+    setTimeout(() => {
+        const recoveryPayload = buildRecoveryStatePayload();
+        if (recoveryPayload) {
+            sendState(recoveryPayload);
+            sendStatus("yellow", "ring", `${fixtureId} ready — awaiting HA commands`);
+            console.log(`Recovery state sent for mode: ${CFG.colorModes}`);
+        } else {
+            sendStatus("yellow", "ring", `${fixtureId} ready — awaiting HA commands`);
+        }
+    }, 2000);
+}
+
+function handleDeviceRemove() {
+    //# Cancel any running timers before removing
+    [context.get('timer_transition'), context.get('timer_effect'), context.get('timer_diskSave')].forEach(t => {
+        if (t) clearInterval(t);
+    });
+    context.set('timer_transition', null);
+    context.set('timer_effect', null);
+    context.set('timer_diskSave', null);
+
+    clearAllMemory();
+
+    const cfgTopic = `${fixtureTopic}/${CFG.configTopic}`;
+    const cmdTopic = `${fixtureTopic}/${CFG.commandTopic}`;
+
+    node.send([
+        { retain: CFG.retain, qos: CFG.qos, topic: cfgTopic, payload: "" },
+        { retain: CFG.retain, qos: CFG.qos, topic: cmdTopic, action: "unsubscribe" },
+        { status: { fill: "red", shape: "ring", text: `${fixtureId} discovery removed — memory cleared` } },
+        null, null, null,
+    ]);
+    console.log(`Device removed. Unsubscribed: ${cmdTopic}`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//!? ENTRY POINT
+// ─────────────────────────────────────────────────────────────────────────────
+
+//# Pass the original message through on output 4 — suppressed for AUX messages
+//# since the parent Group Node already passed it through, avoiding duplicates.
+const isAuxMessage = msg.dmx_trace != null;
+if (!isAuxMessage) {
+    node.send([null, null, null, msg, null, null, null]);
+}
+
+const prevState = recall("<<FIXTURE_RAM_Memory_State>>", "<<FIXTURE_Disk_Memory_State>>", CFG.defaultState);
+console.log(`prev state: ${prevState}  colorMode: ${CFG.colorModes}  isAux: ${isAuxMessage}`);
+
+//? ── AUX — payload from parent Group Node ───────────────────────────────────
+if (isAuxMessage) {
+    const trace = msg.dmx_trace;
+    console.log(
+        `AUX received — source:${trace.source}  ` +
+        `depth:${trace.depth}  path:${trace.path.join(' → ')}`
+    );
+
+    const { state, transition, effect } = msg.payload;
+
+    if (effect && CFG.effects) {
+        if (CFG.effectsGroupControlled) {
+            //# Group-controlled mode — accept effect from parent Group Node (synced with siblings)
+            console.log(`AUX group-controlled effect: "${effect}"`);
+            runEffect(effect);
+        } else {
+            //# Independent mode — this fixture ignores group effect commands
+            console.log(`AUX effect "${effect}" ignored — fixture controls its own effects (<DMX_Effects_Group_Controlled>=false)`);
+        }
+    } else {
+        //# Non-effect AUX command — stop any running effect first
+        stopEffect();
+        //# Route through normal dispatch — identical to a direct HA command
+        const wantTransition = transition && CFG.transitionsEnabled;
+        const handlerMap = wantTransition ? TRANSITION_HANDLERS : COLOR_MODE_HANDLERS;
+        console.log(`AUX ${wantTransition ? "TRANSITION" : "NO TRANSITION"} — state:${state}  colorMode:${CFG.colorModes}`);
+        dispatch(handlerMap, state, msg.payload);
+    }
+
+//? ── DIRECT HA COMMAND ────────────────────────────────────────────────────────
+} else if (msg.payload?.state != null) {
+    const { state, transition, effect } = msg.payload;
+
+    if (effect && CFG.effects) {
+        if (CFG.effectsGroupControlled) {
+            //# Group-controlled mode — ignore direct HA effect commands, only AUX accepted
+            node.warn(
+                `DMX Node — effect "${effect}" ignored. ` +
+                `<DMX_Effects_Group_Controlled>=true means effects must come via a Group Node ` +
+                `to keep siblings in sync. Set to false to allow direct effect control.`
+            );
+        } else {
+            //# Independent mode — accept direct HA effect commands
+            console.log(`Direct HA effect: "${effect}"`);
+            runEffect(effect);
+        }
+    } else {
+        //# Non-effect command — stop any running effect first so it doesn't fight the new state
+        stopEffect();
+        //# If transitions are disabled for this fixture always use the instant handler
+        const wantTransition = transition && CFG.transitionsEnabled;
+        const handlerMap = wantTransition ? TRANSITION_HANDLERS : COLOR_MODE_HANDLERS;
+        console.log(`${wantTransition ? "TRANSITION" : "NO TRANSITION"} — state:${state}  colorMode:${CFG.colorModes}  transitionsEnabled:${CFG.transitionsEnabled}`);
+        dispatch(handlerMap, state, msg.payload);
+    }
+
+//? ── DEVICE REQUEST — add / remove / debug ───────────────────────────────────
+} else if (msg.device != null && (msg.device?.request != null || typeof msg.device === "string")) {
+    const _devReq = typeof msg.device === "string" ? msg.device : msg.device.request;
+    console.log(`device.request: ${_devReq}`);
+    switch (_devReq) {
+        case "add":    handleDeviceAdd();    break;
+        case "remove": handleDeviceRemove(); break;
+        case "debug":  console.log("DEBUG:", JSON.stringify(msg)); break;
+        default:       node.warn(`Unknown device.request: ${msg.device.request}`);
+    }
+
+//? ── UNKNOWN MESSAGE ──────────────────────────────────────────────────────────
+} else {
+    node.warn(
+        "DMX Node — unrecognised message received. " +
+        "Expected: msg.dmx_trace (AUX from Group Node), " +
+        "msg.payload.state (direct HA command), " +
+        "or msg.device.request (add/remove/debug). " +
+        "Message received and dropped — unrecognised format. See node documentation."
+    );
+}
+
+node.done();
+return [null, null, null, msg, null, null];