smart-home-engine 2.0.0 → 2.1.0

package/src/lib/timing.js

@@ -0,0 +1,416 @@
+'use strict';
+/**
+ * Timing helpers for scripts: debounce, throttle, a restartable timeout, retry with
+ * backoff, and the debounce/throttle of a subscription.
+ *
+ * The helpers do not touch Node's timers. They take the script's tracked timer primitives, so every
+ * pending run is cleared when the script is unloaded or hot-reloaded and shows up in the timer list
+ * with its kind and name. Errors thrown by the wrapped function propagate to the caller — the
+ * sandbox runs the timer callbacks inside the script's domain, which logs them with the script name.
+ *
+ * Units: the function helpers take milliseconds like setTimeout; the subscription options take
+ * seconds like `shift` and `random`.
+ */
+
+const { isValidDelay, describeDelay } = require('./script-timers');
+
+function assertFn(fn, api, what = 'fn') {
+    if (typeof fn !== 'function') throw new TypeError(`${api}: ${what} must be a function (got ${describeDelay(fn)})`);
+}
+
+function assertDelay(ms, api, what) {
+    if (!isValidDelay(ms)) throw new TypeError(`${api}: ${what} must be a number of milliseconds (got ${describeDelay(ms)})`);
+}
+
+/**
+ * @param {object} prim the script's primitives
+ * @param {Function} prim.setTimeout (fn, ms, meta) → id; meta is { kind, name } for the timer list
+ * @param {Function} prim.clearTimeout (id)
+ * @param {Function} [prim.now] → ms, default Date.now
+ * @param {Function} [prim.onUnload] (fn) → off(); fn runs when the script is unloaded
+ * @returns {{ debounce: Function, throttle: Function, timeout: Function, retry: Function }}
+ */
+function createTimingHelpers(prim) {
+    const { setTimeout: setTimer, clearTimeout: clearTimer } = prim;
+    const now = prim.now || Date.now;
+    const onUnload = typeof prim.onUnload === 'function' ? prim.onUnload : () => () => {};
+
+    /**
+     * Bundle calls: run fn with the arguments of the last call once `wait` ms passed without a new
+     * call — at the latest `maxWait` ms after the first call of a bundle.
+     * @param {Function} fn
+     * @param {number} wait ms
+     * @param {object} [opts]
+     * @param {number} [opts.maxWait] ms; run at the latest this long after the first bundled call
+     * @param {boolean} [opts.leading=false] run on the first call of a bundle as well
+     * @param {boolean} [opts.trailing=true] run after the quiet period (with the last call's arguments)
+     * @param {boolean} [opts.flushOnUnload=false] run a pending call when the script is unloaded
+     * @param {string} [opts.name] shown in the timer list
+     * @returns {Function} wrapped(...args) with cancel(), flush(), pending()
+     */
+    function debounce(fn, wait, opts = {}) {
+        const api = 'she.debounce(fn, wait, [opts])';
+        assertFn(fn, api);
+        assertDelay(wait, api, 'wait');
+        const { leading = false, trailing = true, maxWait, flushOnUnload = false, _onSettle } = opts;
+        if (maxWait !== undefined) assertDelay(maxWait, api, 'opts.maxWait');
+        if (!leading && !trailing) throw new TypeError(`${api}: opts.leading and opts.trailing cannot both be false`);
+        const name = opts.name || fn.name || undefined;
+        const meta = { kind: 'debounce', name };
+        const maxMeta = { kind: 'debounce maxWait', name };
+
+        let timer = null;
+        let maxTimer = null;
+        let lastArgs = null;
+        let waiting = false; // a call waits to run
+        let result;
+
+        function settle() {
+            lastArgs = null;
+            waiting = false;
+            if (timer === null && maxTimer === null && typeof _onSettle === 'function') _onSettle();
+        }
+        function clearTimers() {
+            if (timer !== null) clearTimer(timer);
+            if (maxTimer !== null) clearTimer(maxTimer);
+            timer = maxTimer = null;
+        }
+        function invoke() {
+            const args = lastArgs;
+            lastArgs = null;
+            waiting = false;
+            result = fn(...args);
+            if (timer === null && maxTimer === null && typeof _onSettle === 'function') _onSettle();
+            return result;
+        }
+        function onWait() {
+            timer = null;
+            if (maxTimer !== null) {
+                clearTimer(maxTimer);
+                maxTimer = null;
+            }
+            if (trailing && waiting) invoke();
+            else settle();
+        }
+        function onMaxWait() {
+            maxTimer = null;
+            if (timer !== null) {
+                clearTimer(timer);
+                timer = null;
+            }
+            if (waiting) invoke();
+            else settle();
+        }
+        function wrapped(...args) {
+            const idle = timer === null;
+            lastArgs = args;
+            if (idle && maxWait !== undefined && maxTimer === null) maxTimer = setTimer(onMaxWait, maxWait, maxMeta);
+            if (timer !== null) clearTimer(timer);
+            timer = setTimer(onWait, wait, meta);
+            if (idle && leading) invoke();
+            else waiting = true;
+            return result;
+        }
+        wrapped.cancel = () => {
+            clearTimers();
+            settle();
+        };
+        wrapped.flush = () => {
+            clearTimers();
+            if (waiting) return invoke();
+            settle();
+            return result;
+        };
+        wrapped.pending = () => waiting;
+        if (flushOnUnload) onUnload(() => wrapped.flush());
+        return wrapped;
+    }
+
+    /**
+     * Rate-limit calls: run fn at most once per `wait` ms — on the first call of a window
+     * (leading) and, when more calls came in, once more with the last arguments when the window ends
+     * (trailing).
+     * @param {Function} fn
+     * @param {number} wait ms
+     * @param {object} [opts]
+     * @param {boolean} [opts.leading=true]
+     * @param {boolean} [opts.trailing=true]
+     * @param {string} [opts.name] shown in the timer list
+     * @returns {Function} wrapped(...args) with cancel(), flush(), pending()
+     */
+    function throttle(fn, wait, opts = {}) {
+        const api = 'she.throttle(fn, wait, [opts])';
+        assertFn(fn, api);
+        assertDelay(wait, api, 'wait');
+        const { leading = true, trailing = true, _onSettle } = opts;
+        if (!leading && !trailing) throw new TypeError(`${api}: opts.leading and opts.trailing cannot both be false`);
+        const meta = { kind: 'throttle', name: opts.name || fn.name || undefined };
+
+        let timer = null;
+        let lastArgs = null;
+        let waiting = false;
+        let result;
+
+        function settle() {
+            lastArgs = null;
+            waiting = false;
+            if (timer === null && typeof _onSettle === 'function') _onSettle();
+        }
+        function invoke() {
+            const args = lastArgs;
+            lastArgs = null;
+            waiting = false;
+            result = fn(...args);
+            if (timer === null && typeof _onSettle === 'function') _onSettle();
+            return result;
+        }
+        function onWindowEnd() {
+            timer = null;
+            if (trailing && waiting) {
+                // the trailing run opens a new window, so runs stay `wait` apart
+                timer = setTimer(onWindowEnd, wait, meta);
+                invoke();
+            } else settle();
+        }
+        function wrapped(...args) {
+            lastArgs = args;
+            if (timer === null) {
+                timer = setTimer(onWindowEnd, wait, meta);
+                if (leading) invoke();
+                else waiting = true;
+            } else waiting = true;
+            return result;
+        }
+        wrapped.cancel = () => {
+            if (timer !== null) clearTimer(timer);
+            timer = null;
+            settle();
+        };
+        wrapped.flush = () => {
+            if (timer !== null) clearTimer(timer);
+            timer = null;
+            if (waiting) return invoke();
+            settle();
+            return result;
+        };
+        wrapped.pending = () => waiting;
+        return wrapped;
+    }
+
+    /**
+     * A debounce or throttle with a separate state per key. The key is the first argument of the
+     * call unless opts.key(...args) says otherwise. Idle keys are forgotten, so a wildcard
+     * subscription does not accumulate state.
+     */
+    function keyed(factory, api) {
+        return function keyedHelper(fn, wait, opts = {}) {
+            assertFn(fn, api);
+            const { key: keyFn, flushOnUnload = false, name, ...rest } = opts;
+            if (keyFn !== undefined) assertFn(keyFn, api, 'opts.key');
+            const states = new Map();
+            const forKey = (key) => {
+                let state = states.get(key);
+                if (!state) {
+                    state = factory(fn, wait, { ...rest, name: name ? `${name} ${key}` : String(key), _onSettle: () => states.delete(key) });
+                    states.set(key, state);
+                }
+                return state;
+            };
+            function wrapped(...args) {
+                const key = keyFn ? keyFn(...args) : args[0];
+                return forKey(key)(...args);
+            }
+            // without a key: every key
+            wrapped.cancel = (key) => {
+                if (key !== undefined) states.get(key)?.cancel();
+                else for (const state of [...states.values()]) state.cancel();
+            };
+            wrapped.flush = (key) => {
+                if (key !== undefined) return states.get(key)?.flush();
+                for (const state of [...states.values()]) state.flush();
+                return undefined;
+            };
+            wrapped.pending = (key) => {
+                if (key !== undefined) return states.get(key)?.pending() ?? false;
+                for (const state of states.values()) if (state.pending()) return true;
+                return false;
+            };
+            wrapped.keys = () => [...states.keys()];
+            // validate eagerly, so a wrong wait fails at load time and not on the first call
+            factory(fn, wait, { ...rest, _onSettle: undefined }).cancel();
+            if (flushOnUnload) onUnload(() => wrapped.flush());
+            return wrapped;
+        };
+    }
+    debounce.keyed = keyed(debounce, 'she.debounce.keyed(fn, wait, [opts])');
+    throttle.keyed = keyed(throttle, 'she.throttle.keyed(fn, wait, [opts])');
+
+    /**
+     * A restartable one-shot timer. It is created idle: restart() arms it, another restart() starts
+     * the delay over, cancel() disarms it.
+     * @param {number} ms
+     * @param {Function} cb
+     * @param {object} [opts]
+     * @param {string} [opts.name] shown in the timer list
+     * @returns {{ restart: Function, start: Function, cancel: Function, pending: Function, remaining: Function }}
+     */
+    function timeout(ms, cb, opts = {}) {
+        const api = 'she.timeout(ms, cb, [opts])';
+        assertDelay(ms, api, 'ms');
+        assertFn(cb, api, 'cb');
+        const meta = { kind: 'timeout', name: opts.name || cb.name || undefined };
+        let id = null;
+        let due = 0;
+        const handle = {
+            /** (Re)arm the timer; a new delay replaces the one given at creation. */
+            restart(newMs) {
+                if (newMs !== undefined) {
+                    assertDelay(newMs, 'timeout.restart([ms])', 'ms');
+                    ms = newMs;
+                }
+                if (id !== null) clearTimer(id);
+                due = now() + ms;
+                id = setTimer(
+                    () => {
+                        id = null;
+                        cb();
+                    },
+                    ms,
+                    meta,
+                );
+                return handle;
+            },
+            cancel() {
+                if (id !== null) clearTimer(id);
+                id = null;
+                return handle;
+            },
+            pending: () => id !== null,
+            remaining: () => (id === null ? 0 : Math.max(0, due - now())),
+        };
+        handle.start = handle.restart;
+        return handle;
+    }
+
+    /**
+     * Call fn until it succeeds, waiting between the attempts. fn(attempt) may return a promise.
+     * The promise resolves with fn's result; when every attempt failed it calls onFail(err, tries)
+     * and resolves with its return value, or — without onFail — rejects with the last error. A
+     * script unload stops the attempts; the promise then never settles.
+     * @param {Function} fn
+     * @param {object} [opts]
+     * @param {number} [opts.tries=3] attempts in total
+     * @param {number} [opts.delay=1000] ms before the second attempt
+     * @param {number} [opts.backoff=1] the delay is multiplied by this after each failure (2 doubles it)
+     * @param {Function} [opts.onFail] (err, tries) after the last failure
+     * @param {string} [opts.name] shown in the timer list
+     * @returns {Promise}
+     */
+    function retry(fn, opts = {}) {
+        const api = 'she.retry(fn, [opts])';
+        assertFn(fn, api);
+        const { tries = 3, delay = 1000, backoff = 1, onFail } = opts;
+        if (!Number.isInteger(tries) || tries < 1) throw new TypeError(`${api}: opts.tries must be a whole number of attempts, at least 1 (got ${describeDelay(tries)})`);
+        assertDelay(delay, api, 'opts.delay');
+        if (typeof backoff !== 'number' || !Number.isFinite(backoff) || backoff < 0) throw new TypeError(`${api}: opts.backoff must be a factor (got ${describeDelay(backoff)})`);
+        if (onFail !== undefined) assertFn(onFail, api, 'opts.onFail');
+        const name = opts.name || fn.name || undefined;
+
+        let aborted = false;
+        const off = onUnload(() => {
+            aborted = true;
+        });
+        return new Promise((resolve, reject) => {
+            const attempt = (n) => {
+                if (aborted) return;
+                let p;
+                try {
+                    p = Promise.resolve(fn(n));
+                } catch (err) {
+                    p = Promise.reject(err);
+                }
+                p.then(
+                    (value) => {
+                        off();
+                        resolve(value);
+                    },
+                    (err) => {
+                        if (aborted) return;
+                        if (n >= tries) {
+                            off();
+                            if (onFail) {
+                                try {
+                                    resolve(onFail(err, n));
+                                } catch (e) {
+                                    reject(e);
+                                }
+                            } else reject(err);
+                            return;
+                        }
+                        const wait = delay * Math.pow(backoff, n - 1);
+                        setTimer(() => attempt(n + 1), wait, { kind: 'retry', name: `${name ? name + ' ' : ''}attempt ${n + 1}/${tries}` });
+                    },
+                );
+            };
+            attempt(1);
+        });
+    }
+
+    return { debounce, throttle, timeout, retry };
+}
+
+/**
+ * The limiter of a subscription (sub options `debounce`, `maxWait`, `throttle`, `perTopic`, `name`;
+ * seconds). Returns deliver'(topic, val, obj, objPrev, msg): events are bundled, and the callback
+ * gets the last event's topic, val, obj and msg with the objPrev from before the first bundled
+ * event — so a comparison of obj and objPrev still tells whether the value really changed.
+ * @param {object} options the subscription options
+ * @param {Function} deliver (topic, val, obj, objPrev, msg) runs the script's callback
+ * @param {object} helpers from createTimingHelpers
+ * @param {string} label the default name for the timer list (the topic)
+ * @returns {Function|null} the limited deliver, or null when the options ask for none
+ */
+function subscriptionLimiter(options, deliver, helpers, label) {
+    const api = 'she.mqtt.sub(topic, opts, cb)';
+    const seconds = (what) => {
+        const v = options[what];
+        if (v === undefined) return undefined;
+        if (!isValidDelay(v)) throw new TypeError(`${api}: opts.${what} must be a number of seconds (got ${describeDelay(v)})`);
+        return v * 1000;
+    };
+    const debounce = seconds('debounce');
+    const throttle = seconds('throttle');
+    const maxWait = seconds('maxWait');
+    if (debounce === undefined && throttle === undefined) {
+        if (maxWait !== undefined) throw new TypeError(`${api}: opts.maxWait needs opts.debounce`);
+        return null;
+    }
+    if (debounce !== undefined && throttle !== undefined) throw new TypeError(`${api}: opts.debounce and opts.throttle exclude each other`);
+    if (throttle !== undefined && maxWait !== undefined) throw new TypeError(`${api}: opts.maxWait needs opts.debounce, not opts.throttle`);
+    const perTopic = !!options.perTopic;
+    const name = options.name !== undefined ? String(options.name) : label;
+
+    const firstPrev = new Map(); // key → objPrev of the first bundled event
+    const keyOf = (topic) => (perTopic ? topic : '');
+    const run = (topic, val, obj, objPrev, msg) => {
+        const key = keyOf(topic);
+        const prev = firstPrev.has(key) ? firstPrev.get(key) : objPrev;
+        firstPrev.delete(key);
+        deliver(topic, val, obj, prev, msg);
+    };
+    let limited;
+    if (debounce !== undefined) {
+        const opts = { maxWait, name, flushOnUnload: !!options.flushOnUnload, leading: !!options.leading, trailing: options.trailing !== false };
+        limited = perTopic ? helpers.debounce.keyed(run, debounce, opts) : helpers.debounce(run, debounce, opts);
+    } else {
+        const opts = { name, leading: options.leading !== false, trailing: options.trailing !== false };
+        limited = perTopic ? helpers.throttle.keyed(run, throttle, opts) : helpers.throttle(run, throttle, opts);
+    }
+    return (topic, val, obj, objPrev, msg) => {
+        const key = keyOf(topic);
+        if (!firstPrev.has(key)) firstPrev.set(key, objPrev);
+        limited(topic, val, obj, objPrev, msg);
+    };
+}
+
+module.exports = { createTimingHelpers, subscriptionLimiter };

package/src/matter/thread-mesh.js

@@ -46,6 +46,39 @@ function hex64(v) {
 }
 
 /** LQI 3 → good, 2 → fair, 1 → poor, 0 → unknown (the OHF dashboard's colours). */
+/**
+ * A Thread partition ID as 8 hex digits: devices report it as a number (Network Diagnostics), border
+ * routers as hex (their mDNS TXT record) — the same partition must compare equal.
+ */
+function partitionHex(v) {
+    if (typeof v === 'number' || typeof v === 'bigint' || /^\d+$/.test(String(v))) {
+        return Number(v).toString(16).toUpperCase().padStart(8, '0');
+    }
+    return String(v).toUpperCase().padStart(8, '0');
+}
+
+/** an IPv6 address from 16 bytes (a Uint8Array or `{ $bytes }`) in the usual short form */
+function _ipv6(v) {
+    const buf = v?.$bytes ? Buffer.from(v.$bytes, 'hex') : ArrayBuffer.isView(v) ? Buffer.from(v.buffer, v.byteOffset, v.byteLength) : null;
+    if (!buf || buf.length !== 16) return null;
+    const groups = [];
+    for (let i = 0; i < 16; i += 2) groups.push(buf.readUInt16BE(i).toString(16));
+    // the longest run of two or more zero groups becomes "::"
+    let best = { at: -1, len: 0 };
+    for (let i = 0; i < 8; ) {
+        if (groups[i] !== '0') {
+            i++;
+            continue;
+        }
+        let j = i;
+        while (j < 8 && groups[j] === '0') j++;
+        if (j - i > best.len && j - i > 1) best = { at: i, len: j - i };
+        i = j;
+    }
+    if (best.at < 0) return groups.join(':');
+    return `${groups.slice(0, best.at).join(':')}::${groups.slice(best.at + best.len).join(':')}`;
+}
+
 function lqiQuality(lqi) {
     if (lqi >= 3) return 'good';
     if (lqi === 2) return 'fair';
@@ -68,7 +101,7 @@ function rssiQuality(rssi) {
  * @param {object[]} bindings  M13's binding list
  */
 function buildGraph(nodes, borderRouters = [], bindings = [], meshcop = []) {
-    const out = { nodes: [], links: [], networks: [], meshcop: { nodes: 0, networks: [] } };
+    const out = { nodes: [], links: [], networks: [], hidden: { wifi: 0, other: 0 }, meshcop: { nodes: 0, networks: [] } };
     const byExt = new Map();
     const byRloc = new Map();
     const byNodeId = new Map();
@@ -87,6 +120,8 @@ function buildGraph(nodes, borderRouters = [], bindings = [], meshcop = []) {
                 channel: n.thread.channel ?? null,
                 partitionId: n.thread.partitionId ?? null,
                 networkName: n.thread.networkName ?? null,
+                extPanId: n.thread.extPanId ?? null,
+                ipv6: n.thread.ipv6 ?? [],
                 neighbours: (n.thread.neighborTable ?? []).length,
                 routes: (n.thread.routeTable ?? []).length,
                 readAt: n.thread.readAt ?? null,
@@ -95,23 +130,10 @@ function buildGraph(nodes, borderRouters = [], bindings = [], meshcop = []) {
             byNodeId.set(n.nodeId, g);
             if (g.extAddress) byExt.set(g.extAddress, g);
             if (g.rloc16 !== null) byRloc.set(g.rloc16, g);
-        } else if (n.wifi) {
-            const g = {
-                id: `node:${n.nodeId}`,
-                kind: 'wifi',
-                nodeId: n.nodeId,
-                name: n.name ?? `Node ${n.nodeId}`,
-                online: !!n.online,
-                rssi: n.wifi.rssi ?? null,
-                bssid: n.wifi.bssid ?? null,
-                quality: rssiQuality(n.wifi.rssi),
-            };
-            out.nodes.push(g);
-            byNodeId.set(n.nodeId, g);
         } else {
-            const g = { id: `node:${n.nodeId}`, kind: 'other', nodeId: n.nodeId, name: n.name ?? `Node ${n.nodeId}`, online: !!n.online };
-            out.nodes.push(g);
-            byNodeId.set(n.nodeId, g);
+            // Wi-Fi, Ethernet and devices without diagnostics (offline, bridges) are not part of a Thread
+            // mesh: counted for the caption, not drawn
+            out.hidden[n.wifi ? 'wifi' : 'other']++;
         }
     }
     // border routers: a graph node each, joined to a fabric node when the ext address matches
@@ -133,6 +155,9 @@ function buildGraph(nodes, borderRouters = [], bindings = [], meshcop = []) {
             role: br.state?.role ?? null,
             online: true,
             rloc16: br.rest?.node?.rloc16 ?? null,
+            partitionId: br.partitionId ?? null,
+            addresses: br.addresses ?? [],
+            hostname: br.hostname ?? null,
         };
         out.nodes.push(g);
         if (ext) byExt.set(ext, g);
@@ -158,6 +183,8 @@ function buildGraph(nodes, borderRouters = [], bindings = [], meshcop = []) {
                         extAddress: ext,
                         rloc16: nb.rloc16 ?? null,
                         online: true,
+                        networkName: from.networkName ?? null,
+                        extPanId: from.extPanId ?? null,
                         explanation:
                             "A neighbour of a device in she's fabric that is not paired with she: a device of another controller, or a border router that announces a different address.",
                     };
@@ -263,14 +290,24 @@ function buildGraph(nodes, borderRouters = [], bindings = [], meshcop = []) {
             label: `${b.sourceEndpointName ?? 'ep ' + b.sourceEndpointId} → ${b.targetEndpointName ?? 'ep ' + b.endpoint}`,
         });
     }
-    // networks seen in the fabric
+    // the Thread networks: every drawn node belongs to one (by extended PAN ID, else by name), so the graph
+    // can group them — border routers of the same network included, whether in she's fabric or not
     const nets = new Map();
     for (const g of out.nodes) {
-        if (g.kind !== 'thread' || !g.networkName) continue;
-        const n = nets.get(g.networkName) ?? { networkName: g.networkName, partitions: new Set(), channel: g.channel ?? null, nodes: 0 };
-        if (g.partitionId !== null && g.partitionId !== undefined) n.partitions.add(String(g.partitionId));
+        if (!g.extPanId && g.networkName) {
+            const byName = out.nodes.find((x) => x.extPanId && x.networkName === g.networkName);
+            if (byName) g.extPanId = byName.extPanId;
+        }
+        const key = g.extPanId || (g.networkName ? `name:${g.networkName}` : null);
+        if (!key) continue;
+        g.network = key;
+        const n = nets.get(key) ?? { key, extPanId: g.extPanId ?? null, networkName: g.networkName ?? null, partitions: new Set(), channel: null, nodes: 0, borderRouters: 0 };
+        if (!n.networkName && g.networkName) n.networkName = g.networkName;
+        if (g.partitionId !== null && g.partitionId !== undefined) n.partitions.add(partitionHex(g.partitionId));
+        if (n.channel === null && g.channel !== null && g.channel !== undefined) n.channel = g.channel;
         n.nodes++;
-        nets.set(g.networkName, n);
+        if (g.kind === 'border-router' || g.borderRouter) n.borderRouters++;
+        nets.set(key, n);
     }
     out.networks = [...nets.values()].map((n) => ({ ...n, partitions: [...n.partitions] }));
     return out;
@@ -297,6 +334,8 @@ function _nodeData(node, nodeId) {
             partitionId: tnd.partitionId === undefined || tnd.partitionId === null ? null : Number(tnd.partitionId),
             leaderRouterId: tnd.leaderRouterId ?? null,
             networkName: tnd.networkName ?? null,
+            extPanId: hex64(tnd.extendedPanId),
+            ipv6: (threadIf?.iPv6Addresses ?? []).map(_ipv6).filter(Boolean),
             neighborTable: fresh?.neighborTable ?? (Array.isArray(tnd.neighborTable) ? tnd.neighborTable : []),
             routeTable: fresh?.routeTable ?? (Array.isArray(tnd.routeTable) ? tnd.routeTable : []),
             readAt: fresh?.readAt ?? null,
@@ -493,4 +532,4 @@ function stop() {
     _lastRefresh = null;
 }
 
-module.exports = { buildGraph, getMesh, refresh, meshcopQuery, start, stop, hex64, lqiQuality, rssiQuality, ROLES, _tables, _meshcop, _meshcopNode };
+module.exports = { _ipv6, partitionHex, buildGraph, getMesh, refresh, meshcopQuery, start, stop, hex64, lqiQuality, rssiQuality, ROLES, _tables, _meshcop, _meshcopNode };

package/src/sandbox/stdlib.js

@@ -123,6 +123,15 @@ module.exports = function (she, ctx = {}) {
          * cleared by an initial timeout on startup.
          */
         timer: function Sandbox_mqtt_timer(src, ms, target) {
+            // Swapped arguments used to become a 1 ms timer and a variable named like the number —
+            // silently, apart from Node's anonymous TimeoutNaNWarning. Fail at load instead.
+            const signature = 'she.mqtt.timer(src, ms, target)';
+            if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) {
+                throw new TypeError(`${signature}: ms must be a number of milliseconds (got ${typeof ms === 'string' ? JSON.stringify(ms) : String(ms)})`);
+            }
+            if (typeof target !== 'string' && typeof target !== 'function') {
+                throw new TypeError(`${signature}: target must be a topic string or a callback (got ${typeof target})`);
+            }
             const key = target;
             she.mqttsub(src, { retain: false }, (topic, val) => {
                 if (isTruthy(val)) {

package/src/web/ai-tools.js

@@ -1532,7 +1532,7 @@ function toolListTimers({ script = '' } = {}, ctx = {}) {
     for (const sc of ctx.introspect.scripts()) {
         if (q && !sc.label.toLowerCase().includes(q)) continue;
         const items = [
-            ...sc.timers.map((t) => (t.every ? `interval every ${ago(t.every)}, next ${inTime(t.due)}` : `timer ${inTime(t.due)}`)),
+            ...sc.timers.map((t) => (t.every ? `interval every ${ago(t.every)}, next ${inTime(t.due)}` : `${t.kind || 'timer'}${t.name ? ` "${t.name}"` : ''} ${inTime(t.due)}`)),
             ...sc.jobs.map((j) => `schedule job ${inTime(j.next)}`),
             ...sc.sunEvents.map((e) => `${e.pattern} ${inTime(e.next)}`),
         ];

package/src/web/prompts/api-ref-compact.md

@@ -1,8 +1,8 @@
 ## she sandbox API (the common part)
 Scripts start with `/* global she */` and `'use strict';`. `require()` works for installed npm packages.
 ```
-she.mqtt.sub(topic, [opts], cb)     cb(topic, val, obj)   opts: { change: true } fires on changes only; wildcards + and #
-she.mqtt.pub(topic, payload)        publish (commands: no retain)
+she.mqtt.sub(topic, [opts], cb)     cb(topic, val, obj)   opts: { change: true } fires on changes only; { debounce: 5, maxWait: 15 } (SECONDS) bundles events; wildcards + and #
+she.mqtt.pub(topic, payload, [opts]) publish (commands: no retain); { changed: true } publishes only when the payload differs from the last one
 she.mqtt.get(topic)                 last known value
 she.mqtt.age(topic)                 seconds since the value last changed
 she.mqtt.timer(src, ms, target)     publish 1 when src turns truthy, 0 after ms
@@ -10,7 +10,8 @@ she.mqtt.or(srcs[], target) / and   publish 1 when any / all sources are truthy,
 she.schedule('0 7 * * *', cb)       cron string, Date, or 'sunrise' / 'sunset' with { shift: seconds }
 she.http.fetch(url, [opts])         → Promise<{ body, code, headers }>
 she.debug / info / warn / error     logging
-setTimeout / setInterval            available
+setTimeout / setInterval            available; she.timeout(ms, cb) → handle.restart()/cancel() is a restartable timer (motion light)
+she.debounce(fn, ms, [{ maxWait }]) / she.throttle(fn, ms) / she.retry(fn, { tries, delay, onFail })   MILLISECONDS; cleared on reload
 ```
 Variables: read `var/status/<name>`, write `she.mqtt.pub('var/set/<name>', value)`.
 For anything else ask with the tool she_api_doc or say that you are not sure.

package/src/web/prompts/api-ref.md

@@ -8,23 +8,41 @@ she.mqtt.sub(topic, [opts], cb)        Subscribe; topic may be a string or an ar
     opts.retain     also fire for the retained value present on connect and script start
     opts.shift      delay the callback by N seconds; opts.random adds up to N random seconds
     opts.condition  fn(val) or a one-line JS string over val/obj/objPrev; the callback runs only when truthy
-    cb(topic, val, obj, objPrev, msg)   obj and objPrev are { val, ts, lc }
-she.mqtt.pub(topic, payload, [opts])   Publish; objects are JSON-stringified; opts { qos, retain }
+    opts.debounce   SECONDS: bundle events, one callback once nothing came in for N s; opts.maxWait (seconds) runs it at the latest then
+    opts.throttle   SECONDS: the first event at once, then at most one callback per N s (with the last event)
+    opts.perTopic   with debounce/throttle on an array or wildcard: one bundle per topic; opts.name names it in the timer list
+    opts.flushOnUnload  with debounce: run a pending callback once on unload/reload (default: dropped)
+    cb(topic, val, obj, objPrev, msg)   obj and objPrev are { val, ts, lc }; debounced: the last event, objPrev from before the first bundled one
+she.mqtt.pub(topic, payload, [opts])   Publish; objects are JSON-stringified; opts { qos, retain, changed }
+    opts.changed    publish only when the payload differs from this script's last publish to the topic (before that: from the topic's state, set→status)
 she.mqtt.get(topic)                    Last known value (undefined when never seen); an empty payload removes a topic
 she.mqtt.getProp(topic, 'val'|'ts'|'lc')  One property of the state; without a property the whole { val, ts, lc }
 she.mqtt.age(topic, ['message'])       Seconds since the last change, or since the last message with 'message'; NaN when never seen
 she.mqtt.link(src, target, [fn])       Forward src changes to target, optionally transformed
 she.mqtt.or / and / max / min(srcs[], topicOrCb)   Combine sources; publish 1/0 or the extreme value; re-evaluated on every change
-she.mqtt.timer(src, ms, topicOrCb)     Publish 1 when src turns truthy, 0 after ms; restarted when src fires again
+she.mqtt.timer(src, ms, topicOrCb)     Publish 1 when src turns truthy, 0 after ms (a number — swapped arguments throw at load); restarted when src fires again
                                         topicOrCb: a topic string or cb(topic, val)
 ```
 
+### Timing helpers (MILLISECONDS, like setTimeout; cleared on unload/reload; pending runs listed by list_timers with kind and name)
+```
+she.timeout(ms, cb, [{ name }])         A restartable timer, created idle → handle.restart([ms]) arms or starts over, cancel(), pending(), remaining()
+                                        the motion-light pattern: off.restart() on every motion, off.cancel() when the state changes
+she.debounce(fn, wait, [opts])          Bundle calls: fn runs with the LAST call's args after `wait` ms of quiet; opts { maxWait, leading=false, trailing=true, flushOnUnload, name }
+                                        → wrapped(...args) with cancel(), flush(), pending(); maxWait keeps a never-resting source from starving fn
+she.throttle(fn, wait, [opts])          Rate-limit: first call at once, then at most once per `wait` ms; opts { leading=true, trailing=true, name }; trailing:false = fire, then block
+she.debounce.keyed / she.throttle.keyed(fn, wait, [opts])   One state per key (the first argument, or opts.key(...args)); cancel(key)/flush(key)/pending(key), without key: all
+she.retry(fn, [opts])                   → Promise; fn(attempt) may be async; opts { tries=3, delay=1000, backoff=1, onFail(err, tries), name }
+                                        resolves with fn's result; after the last failure: onFail's return value, or rejects without onFail; an unload stops it
+she.setTimeout / she.clearTimeout       The sandbox's setTimeout/clearTimeout under she (official aliases); a non-number delay is logged with the script name
+```
+
 ### Scheduling
 ```
 she.schedule(pattern, [opts], cb)      pattern: cron string | Date | 'sunrise' 'sunset' 'dawn' 'dusk' 'nauticalDawn' 'nauticalDusk' 'solarNoon' 'night'
     opts.shift    seconds offset (-1800 = 30 min before);  opts.random  up to N random seconds later
 she.now()                              Milliseconds since the epoch
-setTimeout / setInterval               Available; cleared automatically when the script is unloaded
+setTimeout / setInterval               Available; cleared automatically when the script is unloaded; a bad delay is logged with the script name
 ```
 
 ### sheDB (documents, ids like topics: devices/lamp1)