chamba 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # chamba
 
-A browser workspace paired to your terminal coding agent over one shared conversation.
+A browser workspace beside your terminal coding agent - a rich parallel interface to the terminal chat.
 
 ## Quick start
 
@@ -10,10 +10,58 @@ Install the skill for your agent:
 npx chamba@latest skill install
 ```
 
-Then, in your agent, run `/chamba` (or ask it to "open chamba"). It opens a browser workspace where you read rendered markdown, paste screenshots the agent can read, and point at UI - all in the same thread as the terminal.
+Then, in your agent, run `/chamba` (or ask it to "open chamba").
+It opens a browser workspace where you read rendered markdown, paste screenshots the agent can read, point at UI in the app tab, and view rich HTML pages the agent renders in the Illustration tab.
+
+The browser is a second conversation beside the terminal: a background `chamba poll` keeps the agent listening for browser input while it stays available in the terminal, and each channel is answered where it was asked.
 
 Add `--global` to install the skill for every project (`~/.claude/skills`).
 
+## Testing
+
+`pnpm check` is the full gate: typecheck (the packages plus the test sources, via `tsconfig.test.json`), lint, both builds (`inject`, `web`), then `pnpm test` and `pnpm test:e2e:flake`.
+`pnpm test` runs Vitest's two projects (`unit` + `integration`).
+`pnpm test:e2e` runs the Playwright suite once; `pnpm test:e2e:flake` repeats it three times with no retries so an intermittent failure cannot hide, and is the e2e variant the gate runs on every push.
+`pnpm test:e2e:video` runs the suite once and records a video of every flow under `test-results/e2e/`, for watching the browser interactions.
+
+| Path | Covers | Run by |
+| --- | --- | --- |
+| `packages/*/src/**/*.test.ts` | Unit tests colocated with each package (`shared`, `server`, `cli`, `inject`): pure schema and logic. | `pnpm test` (Vitest `unit` project, parallel). |
+| `tests/integration/` | Integration: real server and CLI processes over real ports and the WebSocket transport (roundtrip, durability, annotations, attachments, issues, pages, references, binding, init, lifecycle). Shared helpers live in `tests/support/`. | `pnpm test` (Vitest `integration` project, sequential forks with long timeouts, since parallel port binding would flake). |
+| `tests/e2e/` | End-to-end: a real browser drives the production web build against a real server and CLI, proving the human and agent exchange renders live. | `pnpm test:e2e` (Playwright, serial; `pretest:e2e` installs the browser first). |
+| `tests/fixtures/` | Sample apps for the "Your app" surface: a Vite + React app on port 4001 and a Next.js app on port 4002. The e2e suite drives the React app as a cross-origin annotation target; both are runnable by hand for manual exploration. | `pnpm fixture:react`, `pnpm fixture:next` (see `tests/fixtures/README.md`). |
+
+The e2e browser runs inside the dev container, which provides the Chromium system libraries and fonts it needs.
+
+## Local package testing
+
+`pnpm -s chamba` drives the working copy: it runs the source under tsx (no build) and resolves only inside this repo, so it is always the local version, never the published package.
+
+### One command
+
+From the repo root:
+
+```
+pnpm try:chamba
+```
+
+It waits until the Next fixture is serving `:4002`, then drops you straight into a sandbox session in the same terminal tab.
+This tab never starts the fixture itself, so it can never leave one running in the background.
+If nothing is serving `:4002` yet, it prints the command to start the fixture and waits; open a separate tab in the repo root, run `pnpm dev:next` (or `pnpm re:dev:next` for a clean reinstall first), and this tab continues on its own once the port is up.
+
+### The individual pieces
+
+Each runs from the repo root; add `-w` (`pnpm -w dev:next`) to run it from any subdir.
+
+- `pnpm dev:next` - Next fixture on `:4002` (fast; assumes deps are installed via `pnpm install`).
+- `pnpm re:dev:next` - clean build dirs, reinstall, then the same (the container shadows `node_modules`, so this matters for a truly fresh run).
+- `pnpm fixtures:stop` - stop the fixture dev servers (React on `:4001`, Next on `:4002`). Run it where the fixture runs (host or container); it kills only the fixture processes, never Docker's port forwarder.
+- `npx totopo` - start the workspace's sandbox session; runs from anywhere under the repo.
+- `pnpm -s chamba open` - inside the session, opens chamba and prints its URL.
+
+Confirm the workspace publishes chamba's port with `CHAMBA_HOST=0.0.0.0` and `CHAMBA_PORT=4319`; the fixture's inject script targets `:4319`.
+Then open the printed chamba URL, point the "Your app" tab at `:4002`, and do real work: paste a screenshot, annotate, ask the agent to show an illustration page.
+
 ---
 
 A personal tool, published as-is with no stability promises.