Fix AI energy level platform-flip bug found in Opus review

The switch and select shared a stub-time asymmetry: only the select had a
`not rep` carve-out, so an unfetched-stub rep at the moment platforms are
set up (entity creation runs once, ever) would instantiate a Select, while
flatten() re-evaluates exists_fn every poll against live data -- once the
resource populated to a single-level list, the switch's exists_fn would win
instead and feed the already-created Select a bool through their shared
'ai_energy_level' key, which isn't a valid select option.

Dropped the stub carve-out from the select's exists_fn so both sides
require real, populated data to decide the platform -- on a device that
stubs this cold-tier href on its very first poll, the entity now simply
doesn't appear until a reload, instead of appearing as the wrong widget
type. Added tests for the missing/empty-list supportedAiLevel shapes on
both widgets and a regression test locking in the stub behavior.

custom_components/localthings/coordinator.py

@@ -12,6 +12,7 @@ import cbor2
 
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant, callback
+from homeassistant.exceptions import ServiceValidationError
 from homeassistant.helpers import issue_registry as ir
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
 from homeassistant.helpers.device_registry import DeviceInfo
@@ -509,13 +510,23 @@ class LocalThingsCoordinator(DataUpdateCoordinator[dict[str, Any]]):
 
     async def async_send_command(self, bound_entity: BoundEntity,
                                  payload: Any) -> None:
-        """Write a value to the device. Fire-and-forget style."""
+        """Write a value to the device. Fire-and-forget style.
+
+        A description-level validate_fn (currently SwitchDesc only) runs
+        here rather than per-platform, so rejecting a write with a
+        user-facing message -- as opposed to write_fn's silent no-op below
+        -- is available to every platform for free."""
         desc = bound_entity.desc
         write_fn = getattr(desc, 'write_fn', None)
         if write_fn is None:
             return
         href = bound_entity.href
         rep = self._cache.get(href or '') or {}
+        validate_fn = getattr(desc, 'validate_fn', None)
+        if validate_fn is not None:
+            error = validate_fn(payload, rep, self._cache.snapshot())
+            if error:
+                raise ServiceValidationError(error)
         result = write_fn(payload, rep, href)
         if result is None:
             self._log.warning("write_fn rejected payload %r for %s", payload, href)

custom_components/localthings/registry/by_type/airconditioner.py

@@ -3,23 +3,20 @@
 The first device whose core controls surface as a single composite HA `climate`
 entity (see capabilities/airconditioner.py and climate.py). Power/mode/temp/wind
 are consumed by that entity rather than exposed as separate switches/selects, so
-this registry deliberately does NOT include the common POWER caps -- on/off is
-the climate entity's HVACMode.OFF / TURN_ON/OFF.
+this registry includes *common.UNIVERSAL but deliberately NOT common.POWER --
+on/off is the climate entity's HVACMode.OFF / TURN_ON/OFF. See common.POWER's
+own comment in capabilities/common.py for why it's excluded.
 
-Reuses common.ALARMS + common.ENERGY_METER, fridge.FIRMWARE_UPDATE (as every
-registry does), and dishwasher.DIAGNOSIS for /diagnosis/vs/0.
+Reuses dishwasher.DIAGNOSIS for /diagnosis/vs/0.
 """
-from ..capabilities import airconditioner, common, dishwasher, fridge, ignored
+from ..capabilities import airconditioner, common, dishwasher, ignored
 from ._base import DeviceRegistry, _build
 
 REGISTRY = DeviceRegistry(
     name='airconditioner',
     capabilities=_build([
         *ignored.IGNORED,
-        common.ALARMS,
-        common.ENERGY_METER,
-        fridge.FIRMWARE_UPDATE,
-        fridge.SELF_CHECK,
+        *common.UNIVERSAL,
         dishwasher.DIAGNOSIS,
         airconditioner.CLIMATE,
         airconditioner.AIR_PURIFY,

custom_components/localthings/registry/by_type/dishwasher.py

@@ -1,19 +1,13 @@
 """Dishwasher device registry."""
-from ..capabilities import common, dishwasher, fridge, ignored, laundry, operational
+from ..capabilities import common, dishwasher, ignored, laundry, operational
 from ._base import DeviceRegistry, _build
 
 REGISTRY = DeviceRegistry(
     name='dishwasher',
     capabilities=_build([
         *ignored.IGNORED,
-        common.POWER_GENERIC,
-        common.POWER_VS_FALLBACK,
-        common.KIDS_LOCK_GENERIC,
-        common.KIDS_LOCK_VS_FALLBACK,
-        common.REMOTE_CONTROL_GENERIC,
-        common.REMOTE_CONTROL_VS_FALLBACK,
-        common.ALARMS,
-        common.ENERGY_METER,
+        *common.UNIVERSAL,
+        *common.POWER,
         common.WATER_METER,
         common.WATER_FILTER,
         operational.OPERATIONAL_STATE,
@@ -25,6 +19,5 @@ REGISTRY = DeviceRegistry(
         laundry.DOOR_LED,
         laundry.SOUND_MODE,
         laundry.SOUND_VOLUME,
-        fridge.FIRMWARE_UPDATE,
     ]),
 )

custom_components/localthings/registry/by_type/dryer.py

@@ -9,21 +9,15 @@ objects the washer registry uses -- washer and dryer expose the same
 DA_WM_-family surface, so they stay consistent instead of each carrying a
 bespoke variant.
 """
-from ..capabilities import common, dryer, fridge, ignored, laundry, operational
+from ..capabilities import common, dryer, ignored, laundry, operational
 from ._base import DeviceRegistry, _build
 
 REGISTRY = DeviceRegistry(
     name='dryer',
     capabilities=_build([
         *ignored.IGNORED,
-        common.POWER_GENERIC,
-        common.POWER_VS_FALLBACK,
-        common.KIDS_LOCK_GENERIC,
-        common.KIDS_LOCK_VS_FALLBACK,
-        common.REMOTE_CONTROL_GENERIC,
-        common.REMOTE_CONTROL_VS_FALLBACK,
-        common.ALARMS,
-        common.ENERGY_METER,
+        *common.UNIVERSAL,
+        *common.POWER,
         operational.OPERATIONAL_STATE,
         laundry.DOOR_LED,
         laundry.SOUND_MODE,
@@ -32,6 +26,5 @@ REGISTRY = DeviceRegistry(
         dryer.DRYER_SETTINGS,
         dryer.DRYER_COURSE,
         dryer.DRYER_DIAGNOSIS,
-        fridge.FIRMWARE_UPDATE,
     ]),
 )

custom_components/localthings/registry/by_type/oven.py

@@ -1,24 +1,18 @@
 """Oven device registry."""
-from ..capabilities import common, fridge, ignored, oven
+from ..capabilities import common, ignored, oven
 from ._base import DeviceRegistry, _build
 
 REGISTRY = DeviceRegistry(
     name='oven',
     capabilities=_build([
         *ignored.IGNORED,
-        common.POWER_GENERIC,
-        common.POWER_VS_FALLBACK,
-        common.KIDS_LOCK_GENERIC,
-        common.KIDS_LOCK_VS_FALLBACK,
-        common.REMOTE_CONTROL_GENERIC,
-        common.REMOTE_CONTROL_VS_FALLBACK,
-        common.ALARMS,
+        *common.UNIVERSAL,
+        *common.POWER,
         oven.OVEN_CAVITY,
         oven.OVEN_SETPOINT,
         oven.OVEN_MODE,
         oven.OVEN_OPERATIONAL_STATE,
         oven.OVEN_DOOR,
         oven.OVEN_CONNECTED,
-        fridge.FIRMWARE_UPDATE,
     ]),
 )

custom_components/localthings/registry/by_type/refrigerator.py

@@ -6,21 +6,14 @@ REGISTRY = DeviceRegistry(
     name='refrigerator',
     capabilities=_build([
         *ignored.IGNORED,
-        common.POWER_GENERIC,
-        common.POWER_VS_FALLBACK,
+        *common.UNIVERSAL,
+        *common.POWER,
         fridge.STATUS_LOCK,
         fridge.DOOR_ALERT,
-        common.KIDS_LOCK_GENERIC,
-        common.KIDS_LOCK_VS_FALLBACK,
-        common.REMOTE_CONTROL_GENERIC,
-        common.REMOTE_CONTROL_VS_FALLBACK,
-        common.ALARMS,
-        common.ENERGY_METER,
         common.WATER_FILTER,
         dishwasher.DIAGNOSIS,
         fridge.ICEMAKER_NIGHTTIME,
         fridge.FLEX_ZONE,
-        fridge.AI_ENERGY_LEVEL,
         fridge.REFRIGERATION,
         fridge.AUTOFILL,
         fridge.WELCOME_LIGHTING,
@@ -29,11 +22,9 @@ REGISTRY = DeviceRegistry(
         fridge.SABBATH,
         fridge.BEVERAGE_ZONE,
         fridge.PANTRY_ZONE,
-        fridge.FIRMWARE_UPDATE,
         fridge.DEFROST_DELAY,
         fridge.DEFROST_DELAY_NATIVE_DUPLICATE,
         fridge.DEFROST_BLOCK_STATUS,
-        fridge.SELF_CHECK,
         fridge.DOORS_FALLBACK,
         fridge.TEMPERATURES_FALLBACK,
         fridge.ICEMAKER_STATUS_FALLBACK,

custom_components/localthings/registry/by_type/washer.py

@@ -1,26 +1,19 @@
 """Washer device registry."""
-from ..capabilities import common, dishwasher, fridge, ignored, laundry, operational, washer
+from ..capabilities import common, dishwasher, ignored, laundry, operational, washer
 from ._base import DeviceRegistry, _build
 
 REGISTRY = DeviceRegistry(
     name='washer',
     capabilities=_build([
         *ignored.IGNORED,
-        common.POWER_GENERIC,
-        common.POWER_VS_FALLBACK,
-        common.KIDS_LOCK_GENERIC,
-        common.KIDS_LOCK_VS_FALLBACK,
-        common.REMOTE_CONTROL_GENERIC,
-        common.REMOTE_CONTROL_VS_FALLBACK,
+        *common.UNIVERSAL,
+        *common.POWER,
         washer.WASHER_SETTINGS,
         washer.WASHER_COURSE,
         laundry.BUZZER_SOUND,
         laundry.JOB_BEGINNING_STATUS,
-        common.ALARMS,
-        common.ENERGY_METER,
         common.WATER_METER,
         operational.OPERATIONAL_STATE,
         dishwasher.DIAGNOSIS,
-        fridge.FIRMWARE_UPDATE,
     ]),
 )

custom_components/localthings/registry/capabilities/airconditioner.py

@@ -219,8 +219,9 @@ _AC_IGNORED = [
     # user-actionable state or no documented write contract, so per the
     # 'don't guess' rule they are ignored rather than modeled.
     # /option/muteonce/vs/0 and /selfcheck/vs/0 are deliberately NOT here --
-    # see MUTE_ONCE and fridge.SELF_CHECK above/in the by_type registry,
-    # both of which have a confirmed, cleanly modelable contract.
+    # see MUTE_ONCE above and common.SELF_CHECK (via common.UNIVERSAL) in
+    # the by_type registry, both of which have a confirmed, cleanly
+    # modelable contract.
     '/airlevelcheck/vs/0',         # periodic air-quality sensing scheduler plumbing
     '/aisleep/vs/0',               # AI-sleep feedback state (no actionable control)
     '/availablecontrolsets/vs/0',  # opaque hex-encoded control-set bitmap

custom_components/localthings/registry/capabilities/common.py

@@ -11,7 +11,9 @@ against live device dumps:
   /filter/waterfilter/vs/0  -> x.com.samsung.da.filterUsage / filterStatus
 """
 from ..capability import Capability
-from ..entities import BinarySensorDesc, SensorDesc, SwitchDesc
+from ..entities import (
+    BinarySensorDesc, ButtonDesc, SelectDesc, SensorDesc, SwitchDesc,
+)
 
 
 def _num(v):
@@ -231,3 +233,162 @@ WATER_FILTER = Capability(
                    name='Filter status', icon='mdi:filter-check'),
     ),
 )
+
+# AI energy-saving level -- '0' is off, and supportedAiLevel lists the
+# additional level(s) the device offers ('1' meaning just "on" on most
+# hardware, but multi-level boards have been reported). Verified cross-family:
+# fridge (issue #21) and washer (issue #40) both expose this href.
+#
+# supportedAiLevel is a single-entry list on most captured hardware, where a
+# select would offer only one real choice against an implicit "off" -- shown
+# as a switch instead. '0' itself is never in supportedAiLevel but has been
+# observed live as the off value of aiLevel, so the select synthesizes it
+# back in as an explicit option rather than leaving no way to turn off.
+#
+# No translation_key: aiLevel's values are plain digit strings, and
+# select.py's _display() already renders an untranslated numeric string
+# as-is -- there's nothing a strings.json entry adds that's worth maintaining
+# against an unknown, growing number of future levels.
+
+
+def _ai_energy_supported_levels(rep):
+    """supportedAiLevel as a list -- a stray scalar (e.g. a string) must not
+    be len()-checked as if it were a list."""
+    sl = rep.get('supportedAiLevel')
+    return list(sl) if isinstance(sl, (list, tuple)) else []
+
+
+def _ai_energy_level_options(resources):
+    rep = resources.get('/energy/ailevel/vs/0') or {}
+    return ['0', *_ai_energy_supported_levels(rep)]
+
+
+def _ai_energy_level_write(p, rep, href=None):
+    return ['energy', 'ailevel', 'vs', '0'], {'aiLevel': p}
+
+
+def _ai_energy_level_switch_write(p, rep, href=None):
+    levels = _ai_energy_supported_levels(rep)
+    on_level = levels[0] if levels else '1'
+    return ['energy', 'ailevel', 'vs', '0'], {'aiLevel': on_level if p == 'On' else '0'}
+
+
+AI_ENERGY_LEVEL = Capability(
+    href='/energy/ailevel/vs/0',
+    poll_tier='cold',
+    entities=(
+        # No `not rep` stub carve-out on either side, unlike most exists_fn
+        # gates in this file -- entity creation only ever runs once, against
+        # whichever snapshot happens to be current the moment platforms are
+        # set up (see entity._is_included / __init__.py's
+        # async_config_entry_first_refresh-before-forward-entry-setups
+        # ordering), while flatten() re-evaluates exists_fn every poll
+        # against live data. Both descriptors share key='ai_energy_level',
+        # so if a stub carve-out let one of them win at setup time while the
+        # other wins once real data lands, flatten() would feed the
+        # instantiated entity a value shaped for the other platform (e.g. a
+        # bool into a Select). Requiring real, populated data on both sides
+        # keeps the entity-creation decision and the live-value decision in
+        # permanent agreement -- the cost is this entity doesn't appear
+        # until a reload if the device's very first poll stubs this
+        # cold-tier href, the same reload already required to fix which
+        # platform got picked in that case.
+        SwitchDesc(key='ai_energy_level', field='aiLevel',
+                   name='AI energy level', icon='mdi:leaf',
+                   entity_category='config',
+                   value_fn=lambda v: v != '0',
+                   exists_fn=lambda rep, resources: (
+                       len(_ai_energy_supported_levels(rep)) == 1),
+                   write_fn=_ai_energy_level_switch_write),
+        SelectDesc(key='ai_energy_level', field='aiLevel',
+                   name='AI energy level', icon='mdi:leaf',
+                   entity_category='config',
+                   options=_ai_energy_level_options,
+                   exists_fn=lambda rep, resources: (
+                       len(_ai_energy_supported_levels(rep)) > 1),
+                   write_fn=_ai_energy_level_write),
+    ),
+)
+
+FIRMWARE_UPDATE = Capability(
+    href='/otninformation/vs/0',
+    poll_tier='cold',
+    entities=(
+        BinarySensorDesc(
+            key='firmware_update',
+            field='x.com.samsung.da.newVersionAvailable',
+            name='Firmware update available',
+            device_class='update',
+            entity_category='diagnostic',
+            value_fn=lambda v: str(v).lower() == 'true' if v is not None else None,
+        ),
+    ),
+)
+
+SELF_CHECK = Capability(
+    href='/selfcheck/vs/0',
+    poll_tier='cold',
+    entities=(
+        SensorDesc(key='selfcheck_status', field='x.com.samsung.da.status',
+                   name='Self-check status', icon='mdi:stethoscope',
+                   entity_category='diagnostic'),
+        SensorDesc(key='selfcheck_result', field='x.com.samsung.da.result',
+                   name='Self-check result', icon='mdi:clipboard-check-outline',
+                   entity_category='diagnostic'),
+        # List of error codes from the last self-check; joined for display.
+        # Not every fridge reports the field, hence the exists_fn.
+        SensorDesc(key='selfcheck_error', field='x.com.samsung.da.error',
+                   name='Self-check error', icon='mdi:alert-circle-outline',
+                   entity_category='diagnostic',
+                   exists_fn=lambda rep, resources: (
+                       not rep or 'x.com.samsung.da.error' in rep),
+                   value_fn=lambda v: (', '.join(v) if v else None) if isinstance(v, list) else v),
+        ButtonDesc(key='selfcheck_start', field='', name='Start self-check',
+                   payload='Start', icon='mdi:play-circle-outline',
+                   entity_category='diagnostic',
+                   write_fn=lambda p, rep, href=None: (
+                       ['selfcheck', 'vs', '0'], {'x.com.samsung.da.status': p})),
+    ),
+)
+
+# ---------------------------------------------------------------------------
+# Cross-family bundles, unpacked into every by_type registry's _build([...])
+# call the same way ignored.IGNORED is (*common.UNIVERSAL / *common.POWER).
+# discover() only binds a capability whose href is actually present in a
+# given device's resource dump, so listing one here for a family that
+# doesn't expose the href is a no-op, not a phantom entity -- see the
+# adding-device-support skill's coverage-discipline section.
+#
+# UNIVERSAL holds every capability with no known family that both (a) has
+# the href and (b) needs to model it some other way -- broadening one of
+# these to a new family is a safe, harmless guess (issue #40's AI energy
+# level: 2 of 6 families confirmed, blanket-added everywhere else).
+#
+# POWER is kept separate -- airconditioner is the one family that opts out
+# of it. Canonical reason (see by_type/airconditioner.py and its test for
+# pointers back here, not restatements): AC's climate entity already owns
+# /power/0 and /power/vs/0 via bare, no-entity Capability objects
+# (airconditioner.COVERAGE), and a second, real POWER_GENERIC/
+# POWER_VS_FALLBACK cap on the same href would make _build() raise (a href
+# with >1 cap must have every cap discriminated by rt_filter/match_fn, and
+# the bare COVERAGE cap has neither). Kids-lock/remote-control don't have
+# this conflict -- no AC dump has ever reported those hrefs -- so they stay
+# in UNIVERSAL.
+# ---------------------------------------------------------------------------
+
+UNIVERSAL = (
+    ALARMS,
+    ENERGY_METER,
+    FIRMWARE_UPDATE,
+    SELF_CHECK,
+    AI_ENERGY_LEVEL,
+    KIDS_LOCK_GENERIC,
+    KIDS_LOCK_VS_FALLBACK,
+    REMOTE_CONTROL_GENERIC,
+    REMOTE_CONTROL_VS_FALLBACK,
+)
+
+POWER = (
+    POWER_GENERIC,
+    POWER_VS_FALLBACK,
+)

custom_components/localthings/registry/capabilities/dishwasher.py

@@ -8,7 +8,7 @@ wash, auto release dry) are read locally here.
 """
 from ..capability import Capability
 from ..entities import ButtonDesc, SelectDesc, SensorDesc, SwitchDesc
-from .laundry import cycle_select, option_value, replace_in_options
+from .laundry import bool_option_switch, cycle_select
 
 # ---------------------------------------------------------------------------
 # /dishwasher/vs/0 — cycle wash/dry settings
@@ -35,49 +35,20 @@ DISHWASHER_SETTINGS = Capability(
 # ---------------------------------------------------------------------------
 # /course/vs/0 — cycle selection (shared laundry.cycle_select) plus the
 # dishwasher-only StormWashZone / AutoDoorRelease toggles that ride in the
-# same options array. Course display names live in translations under
+# same options array (shared laundry.bool_option_switch, same options[]
+# boolean-toggle contract washer's bubble-soak/pre-wash/intensive switches
+# use). Course display names live in translations under
 # entity.select.dishwasher_cycle (see laundry.cycle_select).
 # ---------------------------------------------------------------------------
 
-
-def _storm_wash_write(p, rep, href=None):
-    if p not in ('On', 'Off'):
-        return None
-    opts = list(rep.get('x.com.samsung.da.options') or [])
-    if not opts:
-        return None
-    return ['course', 'vs', '0'], {
-        'x.com.samsung.da.options': replace_in_options(opts, 'StormWashZone', p),
-    }
-
-
-def _auto_release_write(p, rep, href=None):
-    if p not in ('On', 'Off'):
-        return None
-    opts = list(rep.get('x.com.samsung.da.options') or [])
-    if not opts:
-        return None
-    return ['course', 'vs', '0'], {
-        'x.com.samsung.da.options': replace_in_options(opts, 'AutoDoorRelease', p),
-    }
-
-
 CYCLE_OPTIONS = Capability(
     href='/course/vs/0',
     entities=(
         cycle_select(translation_key='dishwasher_cycle', icon='mdi:dishwasher'),
-        SwitchDesc(key='storm_wash', name='Storm Wash+', icon='mdi:weather-lightning-rainy',
-                   rep_fn=lambda rep: option_value(
-                       rep.get('x.com.samsung.da.options'), 'StormWashZone') == 'On',
-                   write_fn=_storm_wash_write),
-        SwitchDesc(key='auto_release_dry', name='Auto release dry', icon='mdi:door-open',
-                   exists_fn=lambda rep, resources: any(
-                       isinstance(o, str) and o.startswith('AutoDoorRelease_')
-                       for o in (rep.get('x.com.samsung.da.options') or [])
-                   ),
-                   rep_fn=lambda rep: option_value(
-                       rep.get('x.com.samsung.da.options'), 'AutoDoorRelease') == 'On',
-                   write_fn=_auto_release_write),
+        bool_option_switch('storm_wash', 'Storm Wash+', 'mdi:weather-lightning-rainy',
+                            'StormWashZone'),
+        bool_option_switch('auto_release_dry', 'Auto release dry', 'mdi:door-open',
+                            'AutoDoorRelease', gate_on_presence=True),
     ),
 )
 

custom_components/localthings/registry/capabilities/fridge.py

@@ -19,7 +19,7 @@ import datetime
 
 from ..capability import Capability
 from ..entities import (
-    BinarySensorDesc, ButtonDesc, NumberDesc, SelectDesc, SensorDesc,
+    BinarySensorDesc, NumberDesc, SelectDesc, SensorDesc,
     SwitchDesc, TimeDesc,
 )
 from .common import normalize_temp_unit
@@ -228,36 +228,6 @@ DEFROST_BLOCK_STATUS = Capability(
     ),
 )
 
-# ---------------------------------------------------------------------------
-# Self-check diagnostic
-# ---------------------------------------------------------------------------
-
-SELF_CHECK = Capability(
-    href='/selfcheck/vs/0',
-    poll_tier='cold',
-    entities=(
-        SensorDesc(key='selfcheck_status', field='x.com.samsung.da.status',
-                   name='Self-check status', icon='mdi:stethoscope',
-                   entity_category='diagnostic'),
-        SensorDesc(key='selfcheck_result', field='x.com.samsung.da.result',
-                   name='Self-check result', icon='mdi:clipboard-check-outline',
-                   entity_category='diagnostic'),
-        # List of error codes from the last self-check; joined for display.
-        # Not every fridge reports the field, hence the exists_fn.
-        SensorDesc(key='selfcheck_error', field='x.com.samsung.da.error',
-                   name='Self-check error', icon='mdi:alert-circle-outline',
-                   entity_category='diagnostic',
-                   exists_fn=lambda rep, resources: (
-                       not rep or 'x.com.samsung.da.error' in rep),
-                   value_fn=lambda v: (', '.join(v) if v else None) if isinstance(v, list) else v),
-        ButtonDesc(key='selfcheck_start', field='', name='Start self-check',
-                   payload='Start', icon='mdi:play-circle-outline',
-                   entity_category='diagnostic',
-                   write_fn=lambda p, rep, href=None: (
-                       ['selfcheck', 'vs', '0'], {'x.com.samsung.da.status': p})),
-    ),
-)
-
 # ---------------------------------------------------------------------------
 # Refrigeration modes (rapid cooling)
 # ---------------------------------------------------------------------------
@@ -588,52 +558,6 @@ FLEX_ZONE = Capability(
     ),
 )
 
-# ---------------------------------------------------------------------------
-# AI energy-saving level
-#
-# supportedAiLevel is a single-entry list ('1' only) on some hardware, where
-# a select would offer no real choice — gated to >1 supported level.
-# ---------------------------------------------------------------------------
-
-AI_ENERGY_LEVEL = Capability(
-    href='/energy/ailevel/vs/0',
-    poll_tier='cold',
-    entities=(
-        # Only levels '1'/'2' have translated labels in strings.json/translations;
-        # a higher supportedAiLevel entry renders as its raw value until added.
-        SelectDesc(key='ai_energy_level', field='aiLevel',
-                   name='AI energy level', icon='mdi:leaf',
-                   translation_key='ai_energy_level',
-                   entity_category='config',
-                   options_field='supportedAiLevel',
-                   exists_fn=lambda rep, resources: (
-                       not rep or (
-                           isinstance((sl := rep.get('supportedAiLevel')), (list, tuple))
-                           and len(sl) > 1)),
-                   write_fn=lambda p, rep, href=None: (
-                       ['energy', 'ailevel', 'vs', '0'], {'aiLevel': p})),
-    ),
-)
-
-# ---------------------------------------------------------------------------
-# Firmware update
-# ---------------------------------------------------------------------------
-
-FIRMWARE_UPDATE = Capability(
-    href='/otninformation/vs/0',
-    poll_tier='cold',
-    entities=(
-        BinarySensorDesc(
-            key='firmware_update',
-            field='x.com.samsung.da.newVersionAvailable',
-            name='Firmware update available',
-            device_class='update',
-            entity_category='diagnostic',
-            value_fn=lambda v: str(v).lower() == 'true' if v is not None else None,
-        ),
-    ),
-)
-
 # ---------------------------------------------------------------------------
 # Generic door pattern capability (href=None — use as pattern_cap only)
 # ---------------------------------------------------------------------------

custom_components/localthings/registry/capabilities/laundry.py

@@ -217,6 +217,59 @@ def cycle_select(*, translation_key, icon):
     )
 
 
+# ---------------------------------------------------------------------------
+# Plain boolean toggles over /course/vs/0's options[] array: a
+# '<prefix>_On'/'<prefix>_Off' token, read-modify-written the same way as
+# the 'Course' token above. Shared by washer (bubble soak, pre-wash,
+# intensive -- issue #22) and dishwasher (storm wash, auto release dry) --
+# both families ride this exact contract, just with different prefixes and
+# different presence/validation needs on top.
+# ---------------------------------------------------------------------------
+
+
+def bool_option_write(prefix):
+    def write(p, rep, href=None):
+        if p not in ('On', 'Off'):
+            return None
+        opts = list(rep.get('x.com.samsung.da.options') or [])
+        if not opts:
+            return None
+        return ['course', 'vs', '0'], {
+            'x.com.samsung.da.options': replace_in_options(opts, prefix, p),
+        }
+    return write
+
+
+def bool_option_value(prefix):
+    return lambda rep: option_value(rep.get('x.com.samsung.da.options'), prefix) == 'On'
+
+
+def bool_option_exists(prefix):
+    return lambda rep, resources: option_value(
+        rep.get('x.com.samsung.da.options'), prefix) is not None
+
+
+def bool_option_switch(key, name, icon, prefix, *, entity_category=None,
+                        gate_on_presence=False, validate_fn=None):
+    """A SwitchDesc over a '<prefix>_On'/'<prefix>_Off' options[] token.
+
+    gate_on_presence self-gates the entity off on models that never report
+    the token at all (washer's bubble soak/pre-wash/intensive); leave False
+    for a toggle every device in the family reports (dishwasher's storm
+    wash). validate_fn is passed straight through to SwitchDesc for callers
+    that need to reject a write against live device state (e.g. washer's
+    per-course availability check) -- this factory has no opinion on it and
+    building one, if needed, is the caller's job.
+    """
+    return SwitchDesc(
+        key=key, name=name, icon=icon, entity_category=entity_category,
+        exists_fn=bool_option_exists(prefix) if gate_on_presence else None,
+        rep_fn=bool_option_value(prefix),
+        write_fn=bool_option_write(prefix),
+        validate_fn=validate_fn,
+    )
+
+
 # ---------------------------------------------------------------------------
 # /wm/jobbeginingstatus/vs/0 -- the "why did the cycle not start" reason
 # (e.g. door open, no water). The vendor field is x.com.samsung.da.currentStatus

custom_components/localthings/registry/capabilities/washer.py

@@ -17,10 +17,13 @@ from datetime import datetime, timezone
 
 from ..capability import Capability
 from ..entities import BinarySensorDesc, SelectDesc, SensorDesc
-from .laundry import cycle_select, hex_pairs, option_value, replace_in_options
+from .laundry import (
+    bool_option_exists, bool_option_switch, cycle_options, cycle_select, hex_pairs, option_value,
+    replace_in_options,
+)
 
 # ---------------------------------------------------------------------------
-# Course_XX hex codes. The 23 codes named in strings.json/translations
+# Course_XX hex codes. 23 of the codes named in strings.json/translations
 # under entity.select.washer_cycle.state.<id, lowercased> were captured
 # from a live WW90DG6U25LEU4's x.com.samsung.da.editCourseList
 # (EditCourseList_1C1D211B1E29243328262722202325322F2E30662D8F96), matched
@@ -35,6 +38,13 @@ from .laundry import cycle_select, hex_pairs, option_value, replace_in_options
 # you'd expect to be pinned (default cycle + maintenance cycle),
 # corroborating the positional match.
 #
+# A further 5 codes -- '36' Wash+Dry, '37' Air Wash, '38' Cotton Dry,
+# '39' Synthetics Dry, and a second, distinct '1F' Intense Cold (not the
+# same code as '8F' above) -- came from a WD90T654DBN/S1 washer/dryer
+# combo's editCourseList and were named from that user's app screenshot
+# (issue #22). Combo units carry their own course set, so these codes
+# don't imply anything about '1F' on a plain washer.
+#
 # No static fallback list of those codes is kept here, deliberately: other
 # washer models have a different actual course set (a second dump's active
 # course, '65', isn't even in the list above; models with 'AI Wash'/'Mixed
@@ -226,9 +236,58 @@ def _dosing_low(prefix):
         rep.get('x.com.samsung.da.options'), prefix) not in (None, 'Off')
 
 
-def _dosing_alarm_exists(prefix):
-    return lambda rep, resources: option_value(
-        rep.get('x.com.samsung.da.options'), prefix) is not None
+# Bubble soak / pre-wash / intensive-wash toggles, from the same options[]
+# array (issue #22 follow-up on a WD90T654DBN/S1 combo). Each rides as a
+# plain '<Prefix>_On'/'<Prefix>_Off' token, confirmed by a dump taken with
+# Bubble Soak switched on in the app (BubbleSoak_On) -- the same On/Off shape
+# already used by AiOption and KidsLockBypass in this same array, so
+# PreWashSetting/IntensiveSetting are assumed to follow suit.
+#
+# Each also has a differently-named hex-pair availability field that lines up
+# positionally with editCourseList: BubbleSoakSet, PreWashAvailableSet,
+# IntensiveAvailableSet. On the reporter's dump (course '30' at position 1 of
+# 24), all three read 'F0' at that position and the toggle was writable --
+# and the same dump's earlier state (course '1C' at position 0, 'BubbleSoak
+# Off') decodes to '00' for that course, matching the app graying the
+# control out there. 'F0'/'00' is treated as available/unavailable on that
+# evidence. exists_fn (device-level presence) still only runs once, against
+# the setup-time snapshot, so it isn't a fit for this per-course check --
+# validate_fn runs on every write attempt instead (dispatched from
+# coordinator.async_send_command, ahead of write_fn), rejecting an on-write
+# for a course whose byte isn't 'F0' with a user-facing error rather than
+# silently no-opping against the device. The read/write/presence machinery
+# itself is laundry.bool_option_switch, shared with dishwasher's storm-wash/
+# auto-release-dry toggles -- only this per-course gating is washer-only, so
+# it stays here rather than in laundry.py (see laundry.bool_option_switch's
+# docstring: it takes a prebuilt validate_fn and has no opinion on it).
+def _bool_option_switch(key, name, icon, prefix, availability_field):
+    def validate(p, rep, resources):
+        """Reject turning on when the selected course's byte in
+        `availability_field` isn't 'F0'. Turning off is never blocked. Falls
+        back to allowing the write whenever the availability data can't be
+        resolved (unrecognized course, missing/mismatched-length bitmap)
+        rather than guessing -- a false rejection is worse than an
+        occasional no-op write."""
+        if p != 'On':
+            return None
+        opts = rep.get('x.com.samsung.da.options') or []
+        current = option_value(opts, 'Course')
+        courses = cycle_options(resources)
+        if not current or current not in courses:
+            return None
+        raw = option_value(opts, availability_field)
+        if raw is None:
+            return None
+        pairs = hex_pairs(raw)
+        if len(pairs) != len(courses):
+            return None
+        if pairs[courses.index(current)] != 'F0':
+            return f"{name} isn't available on the selected cycle."
+        return None
+
+    return bool_option_switch(
+        key, name, icon, prefix,
+        entity_category='config', gate_on_presence=True, validate_fn=validate)
 
 
 WASHER_COURSE = Capability(
@@ -281,11 +340,17 @@ WASHER_COURSE = Capability(
                    write_fn=_level_write('SoftenerLevel2Ctrl')),
         BinarySensorDesc(key='detergent_low', name='Detergent low',
                          icon='mdi:alert-circle-outline', device_class='problem',
-                         exists_fn=_dosing_alarm_exists('DetergentAlarm'),
+                         exists_fn=bool_option_exists('DetergentAlarm'),
                          rep_fn=_dosing_low('DetergentAlarm')),
         BinarySensorDesc(key='softener_low', name='Softener low',
                          icon='mdi:alert-circle-outline', device_class='problem',
-                         exists_fn=_dosing_alarm_exists('SoftenerAlarm'),
+                         exists_fn=bool_option_exists('SoftenerAlarm'),
                          rep_fn=_dosing_low('SoftenerAlarm')),
+        _bool_option_switch('bubble_soak', 'Bubble soak', 'mdi:chart-bubble',
+                             'BubbleSoak', 'BubbleSoakSet'),
+        _bool_option_switch('pre_wash', 'Pre wash', 'mdi:washing-machine',
+                             'PreWashSetting', 'PreWashAvailableSet'),
+        _bool_option_switch('intensive', 'Intensive', 'mdi:washing-machine',
+                             'IntensiveSetting', 'IntensiveAvailableSet'),
     ),
 )

custom_components/localthings/registry/entities.py

@@ -2,7 +2,9 @@
 
 Frozen dataclasses so the future native HA component can consume them as
 EntityDescription subclasses unchanged. Read transforms live in value_fn;
-presence gating in exists_fn; write logic in write_fn on command platforms.
+presence gating in exists_fn; write logic in write_fn on command platforms;
+pre-write rejection (surfaced to the user, not just logged) in validate_fn
+where a description declares one.
 """
 from __future__ import annotations
 
@@ -10,6 +12,11 @@ from dataclasses import dataclass, field
 from typing import Any, Callable, Optional
 
 WriteFn = Optional[Callable[[Any, dict], "tuple[list[str], dict] | None"]]
+# (payload, rep, resources) -> a human-readable rejection message, or None to
+# allow the write. resources is the coordinator's full href->rep snapshot, for
+# the same cross-resource lookups exists_fn needs (e.g. reading a sibling
+# href's live option list).
+ValidateFn = Optional[Callable[[Any, dict, dict], "str | None"]]
 
 
 def _identity(v: Any) -> Any:
@@ -61,6 +68,7 @@ class SelectDesc(SamsungEntityDescription):
 class SwitchDesc(SamsungEntityDescription):
     device_class: Optional[str] = None
     write_fn: WriteFn = None
+    validate_fn: ValidateFn = None
 
 
 @dataclass(frozen=True, kw_only=True)

custom_components/localthings/strings.json

@@ -89,7 +89,12 @@
           "66": "Denim",
           "2d": "Silent Wash",
           "8f": "Intense Cold",
-          "96": "Less Microfiber"
+          "96": "Less Microfiber",
+          "36": "Wash+Dry",
+          "37": "Air Wash",
+          "38": "Cotton Dry",
+          "39": "Synthetics Dry",
+          "1f": "Intense Cold"
         }
       },
       "dryer_cycle": {
@@ -143,12 +148,6 @@
           "180": "3 hr",
           "240": "4 hr"
         }
-      },
-      "ai_energy_level": {
-        "state": {
-          "1": "Level 1",
-          "2": "Level 2"
-        }
       }
     },
     "sensor": {

custom_components/localthings/translations/en.json

@@ -89,7 +89,12 @@
           "66": "Denim",
           "2d": "Silent Wash",
           "8f": "Intense Cold",
-          "96": "Less Microfiber"
+          "96": "Less Microfiber",
+          "36": "Wash+Dry",
+          "37": "Air Wash",
+          "38": "Cotton Dry",
+          "39": "Synthetics Dry",
+          "1f": "Intense Cold"
         }
       },
       "dryer_cycle": {
@@ -143,12 +148,6 @@
           "180": "3 hr",
           "240": "4 hr"
         }
-      },
-      "ai_energy_level": {
-        "state": {
-          "1": "Level 1",
-          "2": "Level 2"
-        }
       }
     },
     "sensor": {

tests/fixtures/golden/refrigerator_tp1x_ref_21k_us.json

@@ -1,5 +1,6 @@
 {
   "state_keys": [
+    "ai_energy_level",
     "alarm_code",
     "autofill",
     "cooler_setpoint",

tests/fixtures/golden/washer.json

@@ -1,6 +1,8 @@
 {
   "state_keys": [
+    "ai_energy_level",
     "alarm_code",
+    "bubble_soak",
     "buzzer_sound",
     "child_lock",
     "cycle",
@@ -14,9 +16,11 @@
     "energy_saved_kwh",
     "finish_time",
     "firmware_update",
+    "intensive",
     "job_beginning_status",
     "machine_state",
     "power_switch",
+    "pre_wash",
     "progress",
     "progress_percentage",
     "remote_control",

tests/fixtures/golden/washer_dryer_combo.json

@@ -1,6 +1,7 @@
 {
   "state_keys": [
     "alarm_code",
+    "bubble_soak",
     "child_lock",
     "cycle",
     "cycle_active",
@@ -12,9 +13,11 @@
     "energy_kwh",
     "finish_time",
     "firmware_update",
+    "intensive",
     "job_beginning_status",
     "machine_state",
     "power_switch",
+    "pre_wash",
     "progress",
     "progress_percentage",
     "remote_control",

tests/fixtures/washer_device.json

@@ -44,6 +44,21 @@
       "href": "/energy/consumption/0",
       "rep": {}
     },
+    {
+      "href": "/energy/ailevel/vs/0",
+      "rep": {
+        "aiLevel": "0",
+        "supportedAiLevel": [
+          "1"
+        ],
+        "energySavingInfo": [
+          {
+            "aiLevel": "1",
+            "maxEnergySavingRate": "70"
+          }
+        ]
+      }
+    },
     {
       "href": "/course/vs/0",
       "rep": {

tests/test_common_capabilities.py

@@ -130,3 +130,202 @@ class TestEnergyMeter:
         phantom power sensor (the exists_fn replaces the field-presence gate)."""
         pw = next(e for e in common.ENERGY_METER.entities if e.key == 'power_watts')
         assert pw.exists_fn({'x.com.samsung.da.cumulativePower': '5'}, {}) is False
+
+
+# ---------------------------------------------------------------------------
+# AI energy-saving level. '0' is off; supportedAiLevel lists the additional
+# level(s) on offer. A single-entry list (issue #21 fridge, issue #40 washer)
+# is really a binary toggle, so it's exposed as a switch instead of a
+# one-choice select; multiple entries get a select with '0' synthesized back
+# in as the explicit off option (supportedAiLevel never lists '0' itself, but
+# it's a real, observed value of aiLevel).
+# ---------------------------------------------------------------------------
+
+
+def _ai_energy_level_desc(cls_name):
+    return next(e for e in common.AI_ENERGY_LEVEL.entities
+                if e.__class__.__name__ == cls_name)
+
+
+class TestAiEnergyLevelSwitch:
+    def _desc(self):
+        return _ai_energy_level_desc('SwitchDesc')
+
+    def test_href(self):
+        assert common.AI_ENERGY_LEVEL.href == '/energy/ailevel/vs/0'
+
+    def test_shown_only_with_single_supported_level(self):
+        desc = self._desc()
+        assert desc.exists_fn({'aiLevel': '1', 'supportedAiLevel': ['1']}, {}) is True
+        assert desc.exists_fn({'aiLevel': '1', 'supportedAiLevel': ['1', '2']}, {}) is False
+
+    def test_hidden_when_supported_level_is_non_list_scalar(self):
+        """A stray scalar (e.g. a string) must not be len()-checked as if it
+        were a list -- a 2-char string would otherwise wrongly pass `== 1`
+        style checks."""
+        desc = self._desc()
+        assert desc.exists_fn({'aiLevel': '1', 'supportedAiLevel': '1'}, {}) is False
+
+    def test_hidden_when_supported_level_missing(self):
+        desc = self._desc()
+        assert desc.exists_fn({'aiLevel': '1'}, {}) is False
+
+    def test_hidden_when_supported_level_empty_list(self):
+        desc = self._desc()
+        assert desc.exists_fn({'aiLevel': '0', 'supportedAiLevel': []}, {}) is False
+
+    def test_hidden_on_empty_stub_rep(self):
+        desc = self._desc()
+        assert desc.exists_fn({}, {}) is False
+
+    def test_value_fn(self):
+        desc = self._desc()
+        assert desc.value_fn('0') is False
+        assert desc.value_fn('1') is True
+
+    def test_write_on_uses_the_single_supported_level(self):
+        """The on-value is whatever the device calls its one level, not a
+        hardcoded '1'."""
+        desc = self._desc()
+        path, body = desc.write_fn('On', {'supportedAiLevel': ['2']})
+        assert path == ['energy', 'ailevel', 'vs', '0']
+        assert body == {'aiLevel': '2'}
+
+    def test_write_off(self):
+        desc = self._desc()
+        path, body = desc.write_fn('Off', {'supportedAiLevel': ['1']})
+        assert body == {'aiLevel': '0'}
+
+
+class TestAiEnergyLevelSelect:
+    def _desc(self):
+        return _ai_energy_level_desc('SelectDesc')
+
+    def test_shown_only_with_multiple_supported_levels(self):
+        desc = self._desc()
+        assert desc.exists_fn({'aiLevel': '1', 'supportedAiLevel': ['1', '2']}, {}) is True
+        assert desc.exists_fn({'aiLevel': '1', 'supportedAiLevel': ['1']}, {}) is False
+
+    def test_hidden_when_supported_level_is_non_list_scalar(self):
+        desc = self._desc()
+        assert desc.exists_fn({'aiLevel': '1', 'supportedAiLevel': '12'}, {}) is False
+
+    def test_hidden_when_supported_level_missing(self):
+        desc = self._desc()
+        assert desc.exists_fn({'aiLevel': '1'}, {}) is False
+
+    def test_hidden_when_supported_level_empty_list(self):
+        desc = self._desc()
+        assert desc.exists_fn({'aiLevel': '0', 'supportedAiLevel': []}, {}) is False
+
+    def test_no_translation_key(self):
+        """aiLevel's values are plain digits that render fine untranslated
+        (select.py's _display()) -- no strings.json entry to maintain
+        against an unknown number of future levels."""
+        desc = self._desc()
+        assert desc.translation_key is None
+
+    def test_options_synthesize_off(self):
+        """'0' is never in supportedAiLevel but is a real, observed aiLevel
+        value -- synthesized back in as the explicit off option."""
+        desc = self._desc()
+        resources = {'/energy/ailevel/vs/0': {'supportedAiLevel': ['1', '2']}}
+        assert desc.options(resources) == ['0', '1', '2']
+
+    def test_options_empty_when_resource_missing(self):
+        desc = self._desc()
+        assert desc.options({}) == ['0']
+
+    def test_write(self):
+        desc = self._desc()
+        path, body = desc.write_fn('2', {})
+        assert path == ['energy', 'ailevel', 'vs', '0']
+        assert body == {'aiLevel': '2'}
+
+
+class TestAiEnergyLevelStubDoesNotDecideThePlatform:
+    """Issue found in review: entity *creation* runs once, against whatever
+    snapshot is current when platforms are set up (see
+    __init__.py's async_config_entry_first_refresh-before-forward-entry-setups
+    ordering), while flatten() re-evaluates exists_fn every poll against live
+    data. Both descriptors share key='ai_energy_level' (see adapter._key), so
+    if a stub carve-out let one of them win at setup time while the other
+    wins once real data lands, flatten() would feed the already-instantiated
+    entity a value shaped for the other platform (e.g. a bool into a Select
+    expecting a string option). Neither side gets a `not rep` carve-out, so
+    an unfetched stub can never win entity creation for either platform --
+    the entity simply doesn't appear until a reload happens with real data,
+    same as any other exists_fn-gated entity in this codebase that's unlucky
+    on first-poll timing, instead of appearing as the wrong widget type."""
+
+    def test_neither_widget_exists_on_empty_stub_rep(self):
+        switch = _ai_energy_level_desc('SwitchDesc')
+        select = _ai_energy_level_desc('SelectDesc')
+        assert switch.exists_fn({}, {}) is False
+        assert select.exists_fn({}, {}) is False
+
+
+class TestSelfCheckError:
+    """Self-check diagnostic error list -- surfaced on hardware that reports
+    x.com.samsung.da.error, joined into a single display string."""
+
+    def _desc(self):
+        return next(e for e in common.SELF_CHECK.entities if e.key == 'selfcheck_error')
+
+    def test_exists_when_field_present(self):
+        desc = self._desc()
+        assert desc.exists_fn({'x.com.samsung.da.error': ['DA_ERROR_NONE']}, {}) is True
+
+    def test_does_not_exist_when_field_absent(self):
+        desc = self._desc()
+        assert desc.exists_fn({'x.com.samsung.da.status': 'Ready'}, {}) is False
+
+    def test_exists_for_empty_stub_rep(self):
+        """An empty {} rep is /device/0's not-yet-fetched-stub carve-out --
+        must be included-for-now, same as ENERGY_METER's fields."""
+        desc = self._desc()
+        assert desc.exists_fn({}, {}) is True
+
+    def test_value_joins_list(self):
+        desc = self._desc()
+        assert desc.value_fn(['E1', 'E2']) == 'E1, E2'
+
+    def test_value_passes_through_scalar(self):
+        desc = self._desc()
+        assert desc.value_fn('DA_ERROR_NONE') == 'DA_ERROR_NONE'
+
+    def test_value_none_for_empty_list(self):
+        """An empty error list means no value to show -- None (unknown),
+        not an empty string."""
+        desc = self._desc()
+        assert desc.value_fn([]) is None
+
+
+# ---------------------------------------------------------------------------
+# Cross-family bundles (UNIVERSAL / POWER) -- unpacked into every by_type
+# registry's _build([...]) call in place of the hand-duplicated capability
+# lists that used to live there.
+# ---------------------------------------------------------------------------
+
+
+class TestUniversalAndPowerBundles:
+    def test_universal_contains_the_no_conflict_capabilities(self):
+        assert set(common.UNIVERSAL) == {
+            common.ALARMS, common.ENERGY_METER, common.FIRMWARE_UPDATE,
+            common.SELF_CHECK, common.AI_ENERGY_LEVEL,
+            common.KIDS_LOCK_GENERIC, common.KIDS_LOCK_VS_FALLBACK,
+            common.REMOTE_CONTROL_GENERIC, common.REMOTE_CONTROL_VS_FALLBACK,
+        }
+
+    def test_power_kept_separate_for_airconditioners_sake(self):
+        """See common.POWER's own comment for why airconditioner opts out."""
+        assert set(common.POWER) == {common.POWER_GENERIC, common.POWER_VS_FALLBACK}
+
+    def test_no_overlap_between_the_two_bundles(self):
+        assert not (set(common.UNIVERSAL) & set(common.POWER))
+
+    def test_airconditioner_registry_does_not_include_power(self):
+        from custom_components.localthings.registry.by_type import airconditioner
+        bound_caps = {c for caps in airconditioner.REGISTRY.capabilities.values() for c in caps}
+        assert common.POWER_GENERIC not in bound_caps
+        assert common.POWER_VS_FALLBACK not in bound_caps

tests/test_fridge_capabilities.py

@@ -231,84 +231,17 @@ class TestArtik051AndTp2xFixturesHaveCompleteCoverage:
         assert state['flex_zone_mode'] == 'CV_FDR_BEVERAGE'
 
 
-class TestSelfCheckError:
-    """Self-check diagnostic error list -- surfaced on hardware that reports
-    x.com.samsung.da.error, joined into a single display string."""
+class TestRefrigeratorAiEnergyLevelFixtureCoverage:
+    """AI energy-saving level (common.AI_ENERGY_LEVEL, see
+    test_common_capabilities.py) is exercised end-to-end here against the
+    refrigerator fixture/registry.
 
-    def _desc(self):
-        return next(e for e in fridge.SELF_CHECK.entities if e.key == 'selfcheck_error')
-
-    def test_exists_when_field_present(self):
-        desc = self._desc()
-        assert desc.exists_fn({'x.com.samsung.da.error': ['DA_ERROR_NONE']}, {}) is True
-
-    def test_does_not_exist_when_field_absent(self):
-        desc = self._desc()
-        assert desc.exists_fn({'x.com.samsung.da.status': 'Ready'}, {}) is False
-
-    def test_exists_for_empty_stub_rep(self):
-        """An empty {} rep is /device/0's not-yet-fetched-stub carve-out --
-        must be included-for-now, same as ENERGY_METER's fields."""
-        desc = self._desc()
-        assert desc.exists_fn({}, {}) is True
-
-    def test_value_joins_list(self):
-        desc = self._desc()
-        assert desc.value_fn(['E1', 'E2']) == 'E1, E2'
-
-    def test_value_passes_through_scalar(self):
-        desc = self._desc()
-        assert desc.value_fn('DA_ERROR_NONE') == 'DA_ERROR_NONE'
-
-    def test_value_none_for_empty_list(self):
-        """An empty error list means no value to show -- None (unknown),
-        not an empty string."""
-        desc = self._desc()
-        assert desc.value_fn([]) is None
-
-
-class TestAiEnergyLevel:
-    """AI energy-saving level select on /energy/ailevel/vs/0 -- only
-    exposed when the device actually offers more than one level; hardware
-    that only ever reports a single supported level keeps this ignored
-    (see capabilities/ignored.py)."""
-
-    def test_href(self):
-        assert fridge.AI_ENERGY_LEVEL.href == '/energy/ailevel/vs/0'
-
-    def test_hidden_with_single_supported_level(self):
-        desc = fridge.AI_ENERGY_LEVEL.entities[0]
-        assert desc.exists_fn({'aiLevel': '1', 'supportedAiLevel': ['1']}, {}) is False
-
-    def test_shown_with_multiple_supported_levels(self):
-        desc = fridge.AI_ENERGY_LEVEL.entities[0]
-        assert desc.exists_fn(
-            {'aiLevel': '1', 'supportedAiLevel': ['1', '2']}, {}) is True
-
-    def test_exists_for_empty_stub_rep(self):
-        """An empty {} rep is /device/0's not-yet-fetched-stub carve-out --
-        must be included-for-now, same as ENERGY_METER's fields."""
-        desc = fridge.AI_ENERGY_LEVEL.entities[0]
-        assert desc.exists_fn({}, {}) is True
-
-    def test_hidden_when_supported_level_is_non_list_scalar(self):
-        """A stray scalar (e.g. a string) must not be len()-checked as if it
-        were a list -- a 5-char string would otherwise wrongly pass `> 1`."""
-        desc = fridge.AI_ENERGY_LEVEL.entities[0]
-        assert desc.exists_fn(
-            {'aiLevel': '1', 'supportedAiLevel': '12'}, {}) is False
-
-    def test_write(self):
-        desc = fridge.AI_ENERGY_LEVEL.entities[0]
-        path, body = desc.write_fn('2', {})
-        assert path == ['energy', 'ailevel', 'vs', '0']
-        assert body == {'aiLevel': '2'}
+    refrigerator_device.json's supportedAiLevel was extended to two entries
+    (['1', '2']) specifically to exercise the select branch -- the real
+    captured TP1X_REF_21K_US dump only ever reports one entry (switch
+    branch), so the select is synthetic-fixture-only for now."""
 
     def test_synthetic_fixture_has_complete_coverage(self):
-        """refrigerator_device.json's supportedAiLevel was extended to two
-        entries (['1', '2']) specifically to exercise this select -- the
-        real captured TP1X_REF_21K_US dump only ever reports one entry, so
-        this capability is synthetic-fixture-only for now."""
         from custom_components.localthings.registry.adapter import flatten
         from custom_components.localthings.registry.by_type import refrigerator
         from custom_components.localthings.registry.discovery import discover

tests/test_washer_capabilities.py

@@ -251,6 +251,161 @@ class TestDetergentSoftenerDosing:
         assert self._desc('detergent_low').exists_fn(rep, {}) is True
 
 
+class TestWashOptionToggles:
+    """Bubble soak / pre-wash / intensive-wash switches, from the same
+    options[] array as the cycle select (issue #22 follow-up). Confirmed
+    On/Off shape from a dump with Bubble Soak toggled on in the app."""
+
+    @staticmethod
+    def _desc(key):
+        return next(e for e in washer.WASHER_COURSE.entities if e.key == key)
+
+    @staticmethod
+    def _keys():
+        return ('bubble_soak', 'pre_wash', 'intensive')
+
+    @staticmethod
+    def _prefix(key):
+        return {'bubble_soak': 'BubbleSoak',
+                'pre_wash': 'PreWashSetting',
+                'intensive': 'IntensiveSetting'}[key]
+
+    def test_exists_only_when_field_present(self):
+        for key in self._keys():
+            desc = self._desc(key)
+            assert desc.exists_fn({'x.com.samsung.da.options': []}, {}) is False
+            prefix = self._prefix(key)
+            rep = {'x.com.samsung.da.options': [f'{prefix}_Off']}
+            assert desc.exists_fn(rep, {}) is True
+
+    def test_reads_off(self):
+        for key in self._keys():
+            prefix = self._prefix(key)
+            rep = {'x.com.samsung.da.options': [f'{prefix}_Off']}
+            assert self._desc(key).rep_fn(rep) is False
+
+    def test_reads_on(self):
+        for key in self._keys():
+            prefix = self._prefix(key)
+            rep = {'x.com.samsung.da.options': [f'{prefix}_On']}
+            assert self._desc(key).rep_fn(rep) is True
+
+    def test_write_on_and_off(self):
+        """write_fn receives the same 'On'/'Off' string switch.py sends
+        (not a bool) -- covers a bug where an earlier `'On' if p else 'Off'`
+        implementation always wrote 'On', since any non-empty string
+        (including 'Off') is truthy."""
+        for key in self._keys():
+            prefix = self._prefix(key)
+            rep = {'x.com.samsung.da.options': [f'{prefix}_Off', 'GMT_02']}
+            path, body = self._desc(key).write_fn('On', rep)
+            assert path == ['course', 'vs', '0']
+            assert f'{prefix}_On' in body['x.com.samsung.da.options']
+            assert 'GMT_02' in body['x.com.samsung.da.options']
+
+            rep = {'x.com.samsung.da.options': [f'{prefix}_On']}
+            path, body = self._desc(key).write_fn('Off', rep)
+            assert f'{prefix}_Off' in body['x.com.samsung.da.options']
+            assert f'{prefix}_On' not in body['x.com.samsung.da.options']
+
+    def test_write_rejects_non_on_off_payload(self):
+        for key in self._keys():
+            prefix = self._prefix(key)
+            rep = {'x.com.samsung.da.options': [f'{prefix}_Off']}
+            assert self._desc(key).write_fn('bogus', rep) is None
+
+
+# editCourseList and availability bitmaps from the reporter's issue #22
+# follow-up dump (WD90T654DBN/S1, course '30' selected, Bubble Soak just
+# turned on in the app): 24 courses, course '30' at position 1 reads 'F0'
+# (available) on all three bitmaps; course '1C' at position 0 reads '00' on
+# BubbleSoakSet (matching the app graying that control out for Eco 40-60).
+_EDIT_COURSE_RESOURCES = {
+    '/wm/editcourse/vs/0': {
+        'x.com.samsung.da.editCourseList':
+            'EditCourseList_1C301E26361B1D1F253324322022232F212D272838393729',
+    },
+}
+_BUBBLE_SOAK_SET = 'BubbleSoakSet_00F000F000F000F0F0F0F00000F000F0F00000F000000000'
+_PRE_WASH_AVAILABLE_SET = 'PreWashAvailableSet_F0F000F0F0F000F0F0F0F00000F0F0F0F00000F000000000'
+_INTENSIVE_AVAILABLE_SET = 'IntensiveAvailableSet_F0F000F0F0F000F0F0F0F00000F0F0F0F00000F000000000'
+
+
+class TestWashOptionToggleValidation:
+    """validate_fn rejects turning a toggle on for a course whose byte in
+    its availability bitmap isn't 'F0', with a user-facing message switch.py
+    raises as ServiceValidationError -- distinct from write_fn's silent
+    no-op for a malformed payload."""
+
+    @staticmethod
+    def _desc(key):
+        return next(e for e in washer.WASHER_COURSE.entities if e.key == key)
+
+    def test_allowed_on_a_supported_course(self):
+        rep = {'x.com.samsung.da.options': ['Course_30', _BUBBLE_SOAK_SET]}
+        assert self._desc('bubble_soak').validate_fn(
+            'On', rep, _EDIT_COURSE_RESOURCES) is None
+
+    def test_rejected_on_an_unsupported_course(self):
+        rep = {'x.com.samsung.da.options': ['Course_1C', _BUBBLE_SOAK_SET]}
+        msg = self._desc('bubble_soak').validate_fn('On', rep, _EDIT_COURSE_RESOURCES)
+        assert msg == "Bubble soak isn't available on the selected cycle."
+
+    def test_pre_wash_and_intensive_use_their_own_availableset_field(self):
+        rep = {'x.com.samsung.da.options': ['Course_30', _PRE_WASH_AVAILABLE_SET]}
+        assert self._desc('pre_wash').validate_fn(
+            'On', rep, _EDIT_COURSE_RESOURCES) is None
+        rep = {'x.com.samsung.da.options': ['Course_30', _INTENSIVE_AVAILABLE_SET]}
+        assert self._desc('intensive').validate_fn(
+            'On', rep, _EDIT_COURSE_RESOURCES) is None
+
+    def test_turning_off_is_never_blocked(self):
+        rep = {'x.com.samsung.da.options': ['Course_1C', _BUBBLE_SOAK_SET]}
+        assert self._desc('bubble_soak').validate_fn(
+            'Off', rep, _EDIT_COURSE_RESOURCES) is None
+
+    def test_allows_write_when_course_unresolvable(self):
+        """No editCourseList, no Course_ token, or a bitmap whose length
+        doesn't match editCourseList -- in every case, fail open rather than
+        block a write we can't actually verify."""
+        desc = self._desc('bubble_soak')
+        rep = {'x.com.samsung.da.options': ['Course_1C', _BUBBLE_SOAK_SET]}
+        assert desc.validate_fn('On', rep, {}) is None
+
+        rep = {'x.com.samsung.da.options': [_BUBBLE_SOAK_SET]}
+        assert desc.validate_fn('On', rep, _EDIT_COURSE_RESOURCES) is None
+
+        rep = {'x.com.samsung.da.options': ['Course_1C', 'BubbleSoakSet_00F0']}
+        assert desc.validate_fn('On', rep, _EDIT_COURSE_RESOURCES) is None
+
+
+class TestAiEnergyLevel:
+    """Issue #40 -- /energy/ailevel/vs/0 was unbound on a plain washer.
+
+    The capability itself (common.AI_ENERGY_LEVEL) is tested in
+    test_common_capabilities.py; this just confirms it's wired into the
+    washer registry and that the fixture's single-entry supportedAiLevel
+    (['1'], matching the issue's dump) surfaces as a switch, not a select."""
+
+    def test_fixture_has_complete_coverage(self):
+        from custom_components.localthings.registry.adapter import flatten
+        from custom_components.localthings.registry.by_type import washer as washer_registry
+        from custom_components.localthings.registry.discovery import discover
+        from tests.conftest import _load_device
+
+        resources = _load_device('washer')
+        unbound = []
+        bound = discover(
+            resources,
+            washer_registry.REGISTRY.capabilities,
+            washer_registry.REGISTRY.pattern_capabilities,
+            log=unbound.append,
+        )
+        assert unbound == []
+        state = flatten(bound, resources)
+        assert state['ai_energy_level'] is False  # aiLevel '0' -- off
+
+
 class TestFlexWashAndComboFixturesHaveCompleteCoverage:
     """FlexWash (issue #19, previously unrecognized entirely) and
     washer/dryer combo (issue #22, dry_level) dumps must both resolve to