chamba 0.2.0 → 0.3.1

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "chamba",
-  "version": "0.2.0",
-  "description": "A browser workspace paired to your terminal coding agent over one shared conversation.",
+  "version": "0.3.1",
+  "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": ">=20.19.0"
   },
   "files": [
     "dist",
@@ -17,11 +17,9 @@
     "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"
+    "zod": "4.4.3"
   }
 }

package/skill/SKILL.md

@@ -1,285 +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.
-
-## First run: the workspace
-
-chamba keeps everything under a `.chamba/` directory in the project. The first
-`open` creates it at the git repo root and says where (`created chamba workspace
-at ...`); each project gets its own server on a port derived from that location,
-so several projects run side by side without colliding. If the project has no
-`.git`, `open` will not guess a location - ask the human where the workspace
-should live and run `npx chamba@latest init <dir>` once (or `init --here` for the
-current directory), then `open`. `npx chamba@latest` with no arguments (a bare
-status) tells you whether a workspace exists yet.
-
-## Opening a session
-
-```
-npx chamba@latest open --title "what this is about"
-```
-
-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.
-
-With no `--kind`, the session opens undecided: the browser shows the human a
-chooser as their first interaction, and their pick sets the kind on this same
-session. Your next `poll` reports the choice as a `· Session set to spec` or
-`· Session set to everyday` line - drive the session accordingly from there. Pass
-`--kind spec` (or `--kind everyday`) to decide up front and skip the chooser; spec
-work adds the Draft/Mock/Diagram surfaces.
-
-## The app tab: connecting annotation
-
-The browser's "Your app" tab loads the human's running dev app in a frame so they can point at real UI and send you annotations.
-That needs chamba's annotation client running inside their app: one `<script>` tag that loads `/inject/annotate.js` from this chamba server.
-Until the app serves that script, the tab shows "Annotation layer not detected".
-
-Wire it in when the human asks - the app tab has an "Ask the agent to set this up" button that sends you exactly that request, and it may also come in their own words:
-
-- Use the exact tag the "not detected" banner shows; it already carries the right `src` (the origin the browser uses to reach chamba).
-  If you cannot see the banner, the tag is `<script src="<chamba-origin>/inject/annotate.js"></script>`, where `<chamba-origin>` is this project's chamba server URL - the same host and port as the `open` URL.
-- Add it to the app's HTML entry or root layout, and guard it to development so it never ships to production.
-  Where that goes depends on the project, so adapt to what you find: the `<head>` of `index.html` for Vite, a dev-only `<Script>` in `app/layout.tsx` (or `pages/_document`) for Next, `public/index.html` for Create React App, or the real HTML entry of anything else.
-- Have the human reload the app in the tab afterwards (or reload it yourself if you drive its dev server); the banner clears and the tab reads "connected" once the client is in.
-
-This is one-time setup per app: once the tag is in, annotation works for every session.
-
-## 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. It
-keeps waiting across quiet windows on its own, so a single `poll` is normally all
-you run between actions - it returns the moment a batch arrives. After a few minutes
-with nothing it prints `still listening - re-run chamba poll to keep waiting` to
-stderr and exits 0; just run it again. Give it a generous command timeout, since one
-call may block for minutes. It is safe to re-run - a batch re-delivers if you were
-interrupted before acting.
-
-Once you are attending a session, every exchange with the human goes through this
-loop - `poll` to receive, `reply` to send - and that includes your own questions,
-status updates, and "what should I do next?" checks. The human cannot see your
-terminal, so anything you write there is invisible to them; never stop polling to
-say or ask something in the terminal. `· Session ended` is the only line that ends the loop:
-it means the human handed back (clicked "Hand back", ended the session, or told you
-to stop, at which point you may run `end`). Nothing else is a reason to stop - not a
-heartbeat, not a quiet stretch, not finishing the task, not having a question. When
-in doubt, `poll` again. (`poll --once` does a single bounded check instead, for
-scripts.) React to what each line says:
-
-- A message from the human (`you: ...`): do the work, then answer with `reply` and
-  poll again. If you need something back first - a question, a choice, a
-  clarification - send that with `reply` too and keep polling for their answer;
-  never pause the loop to raise it in the terminal.
-- 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.)
-- `· Session set to spec` / `· Session set to everyday`: the human picked the kind
-  for a session that opened undecided. From here drive it accordingly - spec means
-  the interview flow (`ask`, `decision`, `artifact`); everyday is open conversation.
-- `· You moved to another session (<id>)`: the human switched sessions. Hand off
-  with `npx chamba@latest attach <id>`, then keep polling that one.
-- `· The user moved away`: a hand-off with no target session. Informational only -
-  keep polling this session.
-- `· Session ended`: the human handed back to the terminal. This is the only line
-  that ends the loop - 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:
+`--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.
 
-```
-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.
-
-## Handing back
+## Illustration pages
 
 ```
-npx chamba@latest end
+npx chamba@latest show /abs/page.html --name architecture
 ```
 
-Run this only when the human explicitly asks to stop or hand back - never on your
-own initiative to leave the loop. It 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`:
-
-```
-npx chamba@latest open --kind spec --title "checkout redesign spec"
-```
+## The app tab
 
-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.
+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.
 
-### 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, unclear 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": "Start 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. Each project has
-  its own server on a port derived from its `.chamba` location, so you never set a
-  port by hand.
-- Presence is automatic and honest: a parked `poll` shows the agent as "here"
-  (attending, waiting for input); the moment a poll returns carrying the human's
-  message and you go act on it, the browser shows "working"; a reply or your next
-  poll returns it to "here". It flips to "away" only after a long idle stretch with
-  no poll, or promptly when the `poll` process exits (killed or crashed).
-- There is no channel from the browser back into your terminal: anything you print
-  there is invisible to the human, so never break the `poll` loop to talk to them -
-  keep it running for the whole life of the session. If the human wants you on a
-  session you are not polling, they resume it from their side: by running `chamba
-  attach <id>` in the terminal, or - when you are attending another session -
-  clicking "Activate this session" in the browser, which you pick up as a `· You
-  moved to another session` line and follow with `attach`.
-- The server shuts itself down after a spell with no browser open and no parked
-  poll; the next `open`/`attach` starts a fresh one. Nothing sent is lost - it is
-  durable on disk and re-delivered when you next `poll`. To stop it deliberately
-  (for example before closing out the project), run `npx chamba@latest stop`.
-- 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};