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/compat/AlexaInterface.d.ts

@@ -1,6 +1,6 @@
 import { Capability } from "../device/Capability.js";
 import type { CapabilityJson } from "../device/Capability.js";
-import type { Semantics } from "../registry/types.js";
+import type { Label, Semantics } from "../registry/types.js";
 import type { ActionMapping } from "./ActionMapping.js";
 import type { AlexaInterfaceType } from "./enums.js";
 /** One ModeController mode as discovery lists it (configuration.supportedModes): the value plus its friendly names. */
@@ -19,7 +19,11 @@ export interface SupportedMode {
 }
 interface Options {
     semantics?: Semantics;
-    supportedModes?: Array<string | SupportedMode>;
+    supportedModes?: Array<{
+        value: string;
+        friendlyNames: Label[];
+    }>;
+    ordered?: boolean;
 }
 /**
  * A capability as 1.x declares it: device.addCapability(type, options), then the add and set methods below. It is a
@@ -33,8 +37,14 @@ export declare class AlexaInterface extends Capability<any, any, Options> {
     get type(): AlexaInterfaceType;
     addActionMapping(mapping: ActionMapping): void;
     addFriendlyName(name: string, locale: string): void;
-    /** The modes of a ModeController, as { value, modeResources } objects. */
-    addSupportedModes(modes: Array<string | SupportedMode>): void;
+    /**
+     * The modes of a ModeController, as { value, modeResources } objects. A mode given as a string is announced as
+     * { value } and noted: Alexa wants friendly names for it. ordered is true unless options.ordered says otherwise,
+     * as 1.x announced every mode list; with device.add() the default is false.
+     */
+    addSupportedModes(modes: Array<string | SupportedMode>, options?: {
+        ordered?: boolean;
+    }): void;
     setInstance(name: string): void;
     getType(): AlexaInterfaceType;
     /** @deprecated The same as getType(). */

dist/esm/compat/AlexaInterface.js

@@ -25,9 +25,19 @@ export class AlexaInterface extends Capability {
     addFriendlyName(name, locale) {
         this.friendlyNames.push(text(name, locale));
     }
-    /** The modes of a ModeController, as { value, modeResources } objects. */
-    addSupportedModes(modes) {
-        this.options.supportedModes = modes;
+    /**
+     * The modes of a ModeController, as { value, modeResources } objects. A mode given as a string is announced as
+     * { value } and noted: Alexa wants friendly names for it. ordered is true unless options.ordered says otherwise,
+     * as 1.x announced every mode list; with device.add() the default is false.
+     */
+    addSupportedModes(modes, options = {}) {
+        this.options.ordered = options.ordered ?? true;
+        this.options.supportedModes = modes.map((mode) => {
+            if (typeof mode !== "string")
+                return { value: mode.value, friendlyNames: (mode.modeResources?.friendlyNames ?? []) };
+            this.notes.push(`the mode ${mode} was given as a string, pass { value, modeResources }`);
+            return { value: mode, friendlyNames: [] };
+        });
     }
     setInstance(name) {
         this.instance = name;