Document prerelease changelog and publish workflow

Clarify that webmux is not yet published, keep release notes under Unreleased, and document first-release steps. Add migration notes for the new ControlButton schema and drawer.buttons config key.

Author: connorads

AGENTS.md

@@ -1,6 +1,6 @@
 # webmux
 
-Mobile-friendly terminal overlay for ttyd + tmux. Published as `webmux` on npm (Bun-only).
+Mobile-friendly terminal overlay for ttyd + tmux. Intended for npm as `webmux` (Bun-only).
 
 ## Architecture
 
@@ -49,13 +49,22 @@ bun run build         # Build dist/index.html
 - CI: `.github/workflows/ci.yml` — bun test + biome check
 - Publish: `.github/workflows/publish.yml` — triggered on `v*` tags → npm publish
 - `bun link` for local development (CLI available globally, changes immediate)
+- First publish workflow:
+  - Keep release notes under `CHANGELOG.md` → `Unreleased` until first publish
+  - On release, set `package.json` version, rename `Unreleased` to that version + date
+  - Create and push matching tag (`v<version>`) to trigger publish workflow
 
 ## Conventions
 
 - Button actions use discriminated unions (`type: 'send' | 'ctrl-modifier' | 'paste' | 'drawer-toggle'`)
+- Unified control schema: use `ControlButton` for both toolbar and drawer items
+- Config shape: `drawer.buttons` (not `drawer.commands`)
 - Config via `defineConfig()` — typed, with sensible defaults
 - Config resolution: `--config` flag → cwd → `~/.config/webmux/` (XDG fallback)
 - Drawer takes a flat `readonly ControlButton[]` — rendered as a single grid
+- Help overlay is config-driven and must be fail-safe (never break core controls if help fails)
+- Mobile viewport handling: lock document scroll and compute height from visual viewport (keyboard-aware)
+- When behaviour/config/API changes, update `CHANGELOG.md` under `Unreleased` in the same change set
 - All DOM creation in `util/dom.ts` helpers
 - Keyboard state preserved: capture `isKeyboardOpen()` before action, use `conditionalFocus()` after
 - Tests use happy-dom for DOM environment

CHANGELOG.md

@@ -1,18 +1,12 @@
 # Changelog
 
-## 0.1.0
+## Unreleased
 
-Initial release — extracted from dotfiles into standalone npm package.
+This project has not been published yet. On first release, rename this section to `0.1.0` and add the release date.
 
-- Two-row touch toolbar with sticky Ctrl modifier
-- Context-aware command drawer with tab switching
-- Swipe gestures for tmux window navigation
-- Pinch-to-zoom font sizing
-- Font size +/- controls
-- Help overlay
-- Scroll buttons for touch devices
-- Catppuccin Mocha default theme
-- Landscape keyboard detection
-- CLI: `build`, `inject`, `init` commands
-- XDG config fallback (`~/.config/webmux/`)
-- Ships TypeScript source (Bun-only, no transpilation)
+- 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.
+- Tests: expanded integration/config/height coverage for the new config model and viewport logic.

README.md

@@ -25,6 +25,8 @@ Turns a ttyd web terminal into a touch-optimised tmux client with toolbar, gestu
 
 ## Quick start
 
+If the npm package is not published yet, use local development flow with `bun link` instead of `bun add -g webmux`.
+
 ```bash
 # 1. Install
 bun add -g webmux
@@ -110,6 +112,12 @@ export default defineConfig({
 
 All fields are optional — defaults are filled in via `defineConfig()`.
 
+### Beta migration note
+
+- Drawer config key is `drawer.buttons` (previously `drawer.commands`).
+- Toolbar and drawer entries share one schema: `ControlButton` (`id`, `label`, `description`, `action`).
+- Help content is generated from configured controls, so keep `description` clear and user-facing.
+
 `gestures.scroll.strategy` controls touch scroll behaviour:
 
 - `wheel` (default): sends SGR mouse wheel events with touch-mapped terminal coordinates.