chore: add yarn start:android-usb for local USB device testing

AGENTS.md

@@ -175,11 +175,14 @@ This project uses [Portless](https://github.com/vercel-labs/portless) for local
 
 To bypass Portless: `PORTLESS=0 yarn start`
 
+Android phone over USB (Chrome on device → dev server via `adb reverse`): `yarn start:android-usb`
+
 ## Common Commands
 
 ```bash
 corepack yarn install
 yarn start                # http://5chan.localhost:1355
+yarn start:android-usb    # Vite + adb reverse for USB Android (http://localhost:1355 on device)
 yarn build
 yarn test
 yarn test:coverage

README.md

@@ -106,9 +106,14 @@ To have your board appear in a directory on the 5chan homepage:
 
 The dev server runs at http://5chan.localhost:1355 via [Portless](https://port1355.dev/), which gives each Bitsocial project a stable, named URL instead of a random port. To bypass Portless and use a plain Vite dev server: `PORTLESS=0 yarn start`
 
+For device testing on a USB-connected Android phone (without relying on `5chan.localhost` DNS from the device):
+
+- `yarn start:android-usb` starts Vite bound to `127.0.0.1` and runs `adb reverse`, so the phone can load the dev site at `http://localhost:1355` in Chrome (or another browser). Requires [Android platform-tools](https://developer.android.com/tools/releases/platform-tools) (`adb` on your `PATH`), USB debugging enabled, and the device showing as `device` in `adb devices`.
+
 ### Scripts
 
 - **Web client**: `yarn start` (http://5chan.localhost:1355)
+- **Web client (Android phone over USB)**: `yarn start:android-usb` (see above)
 - **Electron client** (must start web client first): `yarn electron`
 - **Electron client** (don't delete data): `yarn electron:no-delete-data`
 - **Web client and electron client**: `yarn electron:start`

package.json

@@ -52,6 +52,7 @@
     "prebuild": "corepack yarn sync:directories && corepack yarn generate:assets",
     "prestart": "corepack yarn sync:directories && corepack yarn generate:assets",
     "start": "node scripts/start-dev.js",
+    "start:android-usb": "node scripts/start-android-usb.mjs",
     "build": "cross-env PUBLIC_URL=./ GENERATE_SOURCEMAP=false vite build",
     "build:preload": "vite build --config electron/vite.preload.config.js",
     "build-vercel": "cross-env NODE_OPTIONS=\"--max_old_space_size=4096\" PUBLIC_URL=./ GENERATE_SOURCEMAP=true VITE_COMMIT_REF=$COMMIT_REF CI='' vite build",

scripts/AGENTS.md

@@ -4,7 +4,7 @@ These rules apply to `scripts/**`. Follow the repo-root `AGENTS.md` first, then
 
 - Keep scripts non-interactive and idempotent. Print the command, URL, branch, or path being acted on so failures are diagnosable.
 - Use repo-relative paths and environment variables instead of user-specific absolute paths.
-- For dev-server helpers, default to `http://5chan.localhost:1355` and respect the existing `PORTLESS=0` fallback instead of hard-coding alternate ports.
+- For dev-server helpers, default to `http://5chan.localhost:1355` and respect the existing `PORTLESS=0` fallback instead of hard-coding alternate ports. For USB Android preview, `scripts/start-android-usb.mjs` mirrors bitsocial-web: `adb reverse` plus Vite on `127.0.0.1` so the device opens `http://localhost:<port>`.
 - Keep shell helpers thin. When logic becomes stateful or cross-platform, prefer a Node script.
 - Git and worktree helpers must validate input and default to safe operations.
 - If a helper deletes local branches automatically, document the exact eligibility checks and keep the behavior conservative.

scripts/dev-server-utils.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const repoRoot = path.resolve(__dirname, '..');
+export const isWindows = process.platform === 'win32';
+
+function checkPort(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+
+    server.once('error', () => resolve(false));
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port);
+  });
+}
+
+export async function resolvePort(requestedPort) {
+  let port = requestedPort;
+
+  while (!(await checkPort(port))) {
+    port += 1;
+  }
+
+  return port;
+}
+
+export function startVite(host, port) {
+  const child = spawn('corepack', ['yarn', 'exec', 'vite', '--host', host, '--port', String(port), '--strictPort'], {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      PORTLESS: '0',
+    },
+    stdio: 'inherit',
+  });
+
+  const forwardSignal = (signal) => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  };
+
+  const onSigint = () => forwardSignal('SIGINT');
+  const onSigterm = () => forwardSignal('SIGTERM');
+
+  process.on('SIGINT', onSigint);
+  process.on('SIGTERM', onSigterm);
+
+  child.on('exit', (code, signal) => {
+    process.off('SIGINT', onSigint);
+    process.off('SIGTERM', onSigterm);
+
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+
+    process.exit(code ?? 0);
+  });
+
+  return child;
+}

scripts/start-android-usb.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { isWindows, repoRoot, resolvePort, startVite } from './dev-server-utils.mjs';
+
+const adbBin = isWindows ? 'adb.exe' : 'adb';
+const host = '127.0.0.1';
+const requestedPort = Number(process.env.ANDROID_USB_PORT || 1355);
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function runPrestart() {
+  const pre = spawnSync('corepack', ['yarn', 'run', 'prestart'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  if (pre.status !== 0) {
+    fail(`prestart failed with exit code ${pre.status ?? 'unknown'}`);
+  }
+}
+
+function getReadyDevices() {
+  const adbDevices = spawnSync(adbBin, ['devices'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+
+  if (adbDevices.error) {
+    fail('ADB not found. Install Android platform-tools, connect the phone over USB, and enable USB debugging.');
+  }
+
+  if (adbDevices.status !== 0) {
+    fail(`ADB check failed: ${adbDevices.stderr.trim() || adbDevices.stdout.trim() || 'unknown error'}`);
+  }
+
+  const devices = adbDevices.stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('List of devices attached'));
+
+  const readyDevices = devices.filter((line) => line.endsWith('\tdevice')).map((line) => line.split('\t')[0]);
+
+  if (readyDevices.length === 0) {
+    const detail = devices.length > 0 ? ` Detected states: ${devices.join(', ')}` : '';
+    fail(`No Android device is ready over USB.${detail} Connect the phone, unlock it, trust the computer, and enable USB debugging.`);
+  }
+
+  return readyDevices;
+}
+
+function reversePorts(devices, port) {
+  for (const serial of devices) {
+    const adbReverse = spawnSync(adbBin, ['-s', serial, 'reverse', `tcp:${port}`, `tcp:${port}`], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+    });
+
+    if (adbReverse.status !== 0) {
+      fail(`ADB reverse failed for ${serial}: ${adbReverse.stderr.trim() || adbReverse.stdout.trim() || 'unknown error'}`);
+    }
+  }
+}
+
+runPrestart();
+
+const devices = getReadyDevices();
+const port = await resolvePort(requestedPort);
+
+reversePorts(devices, port);
+
+console.log('');
+console.log(`Starting Android USB preview from ${repoRoot}`);
+console.log(`Host URL: http://${host}:${port}`);
+if (port !== requestedPort) {
+  console.log(`Preferred port ${requestedPort} is busy, so this run will use ${port}.`);
+}
+console.log(`ADB reverse is active for: ${devices.join(', ')}`);
+console.log(`Open http://localhost:${port} in Chrome on the Android device.`);
+console.log('');
+
+startVite(host, port);