Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(desktop): add the desktop app shell under apps/

nirholasb1aef4a28a2b
diff --git a/apps/desktop/README.md b/apps/desktop/README.md
new file mode 100644
index 000000000..cb631fe3a
--- /dev/null
+++ b/apps/desktop/README.md
@@ -0,0 +1,123 @@
+# three.ws Companion for desktop
+
+A 3D character that lives on your desktop, strolls across the bottom of your
+screen, and walks over to tell you the things worth interrupting you for.
+
+Not a notification center. Not another window to manage. A small person who
+knows which of your messages matter, arrives in the body of whoever sent them,
+and says it out loud.
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│ │
+│ your actual desktop, untouched │
+│ │
+│ ╭───────────────────────────────╮ │
+│ │ SARAH │ │
+│ │ Sarah says she is downstairs │ │
+│ │ and cannot find your door. │ │
+│ │ 88/100 · saved contact; asks │ │
+│ │ you for something directly │ │
+│ │ [ Open ] [ Got it ] │ │
+│ ╰───────────────╮───────────────╯ │
+│ 🚶 ← walks over, waves, speaks │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+## What it does
+
+- **Lives on top of everything**, on every workspace, including over full-screen
+ apps, and is click-through everywhere except the character and its bubble. You
+ never have to move it, and it never eats a click meant for your editor.
+- **Wanders.** It walks to a new spot every half minute or so, facing the way it
+ is going, then idles. It is alive, not a widget.
+- **Delivers in person.** When something clears your bar (a message from a saved
+ contact, a meeting about to start, a one-time code, an agent that decided you
+ need to know), it walks to the middle of the screen, waves, shows the line and
+ says it aloud in that sender's voice, wearing that sender's avatar.
+- **Respects the bar you set.** Threshold, quiet hours, per-contact priority and
+ which sources are connected all live at
+ [three.ws/companion](https://three.ws/companion). This app is a body, not a
+ second set of rules.
+- **Pauses from the tray**, and can start at login.
+
+## Install and run
+
+```bash
+cd apps/desktop
+npm install
+npm start
+```
+
+Then either sign in from the window that opens, or, if you already use the CLI:
+
+```bash
+npx @three-ws/companion login --token cmp_…
+```
+
+Both read the same file (`~/.config/three-ws/companion.json`, or
+`~/Library/Application Support/three-ws/companion.json` on macOS), so signing in
+once signs in everything on that machine. Get the token from
+[three.ws/companion](https://three.ws/companion); rotating it there disconnects
+every device at once.
+
+### Build an installer
+
+```bash
+npm run dist # for the platform you are on
+npm run dist:mac # dmg + zip
+npm run dist:win # nsis
+npm run dist:linux # AppImage + deb
+```
+
+## How it works
+
+```
+three.ws ──SSE──▶ main process ──IPC──▶ transparent window
+ triage @three-ws/companion walk-embed iframe
+ stream + token postMessage contract
+```
+
+- **`src/main.js`** owns the transparent always-on-top window, the tray menu,
+ the delivery stream (`@three-ws/companion`), and the OS-level fallbacks
+ (native notification, `say` on macOS). It hands mouse input back to the OS
+ everywhere the renderer says nothing clickable is.
+- **`src/preload.cjs`** is the only bridge into the renderer: context isolation
+ on, node integration off, six calls exposed and nothing else. The renderer
+ embeds remote content, so it gets no filesystem and no process access.
+- **`src/renderer/`** is the stage. The body is the published three.ws walking
+ avatar embed driven over its
+ [documented postMessage contract](https://three.ws/docs/walk-embed-api), so
+ this app carries no 3D code of its own and inherits every avatar, rig and
+ animation the platform ships.
+
+## Privacy
+
+- The app holds one credential: your bridge token. No mail password, no bot
+ token, no calendar URL ever reaches it.
+- It makes exactly two kinds of outbound request: the delivery stream, and the
+ voice lane that speaks a line. Both go to the server you configured.
+- If you would rather your own inbox never leave your machine at all, run
+ `companion watch-imap --redact` from `@three-ws/companion`: it triages mail
+ locally and sends only the sentence that earned an interruption.
+
+## Platform notes
+
+- **macOS**: the window is a `panel`, so it floats over full-screen apps. The
+ dock icon is hidden; the app lives in the menu bar. `say` is the last-resort
+ voice if the hosted lanes and the built-in speech synthesis both fail.
+- **Windows / Linux**: always-on-top with click-through. Transparent windows
+ need a compositor; on a bare X11 session without one the window falls back to
+ an opaque strip, and the tray menu still works.
+- Multi-monitor: the stage tracks the primary display's work area and follows
+ resolution changes.
+
+## Related
+
+- [`packages/companion-sdk`](../../packages/companion-sdk) - the client, the triage rules, the CLI, the MCP server.
+- [`three.ws/companion`](https://three.ws/companion) - sources, contacts, threshold, quiet hours.
+- [`docs/companion.md`](../../docs/companion.md) - the whole system, and every bridge recipe.
+
+## License
+
+Apache-2.0
diff --git a/apps/desktop/assets/icon.png b/apps/desktop/assets/icon.png
new file mode 100644
index 000000000..25734ed31
Binary files /dev/null and b/apps/desktop/assets/icon.png differ
diff --git a/apps/desktop/assets/tray-icon.png b/apps/desktop/assets/tray-icon.png
new file mode 100644
index 000000000..25734ed31
Binary files /dev/null and b/apps/desktop/assets/tray-icon.png differ
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
new file mode 100644
index 000000000..219f3f584
--- /dev/null
+++ b/apps/desktop/package.json
@@ -0,0 +1,63 @@
+{
+ "name": "three-ws-companion-desktop",
+ "productName": "three.ws Companion",
+ "version": "0.1.0",
+ "description": "A 3D companion that lives on your desktop, walks across it, and tells you the things worth interrupting you for.",
+ "author": "three.ws <[email protected]> (https://three.ws)",
+ "license": "Apache-2.0",
+ "homepage": "https://three.ws/companion",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/nirholas/three.ws.git",
+ "directory": "apps/desktop"
+ },
+ "private": true,
+ "type": "module",
+ "main": "src/main.js",
+ "scripts": {
+ "start": "electron .",
+ "dev": "electron . --dev",
+ "dist": "electron-builder --publish never",
+ "dist:mac": "electron-builder --mac --publish never",
+ "dist:win": "electron-builder --win --publish never",
+ "dist:linux": "electron-builder --linux --publish never"
+ },
+ "dependencies": {
+ "@three-ws/companion": "file:../../packages/companion-sdk"
+ },
+ "devDependencies": {
+ "electron": "^33.2.0",
+ "electron-builder": "^25.1.8"
+ },
+ "build": {
+ "appId": "ws.three.companion",
+ "productName": "three.ws Companion",
+ "files": [
+ "src/**/*",
+ "assets/**/*",
+ "node_modules/**/*"
+ ],
+ "mac": {
+ "category": "public.app-category.productivity",
+ "icon": "assets/icon.png",
+ "target": [
+ "dmg",
+ "zip"
+ ]
+ },
+ "win": {
+ "icon": "assets/icon.png",
+ "target": [
+ "nsis"
+ ]
+ },
+ "linux": {
+ "icon": "assets/icon.png",
+ "category": "Utility",
+ "target": [
+ "AppImage",
+ "deb"
+ ]
+ }
+ }
+}
diff --git a/apps/desktop/src/main.js b/apps/desktop/src/main.js
new file mode 100644
index 000000000..07c94aa44
--- /dev/null
+++ b/apps/desktop/src/main.js
@@ -0,0 +1,315 @@
+// three.ws Companion for the desktop - the main process.
+//
+// What this app is: a transparent, click-through window the size of your screen
+// with a 3D character living in it. The character walks across the bottom of
+// the desktop, and when something arrives that clears your bar (a message from
+// a saved contact, a meeting about to start, a one-time code, an agent that
+// decided you need to know), it walks over, turns to you, and says it out loud.
+//
+// Three details make it feel like part of the machine rather than a browser:
+//
+// 1. The window ignores the mouse everywhere except the character and its
+// speech bubble. `setIgnoreMouseEvents(true, { forward: true })` still
+// delivers move events to the renderer, so the renderer tells us the
+// moment the pointer is over something clickable and we hand input back.
+// 2. It is visible on every workspace, including over full-screen apps
+// (macOS panel level), so it is a companion rather than another window to
+// manage.
+// 3. It holds no credentials of its own. The bridge token is the same one the
+// CLI uses (packages/companion-sdk/src/config.js), so `companion login` on
+// the command line signs this app in too, and rotating the token at
+// three.ws/companion revokes every device at once.
+
+import { app, BrowserWindow, Tray, Menu, ipcMain, screen, shell, Notification, nativeImage } from 'electron';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { createCompanionClient } from '@three-ws/companion';
+import { resolveCredentials, writeConfig, configPath } from '@three-ws/companion/config';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ASSETS = join(__dirname, '..', 'assets');
+
+// How tall a strip of the screen the companion lives in. The window is only as
+// large as it needs to be: a full-screen transparent window over every display
+// costs compositor work for nothing.
+const STAGE_HEIGHT = 420;
+
+const state = {
+ window: null,
+ tray: null,
+ client: null,
+ stopStream: null,
+ paused: false,
+ lastDelivery: null,
+ connected: false,
+ signInWindow: null,
+};
+
+function credentials() {
+ return resolveCredentials();
+}
+
+// ── The stage window ─────────────────────────────────────────────────────────
+
+function createStageWindow() {
+ const display = screen.getPrimaryDisplay();
+ const { x, y, width, height } = display.workArea;
+
+ const win = new BrowserWindow({
+ x,
+ y: y + Math.max(0, height - STAGE_HEIGHT),
+ width,
+ height: Math.min(STAGE_HEIGHT, height),
+ transparent: true,
+ frame: false,
+ resizable: false,
+ movable: false,
+ minimizable: false,
+ maximizable: false,
+ fullscreenable: false,
+ skipTaskbar: true,
+ hasShadow: false,
+ focusable: false,
+ // 'panel' floats above full-screen apps on macOS; the other platforms
+ // take the plain always-on-top path.
+ ...(process.platform === 'darwin' ? { type: 'panel' } : {}),
+ webPreferences: {
+ preload: join(__dirname, 'preload.cjs'),
+ contextIsolation: true,
+ nodeIntegration: false,
+ // The renderer embeds three.ws/walk-embed in an iframe; that is the
+ // only remote content it loads, and it runs sandboxed.
+ sandbox: false,
+ },
+ });
+
+ win.setAlwaysOnTop(true, 'screen-saver');
+ win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+ // Click-through by default; the renderer hands input back when the pointer
+ // is genuinely over the character or its bubble.
+ win.setIgnoreMouseEvents(true, { forward: true });
+ win.loadFile(join(__dirname, 'renderer', 'index.html'));
+
+ if (process.argv.includes('--dev')) win.webContents.openDevTools({ mode: 'detach' });
+
+ // Keep the stage glued to the bottom of whatever the display becomes.
+ const reposition = () => {
+ if (win.isDestroyed()) return;
+ const area = screen.getPrimaryDisplay().workArea;
+ win.setBounds({
+ x: area.x,
+ y: area.y + Math.max(0, area.height - STAGE_HEIGHT),
+ width: area.width,
+ height: Math.min(STAGE_HEIGHT, area.height),
+ });
+ };
+ screen.on('display-metrics-changed', reposition);
+ screen.on('display-added', reposition);
+ screen.on('display-removed', reposition);
+
+ return win;
+}
+
+function send(channel, payload) {
+ if (state.window && !state.window.isDestroyed()) state.window.webContents.send(channel, payload);
+}
+
+// ── The delivery stream ──────────────────────────────────────────────────────
+
+function connect() {
+ state.stopStream?.();
+ state.stopStream = null;
+ state.connected = false;
+
+ const { token, apiBase } = credentials();
+ if (!token) {
+ send('companion:status', { signedIn: false, apiBase });
+ refreshTray();
+ return;
+ }
+
+ state.client = createCompanionClient({ token, apiBase });
+ send('companion:status', { signedIn: true, apiBase, paused: state.paused });
+
+ state.stopStream = state.client.stream({
+ onOpen: (hello) => {
+ state.connected = true;
+ refreshTray();
+ send('companion:connected', { ...hello, apiBase });
+ },
+ onDelivery: (delivery) => {
+ state.lastDelivery = delivery;
+ if (state.paused) return;
+ send('companion:delivery', delivery);
+ // The stage says it; the OS notification is the fallback for a
+ // machine whose screen is locked or whose GPU refused the renderer.
+ if (!state.window || state.window.isDestroyed()) notifyNatively(delivery);
+ state.client.markDelivered(delivery.id).catch(() => {});
+ },
+ onError: () => {
+ state.connected = false;
+ refreshTray();
+ },
+ });
+ refreshTray();
+}
+
+function notifyNatively(delivery) {
+ if (!Notification.isSupported()) return;
+ new Notification({
+ title: delivery.speaker || 'Your companion',
+ body: delivery.spoken_line || delivery.title,
+ silent: false,
+ }).show();
+}
+
+// ── Tray ─────────────────────────────────────────────────────────────────────
+
+function refreshTray() {
+ if (!state.tray) return;
+ const { token } = credentials();
+ const status = !token
+ ? 'Not signed in'
+ : state.paused
+ ? 'Paused'
+ : state.connected
+ ? 'Listening'
+ : 'Reconnecting…';
+
+ state.tray.setToolTip(`three.ws Companion - ${status}`);
+ state.tray.setContextMenu(Menu.buildFromTemplate([
+ { label: `three.ws Companion (${status})`, enabled: false },
+ { type: 'separator' },
+ {
+ label: state.paused ? 'Resume' : 'Pause deliveries',
+ click: () => {
+ state.paused = !state.paused;
+ send('companion:status', { signedIn: Boolean(token), paused: state.paused });
+ refreshTray();
+ },
+ },
+ {
+ label: 'Say the last one again',
+ enabled: Boolean(state.lastDelivery),
+ click: () => state.lastDelivery && send('companion:delivery', state.lastDelivery),
+ },
+ { type: 'separator' },
+ { label: token ? 'Change bridge token…' : 'Sign in…', click: openSignIn },
+ { label: 'Open three.ws/companion', click: () => shell.openExternal(`${credentials().apiBase}/companion`) },
+ {
+ label: 'Start at login',
+ type: 'checkbox',
+ checked: app.getLoginItemSettings().openAtLogin,
+ click: (item) => app.setLoginItemSettings({ openAtLogin: item.checked, openAsHidden: true }),
+ },
+ { type: 'separator' },
+ { label: `Config: ${configPath()}`, enabled: false },
+ { label: 'Quit', role: 'quit' },
+ ]));
+}
+
+// ── Sign in ──────────────────────────────────────────────────────────────────
+
+function openSignIn() {
+ if (state.signInWindow && !state.signInWindow.isDestroyed()) {
+ state.signInWindow.focus();
+ return;
+ }
+ state.signInWindow = new BrowserWindow({
+ width: 460,
+ height: 380,
+ resizable: false,
+ title: 'Sign in to your companion',
+ webPreferences: {
+ preload: join(__dirname, 'preload.cjs'),
+ contextIsolation: true,
+ nodeIntegration: false,
+ },
+ });
+ state.signInWindow.loadFile(join(__dirname, 'renderer', 'sign-in.html'));
+ state.signInWindow.on('closed', () => {
+ state.signInWindow = null;
+ });
+}
+
+// ── IPC ──────────────────────────────────────────────────────────────────────
+
+ipcMain.handle('companion:credentials', () => {
+ const { token, apiBase } = credentials();
+ return { signedIn: Boolean(token), apiBase, paused: state.paused, configPath: configPath() };
+});
+
+ipcMain.handle('companion:save-token', async (_event, { token, apiBase }) => {
+ const trimmed = String(token || '').trim();
+ if (!trimmed) return { ok: false, error: 'Paste the bridge token from three.ws/companion.' };
+ const base = String(apiBase || credentials().apiBase);
+ try {
+ // Prove it before storing it: a bad token should fail here, in a window
+ // the person is looking at, not silently at 3am.
+ await createCompanionClient({ token: trimmed, apiBase: base }).list({ limit: 1 });
+ } catch (err) {
+ return { ok: false, error: `That token was refused: ${err.message}` };
+ }
+ writeConfig({ token: trimmed, apiBase: base });
+ connect();
+ return { ok: true };
+});
+
+ipcMain.handle('companion:open-external', (_event, url) => {
+ const target = String(url || '');
+ if (!/^https?:\/\//i.test(target)) return false;
+ shell.openExternal(target);
+ return true;
+});
+
+// The renderer owns hit-testing: it knows where the character and bubble are.
+ipcMain.on('companion:set-interactive', (_event, interactive) => {
+ if (!state.window || state.window.isDestroyed()) return;
+ state.window.setIgnoreMouseEvents(!interactive, { forward: true });
+});
+
+// macOS ships a real speech synthesiser; used when the hosted voice lanes and
+// the renderer's own speech synthesis both come up empty.
+ipcMain.on('companion:say-native', (_event, text) => {
+ if (process.platform !== 'darwin') return;
+ try {
+ spawn('say', [String(text).slice(0, 500)], { stdio: 'ignore', detached: true }).unref();
+ } catch {
+ /* no `say` binary: the bubble already carries the line */
+ }
+});
+
+ipcMain.on('companion:notify-native', (_event, delivery) => notifyNatively(delivery || {}));
+
+// ── Lifecycle ────────────────────────────────────────────────────────────────
+
+// One instance only: two companions on one desktop would speak in unison.
+if (!app.requestSingleInstanceLock()) {
+ app.quit();
+} else {
+ app.on('second-instance', () => openSignIn());
+
+ app.whenReady().then(() => {
+ // The dock icon is noise for something that lives in the menu bar.
+ if (process.platform === 'darwin') app.dock?.hide();
+
+ state.window = createStageWindow();
+
+ const icon = nativeImage.createFromPath(join(ASSETS, 'tray-icon.png'));
+ state.tray = new Tray(icon.isEmpty() ? nativeImage.createEmpty() : icon.resize({ width: 18, height: 18 }));
+ refreshTray();
+ state.tray.on('click', () => state.tray.popUpContextMenu());
+
+ connect();
+
+ if (!credentials().token) openSignIn();
+ });
+
+ // A companion has no windows to close back into: it lives in the tray.
+ app.on('window-all-closed', (event) => event.preventDefault?.());
+
+ app.on('before-quit', () => {
+ state.stopStream?.();
+ });
+}
diff --git a/apps/desktop/src/preload.cjs b/apps/desktop/src/preload.cjs
new file mode 100644
index 000000000..b61f8ca50
--- /dev/null
+++ b/apps/desktop/src/preload.cjs
@@ -0,0 +1,35 @@
+// The only bridge between the companion's renderer and the machine.
+//
+// Context isolation is on and node integration is off, so the renderer (which
+// embeds remote content from three.ws in an iframe) can reach exactly these
+// calls and nothing else. No fs, no child_process, no ipcRenderer.
+
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('companion', {
+ // State
+ credentials: () => ipcRenderer.invoke('companion:credentials'),
+ saveToken: (payload) => ipcRenderer.invoke('companion:save-token', payload),
+
+ // Events from the main process
+ onDelivery: (handler) => {
+ const listener = (_event, delivery) => handler(delivery);
+ ipcRenderer.on('companion:delivery', listener);
+ return () => ipcRenderer.removeListener('companion:delivery', listener);
+ },
+ onStatus: (handler) => {
+ const listener = (_event, status) => handler(status);
+ ipcRenderer.on('companion:status', listener);
+ ipcRenderer.on('companion:connected', listener);
+ return () => {
+ ipcRenderer.removeListener('companion:status', listener);
+ ipcRenderer.removeListener('companion:connected', listener);
+ };
+ },
+
+ // Actions
+ setInteractive: (interactive) => ipcRenderer.send('companion:set-interactive', Boolean(interactive)),
+ sayNative: (text) => ipcRenderer.send('companion:say-native', String(text || '')),
+ notifyNative: (delivery) => ipcRenderer.send('companion:notify-native', delivery),
+ openExternal: (url) => ipcRenderer.invoke('companion:open-external', url),
+});
diff --git a/apps/desktop/src/renderer/companion.js b/apps/desktop/src/renderer/companion.js
new file mode 100644
index 000000000..6a98337a4
--- /dev/null
+++ b/apps/desktop/src/renderer/companion.js
@@ -0,0 +1,268 @@
+// The desktop companion's renderer: a character that lives on your screen.
+//
+// Three jobs:
+// 1. Wander. Every so often the character strolls to a new spot along the
+// bottom of the display, facing the way it is going, and idles there. The
+// motion is a CSS transform on the whole stage (cheap, compositor-only)
+// while the avatar itself plays its walk cycle inside the embed.
+// 2. Deliver. When the main process pushes a delivery, the character turns
+// to the middle of the screen, swaps to the sender's own body when they
+// have one, shows the line, says it out loud, then goes back to wandering.
+// 3. Stay out of the way. The window is click-through; the moment the pointer
+// is over the character or the bubble we ask the main process for input,
+// and give it straight back when the pointer leaves.
+//
+// The body is the published three.ws walk embed, driven over its documented
+// postMessage contract (https://three.ws/docs/walk-embed-api), so this app owns
+// no 3D code of its own and inherits every avatar, rig and animation the
+// platform ships.
+
+const stage = document.getElementById('stage');
+const body = document.getElementById('body');
+const bubble = document.getElementById('bubble');
+const whoEl = document.getElementById('who');
+const lineEl = document.getElementById('line');
+const whyEl = document.getElementById('why');
+const actionsEl = document.getElementById('actions');
+const hintEl = document.getElementById('hint');
+
+const STAGE_WIDTH = 260;
+const WANDER_MIN_MS = 22_000;
+const WANDER_MAX_MS = 55_000;
+const WALK_MS = 6000; // matches the CSS transition on #stage
+
+let apiBase = 'https://three.ws';
+let defaultAvatarUrl = null;
+let currentAvatarUrl = null;
+let embedReady = false;
+let paused = false;
+let holdTimer = null;
+let wanderTimer = null;
+let audio = null;
+let position = 40;
+
+// ── The embed ────────────────────────────────────────────────────────────────
+
+function embedUrl(base) {
+ const params = new URLSearchParams({
+ bg: 'transparent',
+ ground: 'false',
+ controls: 'none',
+ badge: 'false',
+ orbit: 'false',
+ click: 'false',
+ env: 'studio',
+ });
+ return `${base}/walk-embed?${params}`;
+}
+
+// The embed's typed envelope (src/walk-embed-events.js): channel + version +
+// type + payload, targeted at the embed's own origin so nothing else on the
+// machine can drive the character.
+function toEmbed(type, payload = {}) {
+ if (!embedReady && type !== 'walk:ping') return;
+ body.contentWindow?.postMessage({ channel: 'three-walk', v: 1, type, ...payload }, apiBase);
+}
+
+// A host that attaches after the embed already loaded would otherwise wait
+// forever for a handshake that has been and gone: ask for it again on load.
+body.addEventListener('load', () => {
+ body.contentWindow?.postMessage({ channel: 'three-walk', v: 1, type: 'walk:ping' }, apiBase);
+});
+
+window.addEventListener('message', (event) => {
+ if (!event.data || typeof event.data !== 'object') return;
+ // Only the embed origin may drive the character.
+ if (apiBase && event.origin !== new URL(apiBase).origin) return;
+ if (event.data.type === 'walk:ready') {
+ embedReady = true;
+ if (currentAvatarUrl) toEmbed('walk:avatar', { avatarId: currentAvatarUrl });
+ scheduleWander(4000);
+ }
+});
+
+// ── Wandering ────────────────────────────────────────────────────────────────
+
+function maxX() {
+ return Math.max(0, window.innerWidth - STAGE_WIDTH - 40);
+}
+
+function walkTo(x) {
+ const target = Math.min(maxX(), Math.max(0, x));
+ stage.dataset.facing = target < position ? 'left' : 'right';
+ position = target;
+ stage.style.transform = `translateX(${target}px)`;
+ // Legs move while the stage slides; the embed recentres itself afterwards so
+ // the character never drifts out of its own frame.
+ toEmbed('walk:move', { x: 0.7, y: 0 });
+ setTimeout(() => toEmbed('walk:reset', {}), WALK_MS);
+}
+
+function scheduleWander(delay = null) {
+ clearTimeout(wanderTimer);
+ const wait = delay ?? (WANDER_MIN_MS + Math.random() * (WANDER_MAX_MS - WANDER_MIN_MS));
+ wanderTimer = setTimeout(() => {
+ if (!paused && !bubble.dataset.visible) walkTo(Math.random() * maxX());
+ scheduleWander();
+ }, wait);
+}
+
+// ── Voice ────────────────────────────────────────────────────────────────────
+
+function stopAudio() {
+ if (audio) {
+ audio.pause();
+ audio.src = '';
+ audio = null;
+ }
+ try {
+ window.speechSynthesis?.cancel();
+ } catch {
+ /* no speech synthesis available */
+ }
+}
+
+async function say(text, voice) {
+ stopAudio();
+ // 1: the platform voice lanes, in the voice this contact was given.
+ try {
+ const res = await fetch(`${apiBase}/api/tts/speak`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ text, voice: voice || 'alloy', format: 'mp3' }),
+ });
+ if (res.ok) {
+ const blob = await res.blob();
+ if (blob.size) {
+ audio = new Audio(URL.createObjectURL(blob));
+ await audio.play();
+ return;
+ }
+ }
+ } catch {
+ /* fall through to the local voices */
+ }
+ // 2: the browser engine inside Electron.
+ try {
+ if (window.speechSynthesis) {
+ window.speechSynthesis.speak(new SpeechSynthesisUtterance(text));
+ return;
+ }
+ } catch {
+ /* fall through to the OS voice */
+ }
+ // 3: the machine's own voice (macOS `say`).
+ window.companion?.sayNative(text);
+}
+
+// ── Delivering ───────────────────────────────────────────────────────────────
+
+function holdMsFor(text) {
+ return Math.min(15_000, 5200 + String(text || '').length * 55);
+}
+
+function clearBubble() {
+ clearTimeout(holdTimer);
+ bubble.removeAttribute('data-visible');
+ stopAudio();
+ if (defaultAvatarUrl && currentAvatarUrl !== defaultAvatarUrl) {
+ currentAvatarUrl = defaultAvatarUrl;
+ toEmbed('walk:avatar', { avatarId: defaultAvatarUrl });
+ }
+ scheduleWander();
+}
+
+function deliver(delivery) {
+ if (paused) return;
+ const line = delivery.spoken_line || delivery.title || '';
+
+ // Walk into the middle of the screen to say something: a companion that
+ // delivers from the far corner reads as a toast, not as a person.
+ clearTimeout(wanderTimer);
+ walkTo(maxX() / 2);
+
+ if (delivery.avatar_glb_url && delivery.avatar_glb_url !== currentAvatarUrl) {
+ currentAvatarUrl = delivery.avatar_glb_url;
+ toEmbed('walk:avatar', { avatarId: delivery.avatar_glb_url });
+ }
+
+ whoEl.textContent = delivery.speaker || delivery.sender || 'Your companion';
+ lineEl.textContent = line;
+ whyEl.textContent = delivery.reason ? `${delivery.importance}/100 · ${delivery.reason}` : '';
+
+ actionsEl.innerHTML = '';
+ if (delivery.url) {
+ const open = document.createElement('button');
+ open.textContent = 'Open';
+ open.addEventListener('click', () => window.companion?.openExternal(delivery.url));
+ actionsEl.appendChild(open);
+ }
+ const dismiss = document.createElement('button');
+ dismiss.textContent = 'Got it';
+ dismiss.addEventListener('click', clearBubble);
+ actionsEl.appendChild(dismiss);
+
+ bubble.dataset.visible = '1';
+ setTimeout(() => toEmbed('walk:gesture', { gesture: 'wave' }), 400);
+ say(line, delivery.voice);
+
+ clearTimeout(holdTimer);
+ holdTimer = setTimeout(clearBubble, holdMsFor(line));
+}
+
+// ── Hit testing: hand the mouse back and forth ───────────────────────────────
+
+let interactive = false;
+function setInteractive(next) {
+ if (next === interactive) return;
+ interactive = next;
+ window.companion?.setInteractive(next);
+}
+
+window.addEventListener('mousemove', (event) => {
+ const overBubble = bubble.dataset.visible === '1' && hits(bubble, event);
+ const overBody = hits(body, event);
+ setInteractive(overBubble || overBody);
+});
+
+function hits(element, event) {
+ const rect = element.getBoundingClientRect();
+ return event.clientX >= rect.left && event.clientX <= rect.right
+ && event.clientY >= rect.top && event.clientY <= rect.bottom;
+}
+
+// Clicking the character opens the control room: the one gesture people try.
+body.addEventListener('click', () => window.companion?.openExternal(`${apiBase}/companion`));
+
+// ── Wiring ───────────────────────────────────────────────────────────────────
+
+async function boot() {
+ const creds = await window.companion.credentials();
+ apiBase = creds.apiBase || apiBase;
+ paused = Boolean(creds.paused);
+ body.src = embedUrl(apiBase);
+ hintEl.dataset.visible = creds.signedIn ? '0' : '1';
+ if (!creds.signedIn) stage.dataset.hidden = '1';
+
+ window.companion.onStatus((status) => {
+ if (typeof status?.paused === 'boolean') paused = status.paused;
+ if (status?.apiBase) apiBase = status.apiBase;
+ if (typeof status?.signedIn === 'boolean') {
+ hintEl.dataset.visible = status.signedIn ? '0' : '1';
+ stage.dataset.hidden = status.signedIn ? '0' : '1';
+ }
+ if (status?.default_avatar_glb_url) {
+ defaultAvatarUrl = status.default_avatar_glb_url;
+ if (!currentAvatarUrl) {
+ currentAvatarUrl = defaultAvatarUrl;
+ toEmbed('walk:avatar', { avatarId: defaultAvatarUrl });
+ }
+ }
+ if (paused) clearBubble();
+ });
+
+ window.companion.onDelivery(deliver);
+ window.addEventListener('resize', () => walkTo(Math.min(position, maxX())));
+}
+
+boot();
diff --git a/apps/desktop/src/renderer/index.html b/apps/desktop/src/renderer/index.html
new file mode 100644
index 000000000..73538615a
--- /dev/null
+++ b/apps/desktop/src/renderer/index.html
@@ -0,0 +1,146 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ <title>three.ws Companion</title>
+ <style>
+ :root {
+ color-scheme: dark light;
+ --bubble-bg: rgba(18, 18, 20, 0.94);
+ --bubble-fg: #f2f4f8;
+ --bubble-line: rgba(255, 255, 255, 0.14);
+ }
+ @media (prefers-color-scheme: light) {
+ :root {
+ --bubble-bg: rgba(255, 255, 255, 0.96);
+ --bubble-fg: #14161a;
+ --bubble-line: rgba(0, 0, 0, 0.1);
+ }
+ }
+ * { box-sizing: border-box; margin: 0; padding: 0; }
+ html, body {
+ height: 100%;
+ background: transparent;
+ overflow: hidden;
+ font-family: Inter, -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+ /* The window itself is click-through; only the character and the
+ bubble opt back in, and main.js hands input over when the
+ pointer is actually on them. */
+ cursor: default;
+ }
+
+ #stage {
+ position: absolute;
+ bottom: 0;
+ left: 40px;
+ width: 260px;
+ height: 340px;
+ transition: transform 6s cubic-bezier(0.4, 0, 0.2, 1), opacity .5s ease;
+ will-change: transform;
+ }
+ #stage[data-facing="left"] #body { transform: scaleX(-1); }
+ #stage[data-hidden="1"] { opacity: 0; pointer-events: none; }
+
+ #body {
+ width: 100%;
+ height: 260px;
+ border: 0;
+ display: block;
+ background: transparent;
+ pointer-events: auto;
+ }
+
+ #bubble {
+ position: absolute;
+ bottom: 250px;
+ left: 50%;
+ transform: translate(-50%, 8px);
+ width: 320px;
+ max-width: 90vw;
+ background: var(--bubble-bg);
+ color: var(--bubble-fg);
+ border: 1px solid var(--bubble-line);
+ border-radius: 16px;
+ padding: 14px 16px;
+ box-shadow: 0 18px 50px rgba(0, 0, 0, 0.45);
+ backdrop-filter: blur(12px);
+ opacity: 0;
+ pointer-events: none;
+ transition: opacity .28s ease, transform .28s ease;
+ font-size: 14px;
+ line-height: 1.5;
+ }
+ #bubble[data-visible="1"] { opacity: 1; transform: translate(-50%, 0); pointer-events: auto; }
+ #who {
+ font-size: 11px;
+ letter-spacing: .06em;
+ text-transform: uppercase;
+ opacity: .55;
+ margin-bottom: 5px;
+ }
+ #line { font-weight: 500; }
+ #why { font-size: 11.5px; opacity: .5; margin-top: 8px; }
+ #actions { display: flex; gap: 8px; margin-top: 12px; flex-wrap: wrap; }
+ button {
+ font: 600 12px/1 Inter, system-ui, sans-serif;
+ color: inherit;
+ background: rgba(127, 127, 127, 0.16);
+ border: 1px solid var(--bubble-line);
+ border-radius: 8px;
+ padding: 7px 11px;
+ cursor: pointer;
+ transition: background .15s, border-color .15s;
+ }
+ button:hover { background: rgba(127, 127, 127, 0.3); }
+ button:focus-visible { outline: 2px solid #3b82f6; outline-offset: 2px; }
+
+ #hint {
+ position: absolute;
+ bottom: 16px;
+ left: 50%;
+ transform: translateX(-50%);
+ background: var(--bubble-bg);
+ color: var(--bubble-fg);
+ border: 1px solid var(--bubble-line);
+ border-radius: 12px;
+ padding: 12px 16px;
+ font-size: 13px;
+ pointer-events: auto;
+ display: none;
+ }
+ #hint[data-visible="1"] { display: block; }
+
+ @media (prefers-reduced-motion: reduce) {
+ #stage { transition: none; }
+ #bubble { transition: none; }
+ }
+ </style>
+ </head>
+ <body>
+ <div id="stage" data-facing="right">
+ <div id="bubble" role="status" aria-live="polite">
+ <div id="who"></div>
+ <div id="line"></div>
+ <div id="why"></div>
+ <div id="actions"></div>
+ </div>
+ <!-- The body itself: the three.ws walking-avatar embed, transparent,
+ driven over the documented postMessage contract
+ (https://three.ws/docs/walk-embed-api). -->
+ <iframe
+ id="body"
+ title="Your companion"
+ allow="autoplay"
+ referrerpolicy="no-referrer"
+ ></iframe>
+ </div>
+
+ <div id="hint">
+ <strong>three.ws Companion</strong> is not signed in yet.
+ Open the tray icon and choose <em>Sign in</em>, or run <code>companion login</code>.
+ </div>
+
+ <script type="module" src="./companion.js"></script>
+ </body>
+</html>
diff --git a/apps/desktop/src/renderer/sign-in.html b/apps/desktop/src/renderer/sign-in.html
new file mode 100644
index 000000000..db46278c0
--- /dev/null
+++ b/apps/desktop/src/renderer/sign-in.html
@@ -0,0 +1,87 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ <title>Sign in to your companion</title>
+ <style>
+ :root { color-scheme: dark light; --bg: #101114; --fg: #eef1f6; --line: rgba(255,255,255,.14); --muted: rgba(238,241,246,.6); --blue: #3b82f6; }
+ @media (prefers-color-scheme: light) { :root { --bg: #fff; --fg: #14161a; --line: rgba(0,0,0,.12); --muted: rgba(20,22,26,.6); } }
+ * { box-sizing: border-box; margin: 0; padding: 0; }
+ body { background: var(--bg); color: var(--fg); font: 14px/1.55 Inter, -apple-system, system-ui, sans-serif; padding: 26px; }
+ h1 { font-size: 17px; margin-bottom: 8px; }
+ p { color: var(--muted); font-size: 13px; margin-bottom: 18px; }
+ label { display: block; font-size: 12px; color: var(--muted); margin-bottom: 6px; }
+ input { width: 100%; background: transparent; color: inherit; border: 1px solid var(--line); border-radius: 9px; padding: 10px 12px; font: inherit; }
+ input:focus { outline: none; border-color: var(--blue); }
+ .row { display: flex; gap: 10px; margin-top: 18px; }
+ button { font: 600 13px/1 inherit; border-radius: 9px; padding: 11px 15px; border: 1px solid var(--line); background: transparent; color: inherit; cursor: pointer; }
+ button.primary { background: var(--blue); border-color: var(--blue); color: #fff; }
+ button:disabled { opacity: .5; cursor: default; }
+ button:focus-visible { outline: 2px solid var(--blue); outline-offset: 2px; }
+ #status { margin-top: 14px; font-size: 12.5px; min-height: 18px; }
+ #status[data-kind="error"] { color: #ff7a8a; }
+ #status[data-kind="ok"] { color: #43d6a0; }
+ .field + .field { margin-top: 14px; }
+ </style>
+ </head>
+ <body>
+ <h1>Connect this machine</h1>
+ <p>
+ Your bridge token lives at three.ws/companion. It lets this app receive
+ your deliveries and nothing else, and rotating it there disconnects every
+ device at once.
+ </p>
+
+ <form id="form">
+ <div class="field">
+ <label for="token">Bridge token</label>
+ <input id="token" name="token" type="password" placeholder="cmp_…" autocomplete="off" required />
+ </div>
+ <div class="field">
+ <label for="api">Server</label>
+ <input id="api" name="api" type="text" value="https://three.ws" />
+ </div>
+ <div class="row">
+ <button type="submit" class="primary" id="save">Connect</button>
+ <button type="button" id="open">Get my token</button>
+ </div>
+ </form>
+ <div id="status" aria-live="polite"></div>
+
+ <script>
+ const form = document.getElementById('form');
+ const status = document.getElementById('status');
+ const save = document.getElementById('save');
+
+ document.getElementById('open').addEventListener('click', () => {
+ const base = document.getElementById('api').value.trim() || 'https://three.ws';
+ window.companion.openExternal(`${base}/companion`);
+ });
+
+ window.companion.credentials().then((creds) => {
+ if (creds?.apiBase) document.getElementById('api').value = creds.apiBase;
+ });
+
+ form.addEventListener('submit', async (event) => {
+ event.preventDefault();
+ save.disabled = true;
+ status.dataset.kind = '';
+ status.textContent = 'Checking the token…';
+ const result = await window.companion.saveToken({
+ token: document.getElementById('token').value,
+ apiBase: document.getElementById('api').value.trim(),
+ });
+ save.disabled = false;
+ if (result.ok) {
+ status.dataset.kind = 'ok';
+ status.textContent = 'Connected. Your companion is listening.';
+ setTimeout(() => window.close(), 1200);
+ } else {
+ status.dataset.kind = 'error';
+ status.textContent = result.error;
+ }
+ });
+ </script>
+ </body>
+</html>