@camstack/types 1.2.268 → 1.2.270

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

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import type { CapabilityDefinition } from '../capabilities/capability-definition.js';
+import { EventCategory } from '../enums/event-category.js';
+export declare const COMPOSITION_EVENT_CATEGORY: {
+    readonly 'doorbell.onPressed': EventCategory.DoorbellOnPressed;
+};
+export declare const CompositionEventPlanSchema: z.ZodObject<{
+    featureIndex: z.ZodNumber;
+    cap: z.ZodString;
+    eventName: z.ZodString;
+    category: z.ZodEnum<typeof EventCategory>;
+    stateField: z.ZodString;
+    fieldKey: z.ZodString;
+}, z.core.$strip>;
+export type CompositionEventPlan = z.infer<typeof CompositionEventPlanSchema>;
+type EventProblemCode = 'unknown-field' | 'kind-mismatch' | 'not-composable';
+export interface CompositionEventProblem {
+    readonly code: EventProblemCode;
+    readonly path: string;
+    readonly message: string;
+}
+export interface CompositionEventFeatureInput {
+    readonly featureIndex: number;
+    readonly cap: string;
+    readonly mode: 'new' | 'add' | 'replace';
+}
+export interface CompositionEventFieldInput {
+    readonly featureIndex: number;
+    readonly cap: string;
+    readonly path: string;
+    readonly item?: unknown;
+}
+export interface CompositionEventPlanningResult {
+    readonly problems: readonly CompositionEventProblem[];
+    readonly events: readonly CompositionEventPlan[];
+}
+/**
+ * Plan one capability's state-derived events after its feature mode and fields
+ * are known. A native replacement never becomes a second event authority.
+ */
+export declare function planCompositionEvents(def: CapabilityDefinition, feature: CompositionEventFeatureInput, fields: readonly CompositionEventFieldInput[]): CompositionEventPlanningResult;
+export {};

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

@@ -5,15 +5,15 @@
 import { z } from 'zod';
 export declare const CompositionProblemCodeSchema: z.ZodEnum<{
     "source-missing": "source-missing";
+    "unknown-field": "unknown-field";
+    "kind-mismatch": "kind-mismatch";
+    "not-composable": "not-composable";
     "reserved-variant": "reserved-variant";
     "unknown-capability": "unknown-capability";
-    "not-composable": "not-composable";
     "wrong-device-type": "wrong-device-type";
     "has-commands": "has-commands";
-    "unknown-field": "unknown-field";
     "nested-field": "nested-field";
     "missing-field": "missing-field";
-    "kind-mismatch": "kind-mismatch";
     "may-be-null": "may-be-null";
     "source-unreadable": "source-unreadable";
     "source-capability-missing": "source-capability-missing";
@@ -32,15 +32,15 @@ export type CompositionProblemCode = z.infer<typeof CompositionProblemCodeSchema
 export declare const CompositionProblemSchema: z.ZodObject<{
     code: z.ZodEnum<{
         "source-missing": "source-missing";
+        "unknown-field": "unknown-field";
+        "kind-mismatch": "kind-mismatch";
+        "not-composable": "not-composable";
         "reserved-variant": "reserved-variant";
         "unknown-capability": "unknown-capability";
-        "not-composable": "not-composable";
         "wrong-device-type": "wrong-device-type";
         "has-commands": "has-commands";
-        "unknown-field": "unknown-field";
         "nested-field": "nested-field";
         "missing-field": "missing-field";
-        "kind-mismatch": "kind-mismatch";
         "may-be-null": "may-be-null";
         "source-unreadable": "source-unreadable";
         "source-capability-missing": "source-capability-missing";
@@ -80,12 +80,14 @@ export declare const CompositionUnavailableModeSchema: z.ZodEnum<{
 export type CompositionUnavailableMode = z.infer<typeof CompositionUnavailableModeSchema>;
 /**
  * `derived` reads a source · `clock` reads only `now`, recomputed when a sibling
- * field of its cap changes value · `constant` reads nothing, computed once.
+ * field of its cap changes value · `constant` reads nothing, computed once ·
+ * `accumulator` advances from the target's seed/current output.
  */
 export declare const CompositionFieldRoleSchema: z.ZodEnum<{
     derived: "derived";
     clock: "clock";
     constant: "constant";
+    accumulator: "accumulator";
 }>;
 export type CompositionFieldRole = z.infer<typeof CompositionFieldRoleSchema>;
 /** The item a planned field belongs to; its `path` is then the dotted path INSIDE the item. */
@@ -122,6 +124,7 @@ export declare const CompositionFieldPlanSchema: z.ZodObject<{
         derived: "derived";
         clock: "clock";
         constant: "constant";
+        accumulator: "accumulator";
     }>;
     source: z.ZodDiscriminatedUnion<[z.ZodObject<{
         source: z.ZodObject<{
@@ -188,15 +191,15 @@ export declare const CompositionValidationSchema: z.ZodObject<{
     problems: z.ZodArray<z.ZodObject<{
         code: z.ZodEnum<{
             "source-missing": "source-missing";
+            "unknown-field": "unknown-field";
+            "kind-mismatch": "kind-mismatch";
+            "not-composable": "not-composable";
             "reserved-variant": "reserved-variant";
             "unknown-capability": "unknown-capability";
-            "not-composable": "not-composable";
             "wrong-device-type": "wrong-device-type";
             "has-commands": "has-commands";
-            "unknown-field": "unknown-field";
             "nested-field": "nested-field";
             "missing-field": "missing-field";
-            "kind-mismatch": "kind-mismatch";
             "may-be-null": "may-be-null";
             "source-unreadable": "source-unreadable";
             "source-capability-missing": "source-capability-missing";
@@ -240,6 +243,7 @@ export declare const CompositionValidationSchema: z.ZodObject<{
             derived: "derived";
             clock: "clock";
             constant: "constant";
+            accumulator: "accumulator";
         }>;
         source: z.ZodDiscriminatedUnion<[z.ZodObject<{
             source: z.ZodObject<{
@@ -286,6 +290,14 @@ export declare const CompositionValidationSchema: z.ZodObject<{
             add: "add";
         }>;
     }, z.core.$strip>>;
+    events: z.ZodArray<z.ZodObject<{
+        featureIndex: z.ZodNumber;
+        cap: z.ZodString;
+        eventName: z.ZodString;
+        category: z.ZodEnum<typeof import("../index.js").EventCategory>;
+        stateField: z.ZodString;
+        fieldKey: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CompositionValidation = z.infer<typeof CompositionValidationSchema>;
 /**

package/dist/composition/composition.d.ts

@@ -203,6 +203,7 @@ export type CompositionItemEntry = z.infer<typeof CompositionItemEntrySchema>;
 export declare const CompositionFieldsFeatureSchema: z.ZodObject<{
     kind: z.ZodLiteral<"fields">;
     cap: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
     fields: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
         source: z.ZodObject<{
             addonId: z.ZodString;
@@ -278,6 +279,7 @@ export type CompositionFieldsFeature = z.infer<typeof CompositionFieldsFeatureSc
 export declare const CompositionPassthroughFeatureSchema: z.ZodObject<{
     kind: z.ZodLiteral<"passthrough">;
     cap: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
     source: z.ZodObject<{
         addonId: z.ZodString;
         stableId: z.ZodString;
@@ -287,6 +289,7 @@ export type CompositionPassthroughFeature = z.infer<typeof CompositionPassthroug
 export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"fields">;
     cap: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
     fields: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
         source: z.ZodObject<{
             addonId: z.ZodString;
@@ -359,12 +362,15 @@ export declare const CompositionFeatureSchema: z.ZodDiscriminatedUnion<[z.ZodObj
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"passthrough">;
     cap: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
     source: z.ZodObject<{
         addonId: z.ZodString;
         stableId: z.ZodString;
     }, z.core.$strip>;
 }, z.core.$strip>], "kind">;
 export type CompositionFeature = z.infer<typeof CompositionFeatureSchema>;
+/** Only an explicit `false` disables a feature; omitted preserves the existing wire default. */
+export declare function compositionFeatureEnabled(feature: CompositionFeature): boolean;
 /**
  * A NEW device. It has no `name` of its own: the block's name IS the device's
  * name (2026-08-08). A second copy here would be a second writer of one string (D62).
@@ -411,6 +417,7 @@ export declare const CompositionSchema: z.ZodObject<{
     features: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"fields">;
         cap: z.ZodString;
+        enabled: z.ZodOptional<z.ZodBoolean>;
         fields: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
             source: z.ZodObject<{
                 addonId: z.ZodString;
@@ -483,6 +490,7 @@ export declare const CompositionSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"passthrough">;
         cap: z.ZodString;
+        enabled: z.ZodOptional<z.ZodBoolean>;
         source: z.ZodObject<{
             addonId: z.ZodString;
             stableId: z.ZodString;

package/dist/composition/evaluate-field.d.ts

@@ -30,6 +30,7 @@
  * source) behind an early return.
  */
 import type { ExpressionValue } from '../expression/ast.js';
+import { type StatefulExpressionMemory } from '../expression/expression-source.js';
 import { type CompositionFieldRead, type CompositionFieldSource } from './composition.js';
 export interface SourceFreshReading {
     readonly state: 'fresh';
@@ -71,5 +72,12 @@ export interface EvaluateCompositionFieldInput {
     readonly source: CompositionFieldSource;
     readonly read: SourceReader;
     readonly now: number;
+    readonly stateful?: {
+        readonly currentOutput: unknown;
+        readonly expressionMemory: StatefulExpressionMemory;
+        readonly startedAtMs: number;
+        /** Scope structural AST paths to their owning output field. */
+        readonly callPathPrefix?: string;
+    };
 }
 export declare function evaluateCompositionField(input: EvaluateCompositionFieldInput): FieldOutcome;

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

@@ -33,4 +33,5 @@ export interface InferenceFailure {
 }
 export type InferExpressionKindsResult = InferredKinds | InferenceFailure;
 export declare function kindOfValue(value: ExpressionValue): ExpressionValueKind;
+export declare function expressionContainsBuiltinCall(expr: string, callee: string): boolean;
 export declare function inferExpressionKinds(input: InferExpressionKindsInput): InferExpressionKindsResult;

package/dist/composition/index.d.ts

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

package/dist/composition/plan-result.d.ts

@@ -4,11 +4,13 @@
  * barrel (`problem`/`refused` are too generic a name for `@camstack/types`).
  */
 import type { CompositionFeaturePlan, CompositionFieldPlan, CompositionProblem, CompositionProblemCode } from './composition-report.js';
+import type { CompositionEventPlan } from './composition-events.js';
 export interface CompositionPlanResult {
     readonly problems: readonly CompositionProblem[];
     readonly fields: readonly CompositionFieldPlan[];
     /** One entry per planned feature, with its mode; empty for a per-field or per-item result. */
     readonly features: readonly CompositionFeaturePlan[];
+    readonly events: readonly CompositionEventPlan[];
 }
 export declare function problem(code: CompositionProblemCode, path: string, message: string): CompositionProblem;
 export declare function refused(...problems: readonly CompositionProblem[]): CompositionPlanResult;