@devicechain/dashboards 0.19.0-rc.1 → 0.20.0-rc.4

package/dist/index.js

@@ -61,6 +61,85 @@ var WIDGET_TYPES = [
   "entity-selector",
   "map"
 ];
+var UNKNOWN_WIDGET_TYPE = "unknown-widget";
+
+// src/widget-compat.ts
+var BUILTIN_TYPES = new Set(WIDGET_TYPES);
+function isBuiltinWidget(widget) {
+  return BUILTIN_TYPES.has(widget.type);
+}
+function isResolvedWidget(widget) {
+  return widget.type !== UNKNOWN_WIDGET_TYPE;
+}
+var SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function parseWidgetRef(raw) {
+  if (raw === void 0) return void 0;
+  if (!isRecord(raw)) return null;
+  const { version, optionsVersion, sdkApiVersion } = raw;
+  if (typeof version !== "string" || !SEMVER.test(version)) return null;
+  if (typeof optionsVersion !== "number" || !Number.isInteger(optionsVersion) || optionsVersion < 1) return null;
+  const ref = { version, optionsVersion };
+  if (sdkApiVersion !== void 0) {
+    if (typeof sdkApiVersion !== "number" || !Number.isInteger(sdkApiVersion) || sdkApiVersion < 1) return null;
+    ref.sdkApiVersion = sdkApiVersion;
+  }
+  return ref;
+}
+function checkWidgetCompatibility(id, ref, descriptor) {
+  if (ref.optionsVersion !== descriptor.optionsVersion) {
+    return {
+      code: "options-version",
+      message: `"${id}" was saved with settings version ${ref.optionsVersion}; the installed widget uses settings version ${descriptor.optionsVersion}`
+    };
+  }
+  if (ref.sdkApiVersion !== void 0 && ref.sdkApiVersion !== descriptor.sdkApiVersion) {
+    return {
+      code: "sdk-incompatible",
+      message: `"${id}" was authored for widget SDK API ${ref.sdkApiVersion}; the installed widget uses API ${descriptor.sdkApiVersion}`
+    };
+  }
+  return void 0;
+}
+function widgetVersionNotice(id, ref, descriptor) {
+  if (!ref || ref.version === descriptor.version) return void 0;
+  return `"${id}" was authored with version ${ref.version}; rendering with version ${descriptor.version}`;
+}
+function unresolvedReason(type, rawRef, catalog, builtin) {
+  const ref = parseWidgetRef(rawRef);
+  if (ref === null) {
+    return { code: "invalid-metadata", message: `"${type}" carries widget version metadata that is not valid` };
+  }
+  if (!catalog) {
+    return builtin ? void 0 : { code: "unregistered", message: `"${type}" is not available: no widget catalog was supplied` };
+  }
+  const descriptor = catalog.get(type);
+  if (!descriptor) {
+    return {
+      code: "unregistered",
+      message: builtin ? `"${type}" is not registered in this host` : `"${type}" is not installed in this host; add its package to the host's widget registry`
+    };
+  }
+  if (ref === void 0) {
+    return builtin ? void 0 : { code: "unversioned", message: `"${type}" is stored without version metadata, so the installed widget cannot be matched to it` };
+  }
+  return checkWidgetCompatibility(type, ref, descriptor);
+}
+function unresolvedWidgets(definition) {
+  const out = [];
+  for (const w of definition.widgets) {
+    if (w.type !== UNKNOWN_WIDGET_TYPE) continue;
+    const storedType = typeof w.raw.type === "string" ? w.raw.type : "";
+    out.push({
+      widgetId: w.id,
+      type: storedType,
+      reason: w.reason ?? { code: "unregistered", message: `"${storedType}" is not available in this host` }
+    });
+  }
+  return out;
+}
 
 // src/definition.ts
 var BASE_BREAKPOINT = "base";
@@ -73,33 +152,33 @@ var DashboardDefinitionError = class extends Error {
     this.name = "DashboardDefinitionError";
   }
 };
-function isRecord(v) {
+function isRecord2(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 function numberAt(rec, key, fallback) {
   const v = rec[key];
   return typeof v === "number" && Number.isFinite(v) ? v : fallback;
 }
-function parseDashboardDefinition(raw) {
-  if (!isRecord(raw)) throw new DashboardDefinitionError("not a JSON object");
+function parseDashboardDefinition(raw, options = {}) {
+  if (!isRecord2(raw)) throw new DashboardDefinitionError("not a JSON object");
   const widgetsRaw = raw.widgets;
   if (!Array.isArray(widgetsRaw)) throw new DashboardDefinitionError("widgets must be an array");
   const def = {
     schemaVersion: numberAt(raw, "schemaVersion", 1),
     title: typeof raw.title === "string" ? raw.title : "",
     canvas: parseCanvas(raw.canvas),
-    widgets: widgetsRaw.map((w, i) => parseWidget(w, i))
+    widgets: widgetsRaw.map((w, i) => parseWidget(w, i, options.catalog))
   };
   const slots = parseSlots(raw.slots);
   if (slots) def.slots = slots;
   return def;
 }
 function parseSlots(raw) {
-  if (!isRecord(raw)) return void 0;
+  if (!isRecord2(raw)) return void 0;
   const slots = {};
   for (const [name, spec] of Object.entries(raw)) {
     if (name === "__proto__") continue;
-    if (!isRecord(spec)) continue;
+    if (!isRecord2(spec)) continue;
     const type = spec.type === "anchor" ? "anchor" : "device";
     const slot = { type };
     if (typeof spec.label === "string") slot.label = spec.label;
@@ -114,7 +193,7 @@ function parseSlots(raw) {
   return slots;
 }
 function parseScope(raw) {
-  if (!isRecord(raw)) return void 0;
+  if (!isRecord2(raw)) return void 0;
   const parent = typeof raw.parent === "string" ? raw.parent : "";
   if (!parent) return void 0;
   return { parent, strategy: raw.strategy === "manual" ? "manual" : "first" };
@@ -158,13 +237,13 @@ function canScopeSlot(slots, child, parentName) {
   return true;
 }
 function parseSlotBinding(raw) {
-  if (!isRecord(raw)) return void 0;
+  if (!isRecord2(raw)) return void 0;
   if (raw.kind === "device") {
     const token = stringAt(raw, "deviceToken");
     return token ? { kind: "device", deviceToken: token } : void 0;
   }
   if (raw.kind === "anchor") {
-    const anchorRec = isRecord(raw.anchor) ? raw.anchor : {};
+    const anchorRec = isRecord2(raw.anchor) ? raw.anchor : {};
     const targetToken = stringAt(anchorRec, "targetToken");
     if (!targetToken) return void 0;
     return {
@@ -179,13 +258,13 @@ function parseSlotBinding(raw) {
   return void 0;
 }
 function parseGrid(raw) {
-  const rec = isRecord(raw) ? raw : {};
+  const rec = isRecord2(raw) ? raw : {};
   const columns = Math.max(1, Math.round(numberAt(rec, "columns", DEFAULT_GRID.columns)));
   const rowHeight = Math.max(1, numberAt(rec, "rowHeight", DEFAULT_GRID.rowHeight));
   let gap = DEFAULT_GRID.gap;
   if (typeof rec.gap === "number" && Number.isFinite(rec.gap)) {
     gap = Math.max(0, rec.gap);
-  } else if (isRecord(rec.gap)) {
+  } else if (isRecord2(rec.gap)) {
     gap = {
       row: Math.max(0, numberAt(rec.gap, "row", DEFAULT_GRID.gap)),
       col: Math.max(0, numberAt(rec.gap, "col", DEFAULT_GRID.gap))
@@ -194,7 +273,7 @@ function parseGrid(raw) {
   return { columns, gap, rowHeight };
 }
 function parseSizing(raw) {
-  if (isRecord(raw)) {
+  if (isRecord2(raw)) {
     if (typeof raw.width === "number" && Number.isFinite(raw.width)) {
       return { width: Math.max(1, raw.width) };
     }
@@ -205,17 +284,17 @@ function parseSizing(raw) {
   return DEFAULT_SIZING;
 }
 function parseCanvas(raw) {
-  const rec = isRecord(raw) ? raw : {};
+  const rec = isRecord2(raw) ? raw : {};
   const grid = parseGrid(rec.grid);
   const sizing = parseSizing(rec.sizing);
-  const bpRec = isRecord(rec.breakpoints) ? rec.breakpoints : {};
+  const bpRec = isRecord2(rec.breakpoints) ? rec.breakpoints : {};
   const breakpoints = {};
   for (const [name, width] of Object.entries(bpRec)) {
     if (typeof width === "number" && Number.isFinite(width)) breakpoints[name] = width;
   }
   if (!(BASE_BREAKPOINT in breakpoints)) breakpoints[BASE_BREAKPOINT] = 0;
   const canvas = { grid, sizing, breakpoints };
-  if (isRecord(rec.background)) {
+  if (isRecord2(rec.background)) {
     const { color, imageUrl } = rec.background;
     canvas.background = {
       color: typeof color === "string" ? color : null,
@@ -224,22 +303,81 @@ function parseCanvas(raw) {
   }
   return canvas;
 }
-function parseWidget(raw, index) {
-  if (!isRecord(raw)) throw new DashboardDefinitionError(`widgets[${index}] is not an object`);
+function parseWidget(raw, index, catalog) {
+  if (!isRecord2(raw)) throw new DashboardDefinitionError(`widgets[${index}] is not an object`);
   const type = raw.type;
-  if (typeof type !== "string" || !WIDGET_TYPE_SET.has(type)) {
+  if (typeof type !== "string" || type.length === 0) {
     throw new DashboardDefinitionError(`widgets[${index}] has unknown type ${JSON.stringify(type)}`);
   }
-  const widget = {
-    id: typeof raw.id === "string" && raw.id.length > 0 ? raw.id : generateWidgetId(),
+  if (type === UNKNOWN_WIDGET_TYPE && isRecord2(raw.raw)) return reparseUnknownWidget(raw, index, catalog);
+  const builtin = WIDGET_TYPE_SET.has(type);
+  const reason = unresolvedReason(type, raw.widget, catalog, builtin) ?? (builtin ? void 0 : reservedFieldReason(type, raw));
+  if (reason) return parseUnknownWidget(raw, index, reason);
+  const ref = parseWidgetRef(raw.widget) ?? void 0;
+  const widget = builtin ? {
+    id: storedWidgetId(raw) ?? generateWidgetId(),
     type,
+    ...ref ? { widget: ref } : {},
+    layout: parseLayout(raw.layout, index)
+  } : {
+    id: storedWidgetId(raw) ?? generateWidgetId(),
+    type,
+    widget: ref,
+    // unresolvedReason guarantees a valid ref here
     layout: parseLayout(raw.layout, index)
   };
-  const ds = parseDatasource(raw.datasource);
+  const ds = parseDatasource(raw.datasource, index);
   if (ds) widget.datasource = ds;
-  if (isRecord(raw.options)) widget.options = raw.options;
+  if (isRecord2(raw.options)) widget.options = raw.options;
+  if (!builtin) return withStoredFields(raw, widget);
   return widget;
 }
+var OWNED_WIDGET_KEYS = /* @__PURE__ */ new Set(["id", "type", "widget", "layout", "datasource", "options"]);
+function withStoredFields(raw, parsed) {
+  const owned = parsed;
+  const out = {};
+  const put = (key, value) => Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true });
+  for (const key of Object.keys(raw)) {
+    if (!OWNED_WIDGET_KEYS.has(key)) put(key, JSON.parse(JSON.stringify(raw[key])));
+    else if (key === "widget") put(key, { ...raw.widget, ...parsed.widget });
+    else if (owned[key] !== void 0) put(key, owned[key]);
+  }
+  for (const key of OWNED_WIDGET_KEYS) {
+    if (!Object.prototype.hasOwnProperty.call(out, key) && owned[key] !== void 0) put(key, owned[key]);
+  }
+  return out;
+}
+function reservedFieldReason(type, raw) {
+  const clash = ["raw", "reason"].find((k) => Object.prototype.hasOwnProperty.call(raw, k));
+  return clash === void 0 ? void 0 : { code: "invalid-metadata", message: `"${type}" carries a top-level "${clash}" field, which the dashboard format reserves` };
+}
+function storedWidgetId(raw) {
+  return typeof raw.id === "string" && raw.id.length > 0 ? raw.id : void 0;
+}
+function parseUnknownWidget(raw, index, reason) {
+  return {
+    id: storedWidgetId(raw) ?? generateWidgetId(),
+    type: UNKNOWN_WIDGET_TYPE,
+    layout: parseLayout(raw.layout, index),
+    raw: JSON.parse(JSON.stringify(raw)),
+    reason
+  };
+}
+function reparseUnknownWidget(raw, index, catalog) {
+  const stored = JSON.parse(JSON.stringify(raw.raw));
+  const storedType = typeof stored.type === "string" ? stored.type : "";
+  const reason = unresolvedReason(storedType, stored.widget, catalog, WIDGET_TYPE_SET.has(storedType)) ?? {
+    code: "unregistered",
+    message: `"${storedType}" is not available in this host`
+  };
+  return {
+    id: storedWidgetId(raw) ?? generateWidgetId(),
+    type: UNKNOWN_WIDGET_TYPE,
+    layout: parseLayout(raw.layout, index),
+    raw: stored,
+    reason
+  };
+}
 function stringAt(rec, key) {
   const v = rec[key];
   return typeof v === "string" ? v : "";
@@ -249,17 +387,22 @@ function stringArrayAt(rec, key) {
   return Array.isArray(v) ? v.filter((m) => typeof m === "string") : [];
 }
 function parseLocationSelection(raw) {
-  if (!isRecord(raw)) return void 0;
+  if (!isRecord2(raw)) return void 0;
   return raw.series === "latest" ? { series: "latest" } : void 0;
 }
 function withLocation(selector, raw) {
   const location = parseLocationSelection(raw.location);
   return location ? { ...selector, location } : selector;
 }
-function parseDatasource(raw) {
-  if (!isRecord(raw)) return void 0;
+function parseDatasource(raw, index) {
+  if (!isRecord2(raw)) return void 0;
   const kind = raw.kind;
   if (typeof kind !== "string" || kind.length === 0) return void 0;
+  if (kind === "unbound") {
+    throw new DashboardDefinitionError(
+      `widgets[${index}].datasource has kind 'unbound', which is never stored; bind the widget through a slot`
+    );
+  }
   if (kind === "device") {
     return withLocation(
       { kind: "device", deviceToken: stringAt(raw, "deviceToken"), measurements: stringArrayAt(raw, "measurements") },
@@ -267,7 +410,7 @@ function parseDatasource(raw) {
     );
   }
   if (kind === "anchor") {
-    const anchorRec = isRecord(raw.anchor) ? raw.anchor : {};
+    const anchorRec = isRecord2(raw.anchor) ? raw.anchor : {};
     const selector = withLocation(
       {
         kind: "anchor",
@@ -282,7 +425,7 @@ function parseDatasource(raw) {
       },
       raw
     );
-    if (isRecord(raw.aggregation)) {
+    if (isRecord2(raw.aggregation)) {
       selector.aggregation = raw.aggregation;
     }
     return selector;
@@ -296,10 +439,10 @@ function parseDatasource(raw) {
   return raw;
 }
 function parseLayout(raw, index) {
-  if (!isRecord(raw)) throw new DashboardDefinitionError(`widgets[${index}].layout is missing`);
+  if (!isRecord2(raw)) throw new DashboardDefinitionError(`widgets[${index}].layout is missing`);
   const layout = {};
   for (const [bp, box] of Object.entries(raw)) {
-    if (isRecord(box)) layout[bp] = parseBox(box);
+    if (isRecord2(box)) layout[bp] = parseBox(box);
   }
   if (!(BASE_BREAKPOINT in layout)) {
     throw new DashboardDefinitionError(`widgets[${index}].layout has no '${BASE_BREAKPOINT}' box`);
@@ -316,13 +459,64 @@ function parseBox(rec) {
     // so keep it an integer like every other box field.
     z: Math.round(numberAt(rec, "z", 0))
   };
-  if (isRecord(rec.offset)) {
+  if (isRecord2(rec.offset)) {
     box.offset = { x: numberAt(rec.offset, "x", 0), y: numberAt(rec.offset, "y", 0) };
   }
   return box;
 }
+function storedDefinition(def) {
+  if (!def.widgets.some((w) => w.type === UNKNOWN_WIDGET_TYPE)) return def;
+  return {
+    ...def,
+    widgets: def.widgets.map((w) => w.type === UNKNOWN_WIDGET_TYPE ? storedUnknownWidget(w) : w)
+  };
+}
+function storedUnknownWidget(w) {
+  let out = w.raw;
+  const rawId = storedWidgetId(w.raw);
+  if (rawId !== void 0 && rawId !== w.id) out = { ...out, id: w.id };
+  const layout = storedUnknownLayout(w.layout, w.raw.layout);
+  if (layout !== w.raw.layout) out = { ...out, layout };
+  return out;
+}
+function storedUnknownLayout(layout, rawLayout) {
+  const stored = isRecord2(rawLayout) ? rawLayout : {};
+  const out = {};
+  let changed = !isRecord2(rawLayout);
+  for (const [bp, box] of Object.entries(stored)) {
+    if (!isRecord2(box)) {
+      out[bp] = box;
+      continue;
+    }
+    const current = Object.prototype.hasOwnProperty.call(layout, bp) ? layout[bp] : void 0;
+    if (!current) {
+      changed = true;
+      continue;
+    }
+    if (sameBox(parseBox(box), current)) {
+      out[bp] = box;
+    } else {
+      out[bp] = movedBox(box, current);
+      changed = true;
+    }
+  }
+  for (const [bp, box] of Object.entries(layout)) {
+    if (Object.prototype.hasOwnProperty.call(stored, bp) && isRecord2(stored[bp])) continue;
+    out[bp] = box;
+    changed = true;
+  }
+  return changed ? out : rawLayout;
+}
+function movedBox(stored, current) {
+  const out = { ...stored, ...current };
+  if (current.offset === void 0) delete out.offset;
+  return out;
+}
+function sameBox(a, b) {
+  return a.col === b.col && a.colSpan === b.colSpan && a.row === b.row && a.rowSpan === b.rowSpan && a.z === b.z && a.offset?.x === b.offset?.x && a.offset?.y === b.offset?.y;
+}
 function serializeDefinition(def) {
-  return JSON.stringify(def);
+  return JSON.stringify(storedDefinition(def));
 }
 function isDirty(a, b) {
   return serializeDefinition(a) !== serializeDefinition(b);
@@ -386,6 +580,14 @@ function stripDefaultBindings(def) {
   }
   return { ...def, slots };
 }
+function resolveWidgetDatasource(datasource, bindings) {
+  if (!datasource || datasource.kind !== "slot") return datasource;
+  const binding = bindings && Object.prototype.hasOwnProperty.call(bindings, datasource.slot) ? bindings[datasource.slot] : void 0;
+  const series = datasource.location ? { measurements: datasource.measurements, location: datasource.location } : { measurements: datasource.measurements };
+  if (binding?.kind === "device") return { kind: "device", deviceToken: binding.deviceToken, ...series };
+  if (binding?.kind === "anchor") return { kind: "anchor", anchor: binding.anchor, ...series };
+  return { kind: "unbound", ...series };
+}
 
 // src/context.ts
 function ownGet(map, key) {
@@ -527,7 +729,11 @@ function bindWidgetSlot(def, widgetId, binding, measurements, location) {
   const currentDef = currentSlot ? slots[currentSlot] : void 0;
   const slot = currentSlot && currentDef && (currentDef.scope || sameBinding(currentDef.defaultBinding, binding)) ? currentSlot : findOrAddSlot(slots, binding);
   const widgets = def.widgets.map(
-    (w) => w.id === widgetId ? { ...w, datasource: slotSelector(slot, measurements, location) } : w
+    (w) => (
+      // A placeholder for an unknown widget type binds nothing this build can see, so it is
+      // never given a datasource here: its bindings live in its raw object.
+      w.id === widgetId && w.type !== UNKNOWN_WIDGET_TYPE ? { ...w, datasource: slotSelector(slot, measurements, location) } : w
+    )
   );
   return { ...def, widgets, slots };
 }
@@ -539,6 +745,18 @@ function clearWidgetDatasource(def, widgetId) {
   });
   return { ...def, widgets };
 }
+var RAW_SLOT_SCAN_DEPTH = 32;
+function collectRawSlotReferences(value, used, depth) {
+  if (depth > RAW_SLOT_SCAN_DEPTH || typeof value !== "object" || value === null) return;
+  if (Array.isArray(value)) {
+    for (const item of value) collectRawSlotReferences(item, used, depth + 1);
+    return;
+  }
+  const rec = value;
+  if (rec.kind === "slot" && typeof rec.slot === "string" && rec.slot.length > 0) used.add(rec.slot);
+  if (typeof rec.selectionTarget === "string" && rec.selectionTarget.length > 0) used.add(rec.selectionTarget);
+  for (const child of Object.values(rec)) collectRawSlotReferences(child, used, depth + 1);
+}
 function pruneSlots(def) {
   if (!def.slots) return def;
   const defSlots = def.slots;
@@ -547,6 +765,7 @@ function pruneSlots(def) {
     if (w.datasource?.kind === "slot") used.add(w.datasource.slot);
     const target = w.options?.selectionTarget;
     if (typeof target === "string" && target.length > 0) used.add(target);
+    if (w.raw) collectRawSlotReferences(w.raw, used, 0);
   }
   for (const start of [...used]) {
     let cur = start;
@@ -594,10 +813,15 @@ function widgetSlotName(widget) {
 }
 function resolveConcrete(def, widget) {
   const binding = widgetBinding(def, widget);
-  if (!binding) return void 0;
   const measurements = widget.datasource?.measurements ?? [];
   const location = widget.datasource?.location;
   const base = location ? { measurements, location } : { measurements };
+  if (!binding) {
+    const ds = widget.datasource;
+    if (ds?.kind === "device") return { kind: "device", deviceToken: ds.deviceToken, ...base };
+    if (ds?.kind === "anchor") return { kind: "anchor", anchor: ds.anchor, ...base };
+    return void 0;
+  }
   return binding.kind === "device" ? { kind: "device", deviceToken: binding.deviceToken, ...base } : { kind: "anchor", anchor: binding.anchor, ...base };
 }
 
@@ -938,15 +1162,8 @@ var DashboardHub = class {
     // device stream), so disposeAll() can tear down every map widget's poll.
     this.locationDisposers = /* @__PURE__ */ new Set();
     this.resolver = config.resolver;
-    this.bindings = config.bindings ?? {};
     this.authorities = new Set(config.authorities ?? []);
   }
-  // setBindings replaces the slot manifest. New subscriptions resolve through it;
-  // callers that need already-open slot streams to re-resolve should re-subscribe
-  // (the console keys the renderer on the manifest to do exactly that).
-  setBindings(bindings) {
-    this.bindings = bindings;
-  }
   // subscribeWidget binds a widget's datasource to a sink and returns a disposer.
   // Selector resolution is async (anchor→devices); the disposer is returned
   // synchronously and cancels a still-pending resolution, so tearing a widget down
@@ -1028,7 +1245,10 @@ var DashboardHub = class {
   }
   // resolveAlarmScope turns an alarm widget's scope selector into the originator device
   // tokens to filter on, or tenant-wide when it carries no datasource. Reuses the same
-  // device/anchor/slot resolution the measurement channel does.
+  // device/anchor/unbound resolution the measurement channel does.
+  //
+  // 🔴 Only an ABSENT datasource is tenant-wide. `{kind:'unbound'}` is a datasource, and
+  // it resolves to zero devices like any other empty scope.
   async resolveAlarmScope(datasource) {
     if (!datasource) return { tenantWide: true, tokens: [] };
     const groups = await this.resolveDevices(datasource);
@@ -1276,9 +1496,10 @@ var DashboardHub = class {
     return this.streams.size;
   }
   // isDatasourceAvailable reports whether a widget's bound device still exists. Only a
-  // device selector (or a slot bound to a device) is validated — an anchor, an unbound
-  // slot, or no datasource has a legitimate empty state and is always "available". Fails
-  // open: an existence-check outage returns true (never falsely mark a live device gone).
+  // device selector is validated (a slot bound to a device arrives as one) — an anchor, an
+  // unbound slot, or no datasource has a legitimate empty state and is always "available".
+  // Fails open: an existence-check outage returns true (never falsely mark a live device
+  // gone).
   async isDatasourceAvailable(datasource) {
     const deviceToken = this.availabilityToken(datasource);
     if (deviceToken === void 0) return true;
@@ -1291,14 +1512,10 @@ var DashboardHub = class {
   // availabilityToken returns the single device token whose existence gates a widget's
   // availability, or undefined when there is nothing device-specific to validate (an
   // anchor's membership is self-validating; an unbound slot is a placeholder; a reserved
-  // kind isn't resolved yet).
+  // kind isn't resolved yet; an unresolved slot fails on its data channel instead).
   availabilityToken(datasource) {
     if (!datasource) return void 0;
     if (datasource.kind === "device") return datasource.deviceToken || void 0;
-    if (datasource.kind === "slot") {
-      const binding = Object.prototype.hasOwnProperty.call(this.bindings, datasource.slot) ? this.bindings[datasource.slot] : void 0;
-      return binding && binding.kind === "device" ? binding.deviceToken || void 0 : void 0;
-    }
     return void 0;
   }
   // resolveDevices turns a selector into the devices to stream, each with the
@@ -1316,11 +1533,12 @@ var DashboardHub = class {
           { kind: "anchor", anchor: datasource.anchor },
           new Set(datasource.measurements)
         );
-      case "slot": {
-        const binding = Object.prototype.hasOwnProperty.call(this.bindings, datasource.slot) ? this.bindings[datasource.slot] : void 0;
-        if (!binding) return [];
-        return this.resolveBinding(binding, new Set(datasource.measurements));
-      }
+      case "unbound":
+        return [];
+      case "slot":
+        throw new Error(
+          `dashboard slot '${datasource.slot}' reached the data source unresolved; resolve it through the bindings first (resolveWidgetDatasource)`
+        );
       default:
         throw new Error(
           `dashboard selector kind '${datasource.kind}' is not supported yet`
@@ -1640,6 +1858,853 @@ var SyntheticDataSource = class {
   }
 };
 
+// src/recording.ts
+var RECORDING_FORMAT_VERSION = 1;
+var RECORDING_KIND = "sitepulse-board-recording";
+var ALARM_STATES = ["ACTIVE", "CLEARED"];
+var ALARM_SEVERITIES = ["CRITICAL", "MAJOR", "MINOR", "WARNING"];
+var RecordingFormatError = class extends Error {
+  constructor(path, reason) {
+    super(`invalid recording at ${path}: ${reason}`);
+    this.path = path;
+    this.name = "RecordingFormatError";
+  }
+};
+function recordingBounds(rec) {
+  return rec.excerpt ? { ...rec.excerpt } : { fromMs: 0, toMs: rec.durationMs };
+}
+function recordedWallTimeMs(rec, tMs) {
+  return Date.parse(rec.startedAtUtc) + tMs;
+}
+function simulationScaleAt(rec, tMs) {
+  let hit = null;
+  for (const seg of rec.clock) {
+    if (seg.fromMs <= tMs) hit = seg;
+  }
+  return hit ? { mode: hit.mode, scale: hit.scale } : null;
+}
+function isObj(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function strict(v, path, required, optional = []) {
+  if (!isObj(v)) throw new RecordingFormatError(path, "expected an object");
+  const allowed = /* @__PURE__ */ new Set([...required, ...optional]);
+  for (const key of Object.keys(v)) {
+    if (!allowed.has(key)) throw new RecordingFormatError(`${path}.${key}`, "unknown key");
+  }
+  for (const key of required) {
+    if (!Object.prototype.hasOwnProperty.call(v, key)) {
+      throw new RecordingFormatError(`${path}.${key}`, "missing required key");
+    }
+  }
+  return v;
+}
+function str(v, path) {
+  if (typeof v !== "string" || v === "") throw new RecordingFormatError(path, "expected a non-empty string");
+  return v;
+}
+function bool(v, path) {
+  if (typeof v !== "boolean") throw new RecordingFormatError(path, "expected a boolean");
+  return v;
+}
+function num(v, path) {
+  if (typeof v !== "number" || !Number.isFinite(v)) throw new RecordingFormatError(path, "expected a finite number");
+  return v;
+}
+function arr(v, path) {
+  if (!Array.isArray(v)) throw new RecordingFormatError(path, "expected an array");
+  return v;
+}
+function oneOf(v, path, allowed) {
+  if (typeof v !== "string" || !allowed.includes(v)) {
+    throw new RecordingFormatError(path, `expected one of ${allowed.join(", ")}`);
+  }
+  return v;
+}
+function matching(v, path, re, what) {
+  if (typeof v !== "string" || !re.test(v)) throw new RecordingFormatError(path, `expected ${what}`);
+  return v;
+}
+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) {
+  const s = str(v, path);
+  const m = INSTANT.exec(s);
+  if (m) {
+    const [y, mo, d, h, mi, sec] = m.slice(1, 7).map(Number);
+    const t = new Date(Date.UTC(y, mo - 1, d, h, mi, sec));
+    if (t.getUTCFullYear() === y && t.getUTCMonth() === mo - 1 && t.getUTCDate() === d && t.getUTCHours() === h && t.getUTCMinutes() === mi && t.getUTCSeconds() === sec) {
+      return s;
+    }
+  }
+  throw new RecordingFormatError(path, "expected an RFC 3339 UTC instant ending in Z that exists on the calendar");
+}
+function compareInstants(a, b) {
+  const pa = INSTANT.exec(a);
+  const pb = INSTANT.exec(b);
+  if (!pa || !pb) throw new RangeError(`compareInstants: not an instant: ${pa ? b : a}`);
+  const whole = (m) => Date.parse(`${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}Z`);
+  const wa = whole(pa);
+  const wb = whole(pb);
+  if (wa !== wb) return wa < wb ? -1 : 1;
+  const fa = (pa[7] ?? "").padEnd(12, "0");
+  const fb = (pb[7] ?? "").padEnd(12, "0");
+  return fa < fb ? -1 : fa > fb ? 1 : 0;
+}
+function column(v, path, item, length) {
+  const a = arr(v, path);
+  if (length !== void 0 && a.length !== length) {
+    throw new RecordingFormatError(path, `length ${a.length} does not match the time column (${length})`);
+  }
+  return a.map((x, i) => item(x, `${path}[${i}]`));
+}
+function nonNegative(v, path) {
+  const n = num(v, path);
+  if (n < 0) throw new RecordingFormatError(path, "must not be negative");
+  return n;
+}
+function parseBoardRecording(input) {
+  const root = strict(
+    input,
+    "$",
+    [
+      "kind",
+      "formatVersion",
+      "runId",
+      "startedAtUtc",
+      "durationMs",
+      "platformVersion",
+      "instance",
+      "tenant",
+      "build",
+      "clock",
+      "devices",
+      "channels",
+      "board",
+      "sourceHashes",
+      "converter",
+      "chapters",
+      "measurements",
+      "alarms",
+      "locations"
+    ],
+    ["excerpt"]
+  );
+  if (root.kind !== RECORDING_KIND) {
+    throw new RecordingFormatError("$.kind", `expected ${JSON.stringify(RECORDING_KIND)}`);
+  }
+  if (root.formatVersion !== RECORDING_FORMAT_VERSION) {
+    throw new RecordingFormatError(
+      "$.formatVersion",
+      `unsupported version ${JSON.stringify(root.formatVersion)}; this reader understands ${RECORDING_FORMAT_VERSION}`
+    );
+  }
+  const durationMs = num(root.durationMs, "$.durationMs");
+  if (durationMs <= 0) throw new RecordingFormatError("$.durationMs", "must be positive");
+  const b = strict(root.build, "$.build", ["gitSha", "sdkCommit"]);
+  const build = {
+    gitSha: matching(b.gitSha, "$.build.gitSha", HEX_SHORT, "a lowercase hex commit id"),
+    sdkCommit: matching(b.sdkCommit, "$.build.sdkCommit", HEX_SHORT, "a lowercase hex commit id")
+  };
+  const clock = column(root.clock, "$.clock", (x, p) => {
+    const o = strict(x, p, ["fromMs", "mode", "scale"]);
+    const scale = num(o.scale, `${p}.scale`);
+    if (scale <= 0) throw new RecordingFormatError(`${p}.scale`, "must be positive");
+    return { fromMs: nonNegative(o.fromMs, `${p}.fromMs`), mode: str(o.mode, `${p}.mode`), scale };
+  });
+  clock.forEach((seg, i) => {
+    if (i > 0 && seg.fromMs <= clock[i - 1].fromMs) throw new RecordingFormatError(`$.clock[${i}].fromMs`, "must increase");
+  });
+  const devices = column(root.devices, "$.devices", (x, p) => {
+    const o = strict(x, p, ["id", "token", "kind"]);
+    return { id: str(o.id, `${p}.id`), token: str(o.token, `${p}.token`), kind: str(o.kind, `${p}.kind`) };
+  });
+  const tokens = new Set(devices.map((d) => d.token));
+  if (tokens.size !== devices.length || new Set(devices.map((d) => d.id)).size !== devices.length) {
+    throw new RecordingFormatError("$.devices", "duplicate device id or token");
+  }
+  const ch = strict(root.channels, "$.channels", ["measurements", "alarms", "locations", "commands"]);
+  if (ch.locations !== false) {
+    throw new RecordingFormatError("$.channels.locations", "this version records no positions; must be false");
+  }
+  if (ch.commands !== false) {
+    throw new RecordingFormatError("$.channels.commands", "this version records no command data; must be false");
+  }
+  const channels = {
+    measurements: column(ch.measurements, "$.channels.measurements", str),
+    alarms: bool(ch.alarms, "$.channels.alarms"),
+    locations: false,
+    commands: false
+  };
+  if (new Set(channels.measurements).size !== channels.measurements.length) {
+    throw new RecordingFormatError("$.channels.measurements", "duplicate measurement name");
+  }
+  const bd = strict(root.board, "$.board", ["path", "sourceCommit", "sha256"]);
+  const board = {
+    path: str(bd.path, "$.board.path"),
+    sourceCommit: matching(bd.sourceCommit, "$.board.sourceCommit", HEX40, "a full lowercase hex commit id"),
+    sha256: matching(bd.sha256, "$.board.sha256", HEX64, "a lowercase hex SHA-256")
+  };
+  const sh = root.sourceHashes;
+  if (!isObj(sh)) throw new RecordingFormatError("$.sourceHashes", "expected an object");
+  const sourceHashes = {};
+  for (const key of Object.keys(sh)) {
+    if (key === "__proto__") throw new RecordingFormatError(`$.sourceHashes.${key}`, "reserved key");
+    sourceHashes[key] = matching(sh[key], `$.sourceHashes.${key}`, HEX64, "a lowercase hex SHA-256");
+  }
+  const cv = strict(root.converter, "$.converter", ["version"]);
+  const converter = { version: num(cv.version, "$.converter.version") };
+  let excerpt;
+  if (root.excerpt !== void 0) {
+    const e = strict(root.excerpt, "$.excerpt", ["fromMs", "toMs"]);
+    excerpt = { fromMs: nonNegative(e.fromMs, "$.excerpt.fromMs"), toMs: nonNegative(e.toMs, "$.excerpt.toMs") };
+    if (excerpt.fromMs >= excerpt.toMs || excerpt.toMs > durationMs) {
+      throw new RecordingFormatError("$.excerpt", "must be a non-empty window inside the run");
+    }
+  }
+  const lo = excerpt ? excerpt.fromMs : 0;
+  const hi = excerpt ? excerpt.toMs : durationMs;
+  const chapters = column(root.chapters, "$.chapters", (x, p) => {
+    const o = strict(x, p, ["tMs", "name", "note"]);
+    const tMs = num(o.tMs, `${p}.tMs`);
+    if (tMs < 0 || tMs > durationMs) throw new RecordingFormatError(`${p}.tMs`, "is outside the run");
+    if (excerpt && (tMs < lo || tMs > hi)) throw new RecordingFormatError(`${p}.tMs`, "is outside the excerpt window");
+    return { tMs, name: str(o.name, `${p}.name`), note: str(o.note, `${p}.note`) };
+  });
+  chapters.forEach((c, i) => {
+    if (i > 0 && c.tMs < chapters[i - 1].tMs) throw new RecordingFormatError(`$.chapters[${i}].tMs`, "chapters must not decrease in time");
+  });
+  const m = strict(root.measurements, "$.measurements", ["d", "n", "t", "v", "s"]);
+  const t = column(m.t, "$.measurements.t", num);
+  let prev = lo;
+  t.forEach((x, i) => {
+    if (x < lo || x > hi) throw new RecordingFormatError(`$.measurements.t[${i}]`, `${x} is outside [${lo}, ${hi}]`);
+    if (x < prev) throw new RecordingFormatError(`$.measurements.t[${i}]`, "time column must not decrease");
+    prev = x;
+  });
+  const index = (name, limit) => (x, p) => {
+    const n = num(x, p);
+    if (!Number.isInteger(n) || n < 0 || n >= limit) throw new RecordingFormatError(p, `${name} index out of range`);
+    return n;
+  };
+  const measurements = {
+    d: column(m.d, "$.measurements.d", index("device", devices.length), t.length),
+    n: column(m.n, "$.measurements.n", index("measurement", channels.measurements.length), t.length),
+    t,
+    v: column(m.v, "$.measurements.v", num, t.length),
+    s: column(
+      m.s,
+      "$.measurements.s",
+      (x, p) => {
+        if (x !== 0 && x !== 1) throw new RecordingFormatError(p, "expected 0 or 1");
+        return x;
+      },
+      t.length
+    )
+  };
+  const al = strict(root.alarms, "$.alarms", ["snapshots", "events"]);
+  const alarm = (o, p) => {
+    const id = matching(o.id, `${p}.id`, /^alarm-\d+$/, "a re-minted id (alarm-N)");
+    const dev = str(o.dev, `${p}.dev`);
+    if (!tokens.has(dev)) throw new RecordingFormatError(`${p}.dev`, `device '${dev}' is not in $.devices`);
+    if (o.ack !== void 0 && o.ack !== true) throw new RecordingFormatError(`${p}.ack`, "present only when true");
+    const out = {
+      id,
+      dev,
+      key: str(o.key, `${p}.key`),
+      metric: str(o.metric, `${p}.metric`),
+      state: oneOf(o.state, `${p}.state`, ALARM_STATES),
+      sev: oneOf(o.sev, `${p}.sev`, ALARM_SEVERITIES),
+      occ: instant(o.occ, `${p}.occ`)
+    };
+    if (o.ack === true) out.ack = true;
+    return out;
+  };
+  const ALARM_KEYS = ["id", "dev", "key", "metric", "state", "sev", "occ"];
+  const checkTime = (tMs, p) => {
+    if (tMs < 0 || tMs > hi) throw new RecordingFormatError(p, `${tMs} is outside [0, ${hi}]`);
+    return tMs;
+  };
+  const snapshots = column(al.snapshots, "$.alarms.snapshots", (x, p) => {
+    const o = strict(x, p, ["tMs", "requestedAtMs", "total", "alarms"]);
+    const alarms = column(o.alarms, `${p}.alarms`, (a, ap) => alarm(strict(a, ap, ALARM_KEYS, ["ack"]), ap));
+    const ids = /* @__PURE__ */ new Set();
+    alarms.forEach((a, i) => {
+      if (ids.has(a.id)) throw new RecordingFormatError(`${p}.alarms[${i}].id`, `duplicate alarm ${a.id} in one snapshot`);
+      ids.add(a.id);
+    });
+    const total = nonNegative(o.total, `${p}.total`);
+    if (total !== alarms.length) {
+      throw new RecordingFormatError(`${p}.total`, `is ${total} but ${alarms.length} alarms are listed (truncated snapshot)`);
+    }
+    const tMs = checkTime(num(o.tMs, `${p}.tMs`), `${p}.tMs`);
+    const requestedAtMs = nonNegative(o.requestedAtMs, `${p}.requestedAtMs`);
+    if (!Number.isInteger(requestedAtMs)) throw new RecordingFormatError(`${p}.requestedAtMs`, "expected an integer");
+    if (requestedAtMs > tMs) throw new RecordingFormatError(`${p}.requestedAtMs`, "a query cannot be sent after its answer");
+    return { tMs, requestedAtMs, total, alarms };
+  });
+  const events = column(al.events, "$.alarms.events", (x, p) => {
+    const o = strict(x, p, [...ALARM_KEYS, "tMs"], ["ack"]);
+    return { ...alarm(o, p), tMs: checkTime(num(o.tMs, `${p}.tMs`), `${p}.tMs`) };
+  });
+  for (const [name, list] of [["snapshots", snapshots], ["events", events]]) {
+    list.forEach((e, i) => {
+      if (i > 0 && e.tMs < list[i - 1].tMs) throw new RecordingFormatError(`$.alarms.${name}[${i}].tMs`, "must not decrease");
+    });
+  }
+  const deviceOf = /* @__PURE__ */ new Map();
+  const everyAlarm = [
+    ...snapshots.flatMap((s, i) => s.alarms.map((a, j) => [`$.alarms.snapshots[${i}].alarms[${j}]`, a])),
+    ...events.map((e, i) => [`$.alarms.events[${i}]`, e])
+  ];
+  for (const [path, a] of everyAlarm) {
+    const seen = deviceOf.get(a.id);
+    if (seen !== void 0 && seen !== a.dev) {
+      throw new RecordingFormatError(`${path}.dev`, `alarm ${a.id} was on '${seen}' and cannot move to '${a.dev}'`);
+    }
+    deviceOf.set(a.id, a.dev);
+  }
+  if (!channels.alarms && (snapshots.length > 0 || events.length > 0)) {
+    throw new RecordingFormatError("$.alarms", "history present but $.channels.alarms is false");
+  }
+  if (!Array.isArray(root.locations) || root.locations.length !== 0) {
+    throw new RecordingFormatError("$.locations", "this version carries no positions; must be an empty array");
+  }
+  const rec = {
+    kind: RECORDING_KIND,
+    formatVersion: RECORDING_FORMAT_VERSION,
+    runId: str(root.runId, "$.runId"),
+    startedAtUtc: instant(root.startedAtUtc, "$.startedAtUtc"),
+    durationMs,
+    platformVersion: str(root.platformVersion, "$.platformVersion"),
+    instance: str(root.instance, "$.instance"),
+    tenant: str(root.tenant, "$.tenant"),
+    build,
+    clock,
+    devices,
+    channels,
+    board,
+    sourceHashes,
+    converter,
+    chapters,
+    measurements,
+    alarms: { snapshots, events },
+    locations: []
+  };
+  if (excerpt) rec.excerpt = excerpt;
+  return rec;
+}
+
+// src/recorded.ts
+var RECORDED_HISTORY_WINDOW_MS = 60 * 60 * 1e3;
+var NotInRecordingError = class extends Error {
+  constructor(channel, detail = "") {
+    super(`Not in this recording${detail ? `: ${detail}` : ""}`);
+    this.name = "NotInRecordingError";
+    this.channel = channel;
+    this.detail = detail;
+  }
+  // The widget error frame prints String(error). The default would read
+  // "NotInRecordingError: Not in this recording", which says the name twice; the message
+  // alone is what a viewer should see.
+  toString() {
+    return this.message;
+  }
+};
+var PLAYBACK_RATES = [1, 4, 16];
+function defaultTicker() {
+  return {
+    start(onFrame) {
+      const now = () => typeof performance !== "undefined" ? performance.now() : Date.now();
+      let last = now();
+      const step = () => {
+        const t = now();
+        const dt = t - last;
+        last = t;
+        onFrame(dt);
+      };
+      if (typeof requestAnimationFrame === "function") {
+        let handle = 0;
+        let stopped = false;
+        const loop = () => {
+          if (stopped) return;
+          step();
+          handle = requestAnimationFrame(loop);
+        };
+        handle = requestAnimationFrame(loop);
+        return () => {
+          stopped = true;
+          if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(handle);
+        };
+      }
+      const timer = setInterval(step, 100);
+      return () => clearInterval(timer);
+    }
+  };
+}
+var RecordedClock = class {
+  constructor(durationMs, options = {}) {
+    this.isPlaying = false;
+    this.playbackRate = 1;
+    this.stopTicker = null;
+    this.listeners = /* @__PURE__ */ new Set();
+    if (!Number.isFinite(durationMs) || durationMs <= 0) {
+      throw new RangeError(`RecordedClock: durationMs must be positive and finite, got ${durationMs}`);
+    }
+    this.durationMs = durationMs;
+    this.minMs = options.minMs ?? 0;
+    if (!Number.isFinite(this.minMs) || this.minMs < 0 || this.minMs >= durationMs) {
+      throw new RangeError(`RecordedClock: minMs must be in [0, ${durationMs}), got ${this.minMs}`);
+    }
+    this.ticker = options.ticker ?? defaultTicker();
+    this.time = this.clampTime(options.startMs ?? this.minMs);
+  }
+  get timeMs() {
+    return this.time;
+  }
+  get playing() {
+    return this.isPlaying;
+  }
+  get rate() {
+    return this.playbackRate;
+  }
+  get ended() {
+    return this.time >= this.durationMs;
+  }
+  // play starts the cursor moving. At the end of the run it does nothing: playback stops
+  // there (no loop seam) and a host that wants to start over seeks to 0 first.
+  play() {
+    if (this.isPlaying || this.ended) return;
+    this.isPlaying = true;
+    this.stopTicker = this.ticker.start((dt) => this.advance(dt));
+    this.emit("state");
+  }
+  pause() {
+    if (!this.isPlaying) return;
+    this.halt();
+    this.emit("state");
+  }
+  // seek moves the cursor, clamped to [minMs, durationMs]. Playback state is unchanged, except
+  // that seeking to the very end stops it (there is nothing left to play).
+  seek(tMs) {
+    if (!Number.isFinite(tMs)) throw new RangeError(`RecordedClock.seek: not a finite time: ${tMs}`);
+    this.time = this.clampTime(tMs);
+    if (this.isPlaying && this.ended) this.halt();
+    this.emit("seek");
+  }
+  setRate(rate) {
+    if (!PLAYBACK_RATES.includes(rate)) {
+      throw new RangeError(`RecordedClock.setRate: ${rate} is not one of ${PLAYBACK_RATES.join(", ")}`);
+    }
+    this.playbackRate = rate;
+    this.emit("state");
+  }
+  // advance moves the cursor by wallDeltaMs of real time (scaled by the playback rate).
+  // The ticker calls this each frame; a test calls it directly. It does nothing while
+  // paused, and stops at the end of the run.
+  advance(wallDeltaMs) {
+    if (!this.isPlaying) return;
+    if (!Number.isFinite(wallDeltaMs) || wallDeltaMs < 0) {
+      throw new RangeError(`RecordedClock.advance: expected a non-negative finite delta, got ${wallDeltaMs}`);
+    }
+    this.time = this.clampTime(this.time + wallDeltaMs * this.playbackRate);
+    if (this.ended) this.halt();
+    this.emit("tick");
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  halt() {
+    this.isPlaying = false;
+    this.stopTicker?.();
+    this.stopTicker = null;
+  }
+  clampTime(t) {
+    return t < this.minMs ? this.minMs : t > this.durationMs ? this.durationMs : t;
+  }
+  emit(reason) {
+    for (const listener of [...this.listeners]) listener({ timeMs: this.time, reason });
+  }
+};
+function lowerBound(a, x) {
+  let lo = 0;
+  let hi = a.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (a[mid] < x) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+function upperBound(a, x) {
+  let lo = 0;
+  let hi = a.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (a[mid] <= x) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+function createRecordedClock(rec, options = {}) {
+  const { fromMs, toMs } = recordingBounds(rec);
+  return new RecordedClock(toMs, { minMs: fromMs, ticker: options.ticker });
+}
+function sameAnchor(a, b) {
+  return a.relationship === b.relationship && a.targetType === b.targetType && a.targetToken === b.targetToken;
+}
+function declaredSite(options) {
+  const anchors = options.siteAnchors;
+  if (anchors === void 0) return null;
+  if (anchors.length !== 1) {
+    throw new Error(`RecordedSiteOptions.siteAnchors must declare exactly one anchor, got ${anchors.length}`);
+  }
+  if (anchors[0].targetType !== "customer") {
+    throw new Error(
+      `RecordedSiteOptions.siteAnchors must be a customer anchor, got '${anchors[0].targetType}': a recording cannot say that every device belongs to an area or an asset`
+    );
+  }
+  return anchors[0];
+}
+function anchorMembers(rec, site, anchor) {
+  if (!site || !sameAnchor(site, anchor)) {
+    throw new Error(
+      `anchor ${anchor.targetType} '${anchor.targetToken}' (${anchor.relationship}) is not in this recording`
+    );
+  }
+  return rec.devices.map((d) => d.token);
+}
+function createRecordedResolver(rec, options = {}) {
+  const devices = new Set(rec.devices.map((d) => d.token));
+  const site = declaredSite(options);
+  return {
+    devicesForAnchor: async (anchor) => anchorMembers(rec, site, anchor),
+    deviceExists: async (token) => devices.has(token)
+  };
+}
+function createRecordedLister(rec, options = {}) {
+  const site = declaredSite(options);
+  return async (kind) => {
+    if (kind === "device") return rec.devices.map((d) => ({ token: d.token, name: null }));
+    return site && site.targetType === kind ? [{ token: site.targetToken, name: null }] : [];
+  };
+}
+var indexCache = /* @__PURE__ */ new WeakMap();
+function indexOf(rec) {
+  const cached = indexCache.get(rec);
+  if (cached) return cached;
+  const bySeries = /* @__PURE__ */ new Map();
+  const byDevice = /* @__PURE__ */ new Map();
+  const { d, n, t } = rec.measurements;
+  for (let i = 0; i < t.length; i++) {
+    const key = d[i] * rec.channels.measurements.length + n[i];
+    let s = bySeries.get(String(key));
+    if (!s) {
+      s = { device: rec.devices[d[i]].token, name: rec.channels.measurements[n[i]], rows: [], times: [] };
+      bySeries.set(String(key), s);
+      const list = byDevice.get(s.device);
+      if (list) list.push(s);
+      else byDevice.set(s.device, [s]);
+    }
+    s.rows.push(i);
+    s.times.push(t[i]);
+  }
+  const timeline = [
+    ...rec.alarms.snapshots.map((snapshot) => ({ tMs: snapshot.tMs, snapshot })),
+    ...rec.alarms.events.map((event) => ({ tMs: event.tMs, event }))
+  ];
+  timeline.sort((a, b) => a.tMs - b.tMs);
+  const indexed = { byDevice, timeline, timelineTimes: timeline.map((e) => e.tMs) };
+  indexCache.set(rec, indexed);
+  return indexed;
+}
+var RecordedDataSource = class {
+  // `clock` is the shared replay clock; the view starts at its current time. `options`
+  // names the site anchors this recording's devices belong to (see RecordedSiteOptions).
+  constructor(rec, clock, options = {}) {
+    this.subs = /* @__PURE__ */ new Set();
+    this.stale = false;
+    this.rec = rec;
+    this.site = declaredSite(options);
+    this.index = indexOf(rec);
+    this.cursor = clock.timeMs;
+    this.startMs = Date.parse(rec.startedAtUtc);
+    this.devices = new Set(rec.devices.map((d) => d.token));
+    this.unlisten = clock.subscribe((ev) => this.onClock(ev));
+  }
+  // True once the clock has been seeked since this view was built. A stale view emits
+  // nothing further; the host builds a new view at the new cursor.
+  get isStale() {
+    return this.stale;
+  }
+  onClock(ev) {
+    if (this.stale) return;
+    if (ev.reason === "seek") {
+      this.stale = true;
+      this.unlisten();
+      return;
+    }
+    if (ev.reason !== "tick") return;
+    this.cursor = ev.timeMs;
+    for (const sub of [...this.subs]) sub.advance(this.cursor);
+  }
+  iso(offsetMs) {
+    return new Date(this.startMs + offsetMs).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
+  // contract every source keeps: a synchronous disposer, and nothing emitted after it).
+  // `advance` runs on each forward tick after that.
+  open(handlers) {
+    let disposed = false;
+    let started = false;
+    const isDisposed = () => disposed;
+    const sub = {
+      advance: (cursor) => {
+        if (started && !disposed) handlers.advance(cursor, isDisposed);
+      },
+      dispose: () => {
+        disposed = true;
+        this.subs.delete(sub);
+      }
+    };
+    this.subs.add(sub);
+    queueMicrotask(() => {
+      if (disposed || this.stale) return;
+      started = true;
+      handlers.start(this.cursor, isDisposed);
+    });
+    return sub.dispose;
+  }
+  // Resolve a selector to the devices it names, synchronously and from the recording.
+  // Mirrors the hub: unbound is zero devices, an unresolved slot is a loud error.
+  resolve(ds) {
+    switch (ds.kind) {
+      case "device":
+        return [{ deviceToken: ds.deviceToken, names: new Set(ds.measurements) }];
+      case "anchor":
+        return anchorMembers(this.rec, this.site, ds.anchor).map((deviceToken) => ({
+          deviceToken,
+          names: new Set(ds.measurements)
+        }));
+      case "unbound":
+        return [];
+      case "slot":
+        throw new Error(
+          `dashboard slot '${ds.slot}' reached the data source unresolved; resolve it through the bindings first (resolveWidgetDatasource)`
+        );
+      default:
+        throw new Error(`dashboard selector kind '${ds.kind}' is not supported yet`);
+    }
+  }
+  // Report a failure on a sink, asynchronously and only if the subscription is still live.
+  failLater(err, sink) {
+    let disposed = false;
+    queueMicrotask(() => {
+      if (!disposed) sink.error?.(err);
+    });
+    return () => {
+      disposed = true;
+    };
+  }
+  // ── measurements ──────────────────────────────────────────────────────────
+  subscribeWidget(datasource, sink) {
+    let groups;
+    try {
+      groups = this.resolve(datasource);
+      for (const g of groups) {
+        for (const name of g.names) {
+          if (!this.rec.channels.measurements.includes(name)) {
+            throw new NotInRecordingError("measurements", `no '${name}' series was recorded`);
+          }
+        }
+      }
+    } catch (err) {
+      return this.failLater(err, sink);
+    }
+    const picked = [];
+    for (const g of groups) {
+      for (const s of this.index.byDevice.get(g.deviceToken) ?? []) {
+        if (g.names.size === 0 || g.names.has(s.name)) picked.push({ s, next: 0 });
+      }
+    }
+    const { t, v } = this.rec.measurements;
+    const flush = (cursor, isDisposed) => {
+      const due = [];
+      for (const p of picked) {
+        const { s } = p;
+        while (p.next < s.times.length && s.times[p.next] <= cursor) {
+          const row = s.rows[p.next++];
+          due.push({
+            t: t[row],
+            sample: {
+              id: `${s.device}|${s.name}|${row}`,
+              deviceToken: s.device,
+              eventType: 0,
+              // The time the viewer applied the row: the recording holds no separate
+              // occurred time for measurements.
+              occurredTime: this.iso(t[row]),
+              name: s.name,
+              value: v[row],
+              classifier: null
+            }
+          });
+        }
+      }
+      due.sort((a, b) => a.t - b.t);
+      for (const d of due) {
+        if (isDisposed()) return;
+        sink.next(d.sample);
+      }
+    };
+    return this.open({
+      // Back-fill: rows from the preceding window up to the cursor, then play on.
+      start: (cursor, isDisposed) => {
+        for (const p of picked) p.next = lowerBound(p.s.times, cursor - RECORDED_HISTORY_WINDOW_MS);
+        flush(cursor, isDisposed);
+      },
+      advance: flush
+    });
+  }
+  // ── alarms ────────────────────────────────────────────────────────────────
+  subscribeAlarms(subscription, sink) {
+    let scope = null;
+    try {
+      if (!this.rec.channels.alarms) throw new NotInRecordingError("alarms");
+      if (subscription.datasource) {
+        scope = new Set(this.resolve(subscription.datasource).map((g) => g.deviceToken));
+      }
+    } catch (err) {
+      return this.failLater(err, sink);
+    }
+    const { timeline, timelineTimes } = this.index;
+    const alarms = /* @__PURE__ */ new Map();
+    let applied = 0;
+    let lastSignature = null;
+    const apply = (a, asOfMs) => {
+      const prior = alarms.get(a.id);
+      alarms.set(a.id, {
+        id: a.id,
+        dev: a.dev,
+        key: a.key,
+        metric: a.metric,
+        state: a.state,
+        sev: a.sev,
+        // `occ` is the time of THIS state: the raise time for an ACTIVE row, the clear time
+        // for a CLEARED one. A cleared alarm keeps the raise time its ACTIVE row gave it
+        // (null if the history never showed it being raised).
+        raised: a.state === "ACTIVE" ? a.occ : prior?.raised ?? null,
+        cleared: a.state === "CLEARED" ? a.occ : null,
+        // Each record's own `ack` decides; acknowledgement is not carried over from an
+        // earlier record of the same alarm.
+        ack: a.ack === true,
+        asOfMs
+      });
+    };
+    const emit = (cursor, isDisposed) => {
+      const upTo = upperBound(timelineTimes, cursor);
+      for (; applied < upTo; applied++) {
+        const entry = timeline[applied];
+        if ("snapshot" in entry) {
+          const { requestedAtMs } = entry.snapshot;
+          const newer = [...alarms.values()].filter((a) => a.asOfMs > requestedAtMs);
+          alarms.clear();
+          for (const a of entry.snapshot.alarms) apply(a, requestedAtMs);
+          for (const a of newer) alarms.set(a.id, a);
+        } else {
+          apply(entry.event, entry.event.tMs);
+        }
+      }
+      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)
+      );
+      const when = (a) => a.raised ?? a.cleared;
+      const byTime = (a, b) => {
+        const wa = when(a);
+        const wb = when(b);
+        if (wa === null || wb === null) return wa === wb ? 0 : wa === null ? 1 : -1;
+        return compareInstants(wb, wa);
+      };
+      matches.sort((a, b) => byTime(a, b) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+      const page = matches.slice(0, subscription.pageSize);
+      const signature = JSON.stringify([matches.length, page]);
+      if (signature === lastSignature || isDisposed()) return;
+      lastSignature = signature;
+      const snapshot = { alarms: page.map(toAlarmRow), total: matches.length };
+      sink.next(snapshot);
+    };
+    return this.open({ start: emit, advance: emit });
+  }
+  // ── commands ──────────────────────────────────────────────────────────────
+  // The recording holds no command data, so this channel is never available.
+  subscribeCommands(_subscription, sink) {
+    return this.failLater(new NotInRecordingError("commands"), sink);
+  }
+  // ── locations ─────────────────────────────────────────────────────────────
+  // This format version records no positions. A selector that names no location series
+  // asks for nothing, and one that resolves to no device has nothing to place: both get the
+  // empty snapshot, as from the hub. Naming a location series for devices that exist is a
+  // request for data the recording does not have, which is an error, never an empty map.
+  subscribeLocations(subscription, sink) {
+    const ds = subscription.datasource;
+    let tokens = [];
+    if (ds?.location) {
+      try {
+        tokens = this.resolve(ds).map((g) => g.deviceToken);
+      } catch (err) {
+        return this.failLater(err, sink);
+      }
+      if (tokens.length > 0) {
+        return this.failLater(new NotInRecordingError("locations", "no positions were recorded"), sink);
+      }
+    }
+    return this.open({
+      start: (_cursor, isDisposed) => {
+        if (!isDisposed()) sink.next({ kind: "positions", deviceTokens: [], locations: [] });
+      },
+      advance: () => {
+      }
+    });
+  }
+  // ── availability ──────────────────────────────────────────────────────────
+  // A device selector is available iff the run has that device. Anchors, unbound slots and
+  // no datasource have a legitimate empty state and are available, as on the hub.
+  async isDatasourceAvailable(datasource) {
+    if (datasource?.kind === "device" && datasource.deviceToken) return this.devices.has(datasource.deviceToken);
+    return true;
+  }
+  // Stop every subscription and leave the clock. Call when the view is replaced.
+  disposeAll() {
+    this.unlisten();
+    for (const sub of [...this.subs]) sub.dispose();
+  }
+};
+function toAlarmRow(a) {
+  return {
+    token: a.id,
+    originatorType: "device",
+    originatorToken: a.dev,
+    alarmKey: a.key,
+    metricKey: a.metric,
+    state: a.state,
+    acknowledged: a.ack,
+    severity: a.sev,
+    raisedTime: a.raised,
+    clearedTime: a.cleared,
+    // The recording notes THAT an alarm was acknowledged, not when or by whom.
+    acknowledgedTime: null,
+    acknowledgedBy: null,
+    // The stored alarm's last value is not recorded, and a nearby measurement would
+    // invent the integrator's state. Null renders as an em dash.
+    lastValue: null
+  };
+}
+
 // src/editor-model.ts
 function baseBox(widget) {
   return widget.layout[BASE_BREAKPOINT];
@@ -1687,27 +2752,21 @@ function setCanvasSizing(def, sizing) {
 function updateWidget(def, id, next) {
   return { ...def, widgets: def.widgets.map((w) => w.id === id ? next : w) };
 }
-function humanizeType(type) {
-  const words = type.replace(/-/g, " ");
-  return words.charAt(0).toUpperCase() + words.slice(1);
-}
-function defaultOptions(type) {
-  if (type === "label") return { text: "New label" };
-  if (type === "alarm-table" || type === "alarm-count") {
-    return { title: humanizeType(type), state: "ACTIVE" };
-  }
-  return { title: humanizeType(type) };
-}
-function addWidget(def, type) {
+function addWidget(def, descriptor) {
   const maxZ = def.widgets.reduce((m, w) => Math.max(m, baseBox(w).z), 0);
   const id = generateWidgetId();
   const box = { col: 0, colSpan: 8, row: 0, rowSpan: 4, z: maxZ + 1 };
-  const widget = {
+  const common = {
     id,
-    type,
+    widget: {
+      version: descriptor.version,
+      optionsVersion: descriptor.optionsVersion,
+      sdkApiVersion: descriptor.sdkApiVersion
+    },
     layout: { [BASE_BREAKPOINT]: box },
-    options: defaultOptions(type)
+    options: { ...descriptor.defaults }
   };
+  const widget = { ...common, type: descriptor.id };
   return { definition: { ...def, widgets: [...def.widgets, widget] }, id };
 }
 function gridBoxToPx(box, geom) {
@@ -1810,8 +2869,8 @@ function defaultHistoryWindow() {
     intervalSeconds: 60
   };
 }
-async function fetchWidgetHistory(widget, window, bindings) {
-  const ds = resolveHistorySelector(widget.datasource, bindings);
+async function fetchWidgetHistory(widget, window) {
+  const ds = widget.datasource;
   if (!ds || ds.kind !== "device") return [];
   try {
     const deviceToken = ds.deviceToken;
@@ -1842,57 +2901,613 @@ async function fetchWidgetHistory(widget, window, bindings) {
     return [];
   }
 }
-function resolveHistorySelector(ds, bindings) {
-  if (!ds || ds.kind !== "slot") return ds;
-  const binding = bindings && Object.prototype.hasOwnProperty.call(bindings, ds.slot) ? bindings[ds.slot] : void 0;
-  if (binding?.kind === "device") {
-    return { kind: "device", deviceToken: binding.deviceToken, measurements: ds.measurements };
+
+// src/option-schema.ts
+var HOST_OPTION_CONTROLS = ["command-vocabulary", "slot-target", "basemap"];
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function validateOptions(specs, options, context) {
+  const { label: widgetId } = context;
+  const issues = [];
+  const bag = options ?? {};
+  for (const [key, spec] of Object.entries(specs)) {
+    const value = bag[key];
+    if (value === void 0 || spec.required && value === "") {
+      if (spec.required) {
+        issues.push({ widgetId, key, code: "missing", message: `${key} is required but not set` });
+      }
+      continue;
+    }
+    issues.push(...checkValue(widgetId, key, spec, value));
+  }
+  for (const key of Object.keys(bag)) {
+    if (hasOwn(specs, key)) continue;
+    issues.push({
+      widgetId,
+      key,
+      code: "unknown",
+      message: `${key} is not read by a ${widgetId} widget`
+    });
   }
-  if (binding?.kind === "anchor") {
-    return { kind: "anchor", anchor: binding.anchor, measurements: ds.measurements };
+  for (const constraint of context.constraints ?? []) {
+    const issue = checkConstraint(constraint, bag);
+    if (issue) issues.push({ widgetId, ...issue });
+  }
+  return issues;
+}
+function checkConstraint(constraint, bag) {
+  switch (constraint.kind) {
+    case "greater-than": {
+      const value = bag[constraint.key];
+      const than = bag[constraint.than];
+      if (typeof value !== "number" || typeof than !== "number") return void 0;
+      if (!Number.isFinite(value) || !Number.isFinite(than)) return void 0;
+      if (value > than) return void 0;
+      return {
+        key: constraint.key,
+        code: "invariant",
+        message: `${constraint.key} (${value}) must be greater than ${constraint.than} (${than})`
+      };
+    }
   }
-  return void 0;
+}
+function checkValue(widgetId, key, spec, value) {
+  const issue = (code, message) => [{ widgetId, key, code, message }];
+  switch (spec.kind) {
+    case "string":
+      if (typeof value !== "string") {
+        return issue("type", `${key} must be a string, got ${describe(value)}`);
+      }
+      if (spec.format === "json" && !parsesAsJson(value)) {
+        return issue("json", `${key} must be valid JSON`);
+      }
+      return [];
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        return issue("type", `${key} must be a finite number, got ${describe(value)}`);
+      }
+      if (spec.integer && !Number.isInteger(value)) {
+        return issue("range", `${key} must be a whole number, got ${value}`);
+      }
+      if (spec.min !== void 0 && value < spec.min) {
+        return issue("range", `${key} must be at least ${spec.min}, got ${value}`);
+      }
+      if (spec.max !== void 0 && value > spec.max) {
+        return issue("range", `${key} must be at most ${spec.max}, got ${value}`);
+      }
+      return [];
+    case "boolean":
+      if (typeof value !== "boolean") {
+        return issue("type", `${key} must be a boolean, got ${describe(value)}`);
+      }
+      return [];
+    case "enum":
+      if (typeof value !== "string") {
+        return issue("type", `${key} must be a string, got ${describe(value)}`);
+      }
+      if (!spec.values.includes(value)) {
+        return issue("enum", `${key} must be one of ${spec.values.join(", ")}, got ${JSON.stringify(value)}`);
+      }
+      return [];
+  }
+}
+function parsesAsJson(value) {
+  try {
+    JSON.parse(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function describe(value) {
+  if (value === null) return "null";
+  if (typeof value === "string") return `string ${JSON.stringify(value)}`;
+  if (Array.isArray(value)) return "an array";
+  return `${typeof value} ${JSON.stringify(value)}`;
+}
+function numberSpec(specs, key) {
+  if (!hasOwn(specs, key)) return void 0;
+  const spec = specs[key];
+  return spec.kind === "number" ? spec : void 0;
+}
+function clampNumberOption(spec, value) {
+  if (!Number.isFinite(value)) return void 0;
+  if (!spec) return value;
+  let next = spec.integer ? Math.trunc(value) : value;
+  if (spec.min !== void 0) next = Math.max(spec.min, next);
+  if (spec.max !== void 0) next = Math.min(spec.max, next);
+  return next;
+}
+function enumValues(specs, key) {
+  if (!hasOwn(specs, key)) return void 0;
+  const spec = specs[key];
+  return spec.kind === "enum" ? spec.values : void 0;
+}
+function applyOptionPatch(specs, options, patch, label = "widget") {
+  const next = { ...options ?? {} };
+  for (const [key, value] of Object.entries(patch)) {
+    if (!hasOwn(specs, key)) throw new Error(`${label}: "${key}" is not a declared option`);
+    const spec = specs[key];
+    if (value === void 0 || value === "" || spec.kind === "boolean" && value === false) {
+      delete next[key];
+      continue;
+    }
+    const refuse = (expected) => {
+      throw new TypeError(`${label}: option "${key}" takes ${expected}, got ${JSON.stringify(value)}`);
+    };
+    switch (spec.kind) {
+      case "string":
+        if (typeof value !== "string") refuse("a string");
+        if (spec.format === "json" && !parsesAsJson(value)) refuse("a JSON string");
+        next[key] = value;
+        break;
+      case "boolean":
+        if (typeof value !== "boolean") refuse("a boolean");
+        next[key] = value;
+        break;
+      case "number": {
+        if (typeof value !== "number") refuse("a finite number");
+        const clamped = clampNumberOption(spec, value);
+        if (clamped === void 0) refuse("a finite number");
+        next[key] = clamped;
+        break;
+      }
+      case "enum":
+        if (typeof value !== "string" || !spec.values.includes(value)) {
+          refuse(`one of ${spec.values.map((v) => JSON.stringify(v)).join(", ")}`);
+        }
+        next[key] = value;
+        break;
+    }
+  }
+  return next;
+}
+
+// src/widget-descriptor.ts
+var BUILTIN_IDS = new Set(WIDGET_TYPES);
+function isBuiltinWidgetId(id) {
+  return typeof id === "string" && BUILTIN_IDS.has(id);
+}
+var NAMESPACED_ID = /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/;
+function isNamespacedWidgetId(id) {
+  return typeof id === "string" && NAMESPACED_ID.test(id);
+}
+var SDK_API_VERSION = 1;
+function defineWidgetDescriptor(descriptor) {
+  return descriptor;
+}
+
+// src/widget-catalog.ts
+var WidgetCatalogError = class extends Error {
+  constructor(issues, subject = "widget catalog") {
+    super(describeIssues(subject, issues));
+    this.name = "WidgetCatalogError";
+    this.issues = Object.freeze([...issues]);
+  }
+};
+function describeIssues(subject, issues) {
+  const lines = issues.map((i) => `  - ${i.id}${i.path ? `.${i.path}` : ""}: ${i.message}`);
+  return `invalid ${subject} (${issues.length} problem${issues.length === 1 ? "" : "s"}):
+${lines.join("\n")}`;
+}
+var CHANNELS = ["measurement", "alarm", "control", "selection", "location", "none"];
+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"],
+  alarm: ["pageSize", "state", "severity", "acknowledged"],
+  control: ["pageSize"],
+  location: [],
+  selection: [],
+  none: []
+};
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPlainObject(value) {
+  if (!isRecord3(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+var join = (base, key) => base ? `${base}.${key}` : key;
+function validateWidgetDescriptor(descriptor) {
+  const rawId = isRecord3(descriptor) && typeof descriptor.id === "string" ? descriptor.id : "";
+  return collectDescriptorIssues(descriptor, rawId || "#?");
+}
+function collectDescriptorIssues(d, id) {
+  const issues = [];
+  const add = (path, message) => {
+    issues.push({ id, path, message });
+  };
+  if (!isPlainObject(d)) {
+    add("", "a descriptor must be a plain object");
+    return issues;
+  }
+  jsonOnly(d, "", add, /* @__PURE__ */ new Set());
+  if (typeof d.id !== "string" || d.id === "") {
+    add("id", "id must be a non-empty string");
+  } else if (!isBuiltinWidgetId(d.id) && !isNamespacedWidgetId(d.id)) {
+    add("id", `id ${JSON.stringify(d.id)} must be a reserved built-in id or a namespaced "scope/name" id`);
+  }
+  if (typeof d.version !== "string" || !SEMVER2.test(d.version)) {
+    add("version", `version must be MAJOR.MINOR.PATCH, got ${JSON.stringify(d.version)}`);
+  }
+  if (d.sdkApiVersion !== SDK_API_VERSION) {
+    add("sdkApiVersion", `unsupported sdkApiVersion ${JSON.stringify(d.sdkApiVersion)}; this build supports ${SDK_API_VERSION}`);
+  }
+  if (typeof d.optionsVersion !== "number" || !Number.isInteger(d.optionsVersion) || d.optionsVersion < 1) {
+    add("optionsVersion", `optionsVersion must be a positive integer, got ${JSON.stringify(d.optionsVersion)}`);
+  }
+  if (!isRecord3(d.display)) {
+    add("display", "display must be an object");
+  } else {
+    if (typeof d.display.title !== "string" || d.display.title === "") {
+      add("display.title", "display.title must be a non-empty string");
+    }
+    for (const text of ["description", "category", "titleId", "categoryId"]) {
+      const value = d.display[text];
+      if (value !== void 0 && typeof value !== "string") add(`display.${text}`, `display.${text} must be a string`);
+    }
+  }
+  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 constraints = checkConstraints(d.constraints, specs, add);
+  if (specs) checkDefaults(d.defaults, specs, constraints, typeof d.id === "string" ? d.id : id, add);
+  else if (!isRecord3(d.defaults)) add("defaults", "defaults must be an object");
+  checkDatasource(d.datasource, channel, add);
+  if (channel) checkBinding(d.binding, channel, specs, add);
+  checkInteractions(d.interactions, channel, add);
+  return issues;
+}
+function jsonOnly(value, path, add, ancestors) {
+  const here = path || "(descriptor)";
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return;
+    case "number":
+      if (!Number.isFinite(value)) add(path, `${here} is ${value}; descriptors hold JSON values only`);
+      return;
+    case "undefined":
+      add(path, `${here} is undefined; omit the key instead (descriptors hold JSON values only)`);
+      return;
+    case "function":
+    case "symbol":
+    case "bigint":
+      add(path, `${here} is a ${typeof value}; descriptors hold JSON values only`);
+      return;
+  }
+  if (value === null) return;
+  const obj = value;
+  if (ancestors.has(obj)) {
+    add(path, `${here} is a circular reference; descriptors hold JSON values only`);
+    return;
+  }
+  ancestors.add(obj);
+  if (Array.isArray(obj)) {
+    obj.forEach((item, i) => jsonOnly(item, `${path}[${i}]`, add, ancestors));
+  } else if (!isPlainObject(obj)) {
+    add(path, `${here} is not a plain object; descriptors hold JSON values only`);
+  } else {
+    if (Object.getOwnPropertySymbols(obj).length > 0) add(path, `${here} has a symbol key; descriptors hold JSON values only`);
+    for (const [key, item] of Object.entries(obj)) jsonOnly(item, join(path, key), add, ancestors);
+  }
+  ancestors.delete(obj);
+}
+function checkOptions(options, add) {
+  if (!isRecord3(options)) {
+    add("options", "options must be an object mapping option keys to specs");
+    return void 0;
+  }
+  let sound = true;
+  for (const [key, spec] of Object.entries(options)) {
+    const at = `options.${key}`;
+    if (!isRecord3(spec)) {
+      add(at, "an option spec must be an object");
+      sound = false;
+      continue;
+    }
+    if (typeof spec.doc !== "string") {
+      add(`${at}.doc`, "doc must be a string");
+    }
+    for (const text of ["label", "help", "labelId", "helpId", "placeholder", "placeholderId"]) {
+      if (spec[text] !== void 0 && typeof spec[text] !== "string") add(`${at}.${text}`, `${text} must be a string`);
+    }
+    if (spec.control !== void 0 && (typeof spec.control !== "string" || spec.control === "")) {
+      add(`${at}.control`, `control must be a non-empty string, got ${JSON.stringify(spec.control)}`);
+    }
+    switch (spec.kind) {
+      case "string":
+      case "boolean":
+        break;
+      case "number":
+        for (const bound of ["min", "max"]) {
+          if (spec[bound] !== void 0 && typeof spec[bound] !== "number") add(`${at}.${bound}`, `${bound} must be a number`);
+        }
+        break;
+      case "enum":
+        if (!Array.isArray(spec.values) || spec.values.length === 0 || !spec.values.every((v) => typeof v === "string")) {
+          add(`${at}.values`, "an enum option needs a non-empty list of string values");
+          sound = false;
+        }
+        for (const table of ["valueLabels", "valueLabelIds"]) {
+          const labels = spec[table];
+          if (labels === void 0) continue;
+          if (!isRecord3(labels)) {
+            add(`${at}.${table}`, `${table} must be an object mapping enum values to strings`);
+            continue;
+          }
+          for (const [value, label] of Object.entries(labels)) {
+            if (typeof label !== "string") add(`${at}.${table}.${value}`, `${table} entries must be strings`);
+            else if (Array.isArray(spec.values) && !spec.values.includes(value)) {
+              add(`${at}.${table}.${value}`, `${JSON.stringify(value)} is not one of this option's values`);
+            }
+          }
+        }
+        break;
+      default:
+        add(`${at}.kind`, `kind must be string, number, boolean or enum, got ${JSON.stringify(spec.kind)}`);
+        sound = false;
+    }
+  }
+  return sound ? options : void 0;
+}
+function checkConstraints(constraints, specs, add) {
+  if (constraints === void 0) return [];
+  if (!Array.isArray(constraints)) {
+    add("constraints", "constraints must be a list");
+    return [];
+  }
+  const valid = [];
+  constraints.forEach((c, i) => {
+    const at = `constraints[${i}]`;
+    if (!isRecord3(c) || c.kind !== "greater-than") {
+      add(`${at}.kind`, `constraint kind must be "greater-than", got ${JSON.stringify(isRecord3(c) ? c.kind : c)}`);
+      return;
+    }
+    let ok = true;
+    for (const field of ["key", "than"]) {
+      const name = c[field];
+      if (typeof name !== "string") {
+        add(`${at}.${field}`, `${field} must name a declared option`);
+        ok = false;
+      } else if (specs && (!hasOwn(specs, name) || specs[name].kind !== "number")) {
+        add(`${at}.${field}`, `${field} ${JSON.stringify(name)} must name a declared number option`);
+        ok = false;
+      }
+    }
+    if (ok) valid.push({ kind: "greater-than", key: c.key, than: c.than });
+  });
+  return valid;
+}
+function checkDefaults(defaults, specs, constraints, id, add) {
+  if (!isRecord3(defaults)) {
+    add("defaults", "defaults must be an object");
+    return;
+  }
+  const found = validateOptions(specs, defaults, { constraints, label: id }).filter(
+    (issue) => issue.code !== "missing"
+  );
+  for (const issue of found) add(`defaults.${issue.key}`, issue.message);
+}
+function checkDatasource(datasource, channel, add) {
+  if (!isRecord3(datasource)) {
+    add("datasource", "datasource must be an object");
+    return;
+  }
+  const mode = datasource.mode;
+  if (mode !== "none" && mode !== "optional" && mode !== "required") {
+    add("datasource.mode", `mode must be none, optional or required, got ${JSON.stringify(mode)}`);
+    return;
+  }
+  if ((channel === "none" || channel === "selection") && mode !== "none") {
+    add("datasource.mode", `a ${channel}-channel widget opens no data channel, so its datasource mode must be "none"`);
+  }
+  if (mode === "none") {
+    if (datasource.selectors !== void 0) add("datasource.selectors", 'a datasource mode of "none" takes no selectors');
+    return;
+  }
+  const selectors = datasource.selectors;
+  if (!Array.isArray(selectors) || selectors.length === 0) {
+    add("datasource.selectors", `a datasource mode of "${mode}" needs a non-empty list of selector kinds`);
+    return;
+  }
+  selectors.forEach((s, i) => {
+    if (typeof s !== "string" || !SELECTOR_KINDS.includes(s)) {
+      add(`datasource.selectors[${i}]`, `selector must be one of ${SELECTOR_KINDS.join(", ")}, got ${JSON.stringify(s)}`);
+    } else if (channel === "control" && s !== "device" && s !== "slot") {
+      add(`datasource.selectors[${i}]`, "a command target must be a device, so a control widget accepts only device and slot selectors");
+    }
+  });
+}
+function checkBinding(binding, channel, specs, add) {
+  if (!isRecord3(binding)) {
+    add("binding", "binding must be an object");
+    return;
+  }
+  const allowed = BINDING_KEYS[channel];
+  for (const key of Object.keys(binding)) {
+    if (!allowed.includes(key)) add(`binding.${key}`, `a ${channel}-channel widget has no binding policy "${key}"`);
+  }
+  if (allowed.includes("pageSize") && binding.pageSize === void 0) {
+    add("binding.pageSize", `a ${channel}-channel widget must declare binding.pageSize`);
+  }
+  const ref = (key, accept, expect, allowConst) => {
+    const policy = binding[key];
+    if (policy === void 0) return;
+    const at = `binding.${key}`;
+    if (!isRecord3(policy)) {
+      add(at, `${key} must be an object`);
+      return;
+    }
+    const hasConst = policy.const !== void 0;
+    const hasOption = policy.option !== void 0;
+    if (hasConst) {
+      if (!allowConst) add(`${at}.const`, `${key} takes an option reference, not a constant`);
+      else if (typeof policy.const !== "number" || !Number.isInteger(policy.const) || policy.const < 1) {
+        add(`${at}.const`, `const must be a positive integer, got ${JSON.stringify(policy.const)}`);
+      }
+      if (hasOption) add(at, `${key} must be a constant or an option reference, not both`);
+      return;
+    }
+    if (!hasOption) {
+      add(at, `${key} must be a constant or an option reference`);
+      return;
+    }
+    const name = policy.option;
+    if (typeof name !== "string") {
+      add(`${at}.option`, "option must name a declared option key");
+    } else if (specs) {
+      if (!hasOwn(specs, name)) add(`${at}.option`, `option ${JSON.stringify(name)} is not a declared option key`);
+      else if (!accept(specs[name])) add(`${at}.option`, `option ${JSON.stringify(name)} must be ${expect}`);
+    }
+    if (policy.min !== void 0 && typeof policy.min !== "number") add(`${at}.min`, "min must be a number");
+    if (policy.default !== void 0) {
+      const wantsNumber = key === "window" || key === "pageSize";
+      if (typeof policy.default !== (wantsNumber ? "number" : "string")) {
+        add(`${at}.default`, `default must be a ${wantsNumber ? "number" : "string"}`);
+      }
+    }
+  };
+  const isNumber = (s) => s.kind === "number";
+  const isText = (s) => s.kind === "string" || s.kind === "enum";
+  const isBoolEnum = (s) => s.kind === "enum" && s.values.every((v) => v === "true" || v === "false");
+  ref("window", isNumber, "a number option", false);
+  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("acknowledged", isBoolEnum, 'an enum option whose values are only "true" and "false"', false);
+}
+function checkInteractions(interactions, channel, add) {
+  if (!isRecord3(interactions)) {
+    add("interactions", "interactions must be an object");
+    return;
+  }
+  const only = { alarmActions: "alarm", commandSend: "control" };
+  for (const [key, value] of Object.entries(interactions)) {
+    const at = `interactions.${key}`;
+    if (key !== "alarmActions" && key !== "commandSend" && key !== "selection" && key !== "candidates") {
+      add(at, `unknown interaction "${key}"`);
+    } else if (value !== true) {
+      add(at, `${key} must be true when declared (omit it otherwise)`);
+    } else if (channel && only[key] && only[key] !== channel) {
+      add(at, `${key} is only available to ${only[key]}-channel widgets, not ${channel}`);
+    }
+  }
+}
+function deepFreeze(value) {
+  if (typeof value === "object" && value !== null) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+function createWidgetCatalog(descriptors) {
+  const issues = collectCatalogIssues(descriptors);
+  if (issues.length > 0) throw new WidgetCatalogError(issues);
+  return sealCatalog(descriptors);
+}
+function collectCatalogIssues(descriptors) {
+  if (!Array.isArray(descriptors)) {
+    return [{ id: "#?", path: "", message: "descriptors must be an array" }];
+  }
+  const issues = [];
+  const seen = /* @__PURE__ */ new Map();
+  descriptors.forEach((d, index) => {
+    const id = isRecord3(d) && typeof d.id === "string" && d.id !== "" ? d.id : `#${index}`;
+    issues.push(...collectDescriptorIssues(d, id));
+    if (id.startsWith("#")) return;
+    const first = seen.get(id);
+    if (first === void 0) seen.set(id, index);
+    else issues.push({ id, path: "id", message: `duplicate widget id (first registered at position ${first}, again at ${index})` });
+  });
+  return issues;
+}
+function sealCatalog(descriptors) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const d of descriptors) byId.set(d.id, deepFreeze(d));
+  const ordered = Object.freeze([...byId.values()]);
+  return Object.freeze({
+    has: (id) => byId.has(id),
+    get: (id) => byId.get(id),
+    list: () => ordered
+  });
 }
 export {
   BASE_BREAKPOINT,
   COMMAND_STATUSES,
   DashboardDefinitionError,
   DashboardHub,
+  HOST_OPTION_CONTROLS,
+  NotInRecordingError,
+  PLAYBACK_RATES,
+  RECORDED_HISTORY_WINDOW_MS,
+  RECORDING_FORMAT_VERSION,
+  RECORDING_KIND,
+  RecordedClock,
+  RecordedDataSource,
+  RecordingFormatError,
+  SDK_API_VERSION,
   SYNTHETIC_GENERATORS,
   SyntheticDataSource,
+  UNKNOWN_WIDGET_TYPE,
   WIDGET_TYPES,
+  WidgetCatalogError,
   activeBreakpoint,
   addWidget,
   anchorSlotNames,
+  applyOptionPatch,
   applySelection,
   baseBox,
   bindWidgetSlot,
   bindingsWithoutScopedSlots,
   bringToFront,
   canScopeSlot,
+  checkWidgetCompatibility,
+  clampNumberOption,
   clearWidgetDatasource,
+  collectCatalogIssues,
   createDeviceResolver,
   createEntityLister,
+  createRecordedClock,
+  createRecordedLister,
+  createRecordedResolver,
+  createWidgetCatalog,
   defaultHistoryWindow,
+  defineWidgetDescriptor,
   deleteWidget,
+  describeIssues,
   effectiveBindings,
+  enumValues,
   fetchWidgetHistory,
   generateWidgetId,
   gridBoxToPx,
   hasScopedSlots,
+  isBuiltinWidget,
+  isBuiltinWidgetId,
   isCancellableCommandStatus,
   isDirty,
+  isNamespacedWidgetId,
+  isResolvedWidget,
   isTerminalCommandStatus,
   migrateToSlots,
+  numberSpec,
   parseBindingManifest,
+  parseBoardRecording,
   parseDashboardDefinition,
   parseSlotBinding,
+  parseWidgetRef,
   pruneSlots,
   pxToGridBox,
+  recordedWallTimeMs,
+  recordingBounds,
   resolveConcrete,
   resolveContextBindings,
   resolveSlotCandidates,
   resolveWidgetBox,
+  resolveWidgetDatasource,
   sameBinding,
   serializeDefinition,
   setCanvasGrid,
@@ -1900,9 +3515,15 @@ export {
   setSlotScope,
   setTitle,
   setWidgetBox,
+  simulationScaleAt,
+  storedDefinition,
   stripDefaultBindings,
+  unresolvedWidgets,
   updateWidget,
+  validateOptions,
+  validateWidgetDescriptor,
   widgetBinding,
-  widgetSlotName
+  widgetSlotName,
+  widgetVersionNotice
 };
 //# sourceMappingURL=index.js.map