create-bridgething 0.11.0 → 0.12.0

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.