remobi 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## 0.1.0 — 2026-03-15
+
+- Changed: overlay is now pre-built as an IIFE during `build:dist` — faster `remobi serve` startup (no runtime esbuild), smaller install footprint (esbuild moved to devDependencies). Dev mode falls back to esbuild-from-source when `dist/overlay.iife.js` is absent.
+
+- Breaking: migrated from Bun to Node.js 22+ with pnpm. Runtime is now Node, bundler is esbuild, test runner is vitest, transpiler is tsdown. `remobi serve` uses Hono + @hono/node-ws for HTTP/WS. Package now ships transpiled JS (`dist/`) instead of TypeScript source.
+
+- Internal: expanded oxlint — `suspicious` + `perf` categories, `import/no-cycle`, `import/no-self-import`, `typescript/no-non-null-asserted-optional-chain`, `unicorn/throw-new-error` (141 rules total).
+- Internal: expanded Biome — `noExcessiveCognitiveComplexity` (warn, max 25), `useFilenamingConvention` (kebab-case).
+- Internal: added knip for unused export/dependency detection. Removed 11 unused exports, removed redundant `happy-dom` devDep.
+- Internal: added publint for npm package validation. Fixed `pkg.repository.url` to `git+https://` convention.
+- Internal: added typos spell checker via mise.
+- Internal: added hk pre-commit hooks (biome, oxlint, typos).
+- Internal: added knip, publint, typos to CI pipeline and prepublishOnly gate.
+- Changed: removed `ttyd` from `mise.toml` (unsupported on macOS arm64 via current aqua metadata) and updated ttyd install guidance to be macOS/Linux friendly (`brew` on macOS, distro/source options on Linux).
+- Changed: shipped drawer defaults now stick to stock tmux bindings for split/session/window/copy actions and no longer include opinionated `Git`, `Files`, or `Links` buttons.
+
+- Removed: plugin system (`RemobiPlugin`, `UISlot`, `UIContributionCollector`, plugin manager, UI contributions, build-time resolution, `config.plugins`). Hooks and actions remain as core infrastructure. The plugin API can be reintroduced when there's a concrete second use case.
+
+- Fixed: visibilitychange listener leak in reconnect dispose path — the anonymous listener was never removed, causing a leak on each dispose/re-init cycle.
+- Fixed: reconnect overlay now retries on any overlay tap, keeps the button focused for keyboard `Enter`, and guards against duplicate reload attempts.
+- Fixed: unhandled promise rejection when `document.fonts.ready` fails — font loading failure is non-critical, terminal still works.
+- Internal: `bun test --coverage` reporting via `test:coverage` script.
+- Internal: shared `mockTerminal` test fixture extracted from 9 test files.
+- Internal: new tests for `applyTheme`, `haptic`, and `checkLandscapeKeyboard`.
+
+- Added: reconnect overlay — detects connection loss via WebSocket interception and shows a full-screen "Connection lost" overlay with a Reconnect button. Auto-reconnects when the browser comes back online. Enabled by default (`reconnect: { enabled: true }`), disable with `reconnect: { enabled: false }`.
+
+- Added: Remotion-based demo video in `demo/` — programmatically rendered, Catppuccin Mocha themed.
+- Added: oxlint with `consistent-type-assertions: never` rule to prevent unsafe type assertions.
+- Changed: `waitForTerm` now rejects after timeout (default 10s) instead of polling indefinitely.
+- Changed: plugin manager validates plugin shape at init — invalid plugins are skipped with a warning.
+- Changed: help overlay rewritten to DOM API (no innerHTML), eliminating XSS surface.
+- Changed: PWA meta-tag values are now HTML-attribute-escaped.
+- Added: unit tests for `buildTtydArgs`, `randomInternalPort`, `waitForTerm`, and plugin validation.
+- Added: `bun run build` step in CI workflow.
+- Added: `remobi serve --no-sleep` flag — prevents macOS system sleep while serving by wrapping ttyd with `caffeinate -s -w <pid>`. The assertion is held for exactly the lifetime of the server and dropped automatically on shutdown. Gracefully ignored with a warning on non-macOS platforms.
+- Added: keep-awake guide (`docs/guides/keep-awake.md`) covering `--no-sleep`, persistent pmset settings, nix-darwin config, and lid-close behaviour.
+- Added: mobile-friendly tmux config guide (`docs/guides/mobile-tmux.md`) and optional tmux optimisation step in setup skill.
+- Added: agent setup skill (`skills/remobi-setup/SKILL.md`), guide (`docs/guides/agent-setup.md`), and README collapsible prompt for AI-assisted configuration.
+- Added: `remobi serve` — single command to run remobi with full PWA support. Builds overlay in memory, manages ttyd lifecycle, serves manifest + icons + WebSocket relay. Replaces the multi-step build + ttyd + proxy workflow.
+- Added: PWA support — web app manifest, 192/512px icons, apple-touch-icon, theme-color meta tags for "Add to Home Screen" installability on iOS and Android.
+- Added: `pwa` config section (`enabled`, `shortName`, `themeColor`) — controls manifest generation and meta tag injection. `shortName` defaults to `name` when absent.
+- Added: top-level `name` config field (default `'remobi'`) — used as document title, PWA manifest name, and apple-mobile-web-app-title. Replaces `pwa.name` and `pwa.shortName` (the latter is now optional and falls back to `name`).
+- Added: default toolbar backspace button (`⌫`, sends `\x7f`) to provide reliable deletion on mobile keyboards when IME composition behaviour is inconsistent.
+- v0.2 extensibility and DX milestone complete: action registry, hook system, plugin manager, UI contributions, declarative button customisation, .local config overrides, plugin guide, Bun-only ADR, e2e scaffolding. Closes #1.
+- Added: e2e smoke test scaffold (`tests/e2e/smoke.test.ts`) — checks ttyd availability, skips gracefully when absent, tests HTML serving and `remobi inject` pipe path against a real ttyd process. Closes #9.
+- Added: ADR `docs/decisions/001-bun-only.md` — documents the decision to remain Bun-only, the Bun-specific APIs in use, and the conditions under which a Node runtime track would be considered. Closes #11.
+- Added: plugin author guide (`docs/guides/plugins.md`) covering hooks, UI contributions, custom actions, and cleanup patterns. Closes #10.
+- Added: stable public API surface defined in README — semver policy documents which import paths are public, what constitutes major/minor/patch. Closes #4.
+- Added: UI contribution API for plugins — `context.ui.add(slot, button, priority?)` lets plugins contribute buttons to `'toolbar.row1'`, `'toolbar.row2'`, or `'drawer'` slots. Contributions are merged (appended) after config buttons, sorted by priority. Closes #8.
+- Added: per-machine config overrides via `.local` config file — place `remobi.config.local.ts` next to your shared `remobi.config.ts` to apply machine-specific overrides (gitignore the `.local` file). Merged on top of the shared config using the same `RemobiConfigOverrides` schema. Closes #12.
+- Added: declarative button customisation — toolbar rows and drawer buttons now accept `ButtonArrayInput`: a plain array (replace) or a function `(defaults) => newArray`. Standard JS array methods cover all customisation needs (filter, map, spread, etc.). Closes #13.
+
+- Breaking: unified toolbar/drawer model to `ControlButton` (`id`, `label`, `description`, `action`) and renamed `drawer.commands` to `drawer.buttons`.
+- Changed: touch scrolling defaults to wheel semantics for better behaviour across OpenCode, Claude Code, and plain tmux shells.
+- Added: dynamic help overlay rendered from current config (no stale hardcoded sections).
+- Fixed: help overlay is now fail-safe and cannot block core overlay init.
+- Fixed: viewport/keyboard height handling and document scroll lock to reduce white-gap/rubber-band issues on mobile.
+- Added: runtime config validation with path-based errors and unknown-key checks at CLI load boundaries.
+- Changed: config validation errors now include received-value previews, and CLI validates merged resolved config before build/inject execution.
+- Added: stricter CLI parsing (`-c`/`-o`/`-n`, unknown-flag errors) plus `--dry-run` for `build` and `inject`. Closes #3.
+- Changed: toolbar/drawer button handling now runs through a shared action registry abstraction. Closes #5.
+- Added: typed hook registry for overlay lifecycle and terminal send pipeline with ordered execution and error isolation. Closes #6.
+- Added: plugin manager primitives (`RemobiPlugin`, setup/dispose lifecycle, failure isolation) and plugin-aware `init(..., hooks, plugins)` entry. Closes #7.
+- Added: config `plugins` array support in CLI build/inject path with resolved local specifiers.
+- Changed: CLI config validation remains strict; legacy config shapes are not auto-normalised.
+- Tests: expanded integration/config/height coverage for the new config model and viewport logic.
+- Added: `gestures.swipe.left`/`right` (data to send on swipe) and `leftLabel`/`rightLabel` (help overlay text) — defaults match previous hardcoded behaviour (`\x02n`/`\x02p`, next/previous tmux window).
+- Added: `mobile.initData` (string | null) — arbitrary data sent to the terminal on mobile init when viewport is below `mobile.widthThreshold` (default 768px). Useful for auto-zooming a tmux pane (`'\x02z'`) or any other mobile-specific setup.
+- Added: `floatingButtons` config — always-visible buttons on touch devices using the same `ControlButton` schema as toolbar/drawer. Renders in the help overlay when non-empty.
+- Breaking: `floatingButtons` changed from a flat `ControlButton[]` to `FloatingButtonGroup[]`. Each group has a `position` (`'top-left' | 'top-right' | 'top-centre' | 'bottom-left' | 'bottom-right' | 'bottom-centre' | 'centre-left' | 'centre-right'`), optional `direction` (`'row' | 'column'`, default `'row'`), and a `buttons` array. Migrate: `floatingButtons: [btn]` → `floatingButtons: [{ position: 'top-left', buttons: [btn] }]`.
+- Changed: Tailscale Serve guide now recommends always rebuilding the overlay before start; removed version-hash cache-key snippet to prevent stale build issues.
+- Changed: default toolbar now uses explicit tmux `Prefix` (`C-b`) and `Alt+Enter` buttons for more predictable mobile input.
+- Added: new drawer `Combo` action (`combo-picker`) that opens a small combo input modal for explicit Ctrl/Alt key sends.
+- Added: default toolbar `q` button (row 2, left) for quitting interactive TUIs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Connor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,302 @@
+# remobi
+
+[![CI](https://github.com/connorads/remobi/actions/workflows/ci.yml/badge.svg)](https://github.com/connorads/remobi/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/remobi)](https://www.npmjs.com/package/remobi)
+[![licence](https://img.shields.io/npm/l/remobi)](LICENSE)
+
+**Your terminal. Everywhere.**
+
+Running coding agents in tmux? remobi lets you monitor and control them from your phone. Swipe between windows, scroll through output, pinch to zoom, tap buttons for tmux commands. Same session, touch-native controls. No workflow changes.
+
+[ttyd](https://github.com/tsl0922/ttyd) gives you a terminal in a browser. On mobile, it's unusable — no toolbar, no gestures, tiny unresizable text. remobi adds a touch overlay on top. One command. Install it like a native app.
+
+<div align="center">
+  <!-- Upload demo/out/demo.mp4 via GitHub issue/PR drag-and-drop, then replace the src below -->
+  <video src="https://github.com/user-attachments/assets/PLACEHOLDER" width="300" autoplay loop muted playsinline></video>
+</div>
+
+## Who this is for
+
+- You run coding agents (Claude Code, OpenCode, Codex, pi, etc.) in tmux and want to monitor or interact from your phone
+- You're a terminal-first developer who wants your full tmux setup accessible anywhere
+- You want self-hosted mobile terminal access without changing your existing workflow
+
+## Why remobi
+
+- **One command** — `remobi serve` builds the overlay, manages ttyd, serves with PWA support
+- **Swipe between panes** — gesture navigation, no prefix key fumbling on a phone screen
+- **Pinch to zoom** — resize text like every other app on your phone
+- **Install to your home screen** — standalone PWA, looks and feels native
+- **Config-driven** — your buttons, your gestures, your layout. Or let an AI agent configure it for you
+- **Self-hosted** — your data never leaves your network. Bring your own tunnel (Tailscale, Cloudflare, ngrok)
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) ≥ 22
+- [ttyd](https://github.com/tsl0922/ttyd) — must be on PATH for `remobi serve` and `remobi build` (they spawn a temporary ttyd to fetch base HTML). Install on macOS with `brew install ttyd`; on Linux use your distro package manager or build from source via the [ttyd installation guide](https://github.com/tsl0922/ttyd#installation). `remobi inject` pipes HTML from stdin and does **not** require ttyd — useful for CI or environments where ttyd isn't installed locally.
+- [tmux](https://github.com/tmux/tmux) (the target multiplexer)
+
+remobi uses standard ttyd flags (`--writable`, `-t`, `-i`) and should work with any recent ttyd release.
+
+## Quick start
+
+```bash
+# 1. Install
+npm install -g remobi
+
+# 2. Start (builds overlay, manages ttyd, serves with PWA support)
+remobi serve
+```
+
+For local development, use `pnpm link --global` from the repo root instead of `npm install -g remobi`.
+
+Open `http://localhost:7681` on your phone. Add to Home Screen for an app-like experience.
+
+## CLI reference
+
+```
+remobi serve [--config <path>] [--port <n>] [-- <command...>]
+  Build overlay in memory, manage ttyd, serve with PWA support.
+  Default port: 7681. Default command: tmux new-session -A -s main
+  Example: remobi serve --port 8080 -- tmux new -As dev
+
+remobi build [--config <path>] [--output <path>] [--dry-run]
+  Build patched index.html for ttyd --index flag (advanced).
+  Default output: dist/index.html
+
+remobi inject [--config <path>] [--dry-run]
+  Pipe mode: reads ttyd HTML from stdin, outputs patched HTML to stdout.
+  Example: curl -s http://localhost:7681/ | remobi inject > patched.html
+
+remobi init
+  Scaffold a remobi.config.ts with commented defaults.
+
+remobi --version
+remobi --help
+```
+
+Short flags: `-c` (`--config`), `-o` (`--output`), `-p` (`--port`), `-n` (`--dry-run`).
+
+### Config resolution
+
+When `--config` is not specified, remobi searches:
+
+1. `remobi.config.ts` / `.js` in the current directory
+2. `~/.config/remobi/remobi.config.ts` / `.js` (XDG fallback)
+
+## Configuration
+
+Create `remobi.config.ts` (or run `remobi init`):
+
+```typescript
+import { defineConfig } from 'remobi/config'
+
+export default defineConfig({
+  font: {
+    family: 'JetBrainsMono NFM, monospace',
+    mobileSizeDefault: 16,
+    sizeRange: [8, 32],
+  },
+  toolbar: {
+    row1: [
+      { id: 'esc', label: 'Esc', description: 'Send Escape key', action: { type: 'send', data: '\x1b' } },
+      { id: 'tmux-prefix', label: 'Prefix', description: 'Send tmux prefix key (Ctrl-B)', action: { type: 'send', data: '\x02' } },
+      // ...
+    ],
+    row2: [
+      { id: 'alt-enter', label: 'M-↵', description: 'Send Alt+Enter (ESC + Enter)', action: { type: 'send', data: '\x1b\r' } },
+      { id: 'drawer-toggle', label: '☰ More', description: 'Open command drawer', action: { type: 'drawer-toggle' } },
+      { id: 'paste', label: 'Paste', description: 'Paste from clipboard', action: { type: 'paste' } },
+      { id: 'backspace', label: '⌫', description: 'Send Backspace key', action: { type: 'send', data: '\x7f' } },
+      // ...
+    ],
+  },
+  drawer: {
+    buttons: [
+      { id: 'tmux-new-window', label: '+ Win', description: 'Create tmux window', action: { type: 'send', data: '\x02c' } },
+      { id: 'tmux-split-vertical', label: 'Split |', description: 'Split pane vertically', action: { type: 'send', data: '\x02%' } },
+      { id: 'combo-picker', label: 'Combo', description: 'Open combo sender (Ctrl/Alt + key)', action: { type: 'combo-picker' } },
+      // ...
+    ],
+  },
+  gestures: {
+    swipe: {
+      enabled: true,
+      left: '\x02n',         // data sent on swipe left (default: next tmux window)
+      right: '\x02p',        // data sent on swipe right (default: prev tmux window)
+      leftLabel: 'Next tmux window',    // shown in help overlay
+      rightLabel: 'Previous tmux window',
+    },
+    scroll: {
+      enabled: true,
+      strategy: 'wheel',
+      sensitivity: 40,
+      wheelIntervalMs: 24,
+    },
+    pinch: { enabled: true },
+  },
+  mobile: {
+    initData: '\x02z',     // send on mobile load when viewport < widthThreshold
+    widthThreshold: 768,   // px — default matches common phone/tablet breakpoint
+  },
+  floatingButtons: [
+    {
+      position: 'top-left',
+      buttons: [
+        { id: 'zoom', label: 'Zoom', description: 'Toggle pane zoom', action: { type: 'send', data: '\x02z' } },
+      ],
+    },
+  ],
+})
+```
+
+<details>
+<summary>Configure with an AI agent</summary>
+
+### Install the remobi skill
+
+```bash
+npx skills add connorads/remobi
+```
+
+For a specific agent only (e.g. Claude Code, globally): `npx skills add connorads/remobi -a claude-code -g`
+
+### Or paste this prompt
+
+> Inspect my tmux config (`tmux show-options -g prefix` and `tmux list-keys`), then generate a `remobi.config.ts` tailored to my setup. Allowed root keys: `name theme font toolbar drawer gestures mobile floatingButtons pwa reconnect`. Action types: `send | ctrl-modifier | paste | combo-picker | drawer-toggle`. Use `drawer.buttons` not `drawer.commands`. Validate with `remobi build --dry-run` and fix any errors. Summarise what was configured.
+
+See the full [agent setup guide](docs/guides/agent-setup.md) for examples and escape-code reference.
+
+</details>
+
+All fields are optional — defaults are filled in via `defineConfig()`.
+
+Shipped tmux drawer defaults stick to stock tmux bindings (`c`, `%`, `"`, `s`, `w`, `[`, `?`, `x`, `z`) rather than personal popup workflows.
+
+Replace the drawer entirely with a plain array when you want a fully custom setup:
+
+```typescript
+import { defineConfig } from 'remobi/config'
+
+export default defineConfig({
+  drawer: {
+    buttons: [
+      { id: 'sessions', label: 'Sessions', description: 'Choose tmux session', action: { type: 'send', data: '\x02s' } },
+      { id: 'git', label: 'Git', description: 'Open my tmux git popup', action: { type: 'send', data: '\x02g' } },
+    ],
+  },
+})
+```
+
+At runtime, remobi validates the config object shape and rejects unknown keys with clear path-based errors.
+
+`gestures.scroll.strategy` controls touch scroll behaviour:
+
+- `wheel` (default): sends SGR mouse wheel events with touch-mapped terminal coordinates.
+- `keys`: sends `PageUp` / `PageDown` for app-level paging when preferred.
+
+### Programmatic API
+
+```typescript
+import { defineConfig, serialiseThemeForTtyd } from 'remobi/config'
+import type { RemobiConfig, ControlButton } from 'remobi/types'
+import { init } from 'remobi'
+```
+
+Advanced consumers can use hook registry primitives to observe lifecycle and terminal-send events:
+
+```typescript
+import { createHookRegistry, init } from 'remobi'
+
+const hooks = createHookRegistry()
+hooks.on('beforeSendData', (ctx) => {
+  if (ctx.data.includes('rm -rf /')) return { block: true }
+})
+
+init(undefined, hooks)
+```
+
+## Deployment guides
+
+- [Tailscale Serve](docs/guides/tailscale-serve.md) — expose over your tailnet with HTTPS
+- [Keeping your Mac awake](docs/guides/keep-awake.md) — prevent sleep during remote sessions
+- [ttyd flags](docs/guides/ttyd-flags.md) — recommended ttyd options and theme flags
+- [Mobile pane navigation](docs/guides/mobile-panes.md) — zoom-aware swipe, auto-zoom on load, floating buttons
+- [Mobile-friendly tmux config](docs/guides/mobile-tmux.md) — responsive status bar, popup sizing, binding ergonomics
+- [Agent setup](docs/guides/agent-setup.md) — configure remobi with AI agents
+
+## Architecture
+
+Pure TypeScript + DOM API — no framework. The build bundles all JS/CSS into a single HTML file via esbuild. ttyd handles WebSocket/PTY bridging; remobi only adds the mobile UI overlay.
+
+Key modules:
+
+| Module | Purpose |
+|--------|---------|
+| `src/toolbar/` | Two-row touch toolbar |
+| `src/drawer/` | Command drawer with grid layout |
+| `src/gestures/` | Swipe, pinch, scroll detection |
+| `src/controls/` | Font size, help overlay, scroll buttons |
+| `src/theme/` | Catppuccin Mocha + theme application |
+| `src/viewport/` | Height management, landscape detection |
+| `src/util/` | DOM helpers, terminal, keyboard, haptics |
+
+## Public API and semver
+
+remobi follows semantic versioning. The public API is defined by the following import paths:
+
+| Import path | Contents | Stability |
+|---|---|---|
+| `remobi` | `init`, `defineConfig`, `createHookRegistry`, `RemobiConfig`, `ControlButton`, `ButtonAction`, `ButtonArrayPatch`, `ButtonArrayInput`, `RemobiConfigOverrides`, `HookRegistry` | Public — breaking changes are semver-major |
+| `remobi/config` | `defineConfig`, `mergeConfig`, `defaultConfig`, `serialiseThemeForTtyd` | Public |
+| `remobi/types` | All types in `src/types.ts` | Public |
+
+**Internal modules** (not part of the public API — may change without a major version bump):
+`src/toolbar/`, `src/drawer/`, `src/gestures/`, `src/controls/`, `src/theme/`, `src/viewport/`, `src/util/`, `src/serve.ts`, `src/cli/`, `build.ts`
+
+**Semver policy**:
+- **Major**: removing or renaming a public export, changing a public function signature incompatibly, removing a config field
+- **Minor**: adding new public exports, new optional config fields, new `ButtonArrayInput` operations
+- **Patch**: bug fixes, internal refactors, documentation updates
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm run check     # biome lint + format
+pnpm run build     # build dist/index.html (dev-time, uses tsx)
+```
+
+For local development:
+
+```bash
+cd ~/git/remobi
+pnpm link --global   # remobi CLI available globally
+pnpm run build:dist  # transpile TS → JS (tsdown)
+```
+
+## FAQ
+
+**Is this secure?**
+remobi doesn't handle auth — it's a UI overlay. Use a tunnel or VPN you trust. We recommend [Tailscale](docs/guides/tailscale-serve.md) (deployment guide included) — your session never leaves your tailnet. Cloudflare Tunnel and ngrok also work. Security is your responsibility.
+
+**Why not Termux / Termius / SSH apps?**
+They work. But you're managing SSH keys, losing your tmux setup, and fighting a UI that wasn't built for touch. remobi keeps your exact workflow — same panes, same windows, same bindings — and adds touch controls on top.
+
+**Why not [Happy](https://github.com/slopus/happy) / Claude resume / chat-based mobile apps?**
+Those tools change your workflow. Chat relays route through third-party servers. Claude's resume has limitations. remobi gives you the raw terminal — full power, self-hosted, works with every agent because it works with tmux.
+
+**Why Node?**
+remobi migrated from Bun to Node.js + pnpm for broader compatibility. It transpiles to JS via tsdown for npm distribution and uses esbuild for the browser overlay bundle.
+
+**Is this production-ready?**
+It's v0.1. The author uses it daily. It works. It's also early — feedback welcome, forks encouraged.
+
+## Acknowledgements
+
+remobi is a thin overlay. The heavy lifting is done by [ttyd](https://github.com/tsl0922/ttyd) (terminal sharing over the web) and [xterm.js](https://xtermjs.org/) (terminal rendering in the browser). remobi just adds the mobile touch controls on top.
+
+## Licence
+
+MIT

package/dist/build.d.mts

@@ -0,0 +1,17 @@
+import { RemobiConfig } from "./src/types.mjs";
+
+//#region build.d.ts
+/** Bundle the overlay JS + CSS into strings */
+declare function bundleOverlay(config: RemobiConfig): Promise<{
+  js: string;
+  css: string;
+}>;
+/** Inject remobi overlay into ttyd's HTML */
+declare function injectOverlay(html: string, js: string, css: string, config: RemobiConfig): string;
+/** Full build pipeline: bundle → fetch ttyd HTML → inject → write output */
+declare function build(config: RemobiConfig, outputPath: string): Promise<void>;
+/** Build from stdin HTML (pipe mode) */
+declare function injectFromStdin(config: RemobiConfig): Promise<string>;
+//#endregion
+export { build, bundleOverlay, injectFromStdin, injectOverlay };
+//# sourceMappingURL=build.d.mts.map

package/dist/build.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.mts","names":[],"sources":["../build.ts"],"mappings":";;;;iBAmBsB,aAAA,CAAc,MAAA,EAAQ,YAAA,GAAe,OAAA;EAAU,EAAA;EAAY,GAAA;AAAA;;iBA+FjE,aAAA,CAAc,IAAA,UAAc,EAAA,UAAY,GAAA,UAAa,MAAA,EAAQ,YAAA;;iBAoBvD,KAAA,CAAM,MAAA,EAAQ,YAAA,EAAc,UAAA,WAAqB,OAAA;;iBAQjD,eAAA,CAAgB,MAAA,EAAQ,YAAA,GAAe,OAAA"}

package/dist/build.mjs

@@ -0,0 +1,115 @@
+import { i as generatePwaHtml, n as sleep, r as spawnProcess, t as readStdin } from "./node-compat-BzXgbTV9.mjs";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+//#region build.ts
+function findProjectRoot() {
+	let dir = import.meta.dirname;
+	for (let i = 0; i < 5; i++) {
+		if (existsSync(resolve(dir, "styles/base.css"))) return dir;
+		dir = dirname(dir);
+	}
+	return import.meta.dirname;
+}
+const PROJECT_ROOT = findProjectRoot();
+/** Bundle the overlay JS + CSS into strings */
+async function bundleOverlay(config) {
+	const css = readFileSync(resolve(PROJECT_ROOT, "styles/base.css"), "utf-8");
+	const prebuiltPath = resolve(PROJECT_ROOT, "dist/overlay.iife.js");
+	if (existsSync(prebuiltPath)) {
+		const overlayJs = readFileSync(prebuiltPath, "utf-8");
+		return {
+			js: `globalThis.__remobiConfig=${JSON.stringify(config)};${overlayJs}`,
+			css
+		};
+	}
+	const esbuild = await import("esbuild");
+	const entryCode = `
+import { init, createHookRegistry } from './src/index.ts'
+const hooks = createHookRegistry()
+const config = ${JSON.stringify(config)}
+;(function() { init(config, hooks) })()
+`;
+	const tmpEntry = resolve(PROJECT_ROOT, ".tmp-entry.ts");
+	writeFileSync(tmpEntry, entryCode);
+	try {
+		const output = (await esbuild.build({
+			entryPoints: [tmpEntry],
+			bundle: true,
+			platform: "browser",
+			minify: true,
+			format: "esm",
+			write: false
+		})).outputFiles[0];
+		if (!output) throw new Error("Build produced no output");
+		return {
+			js: output.text,
+			css
+		};
+	} finally {
+		try {
+			unlinkSync(tmpEntry);
+		} catch {}
+	}
+}
+/** Fetch ttyd's base index.html by starting a temporary instance */
+async function fetchTtydHtml() {
+	const port = 19876 + Math.floor(Math.random() * 1e3);
+	const proc = spawnProcess([
+		"ttyd",
+		"--port",
+		String(port),
+		"-i",
+		"127.0.0.1",
+		"echo",
+		"noop"
+	], {
+		stdout: "ignore",
+		stderr: "ignore"
+	});
+	let html = "";
+	for (let i = 0; i < 30; i++) {
+		await sleep(200);
+		try {
+			const resp = await fetch(`http://127.0.0.1:${port}/`);
+			if (resp.ok) {
+				html = await resp.text();
+				break;
+			}
+		} catch {}
+	}
+	proc.kill();
+	await proc.exited;
+	if (!html) throw new Error("Failed to fetch ttyd index.html — is ttyd installed and on PATH?\nInstall ttyd: macOS `brew install ttyd`; Linux use your distro package manager or build from source: https://github.com/tsl0922/ttyd#installation\nAlternatively, pipe existing ttyd HTML via `remobi inject` (no ttyd required).");
+	return html;
+}
+/** Synchronous script that captures WebSocket instances for reconnect detection */
+const WS_INTERCEPTOR = "<script>(function(){var O=WebSocket,S=window.__remobiSockets=[];window.WebSocket=class extends O{constructor(u,p){super(u,p);S.push(this)}}})()<\/script>";
+/** Inject remobi overlay into ttyd's HTML */
+function injectOverlay(html, js, css, config) {
+	const fontLink = `<link rel="preload" href="${config.font.cdnUrl}" as="style" onload="this.rel='stylesheet'">`;
+	const viewport = "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0, maximum-scale=1, viewport-fit=cover\">";
+	const styleTag = `<style>${css}</style>`;
+	const scriptTag = `<script type="module">${js.replace(/<(?=\/script)/gi, "\\x3c")}<\/script>`;
+	const pwaHtml = config.pwa.enabled ? `${generatePwaHtml(config.name, config.pwa)}\n` : "";
+	const injection = `${config.reconnect.enabled ? `${WS_INTERCEPTOR}\n` : ""}${fontLink}\n${viewport}\n${pwaHtml}${styleTag}\n${scriptTag}\n`;
+	const idx = html.indexOf("</head>");
+	if (idx === -1) throw new Error("No </head> found in base HTML");
+	return html.slice(0, idx) + injection + html.slice(idx);
+}
+/** Full build pipeline: bundle → fetch ttyd HTML → inject → write output */
+async function build(config, outputPath) {
+	const { js, css } = await bundleOverlay(config);
+	writeFileSync(outputPath, injectOverlay(await fetchTtydHtml(), js, css, config));
+}
+/** Build from stdin HTML (pipe mode) */
+async function injectFromStdin(config) {
+	const { js, css } = await bundleOverlay(config);
+	const stdin = await readStdin();
+	if (stdin.trim().length === 0) throw new Error("remobi inject expects piped ttyd HTML on stdin");
+	return injectOverlay(stdin, js, css, config);
+}
+
+//#endregion
+export { build, bundleOverlay, injectFromStdin, injectOverlay };
+//# sourceMappingURL=build.mjs.map

package/dist/build.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.mjs","names":[],"sources":["../build.ts"],"sourcesContent":["import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'\nimport { dirname, resolve } from 'node:path'\nimport { generatePwaHtml } from './src/pwa/meta-tags'\nimport type { RemobiConfig } from './src/types'\nimport { readStdin, sleep, spawnProcess } from './src/util/node-compat'\n\n// Walk up from module location to find project root (where styles/ lives)\nfunction findProjectRoot(): string {\n\tlet dir = import.meta.dirname\n\tfor (let i = 0; i < 5; i++) {\n\t\tif (existsSync(resolve(dir, 'styles/base.css'))) return dir\n\t\tdir = dirname(dir)\n\t}\n\treturn import.meta.dirname\n}\n\nconst PROJECT_ROOT = findProjectRoot()\n\n/** Bundle the overlay JS + CSS into strings */\nexport async function bundleOverlay(config: RemobiConfig): Promise<{ js: string; css: string }> {\n\t// Read CSS\n\tconst cssPath = resolve(PROJECT_ROOT, 'styles/base.css')\n\tconst css = readFileSync(cssPath, 'utf-8')\n\n\t// Pre-built overlay: read dist/overlay.iife.js and prepend config via globalThis\n\tconst prebuiltPath = resolve(PROJECT_ROOT, 'dist/overlay.iife.js')\n\tif (existsSync(prebuiltPath)) {\n\t\tconst overlayJs = readFileSync(prebuiltPath, 'utf-8')\n\t\tconst js = `globalThis.__remobiConfig=${JSON.stringify(config)};${overlayJs}`\n\t\treturn { js, css }\n\t}\n\n\t// Dev fallback: bundle from source via esbuild (requires src/ and esbuild)\n\tconst esbuild = await import('esbuild')\n\n\tconst configJson = JSON.stringify(config)\n\tconst entryCode = `\nimport { init, createHookRegistry } from './src/index.ts'\nconst hooks = createHookRegistry()\nconst config = ${configJson}\n;(function() { init(config, hooks) })()\n`\n\n\tconst tmpEntry = resolve(PROJECT_ROOT, '.tmp-entry.ts')\n\twriteFileSync(tmpEntry, entryCode)\n\n\ttry {\n\t\tconst result = await esbuild.build({\n\t\t\tentryPoints: [tmpEntry],\n\t\t\tbundle: true,\n\t\t\tplatform: 'browser',\n\t\t\tminify: true,\n\t\t\tformat: 'esm',\n\t\t\twrite: false,\n\t\t})\n\n\t\tconst output = result.outputFiles[0]\n\t\tif (!output) {\n\t\t\tthrow new Error('Build produced no output')\n\t\t}\n\t\tconst js = output.text\n\n\t\treturn { js, css }\n\t} finally {\n\t\ttry {\n\t\t\tunlinkSync(tmpEntry)\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t}\n}\n\n/** Fetch ttyd's base index.html by starting a temporary instance */\nasync function fetchTtydHtml(): Promise<string> {\n\tconst port = 19876 + Math.floor(Math.random() * 1000)\n\tconst proc = spawnProcess(['ttyd', '--port', String(port), '-i', '127.0.0.1', 'echo', 'noop'], {\n\t\tstdout: 'ignore',\n\t\tstderr: 'ignore',\n\t})\n\n\t// Wait for ttyd to start\n\tlet html = ''\n\tfor (let i = 0; i < 30; i++) {\n\t\tawait sleep(200)\n\t\ttry {\n\t\t\tconst resp = await fetch(`http://127.0.0.1:${port}/`)\n\t\t\tif (resp.ok) {\n\t\t\t\thtml = await resp.text()\n\t\t\t\tbreak\n\t\t\t}\n\t\t} catch {\n\t\t\t// not ready yet\n\t\t}\n\t}\n\n\tproc.kill()\n\tawait proc.exited\n\n\tif (!html) {\n\t\tthrow new Error(\n\t\t\t'Failed to fetch ttyd index.html — is ttyd installed and on PATH?\\n' +\n\t\t\t\t'Install ttyd: macOS `brew install ttyd`; Linux use your distro package manager or build from source: https://github.com/tsl0922/ttyd#installation\\n' +\n\t\t\t\t'Alternatively, pipe existing ttyd HTML via `remobi inject` (no ttyd required).',\n\t\t)\n\t}\n\n\treturn html\n}\n\n/** Synchronous script that captures WebSocket instances for reconnect detection */\nconst WS_INTERCEPTOR =\n\t'<script>(function(){var O=WebSocket,S=window.__remobiSockets=[];window.WebSocket=class extends O{constructor(u,p){super(u,p);S.push(this)}}})()</script>'\n\n/** Inject remobi overlay into ttyd's HTML */\nexport function injectOverlay(html: string, js: string, css: string, config: RemobiConfig): string {\n\tconst fontLink = `<link rel=\"preload\" href=\"${config.font.cdnUrl}\" as=\"style\" onload=\"this.rel='stylesheet'\">`\n\tconst viewport =\n\t\t'<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0, maximum-scale=1, viewport-fit=cover\">'\n\tconst styleTag = `<style>${css}</style>`\n\tconst safeJs = js.replace(/<(?=\\/script)/gi, '\\\\x3c')\n\tconst scriptTag = `<script type=\"module\">${safeJs}</script>`\n\tconst pwaHtml = config.pwa.enabled ? `${generatePwaHtml(config.name, config.pwa)}\\n` : ''\n\tconst wsScript = config.reconnect.enabled ? `${WS_INTERCEPTOR}\\n` : ''\n\n\tconst injection = `${wsScript}${fontLink}\\n${viewport}\\n${pwaHtml}${styleTag}\\n${scriptTag}\\n`\n\n\t// Avoid String.replace() — minified JS may contain $& which .replace()\n\t// interprets as a special replacement pattern, corrupting the output\n\tconst idx = html.indexOf('</head>')\n\tif (idx === -1) throw new Error('No </head> found in base HTML')\n\treturn html.slice(0, idx) + injection + html.slice(idx)\n}\n\n/** Full build pipeline: bundle → fetch ttyd HTML → inject → write output */\nexport async function build(config: RemobiConfig, outputPath: string): Promise<void> {\n\tconst { js, css } = await bundleOverlay(config)\n\tconst baseHtml = await fetchTtydHtml()\n\tconst patched = injectOverlay(baseHtml, js, css, config)\n\twriteFileSync(outputPath, patched)\n}\n\n/** Build from stdin HTML (pipe mode) */\nexport async function injectFromStdin(config: RemobiConfig): Promise<string> {\n\tconst { js, css } = await bundleOverlay(config)\n\tconst stdin = await readStdin()\n\tif (stdin.trim().length === 0) {\n\t\tthrow new Error('remobi inject expects piped ttyd HTML on stdin')\n\t}\n\treturn injectOverlay(stdin, js, css, config)\n}\n"],"mappings":"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"}

package/dist/catppuccin-mocha-CGTshAuT.mjs

@@ -0,0 +1,48 @@
+//#region src/config-resolve.ts
+/** Type predicate — Array.isArray doesn't narrow `readonly T[]` from generic unions */
+function isReadonlyArray(input) {
+	return Array.isArray(input);
+}
+/**
+* Resolve a ButtonArrayInput against the defaults array.
+*
+* - undefined → return defaults unchanged
+* - Array → return as-is (replaces defaults entirely)
+* - Function → call with defaults, return result
+*/
+function resolveButtonArray(defaults, input) {
+	if (input === void 0) return defaults;
+	if (isReadonlyArray(input)) return input;
+	return input(defaults);
+}
+
+//#endregion
+//#region src/theme/catppuccin-mocha.ts
+/** Catppuccin Mocha colour palette for xterm.js */
+const catppuccinMocha = {
+	background: "#1e1e2e",
+	foreground: "#cdd6f4",
+	cursor: "#f5e0dc",
+	cursorAccent: "#1e1e2e",
+	selectionBackground: "#45475a",
+	black: "#45475a",
+	red: "#f38ba8",
+	green: "#a6e3a1",
+	yellow: "#f9e2af",
+	blue: "#89b4fa",
+	magenta: "#cba6f7",
+	cyan: "#94e2d5",
+	white: "#bac2de",
+	brightBlack: "#585b70",
+	brightRed: "#f38ba8",
+	brightGreen: "#a6e3a1",
+	brightYellow: "#f9e2af",
+	brightBlue: "#89b4fa",
+	brightMagenta: "#cba6f7",
+	brightCyan: "#94e2d5",
+	brightWhite: "#a6adc8"
+};
+
+//#endregion
+export { resolveButtonArray as n, catppuccinMocha as t };
+//# sourceMappingURL=catppuccin-mocha-CGTshAuT.mjs.map

package/dist/catppuccin-mocha-CGTshAuT.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"catppuccin-mocha-CGTshAuT.mjs","names":[],"sources":["../src/config-resolve.ts","../src/theme/catppuccin-mocha.ts"],"sourcesContent":["import type { ButtonArrayInput } from './types'\n\n/** Type predicate — Array.isArray doesn't narrow `readonly T[]` from generic unions */\nfunction isReadonlyArray<T extends { readonly id: string }>(\n\tinput: ButtonArrayInput<T>,\n): input is readonly T[] {\n\treturn Array.isArray(input)\n}\n\n/**\n * Resolve a ButtonArrayInput against the defaults array.\n *\n * - undefined → return defaults unchanged\n * - Array → return as-is (replaces defaults entirely)\n * - Function → call with defaults, return result\n */\nexport function resolveButtonArray<T extends { readonly id: string }>(\n\tdefaults: readonly T[],\n\tinput: ButtonArrayInput<T> | undefined,\n): readonly T[] {\n\tif (input === undefined) {\n\t\treturn defaults\n\t}\n\n\tif (isReadonlyArray(input)) {\n\t\treturn input\n\t}\n\n\treturn input(defaults)\n}\n","import type { TermTheme } from '../types'\n\n/** Catppuccin Mocha colour palette for xterm.js */\nexport const catppuccinMocha: TermTheme = {\n\tbackground: '#1e1e2e',\n\tforeground: '#cdd6f4',\n\tcursor: '#f5e0dc',\n\tcursorAccent: '#1e1e2e',\n\tselectionBackground: '#45475a',\n\tblack: '#45475a',\n\tred: '#f38ba8',\n\tgreen: '#a6e3a1',\n\tyellow: '#f9e2af',\n\tblue: '#89b4fa',\n\tmagenta: '#cba6f7',\n\tcyan: '#94e2d5',\n\twhite: '#bac2de',\n\tbrightBlack: '#585b70',\n\tbrightRed: '#f38ba8',\n\tbrightGreen: '#a6e3a1',\n\tbrightYellow: '#f9e2af',\n\tbrightBlue: '#89b4fa',\n\tbrightMagenta: '#cba6f7',\n\tbrightCyan: '#94e2d5',\n\tbrightWhite: '#a6adc8',\n}\n"],"mappings":";;AAGA,SAAS,gBACR,OACwB;AACxB,QAAO,MAAM,QAAQ,MAAM;;;;;;;;;AAU5B,SAAgB,mBACf,UACA,OACe;AACf,KAAI,UAAU,OACb,QAAO;AAGR,KAAI,gBAAgB,MAAM,CACzB,QAAO;AAGR,QAAO,MAAM,SAAS;;;;;;ACzBvB,MAAa,kBAA6B;CACzC,YAAY;CACZ,YAAY;CACZ,QAAQ;CACR,cAAc;CACd,qBAAqB;CACrB,OAAO;CACP,KAAK;CACL,OAAO;CACP,QAAQ;CACR,MAAM;CACN,SAAS;CACT,MAAM;CACN,OAAO;CACP,aAAa;CACb,WAAW;CACX,aAAa;CACb,cAAc;CACd,YAAY;CACZ,eAAe;CACf,YAAY;CACZ,aAAa;CACb"}

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };