create-bridgething 0.11.0 → 0.12.1

package/template/tsconfig.json

@@ -18,5 +18,5 @@
     "verbatimModuleSyntax": true,
     "useDefineForClassFields": true
   },
-  "include": ["src"]
+  "include": ["src", "settings", "extension"]
 }

package/template/vite.config.ts

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

package/template/vite.settings.config.ts

@@ -26,14 +26,14 @@ function sizeGuard(): Plugin {
             '',
             '========================================================================',
             `  settings.html is ${kib} KiB.`,
-            `  the companion hard-rejects settings pages over ${HARD_CAP} at install.`,
-            '  trim dependencies or inline assets before this page stops installing.',
+            `  the device refuses to install a bundle whose settings page is over ${HARD_CAP}.`,
+            '  trim dependencies or inline assets; the whole install fails, not just this page.',
             '========================================================================',
             '',
           ].join('\n'),
         );
       } else if (bytes > WARN_BYTES) {
-        console.warn(`settings.html is ${kib} KiB; keep it lean (install hard cap is ${HARD_CAP}).`);
+        console.warn(`settings.html is ${kib} KiB; keep it lean (install fails over ${HARD_CAP}).`);
       }
     },
   };

package/template-extension/_claude_append.md

@@ -0,0 +1,23 @@
+## This project ships a native extension
+
+`manifest.json` declares an `extension` block, so this bundle has two halves.
+
+- `src/` is the webapp, running in the device's chromium kiosk.
+- `extension/` is a Deno process on the desktop. The bridgething desktop app
+  spawns it while the app is installed and enabled, with or without a Car Thing
+  connected.
+
+The two halves talk over the daemon's forward surface: `client.forward` in the
+webapp, `device.send` and `ctx.on('message', ...)` in the extension. The daemon
+delivers a forward while this webapp is the active one on that device.
+
+Host access belongs in the extension, an ordinary Deno program with `npm:`,
+`jsr:`, and `node:` available. Keep `src/` a view over what it sends. The webapp
+also runs with nothing attached, so check `capabilities.available.forward` and
+give the user something useful when it is false.
+
+`manifest.json` starts with `"permissions": ["all"]`. Narrow it to the Deno
+permissions you use before you publish.
+
+The `ctx` contract, the permission grammar, the dev loop, and the gotchas:
+`.claude/skills/bridgething/reference/extension.md`.

package/template-extension/extension/main.ts

@@ -0,0 +1,20 @@
+import { asJson, defineExtension, json } from '@bridgething/extension';
+
+defineExtension({
+  start(ctx) {
+    ctx.log.info(`__PROJECT_NAME__ extension up, data in ${ctx.dataDir}`);
+
+    ctx.on('device', event => {
+      if (event.type !== 'connected') return;
+      const greeting = ctx.config(event.device).greeting ?? 'hello';
+      ctx.log.info(`${event.device.name} connected; greeting is "${greeting}"`);
+      event.device.send(json({ type: 'greeting', text: greeting }));
+    });
+
+    ctx.on('message', (device, message) => {
+      const payload = asJson<Record<string, unknown>>(message);
+      if (!payload) return;
+      device.send(json({ type: 'echo', payload }));
+    });
+  },
+});

package/template-launcher/_claude_append.md

@@ -1,40 +1,24 @@
-
 ## 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.
+`manifest.json` declares `"role": "launcher"`. The daemon keeps this bundle out
+of `client.webapp.list`, so the grid you draw excludes itself. Holding the
+device's launcher slot makes it the home screen: the boot default, the target of
+the Mode gesture, and where 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.
+`bun run push` claims the slot and switches to it. `bun run push --release` hands
+it back to the built-in hub, the recovery path when a build wedges the device.
 
-### What a home screen is expected to do
+### What a home screen covers
 
-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:
+A launcher implements as much or as little as you want. 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
+- the app grid (`client.webapp.list`, `.icon`, `.activate`, `.current`, plus
+  `onWebappInstalled` and `onWebappUninstalled`)
+- bluetooth 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
+- OTA progress (`client.system.onOtaProgress` and `.onOtaError`)
 
-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.
+The starter here draws the grid. Everything the hub uses is on the public client
+SDK.

package/template-launcher/src/App.tsx

@@ -1,9 +1,6 @@
 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/');
+import { daemonUrl } from './daemon';
 
 type Entry = {
   info: WebappInfo;
@@ -11,7 +8,7 @@ type Entry = {
 };
 
 export default function App() {
-  const client = useMemo(() => new BridgethingClient({ url: wsUrl }), []);
+  const client = useMemo(() => new BridgethingClient({ url: daemonUrl() }), []);
   const [entries, setEntries] = useState<Entry[] | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [activating, setActivating] = useState<string | null>(null);

package/template-overlay/_claude_append.md

@@ -1,19 +1,13 @@
-
 ## 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.
+`manifest.json` declares `"overlay": "overlay.js"`. While 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/` renders when someone launches this bundle from
+the hub.
 
-`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.
+`bun run push` claims the overlay slot and reloads the kiosk, so the overlay
+appears over the webapp that is showing. `bun run push --release` hands the slot
+back to the built-in overlay, the recovery path when a build misbehaves.
 
 ### The contract
 
@@ -23,42 +17,34 @@ The daemon prepends one global before your bundle:
 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.
+`surfaces` is the active webapp's declared profile, a boolean each for
+`notifications`, `call`, `pairing`, `connection`, `volume`, and `voice`. Render
+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.
 
-Everything else comes from `@bridgething/client` over the local websocket, the
-same SDK a normal webapp uses.
+`origin` is the kiosk origin. Compare `location.origin` against it before
+mounting. Everything else comes from `@bridgething/client` over the local
+websocket.
 
-### Constraints that are not style
+### Output constraints
 
-`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.
+`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.
 
-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`.
+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
+into the shadow root as a string. Tailwind scans only `overlay/main.tsx`
+(`source(none)`), so add an `@source` line for every file you split across.
 
-The starter encodes four things you should not drop:
+### Keep these four from the starter
 
-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.
+1. The origin guard before mounting.
+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
+   showing.
 
-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.
+You run inside every webapp's page. A crash, a fullscreen paint, or a broad key
+handler takes down all of them.

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

@@ -18,7 +18,7 @@ function sizeGuard(): Plugin {
         return;
       }
       if (bytes > WARN_BYTES) {
-        console.warn(`overlay.js is ${(bytes / 1024).toFixed(1)} KiB; the daemon ignores overlays over ${HARD_CAP}.`);
+        console.warn(`overlay.js is ${(bytes / 1024).toFixed(1)} KiB; install fails over ${HARD_CAP}.`);
       }
     },
   };

package/template-source/CLAUDE.md

@@ -0,0 +1,104 @@
+# Building bridgething webapps in this repo
+
+This repo is a bun workspace of webapps for the Spotify Car Thing, plus the pipeline that publishes them as a `catalog.v1` source on GitHub Pages. Each `apps/<slug>` is one webapp: a single page running full-screen in the chromium kiosk on the device, reaching the on-device daemon through `@bridgething/client`.
+
+## The device
+
+The screen is 800x480, landscape, and never resizes. The kiosk shows one webapp, so build in-app views rather than tabs or windows. Add an on-screen keyboard if the app needs text entry.
+
+Listen with a `keydown` handler and a `wheel` handler on `window`.
+
+| Control      | Event                                 |
+| ------------ | ------------------------------------- |
+| Preset 1-4   | `keydown` key `"1"` `"2"` `"3"` `"4"` |
+| Mode         | `keydown` key `"m"`                   |
+| Back         | `keydown` key `"Escape"`              |
+| Rotary wheel | `wheel` with horizontal `deltaX`      |
+| Touch        | pointer and touch events              |
+
+Make horizontal wheel scroll move through the main list. Five fast presses of Mode returns to the launcher.
+
+## The client
+
+```ts
+import { BridgethingClient } from '@bridgething/client';
+import { useMemo } from 'react';
+
+import { daemonUrl } from './daemon';
+
+const client = useMemo(() => new BridgethingClient({ url: daemonUrl() }), []);
+```
+
+Construct it once and reuse it. It connects and reconnects on its own. Call `daemonUrl()` instead of a literal `ws://` address.
+
+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.
+
+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.
+
+## Working on one app
+
+```sh
+bun run dev                            # the only app, against a connected Car Thing
+bun run dev <slug>                     # name it when there is more than one
+bun run --cwd apps/<slug> dev          # always works
+bun run --cwd apps/<slug> dev:device   # show that server on the device's own screen
+bun run --cwd apps/<slug> push         # build and install onto the connected device
+bun run --cwd apps/<slug> build        # writes dist/
+bun run --cwd apps/<slug> typecheck    # checks src, settings and extension together
+bun run --cwd apps/<slug> share        # zips dist/ to hand to someone directly
+bun run --cwd apps/<slug> update       # brings the device to the latest bridgething release
+```
+
+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`.
+
+## The three files that describe an app
+
+**`apps/<slug>/public/manifest.json`** is the app's identity as far as the device and the catalog are concerned.
+
+- `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.
+- `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`.
+- `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.
+
+**`apps/<slug>/CHANGELOG.md`** carries a `## <version>` section per release, which becomes that version's changelog in the catalog.
+
+## Adding and shipping
+
+```sh
+bun run new <slug> [--extension | --launcher | --overlay]
+bun run shot <slug> [--replace | --name <label>]
+bun run bump <slug> <major | minor | patch | x.y.z> [-m "note"]
+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.
+
+`bump` writes `public/manifest.json` and `package.json` together and opens the changelog section. Editing one without the other fails the build.
+
+`check` is the whole gate and is exactly what CI runs: typecheck, build, bundle, generate the catalog, validate it against `catalog.v1` and the cross-reference invariants. Run it before claiming anything works.
+
+Pushing to main publishes. `bun run publish --dry-run` assembles the exact bytes that would be pushed, into `site/`, without pushing.
+
+## 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.
+- **Bundles are reproducible.** Timestamps are flattened before zipping so the same source gives the same digest. Do not add anything nondeterministic to a build.
+- **`site/` is generated and gitignored.** Nothing about a release belongs on main.
+- **CORS is a requirement.** A source must serve its catalog and its downloads with `Access-Control-Allow-Origin: *` or browser clients cannot read it. GitHub Pages does; most self-hosting does not.
+- **`base_url` in `source.json` is where this catalog is served.** If you forked this repo, point it at your own pages site and give every app a fresh uuid, or you publish app ids that belong to someone else. `check` refuses when it disagrees with the origin remote.
+
+## Comments
+
+Terse, lowercase, self-contained, non-obvious WHY only, 120 columns. No historical cross-references, no pointers at other files, no emdashes. Most code here needs none.

package/template-source/README.md

@@ -0,0 +1,57 @@
+# **SOURCE_NAME**
+
+**SOURCE_DESCRIPTION**
+
+Webapps for the Spotify Car Thing running [bridgething](https://bridgething.com).
+
+## First run
+
+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>
+
+## Develop
+
+```sh
+bun run dev            # develop the app against a connected bridgething instance
+bun run dev:device     # show the dev server on the car thing screen
+bun run push           # build and install to the device
+bun run check          # ensure the catalog is valid
+```
+
+With more than one app in `apps/` your commands must specify which one: `bun run dev __APP_SLUG__`.
+
+Screenshot for the store listing:
+
+```sh
+bun run shot __APP_SLUG__            # grabs what is on the screen
+bun run shot __APP_SLUG__ --replace  # overwrite
+```
+
+## Add another app
+
+```sh
+bun run new weather                 # a webapp
+bun run new dashboard --extension   # a webapp plus a desktop-side Deno process
+bun run new home --launcher         # a replacement home screen
+bun run new hud --overlay           # a system overlay drawn over every webapp
+```
+
+## Ship
+
+```sh
+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.
+
+## Agent skill
+
+`.claude/skills/bridgething/` holds the `/bridgething` skill.
+
+```sh
+bun run skills           # refresh it from the published create-bridgething
+bun run skills --check   # check whether it is behind
+```

package/template-source/_bunversion

@@ -0,0 +1 @@
+1.4.0

package/template-source/_github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+
+      - run: bun install --frozen-lockfile
+
+      - name: build, bundle and validate the catalog
+        env:
+          CHECK_BASE_REF: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || '' }}
+        run: bun run check

package/template-source/_github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: publish
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+
+      - run: bun install --frozen-lockfile
+
+      - name: identify the publisher
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: build every unpublished version and push the catalog
+        run: bun run publish

package/template-source/_gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+site
+.dev-extension
+.DS_Store
+*.log
+.env*

package/template-source/_prettierrc.js

@@ -0,0 +1,10 @@
+/** @type {import("prettier").Config} */
+export default {
+  bracketSpacing: true,
+  bracketSameLine: true,
+  singleQuote: true,
+  trailingComma: 'all',
+  arrowParens: 'avoid',
+  semi: true,
+  overrides: [{ files: ['*.ts', '*.js', '*.tsx', '*.jsx', '*.cjs', '*.mjs'], options: { printWidth: 120 } }],
+};

package/template-source/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "__REPO_NAME__",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "apps/*"
+  ],
+  "scripts": {
+    "new": "bunx create-bridgething",
+    "dev": "bridgething-source run dev",
+    "dev:device": "bridgething-source run dev:device",
+    "build": "bridgething-source run build",
+    "push": "bridgething-source run push",
+    "share": "bridgething-source run share",
+    "check": "bridgething-source check",
+    "bump": "bridgething-source bump",
+    "shot": "bridgething-source shot",
+    "catalog": "bridgething-source catalog",
+    "publish": "bridgething-source publish",
+    "skills": "bridgething-source skills",
+    "format": "prettier --write \"*.json\" \"*.js\""
+  },
+  "devDependencies": {
+    "prettier": "^3.9.6",
+    "typescript": "^6.0.3"
+  }
+}

package/template-source/source.json

@@ -0,0 +1,8 @@
+{
+  "name": "__SOURCE_NAME__",
+  "description": "__SOURCE_DESCRIPTION__",
+  "homepage": "https://github.com/__REPO_OWNER__/__REPO_NAME__",
+  "icon": null,
+  "base_url": "https://__REPO_OWNER_LOWER__.github.io/__REPO_NAME__",
+  "recommended_sources": []
+}

package/template-versions.json

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