@devicechain/dashboards 0.23.0 → 0.24.0

package/dist/index.js

@@ -57,6 +57,7 @@ var WIDGET_TYPES = [
   "image",
   "alarm-table",
   "alarm-count",
+  "alarm-severity",
   "command-button",
   "entity-selector",
   "map",
@@ -72,7 +73,10 @@ var WIDGET_TYPES = [
   "stat-card",
   "bar-chart",
   "pie-chart",
-  "fleet-table"
+  "fleet-table",
+  "fleet-count",
+  "device-status",
+  "online-doughnut"
 ];
 var PLACEMENT_ANCHORS = [
   "top-left",
@@ -1381,6 +1385,81 @@ function bindingMatchesType(binding, type) {
   return binding.kind === type;
 }
 
+// src/deep-link.ts
+import { isValidToken } from "@devicechain/client";
+var BIND_PARAM_PREFIX = "bind.";
+function ownSlot(definition, slot) {
+  const slots = definition.slots;
+  return slots && Object.prototype.hasOwnProperty.call(slots, slot) ? slots[slot] : void 0;
+}
+function parseBindParams(search, definition) {
+  const binds = {};
+  const issues = [];
+  const params = new URLSearchParams(search);
+  const seen = /* @__PURE__ */ new Set();
+  for (const [key, token] of params) {
+    if (!key.startsWith(BIND_PARAM_PREFIX)) continue;
+    const slot = key.slice(BIND_PARAM_PREFIX.length);
+    if (seen.has(slot)) continue;
+    seen.add(slot);
+    const def = ownSlot(definition, slot);
+    if (params.getAll(key).length > 1) issues.push({ kind: "duplicate-slot", slot, token });
+    else if (!def) issues.push({ kind: "unknown-slot", slot, token });
+    else if (def.type !== "device") issues.push({ kind: "not-a-device-slot", slot, token });
+    else if (def.scope?.strategy === "first") issues.push({ kind: "derived-slot", slot, token });
+    else if (!isValidToken(token)) issues.push({ kind: "invalid-token", slot, token });
+    else Object.defineProperty(binds, slot, { value: token, enumerable: true, writable: true, configurable: true });
+  }
+  return { binds, issues };
+}
+async function validateBinds(binds, resolver) {
+  const out = { ok: {}, missing: [], failed: [] };
+  await Promise.all(
+    Object.entries(binds).map(async ([slot, token]) => {
+      try {
+        if (await resolver.deviceExists(token)) Object.defineProperty(out.ok, slot, { value: token, enumerable: true, writable: true, configurable: true });
+        else out.missing.push({ slot, token });
+      } catch {
+        out.failed.push({ slot, token });
+      }
+    })
+  );
+  return out;
+}
+function bindsToSelection(binds) {
+  const out = {};
+  for (const [slot, deviceToken] of Object.entries(binds)) {
+    Object.defineProperty(out, slot, {
+      value: { kind: "device", deviceToken },
+      enumerable: true,
+      writable: true,
+      configurable: true
+    });
+  }
+  return out;
+}
+function selectionToBinds(selection, definition) {
+  const out = {};
+  for (const slot of Object.keys(selection)) {
+    const b = selection[slot];
+    if (b.kind !== "device" || ownSlot(definition, slot)?.type !== "device") continue;
+    Object.defineProperty(out, slot, { value: b.deviceToken, enumerable: true, writable: true, configurable: true });
+  }
+  return out;
+}
+function withBindParams(search, binds) {
+  const next = new URLSearchParams();
+  for (const [k, v] of new URLSearchParams(search)) if (!k.startsWith(BIND_PARAM_PREFIX)) next.append(k, v);
+  for (const slot of Object.keys(binds).sort()) next.append(BIND_PARAM_PREFIX + slot, binds[slot]);
+  return next.toString();
+}
+function bindParamsOf(search) {
+  const only = new URLSearchParams();
+  for (const [k, v] of new URLSearchParams(search)) if (k.startsWith(BIND_PARAM_PREFIX)) only.append(k, v);
+  only.sort();
+  return only.toString();
+}
+
 // src/slots.ts
 function slotSelector(slot, measurements, location) {
   return location ? { kind: "slot", slot, measurements, location } : { kind: "slot", slot, measurements };
@@ -1621,6 +1700,9 @@ var CUSTOMER_DEVICES = `
       results {
         token
         name
+        deviceType {
+          token
+        }
       }
       pagination {
         totalRecords
@@ -1640,6 +1722,23 @@ var DEVICE_NAMES = `
     devicesByToken(tokens: $tokens) {
       token
       name
+      deviceType {
+        token
+      }
+    }
+  }
+`;
+var DECLARED_METRICS = `
+  query DashboardDeclaredMetrics($tokens: [String!]!) {
+    deviceTypesByToken(tokens: $tokens) {
+      token
+      profile {
+        activeProfileVersion {
+          metrics {
+            metricKey
+          }
+        }
+      }
     }
   }
 `;
@@ -1827,6 +1926,34 @@ var ConnectionTracker = class {
   }
 };
 
+// src/event-window.ts
+function eventWindowBounds(window2, now) {
+  const end = window2.endAt ?? now;
+  return { from: end - window2.spanSeconds * 1e3, to: window2.endAt };
+}
+function windowCriteria(window2, now) {
+  if (!window2) return { startTime: null, endTime: null };
+  const { from, to } = eventWindowBounds(window2, now);
+  return { startTime: new Date(from).toISOString(), endTime: to === void 0 ? null : new Date(to).toISOString() };
+}
+var instant = (iso) => {
+  if (!iso) return null;
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? null : t;
+};
+function alarmOverlaps(row, window2, now) {
+  const { from, to } = eventWindowBounds(window2, now);
+  const raised = instant(row.raisedTime);
+  if (raised === null || to !== void 0 && raised > to) return false;
+  const cleared = instant(row.clearedTime);
+  return cleared === null || cleared >= from;
+}
+function commandInRange(row, window2, now) {
+  const { from, to } = eventWindowBounds(window2, now);
+  const at = instant(row.sentTime) ?? instant(row.queuedTime);
+  return at !== null && at >= from && (to === void 0 || at <= to);
+}
+
 // src/hub.ts
 import { gql as gql2, isForbiddenError, isScopeUnsupportedError, subscribe } from "@devicechain/client";
 
@@ -1855,6 +1982,37 @@ var ALARMS_QUERY = `
     }
   }
 `;
+var ALARM_DEVICE_TYPES = `
+  query DashboardAlarmDeviceTypes($tokens: [String!]!) {
+    devicesByToken(tokens: $tokens) {
+      token
+      deviceType {
+        token
+        name
+      }
+    }
+  }
+`;
+var ALARM_TYPE_COUNTS = `
+  query DashboardAlarmTypeCounts($criteria: AlarmCountCriteria!) {
+    alarmCountsByDeviceType(criteria: $criteria) {
+      deviceType {
+        token
+        name
+      }
+      severity
+      count
+    }
+  }
+`;
+var ALARM_SEVERITY_COUNTS = `
+  query DashboardAlarmSeverityCounts($criteria: AlarmCountCriteria!, $deviceType: String) {
+    alarmCountsBySeverity(criteria: $criteria, deviceType: $deviceType) {
+      severity
+      count
+    }
+  }
+`;
 var ALARM_STREAM = `
   subscription DashboardAlarmStream(
     $originatorType: String
@@ -1943,6 +2101,18 @@ var LATEST_LOCATIONS_QUERY = `
   }
 `;
 
+// src/internal/presence-doc.ts
+var DEVICE_PRESENCE_QUERY = `
+  query DashboardDevicePresence($deviceTokens: [String!]!) {
+    deviceStatesByDeviceToken(deviceTokens: $deviceTokens) {
+      deviceToken
+      active
+      lastActivityTime
+      inactivityTimeout
+    }
+  }
+`;
+
 // src/members.ts
 var MEMBER_SEED_CONCURRENCY = 6;
 var SEED_CANCELLED = /* @__PURE__ */ Symbol("member seed cancelled");
@@ -1998,8 +2168,11 @@ function randomToken() {
 }
 var ALARM_RECONCILE_DEBOUNCE_MS = 800;
 var ALARM_POLL_MS = 3e4;
+var ALARM_DEVICE_TYPES_CHUNK = 1e3;
 var COMMAND_POLL_MS = 4e3;
 var LOCATION_POLL_MS = 15e3;
+var PRESENCE_POLL_MS = 15e3;
+var PRESENCE_CHUNK = 1e3;
 var DashboardHub = class {
   constructor(config) {
     // Per alarm-subscription reconcile triggers — invoked after an ack/clear so the
@@ -2023,11 +2196,17 @@ var DashboardHub = class {
     // commandDisposers — the location channel holds a poll per subscription, not a shared
     // device stream), so disposeAll() can tear down every map widget's poll.
     this.locationDisposers = /* @__PURE__ */ new Set();
+    // Live presence-subscription disposers (same rationale: a poll per subscription).
+    this.presenceDisposers = /* @__PURE__ */ new Set();
     // Which of this hub's sockets are down, folded into one state a header can show.
     this.connection = new ConnectionTracker();
     // Streams evicted by an upstream error that still have subscribers: out of `streams`, but
     // still holding their connection handle (see ensureStream), so disposeAll() can reach them.
     this.deadStreams = /* @__PURE__ */ new Set();
+    // One read per distinct device type, whoever asks and however many devices have it. A settled
+    // answer (names, or null for "no published profile") is kept for the session; a failed read is
+    // not, so a later ask tries again, and that ask is answered null meanwhile.
+    this.declared = /* @__PURE__ */ new Map();
     // The hub-wide cap on in-flight member seed reads, and the reads currently in flight (so a second
     // widget asking the same question of the same device shares one request).
     this.seedLimiter = createLimiter(MEMBER_SEED_CONCURRENCY);
@@ -2036,6 +2215,12 @@ var DashboardHub = class {
     // that ask the same question while a read is in flight share it: stat cards on one measurement
     // and span read on the same minute boundaries, so a board of them costs one read per question.
     this.bucketReads = /* @__PURE__ */ new Map();
+    // Each device's type, for the lifetime of the hub: a device's type is fixed for a viewing session,
+    // and the same originators come back every poll. ONE devicesByToken read per chunk of uncached
+    // tokens (the server takes 1000), never one per alarm. A failed read leaves those rows with no
+    // `deviceType` (unknown, so a grouping widget lists them under All only) instead of failing the
+    // whole alarm table, and is retried on the next reconcile because a failure is not cached.
+    this.alarmDeviceTypes = /* @__PURE__ */ new Map();
     this.resolver = config.resolver;
     this.authorities = new Set(config.authorities ?? []);
   }
@@ -2111,6 +2296,19 @@ var DashboardHub = class {
     const members = groups.map((g) => ({ token: g.deviceToken, name: null }));
     return { roster: { members, total: members.length, unbound: datasource.kind === "unbound" }, names };
   }
+  declaredMetrics(deviceType) {
+    const read = this.resolver.declaredMetrics;
+    if (!read) return Promise.resolve(null);
+    let pending = this.declared.get(deviceType);
+    if (!pending) {
+      pending = read.call(this.resolver, deviceType).catch(() => {
+        this.declared.delete(deviceType);
+        return null;
+      });
+      this.declared.set(deviceType, pending);
+    }
+    return pending;
+  }
   async readMemberSeeds(deviceTokens, plan, onSeed, cancelled = () => false) {
     await Promise.all(
       deviceTokens.map(async (token) => {
@@ -2248,26 +2446,50 @@ var DashboardHub = class {
   // and merges — deduped by token, newest first, capped to pageSize; total is the sum of
   // per-originator match counts.
   async queryAlarms(sub, tokens, tenantWide) {
-    const base = {
-      pageNumber: 1,
-      // the alarms query paginates 1-based
-      pageSize: sub.pageSize,
+    const filters = {
       state: sub.state ?? null,
       severity: sub.severity ?? null,
       acknowledged: sub.acknowledged ?? null
     };
-    if (tenantWide) {
-      const data = await gql2(DEVICE_AREA, ALARMS_QUERY, {
-        criteria: { ...base, originatorType: null, originator: null }
-      });
-      return { alarms: data.alarms.results, total: data.alarms.pagination.totalRecords };
+    const originators = tenantWide ? [{ originatorType: null, originator: null }] : tokens.map((token) => ({ originatorType: "device", originator: token }));
+    if (sub.countBySeverity) {
+      const pages2 = await Promise.all(
+        originators.map(
+          (o) => gql2(DEVICE_AREA, ALARM_SEVERITY_COUNTS, { criteria: { ...filters, ...o }, deviceType: sub.deviceType ?? null })
+        )
+      );
+      const merged = /* @__PURE__ */ new Map();
+      for (const page of pages2) {
+        for (const c of page.alarmCountsBySeverity) merged.set(c.severity, (merged.get(c.severity) ?? 0) + c.count);
+      }
+      const severityCounts = [...merged].map(([severity, count]) => ({ severity, count }));
+      return { alarms: [], total: severityCounts.reduce((n, c) => n + c.count, 0), severityCounts };
+    }
+    if (sub.countByDeviceType) {
+      const pages2 = await Promise.all(
+        originators.map((o) => gql2(DEVICE_AREA, ALARM_TYPE_COUNTS, { criteria: { ...filters, ...o } }))
+      );
+      const merged = /* @__PURE__ */ new Map();
+      for (const page of pages2) {
+        for (const c of page.alarmCountsByDeviceType) {
+          const key = `${c.deviceType.token}\0${c.severity}`;
+          const prior = merged.get(key);
+          merged.set(key, prior ? { ...prior, count: prior.count + c.count } : { ...c, deviceType: { ...c.deviceType } });
+        }
+      }
+      const typeCounts = [...merged.values()];
+      return { alarms: [], total: typeCounts.reduce((n, c) => n + c.count, 0), typeCounts };
     }
+    const base = {
+      pageNumber: 1,
+      // the alarms query paginates 1-based
+      pageSize: sub.pageSize,
+      ...filters,
+      deviceType: sub.deviceType ?? null,
+      ...windowCriteria(sub.window, Date.now())
+    };
     const pages = await Promise.all(
-      tokens.map(
-        (token) => gql2(DEVICE_AREA, ALARMS_QUERY, {
-          criteria: { ...base, originatorType: "device", originator: token }
-        })
-      )
+      originators.map((o) => gql2(DEVICE_AREA, ALARMS_QUERY, { criteria: { ...base, ...o } }))
     );
     const byToken = /* @__PURE__ */ new Map();
     let total = 0;
@@ -2275,9 +2497,29 @@ var DashboardHub = class {
       total += page.alarms.pagination.totalRecords;
       for (const row of page.alarms.results) byToken.set(row.token, row);
     }
-    const alarms = [...byToken.values()].sort((a, b) => (b.raisedTime ?? "").localeCompare(a.raisedTime ?? "")).slice(0, sub.pageSize);
+    let alarms = [...byToken.values()].sort((a, b) => (b.raisedTime ?? "").localeCompare(a.raisedTime ?? "")).slice(0, sub.pageSize);
+    if (sub.enrichDeviceType === true) alarms = await this.withDeviceTypes(alarms);
     return { alarms, total };
   }
+  async withDeviceTypes(rows) {
+    const missing = [
+      ...new Set(
+        rows.filter((r) => r.originatorType === "device" && r.originatorToken && !this.alarmDeviceTypes.has(r.originatorToken)).map((r) => r.originatorToken)
+      )
+    ];
+    for (let i = 0; i < missing.length; i += ALARM_DEVICE_TYPES_CHUNK) {
+      try {
+        const r = await gql2(DEVICE_AREA, ALARM_DEVICE_TYPES, { tokens: missing.slice(i, i + ALARM_DEVICE_TYPES_CHUNK) });
+        for (const d of r.devicesByToken) this.alarmDeviceTypes.set(d.token, d.deviceType);
+      } catch {
+      }
+    }
+    return rows.map((r) => {
+      if (r.originatorType !== "device" || !r.originatorToken) return { ...r, deviceType: null };
+      const deviceType = this.alarmDeviceTypes.get(r.originatorToken);
+      return deviceType ? { ...r, deviceType } : r;
+    });
+  }
   // ── Control channel ──────────────────────────────────────────────────────
   // subscribeCommands binds a command widget's scope to a sink and returns a disposer.
   // Poll-only (command-delivery has no subscription): resolve the target device once,
@@ -2336,7 +2578,7 @@ var DashboardHub = class {
   async queryCommands(sub, deviceToken) {
     if (!deviceToken) return { deviceToken: null, commands: [], total: 0 };
     const data = await gql2(COMMAND_AREA, COMMANDS_QUERY, {
-      criteria: { pageNumber: 1, pageSize: sub.pageSize, deviceToken, status: null }
+      criteria: { pageNumber: 1, pageSize: sub.pageSize, deviceToken, status: null, ...windowCriteria(sub.window, Date.now()) }
     });
     return {
       deviceToken,
@@ -2411,6 +2653,70 @@ var DashboardHub = class {
       throw err;
     }
   }
+  // subscribePresence: the roster, then the roster's device-state on an interval. Poll-only (see
+  // PRESENCE_POLL_MS). A refusal (`state:read` is outside some members' grants) becomes `forbidden`,
+  // and every other failure stays an error, as for the location channel. A slow read that lands after
+  // a newer one is dropped, so an old answer never overwrites a fresher one.
+  subscribePresence(datasource, sink) {
+    let disposed = false;
+    let poll;
+    let shown;
+    let generation = 0;
+    const dispose = () => {
+      disposed = true;
+      if (poll) clearInterval(poll);
+      if (shown) document.removeEventListener("visibilitychange", shown);
+      this.presenceDisposers.delete(dispose);
+    };
+    this.presenceDisposers.add(dispose);
+    const reconcile = (tokens) => {
+      const gen = ++generation;
+      this.queryPresence(tokens).then(
+        (states) => {
+          if (!disposed && gen === generation) sink.next(states);
+        },
+        (err) => {
+          if (disposed || gen !== generation) return;
+          if (isForbiddenError(err)) sink.forbidden?.();
+          else sink.error?.(err);
+        }
+      );
+    };
+    this.resolveRoster(datasource).then(
+      ({ roster }) => {
+        if (disposed) return;
+        sink.roster(roster);
+        const tokens = roster.members.map((m) => m.token);
+        if (tokens.length === 0) {
+          sink.next([]);
+          return;
+        }
+        const hidden = () => typeof document !== "undefined" && document.hidden;
+        poll = setInterval(() => {
+          if (!hidden()) reconcile(tokens);
+        }, PRESENCE_POLL_MS);
+        if (typeof document !== "undefined") {
+          shown = () => {
+            if (!hidden()) reconcile(tokens);
+          };
+          document.addEventListener("visibilitychange", shown);
+        }
+        reconcile(tokens);
+      },
+      (err) => {
+        if (disposed) return;
+        if (isForbiddenError(err)) sink.forbidden?.();
+        else sink.error?.(err);
+      }
+    );
+    return dispose;
+  }
+  async queryPresence(tokens) {
+    const chunks = [];
+    for (let i = 0; i < tokens.length; i += PRESENCE_CHUNK) chunks.push(tokens.slice(i, i + PRESENCE_CHUNK));
+    const reads = await Promise.all(chunks.map((deviceTokens) => gql2(STATE_AREA, DEVICE_PRESENCE_QUERY, { deviceTokens })));
+    return reads.flatMap((r) => r.deviceStatesByDeviceToken);
+  }
   // ── WidgetActions (the write seam) ───────────────────────────────────────
   // can reports whether the viewer holds an authority ('*' grants all). Drives whether
   // a widget renders an action control; the server enforces authority regardless.
@@ -2480,6 +2786,8 @@ var DashboardHub = class {
     this.commandDisposers.clear();
     for (const dispose of [...this.locationDisposers]) dispose();
     this.locationDisposers.clear();
+    for (const dispose of [...this.presenceDisposers]) dispose();
+    this.presenceDisposers.clear();
   }
   // The number of distinct upstream device streams currently open (observability
   // + test hook — proves multiplexing collapses shared devices to one stream).
@@ -2663,6 +2971,16 @@ var DashboardHub = class {
 // src/synthetic.ts
 var SYNTHETIC_GENERATORS = ["sine", "ramp", "random-walk"];
 var DEFAULT_NAME = "value";
+var SYNTHETIC_DEVICE_TYPES = {
+  "thermostat-01": { token: "thermostat", name: "Thermostat" },
+  "sensor-14": { token: "sensor", name: "Sensor" },
+  "sensor-03": { token: "sensor", name: "Sensor" },
+  "gateway-02": { token: "gateway", name: "Gateway" }
+};
+function withType(token) {
+  const deviceType = token ? SYNTHETIC_DEVICE_TYPES[token] : void 0;
+  return deviceType ? { deviceType } : {};
+}
 var SYNTHETIC_ALARMS = [
   { severity: "CRITICAL", state: "ACTIVE", acknowledged: false, alarmKey: "over-temperature", metricKey: "temperature", lastValue: 87.4, originatorToken: "thermostat-01" },
   { severity: "MAJOR", state: "ACTIVE", acknowledged: true, alarmKey: "low-battery", metricKey: "battery", lastValue: 12, originatorToken: "sensor-14" },
@@ -2751,8 +3069,9 @@ var SyntheticDataSource = class {
   // a device. Re-emits on the same cadence with advancing raised times so the table
   // looks live. Returns whole snapshots, matching the live hub's contract.
   subscribeAlarms(subscription, sink) {
+    const typed = subscription.enrichDeviceType === true;
     const matches = SYNTHETIC_ALARMS.filter(
-      (a) => (!subscription.state || a.state === subscription.state) && (!subscription.severity || a.severity === subscription.severity) && (subscription.acknowledged == null || a.acknowledged === subscription.acknowledged)
+      (a) => (subscription.deviceType === void 0 || SYNTHETIC_DEVICE_TYPES[a.originatorToken ?? ""]?.token === subscription.deviceType) && (!subscription.state || a.state === subscription.state) && (!subscription.severity || a.severity === subscription.severity) && (subscription.acknowledged == null || a.acknowledged === subscription.acknowledged)
     );
     const emit = () => {
       const now = Date.now();
@@ -2771,10 +3090,32 @@ var SyntheticDataSource = class {
           raisedTime: raised,
           clearedTime: a.state === "CLEARED" ? raised : null,
           acknowledgedTime: a.acknowledged ? raised : null,
-          acknowledgedBy: a.acknowledged ? "preview@devicechain" : null
+          acknowledgedBy: a.acknowledged ? "preview@devicechain" : null,
+          ...typed ? withType(a.originatorToken) : {}
         };
       });
-      sink.next({ alarms: rows.slice(0, subscription.pageSize), total: rows.length });
+      if (subscription.countBySeverity) {
+        const bySeverity = /* @__PURE__ */ new Map();
+        for (const r of rows) bySeverity.set(r.severity, (bySeverity.get(r.severity) ?? 0) + 1);
+        const severityCounts = [...bySeverity].map(([severity, count]) => ({ severity, count }));
+        sink.next({ alarms: [], total: rows.length, severityCounts });
+        return;
+      }
+      if (subscription.countByDeviceType) {
+        const counts = /* @__PURE__ */ new Map();
+        for (const r of rows) {
+          const deviceType = SYNTHETIC_DEVICE_TYPES[r.originatorToken ?? ""];
+          if (!deviceType) continue;
+          const key = `${deviceType.token}/${r.severity}`;
+          const prior = counts.get(key);
+          counts.set(key, { deviceType, severity: r.severity, count: (prior?.count ?? 0) + 1 });
+        }
+        const typeCounts = [...counts.values()];
+        sink.next({ alarms: [], total: typeCounts.reduce((n, c) => n + c.count, 0), typeCounts });
+        return;
+      }
+      const inRange = subscription.window ? rows.filter((r) => alarmOverlaps(r, subscription.window, now)) : rows;
+      sink.next({ alarms: inRange.slice(0, subscription.pageSize), total: inRange.length });
     };
     emit();
     const timer = setInterval(emit, this.intervalMs);
@@ -2809,10 +3150,11 @@ var SyntheticDataSource = class {
           respondedTime: answered ? queued : null
         };
       });
+      const inRange = subscription.window ? commands.filter((c) => commandInRange(c, subscription.window, now)) : commands;
       sink.next({
         deviceToken: SYNTHETIC_COMMAND_DEVICE,
-        commands: commands.slice(0, subscription.pageSize),
-        total: commands.length
+        commands: inRange.slice(0, subscription.pageSize),
+        total: inRange.length
       });
     };
     emit();
@@ -2941,6 +3283,34 @@ var SyntheticDataSource = class {
       if (this.timers.delete(timer)) clearInterval(timer);
     };
   }
+  // A preview fleet's connectivity: three online, one offline (silent for hours) and one that never
+  // reported, with no state row, so every state a presence widget draws is previewed. Last-active
+  // times are offsets from now, so the preview always reads as just-seen for the online ones.
+  subscribePresence(datasource, sink) {
+    const members = datasource.kind === "device" ? [{ token: datasource.deviceToken, name: null }] : this.previewMembers(datasource);
+    sink.roster({ members, total: members.length, unbound: datasource.kind === "unbound" });
+    const emit = () => {
+      const now = Date.now();
+      const states = [];
+      members.forEach((m, i) => {
+        if (m.token === "synthetic-5") return;
+        const offline = m.token === "synthetic-4";
+        states.push({
+          deviceToken: m.token,
+          active: !offline,
+          lastActivityTime: new Date(now - (offline ? 2 * 36e5 : (i + 1) * 2e4)).toISOString(),
+          inactivityTimeout: 600
+        });
+      });
+      sink.next(states);
+    };
+    emit();
+    const timer = setInterval(emit, this.intervalMs);
+    this.timers.add(timer);
+    return () => {
+      if (this.timers.delete(timer)) clearInterval(timer);
+    };
+  }
   // A preview has no history to read: its members report the moment they are subscribed, so the
   // seed settles empty and the live feed alone fills the cells.
   async readMemberSeeds(deviceTokens, _plan, onSeed) {
@@ -3048,7 +3418,7 @@ var HEX64 = /^[0-9a-f]{64}$/;
 var HEX40 = /^[0-9a-f]{40}$/;
 var HEX_SHORT = /^[0-9a-f]{7,40}$/;
 var INSTANT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?Z$/;
-function instant(v, path) {
+function instant2(v, path) {
   const s = str(v, path);
   const m = INSTANT.exec(s);
   if (m) {
@@ -3109,7 +3479,7 @@ function parseBoardRecording(input) {
       "alarms",
       "locations"
     ],
-    ["excerpt"]
+    ["excerpt", "declaredMetrics"]
   );
   if (root.kind !== RECORDING_KIND) {
     throw new RecordingFormatError("$.kind", `expected ${JSON.stringify(RECORDING_KIND)}`);
@@ -3145,6 +3515,22 @@ function parseBoardRecording(input) {
   if (tokens.size !== devices.length || new Set(devices.map((d) => d.id)).size !== devices.length) {
     throw new RecordingFormatError("$.devices", "duplicate device id or token");
   }
+  let declaredMetrics;
+  if (root.declaredMetrics !== void 0) {
+    if (version === 1) throw new RecordingFormatError("$.declaredMetrics", "version 1 carries no declarations");
+    const dm = root.declaredMetrics;
+    if (!isObj(dm)) throw new RecordingFormatError("$.declaredMetrics", "expected an object");
+    const kinds = new Set(devices.map((d) => d.kind));
+    declaredMetrics = {};
+    for (const kind of Object.keys(dm)) {
+      const p = `$.declaredMetrics.${kind}`;
+      if (!kinds.has(kind)) throw new RecordingFormatError(p, `no device in $.devices is of kind '${kind}'`);
+      const names = column(dm[kind], p, str);
+      if (names.length === 0) throw new RecordingFormatError(p, "declares nothing; leave the kind out instead");
+      if (new Set(names).size !== names.length) throw new RecordingFormatError(p, "duplicate measurement name");
+      declaredMetrics[kind] = names;
+    }
+  }
   const ch = strict(root.channels, "$.channels", ["measurements", "alarms", "locations", "commands"]);
   if (version === 1 && ch.locations !== false) {
     throw new RecordingFormatError("$.channels.locations", "version 1 records no positions; must be false");
@@ -3245,7 +3631,7 @@ function parseBoardRecording(input) {
       metric: str(o.metric, `${p}.metric`),
       state: oneOf2(o.state, `${p}.state`, ALARM_STATES),
       sev: oneOf2(o.sev, `${p}.sev`, ALARM_SEVERITIES),
-      occ: instant(o.occ, `${p}.occ`)
+      occ: instant2(o.occ, `${p}.occ`)
     };
     if (o.ack === true) out.ack = true;
     if (typeof o.val === "number") out.val = o.val;
@@ -3330,7 +3716,7 @@ function parseBoardRecording(input) {
     kind: RECORDING_KIND,
     formatVersion: version,
     runId: str(root.runId, "$.runId"),
-    startedAtUtc: instant(root.startedAtUtc, "$.startedAtUtc"),
+    startedAtUtc: instant2(root.startedAtUtc, "$.startedAtUtc"),
     durationMs,
     platformVersion: str(root.platformVersion, "$.platformVersion"),
     instance: str(root.instance, "$.instance"),
@@ -3348,6 +3734,7 @@ function parseBoardRecording(input) {
     locations
   };
   if (excerpt) rec.excerpt = excerpt;
+  if (declaredMetrics) rec.declaredMetrics = declaredMetrics;
   return rec;
 }
 
@@ -3597,6 +3984,7 @@ var RecordedDataSource = class {
     this.shiftMs = shift;
     this.startMs = Date.parse(rec.startedAtUtc);
     this.devices = new Set(rec.devices.map((d) => d.token));
+    this.kinds = new Map(rec.devices.map((d) => [d.token, d.kind]));
     this.unlisten = clock.subscribe((ev) => this.onClock(ev));
   }
   // True once the clock has been seeked since this view was built. A stale view emits
@@ -3629,9 +4017,9 @@ var RecordedDataSource = class {
   }
   // A recorded instant (an alarm's raise or clear time), moved by the shift. Unshifted, the
   // recording's own string is kept, digits and all.
-  shifted(instant2) {
-    if (instant2 === null || this.shiftMs === 0) return instant2;
-    return new Date(Date.parse(instant2) + this.shiftMs).toISOString();
+  shifted(instant3) {
+    if (instant3 === null || this.shiftMs === 0) return instant3;
+    return new Date(Date.parse(instant3) + this.shiftMs).toISOString();
   }
   // open tracks a subscription and returns its disposer. `start` runs once, in a
   // microtask, so the disposer is in the caller's hands before anything is emitted (the
@@ -3758,10 +4146,13 @@ var RecordedDataSource = class {
   // other surface of the board (a gauge's subject line, the machine selector, an alarm's
   // originator) names a device by its token. Labelling the table's rows by external id made one
   // machine "SP-HL-0003" in the table and "sp-hauler-03" in the alarm beside it.
+  //
+  // A member's `deviceType` is its recorded KIND ("Hauler"), the key declaredMetrics answers by:
+  // a recording names no device-type tokens, and nothing but the declarations reads it.
   subscribeMembers(datasource, sink) {
     let members;
     try {
-      members = this.resolve(datasource).map((g) => ({ token: g.deviceToken, name: null }));
+      members = this.resolve(datasource).map((g) => ({ token: g.deviceToken, name: null, deviceType: this.kinds.get(g.deviceToken) }));
     } catch (err) {
       return this.failLater(err, sink);
     }
@@ -3779,6 +4170,14 @@ var RecordedDataSource = class {
       stop?.();
     };
   }
+  // What a kind's profile declares, as the recording carries it (recording.ts, `declaredMetrics`),
+  // or null when it does not say: a recording made before it carried declarations, or a kind it
+  // has no entry for. Null is "unknown", which the fleet widgets read as declared -- never as
+  // absent, so an old recording shows "no data in range" rather than a confident "does not report".
+  async declaredMetrics(kind) {
+    const declared = this.rec.declaredMetrics;
+    return declared && Object.prototype.hasOwnProperty.call(declared, kind) ? declared[kind] : null;
+  }
   // Each device's seed comes from the recording itself, with no read to make: its newest reading per
   // measurement inside the history window, and every measurement it reported in that window, which
   // is how "does not report this" (a dozer's tyres) is told from "sent nothing".
@@ -3809,6 +4208,9 @@ var RecordedDataSource = class {
     let scope = null;
     try {
       if (!this.rec.channels.alarms) throw new NotInRecordingError("alarms");
+      if (subscription.deviceType !== void 0 || subscription.countByDeviceType) {
+        throw new NotInRecordingError("alarms", "device types");
+      }
       if (subscription.datasource) {
         scope = new Set(this.resolve(subscription.datasource).map((g) => g.deviceToken));
       }
@@ -3857,7 +4259,9 @@ var RecordedDataSource = class {
         }
       }
       const matches = [...alarms.values()].filter(
-        (a) => (scope === null || scope.has(a.dev)) && (!subscription.state || a.state === subscription.state) && (!subscription.severity || a.sev === subscription.severity) && (subscription.acknowledged == null || a.ack === subscription.acknowledged)
+        (a) => (scope === null || scope.has(a.dev)) && (!subscription.state || a.state === subscription.state) && (!subscription.severity || a.sev === subscription.severity) && (subscription.acknowledged == null || a.ack === subscription.acknowledged) && // The range is applied before paging, as device-management applies it, so `total`
+        // counts the range. Measured against the view's now(), in the view's (shifted) time.
+        (!subscription.window || alarmOverlaps({ raisedTime: this.shifted(a.raised), clearedTime: this.shifted(a.cleared) }, subscription.window, this.now()))
       );
       const when = (a) => a.raised ?? a.cleared;
       const byTime = (a, b) => {
@@ -3867,6 +4271,16 @@ var RecordedDataSource = class {
         return compareInstants(wb, wa);
       };
       matches.sort((a, b) => byTime(a, b) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+      if (subscription.countBySeverity) {
+        const bySeverity = /* @__PURE__ */ new Map();
+        for (const a of matches) bySeverity.set(a.sev, (bySeverity.get(a.sev) ?? 0) + 1);
+        const severityCounts = [...bySeverity].map(([severity, count]) => ({ severity, count }));
+        const signature2 = JSON.stringify(severityCounts);
+        if (signature2 === lastSignature || isDisposed()) return;
+        lastSignature = signature2;
+        sink.next({ alarms: [], total: matches.length, severityCounts });
+        return;
+      }
       const page = matches.slice(0, subscription.pageSize);
       const signature = JSON.stringify([matches.length, page]);
       if (signature === lastSignature || isDisposed()) return;
@@ -4717,6 +5131,7 @@ function duplicateWidget(def, id) {
 // src/resolver.ts
 import { gql as gql3 } from "@devicechain/client";
 var ANCHOR_PAGE_SIZE = 500;
+var DECLARED_BATCH_SIZE = 100;
 var trueSize = (reported, page) => Math.max(reported ?? page, page);
 function readAnchorPage(anchor) {
   if (anchor.targetType === "customer") {
@@ -4732,7 +5147,8 @@ function readAnchorPage(anchor) {
       return {
         tokens: rows.map((d) => d.token),
         total: trueSize(r.customerDevices.pagination?.totalRecords, rows.length),
-        names: new Map(rows.map((d) => [d.token, d.name]))
+        names: new Map(rows.map((d) => [d.token, d.name])),
+        types: new Map(rows.map((d) => [d.token, d.deviceType?.token ?? null]))
       };
     });
   }
@@ -4754,6 +5170,7 @@ function createDeviceResolver() {
   const anchorCache = /* @__PURE__ */ new Map();
   const memberCache = /* @__PURE__ */ new Map();
   const existsCache = /* @__PURE__ */ new Map();
+  let declaredBatch = null;
   function anchorKey(anchor) {
     return `${anchor.relationship}|${anchor.targetType}|${anchor.targetToken}`;
   }
@@ -4781,16 +5198,20 @@ function createDeviceResolver() {
       const key = anchorKey(anchor);
       let pending = memberCache.get(key);
       if (!pending) {
-        pending = anchorPage(anchor).then(async ({ tokens, total, names: listed }) => {
+        pending = anchorPage(anchor).then(async ({ tokens, total, names: listed, types: listedTypes }) => {
           const names = listed ?? /* @__PURE__ */ new Map();
+          const types = listedTypes ?? /* @__PURE__ */ new Map();
           if (!listed && tokens.length > 0) {
             try {
               const r = await gql3("device-management", DEVICE_NAMES, { tokens });
-              for (const d of r.devicesByToken) names.set(d.token, d.name);
+              for (const d of r.devicesByToken) {
+                names.set(d.token, d.name);
+                types.set(d.token, d.deviceType?.token ?? null);
+              }
             } catch {
             }
           }
-          return { members: tokens.map((token) => ({ token, name: names.get(token) ?? null })), total };
+          return { members: tokens.map((token) => ({ token, name: names.get(token) ?? null, deviceType: types.get(token) ?? null })), total };
         }).catch((err) => {
           memberCache.delete(key);
           throw err;
@@ -4799,6 +5220,43 @@ function createDeviceResolver() {
       }
       return pending;
     },
+    // The names a device type's active profile version declares, or null when it has nothing to
+    // say: no profile, never published, not found, or a published version that declares no metric
+    // at all (an undeclared measurement is still accepted, so an empty declaration rules nothing
+    // out). A failed read rejects: the caller treats that as unknown too, and does not cache it.
+    // Every type asked in the same tick goes in ONE read, so a board of many types costs one
+    // request rather than one per type.
+    declaredMetrics(deviceType) {
+      return new Promise((resolve, reject) => {
+        let batch = declaredBatch;
+        if (!batch) {
+          batch = declaredBatch = /* @__PURE__ */ new Map();
+          queueMicrotask(() => {
+            const asked = declaredBatch;
+            declaredBatch = null;
+            const tokens = [...asked.keys()];
+            for (let i = 0; i < tokens.length; i += DECLARED_BATCH_SIZE) {
+              const chunk = tokens.slice(i, i + DECLARED_BATCH_SIZE);
+              gql3("device-management", DECLARED_METRICS, { tokens: chunk }).then(
+                (r) => {
+                  for (const token of chunk) {
+                    const version = r.deviceTypesByToken.find((t) => t.token === token)?.profile?.activeProfileVersion;
+                    const names = version && version.metrics.length > 0 ? version.metrics.map((m) => m.metricKey) : null;
+                    for (const w of asked.get(token)) w.resolve(names);
+                  }
+                },
+                (err) => {
+                  for (const token of chunk) for (const w of asked.get(token)) w.reject(err);
+                }
+              );
+            }
+          });
+        }
+        const waiting = batch.get(deviceType) ?? [];
+        waiting.push({ resolve, reject });
+        batch.set(deviceType, waiting);
+      });
+    },
     // deviceExists caches only a POSITIVE result (a live device is stable for the
     // session); a negative and an error both drop the entry so a later check re-queries.
     // ADR-042 frees a token on delete, so a deleted-then-recreated device must be able to
@@ -4869,7 +5327,7 @@ async function fetchWidgetHistory(widget, window2, options = {}) {
 }
 
 // src/option-schema.ts
-var HOST_OPTION_CONTROLS = ["command-vocabulary", "slot-target", "basemap"];
+var HOST_OPTION_CONTROLS = ["command-vocabulary", "slot-target", "basemap", "device-type"];
 function hasOwn(obj, key) {
   return Object.prototype.hasOwnProperty.call(obj, key);
 }
@@ -5083,8 +5541,8 @@ var CHANNELS = ["measurement", "alarm", "control", "selection", "location", "agg
 var SEMVER2 = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 var SELECTOR_KINDS = ["device", "anchor", "slot"];
 var BINDING_KEYS = {
-  measurement: ["window", "windowSeconds", "members"],
-  alarm: ["pageSize", "state", "severity", "acknowledged"],
+  measurement: ["window", "windowSeconds", "members", "presence"],
+  alarm: ["pageSize", "state", "severity", "acknowledged", "groupBy", "countBySeverity", "deviceType"],
   control: ["pageSize"],
   location: [],
   aggregate: ["windowSeconds"],
@@ -5138,7 +5596,7 @@ function collectDescriptorIssues(d, id) {
   }
   const channel = CHANNELS.find((c) => c === d.channel);
   if (!channel) add("channel", `channel must be one of ${CHANNELS.join(", ")}, got ${JSON.stringify(d.channel)}`);
-  const specs = checkOptions(d.options, add);
+  const specs = checkOptions(d.options, !isBuiltinWidgetId(d.id), add);
   const constraints = checkConstraints(d.constraints, specs, add);
   if (specs) checkDefaults(d.defaults, specs, constraints, typeof d.id === "string" ? d.id : id, add);
   else if (!isRecord(d.defaults)) add("defaults", "defaults must be an object");
@@ -5187,14 +5645,14 @@ function jsonOnly(value, path, add, ancestors) {
   }
   ancestors.delete(obj);
 }
-function checkOptions(options, add) {
+function checkOptions(options, requireDoc, add) {
   if (!isRecord(options)) {
     add("options", "options must be an object mapping option keys to specs");
     return void 0;
   }
-  return checkOptionsAt(options, "options.", add) ? options : void 0;
+  return checkOptionsAt(options, "options.", requireDoc, add) ? options : void 0;
 }
-function checkOptionsAt(options, prefix, add) {
+function checkOptionsAt(options, prefix, requireDoc, add) {
   let sound = true;
   for (const [key, spec] of Object.entries(options)) {
     const at = `${prefix}${key}`;
@@ -5203,7 +5661,7 @@ function checkOptionsAt(options, prefix, add) {
       sound = false;
       continue;
     }
-    if (typeof spec.doc !== "string") {
+    if (typeof spec.doc !== "string" && (requireDoc || spec.doc !== void 0)) {
       add(`${at}.doc`, "doc must be a string");
     }
     for (const text of ["label", "help", "labelId", "helpId", "placeholder", "placeholderId"]) {
@@ -5245,6 +5703,9 @@ function checkOptionsAt(options, prefix, add) {
         if (spec.maxItems !== void 0 && (typeof spec.maxItems !== "number" || !Number.isInteger(spec.maxItems) || spec.maxItems < 1)) {
           add(`${at}.maxItems`, "maxItems must be a whole number of at least 1");
         }
+        if (spec.ordered !== void 0 && typeof spec.ordered !== "boolean") {
+          add(`${at}.ordered`, "ordered must be true or false");
+        }
         if (!isRecord(spec.item) || Object.keys(spec.item).length === 0) {
           add(`${at}.item`, "a list option needs an item object declaring at least one field");
           sound = false;
@@ -5259,7 +5720,7 @@ function checkOptionsAt(options, prefix, add) {
           sound = false;
           break;
         }
-        if (!checkOptionsAt(flat, `${at}.item.`, add)) sound = false;
+        if (!checkOptionsAt(flat, `${at}.item.`, requireDoc, add)) sound = false;
         break;
       }
       default:
@@ -5394,23 +5855,37 @@ function checkBinding(binding, channel, specs, add) {
   ref("pageSize", isNumber, "a number option", true);
   ref("state", isText, "a string or enum option", false);
   ref("severity", isText, "a string or enum option", false);
+  ref("deviceType", isText, "a string or enum option", false);
   ref("acknowledged", isBoolEnum, 'an enum option whose values are only "true" and "false"', false);
-  const members = binding.members;
-  if (members !== void 0) {
-    const m = isRecord(members) ? members : {};
+  const modeBinding = (key) => {
+    const mode = binding[key];
+    if (mode === void 0) return;
+    const m = isRecord(mode) ? mode : {};
+    const at = `binding.${key}`;
+    const allowConst = key === "members";
     const isConst = m.const !== void 0;
-    if (isConst ? m.option !== void 0 || m.equals !== void 0 : typeof m.option !== "string" || typeof m.equals !== "string") {
-      add("binding.members", "members must be { const: true } or { option, equals } naming a declared option and a value of it");
+    if (isConst ? !allowConst || m.option !== void 0 || m.equals !== void 0 : typeof m.option !== "string" || typeof m.equals !== "string") {
+      add(at, `${key} must be ${allowConst ? "{ const: true } or " : ""}{ option, equals } naming a declared option and a value of it`);
     } else if (isConst) {
-      if (m.const !== true) add("binding.members.const", `const must be true, got ${JSON.stringify(m.const)}`);
+      if (m.const !== true) add(`${at}.const`, `const must be true, got ${JSON.stringify(m.const)}`);
     } else if (specs) {
       const spec = hasOwn(specs, m.option) ? specs[m.option] : void 0;
-      if (!spec) add("binding.members.option", `option ${JSON.stringify(m.option)} is not a declared option key`);
-      else if (!isText(spec)) add("binding.members.option", `option ${JSON.stringify(m.option)} must be a string or enum option`);
+      if (!spec) add(`${at}.option`, `option ${JSON.stringify(m.option)} is not a declared option key`);
+      else if (!isText(spec)) add(`${at}.option`, `option ${JSON.stringify(m.option)} must be a string or enum option`);
       else if (spec.kind === "enum" && !spec.values.includes(m.equals)) {
-        add("binding.members.equals", `${JSON.stringify(m.equals)} is not one of the option's values`);
+        add(`${at}.equals`, `${JSON.stringify(m.equals)} is not one of the option's values`);
       }
     }
+  };
+  const presence = binding.presence;
+  if (presence !== void 0 && !(isRecord(presence) && presence.const === true && Object.keys(presence).length === 1)) {
+    add("binding.presence", "must be { const: true }");
+  }
+  modeBinding("members");
+  modeBinding("groupBy");
+  const counts = binding.countBySeverity;
+  if (counts !== void 0 && !(isRecord(counts) && counts.const === true && Object.keys(counts).length === 1)) {
+    add("binding.countBySeverity", "must be { const: true }");
   }
 }
 function readSpan(value, path, add) {
@@ -5588,6 +6063,7 @@ function effectiveLayout(def, containerWidth, options = {}) {
 export {
   ANCHOR_PAGE_SIZE,
   BASE_BREAKPOINT,
+  BIND_PARAM_PREFIX,
   CANVAS_DENSITIES,
   COMMAND_STATUSES,
   CURRENT_SCHEMA_VERSION,
@@ -5645,8 +6121,10 @@ export {
   applyOptionPatch,
   applySelection,
   basePlacement,
+  bindParamsOf,
   bindWidgetSlot,
   bindingsWithoutScopedSlots,
+  bindsToSelection,
   blockingLayoutFindings,
   breakpointColumns,
   breakpointMinWidth,
@@ -5679,6 +6157,7 @@ export {
   effectiveBindings,
   effectiveLayout,
   enumValues,
+  eventWindowBounds,
   fetchWidgetHistory,
   firstFreeSlot,
   fitToLimits,
@@ -5711,6 +6190,7 @@ export {
   moveWidget,
   numberSpec,
   paddingPx,
+  parseBindParams,
   parseBindingManifest,
   parseBoardRecording,
   parseDashboardDefinition,
@@ -5750,6 +6230,7 @@ export {
   sameLabel,
   sealHistory,
   seedBucketCount,
+  selectionToBinds,
   serializeDefinition,
   serializeWidgetClipboard,
   setBoardTimeRange,
@@ -5772,11 +6253,13 @@ export {
   undoEdit,
   unresolvedWidgets,
   updateWidget,
+  validateBinds,
   validateOptions,
   validateWidgetDescriptor,
   widgetBinding,
   widgetSlotName,
   widgetVersionNotice,
+  withBindParams,
   withSpan,
   withoutConversionMark
 };