@pollen-robotics/reachy-mini-sdk 1.7.3-main.b44388c

package/host/dist/lib/tokens.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared design tokens.
+ *
+ * Mirrors `reachy_mini_mobile_app/src/ui/design/tokens.ts` so the
+ * host shell, the mobile shell, and the desktop app share one
+ * visual vocabulary (typography scale, weight scale, radii,
+ * status colours, motion durations). Keep this file in lockstep
+ * with the mobile one - drift is what gets flagged at design
+ * review.
+ *
+ * Safe-area insets are NOT exposed here: the host shell ships on
+ * desktop browsers and HF Spaces, where notch / home-indicator
+ * insets are not a concern. The mobile shell keeps that layer in
+ * its own tokens module.
+ */
+export declare const TYPO: {
+    readonly micro: "0.65rem";
+    readonly tiny: "0.7rem";
+    readonly xs: "0.75rem";
+    readonly sm: "0.8rem";
+    readonly body: "0.85rem";
+    readonly md: "0.9rem";
+    readonly lg: "1rem";
+    readonly xl: "1.1rem";
+    readonly xxl: "1.25rem";
+    readonly hero: "1.5rem";
+    readonly display: "1.625rem";
+};
+export declare const FONT_WEIGHT: {
+    readonly regular: 400;
+    readonly medium: 500;
+    readonly semibold: 600;
+    readonly bold: 700;
+};
+export declare const RADIUS: {
+    readonly xs: 4;
+    readonly sm: 6;
+    readonly md: 8;
+    readonly lg: 12;
+    readonly xl: 16;
+    readonly xxl: 20;
+    readonly pill: 9999;
+    readonly circle: "50%";
+};
+export declare const STATUS: {
+    readonly success: "#22c55e";
+    readonly successSoft: "#16a34a";
+    readonly error: "#ef4444";
+    readonly warning: "#f59e0b";
+    readonly info: "#6366f1";
+};
+export declare const DURATION: {
+    readonly fast: 150;
+    readonly base: 250;
+    readonly slow: 400;
+};
+export declare const LAYOUT: {
+    /** Max width of any centred "card-in-screen" content (sign-in,
+     *  picker, error). Matches the mobile shell. */
+    readonly contentMaxWidth: 420;
+    readonly heroSize: 160;
+    readonly heroSizeSmall: 120;
+};
+//# sourceMappingURL=tokens.d.ts.map

package/host/dist/lib/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/lib/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,IAAI;;;;;;;;;;;;CAYP,CAAC;AAEX,eAAO,MAAM,WAAW;;;;;CAKd,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;;;;;CAST,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC;AAEX,eAAO,MAAM,QAAQ;;;;CAIX,CAAC;AAEX,eAAO,MAAM,MAAM;IACjB;oDACgD;;;;CAIxC,CAAC"}

package/host/dist/mountHost.d.ts

@@ -0,0 +1,36 @@
+import type { ConfigPayload } from './lib/protocol';
+export interface MountHostOptions {
+    /** REQUIRED. Passed to the SDK + shown in the top bar. */
+    appName: string;
+    /** Optional top-bar logo. Recommended PNG/SVG, 32×32. */
+    appIconUrl?: string;
+    /** Optional emoji fallback (used when no icon URL). */
+    appEmoji?: string;
+    /** Allow microphone capture inside the iframe. */
+    enableMicrophone?: boolean;
+    /** HF OAuth client ID override; falls back to HF Spaces
+     *  injection then localStorage. */
+    clientId?: string;
+    /** Dev shortcut: seed a personal access token so the host
+     *  skips the OAuth dance. Strip this before deploying. */
+    devToken?: {
+        token: string;
+        userName: string;
+    };
+    /** Mount target: an HTMLElement or a CSS selector. Defaults
+     *  to `#root` (auto-created if missing). */
+    target?: HTMLElement | string;
+    /** Embed path within the same origin. Defaults to
+     *  `/?embedded=1`. */
+    embedPath?: string;
+    /** Override the host display name in the top bar. */
+    hostName?: string;
+    /** Pre-set the initial config (mostly for tests; production
+     *  reads `?config=` automatically). */
+    initialConfig?: ConfigPayload;
+}
+export interface MountedHost {
+    unmount(): void;
+}
+export declare function mountHost(options: MountHostOptions): MountedHost;
+//# sourceMappingURL=mountHost.d.ts.map

package/host/dist/mountHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mountHost.d.ts","sourceRoot":"","sources":["../src/mountHost.tsx"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;uCACmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;8DAC0D;IAC1D,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;gDAC4C;IAC5C,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAC9B;0BACsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;2CACuC;IACvC,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,WAAW,CA6ChE"}

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "@pollen-robotics/reachy-mini-sdk",
+  "version": "1.7.3-main.b44388c",
+  "description": "Browser SDK for controlling a Reachy Mini robot over WebRTC, plus an optional Hugging Face Spaces host shell (OAuth + robot picker + iframe bridge) exposed via the ./host subpath.",
+  "type": "module",
+  "main": "./reachy-mini-sdk.js",
+  "module": "./reachy-mini-sdk.js",
+  "types": "./reachy-mini-sdk.d.ts",
+  "exports": {
+    ".": {
+      "types": "./reachy-mini-sdk.d.ts",
+      "import": "./reachy-mini-sdk.js",
+      "default": "./reachy-mini-sdk.js"
+    },
+    "./host": {
+      "types": "./host/dist/index.d.ts",
+      "import": "./host/dist/index.js"
+    },
+    "./host/auto": {
+      "types": "./host/dist/entry/auto.d.ts",
+      "import": "./host/dist/entry/auto.js"
+    },
+    "./host/embed": {
+      "types": "./host/dist/entry/embed.d.ts",
+      "import": "./host/dist/entry/embed.js"
+    },
+    "./host/protocol": {
+      "types": "./host/dist/lib/protocol.d.ts",
+      "import": "./host/dist/lib/protocol.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "reachy-mini-sdk.js",
+    "reachy-mini-sdk.d.ts",
+    "host/dist",
+    "host/README.md",
+    "host/SPEC.md",
+    "host/APP_AUTHOR_GUIDE.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "cd host && vite build && tsc -p tsconfig.build.json",
+    "build:watch": "cd host && vite build --watch",
+    "typecheck": "cd host && tsc --noEmit",
+    "dev": "cd host && vite",
+    "clean": "rm -rf host/dist"
+  },
+  "dependencies": {
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@huggingface/hub": "^0.15.2",
+    "@mui/icons-material": "^7.3.5",
+    "@mui/material": "^7.3.5"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react-swc": "^4.0.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "^5.7.3",
+    "vite": "^7.2.1"
+  },
+  "keywords": [
+    "reachy",
+    "reachy-mini",
+    "pollen-robotics",
+    "robot",
+    "robotics",
+    "webrtc",
+    "sdk",
+    "browser",
+    "huggingface-spaces",
+    "host",
+    "iframe",
+    "shell"
+  ],
+  "author": "Pollen Robotics",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/pollen-robotics/reachy_mini#readme",
+  "bugs": {
+    "url": "https://github.com/pollen-robotics/reachy_mini/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pollen-robotics/reachy_mini.git",
+    "directory": "js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/reachy-mini-sdk.d.ts

@@ -0,0 +1,285 @@
+/**
+ * Type declarations for the ReachyMini browser SDK. These are the
+ * canonical types shipped with the npm package — the host shell
+ * (`./host` subpath) re-exports them via `host/src/lib/sdk-types.ts`
+ * so React components, hooks, and the embed client all see exactly
+ * the same surface.
+ *
+ * The runtime lives in `reachy-mini-sdk.js`; this `.d.ts` only
+ * declares the public types. We hand-maintain it (rather than
+ * generating from the JSDoc) so consumers get rich types without an
+ * extra build step on our side.
+ *
+ * Legacy CDN consumers can still expose the constructor on
+ * `window.ReachyMini` themselves; the global declaration at the
+ * bottom keeps that shape typed.
+ */
+
+/** Robot summary returned by the central via `robots`/`robotsChanged`. */
+export interface RobotInfo {
+  id: string;
+  meta?: { name?: string };
+  /**
+   * `true` when the central reports an active session held by
+   * another consumer. Older centrals omit it; default `false`.
+   */
+  busy?: boolean;
+  /**
+   * Friendly name of the app currently holding the session, when
+   * the busy consumer advertised one. Pure UX hint, never trust
+   * for security decisions. `null` / undefined when the robot is
+   * free.
+   */
+  activeApp?: string | null;
+  /**
+   * Network transport reported by the daemon (`wifi` / `usb` /
+   * arbitrary string). Surfaced as a chip on the discovery card.
+   * Older centrals or non-conformant daemons may omit it.
+   */
+  transport?: string | null;
+  /**
+   * Hardware id reported by the daemon (e.g. serial number).
+   * When present, the picker shows it in place of the (longer,
+   * less human-friendly) peer id. Optional.
+   */
+  hardwareId?: string | null;
+}
+
+/** Latest robot telemetry mirrored on `robot.robotState` (wire shape). */
+export interface RobotState {
+  /** Flat row-major 4×4 head pose (16 numbers). */
+  head?: number[];
+  /** [rightRad, leftRad]. */
+  antennas?: number[];
+  /** Radians. */
+  body_yaw?: number;
+  motor_mode?: 'enabled' | 'disabled' | 'gravity_compensation';
+  is_move_running?: boolean;
+}
+
+/** SDK constructor options. */
+export interface ReachyMiniOptions {
+  signalingUrl?: string;
+  enableMicrophone?: boolean;
+  clientId?: string;
+  appName?: string;
+  /**
+   * Hint to the receiver's WebRTC jitter buffer (ms). 0 = "render
+   * ASAP", appropriate for teleop. Spec range [0, 4000]. Browsers
+   * that don't implement `RTCRtpReceiver.jitterBufferTarget` fall
+   * back to default buffering (~150-200 ms).
+   */
+  videoJitterBufferTargetMs?: number;
+  /**
+   * When true AND the URL carries a `robot_peer_id` hint, the SDK
+   * auto-calls `startSession(preselectedRobotId)` once that robot
+   * appears in the central's list after `connect()` resolves. One-shot
+   * per page load; the host iframe relies on this to skip the picker.
+   */
+  autoStartFromUrl?: boolean;
+}
+
+/** Options accepted by `autoConnect()`. */
+export interface AutoConnectOptions {
+  /** Skip `authenticate()`; use this raw HF token. */
+  token?: string;
+  /**
+   * Called in the standalone, multi-robot case to let the consumer
+   * pick a robot from the live list. Return the robot id, or `null`
+   * to cancel.
+   */
+  pickRobot?: (robots: AutoConnectRobotChoice[]) => Promise<string | null>;
+  /** Skip `pickRobot` when exactly one robot is free. Default `true`. */
+  autoPickIfSingle?: boolean;
+  /** Hide busy robots from the picker. Default `true`. */
+  filterBusy?: boolean;
+  /** Call `ensureAwake()` after `startSession()`. Default `true`. */
+  wakeOnConnect?: boolean;
+}
+
+/** Robot row passed to `pickRobot` callback (richer than `RobotInfo`). */
+export interface AutoConnectRobotChoice {
+  id: string;
+  name: string | null;
+  busy: boolean;
+  activeApp: string | null;
+  meta: Record<string, unknown>;
+  lastSeenAgeSeconds: number | null;
+}
+
+/** Resolution payload of `autoConnect()`. */
+export interface AutoConnectResult {
+  robotId: string;
+  robotName: string | null;
+  isEmbedded: boolean;
+  /** Set when `autoConnect()` short-circuited on an already-streaming session. */
+  alreadyStreaming?: boolean;
+}
+
+/** Options for the awaitable motion helpers (`wakeUp`, `gotoSleep`). */
+export interface MotionAwaitOptions {
+  /**
+   * Hard upper bound for the trajectory completion response from the
+   * daemon. Defaults to 8000 ms (typical wake_up is ~1-3 s, but
+   * deeply offset poses can take longer). The returned promise
+   * rejects with a `${command} timed out after ${timeoutMs}ms` error
+   * if the daemon goes silent.
+   */
+  timeoutMs?: number;
+}
+
+/** `subscribeLogs()` argument. */
+export interface SubscribeLogsOptions {
+  onLine: (entry: { timestamp: string; line: string }) => void;
+  onError?: (error: string) => void;
+}
+
+/** Public surface of a ReachyMini SDK instance. */
+export interface ReachyMiniInstance extends EventTarget {
+  readonly state: 'disconnected' | 'connected' | 'streaming';
+  readonly robots: RobotInfo[];
+  /**
+   * Mirror of the latest "state" event detail. Fields appear only once
+   * the daemon has sent the corresponding source field.
+   */
+  readonly robotState: RobotState;
+  readonly username: string | null;
+  readonly isAuthenticated: boolean;
+  readonly micSupported: boolean;
+  readonly micMuted: boolean;
+  readonly audioMuted: boolean;
+  /** Set by the SDK from `?robot_peer_id=` / `#robot_peer_id=`. */
+  readonly preselectedRobotId: string | null;
+  /** `true` iff `preselectedRobotId !== null`. UX branching helper. */
+  readonly isEmbedded: boolean;
+
+  /** Underlying RTCPeerConnection. Apps can read it to inspect
+   *  audio / video transceivers. */
+  _pc: RTCPeerConnection | null;
+  /** Local microphone MediaStream acquired by the SDK on
+   *  `startSession()` when `enableMicrophone` is `true`. */
+  _micStream: MediaStream | null;
+
+  authenticate(): Promise<boolean>;
+  login(): Promise<void>;
+  logout(): void;
+
+  connect(token?: string): Promise<void>;
+  /**
+   * One-shot bring-up: auth → SSE connect → robot selection → session →
+   * wake up. The all-in-one entry point that captures the common
+   * "embed *or* standalone, just get me streaming" flow.
+   */
+  autoConnect(options?: AutoConnectOptions): Promise<AutoConnectResult>;
+  disconnect(): void;
+
+  startSession(robotId: string): Promise<void>;
+  stopSession(): Promise<void>;
+
+  attachVideo(el: HTMLVideoElement): () => void;
+
+  setHeadRpyDeg(roll: number, pitch: number, yaw: number): boolean;
+  setAntennasDeg(right: number, left: number): boolean;
+  setBodyYawDeg(yawDeg: number): boolean;
+  /**
+   * Streaming variant for the trajectory player: sets the full
+   * target frame at 50-100 Hz. Unspecified joints keep their
+   * previous target. Returns `false` if the data channel is not
+   * open.
+   */
+  setTarget(args: {
+    head?: number[];
+    antennas?: number[];
+    body_yaw?: number;
+  }): boolean;
+  /**
+   * Smooth daemon-side interpolation to a target pose over `duration`
+   * seconds. Mirrors `setTarget`'s wire shape and adds a required
+   * `duration` field. Throws `TypeError` on invalid input.
+   */
+  gotoTarget(args: {
+    head?: number[];
+    antennas?: number[];
+    body_yaw?: number;
+    duration: number;
+  }): boolean;
+  /** Send an arbitrary JSON message on the data channel. */
+  sendRaw(data: unknown): boolean;
+  /** Play a sound file on the robot's speakers (basename). */
+  playSound(file: string): boolean;
+
+  setAudioMuted(muted: boolean): void;
+  setMicMuted(muted: boolean): void;
+
+  getVolume(): Promise<number | null>;
+  setVolume(volume: number): Promise<number | null>;
+  getMicrophoneVolume(): Promise<number | null>;
+  setMicrophoneVolume(volume: number): Promise<number | null>;
+
+  /** Daemon version string, or `null` when unavailable. */
+  getVersion(): Promise<string | null>;
+  /** Hardware ID (USB serial), or `null` on developer machines. */
+  getHardwareId(): Promise<string | null>;
+  /** Force a `state` event right now (background poll runs at 500 ms). */
+  requestState(): boolean;
+  /** Subscribe to daemon `journalctl` logs over the data channel. */
+  subscribeLogs(options: SubscribeLogsOptions): () => void;
+
+  /**
+   * Motor torque mode: `enabled` (position control), `disabled`
+   * (limp), `gravity_compensation` (float-by-hand). Returns
+   * `false` if the data channel is not open.
+   */
+  setMotorMode(
+    mode: 'enabled' | 'disabled' | 'gravity_compensation',
+  ): boolean;
+  /**
+   * Per-motor torque toggle. When `ids` is omitted, applies globally
+   * (equivalent to `setMotorMode("enabled" | "disabled")`).
+   */
+  setMotorTorque(on: boolean, ids?: string[] | null): boolean;
+  /**
+   * Play the wake-up trajectory (enables motors first). Resolves on
+   * the daemon's `{command: "wake_up", completed: true}` response,
+   * rejects on `timeoutMs` elapsed or on session teardown.
+   */
+  wakeUp(options?: MotionAwaitOptions): Promise<void>;
+  /**
+   * Play the goto-sleep trajectory. Resolves when the daemon reports
+   * completion. Does NOT touch motor mode; caller manages it.
+   */
+  gotoSleep(options?: MotionAwaitOptions): Promise<void>;
+  /** Read the awake state from the cached `motor_mode`. */
+  isAwake(): boolean;
+  /**
+   * Idempotent wakeUp: noop when already awake. Resolves with
+   * the post-call awake state. Does NOT await the trajectory.
+   */
+  ensureAwake(timeoutMs?: number): Promise<boolean>;
+}
+
+export type ReachyMiniConstructor = new (
+  options?: ReachyMiniOptions,
+) => ReachyMiniInstance;
+
+/** SDK constructor. */
+export const ReachyMini: ReachyMiniConstructor;
+
+/** Degrees → radians. */
+export function degToRad(deg: number): number;
+/** Radians → degrees. */
+export function radToDeg(rad: number): number;
+/** Roll/pitch/yaw (degrees) → 4×4 rotation matrix (ZYX convention). */
+export function rpyToMatrix(
+  rollDeg: number,
+  pitchDeg: number,
+  yawDeg: number,
+): number[][];
+/** Rotation matrix (3×3 or 4×4) → `{ roll, pitch, yaw }` in degrees. */
+export function matrixToRpy(m: number[][]): {
+  roll: number;
+  pitch: number;
+  yaw: number;
+};
+
+export default ReachyMini;