@pollen-robotics/reachy-mini-sdk 1.7.3-main.5cd69ad

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

@@ -0,0 +1,69 @@
+/**
+ * Settings + auth helpers for the host shell.
+ *
+ * Three concerns live here:
+ *  1. OAuth client ID resolution (HF Spaces injection > caller-
+ *     supplied > `localStorage`).
+ *  2. Dev token seeding: skips the OAuth dance entirely when the
+ *     app author passes `devToken` to `mountHost()`.
+ *  3. Inter-load flags (`oauth-pending` for the "welcome back"
+ *     animation; `signed-out` so we don't auto-relogin after a
+ *     user-initiated logout).
+ *
+ * Storage rules (SPEC §8.2):
+ *  - HF token + user name live in `sessionStorage` (tab-scoped,
+ *    wiped on close). The Reachy Mini SDK reads them from
+ *    `hf_token` / `hf_username` / `hf_token_expires`.
+ *  - Persistent flags (`hf_oauth_client_id`, `oauth-pending`,
+ *    `signed-out`) live in `localStorage`.
+ *  - Tokens have a 15 min TTL by default; the SDK refreshes
+ *    on demand if a real OAuth refresh flow is wired.
+ */
+export type ClientIdSource = 'none' | 'caller' | 'space' | 'localStorage';
+export interface DevTokenConfig {
+    token: string;
+    userName: string;
+}
+/** Resolve the OAuth client ID from all known sources. */
+export declare function resolveClientId(callerSupplied?: string): string | undefined;
+/** Same as `resolveClientId` but reports which source won.
+ *  Useful for the SignInView's "you're using…" hint. */
+export declare function resolveClientIdSource(callerSupplied?: string): {
+    clientId: string | undefined;
+    source: ClientIdSource;
+};
+/** Persist an OAuth client ID for future sessions. */
+export declare function storeClientId(clientId: string): void;
+/** Pre-seed the SDK's auth cache with a personal access token.
+ *  Used in dev to skip the OAuth redirect. */
+export declare function seedDevToken(config: DevTokenConfig): void;
+/** `true` if a dev token was passed to `mountHost()` this page
+ *  load, regardless of whether the session storage was later
+ *  wiped by a sign-out. */
+export declare function hasCachedDevToken(): boolean;
+/** Re-seed the session storage from the cached dev token. No-op
+ *  if no dev token was provided to `mountHost()`. Returns `true`
+ *  iff a token was re-seeded. */
+export declare function rehydrateDevToken(): boolean;
+/** Mark that we're about to start an OAuth redirect. The host
+ *  reads this on the next boot to show the "welcome back" view. */
+export declare function markOAuthPending(): void;
+/** Read and clear the `oauth-pending` flag in one call. Returns
+ *  `true` iff this boot is the result of an OAuth redirect. */
+export declare function consumeOAuthPending(): boolean;
+/** Mark the user as explicitly signed out so the SDK doesn't
+ *  silently re-authenticate from a leftover session cookie. */
+export declare function markUserSignedOut(): void;
+/** Clear the signed-out flag (called when the user clicks
+ *  "Sign in" after a logout). */
+export declare function clearSignedOutFlag(): void;
+/** Returns `true` if the user explicitly signed out earlier. */
+export declare function isUserSignedOut(): boolean;
+/** Wipe HF token keys from sessionStorage. Called by the embed
+ *  on `host:leaving` before the iframe unmounts (SPEC §8.2). */
+export declare function wipeHfSessionStorage(): void;
+/** Decode a base64 JSON `?config=` URL parameter into a typed
+ *  value. Returns `null` on missing / malformed input. The
+ *  caller is responsible for validating the shape. */
+export declare function readUrlConfig<T = unknown>(): T | null;
+//# sourceMappingURL=settings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/lib/settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAYH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,QAAQ,GACR,OAAO,GACP,cAAc,CAAC;AAEnB,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAW3E;AAED;wDACwD;AACxD,wBAAgB,qBAAqB,CACnC,cAAc,CAAC,EAAE,MAAM,GACtB;IAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAW1D;AAED,sDAAsD;AACtD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAMpD;AAWD;8CAC8C;AAC9C,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAYzD;AAED;;2BAE2B;AAC3B,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;iCAEiC;AACjC,wBAAgB,iBAAiB,IAAI,OAAO,CAI3C;AAID;mEACmE;AACnE,wBAAgB,gBAAgB,IAAI,IAAI,CAMvC;AAED;+DAC+D;AAC/D,wBAAgB,mBAAmB,IAAI,OAAO,CAQ7C;AAID;+DAC+D;AAC/D,wBAAgB,iBAAiB,IAAI,IAAI,CAMxC;AAED;iCACiC;AACjC,wBAAgB,kBAAkB,IAAI,IAAI,CAMzC;AAED,gEAAgE;AAChE,wBAAgB,eAAe,IAAI,OAAO,CAMzC;AAID;gEACgE;AAChE,wBAAgB,oBAAoB,IAAI,IAAI,CAQ3C;AAID;;sDAEsD;AACtD,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI,CAUrD"}

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

@@ -0,0 +1,28 @@
+/**
+ * Resolve the signaling URL for the ReachyMini SDK.
+ *
+ * Priority:
+ *   1. `?signaling_url=<url>` URL parameter (override for
+ *      staging / self-hosted central).
+ *   2. `window.huggingface.variables.SIGNALING_URL` if injected
+ *      by the HF Spaces frontmatter (rare).
+ *   3. The canonical Pollen-Robotics central
+ *      (`https://pollen-robotics-reachy-mini-central.hf.space`).
+ *
+ * Why we don't fall back to the SDK's bundled default
+ * ───────────────────────────────────────────────────
+ * The SDK shipped with `tfrere-reachy-mini-central.hf.space`
+ * baked in for legacy reasons. Reachies registered through the
+ * mobile app (the canonical onboarding path) sit on the
+ * `pollen-robotics-...` Space, so a host that lets the SDK fall
+ * back to the legacy URL ends up showing an empty list even when
+ * the user owns one of those robots. We override the default
+ * here so the host and the mobile app talk to the same central
+ * out of the box.
+ *
+ * Never throws. A malformed override just falls back to the
+ * canonical default.
+ */
+export declare const DEFAULT_CENTRAL_SIGNALING_URL = "https://pollen-robotics-reachy-mini-central.hf.space";
+export declare function resolveSignalingUrl(): string;
+//# sourceMappingURL=signalingUrl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"signalingUrl.d.ts","sourceRoot":"","sources":["../../src/lib/signalingUrl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,eAAO,MAAM,6BAA6B,yDACc,CAAC;AAEzD,wBAAgB,mBAAmB,IAAI,MAAM,CAsB5C"}

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

@@ -0,0 +1,4 @@
+import type { Theme } from '@mui/material/styles';
+export declare const lightTheme: Theme;
+export declare const darkTheme: Theme;
+//# sourceMappingURL=theme.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/lib/theme.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AA2FlD,eAAO,MAAM,UAAU,EAAE,KAA2B,CAAC;AACrD,eAAO,MAAM,SAAS,EAAE,KAA0B,CAAC"}

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

@@ -0,0 +1,9 @@
+import type { ThemeMode } from './protocol';
+/**
+ * React hook returning the current theme mode and reacting to OS
+ * palette changes. Stable across React StrictMode double-mounts:
+ * the `matchMedia` listener is registered in an effect with a
+ * proper cleanup.
+ */
+export declare function useThemeMode(): ThemeMode;
+//# sourceMappingURL=themeMode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"themeMode.d.ts","sourceRoot":"","sources":["../../src/lib/themeMode.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA6B5C;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAqBxC"}

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.5cd69ad",
+  "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,294 @@
+/**
+ * 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;
+  /**
+   * @deprecated The SDK no longer acquires the user's microphone. A silent
+   * placeholder audio sender is always set up so apps can `replaceTrack`
+   * their own audio (TTS, files, or — for teleop — the user's mic) onto
+   * it. This option is parsed for backward compatibility but has no
+   * effect.
+   */
+  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;
+  /** Silent placeholder MediaStream the SDK feeds the WebRTC audio
+   *  sender so robot-speaker output can negotiate sendrecv. Apps inject
+   *  their own audio (TTS, files, the user's mic for teleop) by calling
+   *  `replaceTrack()` on the audio sender from `_pc.getSenders()`. */
+  _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;