create-bridgething 0.11.0 → 0.12.1

package/template/_claude/skills/bridgething/reference/sdk.md

@@ -1,61 +1,38 @@
 # The webapp SDK (`@bridgething/client`)
 
-A webapp reaches the daemon only through this one client: a typed facade over a
-local WebSocket. You never open sockets or build wire messages yourself.
-
-## Contents
-
-- Read the types (the `.d.ts` files are the source of truth)
-- Connect
-- The three call shapes (events / requests / commands)
-- Cookbook (player, asset, store, config, net, library)
-- Full surface index (all 18)
-- Gotchas
-
 ## Read the types
 
-You have no editor to hover in, so read the shipped declarations directly. Every
-method, event, and field carries a doc comment.
+The shipped declarations carry a doc comment on every method, event, and field.
 
-- `node_modules/@bridgething/client/dist/dispatch.generated.d.ts` - every
-  `client.<surface>` method and event, with argument and return types.
-- `node_modules/@bridgething/lib/dist/bindings/*.d.ts` - the payload and reply
-  types (`PlayerState`, `MediaItem`, `NowPlayingUpdate`, `AssetGot`, ...) with
-  per-field docs. `client.d.ts` is the webapp surface; `shared.ts` holds the
-  shared data types.
-
-Useful greps:
+- `node_modules/@bridgething/client/dist/dispatch.generated.d.ts` has every
+  `client.<surface>` method and event with its argument and return types.
+- `node_modules/@bridgething/lib/dist/bindings/client.d.ts` has the request and
+  reply payloads. `shared.d.ts` has the data types.
 
 ```bash
 grep -n 'class PlayerSurface' -A40 node_modules/@bridgething/client/dist/dispatch.generated.d.ts
-grep -n 'export type PlayerState ' -A12 node_modules/@bridgething/lib/dist/bindings/shared.ts
+grep -n 'export type PlayerState ' -A12 node_modules/@bridgething/lib/dist/bindings/shared.d.ts
 ```
 
-The `.d.ts` is the source of truth; this file is the map.
-
 ## Connect
 
 ```ts
 import { BridgethingClient } from '@bridgething/client';
 
-const client = new BridgethingClient();          // on device: talks to the local daemon
-// dev against a real device from your laptop:
-const client = new BridgethingClient({ url: import.meta.env.VITE_BRIDGETHING_URL });
+import { daemonUrl } from './daemon';
+
+const client = new BridgethingClient({ url: daemonUrl() });
 ```
 
-Construct once and reuse (a `useMemo` in React). It auto-connects and
-auto-reconnects. Watch the link with `client.on(e => ...)` (`e.type` is
-`open` / `close` / `connecting` / `message`) and read `client.connectionState`
-(`'connecting' | 'open' | 'closing' | 'closed'`). The daemon is always the sole
-peer; you never address anything.
+Construct once and reuse, a `useMemo` in React. Watch the link with
+`client.on(e => ...)`, where `e.type` is `open`, `close`, `connecting`, or
+`message`, and read `client.connectionState`, one of
+`'connecting' | 'open' | 'closing' | 'closed'`.
 
 ## The three call shapes
 
-Every surface method is one of three shapes. Learn these and the whole SDK reads
-the same way.
-
-**1. Events** - the daemon pushes; you subscribe. `onXxx` returns an unsubscribe
-function (call it in cleanup). Or `subscribe({...})` for several at once.
+Events. `onXxx` returns an unsubscribe function to call in cleanup.
+`subscribe({...})` takes several at once.
 
 ```ts
 const off = client.player.onSnapshot(reply => setState(reply.state));
@@ -63,8 +40,7 @@ const off = client.player.onSnapshot(reply => setState(reply.state));
 off();
 ```
 
-**2. Requests** - you ask, the daemon answers. Returns a tagged result; always
-check `.ok`.
+Requests. Check `.ok` on every result.
 
 ```ts
 const res = await client.player.stateGet();
@@ -72,8 +48,8 @@ if (res.ok) console.log(res.response.state);
 else console.warn(res.kind, res.error); // kind: 'domain' | 'protocol'
 ```
 
-**3. Commands** - fire-and-forget. Returns `Promise<void>`; it resolves when the
-daemon has taken the message, not when the phone finished acting.
+Commands. The returned `Promise<void>` resolves when the daemon has taken the
+message, not when the phone finished acting.
 
 ```ts
 await client.player.skipNext();
@@ -81,31 +57,31 @@ await client.player.skipNext();
 
 ## Cookbook
 
-**Now playing + transport (`client.player`)**
+`client.player`:
 
 ```ts
 client.player.onSnapshot(r => setState(r.state)); // full PlayerState on every material change
 client.player.stateGet().then(r => r.ok && setState(r.response.state)); // prime on mount
 
-// PlayerState: { track?: MediaItem, playback: Playback, queue, options, context? }
+// PlayerState: { track: MediaItem | null, playback: Playback, queue, options, context }
 // track.title / track.artist / track.album / track.artworkId / track.durationMs
 // playback.state: 'stopped' | 'paused' | 'playing'; playback.positionMs; playback.shuffle
 
 client.player.play({ uri: 'spotify:track:...' });
-client.player.pause(); client.player.resume(); client.player.skipNext();
-client.player.skipPrev({ allowSeeking: true });   // true = restart if progressed
+client.player.pause();
+client.player.resume();
+client.player.skipNext();
+client.player.skipPrev({ allowSeeking: true }); // true restarts the track if it is progressed
 client.player.seekTo({ positionMs: 30_000 });
 client.player.setShuffle({ on: true });
-client.player.setRepeat({ mode: 'all' });          // 'off' | 'all' | 'one'
+client.player.setRepeat({ mode: 'all' }); // 'off' | 'all' | 'one'
 ```
 
-Smooth progress: `onSnapshot` fires on material changes (track change, play/pause,
-seek), NOT every second. Extrapolate the playhead locally from `playback.state`
-and `positionMs` between snapshots.
+`onSnapshot` fires on material changes such as a track change, play, pause, and
+seek. For a smooth progress bar, extrapolate the playhead between snapshots from
+`playback.state` and `playback.positionMs`.
 
-**Artwork and images (`client.asset`)**
-
-Player state gives opaque asset ids, never URLs. Fetch bytes and wrap a blob:
+`client.asset`. Player state carries opaque asset ids:
 
 ```ts
 const res = await client.asset.get({ id: track.artworkId, requestId: crypto.randomUUID() });
@@ -116,16 +92,16 @@ if (res.ok) {
 }
 ```
 
-**Persistence (`client.store`)** - per-webapp key/value that survives restarts:
+`client.store`, per-webapp key and value that survives restarts:
 
 ```ts
 await client.store.put({ key: 'theme', value: 'dark' });
-const r = await client.store.get({ key: 'theme' });   // r.ok && r.response.value
+const r = await client.store.get({ key: 'theme' }); // r.ok && r.response.value
 await client.store.delete({ key: 'theme' });
 ```
 
-**User settings (`client.config`)** - values you declare in `manifest.json`; the
-user edits them in the companion app, your side is read-only:
+`client.config`, the values declared in `manifest.json`. The companion app writes
+them, the webapp reads them:
 
 ```ts
 client.config.onChanged(c => applySetting(c.key, c.value));
@@ -133,63 +109,68 @@ const r = await client.config.get({ key: 'units' });
 const all = await client.config.list();
 ```
 
-The user edits these in the companion phone app. The scaffold ships a
-companion-side settings page under `settings/` that reads and writes them via a
-separate SDK, `@bridgething/client/settings` (a `postMessage` bridge to the
-companion host, not this WebSocket). `manifest.json`'s `settings` field points
-the companion at the built `dist/settings.html`.
+The settings page under `settings/` reads and writes them through
+`@bridgething/client/settings`, a `postMessage` bridge. It runs on the phone with
+real internet, but loads from a `file://` origin and the webview enforces CORS on
+fetch and XHR. WebSocket APIs work. Plain HTTP APIs work when the server sends
+permissive CORS headers, since requests arrive with `Origin: null`. For a
+CORS-strict HTTP-only service, fetch through `client.net` instead.
+
+Write it in react like the rest of the app. `react` and `react-dom/client`
+imports, `className`, `htmlFor`, react's event types. The build runs it on
+preact through `@preact/preset-vite`, which is most of what keeps the page
+small, so keep the react-flavoured source and leave the preset alone. One
+tsconfig covers `src`, `settings` and `extension`, so `bun run typecheck`
+checks all three.
 
-NETWORK CAVEAT for the settings page: it runs on the phone with real internet,
-but it loads from a `file://` origin and the webview enforces CORS on
-fetch/XHR. WebSocket APIs work (the WS handshake is not CORS-gated); plain HTTP
-APIs work only when the server sends permissive CORS headers (requests arrive
-with `Origin: null`). Prefer the service's websocket API from the settings
-page; for a CORS-strict HTTP-only service, fetch from the device webapp via
-`client.net` (phone-tunneled, not origin-restricted) and keep the settings page
-for typing and choosing.
+Keep the page small. It builds to one self-contained HTML file, and the device
+refuses to install a bundle whose declared settings page is over 1 MiB, failing
+the whole install with an invalid-manifest error. The build warns past 200 KiB
+and again past 500 KiB. A heavy dependency in `settings/` is the usual way
+there.
 
-**Internet through the phone (`client.net`)** - the device has no direct network;
-`net.fetch` / websockets / a SOCKS proxy all tunnel through the phone. Needs the
-matching `permissions` entry in `manifest.json` (`net.fetch`, `net.ws`,
-`net.proxy`). Read the `NetSurface` block in the `.d.ts` for the request shapes.
+`client.net` tunnels HTTP, websockets, and a SOCKS proxy through the phone. The
+SOCKS proxy needs `"net.proxy"` in the manifest's `permissions`. Read the
+`NetSurface` block in the `.d.ts` for the request shapes.
 
-**Library + search (`client.library`)** - `browse`, `search`, `recommendations`,
-`favoritesList`/`favoritesContains` (requests), `favoritesToggle`/`favoritesSet`
-(commands), `onFavoriteChanged` (event). All Spotify-backed.
+`client.library` is Spotify-backed: `browse`, `search`, `recommendations`,
+`favoritesList`, and `favoritesContains` are requests; `favoritesToggle` and
+`favoritesSet` are commands; `onFavoriteChanged` is an event.
 
-## Full surface index
+## Every surface
 
-18 surfaces on `client.<name>`. Read each surface's class in
-`dispatch.generated.d.ts` for its exact methods and types.
+Read a surface's class in `dispatch.generated.d.ts` for its exact methods.
 
 | Surface | What it does | Notable methods |
 | --- | --- | --- |
-| `player` | now-playing + transport | onSnapshot, stateGet, play, pause, resume, skipNext, skipPrev, seekTo, setShuffle, setRepeat, queueGet |
-| `asset` | fetch blobs by opaque id | get, preload, onReady/onCleared |
-| `store` | per-webapp key/value | get, put, delete |
+| `player` | now-playing and transport | onSnapshot, stateGet, play, pause, resume, skipNext, skipPrev, seekTo, setShuffle, setRepeat, queueGet |
+| `asset` | fetch blobs by opaque id | get, preload, onReady, onCleared |
+| `store` | per-webapp key and value | get, put, delete |
 | `config` | user settings from the manifest | get, list, onChanged |
-| `capabilities` | which gateway features are live | get, onSnapshot |
-| `library` | Spotify browse/search/favorites | browse, search, recommendations, favoritesList/Contains/Toggle/Set, onFavoriteChanged |
-| `audio` | volume, mute, TTS, earcons | volumeUp/Down, setVolume, muteToggle, tts, earcon |
-| `notifications` | phone notification actions | invokePositive/Negative, onPosted/Removed/Updated |
-| `phone` | call control (Android; iOS uses iAP2) | stateGet, accept, end, initiate, mute, dtmf, onCallStarted/Updated/Ended |
-| `geo` | location watches (phone-sourced) | watch, unwatch, getOnce, onPosition |
-| `net` | HTTP / WS / SOCKS via the phone | fetch, wsOpen/wsSend/wsClose, streamOpen/streamCancel |
-| `hardware` | backlight + ambient light sensor | displaySetMode, displaySetLevel, stateGet, onAmbientLightUpdate, onBrightnessChanged |
-| `bluetooth` | adapter alias/bonds/discoverable | list, connect, forget, setAlias, enableDiscoverable |
-| `system` | version, logs, power, diagnostics | versionRequest, logsTail/Subscribe, reboot, powerOff, factoryReset, onVersion, onLogEntry, onOta* |
-| `time` | wall clock (device has no RTC) | get, onSnapshot, onChanged |
-| `voice` | mic / push-to-talk (capability-gated) | pushToTalk, cancel, muteMic, stateGet |
-| `webapp` | launcher: list/activate installed apps | list, current, activate, icon |
-| `forward` | arbitrary passthrough to the companion | text, json, binary, onText/onJson/onBinary |
+| `capabilities` | which companion features are live | get, onSnapshot |
+| `library` | Spotify browse, search, favorites | browse, search, recommendations, favoritesList, favoritesContains, favoritesToggle, favoritesSet, onFavoriteChanged |
+| `audio` | volume, mute, TTS, earcons | volumeUp, volumeDown, setVolume, muteToggle, tts, earcon |
+| `notifications` | phone notification actions | invokePositive, invokeNegative, onPosted, onRemoved, onUpdated |
+| `phone` | call control | stateGet, accept, end, initiate, mute, dtmf, onCallStarted, onCallUpdated, onCallEnded |
+| `geo` | location watches, sourced from the phone | watch, unwatch, getOnce, onPosition |
+| `net` | HTTP, WS, and SOCKS through the phone | fetch, wsOpen, wsSend, wsClose, streamOpen, streamCancel |
+| `hardware` | backlight and ambient light sensor | displaySetMode, displaySetLevel, stateGet, onAmbientLightUpdate, onBrightnessChanged |
+| `bluetooth` | adapter alias, bonds, discoverable | list, connect, forget, setAlias, enableDiscoverable |
+| `system` | version, logs, power, diagnostics | versionRequest, logsTail, logsSubscribe, reboot, powerOff, factoryReset, onVersion, onLogEntry, onOtaProgress |
+| `time` | wall clock | get, onSnapshot, onChanged |
+| `voice` | mic and push-to-talk, capability-gated | pushToTalk, cancel, muteMic, stateGet |
+| `webapp` | list and activate installed webapps | list, current, activate, icon |
+| `forward` | passthrough to the desktop-side extension | text, json, binary, onText, onJson, onBinary |
+| `doc` | per-webapp documents the companion also writes | get, list, set, delete, onChanged |
+| `lyrics` | timed lyrics for the current track | get |
+| `peer` | every known peer and its link state | onSnapshot |
 
 ## Gotchas
 
-- Always check `.ok` on request results; the daemon can answer with a domain or
-  protocol error (e.g. `player.play` with a uri no gateway claims).
-- Assume no phone: player, library, net all depend on the connected companion.
-  Render an empty/placeholder state, do not throw.
-- `config` is read-only from the webapp; only the companion writes it.
-- Asset ids are opaque - never parse or construct them, never build image URLs.
-- Some surfaces are capability-gated or platform-specific (e.g. `voice`, and
-  `phone` on iOS). Check `client.capabilities` and handle absence.
+- Check `.ok` on every request result. The daemon answers with a domain or
+  protocol error when it cannot serve the call, such as `player.play` with a uri
+  no companion claims.
+- Write the app so it works with no phone connected. `player`, `library`, and
+  `net` all depend on the companion app.
+- Treat asset ids as opaque. Pass them to `client.asset.get` as they arrive.
+- Read `client.capabilities` before using `voice` and `phone`.

package/template/_claude/skills/bridgething/reference/ship.md

@@ -1,65 +1,46 @@
 # Installing and sharing the app
 
-Two outputs: install onto your own connected device, and a zip anyone can install
-through the bridgething companion app.
-
 ## Install onto a connected Car Thing
 
 ```bash
-bun run push            # targets bridgething.local (device over USB)
-bun run push <address>  # or an explicit host / IP
+bun run push            # targets bridgething.local (the device over USB)
+bun run push <address>  # or an explicit host or IP
 ```
 
-`push` builds `dist/` itself, rsyncs it to the device, then tells the daemon to
-switch the kiosk to your app - one command, no separate build step. The device
-must be reachable: connected over USB it answers to `bridgething.local`;
-otherwise pass its address. If multiple devices are on the network, set
+`push` builds `dist/` itself, copies it to the device, then switches the kiosk to
+your app. With several devices on the network, set
 `SUPERBIRD_HOST=bridgething-<serial>.local`.
 
-Flags: `--skip-build` reuses the existing `dist/`; `--no-switch` copies without
-activating. Iterating on hardware, rerun `bun run push` after each change. For
-the fast edit loop, drive a local browser instead (see the develop reference) and
-save the device for final checks.
+Flags: `--skip-build` copies whatever is already in `dist/`, and `--no-switch`
+copies without activating. To iterate on hardware, use `bun run dev:device` from
+the develop reference instead.
 
-If `manifest.json` declares `role: launcher` or an `overlay`, `push` also claims
-the matching device slot, so the bundle is live rather than merely installed. A
-launcher is switched to; an overlay is not, since switching away from the app it
-draws over defeats the point. `--no-slot` pushes without claiming, and
-`--release` gives the slots back to the built-in hub and overlay - the recovery
-path when a build wedges the screen.
+When `manifest.json` declares `role: launcher` or an `overlay`, `push` also
+claims the matching slot. A launcher is switched to; an overlay is not, so pass
+`--switch` to open its own page. `--no-slot` pushes without claiming a slot.
+`--release` gives the slots back to the built-in hub and overlay.
 
 ## Make a shareable zip
 
 ```bash
-bun run build   # share does NOT build; produce dist/ first
+bun run build   # share reads dist/, so produce it first
 bun run share   # writes <name>-<version>.zip from dist/
 ```
 
-Send that zip to anyone with a bridgething-flashed Car Thing. They install it
-from the bridgething companion app (no rebuild, no dev tools). The zip is just
-your built bundle with `manifest.json` at its root. `bun run build` also emits
-`dist/settings.html` (the companion-side settings page); it ships in the same
-bundle when `manifest.json` declares `settings`.
+Anyone with a bridgething Car Thing installs that zip from the companion app.
 
-Bump `version` in `public/manifest.json` before sharing an update, so people can
-tell builds apart. Never touch `manifest.json`'s `id` - it is the webapp's
-identity and the install path on the device.
+Raise `version` in `public/manifest.json` before you share an update. Keep `id`.
 
 ## Keep the device on the latest bridgething
 
 ```bash
-bun run update   # updates the connected Car Thing's daemon + image
+bun run update   # updates the connected Car Thing's daemon and image
 ```
 
-`update` runs `@bridgething/updater`: it connects over the same gateway `push`
-uses, reads the release manifest, and brings the device to the latest `stable`
-release.
-
-Multiple devices? Target one explicitly:
+Flags go after `--`:
 
 ```bash
-bun run update -- --host ws://bridgething-<serial>.local:8892/
+bun run update -- --host ws://bridgething-<serial>.local:8892/  # pick one of several devices
+bun run update -- --channel <name>                              # track another channel
+bun run update -- --version <composite-version>                 # install a specific release
 ```
-
-Other flags: `-- --channel <name>` to track a non-stable channel,
-`-- --daemon-only` to skip the image OTA.

package/template/_gitignore

@@ -1,5 +1,6 @@
 node_modules
 dist
+.dev-extension
 .DS_Store
 *.log
 .env*

package/template/package.json

@@ -5,14 +5,15 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
+    "dev:device": "vite --mode device",
     "build": "vite build && vite build -c vite.settings.config.ts",
+    "typecheck": "tsc --noEmit",
     "preview": "vite preview",
     "push": "bun scripts/push.ts",
     "share": "bun scripts/share.ts",
     "update": "bunx @bridgething/updater"
   },
   "dependencies": {
-    "@bridgething/client": "^0.11.0",
     "preact": "^10.29.7",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
@@ -20,14 +21,14 @@
   "devDependencies": {
     "@msgpack/msgpack": "^3.1.3",
     "@preact/preset-vite": "^2.10.5",
-    "@tailwindcss/vite": "^4.1.16",
+    "@tailwindcss/vite": "^4.3.3",
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.1",
+    "@vitejs/plugin-react": "^6.1.1",
     "fflate": "^0.8.2",
-    "tailwindcss": "^4.1.16",
+    "tailwindcss": "^4.3.3",
     "typescript": "^6.0.3",
-    "vite": "^7.1.13",
+    "vite": "^8.2.2",
     "vite-plugin-singlefile": "^2.3.3"
   }
 }