hop2 0.8.0

package/.hop-tmux.conf

@@ -0,0 +1,18 @@
+
+# Hop Terminal - Tmux Configuration
+# Do not use user's config - this is hop-managed
+
+# Enable mouse support
+set -g mouse on
+
+# 2-line scroll speed (compromise between smoothness and remote latency)
+bind -T copy-mode WheelUpPane send -N 2 -X scroll-up
+bind -T copy-mode WheelDownPane send -N 2 -X scroll-down
+bind -T copy-mode-vi WheelUpPane send -N 2 -X scroll-up
+bind -T copy-mode-vi WheelDownPane send -N 2 -X scroll-down
+
+# Increase scrollback buffer
+set -g history-limit 50000
+
+# Better terminal colors
+set -g default-terminal "screen-256color"

package/INTEGRATION.md

@@ -0,0 +1,92 @@
+# Hop + Termshare Integration Plan
+
+This branch integrates [termshare](https://github.com/jzthree/termshare) to replace ttyd/tmux.
+
+## Benefits
+
+- **No ttyd/tmux dependencies** - Pure Node.js solution
+- **Built-in presence** - See who's connected, typing indicators
+- **Control modes** - Collaborative or locked single-controller
+- **No injection hacks** - Direct control over web UI
+- **Mobile-ready** - Responsive design with iOS-style keyboard built-in
+- **CLI client** - Connect from real terminals too
+
+## Architecture Change
+
+### Before (ttyd)
+```
+Browser → Hop Auth Proxy → ttyd (per session) → tmux → shell
+                ↓
+        HTML/WebSocket injection for mobile keyboard
+```
+
+### After (termshare)
+```
+Browser → Hop Auth Proxy → Termshare WebSocket → node-pty → shell
+                ↓
+        Native termshare web UI (mobile keyboard built-in)
+```
+
+## Implementation Steps
+
+### 1. Add Dependencies
+- [x] `node-pty-prebuilt-multiarch` - PTY handling
+- [x] `ws` - WebSocket server
+- [x] Copy termshare room/pty logic into hop (`termshare.js`)
+
+### 2. Remove ttyd/tmux Code
+- [x] Remove `spawn('ttyd', [...])` in `getOrCreateSession()`
+- [ ] Remove `HOP_TMUX_CONF`, `HOP_TMUX_WRAPPER` generation (still present but unused)
+- [ ] Remove `listTmuxSessions()`, `waitForTmuxSessionReady()` (still present but unused)
+- [ ] Remove ttyd dependency check (still present but unused)
+- [x] Remove keyboard HTML injection code (now using termshare's built-in)
+- [x] Remove `getIOSKeyboardInjection()` WebSocket patching (still present but unused)
+
+### 3. Add Termshare Integration
+- [x] Port `Room` and `RoomManager` classes from termshare
+- [x] Port `createPty` function
+- [x] Create termshare WebSocket handler at `/ws` endpoint
+- [x] Map hop sessions to termshare rooms
+
+### 4. Update Session Management
+```javascript
+// Before: activeSessions[name] = { ttyd: Process, port: number }
+// After:  activeSessions[name] = { room: Room }
+```
+✅ Completed
+
+### 5. Serve Termshare Web UI
+- [x] Build termshare web client (with mobile keyboard)
+- [x] Serve static files from hop (`termshare-web/` directory)
+- [x] Inject room parameter for session routing
+
+### 6. Keep Hop Features
+- [x] Authentication (TOTP + cookies)
+- [x] Cloudflare tunneling
+- [x] Session URL routing (`/s/<name>/`)
+- [x] Multi-user support
+
+## Key Files Changed
+
+- `hop` - Main server, updated `getOrCreateSession()` and WebSocket handler
+- `termshare.js` - New module with Room, RoomManager, createPty
+- `termshare-web/` - Built termshare web client with mobile keyboard
+
+## Testing
+
+1. Start hop: `node hop`
+2. Open browser to tunnel URL
+3. Verify:
+   - [ ] Login with TOTP works
+   - [ ] Terminal session works
+   - [ ] Multiple clients see same session
+   - [ ] Presence indicators show
+   - [ ] Control modes work
+   - [ ] Mobile UI works without injection
+
+## Migration Notes
+
+- Sessions are not persistent (by design) - shell exits when all clients disconnect
+- tmux scrollback replaced by termshare's output buffer (200KB)
+- iOS keyboard injection replaced by termshare's built-in mobile keyboard
+- The old ttyd/tmux code paths are still present but no longer used; can be removed in a cleanup pass

package/README.md

@@ -0,0 +1,260 @@
+# 🐰 hop
+
+**Hop into your terminal from anywhere in the world.**
+
+Access your Mac's terminal from your phone, tablet, or any browser — secured with password + 2FA, tunneled through Cloudflare.
+
+> **🍎 macOS/Linux** — Requires cloudflared for tunneling
+
+```
+           (\(\ 
+           ( -.-)    "hop into your shell"
+           o_(")(")
+```
+
+## ✨ Features
+
+- 🔐 **Password + 2FA** — Optional password plus TOTP (required for custom domains)
+- 🌍 **Access Anywhere** — Cloudflare tunnel, no port forwarding
+- 🌐 **Custom Domains + Multi‑User** — Share subdomains with per‑user credentials
+- 📱 **Mobile Virtual Keyboard** — Custom keyboard with Esc, Ctrl, Alt, arrows, and more
+- ⌨️ **Native Keyboard Support** — Tap the blue button for dictation, spellcheck & autocomplete
+- 🪟 **Multi-Session** — Create and switch between named sessions
+- 🔌 **Port Sessions** — Proxy a local HTTP/WS service via hop
+- 🔄 **Quick Session Switching** — Floating menu to switch sessions without leaving the terminal
+- 🎨 **Modern UI** — Clean, minimal iOS-style design
+- ⚡ **Auto-Attach** — Multiple terminals share the same tunnel
+
+## 🚀 Quick Install
+
+### From npm (easiest)
+
+```bash
+npm install -g hop2
+```
+
+Then just run:
+```bash
+hop
+```
+
+### One-liner from source
+
+```bash
+git clone https://github.com/jzthree/hop.git ~/.hop && \
+cd ~/.hop && npm install && \
+sudo ln -sf ~/.hop/hop /usr/local/bin/hop
+```
+
+### Manual Install from source
+
+```bash
+# Clone the repo
+git clone https://github.com/jzthree/hop.git ~/.hop
+
+# Install dependencies
+cd ~/.hop && npm install
+
+# Add to PATH (pick one)
+# Option A: Symlink (requires sudo)
+sudo ln -sf ~/.hop/hop /usr/local/bin/hop
+
+# Option B: Add to PATH
+echo 'export PATH="$HOME/.hop:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+## 🐰 Usage
+
+```bash
+# Start hopping!
+hop
+
+# Use iTerm control mode for local session
+hop --iterm
+```
+
+**First time:**
+1. (Optional) Set a password: `hop password set`
+2. Scan the QR code with your authenticator app (Google Authenticator, Authy, 1Password, etc.)
+3. Note the URL displayed
+4. Press Enter to start your local session
+
+**From your phone:**
+1. Open the URL in your browser
+2. Enter your password (if enabled) and 6‑digit code
+3. Pick or create a session
+4. 🐰 You're in! Use the virtual keyboard for terminal keys, or tap the blue button for native input
+
+## 🪟 Sessions
+
+Create multiple independent terminal sessions from the Session Picker (`/sessions`):
+
+- **Create**: Type a name and click Create
+- **Join**: Click Join on any existing session
+- **Sessions are shared**: Multiple devices can view the same session
+
+You can also create **Port Sessions** that proxy to a local HTTP/WS service on your machine.
+Use the Session Picker or:
+```bash
+hop session add myapp --port 3000
+```
+
+## 🌐 Custom Domains & Multi‑User
+
+### Admin (your machine)
+1. Set a password (required for custom domains):
+   ```bash
+   hop password set
+   ```
+2. Configure your domain:
+   ```bash
+   hop domain hop.yourdomain.com
+   ```
+3. Add a user + export credentials:
+   ```bash
+   hop user add alice
+   hop user export alice
+   ```
+4. Send the exported folder to the user.
+
+### User (their machine)
+```bash
+npm install -g hop2
+hop client ./credentials.json
+```
+First run prompts them to set a password + scan a TOTP QR code.  
+They then log in at their URL, e.g. `https://alice.hop.yourdomain.com`.
+
+## 📱 Mobile Keyboard
+
+On mobile devices, Hop provides a custom virtual keyboard designed for terminal use:
+
+**Accessory Row:**
+- `Esc` `Tab` `Ctrl` `Alt` — Essential terminal keys
+- `← ↓ ↑ →` — Arrow keys for navigation
+- 🔵 **Blue keyboard button** — Opens native iOS keyboard for dictation, spellcheck & autocomplete
+
+**Floating Menu (top-right button):**
+- **Toggle Keyboard** — Show/hide the virtual keyboard
+- **Session List** — Quick-switch between sessions
+- **All Sessions** — Return to session picker
+
+**Tips:**
+- The floating button is draggable — move it anywhere
+- First-time users will see a tooltip pointing to the native keyboard button
+- Use the native keyboard for longer text input with autocomplete
+
+## 🖥️ iTerm Integration
+
+```bash
+hop --iterm
+```
+
+Uses tmux control mode (`-CC`) for native scrolling, copy/paste, splits, and search. Session remains accessible via web.
+
+## 🔌 Port Sessions
+
+Expose local HTTP/WebSocket services through your tunnel:
+
+```bash
+hop session add myapp --port 3000
+# Access at: https://your-tunnel-url/s/myapp/
+```
+
+Works with dev servers, Jupyter, APIs — anything on localhost. Supports WebSocket.
+
+## 🔧 Commands
+
+| Command | Description |
+|---------|-------------|
+| `hop` | Start hop (or attach to existing tunnel) |
+| `hop --iterm` | Use iTerm tmux control mode for local session |
+| `hop url` | Print current tunnel URL |
+| `hop qr` | Show QR code for current URL |
+| `hop domain <hostname>` | Set custom domain (named tunnel) |
+| `hop domain-clear` | Remove custom domain, use random URLs |
+| `hop password set` | Set/change password |
+| `hop password clear` | Remove password protection |
+| `hop user list` | List users |
+| `hop user add <name>` | Add user + subdomain |
+| `hop user remove <name>` | Remove user |
+| `hop user export <name>` | Export user credentials |
+| `hop session list` | List sessions |
+| `hop session add <name>` | Create a terminal session |
+| `hop session add <name> --port N` | Create a port session (proxy) |
+| `hop session remove <name>` | Remove a session |
+| `hop client <credentials>` | Run hop with exported credentials |
+| `hop wipe` | Kill all hop tmux sessions |
+| `quit` | Type at exit prompt to shutdown tunnel |
+
+## 📦 Dependencies
+
+Installed automatically via Homebrew:
+- `tmux` — Terminal multiplexer
+- `ttyd` — Web terminal
+- `cloudflared` — Cloudflare tunnel
+
+Node.js packages:
+- `http-proxy` — Request proxying
+- `otplib` — TOTP authentication
+- `qrcode-terminal` — QR code display
+- `cookie` — Session cookies
+
+## 🛡️ Security
+
+- **Password + TOTP** — Password optional, but required for custom domains
+- **Rate Limiting** — Exponential backoff on failed attempts
+- **Secure Cookies** — `httpOnly`, `secure`, `sameSite=lax`
+- **Random URL** — Unguessable tunnel URL for quick tunnels
+- **Fixed URL** — Custom domains keep a stable URL
+- **Local Binding** — Server only listens on 127.0.0.1
+- **End-to-End TLS** — Cloudflare Tunnel encryption
+
+**Passwords:** Recommended for any public URL; required for custom domains.
+
+**Secrets:** Stored in `~/.hop2/` (treat like `~/.ssh/`)
+
+## 🛠 Development (Hay)
+
+The hay source is vendored in `./hay`. Hop will serve `hay/apps/web/dist` when present.
+
+```bash
+npm run build
+```
+
+This builds hay (web + cli) and syncs `hay/apps/web/dist` into `hay-web/` for Hop to serve.
+If `./hay` exists and the dist folder is missing, `hop` will auto-build hay on startup.
+
+## 🐛 Troubleshooting
+
+**QR code not working?**
+Delete `.auth_secret` and restart hop to generate a new code.
+
+**Client reset (user mode)?**
+Delete `~/.hop2/clients/<tunnel-id>/` and run `hop client` again.
+
+**Tunnel not starting?**
+Make sure `cloudflared` is installed: `brew install cloudflared`
+
+**Stuck processes?**
+```bash
+pkill ttyd; pkill cloudflared; tmux kill-server
+```
+
+## 📝 License
+
+MIT
+
+---
+
+Made with 🐰 for hopping around
+
+```
+   ____
+  /    \
+ | ^  ^ |     hop hop hop
+ |  ..  |
+  \ -- /
+   ||||
+```

package/hay/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## [0.8.0] - 2025-01-25
+
+### Major Changes
+
+- **Replaced ttyd/tmux with hay/node-pty**: Terminal sessions are now managed directly via node-pty instead of ttyd+tmux. This removes external dependencies and provides native multi-client support, presence indicators, and better web/CLI integration.
+
+### Breaking Changes
+
+- **RoomManager.getRoom() signature changed**: Now accepts optional third `cwd` parameter
+  ```typescript
+  // Before
+  getRoom(roomId: string, initialSize: { cols: number; rows: number })
+
+  // After
+  getRoom(roomId: string, initialSize: { cols: number; rows: number }, cwd?: string)
+  ```
+  The per-room `cwd` takes precedence over the RoomManager constructor's default cwd.
+
+### New Features
+
+#### CLI Client
+- **Keyboard shortcuts**: Pan (arrows), center on cursor (0), auto-fit (A), mouse toggle (M), hints (Ctrl+T), detach (Ctrl+G), kill (Ctrl+Q)
+- **Configuration file support**: Reads from `.hop.json` (under `hay-cli` key) or legacy `.hay-cli.json`
+- **Config hierarchy**: Local config takes precedence over global (`~/.hop.json`)
+- **scrollOff setting**: Vim-like scroll margin (default: 3 lines) keeps context visible around cursor
+- **showHints setting**: Toggle keyboard shortcut hints bar
+
+#### Web Client
+- **Haptic feedback**: Tactile feedback on mobile keyboard (iOS via switch element trick, Android via Vibration API)
+- **Improved mobile layout**: Responsive drawer and keyboard
+
+### Bug Fixes
+
+- Fixed sessions always starting in daemon's directory instead of caller's pwd
+- Fixed cursor scroll behavior to match regular terminals (only scroll when cursor exits viewport)
+- Fixed initial viewport positioning on session start
+
+## [0.1.0] - Initial Release
+
+- Multi-client terminal sharing
+- Web and CLI clients
+- Presence indicators and typing status
+- Collaborative and locked control modes
+- Embeddable server library

package/hay/DEV_NOTES.md

@@ -0,0 +1,39 @@
+# Dev Notes
+
+## Mobile touch scrolling + selection mode (iOS Safari)
+
+We intentionally disable native touch handling on the xterm DOM so we can
+implement our own smooth touch scrolling, but we also need a "selection mode"
+that restores iOS text selection handles. The fix is split across CSS and JS.
+
+### Default mode (scrolling)
+* **CSS** (`hay/apps/web/src/styles.css`):
+  * `.terminal-scroll` and `.xterm*` get `touch-action: none` to prevent
+    Safari's native scrolling/selection on the terminal surface.
+  * `.xterm-rows` and span children use `pointer-events: none` so touches hit
+    our container instead of individual text nodes.
+* **JS** (`hay/apps/web/src/App.tsx`, mobile touch effect):
+  * We attach custom `touchstart/move/end` handlers to implement momentum
+    scrolling on the terminal content.
+
+### Selection mode (text selection)
+* **CSS** (`hay/apps/web/src/styles.css`):
+  * `.session.selection-mode` re-enables `pointer-events` and `user-select`
+    on `.xterm-rows` so iOS can show selection handles.
+  * `touch-action: auto` is restored on xterm elements.
+* **JS** (`hay/apps/web/src/App.tsx`):
+  * We skip the custom touch scrolling effect when `selectionMode` is true.
+  * We disable xterm's internal `viewport.handleTouchStart/Move` to stop it
+    from swallowing selection gestures.
+  * The click handler clears selection and toggles `user-select` to re-arm
+    iOS selection after a tap.
+
+### If selection or scrolling regresses
+1. Confirm `.session` has the `selection-mode` class when the toggle is on.
+2. Verify the CSS block for `.session.selection-mode` is present (pointer-events
+   and user-select must be re-enabled).
+3. In `App.tsx`, ensure the selection-mode guards still:
+   * prevent installing custom touch scrolling, and
+   * override `viewport.handleTouchStart/Move`.
+4. If text selection works but scrolling is broken, verify `touch-action: none`
+   and `pointer-events: none` are still applied in default mode.