create-bridgething 0.11.0 → 0.12.0

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

@@ -1,39 +1,46 @@
 # Running and driving the app
 
-The device is an 800x480 landscape screen with five physical controls plus touch.
-To develop effectively you (1) run the app, (2) see it at the real size, and
-(3) press the buttons. The fast loop drives a browser you control on your own
-machine; you only need the physical Car Thing for final validation.
+## Start the dev server
 
-## Contents
+```bash
+bun run dev
+```
 
-- Start the dev server
-- Drive it with Playwright (recommended for agents)
-- Alternative: your own browser + DevTools
-- Drive the real device over CDP
-- Input reference
+Vite serves at `http://localhost:5173/` with hot reload. The page reaches the
+daemon on the Car Thing plugged in over USB through the dev server's
+`/__bridgething` proxy, so now-playing, config, and geo are the real thing rather
+than fixtures. `SUPERBIRD_HOST=bridgething-<serial>.local` targets another
+device, and `BRIDGETHING_DAEMON_URL=ws://host:8891` targets a daemon anywhere
+else.
 
-## Start the dev server
+## Show it on the Car Thing with hot reload
 
 ```bash
-bun run dev
+bun run dev:device
 ```
 
-Vite serves at `http://localhost:5173/` with hot reload.
+On start it installs the app once if the daemon has never seen it, makes it the
+active webapp so config, permissions, and forwards are yours, then points the
+kiosk at `http://<your usb address>:5173/`. Every save from then on hot-reloads
+on the real display. Ctrl-C hands the screen back to the installed build.
 
-## Drive it with Playwright (recommended for agents)
+## The extension half
 
-Playwright is **not** installed by default (a human clicking around does not need
-it). Add it only when you want to see and drive the app programmatically:
+When `public/manifest.json` declares `extension`, both dev commands also bundle
+`extension/main.ts`, run it under Deno with the manifest's permissions, and link
+it to the same Car Thing. Every save rebuilds and restarts it, and `ctx.log.*`
+prints in the vite terminal. The contract is in
+[reference/extension.md](extension.md).
+
+## Drive it with Playwright
+
+To screenshot and drive the app from a script, add Playwright:
 
 ```bash
 bun add -d playwright
 bunx playwright install chromium
 ```
 
-Then a short script gives you a locked 800x480 window you can screenshot and send
-input to:
-
 ```ts
 import { chromium } from 'playwright';
 
@@ -44,50 +51,46 @@ await page.goto('http://localhost:5173/');
 await page.screenshot({ path: 'screen.png' }); // look at the result
 
 // physical controls -> the exact events the device sends:
-await page.keyboard.press('1');       // preset 1  (also '2' '3' '4')
-await page.keyboard.press('m');       // Mode button
-await page.keyboard.press('Escape');  // Back button
-await page.mouse.wheel(120, 0);       // rotary wheel: HORIZONTAL scroll (deltaX)
+await page.keyboard.press('1'); // preset 1  (also '2' '3' '4')
+await page.keyboard.press('m'); // Mode button
+await page.keyboard.press('Escape'); // Back button
+await page.mouse.wheel(120, 0); // rotary wheel: HORIZONTAL scroll (deltaX)
 // touch: page.tap('selector')  or  page.mouse.click(x, y)
 ```
 
-Loop: edit code -> vite hot-reloads -> screenshot -> adjust. Keep the viewport at
-exactly `{ width: 800, height: 480 }` so what you see matches the device.
+Loop: edit code, let vite hot-reload, screenshot, adjust. Keep the viewport at
+`{ width: 800, height: 480 }` so what you see matches the device.
 
-## Alternative: your own browser + DevTools
+## Your own browser and DevTools
 
-Open `http://localhost:5173/` in your normal browser, then in DevTools' device
-toolbar set a custom device of **800 x 480**. You get real DevTools plus the same
-keys (type `1`-`4`, `m`, `Escape`; shift+wheel for the rotary's horizontal
-scroll). This is the recommended manual path.
+Open `http://localhost:5173/`, then set a custom device of 800 x 480 in DevTools'
+device toolbar. Type `1` through `4`, `m`, and `Escape`, and hold shift while
+scrolling for the rotary's horizontal wheel.
 
 ## Drive the real device over CDP
 
-To see and drive the app on real hardware, talk CDP to the device's own chromium.
-CDP input goes straight into the page (never through the physical buttons), so the
-launcher gesture and on-device browser-nav side effects never interfere.
+CDP input goes into the page, so the launcher gesture and browser-nav side
+effects stay out of the way.
 
-Install the app onto the device first so the kiosk is showing it (build + push).
-CDP is served at `bridgething.local:9222`, reachable directly over USB:
+Get the app on the kiosk first with `bun run dev:device` or `bun run push`. CDP
+is served at `bridgething.local:9222`, reachable over USB:
 
 ```bash
-# device answers at bridgething.local over USB; root has no password
 curl -s http://bridgething.local:9222/json/version >/dev/null && echo cdp-up
 ```
 
 Use the `webSocketDebuggerUrl` exactly as returned. It comes back as an IP rather
-than the hostname you asked for, and it is already correct - do not rewrite it.
+than the hostname you asked for, and that address is the correct one.
 
-**Playwright's `connectOverCDP` hangs against the device's embedded chromium** -
-it never finishes the websocket upgrade (a quirk of the device's `cast_shell`
-build; a plain websocket connects fine). Drive it with a raw CDP websocket
-instead. Connect to the `page` target from `/json` (the page-level endpoint, not
-the browser-level one). This script screenshots the live device and presses a
-button; it is the whole loop:
+Playwright's `connectOverCDP` never finishes the websocket upgrade against the
+device's embedded chromium, so drive it with a raw CDP websocket. Connect to the
+`page` target from `/json`, not the browser-level endpoint.
 
 ```ts
 // drive.ts  ->  run with: bun drive.ts
-const targets = (await fetch('http://bridgething.local:9222/json').then(r => r.json())) as any[];
+const targets = (await fetch('http://bridgething.local:9222/json').then(r =>
+  r.json(),
+)) as any[];
 const page = targets.find(t => t.type === 'page');
 const ws = new WebSocket(page.webSocketDebuggerUrl);
 await new Promise<void>((res, rej) => {
@@ -99,45 +102,61 @@ let id = 0;
 const pending = new Map<number, (v: any) => void>();
 ws.onmessage = ev => {
   const m = JSON.parse(ev.data as string);
-  if (m.id && pending.has(m.id)) (pending.get(m.id)!(m.result), pending.delete(m.id));
+  if (m.id && pending.has(m.id))
+    (pending.get(m.id)!(m.result), pending.delete(m.id));
 };
 const send = (method: string, params: any = {}) =>
-  new Promise<any>(res => (pending.set(++id, res), ws.send(JSON.stringify({ id, method, params }))));
+  new Promise<any>(
+    res => (
+      pending.set(++id, res),
+      ws.send(JSON.stringify({ id, method, params }))
+    ),
+  );
 
 // screenshot
 const { data } = await send('Page.captureScreenshot', { format: 'png' });
 await Bun.write('device.png', Buffer.from(data, 'base64'));
 
-// read what is on screen (great for asserting a change happened)
-const text = await send('Runtime.evaluate', { expression: 'document.body.innerText', returnByValue: true });
+// read what is on screen, to assert a change happened
+const text = await send('Runtime.evaluate', {
+  expression: 'document.body.innerText',
+  returnByValue: true,
+});
 console.log(text.result.value);
 
 // press a button: keyDown + keyUp. key/code/text must match a real key.
 const key = (type: string, k: string, code: string, vk: number) =>
-  send('Input.dispatchKeyEvent', { type, key: k, code, text: k.length === 1 ? k : '', windowsVirtualKeyCode: vk });
-await key('keyDown', '3', 'Digit3', 51);   // preset 3
+  send('Input.dispatchKeyEvent', {
+    type,
+    key: k,
+    code,
+    text: k.length === 1 ? k : '',
+    windowsVirtualKeyCode: vk,
+  });
+await key('keyDown', '3', 'Digit3', 51); // preset 3
 await key('keyUp', '3', 'Digit3', 51);
 
 // rotary wheel = horizontal scroll:
-await send('Input.dispatchMouseEvent', { type: 'mouseWheel', x: 400, y: 240, deltaX: 120, deltaY: 0 });
+await send('Input.dispatchMouseEvent', {
+  type: 'mouseWheel',
+  x: 400,
+  y: 240,
+  deltaX: 120,
+  deltaY: 0,
+});
 
 process.exit(0);
 ```
 
-Read the screenshot and the `innerText` to confirm the app reacted. Prefer the
-local loop for fast iteration; use the device to confirm real behavior (real
-now-playing, real artwork, the actual screen).
+Iterate in the local loop, then confirm real now-playing, real artwork, and the
+actual screen on the device.
 
 ## Input reference
 
-The controls arrive as ordinary browser events. Listen for them with a `keydown`
-handler and a `wheel` handler on `window`. Make horizontal wheel scroll move
-through your primary list; it is the control users reach for first.
-
-| Control      | Browser event                        | CDP `key`/`code`/vk    |
-| ------------ | ------------------------------------ | ---------------------- |
-| Preset 1-4   | `keydown` key `"1"` `"2"` `"3"` `"4"` | `Digit1`-`Digit4` / 49-52 |
-| Mode (M)     | `keydown` key `"m"`                  | `KeyM` / 77            |
-| Back         | `keydown` key `"Escape"`             | `Escape` / 27          |
-| Rotary wheel | `wheel` with `deltaX` (horizontal)   | mouseWheel `deltaX`    |
-| Touch        | pointer / touch events               | `Input.dispatchTouchEvent` |
+| Control      | Browser event                         | CDP `key`/`code`/vk        |
+| ------------ | ------------------------------------- | -------------------------- |
+| Preset 1-4   | `keydown` key `"1"` `"2"` `"3"` `"4"` | `Digit1`-`Digit4` / 49-52  |
+| Mode (M)     | `keydown` key `"m"`                   | `KeyM` / 77                |
+| Back         | `keydown` key `"Escape"`              | `Escape` / 27              |
+| Rotary wheel | `wheel` with `deltaX` (horizontal)    | mouseWheel `deltaX`        |
+| Touch        | pointer / touch events                | `Input.dispatchTouchEvent` |

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

@@ -0,0 +1,183 @@
+# Extensions (`@bridgething/extension`)
+
+An extension is the desktop-side half of a webapp: a Deno process the bridgething
+desktop app spawns, one per installed and enabled app. It has whatever host
+access the manifest asks for, and reaches every connected Car Thing through the
+daemon's forward surface.
+
+## Shape of an extension
+
+```ts
+import { asJson, defineExtension, json } from '@bridgething/extension';
+
+let timer: ReturnType<typeof setInterval> | undefined;
+
+defineExtension({
+  start(ctx) {
+    ctx.on('device', event => ctx.log.info(event.type, event.device.name));
+    ctx.on('message', (device, message) =>
+      device.send(json({ echo: asJson(message) })),
+    );
+    timer = setInterval(() => ctx.broadcast(json({ tick: Date.now() })), 5_000);
+  },
+  stop() {
+    clearInterval(timer);
+  },
+});
+```
+
+`defineExtension` runs `start` after the host's `hello`, sends `ready` when the
+returned promise settles, and on `stop`, or when the host closes stdin, runs
+`stop` and exits. The extension runs device or no device.
+
+- Stdout is the protocol. Log with `ctx.log.*` and keep `console.error` on stderr
+  for scratch debugging.
+- Register listeners synchronously at the top of `start`. The host replays every
+  live device immediately after it calls `start`, so a listener added after an
+  `await` misses them.
+
+## The `ctx` contract
+
+Read `node_modules/@bridgething/extension/dist/*.d.ts` for the exact signatures.
+
+Identity:
+
+- `ctx.api` is the host protocol revision, `1`.
+- `ctx.webapp` is `{ id, name, version }` from `manifest.json`.
+- `ctx.dataDir` is a directory this extension owns. The kv store lives there.
+
+Devices:
+
+- `ctx.devices` is the connected devices, recomputed on read.
+- `ctx.device(id)` returns a handle for any id, connected or not. It never
+  throws.
+- `ctx.on('device', event => ...)` streams `event.type` of `connected`,
+  `disconnected`, or `active`, with `event.device` as the handle.
+- A handle carries `id`, `name`, `active`, `connected`, `config`, and `send`, and
+  survives a disconnect with `connected` false.
+
+Messages:
+
+- `ctx.device(id).send(message)` and `ctx.broadcast(message)`. Broadcast reaches
+  every connected device where this webapp is active.
+- `ctx.on('message', (device, message) => ...)` takes forwards coming back.
+- Both directions are fire and forget. Build your own correlation for
+  request and reply.
+- The daemon delivers a forward to the active webapp, so check `device.active`. A
+  send to a backgrounded app is dropped silently.
+
+Config:
+
+- `ctx.config(device)` is a snapshot of that device's settings, keyed by
+  `manifest.json` config key. Values are strings.
+- `ctx.on('config', (device, key, value) => ...)` fires when a settings page
+  writes, from any companion. `value` is `null` when the user cleared the key,
+  and the key leaves the snapshot. An empty string is a real empty value.
+
+Storage, auth, logging:
+
+- `ctx.kv.get(key)`, `.set(key, value)`, `.delete(key)`, and `.list()` are a
+  persistent JSON store scoped to this extension. `get` resolves `undefined` for
+  a missing key.
+- `ctx.auth.authorize(url)` opens the system browser and resolves with the full
+  callback URL, query string included. It rejects when the user backs out.
+- `ctx.log.debug/info/warn/error(...args)` writes into the host's log: the vite
+  terminal in development, the desktop app's log once installed.
+- `kv` and `auth` failures reject with an `ExtensionError` carrying a `kind` of
+  `host-error`, `disconnected`, or `write-failed`.
+
+Persist eagerly as state changes. The host drops your stdin the moment it sends
+`stop`, so a `ctx.kv` or `ctx.auth` call made from `stop` rejects with
+`kind: 'disconnected'`. Use `stop` to release timers, sockets, and children.
+
+## Forward messages
+
+A forward is `{ encoding, data }`, the same type the webapp SDK uses:
+
+| encoding | reading                             | writing                                |
+| -------- | ----------------------------------- | -------------------------------------- |
+| `text`   | `asText(message)` -> `string`       | `send('hi')` or `send(text('hi'))`     |
+| `json`   | `asJson<T>(message)` -> `T`         | `send(json(value))`                    |
+| `binary` | `asBinary(message)` -> `Uint8Array` | `send(bytes)` or `send(binary(bytes))` |
+
+The narrowing helpers return `undefined` when the encoding does not match, so
+`asJson(message) ?? fallback` is the normal shape. Wrap a plain object in
+`json(...)` before sending, because `send` cannot tell one apart from a
+`ForwardMessage`. Binary always arrives as a `Uint8Array`.
+
+## Manifest block and permissions
+
+```json
+"extension": {
+  "entry": "extension/desktop.mjs",
+  "permissions": ["all"],
+  "api": 1
+}
+```
+
+- `entry` is the path inside the built bundle. It must exist, or the daemon
+  refuses the install.
+- `api` is the host protocol revision. `1` is frozen.
+- `permissions` are Deno permission descriptors, handed to the runtime as flags.
+
+Descriptor grammar, one string per entry: `all`, `net`, `net:<host[:port]>`,
+`read`, `read:<path>`, `write`, `write:<path>`, `run`, `run:<binary>`, `env`,
+`env:<VAR>`, `sys`, `sys:<kind>`, `ffi`, `ffi:<path>`. A path may start with `~`.
+
+Narrow `["all"]` before you publish. The dev loop runs the extension with exactly
+the declared flags, so it fails on your machine the moment you use something you
+did not declare. The store card lists the permissions and the desktop app makes
+the user confirm them at install. A version declaring `extension` must publish
+from a public GitHub repo.
+
+## The dev loop
+
+```bash
+bun run dev            # page in your browser + extension under deno, both on the connected Car Thing
+bun run dev:device     # the same, with the page on the Car Thing's own screen
+bun run build          # webapp + settings page + dist/extension/desktop.mjs
+bun run share          # zips dist/, extension included
+```
+
+Both dev commands:
+
+1. Make this app the active webapp on the Car Thing, installing it once if the
+   device has never seen it, so forwards route.
+2. Bundle `extension/main.ts` with esbuild and run it under Deno with the
+   manifest's permissions, from the gitignored `.dev-extension/`, which also
+   holds the kv store. Every save rebuilds and restarts it. A build error prints
+   and leaves the previous build running.
+3. Link to the daemon over USB as an extension host, so the extension gets
+   `device.connected`, `device.active`, `config.changed`, and every forward the
+   page sends. With the Car Thing unplugged it links up when one appears.
+
+`ctx.log.*` and stderr both print in the vite terminal. A crash restarts with
+backoff, or immediately on the next save; a tight loop shows as `crashed` in the
+desktop app's row. Ctrl-C stops the extension and, under `dev:device`, hands the
+screen back. Disable this app's extension in the desktop app while you develop,
+or the page hears both copies.
+
+Under `bun run dev`, `ctx.auth.authorize(url)` ends on bridgething.com's callback
+page. Copy that page's address and paste it at
+`http://localhost:5173/__extension/authorize` to deliver it to the extension. The
+desktop app captures the callback itself once the app is installed there.
+
+The runtime is the `deno` npm package, pinned to the version the desktop app
+downloads and fetched into `node_modules` on first run. `BRIDGETHING_DENO=/path`
+overrides it.
+
+## Shipping
+
+`bun run push` installs the webapp on a Car Thing, and the extension stays on the
+desktop. Once someone installs the app through the desktop app, that app runs the
+extension from the zip. Phones have no extension host, and the desktop app can be
+closed while the device is on a phone, so make the webapp useful with nothing
+attached.
+
+`npm:`, `jsr:`, and `node:` specifiers work in the bundle, as do `Deno.Command`
+and unix sockets, subject to the permissions you declared. Deno resolves them at
+runtime only when it is not standing in a project: a `package.json` or
+`deno.json` anywhere above the bundle switches it to node_modules resolution and
+it refuses `npm:` with _"Could not find a matching package"_. The dev loop and
+the desktop app run the bundle from a data directory with
+`DENO_NO_PACKAGE_JSON=1`. Set that variable when you run the bundle by hand.