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

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.

package/README.md

@@ -1,7 +1,7 @@
-# SW Light — v0.1.8
+# 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,6 +10,32 @@ 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`.
@@ -26,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.8
+npm install @johanwistbacka/node-red-contrib-sw-light@0.1.9
 ```
 
 Restart Node-RED and reload the editor. Existing flow nodes retain type
@@ -52,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.8
+npm install @johanwistbacka/node-red-contrib-sw-light@0.1.9
 ```
 
 After publication, the current development release is available under npm latest:
@@ -75,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.8` 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
@@ -87,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.8
+## 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,
@@ -97,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.8`. 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
@@ -295,7 +321,7 @@ Adaptive Lighting, including sun/time and sleep settings.
 
 ### Real-world verification
 
-1. Install the local 0.1.8 archive, restart Node-RED, and verify its startup
+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
@@ -327,14 +353,14 @@ 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.8 in your HA Node-RED installation
+## 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.8.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.8.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.

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/lib/controller.js

@@ -0,0 +1,98 @@
+'use strict';
+const light = require('./light');
+const adaptive = require('./adaptive');
+
+// One independent controller per entity, shared by every target type.
+function createController(c, adapter, node, isClosed) {
+    const detector = new light.Override(c);
+    let lastAvailability;
+    const protectedAtFullBrightness = state => state?.state === 'on' && state.attributes?.brightness === 255;
+    const overrideActive = state => detector.active || protectedAtFullBrightness(state);
+    function event(type, detail = {}, msg = {}, send = node.send.bind(node)) {
+        if (isClosed()) return;
+        send([null, { ...msg, sw_light_event: { version: 1, type, entity_id: c.entityId,
+            timestamp: new Date().toISOString(), ...detail } }]);
+    }
+    function overrideUpdate(fn, msg, send) {
+        const before = detector.active;
+        fn();
+        if (before !== detector.active) event(detector.active ? 'manual_override' : 'override_released',
+            { active: detector.active, strategy: c.overrideStrategy }, msg, send);
+    }
+    function observe(state) {
+        if (isClosed()) return;
+        overrideUpdate(() => detector.observe(state));
+        const availability = !state ? 'missing' : state.state;
+        if (['missing', 'unknown', 'unavailable'].includes(availability)) {
+            node.status({ fill: 'red', shape: 'ring', text: 'ENTITY UNAVAILABLE' });
+            if (lastAvailability !== availability) event('unavailable', { reason: availability });
+        } else {
+            const active = overrideActive(state);
+            const info = light.normalized(state, active, c.adaptiveEnabled, 'state_changed');
+            let text = active ? 'MANUAL' : `AUTO · ${info.state.toUpperCase()}`;
+            if (info.state === 'on' && info.brightness_pct !== null) text += ` · ${info.brightness_pct}%`;
+            if (info.state === 'on' && info.color_temp_kelvin) text += ` · ${info.color_temp_kelvin}K`;
+            if (info.state === 'on' && c.adaptiveEnabled) text += ' · adaptive';
+            node.status({ fill: active ? 'yellow' : info.state === 'on' ? 'green' : 'grey', shape: 'dot', text });
+        }
+        lastAvailability = availability;
+    }
+
+    async function execute(msg, send) {
+        let command, serviceCompleted = false;
+        try {
+            const state = adapter.state(c.entityId);
+            if (!state || !['on', 'off'].includes(state.state)) throw light.fault(`Light is ${state?.state ?? 'missing'}`, 'unavailable');
+            observe(state);
+            const requestedOverride = Object.prototype.hasOwnProperty.call(msg, 'manual_override');
+            if (requestedOverride && (msg.source ?? 'automatic') !== 'manual') throw light.fault('manual_override requires source: manual');
+            if (requestedOverride && typeof msg.manual_override !== 'boolean') throw light.fault('manual_override must be boolean');
+            command = light.plan(c, msg, state, overrideActive(state));
+            if (requestedOverride) {
+                overrideUpdate(() => detector.set(msg.manual_override), msg, send);
+                command.blocked = false; // validated manual source
+            }
+            if (command.unsupported.length) event('unsupported', { parameters: command.unsupported, reason: 'lamp_capabilities_or_action' }, msg, send);
+            if (command.blocked) {
+                event('manual_override', { active: true, blocked: true, requested_action: command.action }, msg, send);
+                const percent = Number.isFinite(state.attributes?.brightness) ? Math.round(light.pct(state.attributes.brightness)) : '?';
+                node.status({ fill: 'yellow', shape: 'dot', text: `MANUAL · ${percent}% · BLOCK ${command.action.toUpperCase()}` });
+                return { ...light.normalized(state, overrideActive(state), command.adaptiveEnabled, command.service), entity_id: c.entityId, outcome: 'skipped', reason: 'manual_override', source: command.source, requested_action: command.action, state_confirmation: 'last_observed' };
+            }
+            await adapter.call('light', command.service, command.data, { entity_id: c.entityId });
+            serviceCompleted = true;
+            if (isClosed()) return { entity_id: c.entityId, outcome: 'skipped', reason: 'node_closed' };
+            let adaptiveResult;
+            try {
+                adaptiveResult = await adaptive.apply(adapter, c, command);
+                if (adaptiveResult.reason === 'unsupported_color_temperature') event('unsupported',
+                    { phase: 'adaptive_apply', reason: adaptiveResult.reason, light_service_completed: true }, msg, send);
+            }
+            catch (error) {
+                adaptiveResult = { applied: false, reason: error.reason || 'apply_failed' };
+                event('warning', { message: error.message, reason: adaptiveResult.reason,
+                    phase: 'adaptive_apply', light_service_completed: true }, msg, send);
+            }
+            if (isClosed()) return { entity_id: c.entityId, outcome: 'skipped', reason: 'node_closed' };
+            const current = adapter.state(c.entityId);
+            observe(current);
+            const result = { ...light.normalized(current, overrideActive(current), command.adaptiveEnabled, command.service),
+                entity_id: c.entityId, source: command.source, requested_action: command.action,
+                service_data: command.data, ignored_conflicts: command.ignoredConflicts,
+                state_confirmation: 'last_observed', adaptive: { ...adaptive.inspect({ ...c, adaptiveEnabled: command.adaptiveEnabled }, adapter.states()), ...adaptiveResult } };
+
+            const level = command.data.brightness === undefined ? '' : ` · ${Math.round(light.pct(command.data.brightness))}%`;
+            node.status({ fill: command.source === 'manual' ? 'yellow' : command.turningOn ? 'green' : 'grey', shape: 'dot',
+                text: `${command.source === 'manual' ? 'MANUAL' : 'AUTO'} · ${command.turningOn ? 'ON' : 'OFF'}${level}` });
+            return { ...result, outcome: 'succeeded' };
+        } catch (error) {
+            event(error.eventType || 'error', { message: error.message, light_service_completed: serviceCompleted }, msg, send);
+            if (!isClosed()) node.status({ fill: 'red', shape: 'ring', text: error.eventType === 'config_error' ? 'CONFIG ERROR' :
+                error.eventType === 'unavailable' ? (error.message.startsWith('HA NOT READY:') || !adapter || !adapter.connected() ? 'HA NOT READY' : 'ENTITY UNAVAILABLE') : error.message });
+            return { ...light.normalized(adapter.state(c.entityId), overrideActive(adapter.state(c.entityId)), c.adaptiveEnabled), entity_id: c.entityId, outcome: 'failed', error: { type: error.eventType || 'error', message: error.message }, light_service_completed: serviceCompleted, cause: error };
+        }
+
+    }
+    return { observe, execute, info: () => { const state = adapter.state(c.entityId); return light.normalized(state, overrideActive(state), c.adaptiveEnabled); } };
+}
+module.exports = { createController };

package/lib/ha-adapter.js

@@ -27,6 +27,13 @@ function createAdapter(RED, serverId, integration, diagnostic = () => {}) {
     let ha, stopped = false, observers, installing = false;
     const listeners = [], subscriptions = new Set(), rawStates = new Map();
     let pendingSubscription = Promise.resolve();
+    let registryBound = false, connectionBound = false;
+    let registryListener, registryCache, registryPending, registryGeneration = 0;
+    let entityIds = new Set();
+    function invalidateRegistries() {
+        registryGeneration++; registryCache = undefined;
+        if (!stopped) registryListener?.();
+    }
     const diagnostics = new Map();
     function report(server, client, phase) {
         const info = { phase, serverIdPresent: Boolean(serverId), serverResolved: Boolean(server),
@@ -48,11 +55,12 @@ function createAdapter(RED, serverId, integration, diagnostic = () => {}) {
     }
     async function detach() {
         for (const [bus, event, fn] of listeners) bus.removeListener(event, fn);
-        listeners.length = 0;
+        listeners.length = 0; registryBound = false; connectionBound = false;
         await pendingSubscription;
         await Promise.allSettled([...subscriptions].map(fn => Promise.resolve().then(fn)));
         subscriptions.clear();
         rawStates.clear();
+        invalidateRegistries();
     }
     async function install() {
         if (stopped || installing || subscriptions.size || !connected() || !observers) return;
@@ -60,10 +68,10 @@ function createAdapter(RED, serverId, integration, diagnostic = () => {}) {
         const client = ha;
         try {
             const unsubscribe = await client.websocket.subscribeMessage(event => {
-                if (stopped || ha !== client || event.data?.entity_id !== observers.entityId) return;
+                if (stopped || ha !== client || !entityIds.has(event.data?.entity_id)) return;
                 const state = event.data.new_state;
-                rawStates.set(observers.entityId, state ?? undefined);
-                try { observers.onState(state); } catch (error) { observers.onError(error); }
+                rawStates.set(event.data.entity_id, state ?? undefined);
+                try { observers.onState(state, event.data.entity_id); } catch (error) { observers.onError(error); }
             }, { type: 'subscribe_events', event_type: 'state_changed' }, { resubscribe: true });
             if (stopped || ha !== client) await unsubscribe();
             else subscriptions.add(unsubscribe);
@@ -72,16 +80,24 @@ function createAdapter(RED, serverId, integration, diagnostic = () => {}) {
     }
     function refresh() {
         rawStates.clear();
+        invalidateRegistries();
         if (!stopped && observers) {
             observers.onConnection(connected());
             if (!installing && !subscriptions.size && connected()) pendingSubscription = install();
         }
     }
+    function bindRegistries() {
+        if (!ha || !registryListener || registryBound || stopped) return;
+        registryBound = true;
+        for (const event of ['labels_updated', 'entity_registry_updated', 'devices_updated', 'areas_updated']) listen(event, invalidateRegistries);
+    }
     function bind() {
-        if (!ha || !observers || stopped || listeners.length) return;
+        bindRegistries();
+        if (!ha || !observers || stopped || connectionBound) return;
+        connectionBound = true;
         for (const event of ['ha_client:ready', 'ha_client:states_loaded', 'ha_client:connected']) listen(event, refresh);
         for (const event of ['ha_client:close', 'ha_client:connecting', 'ha_client:error']) {
-            listen(event, () => { rawStates.clear(); if (!stopped) observers.onConnection(false); });
+            listen(event, () => { rawStates.clear(); invalidateRegistries(); if (!stopped) observers.onConnection(false); });
         }
         refresh();
     }
@@ -123,8 +139,36 @@ function createAdapter(RED, serverId, integration, diagnostic = () => {}) {
             if (!connected()) throw fault('HA NOT READY: disconnected or loading states', 'unavailable');
             return ha.websocket.callService(domain, service, data, target);
         },
+        onRegistryChange(callback) { registryListener = callback; bindRegistries(); },
+        async labels() {
+            if (!connected()) throw fault('HA NOT READY', 'unavailable');
+            return ha.websocket.send({ type: 'config/label_registry/list' });
+        },
+        async registries() {
+            if (!connected() || typeof ha.websocket.send !== 'function') throw fault('HA registries unavailable', 'target_resolution_failure');
+            if (registryCache && Date.now() - registryCache.time < 30000) return registryCache.data;
+            if (registryPending) return registryPending;
+            const generation = registryGeneration, client = ha;
+            const pending = Promise.all(['label', 'entity', 'device', 'area'].map(name =>
+                client.websocket.send({ type: `config/${name}_registry/list` }))).then(([labels, entities, devices, areas]) => {
+                if (stopped || ha !== client || generation !== registryGeneration) throw fault('HA registries changed during resolution; retry', 'target_resolution_failure');
+                const data = { labels, entities, devices, areas };
+                if (!Object.values(data).every(Array.isArray)) throw fault('Invalid HA registry response', 'target_resolution_failure');
+                registryCache = { time: Date.now(), data };
+                return data;
+            });
+            registryPending = pending;
+            try { return await pending; } finally { if (registryPending === pending) registryPending = undefined; }
+        },
+        async watch(ids, onState, onConnection, onError) {
+            entityIds = new Set(ids);
+            for (const id of rawStates.keys()) if (!entityIds.has(id)) rawStates.delete(id);
+            observers = { onState, onConnection, onError };
+            bind();
+        },
         async subscribe(entityId, onState, onConnection, onError) {
-            observers = { entityId, onState, onConnection, onError };
+            entityIds = new Set(entityId ? [entityId] : []);
+            observers = { onState, onConnection, onError };
             bind();
         },
         async close() {

package/lib/light.js

@@ -56,7 +56,10 @@ function config(raw) {
     c.mired = number(c.mired, 'mired', 25, 1000);
     if (!/^#[0-9a-f]{6}$/i.test(c.fixedColor)) throw fault('Fixed color must be #rrggbb');
     if (c.adaptiveEntity && !/^switch\.[a-z0-9_]+$/.test(c.adaptiveEntity)) throw fault('Adaptive entity must be a switch entity');
-    if (!/^light\.[a-z0-9_]+$/.test(c.entityId || '')) throw fault('Select a light entity');
+    if ((c.targetType ?? 'entity') === 'entity' && !/^light\.[a-z0-9_]+$/.test(c.entityId || '')) throw fault('Select a light entity');
+    const configured = require('./targets').target(c);
+    c.targetType = configured.type;
+    if (configured.type === 'label') c.labelId = configured.id;
     return c;
 }
 function pct(brightness) { return brightness * 100 / 255; }

package/lib/targets.js

@@ -0,0 +1,54 @@
+'use strict';
+const { fault } = require('./light');
+
+function target(raw, override) {
+    const value = override === undefined ? { type: raw.targetType ?? 'entity', id: (raw.targetType ?? 'entity') === 'label' ? raw.labelId : raw.entityId } : override;
+    if (!value || typeof value !== 'object' || Array.isArray(value) || !['entity', 'label'].includes(value.type) ||
+        typeof value.id !== 'string' || !value.id.trim()) throw fault('Target requires type entity/label and a stable id', 'config_error');
+    if (value.type === 'entity' && !/^light\.[a-z0-9_]+$/.test(value.id)) throw fault('Select a light entity', 'config_error');
+    return { type: value.type, id: value.id };
+}
+
+// HA 2026.9 service target semantics. Area relationships are part of Label
+// expansion; Area is deliberately not exposed as a configured target type.
+function labelLights(id, { labels, entities, devices, areas }) {
+    if (![labels, entities, devices, areas].every(Array.isArray)) throw fault('HA registries unavailable', 'target_resolution_failure');
+    if (!labels.some(l => l.label_id === id)) throw fault(`Label ${id} was deleted or does not exist`, 'target_resolution_failure');
+    const marked = item => Array.isArray(item.labels) && item.labels.includes(id);
+    const deviceIds = new Set(devices.filter(marked).map(d => d.id));
+    const areaIds = new Set(areas.filter(marked).map(a => a.area_id));
+    const areaDevices = new Set(devices.filter(d => areaIds.has(d.area_id)).map(d => d.id));
+    return [...new Set(entities.filter(e => {
+        if (!/^light\.[a-z0-9_]+$/.test(e.entity_id) || e.hidden_by || e.disabled_by) return false;
+        if (marked(e)) return true;
+        if (e.entity_category) return false;
+        return deviceIds.has(e.device_id) || areaIds.has(e.area_id) || (!e.area_id && areaDevices.has(e.device_id));
+    }).map(e => e.entity_id))].sort();
+}
+async function resolveTarget(adapter, configured) {
+    if (configured.type === 'entity') return [configured.id];
+    return labelLights(configured.id, await adapter.registries());
+}
+function createTargetResolver(adapter) {
+    let snapshot;
+    const membership = new Map();
+    return async selected => {
+        if (selected.type === 'entity') return [selected.id];
+        const next = await adapter.registries();
+        if (next !== snapshot) { membership.clear(); snapshot = next; }
+        if (!membership.has(selected.id)) membership.set(selected.id, labelLights(selected.id, snapshot));
+        return [...membership.get(selected.id)];
+    };
+}
+function aggregateStatus(infos) {
+    const counts = { on: 0, manual: 0, off: 0, unavailable: 0 };
+    for (const info of infos) {
+        if (!['on', 'off'].includes(info.state)) counts.unavailable++;
+        else if (info.manual_override) counts.manual++;
+        else counts[info.state]++;
+    }
+    return { fill: counts.unavailable ? 'red' : counts.manual ? 'yellow' : counts.on ? 'green' : 'grey',
+        shape: counts.unavailable ? 'ring' : 'dot',
+        text: infos.length ? Object.entries(counts).filter(([,n]) => n).map(([key,n]) => `${n} ${key}`).join(' · ') : 'LABEL EMPTY' };
+}
+module.exports = { target, labelLights, resolveTarget, createTargetResolver, aggregateStatus };

package/nodes/sw-light.html

@@ -13,6 +13,10 @@
             return true;
         };
     }
+    function targetKind(node) {
+        const field = typeof $ === 'function' ? $('#node-input-targetType') : null;
+        return field?.length ? field.val() || node.targetType || 'entity' : node.targetType || 'entity';
+    }
     RED.nodes.registerType('sw-light', {
         category: 'home assistant', color: '#c7d7e8', icon: 'font-awesome/fa-lightbulb-o',
         inputs: 1, outputs: 2, outputLabels: ['result / state', 'events / errors'],
@@ -20,7 +24,9 @@
         defaults: {
             name: { value: '' }, server: { value: '', type: 'server', required: true },
             action: { value: 'msg', validate: v => ['on','off','toggle','msg'].includes(v) },
-            entityId: { value: '', required: true, validate: v => /^light\.[a-z0-9_]+$/.test(v) },
+            targetType: { value: 'entity', validate: v => ['entity','label'].includes(v) },
+            entityId: { value: '', validate: function (v) { return targetKind(this) === 'label' || /^light\.[a-z0-9_]+$/.test(v); } },
+            labelId: { value: '', validate: function (v) { return targetKind(this) !== 'label' || (typeof v === 'string' && v.trim().length > 0); } },
             brightnessPct: { value: 94, validate: numeric('brightnessPct') },
             autoMaxPct: { value: 94, validate: numeric('autoMaxPct') },
             minPct: { value: 1, validate: numeric('minPct') },
@@ -38,26 +44,31 @@
                 $('#node-input-colorMode').val('keep');
                 $('#node-input-adaptiveEnabled').prop('checked', this.adaptiveApply === true);
             }
-            let states = {}, request, generation = 0;
+            let states = {}, labels = [], request, labelRequest, generation = 0;
+            $('#node-input-targetType').val(this.targetType || 'entity');
+            const label = $('#node-input-labelId');
             const entity = $('#node-input-entityId'), adaptive = $('#node-input-adaptiveEntity');
             function modesForLight() { return states[entity.val()]?.attributes?.supported_color_modes || []; }
             function update() {
+                const isLabel = $('#node-input-targetType').val() === 'label';
+                $('.sw-entity-target').toggle(!isLabel); $('.sw-label-target').toggle(isLabel);
+                $('#sw-label-name').text(labels.find(l => l.label_id === label.val())?.name || 'Select a Label or enter its stable ID.');
                 const mode = $('#node-input-colorMode').val();
                 $('.sw-color-row').hide();
                 $('.sw-color-' + mode).show();
                 $('.sw-adaptive-row').toggle($('#node-input-adaptiveEnabled').prop('checked'));
                 const profiles = Object.values(states).filter(s => s.entity_id.startsWith('switch.') &&
                     Array.isArray(s.attributes?.configuration?.lights) && s.attributes.configuration.lights.includes(entity.val()));
-                $('#sw-adaptive-info').text(modesForLight().includes('color_temp') ?
+                $('#sw-adaptive-info').text(isLabel ? 'A unique profile is discovered per light. Advanced selects one shared fallback; keep its main switch off.' : modesForLight().includes('color_temp') ?
                     (profiles.length === 1 ? 'Profile found. Keep its main switch off for one-shot use.' :
                         'No unique profile found. Select a profile under Advanced.') : 'This light has no known color-temperature support. Normal ON still works.');
                 $('.sw-override-row').toggle($('#node-input-manualOverride').prop('checked'));
                 $('.sw-threshold-row').toggle($('#node-input-manualOverride').prop('checked') && $('#node-input-overrideStrategy').val() === 'threshold');
                 const s = states[entity.val()], modes = s && s.attributes && s.attributes.supported_color_modes;
-                $('#sw-capabilities').text(modes ? 'Supported: ' + modes.join(', ') : 'Select a deployed server and light to read capabilities.');
+                $('#sw-capabilities').text(isLabel ? 'Capabilities and Adaptive Lighting profiles are evaluated per resolved light.' : modes ? 'Supported: ' + modes.join(', ') : 'Select a deployed server and light to read capabilities.');
                 // Disabled options reflect known capabilities, without discarding saved settings.
-                $('#node-input-colorMode option[value="kelvin"], #node-input-colorMode option[value="mired"]').prop('disabled', !!modes && !modes.includes('color_temp'));
-                $('#node-input-colorMode option[value="color"]').prop('disabled', !!modes && !modes.some(m => ['hs','xy','rgb','rgbw','rgbww'].includes(m)));
+                $('#node-input-colorMode option[value="kelvin"], #node-input-colorMode option[value="mired"]').prop('disabled', !isLabel && !!modes && !modes.includes('color_temp'));
+                $('#node-input-colorMode option[value="color"]').prop('disabled', !isLabel && !!modes && !modes.some(m => ['hs','xy','rgb','rgbw','rgbww'].includes(m)));
             }
             function source(domain) {
                 return function (req, respond) {
@@ -69,27 +80,36 @@
                 };
             }
             entity.autocomplete({ minLength: 0, source: source('light'), select: function (_e, ui) { entity.val(ui.item.value); update(); } });
+            label.autocomplete({ minLength: 0, source: function (req, respond) {
+                const term = req.term.toLowerCase();
+                respond(labels.filter(l => l.label_id.toLowerCase().includes(term) || l.name.toLowerCase().includes(term))
+                    .map(l => ({ label: l.name + ' (' + l.label_id + ')', value: l.label_id })));
+            }, select: function (_e, ui) { label.val(ui.item.value); update(); } });
+            label.on('focus.swLight', function () { label.autocomplete('search', label.val()); });
             adaptive.autocomplete({ minLength: 0, source: source('switch') });
             function load() {
                 generation++; const token = generation;
-                if (request) request.abort();
-                states = {}; update();
+                if (request) request.abort(); if (labelRequest) labelRequest.abort();
+                states = {}; labels = []; update();
                 const server = $('#node-input-server').val();
                 if (!server || server === '_ADD_') return;
                 $('#sw-capabilities').text('Loading Home Assistant entities…');
-                // HA contrib's own editor endpoint. No auth tokens or static entity lists.
+                // Label route uses the shared adapter; Entity route belongs to HA contrib.
+                labelRequest = $.getJSON('sw-light/labels/' + encodeURIComponent(server))
+                    .done(function (data) { if (token === generation) { labels = Array.isArray(data) ? data : []; update(); } })
+                    .fail(function (_xhr, status) { if (status !== 'abort' && token === generation) $('#sw-label-name').text('Server must be deployed and connected. A stable Label ID can also be entered directly.'); });
                 request = $.getJSON('homeassistant/states/' + encodeURIComponent(server))
                     .done(function (data) { if (token === generation) { states = data || {}; update(); } })
                     .fail(function (_xhr, status) { if (status !== 'abort' && token === generation) $('#sw-capabilities').text('Server must be deployed and connected. Entity IDs can also be entered directly.'); });
             }
             $('#node-input-server').on('change.swLight', load);
-            $('#node-input-colorMode, #node-input-adaptiveEnabled, #node-input-manualOverride, #node-input-overrideStrategy, #node-input-entityId').on('change.swLight', update);
+            $('#node-input-targetType, #node-input-labelId, #node-input-colorMode, #node-input-adaptiveEnabled, #node-input-manualOverride, #node-input-overrideStrategy, #node-input-entityId').on('change.swLight', update);
             entity.on('focus.swLight', function () { entity.autocomplete('search', entity.val()); });
             adaptive.on('focus.swLight', function () { adaptive.autocomplete('search', adaptive.val()); });
             this._swCleanup = function () {
-                generation++; if (request) request.abort();
-                $('#node-input-server, #node-input-colorMode, #node-input-adaptiveEnabled, #node-input-manualOverride, #node-input-overrideStrategy, #node-input-entityId, #node-input-adaptiveEntity').off('.swLight');
-                entity.autocomplete('destroy'); adaptive.autocomplete('destroy');
+                generation++; if (request) request.abort(); if (labelRequest) labelRequest.abort();
+                $('#node-input-server, #node-input-targetType, #node-input-labelId, #node-input-colorMode, #node-input-adaptiveEnabled, #node-input-manualOverride, #node-input-overrideStrategy, #node-input-entityId, #node-input-adaptiveEntity').off('.swLight');
+                label.autocomplete('destroy'); label.off('.swLight'); entity.autocomplete('destroy'); adaptive.autocomplete('destroy');
                 delete this._swCleanup;
             };
             load(); update();
@@ -103,7 +123,9 @@
 <script type="text/html" data-template-name="sw-light">
     <div class="form-row"><label for="node-input-name"><i class="fa fa-tag"></i> Name</label><input id="node-input-name" type="text" placeholder="SW Light"></div>
     <div class="form-row"><label for="node-input-server"><i class="fa fa-server"></i> HA server</label><input id="node-input-server" type="text"></div>
-    <div class="form-row"><label for="node-input-entityId"><i class="fa fa-lightbulb-o"></i> Light</label><input id="node-input-entityId" type="text" placeholder="light.entity_id"></div>
+    <div class="form-row"><label for="node-input-targetType">Target</label><select id="node-input-targetType"><option value="entity">Entity</option><option value="label">Label</option></select></div>
+    <div class="form-row sw-label-target"><label for="node-input-labelId">Label</label><input id="node-input-labelId" type="text" placeholder="Stable Label ID"><p id="sw-label-name"></p></div>
+    <div class="form-row sw-entity-target"><label for="node-input-entityId"><i class="fa fa-lightbulb-o"></i> Light</label><input id="node-input-entityId" type="text" placeholder="light.entity_id"></div>
     <div class="form-row"><label for="node-input-action">Action</label><select id="node-input-action"><option value="on">On</option><option value="off">Off</option><option value="toggle">Toggle</option><option value="msg">From msg</option></select></div>
     <div class="form-tips" id="sw-capabilities" style="margin-bottom:16px"></div>
     <fieldset><legend>Automatic lighting</legend>
@@ -134,7 +156,8 @@
 </script>
 
 <script type="text/html" data-help-name="sw-light">
-    <p>Controls one Home Assistant light directly: Trigger → SW Light → Home Assistant. No downstream HA Action node is required. Select On, Off, Toggle, or From msg. Toggle resolves the current state to turn_on or turn_off.</p>
+    <p>Controls a Home Assistant Entity or Label directly: Trigger → SW Light → Home Assistant. No downstream HA Action node is required. Select On, Off, Toggle, or From msg. Toggle resolves the current state to turn_on or turn_off.</p>
+    <p>Entity is the default for existing flows. Label stores its stable ID and resolves current light members, including labeled devices and labeled area relationships. Each light retains its own override and capabilities. Label output 1 contains target, resolved_entity_ids, results and counts; status summarizes observed states. A failed member does not stop others. <code>msg.target = {type: "label", id: "label_id"}</code> or <code>{type: "entity", id: "light.example"}</code> overrides the configured target for one input. The latest target is observed until the next input.</p>
     <h3>Inputs</h3>
     <dl class="message-properties"><dt>action <span class="property-type">string</span></dt><dd>Required with From msg: <code>on</code>, <code>off</code>, or <code>toggle</code>. Falls back to <code>msg.auto_light.action</code> when msg.action is absent. Fixed Action settings ignore message actions.</dd><dt class="optional">source <span class="property-type">string</span></dt><dd><code>automatic</code> (default) or <code>manual</code>.</dd><dt class="optional">brightness_pct <span class="property-type">number</span></dt><dd>0–100. Automatic brightness is capped at the configured maximum.</dd><dt class="optional">transition <span class="property-type">number</span></dt><dd>Fade seconds, 0–3600, if supported.</dd><dt class="optional">manual_override <span class="property-type">boolean</span></dt><dd>Latch/release override with <code>source: "manual"</code>.</dd></dl>
     <h3>Outputs</h3><ol><li>Original message plus <code>msg.sw_light</code>: last observed HA state, action, service data, and override/adaptive information.</li><li>Original message plus <code>msg.sw_light_event</code>: version, type, entity_id, timestamp, and details.</li></ol>

package/nodes/sw-light.js

@@ -1,70 +1,108 @@
 'use strict';
-
 const light = require('../lib/light');
-const adaptive = require('../lib/adaptive');
+const { createController } = require('../lib/controller');
+const { target, createTargetResolver, aggregateStatus } = require('../lib/targets');
 const { createAdapter } = require('../lib/ha-adapter');
 
-// Optional factory is for isolated transport/lifecycle tests, never flow config.
 module.exports = function register(RED, adapterFactory = createAdapter) {
+    // HA contrib 0.80.3's Label selector is bundled privately and its HTTP API
+    // has no labels endpoint. Reuse its authenticated shared transport here.
+    if (RED.httpAdmin && RED.auth) RED.httpAdmin.get('/sw-light/labels/:serverId', RED.auth.needsPermission('server.read'), async (req, res) => {
+        let handle;
+        try {
+            handle = adapterFactory(RED, req.params.serverId);
+            await handle.resolve();
+            res.json(await handle.labels());
+        } catch (error) { res.status(503).json({ error: error.message }); }
+        finally { await handle?.close(); }
+    });
     function SWLight(raw) {
         RED.nodes.createNode(this, raw);
         const node = this;
         node.log?.(`[SW Light debug] version=${require('../package.json').version} constructor=created serverIdPresent=${Boolean(raw.server)}`);
-        let c, detector, adapter, closed = false, lastAvailability;
-        let queue = Promise.resolve(), startup = Promise.resolve(), observerTimer;
-        const protectedAtFullBrightness = state => state?.state === 'on' && state.attributes?.brightness === 255;
-        const overrideActive = state => detector.active || protectedAtFullBrightness(state);
+        let c, configured, adapter, resolver, closed = false, ready = false, observerTimer, refreshTimer, registryTimer;
+        let queue = Promise.resolve(), startup = Promise.resolve(), activeIds = [];
+        const controllers = new Map();
         function event(type, detail = {}, msg = {}, send = node.send.bind(node)) {
-            if (closed) return;
-            send([null, { ...msg, sw_light_event: { version: 1, type, entity_id: c?.entityId ?? raw.entityId,
-                timestamp: new Date().toISOString(), ...detail } }]);
+            if (!closed) send([null, { ...msg, sw_light_event: { version: 1, type,
+                entity_id: configured?.type === 'entity' ? configured.id : undefined,
+                target: configured, timestamp: new Date().toISOString(), ...detail } }]);
+        }
+        function status() {
+            if (!closed && ready && configured?.type === 'label') node.status(aggregateStatus(activeIds.map(id => controllers.get(id).info())));
         }
-        function overrideUpdate(fn, msg, send) {
-            const before = detector.active;
-            fn();
-            if (before !== detector.active) event(detector.active ? 'manual_override' : 'override_released',
-                { active: detector.active, strategy: c.overrideStrategy }, msg, send);
+        function controller(id) {
+            if (!controllers.has(id)) controllers.set(id, createController({ ...c, entityId: id }, adapter, {
+                send: node.send.bind(node), status: value => { if (!closed && configured.type === 'entity') node.status(value); }
+            }, () => closed));
+            return controllers.get(id);
         }
-        function observe(state) {
+        async function reconcile(selected = configured) {
+            if (closed) return [];
+            const ids = await resolver(selected);
+            if (closed) return [];
+            // Runtime overrides become the observed target until the next input.
+            configured = selected;
+            activeIds = ids;
+            for (const id of ids) controller(id);
+            for (const id of controllers.keys()) if (!ids.includes(id)) controllers.delete(id);
+            const observe = (state, id) => { if (!closed) { controllers.get(id || selected.id)?.observe(state); status(); } };
+            if (adapter.watch) await adapter.watch(ids, observe, connection, error => event('error', { message: error.message }));
+            else if (ids.length === 1) await adapter.subscribe(ids[0], state => observe(state, ids[0]), connection, error => event('error', { message: error.message }));
+            for (const id of ids) controller(id).observe(adapter.state(id));
+            status();
+            return ids;
+        }
+        function scheduleRefresh() {
+            if (closed || configured?.type !== 'label') return;
+            clearTimeout(refreshTimer);
+            refreshTimer = setTimeout(() => {
+                queue = queue.then(async () => {
+                    if (closed || !adapter.connected()) return;
+                    try { await reconcile(); }
+                    catch (error) { resolutionError(error); }
+                }).catch(error => resolutionError(error));
+            }, 100);
+            refreshTimer.unref?.();
+        }
+        function resolutionError(error, msg, send, selected = configured) {
             if (closed) return;
-            overrideUpdate(() => detector.observe(state));
-            const availability = !state ? 'missing' : state.state;
-            if (['missing', 'unknown', 'unavailable'].includes(availability)) {
-                node.status({ fill: 'red', shape: 'ring', text: 'ENTITY UNAVAILABLE' });
-                if (lastAvailability !== availability) event('unavailable', { reason: availability });
-            } else {
-                const active = overrideActive(state);
-                const info = light.normalized(state, active, c.adaptiveEnabled, 'state_changed');
-                let text = active ? 'MANUAL' : `AUTO · ${info.state.toUpperCase()}`;
-                if (info.state === 'on' && info.brightness_pct !== null) text += ` · ${info.brightness_pct}%`;
-                if (info.state === 'on' && info.color_temp_kelvin) text += ` · ${info.color_temp_kelvin}K`;
-                if (info.state === 'on' && c.adaptiveEnabled) text += ' · adaptive';
-                node.status({ fill: active ? 'yellow' : info.state === 'on' ? 'green' : 'grey', shape: 'dot', text });
-            }
-            lastAvailability = availability;
+            node.status({ fill: 'red', shape: 'ring', text: 'TARGET UNAVAILABLE' });
+            activeIds = [];
+            adapter?.watch?.([], () => {}, connection, failure => event('error', { message: failure.message }));
+            event('target_resolution_failure', { message: error.message, target: selected }, msg, send);
         }
-        function connection(ready) {
+        function connection(value) {
             if (closed) return;
-            if (ready) observe(adapter.state(c.entityId));
-            else {
+            const wasReady = ready;
+            ready = value;
+            if (ready) {
+                if (configured.type === 'entity') controllers.get(configured.id)?.observe(adapter.state(configured.id));
+                else if (!wasReady) scheduleRefresh();
+            } else {
                 node.status({ fill: 'red', shape: 'ring', text: 'HA NOT READY' });
-                if (lastAvailability !== 'disconnected') event('unavailable', { reason: 'disconnected' });
-                lastAvailability = 'disconnected';
+                if (wasReady) event('unavailable', { reason: 'disconnected' });
             }
         }
         function startAdapter() {
             adapter = adapterFactory(RED, c.server, undefined, detail => node.log?.(`[SW Light debug] ${detail}`));
-            startup = adapter.subscribe(c.entityId, observe, connection,
-                error => event('error', { message: error.message })).catch(error => {
-                if (!closed) { node.status({ fill: 'red', shape: 'ring', text: 'subscription failed' }); event(error.eventType || 'error', { message: error.message }); }
-            });
+            resolver = createTargetResolver(adapter);
+            if (configured.type === 'label') adapter.onRegistryChange?.(scheduleRefresh);
+            registryTimer = setInterval(scheduleRefresh, 30000); registryTimer.unref?.();
+            // Bind connection notifications even while Label registries are unavailable.
+            startup = adapter.subscribe(configured.type === 'entity' ? configured.id : '',
+                state => { controllers.get(configured.id)?.observe(state); }, connection,
+                error => event('error', { message: error.message }));
             connection(adapter.connected());
         }
         function startObserving() {
             if (closed || node.swLightError) return;
-            startup = Promise.resolve().then(async () => {
+            startup = queue = queue.then(async () => {
+                if (closed) return;
                 if (!adapter) startAdapter();
                 if (adapter.resolve) await adapter.resolve();
+                if (!adapter.connected()) throw light.fault('HA NOT READY', 'unavailable');
+                await reconcile();
             }).catch(error => {
                 if (closed) return;
                 event(error.eventType || 'error', { message: error.message, phase: 'state_subscription' });
@@ -73,89 +111,60 @@ module.exports = function register(RED, adapterFactory = createAdapter) {
             });
         }
         try {
-            c = light.config(raw);
-            detector = new light.Override(c);
-            // Defer provider resolution until after Flow.start. Observe even
-            // before this node's first command; retry temporary startup failures.
+            c = light.config(raw); configured = target(c);
             node.status({ fill: 'red', shape: 'ring', text: 'HA NOT READY' });
-            observerTimer = setTimeout(startObserving, 0);
-            observerTimer.unref?.();
+            observerTimer = setTimeout(startObserving, 0); observerTimer.unref?.();
         } catch (error) {
             node.status({ fill: 'red', shape: 'ring', text: 'CONFIG ERROR' });
-            node.error(error.message);
-            node.swLightError = error;
+            node.error(error.message); node.swLightError = error;
         }
         node.on('input', (msg, send, done) => {
             send = send || node.send.bind(node);
             done = done || (error => { if (error) node.error(error, msg); });
             const run = async () => {
                 if (closed) { done(); return; }
-                let command, serviceCompleted = false;
                 try {
                     if (node.swLightError) throw node.swLightError;
-                    // A temporarily absent/uninitialized provider is retried on
-                    // the next input, rather than freezing the constructor error.
+                    const selected = target(c, msg.target);
                     if (!adapter) startAdapter();
+                    if (selected.type === 'label') adapter.onRegistryChange?.(scheduleRefresh);
                     if (adapter.resolve) await adapter.resolve();
                     if (closed) { done(); return; }
-                    if (!adapter.connected()) throw light.fault('Home Assistant is disconnected or loading states', 'unavailable');
-                    const state = adapter.state(c.entityId);
-                    if (!state || !['on', 'off'].includes(state.state)) throw light.fault(`Light is ${state?.state ?? 'missing'}`, 'unavailable');
-                    observe(state);
-                    const requestedOverride = Object.prototype.hasOwnProperty.call(msg, 'manual_override');
-                    if (requestedOverride && (msg.source ?? 'automatic') !== 'manual') throw light.fault('manual_override requires source: manual');
-                    if (requestedOverride && typeof msg.manual_override !== 'boolean') throw light.fault('manual_override must be boolean');
-                    command = light.plan(c, msg, state, overrideActive(state));
-                    if (requestedOverride) {
-                        overrideUpdate(() => detector.set(msg.manual_override), msg, send);
-                        command.blocked = false; // validated manual source
-                    }
-                    if (command.unsupported.length) event('unsupported', { parameters: command.unsupported, reason: 'lamp_capabilities_or_action' }, msg, send);
-                    if (command.blocked) {
-                        event('manual_override', { active: true, blocked: true, requested_action: command.action }, msg, send);
-                        const percent = Number.isFinite(state.attributes?.brightness) ? Math.round(light.pct(state.attributes.brightness)) : '?';
-                        node.status({ fill: 'yellow', shape: 'dot', text: `MANUAL · ${percent}% · BLOCK ${command.action.toUpperCase()}` });
-                        done(); return;
-                    }
-                    await adapter.call('light', command.service, command.data, { entity_id: c.entityId });
-                    serviceCompleted = true;
+                    if (!adapter.connected()) throw light.fault('HA NOT READY: disconnected or loading states', 'unavailable');
+                    let ids;
+                    try { ids = await reconcile(selected); }
+                    catch (error) { resolutionError(error, msg, send, selected); done(error); return; }
                     if (closed) { done(); return; }
-                    let adaptiveResult;
-                    try {
-                        adaptiveResult = await adaptive.apply(adapter, c, command);
-                        if (adaptiveResult.reason === 'unsupported_color_temperature') event('unsupported',
-                            { phase: 'adaptive_apply', reason: adaptiveResult.reason, light_service_completed: true }, msg, send);
-                    }
-                    catch (error) {
-                        adaptiveResult = { applied: false, reason: error.reason || 'apply_failed' };
-                        event('warning', { message: error.message, reason: adaptiveResult.reason,
-                            phase: 'adaptive_apply', light_service_completed: true }, msg, send);
+                    if (!ids.length) event('target_empty', { target: selected, resolved_entity_ids: [] }, msg, send);
+                    const results = [];
+                    for (const id of ids) {
+                        if (closed) break;
+                        results.push(await controller(id).execute(msg, send));
                     }
                     if (closed) { done(); return; }
-                    const current = adapter.state(c.entityId);
-                    observe(current);
-                    send([{ ...msg, sw_light: { ...light.normalized(current, overrideActive(current), command.adaptiveEnabled, command.service),
-                        entity_id: c.entityId, source: command.source, requested_action: command.action,
-                        service_data: command.data, ignored_conflicts: command.ignoredConflicts,
-                        state_confirmation: 'last_observed', adaptive: { ...adaptive.inspect({ ...c, adaptiveEnabled: command.adaptiveEnabled }, adapter.states()), ...adaptiveResult } } }, null]);
-                    const level = command.data.brightness === undefined ? '' : ` · ${Math.round(light.pct(command.data.brightness))}%`;
-                    node.status({ fill: command.source === 'manual' ? 'yellow' : command.turningOn ? 'green' : 'grey', shape: 'dot',
-                        text: `${command.source === 'manual' ? 'MANUAL' : 'AUTO'} · ${command.turningOn ? 'ON' : 'OFF'}${level}` });
-                    done();
+                    if (selected.type === 'entity') {
+                        const { outcome, cause, ...result } = results[0];
+                        if (outcome === 'succeeded') send([{ ...msg, sw_light: result }, null]);
+                        done(cause); return;
+                    }
+                    const normalized = results.map(({ cause, ...result }) => result);
+                    const counts = { succeeded: 0, skipped: 0, failed: 0, manual: 0 };
+                    for (const result of results) { counts[result.outcome]++; if (result.manual_override) counts.manual++; }
+                    send([{ ...msg, sw_light: { version: 1, target: selected, resolved_entity_ids: ids,
+                        results: normalized, counts, state_confirmation: 'last_observed' } }, null]);
+                    status(); done();
                 } catch (error) {
-                    event(error.eventType || 'error', { message: error.message, light_service_completed: serviceCompleted }, msg, send);
+                    event(error.eventType || 'error', { message: error.message, light_service_completed: false }, msg, send);
                     if (!closed) node.status({ fill: 'red', shape: 'ring', text: error.eventType === 'config_error' ? 'CONFIG ERROR' :
-                        error.eventType === 'unavailable' ? (error.message.startsWith('HA NOT READY:') || !adapter || !adapter.connected() ? 'HA NOT READY' : 'ENTITY UNAVAILABLE') : error.message });
+                        error.eventType === 'unavailable' ? 'HA NOT READY' : error.message });
                     done(error);
                 }
             };
-            // Serialize relative brightness and toggles; contain all asynchronous failures.
-            queue = queue.then(run).catch(error => { done(error); });
+            queue = queue.then(run).catch(error => done(error));
         });
         node.on('close', (_removed, done) => {
-            closed = true;
-            clearTimeout(observerTimer);
-            Promise.resolve().then(() => adapter?.close()).then(() => startup).catch(() => {}).finally(() => done());
+            closed = true; clearTimeout(observerTimer); clearTimeout(refreshTimer); clearInterval(registryTimer);
+            Promise.resolve().then(() => adapter?.close()).then(() => startup).catch(() => {}).finally(() => { controllers.clear(); done(); });
         });
     }
     RED.nodes.registerType('sw-light', SWLight);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johanwistbacka/node-red-contrib-sw-light",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Home Assistant light control with automatic brightness limits and manual override",
   "license": "MIT",
   "keywords": [
@@ -24,6 +24,8 @@
   "files": [
     "nodes/sw-light.js",
     "nodes/sw-light.html",
+    "lib/controller.js",
+    "lib/targets.js",
     "lib/light.js",
     "lib/adaptive.js",
     "lib/ha-adapter.js",
@@ -31,7 +33,8 @@
     "examples/manual-adaptive.json",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/labels.md"
   ],
   "scripts": {
     "test": "node --test",