@pollen-robotics/reachy-mini-sdk 1.7.3-main.7457b2b

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/CHANGELOG.md +188 -0
  2. package/LICENSE +201 -0
  3. package/README.md +129 -0
  4. package/host/APP_AUTHOR_GUIDE.md +646 -0
  5. package/host/README.md +155 -0
  6. package/host/SPEC.md +618 -0
  7. package/host/dist/ReachyHost.d.ts +39 -0
  8. package/host/dist/ReachyHost.d.ts.map +1 -0
  9. package/host/dist/assets/index.d.ts +16 -0
  10. package/host/dist/assets/index.d.ts.map +1 -0
  11. package/host/dist/chunks/index-C3B3FuBC.js +402 -0
  12. package/host/dist/chunks/index-C3B3FuBC.js.map +1 -0
  13. package/host/dist/chunks/mountHost-8f-laxwI.js +48280 -0
  14. package/host/dist/chunks/mountHost-8f-laxwI.js.map +1 -0
  15. package/host/dist/chunks/reachy-mini-sdk-T3Zr7Hwc.js +1726 -0
  16. package/host/dist/chunks/reachy-mini-sdk-T3Zr7Hwc.js.map +1 -0
  17. package/host/dist/components/ConnectingView.d.ts +13 -0
  18. package/host/dist/components/ConnectingView.d.ts.map +1 -0
  19. package/host/dist/components/EmbedFrame.d.ts +16 -0
  20. package/host/dist/components/EmbedFrame.d.ts.map +1 -0
  21. package/host/dist/components/ErrorView.d.ts +21 -0
  22. package/host/dist/components/ErrorView.d.ts.map +1 -0
  23. package/host/dist/components/LeavingView.d.ts +33 -0
  24. package/host/dist/components/LeavingView.d.ts.map +1 -0
  25. package/host/dist/components/PickerView.d.ts +51 -0
  26. package/host/dist/components/PickerView.d.ts.map +1 -0
  27. package/host/dist/components/ReachyHostShell.d.ts +21 -0
  28. package/host/dist/components/ReachyHostShell.d.ts.map +1 -0
  29. package/host/dist/components/SignInView.d.ts +32 -0
  30. package/host/dist/components/SignInView.d.ts.map +1 -0
  31. package/host/dist/components/StepsProgressIndicator.d.ts +41 -0
  32. package/host/dist/components/StepsProgressIndicator.d.ts.map +1 -0
  33. package/host/dist/components/TopBar.d.ts +52 -0
  34. package/host/dist/components/TopBar.d.ts.map +1 -0
  35. package/host/dist/components/WelcomeBackOverlay.d.ts +28 -0
  36. package/host/dist/components/WelcomeBackOverlay.d.ts.map +1 -0
  37. package/host/dist/embed/index.d.ts +150 -0
  38. package/host/dist/embed/index.d.ts.map +1 -0
  39. package/host/dist/entry/auto.d.ts +12 -0
  40. package/host/dist/entry/auto.d.ts.map +1 -0
  41. package/host/dist/entry/auto.js +7 -0
  42. package/host/dist/entry/auto.js.map +1 -0
  43. package/host/dist/entry/embed.d.ts +12 -0
  44. package/host/dist/entry/embed.d.ts.map +1 -0
  45. package/host/dist/entry/embed.js +7 -0
  46. package/host/dist/entry/embed.js.map +1 -0
  47. package/host/dist/hooks/useHfProfile.d.ts +7 -0
  48. package/host/dist/hooks/useHfProfile.d.ts.map +1 -0
  49. package/host/dist/hooks/useHostBridge.d.ts +37 -0
  50. package/host/dist/hooks/useHostBridge.d.ts.map +1 -0
  51. package/host/dist/hooks/useOAuth.d.ts +16 -0
  52. package/host/dist/hooks/useOAuth.d.ts.map +1 -0
  53. package/host/dist/hooks/useRobots.d.ts +17 -0
  54. package/host/dist/hooks/useRobots.d.ts.map +1 -0
  55. package/host/dist/hooks/useSdk.d.ts +16 -0
  56. package/host/dist/hooks/useSdk.d.ts.map +1 -0
  57. package/host/dist/index.d.ts +25 -0
  58. package/host/dist/index.d.ts.map +1 -0
  59. package/host/dist/index.js +15 -0
  60. package/host/dist/index.js.map +1 -0
  61. package/host/dist/lib/centralListener.d.ts +73 -0
  62. package/host/dist/lib/centralListener.d.ts.map +1 -0
  63. package/host/dist/lib/centralRest.d.ts +35 -0
  64. package/host/dist/lib/centralRest.d.ts.map +1 -0
  65. package/host/dist/lib/protocol.d.ts +230 -0
  66. package/host/dist/lib/protocol.d.ts.map +1 -0
  67. package/host/dist/lib/protocol.js +48 -0
  68. package/host/dist/lib/protocol.js.map +1 -0
  69. package/host/dist/lib/sdk-types.d.ts +46 -0
  70. package/host/dist/lib/sdk-types.d.ts.map +1 -0
  71. package/host/dist/lib/settings.d.ts +69 -0
  72. package/host/dist/lib/settings.d.ts.map +1 -0
  73. package/host/dist/lib/signalingUrl.d.ts +28 -0
  74. package/host/dist/lib/signalingUrl.d.ts.map +1 -0
  75. package/host/dist/lib/theme.d.ts +4 -0
  76. package/host/dist/lib/theme.d.ts.map +1 -0
  77. package/host/dist/lib/themeMode.d.ts +9 -0
  78. package/host/dist/lib/themeMode.d.ts.map +1 -0
  79. package/host/dist/lib/tokens.d.ts +64 -0
  80. package/host/dist/lib/tokens.d.ts.map +1 -0
  81. package/host/dist/mountHost.d.ts +36 -0
  82. package/host/dist/mountHost.d.ts.map +1 -0
  83. package/package.json +109 -0
  84. package/reachy-mini-sdk.d.ts +285 -0
  85. package/reachy-mini-sdk.js +2625 -0
package/host/README.md ADDED
@@ -0,0 +1,155 @@
1
+ # Host shell
2
+
3
+ > Shell + iframe bridge for [Reachy Mini](https://huggingface.co/pollen-robotics) web apps.
4
+ > Handles Hugging Face OAuth, robot selection, session lifecycle, and the parent / iframe
5
+ > postMessage protocol so app authors only ship their app, not the plumbing.
6
+
7
+ [![npm version](https://img.shields.io/npm/v/@pollen-robotics/reachy-mini-sdk.svg)](https://www.npmjs.com/package/@pollen-robotics/reachy-mini-sdk)
8
+ [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](../LICENSE)
9
+
10
+ ---
11
+
12
+ ## What is this?
13
+
14
+ Subpath exports of [`@pollen-robotics/reachy-mini-sdk`](https://www.npmjs.com/package/@pollen-robotics/reachy-mini-sdk) that power every Reachy Mini app deployed as a
15
+ [Hugging Face Space](https://huggingface.co/docs/hub/spaces-overview). It exposes:
16
+
17
+ - **`mountHost()`** — the shell rendered around your app's iframe. Renders the
18
+ top bar, sign-in screen, robot picker, and connecting / leaving overlays.
19
+ - **`connectToHost()`** — the vanilla-JS client that runs inside the iframe and
20
+ hands your app a fully-connected `ReachyMini` SDK instance.
21
+
22
+ Two boot modes are supported (cf. [SPEC.md §4](./SPEC.md#4-two-boot-modes)):
23
+
24
+ | Mode | Entry point | Use case |
25
+ |------|-------------|----------|
26
+ | **A. Standalone** | `mountHost()` in `dispatch.ts` | A user opens the Space directly in a browser tab. Full OAuth → picker → iframe sequence. |
27
+ | **B. Mobile handoff** | `connectToHost()` in `embed.ts` | The Reachy Mini mobile app launches the app inside a webview with credentials pre-injected via the URL hash. No shell, no picker. |
28
+
29
+ The same app code works in both modes; only the entry point differs.
30
+
31
+ ## Documentation
32
+
33
+ | Document | Audience | Read it when… |
34
+ |----------|----------|----------------|
35
+ | **[SPEC.md](./SPEC.md)** | host maintainers + app authors | You want the canonical behaviour, state machines, invariants, and wire protocol. |
36
+ | **[APP_AUTHOR_GUIDE.md](./APP_AUTHOR_GUIDE.md)** | app authors | You're building a new Reachy Mini app and need the step-by-step recipe. |
37
+ | **[CHANGELOG.md](../CHANGELOG.md)** | everyone | You're upgrading from a previous version. |
38
+
39
+ App authors should start with the **[APP_AUTHOR_GUIDE](./APP_AUTHOR_GUIDE.md)**.
40
+ Library maintainers and reviewers should start with the **[SPEC](./SPEC.md)**.
41
+
42
+ ## Installation
43
+
44
+ Most app authors load the package from a CDN at runtime; npm install is only
45
+ needed for TypeScript types and local dev:
46
+
47
+ ```bash
48
+ npm install --save-dev @pollen-robotics/reachy-mini-sdk
49
+ ```
50
+
51
+ ```html
52
+ <!-- Loaded at runtime by every Reachy Mini app's index.html.
53
+ Both bundles auto-install the SDK on window.ReachyMini at
54
+ load time, so no separate `<script>` for the SDK is needed. -->
55
+ <script type="module"
56
+ src="https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@1/host/dist/entry/auto.js">
57
+ </script>
58
+ <script type="module"
59
+ src="https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@1/host/dist/entry/embed.js">
60
+ </script>
61
+ ```
62
+
63
+ The CDN URL pins to the **major** version (`@1`), so patch + minor releases
64
+ land in every Space automatically; only a deliberate breaking change requires
65
+ each app to update its tag. The host shares its version with the SDK and the
66
+ daemon (single repo, single release, single npm package).
67
+
68
+ ## 90-second tour
69
+
70
+ A complete Reachy Mini app, in 4 files:
71
+
72
+ **`index.html`** — picks the entry script based on `?embedded=1`:
73
+
74
+ ```html
75
+ <!doctype html>
76
+ <html lang="en">
77
+ <head>
78
+ <meta charset="utf-8" />
79
+ <title>My App</title>
80
+ <script src="https://reachy-mini-js.example/sdk@v1.0.0.js"></script>
81
+ <script type="module" src="/src/dispatch.ts"></script>
82
+ </head>
83
+ <body><div id="root"></div></body>
84
+ </html>
85
+ ```
86
+
87
+ **`src/dispatch.ts`** — routes to host or embed:
88
+
89
+ ```ts
90
+ const isEmbed = new URLSearchParams(window.location.search).get('embedded') === '1';
91
+ if (isEmbed) {
92
+ await import('./embed');
93
+ } else {
94
+ await import('./host');
95
+ }
96
+ ```
97
+
98
+ **`src/host.ts`** — mounts the shell:
99
+
100
+ ```ts
101
+ import { mountHost } from '@pollen-robotics/reachy-mini-sdk/host/auto';
102
+
103
+ mountHost({
104
+ appName: 'My App',
105
+ appIconUrl: '/icon.svg',
106
+ enableMicrophone: false,
107
+ });
108
+ ```
109
+
110
+ **`src/embed.ts`** — connects and runs the app:
111
+
112
+ ```ts
113
+ import { connectToHost } from '@pollen-robotics/reachy-mini-sdk/host/embed';
114
+
115
+ const handle = await connectToHost();
116
+ handle.reachy.setHeadRpyDeg(0, 10, 0);
117
+ handle.onLeave(() => {
118
+ console.log('Session ending, cleaning up.');
119
+ });
120
+ ```
121
+
122
+ That's the whole contract. The host does OAuth, picks the robot, mounts the
123
+ iframe; the embed wakes the robot and drives it. Everything else is your
124
+ app's logic. See the [APP_AUTHOR_GUIDE](./APP_AUTHOR_GUIDE.md) for the
125
+ detailed walk-through and reference apps.
126
+
127
+ ## Reference apps
128
+
129
+ Three open-source apps live alongside this package and are kept in lockstep
130
+ with every release:
131
+
132
+ | App | Stack | What it shows |
133
+ |-----|-------|---------------|
134
+ | [`pollen-robotics/reachy_mini_minimal_conversation`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_minimal_conversation) | Vanilla TypeScript | Smallest possible app. Tech-freedom proof. |
135
+ | [`pollen-robotics/reachy_mini_emotions`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_emotions) | React + MUI | Plutchik emotion wheel + dance triggers. |
136
+ | [`pollen-robotics/reachy_mini_telepresence`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_telepresence) | React + MUI | Live video + head / body teleop. |
137
+
138
+ App authors are free to use any UI framework they want inside the iframe; the
139
+ host doesn't care. This is a hard design rule, not an accident
140
+ ([SPEC §10.2](./SPEC.md#102-tech-freedom-is-a-core-design-principle)).
141
+
142
+ ## Versioning
143
+
144
+ The host ships inside `@pollen-robotics/reachy-mini-sdk` and shares its
145
+ version with the SDK and the Reachy Mini Python daemon (a single source of
146
+ truth, enforced by the npm publish CI). The major version of the **wire
147
+ protocol** is tracked separately in `PROTOCOL_VERSION` and bumped only on
148
+ incompatible postMessage changes (cf. [SPEC §11](./SPEC.md#11-backlog)).
149
+
150
+ App authors should pin to a major (`@1`) in their CDN URL and audit the
151
+ [CHANGELOG](../CHANGELOG.md) on each minor bump.
152
+
153
+ ## License
154
+
155
+ Apache-2.0 - see [LICENSE](../LICENSE).