@nestor-home/satellite 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nestor-home
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @nestor-home/satellite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript SDK to write **satellites** for [Nestor](https://nestorhome.dev), in browsers and in
+Node: devices (a tab on a wall tablet, a Raspberry Pi speaker, a robot) that pair with a Nestor
+server, stream audio over WebRTC, carry out its intents and report what they observe, following the
+`nestor.satellite/1` protocol. It does not depend on the Nestor server.
+
+**Documentation:** [nestorhome.dev/docs/sdks/typescript](https://nestorhome.dev/docs/sdks/typescript/)
+(Node, pairing options, QR codes, the command, conformance).
+
+```bash
+pnpm add @nestor-home/satellite
+pnpm add @roamhq/wrtc   # in Node only
+```
+
+A tab as a satellite:
+
+```ts
+import {
+  AUDIO_CAPTURE,
+  AUDIO_PLAYBACK,
+  browserWebRtc,
+  IDENTIFY,
+  LocalStorageTokenStore,
+  Manifest,
+  Satellite,
+} from "@nestor-home/satellite";
+
+const satellite = new Satellite({
+  core: location.origin,
+  manifest: Manifest.of(
+    { id: "tablette-cuisine", model: "browser", room: "cuisine" },
+    AUDIO_CAPTURE,
+    AUDIO_PLAYBACK,
+    IDENTIFY,
+  ),
+  tokens: new LocalStorageTokenStore(),
+  webrtc: browserWebRtc(),
+  pairing: {
+    // the device code to type in Nestor; `code` is null once it is no longer needed
+    display: (code, text) => {
+      document.querySelector("#code")!.textContent = code ?? "";
+      document.querySelector("#status")!.textContent = text;
+    },
+  },
+  body: {
+    behavior: (behavior) => (document.body.dataset.behavior = behavior),
+    identify: () => document.body.animate([{ opacity: 0.2 }, { opacity: 1 }], { duration: 500, iterations: 6 }),
+  },
+});
+button.onclick = () => satellite.run(); // a click: browsers only play sound after a gesture
+```
+
+In Node, the machine's microphone and speaker, with nothing to write:
+
+```bash
+NESTOR_PAIRING_URI='nestor+http://nestor.local:7860/?code=K7QF2M9X' npx nestor-satellite run --room salon
+```
+
+The recorded voice that says device codes is shared under CC BY 4.0: see
+[`voice/LICENSE`](voice/LICENSE).
+
+## Development
+
+```bash
+pnpm install
+pnpm lint && pnpm typecheck && pnpm test
+pnpm conformance   # the published server's conformance suite (uvx; version in .nestor-version)
+```
+
+## License
+
+MIT

package/dist/body.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What a driver implements to carry out the core's intents. Every method is optional: implement
+ * what the device can do.
+ *
+ * Calls come from the network loop and must return at once: keep the state, animate elsewhere.
+ * Physical safety (limits, watchdogs) belongs to the driver and never depends on the link.
+ */
+import type { Behavior, Expression } from "./protocol.js";
+export interface Body {
+    /** The assistant's attitude changed (idle, listening, thinking, speaking): show it until the next. */
+    behavior?(behavior: Behavior): void;
+    /** Perform an expression now: it arrives as the matching audio is played. Needs `expression.emotion`. */
+    expression?(expression: Expression, intensity: number): void;
+    /** A word is being played: a light speech accent. Needs `motion.head`. */
+    beat?(): void;
+    /**
+     * Make the device noticed for a few seconds (blink, wiggle, chime, flash the screen), so a person
+     * tells it apart from others: asked while it waits to be paired, and once paired
+     * (`intent.identify`). A driver that implements it declares `device.identify`.
+     */
+    identify?(): void;
+    /** The core was just heard from (a message or audio). A watchdog can rest the device when heartbeats stop. */
+    heartbeat?(): void;
+    /** The link to the core came up (welcomed) or went down. */
+    connected?(up: boolean): void;
+}
+//# sourceMappingURL=body.d.ts.map

package/dist/body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body.d.ts","sourceRoot":"","sources":["../src/body.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,WAAW,IAAI;IACnB,sGAAsG;IACtG,QAAQ,CAAC,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACpC,yGAAyG;IACzG,UAAU,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7D,0EAA0E;IAC1E,IAAI,CAAC,IAAI,IAAI,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,IAAI,IAAI,CAAC;IAClB,8GAA8G;IAC9G,SAAS,CAAC,IAAI,IAAI,CAAC;IACnB,4DAA4D;IAC5D,SAAS,CAAC,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B"}

package/dist/body.js

@@ -0,0 +1,9 @@
+/**
+ * What a driver implements to carry out the core's intents. Every method is optional: implement
+ * what the device can do.
+ *
+ * Calls come from the network loop and must return at once: keep the state, animate elsewhere.
+ * Physical safety (limits, watchdogs) belongs to the driver and never depends on the link.
+ */
+export {};
+//# sourceMappingURL=body.js.map

package/dist/body.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body.js","sourceRoot":"","sources":["../src/body.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/browser.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The browser's own WebRTC: `RTCPeerConnection`, the microphone through `getUserMedia`, the core's
+ * voice through an `<audio>` element.
+ *
+ * Browsers only open the microphone in a secure context (`https:` or `http://localhost`), and only
+ * play sound after a user gesture: start the satellite from a click.
+ */
+import { type Logger } from "./log.js";
+import type { Speaker } from "./voice.js";
+import type { WebRtc } from "./webrtc.js";
+/** What this adapter needs of an `<audio>` element (an `HTMLAudioElement` fits). */
+export interface AudioElementLike {
+    srcObject: unknown;
+    play(): Promise<void>;
+}
+export interface BrowserWebRtcOptions {
+    /** Constraints for `getUserMedia({audio})`; echo cancellation, noise suppression and gain control by default. */
+    readonly microphone?: Readonly<Record<string, boolean | number | string>>;
+    /** Where the core's voice plays (default: a detached `new Audio()`). */
+    readonly element?: AudioElementLike;
+    /** Where the SDK says the device code itself (default: `webAudioSpeaker()`, `null` for none). */
+    readonly speaker?: Speaker | null;
+    readonly logger?: Logger;
+}
+export declare function browserWebRtc(options?: BrowserWebRtcOptions): WebRtc;
+/** What `browserSpeech` needs of the Web Speech API (`window.speechSynthesis` fits). */
+export interface SpeechSynthesisLike {
+    speak(utterance: unknown): void;
+    cancel(): void;
+}
+/**
+ * The browser's voice (Web Speech API) as a pairing output: `pairing: { speak: browserSpeech({ lang }) }`
+ * declares `device_code.speech`. `undefined` when this browser cannot speak, so nothing is declared.
+ * `lang` should match the satellite's `locale`.
+ */
+export declare function browserSpeech(options?: {
+    readonly lang?: string;
+}): ((text: string) => void) | undefined;
+/** What `webAudioSpeaker` needs of Web Audio (`AudioContext` fits). */
+export interface AudioContextLike {
+    readonly currentTime: number;
+    readonly destination: unknown;
+    resume(): Promise<void>;
+    createBuffer(channels: number, length: number, sampleRate: number): {
+        copyToChannel(source: Float32Array<ArrayBuffer>, channel: number): void;
+        readonly duration: number;
+    };
+    createBufferSource(): {
+        buffer: unknown;
+        connect(destination: unknown): unknown;
+        start(when: number): void;
+        stop(): void;
+        onended: (() => void) | null;
+    };
+}
+/**
+ * The page's speaker through Web Audio, with the bundled voice fetched from the package: the device
+ * code sounds the same as on any other satellite, offline. `undefined` when the browser has no Web
+ * Audio. Browsers only play sound after a user gesture: start the satellite from a click.
+ */
+export declare function webAudioSpeaker(options?: {
+    readonly context?: () => AudioContextLike;
+    readonly load?: (path: string) => Promise<Uint8Array>;
+}): Speaker | undefined;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAY,KAAK,MAAM,EAAe,MAAM,UAAU,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,KAAK,EAAiC,MAAM,EAAE,MAAM,aAAa,CAAC;AAEzE,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,iHAAiH;IACjH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;IAC1E,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IACpC,iGAAiG;IACjG,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAaD,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAExE;AAoED,wFAAwF;AACxF,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,MAAM,IAAI,IAAI,CAAC;CAChB;AAOD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAS5G;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,YAAY,CACV,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB;QAAE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1G,kBAAkB,IAAI;QACpB,MAAM,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC;QACvC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,IAAI,IAAI,IAAI,CAAC;QACb,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;KAC9B,CAAC;CACH;AAaD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,gBAAgB,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;CAAO,GACjH,OAAO,GAAG,SAAS,CA0CrB"}

package/dist/browser.js

@@ -0,0 +1,161 @@
+/**
+ * The browser's own WebRTC: `RTCPeerConnection`, the microphone through `getUserMedia`, the core's
+ * voice through an `<audio>` element.
+ *
+ * Browsers only open the microphone in a secure context (`https:` or `http://localhost`), and only
+ * play sound after a user gesture: start the satellite from a click.
+ */
+import { describe, quietLogger } from "./log.js";
+import { W3cPeer } from "./w3c.js";
+const DEFAULT_MICROPHONE = { echoCancellation: true, noiseSuppression: true, autoGainControl: true };
+export function browserWebRtc(options = {}) {
+    return new BrowserWebRtc(options);
+}
+class BrowserWebRtc {
+    options;
+    speaker;
+    logger;
+    microphone = null;
+    element = null;
+    playback = false;
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger ?? quietLogger;
+        this.speaker = (options.speaker === undefined ? webAudioSpeaker() : options.speaker) ?? undefined;
+    }
+    async open(needs) {
+        const media = globals();
+        if (media.RTCPeerConnection === undefined)
+            throw new Error("this browser has no WebRTC (RTCPeerConnection)");
+        this.playback = needs.playback;
+        if (needs.playback)
+            this.element = this.options.element ?? (media.Audio ? new media.Audio() : null);
+        if (!needs.capture)
+            return;
+        const devices = media.navigator?.mediaDevices;
+        if (devices === undefined) {
+            throw new Error("audio.capture is declared but this page cannot open a microphone (needs https or localhost)");
+        }
+        try {
+            const stream = await devices.getUserMedia({ audio: this.options.microphone ?? DEFAULT_MICROPHONE });
+            this.microphone = stream.getAudioTracks()[0] ?? null;
+        }
+        catch (error) {
+            throw new Error(`audio.capture is declared but the microphone did not open: ${describe(error)}`);
+        }
+        if (this.microphone === null)
+            throw new Error("audio.capture is declared but no microphone track came");
+    }
+    createPeer(options) {
+        const Connection = globals().RTCPeerConnection;
+        if (Connection === undefined)
+            throw new Error("this browser has no WebRTC (RTCPeerConnection)");
+        return new W3cPeer(Connection, this, options, this.logger);
+    }
+    async close() {
+        this.microphone?.stop();
+        this.microphone = null;
+        if (this.element !== null)
+            this.element.srcObject = null;
+    }
+    outgoing() {
+        return this.microphone;
+    }
+    incoming(event, onAudio) {
+        onAudio();
+        const element = this.element;
+        if (!this.playback || element === null)
+            return () => { };
+        const Stream = globals().MediaStream;
+        element.srcObject = event.streams[0] ?? (Stream ? new Stream([event.track]) : null);
+        element.play().catch((error) => {
+            this.logger.warn(`the core's voice cannot play yet (start the satellite from a click): ${describe(error)}`);
+        });
+        return () => {
+            if (element.srcObject !== null)
+                element.srcObject = null;
+        };
+    }
+}
+function globals() {
+    return globalThis;
+}
+/**
+ * The browser's voice (Web Speech API) as a pairing output: `pairing: { speak: browserSpeech({ lang }) }`
+ * declares `device_code.speech`. `undefined` when this browser cannot speak, so nothing is declared.
+ * `lang` should match the satellite's `locale`.
+ */
+export function browserSpeech(options = {}) {
+    const { speechSynthesis, SpeechSynthesisUtterance: Utterance } = globalThis;
+    if (speechSynthesis === undefined || Utterance === undefined)
+        return undefined;
+    return (text) => {
+        const utterance = new Utterance(text);
+        if (options.lang !== undefined)
+            utterance.lang = options.lang;
+        speechSynthesis.cancel(); // the latest sentence replaces the one still being said
+        speechSynthesis.speak(utterance);
+    };
+}
+/**
+ * A file of the bundled voice, in the package next to this module. Written so bundlers find the files:
+ * Vite turns each template into the list of what it matches, one folder level per placeholder.
+ */
+function voiceUrl(path) {
+    const [folder, file] = path.split("/");
+    return file === undefined
+        ? new URL(`../voice/${path}`, import.meta.url)
+        : new URL(`../voice/${folder}/${file}`, import.meta.url);
+}
+/**
+ * The page's speaker through Web Audio, with the bundled voice fetched from the package: the device
+ * code sounds the same as on any other satellite, offline. `undefined` when the browser has no Web
+ * Audio. Browsers only play sound after a user gesture: start the satellite from a click.
+ */
+export function webAudioSpeaker(options = {}) {
+    const Context = globalThis.AudioContext;
+    const create = options.context ?? (Context === undefined ? undefined : () => new Context());
+    if (create === undefined)
+        return undefined;
+    const load = options.load ??
+        (async (path) => {
+            const response = await fetch(voiceUrl(path));
+            if (!response.ok)
+                throw new Error(`${path}: HTTP ${response.status}`);
+            return new Uint8Array(await response.arrayBuffer());
+        });
+    let context = null;
+    let next = 0;
+    const playing = new Set();
+    const sampleRate = 16_000; // the clips' own rate: Web Audio resamples to the device's
+    return {
+        sampleRate,
+        load,
+        write(pcm) {
+            if (context === null) {
+                context = create();
+                void context.resume().catch(() => { });
+            }
+            const buffer = context.createBuffer(1, pcm.length, sampleRate);
+            const floats = new Float32Array(pcm.length);
+            for (let i = 0; i < pcm.length; i++)
+                floats[i] = (pcm[i] ?? 0) / 32768;
+            buffer.copyToChannel(floats, 0);
+            const source = context.createBufferSource();
+            source.buffer = buffer;
+            source.connect(context.destination);
+            next = Math.max(next, context.currentTime);
+            source.start(next);
+            next += buffer.duration;
+            playing.add(source);
+            source.onended = () => playing.delete(source);
+        },
+        flush() {
+            for (const source of playing)
+                source.stop();
+            playing.clear();
+            next = 0;
+        },
+    };
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}

package/dist/codes.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The codes of `nestor.satellite/1` pairing, and the pairing URI that carries an enrollment code.
+ *
+ * Device code: 6 decimal digits the core gives the device, which presents them (screen, voice, log)
+ * for a person to type in the admin.
+ *
+ * Enrollment code: 8 symbols of Crockford's base32 (`K7QF-2M9X`), made in the admin and handed to
+ * the device (configured, typed or scanned). Reading one back forgives case, dashes, spaces and the
+ * letters Crockford maps to digits (O → 0, I and L → 1).
+ *
+ * Pairing URI: `nestor+http://nestor.local:7860/?code=K7QF2M9X`, the core's base URL prefixed with
+ * `nestor+`, and the enrollment code.
+ */
+/** Crockford's base32: no I, L, O, U. */
+export declare const ENROLLMENT_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export declare const ENROLLMENT_LENGTH = 8;
+export declare const DEVICE_CODE: RegExp;
+/** The canonical form of a typed or scanned enrollment code (`k7qf-2m9x` → `K7QF2M9X`); `null` when it cannot be one. */
+export declare function normalizeEnrollmentCode(text: string): string | null;
+/** How an enrollment code is shown to people: `K7QF-2M9X`. */
+export declare function groupEnrollmentCode(code: string): string;
+export interface PairingUri {
+    /** The core's base URL, e.g. `http://nestor.local:7860`. */
+    readonly core: string;
+    /** The enrollment code, canonical form. */
+    readonly code: string;
+}
+/** The core's base URL and the enrollment code of `nestor+http(s)://host:port/path/?code=…`. */
+export declare function parsePairingUri(uri: string): PairingUri;
+/**
+ * What a person handed the device: a pairing URI (`core` is then its core) or a bare enrollment code
+ * (`core` is `null`). `null` when it is neither.
+ */
+export declare function readEnrollment(text: string): {
+    readonly core: string | null;
+    readonly code: string;
+} | null;
+//# sourceMappingURL=codes.d.ts.map

package/dist/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../src/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,yCAAyC;AACzC,eAAO,MAAM,mBAAmB,qCAAqC,CAAC;AACtE,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,WAAW,QAAY,CAAC;AAIrC,yHAAyH;AACzH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOnE;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAavD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAU3G"}

package/dist/codes.js

@@ -0,0 +1,67 @@
+/**
+ * The codes of `nestor.satellite/1` pairing, and the pairing URI that carries an enrollment code.
+ *
+ * Device code: 6 decimal digits the core gives the device, which presents them (screen, voice, log)
+ * for a person to type in the admin.
+ *
+ * Enrollment code: 8 symbols of Crockford's base32 (`K7QF-2M9X`), made in the admin and handed to
+ * the device (configured, typed or scanned). Reading one back forgives case, dashes, spaces and the
+ * letters Crockford maps to digits (O → 0, I and L → 1).
+ *
+ * Pairing URI: `nestor+http://nestor.local:7860/?code=K7QF2M9X`, the core's base URL prefixed with
+ * `nestor+`, and the enrollment code.
+ */
+import { ProtocolError } from "./protocol.js";
+/** Crockford's base32: no I, L, O, U. */
+export const ENROLLMENT_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export const ENROLLMENT_LENGTH = 8;
+export const DEVICE_CODE = /^\d{6}$/;
+const ALIASES = { O: "0", I: "1", L: "1" };
+/** The canonical form of a typed or scanned enrollment code (`k7qf-2m9x` → `K7QF2M9X`); `null` when it cannot be one. */
+export function normalizeEnrollmentCode(text) {
+    const code = text
+        .replace(/[\s-]/g, "")
+        .toUpperCase()
+        .replace(/[OIL]/g, (c) => ALIASES[c] ?? c);
+    if (code.length !== ENROLLMENT_LENGTH || [...code].some((c) => !ENROLLMENT_ALPHABET.includes(c)))
+        return null;
+    return code;
+}
+/** How an enrollment code is shown to people: `K7QF-2M9X`. */
+export function groupEnrollmentCode(code) {
+    return `${code.slice(0, 4)}-${code.slice(4)}`;
+}
+/** The core's base URL and the enrollment code of `nestor+http(s)://host:port/path/?code=…`. */
+export function parsePairingUri(uri) {
+    const invalid = () => new ProtocolError("a pairing URI looks like nestor+http://host:port/?code=K7QF2M9X");
+    let url;
+    try {
+        url = new URL(uri.trim());
+    }
+    catch {
+        throw invalid();
+    }
+    const scheme = { "nestor+http:": "http", "nestor+https:": "https" }[url.protocol];
+    const codes = url.searchParams.getAll("code");
+    const code = codes.length === 1 && codes[0] !== undefined ? normalizeEnrollmentCode(codes[0]) : null;
+    if (scheme === undefined || url.host === "" || code === null)
+        throw invalid();
+    return { core: `${scheme}://${url.host}${url.pathname.replace(/\/+$/, "")}`, code };
+}
+/**
+ * What a person handed the device: a pairing URI (`core` is then its core) or a bare enrollment code
+ * (`core` is `null`). `null` when it is neither.
+ */
+export function readEnrollment(text) {
+    if (/^nestor\+/i.test(text.trim())) {
+        try {
+            return parsePairingUri(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    const code = normalizeEnrollmentCode(text);
+    return code === null ? null : { core: null, code };
+}
+//# sourceMappingURL=codes.js.map

package/dist/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../src/codes.ts"],"names":[],"mappings":"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"}

package/dist/dispatch.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What the satellite does with each message from the core: hand intents to the body and
+ * acknowledge them, take note of the welcome, notice the core hanging up. The connection reports
+ * the link up to the body once it is welcomed.
+ */
+import type { Body } from "./body.js";
+import { type Logger } from "./log.js";
+import { type AckMessage, type Welcome } from "./wire.js";
+export type Outcome = "nothing" | "welcomed" | "hung-up";
+export declare class Dispatcher {
+    private readonly body;
+    private readonly reply;
+    private readonly logger;
+    welcome: Welcome | null;
+    constructor(body: Body, reply: (message: AckMessage) => void, logger?: Logger);
+    handle(raw: string): Outcome;
+    /** A failing body is the driver's bug: it is logged, never allowed to break the link. */
+    private call;
+}
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAY,KAAK,MAAM,EAAe,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,KAAK,UAAU,EAA0B,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAElF,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAEzD,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,EAAE,OAAO,GAAG,IAAI,CAAQ;gBAGZ,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,EACpC,MAAM,GAAE,MAAoB;IAG/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAqC5B,yFAAyF;IACzF,OAAO,CAAC,IAAI;CAOb"}

package/dist/dispatch.js

@@ -0,0 +1,67 @@
+/**
+ * What the satellite does with each message from the core: hand intents to the body and
+ * acknowledge them, take note of the welcome, notice the core hanging up. The connection reports
+ * the link up to the body once it is welcomed.
+ */
+import { describe, quietLogger } from "./log.js";
+import { ack, parse, signalling } from "./wire.js";
+export class Dispatcher {
+    body;
+    reply;
+    logger;
+    welcome = null;
+    constructor(body, reply, logger = quietLogger) {
+        this.body = body;
+        this.reply = reply;
+        this.logger = logger;
+    }
+    handle(raw) {
+        let data;
+        let received;
+        try {
+            data = JSON.parse(raw);
+            const transport = signalling(data);
+            if (transport !== null)
+                return transport.hungUp ? "hung-up" : "nothing";
+            received = parse(data);
+        }
+        catch (error) {
+            this.logger.warn(`ignoring an off-contract message from the core: ${describe(error)}`);
+            return "nothing";
+        }
+        this.call(() => this.body.heartbeat?.());
+        const message = received.message;
+        if (message === null)
+            return "nothing"; // a newer message type: nothing to acknowledge
+        if (message.type === "welcome") {
+            this.welcome = message;
+            return "welcomed";
+        }
+        switch (message.type) {
+            case "intent.behavior":
+                this.call(() => this.body.behavior?.(message.behavior));
+                break;
+            case "intent.expression":
+                this.call(() => this.body.expression?.(message.expression, message.intensity));
+                break;
+            case "intent.beat":
+                this.call(() => this.body.beat?.());
+                break;
+            case "intent.identify":
+                this.call(() => this.body.identify?.());
+                break;
+        }
+        this.reply(ack(received.id)); // received, whatever the body made of it
+        return "nothing";
+    }
+    /** A failing body is the driver's bug: it is logged, never allowed to break the link. */
+    call(action) {
+        try {
+            action();
+        }
+        catch (error) {
+            this.logger.warn(`the body failed: ${describe(error)}`);
+        }
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,QAAQ,EAAe,WAAW,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAmB,GAAG,EAAE,KAAK,EAAE,UAAU,EAAgB,MAAM,WAAW,CAAC;AAIlF,MAAM,OAAO,UAAU;IAIF;IACA;IACA;IALnB,OAAO,GAAmB,IAAI,CAAC;IAE/B,YACmB,IAAU,EACV,KAAoC,EACpC,SAAiB,WAAW;QAF5B,SAAI,GAAJ,IAAI,CAAM;QACV,UAAK,GAAL,KAAK,CAA+B;QACpC,WAAM,GAAN,MAAM,CAAsB;IAC5C,CAAC;IAEJ,MAAM,CAAC,GAAW;QAChB,IAAI,IAAa,CAAC;QAClB,IAAI,QAAkC,CAAC;QACvC,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACvB,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,SAAS,KAAK,IAAI;gBAAE,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;YACxE,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,mDAAmD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACvF,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;QACjC,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,SAAS,CAAC,CAAC,+CAA+C;QACvF,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;YACvB,OAAO,UAAU,CAAC;QACpB,CAAC;QACD,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;YACrB,KAAK,iBAAiB;gBACpB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;gBACxD,MAAM;YACR,KAAK,mBAAmB;gBACtB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;gBAC/E,MAAM;YACR,KAAK,aAAa;gBAChB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBACpC,MAAM;YACR,KAAK,iBAAiB;gBACpB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;gBACxC,MAAM;QACV,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,yCAAyC;QACvE,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,yFAAyF;IACjF,IAAI,CAAC,MAAkB;QAC7B,IAAI,CAAC;YACH,MAAM,EAAE,CAAC;QACX,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;CACF"}

package/dist/i18n.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a satellite says to people (its device code, a refused enrollment code, why it cannot pair),
+ * in their language. The catalogues are Fluent (`./locales.ts`); English is the fallback.
+ *
+ * The locale comes from the `locale` option, else the platform (`navigator.languages` in browsers
+ * and in Node), else English. Node's CLI reads `LC_ALL`, `LC_MESSAGES` and `LANG` itself.
+ */
+import { type MessageId } from "./locales.js";
+export type { MessageId } from "./locales.js";
+declare const CATALOGUES: {
+    readonly en: "\ndevice-code-log = Pairing code: { $code }. Type it in Nestor to add this device.\ndevice-code-display = Type this code in Nestor to add this device.\n# The bundled voice has a clip for each piece of text around the digits (nestor-satellite-python's\n# scripts/voice.py records them): record them again after changing this sentence.\ndevice-code-speech = Pairing code: { $digits }. I repeat: { $digits }.\nheadless-hint = This device has no screen and no voice, so the easiest way to pair it is an enrollment code. Add a satellite in Nestor, then set NESTOR_PAIRING_URI.\nenrollment-sent = Sending the enrollment code { $code } to Nestor.\nenrollment-refused = { $reason ->\n    [expired] The enrollment code { $code } has expired.\n    [used] The enrollment code { $code } was already used.\n    [cancelled] The enrollment code { $code } was cancelled.\n   *[unknown] Nestor does not know the enrollment code { $code }.\n}\nenrollment-fallback = Asking for a pairing code instead.\nenrollment-already-refused = The enrollment code { $code } was already refused. Make a new one in Nestor.\nenrollment-invalid = This is not an enrollment code. One has 8 letters and digits, like K7QF-2M9X.\nenrollment-not-pending = This device no longer waits for an enrollment code.\npaired = Paired with Nestor.\npairing-expired = The pairing code expired. Asking for a new one.\nidentify = Nestor asks this device to show itself.\ntoo-many-attempts = Too many wrong codes were tried. Trying again in { $seconds } s.\ntoo-many-pending = Too many devices are waiting to be paired. Trying again in { $seconds } s.\nprotocol-unsupported = This Nestor speaks another version of the satellite protocol. Update this device or Nestor.\ninvalid-request = Nestor refused this device's pairing request. Update this device or Nestor.\ntoken-refused = Nestor no longer knows this device. Pairing it again.\nlink-failed = The link to Nestor failed ({ $error }). Trying again.\ncamera-failed = The camera did not open, so this device cannot scan a QR code ({ $error }).\n";
+    readonly fr: "\ndevice-code-log = Code d'appairage : { $code }. Saisissez-le dans Nestor pour ajouter cet appareil.\ndevice-code-display = Saisissez ce code dans Nestor pour ajouter cet appareil.\n# La voix fournie a un extrait pour chaque texte autour des chiffres (scripts/voice.py de\n# nestor-satellite-python les enregistre) : les réenregistrer après avoir changé cette phrase.\ndevice-code-speech = Code d'appairage : { $digits }. Je répète : { $digits }.\nheadless-hint = Cet appareil n'a ni écran ni voix : le plus simple est de l'appairer avec un code d'enrôlement. Ajoutez un satellite dans Nestor, puis renseignez NESTOR_PAIRING_URI.\nenrollment-sent = Envoi du code d'enrôlement { $code } à Nestor.\nenrollment-refused = { $reason ->\n    [expired] Le code d'enrôlement { $code } a expiré.\n    [used] Le code d'enrôlement { $code } a déjà servi.\n    [cancelled] Le code d'enrôlement { $code } a été annulé.\n   *[unknown] Nestor ne connaît pas le code d'enrôlement { $code }.\n}\nenrollment-fallback = Je demande un code d'appairage à la place.\nenrollment-already-refused = Le code d'enrôlement { $code } a déjà été refusé. Créez-en un nouveau dans Nestor.\nenrollment-invalid = Ce n'est pas un code d'enrôlement. Il compte 8 lettres et chiffres, comme K7QF-2M9X.\nenrollment-not-pending = Cet appareil n'attend plus de code d'enrôlement.\npaired = Appairé avec Nestor.\npairing-expired = Le code d'appairage a expiré. J'en demande un nouveau.\nidentify = Nestor demande à cet appareil de se signaler.\ntoo-many-attempts = Trop de codes erronés ont été essayés. Nouvel essai dans { $seconds } s.\ntoo-many-pending = Trop d'appareils attendent d'être appairés. Nouvel essai dans { $seconds } s.\nprotocol-unsupported = Ce Nestor parle une autre version du protocole des satellites. Mettez à jour cet appareil ou Nestor.\ninvalid-request = Nestor a refusé la demande d'appairage de cet appareil. Mettez à jour cet appareil ou Nestor.\ntoken-refused = Nestor ne connaît plus cet appareil. Nouvel appairage.\nlink-failed = La liaison avec Nestor a échoué ({ $error }). Nouvel essai.\ncamera-failed = La caméra ne s'est pas ouverte : cet appareil ne peut pas lire de QR code ({ $error }).\n";
+};
+export type Locale = keyof typeof CATALOGUES;
+export declare const LOCALES: readonly Locale[];
+export type MessageArgs = Readonly<Record<string, string | number>>;
+/**
+ * The first supported locale among `requested` (BCP 47 tags such as `fr-FR`, or POSIX ones such as
+ * `fr_FR.UTF-8`), else English.
+ */
+export declare function negotiateLocale(requested: readonly (string | null | undefined)[]): Locale;
+/** The platform's preferred languages, when it says (browsers, Node 21+). */
+export declare function platformLanguages(): readonly string[];
+export declare class Messages {
+    readonly locale: Locale;
+    private readonly bundle;
+    private readonly fallback;
+    /** `locale`: a tag or a list of preferred tags; by default the platform's languages. */
+    constructor(locale?: string | readonly string[]);
+    /** The sentence `id` with its arguments, in this locale (in English when this locale lacks it). */
+    format(id: MessageId, args?: MessageArgs): string;
+}
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAU,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAEtD,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,QAAA,MAAM,UAAU;;;CAAsB,CAAC;AACvC,MAAM,MAAM,MAAM,GAAG,MAAM,OAAO,UAAU,CAAC;AAC7C,eAAO,MAAM,OAAO,EAAE,SAAS,MAAM,EAAuD,CAAC;AAE7F,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;AAEpE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,MAAM,CAUzF;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAGrD;AAED,qBAAa,QAAQ;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IAExC,wFAAwF;gBAC5E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE;IAO/C,mGAAmG;IACnG,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,GAAE,WAAgB,GAAG,MAAM;CAOtD"}