haltija 1.1.0

package/docs/agent-prompt.md

@@ -0,0 +1,139 @@
+# Haltija Agent Quick-Start
+
+Copy this prompt to give an AI agent browser control via Haltija.
+
+---
+
+## The Prompt
+
+```
+# Haltija - Browser Control
+
+## What is this?
+You have browser control via the `hj` command.
+It returns semantic structure — what's clickable, what's hidden and why, what inputs exist.
+Not screenshots, not HTML dumps. The page as an agent should see it.
+
+The server auto-starts if needed. All commands: `hj <verb> [target] [args]`
+
+## Key Concepts
+
+- **Tree** (`hj tree`): Your eyes. A text list of elements with IDs and flags.
+- **Refs**: Every element has a numeric ID (e.g. 5, 42). Use these to target elements.
+  Refs are stable — they survive re-renders. Always prefer refs over CSS selectors.
+- **Flags**: Check these before acting:
+  [interactive] — clickable/typeable
+  [hidden:display] — invisible, don't interact
+  [disabled] — form field is disabled
+  [required] — must be filled
+- **Quoting**: Only needed for spaces: `hj type 5 "hello world"`. Simple args need no quotes.
+
+## Sample Output (`hj tree`)
+
+```
+( 1 body
+  2 h1 "Sign Up"
+  ( 3 div.form-row
+    4 label "Email:"
+    5 input#email-input type=email placeholder=you@example.com interactive
+  )
+  ( 6 div.form-row
+    7 label "Password:"
+    8 input type=password interactive
+  )
+  9 button#btn-submit interactive "Create Account"
+  ( 10 p
+    11 a href=/login interactive "Already have an account?"
+  )
+  12 div hidden:display "Error: invalid email"
+)
+---
+hj tree --json
+```
+
+Reading this:
+- `(` = children follow (push), `)` = end children (pop)
+- Refs are the numbers (e.g. 5, 9, 11)
+- `interactive` means you can click/type it
+- `hidden:display` means it exists but is invisible
+- Attributes (type, placeholder, href) shown inline
+- Text content in quotes
+- `---` footer shows the command for JSON output
+
+To fill this form:
+- Type email: `hj type 5 "user@example.com"`
+- Type password: `hj type 8 s3cret`
+- Submit: `hj click 9`
+- Check if error appeared: `hj tree` (see if ref 12 lost [hidden])
+
+## Workflow
+
+1. **Inspect**: `hj tree` to see what's on the page
+2. **Plan**: Find the target ref. Confirm it shows [interactive].
+3. **Act**: `hj click`/`hj type`/`hj navigate`
+4. **Verify**: `hj tree` or `hj console` to confirm the result
+
+## Commands
+
+### See the page
+  hj tree                Semantic page structure with refs and flags
+  hj tree --visible      Only visible elements
+  hj tree -d 5           Deeper tree
+  hj tree form           Subtree rooted at selector
+  hj console             Recent console logs/errors
+  hj screenshot          Capture page as image
+  hj location            Current URL and title
+  hj events              Recent semantic events
+
+### Inspect
+  hj inspect 3           Deep details on one element
+  hj query input         Quick element lookup
+  hj call 5 value        Get element property
+  hj eval document.title Run arbitrary JavaScript
+
+### Interact
+  hj click 9             Click by ref (preferred)
+  hj click "Submit"      Click by text content
+  hj click "#btn"        Click by selector (fragile)
+  hj type 5 hello        Type into element
+  hj key Enter           Press key
+  hj key s --ctrl        Keyboard shortcut
+  hj scroll 20           Scroll element into view
+  hj navigate https://...  Go to URL
+
+### Show the user
+  hj highlight 5 "Here"  Draw a labeled box on their screen
+  hj unhighlight          Remove highlight
+
+### Wait
+  hj wait .modal          Wait for element to appear
+  hj wait .loading 10000  Wait up to 10s
+
+### Multiple tabs
+  hj windows              List connected tabs
+  hj click 5 --window abc  Target specific tab
+
+## Tips
+
+- Start with `hj tree` — look for [interactive] to find actionable elements
+- Always prefer refs over selectors — refs survive DOM changes
+- After async actions: `hj wait .spinner` then `hj tree`
+- Show the user what you found: `hj highlight 5 "This button"`
+- If a click fails: `hj console` for JS errors
+- Hidden elements can't be clicked — check [hidden] flag first
+- Some apps use clickable divs: try `hj eval "document.querySelector('#el').click()"` as fallback
+- Forms need proper events: use `hj type` (not eval) to fire input events correctly
+
+## More info
+
+`hj api` for full reference, `hj docs` for quick start.
+```
+
+---
+
+## Notes
+
+- The sample output block is the most important part — agents learn the format by example.
+- Refs are bare numbers. The command verb determines how arguments are parsed,
+  so there's no ambiguity between `hj click 5` (ref) and `hj scroll 300` (pixels).
+- Only quote arguments that contain spaces.

package/docs/getting-started/app.md

@@ -0,0 +1,96 @@
+# Haltija App
+
+You're running Haltija in the desktop app. This gives you a browser with superpowers - the Haltija widget is automatically injected into every page you visit, bypassing security restrictions that would normally block it.
+
+## Quick Start
+
+1. **Navigate to any website** using the address bar above
+2. **Look for the widget** in the bottom-right corner (the elf icon)
+3. **Connect your AI agent** using the REST API at `http://localhost:8700`
+
+## For Your AI Agent
+
+Give your agent this prompt to get started:
+
+```prompt
+I have Haltija running at http://localhost:8700. You can see and control my browser.
+
+**Quick start:**
+1. Check server: curl http://localhost:8700/status
+2. Find tabs: curl http://localhost:8700/windows
+3. See what's on page: curl -X POST http://localhost:8700/tree -d '{"selector":"body","mode":"actionable"}'
+4. Do something: curl -X POST http://localhost:8700/click -d '{"selector":"button"}'
+
+**Key endpoints:**
+- GET /status - check connection, list tabs
+- GET /windows - list connected tabs with IDs
+- GET /location?window=ID - current URL
+- GET /endpoints - compact JSON list of all capabilities
+- POST /tree - see page structure (use mode:"actionable" for summary of buttons/links/inputs)
+- POST /click - click an element
+- POST /type - type into a field
+- POST /scroll - smooth scroll to element or position
+- POST /highlight - show the user an element (with optional label)
+- POST /wait - wait for element to appear/disappear or fixed delay
+- POST /eval - run JavaScript (escape hatch)
+- POST /screenshot - capture page image (see options below)
+- GET /events - recent events including network errors
+- GET /console - recent console logs/errors
+- GET /select/result - get elements user has selected in browser
+
+**Screenshot options:**
+- format: "png" (default), "webp", "jpeg"
+- quality: 0.0-1.0 (for webp/jpeg, default 0.8)
+- scale: 0.5 = half size (saves bandwidth)
+- maxWidth/maxHeight: constrain dimensions (great for vision models)
+- selector: capture specific element instead of full page
+
+Example: curl -X POST http://localhost:8700/screenshot -d '{"scale":0.5,"format":"webp"}'
+
+**Wait for async UI:**
+- curl -X POST http://localhost:8700/wait -d '{"forElement":".modal"}'           # Wait for element
+- curl -X POST http://localhost:8700/wait -d '{"forElement":".loading","hidden":true}'  # Wait for disappear
+- curl -X POST http://localhost:8700/wait -d '{"ms":500}'                         # Simple delay
+
+**Showing things to the user:**
+When explaining something or pointing out an issue, use /highlight to visually show the user:
+- curl -X POST http://localhost:8700/highlight -d '{"selector":"#login-btn","label":"Click here"}'
+- curl -X POST http://localhost:8700/highlight -d '{"selector":".error","label":"This is the problem","color":"#ef4444"}'
+The highlight stays until you call /unhighlight or set a duration in ms.
+
+**Target a specific tab:** Add ?window=<id> or include "window":"id" in POST body
+
+All POST endpoints return: {"success": true, "data": ...} or {"success": false, "error": "..."}
+```
+
+For the full agent prompt with more examples, see [agent-prompt.md](../agent-prompt.md).
+
+## Useful Commands
+
+Check if the server is running:
+```bash
+curl http://localhost:8700/status
+```
+
+Get the page structure:
+```bash
+curl -X POST http://localhost:8700/tree -d '{"selector": "body", "depth": 3}'
+```
+
+Take a screenshot:
+```bash
+curl -X POST http://localhost:8700/screenshot -d '{"scale": 0.5}'
+```
+
+Click a button:
+```bash
+curl -X POST http://localhost:8700/click -d '{"selector": "button"}'
+```
+
+## Keyboard Shortcuts
+
+- **Cmd+T** - New tab
+- **Cmd+W** - Close tab
+- **Cmd+1-9** - Switch to tab
+- **Cmd+L** - Focus address bar
+- **Cmd+R** - Refresh page

package/docs/getting-started/playground.md

@@ -0,0 +1,75 @@
+# Playground
+
+This is a sandbox for testing Haltija commands. The elements below are designed for agents to practice interacting with web pages.
+
+## Interactive Elements
+
+Use these to test clicking, typing, and reading page content.
+
+### Buttons
+
+<div class="test-buttons">
+  <button id="btn-primary" class="btn-test primary">Primary Button</button>
+  <button id="btn-secondary" class="btn-test secondary">Secondary Button</button>
+  <button id="btn-danger" class="btn-test danger">Danger Button</button>
+</div>
+
+### Form Inputs
+
+<div class="test-form">
+  <div class="form-row">
+    <label for="text-input">Text Input:</label>
+    <input type="text" id="text-input" placeholder="Type something here...">
+  </div>
+  <div class="form-row">
+    <label for="email-input">Email:</label>
+    <input type="email" id="email-input" placeholder="you@example.com">
+  </div>
+  <div class="form-row">
+    <label for="select-input">Dropdown:</label>
+    <select id="select-input">
+      <option value="">Choose an option...</option>
+      <option value="a">Option A</option>
+      <option value="b">Option B</option>
+      <option value="c">Option C</option>
+    </select>
+  </div>
+  <div class="form-row">
+    <label>Checkboxes:</label>
+    <div class="checkbox-group">
+      <label><input type="checkbox" id="check-1"> Option 1</label>
+      <label><input type="checkbox" id="check-2"> Option 2</label>
+      <label><input type="checkbox" id="check-3"> Option 3</label>
+    </div>
+  </div>
+</div>
+
+### Output Area
+
+<div id="output" class="output-box">
+  Click buttons or type in fields to see results here.
+</div>
+
+## Test Commands
+
+Try these commands to interact with the playground:
+
+Click the primary button:
+```bash
+curl -X POST http://localhost:8700/click -H "Content-Type: application/json" -d '{"selector": "#btn-primary"}'
+```
+
+Type in the text input:
+```bash
+curl -X POST http://localhost:8700/type -H "Content-Type: application/json" -d '{"selector": "#text-input", "text": "Hello from the agent!"}'
+```
+
+Read the output area:
+```bash
+curl -X POST http://localhost:8700/query -H "Content-Type: application/json" -d '{"selector": "#output"}'
+```
+
+Get all form values:
+```bash
+curl -X POST http://localhost:8700/eval -H "Content-Type: application/json" -d '{"code": "JSON.stringify({text: document.getElementById(\"text-input\").value, email: document.getElementById(\"email-input\").value})"}'
+```

package/docs/getting-started/service.md

@@ -0,0 +1,96 @@
+# Haltija Service
+
+You're running the Haltija server. To give your AI agent browser control, inject the widget into a web page.
+
+## Quick Start
+
+1. **Drag the bookmarklet** below to your bookmarks bar
+2. **Open any website** in your browser
+3. **Click the bookmarklet** to inject the widget
+4. **Use hj commands** to control the browser
+
+## The Bookmarklet
+
+Drag this to your bookmarks bar:
+
+```bookmarklet
+Haltija
+```
+
+Or copy this JavaScript URL manually:
+
+```js
+javascript:(function(){var s=document.createElement('script');s.src='http://localhost:8700/inject.js';document.body.appendChild(s);})()
+```
+
+## For Your AI Agent
+
+Give your agent this prompt:
+
+```
+I have Haltija running. Use the hj command to control my browser:
+
+hj status              # Check connection
+hj tree                # See page structure
+hj click <ref>         # Click by ref ID from tree
+hj click "#selector"   # Click by CSS selector
+hj type <ref> "text"   # Type into input
+hj key Enter           # Press keys
+hj screenshot          # Capture page
+hj docs                # Full command reference
+
+Example workflow:
+1. hj tree              # See what's on page
+2. hj click 42          # Click element with ref 42
+3. hj type 15 "hello"   # Type into input ref 15
+```
+
+## Commands
+
+```bash
+# Check status
+hj status              # Server running?
+hj windows             # Browser tabs connected?
+
+# See the page  
+hj tree                # DOM structure with ref IDs
+hj tree -d 5           # Deeper tree
+hj console             # Browser console output
+
+# Interact
+hj click 42            # Click by ref
+hj click "#submit"     # Click by selector
+hj type 10 "hello"     # Type text
+hj key Enter           # Press key
+hj key s --ctrl        # Keyboard shortcut
+
+# Navigate
+hj navigate example.com
+hj refresh
+hj location
+
+# Show the user
+hj highlight 5 "Look here"
+hj unhighlight
+
+# Capture
+hj screenshot
+hj events              # Recent activity
+```
+
+Run `hj --help` for all commands, or `hj docs` for full reference.
+
+## Troubleshooting
+
+**Widget not appearing?**
+- Some sites have strict CSP that blocks the widget
+- Try the Haltija desktop app: `bunx haltija`
+
+**Agent can't connect?**
+- Click the bookmarklet after the page loads
+- Check widget shows green status (connected)
+- Run `hj status` to verify server
+
+## REST API
+
+For direct HTTP integration, see [REST-API.md](../REST-API.md).

package/docs/recipes.md

@@ -0,0 +1,245 @@
+# Haltija Recipes
+
+Common workflows with copy-paste examples.
+
+---
+
+## Testing a Login Flow
+
+**Goal**: Verify login works end-to-end.
+
+```bash
+# Navigate to login page
+curl -X POST localhost:8700/navigate -d '{"url":"http://localhost:3000/login"}'
+
+# See what's on the form
+curl -X POST localhost:8700/tree -d '{"mode":"actionable"}'
+
+# Fill credentials
+curl -X POST localhost:8700/type -d '{"selector":"#email","text":"test@example.com"}'
+curl -X POST localhost:8700/type -d '{"selector":"#password","text":"secret123"}'
+
+# Submit
+curl -X POST localhost:8700/click -d '{"selector":"button[type=submit]"}'
+
+# Wait for redirect
+curl -X POST localhost:8700/wait -d '{"selector":".dashboard","timeout":5000}'
+
+# Verify we landed on dashboard
+curl localhost:8700/location
+```
+
+**Or just tell the agent**: "Log in with test@example.com / secret123 and verify the dashboard loads"
+
+---
+
+## Exploring a New Codebase UI
+
+**Goal**: Understand what's on the page without reading source code.
+
+```bash
+# Get high-level structure
+curl -X POST localhost:8700/tree -d '{"depth":2,"compact":true}'
+
+# Find all interactive elements
+curl -X POST localhost:8700/tree -d '{"mode":"actionable"}'
+
+# Inspect a specific component
+curl -X POST localhost:8700/inspect -d '{"selector":"nav","fullStyles":true}'
+
+# See what CSS rules apply
+curl -X POST localhost:8700/inspect -d '{"selector":".header","matchedRules":true}'
+```
+
+**Or just tell the agent**: "What's on this page? Walk me through the main sections."
+
+---
+
+## Recording a Bug Reproduction
+
+**Goal**: Capture steps to reproduce a bug for the team.
+
+```bash
+# Start watching events
+curl -X POST localhost:8700/events/watch -d '{"preset":"interactive"}'
+
+# ... user reproduces the bug manually ...
+
+# Get what happened
+curl localhost:8700/events
+
+# Take a screenshot of the broken state
+curl -X POST localhost:8700/screenshot -d '{"scale":0.5}'
+```
+
+**Output**: Semantic events like "user clicked Settings", "user typed 'admin'", "error: 500 from /api/users"
+
+**Or just tell the agent**: "Watch what I do and write up repro steps"
+
+---
+
+## Generating Tests from Manual Exploration
+
+**Goal**: Turn a manual walkthrough into an automated test.
+
+```bash
+# Start recording
+curl -X POST localhost:8700/recording/start -d '{"name":"checkout-flow"}'
+
+# ... click around manually ...
+
+# Stop and generate test
+curl -X POST localhost:8700/recording/stop
+curl -X POST localhost:8700/recording/generate -d '{"name":"checkout-flow"}'
+```
+
+**Output**: JSON test file ready for CI.
+
+**Or just tell the agent**: "Watch me go through checkout, then write a test for it"
+
+---
+
+## Debugging a Customer Issue
+
+**Goal**: See exactly what a customer described.
+
+```bash
+# Navigate to where they were
+curl -X POST localhost:8700/navigate -d '{"url":"https://app.example.com/settings"}'
+
+# Get the current state
+curl -X POST localhost:8700/tree -d '{"mode":"actionable"}'
+
+# Check for errors
+curl localhost:8700/events
+
+# Highlight what might be wrong
+curl -X POST localhost:8700/highlight -d '{"selector":".error-message","label":"This error"}'
+
+# Screenshot for the ticket
+curl -X POST localhost:8700/screenshot -d '{"maxWidth":1200}'
+```
+
+**Or just tell the agent**: "Customer says Settings page is broken. Check it out."
+
+---
+
+## Checking Accessibility
+
+**Goal**: Audit a page for accessibility issues.
+
+```bash
+# Get all interactive elements with ARIA info
+curl -X POST localhost:8700/tree -d '{"mode":"actionable","depth":-1}'
+
+# Inspect specific element for ARIA attributes
+curl -X POST localhost:8700/inspect -d '{"selector":"button.icon-only"}'
+
+# Check all buttons have accessible names
+curl -X POST localhost:8700/find -d '{"selector":"button","text":""}'
+```
+
+**Look for**: Missing `aria-label`, buttons with only icons, form inputs without labels.
+
+**Or just tell the agent**: "Check this page for accessibility issues"
+
+---
+
+## Multi-Tab Testing (OAuth, Admin/User)
+
+**Goal**: Test flows that span multiple windows.
+
+```bash
+# See all connected tabs
+curl localhost:8700/windows
+
+# Returns: {"windows":[{"windowId":"abc","url":"..."},{"windowId":"def","url":"..."}]}
+
+# Click in specific tab
+curl -X POST "localhost:8700/click?window=abc" -d '{"selector":"#authorize"}'
+
+# Check other tab updated
+curl "localhost:8700/location?window=def"
+```
+
+**Use case**: OAuth popups, admin + customer side-by-side, multi-tenant testing.
+
+---
+
+## Waiting for Dynamic Content
+
+**Goal**: Handle SPAs where content loads async.
+
+```bash
+# Wait for element to appear
+curl -X POST localhost:8700/wait -d '{"selector":".results","timeout":10000}'
+
+# Wait for element to disappear (loading spinner)
+curl -X POST localhost:8700/wait -d '{"selector":".loading","appear":false}'
+
+# Wait for text content
+curl -X POST localhost:8700/wait -d '{"selector":".status","text":"Complete"}'
+```
+
+**Or just tell the agent**: "Click Search and wait for results to load"
+
+---
+
+## Pointing Things Out to Users
+
+**Goal**: Show users what you're talking about.
+
+```bash
+# Highlight with label
+curl -X POST localhost:8700/highlight -d '{"selector":"#save-btn","label":"Click here"}'
+
+# Highlight problem area in red
+curl -X POST localhost:8700/highlight -d '{"selector":".broken","label":"Bug","color":"#ef4444"}'
+
+# Auto-dismiss after 3 seconds
+curl -X POST localhost:8700/highlight -d '{"selector":"nav","duration":3000}'
+
+# Clear highlight
+curl -X POST localhost:8700/unhighlight
+```
+
+**Best practice**: Always highlight when explaining something visual.
+
+---
+
+## User Selection (Point at Problem)
+
+**Goal**: Let user show you what's wrong.
+
+```bash
+# Start selection mode
+curl -X POST localhost:8700/select/start
+
+# ... user drags rectangle over problem area ...
+
+# Get what they selected
+curl localhost:8700/select/result
+
+# Returns: elements in selection with selectors, HTML, bounding boxes
+```
+
+**Or just tell the agent**: "Let me show you which element is broken"
+
+---
+
+## Quick Health Check
+
+**Goal**: Verify Haltija is working.
+
+```bash
+# Server running?
+curl localhost:8700/status
+
+# Browser connected?
+curl localhost:8700/windows
+
+# Can we see the page?
+curl -X POST localhost:8700/tree -d '{"depth":1}'
+```
+
+If all three work, you're ready to go.