fastbrowser_cli 1.0.33 → 1.0.37

package/examples/whatsapp/whatsapp.sh

@@ -0,0 +1,10 @@
+#!/bin/env bash
+
+# restart the server
+NODE_OPTIONS='' NPM_CONFIG_LOGLEVEL=silent npm run dev:cli -- server restart
+
+# navigate to whatsapp web
+NODE_OPTIONS='' NPM_CONFIG_LOGLEVEL=silent npm run dev:cli -- navigate_page --url https://web.whatsapp.com/
+
+# List all conversations in the chat list
+NODE_OPTIONS='' NPM_CONFIG_LOGLEVEL=silent npm run dev:cli -- query_selectors -s 'grid[name="Chat list"] > row' -a

package/listitem

@@ -0,0 +1,3 @@
+Expected ] at column 22:
+  list[name=Conversation List]
+                        ^

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastbrowser_cli",
-  "version": "1.0.33",
+  "version": "1.0.37",
   "description": "A CLI tool for FastBrowser, providing commands to interact with the FastBrowser MCP (Model Context Protocol) server and perform various browser automation tasks.",
   "main": "dist/fastbrowser_cli/fastbrowser_cli.js",
   "bin": {
@@ -30,7 +30,7 @@
     "typescript": "^6.0.3",
     "zod": "^4.3.6",
     "zod-from-json-schema": "^0.5.2",
-    "a11y_parse": "^1.0.5"
+    "a11y_parse": "^1.0.7"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
@@ -51,6 +51,7 @@
     "prepublish:check": "test -z \"$(git status --porcelain)\" || (echo 'Working tree dirty — commit or stash first' && exit 1)",
     "version:bump": "npm version patch --no-git-tag-version && git add package.json && git commit -m \"feat: bump version in fastbrowser_cli package.json\"",
     "publish:all": "pnpm run prepublish:check && pnpm run build && pnpm run version:bump && pnpm publish --access public",
+    "clean:output:log": "rm -f outputs/*.log",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npx tsx --test 'tests/**/*.test.ts'"
   }

package/skills/fastbrowser/SKILL.md

@@ -45,6 +45,31 @@ npx fastbrowser_cli close_page --page-id 1
 
 # Navigate the current page to a URL
 npx fastbrowser_cli navigate_page --url https://example.com
+
+# Restart the daemon - run this if pages opened by the bridge were closed manually
+# and the MCP connection has broken
+npx fastbrowser_cli server restart
+```
+
+
+## Configuration
+
+Global flags accepted by every command:
+
+| Flag / env | Purpose | Default |
+|---|---|---|
+| `--server <url>` / `FASTBROWSER_SERVER` | URL of the `fastbrowser_httpd` daemon | `http://localhost:8787` |
+| `--autostart` / `--no-autostart` | Auto-start the daemon if it is not already running | `--autostart` |
+| `--mcp-target <target>` / `FASTBROWSER_MCP_TARGET` | Browser backend: `playwright` or `chrome_devtools` | `playwright` |
+
+The daemon binds to one backend at startup. If it is already running with a different backend, the CLI refuses the request and prints the exact restart command to switch.
+
+```bash
+# Use chrome-devtools-mcp for one command
+npx fastbrowser_cli --mcp-target chrome_devtools list_pages
+
+# Switch the running daemon to a different backend
+npx fastbrowser_cli --mcp-target chrome_devtools server restart
 ```
 
 
@@ -59,7 +84,7 @@ Matches nodes by their accessibility role.
 ```
 button
 link
-comboxbox
+combobox
 searchbox
 heading
 WebArea
@@ -93,6 +118,7 @@ Attribute selectors match values inside `node.attributes`. The special virtual a
 | `[attr^="prefix"]` | starts with |
 | `[attr$="suffix"]` | ends with |
 | `[attr*="sub"]` | contains substring |
+| `[attr~="word"]` | contains `word` as a whole space-separated word |
 
 ```
 link[href]
@@ -100,6 +126,7 @@ button[disabled="true"]
 link[href^="https"]
 link[href$=".com"]
 link[href*="example"]
+button[name~="Submit"]
 heading[name="Welcome"]
 link[name="Click \"here\""]
 ```
@@ -110,15 +137,56 @@ link[name="Click \"here\""]
 |--------|-----------|
 | `A B` | B is a descendant of A (any depth) |
 | `A > B` | B is a direct child of A |
+| `A + B` | B is the immediately following sibling of A |
+| `A ~ B` | B is any following sibling of A |
 | `A, B` | union — matches A or B |
 
 ```
 WebArea link
 main > button
+label + textbox
+link ~ link
 heading, button
 RootWebArea > link[href^="https"]
 ```
 
+### Positional pseudo-classes
+
+Narrow a match by position within the parent's children array. Indexing is 1-based; the root node never matches a positional pseudo-class.
+
+| Syntax | Semantics |
+|--------|-----------|
+| `:first-child` | node is the first child of its parent |
+| `:last-child` | node is the last child of its parent |
+| `:nth-child(n)` | node is the nth child (1-based) |
+
+```
+link:first-child
+button:last-child
+menuitem:nth-child(2)
+```
+
+### Functional pseudo-classes
+
+Take a comma-separated selector list inside parentheses. The argument list itself supports the full selector language and may be nested.
+
+| Syntax | Semantics |
+|--------|-----------|
+| `:is(s1, s2, …)` | node matches any selector in the list |
+| `:where(s1, s2, …)` | alias of `:is()` (no specificity in this engine) |
+| `:not(s1, s2, …)` | node matches none of the selectors |
+| `:has(s1, s2, …)` | node has a descendant matching any selector |
+
+`:has()` walks descendants of the candidate node (excluding the node itself). Relative leading combinators (e.g. `:has(> link)`) are not supported.
+
+```
+:is(heading, button)
+link:not(:first-child)
+*:has(button)
+*:not(:has(link))
+main > *:not(button)
+```
+
 ### Examples
 
 Sample accessibility tree:
@@ -136,38 +204,47 @@ uid=1 WebArea "Main Page"
 
 Example queries on it:
 - `link` matches all the links (uid=4, uid=7, uid=8)
-- 'navigation > link' matches only the links that are direct children of navigation (uid=7, uid=8)
+- `navigation > link` matches only the links that are direct children of navigation (uid=7, uid=8)
 - `link[href^="https"]` matches links with an external href (uid=4)
 - `button[name="Submit"]` matches the submit button by name (uid=5)
 - `*[disabled="true"]` matches any disabled element (uid=5)
 - `heading, button` matches both headings and buttons in one query (uid=3, uid=5)
 - `#7` matches a node by its UID (uid=7)
+- `link:first-child` matches uid=4 and uid=7 (first child of `main` and `navigation`)
+- `link + button` matches uid=5 (button immediately after a link)
+- `:is(heading, button)` is equivalent to `heading, button` (uid=3, uid=5)
+- `link:not([href^="https"])` matches the relative-href links (uid=7, uid=8)
+- `*:has(button)` matches ancestors of a button (uid=1, uid=2)
 
 ## Inspection
 
 - `query_selectors` is the most efficient way to get specific elements or data from the page. Use it instead of `take_snapshot` whenever possible.
 - By default, `query_selectors` returns the first match per selector (cheaper, less output). Pass `-a, --all` when you need every match — pair it with `--limit` to cap results per selector.
+- Use `--wa, --with-ancestors` to include each match's ancestor chain in the result, and `--wc, --with-children` to include the descendant subtree of each match.
 
 ```bash
 # Query the accessibility tree returning the FIRST match per selector (--selector is repeatable)
 npx fastbrowser_cli query_selectors --selector "button" --selector "link"
 
-# Exclude ancestor nodes from the result
-npx fastbrowser_cli query_selectors --selector 'heading[level="1"]' --no-with-ancestors
+# Include ancestor nodes in the result
+npx fastbrowser_cli query_selectors --selector 'heading[level="1"]' --with-ancestors
+
+# Include the descendant subtree of each match
+npx fastbrowser_cli query_selectors --selector 'main' --with-children
 
-# Per-selector control over withAncestors via JSON
+# Per-selector control over withAncestors / withChildren via JSON
 npx fastbrowser_cli query_selectors \
-  --selectors-json '[{"selector":"button","withAncestors":true},{"selector":"link","withAncestors":false}]'
+  --selectors-json '[{"selector":"button","withAncestors":true},{"selector":"link","withChildren":true}]'
 
 # Pass --all to return every match per selector; --limit caps results per selector (0 = unlimited)
 npx fastbrowser_cli query_selectors --all --selector "button" --selector "link" --limit 5
 
-# Exclude ancestor nodes from the result
-npx fastbrowser_cli query_selectors --all --selector 'heading[level="1"]' --no-with-ancestors
+# Include ancestor nodes in the result
+npx fastbrowser_cli query_selectors --all --selector 'heading[level="1"]' --with-ancestors
 
-# Per-selector control over limit / withAncestors via JSON (with --all)
+# Per-selector control over limit / withAncestors / withChildren via JSON (with --all)
 npx fastbrowser_cli query_selectors --all \
-  --selectors-json '[{"selector":"button","limit":3,"withAncestors":true},{"selector":"link","limit":0,"withAncestors":false}]'
+  --selectors-json '[{"selector":"button","limit":3,"withAncestors":true},{"selector":"link","limit":0,"withChildren":true}]'
 
 # Take an accessibility-tree full page snapshot of the current page - very expensive, prefer targeted queries when possible
 npx fastbrowser_cli take_snapshot
@@ -239,9 +316,11 @@ press_keys --keys "Tab, Enter"
 | `fill_form` | Fill a form field by accessibility selector | `--selector` / `-s`, `--value` |
 | `press_keys` | Press a comma-separated key sequence | `--keys` |
 | `batch` | Run multiple commands from a file, piped stdin, or `--script` inline | one of: `<file>`, `--script`, or piped stdin |
+| `install [skill-folder]` | Install bundled skills into `<skill-folder>/skills/` (default: `.`) | — |
 | `server start` | Start the HTTP server daemon | — |
 | `server status` | Report server running/stopped | — |
 | `server stop` | Stop the HTTP server | — |
+| `server restart` | Restart the HTTP server (re-establishes the MCP connection) | — |
 
 ## Output & Errors
 

package/src/fastbrowser_mcp/fastbrowser_mcp.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 // node imports
-import * as Assert from 'node:assert/strict';
 import Fs from 'node:fs';
 import Path from 'node:path';
 
@@ -52,21 +51,62 @@ const logger = Logger.fromMetaUrl(import.meta.url, {
 ///////////////////////////////////////////////////////////////////////////////
 
 class MainHelper {
+	/**
+	 * Multiple retry... not sure it is actually useful - https://github.com/jeromeetienne/skillmd_collection/issues/47
+	 * 
+	 * @param mcpClient 
+	 * @returns 
+	 */
 	private static async _getA11yText(mcpClient: McpMyClient): Promise<string> {
 		const mcpTarget = await mcpClient.getMcpTarget();
 		const toolConfig = await McpTargetHelper.targetToolTakeSnapshot(mcpTarget);
 
-		// FIXME: the first take_snapshot call after connecting to the MCP target often returns an empty snapshot for unknown reasons 
-		// — working around this by calling it once and discarding the result before calling it again to get the actual snapshot text
-		await mcpClient.callTool(toolConfig.toolName, toolConfig.toolArgs);
+		// `take_snapshot` is racy — for reasons we haven't traced (could be playwright's a11y serializer, the
+		// `@playwright/mcp` extension transport, or the chrome extension itself), back-to-back calls on an unchanged
+		// page sometimes return incomplete or empty trees. Stabilize by taking snapshots in pairs and only returning
+		// once two consecutive ones agree on node count within STABLE_TOLERANCE. On exhaustion, return best-effort
+		// rather than throw, so legitimately tiny pages don't break workflows.
+		const MAX_ATTEMPTS = 6;
+		const RETRY_DELAY_MS = 250;
+		const STABLE_TOLERANCE = 2;
+
+		let prev: { text: string; nodeCount: number } | undefined = undefined;
+		let last: { text: string; nodeCount: number } = { text: '', nodeCount: 0 };
+
+		for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+			const callToolResult = await mcpClient.callTool(toolConfig.toolName, toolConfig.toolArgs);
+			const text = await ResponseFormatter.formatTakeSnapshot(mcpTarget, callToolResult);
+			const nodeCount = MainHelper._countSnapshotNodes(text);
+			last = { text, nodeCount };
+
+			if (prev !== undefined && Math.abs(nodeCount - prev.nodeCount) <= STABLE_TOLERANCE) {
+				if (nodeCount === 0) {
+					logger.warn(`${mcpTarget}:take_snapshot: settled at empty after ${attempt} attempt(s) — returning empty snapshot`);
+				}
+				return text;
+			}
 
-		const callToolResult = await mcpClient.callTool(toolConfig.toolName, toolConfig.toolArgs);
-		const snapshotText = await ResponseFormatter.formatTakeSnapshot(mcpTarget, callToolResult);
-		// sanity check
-		Assert.ok(snapshotText !== undefined, "Snapshot text is empty");
+			logger.warn(`${mcpTarget}:take_snapshot: attempt ${attempt}/${MAX_ATTEMPTS}: nodeCount=${nodeCount}, prev=${prev === undefined ? 'n/a' : prev.nodeCount} — not stable, retrying`);
 
-		// return the snapshot text
-		return snapshotText;
+			prev = last;
+			if (attempt < MAX_ATTEMPTS) {
+				await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+			}
+		}
+
+		logger.warn(`${mcpTarget}:take_snapshot: exhausted ${MAX_ATTEMPTS} attempts without stabilizing — returning best-effort (nodeCount=${last.nodeCount})`);
+		return last.text;
+	}
+
+	private static _countSnapshotNodes(snapshotText: string): number {
+		if (snapshotText.trim().length === 0) return 0;
+		let count = 0;
+		for (const line of snapshotText.split('\n')) {
+			if (line.trim().startsWith('uid=')) {
+				count += 1;
+			}
+		}
+		return count;
 	}
 
 	/**

package/src/fastbrowser_mcp/libs/playwright_a11y_helper.ts

@@ -115,7 +115,39 @@ export class PlaywrightA11yConverter {
 			stack.push(node);
 		}
 
-		return allNodes.map((node) => PlaywrightA11yConverter._stringifyNode(node)).join('\n');
+		// Playwright's `browser_snapshot` response often interleaves the a11y tree with preamble lines like
+		// `- Page URL: ...`, `- Page Title: ...`, `- Console: 193 errors, 0 warnings`, plus trailing entries
+		// like `- New`. Each of those parses as a spurious top-level (indent=0) node. Downstream,
+		// `A11yParse.A11yTree.parse` silently overwrites `root` for every indent-0 line and returns only the
+		// LAST top-level subtree — so the real a11y page tree (usually a large `generic [active]` subtree
+		// in the middle) gets discarded and queries return zero hits even though the data is in the text.
+		// Pick the largest top-level subtree, which is reliably the actual page tree since the metadata
+		// subtrees are tiny (0–1 nodes).
+		const primary = PlaywrightA11yConverter._pickPrimarySubtree(allNodes);
+		return primary.map((node) => PlaywrightA11yConverter._stringifyNode(node)).join('\n');
+	}
+
+	private static _pickPrimarySubtree(allNodes: EmittedNode[]): EmittedNode[] {
+		if (allNodes.length === 0) return allNodes;
+
+		const topLevelIndices: number[] = [];
+		for (let i = 0; i < allNodes.length; i++) {
+			if (allNodes[i].indent === 0) topLevelIndices.push(i);
+		}
+		if (topLevelIndices.length <= 1) return allNodes;
+
+		let bestStart = topLevelIndices[0];
+		let bestSize = 0;
+		for (let k = 0; k < topLevelIndices.length; k++) {
+			const start = topLevelIndices[k];
+			const end = k + 1 < topLevelIndices.length ? topLevelIndices[k + 1] : allNodes.length;
+			const size = end - start;
+			if (size > bestSize) {
+				bestSize = size;
+				bestStart = start;
+			}
+		}
+		return allNodes.slice(bestStart, bestStart + bestSize);
 	}
 
 	///////////////////////////////////////////////////////////////////////////////

package/examples/linkedin_cli/linked_dm.sh

@@ -1,16 +0,0 @@
-#!/bin/bash
-
-# Goto linkedin messaging page using the CLI commands below:
-npx fastbrowser_cli navigate_page --url https://www.linkedin.com/messaging/
-
-# list[name="Conversation list"] > listitem > heading
-npx fastbrowser_cli query_selectors -s 'list[name="Conversation List"] > listitem heading' -a
-
-# Select the conversation with Eric Defiez
-npx fastbrowser_cli click -s 'list[name="Conversation List"] > listitem heading[name^="Eric Defiez"]' 
-
-# Fill the message content
-npx fastbrowser_cli fill_form -s 'textbox[name^="Write"]' -v "Hello"
-
-# Click the "Send" button to send the message
-npx fastbrowser_cli click -s 'button[name^="Send"]'