create-bridgething 0.1.6 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bridgething",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "type": "module",
   "description": "Scaffold a new bridgething webapp (React + Vite + Tailwind v4)",
   "license": "MIT",
@@ -32,6 +32,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
+    "@types/node": "^26.1.1",
     "@types/uuid": "^11.0.0",
     "tsdown": "^0.21.10"
   },

package/template/CLAUDE.md

@@ -70,6 +70,12 @@ files for a specific method or type.
 - `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.
+- `settings` - one self-contained HTML file (built from `settings/`) the
+  companion phone app renders as this webapp's settings page. It talks to the
+  companion over `@bridgething/client/settings`, not the on-device SDK. Capped
+  at 1 MiB at install. It loads from a `file://` origin: websocket APIs work
+  from it, but plain HTTP fetch is CORS-gated (`Origin: null`) - see the
+  network caveat in the `/bridgething` skill's sdk reference.
 
 ## Workflow
 

package/template/README.md

@@ -61,3 +61,10 @@ to bring the connected Car Thing to the latest bridgething release. Multiple dev
 - `src/index.css` - `@import "tailwindcss";`.
 - `vite.config.ts` - vite + tailwind plugin, `es2022` target.
 - `index.html` - 800x480 viewport, no overscroll, no tap highlight.
+- `settings/` - the companion-side settings page (preact), built by
+  `vite.settings.config.ts` into a single self-contained `dist/settings.html`.
+  It reads and writes settings over `@bridgething/client/settings`.
+
+`bun run build` runs both configs: the main app into `dist/`, then the settings
+page as `dist/settings.html`. `manifest.json`'s `settings` field points the
+companion at it.

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

@@ -133,6 +133,21 @@ const r = await client.config.get({ key: 'units' });
 const all = await client.config.list();
 ```
 
+The user edits these in the companion phone app. The scaffold ships a
+companion-side settings page under `settings/` that reads and writes them via a
+separate SDK, `@bridgething/client/settings` (a `postMessage` bridge to the
+companion host, not this WebSocket). `manifest.json`'s `settings` field points
+the companion at the built `dist/settings.html`.
+
+NETWORK CAVEAT for the settings page: it runs on the phone with real internet,
+but it loads from a `file://` origin and the webview enforces CORS on
+fetch/XHR. WebSocket APIs work (the WS handshake is not CORS-gated); plain HTTP
+APIs work only when the server sends permissive CORS headers (requests arrive
+with `Origin: null`). Prefer the service's websocket API from the settings
+page; for a CORS-strict HTTP-only service, fetch from the device webapp via
+`client.net` (phone-tunneled, not origin-restricted) and keep the settings page
+for typing and choosing.
+
 **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`,

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

@@ -30,7 +30,9 @@ 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.
+your built bundle with `manifest.json` at its root. `bun run build` also emits
+`dist/settings.html` (the companion-side settings page); it ships in the same
+bundle when `manifest.json` declares `settings`.
 
 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

package/template/package.json

@@ -5,19 +5,21 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vite build",
+    "build": "vite build && vite build -c vite.settings.config.ts",
     "preview": "vite preview",
     "push": "bun scripts/push.ts",
     "share": "bun scripts/share.ts",
     "update": "bunx @bridgething/updater"
   },
   "dependencies": {
-    "@bridgething/client": "^0.1.6",
+    "@bridgething/client": "^0.2.0",
+    "preact": "^10.29.7",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },
   "devDependencies": {
     "@msgpack/msgpack": "^3.1.3",
+    "@preact/preset-vite": "^2.10.5",
     "@tailwindcss/vite": "^4.1.16",
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",
@@ -25,6 +27,7 @@
     "fflate": "^0.8.2",
     "tailwindcss": "^4.1.16",
     "typescript": "^6.0.3",
-    "vite": "^7.1.13"
+    "vite": "^7.1.13",
+    "vite-plugin-singlefile": "^2.3.3"
   }
 }

package/template/public/manifest.json

@@ -3,6 +3,7 @@
   "name": "__PROJECT_NAME__",
   "version": "0.1.0",
   "description": "",
+  "settings": "settings.html",
   "config": [],
   "permissions": [],
   "art": { "heroPx": 248, "thumbPx": 96 }

package/template/settings/main.tsx

@@ -0,0 +1,103 @@
+import { settings, type ConfigField, type SettingsContext } from '@bridgething/client/settings';
+import { render } from 'preact';
+import { useEffect, useState } from 'preact/hooks';
+import './style.css';
+
+function fieldMeta(field: ConfigField): { key: string; label: string } {
+  return { key: field.data.key, label: field.data.label };
+}
+
+function Settings() {
+  const [ctx, setCtx] = useState<SettingsContext | null>(null);
+  const [fields, setFields] = useState<ConfigField[]>([]);
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [status, setStatus] = useState('');
+
+  useEffect(() => {
+    (async () => {
+      try {
+        setCtx(await settings.context());
+        const [schema, entries] = await Promise.all([settings.config.fields(), settings.config.list()]);
+        setFields(schema);
+        setValues(Object.fromEntries(entries.map(e => [e.key, e.value])));
+      } catch (err) {
+        setStatus(err instanceof Error ? err.message : String(err));
+      }
+    })();
+  }, []);
+
+  async function saveConfig(event: Event) {
+    event.preventDefault();
+    setStatus('saving...');
+    try {
+      for (const field of fields) {
+        const { key } = fieldMeta(field);
+        await settings.config.set(key, values[key] ?? '');
+      }
+      setStatus('settings saved');
+    } catch (err) {
+      setStatus(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  async function saveToDevice() {
+    setStatus('writing to device...');
+    try {
+      await settings.doc.set('preferences', JSON.stringify({ values, savedAt: Date.now() }));
+      setStatus('synced a preferences doc to the device');
+    } catch (err) {
+      setStatus(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  return (
+    <main>
+      <h1>{ctx?.name ?? '__PROJECT_NAME__'} settings</h1>
+      <p class="hint">{ctx ? `${ctx.webappId} on ${ctx.deviceId}` : 'connecting to the companion host...'}</p>
+
+      <form onSubmit={saveConfig}>
+        {fields.length === 0 && <p class="hint">this webapp declares no config fields yet.</p>}
+        {fields.map(field => {
+          const { key, label } = fieldMeta(field);
+          const value = values[key] ?? '';
+          const onInput = (e: Event) => setValues({ ...values, [key]: (e.target as HTMLInputElement).value });
+          return (
+            <div class="field" key={key}>
+              <label for={key}>{label}</label>
+              {field.type === 'enum' ? (
+                <select id={key} value={value} onInput={onInput}>
+                  {field.data.choices.map(choice => (
+                    <option value={choice} key={choice}>
+                      {choice}
+                    </option>
+                  ))}
+                </select>
+              ) : (
+                <input
+                  id={key}
+                  type={field.type === 'number' ? 'number' : field.type === 'secret' ? 'password' : 'text'}
+                  value={value}
+                  onInput={onInput}
+                />
+              )}
+            </div>
+          );
+        })}
+
+        <div class="row">
+          <button type="submit">Save settings</button>
+          <button type="button" class="secondary" onClick={saveToDevice}>
+            Save to device
+          </button>
+          <button type="button" class="secondary" onClick={() => settings.done()}>
+            Done
+          </button>
+        </div>
+      </form>
+
+      <p class="status">{status}</p>
+    </main>
+  );
+}
+
+render(<Settings />, document.getElementById('root')!);

package/template/settings/settings.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <title>__PROJECT_NAME__ settings</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/main.tsx"></script>
+  </body>
+</html>

package/template/settings/style.css

@@ -0,0 +1,85 @@
+:root {
+  color-scheme: light dark;
+  font-family:
+    system-ui,
+    -apple-system,
+    sans-serif;
+}
+
+body {
+  margin: 0;
+  padding: 20px;
+  line-height: 1.5;
+}
+
+main {
+  max-width: 560px;
+  margin: 0 auto;
+}
+
+h1 {
+  font-size: 1.25rem;
+  margin: 0 0 0.25rem;
+}
+
+.hint {
+  opacity: 0.7;
+  font-size: 0.85rem;
+  margin: 0 0 1.25rem;
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  margin-bottom: 14px;
+}
+
+.field label {
+  font-size: 0.85rem;
+  font-weight: 600;
+}
+
+.field input,
+.field select {
+  padding: 8px 10px;
+  font-size: 1rem;
+  border: 1px solid color-mix(in srgb, currentColor 25%, transparent);
+  border-radius: 8px;
+  background: transparent;
+  color: inherit;
+}
+
+.row {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  margin-top: 8px;
+}
+
+button {
+  padding: 9px 16px;
+  font-size: 0.95rem;
+  font-weight: 600;
+  border: none;
+  border-radius: 8px;
+  background: #00a8e8;
+  color: #06232e;
+  cursor: pointer;
+}
+
+button.secondary {
+  background: color-mix(in srgb, currentColor 12%, transparent);
+  color: inherit;
+}
+
+button:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.status {
+  font-size: 0.85rem;
+  opacity: 0.8;
+  min-height: 1.2em;
+}

package/template/vite.settings.config.ts

@@ -0,0 +1,53 @@
+import preact from '@preact/preset-vite';
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { defineConfig, type Plugin } from 'vite';
+import { viteSingleFile } from 'vite-plugin-singlefile';
+
+const WARN_BYTES = 200 * 1024;
+const LOUD_BYTES = 500 * 1024;
+const HARD_CAP = '1 MiB';
+
+function sizeGuard(): Plugin {
+  return {
+    name: 'settings-size-guard',
+    closeBundle() {
+      const out = resolve(__dirname, 'dist', 'settings.html');
+      let bytes: number;
+      try {
+        bytes = statSync(out).size;
+      } catch {
+        return;
+      }
+      const kib = (bytes / 1024).toFixed(1);
+      if (bytes > LOUD_BYTES) {
+        console.warn(
+          [
+            '',
+            '========================================================================',
+            `  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.',
+            '========================================================================',
+            '',
+          ].join('\n'),
+        );
+      } else if (bytes > WARN_BYTES) {
+        console.warn(`settings.html is ${kib} KiB; keep it lean (install hard cap is ${HARD_CAP}).`);
+      }
+    },
+  };
+}
+
+export default defineConfig({
+  root: 'settings',
+  plugins: [preact(), viteSingleFile(), sizeGuard()],
+  build: {
+    target: 'es2022',
+    outDir: resolve(__dirname, 'dist'),
+    emptyOutDir: false,
+    rollupOptions: {
+      input: resolve(__dirname, 'settings', 'settings.html'),
+    },
+  },
+});