registry: RangeController, ModeController, ToggleController with resources, presets and semantics

The three generic controllers are described in full and leave the stub table (62 stubs remain). A declaration
takes an instance name, friendly names from text() and asset(), and the options of the interface: range, unit and
presets for a range; supportedModes and ordered for a mode; semantics() for all three, with actions mapped to
directives and states mapped to a value or a range of values.

Refused at device.add(), each with the endpoint, interface and instance in the message: no instance name or no
friendly name; an instance declared twice; a first friendly name or a phrase used by another capability of the
endpoint; a reserved word, an asset id that is not in the catalog; range.max not above range.min; a preset off the
precision grid or outside the range; fewer than two modes or a mode listed twice; a mapping to a directive the
interface does not have, to a payload that does not fit, to a mode that is not listed, to AdjustMode on modes
that are not ordered; SetEcoOn, SetEcoOff, EcoOn and EcoOff on anything but a toggle.

For 1.x callers: Alexa.RangeController lists rangeValue (1.5.2 sent supported: []); addSupportedModes() announces
a mode given as a string as { value } and notes it, and takes { ordered: false } as a second argument, the default
stays true as 1.5.2 sent it (device.add() defaults to false). Declared the 1.x way, the zoo fan and curtain give
the same JSON as before.

Tests: the zoo blind, whose range, unit and semantics were written by hand into the JSON of 1.5.2, is declared
with device.add() and equals that JSON plus the Alexa capability; five capability objects of Amazon's examples
are reproduced the same way. 27 examples of four pages added. npm test: 108 pass (was 85) in 10.5-11.3 s, also on
Node 18.20.8 and 20.20.2.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

dist/esm/registry/interfaces/ModeController.d.ts

@@ -0,0 +1,43 @@
+import type { Schema } from "../schema.js";
+import type { Label } from "../types.js";
+/** One mode: its value and what the user calls it. */
+export interface Mode {
+    value: string;
+    friendlyNames: Label[];
+}
+/**
+ * One of a list of values, under an instance name: the wash cycle of a washer, the position of a garage door. Amazon
+ * certifies a garage door only with this interface and the display category GARAGE_DOOR.
+ */
+export declare const ModeController: import("../types.js").InterfaceDescriptor<{
+    mode: {
+        name: string;
+        value: Schema<string | null>;
+        note: string;
+    };
+}, {
+    SetMode: {
+        name: string;
+        payload: Schema<import("../schema.js").InferShape<{
+            mode: Schema<string>;
+        }>>;
+    };
+    AdjustMode: {
+        name: string;
+        payload: Schema<import("../schema.js").InferShape<{
+            modeDelta: import("../schema.js").OptionalSchema<number>;
+        }>>;
+        when: ({ options }: {
+            options: {
+                ordered?: boolean;
+            };
+        }) => boolean;
+        note: string;
+    };
+}, import("../schema.js").InferShape<{
+    /** At least two. When the modes have an order, in increasing order. */
+    supportedModes: Schema<Mode[]>;
+    /** The modes have an order, cold to hot, and the user can say "increase": Alexa sends AdjustMode. Default: false. */
+    ordered: import("../schema.js").OptionalSchema<boolean>;
+    semantics: import("../schema.js").OptionalSchema<import("../types.js").Semantics>;
+}>, true>;

dist/esm/registry/interfaces/ModeController.js

@@ -0,0 +1,84 @@
+import { labels } from "../resources.js";
+import { at, mismatch, s } from "../schema.js";
+import { semanticsOf } from "../semantics.js";
+import { DeclarationError, defineInterface } from "../types.js";
+const directives = {
+    SetMode: { name: "SetMode", payload: s.object({ mode: s.string({ min: 1 }) }) },
+    AdjustMode: {
+        name: "AdjustMode",
+        payload: s.object({ modeDelta: s.optional(s.number({ integer: true })) }),
+        // alexa-modecontroller.html, "Capabilities object": "Modes that have an order support the AdjustMode directive."
+        when: ({ options }) => options.ordered === true,
+        note: "modeDelta is the number of modes to move by, 1 when it is left out",
+    },
+};
+// A mode is declared as { value, friendlyNames }. The object of discovery and of 1.x, { value, modeResources:
+// { friendlyNames } }, is taken as well.
+const eitherForm = s.object({
+    value: s.string({ min: 1 }),
+    friendlyNames: s.optional(s.unknown()),
+    modeResources: s.optional(s.object({ friendlyNames: s.unknown() })),
+}, { unknownKeys: "reject" });
+const mode = {
+    expects: "a mode { value, friendlyNames }",
+    parse(input, path = "") {
+        if (typeof input !== "object" || input === null)
+            throw mismatch(path, mode.expects, input);
+        const { value, friendlyNames, modeResources } = eitherForm.parse(input, path);
+        const named = friendlyNames === undefined && modeResources ? "modeResources.friendlyNames" : "friendlyNames";
+        return { value, friendlyNames: labels.parse(friendlyNames ?? modeResources?.friendlyNames, at(path, named)) };
+    },
+};
+/**
+ * One of a list of values, under an instance name: the wash cycle of a washer, the position of a garage door. Amazon
+ * certifies a garage door only with this interface and the display category GARAGE_DOOR.
+ */
+export const ModeController = defineInterface({
+    namespace: "Alexa.ModeController",
+    version: "3",
+    doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-modecontroller.html",
+    kind: "controller",
+    tier: 1,
+    instanced: true,
+    properties: {
+        mode: { name: "mode", value: s.nullable(s.string({ min: 1 })), note: "null when no mode is set, as when the device is off" },
+    },
+    directives,
+    options: s.object({
+        /** At least two. When the modes have an order, in increasing order. */
+        supportedModes: s.array(mode, { min: 2 }),
+        /** The modes have an order, cold to hot, and the user can say "increase": Alexa sends AdjustMode. Default: false. */
+        ordered: s.optional(s.boolean()),
+        semantics: s.optional(semanticsOf({ directives, stateValue: s.string({ min: 1 }) })),
+    }, { unknownKeys: "reject" }),
+    // A capability declared the 1.x way may be without modes, or have modes without names
+    discovery({ options: { supportedModes = [], ordered = false } }) {
+        if (supportedModes.length === 0)
+            return {};
+        const modes = supportedModes.map(({ value, friendlyNames = [] }) => (friendlyNames.length > 0 ? { value, modeResources: { friendlyNames } } : { value }));
+        return { configuration: { ordered, supportedModes: modes } };
+    },
+    validate(capability) {
+        const { supportedModes, ordered = false, semantics } = capability.options;
+        const values = supportedModes.map(({ value }) => value);
+        const twice = values.find((value, i) => values.indexOf(value) !== i);
+        if (twice !== undefined)
+            throw new DeclarationError(capability, `the mode ${twice} is listed twice`);
+        const isMode = (value) => values.includes(value);
+        for (const { directive } of semantics?.actionMappings ?? []) {
+            if (directive.name === "AdjustMode" && !ordered) {
+                throw new DeclarationError(capability, "an action is mapped to AdjustMode, which needs ordered: true");
+            }
+            if (directive.name === "SetMode" && !isMode(directive.payload?.mode)) {
+                throw new DeclarationError(capability, `an action is mapped to SetMode ${directive.payload?.mode}, the modes are ${values.join(", ")}`);
+            }
+        }
+        for (const mapping of semantics?.stateMappings ?? []) {
+            if (mapping["@type"] === "StatesToValue" && !isMode(mapping.value)) {
+                throw new DeclarationError(capability, `a state is mapped to ${mapping.value}, the modes are ${values.join(", ")}`);
+            }
+        }
+    },
+    errorNamespace: "Alexa.Safety",
+    errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"],
+});

dist/esm/registry/interfaces/RangeController.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A number in a range, under an instance name: the position of a blind, the speed of a fan. With nonControllable it
+ * is a reading the user can ask for, like an air quality index.
+ */
+export declare const RangeController: import("../types.js").InterfaceDescriptor<{
+    rangeValue: {
+        name: string;
+        value: import("../schema.js").Schema<number>;
+    };
+}, {
+    SetRangeValue: {
+        name: string;
+        payload: import("../schema.js").Schema<import("../schema.js").InferShape<{
+            rangeValue: import("../schema.js").Schema<number>;
+        }>>;
+    };
+    AdjustRangeValue: {
+        name: string;
+        payload: import("../schema.js").Schema<import("../schema.js").InferShape<{
+            rangeValueDelta: import("../schema.js").Schema<number>;
+            rangeValueDeltaDefault: import("../schema.js").Schema<boolean>;
+        }>>;
+        note: string;
+    };
+}, import("../schema.js").InferShape<{
+    /** precision is the step of the range and what "turn up the fan speed" changes it by. */
+    range: import("../schema.js").Schema<import("../schema.js").InferShape<{
+        min: import("../schema.js").Schema<number>;
+        max: import("../schema.js").Schema<number>;
+        precision: import("../schema.js").Schema<number>;
+    }>>;
+    unit: import("../schema.js").OptionalSchema<import("../catalog.js").UnitOfMeasure>;
+    /** Names for values: "set the fan speed to maximum". */
+    presets: import("../schema.js").OptionalSchema<import("../schema.js").InferShape<{
+        value: import("../schema.js").Schema<number>;
+        friendlyNames: import("../schema.js").Schema<import("../types.js").Label[]>;
+    }>[]>;
+    semantics: import("../schema.js").OptionalSchema<import("../types.js").Semantics>;
+}>, true>;

dist/esm/registry/interfaces/RangeController.js

@@ -0,0 +1,73 @@
+import { UNITS_OF_MEASURE } from "../catalog.js";
+import { labels } from "../resources.js";
+import { s } from "../schema.js";
+import { semanticsOf } from "../semantics.js";
+import { DeclarationError, defineInterface } from "../types.js";
+const directives = {
+    SetRangeValue: { name: "SetRangeValue", payload: s.object({ rangeValue: s.number() }) },
+    AdjustRangeValue: {
+        name: "AdjustRangeValue",
+        payload: s.object({ rangeValueDelta: s.number(), rangeValueDeltaDefault: s.boolean() }),
+        note: "rangeValueDeltaDefault is true when the user named no amount; rangeValueDelta is then the precision",
+    },
+};
+// 0.1 + 0.2 is not 0.3: a value is on the grid when it is within a millionth of a step of it
+function onGrid(value, origin, step) {
+    const steps = (value - origin) / step;
+    return Math.abs(steps - Math.round(steps)) < 1e-6;
+}
+/**
+ * A number in a range, under an instance name: the position of a blind, the speed of a fan. With nonControllable it
+ * is a reading the user can ask for, like an air quality index.
+ */
+export const RangeController = defineInterface({
+    namespace: "Alexa.RangeController",
+    version: "3",
+    doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-rangecontroller.html",
+    kind: "controller",
+    tier: 1,
+    instanced: true,
+    properties: {
+        rangeValue: { name: "rangeValue", value: s.number() },
+    },
+    directives,
+    options: s.object({
+        /** precision is the step of the range and what "turn up the fan speed" changes it by. */
+        range: s.object({ min: s.number(), max: s.number(), precision: s.number({ gt: 0 }) }, { unknownKeys: "reject" }),
+        unit: s.optional(s.oneOf(UNITS_OF_MEASURE, "a unit of measure like Alexa.Unit.Percent")),
+        /** Names for values: "set the fan speed to maximum". */
+        presets: s.optional(s.array(s.object({ value: s.number(), friendlyNames: labels }, { unknownKeys: "reject" }))),
+        semantics: s.optional(semanticsOf({ directives, stateValue: s.number(), ranges: true })),
+    }, { unknownKeys: "reject" }),
+    // A capability declared the 1.x way may be without a range; check() says so, discovery lists what there is
+    discovery({ options: { range, unit, presets } }) {
+        const configuration = {
+            ...(range && { supportedRange: { minimumValue: range.min, maximumValue: range.max, precision: range.precision } }),
+            ...(unit && { unitOfMeasure: unit }),
+            ...(presets && { presets: presets.map(({ value, friendlyNames }) => ({ rangeValue: value, presetResources: { friendlyNames } })) }),
+        };
+        return Object.keys(configuration).length > 0 ? { configuration } : {};
+    },
+    validate(capability) {
+        const { range: { min, max, precision }, presets = [], semantics } = capability.options;
+        const inRange = (value) => value >= min && value <= max;
+        if (max <= min)
+            throw new DeclarationError(capability, `range.max ${max} is not above range.min ${min}`);
+        for (const { value } of presets) {
+            // alexa-rangecontroller.html, "Preset object": "minimum range value + (n x precision) where n is an integer"
+            if (!inRange(value) || !onGrid(value, min, precision)) {
+                throw new DeclarationError(capability, `the preset ${value} is not ${min} + n x ${precision}, up to ${max}`);
+            }
+        }
+        for (const { directive } of semantics?.actionMappings ?? []) {
+            const { rangeValue } = directive.payload ?? {};
+            if (directive.name === "SetRangeValue" && !inRange(rangeValue)) {
+                throw new DeclarationError(capability, `an action is mapped to SetRangeValue ${rangeValue}, the range is ${min} to ${max}`);
+            }
+        }
+    },
+    // alexa-rangecontroller.html, "SetRangeValue directive error handling": "If your error is safety related, respond
+    // with an Alexa.Safety.ErrorResponse"
+    errorNamespace: "Alexa.Safety",
+    errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"],
+});

dist/esm/registry/interfaces/ToggleController.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Something that is on or off, under an instance name: the oscillation of a fan, the light of an oven. The one
+ * generic controller that Alexa hunches work with (SetEcoOn, SetEcoOff, EcoOn, EcoOff).
+ */
+export declare const ToggleController: import("../types.js").InterfaceDescriptor<{
+    toggleState: {
+        name: string;
+        value: import("../schema.js").EnumSchema<"ON" | "OFF">;
+    };
+}, {
+    TurnOn: {
+        name: string;
+        payload: import("../schema.js").Schema<import("../schema.js").InferShape<{}>>;
+    };
+    TurnOff: {
+        name: string;
+        payload: import("../schema.js").Schema<import("../schema.js").InferShape<{}>>;
+    };
+}, import("../schema.js").InferShape<{
+    semantics: import("../schema.js").OptionalSchema<import("../types.js").Semantics>;
+}>, true>;

dist/esm/registry/interfaces/ToggleController.js

@@ -0,0 +1,28 @@
+import { s } from "../schema.js";
+import { semanticsOf } from "../semantics.js";
+import { defineInterface } from "../types.js";
+const directives = {
+    TurnOn: { name: "TurnOn", payload: s.object({}) },
+    TurnOff: { name: "TurnOff", payload: s.object({}) },
+};
+/**
+ * Something that is on or off, under an instance name: the oscillation of a fan, the light of an oven. The one
+ * generic controller that Alexa hunches work with (SetEcoOn, SetEcoOff, EcoOn, EcoOff).
+ */
+export const ToggleController = defineInterface({
+    namespace: "Alexa.ToggleController",
+    version: "3",
+    doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-togglecontroller.html",
+    kind: "controller",
+    tier: 1,
+    instanced: true,
+    properties: {
+        toggleState: { name: "toggleState", value: s.enum("ON", "OFF") },
+    },
+    directives,
+    options: s.object({
+        semantics: s.optional(semanticsOf({ directives, stateValue: s.enum("ON", "OFF"), hunches: true })),
+    }, { unknownKeys: "reject" }),
+    errorNamespace: "Alexa.Safety",
+    errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"],
+});

dist/esm/registry/interfaces/stubs.js

@@ -45,7 +45,6 @@ const TABLE = [
     ["Alexa.Media.PlayQueue", "1", [], "alexa-media-playqueue.html"],
     ["Alexa.Media.Playback", "1", [], "alexa-media-playback.html"],
     ["Alexa.Media.Search", "1", [], "alexa-media-search.html"],
-    ["Alexa.ModeController", "3", ["mode"], "alexa-modecontroller.html"],
     ["Alexa.MotionSensor", "3", [], "alexa-motionsensor.html"],
     ["Alexa.PercentageController", "3", [], "alexa-percentagecontroller.html"],
     ["Alexa.PlaybackController", "3", [], "alexa-playbackcontroller.html"],
@@ -53,7 +52,6 @@ const TABLE = [
     ["Alexa.PowerLevelController", "3", [], "alexa-powerlevelcontroller.html"],
     ["Alexa.ProactiveNotificationSource", "1", [], "alexa-proactivenotificationsource.html"],
     ["Alexa.RTCSessionController", "1", [], "alexa-rtcsessioncontroller.html"],
-    ["Alexa.RangeController", "3", [], "alexa-rangecontroller.html"],
     ["Alexa.RecordController", "3", [], "alexa-recordcontroller.html"],
     ["Alexa.RemoteVideoPlayer", "1", [], "alexa-remotevideoplayer.html"],
     ["Alexa.SceneController", "3", [], "alexa-scenecontroller.html"],
@@ -71,13 +69,12 @@ const TABLE = [
     ["Alexa.ThermostatController.Schedule", "1", [], "alexa-thermostatcontroller-schedule.html"],
     // "UNKNOWN" in 1.5.2 as well; the page is titled "Interface 3"
     ["Alexa.TimeHoldController", "3", [], "alexa-timeholdcontroller.html"],
-    ["Alexa.ToggleController", "3", ["toggleState"], "alexa-togglecontroller.html"],
     ["Alexa.UIController", "1", [], "alexa-uicontroller.html"],
     ["Alexa.UserPreference", "1", [], "alexa-userpreference.html"],
     ["Alexa.VideoRecorder", "1", [], "alexa-videorecorder.html"],
     ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"],
 ];
-// What 1.5.2 added to the capability object of three of them
+// What 1.5.2 added to the capability object of two of them
 const EXTRAS = {
     // No properties object; supportsDeactivation and proactivelyReported on the capability itself
     "Alexa.SceneController": ({ proactivelyReported }) => ({
@@ -87,9 +84,6 @@ const EXTRAS = {
     "Alexa.ThermostatController": () => ({
         configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false },
     }),
-    "Alexa.ModeController": ({ options }) => (options.supportedModes?.length > 0
-        ? { configuration: { ordered: true, supportedModes: options.supportedModes } }
-        : {}),
 };
 function kindOf(namespace) {
     if (namespace.endsWith("Sensor"))