@camstack/types 1.2.423 → 1.2.425

package/dist/composition/composition.d.ts

@@ -128,6 +128,7 @@ export declare const CompositionAggregateSourceSchema: z.ZodObject<{
         cap: z.ZodString;
         fieldPath: z.ZodString;
     }, z.core.$strip>>;
+    activeWhen: z.ZodOptional<z.ZodArray<z.ZodString>>;
     publish: z.ZodEnum<{
         excluded: "excluded";
         included: "included";
@@ -213,6 +214,7 @@ export declare const CompositionFieldSourceSchema: z.ZodDiscriminatedUnion<[z.Zo
         cap: z.ZodString;
         fieldPath: z.ZodString;
     }, z.core.$strip>>;
+    activeWhen: z.ZodOptional<z.ZodArray<z.ZodString>>;
     publish: z.ZodEnum<{
         excluded: "excluded";
         included: "included";
@@ -328,6 +330,7 @@ export declare const CompositionItemEntrySchema: z.ZodObject<{
             cap: z.ZodString;
             fieldPath: z.ZodString;
         }, z.core.$strip>>;
+        activeWhen: z.ZodOptional<z.ZodArray<z.ZodString>>;
         publish: z.ZodEnum<{
             excluded: "excluded";
             included: "included";
@@ -412,6 +415,7 @@ export declare const CompositionFieldsFeatureSchema: z.ZodObject<{
             cap: z.ZodString;
             fieldPath: z.ZodString;
         }, z.core.$strip>>;
+        activeWhen: z.ZodOptional<z.ZodArray<z.ZodString>>;
         publish: z.ZodEnum<{
             excluded: "excluded";
             included: "included";
@@ -492,6 +496,7 @@ export declare const CompositionFieldsFeatureSchema: z.ZodObject<{
                 cap: z.ZodString;
                 fieldPath: z.ZodString;
             }, z.core.$strip>>;
+            activeWhen: z.ZodOptional<z.ZodArray<z.ZodString>>;
             publish: z.ZodEnum<{
                 excluded: "excluded";
                 included: "included";
@@ -600,6 +605,7 @@ export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObj
             cap: z.ZodString;
             fieldPath: z.ZodString;
         }, z.core.$strip>>;
+        activeWhen: z.ZodOptional<z.ZodArray<z.ZodString>>;
         publish: z.ZodEnum<{
             excluded: "excluded";
             included: "included";
@@ -680,6 +686,7 @@ export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObj
                 cap: z.ZodString;
                 fieldPath: z.ZodString;
             }, z.core.$strip>>;
+            activeWhen: z.ZodOptional<z.ZodArray<z.ZodString>>;
             publish: z.ZodEnum<{
                 excluded: "excluded";
                 included: "included";
@@ -830,6 +837,7 @@ export declare const CompositionSchema: z.ZodObject<{
                 cap: z.ZodString;
                 fieldPath: z.ZodString;
             }, z.core.$strip>>;
+            activeWhen: z.ZodOptional<z.ZodArray<z.ZodString>>;
             publish: z.ZodEnum<{
                 excluded: "excluded";
                 included: "included";
@@ -910,6 +918,7 @@ export declare const CompositionSchema: z.ZodObject<{
                     cap: z.ZodString;
                     fieldPath: z.ZodString;
                 }, z.core.$strip>>;
+                activeWhen: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 publish: z.ZodEnum<{
                     excluded: "excluded";
                     included: "included";

package/dist/composition/helpers/actuator-methods.d.ts

@@ -0,0 +1,39 @@
+/**
+ * One method table per actuator type (D944). A group offers a method only
+ * when every member can take it, so a command never reaches a member that
+ * lacks the surface: the cap must be bound by every member (the primary cap of
+ * the type is the exception — a member that lacks it is simply not commanded),
+ * and a row that names a device feature needs every member to advertise it.
+ * Offline does not remove a method: capability is the binding, not liveness.
+ */
+import { DeviceFeature } from '../../device/device-type.js';
+export declare const ACTUATOR_TEMPLATE_IDS: readonly ['switch', 'light', 'fan', 'cover', 'valve', 'lock', 'media-player', 'climate'];
+export type ActuatorTemplateId = (typeof ACTUATOR_TEMPLATE_IDS)[number];
+export interface ActuatorMethodRow {
+    readonly cap: string;
+    readonly method: string;
+    /** Every member must advertise this feature for the row to be shared. */
+    readonly requires: DeviceFeature | null;
+    /** The call must say `confirm: true`; the group refuses it otherwise. */
+    readonly confirm: boolean;
+}
+/** The first row's cap is the type's own: always offered, members without it are skipped. */
+export declare const ACTUATOR_METHODS: Readonly<Record<ActuatorTemplateId, readonly ActuatorMethodRow[]>>;
+export interface ActuatorMemberSurface {
+    readonly caps: readonly string[];
+    readonly features: readonly string[];
+}
+export declare function actuatorMethodRow(templateId: ActuatorTemplateId, cap: string, method: string): ActuatorMethodRow | null;
+/**
+ * The rows every member can take. An empty member list shares nothing; the
+ * caller passes a surface for every member it could read, or none at all.
+ */
+export declare function sharedActuatorMethods(templateId: ActuatorTemplateId, members: readonly ActuatorMemberSurface[]): readonly ActuatorMethodRow[];
+/** The device features every member has, among those the table gates on, in table order. */
+export declare function sharedActuatorFeatures(templateId: ActuatorTemplateId, featureLists: readonly (readonly string[])[]): readonly DeviceFeature[];
+export declare const UNLOCK_CONFIRMATION: string;
+/**
+ * Why a call must not be fanned out, or null. Only a confirmed row passes
+ * without `confirm: true`; anything else is the caller's to refuse by name.
+ */
+export declare function methodRefusal(method: ActuatorMethodRow | null, args: Readonly<Record<string, unknown>>): string | null;

package/dist/composition/helpers/aggregate.d.ts

@@ -20,6 +20,8 @@ export interface AggregateCounts {
 export type AggregatePublish = 'value' | 'included' | 'excluded' | 'total';
 export type AggregateEmpty = 'null' | 'omit' | 'offline';
 export interface EvaluateAggregateInput {
+    /** Enum states that count as active, for a reducer over states instead of booleans. */
+    readonly activeWhen?: readonly string[];
     readonly reducer: AggregateReducer;
     readonly members: readonly AggregateReadResult[];
     readonly publish: AggregatePublish;

package/dist/composition/helpers/catalog.d.ts

@@ -20,8 +20,14 @@ export interface GroupTemplate {
     readonly summary: string;
     readonly deviceType: DeviceType;
     readonly role: DeviceRole | undefined;
-    /** Members are this one device type. */
+    /** Members are this one device type — or, for a climate group, one of a few. */
     readonly memberDeviceType: DeviceType;
+    readonly memberDeviceTypes: readonly DeviceType[];
+    /**
+     * Enum states of the member field that count as active. Set when the member
+     * field is a state rather than a yes/no (a cover is `open`, a lock `locked`).
+     */
+    readonly activeWhen: readonly string[] | undefined;
     readonly outputCap: string;
     readonly outputField: string;
     /**

package/dist/composition/helpers/compile-history.d.ts

@@ -1,12 +1,27 @@
 import type { CompositionProblem } from '../composition-report.js';
 import type { SeriesKind } from './history-math.js';
 import { type HistoryRetention } from './history-window.js';
-import type { HelperMember, IntegralHelperSpec, StatisticHelperSpec } from './spec.js';
+import type { DerivativeHelperSpec, HelperMember, IntegralHelperSpec, StatisticHelperSpec } from './spec.js';
+/**
+ * The unit of a rate: the source series' unit per second, minute or hour
+ * (`°C/h`). A source with no unit of its own (a generic number) has none to
+ * borrow, so the label is null and the chart shows the bare number.
+ */
+export declare function derivativeUnitLabel(spec: DerivativeHelperSpec): string | null;
 export declare function declaredSeriesKind(member: HelperMember): SeriesKind | 'enum' | null;
 export declare function statisticDraft(spec: StatisticHelperSpec, retention?: HistoryRetention): {
     readonly draft: unknown;
     readonly problems: readonly CompositionProblem[];
 };
+/**
+ * A derivative reads a gauge or a counter and publishes its rate per second,
+ * minute or hour. The output is a plain number: a rate of a temperature is not
+ * a temperature, so the chart carries no inherited unit.
+ */
+export declare function derivativeDraft(spec: DerivativeHelperSpec, retention?: HistoryRetention): {
+    readonly draft: unknown;
+    readonly problems: readonly CompositionProblem[];
+};
 export declare function integralDraft(spec: IntegralHelperSpec, retention?: HistoryRetention): {
     readonly draft: unknown;
     readonly problems: readonly CompositionProblem[];

package/dist/composition/helpers/compile-math.d.ts

@@ -0,0 +1,9 @@
+import type { CompositionProblem } from '../composition-report.js';
+import type { ArithmeticHelperSpec, ExpressionHelperSpec, ThresholdHelperSpec } from './spec.js';
+export interface MathDraft {
+    readonly draft: unknown;
+    readonly problems: readonly CompositionProblem[];
+}
+export declare function thresholdDraft(spec: ThresholdHelperSpec): MathDraft;
+export declare function arithmeticDraft(spec: ArithmeticHelperSpec): MathDraft;
+export declare function expressionDraft(spec: ExpressionHelperSpec): MathDraft;

package/dist/composition/helpers/history-math.d.ts

@@ -37,3 +37,11 @@ export interface HistoryValue {
 export declare function evaluateStatistic(stat: StatisticStat, read: SeriesRead): HistoryValue;
 export type IntegralScale = 'energy-kwh' | 'per-second';
 export declare function integrateReading(read: SeriesRead, scale: IntegralScale): HistoryValue;
+/**
+ * Rate of change over a window, per `perMs`. The slope is taken between the
+ * first and the last measured sample, so a hole inside the window neither
+ * counts as zero nor stretches the elapsed time. A gauge that reported
+ * nothing after the value held at the start is flat (rate 0); fewer than two
+ * samples and no held value is a known gap (D393).
+ */
+export declare function evaluateDerivative(read: SeriesRead, perMs: number): HistoryValue;

package/dist/composition/helpers/index.d.ts

@@ -1,12 +1,14 @@
+export { ACTUATOR_METHODS, ACTUATOR_TEMPLATE_IDS, type ActuatorMemberSurface, type ActuatorMethodRow, type ActuatorTemplateId, actuatorMethodRow, methodRefusal, sharedActuatorFeatures, sharedActuatorMethods, UNLOCK_CONFIRMATION, } from './actuator-methods.js';
 export { FAN_OUT_CONCURRENCY, LIGHT_SHARED_CAPS, type FanOutCall, type FanOutFailed, type FanOutMember, type FanOutMemberResult, type FanOutOk, type LightSharedCap, activeForReducer, fanOutTargets, reducerForActive, runFanOut, sharedColorModes, sharedLightCaps, } from './actuator.js';
 export { type AggregateCounts, type AggregateEmpty, type AggregateOutcome, type AggregatePublish, type AggregateReadResult, type AggregateUnavailable, type AggregateValue, type EvaluateAggregateInput, evaluateAggregate, } from './aggregate.js';
 export { APPLIANCE_DEFAULTS, APPLIANCE_KINDS, APPLIANCE_TEMPLATE_ID, type ApplianceDefaults, type ApplianceKind, applianceDeviceType, isApplianceKind, sourcePickForAppliance, } from './appliance.js';
 export { type GroupTemplate, type HelperAccept, type HelperCompanion, GROUP_TEMPLATES, groupTemplate, } from './catalog.js';
 export { type HelperCompileResult, type HelperCompiled, type HelperRefused, compileHelper, sameHelperBody, templateDeviceType, } from './compile.js';
-export { declaredSeriesKind, integralDraft, statisticDraft } from './compile-history.js';
+export { declaredSeriesKind, derivativeDraft, derivativeUnitLabel, integralDraft, statisticDraft, } from './compile-history.js';
+export { arithmeticDraft, expressionDraft, thresholdDraft } from './compile-math.js';
 export { KWH_PER_WATT_MS, wattMillisecondsToKwh } from './energy.js';
-export { type HistoryValue, type IntegralScale, type SeriesBefore, type SeriesKind, type SeriesPoint, type SeriesRead, STATISTIC_STATS, SERIES_KINDS, evaluateStatistic, integrateReading, } from './history-math.js';
+export { type HistoryValue, type IntegralScale, type SeriesBefore, type SeriesKind, type SeriesPoint, type SeriesRead, STATISTIC_STATS, SERIES_KINDS, evaluateDerivative, evaluateStatistic, integrateReading, } from './history-math.js';
 export { type CalendarPeriod, type CalendarWindow, type HistoryRetention, type HistoryTier, type HistoryTierPlan, type OpenRange, type ResetPeriod, type RollingSpan, type RollingWindow, type StatisticWindow, CALENDAR_PERIODS, CalendarWindowSchema, DAY_MS, DEFAULT_HISTORY_RETENTION, HISTORY_FAST_MS, HISTORY_SLOW_MS, HISTORY_TIERS, HOUR_MS, MINUTE_MS, MIN_CUSTOM_MINUTES, RESET_PERIODS, ROLLING_SPANS, RollingWindowSchema, StatisticWindowSchema, integralCadenceMs, maxDurationMs, nextLocalMidnight, openReset, openStatistic, planResetTier, planStatisticTier, rollingDurationMs, statisticCadenceMs, } from './history-window.js';
 export { type HelperMemberFact, helperSaveProblems, } from './save.js';
-export { type SourcePick, type SourcePickAccept, type SourcePickHistory, type SourcePickRequest, sourcePickForHistory, sourcePickForTemplate, } from './source-pick.js';
-export { ACTIVE_CRITERIA, AGGREGATE_REDUCERS, ActiveCriterionSchema, AggregateReducerSchema, BINARY_AGGREGATES, GROUP_TEMPLATE_IDS, ApplianceHelperSpecSchema, GroupHelperSpecSchema, GroupTemplateIdSchema, HelperMemberSchema, HelperSpecSchema, INTEGRAL_OUTPUTS, IntegralHelperSpecSchema, MAX_HELPER_MEMBERS, helperMembers, NUMERIC_AGGREGATES, StatisticHelperSpecSchema, type ActiveCriterion, type AggregateReducer, type BinaryAggregate, type ApplianceHelperSpec, type GroupHelperSpec, type GroupTemplateId, type HelperMember, type HelperSpec, type IntegralHelperSpec, type IntegralOutput, type NumericAggregate, type StatisticHelperSpec, type StatisticStat, } from './spec.js';
+export { type SourcePick, type SourcePickAccept, type SourcePickHistory, type SourcePickRequest, type MathSourceKind, sourcePickForHistory, sourcePickForMath, sourcePickForTemplate, } from './source-pick.js';
+export { ACTIVE_CRITERIA, AGGREGATE_REDUCERS, ActiveCriterionSchema, AggregateReducerSchema, BINARY_AGGREGATES, GROUP_TEMPLATE_IDS, ApplianceHelperSpecSchema, ARITHMETIC_OPS, ArithmeticHelperSpecSchema, DERIVATIVE_UNITS, DerivativeHelperSpecSchema, EXPRESSION_OUTPUTS, ExpressionHelperSpecSchema, ThresholdHelperSpecSchema, GroupHelperSpecSchema, GroupTemplateIdSchema, HelperMemberSchema, HelperSpecSchema, INTEGRAL_OUTPUTS, IntegralHelperSpecSchema, MAX_HELPER_MEMBERS, helperMembers, isHistoryHelper, NUMERIC_AGGREGATES, StatisticHelperSpecSchema, type ActiveCriterion, type AggregateReducer, type BinaryAggregate, type ApplianceHelperSpec, type ArithmeticHelperSpec, type ArithmeticOp, type DerivativeHelperSpec, type DerivativeUnit, type ExpressionHelperSpec, type ExpressionInput, type ExpressionOutput, type ThresholdHelperSpec, type GroupHelperSpec, type GroupTemplateId, type HelperMember, type HelperSpec, type HistoryHelperSpec, type IntegralHelperSpec, type IntegralOutput, type NumericAggregate, type StatisticHelperSpec, type StatisticStat, } from './spec.js';

package/dist/composition/helpers/source-pick.d.ts

@@ -9,7 +9,7 @@ import type { GroupTemplate } from './catalog.js';
 export interface SourcePickAccept {
     readonly cap: string;
     readonly fieldPath: string;
-    readonly valueKind: 'number' | 'boolean';
+    readonly valueKind: 'number' | 'boolean' | 'state';
 }
 export interface SourcePickHistory {
     readonly required: boolean;
@@ -40,3 +40,10 @@ export interface SourcePick {
 export declare function sourcePickForTemplate(template: GroupTemplate): SourcePickRequest;
 /** A statistic or integral reads one field that declares history. */
 export declare function sourcePickForHistory(kind: 'statistic' | 'integral'): SourcePickRequest;
+export type MathSourceKind = 'threshold' | 'sum' | 'difference' | 'ratio' | 'expression' | 'derivative';
+/**
+ * What the input step asks the selector for a math helper. A threshold reads
+ * one number, a difference or a ratio two, a sum and an expression several.
+ * A derivative reads one historised number.
+ */
+export declare function sourcePickForMath(kind: MathSourceKind): SourcePickRequest;

package/dist/composition/helpers/spec.d.ts

@@ -5,11 +5,11 @@
 import { z } from 'zod';
 import { APPLIANCE_TEMPLATE_ID } from './appliance.js';
 import { STATISTIC_STATS } from './history-math.js';
-import { type ResetPeriod, type StatisticWindow } from './history-window.js';
+import { type ResetPeriod, type RollingWindow, type StatisticWindow } from './history-window.js';
 import { CompositionSourceRefSchema } from '../source-ref.js';
 /** A group may name more members than an expression call (the 16-arg cap). */
 export declare const MAX_HELPER_MEMBERS: number;
-export declare const GROUP_TEMPLATE_IDS: readonly ['temperature', 'humidity', 'pressure', 'illuminance', 'power', 'energy', 'battery', 'numeric', 'motion', 'contact', 'leak', 'smoke', 'occupancy', 'binary', 'switch', 'light'];
+export declare const GROUP_TEMPLATE_IDS: readonly ['temperature', 'humidity', 'pressure', 'illuminance', 'power', 'energy', 'battery', 'numeric', 'motion', 'contact', 'leak', 'smoke', 'occupancy', 'binary', 'switch', 'light', 'fan', 'cover', 'valve', 'lock', 'media-player', 'climate'];
 export type GroupTemplateId = (typeof GROUP_TEMPLATE_IDS)[number];
 export declare const NUMERIC_AGGREGATES: readonly ['mean', 'median', 'min', 'max', 'sum'];
 export type NumericAggregate = (typeof NUMERIC_AGGREGATES)[number];
@@ -70,7 +70,53 @@ export type IntegralHelperSpec = {
     readonly source: HelperMember;
 };
 export declare const IntegralHelperSpecSchema: z.ZodType<IntegralHelperSpec>;
-export type HelperSpec = GroupHelperSpec | ApplianceHelperSpec | StatisticHelperSpec | IntegralHelperSpec;
+/** Math (D944 phase 3). A reading in, a reading or a yes/no out. */
+export type ThresholdHelperSpec = {
+    readonly kind: 'threshold';
+    readonly source: HelperMember;
+    /** The output turns on once the reading is at or above this. */
+    readonly high: number;
+    /** The output turns off once the reading is at or below this. `low <= high`. */
+    readonly low: number;
+    readonly onForMs: number;
+    readonly offForMs: number;
+};
+export declare const ThresholdHelperSpecSchema: z.ZodType<ThresholdHelperSpec>;
+export declare const ARITHMETIC_OPS: readonly ['sum', 'difference', 'ratio'];
+export type ArithmeticOp = (typeof ARITHMETIC_OPS)[number];
+export type ArithmeticHelperSpec = {
+    readonly kind: 'arithmetic';
+    readonly op: ArithmeticOp;
+    /** Sum: two or more. Difference and ratio: exactly two, first minus / over second. */
+    readonly inputs: readonly HelperMember[];
+};
+export declare const ArithmeticHelperSpecSchema: z.ZodType<ArithmeticHelperSpec>;
+export declare const EXPRESSION_OUTPUTS: readonly ['number', 'boolean'];
+export type ExpressionOutput = (typeof EXPRESSION_OUTPUTS)[number];
+export interface ExpressionInput {
+    readonly name: string;
+    readonly member: HelperMember;
+}
+export type ExpressionHelperSpec = {
+    readonly kind: 'expression';
+    readonly expr: string;
+    readonly inputs: readonly ExpressionInput[];
+    readonly output: ExpressionOutput;
+};
+export declare const ExpressionHelperSpecSchema: z.ZodType<ExpressionHelperSpec>;
+export declare const DERIVATIVE_UNITS: readonly ['second', 'minute', 'hour'];
+export type DerivativeUnit = (typeof DERIVATIVE_UNITS)[number];
+export type DerivativeHelperSpec = {
+    readonly kind: 'derivative';
+    readonly window: RollingWindow;
+    readonly per: DerivativeUnit;
+    readonly source: HelperMember;
+};
+export declare const DerivativeHelperSpecSchema: z.ZodType<DerivativeHelperSpec>;
+export type HelperSpec = GroupHelperSpec | ApplianceHelperSpec | StatisticHelperSpec | IntegralHelperSpec | ThresholdHelperSpec | ArithmeticHelperSpec | ExpressionHelperSpec | DerivativeHelperSpec;
 export declare const HelperSpecSchema: z.ZodType<HelperSpec>;
+/** The kinds the composer runs from device history, on a schedule. */
+export type HistoryHelperSpec = StatisticHelperSpec | IntegralHelperSpec | DerivativeHelperSpec;
+export declare function isHistoryHelper(spec: HelperSpec): spec is HistoryHelperSpec;
 /** Every member a helper reads. A group has many; the others have one. */
 export declare function helperMembers(spec: HelperSpec): readonly HelperMember[];

package/dist/{composition-CpETZ4HL.mjs → composition-Bb8iwHEJ.mjs}

@@ -1138,7 +1138,7 @@ var ExpressionEvalError = class extends Error {
 //#endregion
 //#region src/expression/builtins.ts
 function isStatefulBuiltin(name) {
-	return name === "rose" || name === "count" || name === "dwell" || name === "latchedAt";
+	return name === "rose" || name === "count" || name === "dwell" || name === "latchedAt" || name === "schmitt";
 }
 function asFiniteNumber(value, name, index) {
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new ExpressionEvalError(`${name}: argument ${index + 1} must be a finite number`);
@@ -1266,6 +1266,41 @@ function evaluateDwell(activeRaw, onForMsRaw, offForMsRaw, call, nowMs, hooks) {
 	hooks?.noteDeadline?.(call.pendingSince + delay);
 	return call.latched;
 }
+/**
+* `schmitt(x, high, low[, onForMs, offForMs])`: true once `x >= high`, false
+* once `x <= low`, and the last answer in between. A transition waits its delay
+* and is dropped if `x` returns to the held side first. The first answer needs
+* a crossing, or the restored output as `seed`: a reading inside the band with
+* nothing to hold is unknown, never off (D393). A null reading throws, so the
+* field is unavailable and the latch is kept.
+*/
+function evaluateSchmitt(args, call, nowMs, seed, hooks) {
+	const x = asFiniteNumber(args[0], "schmitt", 0);
+	const high = asFiniteNumber(args[1], "schmitt", 1);
+	const low = asFiniteNumber(args[2], "schmitt", 2);
+	const onForMs = args.length > 3 ? asNonNegativeMs(args[3], "schmitt", 3) : 0;
+	const offForMs = args.length > 4 ? asNonNegativeMs(args[4], "schmitt", 4) : 0;
+	if (low > high) throw new ExpressionEvalError("schmitt: the low edge is above the high edge");
+	if (call.latched === null && seed !== null) call.latched = seed;
+	const wants = x >= high ? true : x <= low ? false : call.latched;
+	if (call.latched === null) {
+		if (wants !== null) call.latched = wants;
+		return call.latched;
+	}
+	if (wants === null || wants === call.latched) {
+		call.pendingSince = null;
+		return call.latched;
+	}
+	if (call.pendingSince === null) call.pendingSince = nowMs;
+	const delay = wants ? onForMs : offForMs;
+	if (nowMs - call.pendingSince >= delay) {
+		call.latched = wants;
+		call.pendingSince = null;
+		return call.latched;
+	}
+	hooks?.noteDeadline?.(call.pendingSince + delay);
+	return call.latched;
+}
 /** `latchedAt(value)`: epoch ms when `value` last changed; null clears the stamp. */
 function evaluateLatchedAt(value, call, nowMs) {
 	if (value === null) {
@@ -1463,6 +1498,13 @@ var table = {
 		apply: () => {
 			throw new ExpressionEvalError("latchedAt: stateful evaluation context is required");
 		}
+	},
+	schmitt: {
+		minArgs: 3,
+		maxArgs: 5,
+		apply: () => {
+			throw new ExpressionEvalError("schmitt: stateful evaluation context is required");
+		}
 	}
 };
 /** Frozen, null-prototype builtin table. */
@@ -2072,6 +2114,16 @@ function evaluateStatefulExpressionCall(invocation, memory, env, hooks) {
 			memory.calls.set(invocation.path, call);
 			return evaluateDwell(invocation.args[0], invocation.args[1], invocation.args[2], call, env.nowMs, hooks);
 		}
+		case "schmitt": {
+			const call = existing?.kind === "schmitt" ? existing : {
+				kind: "schmitt",
+				latched: null,
+				pendingSince: null
+			};
+			memory.calls.set(invocation.path, call);
+			const seed = typeof env.currentOutput === "boolean" ? env.currentOutput : null;
+			return evaluateSchmitt(invocation.args, call, env.nowMs, seed, hooks);
+		}
 		case "latchedAt": {
 			const call = existing?.kind === "latchedAt" ? existing : {
 				kind: "latchedAt",
@@ -2442,6 +2494,58 @@ function integrateReading(read, scale) {
 	for (const segment of covered.segments) unitMs += segment.value * segment.ms;
 	return numberValue(scale === "energy-kwh" ? wattMillisecondsToKwh(unitMs) : unitMs / 1e3, covered.included, covered.gaps, GAP_REASON);
 }
+function samplesOf(read) {
+	const out = [];
+	if (read.before !== null && finite(read.before.value)) out.push({
+		at: read.from,
+		value: read.before.value
+	});
+	for (const point of read.points) {
+		if (point.t < read.from || point.t > read.to) continue;
+		const value = pointValue(point);
+		if (value === null) continue;
+		const at = read.tier === "raw" || !finite(point.twMs) ? point.t : point.t + point.twMs;
+		out.push({
+			at: Math.min(at, read.to),
+			value
+		});
+	}
+	return out.toSorted((a, b) => a.at - b.at);
+}
+/** A sample-less tail or head longer than this share of the window is counted as a gap. */
+var UNCOVERED_LIMIT = .1;
+var DERIVATIVE_GAP_REASON = "history stops short of the window — the rate is over the part that was measured";
+function derivativeValue(change, spanMs, perMs, included, windowMs) {
+	return numberValue(change / (spanMs / perMs), included, windowMs - spanMs > windowMs * UNCOVERED_LIMIT ? 1 : 0, DERIVATIVE_GAP_REASON);
+}
+/**
+* Rate of change over a window, per `perMs`. The slope is taken between the
+* first and the last measured sample, so a hole inside the window neither
+* counts as zero nor stretches the elapsed time. A gauge that reported
+* nothing after the value held at the start is flat (rate 0); fewer than two
+* samples and no held value is a known gap (D393).
+*/
+function evaluateDerivative(read, perMs) {
+	if (read.truncated) return hold("the history query was truncated — the last rate is kept");
+	if (read.to <= read.from) return gapValue("the range is empty", 0);
+	const windowMs = read.to - read.from;
+	const samples = samplesOf(read);
+	const first = samples[0];
+	const last = samples[samples.length - 1];
+	if (first === void 0 || last === void 0) return gapValue("history has no reading in this window", 0);
+	if (read.kind === "counter") {
+		const heldAtStart = read.before !== null && finite(read.before.value);
+		const startsAt = heldAtStart ? read.from : first.at;
+		const deltas = read.points.flatMap((point) => point.t >= read.from && point.t <= read.to && finite(point.delta) && (heldAtStart || point.t > first.at) ? [point.delta] : []);
+		const spanMs = last.at - startsAt;
+		if (deltas.length === 0 || spanMs <= 0) return gapValue("the counter has no growth in this window", samples.length);
+		return derivativeValue(deltas.reduce((sum, delta) => sum + delta, 0), spanMs, perMs, samples.length, windowMs);
+	}
+	if (samples.length === 1 && first.at === read.from && read.before !== null) return numberValue(0, 1, 0, null);
+	const spanMs = last.at - first.at;
+	if (samples.length < 2 || spanMs <= 0) return gapValue("the rate needs two readings in the window", samples.length);
+	return derivativeValue(last.value - first.value, spanMs, perMs, samples.length, windowMs);
+}
 //#endregion
 //#region src/composition/helpers/history-window.ts
 /**
@@ -2805,7 +2909,13 @@ var GROUP_TEMPLATE_IDS = [
 	"occupancy",
 	"binary",
 	"switch",
-	"light"
+	"light",
+	"fan",
+	"cover",
+	"valve",
+	"lock",
+	"media-player",
+	"climate"
 ];
 var NUMERIC_AGGREGATES = [
 	"mean",
@@ -2868,19 +2978,73 @@ var integralHelperObject = z.object({
 	source: HelperMemberSchema
 });
 var IntegralHelperSpecSchema = integralHelperObject;
+var thresholdHelperObject = z.object({
+	kind: z.literal("threshold"),
+	source: HelperMemberSchema,
+	high: z.number(),
+	low: z.number(),
+	onForMs: z.number().int().nonnegative(),
+	offForMs: z.number().int().nonnegative()
+});
+var ThresholdHelperSpecSchema = thresholdHelperObject;
+var ARITHMETIC_OPS = [
+	"sum",
+	"difference",
+	"ratio"
+];
+var arithmeticHelperObject = z.object({
+	kind: z.literal("arithmetic"),
+	op: z.enum(ARITHMETIC_OPS),
+	inputs: z.array(HelperMemberSchema).min(2).max(64)
+});
+var ArithmeticHelperSpecSchema = arithmeticHelperObject;
+var EXPRESSION_OUTPUTS = ["number", "boolean"];
+var expressionHelperObject = z.object({
+	kind: z.literal("expression"),
+	expr: z.string().min(1),
+	inputs: z.array(z.object({
+		name: z.string().min(1),
+		member: HelperMemberSchema
+	})).min(1).max(64),
+	output: z.enum(EXPRESSION_OUTPUTS)
+});
+var ExpressionHelperSpecSchema = expressionHelperObject;
+var DERIVATIVE_UNITS = [
+	"second",
+	"minute",
+	"hour"
+];
+var derivativeHelperObject = z.object({
+	kind: z.literal("derivative"),
+	window: RollingWindowSchema,
+	per: z.enum(DERIVATIVE_UNITS),
+	source: HelperMemberSchema
+});
+var DerivativeHelperSpecSchema = derivativeHelperObject;
 var HelperSpecSchema = z.discriminatedUnion("kind", [
 	GroupHelperSpecSchema,
 	ApplianceHelperSpecSchema,
 	statisticHelperObject,
-	integralHelperObject
+	integralHelperObject,
+	thresholdHelperObject,
+	arithmeticHelperObject,
+	expressionHelperObject,
+	derivativeHelperObject
 ]);
+function isHistoryHelper(spec) {
+	return spec.kind === "statistic" || spec.kind === "integral" || spec.kind === "derivative";
+}
 /** Every member a helper reads. A group has many; the others have one. */
 function helperMembers(spec) {
 	switch (spec.kind) {
 		case "group": return spec.members;
 		case "appliance": return [spec.member];
 		case "statistic":
-		case "integral": return [spec.source];
+		case "integral":
+		case "threshold":
+		case "derivative": return [spec.source];
+		case "arithmetic": return spec.inputs;
+		case "expression": return spec.inputs.map((input) => input.member);
 	}
 }
 //#endregion
@@ -2978,6 +3142,12 @@ var CompositionAggregateSourceSchema = z.object({
 		"all"
 	]),
 	reads: z.array(CompositionFieldReadSchema).min(1).max(64),
+	/**
+	* Set when the reads are an enum state, not a yes/no: the listed states
+	* count as active (a cover is `open`). A state outside the list is inactive;
+	* a read that is not a state at all is left out. Only `any` / `all` use it.
+	*/
+	activeWhen: z.array(z.string().min(1)).min(1).optional(),
 	/** `value` is the reading; the others are the member counts. */
 	publish: z.enum([
 		"value",
@@ -3168,4 +3338,4 @@ function featureSources(feature) {
 	return featureFieldEntries(feature).map((e) => e.source);
 }
 //#endregion
-export { NUMERIC_AGGREGATES as $, MAX_EXPRESSION_AST_NODES as $t, composedDeviceStableId as A, Fmp4BoxSplitter as An, KWH_PER_WATT_MS as At, AGGREGATE_REDUCERS as B, pickVideoEncoder as Bn, createStatefulExpressionMemory as Bt, CompositionSeriesSourceSchema as C, FFMPEG_PATH_ENV as Cn, planStatisticTier as Ct, MAX_COMPOSITION_FIELDS_PER_FEATURE as D, getFfmpegArtifact as Dn, STATISTIC_STATS as Dt, MAX_COMPOSITION_FEATURES as E, FFMPEG_RELEASE as En, SERIES_KINDS as Et, compositionSourceKey as F, buildInputArgs as Fn, applianceDeviceType as Ft, GROUP_TEMPLATE_IDS as G, createExpressionScope as Gt, AggregateReducerSchema as H, evaluateStatefulExpressionCall as Ht, featureFieldEntries as I, buildVideoArgs as In, isApplianceKind as It, HelperMemberSchema as J, compileExpressionSafe as Jt, GroupHelperSpecSchema as K, evaluateAst as Kt, featureSources as L, invocationFromEncodeProfile as Ln, sourcePickForAppliance as Lt, compositionItemFieldPath as M, audioPlanFromEncodeProfile as Mn, APPLIANCE_DEFAULTS as Mt, compositionReadKey as N, buildAudioArgs as Nn, APPLIANCE_KINDS as Nt, MAX_COMPOSITION_ITEMS as O, getFfmpegDownloadUrl as On, evaluateStatistic as Ot, compositionSliceKey as P, buildFfmpegArgs as Pn, APPLIANCE_TEMPLATE_ID as Pt, MAX_HELPER_MEMBERS as Q, EXPRESSION_IDENTIFIER_RE as Qt, fieldReads as R, isSoftwareDecode as Rn, EXPRESSION_INJECTED_NOW as Rt, CompositionSchema as S, sliceChangedAt as Sn, planResetTier as St, MAX_COMPOSITION_CODE_LENGTH as T, ffmpegBinaryName as Tn, statisticCadenceMs as Tt, ApplianceHelperSpecSchema as U, toExpressionValue as Ut, ActiveCriterionSchema as V, resolveStreamMaps as Vn, evaluateExpressionSource as Vt, BINARY_AGGREGATES as W, validateExpressionSource as Wt, INTEGRAL_OUTPUTS as X, tokenize as Xt, HelperSpecSchema as Y, parseExpression as Yt, IntegralHelperSpecSchema as Z, EXPRESSION_COMPILE_CACHE_CAPACITY as Zt, CompositionFromSourceSchema as _, SOURCE_DEVICE_TYPES as _n, integralCadenceMs as _t, CUSTOMIZATION_BLOCK_NAME_PREFIX as a, EXPRESSION_BUILTINS as an, DAY_MS as at, CompositionNewTargetSchema as b, isSourceCap as bn, openReset as bt, CompositionCodeSourceSchema as c, evaluateCount as cn, HISTORY_SLOW_MS as ct, CompositionExpressionSourceSchema as d, ExpressionEvalError as dn, MINUTE_MS as dt, MAX_EXPRESSION_BINDINGS as en, StatisticHelperSpecSchema as et, CompositionFeatureSchema as f, ExpressionParseError as fn, MIN_CUSTOM_MINUTES as ft, CompositionForwardCommandSchema as g, SOURCE_CAP_CHANGED_AT_FIELD as gn, StatisticWindowSchema as gt, CompositionFieldsFeatureSchema as h, SOURCE_CAP_ACTIVE_FIELD as hn, RollingWindowSchema as ht, COMPOSITION_ITEM_KEY_RE as i, RESERVED_BINDING_NAMES as in, CalendarWindowSchema as it, compositionFeatureEnabled as j, AUDIO_PRESETS as jn, wattMillisecondsToKwh as jt, composedDeviceRef as k, canonicalHash as kn, integrateReading as kt, CompositionCommandTargetSchema as l, evaluateRose as ln, HISTORY_TIERS as lt, CompositionFieldSourceSchema as m, SOURCE_CAPS as mn, ROLLING_SPANS as mt, COMPOSER_ADDON_ID as n, MAX_EXPRESSION_EVAL_STEPS as nn, CompositionSourceRefSchema as nt, CompositionAggregateSourceSchema as o, EXPRESSION_BUILTIN_NAMES as on, DEFAULT_HISTORY_RETENTION as ot, CompositionFieldReadSchema as p, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as pn, RESET_PERIODS as pt, GroupTemplateIdSchema as q, compileExpression as qt, COMPOSITION_ITEM_ARRAY_PATH as r, MAX_EXPRESSION_SOURCE_LENGTH as rn, CALENDAR_PERIODS as rt, CompositionBindingSchema as s, disarmRoseMemory as sn, HISTORY_FAST_MS as st, COMPOSED_DEVICE_STABLE_ID_PREFIX as t, MAX_EXPRESSION_CALL_ARGS as tn, helperMembers as tt, CompositionExistingTargetSchema as u, isStatefulBuiltin as un, HOUR_MS as ut, CompositionItemEntrySchema as v, evaluateSensorEdge as vn, maxDurationMs as vt, CompositionTargetSchema as w, chooseFfmpegBinary as wn, rollingDurationMs as wt, CompositionPassthroughFeatureSchema as x, sliceActiveValue as xn, openStatistic as xt, CompositionLiteralBindingSchema as y, evaluateSensorLevelEdge as yn, nextLocalMidnight as yt, ACTIVE_CRITERIA as z, logBannerArgs as zn, cloneStatefulExpressionMemory as zt };
+export { GroupTemplateIdSchema as $, validateExpressionSource as $t, composedDeviceStableId as A, sliceActiveValue as An, planResetTier as At, AGGREGATE_REDUCERS as B, AUDIO_PRESETS as Bn, wattMillisecondsToKwh as Bt, CompositionSeriesSourceSchema as C, SOURCE_CAPS as Cn, RollingWindowSchema as Ct, MAX_COMPOSITION_FIELDS_PER_FEATURE as D, evaluateSensorEdge as Dn, nextLocalMidnight as Dt, MAX_COMPOSITION_FEATURES as E, SOURCE_DEVICE_TYPES as En, maxDurationMs as Et, compositionSourceKey as F, FFMPEG_RELEASE as Fn, STATISTIC_STATS as Ft, ArithmeticHelperSpecSchema as G, buildVideoArgs as Gn, isApplianceKind as Gt, ActiveCriterionSchema as H, buildAudioArgs as Hn, APPLIANCE_KINDS as Ht, featureFieldEntries as I, getFfmpegArtifact as In, evaluateDerivative as It, DerivativeHelperSpecSchema as J, logBannerArgs as Jn, cloneStatefulExpressionMemory as Jt, BINARY_AGGREGATES as K, invocationFromEncodeProfile as Kn, sourcePickForAppliance as Kt, featureSources as L, getFfmpegDownloadUrl as Ln, evaluateStatistic as Lt, compositionItemFieldPath as M, FFMPEG_PATH_ENV as Mn, rollingDurationMs as Mt, compositionReadKey as N, chooseFfmpegBinary as Nn, statisticCadenceMs as Nt, MAX_COMPOSITION_ITEMS as O, evaluateSensorLevelEdge as On, openReset as Ot, compositionSliceKey as P, ffmpegBinaryName as Pn, SERIES_KINDS as Pt, GroupHelperSpecSchema as Q, toExpressionValue as Qt, fieldReads as R, canonicalHash as Rn, integrateReading as Rt, CompositionSchema as S, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as Sn, ROLLING_SPANS as St, MAX_COMPOSITION_CODE_LENGTH as T, SOURCE_CAP_CHANGED_AT_FIELD as Tn, integralCadenceMs as Tt, AggregateReducerSchema as U, buildFfmpegArgs as Un, APPLIANCE_TEMPLATE_ID as Ut, ARITHMETIC_OPS as V, audioPlanFromEncodeProfile as Vn, APPLIANCE_DEFAULTS as Vt, ApplianceHelperSpecSchema as W, buildInputArgs as Wn, applianceDeviceType as Wt, ExpressionHelperSpecSchema as X, resolveStreamMaps as Xn, evaluateExpressionSource as Xt, EXPRESSION_OUTPUTS as Y, pickVideoEncoder as Yn, createStatefulExpressionMemory as Yt, GROUP_TEMPLATE_IDS as Z, evaluateStatefulExpressionCall as Zt, CompositionFromSourceSchema as _, evaluateCount as _n, HISTORY_TIERS as _t, CUSTOMIZATION_BLOCK_NAME_PREFIX as a, tokenize as an, NUMERIC_AGGREGATES as at, CompositionNewTargetSchema as b, ExpressionEvalError as bn, MIN_CUSTOM_MINUTES as bt, CompositionCodeSourceSchema as c, MAX_EXPRESSION_AST_NODES as cn, helperMembers as ct, CompositionExpressionSourceSchema as d, MAX_EXPRESSION_EVAL_STEPS as dn, CALENDAR_PERIODS as dt, createExpressionScope as en, HelperMemberSchema as et, CompositionFeatureSchema as f, MAX_EXPRESSION_SOURCE_LENGTH as fn, CalendarWindowSchema as ft, CompositionForwardCommandSchema as g, disarmRoseMemory as gn, HISTORY_SLOW_MS as gt, CompositionFieldsFeatureSchema as h, EXPRESSION_BUILTIN_NAMES as hn, HISTORY_FAST_MS as ht, COMPOSITION_ITEM_KEY_RE as i, parseExpression as in, MAX_HELPER_MEMBERS as it, compositionFeatureEnabled as j, sliceChangedAt as jn, planStatisticTier as jt, composedDeviceRef as k, isSourceCap as kn, openStatistic as kt, CompositionCommandTargetSchema as l, MAX_EXPRESSION_BINDINGS as ln, isHistoryHelper as lt, CompositionFieldSourceSchema as m, EXPRESSION_BUILTINS as mn, DEFAULT_HISTORY_RETENTION as mt, COMPOSER_ADDON_ID as n, compileExpression as nn, INTEGRAL_OUTPUTS as nt, CompositionAggregateSourceSchema as o, EXPRESSION_COMPILE_CACHE_CAPACITY as on, StatisticHelperSpecSchema as ot, CompositionFieldReadSchema as p, RESERVED_BINDING_NAMES as pn, DAY_MS as pt, DERIVATIVE_UNITS as q, isSoftwareDecode as qn, EXPRESSION_INJECTED_NOW as qt, COMPOSITION_ITEM_ARRAY_PATH as r, compileExpressionSafe as rn, IntegralHelperSpecSchema as rt, CompositionBindingSchema as s, EXPRESSION_IDENTIFIER_RE as sn, ThresholdHelperSpecSchema as st, COMPOSED_DEVICE_STABLE_ID_PREFIX as t, evaluateAst as tn, HelperSpecSchema as tt, CompositionExistingTargetSchema as u, MAX_EXPRESSION_CALL_ARGS as un, CompositionSourceRefSchema as ut, CompositionItemEntrySchema as v, evaluateRose as vn, HOUR_MS as vt, CompositionTargetSchema as w, SOURCE_CAP_ACTIVE_FIELD as wn, StatisticWindowSchema as wt, CompositionPassthroughFeatureSchema as x, ExpressionParseError as xn, RESET_PERIODS as xt, CompositionLiteralBindingSchema as y, isStatefulBuiltin as yn, MINUTE_MS as yt, ACTIVE_CRITERIA as z, Fmp4BoxSplitter as zn, KWH_PER_WATT_MS as zt };