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

package/host/dist/hooks/useOAuth.d.ts

@@ -0,0 +1,16 @@
+import type { ReachyMiniInstance } from '../lib/sdk-types';
+export interface OAuthState {
+    /** SDK reports an active auth (token + user name resolved). */
+    isAuthenticated: boolean;
+    /** HF account user name when known. */
+    userName: string | null;
+    /** Boot started from an OAuth redirect (i.e. `oauth-pending`
+     *  flag was set). Reset once `isAuthenticated` flips true. */
+    isPostOauthReturn: boolean;
+    /** Async wrapper around `sdk.login()`. */
+    signIn(): Promise<void>;
+    /** Sync wrapper around `sdk.logout()` + mark signed-out. */
+    signOut(): void;
+}
+export declare function useOAuth(sdk: ReachyMiniInstance | null): OAuthState;
+//# sourceMappingURL=useOAuth.d.ts.map

package/host/dist/hooks/useOAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOAuth.d.ts","sourceRoot":"","sources":["../../src/hooks/useOAuth.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAW3D,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,eAAe,EAAE,OAAO,CAAC;IACzB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;kEAC8D;IAC9D,iBAAiB,EAAE,OAAO,CAAC;IAC3B,0CAA0C;IAC1C,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,4DAA4D;IAC5D,OAAO,IAAI,IAAI,CAAC;CACjB;AAsBD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,GAAG,UAAU,CAsInE"}

package/host/dist/hooks/useRobots.d.ts

@@ -0,0 +1,17 @@
+import type { RobotInfo } from '../lib/sdk-types';
+export interface RobotsState {
+    robots: RobotInfo[];
+    /** True on the very first fetch (no data yet). */
+    isLoading: boolean;
+    /** True while a refresh is in-flight (poll or manual). */
+    isRefreshing: boolean;
+    /** Last error message or null. */
+    error: string | null;
+    /** Trigger an immediate REST refresh. */
+    refresh(): void;
+}
+export declare function useRobots(opts: {
+    hfToken: string | null;
+    enabled: boolean;
+}): RobotsState;
+//# sourceMappingURL=useRobots.d.ts.map

package/host/dist/hooks/useRobots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRobots.d.ts","sourceRoot":"","sources":["../../src/hooks/useRobots.ts"],"names":[],"mappings":"AAiDA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAIlD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,YAAY,EAAE,OAAO,CAAC;IACtB,kCAAkC;IAClC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yCAAyC;IACzC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB,GAAG,WAAW,CAqId"}

package/host/dist/hooks/useSdk.d.ts

@@ -0,0 +1,16 @@
+import type { ReachyMiniInstance, ReachyMiniOptions } from '../lib/sdk-types';
+/** Get (or lazily create) the singleton SDK instance. */
+export declare function getOrCreateSdk(opts: ReachyMiniOptions): ReachyMiniInstance;
+/** Fully drop the singleton (used on logout / hard reset). */
+export declare function destroySdk(): void;
+/**
+ * React hook returning the SDK instance + a "ready" boolean that
+ * flips to true once `window.ReachyMini` is defined. The hook
+ * does NOT call `connect()` / `authenticate()`; that's the
+ * responsibility of `useHostPhase`.
+ */
+export declare function useSdk(opts: ReachyMiniOptions): {
+    sdk: ReachyMiniInstance | null;
+    sdkReady: boolean;
+};
+//# sourceMappingURL=useSdk.d.ts.map

package/host/dist/hooks/useSdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSdk.d.ts","sourceRoot":"","sources":["../../src/hooks/useSdk.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAgB1B,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,IAAI,EAAE,iBAAiB,GAAG,kBAAkB,CAgB1E;AAED,8DAA8D;AAC9D,wBAAgB,UAAU,IAAI,IAAI,CASjC;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG;IAC/C,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC/B,QAAQ,EAAE,OAAO,CAAC;CACnB,CA8BA"}

package/host/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * npm entry point for the `./host` subpath.
+ *
+ *   import { mountHost, connectToHost } from '@pollen-robotics/reachy-mini-sdk/host';
+ *
+ * works for IDE autocomplete and for app authors who prefer the
+ * package directly over the CDN `host/auto` bundle.
+ *
+ * Importing this module also auto-installs the SDK constructor on
+ * `window.ReachyMini` (when unset) and dispatches the
+ * `reachymini:ready` event the host's wait loops listen for.
+ * Apps consuming the host via npm therefore no longer need a
+ * separate jsdelivr `<script type="module">` to expose the SDK
+ * on the global — installing this package is enough.
+ */
+export { ReachyHost } from './ReachyHost';
+export type { ReachyHostProps } from './ReachyHost';
+export { mountHost } from './mountHost';
+export type { MountHostOptions, MountedHost } from './mountHost';
+export { connectToHost } from './embed';
+export type { ConnectedHandle, ConnectToHostOptions } from './embed';
+export type { AppConnectingStep, AppPhase, ConfigPayload, CredsBundle, EmbedToHostMsg, HostToEmbedMsg, LeavingReason, ThemeMode, } from './lib/protocol';
+export { PROTOCOL_VERSION, decodeCredsFromHash, encodeCredsToHash, isProtocolMessage, } from './lib/protocol';
+export type { ReachyMiniInstance, ReachyMiniOptions, ReachyMiniConstructor, RobotInfo, } from './lib/sdk-types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAIrE,YAAY,EACV,iBAAiB,EACjB,QAAQ,EACR,aAAa,EACb,WAAW,EACX,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,GACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAIxB,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,SAAS,GACV,MAAM,iBAAiB,CAAC"}

package/host/dist/index.js

@@ -0,0 +1,15 @@
+import { R as o } from "./chunks/reachy-mini-sdk-eBYlC77N.js";
+import { R as s, m as a } from "./chunks/mountHost-8f-laxwI.js";
+import { c as t } from "./chunks/index-CyLPysJS.js";
+import { PROTOCOL_VERSION as c, decodeCredsFromHash as m, encodeCredsToHash as w, isProtocolMessage as h } from "./lib/protocol.js";
+typeof window < "u" && !window.ReachyMini && (window.ReachyMini = o, window.dispatchEvent(new Event("reachymini:ready")));
+export {
+  c as PROTOCOL_VERSION,
+  s as ReachyHost,
+  t as connectToHost,
+  m as decodeCredsFromHash,
+  w as encodeCredsToHash,
+  h as isProtocolMessage,
+  a as mountHost
+};
+//# sourceMappingURL=index.js.map

package/host/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["/**\n * npm entry point for the `./host` subpath.\n *\n *   import { mountHost, connectToHost } from '@pollen-robotics/reachy-mini-sdk/host';\n *\n * works for IDE autocomplete and for app authors who prefer the\n * package directly over the CDN `host/auto` bundle.\n *\n * Importing this module also auto-installs the SDK constructor on\n * `window.ReachyMini` (when unset) and dispatches the\n * `reachymini:ready` event the host's wait loops listen for.\n * Apps consuming the host via npm therefore no longer need a\n * separate jsdelivr `<script type=\"module\">` to expose the SDK\n * on the global — installing this package is enough.\n */\n\nimport { ReachyMini } from '../../reachy-mini-sdk';\n\nif (typeof window !== 'undefined' && !window.ReachyMini) {\n  window.ReachyMini = ReachyMini;\n  window.dispatchEvent(new Event('reachymini:ready'));\n}\n\nexport { ReachyHost } from './ReachyHost';\nexport type { ReachyHostProps } from './ReachyHost';\n\nexport { mountHost } from './mountHost';\nexport type { MountHostOptions, MountedHost } from './mountHost';\n\nexport { connectToHost } from './embed';\nexport type { ConnectedHandle, ConnectToHostOptions } from './embed';\n\n// Protocol types (useful for app authors implementing custom\n// flows or unit-testing their dispatcher).\nexport type {\n  AppConnectingStep,\n  AppPhase,\n  ConfigPayload,\n  CredsBundle,\n  EmbedToHostMsg,\n  HostToEmbedMsg,\n  LeavingReason,\n  ThemeMode,\n} from './lib/protocol';\nexport {\n  PROTOCOL_VERSION,\n  decodeCredsFromHash,\n  encodeCredsToHash,\n  isProtocolMessage,\n} from './lib/protocol';\n\n// SDK types (re-export so app authors can write\n// `import type { ReachyMiniInstance } from '@pollen-robotics/reachy-mini-sdk/host'`.\nexport type {\n  ReachyMiniInstance,\n  ReachyMiniOptions,\n  ReachyMiniConstructor,\n  RobotInfo,\n} from './lib/sdk-types';\n"],"names":["ReachyMini"],"mappings":";;;;AAkBI,OAAO,SAAW,OAAe,CAAC,OAAO,eAC3C,OAAO,aAAaA,GACpB,OAAO,cAAc,IAAI,MAAM,kBAAkB,CAAC;"}

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

@@ -0,0 +1,73 @@
+/**
+ * Long-lived SSE listener channel to Hugging Face central.
+ *
+ * Ported from the Reachy Mini mobile app (`centralListenerStream.ts`).
+ * Why this exists and how it relates to the SDK is documented in
+ * the docstring of `useRobots.ts`; in short:
+ *
+ *  - The host shell needs realtime updates of the user's robot
+ *    fleet (online/offline, busy/free).
+ *  - The ReachyMini SDK can do this, but only by also registering
+ *    a peer slot at central, which then conflicts with the
+ *    iframe's session WebRTC handshake.
+ *  - Solution: open a *bare* SSE channel here, registered with
+ *    `roles: ["listener"]` only. On `close()` (when the user
+ *    selects a robot and we mount the iframe) central retires
+ *    the listener slot via its `token → peer_id` 1:1 mapping, so
+ *    the iframe's SDK opens a fresh slot without contention.
+ *
+ * Wire surface we listen for
+ * ──────────────────────────
+ *  - `welcome`              opening handshake, includes the assigned peerId
+ *  - `list`                 initial robot snapshot
+ *  - `peerStatusChanged`    a robot came online / went offline
+ *  - `sessionStateChanged`  busy / free transition
+ *
+ * Reconnect policy
+ * ────────────────
+ * Network blips, HF Space cold-restarts, and proxy idle culls all
+ * surface as a stream EOF or fetch error. We retry with exponential
+ * backoff capped at `MAX_BACKOFF_MS`, jittered to avoid thundering
+ * herds on a central restart.
+ */
+export interface CentralStreamProducer {
+    id: string;
+    meta?: Record<string, unknown>;
+    busy?: boolean;
+    activeApp?: string | null;
+}
+export interface CentralListEvent {
+    producers: CentralStreamProducer[];
+}
+export interface CentralPeerStatusChangedEvent {
+    peerId: string;
+    roles: string[];
+    meta?: Record<string, unknown>;
+}
+export interface CentralSessionStateChangedEvent {
+    peerId: string;
+    busy: boolean;
+    activeApp: string | null;
+    meta?: Record<string, unknown>;
+}
+export interface OpenCentralListenerOpts {
+    token: string;
+    signalingUrl: string;
+    onList?: (event: CentralListEvent) => void;
+    onPeerStatusChanged?: (event: CentralPeerStatusChangedEvent) => void;
+    onSessionStateChanged?: (event: CentralSessionStateChangedEvent) => void;
+    /** SSE is open and `setPeerStatus(listener)` has been POSTed. */
+    onConnect?: () => void;
+    /** SSE dropped (network, central restart, scheduled reconnect). */
+    onDisconnect?: (reason: string) => void;
+    /** Non-fatal errors. Fatal auth errors end the stream and call
+     *  onDisconnect with a meaningful reason instead. */
+    onError?: (err: Error) => void;
+}
+export interface CentralListenerHandle {
+    /** Tear the stream down. Idempotent. No further callbacks
+     *  fire after this returns. */
+    close(): void;
+}
+export declare function openCentralListener(opts: OpenCentralListenerOpts): CentralListenerHandle;
+//# sourceMappingURL=centralListener.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"centralListener.d.ts","sourceRoot":"","sources":["../../src/lib/centralListener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAgDH,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,qBAAqB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC3C,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,6BAA6B,KAAK,IAAI,CAAC;IACrE,qBAAqB,CAAC,EAAE,CAAC,KAAK,EAAE,+BAA+B,KAAK,IAAI,CAAC;IACzE,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,mEAAmE;IACnE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;yDACqD;IACrD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC;mCAC+B;IAC/B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,uBAAuB,GAC5B,qBAAqB,CAsOvB"}

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

@@ -0,0 +1,35 @@
+/**
+ * Direct REST access to the HF central signaling server.
+ *
+ * The picker needs a list of robots, but opening an SSE
+ * connection from the host shell (via `sdk.connect()`) breaks
+ * the iframe's WebRTC handshake: central can't reliably route
+ * the daemon's SDP offer once two SSE streams have been
+ * registered for the same HF token, even after one disconnects.
+ *
+ * Central exposes a public `GET /api/robot-status` endpoint
+ * authenticated by Bearer token that returns the same producer
+ * list as `setPeerStatus → list`, without requiring an SSE
+ * registration. The mobile app uses this for "remote mode" and
+ * we reuse the exact same wire shape here.
+ */
+import type { RobotInfo } from './sdk-types';
+export interface FetchRobotsResult {
+    ok: boolean;
+    robots: RobotInfo[];
+    reason?: string;
+}
+/**
+ * Fetch the user's robot list directly from central.
+ *
+ * @param signalingUrl Base URL of the central server (e.g.
+ *                     `https://pollen-robotics-reachy-mini-central.hf.space`)
+ * @param hfToken      Hugging Face user token
+ * @param signal       Optional AbortSignal for cancellation
+ */
+export declare function fetchRobotsFromCentral(opts: {
+    signalingUrl: string;
+    hfToken: string;
+    signal?: AbortSignal;
+}): Promise<FetchRobotsResult>;
+//# sourceMappingURL=centralRest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"centralRest.d.ts","sourceRoot":"","sources":["../../src/lib/centralRest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAmB7C,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAkCD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmD7B"}

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

@@ -0,0 +1,230 @@
+/**
+ * postMessage protocol v1 between the host shell (parent window,
+ * exposed via `@pollen-robotics/reachy-mini-sdk/host`) and an
+ * embedded Reachy Mini app (iframe).
+ *
+ * Canonical reference: SPEC.md §6.
+ *
+ * Contract identity
+ * ─────────────────
+ * - Every message carries `version: 1`. Bumping that integer is
+ *   the ONLY way to introduce a breaking change to the wire
+ *   protocol. Additive changes (new optional fields, new typed
+ *   messages) ship without a version bump.
+ * - Every message carries `source: 'reachy-mini'`. Lets receivers
+ *   distinguish our envelopes from unrelated `postMessage` traffic
+ *   (DevTools, MUI portals, browser extensions, ...).
+ * - Both sides validate `event.origin` against the expected origin
+ *   before trusting the payload. In our deployment (same-origin
+ *   iframe within an HF Space) the expected origin is
+ *   `event.origin === window.location.origin`.
+ *
+ * Message families
+ * ────────────────
+ * 1. Lifecycle: boot / ready / leaving. Drive the visible state
+ *    of the host shell.
+ * 2. State: `embed:app-state` lets the host render accurate
+ *    connection / wake-up overlays.
+ * 3. Config & theme: opaque `config` payload + theme push.
+ * 4. Error: `embed:error` for tear-down on app failure.
+ *
+ * Intentionally NOT in v1 (see SPEC §6 and §11):
+ * - No `host:custom` / `embed:custom` free-form channel.
+ * - No `embed:request-config-update` (apps don't push config).
+ * - No heartbeat / ping-pong (backlog).
+ */
+/** Protocol version. Bump on breaking changes. */
+export declare const PROTOCOL_VERSION = 1;
+/** Source tag attached to every envelope. */
+export declare const PROTOCOL_SOURCE: "reachy-mini";
+/** Theme mode the host applies to the embedded app. */
+export type ThemeMode = 'dark' | 'light';
+/**
+ * Connection lifecycle, as observed by the embedded app. Drives
+ * the host's `ConnectingView` stepper and visibility of the
+ * iframe.
+ *
+ *   boot       : app loaded, no SDK action yet
+ *   connecting : ReachyMini.connect() / startSession() in flight
+ *   live       : session up, motors awake, app interactive
+ *   leaving    : `host:leaving` received, app tearing down
+ *   error      : non-recoverable failure
+ */
+export type AppPhase = 'boot' | 'connecting' | 'live' | 'leaving' | 'error';
+/**
+ * Fine-grained step inside `connecting`. Maps to the 3 dots in
+ * `StepsProgressIndicator`:
+ *   - `link`    : waiting for `host:init` / `connect()` in flight
+ *   - `session` : `startSession()` in flight
+ *   - `wake`    : `ensureAwake()` in flight
+ *
+ * Apps that don't differentiate can omit this field; the host
+ * treats it as `link`.
+ */
+export type AppConnectingStep = 'link' | 'session' | 'wake';
+/** Opaque app-specific payload routed through the host. */
+export type ConfigPayload = unknown;
+/** Reason supplied with `host:leaving` for logging. */
+export type LeavingReason = 'user-action' | 'session-stopped' | 'error' | 'pagehide';
+/**
+ * First message sent by the host once the iframe has shouted
+ * `embed:ready`. Carries the credentials + initial state the app
+ * needs to bring a session up.
+ *
+ * Same-origin iframe: the SDK CDN script is imported with a
+ * relative URL from `index.html`. We still pass `signalingUrl`
+ * here so the host can swap centrals (staging / self-hosted)
+ * without a rebuild of the app.
+ */
+export interface HostInitMsg {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'host:init';
+    version: 1;
+    theme: ThemeMode;
+    signalingUrl: string;
+    /** HF OAuth bearer token. Optional for apps that don't need to
+     *  authenticate (rare). */
+    hfToken?: string;
+    /** HF account user name, when known. */
+    userName?: string | null;
+    /** Robot ID selected by the host's picker. */
+    robotPeerId: string;
+    /** Optional opaque payload from `?config=<base64>` or from the
+     *  mobile-app handoff. App is responsible for parsing /
+     *  validating. */
+    config: ConfigPayload;
+    /** Host display name (e.g. "Reachy Mini") - useful for the
+     *  embed if it wants to surface "Connected via …" copy. */
+    hostName: string;
+    /** Embedded app's display name (passed by the dispatcher). */
+    appName: string;
+}
+/** Theme changed live (user toggled OS palette, host UI switched). */
+export interface HostThemeChangedMsg {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'host:theme-changed';
+    version: 1;
+    theme: ThemeMode;
+}
+/** Config updated live without an iframe reload. */
+export interface HostConfigChangedMsg {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'host:config-changed';
+    version: 1;
+    config: ConfigPayload;
+}
+/**
+ * Host is asking the app to wind down cleanly. The app SHOULD:
+ *   1. Stop emitting motion commands.
+ *   2. Disconnect any non-SDK resources (timers, listeners).
+ *   3. Resolve every registered `onLeave` callback before the
+ *      `timeoutMs` deadline; otherwise the host force-unmounts
+ *      the iframe.
+ *
+ * The host does NOT expect an explicit `leave-ack`; resolving
+ * `onLeave` callbacks within the deadline is sufficient.
+ */
+export interface HostLeavingMsg {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'host:leaving';
+    version: 1;
+    reason: LeavingReason;
+    /** Soft deadline in ms. After this the host unmounts the iframe
+     *  regardless. */
+    timeoutMs: number;
+}
+export type HostToEmbedMsg = HostInitMsg | HostThemeChangedMsg | HostConfigChangedMsg | HostLeavingMsg;
+/**
+ * Emitted by the app as early as possible (synchronous tick of
+ * the embed entry, before the SDK is touched). Tells the host
+ * the iframe is alive and ready to receive `host:init`. The host
+ * MUST NOT send `host:init` before seeing this.
+ */
+export interface EmbedReadyMsg {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'embed:ready';
+    version: 1;
+}
+/**
+ * App-level connection state. The host renders its
+ * `ConnectingView` overlay over the (still-mounted) iframe until
+ * it sees `phase === 'live'`. Apps SHOULD emit this on every
+ * transition; the host caches the last value and won't re-render
+ * unless something changes.
+ */
+export interface EmbedAppStateMsg {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'embed:app-state';
+    version: 1;
+    phase: AppPhase;
+    /** Sub-step inside `connecting`. Ignored for other phases. */
+    connectingStep?: AppConnectingStep | null;
+    /** Optional human-readable hint shown in the overlay caption. */
+    message?: string | null;
+}
+/** App requests to leave (user clicked an in-app exit, error,
+ *  ...). The host runs the same tear-down as a top-bar
+ *  "End session". */
+export interface EmbedRequestLeaveMsg {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'embed:request-leave';
+    version: 1;
+}
+/** App-level error report. `fatal: true` switches the host to
+ *  ErrorView; `fatal: false` is logged and may surface a toast. */
+export interface EmbedErrorMsg {
+    source: typeof PROTOCOL_SOURCE;
+    type: 'embed:error';
+    version: 1;
+    message: string;
+    fatal: boolean;
+    detail?: unknown;
+}
+export type EmbedToHostMsg = EmbedReadyMsg | EmbedAppStateMsg | EmbedRequestLeaveMsg | EmbedErrorMsg;
+/**
+ * Serialised credentials passed from the host (Mode A) or the
+ * mobile app (Mode B) to the embed via the URL hash fragment.
+ *
+ * Hash-only (never URL search): browsers don't send the hash to
+ * any server, so the HF token never appears in access logs,
+ * referer headers, or HF Spaces frontend logs.
+ *
+ * The embed wipes the hash with `history.replaceState` on its
+ * first synchronous tick, before any `await`, then proceeds with
+ * the rest of the boot using the in-memory bundle.
+ */
+export interface CredsBundle {
+    hfToken?: string | null;
+    userName?: string | null;
+    robotPeerId: string;
+    signalingUrl: string;
+    theme: ThemeMode;
+    config: ConfigPayload;
+    hostName: string;
+    appName: string;
+}
+/**
+ * Cheap discriminator: does this `unknown` look like a v1
+ * envelope from our protocol? Receivers call this before
+ * narrowing on `type`. Conservative on the version: an unknown
+ * version is treated as "not our protocol" so the receiver
+ * silently ignores it (forward-compat for a future v2 peer).
+ */
+export declare function isProtocolMessage(value: unknown): value is {
+    source: typeof PROTOCOL_SOURCE;
+    type: string;
+    version: number;
+};
+/**
+ * Encode a creds bundle to the URL hash fragment.
+ * URL-safe base64 wrapper around JSON to avoid percent-encoding
+ * noise.
+ */
+export declare function encodeCredsToHash(bundle: CredsBundle): string;
+/**
+ * Decode the creds bundle from a URL hash fragment. Returns
+ * `null` if no `creds=` segment is present or if the payload is
+ * malformed (caller handles the error by rendering ErrorView).
+ */
+export declare function decodeCredsFromHash(hash: string | null): CredsBundle | null;
+//# sourceMappingURL=protocol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/lib/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,kDAAkD;AAClD,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,6CAA6C;AAC7C,eAAO,MAAM,eAAe,EAAG,aAAsB,CAAC;AAEtD,uDAAuD;AACvD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAE5E;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAE5D,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC;AAEpC,uDAAuD;AACvD,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,iBAAiB,GACjB,OAAO,GACP,UAAU,CAAC;AAIf;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,SAAS,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB;+BAC2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB;;sBAEkB;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB;+DAC2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,aAAa,CAAC;IACtB;sBACkB;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,mBAAmB,GACnB,oBAAoB,GACpB,cAAc,CAAC;AAInB;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,QAAQ,CAAC;IAChB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;qBAEqB;AACrB,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;mEACmE;AACnE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,gBAAgB,GAChB,oBAAoB,GACpB,aAAa,CAAC;AAIlB;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,GACb,KAAK,IAAI;IAAE,MAAM,EAAE,OAAO,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAQ5E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAI7D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CAe3E"}

package/host/dist/lib/protocol.js

@@ -0,0 +1,48 @@
+const f = 1, c = "reachy-mini";
+function d(e) {
+  if (!e || typeof e != "object") return !1;
+  const n = e;
+  return n.source === c && typeof n.type == "string" && n.version === 1;
+}
+function u(e) {
+  const n = JSON.stringify(e), o = s(n);
+  return `creds=${encodeURIComponent(o)}`;
+}
+function a(e) {
+  if (!e) return null;
+  const n = e.startsWith("#") ? e.slice(1) : e;
+  for (const o of n.split("&"))
+    if (o.startsWith("creds="))
+      try {
+        const t = decodeURIComponent(o.slice(6)), r = i(t);
+        return JSON.parse(r);
+      } catch (t) {
+        return console.warn("[reachy-mini-sdk/host] failed to decode creds hash", t), null;
+      }
+  return null;
+}
+function s(e) {
+  if (typeof window < "u" && typeof window.btoa == "function") {
+    const n = new TextEncoder().encode(e);
+    let o = "";
+    for (const t of n) o += String.fromCharCode(t);
+    return window.btoa(o);
+  }
+  return Buffer.from(e, "utf8").toString("base64");
+}
+function i(e) {
+  if (typeof window < "u" && typeof window.atob == "function") {
+    const n = window.atob(e), o = new Uint8Array(n.length);
+    for (let t = 0; t < n.length; t++) o[t] = n.charCodeAt(t);
+    return new TextDecoder().decode(o);
+  }
+  return Buffer.from(e, "base64").toString("utf8");
+}
+export {
+  c as PROTOCOL_SOURCE,
+  f as PROTOCOL_VERSION,
+  a as decodeCredsFromHash,
+  u as encodeCredsToHash,
+  d as isProtocolMessage
+};
+//# sourceMappingURL=protocol.js.map

package/host/dist/lib/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sources":["../../src/lib/protocol.ts"],"sourcesContent":["/**\n * postMessage protocol v1 between the host shell (parent window,\n * exposed via `@pollen-robotics/reachy-mini-sdk/host`) and an\n * embedded Reachy Mini app (iframe).\n *\n * Canonical reference: SPEC.md §6.\n *\n * Contract identity\n * ─────────────────\n * - Every message carries `version: 1`. Bumping that integer is\n *   the ONLY way to introduce a breaking change to the wire\n *   protocol. Additive changes (new optional fields, new typed\n *   messages) ship without a version bump.\n * - Every message carries `source: 'reachy-mini'`. Lets receivers\n *   distinguish our envelopes from unrelated `postMessage` traffic\n *   (DevTools, MUI portals, browser extensions, ...).\n * - Both sides validate `event.origin` against the expected origin\n *   before trusting the payload. In our deployment (same-origin\n *   iframe within an HF Space) the expected origin is\n *   `event.origin === window.location.origin`.\n *\n * Message families\n * ────────────────\n * 1. Lifecycle: boot / ready / leaving. Drive the visible state\n *    of the host shell.\n * 2. State: `embed:app-state` lets the host render accurate\n *    connection / wake-up overlays.\n * 3. Config & theme: opaque `config` payload + theme push.\n * 4. Error: `embed:error` for tear-down on app failure.\n *\n * Intentionally NOT in v1 (see SPEC §6 and §11):\n * - No `host:custom` / `embed:custom` free-form channel.\n * - No `embed:request-config-update` (apps don't push config).\n * - No heartbeat / ping-pong (backlog).\n */\n\n/** Protocol version. Bump on breaking changes. */\nexport const PROTOCOL_VERSION = 1;\n\n/** Source tag attached to every envelope. */\nexport const PROTOCOL_SOURCE = 'reachy-mini' as const;\n\n/** Theme mode the host applies to the embedded app. */\nexport type ThemeMode = 'dark' | 'light';\n\n/**\n * Connection lifecycle, as observed by the embedded app. Drives\n * the host's `ConnectingView` stepper and visibility of the\n * iframe.\n *\n *   boot       : app loaded, no SDK action yet\n *   connecting : ReachyMini.connect() / startSession() in flight\n *   live       : session up, motors awake, app interactive\n *   leaving    : `host:leaving` received, app tearing down\n *   error      : non-recoverable failure\n */\nexport type AppPhase = 'boot' | 'connecting' | 'live' | 'leaving' | 'error';\n\n/**\n * Fine-grained step inside `connecting`. Maps to the 3 dots in\n * `StepsProgressIndicator`:\n *   - `link`    : waiting for `host:init` / `connect()` in flight\n *   - `session` : `startSession()` in flight\n *   - `wake`    : `ensureAwake()` in flight\n *\n * Apps that don't differentiate can omit this field; the host\n * treats it as `link`.\n */\nexport type AppConnectingStep = 'link' | 'session' | 'wake';\n\n/** Opaque app-specific payload routed through the host. */\nexport type ConfigPayload = unknown;\n\n/** Reason supplied with `host:leaving` for logging. */\nexport type LeavingReason =\n  | 'user-action'\n  | 'session-stopped'\n  | 'error'\n  | 'pagehide';\n\n/* ─────────────────── HOST → EMBED ─────────────────── */\n\n/**\n * First message sent by the host once the iframe has shouted\n * `embed:ready`. Carries the credentials + initial state the app\n * needs to bring a session up.\n *\n * Same-origin iframe: the SDK CDN script is imported with a\n * relative URL from `index.html`. We still pass `signalingUrl`\n * here so the host can swap centrals (staging / self-hosted)\n * without a rebuild of the app.\n */\nexport interface HostInitMsg {\n  source: typeof PROTOCOL_SOURCE;\n  type: 'host:init';\n  version: 1;\n  theme: ThemeMode;\n  signalingUrl: string;\n  /** HF OAuth bearer token. Optional for apps that don't need to\n   *  authenticate (rare). */\n  hfToken?: string;\n  /** HF account user name, when known. */\n  userName?: string | null;\n  /** Robot ID selected by the host's picker. */\n  robotPeerId: string;\n  /** Optional opaque payload from `?config=<base64>` or from the\n   *  mobile-app handoff. App is responsible for parsing /\n   *  validating. */\n  config: ConfigPayload;\n  /** Host display name (e.g. \"Reachy Mini\") - useful for the\n   *  embed if it wants to surface \"Connected via …\" copy. */\n  hostName: string;\n  /** Embedded app's display name (passed by the dispatcher). */\n  appName: string;\n}\n\n/** Theme changed live (user toggled OS palette, host UI switched). */\nexport interface HostThemeChangedMsg {\n  source: typeof PROTOCOL_SOURCE;\n  type: 'host:theme-changed';\n  version: 1;\n  theme: ThemeMode;\n}\n\n/** Config updated live without an iframe reload. */\nexport interface HostConfigChangedMsg {\n  source: typeof PROTOCOL_SOURCE;\n  type: 'host:config-changed';\n  version: 1;\n  config: ConfigPayload;\n}\n\n/**\n * Host is asking the app to wind down cleanly. The app SHOULD:\n *   1. Stop emitting motion commands.\n *   2. Disconnect any non-SDK resources (timers, listeners).\n *   3. Resolve every registered `onLeave` callback before the\n *      `timeoutMs` deadline; otherwise the host force-unmounts\n *      the iframe.\n *\n * The host does NOT expect an explicit `leave-ack`; resolving\n * `onLeave` callbacks within the deadline is sufficient.\n */\nexport interface HostLeavingMsg {\n  source: typeof PROTOCOL_SOURCE;\n  type: 'host:leaving';\n  version: 1;\n  reason: LeavingReason;\n  /** Soft deadline in ms. After this the host unmounts the iframe\n   *  regardless. */\n  timeoutMs: number;\n}\n\nexport type HostToEmbedMsg =\n  | HostInitMsg\n  | HostThemeChangedMsg\n  | HostConfigChangedMsg\n  | HostLeavingMsg;\n\n/* ─────────────────── EMBED → HOST ─────────────────── */\n\n/**\n * Emitted by the app as early as possible (synchronous tick of\n * the embed entry, before the SDK is touched). Tells the host\n * the iframe is alive and ready to receive `host:init`. The host\n * MUST NOT send `host:init` before seeing this.\n */\nexport interface EmbedReadyMsg {\n  source: typeof PROTOCOL_SOURCE;\n  type: 'embed:ready';\n  version: 1;\n}\n\n/**\n * App-level connection state. The host renders its\n * `ConnectingView` overlay over the (still-mounted) iframe until\n * it sees `phase === 'live'`. Apps SHOULD emit this on every\n * transition; the host caches the last value and won't re-render\n * unless something changes.\n */\nexport interface EmbedAppStateMsg {\n  source: typeof PROTOCOL_SOURCE;\n  type: 'embed:app-state';\n  version: 1;\n  phase: AppPhase;\n  /** Sub-step inside `connecting`. Ignored for other phases. */\n  connectingStep?: AppConnectingStep | null;\n  /** Optional human-readable hint shown in the overlay caption. */\n  message?: string | null;\n}\n\n/** App requests to leave (user clicked an in-app exit, error,\n *  ...). The host runs the same tear-down as a top-bar\n *  \"End session\". */\nexport interface EmbedRequestLeaveMsg {\n  source: typeof PROTOCOL_SOURCE;\n  type: 'embed:request-leave';\n  version: 1;\n}\n\n/** App-level error report. `fatal: true` switches the host to\n *  ErrorView; `fatal: false` is logged and may surface a toast. */\nexport interface EmbedErrorMsg {\n  source: typeof PROTOCOL_SOURCE;\n  type: 'embed:error';\n  version: 1;\n  message: string;\n  fatal: boolean;\n  detail?: unknown;\n}\n\nexport type EmbedToHostMsg =\n  | EmbedReadyMsg\n  | EmbedAppStateMsg\n  | EmbedRequestLeaveMsg\n  | EmbedErrorMsg;\n\n/* ─────────────────── CREDS BUNDLE ─────────────────── */\n\n/**\n * Serialised credentials passed from the host (Mode A) or the\n * mobile app (Mode B) to the embed via the URL hash fragment.\n *\n * Hash-only (never URL search): browsers don't send the hash to\n * any server, so the HF token never appears in access logs,\n * referer headers, or HF Spaces frontend logs.\n *\n * The embed wipes the hash with `history.replaceState` on its\n * first synchronous tick, before any `await`, then proceeds with\n * the rest of the boot using the in-memory bundle.\n */\nexport interface CredsBundle {\n  hfToken?: string | null;\n  userName?: string | null;\n  robotPeerId: string;\n  signalingUrl: string;\n  theme: ThemeMode;\n  config: ConfigPayload;\n  hostName: string;\n  appName: string;\n}\n\n/* ─────────────────── HELPERS ─────────────────── */\n\n/**\n * Cheap discriminator: does this `unknown` look like a v1\n * envelope from our protocol? Receivers call this before\n * narrowing on `type`. Conservative on the version: an unknown\n * version is treated as \"not our protocol\" so the receiver\n * silently ignores it (forward-compat for a future v2 peer).\n */\nexport function isProtocolMessage(\n  value: unknown,\n): value is { source: typeof PROTOCOL_SOURCE; type: string; version: number } {\n  if (!value || typeof value !== 'object') return false;\n  const record = value as Record<string, unknown>;\n  return (\n    record.source === PROTOCOL_SOURCE &&\n    typeof record.type === 'string' &&\n    record.version === PROTOCOL_VERSION\n  );\n}\n\n/**\n * Encode a creds bundle to the URL hash fragment.\n * URL-safe base64 wrapper around JSON to avoid percent-encoding\n * noise.\n */\nexport function encodeCredsToHash(bundle: CredsBundle): string {\n  const json = JSON.stringify(bundle);\n  const b64 = encodeBase64Utf8(json);\n  return `creds=${encodeURIComponent(b64)}`;\n}\n\n/**\n * Decode the creds bundle from a URL hash fragment. Returns\n * `null` if no `creds=` segment is present or if the payload is\n * malformed (caller handles the error by rendering ErrorView).\n */\nexport function decodeCredsFromHash(hash: string | null): CredsBundle | null {\n  if (!hash) return null;\n  const raw = hash.startsWith('#') ? hash.slice(1) : hash;\n  for (const segment of raw.split('&')) {\n    if (!segment.startsWith('creds=')) continue;\n    try {\n      const b64 = decodeURIComponent(segment.slice('creds='.length));\n      const json = decodeBase64Utf8(b64);\n      return JSON.parse(json) as CredsBundle;\n    } catch (err) {\n      console.warn('[reachy-mini-sdk/host] failed to decode creds hash', err);\n      return null;\n    }\n  }\n  return null;\n}\n\n/* UTF-8 safe base64 helpers (btoa / atob choke on non-Latin\n * characters in `config` payloads). Works in browsers and Node\n * (for unit tests). */\n\nfunction encodeBase64Utf8(input: string): string {\n  if (typeof window !== 'undefined' && typeof window.btoa === 'function') {\n    const bytes = new TextEncoder().encode(input);\n    let bin = '';\n    for (const b of bytes) bin += String.fromCharCode(b);\n    return window.btoa(bin);\n  }\n  // Node fallback (tests / SSR).\n  return Buffer.from(input, 'utf8').toString('base64');\n}\n\nfunction decodeBase64Utf8(input: string): string {\n  if (typeof window !== 'undefined' && typeof window.atob === 'function') {\n    const bin = window.atob(input);\n    const bytes = new Uint8Array(bin.length);\n    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);\n    return new TextDecoder().decode(bytes);\n  }\n  return Buffer.from(input, 'base64').toString('utf8');\n}\n"],"names":["PROTOCOL_VERSION","PROTOCOL_SOURCE","isProtocolMessage","value","record","encodeCredsToHash","bundle","json","b64","encodeBase64Utf8","decodeCredsFromHash","hash","raw","segment","decodeBase64Utf8","err","input","bytes","bin","b","i"],"mappings":"AAqCO,MAAMA,IAAmB,GAGnBC,IAAkB;AAmNxB,SAASC,EACdC,GAC4E;AAC5E,MAAI,CAACA,KAAS,OAAOA,KAAU,SAAU,QAAO;AAChD,QAAMC,IAASD;AACf,SACEC,EAAO,WAAWH,KAClB,OAAOG,EAAO,QAAS,YACvBA,EAAO,YAAY;AAEvB;AAOO,SAASC,EAAkBC,GAA6B;AAC7D,QAAMC,IAAO,KAAK,UAAUD,CAAM,GAC5BE,IAAMC,EAAiBF,CAAI;AACjC,SAAO,SAAS,mBAAmBC,CAAG,CAAC;AACzC;AAOO,SAASE,EAAoBC,GAAyC;AAC3E,MAAI,CAACA,EAAM,QAAO;AAClB,QAAMC,IAAMD,EAAK,WAAW,GAAG,IAAIA,EAAK,MAAM,CAAC,IAAIA;AACnD,aAAWE,KAAWD,EAAI,MAAM,GAAG;AACjC,QAAKC,EAAQ,WAAW,QAAQ;AAChC,UAAI;AACF,cAAML,IAAM,mBAAmBK,EAAQ,MAAM,CAAe,CAAC,GACvDN,IAAOO,EAAiBN,CAAG;AACjC,eAAO,KAAK,MAAMD,CAAI;AAAA,MACxB,SAASQ,GAAK;AACZ,uBAAQ,KAAK,sDAAsDA,CAAG,GAC/D;AAAA,MACT;AAEF,SAAO;AACT;AAMA,SAASN,EAAiBO,GAAuB;AAC/C,MAAI,OAAO,SAAW,OAAe,OAAO,OAAO,QAAS,YAAY;AACtE,UAAMC,IAAQ,IAAI,cAAc,OAAOD,CAAK;AAC5C,QAAIE,IAAM;AACV,eAAWC,KAAKF,EAAO,CAAAC,KAAO,OAAO,aAAaC,CAAC;AACnD,WAAO,OAAO,KAAKD,CAAG;AAAA,EACxB;AAEA,SAAO,OAAO,KAAKF,GAAO,MAAM,EAAE,SAAS,QAAQ;AACrD;AAEA,SAASF,EAAiBE,GAAuB;AAC/C,MAAI,OAAO,SAAW,OAAe,OAAO,OAAO,QAAS,YAAY;AACtE,UAAME,IAAM,OAAO,KAAKF,CAAK,GACvBC,IAAQ,IAAI,WAAWC,EAAI,MAAM;AACvC,aAASE,IAAI,GAAGA,IAAIF,EAAI,QAAQE,IAAK,CAAAH,EAAMG,CAAC,IAAIF,EAAI,WAAWE,CAAC;AAChE,WAAO,IAAI,YAAA,EAAc,OAAOH,CAAK;AAAA,EACvC;AACA,SAAO,OAAO,KAAKD,GAAO,QAAQ,EAAE,SAAS,MAAM;AACrD;"}

package/host/dist/lib/sdk-types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Re-export of the SDK type surface, sourced from the canonical
+ * declarations next to the SDK runtime
+ * (`../../../reachy-mini-sdk.d.ts`). Kept as a thin barrel so existing
+ * `import type ... from '../lib/sdk-types'` call sites in the host
+ * code (`useSdk`, `useRobots`, `embed/index`, picker view, etc.)
+ * don't need to reach across the package layout themselves.
+ *
+ * If you're touching the type surface, edit the canonical file at
+ * `js/reachy-mini-sdk.d.ts` — it ships in the npm tarball as
+ * the companion `.d.ts` next to `reachy-mini-sdk.js`.
+ */
+export type { RobotInfo, RobotState, ReachyMiniOptions, ReachyMiniInstance, ReachyMiniConstructor, AutoConnectOptions, AutoConnectRobotChoice, AutoConnectResult, MotionAwaitOptions, SubscribeLogsOptions, } from '../../../reachy-mini-sdk';
+import type { ReachyMiniConstructor } from '../../../reachy-mini-sdk';
+/**
+ * Host-internal global augmentation: the host shell instantiates
+ * `new window.ReachyMini(opts)` (see `useSdk`, `embed/index.ts`)
+ * after either the npm entry points or the CDN bundles have
+ * auto-assigned the constructor at module-load time. We declare
+ * the global as non-optional here so those use sites stay
+ * non-null-asserted on the type level; the runtime guarantee is
+ * upheld by the side-effect imports in `entry/auto.ts`,
+ * `entry/embed.ts` and `index.ts`.
+ *
+ * The SDK package's companion `reachy-mini-sdk.d.ts` deliberately
+ * does NOT augment `Window.ReachyMini` so external consumers who
+ * import only the SDK don't have a phantom non-optional global
+ * appear in their type-checker.
+ */
+declare global {
+    interface Window {
+        ReachyMini: ReachyMiniConstructor;
+        /** Injected by HF Spaces at container start when
+         *  `hf_oauth: true` is set in the Space frontmatter. */
+        huggingface?: {
+            variables?: {
+                OAUTH_CLIENT_ID?: string;
+                OAUTH_SCOPES?: string;
+                SPACE_HOST?: string;
+                SPACE_ID?: string;
+            };
+        };
+    }
+}
+export {};
+//# sourceMappingURL=sdk-types.d.ts.map

package/host/dist/lib/sdk-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-types.d.ts","sourceRoot":"","sources":["../../src/lib/sdk-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EACV,SAAS,EACT,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,UAAU,EAAE,qBAAqB,CAAC;QAClC;gEACwD;QACxD,WAAW,CAAC,EAAE;YACZ,SAAS,CAAC,EAAE;gBACV,eAAe,CAAC,EAAE,MAAM,CAAC;gBACzB,YAAY,CAAC,EAAE,MAAM,CAAC;gBACtB,UAAU,CAAC,EAAE,MAAM,CAAC;gBACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;aACnB,CAAC;SACH,CAAC;KACH;CACF;AAED,OAAO,EAAE,CAAC"}