@pollen-robotics/reachy-mini-sdk 1.12.0-dev.0.main.fca0550 → 1.12.0-rc.1

package/APP_CREATION_GUIDE.md

@@ -1,20 +1,23 @@
 # App Creation Guide
 
-> ### Use `@pollen-robotics/reachy-mini-sdk@1.8.0` today
+> ### Use the latest `@pollen-robotics/reachy-mini-sdk` release
 >
-> Every reference app pins the same SDK release: **`1.8.0`** (the
-> stable npm release; npm versions are immutable, so this is fully
-> reproducible — no commit suffix needed). The host shell, the embed
+> Install the latest stable release from
+> [npm](https://www.npmjs.com/package/@pollen-robotics/reachy-mini-sdk):
+>
+> ```bash
+> npm install @pollen-robotics/reachy-mini-sdk@latest
+> ```
+>
+> This pins the exact resolved version in your `package.json` (npm
+> versions are immutable, so this is fully reproducible). The minimum
+> supported version is **`1.8.0`** — anything older predates the host
+> shell contract described here. Every
+> reference app pins the same SDK release. The host shell, the embed
 > adapter, the SDK runtime, and the daemon on the robot are validated
 > end-to-end against that release. Mixing versions across these
 > boundaries causes silent protocol drift - see
 > [§10 SDK version pinning](#10-sdk-version-pinning).
->
-> Add this to your `package.json`:
->
-> ```json
-> { "dependencies": { "@pollen-robotics/reachy-mini-sdk": "1.8.0" } }
-> ```
 
 **This is the single source of truth for building a Reachy Mini JS
 app.** [`../AGENTS.md`](../AGENTS.md) at the repo root points here;
@@ -127,7 +130,8 @@ npm run dev
 ```
 
 All three reference apps pin `@pollen-robotics/reachy-mini-sdk` to
-the same RC version in their `package.json` - see [§10 SDK version pinning](#10-sdk-version-pinning).
+the same exact version (the latest npm release) in their
+`package.json` - see [§10 SDK version pinning](#10-sdk-version-pinning).
 
 > **Prefer a no-build path?** You can also ship the app as a single
 > `index.html` with the SDK loaded from a CDN. No `package.json`, no
@@ -363,6 +367,7 @@ The resolved `handle` exposes:
 interface ConnectedHandle<TConfig> {
   // Live state at boot
   reachy: ReachyMiniInstance;        // SDK instance, session live, robot awake
+  media: RobotMedia;                 // WebRTC streams - see "Video: use `handle.media`"
   theme: 'dark' | 'light';
   config: TConfig | null;
   appName: string;
@@ -385,6 +390,41 @@ The API is intentionally minimal. If you need a custom channel
 between host and embed, file a feature request - we'll add it as
 a typed message rather than expose a free-form sink.
 
+### Video: use `handle.media`
+
+`connectToHost()` resolves only *after* the WebRTC handshake is
+complete. By the time your app mounts, the SDK's one-shot
+`videoTrack` event and the underlying `pc.ontrack` have **already
+fired**. So `reachy.attachVideo(el)` installs a listener that never
+fires, and an embed never calls `startSession()` again: the element
+stays black forever, with no error anywhere.
+
+`handle.media` exists for exactly this. It replays the streams from a
+synchronous snapshot of the peer connection's receivers, so a
+late-mounting consumer sees the camera immediately:
+
+```ts
+interface RobotMedia {
+  attachVideo(el: HTMLVideoElement): () => void;  // returns a detach fn
+  readonly robotStream: MediaStream | null;       // robot video + audio
+  readonly micStream: MediaStream | null;         // local mic, if enabled
+}
+
+const handle = await connectToHost();
+const detach = handle.media.attachVideo(videoEl);
+handle.onLeave(() => detach());
+```
+
+There is no equivalent race for the data channel, mute toggles, motor
+commands or state updates: the bridge resolves only once ICE **and**
+the data channel are connected, and state events keep arriving (every
+~500 ms, or ~30 Hz after `subscribePose()`). Keep calling `reachy.setHeadRpyDeg(...)`,
+`reachy.setMicMuted(...)` and `reachy.addEventListener('state', ...)`
+directly.
+
+`reachy.attachVideo()` remains correct in a **standalone** app
+(`mountHost`), where your code runs before the session starts.
+
 ### Typing your config
 
 `connectToHost<T>()` types the `config` field; runtime validation
@@ -645,30 +685,31 @@ Pin yours the same way - mixing versions across `@pollen-robotics/reachy-mini-sd
 `@pollen-robotics/reachy-mini-sdk/host`, and the daemon on the robot
 produces hard-to-debug protocol drift.
 
-The current pinned version across all three reference apps:
+Install the latest stable release from
+[npm](https://www.npmjs.com/package/@pollen-robotics/reachy-mini-sdk):
 
-```json
-{
-  "dependencies": {
-    "@pollen-robotics/reachy-mini-sdk": "1.8.0"
-  }
-}
+```bash
+npm install @pollen-robotics/reachy-mini-sdk@latest
 ```
 
-This is the stable `1.8.0` npm release, validated end-to-end against
-the host shell + daemon. npm versions are immutable, so pinning the
-exact version is fully reproducible — no commit suffix needed. **Use
-the same string in your `package.json`** unless you're explicitly
-tracking a newer release.
-
-> When a newer release is published, the source of truth is whichever
-> string is currently shared by [`reachy_mini_minimal_conversation`'s
+npm writes the exact resolved version into your `package.json`. npm
+versions are immutable, so pinning the exact version is fully
+reproducible — no commit suffix needed. The stable release is
+validated end-to-end against the host shell + daemon. **Use the exact
+version string npm writes** unless you're explicitly tracking a newer
+release. In all cases the version must be **`>= 1.8.0`** — older
+releases predate the host shell + protocol v1 contract and are not
+supported.
+
+> The source of truth for "what's current" is the
+> [npm package page](https://www.npmjs.com/package/@pollen-robotics/reachy-mini-sdk)
+> (`npm view @pollen-robotics/reachy-mini-sdk version` works too), and
+> whichever string is currently shared by [`reachy_mini_minimal_conversation`'s
 > `package.json`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_minimal_conversation/blob/main/package.json),
 > [`reachy_mini_emotions`'s `package.json`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_emotions/blob/main/package.json),
 > and [`reachy_mini_telepresence`'s `package.json`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_telepresence/blob/main/package.json).
-> If those three diverge, fall back to whatever this guide says.
 
-### Why pin a specific build (not `^1.8.0` or a major like `@1`)?
+### Why pin a specific build (not `^x.y.z` or a major like `@1`)?
 
 The host shell, the embed adapter (`connectToHost`), the SDK, and the
 robot daemon negotiate over a versioned WebRTC data-channel protocol.
@@ -920,16 +961,18 @@ my-bare-app/
 
 **Importing the SDK from a CDN**
 
-Pin to an exact build SHA - **the same string you would use in
-`package.json`** (see [§10 SDK version pinning](#10-sdk-version-pinning)).
-jsDelivr's `/+esm` suffix tells the CDN to bundle the package to ESM at
-the edge:
+Pin to an exact version - **the same string you would use in
+`package.json`**, i.e. the latest release shown on
+[npm](https://www.npmjs.com/package/@pollen-robotics/reachy-mini-sdk)
+(see [§10 SDK version pinning](#10-sdk-version-pinning)). Substitute it
+for `<version>` below. jsDelivr's `/+esm` suffix tells the CDN to bundle
+the package to ESM at the edge:
 
 ```html
 <script type="module">
-  import { ReachyMini } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@1.8.0/+esm";
-  import { mountHost } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@1.8.0/host/dist/entry/auto.js";
-  import { connectToHost } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@1.8.0/host/dist/entry/embed.js";
+  import { ReachyMini } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@<version>/+esm";
+  import { mountHost } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@<version>/host/dist/entry/auto.js";
+  import { connectToHost } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@<version>/host/dist/entry/embed.js";
 
   window.ReachyMini = ReachyMini;
   window.dispatchEvent(new Event("reachymini:ready"));
@@ -993,9 +1036,10 @@ shell without touching your motion code. The four-step recipe:
    import { ReachyMini } from "https://cdn.jsdelivr.net/gh/pollen-robotics/reachy_mini@v1.7.2/js/reachy-mini.js";
 
    // AFTER (modern host shell, same SDK runtime API)
-   import { ReachyMini } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@1.8.0/+esm";
-   import { mountHost } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@1.8.0/host/dist/entry/auto.js";
-   import { connectToHost } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@1.8.0/host/dist/entry/embed.js";
+   // <version> = latest release on npm (see §10 SDK version pinning)
+   import { ReachyMini } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@<version>/+esm";
+   import { mountHost } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@<version>/host/dist/entry/auto.js";
+   import { connectToHost } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@<version>/host/dist/entry/embed.js";
    ```
 
 2. **Branch on `?embedded=1`.** Wrap your existing app boot in:
@@ -1030,8 +1074,11 @@ shell without touching your motion code. The four-step recipe:
    only exists on the modern SDK; if you weren't using it, nothing
    changes. If you reached into private fields like `robot._pc`
    (RTCPeerConnection), prefer the public alternatives:
-   `robot.attachVideo(videoEl)` for video, `enableMicrophone: true` on
-   `mountHost` for bidirectional audio.
+   `handle.media.attachVideo(videoEl)` for video, `enableMicrophone: true`
+   on `mountHost` for bidirectional audio. Once embedded, use
+   `handle.media.attachVideo()` and **not** `robot.attachVideo()`: the
+   latter silently no-ops because the handshake completed before your
+   app mounted (see [§5 Video](#video-use-handlemedia)).
 
 Your `README.md` frontmatter doesn't need any changes: `sdk: static`
 and `hf_oauth: true` work for both variants. You can still skip
@@ -1467,7 +1514,9 @@ rolled out by the SDK team, not by every app team.
 - App bundles (`index-<hash>.js`): hashed by Vite, cache-busted
   on deploy.
 - `@pollen-robotics/reachy-mini-sdk` in `package.json`: pinned to
-  an **exact version** (today: `1.8.0`), not a range. See
+  an **exact version** (the latest release on
+  [npm](https://www.npmjs.com/package/@pollen-robotics/reachy-mini-sdk)),
+  not a range. See
   [§10 SDK version pinning](#10-sdk-version-pinning).
 - `@pollen-robotics/reachy-mini-sdk/host` subpath imports: same
   pin, same package.

package/README.md

@@ -98,7 +98,7 @@ 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:
 
-- **[`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`.
+- **[`APP_CREATION_GUIDE.md`](./APP_CREATION_GUIDE.md)** — single source of truth for app authors (scaffold, `sdk: static` deploy, host ↔ embed contract, invariants). SDK pin: the latest stable release on [npm](https://www.npmjs.com/package/@pollen-robotics/reachy-mini-sdk).
 - [`host/README.md`](./host/README.md) — one-page tour of the host package layout
 
 ## Migration from `@pollen-robotics/reachy-mini-host`

package/dist/lib/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "1.12.0-dev.0.main.fca0550";
+export declare const SDK_VERSION = "1.12.0-rc.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/lib/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../lib/version.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,WAAW,8BAA8B,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../lib/version.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,WAAW,gBAAgB,CAAC"}

package/dist/lib/version.js

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by scripts/gen-version.mjs — DO NOT EDIT.
 // Source of truth is the `version` field in package.json (bumped by CI at
 // release). Regenerated by the `prebuild:sdk` npm lifecycle hook.
-export const SDK_VERSION = "1.12.0-dev.0.main.fca0550";
+export const SDK_VERSION = "1.12.0-rc.1";
 //# sourceMappingURL=version.js.map

package/dist/lib/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../lib/version.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,0EAA0E;AAC1E,kEAAkE;AAClE,MAAM,CAAC,MAAM,WAAW,GAAG,2BAA2B,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../lib/version.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,0EAA0E;AAC1E,kEAAkE;AAClE,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC"}

package/host/README.md

@@ -32,7 +32,7 @@ The same app code works in both modes; only the entry point differs.
 
 | Document | Audience | Read it when… |
 |----------|----------|----------------|
-| **[`../APP_CREATION_GUIDE.md`](../APP_CREATION_GUIDE.md)** | app authors **and** host maintainers | Single source of truth: scaffold, `sdk: static` deploy, host ↔ embed contract, invariants, protocol v1. Today's SDK pin: `1.8.0`. |
+| **[`../APP_CREATION_GUIDE.md`](../APP_CREATION_GUIDE.md)** | app authors **and** host maintainers | Single source of truth: scaffold, `sdk: static` deploy, host ↔ embed contract, invariants, protocol v1. SDK pin: the latest stable release on [npm](https://www.npmjs.com/package/@pollen-robotics/reachy-mini-sdk). |
 
 App authors and library maintainers both start with the
 **[App Creation Guide](../APP_CREATION_GUIDE.md)**: §1-§12 are the
@@ -149,7 +149,7 @@ incompatible postMessage changes
 (see [`APP_CREATION_GUIDE.md` §13.6](../APP_CREATION_GUIDE.md#136-protocol-v1-messages)).
 
 App authors should **pin to the exact version that the reference
-apps use** - today `1.8.0`, see
+apps use** - the latest stable release on [npm](https://www.npmjs.com/package/@pollen-robotics/reachy-mini-sdk), see
 [`APP_CREATION_GUIDE.md` §10](../APP_CREATION_GUIDE.md#10-sdk-version-pinning).
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pollen-robotics/reachy-mini-sdk",
-  "version": "1.12.0-dev.0.main.fca0550",
+  "version": "1.12.0-rc.1",
   "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": "./dist/reachy-mini-sdk.js",