create-bridgething 0.5.2 → 0.7.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { v7 } from "uuid";
@@ -9,13 +9,37 @@ import { v7 } from "uuid";
 //! substitute the project name, print next steps. Opinionated stack:
 //! React 19 + Vite + Tailwind v4 + TypeScript strict, plus
 //! `@bridgething/client` preinstalled.
-const TEMPLATE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "template");
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = resolve(__dirname, "..", "template");
+const VARIANTS = {
+	app: { summary: "webapp" },
+	launcher: {
+		dir: "template-launcher",
+		manifest: {
+			role: "launcher",
+			description: "A custom home screen."
+		},
+		summary: "launcher (a replacement home screen)"
+	},
+	overlay: {
+		dir: "template-overlay",
+		manifest: {
+			overlay: "overlay.js",
+			description: "A custom system overlay."
+		},
+		scripts: { build: "vite build && vite build -c vite.settings.config.ts && vite build -c vite.overlay.config.ts" },
+		summary: "overlay (system UI drawn over every webapp)"
+	}
+};
 function parseArgs(argv) {
 	const positional = [];
 	let install = true;
 	let git = true;
+	let variant = "app";
 	for (const arg of argv) if (arg === "--no-install") install = false;
 	else if (arg === "--no-git") git = false;
+	else if (arg === "--launcher") variant = "launcher";
+	else if (arg === "--overlay") variant = "overlay";
 	else if (arg === "--help" || arg === "-h") {
 		printHelp();
 		process.exit(0);
@@ -31,19 +55,52 @@ function parseArgs(argv) {
 	return {
 		target: positional[0],
 		install,
-		git
+		git,
+		variant
 	};
 }
 function printHelp() {
-	console.log(`Usage: create-bridgething <target-dir> [--no-install] [--no-git]
+	console.log(`Usage: create-bridgething <target-dir> [--launcher | --overlay] [--no-install] [--no-git]
 
 Scaffold a new bridgething webapp at <target-dir>.
 
+Variants:
+  (default)     A normal webapp.
+  --launcher    A home screen. Declares 'role: launcher' and can take the
+                device's launcher slot, replacing the built-in hub.
+  --overlay     A system overlay. Ships an 'overlay.js' the daemon injects
+                into every webapp, replacing the built-in one.
+
 Options:
   --no-install  Skip 'bun install' after copying.
   --no-git      Skip 'git init' after copying.
 `);
 }
+function patchJson(path, patch) {
+	const parsed = JSON.parse(readFileSync(path, "utf8"));
+	writeFileSync(path, `${JSON.stringify({
+		...parsed,
+		...patch
+	}, null, 2)}\n`);
+}
+function applyVariant(target, variant, subs) {
+	const spec = VARIANTS[variant];
+	if (spec.dir) copyTemplate(resolve(__dirname, "..", spec.dir), target, subs);
+	const appendPath = join(target, "_claude_append.md");
+	if (existsSync(appendPath)) {
+		const claudePath = join(target, "CLAUDE.md");
+		writeFileSync(claudePath, readFileSync(claudePath, "utf8") + readFileSync(appendPath, "utf8"));
+		rmSync(appendPath);
+	}
+	if (spec.manifest) patchJson(join(target, "public", "manifest.json"), spec.manifest);
+	if (spec.scripts) {
+		const pkgPath = join(target, "package.json");
+		patchJson(pkgPath, { scripts: {
+			...JSON.parse(readFileSync(pkgPath, "utf8")).scripts,
+			...spec.scripts
+		} });
+	}
+}
 const BINARY_EXT = new Set([
 	".ttf",
 	".otf",
@@ -108,12 +165,14 @@ function main() {
 		}
 	} else mkdirSync(target, { recursive: true });
 	const webappUuid = v7();
-	console.log(`scaffolding ${projectName} (${webappUuid}) in ${target}`);
-	copyTemplate(TEMPLATE_DIR, target, {
+	const subs = {
 		projectName,
 		webappUuid
-	});
-	console.log("  ✓ template copied");
+	};
+	console.log(`scaffolding ${projectName} (${webappUuid}) in ${target}`);
+	copyTemplate(TEMPLATE_DIR, target, subs);
+	applyVariant(target, args.variant, subs);
+	console.log(`  ✓ template copied (${VARIANTS[args.variant].summary})`);
 	linkAgentAliases(target);
 	console.log("  ✓ agent guides linked (CLAUDE.md, AGENTS.md, /bridgething skill)");
 	if (args.git) if (run("git", ["init", "--quiet"], target)) console.log("  ✓ git initialized");
@@ -138,7 +197,12 @@ driving the app, and installing and sharing it.
   bun run push <addr>  # build + install onto a connected Car Thing (default bridgething.local)
   bun run share        # build first, then zip dist/ to hand to friends
   bun run update       # bring the connected Car Thing to the latest bridgething release
-
+${args.variant === "app" ? "" : `
+'bun run push' also claims the device's ${args.variant} slot, so this is live the
+moment it lands. 'bun run push --release' hands the slot back to the built-in
+${args.variant === "launcher" ? "hub" : "overlay"}, which is how you recover if a build of this wedges the screen.
+The companion phone app can do the same thing.
+`}
 The starter App connects to ws://127.0.0.1:8891/ on the device, and to
 ws://<device-ip>:8891/ in dev when you set VITE_BRIDGETHING_URL.
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bridgething",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "type": "module",
   "description": "Scaffold a new bridgething webapp (React + Vite + Tailwind v4)",
   "license": "MIT",
@@ -24,9 +24,12 @@
   },
   "files": [
     "dist",
-    "template"
+    "template",
+    "template-launcher",
+    "template-overlay"
   ],
   "scripts": {
+    "prebuild": "bun scripts/sync-push.ts",
     "build": "tsdown",
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit"

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

@@ -68,25 +68,26 @@ CDP input goes straight into the page (never through the physical buttons), so t
 launcher gesture and on-device browser-nav side effects never interfere.
 
 Install the app onto the device first so the kiosk is showing it (build + push).
-Then tunnel the device's CDP port to your machine (it is bound to `127.0.0.1` and
-chromium refuses to bind it to anything routable, so a tunnel is mandatory):
+CDP is served at `bridgething.local:9222`, reachable directly over USB:
 
 ```bash
 # device answers at bridgething.local over USB; root has no password
-ssh -o StrictHostKeyChecking=no -fN -L 9223:127.0.0.1:9223 root@bridgething.local
-curl -s http://localhost:9223/json/version >/dev/null && echo tunnel-up
+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.
+
 **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, not the tunnel: a plain websocket connects fine over the same tunnel).
-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:
+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:
 
 ```ts
 // drive.ts  ->  run with: bun drive.ts
-const targets = (await fetch('http://localhost:9223/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) => {

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

@@ -21,6 +21,13 @@ 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.
 
+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.
+
 ## Make a shareable zip
 
 ```bash

package/template/package.json

@@ -12,7 +12,7 @@
     "update": "bunx @bridgething/updater"
   },
   "dependencies": {
-    "@bridgething/client": "^0.5.2",
+    "@bridgething/client": "^0.7.0",
     "preact": "^10.29.7",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"

package/template/scripts/push.ts

@@ -1,12 +1,14 @@
 #!/usr/bin/env bun
-// Build this webapp and install it onto a connected Car Thing: rsync dist/ to
-// the device, then tell the daemon to switch the kiosk to it. You own this
-// script; tweak it freely.
+// Build this webapp and install it onto a connected Car Thing, then make it
+// visible: a plain app becomes active, a launcher takes the home-screen slot,
+// an overlay takes the overlay slot. Run with --help for the flags.
+//
+// Generated from @bridgething/webapp-shared. It is yours now; tweak it freely.
 import { decode as msgpackDecode, encode as msgpackEncode } from '@msgpack/msgpack';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 
 function parseUuid(s: string): Uint8Array {
   const hex = s.replace(/-/g, '').toLowerCase();
@@ -27,6 +29,12 @@ function uuidToString(bytes: Uint8Array): string {
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
 
+function bundleDirName(id: string): string {
+  const hex = id.replace(/-/g, '').toLowerCase();
+  if (!/^[0-9a-f]{32}$/.test(hex)) throw new Error(`manifest id is not a uuid: ${id}`);
+  return hex;
+}
+
 const FRAME_HEADER_LENGTH = 16;
 const FRAME_MAGIC = 0xdead;
 const FRAME_VERSION = 2;
@@ -98,107 +106,82 @@ function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
   return diff === 0;
 }
 
-type SwitchOutcome =
-  | { ok: true; activeId: Uint8Array | null; activeName: string | null }
-  | { ok: false; reason: string };
+const ANNOUNCE_DATA = {
+  type: 'capabilities',
+  data: {
+    event: 'announce',
+    data: {
+      gateway: {
+        address: '',
+        name: 'bridgething-webapp-push',
+        osName: 'host',
+        appName: 'bridgething-webapp-push',
+        appVersion: '0.1.0',
+        adapterVersion: 'host',
+        libVersion: 'v0',
+        libbridgethingVersion: 'v0',
+      },
+      uriSchemes: [],
+      network: { kind: 'unknown', metered: false },
+      available: { geo: false, notifications: false, netFetch: false, netWs: false, audioTts: false },
+      audio: { earcons: [], voices: [] },
+    },
+  },
+};
 
-async function sendSwitchTo(host: string, port: number, manifestId: string): Promise<SwitchOutcome> {
+function sendRequest(host: string, port: number, data: unknown): Promise<unknown | null> {
   const url = `ws://${host}:${port}/`;
-  console.log(`gateway ${url}`);
   const ws = new WebSocket(url);
   ws.binaryType = 'arraybuffer';
   const acc = new FrameAccumulator();
+  const requestId = freshMsgId();
+  let sent = false;
 
-  const announce: GatewayMsg = {
-    id: freshMsgId(),
-    meta: { kind: 'event' },
-    data: {
-      type: 'capabilities',
-      data: {
-        event: 'announce',
-        data: {
-          gateway: {
-            address: '',
-            name: 'bridgething-webapp-push',
-            osName: 'host',
-            appName: 'bridgething-webapp-push',
-            appVersion: '0.1.0',
-            adapterVersion: 'host',
-            libVersion: 'v0',
-            libbridgethingVersion: 'v0',
-          },
-          uriSchemes: [],
-          network: { kind: 'unknown', metered: false },
-          available: { geo: false, notifications: false, netFetch: false, netWs: false, audioTts: false },
-          audio: { earcons: [], voices: [] },
-        },
-      },
-    },
-  };
-
-  const switchRequestId = freshMsgId();
-  const switchMsg: GatewayMsg = {
-    id: switchRequestId,
-    meta: { kind: 'request' },
-    data: {
-      type: 'webapp',
-      data: { event: 'switchTo', data: { id: parseUuid(manifestId) } },
-    },
-  };
-
-  let switchSent = false;
-
-  return await new Promise<SwitchOutcome>((res, rej) => {
+  return new Promise<unknown | null>((res, rej) => {
     const overall = setTimeout(() => {
       try {
         ws.close();
       } catch {}
-      rej(new Error('gateway switch timed out (15s)'));
+      rej(new Error(`gateway request timed out (15s) against ${url}`));
     }, 15_000);
 
+    const finish = (fn: () => void) => {
+      clearTimeout(overall);
+      try {
+        ws.close();
+      } catch {}
+      fn();
+    };
+
     ws.addEventListener('open', () => {
-      ws.send(frame(announce));
-      ws.send(frame(switchMsg));
-      switchSent = true;
+      ws.send(frame({ id: freshMsgId(), meta: { kind: 'event' }, data: ANNOUNCE_DATA }));
+      ws.send(frame({ id: requestId, meta: { kind: 'request' }, data }));
+      sent = true;
     });
 
     ws.addEventListener('message', (event: MessageEvent) => {
-      const data = event.data;
-      const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data instanceof Uint8Array ? data : null;
+      const raw = event.data;
+      const bytes = raw instanceof ArrayBuffer ? new Uint8Array(raw) : raw instanceof Uint8Array ? raw : null;
       if (!bytes) return;
       try {
         acc.append(bytes);
-        let msg = acc.next();
-        while (msg !== null) {
+        for (let msg = acc.next(); msg !== null; msg = acc.next()) {
           const meta = msg.meta as { kind?: string; data?: { requestId?: Uint8Array } };
-          if (meta?.kind === 'response') {
-            const respId = meta.data?.requestId;
-            if (respId && bytesEqual(respId, switchRequestId)) {
-              clearTimeout(overall);
-              try {
-                ws.close();
-              } catch {}
-              res(interpretSwitchResponse(msg.data));
-              return;
-            }
+          const respId = meta?.kind === 'response' ? meta.data?.requestId : undefined;
+          if (respId && bytesEqual(respId, requestId)) {
+            finish(() => res(msg.data));
+            return;
           }
-          msg = acc.next();
         }
       } catch (err) {
-        clearTimeout(overall);
-        try {
-          ws.close();
-        } catch {}
-        rej(err instanceof Error ? err : new Error(String(err)));
+        finish(() => rej(err instanceof Error ? err : new Error(String(err))));
       }
     });
 
     ws.addEventListener('close', (event: CloseEvent) => {
       clearTimeout(overall);
-      // the daemon activates the webapp and then drops this ephemeral connection;
-      // a clean close after the switch was sent means it took, ack or not.
-      if (switchSent && (event.code === 1000 || event.code === 1005)) {
-        res({ ok: true, activeId: null, activeName: null });
+      if (sent && (event.code === 1000 || event.code === 1005)) {
+        res(null);
         return;
       }
       rej(new Error(`gateway ws closed before response (code ${event.code})`));
@@ -206,84 +189,202 @@ async function sendSwitchTo(host: string, port: number, manifestId: string): Pro
   });
 }
 
-function interpretSwitchResponse(data: unknown): SwitchOutcome {
+type Outcome<T> = { ok: true; value: T | null } | { ok: false; reason: string };
+
+function interpret<T>(data: unknown | null, expected: string): Outcome<T> {
+  if (data === null) return { ok: true, value: null };
   const outer = data as { type?: string; data?: unknown };
   if (outer?.type !== 'webapp') {
     return { ok: false, reason: `unexpected response type ${JSON.stringify(outer?.type)}` };
   }
   const inner = outer.data as { event?: string; data?: unknown };
-  if (inner?.event === 'switched') {
-    const active = inner.data as { id?: Uint8Array | null; name?: string | null } | null;
-    return { ok: true, activeId: active?.id ?? null, activeName: active?.name ?? null };
-  }
+  if (inner?.event === expected) return { ok: true, value: inner.data as T };
   if (inner?.event === 'webappError') {
-    const errVariant = inner.data as { type?: string; data?: { id?: string; reason?: string } } | undefined;
-    return { ok: false, reason: `daemon refused: ${errVariant?.type} ${JSON.stringify(errVariant?.data ?? {})}` };
+    const err = inner.data as { type?: string; data?: Record<string, unknown> } | undefined;
+    return { ok: false, reason: `daemon refused: ${err?.type} ${JSON.stringify(err?.data ?? {})}` };
   }
   return { ok: false, reason: `unexpected webapp response variant ${JSON.stringify(inner?.event)}` };
 }
 
-function rsync(localDir: string, host: string, remoteName: string): Promise<void> {
-  const sshArgs = 'ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o LogLevel=ERROR';
-  const src = localDir.endsWith('/') ? localDir : `${localDir}/`;
-  const dest = `root@${host}:/var/bridgething/webapps/${remoteName}/`;
-  console.log(`rsync ${src} -> ${dest}`);
+type ActiveWebapp = { id?: Uint8Array | null; name?: string | null };
+type Slots = { launcher?: Uint8Array | null; overlay?: Uint8Array | null };
+type Slot = 'launcher' | 'overlay';
+
+async function switchTo(host: string, port: number, id: string): Promise<Outcome<ActiveWebapp>> {
+  const data = { type: 'webapp', data: { event: 'switchTo', data: { id: parseUuid(id) } } };
+  return interpret<ActiveWebapp>(await sendRequest(host, port, data), 'switched');
+}
+
+async function setSlot(host: string, port: number, slot: Slot, id: string | null): Promise<Outcome<Slots>> {
+  const data = {
+    type: 'webapp',
+    data: { event: 'setSlot', data: { slot, id: id === null ? null : parseUuid(id) } },
+  };
+  return interpret<Slots>(await sendRequest(host, port, data), 'slots');
+}
+
+const WEBAPP_ROOT = '/var/bridgething/webapps';
+const SSH_OPTS = ['-o', 'UserKnownHostsFile=/dev/null', '-o', 'StrictHostKeyChecking=no', '-o', 'LogLevel=ERROR'];
+
+function run(cmd: string, args: string[], label: string, cwd?: string): Promise<void> {
   return new Promise<void>((res, rej) => {
-    const child = spawn('rsync', ['-avz', '--delete', '-e', sshArgs, src, dest], { stdio: 'inherit' });
-    child.on('exit', code => (code === 0 ? res() : rej(new Error(`rsync exited ${code}`))));
+    const child = spawn(cmd, args, { stdio: 'inherit', cwd });
+    child.on('exit', code => (code === 0 ? res() : rej(new Error(`${label} exited ${code}`))));
     child.on('error', rej);
   });
 }
 
+async function pushBundle(localDir: string, host: string, dirName: string): Promise<void> {
+  const src = localDir.endsWith('/') ? localDir : `${localDir}/`;
+  const staged = `.push.${dirName}`;
+  const dest = `root@${host}:${WEBAPP_ROOT}/${staged}/`;
+  console.log(`rsync ${src} -> root@${host}:${WEBAPP_ROOT}/${dirName}/`);
+  await run('rsync', ['-avz', '--delete', '-e', ['ssh', ...SSH_OPTS].join(' '), src, dest], 'rsync');
+  const swap = [
+    'set -e',
+    `cd ${WEBAPP_ROOT}`,
+    `rm -rf .old.${dirName}`,
+    `if [ -d ${dirName} ]; then mv ${dirName} .old.${dirName}; fi`,
+    `mv ${staged} ${dirName}`,
+    `rm -rf .old.${dirName}`,
+  ].join('; ');
+  await run('ssh', [...SSH_OPTS, `root@${host}`, swap], 'ssh');
+}
+
 function buildBundle(repoDir: string): Promise<void> {
   console.log('bun run build');
-  return new Promise<void>((res, rej) => {
-    const child = spawn('bun', ['run', 'build'], { cwd: repoDir, stdio: 'inherit' });
-    child.on('exit', code => (code === 0 ? res() : rej(new Error(`bun run build exited ${code}`))));
-    child.on('error', rej);
-  });
+  return run('bun', ['run', 'build'], 'bun run build', repoDir);
 }
 
-async function main(): Promise<void> {
-  const args = process.argv.slice(2);
-  let skipBuild = process.env.SKIP_BUILD === '1';
-  let switchAfter = true;
-  let host = process.env.SUPERBIRD_HOST ?? 'bridgething.local';
-  for (const arg of args) {
-    if (arg === '--skip-build') skipBuild = true;
-    else if (arg === '--no-switch') switchAfter = false;
-    else if (arg.startsWith('--')) throw new Error(`unknown flag: ${arg}`);
-    else host = arg;
+type Manifest = { id?: string; name?: string; role?: string; overlay?: string };
+
+function declaredSlots(manifest: Manifest): Slot[] {
+  const slots: Slot[] = [];
+  if (manifest.role === 'launcher') slots.push('launcher');
+  if (manifest.overlay) slots.push('overlay');
+  return slots;
+}
+
+type Args = {
+  host: string;
+  port: number;
+  skipBuild: boolean;
+  claimSlots: boolean;
+  release: boolean;
+  switchAfter: boolean | null;
+};
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    host: process.env.SUPERBIRD_HOST ?? 'bridgething.local',
+    port: Number(process.env.BRIDGETHING_GATEWAY_PORT ?? 8892),
+    skipBuild: process.env.SKIP_BUILD === '1',
+    claimSlots: true,
+    release: false,
+    switchAfter: null,
+  };
+  for (const arg of argv) {
+    if (arg === '--skip-build') args.skipBuild = true;
+    else if (arg === '--no-switch') args.switchAfter = false;
+    else if (arg === '--switch') args.switchAfter = true;
+    else if (arg === '--no-slot') args.claimSlots = false;
+    else if (arg === '--release') args.release = true;
+    else if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    } else if (arg.startsWith('--')) throw new Error(`unknown flag: ${arg}`);
+    else args.host = arg;
   }
-  const port = Number(process.env.BRIDGETHING_GATEWAY_PORT ?? 8892);
+  return args;
+}
+
+function printHelp(): void {
+  console.log(`Usage: bun run push [host] [options]
+
+Build, rsync dist/ onto a connected Car Thing, and make it visible.
+
+A plain webapp becomes the active app. A launcher also takes the home-screen
+slot; an overlay takes the overlay slot and the daemon reloads the kiosk so it
+is injected into whatever app is showing. Overlay-only bundles are not switched
+to by default, since switching away is the opposite of what you want to test.
 
-  const repoDir = resolve(import.meta.dir, '..');
+Options:
+  --release      hand this bundle's slots back to the built-in ones and stop.
+                 the recovery path when a build wedges the screen.
+  --no-slot      push without claiming any slot.
+  --switch       switch to this bundle even if it is overlay-only.
+  --no-switch    push without switching.
+  --skip-build   rsync whatever is already in dist/.
+
+Env: SUPERBIRD_HOST, BRIDGETHING_GATEWAY_PORT, SKIP_BUILD=1
+`);
+}
+
+export type BridgethingPushOptions = {
+  scriptUrl: string;
+};
+
+export async function bridgethingPush({ scriptUrl }: BridgethingPushOptions): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  const repoDir = resolve(dirname(new URL(scriptUrl).pathname), '..');
   const distDir = resolve(repoDir, 'dist');
   const manifestPath = resolve(distDir, 'manifest.json');
 
-  if (!skipBuild) await buildBundle(repoDir);
+  const readManifest = (): Manifest => {
+    if (!existsSync(manifestPath)) {
+      throw new Error(`no manifest.json at ${manifestPath}; run 'bun run build' first or drop --skip-build`);
+    }
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8')) as Manifest;
+    if (!parsed.id) throw new Error(`${manifestPath} has no 'id' field`);
+    return parsed;
+  };
 
-  if (!existsSync(manifestPath)) {
-    throw new Error(`no manifest.json at ${manifestPath}; run 'bun run build' first or drop --skip-build`);
+  if (args.release) {
+    const manifest = readManifest();
+    for (const slot of declaredSlots(manifest)) {
+      const result = await setSlot(args.host, args.port, slot, null);
+      if (!result.ok) throw new Error(result.reason);
+      console.log(`${slot} slot: reverted to the built-in one`);
+    }
+    if (declaredSlots(manifest).length === 0) console.log('this bundle declares no slots; nothing to release');
+    return;
   }
-  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as { id?: string };
-  if (!manifest.id) throw new Error(`${manifestPath} has no 'id' field`);
 
-  const remoteName = process.env.BRIDGETHING_BUNDLE_NAME ?? manifest.id;
-  await rsync(distDir, host, remoteName);
+  if (!args.skipBuild) await buildBundle(repoDir);
+  const manifest = readManifest();
+  const id = manifest.id as string;
+  const slots = declaredSlots(manifest);
+
+  await pushBundle(distDir, args.host, bundleDirName(id));
 
-  if (!switchAfter) {
-    console.log('skipping switch (--no-switch)');
+  if (args.claimSlots) {
+    for (const slot of slots) {
+      const result = await setSlot(args.host, args.port, slot, id);
+      if (!result.ok) throw new Error(result.reason);
+      console.log(`${slot} slot: ${manifest.name ?? id}`);
+    }
+  }
+
+  const overlayOnly = slots.length > 0 && slots.every(s => s === 'overlay');
+  const shouldSwitch = args.switchAfter ?? !overlayOnly;
+  if (!shouldSwitch) {
+    console.log(overlayOnly ? 'overlay pushed; the kiosk reloaded with it injected' : 'skipping switch');
     return;
   }
 
-  const outcome = await sendSwitchTo(host, port, manifest.id);
-  if (!outcome.ok) throw new Error(outcome.reason);
-  const activeStr = outcome.activeId ? uuidToString(outcome.activeId) : '(none)';
-  console.log(`active webapp: ${outcome.activeName ?? '(unnamed)'} ${activeStr}`);
+  const switched = await switchTo(args.host, args.port, id);
+  if (!switched.ok) throw new Error(switched.reason);
+  const active = switched.value;
+  if (!active) {
+    console.log('switched (the daemon dropped the push connection reloading the kiosk)');
+    return;
+  }
+  const activeStr = active.id ? uuidToString(active.id) : '(none)';
+  console.log(`active webapp: ${active.name ?? '(unnamed)'} ${activeStr}`);
 }
 
-main().catch(err => {
+bridgethingPush({ scriptUrl: import.meta.url }).catch(err => {
   console.error(err instanceof Error ? err.message : err);
   process.exit(1);
 });

package/template-launcher/_claude_append.md

@@ -0,0 +1,40 @@
+
+## This project is a launcher
+
+`manifest.json` declares `"role": "launcher"`, which means two things:
+
+- The daemon hides this bundle from `client.webapp.list`, so a launcher never
+  lists itself in its own grid.
+- The bundle is eligible for the device's **launcher slot**. Holding that slot
+  makes this the home screen: the boot default, the target of the Mode-button
+  gesture, and what the back button returns to.
+
+`bun run push` claims the slot and switches to it, so a push puts you straight
+on the home screen. `bun run push --release` hands it back, and the companion
+phone app can do the same. The built-in hub stays installed and can never be
+uninstalled, so releasing the slot always gets the stock home screen back. That
+is the recovery path if a launcher you are building wedges the device.
+
+### What a home screen is expected to do
+
+Nothing is enforced. The daemon does not require a launcher to implement any
+particular surface; if yours does less than the built-in hub, that is a choice,
+not an error, and the user can switch back. The built-in hub covers:
+
+- the app grid (`client.webapp.list` / `.icon` / `.activate` / `.current`, plus
+  the `onWebappInstalled` / `onWebappUninstalled` events so the grid stays live)
+- bluetooth settings: bonds, adapter alias, discoverable
+- display brightness
+- system info and health
+- power: restart, shut down, factory reset
+- OTA progress (`client.system.onOtaProgress` / `.onOtaError`)
+
+The starter here implements only the grid. Read the built-in hub's source if you
+want a reference for the rest; everything it uses is on the public client SDK.
+
+### Onboarding is not your problem
+
+The first-boot pairing wizard lives in the built-in hub. A phone must already be
+paired before anyone can install your launcher, so by the time this runs, the
+device is set up. A factory reset clears the launcher slot along with everything
+else, which puts the built-in hub and its wizard back.

package/template-launcher/src/App.tsx

@@ -0,0 +1,98 @@
+import { BridgethingClient, type WebappInfo } from '@bridgething/client';
+import { useEffect, useMemo, useState } from 'react';
+
+const wsUrl =
+  import.meta.env.VITE_BRIDGETHING_URL ??
+  (typeof window !== 'undefined' ? `ws://${window.location.host}/` : 'ws://127.0.0.1:8891/');
+
+type Entry = {
+  info: WebappInfo;
+  iconUrl: string | null;
+};
+
+export default function App() {
+  const client = useMemo(() => new BridgethingClient({ url: wsUrl }), []);
+  const [entries, setEntries] = useState<Entry[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [activating, setActivating] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    const revoke: string[] = [];
+
+    const load = async () => {
+      const [list, current] = await Promise.all([client.webapp.list(), client.webapp.current()]);
+      if (!list.ok) {
+        setError('failed to list webapps');
+        return;
+      }
+      const selfId = current.ok ? current.response.id : null;
+      const visible = list.response.webapps.filter(w => w.id !== selfId);
+      const loaded = await Promise.all(
+        visible.map(async (info): Promise<Entry> => {
+          if (!info.iconHash) return { info, iconUrl: null };
+          const icon = await client.webapp.icon({ id: info.id });
+          if (!icon.ok) return { info, iconUrl: null };
+          const bytes = new Uint8Array(icon.response.bytes as unknown as number[]);
+          const url = URL.createObjectURL(
+            new Blob([bytes], { type: icon.response.mime ?? 'application/octet-stream' }),
+          );
+          revoke.push(url);
+          return { info, iconUrl: url };
+        }),
+      );
+      if (!cancelled) setEntries(loaded);
+    };
+
+    load().catch(err => setError(err instanceof Error ? err.message : String(err)));
+
+    const offInstalled = client.webapp.onWebappInstalled(() => void load());
+    const offUninstalled = client.webapp.onWebappUninstalled(() => void load());
+
+    return () => {
+      cancelled = true;
+      offInstalled();
+      offUninstalled();
+      for (const url of revoke) URL.revokeObjectURL(url);
+    };
+  }, [client]);
+
+  const activate = async (id: string) => {
+    if (activating) return;
+    setActivating(id);
+    const result = await client.webapp.activate({ id });
+    if (!result.ok) setActivating(null);
+  };
+
+  if (error) return <Centered>{error}</Centered>;
+  if (!entries) return <Centered>loading</Centered>;
+  if (entries.length === 0) return <Centered>no apps installed</Centered>;
+
+  return (
+    <div className="h-full w-full overflow-y-auto p-6">
+      <div className="grid grid-cols-4 gap-4">
+        {entries.map(({ info, iconUrl }) => (
+          <button
+            key={info.id}
+            type="button"
+            disabled={activating !== null}
+            onClick={() => activate(info.id)}
+            className="flex flex-col items-center gap-2 p-3 disabled:opacity-50">
+            <div className="grid h-20 w-20 place-items-center border">
+              {iconUrl ? (
+                <img src={iconUrl} alt="" className="h-full w-full object-contain" draggable={false} />
+              ) : (
+                <span className="text-2xl">{(info.name.trim().charAt(0) || '?').toUpperCase()}</span>
+              )}
+            </div>
+            <span className="text-center text-sm">{info.name}</span>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function Centered({ children }: { children: React.ReactNode }) {
+  return <div className="grid h-full w-full place-items-center text-sm">{children}</div>;
+}

package/template-overlay/_claude_append.md

@@ -0,0 +1,64 @@
+
+## This project is a system overlay
+
+`manifest.json` declares `"overlay": "overlay.js"`. When this bundle holds the
+device's **overlay slot**, the daemon injects that file into every webapp's
+document as it loads. The page in `src/` is incidental: it only renders if
+someone launches this bundle from the hub.
+
+`bun run push` claims the slot for you and reloads the kiosk, so the overlay
+appears over whatever app is showing. It deliberately does **not** switch to
+this bundle's own page - switching away from the app you are testing against is
+the opposite of what you want.
+
+`bun run push --release` hands the slot back to the daemon's built-in overlay.
+That is the recovery path when a build of yours misbehaves; the companion phone
+app can do the same thing.
+
+### The contract
+
+The daemon prepends one global before your bundle:
+
+```js
+window.__bridgethingOverlay = { origin: 'http://127.0.0.1:8891', surfaces: {...} };
+```
+
+- **`surfaces`** is the active webapp's declared profile: `notifications`,
+  `call`, `pairing`, `connection`, `volume`. An app that draws its own volume
+  indicator declares `volume: false`. **Honor these.** The daemon cannot enforce
+  it, and ignoring them means the user sees two of everything on apps that draw
+  their own. If every surface is off, the daemon injects nothing at all.
+- **`origin`** is the kiosk origin. Check `location.origin` against it before
+  mounting so the bundle never runs in a page the daemon did not serve.
+
+Everything else comes from `@bridgething/client` over the local websocket, the
+same SDK a normal webapp uses.
+
+### Constraints that are not style
+
+`overlay.js` must be **one self-contained file** under 512 KiB. It is injected as
+a script string into another app's document, so it cannot import a module graph,
+fetch assets, or reach a bundler at runtime. `vite.overlay.config.ts` builds it
+as a single inlined iife; keep it that way.
+
+That is a constraint on the *output*, not on how you write it. Style
+`overlay/main.tsx` with tailwind classes exactly like the rest of the project.
+`overlay/style.css` is a real stylesheet; it is imported with vite's `?inline`
+so the compiled css lands in the bundle as a string and gets mounted into the
+shadow root. Add `@theme` tokens or plain rules there. Because the shadow root
+is closed, tailwind is told not to scan the project (`source(none)`) and only
+generates what `overlay/main.tsx` uses - if you split the overlay across more
+files, add each one with `@source`.
+
+The starter encodes four things you should not drop:
+
+1. **Origin guard** before mounting.
+2. **`__bridgethingOverlayMounted`** guard, so a double injection is a no-op.
+3. **Closed shadow root**, so your styles and the host app's cannot reach each
+   other.
+4. **Escape-only, capture-phase key handling**, and only while something is
+   showing. Your overlay sits on top of every app on the device; swallowing keys
+   broadly breaks all of them.
+
+You are running inside someone else's page. A crash, a fullscreen paint, or a
+greedy key handler takes down every webapp, not just this one.

package/template-overlay/overlay/main.tsx

@@ -0,0 +1,228 @@
+import type { BluetoothPin, Notification, PeerSnapshotMap, PhoneCall, VolumeChanged } from '@bridgething/client';
+import { BridgethingClient } from '@bridgething/client';
+import { render } from 'preact';
+import { useEffect, useState } from 'preact/hooks';
+
+import css from './style.css?inline';
+
+type OverlaySurfaces = {
+  notifications: boolean;
+  call: boolean;
+  pairing: boolean;
+  connection: boolean;
+  volume: boolean;
+};
+
+type OverlayConfig = { origin: string; surfaces: OverlaySurfaces };
+
+declare global {
+  interface Window {
+    __bridgethingOverlay?: OverlayConfig;
+    __bridgethingOverlayMounted?: boolean;
+  }
+}
+
+const TOAST_TTL_MS = 5_000;
+const VOLUME_TTL_MS = 1_500;
+const CONNECTION_SHOW_DELAY_MS = 3_000;
+
+function useLatest<T>(
+  subscribe: (emit: (value: T | null) => void) => () => void,
+  ttl?: number,
+  deps: unknown[] = [],
+): T | null {
+  const [value, setValue] = useState<T | null>(null);
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const off = subscribe(next => {
+      clearTimeout(timer);
+      setValue(next);
+      if (next !== null && ttl !== undefined) timer = setTimeout(() => setValue(null), ttl);
+    });
+    return () => {
+      clearTimeout(timer);
+      off();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+  return value;
+}
+
+const CHIP = 'absolute left-1/2 -translate-x-1/2 rounded-full bg-chip px-4 py-2 text-sm text-white';
+
+function ConnectionBanner({ client }: { client: BridgethingClient }) {
+  const [away, setAway] = useState(false);
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const off = client.peer.onSnapshot((snapshot: PeerSnapshotMap) => {
+      const peers = Object.values(snapshot);
+      const paired = peers.some(p => p.paired);
+      const useful = peers.some(p => p.iap2 === 'identified' || p.companion.type === 'connected');
+      if (paired && !useful) {
+        timer ??= setTimeout(() => setAway(true), CONNECTION_SHOW_DELAY_MS);
+      } else {
+        clearTimeout(timer);
+        timer = undefined;
+        setAway(false);
+      }
+    });
+    return () => {
+      clearTimeout(timer);
+      off();
+    };
+  }, [client]);
+
+  if (!away) return null;
+  return <div class={`${CHIP} top-3`}>phone disconnected</div>;
+}
+
+function CallBanner({ client, onDismissible }: { client: BridgethingClient; onDismissible: Dismissible }) {
+  const [call, setCall] = useState<PhoneCall | null>(null);
+
+  useEffect(() => {
+    const offs = [
+      client.phone.onCallStarted(setCall),
+      client.phone.onCallUpdated(next => setCall(prev => (prev === null || prev.callId === next.callId ? next : prev))),
+      client.phone.onCallEnded(ended => setCall(prev => (prev?.callId === ended.callId ? null : prev))),
+    ];
+    return () => offs.forEach(off => off());
+  }, [client]);
+
+  useEffect(() => (call ? onDismissible(() => setCall(null)) : undefined), [call, onDismissible]);
+
+  if (!call) return null;
+  return (
+    <div class={`${CHIP} top-3`}>
+      {call.displayName || call.remoteId || 'unknown caller'} - {call.status}
+    </div>
+  );
+}
+
+function Toasts({ client }: { client: BridgethingClient }) {
+  const [live, setLive] = useState<Notification[]>([]);
+
+  useEffect(() => {
+    const timers = new Map<string, ReturnType<typeof setTimeout>>();
+    const drop = (id: string) => {
+      clearTimeout(timers.get(id));
+      timers.delete(id);
+      setLive(prev => prev.filter(n => n.id !== id));
+    };
+    const post = (n: Notification) => {
+      if (n.flags.silent) return;
+      clearTimeout(timers.get(n.id));
+      timers.set(
+        n.id,
+        setTimeout(() => drop(n.id), TOAST_TTL_MS),
+      );
+      setLive(prev => [...prev.filter(other => other.id !== n.id), n]);
+    };
+    const offs = [
+      client.notifications.onPosted(post),
+      client.notifications.onUpdated(post),
+      client.notifications.onRemoved(removed => drop(removed.id)),
+    ];
+    return () => {
+      timers.forEach(clearTimeout);
+      offs.forEach(off => off());
+    };
+  }, [client]);
+
+  return (
+    <div class="absolute top-0 right-0 flex flex-col items-end gap-3 p-3">
+      {live.map(n => (
+        <div key={n.id} class="w-65 rounded-xl bg-card px-3 py-2.5 text-white">
+          <div class="text-[11px] opacity-60">{n.app.displayName ?? n.app.bundleId}</div>
+          <div class="text-sm font-semibold">{n.title ?? ''}</div>
+          {(n.message ?? n.subtitle) ? <div class="text-xs opacity-80">{n.message ?? n.subtitle}</div> : null}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function PairingModal({ client, onDismissible }: { client: BridgethingClient; onDismissible: Dismissible }) {
+  const [pin, setPin] = useState<BluetoothPin | null>(null);
+
+  useEffect(() => {
+    const offs = [client.bluetooth.onPin(setPin), client.bluetooth.onPairingResult(() => setPin(null))];
+    return () => offs.forEach(off => off());
+  }, [client]);
+
+  useEffect(() => (pin ? onDismissible(() => setPin(null)) : undefined), [pin, onDismissible]);
+
+  if (!pin) return null;
+  return (
+    <div class="pointer-events-auto absolute inset-0 grid place-items-center bg-scrim text-center text-white">
+      <div>
+        <div class="text-[13px] opacity-70">enter this pin on your phone</div>
+        <div class="my-3 text-5xl font-bold tracking-[0.1em]">{pin.pin}</div>
+        <div class="text-xs opacity-60">{pin.name || pin.mac}</div>
+      </div>
+    </div>
+  );
+}
+
+function VolumeChip({ client }: { client: BridgethingClient }) {
+  const volume = useLatest<VolumeChanged>(emit => client.audio.onVolumeChanged(emit), VOLUME_TTL_MS, [client]);
+  if (!volume) return null;
+  const percent = Math.round(Math.min(1, Math.max(0, volume.level)) * 100);
+  return <div class={`${CHIP} bottom-6`}>{volume.muted ? 'muted' : `${percent}%`}</div>;
+}
+
+type Dismissible = (hide: () => void) => () => void;
+
+function Overlay({ cfg, client }: { cfg: OverlayConfig; client: BridgethingClient }) {
+  const [stack] = useState<Array<() => void>>([]);
+  useEffect(() => {
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape' || stack.length === 0) return;
+      event.stopPropagation();
+      event.preventDefault();
+      stack.pop()?.();
+    };
+    document.addEventListener('keydown', onKey, { capture: true });
+    return () => document.removeEventListener('keydown', onKey, { capture: true });
+  }, [stack]);
+
+  const dismissible: Dismissible = hide => {
+    stack.push(hide);
+    return () => {
+      const at = stack.indexOf(hide);
+      if (at >= 0) stack.splice(at, 1);
+    };
+  };
+
+  return (
+    <>
+      <style>{css}</style>
+      <div class="absolute inset-0 font-sans">
+        {cfg.surfaces.connection && <ConnectionBanner client={client} />}
+        {cfg.surfaces.call && <CallBanner client={client} onDismissible={dismissible} />}
+        {cfg.surfaces.notifications && <Toasts client={client} />}
+        {cfg.surfaces.volume && <VolumeChip client={client} />}
+        {cfg.surfaces.pairing && <PairingModal client={client} onDismissible={dismissible} />}
+      </div>
+    </>
+  );
+}
+
+function boot() {
+  const cfg = window.__bridgethingOverlay;
+  if (!cfg || !location.origin.startsWith(cfg.origin)) return;
+  if (window.__bridgethingOverlayMounted) return;
+  window.__bridgethingOverlayMounted = true;
+
+  const mount = () => {
+    const host = document.createElement('div');
+    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);
+  };
+
+  if (document.body) mount();
+  else document.addEventListener('DOMContentLoaded', mount, { once: true });
+}
+
+boot();

package/template-overlay/overlay/style.css

@@ -0,0 +1,8 @@
+@import 'tailwindcss' source(none);
+@source './main.tsx';
+
+@theme {
+  --color-scrim: rgb(0 0 0 / 0.85);
+  --color-chip: rgb(0 0 0 / 0.75);
+  --color-card: rgb(0 0 0 / 0.8);
+}

package/template-overlay/src/App.tsx

@@ -0,0 +1,12 @@
+export default function App() {
+  return (
+    <div className="grid h-full w-full place-items-center p-12 text-center">
+      <div className="flex flex-col gap-3">
+        <div className="text-2xl font-semibold">__PROJECT_NAME__</div>
+        <div className="text-sm opacity-70">
+          A system overlay. Assign it to the overlay slot from the companion app to see it.
+        </div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,44 @@
+import preact from '@preact/preset-vite';
+import tailwindcss from '@tailwindcss/vite';
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { defineConfig, type Plugin } from 'vite';
+
+const WARN_BYTES = 128 * 1024;
+const HARD_CAP = '512 KiB';
+
+function sizeGuard(): Plugin {
+  return {
+    name: 'overlay-size-guard',
+    closeBundle() {
+      let bytes: number;
+      try {
+        bytes = statSync(resolve(__dirname, 'dist', 'overlay.js')).size;
+      } catch {
+        return;
+      }
+      if (bytes > WARN_BYTES) {
+        console.warn(`overlay.js is ${(bytes / 1024).toFixed(1)} KiB; the daemon ignores overlays over ${HARD_CAP}.`);
+      }
+    },
+  };
+}
+
+export default defineConfig({
+  plugins: [preact(), tailwindcss(), sizeGuard()],
+  build: {
+    target: 'es2022',
+    outDir: resolve(__dirname, 'dist'),
+    emptyOutDir: false,
+    cssCodeSplit: false,
+    lib: {
+      entry: resolve(__dirname, 'overlay', 'main.tsx'),
+      formats: ['iife'],
+      name: '__overlay',
+      fileName: () => 'overlay.js',
+    },
+    rollupOptions: {
+      output: { inlineDynamicImports: true },
+    },
+  },
+});