@solidrt/cli 0.0.10 → 0.0.13

package/AGENTS.md

@@ -0,0 +1,50 @@
+# @solidrt/cli - agent notes
+
+Dense, self-contained facts for running and verifying a SolidRT app. Full docs
+live in docs/ (and the website). For the authoring model (elements, props,
+reactivity), see @solidrt/core (its AGENTS.md).
+
+`srt` is the dev tool. Bun is a dev prerequisite only; SolidRT apps run on the
+bundled `flux` runtime, not on Bun. Invoke via `bunx srt <command>`.
+
+## Commands
+
+- `bunx srt init <dir>` - scaffold a new SolidRT project into a new (empty)
+  folder: package.json, tsconfig.json, AGENTS.md, a starter src/index.tsx, then
+  installs deps. Greenfield shortcut (no install needed first):
+  `bun create solidrt <dir>`.
+- `bunx srt run src/index.tsx` - dev server + a local client window, watches and
+  hot-reloads. NEEDS A DISPLAY (opens a GUI window). Not usable headless.
+- `bunx srt bundle src/index.tsx` - transpile to `<file>.srt.js`. With
+  `--compile`, emits `.srt.bin` bytecode. `--minify`, `--dev`, `--stdout`,
+  `--output` also available.
+- `bunx srt record src/index.tsx [flags]` - render OFFSCREEN to PNG frames.
+- `bunx srt server [file]` / `bunx srt client` - the two halves of `run`
+  separately (server distributes code; clients on other devices connect to it).
+
+## Verifying without a display (headless / CI / agent box)
+
+Two reliable checks that need no GUI:
+
+1. `bunx srt bundle src/index.tsx` - exit 0 means the app compiles. Fast.
+2. `bunx srt record src/index.tsx --size 480x640 --duration 1 --fps 2` -
+   renders offscreen via EGL/wgpu and writes `frame-NNNNNN.png`. This actually
+   proves the app renders. Combine with `--fps`/`--duration` (defaults
+   1280x720, 60fps, 1s).
+
+`record` gotchas:
+- Frames are written to the RUNTIME's working dir (`~/.local/share/SolidRT/go/`),
+  NOT the directory you ran the command from. Look there for the PNGs.
+- The recording includes a debug overlay (FPS/REQ/MiB/CPU) in a corner.
+- Run from the project directory. There is no `bunx --cwd` flag.
+
+## Dev server proxies (when clients on other devices need your machine's data)
+
+- `--proxy-http` - route `fetch` through the dev server; responses cached in
+  `.srt-cache.db` (delete the file to clear).
+- `--proxy-files` - route flux:fs (`file`/`dir`/`write`) through the dev server.
+  Exposes your dev machine's files to all clients; use with care.
+
+## REPL (opened by `run`/`server`)
+
+`load <file>`, `reload [n]`, `stop [n]`, `list`, `!<cmd>`, `quit`/`exit`.

package/README.md

@@ -2,6 +2,8 @@
 
 Developer tooling for SolidRT. Provides a development environment for `@solidrt/core` applications.
 
+> LLM agents: see [AGENTS.md](./AGENTS.md) for a dense, self-contained quickstart.
+
 ## Commands
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.10",
+  "version": "0.0.13",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -10,7 +10,8 @@
   "files": [
     "bin/",
     "src/",
-    "LICENSE"
+    "scaffold/",
+    "AGENTS.md"
   ],
   "dependencies": {
     "@babel/core": "^7.28.5",
@@ -20,13 +21,13 @@
     "qrcode-generator": "^2.0.4"
   },
   "optionalDependencies": {
-    "@solidrt/darwin-arm64": "0.0.10",
-    "@solidrt/linux-x64-gnu": "0.0.10",
-    "@solidrt/win32-x64-msvc": "0.0.10"
+    "@solidrt/darwin-arm64": "0.0.13",
+    "@solidrt/linux-x64-gnu": "0.0.13",
+    "@solidrt/win32-x64-msvc": "0.0.13"
   },
   "peerDependencies": {
-    "@solidrt/core": "0.0.10",
-    "typescript": "^5"
+    "@solidrt/core": "0.0.13",
+    "typescript": "^6"
   },
   "devDependencies": {
     "@types/bun": "latest"

package/scaffold/AGENTS.md

@@ -0,0 +1,48 @@
+# SolidRT app - agent notes
+
+This project uses SolidRT: a custom SolidJS renderer that paints through a Rust
+runtime. No DOM, no HTML, no CSS cascade. If you are an AI assistant, read this
+before writing or editing code here.
+
+Authoritative references ship inside the installed packages - read them:
+- node_modules/@solidrt/core/AGENTS.md   - element/prop/reactivity model
+- node_modules/@solidrt/cli/AGENTS.md    - running, bundling, headless verify
+- node_modules/@solidrt/core/src/types.d.ts and jsx-runtime.d.ts - source of truth
+
+<!-- Claude Code auto-imports these; other tools read the paths above. -->
+@./node_modules/@solidrt/core/AGENTS.md
+@./node_modules/@solidrt/cli/AGENTS.md
+
+## The things assistants get wrong (this is not React/DOM)
+
+1. SolidJS 2.0, not React (and not Solid 1.x). Primitives come from
+   @solidjs/signals; no hooks, no virtual DOM, the component body runs once.
+   createEffect has the 2.0 two-function shape - a TRACKED compute that reads
+   signals and returns a value, then an UNTRACKED effect that receives it:
+     createEffect(() => count(), (c) => console.log(c))
+   The Solid 1.x single-callback form, createEffect(() => console.log(count())),
+   does NOT track in 2.0.
+2. Host elements are lowercase intrinsics: window, view, text, rect, oval, path,
+   texture, audio (+ d- variants). No div/span/img/button.
+3. render(() => <App/>) once, top level. The root MUST be <window> or it throws.
+4. Containers (window, view) DO NOT PAINT. Background = a draw primitive child
+   placed behind the content, e.g. <d-rect color="..." />.
+5. Paint color is the color prop (a CSS color string). No fill/stroke/background
+   prop. Outline: drawStyle="stroke" + strokeWidth.
+6. No onClick/onPress. A button is a <view>/<rect> with onPointerDown.
+7. d- prefix = detached from layout: a plain element is laid out by Taffy, a
+   d-element you position with x/y (omit to fill the parent = how backgrounds
+   work).
+8. Per-frame work: onFrame((tick, frame) => {}), or the standard
+   requestAnimationFrame(t => {}) for animations. Also onResize, onLayout.
+9. Device/GPU via subpath imports: @solidrt/core/camera, /microphone, /gpu.
+10. tsconfig needs jsx:"preserve" + jsxImportSource:"@solidrt/core". Solid peer
+    deps are pinned betas - do not bump them casually.
+
+## Run / verify
+
+- bunx srt run src/index.tsx     - dev server + window (needs a display)
+- bunx srt bundle src/index.tsx  - exit 0 means it compiles
+- bunx srt record src/index.tsx --size 480x640 --duration 1 --fps 2 - headless
+  render to PNG frames (proves it renders; see the cli AGENTS.md for where the
+  frames land)

package/scaffold/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+*.srt.js
+*.srt.bin
+.srt-cache.db

package/scaffold/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "solidrt-app",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "srt run src/index.tsx",
+    "bundle": "srt bundle src/index.tsx"
+  },
+  "dependencies": {
+    "@solidrt/core": "latest"
+  },
+  "devDependencies": {
+    "@solidrt/cli": "latest",
+    "@solidrt/flux-types": "latest",
+    "typescript": "^6"
+  }
+}

package/scaffold/src/index.tsx

@@ -0,0 +1,25 @@
+import { render } from "@solidrt/core"
+
+function Icon() {
+  return (
+    <view width={100} height={100} scale={3}>
+      <d-path d="M50 50L0 50L50 0Z" color="#1a3380" />
+      <d-path d="M50 50L50 100L0 50Z" color="#3366b3" />
+      <d-path d="M50 25L50 0L75 25Z" color="#6699e6" />
+      <d-path d="M50 25L75 25L75 50L50 50Z" color="#3366b3" />
+      <d-path d="M50 50L75 50L50 75Z" color="#6699e6" />
+      <d-path d="M75 50L75 75L50 100L50 75Z" color="#1a3380" />
+      <d-path d="M100 50L75 75L75 25Z" color="#6699e6" />
+    </view>
+  )
+}
+
+function App() {
+  return (
+    <window alignItems="center" justifyContent="center">
+      <Icon />
+    </window>
+  )
+}
+
+render(() => <App />)

package/scaffold/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "jsxImportSource": "@solidrt/core",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "types": ["@solidrt/flux-types"]
+  },
+  "include": ["src"]
+}

package/src/args.ts

@@ -13,6 +13,7 @@ export let { values, positionals } = parseArgs({
     fps: { type: "string" },
     duration: { type: "string" },
     size: { type: "string" },
+    stats: { type: "boolean", default: false },
     android: { type: "boolean", default: false },
     device: { type: "string" },
   },
@@ -34,6 +35,9 @@ function usage(line: string): never {
 // Per-command argument requirements. Called once before dispatch.
 export function validateArgs() {
   switch (command) {
+    case "init":
+      if (!source) usage("srt init <dir>  (the target folder is required)")
+      break
     case "bundle":
       if (values.flux) {
         if (!source || !isTs) usage("srt bundle --flux [options] <entry.[ts|js]>")
@@ -64,6 +68,7 @@ export function printUsage() {
   console.error(`Usage: srt <command> [options] [file]
 
 Commands:
+  init <dir>             Scaffold a new SolidRT project into a new (empty) folder
   run [file]             Start dev server + local solidrt-go client
   server [file]          Start dev server only
   client                 Start solidrt-go client only
@@ -77,6 +82,7 @@ run/server options:
 
 run/client options:
       --size <WxH>       Window size (default: 1280x720)
+      --stats            Show the debug stats overlay (FPS, memory, frame timings)
 
 client options:
       --android          Install and launch the client on a connected Android device

package/src/artifacts.ts

@@ -44,27 +44,35 @@ export function resolveBinary(name: string) {
   return null
 }
 
-// The Android client APK is per-ABI (it bundles native .so for one architecture)
-// and host-independent, so it lives under dist/android/<abi>/ rather than the
-// host triple map. Only arm64-v8a is supported for now.
-let ANDROID_ABI = "arm64-v8a"
-let ANDROID_PKG = "@solidrt/android-arm64-v8a"
+// The Android client APK is host-independent (it bundles native .so for the
+// device, not the host), so it lives under dist/android/<abi>/ rather than the
+// host triple map. arm64-v8a (a fat APK: arm64-v8a + the x86_64 emulator) and
+// armeabi-v7a (32-bit) ship published npm packages; other ABIs (e.g. x86) only
+// resolve via the SRT_HOME contributor path.
+let DEFAULT_ANDROID_ABI = "arm64-v8a"
+export let ANDROID_PKG_MAP: Record<string, string> = {
+  "arm64-v8a": "@solidrt/android-arm64-v8a",
+  "armeabi-v7a": "@solidrt/android-armeabi-v7a",
+}
 
-export function resolveApk() {
+export function resolveApk(abi: string = DEFAULT_ANDROID_ABI) {
   // 1. SRT_HOME: contributor checkout, where `make dist-android` stages the APK
   //    under dist/android/<abi>/.
   let srtRoot = process.env.SRT_HOME
   if (srtRoot) {
-    let apk = resolve(srtRoot, "dist/android", ANDROID_ABI, "solidrt-go.apk")
+    let apk = resolve(srtRoot, "dist/android", abi, "solidrt-go.apk")
     if (existsSync(apk)) return apk
   }
 
   // 2. Platform npm package
-  try {
-    let pkgDir = dirname(require.resolve(`${ANDROID_PKG}/package.json`))
-    let apk = resolve(pkgDir, "solidrt-go.apk")
-    if (existsSync(apk)) return apk
-  } catch {}
+  let pkg = ANDROID_PKG_MAP[abi]
+  if (pkg) {
+    try {
+      let pkgDir = dirname(require.resolve(`${pkg}/package.json`))
+      let apk = resolve(pkgDir, "solidrt-go.apk")
+      if (existsSync(apk)) return apk
+    } catch {}
+  }
 
   return null
 }

package/src/cache.ts

@@ -48,7 +48,8 @@ export function isEnabled(): boolean {
 
 // Strings returned by bun:sqlite carry an internal representation that
 // Headers.set() rejects, even when value-identical to an acceptable string
-// (Bun bug, present through 1.3.14). Rebuilding each char yields a clean string.
+// (Bun bug oven-sh/bun#28266, present through 1.3.14). Rebuilding each char
+// yields a clean string.
 function reflatten(s: string): string {
   return Array.from(s, (c) => String.fromCharCode(c.charCodeAt(0))).join("")
 }

package/src/commands/init.ts

@@ -0,0 +1,67 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises"
+import { basename, dirname, join, resolve } from "node:path"
+import { source } from "../args"
+
+const SCAFFOLD_DIR = join(import.meta.dir, "../../scaffold")
+
+// What gets written into a new project. Sources live in cli/scaffold/. The
+// .gitignore is stored there as `gitignore` because npm strips files literally
+// named `.gitignore` from published packages, so it is renamed on the way out.
+const TEMPLATE_FILES: Array<{ from: string; to: string }> = [
+  { from: "package.json", to: "package.json" },
+  { from: "tsconfig.json", to: "tsconfig.json" },
+  { from: "gitignore", to: ".gitignore" },
+  { from: "AGENTS.md", to: "AGENTS.md" },
+  { from: "src/index.tsx", to: "src/index.tsx" },
+]
+
+// A valid npm package name derived from the target directory.
+function packageName(dir: string): string {
+  let name = basename(resolve(dir))
+    .toLowerCase()
+    .replace(/[^a-z0-9-_.]/g, "-")
+  return name || "solidrt-app"
+}
+
+export async function runInitCommand() {
+  // The target folder is required (validateArgs enforces it) and must be empty
+  // or absent, so init can never overwrite files in an existing project.
+  let dir = source!
+  let existing = await readdir(dir).catch(() => null)
+  if (existing && existing.length > 0) {
+    console.error(`!! ${resolve(dir)} already exists and is not empty; choose a new folder name`)
+    process.exit(1)
+  }
+
+  console.log(`>> scaffolding SolidRT project in ${resolve(dir)}`)
+  for (let { from, to } of TEMPLATE_FILES) {
+    let dest = join(dir, to)
+    await mkdir(dirname(dest), { recursive: true })
+    await writeFile(dest, await readFile(join(SCAFFOLD_DIR, from)))
+    console.log(`   write ${to}`)
+  }
+
+  // The scaffold package.json carries a placeholder name; set it from the
+  // target folder.
+  let pkgPath = join(dir, "package.json")
+  let pkg = JSON.parse(await readFile(pkgPath, "utf8"))
+  pkg.name = packageName(dir)
+  await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n")
+
+  // Deps are declared in scaffold/package.json (Solid peers resolve via
+  // @solidrt/core's peerDependencies), so a plain install is enough.
+  console.log("\n>> installing dependencies")
+  let install = Bun.spawnSync(["bun", "install"], {
+    cwd: dir,
+    stdout: "inherit",
+    stderr: "inherit",
+  })
+  if (install.exitCode !== 0) {
+    console.error("\n!! dependency install failed; retry with `bun install` in the project")
+    process.exit(1)
+  }
+
+  let prefix = dir === "." ? "" : `cd ${dir} && `
+  console.log(`\n>> done. next:\n   ${prefix}bunx srt run src/index.tsx\n`)
+  process.exit()
+}

package/src/commands/server.ts

@@ -14,6 +14,7 @@ export async function runServerCommand() {
   // Initialize state from args
   state.source = source
   state.sourceDir = source ? dirname(resolve(source)) : process.cwd()
+  state.stats = values.stats
 
   if (values["proxy-http"]) {
     cache.initCache({ dir: process.cwd() })

package/src/dev-android.ts

@@ -1,26 +1,54 @@
+import { networkInterfaces } from "node:os"
 import { print, requireAdb } from "./util"
-import { resolveApk } from "./artifacts"
+import { resolveApk, ANDROID_PKG_MAP } from "./artifacts"
 import { values } from "./args"
 import { DEV_PORT } from "./dev-server"
 
 // Launch component of the "go" dev-client flavor (see lattice/Makefile.android).
 let PACKAGE_ACTIVITY = "com.solidrt.go/com.solidrt.app.MainActivity"
 
-// Forward the device's loopback DEV_PORT to the host dev server, so the client
-// reaches it at 127.0.0.1:DEV_PORT (see lattice/src/go/connection.rs). This is
-// the adb-reverse path: it works for the emulator (behind NAT, cannot reach the
-// host via LAN mDNS discovery) and for USB-tethered devices alike, and is
-// harmless on any adb connection. (Android only uses this path; the client's
-// mDNS discovery is desktop-only -- see lattice/src/go/connection.rs.)
-function setupAdbReverse(adb: string, target: string) {
-  print(`[cli] Forwarding 127.0.0.1:${DEV_PORT} on ${target} to host dev server`)
-  let res = Bun.spawnSync([adb, "-s", target, "reverse", `tcp:${DEV_PORT}`, `tcp:${DEV_PORT}`], {
+let ipToInt = (ip: string) => ip.split(".").reduce((acc, o) => (acc << 8) + (parseInt(o, 10) & 255), 0) >>> 0
+
+// This host's IPv4 on the same subnet as `deviceIp`: the interface whose
+// (address & netmask) matches the device's. Pure computation over what the OS
+// reports (cross-platform, no routing socket, no hardcoded ranges).
+function hostIpFor(deviceIp: string): string | null {
+  let d = ipToInt(deviceIp)
+  for (let addrs of Object.values(networkInterfaces())) {
+    for (let a of addrs ?? []) {
+      if (a.family === "IPv4" && !a.internal && (ipToInt(a.address) & ipToInt(a.netmask)) === (d & ipToInt(a.netmask))) {
+        return a.address
+      }
+    }
+  }
+  return null
+}
+
+// The device's own IPv4 on its primary network: from the serial for wireless adb
+// (ip:port), else queried over adb. `ip route get` reports the source IP of the
+// route to a public address, i.e. the device's main interface IP.
+function deviceIp(adb: string, target: string): string | null {
+  let m = target.match(/^(\d+\.\d+\.\d+\.\d+):\d+$/)
+  if (m) return m[1] ?? null
+  let res = Bun.spawnSync([adb, "-s", target, "shell", "ip", "route", "get", "1.1.1.1"], {
     stdout: "pipe",
     stderr: "pipe",
   })
-  if (res.exitCode !== 0) {
-    print(`[cli] adb reverse failed (client will fall back to discovery):\n${res.stderr.toString()}`)
-  }
+  return res.stdout.toString().match(/src (\d+\.\d+\.\d+\.\d+)/)?.[1] ?? null
+}
+
+// The host:port the client on `target` should dial to reach this machine's dev
+// server, by adb transport: the emulator reaches the host through its NAT alias
+// 10.0.2.2; every other transport shares a LAN with the host, so match the
+// device's IP to the host interface on its subnet. Replaces the old adb-reverse
+// loopback tunnel, which never worked over wireless adb. Returns null when the
+// address cannot be resolved (the client then falls back to QR/recents).
+function devServerAddress(adb: string, target: string): string | null {
+  if (target.startsWith("emulator-")) return `10.0.2.2:${DEV_PORT}`
+  let dip = deviceIp(adb, target)
+  if (!dip) return null
+  let host = hostIpFor(dip)
+  return host ? `${host}:${DEV_PORT}` : null
 }
 
 // Serials of connected, authorized devices (excludes offline/unauthorized).
@@ -70,22 +98,37 @@ function resolveTarget(adb: string): string {
   return only
 }
 
-// Install + launch the Android client on a connected device over adb, forwarding
-// its loopback to the host dev server so the client connects at 127.0.0.1 (see
-// setupAdbReverse). Fire-and-forget: the client's lifecycle is tracked via WS
-// connect/disconnect in dev-server.ts, not as a child process here.
+// Primary ABI of the connected device (e.g. "arm64-v8a", "armeabi-v7a"), used
+// to pick the matching APK -- a fat (multi-ABI) APK reports its 64-bit ABI
+// here and still installs fine, so this only matters for single-ABI builds.
+function deviceAbi(adb: string, target: string): string {
+  let res = Bun.spawnSync([adb, "-s", target, "shell", "getprop", "ro.product.cpu.abi"], {
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  return res.stdout.toString().trim()
+}
+
+// Install + launch the Android client on a connected device over adb, passing it
+// the dev-server address to dial as a launch-intent extra (see devServerAddress).
+// Fire-and-forget: the client's lifecycle is tracked via WS connect/disconnect in
+// dev-server.ts, not as a child process here.
 export async function spawnAndroidClient() {
   let adb = requireAdb()
 
-  let apk = resolveApk()
+  let target = resolveTarget(adb)
+  let abi = deviceAbi(adb, target)
+
+  let apk = resolveApk(abi)
   if (!apk) {
-    console.error("Could not find the SolidRT-Go APK.")
-    console.error("Add it with: bun add -d @solidrt/android-arm64-v8a")
+    console.error(`Could not find a SolidRT-Go APK for ABI "${abi}".`)
+    let pkg = ANDROID_PKG_MAP[abi]
+    if (pkg) console.error(`Add it with: bun add -d ${pkg}`)
+    let target = abi === "armeabi-v7a" ? "make dist-android-armeabi-v7a" : "make dist-android"
+    console.error(`Or build one locally (from lattice/): ${target}`)
     process.exit(1)
   }
 
-  let target = resolveTarget(adb)
-
   print(`[cli] Installing SolidRT-Go on ${target}`)
   let install = Bun.spawn([adb, "-s", target, "install", "-r", apk], { stdout: "pipe", stderr: "pipe" })
   if ((await install.exited) !== 0) {
@@ -93,12 +136,19 @@ export async function spawnAndroidClient() {
     process.exit(1)
   }
 
-  setupAdbReverse(adb, target)
+  // Hand the client the dev-server address to dial, as a launch-intent extra that
+  // MainActivity forwards to native argv (--dev-server); the client auto-connects
+  // to it. Replaces adb reverse, which never worked over wireless adb.
+  let devServer = devServerAddress(adb, target)
+  let launchArgs = [adb, "-s", target, "shell", "am", "start", "-n", PACKAGE_ACTIVITY]
+  if (devServer) {
+    print(`[cli] Client will dial dev server at ${devServer}`)
+    launchArgs.push("--es", "srt_dev_server", devServer)
+  } else {
+    print("[cli] Could not resolve a host address for the device; client will need a manual/QR connect")
+  }
 
-  let start = Bun.spawn([adb, "-s", target, "shell", "am", "start", "-n", PACKAGE_ACTIVITY], {
-    stdout: "pipe",
-    stderr: "pipe",
-  })
+  let start = Bun.spawn(launchArgs, { stdout: "pipe", stderr: "pipe" })
   if ((await start.exited) !== 0) {
     console.error("adb start failed:\n" + (await new Response(start.stderr).text()))
     process.exit(1)

package/src/dev-server.ts

@@ -8,16 +8,17 @@ import { values } from "./args"
 import * as cache from "./cache"
 
 export const DEV_HOST = "127.0.0.1"
-export const DEV_PORT = 15194
+export const DEV_PORT = 0x8844
 
-// Dev-server WS protocol helpers: the reload message shape and the stop broadcast.
+// Dev-server WS protocol helpers: the reload message shape and a broadcast to all clients.
 export function buildReload(payload: { code?: string | null; bytecode?: string }) {
   return JSON.stringify({ type: "reload", proxyFiles: values["proxy-files"], proxyHttp: values["proxy-http"], ...payload })
 }
 
-export function broadcastStop() {
+export function broadcast(msg: object) {
+  let text = JSON.stringify(msg)
   for (let ws of state.clients.keys()) {
-    ws.send(JSON.stringify({ type: "stop" }))
+    ws.send(text)
   }
 }
 
@@ -157,7 +158,7 @@ export function startServer() {
         print(`[cli] Client connected ${ws.remoteAddress}`)
         // Advertise our real LAN address so clients dialed over the adb loopback
         // can show/remember the directly reachable address (see connection.rs).
-        ws.send(JSON.stringify({ type: "welcome", address: state.serverUrl }))
+        ws.send(JSON.stringify({ type: "welcome", address: state.serverUrl, stats: state.stats }))
         if (state.currentCode) {
           ws.send(buildReload({ code: state.currentCode }))
         }
@@ -245,4 +246,4 @@ export function startServer() {
       ws.ping()
     }
   }, 5000)
-}
+}

package/src/main.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { values, command, validateArgs, printUsage } from "./args"
+import { runInitCommand } from "./commands/init"
 import { runBundleCommand } from "./commands/bundle"
 import { runPackCommand } from "./commands/pack"
 import { runRecordCommand } from "./commands/record"
@@ -35,7 +36,9 @@ if (isProdBuild && process.env.NODE_ENV !== "production") {
 
 // -- Dispatch --
 
-if (command === "bundle") {
+if (command === "init") {
+  await runInitCommand()
+} else if (command === "bundle") {
   await runBundleCommand()
 } else if (command === "pack") {
   await runPackCommand()

package/src/repl.ts

@@ -2,7 +2,7 @@ import { createInterface } from "node:readline"
 import { resolve, dirname } from "path"
 import { readdirSync } from "node:fs"
 import { state, print, printErr, shutdown } from "./util"
-import { buildReload, broadcastStop } from "./dev-server"
+import { buildReload, broadcast } from "./dev-server"
 import { bundle } from "./bundler"
 import { startWatcher, stopWatcher } from "./watcher"
 
@@ -11,7 +11,7 @@ function cmdStop(args: string) {
     stopWatcher()
     state.currentCode = null
     state.source = undefined
-    broadcastStop()
+    broadcast({ type: "stop" })
     print("[cli] Sent stop to all clients")
     return
   }
@@ -56,6 +56,21 @@ async function cmdReload(args: string) {
   }
 }
 
+function cmdStats(args: string) {
+  if (args === "on") {
+    state.stats = true
+  } else if (args === "off") {
+    state.stats = false
+  } else if (!args) {
+    state.stats = !state.stats
+  } else {
+    print("Usage: stats [on|off]")
+    return
+  }
+  broadcast({ type: "stats", stats: state.stats })
+  print(`[cli] Stats overlay ${state.stats ? "on" : "off"}`)
+}
+
 function cmdList() {
   if (state.clients.size === 0) {
     print("No connected clients")
@@ -105,7 +120,7 @@ async function cmdLoad(file: string) {
   print(`[cli] Loaded ${file}`)
 }
 
-let COMMANDS = ["load ", "stop", "reload", "list", "quit", "exit", "help"]
+let COMMANDS = ["load ", "stop", "reload", "list", "stats", "quit", "exit", "help"]
 let LOAD_EXTENSIONS = [".tsx", ".srt.js", ".srt.bin"]
 
 function completer(line: string): [string[], string] {
@@ -150,6 +165,8 @@ export function startRepl() {
       cmdLoad(cmd.slice(5).trim())
     } else if (cmd === "list") {
       cmdList()
+    } else if (cmd === "stats" || cmd.startsWith("stats ")) {
+      cmdStats(cmd.slice(6).trim())
     } else if (cmd === "quit" || cmd === "exit") {
       shutdown()
     } else if (cmd.startsWith("!")) {
@@ -165,7 +182,7 @@ export function startRepl() {
         )
       }
     } else if (cmd === "help") {
-      print("Commands: load, stop, reload, list, !<cmd>, quit, help")
+      print("Commands: load, stop, reload, list, stats, !<cmd>, quit, help")
     } else if (cmd) {
       print(`Unknown command: ${cmd}`)
     }

package/src/util.ts

@@ -15,6 +15,7 @@ export let state = {
   serverUrl: null as string | null,
   rl: null as ReadlineInterface | null,
   bonjour: null as Bonjour | null,
+  stats: false,
 }
 
 // Build target per binary, for the "not found" hint. Run from the repo root.