@pollen-robotics/reachy-mini-sdk 1.8.0 → 1.8.1

package/README.md

@@ -98,9 +98,8 @@ See the JSDoc header in [`reachy-mini-sdk.js`](./reachy-mini-sdk.js) for the ful
 
 For Hugging Face Spaces apps that need OAuth + a robot picker + iframe lifecycle management:
 
-- [`host/README.md`](./host/README.md) — quickstart and integration overview
-- [`host/APP_AUTHOR_GUIDE.md`](./host/APP_AUTHOR_GUIDE.md) — full guide for app authors
-- [`host/SPEC.md`](./host/SPEC.md) — host ↔ embed protocol spec
+- **[`APP_CREATION_GUIDE.md`](./APP_CREATION_GUIDE.md)** — single source of truth for app authors (scaffold, `sdk: static` deploy, host ↔ embed contract, invariants). Today's SDK pin: `1.8.0`.
+- [`host/README.md`](./host/README.md) — one-page tour of the host package layout
 
 ## Migration from `@pollen-robotics/reachy-mini-host`
 
@@ -122,8 +121,6 @@ You can drop `@pollen-robotics/reachy-mini-host` from your `package.json`. The h
 
 The host bundles now import the SDK directly and assign it on `window.ReachyMini` at load time, so apps no longer need a second `<script type="module">` for the SDK alone.
 
-See the [CHANGELOG](./CHANGELOG.md) for the full release history.
-
 ## License
 
 Apache-2.0 — see [LICENSE](./LICENSE).

package/dist/animation/distance.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Pose distance + scaled duration math.
+ *
+ * Pure functions, no SDK calls, no clock reads. The caller passes a
+ * `current` pose (typically from `reachy.robotState`) and a `target`
+ * pose; the helpers return per-channel distances and a "feels right"
+ * duration for `gotoTarget`.
+ *
+ * Mirror of the daemon's `utils/interpolation.distance_between_poses`
+ * (head magic-mm) + the scaled-duration algorithm used internally for
+ * `wake_up` / `goto_sleep`. Duplicated client-side so apps know the
+ * duration **synchronously** for audio sync, streamer scheduling, and
+ * live constant tuning.
+ */
+import type { PartialPose } from "./pose.js";
+import { type ScaledDurationPreset } from "./presets.js";
+/**
+ * Per-channel "raw" distance between two poses.
+ *
+ * Channels missing from either input are absent from the result (the
+ * caller's `current` and `target` may both be `PartialPose`).
+ *
+ * Units:
+ *   - `head`: "magic-mm" — translation_mm + rotation_deg fused into one
+ *     scalar. The Python SDK's `utils/interpolation.distance_between_poses`
+ *     uses the same trick: two unrelated units summed into a single
+ *     number that's monotonic with "how big does this motion feel".
+ *   - `antennas.right` / `antennas.left`: `|Δ°|` per antenna.
+ *   - `body_yaw`: `|Δ°|`.
+ *
+ * Useful in log lines:
+ *   `head=3.2mm, antennaR=18°, body=14°, limiter=antennaR`
+ */
+export interface PoseDistance {
+    head?: number;
+    antennas?: {
+        right: number;
+        left: number;
+    };
+    body_yaw?: number;
+}
+/**
+ * Compute the per-channel distance between two poses.
+ *
+ * Pure function. Allocates only the output object.
+ */
+export declare function distanceBetweenPoses(current: PartialPose, target: PartialPose): PoseDistance;
+/** Outcome of a scaled-duration calculation. */
+export interface ScaledDurationResult {
+    /** Duration to pass to `gotoTarget`, clamped to the preset (sec). */
+    readonly duration: number;
+    /** Which channel was the slowest (i.e. dictated the duration).
+     *  `null` when `current` and `target` had no overlapping channels. */
+    readonly limiter: "head" | "antennaR" | "antennaL" | "body_yaw" | null;
+    /** Per-channel un-clamped candidate durations (sec), for log lines
+     *  and "why is this slow?" diagnostics. */
+    readonly perChannel: Readonly<{
+        head?: number;
+        antennaR?: number;
+        antennaL?: number;
+        body_yaw?: number;
+    }>;
+}
+/**
+ * Pick a `goto` duration that "feels right" for the move from
+ * `current` to `target`.
+ *
+ * Algorithm: for each channel defined on both sides, compute its
+ * candidate duration as `channelDistance × channelCost`. Take the max
+ * (slowest channel limits). Clamp to
+ * `[preset.minDurationSec, preset.maxDurationSec]`.
+ *
+ * If no channel overlaps, returns `{ duration: minDurationSec,
+ * limiter: null, perChannel: {} }` — a safe fallback the caller can
+ * still pass to `gotoTarget` (the resulting move is a no-op held over
+ * the min duration).
+ *
+ * **Divergence from Rémi's `reachy-mini-js-practices` bench (intentional):**
+ * his version returns `max` in the no-overlap case. We return `min`
+ * instead — a no-op move doesn't need the maximum dwell time, and the
+ * minimum is the smallest legal duration the daemon accepts. Callers
+ * that need a longer dwell can pass an explicit duration.
+ *
+ * Pure function. No SDK reads, no clock reads.
+ */
+export declare function scaledDuration(current: PartialPose, target: PartialPose, preset?: ScaledDurationPreset): ScaledDurationResult;
+//# sourceMappingURL=distance.d.ts.map

package/dist/animation/distance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distance.d.ts","sourceRoot":"","sources":["../../animation/distance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAEH,KAAK,oBAAoB,EAC5B,MAAM,cAAc,CAAC;AAItB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,YAAY;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAChC,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,WAAW,GACpB,YAAY,CA0Bd;AAgDD,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;0EACsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,IAAI,CAAC;IACvE;+CAC2C;IAC3C,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;CACN;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,WAAW,EACnB,MAAM,GAAE,oBAAqD,GAC9D,oBAAoB,CAwCtB"}

package/dist/animation/distance.js

@@ -0,0 +1,140 @@
+/**
+ * Pose distance + scaled duration math.
+ *
+ * Pure functions, no SDK calls, no clock reads. The caller passes a
+ * `current` pose (typically from `reachy.robotState`) and a `target`
+ * pose; the helpers return per-channel distances and a "feels right"
+ * duration for `gotoTarget`.
+ *
+ * Mirror of the daemon's `utils/interpolation.distance_between_poses`
+ * (head magic-mm) + the scaled-duration algorithm used internally for
+ * `wake_up` / `goto_sleep`. Duplicated client-side so apps know the
+ * duration **synchronously** for audio sync, streamer scheduling, and
+ * live constant tuning.
+ */
+import { radToDeg } from "../lib/math.js";
+import { DEFAULT_SCALED_DURATION_PRESET, } from "./presets.js";
+/**
+ * Compute the per-channel distance between two poses.
+ *
+ * Pure function. Allocates only the output object.
+ */
+export function distanceBetweenPoses(current, target) {
+    const out = {};
+    if (current.head !== undefined && target.head !== undefined) {
+        out.head = headDistanceMagicMm(current.head, target.head);
+    }
+    if (current.antennas !== undefined && target.antennas !== undefined) {
+        const curR = current.antennas[0] ?? 0;
+        const curL = current.antennas[1] ?? 0;
+        const tgtR = target.antennas[0] ?? 0;
+        const tgtL = target.antennas[1] ?? 0;
+        out.antennas = {
+            right: Math.abs(radToDeg(tgtR - curR)),
+            left: Math.abs(radToDeg(tgtL - curL)),
+        };
+    }
+    if (typeof current.body_yaw === "number" &&
+        typeof target.body_yaw === "number") {
+        out.body_yaw = Math.abs(radToDeg(target.body_yaw - current.body_yaw));
+    }
+    return out;
+}
+/**
+ * Fuse translation (mm) and rotation (deg) of a 4×4 head transform
+ * delta into a single "magic-mm" scalar.
+ *
+ * Mirrors Python `distance_between_poses`:
+ *   - Translation distance = `|t_a - t_b|` (Euclidean, mm).
+ *   - Rotation distance = `arccos((trace(R_a^T · R_b) - 1) / 2)` in
+ *     degrees, robust to numerical drift via clamping.
+ *   - Magic-mm = `translation_mm + rotation_deg`.
+ *
+ * Assumes incoming matrices use **metres** for the translation column
+ * (indices 3, 7, 11 in row-major), matching the daemon's wire format,
+ * and converts to millimetres internally.
+ */
+function headDistanceMagicMm(headA, headB) {
+    // Translation in metres at indices 3, 7, 11 (row-major).
+    const dxM = (headA[3] ?? 0) - (headB[3] ?? 0);
+    const dyM = (headA[7] ?? 0) - (headB[7] ?? 0);
+    const dzM = (headA[11] ?? 0) - (headB[11] ?? 0);
+    const translationMm = Math.sqrt(dxM * dxM + dyM * dyM + dzM * dzM) * 1000;
+    // Top-left 3×3 of each, row-major: trace(A^T · B) = Σ_ij A[i,j] * B[i,j]
+    const trace = (headA[0] ?? 0) * (headB[0] ?? 0) +
+        (headA[1] ?? 0) * (headB[1] ?? 0) +
+        (headA[2] ?? 0) * (headB[2] ?? 0) +
+        (headA[4] ?? 0) * (headB[4] ?? 0) +
+        (headA[5] ?? 0) * (headB[5] ?? 0) +
+        (headA[6] ?? 0) * (headB[6] ?? 0) +
+        (headA[8] ?? 0) * (headB[8] ?? 0) +
+        (headA[9] ?? 0) * (headB[9] ?? 0) +
+        (headA[10] ?? 0) * (headB[10] ?? 0);
+    // Clamp to [-1, 1] before arccos to absorb floating-point drift
+    // (matrices that should be orthonormal sometimes have trace numerically
+    // slightly outside the valid range).
+    let cosTheta = (trace - 1) / 2;
+    if (cosTheta > 1)
+        cosTheta = 1;
+    else if (cosTheta < -1)
+        cosTheta = -1;
+    const rotationDeg = radToDeg(Math.acos(cosTheta));
+    return translationMm + rotationDeg;
+}
+/**
+ * Pick a `goto` duration that "feels right" for the move from
+ * `current` to `target`.
+ *
+ * Algorithm: for each channel defined on both sides, compute its
+ * candidate duration as `channelDistance × channelCost`. Take the max
+ * (slowest channel limits). Clamp to
+ * `[preset.minDurationSec, preset.maxDurationSec]`.
+ *
+ * If no channel overlaps, returns `{ duration: minDurationSec,
+ * limiter: null, perChannel: {} }` — a safe fallback the caller can
+ * still pass to `gotoTarget` (the resulting move is a no-op held over
+ * the min duration).
+ *
+ * **Divergence from Rémi's `reachy-mini-js-practices` bench (intentional):**
+ * his version returns `max` in the no-overlap case. We return `min`
+ * instead — a no-op move doesn't need the maximum dwell time, and the
+ * minimum is the smallest legal duration the daemon accepts. Callers
+ * that need a longer dwell can pass an explicit duration.
+ *
+ * Pure function. No SDK reads, no clock reads.
+ */
+export function scaledDuration(current, target, preset = DEFAULT_SCALED_DURATION_PRESET) {
+    const dist = distanceBetweenPoses(current, target);
+    const perChannel = {};
+    if (dist.head !== undefined) {
+        perChannel.head = dist.head * preset.headSecPerMagicMm;
+    }
+    if (dist.antennas !== undefined) {
+        perChannel.antennaR = dist.antennas.right * preset.antennaSecPerDeg;
+        perChannel.antennaL = dist.antennas.left * preset.antennaSecPerDeg;
+    }
+    if (dist.body_yaw !== undefined) {
+        perChannel.body_yaw = dist.body_yaw * preset.bodyYawSecPerDeg;
+    }
+    let limiter = null;
+    // Sentinel: -1 means "no channel seen yet". Distinguishes "no
+    // overlap" (limiter stays null) from "overlap but zero motion"
+    // (limiter = first overlapping channel, raw = 0).
+    let rawDuration = -1;
+    for (const key of ["head", "antennaR", "antennaL", "body_yaw"]) {
+        const value = perChannel[key];
+        if (value === undefined)
+            continue;
+        if (value > rawDuration) {
+            rawDuration = value;
+            limiter = key;
+        }
+    }
+    let duration = rawDuration < 0 ? 0 : rawDuration;
+    if (duration < preset.minDurationSec)
+        duration = preset.minDurationSec;
+    if (duration > preset.maxDurationSec)
+        duration = preset.maxDurationSec;
+    return { duration, limiter, perChannel };
+}
+//# sourceMappingURL=distance.js.map

package/dist/animation/distance.js.map

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

package/dist/animation/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `@pollen-robotics/reachy-mini-sdk/animation` — motion utilities.
+ *
+ * Phase 1 surface, split by concern:
+ *
+ *   - **Types** (`Pose`, `PartialPose`): the wire format every SDK
+ *     motion call already uses.
+ *   - **Canonical pose** (`INIT_POSE` + sub-constants): the "safe
+ *     rest" pose, mirror of the daemon's `Backend.INIT_HEAD_POSE` +
+ *     `Backend.INIT_ANTENNAS_JOINT_POSITIONS`.
+ *   - **Distance math** (`distanceBetweenPoses`, `scaledDuration`):
+ *     "how big is this move" + "how long should it take", computed
+ *     synchronously client-side so apps can sync audio / scheduling
+ *     against it.
+ *   - **Exit handlers** (`safelyReturnToPose`, `installShutdownHandler`):
+ *     thin convenience wrappers around the three-call SDK sequence
+ *     (`setMotorMode` + read state + `gotoTarget`) for `pagehide` /
+ *     `onLeave` call sites.
+ *
+ * Pure-TS: this lib does not introduce any daemon-side primitive. All
+ * motion routes through existing data-channel commands. See
+ * `DESIGN.md` for the rationale.
+ *
+ * @see DESIGN.md
+ * @see APP_CREATION_GUIDE.md — "Robotics best practices" section
+ */
+export type { Pose, PartialPose } from "./pose.js";
+export type { PoseDistance, ScaledDurationResult } from "./distance.js";
+export type { ScaledDurationPreset } from "./presets.js";
+export type { SafelyReturnOptions, InstallShutdownHandlerOptions, } from "./safe-return.js";
+export { INIT_HEAD_POSE_FLAT, INIT_ANTENNAS_RAD, INIT_BODY_YAW_RAD, INIT_POSE, DEFAULT_SCALED_DURATION_PRESET, } from "./presets.js";
+export { distanceBetweenPoses, scaledDuration } from "./distance.js";
+export { safelyReturnToPose, installShutdownHandler } from "./safe-return.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/animation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../animation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACxE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzD,YAAY,EACR,mBAAmB,EACnB,6BAA6B,GAChC,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACH,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,8BAA8B,GACjC,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGrE,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/animation/index.js

@@ -0,0 +1,33 @@
+/**
+ * `@pollen-robotics/reachy-mini-sdk/animation` — motion utilities.
+ *
+ * Phase 1 surface, split by concern:
+ *
+ *   - **Types** (`Pose`, `PartialPose`): the wire format every SDK
+ *     motion call already uses.
+ *   - **Canonical pose** (`INIT_POSE` + sub-constants): the "safe
+ *     rest" pose, mirror of the daemon's `Backend.INIT_HEAD_POSE` +
+ *     `Backend.INIT_ANTENNAS_JOINT_POSITIONS`.
+ *   - **Distance math** (`distanceBetweenPoses`, `scaledDuration`):
+ *     "how big is this move" + "how long should it take", computed
+ *     synchronously client-side so apps can sync audio / scheduling
+ *     against it.
+ *   - **Exit handlers** (`safelyReturnToPose`, `installShutdownHandler`):
+ *     thin convenience wrappers around the three-call SDK sequence
+ *     (`setMotorMode` + read state + `gotoTarget`) for `pagehide` /
+ *     `onLeave` call sites.
+ *
+ * Pure-TS: this lib does not introduce any daemon-side primitive. All
+ * motion routes through existing data-channel commands. See
+ * `DESIGN.md` for the rationale.
+ *
+ * @see DESIGN.md
+ * @see APP_CREATION_GUIDE.md — "Robotics best practices" section
+ */
+// Constants
+export { INIT_HEAD_POSE_FLAT, INIT_ANTENNAS_RAD, INIT_BODY_YAW_RAD, INIT_POSE, DEFAULT_SCALED_DURATION_PRESET, } from "./presets.js";
+// Distance + scaled duration
+export { distanceBetweenPoses, scaledDuration } from "./distance.js";
+// Exit-handler helpers
+export { safelyReturnToPose, installShutdownHandler } from "./safe-return.js";
+//# sourceMappingURL=index.js.map

package/dist/animation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../animation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAWH,YAAY;AACZ,OAAO,EACH,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,8BAA8B,GACjC,MAAM,cAAc,CAAC;AAEtB,6BAA6B;AAC7B,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAErE,uBAAuB;AACvB,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/animation/pose.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pose primitives.
+ *
+ * A `Pose` is the canonical "frame" the SDK sends and receives on the
+ * data channel. The shape mirrors `setTarget` / `gotoTarget` / the
+ * `state` event payload, named so it can be passed around without
+ * anonymous-object soup.
+ *
+ * Channel units (wire format):
+ *   - `head`     : flat 16-float row-major 4×4 homogeneous matrix.
+ *   - `antennas` : [right, left] in **radians**.
+ *   - `body_yaw` : scalar in **radians**.
+ */
+/**
+ * Canonical pose carried over the data channel. All three channels
+ * required.
+ */
+export interface Pose {
+    /** Flat 16-float row-major 4×4 head pose. */
+    head: number[];
+    /** [right, left] in radians. */
+    antennas: [number, number];
+    /** Body yaw in radians. */
+    body_yaw: number;
+}
+/**
+ * Same shape as `Pose` but every channel is optional. Matches the
+ * partial-update semantics of `setTarget` / `gotoTarget`: only the
+ * channels you specify are commanded; the rest keep their previous
+ * target.
+ *
+ * Also the shape `reachy.robotState` actually carries — fields appear
+ * only once the daemon has emitted them.
+ */
+export interface PartialPose {
+    head?: number[];
+    antennas?: [number, number] | number[];
+    body_yaw?: number;
+}
+//# sourceMappingURL=pose.d.ts.map

package/dist/animation/pose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pose.d.ts","sourceRoot":"","sources":["../../animation/pose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,MAAM,WAAW,IAAI;IACjB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,gCAAgC;IAChC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/animation/pose.js

@@ -0,0 +1,15 @@
+/**
+ * Pose primitives.
+ *
+ * A `Pose` is the canonical "frame" the SDK sends and receives on the
+ * data channel. The shape mirrors `setTarget` / `gotoTarget` / the
+ * `state` event payload, named so it can be passed around without
+ * anonymous-object soup.
+ *
+ * Channel units (wire format):
+ *   - `head`     : flat 16-float row-major 4×4 homogeneous matrix.
+ *   - `antennas` : [right, left] in **radians**.
+ *   - `body_yaw` : scalar in **radians**.
+ */
+export {};
+//# sourceMappingURL=pose.js.map

package/dist/animation/pose.js.map

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

package/dist/animation/presets.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Canonical safe-rest pose + scaled-duration preset.
+ *
+ * Both are mirrored from the daemon (Python). The constants live on
+ * both sides because apps need the values **synchronously** in JS:
+ *
+ *   - `INIT_POSE`: the "home" pose for `safelyReturnToPose`'s default
+ *     target. Mirror of `Backend.INIT_HEAD_POSE` + `Backend.INIT_ANTENNAS_JOINT_POSITIONS`
+ *     in `src/reachy_mini/daemon/backend/abstract.py`.
+ *   - `DEFAULT_SCALED_DURATION_PRESET`: the per-channel "magic-mm × cost"
+ *     tuning. Mirror of the constants the daemon already uses for
+ *     `wake_up()` / `goto_sleep()` durations.
+ *
+ * **If you change a value here**, update the matching constant in
+ * `src/reachy_mini/daemon/backend/abstract.py` in the same commit.
+ */
+import type { Pose } from "./pose.js";
+/**
+ * Identity 4×4 head matrix, row-major, flattened.
+ *
+ * Mirror of `Backend.INIT_HEAD_POSE` (Python `np.eye(4)`) in
+ * `abstract.py`. Frozen so apps can't accidentally mutate the shared
+ * instance via `INIT_POSE.head[0] = 0`.
+ */
+export declare const INIT_HEAD_POSE_FLAT: readonly number[];
+/**
+ * Antennas at ~±10° outward (anti-resonance offset).
+ *
+ * Mirror of `Backend.INIT_ANTENNAS_JOINT_POSITIONS = [-0.1745, 0.1745]`
+ * (rounded to match Python bit-for-bit) in `abstract.py`. Background:
+ * straight-up (0°, 0°) antennas mechanically resonate with the
+ * head-motor cogging frequency; the ~10° symmetric outward tilt damps
+ * it. See [PR #952](https://github.com/pollen-robotics/reachy_mini/pull/952).
+ */
+export declare const INIT_ANTENNAS_RAD: readonly [number, number];
+/** Body squared up: head and body share the world-frame yaw axis at rest. */
+export declare const INIT_BODY_YAW_RAD: number;
+/**
+ * Aggregate canonical "safe rest" pose.
+ *
+ * Default target for `safelyReturnToPose`. Deep-frozen, so spread it
+ * if you need a mutable copy:
+ * `{ ...INIT_POSE, head: INIT_POSE.head.slice() }`.
+ */
+export declare const INIT_POSE: Readonly<Pose>;
+/**
+ * Tuning knobs for `scaledDuration` and friends.
+ *
+ * Each `*SecPer*` field is the per-unit cost of motion on that channel.
+ * A move's duration is `max(channelDistance × channelCost)` across all
+ * channels, clamped to `[minDurationSec, maxDurationSec]`. Slowest
+ * channel wins.
+ */
+export interface ScaledDurationPreset {
+    /** Head: `magicMm × this` = head channel candidate (sec). */
+    readonly headSecPerMagicMm: number;
+    /** Per antenna: `|Δ°| × this` = each antenna's candidate (sec). */
+    readonly antennaSecPerDeg: number;
+    /** Body yaw: `|Δ°| × this` = body channel candidate (sec). */
+    readonly bodyYawSecPerDeg: number;
+    /** Lower bound on the final duration (sec). */
+    readonly minDurationSec: number;
+    /** Upper bound on the final duration (sec). */
+    readonly maxDurationSec: number;
+}
+/**
+ * Default tuning, calibrated on a real Reachy Mini via the
+ * `reachy-mini-js-practices` bench (May 2026).
+ *
+ * Per-channel rationale:
+ *   - **head**: 0.015 s per "magic-mm" (translation_mm + rotation_deg).
+ *     0.02 reads as noticeably slow on the head.
+ *   - **antenna**: 0.005 s/°. Antennas are light, but the mechanical
+ *     resonance window (~PR #952) penalises overly fast moves.
+ *   - **body_yaw**: 0.015 s/°. Body sits between head (heavy) and
+ *     antennas (light).
+ *   - **min/max**: 0.01 / 1.5 s. The low floor matters for in-app
+ *     interactions — at 0.2 s, every tiny correction takes 200 ms
+ *     minimum and reads as sluggish.
+ *
+ * Frozen so apps can't mutate the shared instance. Spread to derive
+ * a custom preset: `{ ...DEFAULT_SCALED_DURATION_PRESET, headSecPerMagicMm: 0.03 }`.
+ */
+export declare const DEFAULT_SCALED_DURATION_PRESET: Readonly<ScaledDurationPreset>;
+//# sourceMappingURL=presets.d.ts.map

package/dist/animation/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../animation/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAItC;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAK/C,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAEzB,CAAC;AAEhC,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,MAAU,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,IAAI,CAInC,CAAC;AAIH;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,mEAAmE;IACnE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,oBAAoB,CAMxE,CAAC"}

package/dist/animation/presets.js

@@ -0,0 +1,82 @@
+/**
+ * Canonical safe-rest pose + scaled-duration preset.
+ *
+ * Both are mirrored from the daemon (Python). The constants live on
+ * both sides because apps need the values **synchronously** in JS:
+ *
+ *   - `INIT_POSE`: the "home" pose for `safelyReturnToPose`'s default
+ *     target. Mirror of `Backend.INIT_HEAD_POSE` + `Backend.INIT_ANTENNAS_JOINT_POSITIONS`
+ *     in `src/reachy_mini/daemon/backend/abstract.py`.
+ *   - `DEFAULT_SCALED_DURATION_PRESET`: the per-channel "magic-mm × cost"
+ *     tuning. Mirror of the constants the daemon already uses for
+ *     `wake_up()` / `goto_sleep()` durations.
+ *
+ * **If you change a value here**, update the matching constant in
+ * `src/reachy_mini/daemon/backend/abstract.py` in the same commit.
+ */
+// ─── Canonical safe-rest pose ────────────────────────────────────────────────
+/**
+ * Identity 4×4 head matrix, row-major, flattened.
+ *
+ * Mirror of `Backend.INIT_HEAD_POSE` (Python `np.eye(4)`) in
+ * `abstract.py`. Frozen so apps can't accidentally mutate the shared
+ * instance via `INIT_POSE.head[0] = 0`.
+ */
+export const INIT_HEAD_POSE_FLAT = Object.freeze([
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1,
+]);
+/**
+ * Antennas at ~±10° outward (anti-resonance offset).
+ *
+ * Mirror of `Backend.INIT_ANTENNAS_JOINT_POSITIONS = [-0.1745, 0.1745]`
+ * (rounded to match Python bit-for-bit) in `abstract.py`. Background:
+ * straight-up (0°, 0°) antennas mechanically resonate with the
+ * head-motor cogging frequency; the ~10° symmetric outward tilt damps
+ * it. See [PR #952](https://github.com/pollen-robotics/reachy_mini/pull/952).
+ */
+export const INIT_ANTENNAS_RAD = Object.freeze([
+    -0.1745, 0.1745,
+]);
+/** Body squared up: head and body share the world-frame yaw axis at rest. */
+export const INIT_BODY_YAW_RAD = 0;
+/**
+ * Aggregate canonical "safe rest" pose.
+ *
+ * Default target for `safelyReturnToPose`. Deep-frozen, so spread it
+ * if you need a mutable copy:
+ * `{ ...INIT_POSE, head: INIT_POSE.head.slice() }`.
+ */
+export const INIT_POSE = Object.freeze({
+    head: INIT_HEAD_POSE_FLAT,
+    antennas: INIT_ANTENNAS_RAD,
+    body_yaw: INIT_BODY_YAW_RAD,
+});
+/**
+ * Default tuning, calibrated on a real Reachy Mini via the
+ * `reachy-mini-js-practices` bench (May 2026).
+ *
+ * Per-channel rationale:
+ *   - **head**: 0.015 s per "magic-mm" (translation_mm + rotation_deg).
+ *     0.02 reads as noticeably slow on the head.
+ *   - **antenna**: 0.005 s/°. Antennas are light, but the mechanical
+ *     resonance window (~PR #952) penalises overly fast moves.
+ *   - **body_yaw**: 0.015 s/°. Body sits between head (heavy) and
+ *     antennas (light).
+ *   - **min/max**: 0.01 / 1.5 s. The low floor matters for in-app
+ *     interactions — at 0.2 s, every tiny correction takes 200 ms
+ *     minimum and reads as sluggish.
+ *
+ * Frozen so apps can't mutate the shared instance. Spread to derive
+ * a custom preset: `{ ...DEFAULT_SCALED_DURATION_PRESET, headSecPerMagicMm: 0.03 }`.
+ */
+export const DEFAULT_SCALED_DURATION_PRESET = Object.freeze({
+    headSecPerMagicMm: 0.015,
+    antennaSecPerDeg: 0.005,
+    bodyYawSecPerDeg: 0.015,
+    minDurationSec: 0.01,
+    maxDurationSec: 1.5,
+});
+//# sourceMappingURL=presets.js.map

package/dist/animation/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../../animation/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAChE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IACV,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IACV,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IACV,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;CACb,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA8B,MAAM,CAAC,MAAM,CAAC;IACtE,CAAC,MAAM,EAAE,MAAM;CAClB,CAA8B,CAAC;AAEhC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,iBAAiB,GAAW,CAAC,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAmB,MAAM,CAAC,MAAM,CAAC;IACnD,IAAI,EAAE,mBAAoD;IAC1D,QAAQ,EAAE,iBAAkE;IAC5E,QAAQ,EAAE,iBAAiB;CAC9B,CAAC,CAAC;AAyBH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAmC,MAAM,CAAC,MAAM,CAAC;IACxF,iBAAiB,EAAE,KAAK;IACxB,gBAAgB,EAAE,KAAK;IACvB,gBAAgB,EAAE,KAAK;IACvB,cAAc,EAAE,IAAI;IACpB,cAAc,EAAE,GAAG;CACtB,CAAC,CAAC"}