@camstack/types 1.2.535 → 1.2.536

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -33008,11 +33008,35 @@ function normalizeStepTargets(steps) {
33008
33008
  /**
33009
33009
  * The steps an internal Action may contain: cap and wait, and nothing that can
33010
33010
  * call back into an Action — so an Action can never reach itself (no cycles).
33011
+ * This is the LEAF shape: no condition of its own.
33011
33012
  */
33012
- var ActionStepSchema = zod.z.discriminatedUnion("kind", [AutomationWaitStepSchema, AutomationCapStepSchema]);
33013
+ var LeafActionStepSchema = zod.z.discriminatedUnion("kind", [AutomationWaitStepSchema, AutomationCapStepSchema]);
33014
+ /**
33015
+ * The optional guard of a step (#472): `if` is the ONE `when` tree (D980), read
33016
+ * on the state mirror when the step is reached; `else` runs when it is false.
33017
+ * An `else` holds leaf steps only — the nesting is bounded at ONE level, so a
33018
+ * branch can never grow a tree the trace has to draw.
33019
+ */
33020
+ var stepGuardShape = {
33021
+ if: AutomationWhenSchema.optional(),
33022
+ else: zod.z.array(LeafActionStepSchema).max(10).optional()
33023
+ };
33024
+ var elseNeedsIf = {
33025
+ message: "an else list needs the condition it is the other side of (if)",
33026
+ path: ["else"]
33027
+ };
33028
+ var GuardedWaitStepSchema = AutomationWaitStepSchema.extend(stepGuardShape).refine((step) => step.else === void 0 || step.if !== void 0, elseNeedsIf);
33029
+ var GuardedCapStepSchema = AutomationCapStepBaseSchema.extend(stepGuardShape).refine((step) => step.target !== void 0 || step.deviceId !== void 0, {
33030
+ message: "a cap step needs a target",
33031
+ path: ["target"]
33032
+ }).refine((step) => step.target?.kind !== "domain" || step.actionId !== void 0, {
33033
+ message: "a domain target needs the vocabulary action it applies to (actionId)",
33034
+ path: ["actionId"]
33035
+ }).refine((step) => step.else === void 0 || step.if !== void 0, elseNeedsIf);
33036
+ var ActionStepSchema = zod.z.discriminatedUnion("kind", [GuardedWaitStepSchema, GuardedCapStepSchema]);
33013
33037
  var AutomationActionSchema = zod.z.discriminatedUnion("kind", [
33014
- AutomationWaitStepSchema,
33015
- AutomationCapStepSchema,
33038
+ GuardedWaitStepSchema,
33039
+ GuardedCapStepSchema,
33016
33040
  zod.z.object({
33017
33041
  kind: zod.z.literal("action"),
33018
33042
  /** An entry of the `actions` surface (`internal:<uuid>` or `<addonId>:<localId>`). */
@@ -33358,10 +33382,32 @@ function emitLeaf(trigger, path) {
33358
33382
  }`;
33359
33383
  }
33360
33384
  }
33385
+ /** The body of a wait or cap step, shared by a top-level step and an else step. */
33386
+ function emitLeafBody(action) {
33387
+ switch (action.kind) {
33388
+ case "wait": return ` await sleep(${j(action.seconds * 1e3)})`;
33389
+ case "cap": {
33390
+ const { target, actionId } = normalizeCapStep(action);
33391
+ return ` await actuateTarget(scope, ${j(target)}, ${j(actionId)}, ${j(action.cap)}, ${j(action.method)}, ${j(action.args ?? {})}, vars)`;
33392
+ }
33393
+ default: return null;
33394
+ }
33395
+ }
33396
+ /** A step's `if` (#472) and its else list, as the fields of a RunnableStep. */
33397
+ function emitGuard(action) {
33398
+ if (action.kind !== "wait" && action.kind !== "cap") return "";
33399
+ if (action.if === void 0) return "";
33400
+ const otherwise = (action.else ?? []).map((el) => {
33401
+ const body = emitLeafBody(el);
33402
+ return `{ meta: ${j(stepMetaOf(el))}, run: async (scope) => {\n${body ?? ""}\n } }`;
33403
+ }).join(", ");
33404
+ return ` guard: () => evaluateCondition(${j(action.if)}),${otherwise === "" ? "" : `\n otherwise: [${otherwise}],`}
33405
+ `;
33406
+ }
33361
33407
  function emitAction(action, index) {
33362
33408
  const step = (body) => ` {
33363
33409
  meta: STEP_META[${index}]!,
33364
- run: async (scope) => {
33410
+ ${emitGuard(action)} run: async (scope) => {
33365
33411
  ${body}
33366
33412
  },
33367
33413
  },`;
@@ -33414,6 +33460,7 @@ function generateAutomationBlock(input) {
33414
33460
  AutomationConditionTraceNode,
33415
33461
  AutomationRunTrace,
33416
33462
  AutomationRunVerdict,
33463
+ AutomationWhen,
33417
33464
  AutomationStepTrace,
33418
33465
  RunnableStep,
33419
33466
  StepScope,
@@ -33437,7 +33484,9 @@ import {
33437
33484
  nextOccurrence,
33438
33485
  stableIdMapOf,
33439
33486
  resolveStepArgs,
33487
+ resolveStepArgsWithTemplates,
33440
33488
  runForDevices,
33489
+ evaluateStepCondition,
33441
33490
  runSteps,
33442
33491
  validateTimeSpecForSite,
33443
33492
  zoneOnlySite,
@@ -33636,7 +33685,7 @@ export default function block(ctx: AddonContext) {
33636
33685
  fetchSlice: (deviceId, cap) => ctx.api.deviceState.getCapSlice.query({ deviceId, capName: cap }),
33637
33686
  fetchStableIds: async () => {
33638
33687
  const all = await ctx.api.deviceManager.listAll.query({})
33639
- return stableIdMapOf(all.devices)
33688
+ return stableIdMapOf(all)
33640
33689
  },
33641
33690
  })
33642
33691
  if (report.kept > 0) {
@@ -33743,6 +33792,12 @@ export default function block(ctx: AddonContext) {
33743
33792
  ctx.logger.warn('template referenced a var that was never set', { var: name })
33744
33793
  }
33745
33794
 
33795
+ /** Device value templates (D1021) render on the hub through the ONE renderer; this block keeps no copy. */
33796
+ async function renderTemplates(templates: readonly string[]) {
33797
+ const out = await ctx.api.deviceManager.renderDeviceTemplates.query({ templates: [...templates] })
33798
+ return out.results
33799
+ }
33800
+
33746
33801
  /** Substitute {{vars.x}} slots and { $var } values. Substitution only — never evaluation. */
33747
33802
  function substitute(value: unknown, vars: Record<string, unknown>): unknown {
33748
33803
  return resolveStepArgs(value, vars, warnMissingVar)
@@ -33771,7 +33826,9 @@ export default function block(ctx: AddonContext) {
33771
33826
  args: Record<string, unknown>,
33772
33827
  vars: Record<string, unknown>,
33773
33828
  ): Promise<void> {
33774
- const substituted = substitute(args, vars)
33829
+ const templated = await resolveStepArgsWithTemplates(args, vars, warnMissingVar, renderTemplates)
33830
+ if (templated.notes.length > 0) scope.setTemplateNotes(templated.notes)
33831
+ const substituted = templated.value
33775
33832
  const resolved: Record<string, unknown> =
33776
33833
  substituted !== null && typeof substituted === 'object' ? { ...substituted } : {}
33777
33834
  scope.setArgs(resolved)
@@ -33788,6 +33845,17 @@ export default function block(ctx: AddonContext) {
33788
33845
  await mutate({ ...resolved, deviceId })
33789
33846
  }
33790
33847
 
33848
+ /** A step's \`if\` (#472), read on a mirror filled for exactly its leaves, NOW (D49: unread = unknown). */
33849
+ function evaluateCondition(when: AutomationWhen) {
33850
+ return evaluateStepCondition(when, {
33851
+ fetchSlice: (deviceId, cap) => ctx.api.deviceState.getCapSlice.query({ deviceId, capName: cap }),
33852
+ fetchStableIds: async () => {
33853
+ const all = await ctx.api.deviceManager.listAll.query({})
33854
+ return stableIdMapOf(all)
33855
+ },
33856
+ })
33857
+ }
33858
+
33791
33859
  /** The THEN half, through the ONE shared step runner: stops at the first
33792
33860
  * failure (continuing past a failed step executes an intent the operator
33793
33861
  * never expressed); every step is traced, the ones after a failure (or an
@@ -33812,6 +33880,13 @@ ${recipe.actions.map((a, i) => emitAction(a, i)).join("\n")}
33812
33880
  error: failure.message,
33813
33881
  })
33814
33882
  },
33883
+ onGuardUnknown: (skipped) => {
33884
+ ctx.logger.warn('step skipped — its condition could not be read', {
33885
+ ...(skipped.deviceId === undefined ? {} : { tags: { deviceId: skipped.deviceId } }),
33886
+ step: skipped.index,
33887
+ reason: skipped.reason,
33888
+ })
33889
+ },
33815
33890
  })
33816
33891
  }
33817
33892
 
@@ -35182,7 +35257,7 @@ var StepDeviceTraceSchema = zod.z.object({
35182
35257
  outcome: zod.z.enum(["ok", "error"]),
35183
35258
  message: zod.z.string().optional()
35184
35259
  });
35185
- var AutomationStepTraceSchema = zod.z.object({
35260
+ var StepTraceBaseSchema = zod.z.object({
35186
35261
  /** `actions.<i>` */
35187
35262
  path: zod.z.string().min(1),
35188
35263
  kind: zod.z.string().min(1),
@@ -35201,15 +35276,35 @@ var AutomationStepTraceSchema = zod.z.object({
35201
35276
  * is shown as {@link REDACTED_ARG}. Absent on traces written before it existed.
35202
35277
  */
35203
35278
  args: zod.z.record(zod.z.string(), TraceValueSchema).optional(),
35204
- /** `empty`: the target resolved to no device, so nothing was done — never silently `ok`. */
35279
+ /**
35280
+ * The device values a templated arg printed as `—`, one `ref: reason` each
35281
+ * (D1021): why a sentence says "—" where a number was expected. Bounded.
35282
+ */
35283
+ templates: zod.z.array(zod.z.string()).max(20).optional(),
35284
+ /**
35285
+ * What the step's own `if` read when the step was reached (#472): `true` the
35286
+ * step ran, `false` its `else` ran (or nothing did), `unknown` a state leaf
35287
+ * could not be read, so NEITHER side ran. Absent on an unguarded step.
35288
+ */
35289
+ condition: zod.z.enum([
35290
+ "true",
35291
+ "false",
35292
+ "unknown"
35293
+ ]).optional(),
35294
+ /** Why the condition read what it read, in the evaluator's own words. */
35295
+ conditionReason: zod.z.string().optional(),
35296
+ /** `empty`: the target resolved to no device, so nothing was done — never silently `ok`. `skipped`: its `if` was false (or unknown) and nothing ran in its place. */
35205
35297
  outcome: zod.z.enum([
35206
35298
  "ok",
35207
35299
  "error",
35208
35300
  "not-run",
35209
- "empty"
35301
+ "empty",
35302
+ "skipped"
35210
35303
  ]),
35211
35304
  message: zod.z.string().optional()
35212
35305
  });
35306
+ /** A step trace; the `else` steps that ran are one level of the same shape (the nesting is bounded at one). */
35307
+ var AutomationStepTraceSchema = StepTraceBaseSchema.extend({ else: zod.z.array(StepTraceBaseSchema).optional() });
35213
35308
  var AutomationRunTraceSchema = zod.z.object({
35214
35309
  runId: zod.z.string().min(1),
35215
35310
  startedAt: zod.z.number(),
@@ -35545,6 +35640,7 @@ var ActionErrorCodeSchema = zod.z.enum([
35545
35640
  "invalid-variables",
35546
35641
  "invalid-steps",
35547
35642
  "not-linked",
35643
+ "template-scope",
35548
35644
  "busy"
35549
35645
  ]);
35550
35646
  /**
@@ -35594,10 +35690,53 @@ function normalizeNcAction(action) {
35594
35690
  };
35595
35691
  }
35596
35692
  //#endregion
35693
+ //#region src/automation/step-condition.ts
35694
+ /**
35695
+ * The guard of a conditional step (#472): the step's `if` is the ONE `when`
35696
+ * tree (D980), read on a {@link ConditionMirror} filled for exactly the leaves
35697
+ * the tree names, at the moment the step is reached. A state that cannot be
35698
+ * read is UNKNOWN, and unknown runs neither side (D49: a failed read changes
35699
+ * nothing, and never decides a branch).
35700
+ */
35701
+ /** Fill a mirror for the tree's leaves from `fetchers` and judge it NOW. */
35702
+ async function evaluateStepCondition(when, fetchers, now = Date.now) {
35703
+ const mirror = new ConditionMirror(collectWhenMirrorSources(when));
35704
+ await mirror.refresh(fetchers);
35705
+ const evaluation = evaluateWhenTree(when, mirror, now());
35706
+ const first = evaluation.nodes.filter((n) => n.outcome !== "pass").map((n) => n.reason)[0];
35707
+ if (evaluation.unknown) return {
35708
+ result: "unknown",
35709
+ reason: `a state the condition reads is not known${first === void 0 ? "" : ` (${first})`}`
35710
+ };
35711
+ return evaluation.pass ? {
35712
+ result: "true",
35713
+ reason: "the condition holds"
35714
+ } : {
35715
+ result: "false",
35716
+ reason: first ?? "the condition does not hold"
35717
+ };
35718
+ }
35719
+ //#endregion
35597
35720
  //#region src/automation/step-runner.ts
35598
35721
  function errorMessage(err) {
35599
35722
  return err instanceof Error ? err.message : String(err);
35600
35723
  }
35724
+ /** A guard that throws is an unknown, never a crash of the run. */
35725
+ async function readGuard(guard) {
35726
+ try {
35727
+ return await guard();
35728
+ } catch (err) {
35729
+ return {
35730
+ result: "unknown",
35731
+ reason: `the condition could not be read: ${errorMessage(err)}`
35732
+ };
35733
+ }
35734
+ }
35735
+ /** The else level of a trace is one level deep: a nested trace carries no `else` of its own. */
35736
+ function withoutElse(trace) {
35737
+ const { else: _else, ...rest } = trace;
35738
+ return rest;
35739
+ }
35601
35740
  async function runSteps(steps, options) {
35602
35741
  const traces = [];
35603
35742
  let failed = false;
@@ -35615,10 +35754,57 @@ async function runSteps(steps, options) {
35615
35754
  continue;
35616
35755
  }
35617
35756
  const startedAt = options.now();
35757
+ let guardTrace = {};
35758
+ if (step.guard !== void 0) {
35759
+ const verdict = await readGuard(step.guard);
35760
+ guardTrace = {
35761
+ condition: verdict.result,
35762
+ conditionReason: verdict.reason
35763
+ };
35764
+ if (verdict.result === "unknown") options.onGuardUnknown?.({
35765
+ index,
35766
+ path,
35767
+ reason: verdict.reason,
35768
+ deviceId: step.meta.deviceId
35769
+ });
35770
+ if (verdict.result !== "true") {
35771
+ const branch = verdict.result === "false" ? step.otherwise ?? [] : [];
35772
+ if (branch.length === 0) {
35773
+ traces.push({
35774
+ ...step.meta,
35775
+ ...guardTrace,
35776
+ path,
35777
+ startedAt,
35778
+ endedAt: options.now(),
35779
+ outcome: "skipped",
35780
+ message: verdict.result === "unknown" ? `not run: ${verdict.reason}` : `not run: the condition is false (${verdict.reason})`
35781
+ });
35782
+ continue;
35783
+ }
35784
+ const sub = await runSteps(branch, {
35785
+ ...options,
35786
+ pathPrefix: `${path}.else`
35787
+ });
35788
+ if (sub.failed) failed = true;
35789
+ else if (sub.aborted) aborted = true;
35790
+ traces.push({
35791
+ ...step.meta,
35792
+ ...guardTrace,
35793
+ path,
35794
+ startedAt,
35795
+ endedAt: options.now(),
35796
+ outcome: sub.failed ? "error" : "ok",
35797
+ ...sub.failed ? { message: "an else step failed" } : {},
35798
+ else: sub.steps.map(withoutElse)
35799
+ });
35800
+ continue;
35801
+ }
35802
+ }
35618
35803
  let deviceId = step.meta.deviceId;
35619
35804
  let sent;
35620
35805
  const perDevice = [];
35621
35806
  let emptyReason;
35807
+ let templateNotes = [];
35622
35808
  const scope = {
35623
35809
  setDeviceId: (id) => {
35624
35810
  deviceId = id;
@@ -35631,8 +35817,12 @@ async function runSteps(steps, options) {
35631
35817
  },
35632
35818
  setArgs: (args) => {
35633
35819
  sent = args;
35820
+ },
35821
+ setTemplateNotes: (notes) => {
35822
+ templateNotes = notes.slice(0, 20);
35634
35823
  }
35635
35824
  };
35825
+ const templatesTrace = () => templateNotes.length === 0 ? {} : { templates: [...templateNotes] };
35636
35826
  const argsTrace = () => sent === void 0 ? {} : { args: buildStepArgsTrace(sent) };
35637
35827
  const devicesTrace = () => perDevice.length === 0 ? {} : { devices: perDevice.slice(0, 200) };
35638
35828
  try {
@@ -35641,7 +35831,9 @@ async function runSteps(steps, options) {
35641
35831
  ...step.meta,
35642
35832
  ...deviceId === void 0 || perDevice.length > 1 ? {} : { deviceId },
35643
35833
  ...argsTrace(),
35834
+ ...templatesTrace(),
35644
35835
  ...devicesTrace(),
35836
+ ...guardTrace,
35645
35837
  path,
35646
35838
  startedAt,
35647
35839
  endedAt: options.now(),
@@ -35661,7 +35853,9 @@ async function runSteps(steps, options) {
35661
35853
  ...step.meta,
35662
35854
  ...deviceId === void 0 || perDevice.length > 1 ? {} : { deviceId },
35663
35855
  ...argsTrace(),
35856
+ ...templatesTrace(),
35664
35857
  ...devicesTrace(),
35858
+ ...guardTrace,
35665
35859
  path,
35666
35860
  startedAt,
35667
35861
  endedAt: options.now(),
@@ -35710,6 +35904,125 @@ function resolveStepArgs(value, vars, onMissing) {
35710
35904
  if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveStepArgs(v, vars, onMissing)]));
35711
35905
  return value;
35712
35906
  }
35907
+ /** A device template that did not render: the step fails with this, never throws past `runSteps`. */
35908
+ var StepTemplateError = class extends Error {
35909
+ reason;
35910
+ constructor(reason, message) {
35911
+ super(`device template [${reason}]: ${message}`);
35912
+ this.reason = reason;
35913
+ this.name = "StepTemplateError";
35914
+ }
35915
+ };
35916
+ /**
35917
+ * A `{{vars.x}}` slot, set aside while a template renders. The slot carries a
35918
+ * nonce drawn per call, so a device value that happens to contain the sentinel
35919
+ * characters can never name a held variable.
35920
+ */
35921
+ var VAR_SLOT_OPEN = "";
35922
+ var VAR_SLOT_CLOSE = "";
35923
+ var TEMPLATE_MARKUP_RE = /\{\{|\{%/;
35924
+ function newSlotNonce() {
35925
+ return Math.random().toString(36).slice(2, 12);
35926
+ }
35927
+ function slotPattern(nonce) {
35928
+ return new RegExp(`${VAR_SLOT_OPEN}${nonce}:([A-Za-z_][A-Za-z0-9_]*)${VAR_SLOT_CLOSE}`, "g");
35929
+ }
35930
+ /** True when a string, once its `{{vars.x}}` slots are set aside, still carries template markup. */
35931
+ function carriesDeviceTemplate(text) {
35932
+ return TEMPLATE_MARKUP_RE.test(text.replace(TEMPLATE_RE, ""));
35933
+ }
35934
+ /** Every string in `value` that is a device template (D1021), de-duplicated, in walk order. */
35935
+ function collectDeviceTemplates(value) {
35936
+ const found = /* @__PURE__ */ new Set();
35937
+ const walk = (node) => {
35938
+ if (typeof node === "string") {
35939
+ if (carriesDeviceTemplate(node)) found.add(node);
35940
+ } else if (Array.isArray(node)) for (const item of node) walk(item);
35941
+ else if (node !== null && typeof node === "object") for (const item of Object.values(node)) walk(item);
35942
+ };
35943
+ walk(value);
35944
+ return [...found];
35945
+ }
35946
+ function protectVarSlots(text, nonce) {
35947
+ return text.replace(TEMPLATE_RE, (_m, key) => `${VAR_SLOT_OPEN}${nonce}:${key}${VAR_SLOT_CLOSE}`);
35948
+ }
35949
+ function restoreVarSlots(text, nonce, vars, onMissing) {
35950
+ return text.replace(slotPattern(nonce), (_m, key) => {
35951
+ const v = vars[key];
35952
+ if (v === void 0) {
35953
+ onMissing(key);
35954
+ return "";
35955
+ }
35956
+ return String(v);
35957
+ });
35958
+ }
35959
+ /**
35960
+ * {@link resolveStepArgs} plus the device templates of a step (D1021). A string
35961
+ * that carries `{{ … }}` / `{% … %}` beyond a `{{vars.x}}` slot is rendered by
35962
+ * `render` BEFORE the variables are put in, so a variable's value is data and
35963
+ * never template source (an action variable can come from a non-admin caller).
35964
+ * A refused render, or no renderer, throws {@link StepTemplateError}: the step
35965
+ * fails with the typed reason and nothing is dispatched.
35966
+ */
35967
+ async function resolveStepArgsWithTemplates(value, vars, onMissing, render) {
35968
+ const nonce = newSlotNonce();
35969
+ const sources = [];
35970
+ const indexOf = /* @__PURE__ */ new Map();
35971
+ const hold = (text) => {
35972
+ const known = indexOf.get(text);
35973
+ if (known !== void 0) return known;
35974
+ sources.push(text);
35975
+ indexOf.set(text, sources.length - 1);
35976
+ return sources.length - 1;
35977
+ };
35978
+ class Pending {
35979
+ index;
35980
+ constructor(index) {
35981
+ this.index = index;
35982
+ }
35983
+ }
35984
+ const collect = (node) => {
35985
+ if (isVarRef(node)) return resolveStepArgs(node, vars, onMissing);
35986
+ if (typeof node === "string") return carriesDeviceTemplate(node) ? new Pending(hold(protectVarSlots(node, nonce))) : resolveStepArgs(node, vars, onMissing);
35987
+ if (Array.isArray(node)) return node.map(collect);
35988
+ if (node !== null && typeof node === "object") return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, collect(v)]));
35989
+ return node;
35990
+ };
35991
+ const skeleton = collect(value);
35992
+ if (sources.length === 0) return {
35993
+ value: skeleton,
35994
+ notes: []
35995
+ };
35996
+ if (render === void 0) throw new StepTemplateError("unavailable", "this node has no device template renderer");
35997
+ let answers;
35998
+ try {
35999
+ answers = await render(sources);
36000
+ } catch (err) {
36001
+ throw new StepTemplateError("unavailable", errorMessage(err));
36002
+ }
36003
+ const texts = [];
36004
+ const notes = [];
36005
+ for (const index of sources.keys()) {
36006
+ const answer = answers[index];
36007
+ if (answer === void 0) throw new StepTemplateError("unavailable", `no answer for template ${index + 1}`);
36008
+ if (!answer.ok) throw new StepTemplateError(answer.refusal.reason, answer.refusal.message);
36009
+ texts.push(restoreVarSlots(answer.text, nonce, vars, onMissing));
36010
+ for (const entry of answer.trace) {
36011
+ const note = `${entry.ref}: ${entry.reason}`;
36012
+ if (!notes.includes(note)) notes.push(note);
36013
+ }
36014
+ }
36015
+ const fill = (node) => {
36016
+ if (node instanceof Pending) return texts[node.index] ?? "";
36017
+ if (Array.isArray(node)) return node.map(fill);
36018
+ if (node !== null && typeof node === "object") return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, fill(v)]));
36019
+ return node;
36020
+ };
36021
+ return {
36022
+ value: fill(skeleton),
36023
+ notes
36024
+ };
36025
+ }
35713
36026
  /** A `{ $var }` device target, resolved from the bag BEFORE dispatch. */
35714
36027
  function resolveDeviceTarget(vars, name) {
35715
36028
  const raw = vars[name];
@@ -35771,19 +36084,36 @@ async function runForDevices(deviceIds, scope, work, concurrency = 4) {
35771
36084
  * variables. Variables are substituted per step, at the moment it runs, so a
35772
36085
  * missing one fails THAT step (traced) and leaves the later ones not-run.
35773
36086
  */
36087
+ /** The guard and the else list of a step, bound to the run (#472); `{}` for an unguarded step. */
36088
+ function guardOf(step, vars, deps) {
36089
+ const when = step.if;
36090
+ if (when === void 0) return {};
36091
+ const evaluate = deps.evaluateCondition;
36092
+ return {
36093
+ guard: async () => evaluate === void 0 ? {
36094
+ result: "unknown",
36095
+ reason: "this consumer has no condition evaluator"
36096
+ } : evaluate(when),
36097
+ ...step.else === void 0 ? {} : { otherwise: buildActionSteps(step.else, vars, deps) }
36098
+ };
36099
+ }
35774
36100
  function buildActionSteps(steps, vars, deps) {
35775
36101
  return steps.map((step) => {
36102
+ const guarded = guardOf(step, vars, deps);
35776
36103
  const meta = stepMetaOfAction(step);
35777
36104
  if (step.kind === "wait") return {
35778
36105
  meta,
36106
+ ...guarded,
35779
36107
  run: () => deps.sleep(step.seconds * 1e3)
35780
36108
  };
35781
36109
  const normalized = normalizeCapStep(step);
35782
36110
  return {
35783
36111
  meta,
36112
+ ...guarded,
35784
36113
  run: async (scope) => {
35785
- const resolved = resolveStepArgs(step.args ?? {}, vars, deps.onMissingVar);
35786
- const args = isPlainRecord(resolved) ? resolved : {};
36114
+ const templated = await resolveStepArgsWithTemplates(step.args ?? {}, vars, deps.onMissingVar, deps.renderTemplates);
36115
+ if (templated.notes.length > 0) scope.setTemplateNotes(templated.notes);
36116
+ const args = isPlainRecord(templated.value) ? templated.value : {};
35787
36117
  const target = await deps.resolveTarget(normalized.target, normalized.actionId, vars, {
35788
36118
  actionId: normalized.actionId,
35789
36119
  owner: deps.owner
@@ -49331,6 +49661,169 @@ function checkDeviceAlias(alias, isTaken) {
49331
49661
  };
49332
49662
  }
49333
49663
  //#endregion
49664
+ //#region src/expression/device-template.ts
49665
+ /**
49666
+ * Device value templates, the parts that need no template engine (D1021).
49667
+ *
49668
+ * A template is plain text with Jinja-style `{{ … }}` / `{% … %}` blocks:
49669
+ * `{{ stufa_veranda.temperature | unit('°F') | round(1) }}`. Devices are named
49670
+ * by their alias (`device-alias.ts`); a field is `alias.field` when the field
49671
+ * name is unique across the device's capabilities, else `alias.<cap>.field`,
49672
+ * and an ambiguous `alias.field` is refused by name.
49673
+ *
49674
+ * The engine itself (nunjucks) lives ONLY in the hub's renderer
49675
+ * (`packages/system/src/builtins/device-manager/device-template/`, guard
49676
+ * `check-device-template-grammar`): it does not sandbox, so it renders only in
49677
+ * a worker thread under a wall-time budget, over frozen plain data. This file
49678
+ * is the shared vocabulary — limits, refusal reasons, the trace, and how a
49679
+ * `(alias, path)` reference resolves against a device's slices.
49680
+ */
49681
+ var DEVICE_TEMPLATE_MAX_LENGTH = 4096;
49682
+ /** Wall time a render may take, host-measured; the worker is terminated past it. */
49683
+ var DEVICE_TEMPLATE_BUDGET_MS = 50;
49684
+ var DEVICE_TEMPLATE_MAX_OUTPUT = 4096;
49685
+ /** What an unknown or unavailable value renders as. */
49686
+ var DEVICE_TEMPLATE_UNAVAILABLE = "—";
49687
+ var DeviceTemplateSchema = zod.z.string().min(1).max(DEVICE_TEMPLATE_MAX_LENGTH);
49688
+ /** The filters a template may use. Anything else is refused at parse time. */
49689
+ var DEVICE_TEMPLATE_FILTERS = [
49690
+ "unit",
49691
+ "round",
49692
+ "default",
49693
+ "since",
49694
+ "ago",
49695
+ "format",
49696
+ "upper",
49697
+ "lower",
49698
+ "title",
49699
+ "capitalize",
49700
+ "trim",
49701
+ "abs",
49702
+ "int",
49703
+ "float",
49704
+ "length",
49705
+ "d",
49706
+ "join",
49707
+ "replace",
49708
+ "first",
49709
+ "last",
49710
+ "sort",
49711
+ "reverse",
49712
+ "sum",
49713
+ "string",
49714
+ "list",
49715
+ "truncate"
49716
+ ];
49717
+ var DEVICE_TEMPLATE_REFUSAL_REASONS = [
49718
+ "too-long",
49719
+ "syntax",
49720
+ "forbidden-syntax",
49721
+ "forbidden-member",
49722
+ "unknown-filter",
49723
+ "ambiguous-field",
49724
+ "busy",
49725
+ "budget-exceeded",
49726
+ "timeout",
49727
+ "output-too-large",
49728
+ "render-failed",
49729
+ "out-of-scope",
49730
+ "unavailable"
49731
+ ];
49732
+ var DeviceTemplateRefusalSchema = zod.z.object({
49733
+ reason: zod.z.enum(DEVICE_TEMPLATE_REFUSAL_REASONS),
49734
+ message: zod.z.string()
49735
+ });
49736
+ var DEVICE_TEMPLATE_TRACE_REASONS = [
49737
+ "unknown-alias",
49738
+ "unknown-field",
49739
+ "no-field",
49740
+ "unavailable"
49741
+ ];
49742
+ var DeviceTemplateTraceEntrySchema = zod.z.object({
49743
+ ref: zod.z.string(),
49744
+ reason: zod.z.enum(DEVICE_TEMPLATE_TRACE_REASONS)
49745
+ });
49746
+ var DeviceTemplateRenderSchema = zod.z.discriminatedUnion("ok", [zod.z.object({
49747
+ ok: zod.z.literal(true),
49748
+ text: zod.z.string(),
49749
+ trace: zod.z.array(DeviceTemplateTraceEntrySchema)
49750
+ }), zod.z.object({
49751
+ ok: zod.z.literal(false),
49752
+ refusal: DeviceTemplateRefusalSchema,
49753
+ trace: zod.z.array(DeviceTemplateTraceEntrySchema)
49754
+ })]);
49755
+ /** A capability name as a template spells it: `temperature-sensor` → `temperature_sensor`. */
49756
+ function templateCapKey(cap) {
49757
+ return cap.replace(/-/g, "_");
49758
+ }
49759
+ function isRecord$3(value) {
49760
+ return typeof value === "object" && value !== null && !Array.isArray(value);
49761
+ }
49762
+ function pickPath(root, path) {
49763
+ let cursor = root;
49764
+ for (const part of path) if (Array.isArray(cursor) && typeof part === "number") cursor = cursor[part];
49765
+ else if (isRecord$3(cursor) && Object.hasOwn(cursor, String(part))) cursor = cursor[String(part)];
49766
+ else return;
49767
+ return cursor;
49768
+ }
49769
+ /**
49770
+ * Resolve the path after an alias. `<cap>.field…` when the first segment names
49771
+ * one of the device's caps; otherwise `field…` when exactly one cap carries a
49772
+ * field of that name; several caps carrying it is `ambiguous`, naming them.
49773
+ */
49774
+ function resolveTemplateRef(view, path) {
49775
+ const head = path[0];
49776
+ if (head === void 0) return {
49777
+ kind: "missing",
49778
+ reason: "no-field"
49779
+ };
49780
+ const caps = Object.keys(view.slices);
49781
+ const named = caps.find((cap) => cap === head || templateCapKey(cap) === head);
49782
+ if (named !== void 0) {
49783
+ const rest = path.slice(1);
49784
+ if (rest.length === 0) return {
49785
+ kind: "missing",
49786
+ reason: "no-field"
49787
+ };
49788
+ const value = pickPath(view.slices[named], rest);
49789
+ if (value === void 0) return {
49790
+ kind: "missing",
49791
+ reason: "unknown-field"
49792
+ };
49793
+ return {
49794
+ kind: "value",
49795
+ cap: named,
49796
+ fieldPath: rest,
49797
+ value
49798
+ };
49799
+ }
49800
+ const owners = caps.filter((cap) => {
49801
+ const slice = view.slices[cap];
49802
+ return isRecord$3(slice) && Object.hasOwn(slice, String(head));
49803
+ });
49804
+ if (owners.length === 0) return {
49805
+ kind: "missing",
49806
+ reason: "unknown-field"
49807
+ };
49808
+ const [only] = owners;
49809
+ if (owners.length > 1 || only === void 0) return {
49810
+ kind: "ambiguous",
49811
+ field: String(head),
49812
+ caps: owners
49813
+ };
49814
+ const value = pickPath(view.slices[only], path);
49815
+ if (value === void 0) return {
49816
+ kind: "missing",
49817
+ reason: "unknown-field"
49818
+ };
49819
+ return {
49820
+ kind: "value",
49821
+ cap: only,
49822
+ fieldPath: path,
49823
+ value
49824
+ };
49825
+ }
49826
+ //#endregion
49334
49827
  //#region src/device/site-zone.ts
49335
49828
  /**
49336
49829
  * A SITE ZONE — a named part of the property that several locations belong to.
@@ -50260,6 +50753,38 @@ var deviceManagerCapability = {
50260
50753
  kind: "mutation",
50261
50754
  auth: "admin"
50262
50755
  }),
50756
+ /**
50757
+ * Render device value templates (D1021). The ONE door every consumer uses:
50758
+ * an action step, a scheduler point, a notification rule, a generated
50759
+ * automation block. Admin-only (an in-process block carries the mesh
50760
+ * principal): it reads device state by alias, so a non-admin never calls it
50761
+ * directly. `allowedDeviceIds` is the set the END caller was proven to see;
50762
+ * a template naming another device answers `out-of-scope`. Answers are
50763
+ * index-aligned with `templates`.
50764
+ */
50765
+ renderDeviceTemplates: require_sleep.method(zod.z.object({
50766
+ templates: zod.z.array(DeviceTemplateSchema).max(64),
50767
+ allowedDeviceIds: zod.z.array(zod.z.number().int()).optional()
50768
+ }), zod.z.object({ results: zod.z.array(DeviceTemplateRenderSchema) }), { auth: "admin" }),
50769
+ /**
50770
+ * Vet templates without rendering them: the syntax refusal, or the devices
50771
+ * each names and whether `allowedDeviceIds` covers them. The save door and
50772
+ * the run-time scope check both ask this.
50773
+ */
50774
+ checkDeviceTemplates: require_sleep.method(zod.z.object({
50775
+ templates: zod.z.array(zod.z.string()).max(64),
50776
+ allowedDeviceIds: zod.z.array(zod.z.number().int()).optional()
50777
+ }), zod.z.object({ results: zod.z.array(zod.z.discriminatedUnion("ok", [zod.z.object({
50778
+ ok: zod.z.literal(true),
50779
+ aliases: zod.z.array(zod.z.object({
50780
+ alias: zod.z.string(),
50781
+ deviceId: zod.z.number().int().nullable(),
50782
+ allowed: zod.z.boolean()
50783
+ }))
50784
+ }), zod.z.object({
50785
+ ok: zod.z.literal(false),
50786
+ refusal: DeviceTemplateRefusalSchema
50787
+ })])) }), { auth: "admin" }),
50263
50788
  /** Update the operator-organisational location label. `null`
50264
50789
  * clears it. */
50265
50790
  setLocation: require_sleep.method(zod.z.object({
@@ -55397,6 +55922,17 @@ var TIMED_RUN_DEVICE_TYPES = [require_device_type.DeviceType.Heater, require_dev
55397
55922
  function timedRunLimitOf(deviceType) {
55398
55923
  return TIMED_RUN_LIMITS[deviceType] ?? null;
55399
55924
  }
55925
+ var MS_PER_SECOND = 1e3;
55926
+ var MS_PER_MINUTE = 6e4;
55927
+ /**
55928
+ * Whole units left on an armed run. Minutes and seconds both ceil, and a run
55929
+ * that has not expired yet never reads as zero.
55930
+ */
55931
+ function timedRunRemaining(activeUntil, now, unit) {
55932
+ const left = activeUntil - now;
55933
+ if (left <= 0) return 0;
55934
+ return Math.max(1, Math.ceil(left / (unit === "min" ? MS_PER_MINUTE : MS_PER_SECOND)));
55935
+ }
55400
55936
  /** Seconds in a duration of `duration` `unit`. */
55401
55937
  function timedRunSeconds(duration, unit) {
55402
55938
  return unit === "min" ? duration * 60 : duration;
@@ -56049,7 +56585,13 @@ var HeroTimedRunSlotSchema = zod.z.object({
56049
56585
  activeUntil: zod.z.number().nullable(),
56050
56586
  quickRun: TimedRunQuickRunSchema,
56051
56587
  run: HeroActionSchema,
56052
- cancel: HeroActionSchema
56588
+ cancel: HeroActionSchema,
56589
+ /**
56590
+ * Whole units left (the limit's unit, ceil). `null` while nothing is armed.
56591
+ * A number, not words: the row formats it, and a text here would not fit the
56592
+ * hero-layout declaration.
56593
+ */
56594
+ remaining: zod.z.number().nullable()
56053
56595
  });
56054
56596
  var HeroPowerSupplySlotSchema = zod.z.object({
56055
56597
  /** The plug's state; `null` = unknown, never off. */
@@ -56170,18 +56712,31 @@ var HeroModelSchema = zod.z.object({
56170
56712
  * 4. a trailing fact (power, else battery, else consumables).
56171
56713
  *
56172
56714
  * Selection rules, all taken from the model:
56173
- * - ONE control is ever shown: the device's own power; else the FIRST control of
56715
+ * - the primary control is the device's own power; else the FIRST control of
56174
56716
  * the FIRST row that has any (a later row's control is never promoted). When
56175
56717
  * the model lists that part in `gated`, the row has no inline control: the
56176
56718
  * projection never falls through to another control the caller could use.
56719
+ * - a timed run, when the model carries the slot, sits beside that primary:
56720
+ * Run while idle, Stop while armed. Gating the slot hides the control.
56177
56721
  * - the status line is the head (what plays, else the state) plus at most
56178
- * {@link ROW_STATUS_FACTS_MAX} facts, the trailing fact excluded;
56722
+ * {@link ROW_STATUS_FACTS_MAX} facts, the trailing fact excluded, then the
56723
+ * time left on an armed timed run;
56179
56724
  * - the trailing fact is the first of power, battery, consumables.
56180
56725
  *
56181
56726
  * `projectDeviceRow` is pure and computes nothing: it selects from a
56182
56727
  * {@link HeroModel}. A row that needed a value the hero lacks would mean the
56183
56728
  * model is missing it, so the fix goes in the model.
56184
56729
  */
56730
+ /**
56731
+ * The row's timed-run control. `id` is `timed-run.run` while idle and
56732
+ * `timed-run.cancel` while armed; `duration` and `unit` are the one-tap run
56733
+ * a Run press starts.
56734
+ */
56735
+ var HeroRowTimedRunSchema = zod.z.object({
56736
+ id: zod.z.enum(["timed-run.run", "timed-run.cancel"]),
56737
+ duration: zod.z.number(),
56738
+ unit: zod.z.enum(["min", "s"])
56739
+ });
56185
56740
  var HeroRowModelSchema = zod.z.object({
56186
56741
  deviceId: zod.z.number().int(),
56187
56742
  name: zod.z.string(),
@@ -56194,6 +56749,11 @@ var HeroRowModelSchema = zod.z.object({
56194
56749
  statusLine: zod.z.array(HeroTextSchema),
56195
56750
  /** `null` = the type has no inline control, or the caller may not act on it. */
56196
56751
  primary: HeroControlSchema.nullable(),
56752
+ /**
56753
+ * Beside `primary` when the device offers a timed run: Run while idle, Stop
56754
+ * while armed. `null` when there is no slot, or the caller may not act.
56755
+ */
56756
+ timedRun: HeroRowTimedRunSchema.nullable(),
56197
56757
  trailing: HeroFactSchema.nullable()
56198
56758
  });
56199
56759
  /** The trailing fact, in order of preference. */
@@ -56230,7 +56790,30 @@ function primaryOf(model) {
56230
56790
  return null;
56231
56791
  }
56232
56792
  function statusLineOf(model, trailing) {
56233
- return [model.rows.find((r) => r.id === "now-playing")?.status ?? null ?? model.title, ...model.facts.filter((f) => f !== trailing).map((f) => f.text).slice(0, 3)];
56793
+ const head = model.rows.find((r) => r.id === "now-playing")?.status ?? null ?? model.title;
56794
+ const rest = model.facts.filter((f) => f !== trailing).map((f) => f.text).slice(0, 3);
56795
+ const slot = model.timedRun;
56796
+ if (slot === null || slot.remaining === null) return [head, ...rest];
56797
+ const word = slot.quickRun.unit === "min" ? "min" : "s";
56798
+ const left = {
56799
+ en: `${slot.remaining} ${word}`,
56800
+ it: `${slot.remaining} ${word}`
56801
+ };
56802
+ return [
56803
+ head,
56804
+ ...rest,
56805
+ left
56806
+ ];
56807
+ }
56808
+ /** Run while the slot is idle, Stop while it is armed. Hidden when the caller may not act. */
56809
+ function timedRunOf(model) {
56810
+ const slot = model.timedRun;
56811
+ if (slot === null || model.gated.includes("timed-run")) return null;
56812
+ return {
56813
+ id: slot.activeUntil === null ? "timed-run.run" : "timed-run.cancel",
56814
+ duration: slot.quickRun.duration,
56815
+ unit: slot.quickRun.unit
56816
+ };
56234
56817
  }
56235
56818
  function projectDeviceRow(model) {
56236
56819
  const trailing = trailingOf(model.facts);
@@ -56244,6 +56827,7 @@ function projectDeviceRow(model) {
56244
56827
  scene: model.scene,
56245
56828
  statusLine: statusLineOf(model, trailing),
56246
56829
  primary: primaryOf(model),
56830
+ timedRun: timedRunOf(model),
56247
56831
  trailing
56248
56832
  };
56249
56833
  }
@@ -91228,7 +91812,7 @@ var ALL_CAPABILITY_DEFINITIONS = [
91228
91812
  * step appears (an automation's actions, an action's steps, a scheduler
91229
91813
  * point's steps), and leaves everything else untouched.
91230
91814
  */
91231
- function isRecord$3(value) {
91815
+ function isRecord$2(value) {
91232
91816
  return typeof value === "object" && value !== null && !Array.isArray(value);
91233
91817
  }
91234
91818
  function expandStep(step) {
@@ -91236,7 +91820,7 @@ function expandStep(step) {
91236
91820
  if (step["kind"] !== "cap" || typeof actionId !== "string") return step;
91237
91821
  const found = require_sleep.findVocabAction(actionId);
91238
91822
  if (found === void 0) return step;
91239
- const given = isRecord$3(step["args"]) ? step["args"] : {};
91823
+ const given = isRecord$2(step["args"]) ? step["args"] : {};
91240
91824
  const args = {
91241
91825
  ...found.action.args,
91242
91826
  ...given
@@ -91250,7 +91834,7 @@ function expandStep(step) {
91250
91834
  }
91251
91835
  function expandDraft(value) {
91252
91836
  if (Array.isArray(value)) return value.map(expandDraft);
91253
- if (!isRecord$3(value)) return value;
91837
+ if (!isRecord$2(value)) return value;
91254
91838
  return expandStep(Object.fromEntries(Object.entries(value).map(([k, v]) => [k, expandDraft(v)])));
91255
91839
  }
91256
91840
  //#endregion
@@ -91337,7 +91921,7 @@ function normalise(kind, json) {
91337
91921
  /** A stable string for ordering a set's elements. */
91338
91922
  function keyOf(value) {
91339
91923
  if (Array.isArray(value)) return `[${value.map(keyOf).join(",")}]`;
91340
- if (isRecord$3(value)) return `{${Object.keys(value).filter((k) => !IGNORED_KEYS.has(k)).toSorted().map((k) => `${k}:${keyOf(value[k])}`).join(",")}}`;
91924
+ if (isRecord$2(value)) return `{${Object.keys(value).filter((k) => !IGNORED_KEYS.has(k)).toSorted().map((k) => `${k}:${keyOf(value[k])}`).join(",")}}`;
91341
91925
  if (typeof value === "string") return JSON.stringify(value.trim().toLowerCase());
91342
91926
  if (typeof value === "number") return String(Math.round(value * DECIMALS) / DECIMALS);
91343
91927
  return JSON.stringify(value) ?? "undefined";
@@ -91414,7 +91998,7 @@ function score(a, b, key) {
91414
91998
  misses: missOf(key)
91415
91999
  };
91416
92000
  if (Array.isArray(a) && Array.isArray(b)) return SET_KEYS.has(key) ? setScore(a, b, key) : orderedScore(a, b, key);
91417
- if (isRecord$3(a) && isRecord$3(b)) return objectScore(a, b);
92001
+ if (isRecord$2(a) && isRecord$2(b)) return objectScore(a, b);
91418
92002
  return keyOf(a) === keyOf(b) ? SAME : {
91419
92003
  score: 0,
91420
92004
  misses: missOf(key)
@@ -92463,7 +93047,7 @@ function validateCompositionDraft(site, json) {
92463
93047
  };
92464
93048
  }
92465
93049
  function validateDraft(kind, json, site) {
92466
- if (!isRecord$3(json)) return {
93050
+ if (!isRecord$2(json)) return {
92467
93051
  ok: false,
92468
93052
  issues: ["(root): the draft must be one JSON object"]
92469
93053
  };
@@ -103250,10 +103834,14 @@ function timerTile(quickRun) {
103250
103834
  value: require_sleep.t(text, text)
103251
103835
  };
103252
103836
  }
103837
+ function remainingWords(amount, unit) {
103838
+ const word = unit === "min" ? "min" : "s";
103839
+ return require_sleep.t(`${amount} ${word}`, `${amount} ${word}`);
103840
+ }
103253
103841
  var timedRunContribution = contribution("timed-run", TimedRunStatusSchema, (slice, ctx) => {
103254
103842
  const type = deviceTypeOf(ctx.type);
103255
- const limit = type === void 0 ? void 0 : TIMED_RUN_LIMITS[type];
103256
- if (limit === void 0) return {};
103843
+ const limit = type === void 0 ? null : timedRunLimitOf(type);
103844
+ if (limit === null) return {};
103257
103845
  const quickRun = slice?.quickRun ?? timedRunQuickRun(limit, null);
103258
103846
  const activeUntil = slice?.activeUntil != null && slice.activeUntil > ctx.now ? slice.activeUntil : null;
103259
103847
  const runArgs = {
@@ -103263,11 +103851,12 @@ var timedRunContribution = contribution("timed-run", TimedRunStatusSchema, (slic
103263
103851
  const run = action("timed-run.run", require_sleep.t(`Run ${quickRun.duration} ${quickRun.unit}`, `Avvia ${quickRun.duration} ${quickRun.unit}`), "timer", "timed-run", "runFor", runArgs, "primary");
103264
103852
  const cancel = action("timed-run.cancel", require_sleep.t("Stop", "Ferma"), "timer-off", "timed-run", "cancel");
103265
103853
  const restart = action("timed-run.restart", require_sleep.t("Restart", "Riavvia"), "rotate-cw", "timed-run", "runFor", runArgs);
103266
- const left = activeUntil === null ? 0 : Math.max(1, Math.ceil((activeUntil - ctx.now) / 6e4));
103854
+ const remaining = activeUntil === null ? null : timedRunRemaining(activeUntil, ctx.now, quickRun.unit);
103855
+ const words = remaining === null ? null : remainingWords(remaining, quickRun.unit);
103267
103856
  const row = {
103268
103857
  id: "run-for",
103269
103858
  icon: "timer",
103270
- status: activeUntil === null ? require_sleep.t(`Run for ${quickRun.duration} ${quickRun.unit}`, `Avvia per ${quickRun.duration} ${quickRun.unit}`) : require_sleep.t(`Stops in ${left} min`, `Si ferma tra ${left} min`),
103859
+ status: words === null ? require_sleep.t(`Run for ${quickRun.duration} ${quickRun.unit}`, `Avvia per ${quickRun.duration} ${quickRun.unit}`) : require_sleep.t(`Stops in ${words.en}`, `Si ferma tra ${words.it}`),
103271
103860
  controls: activeUntil === null ? [asAction(run)] : [asAction(cancel), asAction(restart)]
103272
103861
  };
103273
103862
  const armed = activeUntil === null ? {} : { right: [timerTile(quickRun)] };
@@ -103276,7 +103865,8 @@ var timedRunContribution = contribution("timed-run", TimedRunStatusSchema, (slic
103276
103865
  activeUntil,
103277
103866
  quickRun,
103278
103867
  run,
103279
- cancel
103868
+ cancel,
103869
+ remaining
103280
103870
  },
103281
103871
  rows: [row],
103282
103872
  tilesFallback: true,
@@ -107078,6 +107668,13 @@ var METHOD_ACCESS_MAP = Object.freeze({
107078
107668
  access: "create",
107079
107669
  role: "admin"
107080
107670
  },
107671
+ "deviceManager.checkDeviceTemplates": {
107672
+ capName: "device-manager",
107673
+ capScope: "system",
107674
+ addonId: null,
107675
+ access: "view",
107676
+ role: "admin"
107677
+ },
107081
107678
  "deviceManager.cleanupDeletedDevicesData": {
107082
107679
  capName: "device-manager",
107083
107680
  capScope: "system",
@@ -107477,6 +108074,13 @@ var METHOD_ACCESS_MAP = Object.freeze({
107477
108074
  access: "create",
107478
108075
  role: "admin"
107479
108076
  },
108077
+ "deviceManager.renderDeviceTemplates": {
108078
+ capName: "device-manager",
108079
+ capScope: "system",
108080
+ addonId: null,
108081
+ access: "view",
108082
+ role: "admin"
108083
+ },
107480
108084
  "deviceManager.reportDiscoveryObservations": {
107481
108085
  capName: "device-manager",
107482
108086
  capScope: "system",
@@ -116352,7 +116956,7 @@ function applianceExport(ecosystem, deviceType) {
116352
116956
  //#endregion
116353
116957
  //#region src/device/path-util.ts
116354
116958
  /** Returns true when `x` is a non-null, non-array plain object. */
116355
- function isRecord$2(x) {
116959
+ function isRecord$1(x) {
116356
116960
  return x !== null && typeof x === "object" && !Array.isArray(x);
116357
116961
  }
116358
116962
  /** Read a dot-path (`a.b.c`) out of an object. Returns `undefined` for any
@@ -116361,7 +116965,7 @@ function getByPath(obj, path) {
116361
116965
  const parts = path.split(".");
116362
116966
  let cur = obj;
116363
116967
  for (const part of parts) {
116364
- if (!isRecord$2(cur)) return void 0;
116968
+ if (!isRecord$1(cur)) return void 0;
116365
116969
  cur = cur[part];
116366
116970
  }
116367
116971
  return cur;
@@ -116383,7 +116987,7 @@ function setByPath(obj, path, value) {
116383
116987
  const head = path.slice(0, dotIndex);
116384
116988
  const tail = path.slice(dotIndex + 1);
116385
116989
  const child = obj[head];
116386
- const childObj = isRecord$2(child) ? child : {};
116990
+ const childObj = isRecord$1(child) ? child : {};
116387
116991
  return {
116388
116992
  ...obj,
116389
116993
  [head]: setByPath(childObj, tail, value)
@@ -117436,131 +118040,6 @@ function humanizeKey(key) {
117436
118040
  return key.replace(/([A-Z])/g, " $1").replace(/[_-]/g, " ").replace(/^\w/, (c) => c.toUpperCase()).trim();
117437
118041
  }
117438
118042
  //#endregion
117439
- //#region src/expression/device-template.ts
117440
- /**
117441
- * Device value templates, the parts that need no template engine (D1021).
117442
- *
117443
- * A template is plain text with Jinja-style `{{ … }}` / `{% … %}` blocks:
117444
- * `{{ stufa_veranda.temperature | unit('°F') | round(1) }}`. Devices are named
117445
- * by their alias (`device-alias.ts`); a field is `alias.field` when the field
117446
- * name is unique across the device's capabilities, else `alias.<cap>.field`,
117447
- * and an ambiguous `alias.field` is refused by name.
117448
- *
117449
- * The engine itself (nunjucks) lives ONLY in the hub's renderer
117450
- * (`packages/system/src/builtins/device-manager/device-template/`, guard
117451
- * `check-device-template-grammar`): it does not sandbox, so it renders only in
117452
- * a worker thread under a wall-time budget, over frozen plain data. This file
117453
- * is the shared vocabulary — limits, refusal reasons, the trace, and how a
117454
- * `(alias, path)` reference resolves against a device's slices.
117455
- */
117456
- var DEVICE_TEMPLATE_MAX_LENGTH = 4096;
117457
- /** Wall time a render may take, host-measured; the worker is terminated past it. */
117458
- var DEVICE_TEMPLATE_BUDGET_MS = 50;
117459
- var DEVICE_TEMPLATE_MAX_OUTPUT = 4096;
117460
- /** What an unknown or unavailable value renders as. */
117461
- var DEVICE_TEMPLATE_UNAVAILABLE = "—";
117462
- var DeviceTemplateSchema = zod.z.string().min(1).max(DEVICE_TEMPLATE_MAX_LENGTH);
117463
- /** The filters a template may use. Anything else is refused at parse time. */
117464
- var DEVICE_TEMPLATE_FILTERS = [
117465
- "unit",
117466
- "round",
117467
- "default",
117468
- "since",
117469
- "ago",
117470
- "format",
117471
- "upper",
117472
- "lower",
117473
- "title",
117474
- "capitalize",
117475
- "trim",
117476
- "abs",
117477
- "int",
117478
- "float",
117479
- "length",
117480
- "d",
117481
- "join",
117482
- "replace",
117483
- "first",
117484
- "last",
117485
- "sort",
117486
- "reverse",
117487
- "sum",
117488
- "string",
117489
- "list",
117490
- "truncate"
117491
- ];
117492
- /** A capability name as a template spells it: `temperature-sensor` → `temperature_sensor`. */
117493
- function templateCapKey(cap) {
117494
- return cap.replace(/-/g, "_");
117495
- }
117496
- function isRecord$1(value) {
117497
- return typeof value === "object" && value !== null && !Array.isArray(value);
117498
- }
117499
- function pickPath(root, path) {
117500
- let cursor = root;
117501
- for (const part of path) if (Array.isArray(cursor) && typeof part === "number") cursor = cursor[part];
117502
- else if (isRecord$1(cursor) && Object.hasOwn(cursor, String(part))) cursor = cursor[String(part)];
117503
- else return;
117504
- return cursor;
117505
- }
117506
- /**
117507
- * Resolve the path after an alias. `<cap>.field…` when the first segment names
117508
- * one of the device's caps; otherwise `field…` when exactly one cap carries a
117509
- * field of that name; several caps carrying it is `ambiguous`, naming them.
117510
- */
117511
- function resolveTemplateRef(view, path) {
117512
- const head = path[0];
117513
- if (head === void 0) return {
117514
- kind: "missing",
117515
- reason: "no-field"
117516
- };
117517
- const caps = Object.keys(view.slices);
117518
- const named = caps.find((cap) => cap === head || templateCapKey(cap) === head);
117519
- if (named !== void 0) {
117520
- const rest = path.slice(1);
117521
- if (rest.length === 0) return {
117522
- kind: "missing",
117523
- reason: "no-field"
117524
- };
117525
- const value = pickPath(view.slices[named], rest);
117526
- if (value === void 0) return {
117527
- kind: "missing",
117528
- reason: "unknown-field"
117529
- };
117530
- return {
117531
- kind: "value",
117532
- cap: named,
117533
- fieldPath: rest,
117534
- value
117535
- };
117536
- }
117537
- const owners = caps.filter((cap) => {
117538
- const slice = view.slices[cap];
117539
- return isRecord$1(slice) && Object.hasOwn(slice, String(head));
117540
- });
117541
- if (owners.length === 0) return {
117542
- kind: "missing",
117543
- reason: "unknown-field"
117544
- };
117545
- const [only] = owners;
117546
- if (owners.length > 1 || only === void 0) return {
117547
- kind: "ambiguous",
117548
- field: String(head),
117549
- caps: owners
117550
- };
117551
- const value = pickPath(view.slices[only], path);
117552
- if (value === void 0) return {
117553
- kind: "missing",
117554
- reason: "unknown-field"
117555
- };
117556
- return {
117557
- kind: "value",
117558
- cap: only,
117559
- fieldPath: path,
117560
- value
117561
- };
117562
- }
117563
- //#endregion
117564
118043
  //#region src/generated/cap-status-types.ts
117565
118044
  /**
117566
118045
  * Runtime list of cap names with status. Used by the settings
@@ -122162,6 +122641,8 @@ function createSystemProxy(api) {
122162
122641
  registerDevice: (input) => dispatch("deviceManager", "registerDevice", "mutation", input),
122163
122642
  removeDevice: (input) => dispatch("deviceManager", "removeDevice", "mutation", input),
122164
122643
  persistConfig: (input) => dispatch("deviceManager", "persistConfig", "mutation", input),
122644
+ renderDeviceTemplates: (input) => dispatch("deviceManager", "renderDeviceTemplates", "query", input),
122645
+ checkDeviceTemplates: (input) => dispatch("deviceManager", "checkDeviceTemplates", "query", input),
122165
122646
  getRoleDisplayDefaults: (input) => dispatch("deviceManager", "getRoleDisplayDefaults", "query", input),
122166
122647
  setRoleDisplayDefaults: (input) => dispatch("deviceManager", "setRoleDisplayDefaults", "mutation", input),
122167
122648
  listLocations: (input) => dispatch("deviceManager", "listLocations", "query", input),
@@ -135010,6 +135491,8 @@ exports.DEVICE_TEMPLATE_BUDGET_MS = DEVICE_TEMPLATE_BUDGET_MS;
135010
135491
  exports.DEVICE_TEMPLATE_FILTERS = DEVICE_TEMPLATE_FILTERS;
135011
135492
  exports.DEVICE_TEMPLATE_MAX_LENGTH = DEVICE_TEMPLATE_MAX_LENGTH;
135012
135493
  exports.DEVICE_TEMPLATE_MAX_OUTPUT = DEVICE_TEMPLATE_MAX_OUTPUT;
135494
+ exports.DEVICE_TEMPLATE_REFUSAL_REASONS = DEVICE_TEMPLATE_REFUSAL_REASONS;
135495
+ exports.DEVICE_TEMPLATE_TRACE_REASONS = DEVICE_TEMPLATE_TRACE_REASONS;
135013
135496
  exports.DEVICE_TEMPLATE_UNAVAILABLE = DEVICE_TEMPLATE_UNAVAILABLE;
135014
135497
  exports.DEVICE_TOMBSTONE_RETENTION_MS = DEVICE_TOMBSTONE_RETENTION_MS;
135015
135498
  exports.DEVICE_TRANSITIONS_MAX_PAGE = DEVICE_TRANSITIONS_MAX_PAGE;
@@ -135101,7 +135584,10 @@ exports.DeviceRuntimeState = DeviceRuntimeState;
135101
135584
  exports.DeviceSelectorSchema = DeviceSelectorSchema;
135102
135585
  exports.DeviceSignaturePurposeSchema = DeviceSignaturePurposeSchema;
135103
135586
  exports.DeviceStatusSchema = DeviceStatusSchema;
135587
+ exports.DeviceTemplateRefusalSchema = DeviceTemplateRefusalSchema;
135588
+ exports.DeviceTemplateRenderSchema = DeviceTemplateRenderSchema;
135104
135589
  exports.DeviceTemplateSchema = DeviceTemplateSchema;
135590
+ exports.DeviceTemplateTraceEntrySchema = DeviceTemplateTraceEntrySchema;
135105
135591
  exports.DeviceTombstoneSchema = DeviceTombstoneSchema;
135106
135592
  exports.DeviceTransitionSchema = require_sleep.DeviceTransitionSchema;
135107
135593
  exports.DeviceType = require_device_type.DeviceType;
@@ -136604,6 +137090,7 @@ exports.StationarySubjectSchema = StationarySubjectSchema;
136604
137090
  exports.StatisticHelperSpecSchema = require_composition.StatisticHelperSpecSchema;
136605
137091
  exports.StatisticWindowSchema = require_composition.StatisticWindowSchema;
136606
137092
  exports.StepDeviceTraceSchema = StepDeviceTraceSchema;
137093
+ exports.StepTemplateError = StepTemplateError;
136607
137094
  exports.StorageAbortUploadInputSchema = AbortUploadInputSchema;
136608
137095
  exports.StorageAccessSchema = StorageAccessSchema;
136609
137096
  exports.StorageBeginDownloadInputSchema = BeginDownloadInputSchema;
@@ -137053,6 +137540,7 @@ exports.capabilityScopesOf = capabilityScopesOf;
137053
137540
  exports.capacityForModel = capacityForModel;
137054
137541
  exports.capacitySessionsOf = capacitySessionsOf;
137055
137542
  exports.carbonMonoxideCapability = carbonMonoxideCapability;
137543
+ exports.carriesDeviceTemplate = carriesDeviceTemplate;
137056
137544
  exports.catalogueIssues = catalogueIssues;
137057
137545
  exports.cellsToRects = cellsToRects;
137058
137546
  exports.checkDeviceAlias = checkDeviceAlias;
@@ -137086,6 +137574,7 @@ exports.clusterModelSettingKey = clusterModelSettingKey;
137086
137574
  exports.clusterStepSettingFieldsFor = clusterStepSettingFieldsFor;
137087
137575
  exports.clusterStepSettingKey = clusterStepSettingKey;
137088
137576
  exports.codecIsAccepted = codecIsAccepted;
137577
+ exports.collectDeviceTemplates = collectDeviceTemplates;
137089
137578
  exports.collectHydratedFieldEntries = require_sleep.collectHydratedFieldEntries;
137090
137579
  exports.collectHydratedFieldValues = require_sleep.collectHydratedFieldValues;
137091
137580
  exports.collectKeychainStoredKeys = require_sleep.collectKeychainStoredKeys;
@@ -137318,6 +137807,7 @@ exports.evaluateSensorLevelEdge = require_composition.evaluateSensorLevelEdge;
137318
137807
  exports.evaluateStatefulExpressionCall = require_composition.evaluateStatefulExpressionCall;
137319
137808
  exports.evaluateStationaryTrigger = evaluateStationaryTrigger;
137320
137809
  exports.evaluateStatistic = require_composition.evaluateStatistic;
137810
+ exports.evaluateStepCondition = evaluateStepCondition;
137321
137811
  exports.evaluateWhenTree = evaluateWhenTree;
137322
137812
  exports.evaluateZoneRules = evaluateZoneRules;
137323
137813
  exports.event = require_sleep.event;
@@ -137962,6 +138452,7 @@ exports.resolveSecretMarkers = require_sleep.resolveSecretMarkers;
137962
138452
  exports.resolveSecretViewsIn = require_sleep.resolveSecretViewsIn;
137963
138453
  exports.resolveServerName = resolveServerName;
137964
138454
  exports.resolveStepArgs = resolveStepArgs;
138455
+ exports.resolveStepArgsWithTemplates = resolveStepArgsWithTemplates;
137965
138456
  exports.resolveStreamMaps = require_composition.resolveStreamMaps;
137966
138457
  exports.resolveTemplateRef = resolveTemplateRef;
137967
138458
  exports.resolveVariantModelId = resolveVariantModelId;
@@ -138187,6 +138678,7 @@ exports.timedRunCapability = timedRunCapability;
138187
138678
  exports.timedRunLimitOf = timedRunLimitOf;
138188
138679
  exports.timedRunMaxIn = timedRunMaxIn;
138189
138680
  exports.timedRunQuickRun = timedRunQuickRun;
138681
+ exports.timedRunRemaining = timedRunRemaining;
138190
138682
  exports.timedRunSeconds = timedRunSeconds;
138191
138683
  exports.toAppLinkHubOrigin = toAppLinkHubOrigin;
138192
138684
  exports.toDeviceSummary = toDeviceSummary;