create-bridgething 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joey Eamigh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# create-bridgething
+
+Scaffold a new [bridgething](https://github.com/JoeyEamigh/bridgething) webapp, a
+single-page app that runs on the kiosk chromium of a Spotify Car Thing and talks
+to the on-device daemon. The template ships React + Vite + Tailwind v4 with
+[`@bridgething/client`](https://www.npmjs.com/package/@bridgething/client)
+preinstalled.
+
+```sh
+bun create bridgething my-app
+```
+
+```sh
+npm create bridgething@latest my-app
+```
+
+The generated project includes `bun run push` to deploy the built webapp to a
+connected Car Thing and `bun run share` to share it with the community.
+
+- Full docs: <https://bridgething.com/docs>
+- Source: <https://github.com/JoeyEamigh/bridgething>

package/dist/index.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { v7 } from "uuid";
+//#region src/index.ts
+//! `create-bridgething` - copy the bundled template into a new directory,
+//! 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");
+function parseArgs(argv) {
+	const positional = [];
+	let install = true;
+	let git = true;
+	for (const arg of argv) if (arg === "--no-install") install = false;
+	else if (arg === "--no-git") git = false;
+	else if (arg === "--help" || arg === "-h") {
+		printHelp();
+		process.exit(0);
+	} else if (arg.startsWith("-")) {
+		console.error(`unknown flag: ${arg}`);
+		printHelp();
+		process.exit(1);
+	} else positional.push(arg);
+	if (positional.length !== 1) {
+		printHelp();
+		process.exit(1);
+	}
+	return {
+		target: positional[0],
+		install,
+		git
+	};
+}
+function printHelp() {
+	console.log(`Usage: create-bridgething <target-dir> [--no-install] [--no-git]
+
+Scaffold a new bridgething webapp at <target-dir>.
+
+Options:
+  --no-install  Skip 'bun install' after copying.
+  --no-git      Skip 'git init' after copying.
+`);
+}
+const BINARY_EXT = new Set([
+	".ttf",
+	".otf",
+	".woff",
+	".woff2",
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".avif",
+	".ico",
+	".wasm"
+]);
+function copyTemplate(src, dest, subs) {
+	for (const entry of readdirSync(src)) {
+		const srcPath = join(src, entry);
+		const destPath = join(dest, entry === "_gitignore" ? ".gitignore" : entry === "_claude" ? ".claude" : entry);
+		if (statSync(srcPath).isDirectory()) {
+			mkdirSync(destPath, { recursive: true });
+			copyTemplate(srcPath, destPath, subs);
+		} else if (BINARY_EXT.has(extname(entry).toLowerCase())) copyFileSync(srcPath, destPath);
+		else writeFileSync(destPath, readFileSync(srcPath, "utf8").replace(/__PROJECT_NAME__/g, subs.projectName).replace(/__WEBAPP_UUID__/g, subs.webappUuid));
+	}
+}
+function copyDir(src, dest) {
+	mkdirSync(dest, { recursive: true });
+	for (const entry of readdirSync(src)) {
+		const srcPath = join(src, entry);
+		const destPath = join(dest, entry);
+		if (statSync(srcPath).isDirectory()) copyDir(srcPath, destPath);
+		else copyFileSync(srcPath, destPath);
+	}
+}
+function linkAgentAliases(target) {
+	try {
+		symlinkSync("CLAUDE.md", join(target, "AGENTS.md"));
+	} catch {
+		copyFileSync(join(target, "CLAUDE.md"), join(target, "AGENTS.md"));
+	}
+	mkdirSync(join(target, ".agents"), { recursive: true });
+	try {
+		symlinkSync(join("..", ".claude", "skills"), join(target, ".agents", "skills"), "dir");
+	} catch {
+		copyDir(join(target, ".claude", "skills"), join(target, ".agents", "skills"));
+	}
+}
+function run(cmd, args, cwd) {
+	return spawnSync(cmd, args, {
+		cwd,
+		stdio: "inherit"
+	}).status === 0;
+}
+function main() {
+	const args = parseArgs(process.argv.slice(2));
+	const target = resolve(process.cwd(), args.target);
+	const projectName = args.target.replace(/^.*[\\/]/, "");
+	if (existsSync(target)) {
+		if (readdirSync(target).length > 0) {
+			console.error(`error: ${target} exists and is not empty`);
+			process.exit(1);
+		}
+	} else mkdirSync(target, { recursive: true });
+	const webappUuid = v7();
+	console.log(`scaffolding ${projectName} (${webappUuid}) in ${target}`);
+	copyTemplate(TEMPLATE_DIR, target, {
+		projectName,
+		webappUuid
+	});
+	console.log("  ✓ template copied");
+	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");
+	else console.warn("  ! git init failed (skipping)");
+	if (args.install) {
+		console.log("  installing dependencies with bun...");
+		if (!run("bun", ["install"], target)) console.warn("  ! bun install failed; install manually with `bun install`");
+		else console.log("  ✓ dependencies installed");
+	}
+	console.log(`
+Done! Next steps:
+
+  cd ${args.target}
+${args.install ? "" : "  bun install\n"}  bun run dev          # local dev server (http://localhost:5173/)
+
+Open this folder with your coding agent (Claude Code, Codex, opencode, ...).
+It reads CLAUDE.md / AGENTS.md and the /bridgething skill in .claude/skills
+(mirrored at .agents/skills), which goes deep on the client API, running and
+driving the app, and installing and sharing it.
+
+  bun run build        # production bundle into dist/
+  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
+
+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.
+`);
+}
+main();
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "create-bridgething",
+  "version": "0.1.2",
+  "type": "module",
+  "description": "Scaffold a new bridgething webapp (React + Vite + Tailwind v4)",
+  "license": "MIT",
+  "author": "Joey Eamigh <55670930+JoeyEamigh@users.noreply.github.com> (https://github.com/JoeyEamigh)",
+  "homepage": "https://bridgething.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JoeyEamigh/bridgething.git",
+    "directory": "packages/create-bridgething"
+  },
+  "bugs": {
+    "url": "https://github.com/JoeyEamigh/bridgething/issues"
+  },
+  "keywords": ["bridgething", "spotify", "car-thing", "superbird", "create", "scaffold"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "create-bridgething": "./dist/index.mjs"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/uuid": "^11.0.0",
+    "tsdown": "^0.21.10"
+  },
+  "peerDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "uuid": "^14.0.0"
+  }
+}

package/template/CLAUDE.md

@@ -0,0 +1,87 @@
+# Building this bridgething webapp
+
+You are helping build a **bridgething webapp**: a single-page web UI for the
+Spotify Car Thing. It runs full-screen in a chromium kiosk on the device and
+talks to the on-device daemon over a local WebSocket using `@bridgething/client`.
+This file is always loaded; it holds the constraints. The `/bridgething` skill
+goes deep on the how-to: the client API, running and driving the app, and
+shipping it.
+
+## The device you are targeting
+
+- **Screen: 800x480, landscape.** Fixed. Design for exactly this. The window
+  never resizes; there is no responsive breakpoint to chase.
+- **One page.** The kiosk shows exactly one webapp at a time. In-app views are
+  fine, but there are no browser tabs, popups, or second windows.
+- **Physical controls arrive as ordinary browser events.** Listen with a
+  `keydown` handler and a `wheel` handler on `window`.
+  - Preset buttons **1 2 3 4** -> `keydown` key `"1"` `"2"` `"3"` `"4"`.
+  - **Mode** button -> `keydown` key `"m"`. (Pressing it 5 times fast is a
+    system gesture that jumps back to the launcher, so do not build anything
+    that depends on rapid repeated `m`.)
+  - **Back** button -> `keydown` key `"Escape"`.
+  - **Rotary wheel** -> horizontal scroll: `wheel` events with `deltaX`. This is
+    the primary way users move through lists; make horizontal wheel scroll work.
+  - **Touch** works normally (pointer/touch events).
+- **No keyboard, no mouse.** Those five controls plus touch are the whole input
+  surface. There is no text entry unless you build an on-screen one.
+
+## The SDK: `@bridgething/client`
+
+```ts
+import { BridgethingClient } from '@bridgething/client';
+const client = new BridgethingClient(); // auto-connects to the daemon, auto-reconnects
+```
+
+Construct it once and reuse it. It defaults to the on-device daemon; in dev you
+point it at your device with `VITE_BRIDGETHING_URL` (the starter `App.tsx`
+already does this). Do not hardcode a WebSocket URL.
+
+It is fully typed with a doc comment on every surface, method, and field. Read
+those declarations directly - you have no editor to hover in:
+
+- `node_modules/@bridgething/client/dist/dispatch.generated.d.ts` - every
+  `client.<surface>.<method>` and event, with docs.
+- `node_modules/@bridgething/lib/dist/bindings/*.d.ts` - the payload and reply
+  types (`PlayerState`, `MediaItem`, ...), with per-field docs.
+
+18 surfaces: `player asset config store capabilities library audio notifications
+phone geo net hardware bluetooth system time voice webapp forward`. Each method
+is one of three shapes:
+
+- **events**: `client.<s>.onXxx(handler)` returns an unsubscribe fn; or
+  `client.<s>.subscribe({ onXxx, ... })`.
+- **requests**: `await client.<s>.xxx(req)` returns `{ ok: true, response }` or
+  `{ ok: false, kind, error }` - always check `.ok`.
+- **commands**: `await client.<s>.xxx(payload)` returns `void` (fire-and-forget).
+
+Now-playing and library data come from the **connected phone's** Spotify. Assume
+a phone may not be connected: handle the empty/disconnected state gracefully (the
+starter shows a "connect a phone" placeholder). Fetch artwork by opaque asset id
+via `client.asset.get`; never build image URLs by hand.
+
+Run `/bridgething` for the cookbook, the dev loop, and shipping; grep the `.d.ts`
+files for a specific method or type.
+
+## `manifest.json` (in `public/`)
+
+- `id` - baked in at scaffold, unique to this project. **Never change it.**
+- `name`, `version`, `description`, `icon` - cosmetic / store metadata.
+- `config` - user-tunable settings (each becomes a `client.config` value).
+- `permissions` - capabilities you need (e.g. `net.fetch`, `net.proxy`, `geo`).
+- `art: { heroPx, thumbPx }` - the pixel sizes you want artwork delivered at.
+
+## Workflow
+
+- `bun run dev` - vite dev server. Iterate here. Use `/bridgething` for the loop
+  of seeing the screen and pressing the buttons.
+- `bun run build` - production bundle into `dist/`.
+- `bun run push` - build + install onto a connected Car Thing (see `/bridgething`).
+
+## Do not
+
+- Fight the 800x480 viewport or assume any other size.
+- Hardcode `ws://...`; use the SDK default + `VITE_BRIDGETHING_URL`.
+- Assume a phone is always connected.
+- Build image URLs by hand; fetch by opaque asset id.
+- Rely on rapid repeated `m` (system launcher gesture).

package/template/README.md

@@ -0,0 +1,54 @@
+# **PROJECT_NAME**
+
+A bridgething webapp scaffolded with `create-bridgething`.
+
+Stack: React 19 + Vite + Tailwind v4 + TypeScript strict, with
+[`@bridgething/client`](https://github.com/JoeyEamigh/bridgething) preinstalled.
+
+## Building with an agent
+
+Open this folder with your coding agent (Claude Code, Codex, opencode, ...). It
+reads `CLAUDE.md` / `AGENTS.md` and the `/bridgething` skill.
+
+## Develop
+
+```bash
+bun install
+bun run dev
+```
+
+Opens at http://localhost:5173/. The starter `App.tsx` connects to
+`ws://<host>/` (the daemon's local WebSocket on port 8891 of the device
+itself). To dev against a remote device, set:
+
+```bash
+VITE_BRIDGETHING_URL=ws://<device-ip>:8891/ bun run dev
+```
+
+## Push to a device
+
+```bash
+bun run push
+```
+
+`push` builds `dist/`, rsyncs it into `/var/bridgething/webapps/<manifest-id>/`
+on the Car Thing, and switches the kiosk to your app. Pass an IP address to target
+something other than `bridgething.local` over USB.
+
+## Share
+
+```bash
+bun run build
+bun run share
+```
+
+`share` writes `<name>-<version>.zip` from `dist/`. Anyone with a bridgething Car
+Thing installs it from the app.
+
+## Layout
+
+- `src/App.tsx` - starter UI: subscribes to `client.player.onSnapshot`,
+  fetches artwork via `client.asset.get`, exposes transport controls.
+- `src/index.css` - `@import "tailwindcss";`.
+- `vite.config.ts` - vite + tailwind plugin, `es2022` target.
+- `index.html` - 800x480 viewport, no overscroll, no tap highlight.

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

@@ -0,0 +1,24 @@
+---
+name: bridgething
+description: Build, run, and ship a bridgething webapp for the Spotify Car Thing. Covers @bridgething/client (the SDK a webapp uses to reach the on-device daemon - now-playing, artwork, storage, settings, networking, all 18 surfaces), the loop for running the app and driving its 800x480 screen and physical controls from a browser you control, and installing the built app onto a device or packaging it as a shareable zip. Use whenever calling the daemon, running or previewing the app, pressing its controls, or pushing it to hardware.
+---
+
+# Building a bridgething webapp
+
+A bridgething webapp is a single-page React UI that runs full-screen in the
+device's chromium kiosk and reaches the on-device daemon through one typed
+client. You build it against a browser on your own machine and push it to real
+hardware only for final checks.
+
+Three jobs. Read the reference file for the one in front of you:
+
+- **Call the daemon** - now-playing, transport, artwork, storage, settings,
+  networking, and the full 18-surface index: [reference/sdk.md](reference/sdk.md)
+- **Run and drive the app** - dev server, screenshot the 800x480 screen, press
+  the physical controls (locally, then over CDP on the device):
+  [reference/develop.md](reference/develop.md)
+- **Install and share** - build, push onto a connected Car Thing, package a zip
+  anyone can install: [reference/ship.md](reference/ship.md)
+
+The device shape, the control-to-event mapping, and the hard constraints live in
+CLAUDE.md, which is always loaded. This skill is the how-to on top of it.

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

@@ -0,0 +1,142 @@
+# Running and driving the app
+
+The device is an 800x480 landscape screen with five physical controls plus touch.
+To develop effectively you (1) run the app, (2) see it at the real size, and
+(3) press the buttons. The fast loop drives a browser you control on your own
+machine; you only need the physical Car Thing for final validation.
+
+## Contents
+
+- Start the dev server
+- Drive it with Playwright (recommended for agents)
+- Alternative: your own browser + DevTools
+- Drive the real device over CDP
+- Input reference
+
+## Start the dev server
+
+```bash
+bun run dev
+```
+
+Vite serves at `http://localhost:5173/` with hot reload.
+
+## Drive it with Playwright (recommended for agents)
+
+Playwright is **not** installed by default (a human clicking around does not need
+it). Add it only when you want to see and drive the app programmatically:
+
+```bash
+bun add -d playwright
+bunx playwright install chromium
+```
+
+Then a short script gives you a locked 800x480 window you can screenshot and send
+input to:
+
+```ts
+import { chromium } from 'playwright';
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 800, height: 480 } });
+await page.goto('http://localhost:5173/');
+
+await page.screenshot({ path: 'screen.png' }); // look at the result
+
+// physical controls -> the exact events the device sends:
+await page.keyboard.press('1');       // preset 1  (also '2' '3' '4')
+await page.keyboard.press('m');       // Mode button
+await page.keyboard.press('Escape');  // Back button
+await page.mouse.wheel(120, 0);       // rotary wheel: HORIZONTAL scroll (deltaX)
+// touch: page.tap('selector')  or  page.mouse.click(x, y)
+```
+
+Loop: edit code -> vite hot-reloads -> screenshot -> adjust. Keep the viewport at
+exactly `{ width: 800, height: 480 }` so what you see matches the device.
+
+## Alternative: your own browser + DevTools
+
+Open `http://localhost:5173/` in your normal browser, then in DevTools' device
+toolbar set a custom device of **800 x 480**. You get real DevTools plus the same
+keys (type `1`-`4`, `m`, `Escape`; shift+wheel for the rotary's horizontal
+scroll). This is the recommended manual path.
+
+## Drive the real device over CDP
+
+To see and drive the app on real hardware, talk CDP to the device's own chromium.
+CDP input goes straight into the page (never through the physical buttons), so the
+launcher gesture and on-device browser-nav side effects never interfere.
+
+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):
+
+```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
+```
+
+**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:
+
+```ts
+// drive.ts  ->  run with: bun drive.ts
+const targets = (await fetch('http://localhost:9223/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) => {
+  ws.onopen = () => res();
+  setTimeout(() => rej(new Error('ws open timeout')), 8000);
+});
+
+let id = 0;
+const pending = new Map<number, (v: any) => void>();
+ws.onmessage = ev => {
+  const m = JSON.parse(ev.data as string);
+  if (m.id && pending.has(m.id)) (pending.get(m.id)!(m.result), pending.delete(m.id));
+};
+const send = (method: string, params: any = {}) =>
+  new Promise<any>(res => (pending.set(++id, res), ws.send(JSON.stringify({ id, method, params }))));
+
+// screenshot
+const { data } = await send('Page.captureScreenshot', { format: 'png' });
+await Bun.write('device.png', Buffer.from(data, 'base64'));
+
+// read what is on screen (great for asserting a change happened)
+const text = await send('Runtime.evaluate', { expression: 'document.body.innerText', returnByValue: true });
+console.log(text.result.value);
+
+// press a button: keyDown + keyUp. key/code/text must match a real key.
+const key = (type: string, k: string, code: string, vk: number) =>
+  send('Input.dispatchKeyEvent', { type, key: k, code, text: k.length === 1 ? k : '', windowsVirtualKeyCode: vk });
+await key('keyDown', '3', 'Digit3', 51);   // preset 3
+await key('keyUp', '3', 'Digit3', 51);
+
+// rotary wheel = horizontal scroll:
+await send('Input.dispatchMouseEvent', { type: 'mouseWheel', x: 400, y: 240, deltaX: 120, deltaY: 0 });
+
+process.exit(0);
+```
+
+Read the screenshot and the `innerText` to confirm the app reacted. Prefer the
+local loop for fast iteration; use the device to confirm real behavior (real
+now-playing, real artwork, the actual screen).
+
+## Input reference
+
+The controls arrive as ordinary browser events. Listen for them with a `keydown`
+handler and a `wheel` handler on `window`. Make horizontal wheel scroll move
+through your primary list; it is the control users reach for first.
+
+| Control      | Browser event                        | CDP `key`/`code`/vk    |
+| ------------ | ------------------------------------ | ---------------------- |
+| Preset 1-4   | `keydown` key `"1"` `"2"` `"3"` `"4"` | `Digit1`-`Digit4` / 49-52 |
+| Mode (M)     | `keydown` key `"m"`                  | `KeyM` / 77            |
+| Back         | `keydown` key `"Escape"`             | `Escape` / 27          |
+| Rotary wheel | `wheel` with `deltaX` (horizontal)   | mouseWheel `deltaX`    |
+| Touch        | pointer / touch events               | `Input.dispatchTouchEvent` |