@camstack/types 1.2.416 → 1.2.418

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

@@ -0,0 +1,40 @@
+/**
+ * The request the common source selector (#236) accepts for a helper (D944 §5).
+ * The selector's layout is not specified here. Groups ask for one device type
+ * and the catalog field; they do not opt into incompatible fields.
+ */
+import type { DeviceType } from '../../device/device-type.js';
+import type { CompositionSourceRef } from '../source-ref.js';
+import type { GroupTemplate } from './catalog.js';
+export interface SourcePickAccept {
+    readonly cap: string;
+    readonly fieldPath: string;
+    readonly valueKind: 'number' | 'boolean';
+}
+export interface SourcePickHistory {
+    readonly required: boolean;
+    readonly minRetentionMs: number | null;
+}
+export interface SourcePickRequest {
+    readonly purpose: 'member' | 'reading' | 'historised';
+    readonly multiple: boolean;
+    readonly max: number;
+    readonly deviceTypes: readonly DeviceType[];
+    readonly accept: readonly SourcePickAccept[];
+    readonly history: SourcePickHistory;
+    readonly mustBindCaps: readonly string[];
+    readonly exclude: readonly CompositionSourceRef[];
+}
+export interface SourcePick {
+    readonly source: CompositionSourceRef;
+    readonly deviceId: number;
+    readonly parentName: string | null;
+    readonly cap: string;
+    readonly fieldPath: string;
+    /** Current reading. `null` is unknown, never a stand-in 0. */
+    readonly current: number | boolean | string | null;
+    readonly compatibility: 'direct' | 'convert' | 'incompatible';
+    readonly history: 'recorded' | 'absent' | 'unknown';
+}
+/** What the member step asks the selector for this template. */
+export declare function sourcePickForTemplate(template: GroupTemplate): SourcePickRequest;

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

@@ -0,0 +1,38 @@
+/**
+ * A helper spec is what the editor stores and reads back (D944). The compiled
+ * features are a projection; the editor never edits the expression.
+ */
+import { z } from 'zod';
+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'];
+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];
+export declare const BINARY_AGGREGATES: readonly ['any', 'all'];
+export type BinaryAggregate = (typeof BINARY_AGGREGATES)[number];
+export declare const AGGREGATE_REDUCERS: readonly ['mean', 'median', 'min', 'max', 'sum', 'any', 'all'];
+export type AggregateReducer = (typeof AGGREGATE_REDUCERS)[number];
+export declare const GroupTemplateIdSchema: z.ZodType<GroupTemplateId>;
+export declare const AggregateReducerSchema: z.ZodType<AggregateReducer>;
+/** One member. The field is stored so occupancy can name motion or binary. */
+export declare const HelperMemberSchema: z.ZodObject<{
+    source: typeof CompositionSourceRefSchema;
+    cap: z.ZodString;
+    fieldPath: z.ZodString;
+}>;
+export type HelperMember = z.infer<typeof HelperMemberSchema>;
+/**
+ * Phase 1a is groups only. Math, integral and statistics stay off this union
+ * until the composer can run them — a control must not save a spec it cannot.
+ */
+export declare const GroupHelperSpecSchema: z.ZodObject<{
+    kind: z.ZodLiteral<'group'>;
+    templateId: typeof GroupTemplateIdSchema;
+    aggregate: typeof AggregateReducerSchema;
+    members: z.ZodArray<typeof HelperMemberSchema>;
+}>;
+export type GroupHelperSpec = z.infer<typeof GroupHelperSpecSchema>;
+export declare const HelperSpecSchema: z.ZodDiscriminatedUnion<[typeof GroupHelperSpecSchema], 'kind'>;
+export type HelperSpec = z.infer<typeof HelperSpecSchema>;

package/dist/composition/index.d.ts

@@ -3,6 +3,7 @@
  * inside @camstack/types import the deep modules, never this file.
  */
 export * from './composable-caps.js';
+export * from './helpers/index.js';
 export * from './composition.js';
 export * from './composition-events.js';
 export * from './composition-graph.js';

package/dist/composition/source-ref.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A composition source identity: `(addonId, stableId)`, never a numeric device
+ * id. Split out so helper schemas can name it without a cycle through
+ * `composition.ts` (D659).
+ */
+import { z } from 'zod';
+export declare const CompositionSourceRefSchema: z.ZodObject<{
+    addonId: z.ZodString;
+    stableId: z.ZodString;
+}>;
+export type CompositionSourceRef = z.infer<typeof CompositionSourceRefSchema>;

package/dist/composition/state-fields.d.ts

@@ -20,6 +20,6 @@ export declare function requiredTopLevelKeys(schema: z.ZodType): readonly string
 /**
  * The proper prefixes of `path` whose schema accepts `undefined`: a required
  * leaf under one of them is required only once something writes that parent
- * (`remaining.unit` is required only when `remaining` is present).
+ * (`remaining.kind` is required only when `remaining` is present).
  */
 export declare function optionalAncestors(schema: z.ZodType, path: string): readonly string[];

package/dist/composition/validate-composition.d.ts

@@ -10,6 +10,7 @@
  */
 import type { CapabilityDefinition } from '../capabilities/capability-definition.js';
 import type { DeviceType } from '../device/device-type.js';
+import type { ReadingQuantity } from '../units/quantity.js';
 import { type Composition, type CompositionSourceRef } from './composition.js';
 import { type CompositionPlanResult } from './plan-result.js';
 import { type CompositionPeer } from './composition-graph.js';
@@ -22,6 +23,10 @@ export interface CompositionSourceFound {
     readonly kind: 'found';
     readonly deviceId: number;
     readonly caps: ReadonlySet<string>;
+    /** Present when the row was read. A helper group requires this one type. */
+    readonly deviceType?: DeviceType;
+    /** Present when the device declares one. Mixed quantities are refused. */
+    readonly quantity?: ReadingQuantity;
 }
 export interface CompositionSourceAbsent {
     readonly kind: 'absent';
@@ -67,8 +72,9 @@ export type { CompositionPlanResult } from './plan-result.js';
 export declare const PENDING_BLOCK_ID = "(unsaved)";
 /**
  * The static plan. `target` describes an EXISTING target device (one read);
- * it is ignored for a new one. On an existing target each feature REPLACES a
- * cap the device has natively, else ADDS it (D663).
+ * it is ignored for a new one. On an existing target each feature ADDS a cap
+ * the device lacks. A feature that would replace a native capability is
+ * refused by name (D944). A new device is unchanged.
  */
 export declare function planComposition(composition: Composition, lookupCap: CapabilityLookup, target?: CompositionTargetDescription): CompositionPlanResult;
 export declare function compositionSourceRefs(composition: Composition): readonly CompositionSourceRef[];

package/dist/{composition-kEl9mevu.mjs → composition-B85l9j1M.mjs}

@@ -2160,6 +2160,78 @@ function evaluateExpressionSource(expr, bindingValues, now, opts) {
 	}
 }
 //#endregion
+//#region src/composition/source-ref.ts
+/**
+* A composition source identity: `(addonId, stableId)`, never a numeric device
+* id. Split out so helper schemas can name it without a cycle through
+* `composition.ts` (D659).
+*/
+var CompositionSourceRefSchema = z.object({
+	/** The owning addon; `stableId` is unique only within it. */
+	addonId: z.string().min(1),
+	stableId: z.string().min(1)
+});
+//#endregion
+//#region src/composition/helpers/spec.ts
+/**
+* A helper spec is what the editor stores and reads back (D944). The compiled
+* features are a projection; the editor never edits the expression.
+*/
+/** A group may name more members than an expression call (the 16-arg cap). */
+var MAX_HELPER_MEMBERS = 64;
+var GROUP_TEMPLATE_IDS = [
+	"temperature",
+	"humidity",
+	"pressure",
+	"illuminance",
+	"power",
+	"energy",
+	"battery",
+	"numeric",
+	"motion",
+	"contact",
+	"leak",
+	"smoke",
+	"occupancy",
+	"binary"
+];
+var NUMERIC_AGGREGATES = [
+	"mean",
+	"median",
+	"min",
+	"max",
+	"sum"
+];
+var BINARY_AGGREGATES = ["any", "all"];
+var AGGREGATE_REDUCERS = [
+	"mean",
+	"median",
+	"min",
+	"max",
+	"sum",
+	"any",
+	"all"
+];
+var GroupTemplateIdSchema = z.enum(GROUP_TEMPLATE_IDS);
+var AggregateReducerSchema = z.enum(AGGREGATE_REDUCERS);
+/** One member. The field is stored so occupancy can name motion or binary. */
+var HelperMemberSchema = z.object({
+	source: CompositionSourceRefSchema,
+	cap: z.string().min(1),
+	fieldPath: z.string().min(1)
+});
+/**
+* Phase 1a is groups only. Math, integral and statistics stay off this union
+* until the composer can run them — a control must not save a spec it cannot.
+*/
+var GroupHelperSpecSchema = z.object({
+	kind: z.literal("group"),
+	templateId: GroupTemplateIdSchema,
+	aggregate: AggregateReducerSchema,
+	members: z.array(HelperMemberSchema).min(1).max(64)
+});
+var HelperSpecSchema = z.discriminatedUnion("kind", [GroupHelperSpecSchema]);
+//#endregion
 //#region src/composition/composition.ts
 /**
 * A COMPOSITION: a device assembled from other devices' state (D659).
@@ -2195,11 +2267,6 @@ var MAX_COMPOSITION_FEATURES = 16;
 var MAX_COMPOSITION_FIELDS_PER_FEATURE = 32;
 /** Longest snippet a `code` source may carry (slice 4). */
 var MAX_COMPOSITION_CODE_LENGTH = 2e4;
-var CompositionSourceRefSchema = z.object({
-	/** The owning addon; `stableId` is unique only within it. */
-	addonId: z.string().min(1),
-	stableId: z.string().min(1)
-});
 /** One field of one capability of one source device. */
 var CompositionFieldReadSchema = z.object({
 	source: CompositionSourceRefSchema,
@@ -2242,10 +2309,42 @@ var CompositionCodeSourceSchema = z.object({
 	kind: z.literal("code"),
 	code: z.string().min(1).max(MAX_COMPOSITION_CODE_LENGTH)
 });
+/**
+* `aggregate`: a group reducer. Offline and unknown reads are excluded, not
+* folded in as 0 or false (D944). Free expressions stay `expression` so a
+* stale member is still included there.
+*/
+var CompositionAggregateSourceSchema = z.object({
+	kind: z.literal("aggregate"),
+	reducer: z.enum([
+		"mean",
+		"median",
+		"min",
+		"max",
+		"sum",
+		"any",
+		"all"
+	]),
+	reads: z.array(CompositionFieldReadSchema).min(1).max(64),
+	/** `value` is the reading; the others are the member counts. */
+	publish: z.enum([
+		"value",
+		"included",
+		"excluded",
+		"total"
+	]),
+	/** What a `value` publish does when nobody is included. Counts ignore this. */
+	empty: z.enum([
+		"null",
+		"omit",
+		"offline"
+	])
+});
 var CompositionFieldSourceSchema = z.discriminatedUnion("kind", [
 	CompositionFromSourceSchema,
 	CompositionExpressionSourceSchema,
-	CompositionCodeSourceSchema
+	CompositionCodeSourceSchema,
+	CompositionAggregateSourceSchema
 ]);
 /** `forward`: RESERVED for slice 3. Argument mapping arrives there as an additive optional `args`. */
 var CompositionForwardCommandSchema = z.object({
@@ -2311,7 +2410,13 @@ var CompositionExistingTargetSchema = z.object({
 var CompositionTargetSchema = z.discriminatedUnion("kind", [CompositionNewTargetSchema, CompositionExistingTargetSchema]);
 var CompositionSchema = z.object({
 	target: CompositionTargetSchema,
-	features: z.array(CompositionFeatureSchema).min(1).max(16)
+	features: z.array(CompositionFeatureSchema).min(1).max(16),
+	/**
+	* Present when the block is a helper template. Absent on a free
+	* composition (the room example, device 4603). The editor reads this,
+	* never the compiled features.
+	*/
+	helper: HelperSpecSchema.optional()
 }).superRefine((composition, ctx) => {
 	const seen = /* @__PURE__ */ new Set();
 	composition.features.forEach((feature, index) => {
@@ -2358,6 +2463,7 @@ function fieldReads(source) {
 			cap: binding.cap,
 			fieldPath: binding.fieldPath
 		}] : []);
+		case "aggregate": return source.reads;
 		case "code": return [];
 	}
 }
@@ -2384,4 +2490,4 @@ function featureSources(feature) {
 	return featureFieldEntries(feature).map((e) => e.source);
 }
 //#endregion
-export { MAX_EXPRESSION_AST_NODES as $, compositionFeatureEnabled as A, Fmp4BoxSplitter as At, createStatefulExpressionMemory as B, pickVideoEncoder as Bt, CompositionTargetSchema as C, FFMPEG_PATH_ENV as Ct, MAX_COMPOSITION_ITEMS as D, getFfmpegArtifact as Dt, MAX_COMPOSITION_FIELDS_PER_FEATURE as E, FFMPEG_RELEASE as Et, featureFieldEntries as F, buildInputArgs as Ft, createExpressionScope as G, evaluateStatefulExpressionCall as H, featureSources as I, buildVideoArgs as It, compileExpressionSafe as J, evaluateAst as K, fieldReads as L, invocationFromEncodeProfile as Lt, compositionReadKey as M, audioPlanFromEncodeProfile as Mt, compositionSliceKey as N, buildAudioArgs as Nt, composedDeviceRef as O, getFfmpegDownloadUrl as Ot, compositionSourceKey as P, buildFfmpegArgs as Pt, EXPRESSION_IDENTIFIER_RE as Q, EXPRESSION_INJECTED_NOW as R, isSoftwareDecode as Rt, CompositionSourceRefSchema as S, sliceChangedAt as St, MAX_COMPOSITION_FEATURES as T, ffmpegBinaryName as Tt, toExpressionValue as U, evaluateExpressionSource as V, resolveStreamMaps as Vt, validateExpressionSource as W, tokenize as X, parseExpression as Y, EXPRESSION_COMPILE_CACHE_CAPACITY as Z, CompositionItemEntrySchema as _, SOURCE_DEVICE_TYPES as _t, CUSTOMIZATION_BLOCK_NAME_PREFIX as a, EXPRESSION_BUILTINS as at, CompositionPassthroughFeatureSchema as b, isSourceCap as bt, CompositionCommandTargetSchema as c, evaluateCount as ct, CompositionFeatureSchema as d, ExpressionEvalError as dt, MAX_EXPRESSION_BINDINGS as et, CompositionFieldReadSchema as f, ExpressionParseError as ft, CompositionFromSourceSchema as g, SOURCE_CAP_CHANGED_AT_FIELD as gt, CompositionForwardCommandSchema as h, SOURCE_CAP_ACTIVE_FIELD as ht, COMPOSITION_ITEM_KEY_RE as i, RESERVED_BINDING_NAMES as it, compositionItemFieldPath as j, AUDIO_PRESETS as jt, composedDeviceStableId as k, canonicalHash as kt, CompositionExistingTargetSchema as l, evaluateRose as lt, CompositionFieldsFeatureSchema as m, SOURCE_CAPS as mt, COMPOSER_ADDON_ID as n, MAX_EXPRESSION_EVAL_STEPS as nt, CompositionBindingSchema as o, EXPRESSION_BUILTIN_NAMES as ot, CompositionFieldSourceSchema as p, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as pt, compileExpression as q, COMPOSITION_ITEM_ARRAY_PATH as r, MAX_EXPRESSION_SOURCE_LENGTH as rt, CompositionCodeSourceSchema as s, disarmRoseMemory as st, COMPOSED_DEVICE_STABLE_ID_PREFIX as t, MAX_EXPRESSION_CALL_ARGS as tt, CompositionExpressionSourceSchema as u, isStatefulBuiltin as ut, CompositionLiteralBindingSchema as v, evaluateSensorEdge as vt, MAX_COMPOSITION_CODE_LENGTH as w, chooseFfmpegBinary as wt, CompositionSchema as x, sliceActiveValue as xt, CompositionNewTargetSchema as y, evaluateSensorLevelEdge as yt, cloneStatefulExpressionMemory as z, logBannerArgs as zt };
+export { evaluateStatefulExpressionCall as $, compositionFeatureEnabled as A, evaluateSensorLevelEdge as At, BINARY_AGGREGATES as B, canonicalHash as Bt, CompositionTargetSchema as C, ExpressionParseError as Ct, MAX_COMPOSITION_ITEMS as D, SOURCE_CAP_CHANGED_AT_FIELD as Dt, MAX_COMPOSITION_FIELDS_PER_FEATURE as E, SOURCE_CAP_ACTIVE_FIELD as Et, featureFieldEntries as F, chooseFfmpegBinary as Ft, HelperSpecSchema as G, buildFfmpegArgs as Gt, GroupHelperSpecSchema as H, AUDIO_PRESETS as Ht, featureSources as I, ffmpegBinaryName as It, CompositionSourceRefSchema as J, invocationFromEncodeProfile as Jt, MAX_HELPER_MEMBERS as K, buildInputArgs as Kt, fieldReads as L, FFMPEG_RELEASE as Lt, compositionReadKey as M, sliceActiveValue as Mt, compositionSliceKey as N, sliceChangedAt as Nt, composedDeviceRef as O, SOURCE_DEVICE_TYPES as Ot, compositionSourceKey as P, FFMPEG_PATH_ENV as Pt, evaluateExpressionSource as Q, resolveStreamMaps as Qt, AGGREGATE_REDUCERS as R, getFfmpegArtifact as Rt, CompositionSchema as S, ExpressionEvalError as St, MAX_COMPOSITION_FEATURES as T, SOURCE_CAPS as Tt, GroupTemplateIdSchema as U, audioPlanFromEncodeProfile as Ut, GROUP_TEMPLATE_IDS as V, Fmp4BoxSplitter as Vt, HelperMemberSchema as W, buildAudioArgs as Wt, cloneStatefulExpressionMemory as X, logBannerArgs as Xt, EXPRESSION_INJECTED_NOW as Y, isSoftwareDecode as Yt, createStatefulExpressionMemory as Z, pickVideoEncoder as Zt, CompositionFromSourceSchema as _, EXPRESSION_BUILTIN_NAMES as _t, CUSTOMIZATION_BLOCK_NAME_PREFIX as a, compileExpressionSafe as at, CompositionNewTargetSchema as b, evaluateRose as bt, CompositionCodeSourceSchema as c, EXPRESSION_COMPILE_CACHE_CAPACITY as ct, CompositionExpressionSourceSchema as d, MAX_EXPRESSION_BINDINGS as dt, toExpressionValue as et, CompositionFeatureSchema as f, MAX_EXPRESSION_CALL_ARGS as ft, CompositionForwardCommandSchema as g, EXPRESSION_BUILTINS as gt, CompositionFieldsFeatureSchema as h, RESERVED_BINDING_NAMES as ht, COMPOSITION_ITEM_KEY_RE as i, compileExpression as it, compositionItemFieldPath as j, isSourceCap as jt, composedDeviceStableId as k, evaluateSensorEdge as kt, CompositionCommandTargetSchema as l, EXPRESSION_IDENTIFIER_RE as lt, CompositionFieldSourceSchema as m, MAX_EXPRESSION_SOURCE_LENGTH as mt, COMPOSER_ADDON_ID as n, createExpressionScope as nt, CompositionAggregateSourceSchema as o, parseExpression as ot, CompositionFieldReadSchema as p, MAX_EXPRESSION_EVAL_STEPS as pt, NUMERIC_AGGREGATES as q, buildVideoArgs as qt, COMPOSITION_ITEM_ARRAY_PATH as r, evaluateAst as rt, CompositionBindingSchema as s, tokenize as st, COMPOSED_DEVICE_STABLE_ID_PREFIX as t, validateExpressionSource as tt, CompositionExistingTargetSchema as u, MAX_EXPRESSION_AST_NODES as ut, CompositionItemEntrySchema as v, disarmRoseMemory as vt, MAX_COMPOSITION_CODE_LENGTH as w, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as wt, CompositionPassthroughFeatureSchema as x, isStatefulBuiltin as xt, CompositionLiteralBindingSchema as y, evaluateCount as yt, AggregateReducerSchema as z, getFfmpegDownloadUrl as zt };

package/dist/{composition-DsmkwP9-.js → composition-OJKOJJD-.js}

@@ -2160,6 +2160,78 @@ function evaluateExpressionSource(expr, bindingValues, now, opts) {
 	}
 }
 //#endregion
+//#region src/composition/source-ref.ts
+/**
+* A composition source identity: `(addonId, stableId)`, never a numeric device
+* id. Split out so helper schemas can name it without a cycle through
+* `composition.ts` (D659).
+*/
+var CompositionSourceRefSchema = zod.z.object({
+	/** The owning addon; `stableId` is unique only within it. */
+	addonId: zod.z.string().min(1),
+	stableId: zod.z.string().min(1)
+});
+//#endregion
+//#region src/composition/helpers/spec.ts
+/**
+* A helper spec is what the editor stores and reads back (D944). The compiled
+* features are a projection; the editor never edits the expression.
+*/
+/** A group may name more members than an expression call (the 16-arg cap). */
+var MAX_HELPER_MEMBERS = 64;
+var GROUP_TEMPLATE_IDS = [
+	"temperature",
+	"humidity",
+	"pressure",
+	"illuminance",
+	"power",
+	"energy",
+	"battery",
+	"numeric",
+	"motion",
+	"contact",
+	"leak",
+	"smoke",
+	"occupancy",
+	"binary"
+];
+var NUMERIC_AGGREGATES = [
+	"mean",
+	"median",
+	"min",
+	"max",
+	"sum"
+];
+var BINARY_AGGREGATES = ["any", "all"];
+var AGGREGATE_REDUCERS = [
+	"mean",
+	"median",
+	"min",
+	"max",
+	"sum",
+	"any",
+	"all"
+];
+var GroupTemplateIdSchema = zod.z.enum(GROUP_TEMPLATE_IDS);
+var AggregateReducerSchema = zod.z.enum(AGGREGATE_REDUCERS);
+/** One member. The field is stored so occupancy can name motion or binary. */
+var HelperMemberSchema = zod.z.object({
+	source: CompositionSourceRefSchema,
+	cap: zod.z.string().min(1),
+	fieldPath: zod.z.string().min(1)
+});
+/**
+* Phase 1a is groups only. Math, integral and statistics stay off this union
+* until the composer can run them — a control must not save a spec it cannot.
+*/
+var GroupHelperSpecSchema = zod.z.object({
+	kind: zod.z.literal("group"),
+	templateId: GroupTemplateIdSchema,
+	aggregate: AggregateReducerSchema,
+	members: zod.z.array(HelperMemberSchema).min(1).max(64)
+});
+var HelperSpecSchema = zod.z.discriminatedUnion("kind", [GroupHelperSpecSchema]);
+//#endregion
 //#region src/composition/composition.ts
 /**
 * A COMPOSITION: a device assembled from other devices' state (D659).
@@ -2195,11 +2267,6 @@ var MAX_COMPOSITION_FEATURES = 16;
 var MAX_COMPOSITION_FIELDS_PER_FEATURE = 32;
 /** Longest snippet a `code` source may carry (slice 4). */
 var MAX_COMPOSITION_CODE_LENGTH = 2e4;
-var CompositionSourceRefSchema = zod.z.object({
-	/** The owning addon; `stableId` is unique only within it. */
-	addonId: zod.z.string().min(1),
-	stableId: zod.z.string().min(1)
-});
 /** One field of one capability of one source device. */
 var CompositionFieldReadSchema = zod.z.object({
 	source: CompositionSourceRefSchema,
@@ -2242,10 +2309,42 @@ var CompositionCodeSourceSchema = zod.z.object({
 	kind: zod.z.literal("code"),
 	code: zod.z.string().min(1).max(MAX_COMPOSITION_CODE_LENGTH)
 });
+/**
+* `aggregate`: a group reducer. Offline and unknown reads are excluded, not
+* folded in as 0 or false (D944). Free expressions stay `expression` so a
+* stale member is still included there.
+*/
+var CompositionAggregateSourceSchema = zod.z.object({
+	kind: zod.z.literal("aggregate"),
+	reducer: zod.z.enum([
+		"mean",
+		"median",
+		"min",
+		"max",
+		"sum",
+		"any",
+		"all"
+	]),
+	reads: zod.z.array(CompositionFieldReadSchema).min(1).max(64),
+	/** `value` is the reading; the others are the member counts. */
+	publish: zod.z.enum([
+		"value",
+		"included",
+		"excluded",
+		"total"
+	]),
+	/** What a `value` publish does when nobody is included. Counts ignore this. */
+	empty: zod.z.enum([
+		"null",
+		"omit",
+		"offline"
+	])
+});
 var CompositionFieldSourceSchema = zod.z.discriminatedUnion("kind", [
 	CompositionFromSourceSchema,
 	CompositionExpressionSourceSchema,
-	CompositionCodeSourceSchema
+	CompositionCodeSourceSchema,
+	CompositionAggregateSourceSchema
 ]);
 /** `forward`: RESERVED for slice 3. Argument mapping arrives there as an additive optional `args`. */
 var CompositionForwardCommandSchema = zod.z.object({
@@ -2311,7 +2410,13 @@ var CompositionExistingTargetSchema = zod.z.object({
 var CompositionTargetSchema = zod.z.discriminatedUnion("kind", [CompositionNewTargetSchema, CompositionExistingTargetSchema]);
 var CompositionSchema = zod.z.object({
 	target: CompositionTargetSchema,
-	features: zod.z.array(CompositionFeatureSchema).min(1).max(16)
+	features: zod.z.array(CompositionFeatureSchema).min(1).max(16),
+	/**
+	* Present when the block is a helper template. Absent on a free
+	* composition (the room example, device 4603). The editor reads this,
+	* never the compiled features.
+	*/
+	helper: HelperSpecSchema.optional()
 }).superRefine((composition, ctx) => {
 	const seen = /* @__PURE__ */ new Set();
 	composition.features.forEach((feature, index) => {
@@ -2358,6 +2463,7 @@ function fieldReads(source) {
 			cap: binding.cap,
 			fieldPath: binding.fieldPath
 		}] : []);
+		case "aggregate": return source.reads;
 		case "code": return [];
 	}
 }
@@ -2384,12 +2490,30 @@ function featureSources(feature) {
 	return featureFieldEntries(feature).map((e) => e.source);
 }
 //#endregion
+Object.defineProperty(exports, "AGGREGATE_REDUCERS", {
+	enumerable: true,
+	get: function() {
+		return AGGREGATE_REDUCERS;
+	}
+});
 Object.defineProperty(exports, "AUDIO_PRESETS", {
 	enumerable: true,
 	get: function() {
 		return AUDIO_PRESETS;
 	}
 });
+Object.defineProperty(exports, "AggregateReducerSchema", {
+	enumerable: true,
+	get: function() {
+		return AggregateReducerSchema;
+	}
+});
+Object.defineProperty(exports, "BINARY_AGGREGATES", {
+	enumerable: true,
+	get: function() {
+		return BINARY_AGGREGATES;
+	}
+});
 Object.defineProperty(exports, "COMPOSED_DEVICE_STABLE_ID_PREFIX", {
 	enumerable: true,
 	get: function() {
@@ -2420,6 +2544,12 @@ Object.defineProperty(exports, "CUSTOMIZATION_BLOCK_NAME_PREFIX", {
 		return CUSTOMIZATION_BLOCK_NAME_PREFIX;
 	}
 });
+Object.defineProperty(exports, "CompositionAggregateSourceSchema", {
+	enumerable: true,
+	get: function() {
+		return CompositionAggregateSourceSchema;
+	}
+});
 Object.defineProperty(exports, "CompositionBindingSchema", {
 	enumerable: true,
 	get: function() {
@@ -2594,6 +2724,36 @@ Object.defineProperty(exports, "Fmp4BoxSplitter", {
 		return Fmp4BoxSplitter;
 	}
 });
+Object.defineProperty(exports, "GROUP_TEMPLATE_IDS", {
+	enumerable: true,
+	get: function() {
+		return GROUP_TEMPLATE_IDS;
+	}
+});
+Object.defineProperty(exports, "GroupHelperSpecSchema", {
+	enumerable: true,
+	get: function() {
+		return GroupHelperSpecSchema;
+	}
+});
+Object.defineProperty(exports, "GroupTemplateIdSchema", {
+	enumerable: true,
+	get: function() {
+		return GroupTemplateIdSchema;
+	}
+});
+Object.defineProperty(exports, "HelperMemberSchema", {
+	enumerable: true,
+	get: function() {
+		return HelperMemberSchema;
+	}
+});
+Object.defineProperty(exports, "HelperSpecSchema", {
+	enumerable: true,
+	get: function() {
+		return HelperSpecSchema;
+	}
+});
 Object.defineProperty(exports, "MAX_COMPOSITION_CODE_LENGTH", {
 	enumerable: true,
 	get: function() {
@@ -2648,6 +2808,18 @@ Object.defineProperty(exports, "MAX_EXPRESSION_SOURCE_LENGTH", {
 		return MAX_EXPRESSION_SOURCE_LENGTH;
 	}
 });
+Object.defineProperty(exports, "MAX_HELPER_MEMBERS", {
+	enumerable: true,
+	get: function() {
+		return MAX_HELPER_MEMBERS;
+	}
+});
+Object.defineProperty(exports, "NUMERIC_AGGREGATES", {
+	enumerable: true,
+	get: function() {
+		return NUMERIC_AGGREGATES;
+	}
+});
 Object.defineProperty(exports, "RESERVED_BINDING_NAMES", {
 	enumerable: true,
 	get: function() {

package/dist/device/cap-vocabulary/entries/sensors.d.ts

@@ -1,5 +1,5 @@
 import type { CapVocabularySlice } from '../types.js';
-type SensorCap = 'air-quality-sensor' | 'ambient-light-sensor' | 'binary' | 'carbon-monoxide' | 'connectivity' | 'contact' | 'enum-sensor' | 'flood' | 'gas' | 'humidity-sensor' | 'motion' | 'numeric-sensor' | 'power-meter' | 'presence' | 'pressure-sensor' | 'smoke' | 'tamper' | 'temperature-sensor' | 'vibration' | 'weather' | 'battery' | 'network-link' | 'device-status' | 'doorbell' | 'event-emitter';
+type SensorCap = 'air-quality-sensor' | 'ambient-light-sensor' | 'binary' | 'carbon-monoxide' | 'connectivity' | 'contact' | 'enum-sensor' | 'flood' | 'gas' | 'group-status' | 'humidity-sensor' | 'motion' | 'numeric-sensor' | 'power-meter' | 'presence' | 'pressure-sensor' | 'smoke' | 'tamper' | 'temperature-sensor' | 'vibration' | 'weather' | 'battery' | 'network-link' | 'device-status' | 'doorbell' | 'event-emitter';
 /** The sensor family of the vocabulary. */
 export declare const SENSOR_CAP_VOCABULARY: CapVocabularySlice<SensorCap>;
 export {};

package/dist/device/cap-vocabulary/types.d.ts

@@ -179,9 +179,9 @@ export interface NumericStateTrigger<C extends VocabCapName> {
     /** The quantity WITH its article, as it reads in a sentence ("the temperature" / "la temperatura"). */
     readonly quantity: L10n;
     readonly label: L10n;
-    /** Display unit; omit when the device states it (see `unitField`). */
+    /** Display unit. The stored number is the quantity base; this is the label. */
     readonly unit?: string;
-    /** A status field carrying the device's own unit (`numeric-sensor.unit`). */
+    /** @deprecated D944 removed slice unit siblings. Kept so old rows still parse. */
     readonly unitField?: CapStatusField<C>;
     readonly icon: VocabIcon;
 }

package/dist/device/schema-fields.d.ts

@@ -1,8 +1,11 @@
 import { z } from 'zod';
+import { type ReadingQuantity } from '../units/quantity.js';
 export interface WireableField {
     readonly path: string;
     readonly kind: 'string' | 'number' | 'boolean' | 'enum';
     readonly enumValues?: readonly string[];
+    /** Quantity of a numeric reading, when the schema declares one. */
+    readonly quantity?: ReadingQuantity;
     /** True when `path` is relative to ONE item of an item-array cap (see
      *  `CapabilityStatusItemArray`) — a link targeting it must carry a
      *  `target.itemKey`. Absent/false for plain status fields. */

package/dist/device/source-info.d.ts

@@ -17,12 +17,12 @@ import { z } from 'zod';
  *      providers detect renames by matching `uniqueId` and patch `id`
  *      in-place so dispatch keeps working.
  *
- * **Rendering metadata is NOT stored here.** Display fields (`unit`,
- * `precision`) live in the cap STATUS SLICE so they flow live with every
- * state push and are the single source of truth. The `device_class` tag is
- * an HA-specific input that is consumed at the discovery boundary
- * (`ha-domain-mapping`) to derive the CamStack `DeviceRole`; it is never
- * stored after that point.
+ * **Display unit and precision are NOT stored here.** They are a read-time
+ * preference (D944). A polymorphic reading stores its `quantity` here once,
+ * at adopt, and a date/time value stores `dateTimeShape` the same way —
+ * neither is repeated on each sample. The `device_class` tag is an
+ * HA-specific input consumed at the discovery boundary (`ha-domain-mapping`)
+ * to derive the CamStack `DeviceRole`; it is never stored after that point.
  *
  * The `raw` escape hatch carries provider-specific attributes that don't
  * fit the structured slots (HA `attributes` whitelist, Reolink `deviceCache`
@@ -32,6 +32,12 @@ export declare const SourceInfoSchema: z.ZodObject<{
     id: z.ZodString;
     system: z.ZodString;
     uniqueId: z.ZodOptional<z.ZodString>;
+    quantity: z.ZodOptional<z.ZodType<"angle" | "apparent-power" | "area" | "bitrate" | "colour-temperature" | "concentration-mass" | "concentration-ppb" | "concentration-volume" | "count" | "current" | "device" | "duration" | "duration-ms" | "energy" | "humidity" | "illuminance" | "index" | "information" | "irradiance" | "length" | "mass" | "none" | "percentage" | "power" | "precipitation" | "precipitation-rate" | "pressure" | "rate" | "ratio" | "signal-level" | "sound-level" | "speed" | "temperature" | "voltage" | "volume", unknown, z.core.$ZodTypeInternals<"angle" | "apparent-power" | "area" | "bitrate" | "colour-temperature" | "concentration-mass" | "concentration-ppb" | "concentration-volume" | "count" | "current" | "device" | "duration" | "duration-ms" | "energy" | "humidity" | "illuminance" | "index" | "information" | "irradiance" | "length" | "mass" | "none" | "percentage" | "power" | "precipitation" | "precipitation-rate" | "pressure" | "rate" | "ratio" | "signal-level" | "sound-level" | "speed" | "temperature" | "voltage" | "volume", unknown>>>;
+    dateTimeShape: z.ZodOptional<z.ZodEnum<{
+        date: "date";
+        datetime: "datetime";
+        time: "time";
+    }>>;
     raw: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 export type SourceInfo = z.infer<typeof SourceInfoSchema>;

package/dist/generated/addon-api.d.ts

@@ -3843,6 +3843,20 @@ export type AppRouter = TrpcCoreRouter<{
             meta: object;
         }>;
     }>>;
+    groupStatus: TRPCBuiltRouter<{
+        ctx: TrpcContext;
+        meta: object;
+        errorShape: AugmentedErrorShape;
+        transformer: true;
+    }, TRPCDecorateCreateRouterOptions<{
+        getStatus: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof DEVICE_STATUS_METHOD.getStatus.input>;
+            output: z.infer<typeof DEVICE_STATUS_METHOD.getStatus.output>;
+            meta: object;
+        }>;
+    }>>;
     heatingValve: TRPCBuiltRouter<{
         ctx: TrpcContext;
         meta: object;