Merge pull request #20 from connorads/dev

feat: promote built-in runtime from dev to main

Author: connorads

.agents/skills/remobi-setup/SKILL.md

@@ -44,14 +44,12 @@ Run silently, then report what's present vs missing:
 
 ```bash
 node --version          # need >= 22
-which ttyd              # must be on PATH
 tmux -V                 # target multiplexer
 which remobi            # npm install -g remobi
 ```
 
 If anything is missing, help install it:
 - **Node**: suggest mise, nvm, or direct install
-- **ttyd**: `brew install ttyd` (macOS), distro package or source build (Linux) — see [ttyd installation](https://github.com/tsl0922/ttyd#installation)
 - **tmux**: `brew install tmux` or distro package
 - **remobi**: `npm install -g remobi`
 
@@ -168,13 +166,13 @@ export default {
 
 Place at `~/.config/remobi/remobi.config.ts` (XDG location) unless the user prefers elsewhere.
 
-After writing, validate:
+After writing, validate by starting remobi:
 
 ```bash
-remobi build --dry-run
+remobi serve --config ~/.config/remobi/remobi.config.ts --port 18765 -- /bin/true
 ```
 
-A zero exit with "Dry run: build" output means valid. Fix any errors and re-validate until clean.
+A zero exit means the config loaded and the command started cleanly. Fix any errors and re-validate until clean.
 
 See [Config reference](#config-reference) below for the full schema, allowed keys, action types, and escape codes.
 
@@ -234,13 +232,13 @@ remobi hardens the connection even on private networks. Mention these if the use
 - **Content-Security-Policy** — strict default-src, script-src, connect-src scoped to same host
 - **WebSocket origin validation** — rejects cross-origin upgrade requests
 - **Relay buffer limit** — 1 MB per connection; drops oversized payloads
-- **Crypto-secure internal port** — ttyd listens on a random ephemeral port (crypto PRNG), never exposed
+- **Local-only default** — remobi binds to `127.0.0.1` unless the user explicitly changes `--host`
 - **X-Frame-Options DENY** — prevents clickjacking via iframes
 - **Referrer-Policy: no-referrer** — no URL leaking to external sites
 
 For macOS users, mention `--no-sleep` and point to `references/keep-awake.md` for persistent options.
 
-For users who want manual ttyd control, point to `references/ttyd-flags.md`.
+For users migrating from old ttyd-based setups, point to `references/ttyd-flags.md` as legacy guidance only.
 
 #### Summary
 
@@ -589,11 +587,11 @@ Requires matching tmux bindings (see `references/tmux-basics.md` popup section).
 ## Validation
 
 ```bash
-remobi build --dry-run          # validates config, prints plan, exits without building
-remobi build --dry-run -c ./remobi.config.ts   # explicit path
+remobi serve --config ~/.config/remobi/remobi.config.ts --port 18765 -- /bin/true
+remobi serve --config ./remobi.config.ts --port 18765 -- /bin/true
 ```
 
-A zero exit with "Dry run: build" output means the config is valid. Any error output means fix the reported paths before proceeding.
+A zero exit means the config is valid. Any error output means fix the reported paths before proceeding.
 
 ### Common validation errors
 

.agents/skills/remobi-setup/references/tailscale-serve.md

@@ -4,7 +4,6 @@ Expose a tmux session as a mobile-friendly web terminal over your Tailscale netw
 
 ## Prerequisites
 
-- [ttyd](https://github.com/tsl0922/ttyd) installed (`brew install ttyd` on macOS; Linux via distro package manager or source build from the [installation guide](https://github.com/tsl0922/ttyd#installation))
 - [tmux](https://github.com/tmux/tmux) installed
 - [Tailscale](https://tailscale.com/) configured with HTTPS enabled (`tailscale cert`)
 - remobi installed (`npm install -g remobi`)
@@ -17,7 +16,7 @@ Expose a tmux session as a mobile-friendly web terminal over your Tailscale netw
 remobi serve
 ```
 
-This builds the overlay in memory, starts ttyd on an internal port, and serves on `:7681` with full PWA support (manifest, icons, meta tags).
+This bundles the browser client in memory, starts remobi's built-in HTTP and WebSocket server, and spawns a local PTY-backed terminal session on `:7681` with full PWA support.
 
 By default `remobi serve` binds to `127.0.0.1`, so it is not exposed on your LAN. Tailscale Serve is the thing that publishes it.
 
@@ -57,7 +56,6 @@ function webtermup() {
   local port=${2:-7681}
 
   pkill -f "remobi serve.*--port $port" 2>/dev/null
-  pkill -f "ttyd.*--port $port" 2>/dev/null
 
   remobi serve --no-sleep --port $port -- tmux new-session -A -s "$session" &!
 
@@ -69,42 +67,15 @@ function webtermup() {
 function webtermdown() {
   local port=${1:-7681}
   pkill -f "remobi serve.*--port $port" 2>/dev/null
-  pkill -f "ttyd.*--port $port" 2>/dev/null
   tailscale serve --https=443 off 2>/dev/null
   echo "Web terminal stopped"
 }
 ```
 
-## Advanced: manual build + ttyd
+## Legacy ttyd notes
 
-If you are tempted to run `remobi serve --host 0.0.0.0`, be explicit about the trade-off: that bypasses the localhost-only default and exposes terminal control directly on the bound network interface. Prefer keeping remobi on loopback and letting Tailscale handle reachability.
-
-For cases where you need direct control over ttyd (e.g. custom flags, separate processes):
-
-### 1. Build the overlay
-
-```bash
-remobi build --output ~/.cache/remobi/index.html
-```
-
-Always rebuild before starting to avoid stale overlay issues.
-
-### 2. Start ttyd with the overlay
+Current remobi releases do not depend on `ttyd`. If you are migrating an older setup, move it to `remobi serve` rather than trying to preserve the old `ttyd` path.
 
-```bash
-ttyd -i 127.0.0.1 --port 7681 --writable \
-  --index ~/.cache/remobi/index.html \
-  -t 'theme={"background":"#1e1e2e","foreground":"#cdd6f4"}' \
-  -t 'fontFamily="JetBrainsMono NFM, monospace"' \
-  -t 'scrollSensitivity=3' \
-  -t 'disableLeaveAlert=true' \
-  tmux new-session -A -s main
-```
-
-### 3. Expose via Tailscale Serve
-
-```bash
-tailscale serve --bg 7681
-```
+The old `ttyd` docs in this repo are historical only and are not a supported setup path on current releases.
 
-Note: with the manual approach, PWA file refs (`/manifest.json`, `/apple-touch-icon.png`) will 404 — ttyd only serves a single HTML file. The inline SVG favicon still works. Use `remobi serve` for full PWA support.
+If you are tempted to run `remobi serve --host 0.0.0.0`, be explicit about the trade-off: that bypasses the localhost-only default and exposes terminal control directly on the bound network interface. Prefer keeping remobi on loopback and letting Tailscale handle reachability.

.agents/skills/remobi-setup/references/ttyd-flags.md

@@ -1,8 +1,8 @@
 # Recommended ttyd flags
 
-Reference for ttyd flags that work well with remobi.
+Historical reference for old ttyd-based remobi setups.
 
-> **Note:** `remobi serve` generates these flags automatically from your config. This guide is for manual `ttyd` usage with `remobi build`.
+> **Legacy only:** current remobi releases no longer use `ttyd`, `remobi serve` does not generate ttyd flags, and `remobi build` is deprecated. Use `remobi serve` for supported setups. Keep this page only for understanding or migrating old pre-runtime installs.
 
 ## Essential flags
 

.github/workflows/ci.yml

@@ -2,23 +2,26 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, dev]
   pull_request:
-    branches: [main]
+    branches: [main, dev]
 
 jobs:
   check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: jdx/mise-action@v3
+      # node-pty stable does not ship Linux prebuilds, so CI must support source builds.
+      - name: Verify native build prerequisites
+        run: |
+          python3 --version
+          node-gyp --version
       - run: pnpm install
       - run: pnpm exec playwright install --with-deps chromium webkit
       - run: pnpm test
       - run: pnpm run build:dist
       - run: pnpm run test:pw
-      - name: Validate build pipeline (inject mode, no ttyd needed)
-        run: echo '<html><head></head><body></body></html>' | npx tsx cli.ts inject > /dev/null
       - run: pnpm run check
       - run: pnpm run lint:ox
       - run: pnpm run lint:typos
@@ -27,7 +30,7 @@ jobs:
       - run: pnpm exec tsc --noEmit
 
   release:
-    if: github.ref == 'refs/heads/main'
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev'
     needs: check
     runs-on: ubuntu-latest
     permissions:
@@ -40,6 +43,10 @@ jobs:
         with:
           fetch-depth: 0
       - uses: jdx/mise-action@v3
+      - name: Verify native build prerequisites
+        run: |
+          python3 --version
+          node-gyp --version
       - run: pnpm install
       - run: npx semantic-release
         env:

.hk-hooks/commit-msg

@@ -1,2 +1,5 @@
 #!/bin/sh
-exec hk run commit-msg "$@"
+set -eu
+
+hk run commit-msg "$@"
+pnpm exec tsx scripts/check-breaking-footer.ts "$1"

.releaserc.json

@@ -1,5 +1,12 @@
 {
-	"branches": ["main"],
+	"branches": [
+		"main",
+		{
+			"name": "dev",
+			"channel": "dev",
+			"prerelease": "dev"
+		}
+	],
 	"plugins": [
 		"@semantic-release/commit-analyzer",
 		"@semantic-release/release-notes-generator",

AGENTS.md

@@ -4,19 +4,21 @@ Monitor and control your coding agents from your phone. Touch controls for tmux
 
 ## Architecture
 
-Pure TypeScript + DOM API — no framework. Transpiles to JS via tsdown for npm distribution. Produces a single `index.html` for ttyd's `--index` flag via esbuild.
+Pure TypeScript + DOM API — no framework. Transpiles to JS via tsdown for npm distribution. Bundles a browser client via esbuild and serves it from Node.
 
 ## Stack
 
 - **Node 22+** — runtime
 - **pnpm** — package manager
-- **esbuild** — browser bundle (overlay JS)
+- **esbuild** — browser client bundle
 - **tsdown** — transpile TS → JS for npm publish
 - **vitest** — test runner
 - **TypeScript (strict)** — no `any`, discriminated unions for actions
 - **Biome** — lint + format
 - **happy-dom** — DOM testing
 - **Hono** — HTTP + WebSocket server (`remobi serve`)
+- **node-pty** — PTY bridge for `remobi serve`
+- **xterm.js** — browser terminal rendering
 
 ## Key Commands
 
@@ -26,7 +28,7 @@ pnpm test              # Run all tests
 pnpm run test:pw       # Playwright e2e tests (chromium + webkit)
 pnpm run check         # Biome lint + format check
 pnpm run check:fix     # Auto-fix lint + format
-pnpm run build         # Build dist/index.html (dev-time, uses tsx)
+pnpm run build         # Deprecated legacy command
 pnpm run build:dist    # Transpile for publishing (tsdown)
 ```
 
@@ -51,15 +53,15 @@ Commits must follow [Conventional Commits](https://www.conventionalcommits.org/)
 
 - Format: `type(scope): description`
 - Types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `ci`, `perf`, `style`, `build`, `revert`
-- Breaking changes: `!` after type/scope or `BREAKING CHANGE:` in footer
+- Breaking changes: include a `BREAKING CHANGE:` footer. `!` after type/scope is optional shorthand only and must be paired with the footer because semantic-release major detection relies on the footer.
 
 **Choosing the right type matters** — it controls whether semantic-release publishes to npm:
 
 | Type | Release | When to use |
 |------|---------|-------------|
 | `fix` | patch | Bug fix **visible to package consumers** (runtime behaviour, CLI output, published types) |
 | `feat` | minor | New feature visible to consumers |
-| `fix!`/`feat!` | major | Breaking change to public API |
+| `BREAKING CHANGE:` footer | major | Breaking change to public API; `!` is optional shorthand but not sufficient on its own in this repo |
 | `ci` | none | CI/CD workflow changes (GitHub Actions, release config) |
 | `chore` | none | Tooling, deps, repo hygiene — anything not shipped to consumers |
 | `docs` | none | Documentation only |
@@ -96,17 +98,20 @@ Commits must follow [Conventional Commits](https://www.conventionalcommits.org/)
 - `src/reconnect.ts` — connection loss overlay
 - `src/overlay-entry.ts` — IIFE entry point for browser bundle
 - `styles/base.css` — all CSS
-- `cli.ts` — CLI: build, inject, init, serve, --version
-- `build.ts` — build pipeline: bundle → inject → output
+- `cli.ts` — CLI: serve, init, deprecated build/inject, --version
+- `build.ts` — browser client bundling + HTML rendering
 
 ## Publishing
 
 - Transpiles to JS via tsdown: `bin` → `dist/cli.mjs`, `exports` → `dist/*.mjs` + `dist/*.d.mts`
 - `files` array controls what's published: `dist/`, `styles/`, `src/pwa/icons/`, `README.md`, `CHANGELOG.md`, `LICENSE`
 - CI: `.github/workflows/ci.yml` — pnpm test + biome check
-- Release: `release` job in `.github/workflows/ci.yml` — semantic-release on push to main, gated on `check` job
+- Release: `release` job in `.github/workflows/ci.yml` — semantic-release on push to `main` and `dev`, gated on `check` job
   - Versioning, changelog, npm publish, and GitHub Release are all automated
   - `npx semantic-release --dry-run` for local verification
+  - Stable channel: `main` → npm `latest`
+  - Prerelease channel: `dev` → npm `dev` + GitHub prereleases
+  - Promote experimental releases by merging `dev` into `main`
   - Release triggers: `feat:` → minor, `fix:` → patch, `BREAKING CHANGE` → major
   - No release: `chore:`, `docs:`, `refactor:`, `test:`, `ci:`
 - See **Local Development** above for running from source

CHANGELOG.md

@@ -1,3 +1,32 @@
+# [1.0.0-dev.1](https://github.com/connorads/remobi/compare/v0.5.1-dev.2...v1.0.0-dev.1) (2026-03-27)
+
+
+### chore
+
+* mark built-in runtime migration as breaking ([20d466b](https://github.com/connorads/remobi/commit/20d466b68d861c697b90b51524f7a2956ca33e50))
+
+
+### BREAKING CHANGES
+
+* remobi replaces the ttyd-based runtime with the built-in terminal runtime.
+
+## [0.5.1-dev.2](https://github.com/connorads/remobi/compare/v0.5.1-dev.1...v0.5.1-dev.2) (2026-03-24)
+
+
+### Bug Fixes
+
+* load Unicode11Addon on headless mirror to align character widths ([54a3ec5](https://github.com/connorads/remobi/commit/54a3ec5b875098758d1a1b3d466f7517e025cc57))
+* remove terminal padding that exposed white document background ([cd92504](https://github.com/connorads/remobi/commit/cd92504c93bbc223979a3c77b60a90b0f10a13da)), closes [#terminal](https://github.com/connorads/remobi/issues/terminal)
+* set document background from theme to eliminate white border ([5c821ca](https://github.com/connorads/remobi/commit/5c821ca9d7e4aaea6ac6531bc93116b24166807e)), closes [#1e1e2e](https://github.com/connorads/remobi/issues/1e1e2e) [#terminal-container](https://github.com/connorads/remobi/issues/terminal-container) [#terminal](https://github.com/connorads/remobi/issues/terminal)
+* strip TMUX env vars via destructuring instead of undefined assignment ([33fa6ec](https://github.com/connorads/remobi/commit/33fa6ec2ee550db3d88e789afd989735918685db))
+
+## [0.5.1-dev.1](https://github.com/connorads/remobi/compare/v0.5.0...v0.5.1-dev.1) (2026-03-22)
+
+
+### Bug Fixes
+
+* guard handleClientMessage against resize on exited PTY ([41043ee](https://github.com/connorads/remobi/commit/41043eee23b86005d180ecae770c1055aaa538de))
+
 # [0.5.0](https://github.com/connorads/remobi/compare/v0.4.0...v0.5.0) (2026-03-20)