@johanwistbacka/node-red-contrib-sw-light 0.1.4 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.1.9 — Label target development candidate
+
+- Adds Entity/Label targets, stable Label ID autocomplete, and structured `msg.target` overrides; old Entity flows keep their default behavior.
+- Resolves direct entity/device labels and HA's labeled-area relationships, filters non-light/hidden/disabled entries and deduplicates members. Area is not exposed as a target.
+- Extracts the existing light-control path into one controller per entity, preserving independent override, capability filtering, automatic limits and Adaptive Lighting.
+- Adds cached membership, registry/reconnect invalidation, idle refresh and reconciled state observation; close/redeploy cleans node-owned resources.
+- Adds aggregate Label results/status, per-entity partial failures and empty/deleted target events.
+- Documents the APIs, refresh/lifecycle contract and exact physical multi-light verification sequence in `docs/labels.md`.
+- Local check and full tests include the published HA contrib 0.80.3 integration. Real HA/physical-device verification is pending. No npm publication or HA installation.
+
+## 0.1.8 — 2026-09-30
+
+- Simplify Adaptive Lighting to an On/Off checkbox with collapsed advanced profile selection.
+- Use the supported color-only `adaptive_lighting.apply` action with a fresh provider calculation, only after automatic OFF → ON on CT-capable lights. SW Light retains brightness, maximum, override protection and transitions.
+- Explicit message colors and manual commands suppress adaptation; already-on brightness changes do not reapply it. Add `msg.adaptive_lighting` opt-in/out.
+- Discover only unique exact `configuration.lights` matches. Missing, ambiguous, unavailable, running and RGB sleep profiles fall back with structured warnings. Non-CT lights retain normal ON.
+- Require the HA profile main switch off for one-shot ownership. Preserve inactive legacy nodes; migrate former optional-apply opt-in.
+- Document inspected upstream API/source, two-action timing limitations and the exact live verification sequence.
+- Full syntax/editor/example check and 42 tests passed, including all 3 isolated published-provider integration tests. No live HA/device verification or publication.
+
+## 0.1.7 — local default threshold adjustment
+
+- Sets the runtime/editor default manual override threshold to 98% (HA brightness 250 or above), retaining the 94% automatic maximum.
+- Updates example flows and documentation. Existing saved thresholds remain unchanged.
+- Verifies the new default boundary and release below threshold; preserves explicit 100% threshold coverage.
+- No npm publication.
+
+## 0.1.6 — local HA state normalization fix
+
+- Omits null/non-array observed HA color attributes instead of spreading them, preventing `a[k] is not iterable` during observation and commands.
+- Keeps valid color arrays as independent copies; retains brightness and manual override behavior.
+- Adds null/non-array normalization coverage and exercises all three override regressions with null HA color attributes.
+- Full checks and isolated Node-RED/HA contrib integration: 33 tests passed. No npm publication; physical-device verification pending.
+
+## 0.1.5 — local override fix candidate
+
+- Starts per-light HA observation after flow startup, before the first input.
+- Retries temporary provider initialization failures without freezing the node; preserves the shared-client/readiness adapter.
+- Fixes idle OFF nodes missing external brightness changes: observed 255 activates override, observed 204 releases the default threshold, and explicit manual OFF bypasses the guard.
+- Adds real-adapter regressions for automatic 94% → external 100% → suppressed OFF, external 80% release, manual OFF, and entity isolation.
+- Full suite including isolated Node-RED/HA contrib 0.80.3 integration: 32 tests passed. Physical-device verification of this candidate is pending. No npm publication.
+
 ## 0.1.4 — scoped distribution candidate
 
 - Changes npm identity to `@johanwistbacka/node-red-contrib-sw-light`.

package/README.md

@@ -1,7 +1,7 @@
-# SW Light — v0.1.4
+# SW Light — v0.1.9
 
-A reusable Node-RED node for one Home Assistant `light.*` entity. Select an
-existing HA server, select a light, deploy in a **development** environment,
+A reusable Node-RED node for a Home Assistant `light.*` Entity or Label. Select an
+existing HA server, select a target, deploy in a **development** environment,
 and select Action **On**, **Off**, **Toggle**, or **From msg**. Display name:
 **SW Light**; flow type: `sw-light`.
 
@@ -10,12 +10,39 @@ selected light, checks manual override and calls the HA light service itself.
 No external HA Action node is required; the two outputs are for observation
 and integration only. With a fixed Action, a normal timestamp Inject is enough.
 
+## Label targets in 0.1.9
+
+Choose **Target → Entity** (the default, including existing flows) or **Label**.
+Label autocomplete displays the HA name and stores the stable Label ID. Current
+members are resolved from entity, device and labeled-area registry relationships;
+non-lights are excluded and duplicate light IDs are removed. Area is not a target
+choice in this version.
+
+Each resolved light reuses the same controller with independent override,
+capabilities, brightness limits and Adaptive Lighting. One overridden/unavailable
+member does not stop the others. Output 1 for Labels contains `target`,
+`resolved_entity_ids`, per-light `results` and success/skipped/failure/manual counts;
+output 2 identifies the actual entity for per-light events. Status aggregates
+last observed states.
+
+Membership refreshes on provider registry/reconnect events and a 30-second cache
+expiry/idle reconciliation fallback. One filtered state subscription per node is
+reconciled without per-light subscription leaks. Optional `msg.target =
+{type: "label", id: "label_id"}` or `{type: "entity", id: "light.example"}` overrides
+configuration for one input; that target remains observed until the next input.
+Departed target members discard their controller's explicit latch.
+
+See [Label architecture, API evidence and exact multi-light test sequence](docs/labels.md).
+This is a local development candidate; no npm publication or HA installation is
+part of its preparation. Physical Label behavior still needs the documented test.
+
 ## Package identity and migration
 
 The permanent npm package name is `@johanwistbacka/node-red-contrib-sw-light`.
 The Node-RED type stays `sw-light` and its display name stays **SW Light**.
-The scoped package starts at version 0.1.4; version numbers are independent
-for each npm package name. No runtime/editor or HA integration behavior changes.
+The scoped package started at version 0.1.4; version numbers are independent
+for each npm package name. Version 0.1.5 fixes observation before the first command; 0.1.6 also tolerates
+null/non-array observed HA color attributes.
 
 If upgrading from the old unscoped `node-red-contrib-sw-light`, export your
 flows first. Remove the old package from the Node-RED user directory before
@@ -25,7 +52,7 @@ or, with Node-RED stopped, run these commands in its user directory:
 
 ```sh
 npm uninstall node-red-contrib-sw-light
-npm install @johanwistbacka/node-red-contrib-sw-light@0.1.4
+npm install @johanwistbacka/node-red-contrib-sw-light@0.1.9
 ```
 
 Restart Node-RED and reload the editor. Existing flow nodes retain type
@@ -51,7 +78,7 @@ are enabled. Test with a development light before relying on this node.
 After this version is published, install it in your Node-RED user directory:
 
 ```sh
-npm install @johanwistbacka/node-red-contrib-sw-light@0.1.4
+npm install @johanwistbacka/node-red-contrib-sw-light@0.1.9
 ```
 
 After publication, the current development release is available under npm latest:
@@ -74,7 +101,7 @@ For edits, use npm's local directory installation/link or reinstall an archive
 created with `npm pack`. Restart the isolated Node-RED runtime after changes.
 There is no build step or additional runtime dependency.
 
-The current development release uses the normal SemVer version `0.1.4` and
+The current development release uses the normal SemVer version `0.1.9` and
 npm tag `latest` for Node-RED compatibility. This version remains experimental;
 it is not a SemVer prerelease. Every installation/publication candidate needs a
 unique version. Use `npm version patch --no-git-tag-version` for the next normal
@@ -86,7 +113,7 @@ After publication, submit the package through the
 [Node-RED Flow Library](https://flows.nodered.org/add/node), or request a refresh
 if it is already listed.
 
-## Temporary runtime diagnostics in 0.1.4
+## Temporary runtime diagnostics in 0.1.9
 
 This build logs `[SW Light debug]` at construction and on the first input,
 then when the relevant structure/readiness changes. It reports version,
@@ -96,7 +123,7 @@ It never logs server IDs, entity IDs, credentials, hosts, full objects or state
 snapshots. Provider initialization errors are reduced to a generic message.
 
 After installation, restart Node-RED and verify a log line containing
-`[SW Light debug] version=0.1.4`. Inject once and retain the prefixed lines,
+`[SW Light debug] version=0.1.9`. Inject once and retain the prefixed lines,
 along with any error/stack. Those lines distinguish missing configuration,
 a missing provider client and a connected client with unexpected methods.
 The real installation problem remains unverified until this build is tested
@@ -119,11 +146,10 @@ there is no `require.cache` scan or search for alternate package copies.
 | On/off transition | 1s each | Sent only with light transition capability |
 | Manual override | Enabled | Pause automatic commands while override is active |
 | Detection | Brightness threshold + flag | Alternative: explicit flag only |
-| Threshold | 100% | Lamp brightness at/above this value activates override |
-| Color mode | Adaptive Lighting | No configured color sent during ordinary ON |
-| Adaptive discovery | Enabled | Unique membership match in switch attributes |
-| Adaptive apply on ON | Disabled | Optional color-only `adaptive_lighting.apply` |
-| Respect adaptive manual control | Enabled | Skip apply when light is manually controlled |
+| Threshold | 98% | Lamp brightness at/above this value activates override |
+| Color mode | Keep current | Normal behavior and fallback |
+| Adaptive Lighting | Off | Current temperature once on automatic OFF → ON |
+| Advanced profile | Automatic | Unique exact light membership; explicit selection if ambiguous |
 
 Require `minimum <= on brightness <= automatic maximum`. When threshold
 detection is enabled, automatic maximum must be below the threshold.
@@ -180,6 +206,7 @@ validated**, even those that lose precedence.
 | `rgbww_color`, `rgbw_color`, `rgb_color` | Arrays of 5, 4, 3 integer bytes 0–255 |
 | `hs_color`, `xy_color`, `color_name` | [0–360,0–100], [0–1,0–1], HA color name |
 | `transition` | 0–3600 seconds |
+| `adaptive_lighting` | Boolean; overrides Adaptive Lighting for one command |
 
 The complete color precedence follows the table top to bottom. `color_name`
 is passed to HA for name resolution/validation, only on a color-capable lamp.
@@ -210,15 +237,21 @@ This hard guard requires brightness exactly **255/255**, so 94%, 95%, 99% and
 is disabled or set to explicit-only. Lowering the light below 255 allows
 automatic control again unless an additional configured override is active.
 
-Threshold detection observes HA state, not requested brightness. The configured
-threshold is converted to a byte; default 100% means exactly 255, not 254 rounded
-for display. With defaults, automation uses 1–94%, and observed 100% activates
+Threshold detection observes HA state, not requested brightness. Each node starts
+its state subscription after flow startup, before its first command, and retries
+temporary provider initialization failures. This includes separate ON/OFF nodes
+for the same physical light. The configured
+threshold is converted to a byte; default 98% means brightness 250 or above.
+With defaults, automation uses 1–94%, and observed brightness at/above this threshold activates
 override. It pauses **all automatic commands**, including ON, OFF, toggle and
 brightness zero, so an automatic ON cannot accidentally lower and release a
 manual setting. A manually lowered observed brightness releases the threshold
 flag. OFF releases all flags. Missing/unknown/unavailable state preserves flags
 and rejects commands.
 
+Existing nodes retain their saved threshold. Change a saved 100% threshold to
+98% manually to use the new default behavior.
+
 An explicit latch is independent of the threshold. It persists until explicit
 release or observed OFF. A release flag clears both flags for its command;
 subsequent threshold observations can reactivate override. Flags are in memory,
@@ -228,49 +261,112 @@ detection. `source` is the v0.1 command-origin contract.
 
 ## Adaptive Lighting
 
-Ordinary ON in Adaptive mode sends brightness and supported transition, **no
-color or temperature**. Adaptive Lighting retains ownership of color. A message
-color explicitly overrides that behavior for one command, and suppresses optional
-apply even when the color is unsupported and filtered.
-
-Manual switch selection takes precedence. Discovery uses the light's exact
-membership in `attributes.configuration.lights` or `attributes.lights` on
-switch entities with adaptive-like attributes. It only selects one unique
-candidate; it does not infer names or configure HA. This is best-effort attribute
-discovery, not a registry-backed guarantee that a switch belongs to the integration.
-No actual installation was available for validating its attribute schema.
-Use the switch picker/manual entity ID when discovery fails or is ambiguous.
-
-Optional apply runs **after** successful turn-on, only for an enabled selected
-switch, without explicit message color. It calls `adaptive_lighting.apply` with
-`adapt_brightness: false`, `adapt_color: true`, `turn_on_lights: false`. It respects
-`manual_control` / `manual_control_color` lists by default and never clears them,
-turns on an adaptive switch or changes integration settings. No discovery is
-required when apply is disabled: the ordinary HA light action works on its own.
-An apply failure emits output 2 with `phase: "adaptive_apply"` and
-`light_service_completed: true`; the successful light result still emits.
-
-Adaptive Lighting may interpret explicit brightness commands as manual control
-depending on its own `take_over_control` and related settings. Its background
-brightness adaptation may also exceed this node's maximum; the ceiling only
-applies to **SW Light's outgoing commands**. Configure the integration's own
-brightness limits/ownership in your dev environment and test that combination.
-SW Light never repeatedly corrects brightness or fights its adaptation.
-
-## Test the updated 0.1.4 in your HA Node-RED installation
+The primary editor control is **Adaptive Lighting: On / Off** (off for new nodes).
+Color mode independently defines normal/fallback color behavior; the default is
+Keep current. Advanced profile selection is collapsed. Discovery selects only
+one exact light-membership match in a main switch's `configuration.lights`.
+No entity names or undocumented `lights` attributes are guessed. Configuration
+attributes must be exposed in HA (`include_config_in_attributes`) for discovery;
+otherwise select the main switch explicitly. Multiple matches never choose the
+first profile. Group membership expansion is not performed.
+
+Keep the selected Adaptive Lighting **main switch OFF** to use its calculation
+without continuous control or ON interception. The supported `adaptive_lighting.apply`
+action works with that switch off and calculates fresh values for every call.
+SW Light never toggles that switch, changes profile settings, clears manual
+control or starts a continuous adaptation loop. Choose a profile using
+color-temperature sleep color; RGB sleep profiles are rejected with a warning.
+
+Precedence for each command:
+
+1. Explicit message color/temperature wins, including unsupported color that
+   is omitted with an event. It always suppresses Adaptive Lighting.
+2. Otherwise, Adaptive Lighting runs only after a successful automatic OFF → ON
+   service, on a color-temperature-capable light.
+3. Otherwise, normal configured SW Light color behavior applies.
+4. Keep current/lamp default omit color and leave normal HA/device behavior.
+
+`msg.adaptive_lighting` (boolean) overrides the checkbox for that command.
+Brightness, automatic maximum, override protection and fade stay with SW Light.
+An already-ON brightness command, manual command, OFF or zero-brightness command
+never invokes Adaptive Lighting. Configured fixed color still follows normal
+SW Light behavior on these commands. Legacy adaptive flows with optional apply
+already enabled retain their opt-in; former inactive adaptive flows stay off.
+Legacy discover/respect-manual controls are retired.
+
+After `light.turn_on`, SW Light calls `adaptive_lighting.apply` for exactly one
+light with `adapt_brightness: false`, `adapt_color: true`, `prefer_rgb_color: false`,
+`turn_on_lights: true`, and the SW Light command transition (0 if unsupported).
+The true flag avoids silently skipping color when HA has not yet observed the
+successful ON. Adaptive Lighting clamps temperature to the light's range.
+The two actions are not atomic: a brief initial/default color may be visible,
+and an external OFF between them can race with the second action. Service
+acknowledgement reports an accepted action, not physical temperature confirmation.
+
+Missing/unavailable/ambiguous/running profiles, a missing apply action or its
+failure emit output 2 `warning`, with `phase: "adaptive_apply"`, structured
+`reason`, and `light_service_completed: true`. Normal ON and output 1 survive,
+retaining the configured color fallback. Non-CT lights emit `unsupported` and
+still turn on without temperature parameters. A running HA profile or other
+external automation can still alter lights independently; turn those off for
+this ownership model. SW Light cannot cancel their behavior.
+
+Investigation: [upstream apply documentation](https://adaptive-lighting.nijho.lt/services/)
+and [source inspected on 2026-09-30](https://github.com/basnijholt/adaptive-lighting/blob/283fec08ae7d34901d13c32e91fb001f92395fe7/custom_components/adaptive_lighting/switch.py).
+The main switch exposes last calculated `color_temp_kelvin` when on, but null
+when off; reading that cache cannot deliver the requested fresh calculation.
+`apply` recalculates in `prepare_adaptation_data` even while off. No dedicated
+read-only temperature calculation service is exposed. Calculations remain in
+Adaptive Lighting, including sun/time and sleep settings.
+
+### Real-world verification
+
+1. Install the local 0.1.9 archive, restart Node-RED, and verify its startup
+   version. Use a test light with `color_temp` support. Connect both outputs to Debug.
+2. In HA, expose the profile's configuration attributes for automatic discovery
+   (or select it under Advanced). Keep its main switch off, use color-temperature
+   sleep color, and disable any other automatic controllers for this test light.
+3. In SW Light select Action On, brightness/max 94%, Keep current, Adaptive Lighting
+   On. Turn the light off in HA and wait until Node-RED observes OFF. Trigger ON.
+4. Verify `adaptive.applied: true` and brightness 239/255 (about 93.7%). After the
+   fade, inspect HA light state and physically check the light. To get a comparison
+   value while the profile is off, call HA's `adaptive_lighting.apply` yourself
+   with the same profile/light, brightness false, color true, RGB preference false,
+   turn-on true and transition 0; verify the light's temperature stays the same
+   (allow calculation changes around a time boundary and device rounding).
+5. Turn the light off and wait for OFF. Repeat at another time, or toggle the
+   profile's sleep-mode helper with a distinct configured sleep temperature.
+   Trigger ON; verify the new value rather than the previous temperature is used.
+   Restore the sleep helper after testing.
+6. While ON, send another automatic ON with `brightness_pct: 80`. Verify brightness
+   changes and `adaptive.applied: false`; with Keep current, temperature stays put.
+7. From OFF, send ON with `color_temp_kelvin: 3000`, then a supported explicit
+   color command. Verify each wins and no adaptive action runs. Try a manual ON
+   and verify the same suppression.
+8. Set brightness to 100% externally. Automatic OFF must remain blocked. Lower
+   below the configured threshold and verify OFF works again.
+9. Test missing/ambiguous profiles, the main switch ON, and a non-CT light. Confirm
+   normal ON plus the corresponding warning/unsupported event. Redeploy/reconnect
+   and verify fresh discovery, safe observation and no duplicate adaptive calls.
+
+Actual Adaptive Lighting version, exposed configuration, sleep behavior, lamp
+latency/rounding and the two-action race still require verification on your HA
+installation. Automated tests mock that service boundary, not its algorithm.
+
+## Test the updated 0.1.9 in your HA Node-RED installation
 
 1. Save/export your current test flow. Transfer the rebuilt local
-   `johanwistbacka-node-red-contrib-sw-light-0.1.4.tgz` to the Node-RED host. Check that HA contrib
+   `johanwistbacka-node-red-contrib-sw-light-0.1.9.tgz` to the Node-RED host. Check that HA contrib
    is 0.80.3; do not upgrade it for this task.
 2. In a terminal for that Node-RED instance, find **User directory** in its
    startup log. Change to that directory (not a global npm directory) and run
-   `npm install ./johanwistbacka-node-red-contrib-sw-light-0.1.4.tgz --ignore-scripts --no-audit --no-fund`.
+   `npm install ./johanwistbacka-node-red-contrib-sw-light-0.1.9.tgz --ignore-scripts --no-audit --no-fund`.
    Use the add-on's supported local package installation mechanism if its terminal
    does not expose that user directory/npm. Restart Node-RED/the Node-RED add-on
    and reload the editor so the updated runtime and HTML are both loaded.
 3. Add a timestamp Inject directly into SW Light. Choose your **existing HA
    server**, one `light.*` entity, Action **On**, and the desired On brightness
-   (94% by default). Keep optional Adaptive apply disabled for this basic test.
+   (94% by default). Keep Adaptive Lighting off for this basic test.
    Remove downstream HA Action nodes; leave outputs unconnected or use Debug.
 4. Deploy. SW Light constructs without resolving HA and initially shows
    `HA NOT READY`. With the light OFF, click Inject: the light should turn on at the
@@ -279,7 +375,7 @@ SW Light never repeatedly corrects brightness or fights its adaptation.
 5. Set the lamp to 100% manually in HA (verify attribute `brightness: 255`).
    Try On, Off and Toggle: no automatic light service should run, and the node
    should show `MANUAL · 100% · BLOCK ...`. Lower the light manually to 94%, 95%
-   or 99%, then retry; automatic control should resume with default override settings.
+   then retry; automatic control should resume with default override settings.
 6. Select **From msg** and use Inject properties `action` (string) with `on`,
    `off` and `toggle`. Also test `auto_light.action` when top-level action is
    absent. A missing/invalid action should show an error, emit output 2, and
@@ -310,13 +406,14 @@ Output 1 follows successful light service acknowledgement:
     "service_data": { "brightness": 115, "transition": 1 },
     "ignored_conflicts": [], "state_confirmation": "last_observed",
     "observed_at": "2026-09-30T10:00:00Z",
-    "adaptive": { "entity_id": null, "active": false, "manual_control": false, "state": null }
+    "adaptive": { "entity_id": null, "active": false, "state": null, "candidates": [], "applied": false, "reason": "not_requested" }
   }
 }
 ```
 
-`adaptive_lighting` means **configured mode**. `adaptive.active` means a resolved
-switch is ON. `adaptive.applied` is present when optional apply is evaluated.
+`adaptive_lighting` means the command's effective enablement (message overrides node).
+`adaptive.active` means a resolved profile is available with its main switch OFF.
+`adaptive.applied` reports successful action acknowledgement, not measured Kelvin.
 The state is the **last observed HA snapshot**, possibly preceding the action
 or an unfinished transition. Service acknowledgement does not confirm a physical
 lamp change. No requested value is fabricated as observed state. The first input
@@ -357,7 +454,7 @@ Output 2 has a stable versioned event envelope:
 ```
 
 Types: `manual_override`, `override_released`, `unavailable`, `unsupported`,
-`error`. Details include `reason`, `parameters`, `message`, `phase` as applicable.
+`warning`, `error`. Details include `reason`, `parameters`, `message`, `phase` as applicable.
 Unsupported parameters are omitted and the supported action still runs.
 Blocked commands emit only output 2. Invalid input and transport failures also
 call Node-RED `done(error)` for Catch-node handling. Connection/state events have
@@ -381,7 +478,7 @@ npm pack --dry-run
 Run these checks from the source checkout; test tooling is not included in the npm package.
 Tests use Node's built-in test runner without HA or npm dependencies. They cover
 numeric ranges, precedence, max/min, manual override, color translation,
-unsupported capabilities, adaptive discovery/manual control, runtime outputs,
+unsupported capabilities, one-shot adaptive discovery/fallback, runtime outputs,
 async errors, reconnect readiness and listener cleanup. The source checkout retains a separate development integration report; it is
 excluded from the public npm package. Importable examples are in `examples/`; select your
 own HA server and light before deploying them in a dev instance.
@@ -395,14 +492,14 @@ own HA server and light before deploying them in a dev instance.
 - A v0.1 raw state subscription receives all state changes and filters locally;
   one is created per SW Light node. It is removed on close, and HA's websocket
   resubscription handles reconnects. Sharing subscriptions is a v0.2 improvement.
-- Adaptive attributes are not standardized. Existing manual-control detection
-  and automatic brightness ownership require testing with the actual integration.
+- Adaptive discovery requires exposed configuration and exact light membership.
+  Use Advanced selection when discovery is unavailable; verify the installed profile.
 - Keep current depends on HA/device behavior. Color gamut correction and XY to
   other color-space conversion are not implemented. ON/OFF lights remain usable
   without brightness/color capabilities.
 
 Before live use, test server selection/autocomplete, each lamp capability,
-external brightness changes, threshold/explicit release, adaptive takeover,
+external brightness changes, threshold/explicit release, adaptive one-shot behavior,
 long transitions, deletion/unavailability, reconnect and repeated redeployment
 in your real editor with a development light. No live deployment, global config
 change, npm publication or GitHub release is part of this implementation.

package/docs/labels.md

@@ -0,0 +1,198 @@
+# Label targets — 0.1.9 development candidate
+
+## Investigated APIs and membership
+
+The installed/published HA contrib **0.80.3** artifact was inspected, including
+`Websocket.send`, `subscribeMessage`, registry collections, registry event names,
+private editor selector and HTTP routes. It already owns registry subscriptions
+but does not expose a public custom-node Label selector or Label HTTP endpoint.
+SW Light continues to share its authenticated client through the existing adapter.
+No separate connection, credentials or provider shutdown are introduced.
+
+HA official WebSocket commands used:
+
+- `config/label_registry/list`: `label_id`, human-readable `name`.
+- `config/entity_registry/list`: `entity_id`, `labels`, `device_id`, `area_id`,
+  `hidden_by`, `disabled_by`, `entity_category`.
+- `config/device_registry/list`: `id`, `labels`, `area_id`.
+- `config/area_registry/list`: `area_id`, `labels`.
+
+Membership follows HA 2026.9 service target semantics: directly labeled entities,
+entities of directly labeled devices, and entities reached through labeled areas.
+An entity's explicit area takes precedence over its device's area. A label on a
+parent device is not inherited through `via_device_id`. Hidden entries are excluded;
+indirect device/area expansion excludes config/diagnostic entities, whereas a
+directly labeled entity may have a category. SW Light additionally excludes disabled
+entries and non-`light.*` IDs, and deduplicates the final list. These are registry
+entities; SW Light does not expand a light group's members or custom integration
+relationships. A `light` group can therefore coexist with its physical members;
+avoid putting both in the test Label if independent physical control is required.
+
+Primary sources:
+
+- [HA Labels](https://www.home-assistant.io/docs/organizing/labels/)
+- [HA 2026.9.0 target resolution](https://github.com/home-assistant/core/blob/2026.9.0/homeassistant/helpers/target.py)
+- [HA WebSocket API](https://developers.home-assistant.io/docs/api/websocket/)
+- [HA contrib 0.80.3](https://www.npmjs.com/package/node-red-contrib-home-assistant-websocket/v/0.80.3)
+
+Area relationships are necessary for Label semantics. **Area is not an exposed
+target type**, and no Area/Room configuration, occupancy, scene or mode logic is added.
+
+## Architecture and editor
+
+`targets.js` validates `{type,id}`, resolves registry membership and builds aggregate
+status. `controller.js` owns the existing execution path, one Override detector per
+entity, command planning, capability filtering and Adaptive Lighting. `sw-light.js`
+coordinates controllers and output. `ha-adapter.js` alone knows provider internals.
+Adding a future Area branch to target validation/resolution will reuse these same
+controllers; it does not require another light-control implementation.
+
+Target choices are **Entity** (default) and **Label**. Missing `targetType` in old
+flows means Entity; `entityId` and old outputs/status remain compatible. Label uses
+`labelId`, a stable HA ID. Autocomplete displays `name (label_id)` and a separate
+name helper; it stores only the ID. Changing server aborts requests and ignores
+obsolete responses. Cancel/save destroys autocompletes and handlers.
+
+Entity autocomplete still uses HA contrib's `homeassistant/states` route. Label
+uses `/sw-light/labels/:serverId`, protected by Node-RED `server.read`, fetching
+`config/label_registry/list` through the shared adapter. A deployed connected server
+is required for suggestions; entering a known stable Label ID remains possible.
+
+## Refresh, subscriptions and overrides
+
+A node caches an immutable registry snapshot for **30 seconds**. Resolved lists are
+cached per snapshot and Label ID, so repeated brightness inputs do not rescan all
+registries. Provider events `labels_updated`, `entity_registry_updated`,
+`devices_updated`, `areas_updated` invalidate the snapshot and debounce reconciliation
+by 100 ms. The provider itself throttles registry updates. Ready/connect/state-loaded
+and disconnect events also invalidate it. A 30-second timer reconciles idle nodes,
+providing a fallback if an update event is missed; commands refresh expired snapshots.
+An invalidated in-flight snapshot is rejected rather than installed as fresh data.
+
+There is **one raw state_changed subscription per node**, with a reconciled Set of
+member IDs, rather than a subscription for every light. Departed IDs stop updating
+that node; added IDs get their own controller. Remaining controllers retain their
+explicit/threshold flags. Removed controllers are discarded; rejoining lights start
+with fresh flags and observe their actual state. Registry resolution failure clears
+the watched membership and reports TARGET UNAVAILABLE; existing controllers are
+retained until successful reconciliation. No stale members receive a command.
+
+The shared WebSocket library handles reconnect resubscription. Closing/redeploying
+removes this node's listeners, subscription, timers and controllers; it leaves the
+provider's listeners and connection intact. Close during an in-flight service prevents
+later light/adaptive calls and output from that node.
+
+`msg.target = {type:"label", id:"cozy"}` or
+`msg.target = {type:"entity", id:"light.example"}` overrides configuration for that
+input. Its members remain observed until the next input; an input without `target`
+restores configured targeting. Reconciliation discards controllers that leave the
+active target, including their explicit latch. Use a stable target when retaining
+explicit latches across commands. Unknown types, including Area, fail validation.
+
+Each light retains independent state, automatic maximum, capability filtering,
+override flags and Adaptive eligibility. With max 94%, threshold 98%, window 94%,
+table 100% and floor 70%, automatic OFF controls window/floor and skips table only.
+Lowering table below threshold releases table only. Explicit latches still require
+explicit release or observed OFF; manual-source commands keep their existing bypass.
+The brightness-255 guard remains independent of the configured detector.
+
+ON/OFF-only lights receive no brightness/color parameters. RGB, CT, brightness-only
+and transition support are inspected per actual entity. Unsupported parameters emit
+entity-specific events and are omitted. A member's range/transport/availability error
+does not prevent later members from running.
+
+Adaptive Lighting behavior remains unchanged: eligible automatic observed OFF → ON
+first executes the light action, then applies one-shot CT adaptation for that light
+only. Profile discovery uses that light's exact configuration membership. Unsupported
+members turn on normally; missing/running/ambiguous profiles or failed apply emit
+warnings while the successful light action stays successful. No solar algorithm is
+copied or shared between members.
+
+## Outputs and status
+
+Entity output 1 retains the prior normalized result; blocked Entity commands still
+emit their event without a result. Label output 1 retains the incoming message and
+adds `sw_light` with `version:1`, `target:{type,id}`, `resolved_entity_ids`, `results`
+and `counts:{succeeded,skipped,failed,manual}`. Each result identifies `entity_id`,
+observed state/override and its outcome. Successful results include service data and
+Adaptive details; skipped results explain manual override; failed results contain
+error type/message and whether the light action completed. Adaptive warnings alone
+are not counted as light-action failure.
+
+Success means service completion, **not confirmed physical state**. Output and Label
+status use last observed HA states. The aggregate can show `2 on · 1 manual · 2 off`
+or `4 on · 1 unavailable`; manual members are counted separately from automatic ON.
+Empty Labels emit `target_empty`, an empty aggregate and LABEL EMPTY. Deleted Labels
+or missing registries emit `target_resolution_failure`, TARGET UNAVAILABLE and Catch
+error handling, without controlling old members. Per-member partial failure returns
+an aggregate and entity-specific output 2 events without failing the whole input.
+
+## Exact real-world verification sequence
+
+This sequence is pending; do it after separately authorizing/installing the local
+candidate in your development HA/Node-RED environment.
+
+1. Export the test flow and note the currently installed version. Restart Node-RED
+   after installing 0.1.9, reload the editor and verify the startup `version=0.1.9`.
+   Keep one old Entity node in the flow and confirm it operates without reconfiguration.
+2. Create one HA Label named **SW Light test**, record its generated stable ID, and
+   use physical test lights (not a group entity): a dimmable CT light A, an RGB or
+   brightness-only light B, and an ON/OFF light C where available. Add A directly,
+   B through its device, and C directly. Also add one sensor. If A's device is shared
+   with other lights, labeling it deliberately includes those primary lights too.
+3. Select Target **Label**, choose SW Light test by name, save/reopen and verify the
+   stable ID remains selected. Configure From msg, brightness/max 94%, threshold 98%,
+   1-second fades. Connect both outputs to complete-message Debug nodes.
+4. Start all members OFF. Inject `{action:"on"}`. Confirm all physical members turn
+   on; A/B receive at most 94%, C receives plain ON. Check IDs, independent service
+   data, success counts and subsequent observed aggregate status.
+5. Set A to approximately 94%, B to 100% manually in HA, and leave C ON. Wait for
+   output 2's B `manual_override` event. Inject `{action:"off"}`. A and C must turn
+   OFF while B remains ON; aggregate must show B skipped/manual and two successes.
+   Optionally use three dimmable lights with values 94/100/70 to match the exact example.
+6. Lower B to 70% through HA and wait for its `override_released`. Inject automatic
+   ON and OFF; B now follows both. Raise A to 100%, leave B below threshold, repeat
+   OFF and confirm only A is protected. Inject `{action:"off",source:"manual"}` and
+   confirm the manually overridden member also turns OFF.
+7. Start A/B/C OFF. Enable Adaptive Lighting on SW Light and keep the relevant
+   profile main switch OFF, CT sleep color configured, configuration attributes
+   enabled. Inject ON. Confirm A receives its own one-shot CT apply while B/C turn on
+   normally. Verify no Adaptive brightness change, correct per-light profiles and
+   warnings for unsupported members. Already-ON brightness changes must not reapply.
+8. Add a fourth physical light D to the same Label while the node is idle. Wait for
+   reconciliation (normally provider event delay + 100 ms; fallback about 30 seconds)
+   and confirm D appears in status/next result. Remove C; changing C in HA must no
+   longer produce events for this node. No flow edit should be necessary.
+9. Label A's device as well as A directly; confirm A appears once. Where convenient,
+   label a test area with the same Label and verify the documented area precedence
+   and extra primary lights. Remove that area assignment afterward.
+10. Make B unavailable through the test device/integration's normal controls. Inject
+    automatic ON/OFF. Available members must still succeed; output identifies B as
+    failed/unavailable. Restore B and verify recovery.
+11. Disconnect/reconnect the HA connection in the development environment, then send
+    a fresh command after ready. Verify refreshed membership, external override
+    observation and no duplicate events. Redeploy only the SW Light node, then remove
+    it; confirm removed nodes no longer emit events/status or light actions.
+12. Remove all light assignments while retaining the Label/sensor: expect LABEL EMPTY
+    and no calls. Delete the Label: expect target_resolution_failure and no old calls.
+    Recreate a Label and select its actual new ID; do not assume the name restores identity.
+
+Still requires real HA verification: actual registry permissions/schema on the
+installed HA version, rendered autocomplete/save/reopen, physical service/state timing,
+live membership update latency, real network reconnect/redeploy and Adaptive profile
+behavior. Local tests simulate transport and never connect to or install into HA.
+
+## Changed files and local checks
+
+Runtime/editor: `nodes/sw-light.js`, `nodes/sw-light.html`, `lib/light.js`,
+`lib/ha-adapter.js`, new `lib/controller.js`, new `lib/targets.js`.
+Package/documentation: `package.json`, `README.md`, `CHANGELOG.md`,
+`docs/integration.md`, new `docs/labels.md`.
+Tests: `test/published-integration.test.js`, new `test/targets.test.js`,
+`test/label-runtime.test.js`, `test/label-adapter.test.js`, `test/label-editor.test.js`.
+Existing Adaptive Lighting implementation and example flows are unchanged.
+
+`npm run check` passed. Full suite with the isolated 0.80.3 installation enabled:
+**65 tests passed, zero failures/skips**. Version is prepared through
+`npm version 0.1.9 --no-git-tag-version`. No Git repository exists in this workspace;
+no commit/tag/release/publication/HA deployment is part of this candidate.

package/examples/basic.json

@@ -139,7 +139,8 @@
         "sw-example-basic-events"
       ]
     ],
-    "action": "msg"
+    "action": "msg",
+    "overrideThreshold": 98
   },
   {
     "id": "sw-example-basic-result",

package/examples/manual-adaptive.json

@@ -11,7 +11,7 @@
     "type": "comment",
     "z": "sw-example-manual-adaptive",
     "name": "Select HA server + light in SW Light before deploy",
-    "info": "Adaptive apply is off by default. Select your Adaptive Lighting switch and enable optional color-only apply if desired.",
+    "info": "Adaptive Lighting is off by default. Enable the checkbox for automatic OFF to ON; keep the HA profile main switch off. Advanced selection is only needed when discovery is ambiguous or unavailable.",
     "x": 350,
     "y": 60,
     "wires": []
@@ -193,7 +193,8 @@
         "sw-example-manual-adaptive-events"
       ]
     ],
-    "action": "msg"
+    "action": "msg",
+    "overrideThreshold": 98
   },
   {
     "id": "sw-example-manual-adaptive-result",