@camstack/types 1.2.263 → 1.2.265

package/dist/composition/examples.d.ts

@@ -0,0 +1,10 @@
+import { type Composition, type CompositionSourceRef } from './composition.js';
+export declare const ROOM_OCCUPANCY_WINDOW_MS = 300000;
+export declare const ROOM_EXAMPLE_TEMPERATURE_SOURCES: readonly CompositionSourceRef[];
+export declare const ROOM_EXAMPLE_MOTION_SOURCES: readonly CompositionSourceRef[];
+export interface RoomExampleInput {
+    readonly temperatureSources: readonly CompositionSourceRef[];
+    readonly motionSources: readonly CompositionSourceRef[];
+    readonly occupancyWindowMs: number;
+}
+export declare function roomCompositionExample(input: RoomExampleInput): Composition;

package/dist/composition/expression-kinds.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What an expression can PRODUCE: the static half of type validation at save
+ * (D659). The language is untyped at runtime; this walk gives the set of value
+ * kinds the result may take, so a save that would write a string into
+ * `celsius`, or a possible null into a non-nullable field, is refused by name
+ * before it is stored.
+ */
+import type { ExpressionValue } from '../expression/ast.js';
+export type ExpressionValueKind = 'number' | 'string' | 'boolean' | 'null';
+export type ExpressionKindSet = ReadonlySet<ExpressionValueKind>;
+export interface FixedKindRule {
+    readonly kind: 'fixed';
+    readonly result: readonly ExpressionValueKind[];
+}
+/** `coalesce`: the first non-null argument, null only when every argument may be null. */
+export interface CoalesceKindRule {
+    readonly kind: 'coalesce';
+}
+export type BuiltinKindRule = FixedKindRule | CoalesceKindRule;
+/** One rule per builtin. `expression-kinds.spec.ts` fails for a builtin missing here. */
+export declare const BUILTIN_RESULT_KINDS: Readonly<Record<string, BuiltinKindRule>>;
+export interface InferExpressionKindsInput {
+    readonly expr: string;
+    readonly bindingKinds: ReadonlyMap<string, ExpressionKindSet>;
+}
+export interface InferredKinds {
+    readonly ok: true;
+    readonly kinds: ExpressionKindSet;
+}
+export interface InferenceFailure {
+    readonly ok: false;
+    readonly error: string;
+}
+export type InferExpressionKindsResult = InferredKinds | InferenceFailure;
+export declare function kindOfValue(value: ExpressionValue): ExpressionValueKind;
+export declare function inferExpressionKinds(input: InferExpressionKindsInput): InferExpressionKindsResult;

package/dist/composition/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compositions: composed devices (D659). This is the module barrel; leaf files
+ * inside @camstack/types import the deep modules, never this file.
+ */
+export * from './composition.js';
+export * from './composition-graph.js';
+export * from './composition-report.js';
+export * from './evaluate-field.js';
+export * from './examples.js';
+export * from './expression-kinds.js';
+export * from './state-fields.js';
+export * from './validate-composition.js';

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

@@ -0,0 +1,19 @@
+/**
+ * What a capability's state field IS: kind, nullability, whether required. The
+ * validator needs nullability, which `enumerateSchemaFields` does not report,
+ * and that decides a field's unavailable mode (D393).
+ */
+import { z } from 'zod';
+import { type WireableField } from '../device/schema-fields.js';
+export interface StateFieldDescription {
+    readonly path: string;
+    readonly kind: WireableField['kind'];
+    readonly nullable: boolean;
+    readonly required: boolean;
+    /** Present only when `kind === 'enum'` — the closed set of strings the field accepts. */
+    readonly enumValues?: readonly string[];
+}
+export declare function describeStateField(schema: z.ZodType, path: string): StateFieldDescription | null;
+export declare function describeTopLevelStateFields(schema: z.ZodType): ReadonlyMap<string, StateFieldDescription>;
+/** Top-level keys a value MUST carry: those whose schema refuses `undefined`. */
+export declare function requiredTopLevelKeys(schema: z.ZodType): readonly string[];

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

@@ -0,0 +1,46 @@
+/**
+ * Save-time validation of a composition (D659): shape, capability fit, field
+ * kinds, nullability, sources, cycles. Every refusal names its reason (D391),
+ * and every variant a later slice implements is refused BY NAME with that slice.
+ *
+ * Pure: the caller DESCRIBES the sources (one read each) and passes the other
+ * stored compositions. `planComposition` is the static half the composer
+ * re-runs at apply time, where the sources are the tracker's business.
+ */
+import type { CapabilityDefinition } from '../capabilities/capability-definition.js';
+import { type Composition, type CompositionSourceRef } from './composition.js';
+import { type CompositionPeer } from './composition-graph.js';
+import type { CompositionFieldPlan, CompositionProblem, CompositionValidation } from './composition-report.js';
+export type CapabilityLookup = (capName: string) => CapabilityDefinition | null;
+export declare function buildCapabilityLookup(defs: readonly CapabilityDefinition[]): CapabilityLookup;
+/** Caps every `BaseDevice` registers on itself; a second registration throws. */
+export declare const BASE_DEVICE_CAPS: ReadonlySet<string>;
+export interface CompositionSourceFound {
+    readonly kind: 'found';
+    readonly deviceId: number;
+    readonly caps: ReadonlySet<string>;
+}
+export interface CompositionSourceAbsent {
+    readonly kind: 'absent';
+}
+export interface CompositionSourceUnreadable {
+    readonly kind: 'unreadable';
+    readonly error: string;
+}
+export type CompositionSourceDescription = CompositionSourceFound | CompositionSourceAbsent | CompositionSourceUnreadable;
+export interface ValidateCompositionContext {
+    readonly lookupCap: CapabilityLookup;
+    /** Keyed by `compositionSourceKey`. A ref with no entry was not read, and is refused as unreadable. */
+    readonly sources: ReadonlyMap<string, CompositionSourceDescription>;
+    /** The device this composition writes; null on create, when the block has no id yet. */
+    readonly self: CompositionSourceRef | null;
+    /** Every OTHER stored composition; cycles run through them. */
+    readonly peers: readonly CompositionPeer[];
+}
+export interface CompositionPlanResult {
+    readonly problems: readonly CompositionProblem[];
+    readonly fields: readonly CompositionFieldPlan[];
+}
+export declare function planComposition(composition: Composition, lookupCap: CapabilityLookup): CompositionPlanResult;
+export declare function compositionSourceRefs(composition: Composition): readonly CompositionSourceRef[];
+export declare function validateComposition(composition: Composition, ctx: ValidateCompositionContext): CompositionValidation;

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

@@ -8,6 +8,9 @@ export interface WireableField {
      *  `target.itemKey`. Absent/false for plain status fields. */
     readonly item?: boolean;
 }
+/** Unwrap ZodNullable / ZodOptional / ZodDefault wrappers to reach the inner type.
+ *  Zod v4 exposes `.unwrap()` on all three wrapper classes. */
+export declare function unwrapSchema(schema: z.ZodType): z.ZodType;
 /** Walk a cap status schema into flat wireable leaf fields (dotted paths).
  *  Recurses into nested ZodObject (unwrapping nullable/optional/default first),
  *  so fields with null live values are still offered. Arrays / unknown shapes

package/dist/expression/builtins.d.ts

@@ -1,10 +1,38 @@
+/**
+ * Frozen, null-prototype builtin function table for the expression engine
+ * (spec §4 rule 4). The table is the SOLE surface of callable functions: the
+ * parser rejects any callee not in it, and the evaluator gates each call on an
+ * own-property check against it.
+ *
+ * Because the object has a NULL prototype AND is `Object.freeze`d:
+ *  - it cannot be polluted (no `__proto__` / `constructor` write reaches it);
+ *  - a lookup for `toString` / `hasOwnProperty` / `constructor` finds NOTHING
+ *    (there is no `Object.prototype` in the chain), so those names are not
+ *    callable — they are simply "unknown function" at parse time.
+ *
+ * Every numeric argument is validated as a finite number and every numeric
+ * RESULT is re-checked finite, so `/0`, `sqrt(-1)` (→ NaN) and overflow
+ * (`pow(10,400)` → Infinity) all raise `ExpressionEvalError` and fail the link
+ * closed rather than emitting a garbage value.
+ */
 import type { ExpressionValue } from './ast.js';
-/** Optional runtime hooks the evaluator threads through to builtins. Stage U
- *  installs the real unit-conversion table here; absent → the `convert` stub. */
+/** Optional runtime hooks the evaluator threads through to builtins. */
 export interface ExpressionEvalHooks {
     /** Convert `value` from unit `from` to unit `to`; `null` when the pair is
      *  not convertible. Absent hook → `convert` uses its identity-only stub. */
     readonly convert?: (value: number, from: string, to: string) => number | null;
+    /**
+     * Epoch ms of THIS evaluation. `evaluateExpressionSource` sets it to the same
+     * `now` the scope carries. A windowed builtin with no clock fails closed:
+     * reading the wall clock here would make an evaluation unrepeatable.
+     */
+    readonly now?: number;
+    /**
+     * Called by a windowed builtin with the instant its answer will change ON ITS
+     * OWN, with no source event. The composer arms ONE timer at the earliest such
+     * instant. That is a deadline, never a poll (D659).
+     */
+    readonly noteDeadline?: (at: number) => void;
 }
 export interface ExpressionBuiltin {
     readonly minArgs: number;

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

@@ -27,6 +27,7 @@ import type { cameraGridLayoutCapability } from '../capabilities/camera-grid-lay
 import type { cameraStreamsCapability } from '../capabilities/camera-streams.cap.js';
 import type { climateControlCapability } from '../capabilities/climate-control.cap.js';
 import type { colorCapability } from '../capabilities/color.cap.js';
+import type { composerCapability } from '../capabilities/composer.cap.js';
 import type { connectionTestCapability } from '../capabilities/connection-test.cap.js';
 import type { consumablesCapability } from '../capabilities/consumables.cap.js';
 import type { controlCapability } from '../capabilities/control.cap.js';
@@ -1413,6 +1414,27 @@ export type AppRouter = TrpcCoreRouter<{
             meta: object;
         }>;
     }>>;
+    composer: TRPCBuiltRouter<{
+        ctx: TrpcContext;
+        meta: object;
+        errorShape: AugmentedErrorShape;
+        transformer: true;
+    }, TRPCDecorateCreateRouterOptions<{
+        applyBlocks: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof composerCapability.methods.applyBlocks.input>;
+            output: z.infer<typeof composerCapability.methods.applyBlocks.output>;
+            meta: object;
+        }>;
+        getStates: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof composerCapability.methods.getStates.input>;
+            output: z.infer<typeof composerCapability.methods.getStates.output>;
+            meta: object;
+        }>;
+    }>>;
     connectionTest: TRPCBuiltRouter<{
         ctx: TrpcContext;
         meta: object;
@@ -1574,6 +1596,41 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof coreBlocksCapability.methods.getTypeDefs.output>;
             meta: object;
         }>;
+        createComposition: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof coreBlocksCapability.methods.createComposition.input>;
+            output: z.infer<typeof coreBlocksCapability.methods.createComposition.output>;
+            meta: object;
+        }>;
+        updateComposition: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof coreBlocksCapability.methods.updateComposition.input>;
+            output: z.infer<typeof coreBlocksCapability.methods.updateComposition.output>;
+            meta: object;
+        }>;
+        getComposition: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof coreBlocksCapability.methods.getComposition.input>;
+            output: z.infer<typeof coreBlocksCapability.methods.getComposition.output>;
+            meta: object;
+        }>;
+        listCompositions: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof coreBlocksCapability.methods.listCompositions.input>;
+            output: z.infer<typeof coreBlocksCapability.methods.listCompositions.output>;
+            meta: object;
+        }>;
+        validateComposition: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof coreBlocksCapability.methods.validateComposition.input>;
+            output: z.infer<typeof coreBlocksCapability.methods.validateComposition.output>;
+            meta: object;
+        }>;
     }>>;
     cover: TRPCBuiltRouter<{
         ctx: TrpcContext;

package/dist/generated/capability-router-map.d.ts

@@ -30,6 +30,7 @@ export { cameraStreamsCapability } from '../capabilities/camera-streams.cap.js';
 export { carbonMonoxideCapability } from '../capabilities/carbon-monoxide.cap.js';
 export { climateControlCapability } from '../capabilities/climate-control.cap.js';
 export { colorCapability } from '../capabilities/color.cap.js';
+export { composerCapability } from '../capabilities/composer.cap.js';
 export { connectionTestCapability } from '../capabilities/connection-test.cap.js';
 export { connectivityCapability } from '../capabilities/connectivity.cap.js';
 export { consumablesCapability } from '../capabilities/consumables.cap.js';
@@ -192,6 +193,7 @@ export declare const CAPABILITY_NAMES: {
     readonly carbonMonoxide: "carbon-monoxide";
     readonly climateControl: "climate-control";
     readonly color: "color";
+    readonly composer: "composer";
     readonly connectionTest: "connection-test";
     readonly connectivity: "connectivity";
     readonly consumables: "consumables";
@@ -367,6 +369,7 @@ export interface CapabilityRouterMap<TRouter = unknown> {
     readonly carbonMonoxide: TRouter;
     readonly climateControl: TRouter;
     readonly color: TRouter;
+    readonly composer: TRouter;
     readonly connectionTest: TRouter;
     readonly connectivity: TRouter;
     readonly consumables: TRouter;
@@ -497,8 +500,8 @@ export interface CapabilityRouterMap<TRouter = unknown> {
     readonly zoneRules: TRouter;
     readonly zones: TRouter;
 }
-/** Capability names whose mode is `singleton` (130 caps). */
-export declare const SINGLETON_CAPABILITY_NAMES: readonly ["accessories", "addon-pages", "addon-settings", "addon-widgets", "addons", "admin-ui", "air-quality-sensor", "alarm-panel", "alerts", "ambient-light-sensor", "audio-analysis", "audio-analyzer", "audio-codec", "audio-metrics", "automation-control", "backup", "battery", "binary", "brightness", "button", "camera-credentials", "camera-grid-layout", "camera-pipeline-config", "camera-streams", "carbon-monoxide", "climate-control", "color", "connectivity", "consumables", "contact", "control", "core-blocks", "cover", "day-night", "decoder", "detection-pipeline", "device-admin-link", "device-adoption", "device-discovery", "device-manager", "device-ops", "device-state", "device-status", "doorbell", "enum-sensor", "event-emitter", "face-gallery", "fan-control", "feature-probe", "filesystem-browse", "flood", "gas", "humidifier", "humidity-sensor", "image", "image-settings", "integrations", "intercom", "lawn-mower-control", "llm-runtime", "local-network", "lock-control", "media-player", "metrics-provider", "model-convert", "model-distributor", "motion", "motion-detection", "motion-trigger", "motion-zones", "native-object-detection", "navigation", "network-link", "network-quality", "nodes", "notification-rules", "notifier", "numeric-sensor", "osd", "osd-manager", "pet-feeder", "pipeline-analytics", "pipeline-executor", "pipeline-orchestrator", "pipeline-runner", "plate-gallery", "platform-probe", "power-meter", "presence", "pressure-sensor", "privacy-mask", "ptz", "ptz-autotrack", "reboot", "recording-archive", "recording-export", "recording-onboard", "recording-signal", "scene-monitor", "script-runner", "server-management", "settings-store", "smoke", "snapshot", "sso-bridge", "storage", "storage-migration", "stream-broker", "stream-catalog", "stream-params", "stream-signals", "switch", "system", "tamper", "temperature-sensor", "terminal-session", "toast", "update", "user-management", "vacuum-control", "valve", "vector-store", "vibration", "viewer-ui", "water-heater", "weather", "webrtc-session", "zone-analytics", "zone-rules", "zones"];
+/** Capability names whose mode is `singleton` (131 caps). */
+export declare const SINGLETON_CAPABILITY_NAMES: readonly ["accessories", "addon-pages", "addon-settings", "addon-widgets", "addons", "admin-ui", "air-quality-sensor", "alarm-panel", "alerts", "ambient-light-sensor", "audio-analysis", "audio-analyzer", "audio-codec", "audio-metrics", "automation-control", "backup", "battery", "binary", "brightness", "button", "camera-credentials", "camera-grid-layout", "camera-pipeline-config", "camera-streams", "carbon-monoxide", "climate-control", "color", "composer", "connectivity", "consumables", "contact", "control", "core-blocks", "cover", "day-night", "decoder", "detection-pipeline", "device-admin-link", "device-adoption", "device-discovery", "device-manager", "device-ops", "device-state", "device-status", "doorbell", "enum-sensor", "event-emitter", "face-gallery", "fan-control", "feature-probe", "filesystem-browse", "flood", "gas", "humidifier", "humidity-sensor", "image", "image-settings", "integrations", "intercom", "lawn-mower-control", "llm-runtime", "local-network", "lock-control", "media-player", "metrics-provider", "model-convert", "model-distributor", "motion", "motion-detection", "motion-trigger", "motion-zones", "native-object-detection", "navigation", "network-link", "network-quality", "nodes", "notification-rules", "notifier", "numeric-sensor", "osd", "osd-manager", "pet-feeder", "pipeline-analytics", "pipeline-executor", "pipeline-orchestrator", "pipeline-runner", "plate-gallery", "platform-probe", "power-meter", "presence", "pressure-sensor", "privacy-mask", "ptz", "ptz-autotrack", "reboot", "recording-archive", "recording-export", "recording-onboard", "recording-signal", "scene-monitor", "script-runner", "server-management", "settings-store", "smoke", "snapshot", "sso-bridge", "storage", "storage-migration", "stream-broker", "stream-catalog", "stream-params", "stream-signals", "switch", "system", "tamper", "temperature-sensor", "terminal-session", "toast", "update", "user-management", "vacuum-control", "valve", "vector-store", "vibration", "viewer-ui", "water-heater", "weather", "webrtc-session", "zone-analytics", "zone-rules", "zones"];
 /** Union of singleton capability names (literal string union). */
 export type SingletonCapabilityName = typeof SINGLETON_CAPABILITY_NAMES[number];
 /** Capability names whose mode is `collection` (31 caps). */

package/dist/generated/method-access-map.d.ts

@@ -6,7 +6,7 @@
  * scope+access check inside `protectedProcedure` (see
  * `server/backend/src/api/trpc/trpc.middleware.ts`).
  *
- * Coverage: 1178 method paths across 161 capabilities.
+ * Coverage: 1185 method paths across 162 capabilities.
  */
 import type { CapabilityMethodAccess } from '../capabilities/capability-definition.js';
 export interface MethodAccessRecord {

package/dist/generated/system-proxy.d.ts

@@ -65,7 +65,7 @@ export interface SystemProxy {
     readonly backup: Pick<InferProvider<typeof backupCapability>, 'listDestinations' | 'trigger' | 'listRuns' | 'cancel' | 'list' | 'listLocations' | 'getEntries' | 'restore' | 'delete' | 'listArchives' | 'upsertDestinationPolicy' | 'previewSchedule' | 'listSchedules' | 'upsertSchedule' | 'deleteSchedule'>;
     readonly broker: Pick<InferProvider<typeof brokerCapability>, 'list' | 'get' | 'listProviders' | 'add' | 'remove' | 'testConnection' | 'getSettings' | 'setSettings' | 'getBrokerConfig' | 'getSettingsSchema' | 'testSettings' | 'publish' | 'subscribe' | 'unsubscribe' | 'getState' | 'getStatus'>;
     readonly connectionTest: Pick<InferProvider<typeof connectionTestCapability>, 'testSettings' | 'describeTest'>;
-    readonly coreBlocks: Pick<InferProvider<typeof coreBlocksCapability>, 'list' | 'get' | 'create' | 'update' | 'delete' | 'setEnabled' | 'restart' | 'compile' | 'getTypeDefs'>;
+    readonly coreBlocks: Pick<InferProvider<typeof coreBlocksCapability>, 'list' | 'get' | 'create' | 'update' | 'delete' | 'setEnabled' | 'restart' | 'compile' | 'getTypeDefs' | 'createComposition' | 'updateComposition' | 'getComposition' | 'listCompositions' | 'validateComposition'>;
     readonly decoder: Pick<InferProvider<typeof decoderCapability>, 'supportsCodec' | 'getInfo' | 'createSession' | 'destroySession' | 'pushPacket' | 'openStream' | 'pullFrames' | 'pullHandles' | 'getFrame' | 'getShmStats' | 'updateConfig' | 'getStats' | 'listActiveSessions' | 'reprobeHwaccel'>;
     readonly deviceAdoption: Pick<InferProvider<typeof deviceAdoptionCapability>, 'listCandidateFilters' | 'listCandidates' | 'getCandidate' | 'refresh' | 'adopt' | 'release' | 'resync'>;
     readonly deviceExport: Pick<InferProvider<typeof deviceExportCapability>, 'getStatus' | 'listSupportedDeviceKinds' | 'listExposedDevices' | 'exposeDevice' | 'unexposeDevice'>;

package/dist/index.d.ts

@@ -143,6 +143,7 @@ export { AutomationActionSchema, AutomationConditionOperatorSchema, AutomationCo
 export * from './cap-call-context.js';
 export * from './capabilities/index.js';
 export * from './device-extension/index.js';
+export * from './composition/index.js';
 export { APPLE_SA_TO_MACRO, AUDIO_MACRO_LABELS, getAudioMacroClassIds, mapAudioLabelToMacro, YAMNET_TO_MACRO, } from './catalogs/audio-classmap.js';
 export { COCO_80_LABELS, COCO_TO_MACRO, DETECTION_MACRO_CLASSES, isDetectionMacroClass, MACRO_LABELS, } from './catalogs/coco-classmap.js';
 export { DEVICE_STATE_READERS, readDeviceStateFrom, stateVocabularyFor, } from './catalogs/device-state-vocabulary.js';