High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix: update all documentation examples to use correct API routes
Marioaf40f19e868c
diff --git a/docs/get-started.md b/docs/get-started.mdindex 378b51ff..2cac802d 100644--- a/docs/get-started.md+++ b/docs/get-started.md@@ -94,10 +94,10 @@ sleep 3pinchtab instance navigate $INST https://example.com# Get page structure-curl http://localhost:9867/instances/$INST/snapshot | jq '.nodes | map({role, name}) | .[0:5]'+curl http://localhost:9867/tabs/$TAB_ID/snapshot | jq '.nodes | map({role, name}) | .[0:5]'# Extract text-curl http://localhost:9867/instances/$INST/text | jq '.text'+curl http://localhost:9867/tabs/$TAB_ID/text | jq '.text'```✅ **You're running PinchTab!**@@ -113,14 +113,14 @@ INST=$(pinchtab instance launch | jq -r '.id')sleep 2# Navigate-TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \- -d '{"url":"https://example.com"}' | jq -r '.tabId')+TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \+ -d '{"url":"https://example.com"}' | jq -r '.id')# Read the page as text-curl http://localhost:9867/instances/$INST/text+curl http://localhost:9867/tabs/$TAB_ID/text# Get interactive elements (snapshot)-curl http://localhost:9867/instances/$INST/snapshot | jq '.nodes | map({ref, role, name})'+curl http://localhost:9867/tabs/$TAB_ID/snapshot | jq '.nodes | map({ref, role, name})'```### Take a Screenshot@@ -141,18 +141,18 @@ curl "http://localhost:9867/tabs/$TAB_ID/pdf?landscape=true" -o output.pdf```bash# Get page structure (snapshot)-SNAPSHOT=$(curl http://localhost:9867/instances/$INST/snapshot)+SNAPSHOT=$(curl http://localhost:9867/tabs/$TAB_ID/snapshot)# Extract a reference (e.g., first button)BUTTON_REF=$(echo "$SNAPSHOT" | jq -r '.nodes[] | select(.role=="button") | .ref' | head -1)# Click the button-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-H "Content-Type: application/json" \-d '{"kind":"click","ref":"'$BUTTON_REF'"}'# Or fill a form input-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-H "Content-Type: application/json" \-d '{"kind":"fill","ref":"e3","text":"[email protected]"}'```@@ -171,7 +171,7 @@ curl http://localhost:9867/tabs# Operate on specific tabTAB_ID=$(curl http://localhost:9867/instances/$INST/tabs | jq -r '.[0].id')-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"click","ref":"e5","tabId":"'$TAB_ID'"}'```@@ -205,18 +205,18 @@ INST=$(pinchtab instance launch | jq -r '.id')sleep 2# 2. Navigate to a page-TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \- -d '{"url":"https://example.com"}' | jq -r '.tabId')+TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \+ -d '{"url":"https://example.com"}' | jq -r '.id')# 3. Get page structure (see buttons, links, inputs)-curl http://localhost:9867/instances/$INST/snapshot+curl http://localhost:9867/tabs/$TAB_ID/snapshot# 4. Interact with page (click, type, etc.)-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"click","ref":"e5"}'# 5. Verify changes-curl http://localhost:9867/instances/$INST/snapshot+curl http://localhost:9867/tabs/$TAB_ID/snapshot# 6. Capture resultcurl "http://localhost:9867/tabs/$TAB_ID/screenshot" -o page.png@@ -241,15 +241,15 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch | jq -r '.id')sleep 2# Navigate-curl -X POST http://localhost:9867/instances/$INST/navigate \+curl -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \-d '{"url":"https://example.com"}'# Get snapshot-curl http://localhost:9867/instances/$INST/snapshot+curl http://localhost:9867/tabs/$TAB_ID/snapshot# Extract text-curl http://localhost:9867/instances/$INST/text+curl http://localhost:9867/tabs/$TAB_ID/text# Stop instancecurl -X POST http://localhost:9867/instances/$INST/stop@@ -277,14 +277,15 @@ print(f"Created instance: {inst_id}")# Wait for Chrome to initializetime.sleep(2)-# 2. Navigate-resp = requests.post(f"{BASE}/instances/{inst_id}/navigate", json={+# 2. Create tab by navigating+resp = requests.post(f"{BASE}/instances/{inst_id}/tabs/open", json={"url": "https://example.com"})+tab_id = resp.json()["id"]print(f"Navigated: {resp.json()}")# 3. Get snapshot-snapshot = requests.get(f"{BASE}/instances/{inst_id}/snapshot").json()+snapshot = requests.get(f"{BASE}/tabs/{tab_id}/snapshot").json()# Print interactive elementsfor elem in snapshot.get("nodes", []):@@ -292,13 +293,13 @@ for elem in snapshot.get("nodes", []):print(f"{elem['ref']}: {elem['role']} - {elem['name']}")# 4. Click an element-requests.post(f"{BASE}/instances/{inst_id}/action", json={- "kind": "click",+requests.post(f"{BASE}/tabs/{tab_id}/action", json={+ "action": "click","ref": "e5"})# 5. Get text-text = requests.get(f"{BASE}/instances/{inst_id}/text").json()+text = requests.get(f"{BASE}/tabs/{tab_id}/text").json()print(f"Page text: {text['text'][:200]}...")# 6. Stop instance@@ -330,17 +331,19 @@ async function main() {// Wait for Chrome to initializeawait new Promise(r => setTimeout(r, 2000));- // 2. Navigate- await fetch(`${BASE}/instances/${instId}/navigate`, {+ // 2. Create tab by navigating+ const navResp = await fetch(`${BASE}/instances/${instId}/tabs/open`, {method: "POST",headers: { "Content-Type": "application/json" },body: JSON.stringify({url: "https://example.com"})});+ const navData = await navResp.json();+ const tabId = navData.id;// 3. Get snapshot- const snapResp = await fetch(`${BASE}/instances/${instId}/snapshot`);+ const snapResp = await fetch(`${BASE}/tabs/${tabId}/snapshot`);const snap = await snapResp.json();// Print interactive elements@@ -349,17 +352,17 @@ async function main() {.forEach(n => console.log(`${n.ref}: ${n.role} - ${n.name}`));// 4. Click element- await fetch(`${BASE}/instances/${instId}/action`, {+ await fetch(`${BASE}/tabs/${tabId}/action`, {method: "POST",headers: { "Content-Type": "application/json" },body: JSON.stringify({- kind: "click",+ action: "click",ref: "e5"})});// 5. Get text- const textResp = await fetch(`${BASE}/instances/${instId}/text`);+ const textResp = await fetch(`${BASE}/tabs/${tabId}/text`);const text = await textResp.json();console.log(`Page text: ${text.text.substring(0, 200)}...`);@@ -432,14 +435,14 @@ INST=$(pinchtab instance launch | jq -r '.id')sleep 2# Navigate-curl -X POST http://localhost:9867/instances/$INST/navigate \+curl -X POST http://localhost:9867/instances/$INST/tabs/open \-d '{"url":"https://example.com/article"}'# Extract text-curl http://localhost:9867/instances/$INST/text | jq '.text'+curl http://localhost:9867/tabs/$TAB_ID/text | jq '.text'# Save to file-curl http://localhost:9867/instances/$INST/text | jq -r '.text' > article.txt+curl http://localhost:9867/tabs/$TAB_ID/text | jq -r '.text' > article.txt# Stop instancecurl -X POST http://localhost:9867/instances/$INST/stop@@ -453,28 +456,28 @@ INST=$(pinchtab instance launch | jq -r '.id')sleep 2# Navigate to form-curl -X POST http://localhost:9867/instances/$INST/navigate \+curl -X POST http://localhost:9867/instances/$INST/tabs/open \-d '{"url":"https://example.com/contact"}'# Get form structure-SNAP=$(curl http://localhost:9867/instances/$INST/snapshot)+SNAP=$(curl http://localhost:9867/tabs/$TAB_ID/snapshot)# Fill fields (get refs from snapshot)-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"fill","ref":"e3","text":"John Doe"}'-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"fill","ref":"e5","text":"[email protected]"}'-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"fill","ref":"e7","text":"My message here"}'# Click submit-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"click","ref":"e10"}'# Verify success-curl http://localhost:9867/instances/$INST/snapshot | jq '.nodes | length'+curl http://localhost:9867/tabs/$TAB_ID/snapshot | jq '.nodes | length'```### Scenario 3: Login + Stay Logged In@@ -490,16 +493,16 @@ INST=$(curl -s -X POST http://localhost:9867/instances/start \sleep 2# Login-curl -X POST http://localhost:9867/instances/$INST/navigate \+curl -X POST http://localhost:9867/instances/$INST/tabs/open \-d '{"url":"https://example.com/login"}'-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"fill","ref":"e3","text":"[email protected]"}'-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"fill","ref":"e5","text":"password"}'-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"click","ref":"e7"}'# Stop instance (profile saved)@@ -511,7 +514,7 @@ INST=$(curl -s -X POST http://localhost:9867/instances/start \sleep 2# Navigate to dashboard (cookies preserved)-curl -X POST http://localhost:9867/instances/$INST/navigate \+curl -X POST http://localhost:9867/instances/$INST/tabs/open \-d '{"url":"https://example.com/dashboard"}'```@@ -522,8 +525,8 @@ curl -X POST http://localhost:9867/instances/$INST/navigate \INST=$(pinchtab instance launch | jq -r '.id')sleep 2-TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \- -d '{"url":"https://reports.example.com/monthly"}' | jq -r '.tabId')+TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \+ -d '{"url":"https://reports.example.com/monthly"}' | jq -r '.id')# Export PDFcurl "http://localhost:9867/tabs/$TAB_ID/pdf?landscape=true" -o report.pdf```@@ -549,10 +552,10 @@ SOURCE_TAB=$(echo "$TABS" | jq -r '.[0].id')DEST_TAB=$(echo "$TABS" | jq -r '.[1].id')# Extract from source tab-DATA=$(curl "http://localhost:9867/instances/$INST/text" | jq -r '.text')+DATA=$(curl "http://localhost:9867/tabs/$TAB_ID/text" | jq -r '.text')# Fill destination tab-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-H "Content-Type: application/json" \-d '{"kind":"fill","ref":"e3","text":"'$DATA'","tabId":"'$DEST_TAB'"}'```@@ -589,7 +592,7 @@ while [ "$(curl -s http://localhost:9867/instances/$INST | jq -r '.status')" !=done# Now safe to use-curl -X POST http://localhost:9867/instances/$INST/navigate \+curl -X POST http://localhost:9867/instances/$INST/tabs/open \-d '{"url":"https://example.com"}'```@@ -648,13 +651,13 @@ curl http://localhost:9867/instances/$INST**Solution:**```bash# Get fresh snapshot-SNAP=$(curl http://localhost:9867/instances/$INST/snapshot)+SNAP=$(curl http://localhost:9867/tabs/$TAB_ID/snapshot)# Extract new ref from snapshotNEW_REF=$(echo "$SNAP" | jq -r '.nodes[] | select(.role=="button") | .ref' | head -1)# Use new ref-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"click","ref":"'$NEW_REF'"}'```@@ -666,13 +669,13 @@ curl -X POST http://localhost:9867/instances/$INST/action \```bash# Get text content-curl http://localhost:9867/instances/$INST/text+curl http://localhost:9867/tabs/$TAB_ID/text# Get snapshot (DOM structure)-curl http://localhost:9867/instances/$INST/snapshot+curl http://localhost:9867/tabs/$TAB_ID/snapshot# Filter snapshot to interactive elements-curl http://localhost:9867/instances/$INST/snapshot | \+curl http://localhost:9867/tabs/$TAB_ID/snapshot | \jq '.nodes[] | select(.role | IN("button", "link", "textbox"))'```@@ -680,31 +683,31 @@ curl http://localhost:9867/instances/$INST/snapshot | \```bash# Click element-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"click","ref":"e5"}'# Type text-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"type","ref":"e3","text":"hello"}'# Fill input-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"fill","ref":"e3","text":"value"}'# Press key-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"press","key":"Enter"}'# Focus element-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"focus","ref":"e5"}'# Hover element-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"hover","ref":"e5"}'# Select dropdown-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \-d '{"kind":"select","ref":"e8","text":"Option 2"}'```@@ -748,7 +751,7 @@ done# Distribute work across instances (round-robin)for URL in "${URLS[@]}"; doINST="${INSTANCES[$((INDEX % 5))]}"- curl -X POST "http://localhost:9867/instances/$INST/navigate" \+ curl -X POST "http://localhost:9867/instances/$INST/tabs/open" \-d '{"url":"'$URL'"}' &((INDEX++))done@@ -759,10 +762,10 @@ wait```bash# Use text extraction (cheaper than screenshots)-curl http://localhost:9867/instances/$INST/text # Lower tokens+curl http://localhost:9867/tabs/$TAB_ID/text # Lower tokens# Use snapshot (cheaper than screenshot)-curl http://localhost:9867/instances/$INST/snapshot # Lower tokens+curl http://localhost:9867/tabs/$TAB_ID/snapshot # Lower tokens# Screenshots are expensive (JPG encoding)curl "http://localhost:9867/tabs/$TAB_ID/screenshot" # Higher tokens@@ -777,11 +780,11 @@ curl "http://localhost:9867/tabs/$TAB_ID/screenshot" # Higher tokens| Start orchestrator | `pinchtab` || Health check | `curl http://localhost:9867/health` || Create instance | `INST=$(pinchtab instance launch \| jq -r '.id')` |-| Navigate | `curl -X POST http://localhost:9867/instances/$INST/navigate -d '{"url":"..."}' ` |-| See structure | `curl http://localhost:9867/instances/$INST/snapshot` |-| Get text | `curl http://localhost:9867/instances/$INST/text` |-| Click element | `curl -X POST http://localhost:9867/instances/$INST/action -d '{"kind":"click","ref":"e5"}'` |-| Type text | `curl -X POST http://localhost:9867/instances/$INST/action -d '{"kind":"type","ref":"e3","text":"hello"}'` |+| Navigate | `curl -X POST http://localhost:9867/instances/$INST/tabs/open -d '{"url":"..."}' ` |+| See structure | `curl http://localhost:9867/tabs/$TAB_ID/snapshot` |+| Get text | `curl http://localhost:9867/tabs/$TAB_ID/text` |+| Click element | `curl -X POST http://localhost:9867/tabs/$TAB_ID/action -d '{"kind":"click","ref":"e5"}'` |+| Type text | `curl -X POST http://localhost:9867/tabs/$TAB_ID/action -d '{"kind":"type","ref":"e3","text":"hello"}'` || Screenshot | `curl "http://localhost:9867/tabs/$TAB_ID/screenshot" -o page.png` || PDF export | `curl http://localhost:9867/tabs/$TAB_ID/pdf -o out.pdf` || List instances | `curl http://localhost:9867/instances` |diff --git a/docs/guides/common-patterns.md b/docs/guides/common-patterns.mdindex 1eff8655..ca1fbbaf 100644--- a/docs/guides/common-patterns.md+++ b/docs/guides/common-patterns.md@@ -47,7 +47,7 @@ echo "Chrome window is open - interact manually or use API calls"sleep 2# Optionally navigate to starting URL (via orchestrator proxy)-curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \+curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \-H "Content-Type: application/json" \-d '{"url":"https://app.example.com"}'@@ -115,12 +115,12 @@ for i in "${!INSTANCES[@]}"; do# Run test in parallel (via orchestrator proxy)(- curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \+ curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \-H "Content-Type: application/json" \-d "{\"url\":\"$URL\"}" > /dev/null# Verify page loaded- TITLE=$(curl -s "http://localhost:9867/instances/$INST/snapshot" | jq -r '.title')+ TITLE=$(curl -s "http://localhost:9867/tabs/$TAB_ID/snapshot" | jq -r '.title')echo "Test $i: $TITLE") &done@@ -195,7 +195,7 @@ for i in "${!URLS[@]}"; doURL="${URLS[$i]}"INST="${INSTANCES[$((i % ${#INSTANCES[@]}))]}"- curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \+ curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \-H "Content-Type: application/json" \-d "{\"url\":\"$URL\"}" &done@@ -243,7 +243,7 @@ for i in "${!URLS[@]}"; doURL="${URLS[$i]}"INST="${INSTANCES[$((i % ${#INSTANCES[@]}))]}"- curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \+ curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \-H "Content-Type: application/json" \-d "{\"url\":\"$URL\"}" &done@@ -291,7 +291,7 @@ for i in $(seq 0 $((MAX_JOBS - 1))); doINST="${INSTANCES[$((CURRENT_JOB % MAX_JOBS))]}"(- curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \+ curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \-H "Content-Type: application/json" \-d "{\"url\":\"$URL\"}" > /dev/nullecho "Processed: $URL"@@ -306,7 +306,7 @@ while [ $CURRENT_JOB -lt ${#QUEUE[@]} ]; doINST="${INSTANCES[$((CURRENT_JOB % MAX_JOBS))]}"(- curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \+ curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \-H "Content-Type: application/json" \-d "{\"url\":\"$URL\"}" > /dev/nullecho "Processed: $URL"@@ -366,7 +366,7 @@ U3=$(curl -s -X POST http://localhost:9867/instances/start \# - No interference between users# User 1 navigates (via orchestrator proxy)-curl -s -X POST "http://localhost:9867/instances/$U1/navigate" \+curl -s -X POST "http://localhost:9867/instances/$U1/tabs/open" \-H "Content-Type: application/json" \-d '{"url":"https://app.example.com/login?user=1"}'diff --git a/docs/guides/multi-instance.md b/docs/guides/multi-instance.mdindex 6fea0bb3..14b22d26 100644--- a/docs/guides/multi-instance.md+++ b/docs/guides/multi-instance.md@@ -47,7 +47,7 @@ The instance gets:Navigate the instance via the orchestrator (recommended):```bash-curl -X POST http://localhost:9867/instances/inst_a365262a/navigate \+curl -X POST http://localhost:9867/instances/inst_a365262a/tabs/open \-H "Content-Type: application/json" \-d '{"url":"https://example.com"}'```@@ -55,28 +55,31 @@ curl -X POST http://localhost:9867/instances/inst_a365262a/navigate \**Response:**```json{- "tabId": "tab_19949f62",+ "id": "tab_19949f62","url": "https://example.com","title": "Example Domain"}```-Each navigation automatically creates a new tab. Use the `tabId` for subsequent operations on that specific tab.+Each navigation automatically creates a new tab. Use the `id` (tabId) for subsequent operations on that specific tab.-**Note:** You can also access the instance directly on its port (9868), but using the orchestrator proxy (`9867/instances/{id}/*`) is recommended for consistency.+**Note:** You can also access the instance directly on its port (9868), but using the orchestrator proxy is recommended for consistency.### 4. Get Page Content-Retrieve page snapshot (DOM, text, structured data) via orchestrator:+Retrieve page snapshot using the tab ID:```bash-curl http://localhost:9867/instances/inst_a365262a/snapshot+TAB=$(curl -s -X POST http://localhost:9867/instances/inst_a365262a/tabs/open \+ -d '{"url":"https://example.com"}' | jq -r '.id')++curl http://localhost:9867/tabs/$TAB/snapshot```Or get just the text:```bash-curl http://localhost:9867/instances/inst_a365262a/text+curl http://localhost:9867/tabs/$TAB/text```### 5. Stop Instance@@ -132,24 +135,26 @@ sleep 2echo "Navigating all instances concurrently..."-# Navigate all instances via orchestrator proxy (concurrent)+# Navigate all instances and capture tab IDs+TABS=()for i in "${!INSTANCES[@]}"; doID="${INSTANCES[$i]}"URL="${URLS[$i]}"- curl -s -X POST "http://localhost:9867/instances/$ID/navigate" \+ RESPONSE=$(curl -s -X POST "http://localhost:9867/instances/$ID/tabs/open" \-H "Content-Type: application/json" \- -d "{\"url\":\"$URL\"}" &+ -d "{\"url\":\"$URL\"}")+ TAB_ID=$(echo "$RESPONSE" | jq -r '.id')+ TABS+=("$TAB_ID")done-waitecho "All pages loaded. Getting snapshots..."-# Get snapshots-for i in "${!INSTANCES[@]}"; do- ID="${INSTANCES[$i]}"+# Get snapshots using tab IDs+for i in "${!TABS[@]}"; do+ TAB="${TABS[$i]}"- curl -s "http://localhost:9867/instances/$ID/snapshot" > "snapshot-$i.json" &+ curl -s "http://localhost:9867/tabs/$TAB/snapshot" > "snapshot-$i.json" &donewait@@ -248,7 +253,7 @@ for TASK in "${TASKS[@]}"; doID="${INSTANCES[$((INSTANCE_INDEX % $FLEET_SIZE))]}"# Send task to instance via orchestrator proxy- curl -s -X POST "http://localhost:9867/instances/$ID/navigate" \+ curl -s -X POST "http://localhost:9867/instances/$ID/tabs/open" \-H "Content-Type: application/json" \-d "{\"url\":\"https://api.example.com?task=$TASK\"}" > /dev/null &@@ -402,7 +407,7 @@ while [ "$(curl -s http://localhost:9867/instances/$INST | jq -r '.status')" !=done# Now safe to use-curl -X POST http://localhost:9867/instances/$INST/navigate \+curl -X POST http://localhost:9867/instances/$INST/tabs/open \-d '{"url":"https://example.com"}'```@@ -550,7 +555,7 @@ while [ "$(curl -s http://localhost:9867/instances/$INST | jq -r '.status')" !=done# Now safe to navigate-curl -X POST http://localhost:9867/instances/$INST/navigate \+curl -X POST http://localhost:9867/instances/$INST/tabs/open \-d '{"url":"https://example.com"}'```@@ -593,11 +598,11 @@ Frees ports and RAM for new instances.```bash# DO: Use orchestrator proxy (recommended)-curl -X POST http://localhost:9867/instances/$INST/navigate \+curl -X POST http://localhost:9867/instances/$INST/tabs/open \-d '{"url":"https://example.com"}'# AVOID: Direct port access (less consistent)-curl -X POST http://localhost:$PORT/navigate \+curl -X POST http://localhost:$PORT/tabs/open \-d '{"url":"https://example.com"}'```@@ -758,7 +763,7 @@ curl -X POST http://localhost:9867/instances/$OLD_INST/stop```bash# Instance IDs are stable, but ports change on restart# Always use orchestrator proxy:-curl http://localhost:9867/instances/$INST/navigate \+curl http://localhost:9867/instances/$INST/tabs/open \-d '{"url":"https://example.com"}'# Don't rely on cached port numbersdiff --git a/docs/showcase.md b/docs/showcase.mdindex 689bb8b5..9e0962e0 100644--- a/docs/showcase.md+++ b/docs/showcase.md@@ -76,11 +76,11 @@ curl -X POST http://localhost:9867/instances/launch \sleep 2```-**Step 3: Navigate to URL (returns tabId)**+**Step 3: Create tab and navigate to URL (returns tabId)**```bash-TAB=$(curl -s -X POST http://localhost:9867/instances/inst_abc123/navigate \+TAB=$(curl -s -X POST http://localhost:9867/instances/inst_abc123/tabs/open \-H "Content-Type: application/json" \- -d '{"url":"https://example.com"}' | jq -r '.tabId')+ -d '{"url":"https://example.com"}' | jq -r '.id')echo "Tab created: $TAB"```@@ -88,7 +88,7 @@ echo "Tab created: $TAB"**Response contains:**```json{- "tabId": "tab_def456",+ "id": "tab_def456","title": "Example Domain","url": "https://example.com/"}@@ -96,7 +96,7 @@ echo "Tab created: $TAB"**Step 4: Extract text (use tabId)**```bash-curl "http://localhost:9867/instances/inst_abc123/text?tabId=$TAB"+curl "http://localhost:9867/tabs/$TAB/text"```**Response:**@@ -122,16 +122,16 @@ echo "Created instance: $INST"# Step 2: Wait for Chrome initializationsleep 2-# Step 3: Navigate and capture tabId-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \+# Step 3: Create tab by navigating+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \- -d "{\"url\":\"$URL\"}" | jq -r '.tabId')+ -d "{\"url\":\"$URL\"}" | jq -r '.id')echo "Created tab: $TAB"-# Step 4: Get text using tabId+# Step 4: Get textecho "Extracting text from $URL..."-curl -s "http://localhost:9867/instances/$INST/text?tabId=$TAB" | jq '.text'+curl -s "http://localhost:9867/tabs/$TAB/text" | jq '.text'# Step 5: Cleanupcurl -s -X POST "http://localhost:9867/instances/$INST/stop"@@ -146,7 +146,7 @@ echo "Stopped instance: $INST"### Step-by-Step-**Step 1: Create instance and navigate (get tabId)**+**Step 1: Create instance and navigate to get tabId**```bashINST=$(curl -s -X POST http://localhost:9867/instances/launch \-H "Content-Type: application/json" \@@ -154,16 +154,16 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \sleep 2-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \- -d '{"url":"https://example.com/interactive"}' | jq -r '.tabId')+ -d '{"url":"https://example.com/interactive"}' | jq -r '.id')echo "Instance: $INST, Tab: $TAB"```-**Step 2: Get snapshot (see interactive elements, use tabId)**+**Step 2: Get snapshot (see interactive elements)**```bash-curl "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB"+curl "http://localhost:9867/tabs/$TAB/snapshot"```**Response:**@@ -189,16 +189,16 @@ curl "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB"}```-**Step 3: Click element (e5, use tabId)**+**Step 3: Click element**```bash-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB/action \-H "Content-Type: application/json" \- -d '{"kind":"click","ref":"e5","tabId":"'$TAB'"}'+ -d '{"action":"click","ref":"e5"}'```-**Step 4: Verify result (snapshot again, use tabId)**+**Step 4: Verify result**```bash-curl "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB" | jq '.nodes'+curl "http://localhost:9867/tabs/$TAB/snapshot" | jq '.nodes'```**Complete script:**@@ -213,29 +213,29 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \echo "Instance: $INST"-# Step 2: Wait and navigate (capture tabId)+# Step 2: Wait and navigate to create tabsleep 2-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \- -d "{\"url\":\"$URL\"}" | jq -r '.tabId')+ -d "{\"url\":\"$URL\"}" | jq -r '.id')echo "Tab: $TAB"-# Step 3: Get interactive elements using tabId+# Step 3: Get interactive elementsecho "Getting interactive elements..."-SNAPSHOT=$(curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB")+SNAPSHOT=$(curl -s "http://localhost:9867/tabs/$TAB/snapshot")echo "$SNAPSHOT" | jq '.nodes[] | select(.role | IN("button", "link")) | {ref, name}'-# Step 4: Click button using tabId+# Step 4: Click buttonecho "Clicking button e5..."-curl -s -X POST http://localhost:9867/instances/$INST/action \+curl -s -X POST http://localhost:9867/tabs/$TAB/action \-H "Content-Type: application/json" \- -d '{"kind":"click","ref":"e5","tabId":"'$TAB'"}'+ -d '{"action":"click","ref":"e5"}'-# Step 5: Wait for action and verify using tabId+# Step 5: Wait for action and verifysleep 1echo "Verifying result..."-curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB" | jq '.nodes[] | {ref, role, name}' | head -10+curl -s "http://localhost:9867/tabs/$TAB/snapshot" | jq '.nodes[] | {ref, role, name}' | head -10# Step 6: Cleanupcurl -s -X POST "http://localhost:9867/instances/$INST/stop"@@ -250,7 +250,7 @@ echo "Stopped instance: $INST"### Step-by-Step-**Step 1: Create instance and navigate to form (capture tabId)**+**Step 1: Create instance and navigate to form**```bashINST=$(curl -s -X POST http://localhost:9867/instances/launch \-H "Content-Type: application/json" \@@ -258,16 +258,16 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \sleep 2-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \- -d '{"url":"https://example.com/login"}' | jq -r '.tabId')+ -d '{"url":"https://example.com/login"}' | jq -r '.id')echo "Instance: $INST, Tab: $TAB"```-**Step 2: Get form fields (snapshot with tabId)**+**Step 2: Get form fields**```bash-curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB" | jq '.nodes[] | select(.role | IN("textbox", "button"))'+curl -s "http://localhost:9867/tabs/$TAB/snapshot" | jq '.nodes[] | select(.role | IN("textbox", "button"))'```**Output:**@@ -289,30 +289,30 @@ curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB" | jq '.nodes}```-**Step 3: Fill email field (e3, use tabId)**+**Step 3: Fill email field**```bash-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB/action \-H "Content-Type: application/json" \- -d '{"kind":"fill","ref":"e3","text":"[email protected]","tabId":"'$TAB'"}'+ -d '{"action":"fill","ref":"e3","text":"[email protected]"}'```-**Step 4: Fill password field (e5, use tabId)**+**Step 4: Fill password field**```bash-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB/action \-H "Content-Type: application/json" \- -d '{"kind":"fill","ref":"e5","text":"mypassword","tabId":"'$TAB'"}'+ -d '{"action":"fill","ref":"e5","text":"mypassword"}'```-**Step 5: Click submit (e7, use tabId)**+**Step 5: Click submit**```bash-curl -X POST http://localhost:9867/instances/$INST/action \+curl -X POST http://localhost:9867/tabs/$TAB/action \-H "Content-Type: application/json" \- -d '{"kind":"click","ref":"e7","tabId":"'$TAB'"}'+ -d '{"action":"click","ref":"e7"}'```-**Step 6: Verify success (check page, use tabId)**+**Step 6: Verify success (check page)**```bash-curl -s "http://localhost:9867/instances/$INST/text?tabId=$TAB" | jq '.text'+curl -s "http://localhost:9867/tabs/$TAB/text" | jq '.text'```**Complete script:**@@ -328,39 +328,39 @@ echo "Instance: $INST"# Step 2: Wait and navigate (capture tabId)sleep 2-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \- -d '{"url":"https://example.com/login"}' | jq -r '.tabId')+ -d '{"url":"https://example.com/login"}' | jq -r '.id')echo "Tab: $TAB"# Step 3: Get form fieldsecho "Getting form fields..."-curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB" | \+curl -s "http://localhost:9867/tabs/$TAB/snapshot" | \jq '.nodes[] | select(.role | IN("textbox", "button")) | {ref, name}'-# Step 4: Fill email using tabId-curl -s -X POST http://localhost:9867/instances/$INST/action \+# Step 4: Fill email+curl -s -X POST http://localhost:9867/tabs/$TAB/action \-H "Content-Type: application/json" \- -d '{"kind":"fill","ref":"e3","text":"[email protected]","tabId":"'$TAB'"}'+ -d '{"action":"fill","ref":"e3","text":"[email protected]"}'-# Step 5: Fill password using tabId-curl -s -X POST http://localhost:9867/instances/$INST/action \+# Step 5: Fill password+curl -s -X POST http://localhost:9867/tabs/$TAB/action \-H "Content-Type: application/json" \- -d '{"kind":"fill","ref":"e5","text":"mypassword","tabId":"'$TAB'"}'+ -d '{"action":"fill","ref":"e5","text":"mypassword"}'-# Step 6: Click submit using tabId+# Step 6: Click submitecho "Submitting form..."-curl -s -X POST http://localhost:9867/instances/$INST/action \+curl -s -X POST http://localhost:9867/tabs/$TAB/action \-H "Content-Type: application/json" \- -d '{"kind":"click","ref":"e7","tabId":"'$TAB'"}'+ -d '{"action":"click","ref":"e7"}'# Step 7: Wait for page loadsleep 2-# Step 8: Check result using tabId+# Step 8: Check resultecho "Login result:"-curl -s "http://localhost:9867/instances/$INST/text?tabId=$TAB" | jq '.text' | head -5+curl -s "http://localhost:9867/tabs/$TAB/text" | jq '.text' | head -5# Step 9: Cleanupcurl -s -X POST "http://localhost:9867/instances/$INST/stop"@@ -384,20 +384,20 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \sleep 2```-**Step 2: Create first tab (get tabId)**+**Step 2: Create first tab**```bashTAB1=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \- -d '{"url":"https://github.com"}' | jq -r '.tabId')+ -d '{"url":"https://github.com"}' | jq -r '.id')echo "Tab 1: $TAB1"```-**Step 3: Create second tab (get tabId)**+**Step 3: Create second tab**```bashTAB2=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \- -d '{"url":"https://stackoverflow.com"}' | jq -r '.tabId')+ -d '{"url":"https://stackoverflow.com"}' | jq -r '.id')echo "Tab 2: $TAB2"```@@ -407,26 +407,26 @@ echo "Tab 2: $TAB2"curl -s "http://localhost:9867/instances/$INST/tabs" | jq '.[] | {id, title, url}'```-**Step 5: Get snapshot from each tab (use tabIds)**+**Step 5: Get snapshot from each tab**```bash# Get content from Tab 1-curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB1" | jq '.nodes | length'+curl -s "http://localhost:9867/tabs/$TAB1/snapshot" | jq '.nodes | length'# Get content from Tab 2-curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB2" | jq '.nodes | length'+curl -s "http://localhost:9867/tabs/$TAB2/snapshot" | jq '.nodes | length'```-**Step 6: Interact with tabs (use tabIds)**+**Step 6: Interact with tabs**```bash# Click on element in Tab 1-curl -s -X POST http://localhost:9867/instances/$INST/action \+curl -s -X POST http://localhost:9867/tabs/$TAB1/action \-H "Content-Type: application/json" \- -d '{"kind":"click","ref":"e5","tabId":"'$TAB1'"}'+ -d '{"action":"click","ref":"e5"}'# Click on element in Tab 2-curl -s -X POST http://localhost:9867/instances/$INST/action \+curl -s -X POST http://localhost:9867/tabs/$TAB2/action \-H "Content-Type: application/json" \- -d '{"kind":"click","ref":"e3","tabId":"'$TAB2'"}'+ -d '{"action":"click","ref":"e3"}'# Take screenshot of Tab 1curl "http://localhost:9867/tabs/$TAB1/screenshot" -o screenshot1.png@@ -446,15 +446,15 @@ echo "Instance: $INST"# Step 2: Wait for initializationsleep 2-# Step 3: Create tabs and capture tabIds+# Step 3: Create tabsecho "Creating tabs..."TAB1=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \- -d '{"url":"https://github.com"}' | jq -r '.tabId')+ -d '{"url":"https://github.com"}' | jq -r '.id')TAB2=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \- -d '{"url":"https://stackoverflow.com"}' | jq -r '.tabId')+ -d '{"url":"https://stackoverflow.com"}' | jq -r '.id')echo "Tab 1: $TAB1"echo "Tab 2: $TAB2"@@ -463,25 +463,25 @@ echo "Tab 2: $TAB2"echo "Tabs in instance:"curl -s "http://localhost:9867/instances/$INST/tabs" | jq '.[] | {id, title, url}'-# Step 5: Get content from Tab 1 using tabId+# Step 5: Get content from Tab 1echo "Content from Tab 1:"-curl -s "http://localhost:9867/instances/$INST/text?tabId=$TAB1" | jq '.text' | head -3+curl -s "http://localhost:9867/tabs/$TAB1/text" | jq '.text' | head -3# Step 6: Get snapshots from both tabsecho "Getting snapshots..."-echo "Tab 1 nodes: $(curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB1" | jq '.nodes | length')"-echo "Tab 2 nodes: $(curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB2" | jq '.nodes | length')"+echo "Tab 1 nodes: $(curl -s "http://localhost:9867/tabs/$TAB1/snapshot" | jq '.nodes | length')"+echo "Tab 2 nodes: $(curl -s "http://localhost:9867/tabs/$TAB2/snapshot" | jq '.nodes | length')"# Step 7: Interact with elements in each tabecho "Clicking element in Tab 1..."-curl -s -X POST http://localhost:9867/instances/$INST/action \+curl -s -X POST http://localhost:9867/tabs/$TAB1/action \-H "Content-Type: application/json" \- -d '{"kind":"click","ref":"e5","tabId":"'$TAB1'"}'+ -d '{"action":"click","ref":"e5"}'echo "Clicking element in Tab 2..."-curl -s -X POST http://localhost:9867/instances/$INST/action \+curl -s -X POST http://localhost:9867/tabs/$TAB2/action \-H "Content-Type: application/json" \- -d '{"kind":"click","ref":"e3","tabId":"'$TAB2'"}'+ -d '{"action":"click","ref":"e3"}'# Step 8: Take screenshots of each tabecho "Taking screenshots..."@@ -501,7 +501,7 @@ echo "Stopped instance: $INST"### Step-by-Step-**Step 1: Create instance and navigate (capture tabId)**+**Step 1: Create instance and navigate to create tab**```bashINST=$(curl -s -X POST http://localhost:9867/instances/launch \-H "Content-Type: application/json" \@@ -509,9 +509,9 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \sleep 2-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \- -d '{"url":"https://example.com/report"}' | jq -r '.tabId')+ -d '{"url":"https://example.com/report"}' | jq -r '.id')echo "Instance: $INST, Tab: $TAB"```@@ -536,22 +536,22 @@ echo "Instance: $INST"# Step 2: Wait for initializationsleep 2-# Step 3: Navigate to report page (capture tabId)+# Step 3: Navigate to report pageecho "Navigating to report page..."-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \-H "Content-Type: application/json" \- -d '{"url":"https://example.com/report"}' | jq -r '.tabId')+ -d '{"url":"https://example.com/report"}' | jq -r '.id')echo "Tab: $TAB"-# Step 4: Generate PDF with options using tabId+# Step 4: Generate PDF with optionsecho "Generating PDF..."curl -s "http://localhost:9867/tabs/$TAB/pdf?landscape=true&displayHeaderFooter=true" \-o report.pdfecho "PDF saved: report.pdf"-# Step 5: Take screenshot for preview using tabId+# Step 5: Take screenshot for previewecho "Taking preview screenshot..."curl -s "http://localhost:9867/tabs/$TAB/screenshot" -o /tmp/report_preview.png@@ -586,7 +586,7 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \-H "Content-Type: application/json" \-d '{"mode":"headless"}' | jq -r '.id')-curl -X POST http://localhost:9867/instances/$INST/navigate \+curl -X POST http://localhost:9867/instances/$INST/tabs/open \-d '{"url":"https://example.com"}' # Likely timeout or error# CORRECT - wait for Chrome@@ -611,16 +611,18 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \```bash# WRONG - page changed, e5 no longer a button-curl "http://localhost:9867/instances/$INST/snapshot" > snapshot1.json+curl "http://localhost:9867/tabs/$TAB/snapshot" > snapshot1.json# ... do something ...-curl -X POST http://localhost:9867/instances/$INST/action \- -d '{"kind":"click","ref":"e5"}'+curl -X POST http://localhost:9867/tabs/$TAB/action \+ -H "Content-Type: application/json" \+ -d '{"action":"click","ref":"e5"}'# CORRECT - get fresh snapshot before clicking-curl "http://localhost:9867/instances/$INST/snapshot" > snapshot2.json+curl "http://localhost:9867/tabs/$TAB/snapshot" > snapshot2.json# Read refs from snapshot2.json-curl -X POST http://localhost:9867/instances/$INST/action \- -d '{"kind":"click","ref":"e7"}'+curl -X POST http://localhost:9867/tabs/$TAB/action \+ -H "Content-Type: application/json" \+ -d '{"action":"click","ref":"e7"}'```### ❌ Mistake 5: Forgetting to stop instances