create-bridgething 0.1.2

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

@@ -0,0 +1,180 @@
+# The webapp SDK (`@bridgething/client`)
+
+A webapp reaches the daemon only through this one client: a typed facade over a
+local WebSocket. You never open sockets or build wire messages yourself.
+
+## Contents
+
+- Read the types (the `.d.ts` files are the source of truth)
+- Connect
+- The three call shapes (events / requests / commands)
+- Cookbook (player, asset, store, config, net, library)
+- Full surface index (all 18)
+- Gotchas
+
+## Read the types
+
+You have no editor to hover in, so read the shipped declarations directly. Every
+method, event, and field carries a doc comment.
+
+- `node_modules/@bridgething/client/dist/dispatch.generated.d.ts` - every
+  `client.<surface>` method and event, with argument and return types.
+- `node_modules/@bridgething/lib/dist/bindings/*.d.ts` - the payload and reply
+  types (`PlayerState`, `MediaItem`, `NowPlayingUpdate`, `AssetGot`, ...) with
+  per-field docs. `client.d.ts` is the webapp surface; `shared.ts` holds the
+  shared data types.
+
+Useful greps:
+
+```bash
+grep -n 'class PlayerSurface' -A40 node_modules/@bridgething/client/dist/dispatch.generated.d.ts
+grep -n 'export type PlayerState ' -A12 node_modules/@bridgething/lib/dist/bindings/shared.ts
+```
+
+The `.d.ts` is the source of truth; this file is the map.
+
+## Connect
+
+```ts
+import { BridgethingClient } from '@bridgething/client';
+
+const client = new BridgethingClient();          // on device: talks to the local daemon
+// dev against a real device from your laptop:
+const client = new BridgethingClient({ url: import.meta.env.VITE_BRIDGETHING_URL });
+```
+
+Construct once and reuse (a `useMemo` in React). It auto-connects and
+auto-reconnects. Watch the link with `client.on(e => ...)` (`e.type` is
+`open` / `close` / `connecting` / `message`) and read `client.connectionState`
+(`'connecting' | 'open' | 'closing' | 'closed'`). The daemon is always the sole
+peer; you never address anything.
+
+## The three call shapes
+
+Every surface method is one of three shapes. Learn these and the whole SDK reads
+the same way.
+
+**1. Events** - the daemon pushes; you subscribe. `onXxx` returns an unsubscribe
+function (call it in cleanup). Or `subscribe({...})` for several at once.
+
+```ts
+const off = client.player.onSnapshot(reply => setState(reply.state));
+// ...later
+off();
+```
+
+**2. Requests** - you ask, the daemon answers. Returns a tagged result; always
+check `.ok`.
+
+```ts
+const res = await client.player.stateGet();
+if (res.ok) console.log(res.response.state);
+else console.warn(res.kind, res.error); // kind: 'domain' | 'protocol'
+```
+
+**3. Commands** - fire-and-forget. Returns `Promise<void>`; it resolves when the
+daemon has taken the message, not when the phone finished acting.
+
+```ts
+await client.player.skipNext();
+```
+
+## Cookbook
+
+**Now playing + transport (`client.player`)**
+
+```ts
+client.player.onSnapshot(r => setState(r.state)); // full PlayerState on every material change
+client.player.stateGet().then(r => r.ok && setState(r.response.state)); // prime on mount
+
+// PlayerState: { track?: MediaItem, playback: Playback, queue, options, context? }
+// track.title / track.artist / track.album / track.artworkId / track.durationMs
+// playback.state: 'stopped' | 'paused' | 'playing'; playback.positionMs; playback.shuffle
+
+client.player.play({ uri: 'spotify:track:...' });
+client.player.pause(); client.player.resume(); client.player.skipNext();
+client.player.skipPrev({ allowSeeking: true });   // true = restart if progressed
+client.player.seekTo({ positionMs: 30_000 });
+client.player.setShuffle({ on: true });
+client.player.setRepeat({ mode: 'all' });          // 'off' | 'all' | 'one'
+```
+
+Smooth progress: `onSnapshot` fires on material changes (track change, play/pause,
+seek), NOT every second. Extrapolate the playhead locally from `playback.state`
+and `positionMs` between snapshots.
+
+**Artwork and images (`client.asset`)**
+
+Player state gives opaque asset ids, never URLs. Fetch bytes and wrap a blob:
+
+```ts
+const res = await client.asset.get({ id: track.artworkId, requestId: crypto.randomUUID() });
+if (res.ok) {
+  const bytes = new Uint8Array(res.response.bytes as unknown as number[]);
+  const url = URL.createObjectURL(new Blob([bytes], { type: res.response.mime ?? 'image/jpeg' }));
+  // set <img src={url}>, and URL.revokeObjectURL(url) on cleanup
+}
+```
+
+**Persistence (`client.store`)** - per-webapp key/value that survives restarts:
+
+```ts
+await client.store.put({ key: 'theme', value: 'dark' });
+const r = await client.store.get({ key: 'theme' });   // r.ok && r.response.value
+await client.store.delete({ key: 'theme' });
+```
+
+**User settings (`client.config`)** - values you declare in `manifest.json`; the
+user edits them in the companion app, your side is read-only:
+
+```ts
+client.config.onChanged(c => applySetting(c.key, c.value));
+const r = await client.config.get({ key: 'units' });
+const all = await client.config.list();
+```
+
+**Internet through the phone (`client.net`)** - the device has no direct network;
+`net.fetch` / websockets / a SOCKS proxy all tunnel through the phone. Needs the
+matching `permissions` entry in `manifest.json` (`net.fetch`, `net.ws`,
+`net.proxy`). Read the `NetSurface` block in the `.d.ts` for the request shapes.
+
+**Library + search (`client.library`)** - `browse`, `search`, `recommendations`,
+`favoritesList`/`favoritesContains` (requests), `favoritesToggle`/`favoritesSet`
+(commands), `onFavoriteChanged` (event). All Spotify-backed.
+
+## Full surface index
+
+18 surfaces on `client.<name>`. Read each surface's class in
+`dispatch.generated.d.ts` for its exact methods and types.
+
+| Surface | What it does | Notable methods |
+| --- | --- | --- |
+| `player` | now-playing + transport | onSnapshot, stateGet, play, pause, resume, skipNext, skipPrev, seekTo, setShuffle, setRepeat, queueGet |
+| `asset` | fetch blobs by opaque id | get, preload, onReady/onCleared |
+| `store` | per-webapp key/value | get, put, delete |
+| `config` | user settings from the manifest | get, list, onChanged |
+| `capabilities` | which gateway features are live | get, onSnapshot |
+| `library` | Spotify browse/search/favorites | browse, search, recommendations, favoritesList/Contains/Toggle/Set, onFavoriteChanged |
+| `audio` | volume, mute, TTS, earcons | volumeUp/Down, setVolume, muteToggle, tts, earcon |
+| `notifications` | phone notification actions | invokePositive/Negative, onPosted/Removed/Updated |
+| `phone` | call control (Android; iOS uses iAP2) | stateGet, accept, end, initiate, mute, dtmf, onCallStarted/Updated/Ended |
+| `geo` | location watches (phone-sourced) | watch, unwatch, getOnce, onPosition |
+| `net` | HTTP / WS / SOCKS via the phone | fetch, wsOpen/wsSend/wsClose, streamOpen/streamCancel |
+| `hardware` | backlight + ambient light sensor | displaySetMode, displaySetLevel, stateGet, onAmbientLightUpdate, onBrightnessChanged |
+| `bluetooth` | adapter alias/bonds/discoverable | list, connect, forget, setAlias, enableDiscoverable |
+| `system` | version, logs, power, diagnostics | versionRequest, logsTail/Subscribe, reboot, powerOff, factoryReset, onVersion, onLogEntry, onOta* |
+| `time` | wall clock (device has no RTC) | get, onSnapshot, onChanged |
+| `voice` | mic / push-to-talk (capability-gated) | pushToTalk, cancel, muteMic, stateGet |
+| `webapp` | launcher: list/activate installed apps | list, current, activate, icon |
+| `forward` | arbitrary passthrough to the companion | text, json, binary, onText/onJson/onBinary |
+
+## Gotchas
+
+- Always check `.ok` on request results; the daemon can answer with a domain or
+  protocol error (e.g. `player.play` with a uri no gateway claims).
+- Assume no phone: player, library, net all depend on the connected companion.
+  Render an empty/placeholder state, do not throw.
+- `config` is read-only from the webapp; only the companion writes it.
+- Asset ids are opaque - never parse or construct them, never build image URLs.
+- Some surfaces are capability-gated or platform-specific (e.g. `voice`, and
+  `phone` on iOS). Check `client.capabilities` and handle absence.

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

@@ -0,0 +1,37 @@
+# Installing and sharing the app
+
+Two outputs: install onto your own connected device, and a zip anyone can install
+through the bridgething companion app.
+
+## Install onto a connected Car Thing
+
+```bash
+bun run push            # targets bridgething.local (device over USB)
+bun run push <address>  # or an explicit host / IP
+```
+
+`push` builds `dist/` itself, rsyncs it to the device, then tells the daemon to
+switch the kiosk to your app - one command, no separate build step. The device
+must be reachable: connected over USB it answers to `bridgething.local`;
+otherwise pass its address. If multiple devices are on the network, set
+`SUPERBIRD_HOST=bridgething-<serial>.local`.
+
+Flags: `--skip-build` reuses the existing `dist/`; `--no-switch` copies without
+activating. Iterating on hardware, rerun `bun run push` after each change. For
+the fast edit loop, drive a local browser instead (see the develop reference) and
+save the device for final checks.
+
+## Make a shareable zip
+
+```bash
+bun run build   # share does NOT build; produce dist/ first
+bun run share   # writes <name>-<version>.zip from dist/
+```
+
+Send that zip to anyone with a bridgething-flashed Car Thing. They install it
+from the bridgething companion app (no rebuild, no dev tools). The zip is just
+your built bundle with `manifest.json` at its root.
+
+Bump `version` in `public/manifest.json` before sharing an update, so people can
+tell builds apart. Never touch `manifest.json`'s `id` - it is the webapp's
+identity and the install path on the device.

package/template/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.DS_Store
+*.log
+.env*

package/template/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" class="bg-black text-white">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=800, height=480, initial-scale=1.0, user-scalable=no, viewport-fit=cover" />
+    <meta name="theme-color" content="#000000" />
+    <title>__PROJECT_NAME__</title>
+  </head>
+  <body class="m-0 h-screen w-screen overflow-hidden touch-none select-none antialiased">
+    <div id="root" class="h-full w-full"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "__PROJECT_NAME__",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "push": "bun scripts/push.ts",
+    "share": "bun scripts/share.ts"
+  },
+  "dependencies": {
+    "@bridgething/client": "^0.1.2",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@msgpack/msgpack": "^3.1.3",
+    "@tailwindcss/vite": "^4.1.16",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "fflate": "^0.8.2",
+    "tailwindcss": "^4.1.16",
+    "typescript": "^6.0.3",
+    "vite": "^7.1.13"
+  }
+}

package/template/public/manifest.json

@@ -0,0 +1,9 @@
+{
+  "id": "__WEBAPP_UUID__",
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "description": "",
+  "config": [],
+  "permissions": [],
+  "art": { "heroPx": 248, "thumbPx": 96 }
+}

package/template/scripts/push.ts

@@ -0,0 +1,289 @@
+#!/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.
+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';
+
+function parseUuid(s: string): Uint8Array {
+  const hex = s.replace(/-/g, '').toLowerCase();
+  if (hex.length !== 32 || !/^[0-9a-f]+$/.test(hex)) {
+    throw new Error(`invalid uuid: ${s}`);
+  }
+  const out = new Uint8Array(16);
+  for (let i = 0; i < 16; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+function freshMsgId(): Uint8Array {
+  return parseUuid(randomUUID());
+}
+
+function uuidToString(bytes: Uint8Array): string {
+  const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+const FRAME_HEADER_LENGTH = 16;
+const FRAME_MAGIC = 0xdead;
+const FRAME_VERSION = 2;
+const COMPRESSION_NONE = 0x00;
+const ENCODING_MSGPACK = 0x00;
+const PRIORITY_NORMAL = 0x00;
+
+function writeFrameHeader(payloadLength: number): Uint8Array<ArrayBuffer> {
+  const buf = new Uint8Array(FRAME_HEADER_LENGTH);
+  const view = new DataView(buf.buffer);
+  view.setUint16(0, FRAME_MAGIC, false);
+  view.setUint8(2, FRAME_VERSION);
+  view.setUint8(3, COMPRESSION_NONE);
+  view.setUint8(4, ENCODING_MSGPACK);
+  view.setUint8(5, PRIORITY_NORMAL);
+  view.setBigUint64(8, BigInt(payloadLength), false);
+  return buf;
+}
+
+function frame(message: unknown): Uint8Array<ArrayBuffer> {
+  const body = msgpackEncode(message);
+  const header = writeFrameHeader(body.length);
+  const out = new Uint8Array(header.length + body.length);
+  out.set(header, 0);
+  out.set(body, header.length);
+  return out;
+}
+
+type GatewayMsg = { id: Uint8Array; meta: unknown; data: unknown };
+
+class FrameAccumulator {
+  private buffer = new Uint8Array(0);
+
+  append(chunk: Uint8Array): void {
+    if (chunk.length === 0) return;
+    const merged = new Uint8Array(this.buffer.length + chunk.length);
+    merged.set(this.buffer, 0);
+    merged.set(chunk, this.buffer.length);
+    this.buffer = merged;
+  }
+
+  next(): GatewayMsg | null {
+    if (this.buffer.length < FRAME_HEADER_LENGTH) return null;
+    const view = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength);
+    const magic = view.getUint16(0, false);
+    if (magic !== FRAME_MAGIC) throw new Error(`bad framing magic 0x${magic.toString(16)}`);
+    const version = view.getUint8(2);
+    if (version !== FRAME_VERSION) throw new Error(`unsupported frame version ${version}`);
+    const compression = view.getUint8(3);
+    if (compression !== COMPRESSION_NONE) {
+      throw new Error(`unsupported inbound compression ${compression} (this script only handles uncompressed)`);
+    }
+    const encoding = view.getUint8(4);
+    if (encoding !== ENCODING_MSGPACK) throw new Error(`unsupported inbound encoding ${encoding}`);
+    const len = Number(view.getBigUint64(8, false));
+    const total = FRAME_HEADER_LENGTH + len;
+    if (this.buffer.length < total) return null;
+    const body = this.buffer.subarray(FRAME_HEADER_LENGTH, total);
+    const decoded = msgpackDecode(body) as GatewayMsg;
+    this.buffer = this.buffer.slice(total);
+    return decoded;
+  }
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+type SwitchOutcome =
+  | { ok: true; activeId: Uint8Array | null; activeName: string | null }
+  | { ok: false; reason: string };
+
+async function sendSwitchTo(host: string, port: number, manifestId: string): Promise<SwitchOutcome> {
+  const url = `ws://${host}:${port}/`;
+  console.log(`gateway ${url}`);
+  const ws = new WebSocket(url);
+  ws.binaryType = 'arraybuffer';
+  const acc = new FrameAccumulator();
+
+  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) => {
+    const overall = setTimeout(() => {
+      try {
+        ws.close();
+      } catch {}
+      rej(new Error('gateway switch timed out (15s)'));
+    }, 15_000);
+
+    ws.addEventListener('open', () => {
+      ws.send(frame(announce));
+      ws.send(frame(switchMsg));
+      switchSent = true;
+    });
+
+    ws.addEventListener('message', (event: MessageEvent) => {
+      const data = event.data;
+      const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data instanceof Uint8Array ? data : null;
+      if (!bytes) return;
+      try {
+        acc.append(bytes);
+        let msg = acc.next();
+        while (msg !== null) {
+          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;
+            }
+          }
+          msg = acc.next();
+        }
+      } catch (err) {
+        clearTimeout(overall);
+        try {
+          ws.close();
+        } catch {}
+        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 });
+        return;
+      }
+      rej(new Error(`gateway ws closed before response (code ${event.code})`));
+    });
+  });
+}
+
+function interpretSwitchResponse(data: unknown): SwitchOutcome {
+  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 === '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 ?? {})}` };
+  }
+  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}`);
+  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}`))));
+    child.on('error', rej);
+  });
+}
+
+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);
+  });
+}
+
+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;
+  }
+  const port = Number(process.env.BRIDGETHING_GATEWAY_PORT ?? 8892);
+
+  const repoDir = resolve(import.meta.dir, '..');
+  const distDir = resolve(repoDir, 'dist');
+  const manifestPath = resolve(distDir, 'manifest.json');
+
+  if (!skipBuild) await buildBundle(repoDir);
+
+  if (!existsSync(manifestPath)) {
+    throw new Error(`no manifest.json at ${manifestPath}; run 'bun run build' first or drop --skip-build`);
+  }
+  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 (!switchAfter) {
+    console.log('skipping switch (--no-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}`);
+}
+
+main().catch(err => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/template/scripts/share.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env bun
+import { zipSync } from 'fflate';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+const repoDir = resolve(import.meta.dir, '..');
+const distDir = resolve(repoDir, 'dist');
+const manifestPath = join(distDir, 'manifest.json');
+
+if (!existsSync(manifestPath)) {
+  console.error(`no manifest.json at ${manifestPath}; run 'bun run build' first`);
+  process.exit(1);
+}
+
+const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as { name?: string; version?: string };
+const name = (manifest.name || 'webapp').replace(/[^a-z0-9._-]+/gi, '-');
+const version = manifest.version || '0.0.0';
+
+const files: Record<string, Uint8Array> = {};
+function walk(dir: string): void {
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry);
+    if (statSync(abs).isDirectory()) walk(abs);
+    else files[relative(distDir, abs)] = new Uint8Array(readFileSync(abs));
+  }
+}
+walk(distDir);
+
+const outPath = resolve(repoDir, `${name}-${version}.zip`);
+writeFileSync(outPath, zipSync(files, { level: 9 }));
+console.log(`wrote ${relative(process.cwd(), outPath)} (${Object.keys(files).length} files)`);
+console.log('share it: anyone with a bridgething Car Thing installs it from the companion app');