chamba 0.1.0 → 0.3.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "chamba",
-  "version": "0.1.0",
-  "description": "A browser workspace paired to your terminal coding agent over one shared conversation.",
+  "version": "0.3.0",
+  "description": "A browser workspace beside your terminal coding agent - a rich parallel interface to the terminal chat.",
   "type": "module",
   "bin": {
     "chamba": "dist/cli.js"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12"
   },
   "files": [
     "dist",
@@ -17,11 +17,10 @@
     "README.md"
   ],
   "dependencies": {
-    "hono": "4.12.27",
+    "hono": "4.12.30",
     "@hono/node-server": "1.19.14",
     "@hono/node-ws": "1.3.1",
-    "ws": "8.21.0",
-    "marked": "18.0.5",
-    "zod": "3.25.76"
+    "ws": "8.21.1",
+    "zod": "4.4.3"
   }
 }

package/skill/SKILL.md

@@ -1,213 +1,93 @@
 ---
 name: chamba
-description: Open a browser workspace paired to this terminal session so the human can see rendered markdown, paste screenshots the agent can read, and point at UI - one shared conversation between the terminal agent and the browser. Use when the user says /chamba, asks to "open chamba", wants to share or receive images, or wants a visual workspace alongside the terminal.
-when_to_use: The user typed /chamba, asked to open the chamba workspace, wants to paste or be shown an image/screenshot, or wants a browser surface paired with this terminal session.
+description: Open a browser workspace beside this terminal session - a second, parallel conversation where the human can see rendered markdown, paste screenshots the agent can read, point at UI, and view rich HTML pages the agent renders. Use when the user says /chamba, asks to "open chamba", wants to share or receive images, or wants a visual workspace alongside the terminal.
+when_to_use: The user typed /chamba, asked to open the chamba workspace, wants to paste or be shown an image/screenshot, or wants a browser surface beside this terminal session.
 ---
 
 # chamba
 
-chamba pairs this terminal session with a browser workspace over one shared
-conversation. The terminal stays home base; the browser is where the human reads
-rendered markdown, pastes screenshots you can open, and points at UI. A pasted
-image arrives as a real file path you can `Read`; anything you send back with a
-file renders inline in their browser.
-
-Every command is `npx chamba@latest <command>`. Conversation content prints on
-stdout (what you read and act on); status and hints go to stderr, so a command's
-stdout is just the messages. Using `@latest` resolves the newest published
-version rather than a stale one npx may have cached.
-
-## Opening a session
-
-```
-npx chamba@latest open --title "what this is about"
-```
-
-Optionally `--kind spec` for spec work (extra Draft/Mock/Diagram surfaces). This
-prints a URL on stdout - give that URL to the human and ask them to open it. The
-server starts automatically if it is not already running.
-
-## The loop
-
-After opening (or `attach`), wait for the human:
-
-```
-npx chamba@latest poll
-```
-
-`poll` blocks until there is something to read, then prints it and returns. Run it
-again to keep waiting - it is safe to re-run (a batch re-delivers if you were
-interrupted before acting). React to what each line says:
-
-- A message from the human (`you: ...`): do the work, then answer with `reply`.
-- An attachment line (`  [file] name -> /abs/path`): that path is a real file on
-  disk. `Read` it (screenshots, mockups, logs) and act on what you see.
-- An annotation batch (`you [N annotations]:`): the human pointed at elements in
-  the app tab. Each numbered item carries the comment, the `selector`, the `page`
-  and `viewport`, a `[shot]` screenshot path to `Read`, and - when the app is
-  React/Next - the `component:` name and its source `file:line`. Use the source
-  and selector to find the code, `Read` the shot to see the problem, fix each item,
-  then `reply`. (React 19 shows the component name but may omit `file:line` unless
-  the app opted into bippy's source tier; fall back to the selector then.)
-- `· You moved to another session (<id>)`: the human switched sessions. Hand off
-  with `npx chamba@latest attach <id>`, then keep polling that one.
-- `· Session ended`: the human handed back to the terminal. Stop polling and
-  resume terminal work.
+chamba is a browser conversation running beside this terminal one - two separate channels you attend at the same time.
+Every command is `npx chamba@latest <command>`; conversation content prints on stdout, hints and status on stderr.
+
+## Protocol
+
+1. `npx chamba@latest open --title "what this is about"` - prints the session URL.
+   Say exactly: `Chamba available at: <url>` and nothing more.
+2. Launch `npx chamba@latest poll` as a background task.
+   It parks silently until the human sends something - hours or days, zero cost.
+3. When a poll returns: say `From chamba: <one-line gist of what arrived>`, act on it, answer with `reply`, and relaunch the background `poll` immediately.
+   While no poll is parked the browser tells the human no agent is listening.
+4. While the browser exchange is live, tighten the loop: poll in the foreground with `poll --for 240000` (give the command a generous timeout), reply, re-poll.
+   When it goes quiet, drop back to a background `poll`.
+5. Stop only when the session ends (see the cheatsheet).
+   Then say exactly: `Chamba stopped. Say the word to reopen.`
+
+Do not narrate opening, polling, or switching beyond those one-liners.
+The session is stateless to you: everything lives on disk plus your read cursor, so after any interruption `open` + `poll` puts you exactly back.
+Re-running `open` in the same agent session reconnects to the same session (`--new` forces fresh, `--last` rebinds to the newest active one).
+If `open` reports no git root, ask where the workspace should live and run `init <dir>` once.
+
+## What arrives -> what you do
+
+| You see | It means | You do |
+| --- | --- | --- |
+| `you: ...` | a message from the browser | act, then `reply <text>` |
+| `you [re #42 agent: "..."]: ...` | a reply to earlier event #42; the bracket is that event's gist | act with that context; use `reply --to 42` when answering that event specifically |
+| `you [answer in terminal]: ...` | the human wants the answer HERE, in the terminal | answer in the terminal conversation; do not `reply` |
+| `  [file] name -> /abs/path` | an attachment on the message above | `Read` the path (screenshots, mockups, logs) |
+| `you [N annotations]:` | numbered element comments from the app tab or your page | per item: use `selector`/`component`/`file:line` to find the code, `Read` the `[shot]`, fix, then `reply` |
+| `[chamba <id>#<seq> "..."]` pasted here in the terminal | the human is referencing a browser message | run `npx chamba@latest get <id>#<seq>` to print it, then answer in the terminal |
+| `· Session ended` | the human handed back | stop the loop; say the stop line |
+| `chamba server stopped` | deliberate stop | stop the loop; `open` again only if work should continue |
+
+Anything else on stderr (heartbeat, retry note, quiet stretch) means: relaunch `poll` and keep listening.
+Polling is at-least-once: a batch re-delivers if you were interrupted before acting on it.
+
+## Answer where you were asked
+
+Terminal input is answered in the terminal; browser input is answered with `reply`.
+Never mirror content between the channels.
+The only overrides are explicit: `[answer in terminal]` and a pasted `[chamba ...]` reference both move that one answer to the terminal.
 
 ## Replying
 
 ```
 npx chamba@latest reply on it - here is the diff you asked about
+npx chamba@latest reply here's the chart --image /abs/chart.png
+npx chamba@latest reply --to 42 yes, exactly that one
 ```
 
-Send a file back (renders in their browser); text is optional alongside it:
-
-```
-npx chamba@latest reply here's the chart --image /abs/path/to/chart.png
-```
-
-Use `--file a,b` / `--image a,b` (comma-separated) for several files.
+`--file a,b` / `--image a,b` attach files (comma-separated); text is optional alongside them.
+`--to <seq>` threads the reply to a specific earlier event - use it when answering something older than the latest message.
 
-## Handing back
+## Illustration pages
 
 ```
-npx chamba@latest end
+npx chamba@latest show /abs/page.html --name architecture
 ```
 
-Ends the session from the terminal (the browser goes read-only). The human can
-also hand back from the browser, which you will see as `· Session ended` on your
-next poll.
+Renders a full HTML page in the browser's Illustration tab - use it proactively for diagrams, mockups, comparisons, anything richer than markdown.
 
-## Spec sessions
+- The page must be fully self-contained: inline all CSS/JS/SVG; it runs in a sandboxed iframe (`allow-scripts` only) with no network access.
+- Re-`show` the same `--name` to revise in place; a new name adds a page.
+- The human can annotate your page like any app - comments arrive as an annotation batch with selectors into your own HTML.
 
-A spec session is chamba's deepest use: a structured interview that produces a
-spec package - a canonical markdown draft, mockups, diagrams, and a decision log -
-in the same shared thread and the same annotation system.
-Open one with `--kind spec`:
+## The app tab
 
-```
-npx chamba@latest open --kind spec --title "checkout redesign spec"
-```
+The "Your app" tab frames the human's dev app for annotation; it needs chamba's client script inside that app.
+When asked to set it up (the tab has a button that sends you the request), add the tag from the "not detected" banner - `<script src="<chamba-origin>/inject/annotate.js"></script>`, chamba-origin being the same host/port as the `open` URL - to the app's HTML entry or root layout, guarded to development.
+Then have the app reloaded in the tab.
+One-time per app.
 
-This unlocks three surface tabs beside "Your app" - Draft, Mock, Diagram - each
-annotatable exactly like the app tab.
-You drive the session from the terminal with four commands (`ask`, `decision`,
-`artifact`, `export`); the human answers, points, and annotates from the browser.
-
-### Intake: infer the kind of work, then confirm it
-
-A spec session opens with a free-form dump - text, pasted images, files.
-Read all of it, infer which of four kinds of spec work this is, and confirm your
-read with the human before diving in (they can override).
-Record the confirmed kind with `decision` so it is on the log.
-
-The four kinds are behaviorally distinct - they change what you do, not just a label:
-
-- **co-spec** - no spec exists yet; you build one from scratch.
-  Start wide (goals, users, constraints, what success means), then converge; most
-  of the work is net-new question cards and a draft that grows from nothing.
-- **review** - a spec or feature already exists and the human wants it pressure-tested.
-  Read it first against the codebase, then lead with the gaps, contradictions, and
-  unstated assumptions you find rather than with open-ended questions.
-- **refine** - a draft exists and is roughly right; the work is sharpening.
-  Hunt vague terms, underspecified edges, and missing error/empty/loading states,
-  then propose precise wording and confirm it.
-- **feedback** - the human has a running thing and reactions to it.
-  Lean on the Your app tab and annotations: turn each pointed-at problem into a
-  decision and a draft revision.
-
-### The interview doctrine
-
-- Hunt ambiguity relentlessly; every vague term ("fast", "simple", "secure") is a
-  question waiting to be asked.
-- Assume the highest standard: when you offer options, mark the one you would
-  choose as `recommended` and say why in its description.
-- Give development cost low weight - prefer quality, simplicity, robustness,
-  scalability, and long-term maintainability; surface the trade-off and let the
-  human decide.
-- Cross-reference every claim against the actual code as `path:line`; do not assert
-  what the codebase does from memory.
-- Never let anything unresolved silently vanish: if you cannot get an answer,
-  record it as an `assumed` decision so it surfaces as an open question.
-- The human can stop anytime; the card always carries a stop affordance, so honor it.
-
-### Asking - question cards
-
-Post a structured question with `ask`.
-Options are structured (a label, a description, an optional `recommended` flag), so
-the card is passed as JSON - inline via `--json` or as a file path positional:
-
-```
-npx chamba@latest ask --json '{
-  "question": "How should an expired checkout session behave?",
-  "options": [
-    {"label": "Silent refresh", "description": "Mint a new session, keep the cart, no interruption.", "recommended": true},
-    {"label": "Prompt to resume", "description": "Show a resume dialog before restoring the cart."},
-    {"label": "Hard reset", "description": "Discard the cart and start over."}
-  ]
-}'
-```
-
-Offer as many options as the question genuinely has (up to six); do not pad to a
-number, and do not collapse real choices to fit.
-You never add a "let me type my own" option or a "leave a note" option: the card
-always shows a free-text custom-answer field and always lets the human annotate
-their choice, with voice on both.
-The answer returns as a normal message on your next `poll` - there is no separate
-answer command - and `ask` fills in the card id for you.
-
-### Recording decisions
-
-Every material choice goes on the decision log, marked `confirmed` (the human chose
-it) or `assumed` (you chose it provisionally on their behalf):
-
-```
-npx chamba@latest decision --status confirmed --summary "Expired sessions refresh silently, cart preserved"
-npx chamba@latest decision --status assumed --summary "Guest checkout is in scope" --detail "Unconfirmed; revisit before finalizing"
-```
-
-`assumed` entries are the ones that surface as open questions on export, so record
-them honestly rather than guessing silently.
-
-### Building artifacts - draft, mock, diagram
-
-Publish a draft, mock, or diagram from a file with `artifact`; the matching surface
-tab renders it, annotatable like the app:
-
-```
-npx chamba@latest artifact --kind draft   --name spec     --file /abs/spec.md
-npx chamba@latest artifact --kind mock     --name checkout --file /abs/checkout.html
-npx chamba@latest artifact --kind diagram --name flow     --file /abs/flow.mmd
-```
-
-- `draft` is markdown (rendered), `mock` is HTML (served sandboxed with the
-  annotation layer injected), `diagram` is mermaid.
-- Build the draft live: re-post the same `--kind draft --name <name>` as you write,
-  and its tab reloads to the new revision each time - this is how the spec builds in
-  front of the human.
-- Keep one draft name (e.g. `spec`) as the canonical draft; it becomes `spec.md` on
-  export, and any other draft names land in `assets/`.
-- Mocks and diagrams are annotated through the same select -> comment -> card flow as
-  the app tab; a batch of mock annotations arrives on `poll` just like app ones.
-
-### Exporting the package
-
-Nothing leaves `.chamba/` automatically.
-When the spec is ready to be official, copy the self-contained package to a
-destination the human names (usually under `docs/`):
-
-```
-npx chamba@latest export docs/checkout-spec
-```
+## Ending
 
-This writes `spec.md` (the canonical draft), `assets/` (mocks and diagrams), and
-`decisions.md` (the log, grouped confirmed vs. assumed/open).
+`npx chamba@latest end` - only when the human explicitly asks to stop or hand back, never on your own initiative.
 
 ## Notes
 
-- All commands talk to a local server that shares this container; you never need a
-  host or port beyond the defaults.
-- Presence is automatic: while you are parked in `poll`, the browser shows the
-  agent as here.
-- Past sessions stay readable: `npx chamba@latest attach <id>` reloads any session's
-  recent history.
+- Each project has its own `.chamba/` workspace (created at the git root on first `open`) and its own server on a derived port; never set a port by hand.
+- Presence is automatic: a parked poll shows "listening", a delivered batch flips to "working", a reply or the next poll flips back.
+  No poll parked shows "away".
+- If the server crashed, a parked poll respawns it by itself; after a deliberate `stop` it exits cleanly.
+  Every message is durable on disk either way.
+- Past sessions stay readable in the browser; an ended session opens read-only.

package/web/assets/highlighted-body-OFNGDK62-Bn4Eu7CG.js

@@ -0,0 +1 @@
+import{a as e,n as t,o as n,r,s as i,t as a}from"./index-B9DI4F1Z.js";var o=i(n(),1),s=e(),c=({code:e,language:n,raw:i,className:c,startLine:l,lineNumbers:u,...d})=>{let{shikiTheme:f}=(0,o.useContext)(r),p=t(),[m,h]=(0,o.useState)(i);return(0,o.useEffect)(()=>{if(!p){h(i);return}let t=p.highlight({code:e,language:n,themes:f},e=>{h(e)});t&&h(t)},[e,n,f,p,i]),(0,s.jsx)(a,{className:c,language:n,lineNumbers:u,result:m,startLine:l,...d})};export{c as HighlightedCodeBlockBody};