create-bridgething 0.12.1 → 0.15.0

package/README.md

@@ -1,13 +1,16 @@
 # create-bridgething
 
-Scaffold a [bridgething](https://github.com/JoeyEamigh/bridgething) webapp for
-the Spotify Car Thing: React, Vite, Tailwind v4, and
-[`@bridgething/client`](https://www.npmjs.com/package/@bridgething/client).
+Scaffold a [bridgething](https://github.com/JoeyEamigh/bridgething) app source
+for the Spotify Car Thing: a GitHub repo of webapps (React, Vite, Tailwind v4,
+[`@bridgething/client`](https://www.npmjs.com/package/@bridgething/client)) that
+publishes a store catalog to GitHub Pages.
 
 ```sh
-bun create bridgething my-app
+bun create bridgething my-apps
 ```
 
+Run it again inside the source to add another app.
+
 | flag           | what you get                                  |
 | -------------- | --------------------------------------------- |
 | `--launcher`   | A replacement home screen                     |
@@ -18,9 +21,9 @@ bun create bridgething my-app
 
 `--extension` combines with `--launcher`, `--overlay`, or a plain webapp.
 
-The project ships `bun run dev`, `build`, `push` (install on a connected Car
-Thing), `share` (zip for the store), and `update` (bring the device to the
-latest release).
+The source ships `bun run dev`, `push` (install on a connected Car Thing),
+`share` (zip to hand to someone directly), `bump`, `check`, and `submit` (list
+the source in the bridgething store). Pushing to main publishes the catalog.
 
 - Docs: <https://bridgething.com/docs>
 - Source: <https://github.com/JoeyEamigh/bridgething>

package/dist/index.mjs

@@ -133,6 +133,7 @@ const TEMPLATE_DIR = join(PACKAGE_ROOT, "template");
 const SOURCE_TEMPLATE_DIR = join(PACKAGE_ROOT, "template-source");
 const SKILL_IN_APP = join(".claude", "skills", "bridgething");
 const SDK_VERSIONS = readJson(join(PACKAGE_ROOT, "template-versions.json"));
+const OWN = readJson(join(PACKAGE_ROOT, "package.json"));
 const EXTENSION = {
 	dir: "template-extension",
 	manifest: {
@@ -366,7 +367,14 @@ function scaffoldApp(root, spec) {
 function linkAgentGuides(root, appDir) {
 	const rootSkill = join(root, SKILL_IN_APP);
 	const appSkill = join(appDir, SKILL_IN_APP);
-	if (!existsSync(rootSkill)) move(appSkill, rootSkill);
+	if (!existsSync(rootSkill)) {
+		move(appSkill, rootSkill);
+		writeJson(join(rootSkill, ".source.json"), {
+			package: OWN.name,
+			version: OWN.version,
+			fetched_at: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	}
 	linkOrCopy(relative(dirname(appSkill), rootSkill), appSkill, rootSkill);
 	for (const link of [join(root, "AGENTS.md"), join(appDir, "AGENTS.md")]) {
 		if (existsSync(link) || !existsSync(join(dirname(link), "CLAUDE.md"))) continue;
@@ -479,7 +487,7 @@ Done. ${target}
 Fill in the description in apps/${details.app}/public/manifest.json.
 
 Push to ${repoUrl}, then in Settings > Pages set the branch to gh-pages, folder / (root).
-Your catalog ends up at at ${base}/catalog.v1.json, which you can submit to the bridgething store.
+Your catalog ends up at ${base}/catalog.v1.json. Once it loads, "bun run submit" lists it in the bridgething store.
 
   bun run new <slug>   add another app to this source
   bun run bump ${details.app} [version]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bridgething",
-  "version": "0.12.1",
+  "version": "0.15.0",
   "type": "module",
   "description": "Scaffold a bridgething app source: webapps for the Spotify Car Thing, published as a catalog.v1 on GitHub Pages.",
   "license": "MIT",
@@ -46,13 +46,27 @@
     "test": "bun test"
   },
   "devDependencies": {
-    "@bridgething/extension": "0.12.1",
+    "@bridgething/client": "0.14.0",
+    "@bridgething/extension": "0.14.0",
     "@msgpack/msgpack": "^3.1.3",
+    "@preact/preset-vite": "^2.10.6",
+    "@tailwindcss/vite": "^4.3.3",
     "@types/bun": "^1.4.0",
     "@types/node": "^26.1.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@types/uuid": "^11.0.0",
+    "@vitejs/plugin-react": "^6.1.2",
     "esbuild": "^0.28.2",
-    "tsdown": "^0.21.10"
+    "fflate": "^0.8.3",
+    "happy-dom": "^21.0.3",
+    "preact": "^11.0.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tailwindcss": "^4.3.3",
+    "tsdown": "^0.21.10",
+    "vite": "^8.3.4",
+    "vite-plugin-singlefile": "^2.3.4"
   },
   "peerDependencies": {
     "typescript": "^6.0.3"

package/template/_claude/skills/bridgething/SKILL.md

@@ -1,17 +1,18 @@
 ---
 name: bridgething
-description: Build, run, and ship a bridgething webapp for the Spotify Car Thing. Use for @bridgething/client calls (now-playing, transport, artwork, storage, user settings, networking, every surface), running the dev server and driving the 800x480 screen and its physical controls, pushing the built app to a device or packaging a shareable zip, and writing the desktop-side Deno extension a webapp can ship.
+description: Build, run, and ship a bridgething webapp for the Spotify Car Thing. Use for @bridgething/client calls (now-playing, transport, artwork, storage, user settings, networking, every surface), running the dev server and driving the 800x480 screen and its physical controls, pushing the built app to a device, packaging a shareable zip, or publishing and listing it in the bridgething store, and writing the desktop-side Deno extension a webapp can ship.
 ---
 
 # Building a bridgething webapp
 
 - Calling the daemon, from now-playing to networking, plus every surface the SDK
-  ships: [reference/sdk.md](reference/sdk.md)
+  ships, the companion settings page, its config form, and files the user picks:
+  [reference/sdk.md](reference/sdk.md)
 - Running the app, screenshotting the 800x480 screen, and pressing the physical
   controls locally and over CDP on the device:
   [reference/develop.md](reference/develop.md)
-- Installing onto a connected Car Thing, packaging a zip, and updating the
-  device: [reference/ship.md](reference/ship.md)
+- Installing onto a connected Car Thing, packaging a zip, publishing to the
+  store, and updating the device: [reference/ship.md](reference/ship.md)
 - The desktop-side Deno extension, its `ctx` contract, and its permission model,
   when the project has an `extension/` directory:
   [reference/extension.md](reference/extension.md)

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

@@ -13,6 +13,11 @@ than fixtures. `SUPERBIRD_HOST=bridgething-<serial>.local` targets another
 device, and `BRIDGETHING_DAEMON_URL=ws://host:8891` targets a daemon anywhere
 else.
 
+Blob urls from `client.blob` (`/.bridgething/blob/...`) go through the dev
+server to that same daemon. The daemon serves blobs for its active webapp only,
+so they load once this app is the active one on the device. `bun run dev:device`
+and `bun run push` both make it active.
+
 ## Show it on the Car Thing with hot reload
 
 ```bash
@@ -55,6 +60,7 @@ 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('Enter'); // wheel click
 // touch: page.tap('selector')  or  page.mouse.click(x, y)
 ```
 
@@ -64,8 +70,8 @@ Loop: edit code, let vite hot-reload, screenshot, adjust. Keep the viewport at
 ## Your own browser and DevTools
 
 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.
+device toolbar. Type `1` through `4`, `m`, `Escape`, and `Enter` for the wheel click, and hold
+shift while scrolling for the rotary's horizontal wheel.
 
 ## Drive the real device over CDP
 
@@ -131,11 +137,13 @@ const key = (type: string, k: string, code: string, vk: number) =>
     type,
     key: k,
     code,
-    text: k.length === 1 ? k : '',
+    text: k === 'Enter' ? '\r' : k.length === 1 ? k : '',
     windowsVirtualKeyCode: vk,
   });
 await key('keyDown', '3', 'Digit3', 51); // preset 3
 await key('keyUp', '3', 'Digit3', 51);
+await key('keyDown', 'Enter', 'Enter', 13); // wheel click
+await key('keyUp', 'Enter', 'Enter', 13);
 
 // rotary wheel = horizontal scroll:
 await send('Input.dispatchMouseEvent', {
@@ -160,4 +168,5 @@ actual screen on the device.
 | Mode (M)     | `keydown` key `"m"`                   | `KeyM` / 77                |
 | Back         | `keydown` key `"Escape"`              | `Escape` / 27              |
 | Rotary wheel | `wheel` with `deltaX` (horizontal)    | mouseWheel `deltaX`        |
+| Wheel click  | `keydown` key `"Enter"`               | `Enter` / 13               |
 | Touch        | pointer / touch events                | `Input.dispatchTouchEvent` |

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

@@ -68,6 +68,7 @@ client.player.stateGet().then(r => r.ok && setState(r.response.state)); // prime
 // playback.state: 'stopped' | 'paused' | 'playing'; playback.positionMs; playback.shuffle
 
 client.player.play({ uri: 'spotify:track:...' });
+client.player.play({ uri: 'https://stream.example/live.mp3' }); // any http(s) media url plays on the phone
 client.player.pause();
 client.player.resume();
 client.player.skipNext();
@@ -81,6 +82,14 @@ client.player.setRepeat({ mode: 'all' }); // 'off' | 'all' | 'one'
 seek. For a smooth progress bar, extrapolate the playhead between snapshots from
 `playback.state` and `playback.positionMs`.
 
+An `http`/`https` uri is a raw media stream (internet radio, a podcast episode,
+an HLS playlist) played by the phone's native player. Its snapshot carries the
+stream's live metadata: ICY titles land in `track.title`, station artwork in
+`track.artworkId`, and `playback.setElapsedTimeAvailable` is true only for
+finite media that can seek. Live streams have no duration. A stream that fails
+arrives on `player.onErrorEvent` as `playFailed`, and the stream stops when the
+last Car Thing disconnects.
+
 `client.asset`. Player state carries opaque asset ids:
 
 ```ts
@@ -109,14 +118,151 @@ const r = await client.config.get({ key: 'units' });
 const all = await client.config.list();
 ```
 
-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.
+Each field in the manifest's `config` array is `string`, `secret`, `number`,
+`boolean` or `enum`. Keep `label` short; help text goes in `description`, which
+the settings form shows under the label. An enum stores its `choices` values and
+shows `choiceLabels` in their place:
+
+```json
+{
+  "type": "enum",
+  "data": {
+    "key": "frost",
+    "label": "Overlay frostiness",
+    "description": "How frosted the overlay surfaces look.",
+    "choices": ["0", "1", "2"],
+    "choiceLabels": { "0": "clear", "1": "light", "2": "frosted" },
+    "default": "2"
+  }
+}
+```
+
+## The settings page: `@bridgething/client/settings`
+
+The page under `settings/` runs in the companion: the phone app, the desktop
+app, or the device page at bridgething.com. It reads and writes the app's
+config and docs through `@bridgething/client/settings`, a `postMessage` bridge.
+
+```ts
+import { settings } from '@bridgething/client/settings';
+
+const { webappId, name, version, deviceId } = await settings.context();
+await settings.config.set('units', 'metric'); // also fields, list, delete
+await settings.doc.set('layout', JSON.stringify(layout)); // also get, list, delete
+const off = settings.onDocChanged((key, value) => sync(key, value));
+settings.done(); // closes the settings screen
+```
+
+The page has real internet but renders from a null origin, so the webview's
+own `fetch` and XHR are blocked by CORS against any server without permissive
+headers. WebSockets work from the page directly. For HTTP,
+`settings.fetch(url, init)` has the host make the request natively and hands
+back a real `Response`: 1 MiB each way, buffered whole, with an optional
+`timeoutMs`. It rejects with a `SettingsFetchError` whose `kind` is `network`,
+`timeout`, or `invalid_url`. `settings.installFetch()` swaps the global `fetch`
+for third-party SDKs and returns a function that restores it.
+`settings.auth.authorize(url)` opens an OAuth provider in the real browser and
+resolves with the callback URL; register
+`https://bridgething.com/oauth/callback` as the redirect URI, do PKCE in the
+page, and exchange the code over `settings.fetch`. It rejects with an
+`AuthorizeError` whose `kind` is `cancelled`, `busy` (one authorize at a time),
+or `unsupported`. The device page has neither: there `settings.fetch` rejects
+with a plain `Error` and `authorize` with `unsupported`.
+
+The companion keeps the page loaded after the user leaves it and shows the
+same document the next time they open the app's settings. Three rules follow:
+
+- `settings.onRefresh(context => ...)` fires each time the page comes back on
+  screen, and whenever the app's name, version, or config fields change. Reread
+  anything the page read from the device, such as a doc it cached.
+- `settings.done()` works only while the page is on screen. A `done()` from a
+  page the user already left does nothing.
+- A page that navigates or reloads itself comes back as a fresh document.
+  Calls the old one had in flight are never answered.
+- A page that crashes the webview before it finishes loading, or twice in a
+  row while on screen, shows a failure with a retry instead of loading again.
+
+When the phone's settings screen hides, the phone app blurs the focused field.
+
+## The config form: `@bridgething/client/form`
+
+`<ConfigForm/>` renders every `config` field from the manifest and writes each
+one to the device as the user commits it. An app with `config` and no
+`settings` page still gets a settings screen: the companion shows a default
+page that is just `<ConfigForm/>` and a Done button. A custom page embeds the
+form and adds its own controls around it, so never hand-roll inputs for
+declared fields.
+
+```tsx
+import {
+  ConfigForm,
+  ConfigFormError,
+  closeSettings,
+  type ConfigFormHandle,
+} from '@bridgething/client/form';
+
+const form = useRef<ConfigFormHandle>(null);
+
+async function connect() {
+  try {
+    const values = await form.current!.flush();
+    await signIn(values.base_url, values.token);
+  } catch (err) {
+    if (!(err instanceof ConfigFormError)) throw err;
+    setStatus(err.message);
+  }
+}
+
+async function close() {
+  try {
+    await closeSettings(form.current);
+  } catch (err) {
+    setStatus(err instanceof Error ? err.message : String(err));
+  }
+}
+
+<ConfigForm ref={form} />;
+```
 
-Write it in react like the rest of the app. `react` and `react-dom/client`
+A toggle or a choice commits on tap. A text or number field commits when it
+loses focus, or on Enter. A touch webview does not always take focus off a
+field when a button is tapped, so any button that acts on the values calls
+`flush()` first. A Done button calls `closeSettings(form.current)`, which
+flushes and then closes the page unless an edit was refused, rejecting with
+that error so the page can show it. `flush()` writes every field still being
+typed, waits for the device, and resolves with the values the device holds.
+It rejects with a `ConfigFormError`:
+
+- `kind: 'refused'`: a typed value broke its field's rules, or the device
+  refused the write. `fields` maps each config key to its message and `message`
+  is `<label>: <reason>`. The form shows the same message under the field.
+- `kind: 'unavailable'`: the form never loaded. `message` is the load failure,
+  and the form shows its own retry.
+- `kind: 'replaced'`: the host pointed the page at another app while `flush()`
+  waited. The edits still land on the app they were made for.
+
+`onChange` reports written values only, never text still being typed. It fires
+the moment a field commits, and again with the device's value if the write is
+refused. Take values for an action from `flush()`, not from `onChange` state.
+The form rereads its fields and values on every refresh.
+
+The form styles off `--bt-*` CSS variables (`--bt-color-bg`, `--bt-color-fg`,
+`--bt-color-accent`, `--bt-font-body`, `--bt-text-row`, and the rest of the
+names in `@bridgething/client/theme`).
+
+The host app's theme arrives on its own. `settings.context()` carries
+`theme: { scheme, colors, text, fonts }`, and importing
+`@bridgething/client/settings` paints it as those `--bt-*` variables plus
+`--bt-scheme` (`light` or `dark`), repainting when the phone or desktop flips
+scheme. Use the variables in your own CSS and the page matches the app for
+free; `color-scheme: var(--bt-scheme)` on `html` gets native controls right. The
+painted values have zero specificity, so any `:root` rule of yours wins: set
+the variables there to opt out. `settings.onThemeChanged(theme => ...)` hears
+flips when a canvas or chart needs the raw tokens. An older companion sends no
+theme and the variables fall back to the defaults, following
+`prefers-color-scheme`.
+
+Write the page 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
@@ -129,6 +275,146 @@ 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.
 
+## Files the user picks: `client.blob`
+
+A webapp can show files the user hands it from the companion, like a GIF or
+video background. The settings page picks and uploads them; the webapp only
+reads them.
+
+```tsx
+import type { BlobEntry } from '@bridgething/lib/client';
+
+const [bg, setBg] = useState<BlobEntry | null>(null);
+
+useEffect(() => {
+  const load = async () => {
+    const r = await client.blob.list();
+    setBg(
+      r.ok
+        ? (r.response.entries.find(e => e.key === 'background') ?? null)
+        : null,
+    );
+  };
+  load();
+  return client.blob.onChanged(c => c.key === 'background' && load());
+}, [client]);
+
+if (!bg) return null;
+if (bg.mime.startsWith('video/'))
+  return <video src={bg.url} autoPlay loop muted playsInline />;
+return <img src={bg.url} />;
+```
+
+`url` is `/.bridgething/blob/<key>?v=<sha256>`, served by the daemon from the
+page's own origin with the stored mime, an ETag, and Range support. Use it
+as-is. The `?v=` changes whenever the content does, so caching never shows a
+stale file. Only the active webapp is served, and `onChanged` reaches only the
+active webapp, never an overlay.
+
+On the settings page, `pick` opens the phone's photo picker or the desktop's
+file dialog and hands back a handle, never the bytes. `blob.put` streams the
+file to the device under a key:
+
+```ts
+import { BlobError, settings } from '@bridgething/client/settings';
+
+const picked = await settings.pick({ kind: 'video' }); // null when the user backs out
+if (picked) {
+  thumb.src = picked.preview ?? ''; // small jpeg data url; a video's is its first frame
+  try {
+    await settings.blob.put('background', picked.handle, {
+      onProgress: (sent, total) => (bar.value = sent / total),
+    });
+  } catch (err) {
+    if (err instanceof BlobError && err.kind === 'too_large') showTooBig();
+  }
+}
+```
+
+`kind` is `'image'`, `'video'`, or `'any'`. The companion makes picks fit the
+device before upload, and there are no options beyond `cover`:
+
+- Animated GIF, APNG, and WebP pass through byte for byte. Crop and placement
+  are yours to do in the webapp.
+- Stills larger than the `cover` box scale down until they just cover it,
+  keeping their format. HEIC becomes JPEG.
+- Video always becomes H.264 mp4, no audio, at most 30 fps, scaled to cover the
+  box without upscaling.
+- `any` is untouched.
+- On the device page at bridgething.com, the browser's own file picker is used
+  and nothing is converted or previewed, since a browser has no transcoder.
+
+`cover: [w, h]` is the one override. It defaults to `[800, 800]` for stills,
+which covers the screen in either orientation with zoom headroom, and
+`[800, 480]` for video. Each edge is a whole number from 1 to 4294967295;
+anything else rejects. The result is
+`{ handle, mime, size, width?, height?, durationMs?, preview? }`. One picker is
+open at a time: a `pick` while another is still open rejects with `busy`.
+
+Bytes the page makes itself, like a canvas export, go through a handle too:
+
+```ts
+const png = await new Promise<Blob>(done =>
+  canvas.toBlob(b => done(b!), 'image/png'),
+);
+const handle = await settings.blob.create('image/png');
+await settings.blob.append(handle, png); // Blob, ArrayBuffer, or a typed array
+await settings.blob.put('cropped', handle);
+```
+
+`settings.blob.append` returns the handle's size so far.
+`settings.blob.list()` returns `{ key, sha256, mime, size }` for every key, and
+`settings.blob.delete(key)` removes one.
+
+`put` resolves once the device has the file, however long the link takes: it
+streams on the background lane so now-playing stays smooth, which means a
+large video over a car's Bluetooth link takes minutes. `onProgress` reports the
+bytes the device has confirmed a few times a second and ends on the total, so
+show it. A `put` that picks up an interrupted upload starts at the bytes the
+device already has, not at 0. Putting bytes the device already holds finishes
+at once, and a second `put` of the same key replaces one still in flight.
+
+A handle lives in the companion, not on the device:
+
+- A `put` the device stores uses the handle up. To store the same bytes under
+  a second key, pick or create again.
+- A failed `put` keeps the handle, so the upload can be retried with it.
+- A `put` keeps its handle alive for as long as it streams.
+- A handle nothing is uploading expires after 30 minutes unused.
+- The companion holds at most 128 MiB of handles. A pick or append past that
+  rejects with `busy` until a `put` lands or a handle expires. Nothing already
+  held is dropped.
+- A handle that expired or was used up rejects with `unknown_handle`. Pick
+  again.
+
+`pick` and every `settings.blob` call reject with a `BlobError`. Its `kind`:
+
+- `unsupported`: the companion or the Car Thing predates these calls, or the
+  host cannot do the work.
+- `disconnected`: no Car Thing is linked, or the link dropped mid-upload.
+- `too_large`: the file is over 32 MiB.
+- `quota_exceeded`: the put would take the app past 64 MiB.
+- `storage_full`: the Car Thing has no room left.
+- `not_media`: the picked file is not the kind asked for.
+- `unknown_handle`: the handle is not live. It was never made, it expired, or
+  a stored `put` used it up.
+- `busy`: a picker is already open, or held handles fill the companion's whole
+  handle budget.
+- `no_gesture`: the pick did not start from a tap or click, so the browser
+  opened no picker. Call `pick` from the tap handler itself.
+- `failed`: anything else. Read `message`.
+
+The footguns:
+
+- 32 MiB per file and 64 MiB per webapp of distinct content. The device refuses
+  past either and never evicts to make room, so delete what you replace.
+- A key is 1 to 256 bytes with no control characters. Do not use `.` or `..`:
+  a browser folds them out of the url, so the file never loads.
+- A GIF is decoded on the device's CPU every frame, on a Cortex-A53 that also
+  runs everything else. A big or long GIF starves the now-playing UI. Prefer
+  video for animated backgrounds: it decodes in hardware. Pick with
+  `kind: 'video'`, or tell users to keep GIFs small.
+
 `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.
@@ -156,12 +442,13 @@ Read a surface's class in `dispatch.generated.d.ts` for its exact methods.
 | `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 |
+| `system` | version, logs, power, diagnostics, launcher gesture, companion launch | versionRequest, logsTail, logsSubscribe, reboot, powerOff, factoryReset, launcherGestureGet, launcherGestureSet, companionLaunchGet, companionLaunchSet, onVersion, onLogEntry, onOtaProgress, onLauncherGestureChanged, onCompanionLaunchChanged |
 | `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 |
+| `blob` | files the user picked in the companion, served by url | list, onChanged |
 | `lyrics` | timed lyrics for the current track | get |
 | `peer` | every known peer and its link state | onSnapshot |
 

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

@@ -31,6 +31,26 @@ Anyone with a bridgething Car Thing installs that zip from the companion app.
 
 Raise `version` in `public/manifest.json` before you share an update. Keep `id`.
 
+## Publish to the store
+
+From the repo root, `bun run bump <slug> <major | minor | patch>` moves the
+version, then a push to main runs the publish workflow. It builds every new
+version into `catalog.v1.json` on the `gh-pages` branch. GitHub Pages has to
+serve that branch from `/ (root)` (repo Settings > Pages), and the catalog lands
+at `base_url` from `source.json` plus `/catalog.v1.json`.
+
+Until the source is submitted, the store does not show it, and only people who
+paste that URL into the companion app can install from it. Once the first
+publish is live and the catalog URL loads, ask the user whether they want it in
+the bridgething store. A listing is public, so submit only on a yes:
+
+```bash
+bun run submit   # lists the source, or refreshes an existing listing
+```
+
+The store rechecks every listed source on its own, so later versions appear
+without another submit. Run it again to pick one up right away.
+
 ## Keep the device on the latest bridgething
 
 ```bash

package/template/package.json

@@ -14,13 +14,13 @@
     "update": "bunx @bridgething/updater"
   },
   "dependencies": {
-    "preact": "^10.29.7",
+    "preact": "^11.0.1",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },
   "devDependencies": {
     "@msgpack/msgpack": "^3.1.3",
-    "@preact/preset-vite": "^2.10.5",
+    "@preact/preset-vite": "^2.10.6",
     "@tailwindcss/vite": "^4.3.3",
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",

package/template/scripts/bridgething.ts

@@ -1,7 +1,4 @@
 // Generated from @bridgething/webapp-shared.
-import { createRequire } from 'node:module';
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
 // ../webapp-shared/src/dev.ts
 import { spawn as spawn2 } from 'node:child_process';
 import { isIPv4 } from 'node:net';
@@ -14,7 +11,7 @@ var DAEMON_PROXY_PATH = '/__bridgething';
 // ../webapp-shared/src/extension.ts
 import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { createRequire as createRequire2 } from 'node:module';
+import { createRequire } from 'node:module';
 import { homedir, platform } from 'node:os';
 import { delimiter, dirname, join as join2, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
@@ -383,7 +380,7 @@ async function resolveDeno(root) {
 }
 function denoPackageDir(root) {
   try {
-    return dirname(createRequire2(join2(root, 'package.json')).resolve('deno/package.json'));
+    return dirname(createRequire(join2(root, 'package.json')).resolve('deno/package.json'));
   } catch {
     return null;
   }
@@ -824,6 +821,7 @@ ${lines.join(`
 // ../webapp-shared/src/dev.ts
 var DEVICE_MODE = 'device';
 var AUTHORIZE_PATH = '/__extension/authorize';
+var BLOB_URL_PREFIX = '/.bridgething/blob/';
 var DAEMON_PORT = 8891;
 var SWITCH_SETTLE_MS = 1000;
 async function daemonProxyTarget() {
@@ -832,13 +830,18 @@ async function daemonProxyTarget() {
   return `ws://${await resolveHost(deviceHostName())}:${DAEMON_PORT}`;
 }
 async function daemonProxy() {
+  const target = await daemonProxyTarget();
   return {
     [DAEMON_PROXY_PATH]: {
-      target: await daemonProxyTarget(),
+      target,
       ws: true,
       changeOrigin: true,
       rewrite: path => path.slice(DAEMON_PROXY_PATH.length) || '/',
     },
+    [BLOB_URL_PREFIX]: {
+      target: target.replace(/^ws/, 'http'),
+      changeOrigin: true,
+    },
   };
 }
 function bridgething() {
@@ -1083,4 +1086,4 @@ ${note ? `<p class="note">${escapeHtml(note)}</p>` : ''}
 ${status}
 `;
 }
-export { AUTHORIZE_PATH, bridgething, buildExtension, daemonProxy, daemonProxyTarget, DEVICE_MODE };
+export { AUTHORIZE_PATH, BLOB_URL_PREFIX, bridgething, buildExtension, daemonProxy, daemonProxyTarget, DEVICE_MODE };

package/template/scripts/push.ts

@@ -360,13 +360,13 @@ async function bridgethingPush({ scriptUrl }) {
     return parsed;
   };
   if (args.release) {
-    const manifest2 = readManifest();
-    for (const slot of declaredSlots(manifest2)) {
+    const manifest = readManifest();
+    for (const slot of declaredSlots(manifest)) {
       const result = await setSlot(target, slot, null);
       if (!result.ok) throw new Error(result.reason);
       console.log(`${slot} slot: reverted to the built-in one`);
     }
-    if (declaredSlots(manifest2).length === 0) console.log('this bundle declares no slots; nothing to release');
+    if (declaredSlots(manifest).length === 0) console.log('this bundle declares no slots; nothing to release');
     return;
   }
   if (!args.skipBuild) await buildBundle(repoDir);

package/template/settings/main.tsx

@@ -1,104 +1,61 @@
-import { settings, type ConfigField, type SettingsContext } from '@bridgething/client/settings';
-import { useEffect, useState, type FormEvent, type InputEvent } from 'react';
+import { ConfigForm, closeSettings, type ConfigFormHandle } from '@bridgething/client/form';
+import { settings, type SettingsContext } from '@bridgething/client/settings';
+import { useEffect, useRef, useState } from 'react';
 import { createRoot } from 'react-dom/client';
 import './style.css';
 
-function fieldMeta(field: ConfigField): { key: string; label: string } {
-  return { key: field.data.key, label: field.data.label };
-}
-
 function Settings() {
+  const form = useRef<ConfigFormHandle>(null);
   const [ctx, setCtx] = useState<SettingsContext | null>(null);
-  const [fields, setFields] = useState<ConfigField[]>([]);
-  const [values, setValues] = useState<Record<string, string>>({});
   const [status, setStatus] = useState('');
 
   useEffect(() => {
-    (async () => {
-      try {
-        setCtx(await settings.context());
-        const [schema, entries] = await Promise.all([settings.config.fields(), settings.config.list()]);
-        setFields(schema);
-        setValues(Object.fromEntries(entries.map(e => [e.key, e.value])));
-      } catch (err) {
-        setStatus(err instanceof Error ? err.message : String(err));
-      }
-    })();
+    settings.context().then(setCtx, (err: unknown) => setStatus(errText(err)));
+    return settings.onRefresh(setCtx);
   }, []);
 
-  async function saveConfig(event: FormEvent<HTMLFormElement>) {
-    event.preventDefault();
-    setStatus('saving...');
+  async function saveToDevice() {
+    setStatus('writing to device...');
     try {
-      for (const field of fields) {
-        const { key } = fieldMeta(field);
-        await settings.config.set(key, values[key] ?? '');
-      }
-      setStatus('settings saved');
+      const values = await form.current?.flush();
+      await settings.doc.set('preferences', JSON.stringify({ values, savedAt: Date.now() }));
+      setStatus('synced a preferences doc to the device');
     } catch (err) {
-      setStatus(err instanceof Error ? err.message : String(err));
+      setStatus(errText(err));
     }
   }
 
-  async function saveToDevice() {
-    setStatus('writing to device...');
+  async function close() {
     try {
-      await settings.doc.set('preferences', JSON.stringify({ values, savedAt: Date.now() }));
-      setStatus('synced a preferences doc to the device');
+      await closeSettings(form.current);
     } catch (err) {
-      setStatus(err instanceof Error ? err.message : String(err));
+      setStatus(errText(err));
     }
   }
 
   return (
     <main>
       <h1>{ctx?.name ?? '__PROJECT_NAME__'} settings</h1>
-      <p className="hint">{ctx ? `${ctx.webappId} on ${ctx.deviceId}` : 'connecting to the companion host...'}</p>
+      <p className="hint">{ctx ? `${ctx.name} ${ctx.version}` : 'connecting to the companion host...'}</p>
 
-      <form onSubmit={saveConfig}>
-        {fields.length === 0 && <p className="hint">this webapp declares no config fields yet.</p>}
-        {fields.map(field => {
-          const { key, label } = fieldMeta(field);
-          const value = values[key] ?? '';
-          const onInput = (e: InputEvent<HTMLInputElement | HTMLSelectElement>) =>
-            setValues({ ...values, [key]: (e.target as HTMLInputElement).value });
-          return (
-            <div className="field" key={key}>
-              <label htmlFor={key}>{label}</label>
-              {field.type === 'enum' ? (
-                <select id={key} value={value} onInput={onInput}>
-                  {field.data.choices.map(choice => (
-                    <option value={choice} key={choice}>
-                      {choice}
-                    </option>
-                  ))}
-                </select>
-              ) : (
-                <input
-                  id={key}
-                  type={field.type === 'number' ? 'number' : field.type === 'secret' ? 'password' : 'text'}
-                  value={value}
-                  onInput={onInput}
-                />
-              )}
-            </div>
-          );
-        })}
+      <ConfigForm ref={form} />
 
-        <div className="row">
-          <button type="submit">Save settings</button>
-          <button type="button" className="secondary" onClick={saveToDevice}>
-            Save to device
-          </button>
-          <button type="button" className="secondary" onClick={() => settings.done()}>
-            Done
-          </button>
-        </div>
-      </form>
+      <div className="row">
+        <button type="button" onClick={saveToDevice}>
+          Save to device
+        </button>
+        <button type="button" className="secondary" onClick={close}>
+          Done
+        </button>
+      </div>
 
       <p className="status">{status}</p>
     </main>
   );
 }
 
+function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
 createRoot(document.getElementById('root')!).render(<Settings />);

package/template/settings/style.css

@@ -1,14 +1,14 @@
 :root {
-  color-scheme: light dark;
-  font-family:
-    system-ui,
-    -apple-system,
-    sans-serif;
+  color-scheme: var(--bt-scheme);
 }
 
 body {
   margin: 0;
   padding: 20px;
+  background: var(--bt-color-bg);
+  color: var(--bt-color-fg);
+  font-family: var(--bt-font-body);
+  font-size: var(--bt-text-body);
   line-height: 1.5;
 }
 
@@ -18,68 +18,50 @@ main {
 }
 
 h1 {
-  font-size: 1.25rem;
-  margin: 0 0 0.25rem;
-}
-
-.hint {
-  opacity: 0.7;
-  font-size: 0.85rem;
-  margin: 0 0 1.25rem;
-}
-
-.field {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  margin-bottom: 14px;
-}
-
-.field label {
-  font-size: 0.85rem;
+  font-family: var(--bt-font-display);
+  font-size: var(--bt-text-title);
   font-weight: 600;
+  margin: 0 0 4px;
 }
 
-.field input,
-.field select {
-  padding: 8px 10px;
-  font-size: 1rem;
-  border: 1px solid color-mix(in srgb, currentColor 25%, transparent);
-  border-radius: 8px;
-  background: transparent;
-  color: inherit;
+.hint {
+  color: var(--bt-color-muted);
+  font-family: var(--bt-font-mono);
+  font-size: var(--bt-text-hint);
+  margin: 0 0 20px;
 }
 
 .row {
   display: flex;
-  gap: 10px;
+  gap: 12px;
   align-items: center;
-  margin-top: 8px;
+  margin-top: 16px;
 }
 
-button {
-  padding: 9px 16px;
-  font-size: 0.95rem;
-  font-weight: 600;
-  border: none;
-  border-radius: 8px;
-  background: #00a8e8;
-  color: #06232e;
+.row button {
+  padding: 10px 16px;
+  font-family: var(--bt-font-mono);
+  font-size: var(--bt-text-body);
+  border: 1px solid var(--bt-color-accent);
+  border-radius: 0;
+  background: var(--bt-color-accent-soft);
+  color: var(--bt-color-fg);
   cursor: pointer;
 }
 
-button.secondary {
-  background: color-mix(in srgb, currentColor 12%, transparent);
-  color: inherit;
+.row button.secondary {
+  border-color: var(--bt-color-edge);
+  background: none;
 }
 
-button:disabled {
+.row button:disabled {
   opacity: 0.5;
   cursor: default;
 }
 
 .status {
-  font-size: 0.85rem;
-  opacity: 0.8;
+  color: var(--bt-color-muted);
+  font-family: var(--bt-font-mono);
+  font-size: var(--bt-text-hint);
   min-height: 1.2em;
 }

package/template/vite.config.ts

@@ -3,14 +3,11 @@ import react from '@vitejs/plugin-react';
 import { defineConfig } from 'vite';
 import { bridgething, daemonProxy } from './scripts/bridgething';
 
-export default defineConfig(async () => ({
+export default defineConfig(async ({ command }) => ({
   plugins: [react(), tailwindcss(), bridgething()],
   build: {
     target: 'es2022',
     sourcemap: true,
   },
-  server: {
-    host: true,
-    proxy: await daemonProxy(),
-  },
+  server: command === 'serve' ? { host: true, proxy: await daemonProxy() } : {},
 }));

package/template/vite.settings.config.ts

@@ -12,7 +12,7 @@ function sizeGuard(): Plugin {
   return {
     name: 'settings-size-guard',
     closeBundle() {
-      const out = resolve(__dirname, 'dist', 'settings.html');
+      const out = resolve(import.meta.dirname, 'dist', 'settings.html');
       let bytes: number;
       try {
         bytes = statSync(out).size;
@@ -42,12 +42,13 @@ function sizeGuard(): Plugin {
 export default defineConfig({
   root: 'settings',
   plugins: [preact(), viteSingleFile(), sizeGuard()],
+  resolve: { dedupe: ['preact'] },
   build: {
     target: 'es2022',
-    outDir: resolve(__dirname, 'dist'),
+    outDir: resolve(import.meta.dirname, 'dist'),
     emptyOutDir: false,
     rollupOptions: {
-      input: resolve(__dirname, 'settings', 'settings.html'),
+      input: resolve(import.meta.dirname, 'settings', 'settings.html'),
     },
   },
 });

package/template-overlay/_claude_append.md

@@ -14,7 +14,11 @@ back to the built-in overlay, the recovery path when a build misbehaves.
 The daemon prepends one global before your bundle:
 
 ```js
-window.__bridgethingOverlay = { origin: 'http://127.0.0.1:8891', surfaces: {...} };
+window.__bridgethingOverlay = {
+  origin: 'http://127.0.0.1:8891',
+  url: 'ws://127.0.0.1:8891/?scope=overlay',
+  surfaces: {...},
+};
 ```
 
 `surfaces` is the active webapp's declared profile, a boolean each for
@@ -22,16 +26,22 @@ window.__bridgethingOverlay = { origin: 'http://127.0.0.1:8891', surfaces: {...}
 only the surfaces set to true; an app that draws its own volume indicator
 declares `volume: false`. When every surface is false the daemon injects nothing.
 
-`origin` is the kiosk origin. Compare `location.origin` against it before
-mounting. Everything else comes from `@bridgething/client` over the local
-websocket.
+`url` is the socket to hand `@bridgething/client`. Always use it rather than
+building one from `location`, because the kiosk can be showing a dev server or
+an external page whose host is not the daemon. That socket is scoped to your
+bundle, so `client.config` and `client.doc` read your own settings and storage
+rather than the foreground webapp's, and `client.config.onChanged` fires when a
+companion changes one of your settings.
+
+`origin` is the kiosk origin, for telling a kiosk page apart from a dev server.
 
 ### Output constraints
 
 `overlay.js` must be one self-contained file under 512 KiB. The daemon injects it
-as a script string into another app's document, so it carries its own code and
-styles and reaches nothing at runtime. `vite.overlay.config.ts` builds a single
-inlined iife; keep that shape.
+as a script string into an isolated world over another app's document, so it
+shares the DOM with that app but none of its javascript, and it carries its own
+code and styles. `vite.overlay.config.ts` builds a single inlined iife; keep that
+shape.
 
 Style `overlay/main.tsx` with tailwind classes like the rest of the project.
 `overlay/style.css` is imported with vite's `?inline`, so the compiled css mounts
@@ -40,7 +50,7 @@ into the shadow root as a string. Tailwind scans only `overlay/main.tsx`
 
 ### Keep these four from the starter
 
-1. The origin guard before mounting.
+1. The socket url from the prelude, never one built from `location`.
 2. The `__bridgethingOverlayMounted` guard, so a second injection is a no-op.
 3. The closed shadow root, which keeps your styles and the host app's apart.
 4. Escape-only key handling on the capture phase, active only while something is

package/template-overlay/overlay/main.tsx

@@ -13,7 +13,7 @@ type OverlaySurfaces = {
   volume: boolean;
 };
 
-type OverlayConfig = { origin: string; surfaces: OverlaySurfaces };
+type OverlayConfig = { origin: string; url: string; surfaces: OverlaySurfaces };
 
 declare global {
   interface Window {
@@ -209,8 +209,7 @@ function Overlay({ cfg, client }: { cfg: OverlayConfig; client: BridgethingClien
 
 function boot() {
   const cfg = window.__bridgethingOverlay;
-  if (!cfg || !location.origin.startsWith(cfg.origin)) return;
-  if (window.__bridgethingOverlayMounted) return;
+  if (!cfg || window.__bridgethingOverlayMounted) return;
   window.__bridgethingOverlayMounted = true;
 
   const mount = () => {
@@ -218,7 +217,7 @@ function boot() {
     host.style.cssText = 'position:fixed;inset:0;z-index:2147483647;pointer-events:none';
     const shadow = host.attachShadow({ mode: 'closed' });
     document.body.appendChild(host);
-    render(<Overlay cfg={cfg} client={new BridgethingClient({ url: `ws://${location.host}/` })} />, shadow);
+    render(<Overlay cfg={cfg} client={new BridgethingClient({ url: cfg.url })} />, shadow);
   };
 
   if (document.body) mount();

package/template-overlay/vite.overlay.config.ts

@@ -13,7 +13,7 @@ function sizeGuard(): Plugin {
     closeBundle() {
       let bytes: number;
       try {
-        bytes = statSync(resolve(__dirname, 'dist', 'overlay.js')).size;
+        bytes = statSync(resolve(import.meta.dirname, 'dist', 'overlay.js')).size;
       } catch {
         return;
       }
@@ -28,11 +28,11 @@ export default defineConfig({
   plugins: [preact(), tailwindcss(), sizeGuard()],
   build: {
     target: 'es2022',
-    outDir: resolve(__dirname, 'dist'),
+    outDir: resolve(import.meta.dirname, 'dist'),
     emptyOutDir: false,
     cssCodeSplit: false,
     lib: {
-      entry: resolve(__dirname, 'overlay', 'main.tsx'),
+      entry: resolve(import.meta.dirname, 'overlay', 'main.tsx'),
       formats: ['iife'],
       name: '__overlay',
       fileName: () => 'overlay.js',

package/template-source/CLAUDE.md

@@ -14,9 +14,10 @@ Listen with a `keydown` handler and a `wheel` handler on `window`.
 | Mode         | `keydown` key `"m"`                   |
 | Back         | `keydown` key `"Escape"`              |
 | Rotary wheel | `wheel` with horizontal `deltaX`      |
+| Wheel click  | `keydown` key `"Enter"`               |
 | Touch        | pointer and touch events              |
 
-Make horizontal wheel scroll move through the main list. Five fast presses of Mode returns to the launcher.
+Make horizontal wheel scroll move through the main list and wheel click activate the selected item. Five fast presses of Mode returns to the launcher.
 
 ## The client
 
@@ -33,9 +34,9 @@ Construct it once and reuse it. It connects and reconnects on its own. Call `dae
 
 Now-playing and library data come from the phone's Spotify, so render a placeholder when no phone is connected. Fetch artwork with `client.asset.get` using the opaque id on the track.
 
-Every surface: `player asset config store doc capabilities library audio notifications phone peer geo net hardware bluetooth system time voice lyrics webapp forward`. Each method is an event, a request, or a command.
+Every surface: `player asset config store doc blob capabilities library audio notifications phone peer geo net hardware bluetooth system time voice lyrics webapp forward`. Each method is an event, a request, or a command.
 
-Methods, types, and examples: `.claude/skills/bridgething/reference/sdk.md`. That skill lives once at the repo root and every app symlinks it, so it is one copy for the whole workspace. `bun run skills` refreshes it from the published `create-bridgething`; `bun run check` says when it is behind.
+Methods, types, and examples: `.claude/skills/bridgething/reference/sdk.md`. That skill lives once at the repo root and every app symlinks it, so it is one copy for the whole workspace. `bun run skills` refreshes it from the published `create-bridgething`; it and `bun run check` say when the skill is behind, when `@bridgething/source` is older than the skill expects, and when `package.json` lacks a script the skill uses.
 
 ## Working on one app
 
@@ -53,7 +54,7 @@ bun run --cwd apps/<slug> update       # brings the device to the latest bridget
 
 An app with a variant or an extension carries its own `apps/<slug>/CLAUDE.md` with the parts specific to it.
 
-Running and driving the app: `.claude/skills/bridgething/reference/develop.md`. Push, zip, update: `.claude/skills/bridgething/reference/ship.md`. The desktop-side Deno extension and its permission model, for an app with an `extension/` directory: `.claude/skills/bridgething/reference/extension.md`.
+Running and driving the app: `.claude/skills/bridgething/reference/develop.md`. Push, zip, publish to the store, update: `.claude/skills/bridgething/reference/ship.md`. The desktop-side Deno extension and its permission model, for an app with an `extension/` directory: `.claude/skills/bridgething/reference/extension.md`.
 
 ## The three files that describe an app
 
@@ -62,10 +63,10 @@ Running and driving the app: `.claude/skills/bridgething/reference/develop.md`.
 - `id` identifies this webapp on the device. It is a uuidv7 generated once at scaffold time. **Never change it**: the device keys upgrade-in-place and the app's key-value namespace on it, so a new uuid orphans everyone's installed copy and its data.
 - `version` is what the store publishes against. Move it with `bun run bump`, never by hand.
 - `description` is the store tagline and must not be empty.
-- `config` declares the settings the companion app edits and `client.config` reads.
+- `config` declares the settings `client.config` reads. The companion app edits them through `<ConfigForm/>` from `@bridgething/client/form`, on a default page when the app has no `settings` page.
 - `permissions` grants `geo` and `net.proxy`.
 - `art.heroPx` and `art.thumbPx` are the sizes artwork arrives at.
-- `settings` names the page built from `settings/`, capped at 1 MiB. It talks to the companion app through `@bridgething/client/settings`.
+- `settings` names the page built from `settings/`, capped at 1 MiB. It talks to the companion app through `@bridgething/client/settings` and embeds `<ConfigForm/>` for the declared fields. A button on it that acts on those fields awaits the form's `flush()` first. The companion keeps the page loaded between visits, so it rereads device state in `settings.onRefresh`. It is also where a user picks a file for the app (`settings.pick` + `settings.blob.put`), which the webapp then shows through `client.blob`.
 - `extension` declares the desktop-side Deno process and the host permissions it gets.
 
 **`apps/<slug>/catalog.json`** is the store listing and nothing else: `author`, `homepage`, `source`, an `icon` override, `screenshots`, and `min_libbridgething_version` (the oldest daemon the app works against). Never restate anything the manifest already says. An app that ships an extension must carry its `github.com` repo url in `source`, because the store shows that link next to the host permissions it is asking for.
@@ -83,7 +84,7 @@ bun run check
 
 `new` scaffolds into `apps/<slug>`. Never add an app by hand: the scaffold generates the uuid, writes the store listing, wires the dev server to a connected device, and lands the tsconfig and scripts CI expects.
 
-`shot` captures the kiosk over CDP into `apps/<slug>/screenshots/`. Chromium's debugging port is 9223 and is bound to the device's loopback, so it goes through an ssh tunnel; the command opens and closes one itself. Up to six, filename order, first is the store card.
+`shot` captures the kiosk over CDP into `apps/<slug>/screenshots/`. The image fronts chromium's debugging port on `bridgething.local:9222`, so it needs nothing but the device plugged in. Up to six, filename order, first is the store card.
 
 `bump` writes `public/manifest.json` and `package.json` together and opens the changelog section. Editing one without the other fails the build.
 
@@ -91,6 +92,8 @@ bun run check
 
 Pushing to main publishes. `bun run publish --dry-run` assembles the exact bytes that would be pushed, into `site/`, without pushing.
 
+The store only shows a source that has been submitted to it. Once the first publish is live, ask the user whether they want it in the bridgething store, and run `bun run submit` only on a yes, because a listing is public. The store rechecks listed sources on its own, so a later version needs no second submit.
+
 ## Publishing rules that are not negotiable
 
 - **A published version is immutable.** `published.json` on the `gh-pages` branch records the sha256 clients verify against. Changing an app means a new version, always. `check` fails a pull request that changed an app without bumping it.

package/template-source/README.md

@@ -9,7 +9,7 @@ Webapps for the Spotify Car Thing running [bridgething](https://bridgething.com)
 1. Push this repo to `https://github.com/__REPO_OWNER__/__REPO_NAME__`.
 2. In **Settings > Pages**, set the source to **Deploy from a branch**, branch `gh-pages`, folder `/ (root)`.
 
-The catalog is published to `__BASE_URL__/catalog.v1.json`, which can be submitted to <bridgething.com/apps>
+The catalog is published to `__BASE_URL__/catalog.v1.json`. Once it loads, `bun run submit` lists it in the [bridgething store](https://bridgething.com/apps).
 
 ## Develop
 
@@ -45,7 +45,7 @@ bun run bump __APP_SLUG__ patch -m "Fix the wind direction arrow"
 git commit -am "__APP_SLUG__: fix the wind direction arrow" && git push
 ```
 
-Pushing to main builds the apps and regenerates the catalog.
+Pushing to main builds the apps and regenerates the catalog. The store rechecks listed sources on its own; `bun run submit` refreshes right away.
 
 ## Agent skill
 
@@ -53,5 +53,5 @@ Pushing to main builds the apps and regenerates the catalog.
 
 ```sh
 bun run skills           # refresh it from the published create-bridgething
-bun run skills --check   # check whether it is behind
+bun run skills --check   # check whether it, the toolkit, or the scripts it uses are behind
 ```

package/template-source/package.json

@@ -17,6 +17,7 @@
     "shot": "bridgething-source shot",
     "catalog": "bridgething-source catalog",
     "publish": "bridgething-source publish",
+    "submit": "bridgething-source submit",
     "skills": "bridgething-source skills",
     "format": "prettier --write \"*.json\" \"*.js\""
   },

package/template-versions.json

@@ -1,6 +1,6 @@
 {
-  "@bridgething/client": "^0.12.1",
-  "@bridgething/extension": "^0.12.1",
-  "@bridgething/source": "^0.12.1",
-  "libbridgething": "0.12.1"
+  "@bridgething/client": "^0.14.0",
+  "@bridgething/extension": "^0.14.0",
+  "@bridgething/source": "^0.15.0",
+  "libbridgething": "0.14.1"
 }