@weavetab/skills 2.5.0-beta.5 → 2.5.1

package/browser/dom-strategy.md

@@ -1,119 +1,121 @@
----
-id: dom-strategy
-domain: browser
-triggers:
-  - "read page"
-  - "inspect dom"
-  - "find element"
-  - "parse webpage"
-  - "locate button"
-  - "extract text"
-tools:
-  - "browser_map"
-  - "browser_find"
-  - "browser_scrape"
-  - "browser_snapshot"
-  - "browser_eval"
-weavetab: ">=2.5.0-beta.5"
----
-
-# DOM Strategy & Token Conservation Engine
-
-When parsing modern web applications, naive DOM dumps can consume 50,000+ tokens and cause agent degradation. Weavetab provides a high-efficiency 4-tier reading architecture.
-
----
-
-## 1. The 4-Tier Reading Filter
-
-Always select the narrowest tool that satisfies your immediate objective:
-
-```
-                  ┌───────────────────────────────┐
-                  │ Do you need full structural   │
-                  │ context or just a target?     │
-                  └──────────────┬────────────────┘
-                                 │
-                 ┌───────────────┴───────────────┐
-                 ▼                               ▼
-       [Specific Target]                 [Whole Document]
-                 │                               │
-        ┌────────┴────────┐              ┌───────┴────────┐
-        ▼                 ▼              ▼                ▼
-  Target by text   Target by role   Read articles     Interactive
-   or keywords      or hierarchy     or prose data     UI layout
-        │                 │              │                │
-        ▼                 ▼              ▼                ▼
-  `browser_find`   `browser_map`   `browser_scrape`  `browser_map`
-                   (lite: true)                      (lite: true)
-                                                          │
-                                     [Sparse / Canvas / WebGL / <5 elements?]
-                                                          │
-                                                          ▼
-                                                    `browser_map`
-                                                  (visual: "auto")
-```
-
-### Tier 1: Targeted Keyword Jump (`browser_find`)
-Use `browser_find` when you already know the label, text snippet, placeholder, or aria-label of the target element.
-- **Latency**: Sub-5ms CDP search.
-- **Token Cost**: ~50–100 tokens (returns only matching candidate nodes).
-
-```json
-{
-  "query": "Sign In",
-  "matchType": "contains",
-  "visibleOnly": true
-}
-```
-
-### Tier 2: Token-Optimized DOM Walk (`browser_map` with `lite: true`)
-Use `browser_map` when you must understand the interactive structure of the page.
-- **Rule**: ALWAYS pass `"lite": true` unless you strictly need deeply nested non-interactive DOM trees.
-- **Efficiency**: Strips decorative wrappers, SVG paths, hidden containers, and scripts. Reduces payload by **85% to 95%**.
-- **Viewport Filtering**: Set `"includeOffscreen": false` to only inspect elements currently visible in the active viewport.
-
-```json
-{
-  "lite": true,
-  "includeOffscreen": false,
-  "maxDepth": 6
-}
-```
-
-### Tier 3: Markdown Prose & Data Ingestion (`browser_scrape`)
-Use `browser_scrape` when your objective is reading articles, blog posts, documentation, or legal terms rather than clicking buttons.
-- Converts HTML to clean, semantically structured Markdown.
-- Automatically handles readability filtering and removes advertising/cookie banners.
-
-### Tier 4: Set-of-Marks Visual Grounding (`browser_map` with `visual: "auto"`)
-Use when target pages are canvas-heavy, WebGL, Figma, Google Sheets, or when standard `browser_map` returns < 5 interactive elements.
-- Injects temporary numbered badges `[1]…[N]` over interactive elements & canvas regions.
-- Captures an annotated screenshot + returns a structured mark list.
-- **Zero Page Pollution**: Strips badges immediately after capture.
-- **Action**: Pass `"mark": N` to `browser_click` to click the exact element without re-scanning the DOM.
-
-```json
-{
-  "visual": "auto"
-}
-```
-
-### Tier 5: Runtime State & JavaScript Evaluation (`browser_eval`)
-When DOM nodes are occluded or you need direct access to in-memory window state (e.g. Redux store, localStorage keys, or complex canvas dimensions), use `browser_eval` as an escape hatch:
-```json
-{
-  "expression": "window.__INITIAL_STATE__ || document.title"
-}
-```
-
----
-
-## 2. Volatile Ref ID & Visual Mark Navigation
-
-Weavetab maps elements to ephemeral handles (`w:NN`) and visual marks (`[1]…[N]`):
-
-### Operational Rules:
-1. **Never Construct Speculative CSS Selectors**: If an element has ref `w:14`, pass `"ref": "w:14"` to `browser_click`, `browser_fill`, `browser_type`.
-2. **Visual Mark Targeting**: On canvas or unlabelled elements from `visual: "auto"`, pass `"mark": N` directly to `browser_click({ mark: N })`.
-3. **Lifespan of Handles**: Ref IDs and marks invalidate on page navigation (`browser_navigate`) or heavy SPA re-renders. 
-4. **Recovery on Invalidation**: If an action fails with `ELEMENT_NOT_FOUND` or `MARK_NOT_FOUND`, re-run `browser_map({ visual: "auto" })` to refresh active handles.
+---
+id: dom-strategy
+domain: browser
+triggers:
+  - "read page"
+  - "inspect dom"
+  - "find element"
+  - "parse webpage"
+  - "locate button"
+  - "extract text"
+tools:
+  - "browser_map"
+  - "browser_find"
+  - "browser_scrape"
+  - "browser_snapshot"
+  - "browser_eval"
+weavetab: ">=2.5.0"
+---
+
+# DOM Strategy & Token Conservation Engine
+
+When parsing modern web applications, naive DOM dumps can consume 50,000+ tokens and cause agent degradation. Weavetab provides a high-efficiency 4-tier reading architecture.
+
+---
+
+## 1. The 4-Tier Reading Filter
+
+Always select the narrowest tool that satisfies your immediate objective:
+
+```
+                  ┌───────────────────────────────┐
+                  │ Do you need full structural   │
+                  │ context or just a target?     │
+                  └──────────────┬────────────────┘
+                                 │
+                 ┌───────────────┴───────────────┐
+                 ▼                               ▼
+       [Specific Target]                 [Whole Document]
+                 │                               │
+        ┌────────┴────────┐              ┌───────┴────────┐
+        ▼                 ▼              ▼                ▼
+  Target by text   Target by role   Read articles     Interactive
+   or keywords      or hierarchy     or prose data     UI layout
+        │                 │              │                │
+        ▼                 ▼              ▼                ▼
+  `browser_find`   `browser_map`   `browser_scrape`  `browser_map`
+                   (lite: true)                      (lite: true)
+                                                          │
+                                     [Sparse / Canvas / WebGL / <5 elements?]
+                                                          │
+                                                          ▼
+                                                    `browser_map`
+                                                  (visual: "auto")
+```
+
+### Tier 1: Targeted Keyword Jump (`browser_find`)
+Use `browser_find` when you already know the label, text snippet, placeholder, or aria-label of the target element.
+- **Latency**: Sub-5ms CDP search.
+- **Token Cost**: ~50–100 tokens (returns only matching candidate nodes).
+
+```json
+{
+  "query": "Sign In"
+}
+```
+
+Set `"all": true` to return every match (with `"limit"` capping the count, default 10) instead of only the first.
+
+### Tier 2: Token-Optimized DOM Walk (`browser_map` with `lite: true`)
+Use `browser_map` when you must understand the interactive structure of the page.
+- **Rule**: ALWAYS pass `"lite": true` unless you strictly need deeply nested non-interactive DOM trees.
+- **Efficiency**: Strips decorative wrappers, SVG paths, hidden containers, and scripts. Reduces payload by **85% to 95%**.
+- **Scope & filter**: Narrow a dense page with `"scope": "main"` (or `navigation`, `sidebar`, `form`, `modal`, `utility`) and `"query": "<substring>"` to filter by label/role.
+- **Delta mode**: Set `"delta": true` on repeated maps to receive only what changed since the last call (up to 97% token savings).
+- **Pruning**: Set `"prune": true` to drop hidden, non-interactive subtrees and collapse SVG icons in this snapshot.
+
+```json
+{
+  "lite": true,
+  "scope": "main",
+  "delta": true
+}
+```
+
+### Tier 3: Markdown Prose & Data Ingestion (`browser_scrape`)
+Use `browser_scrape` when your objective is reading articles, blog posts, documentation, or legal terms rather than clicking buttons.
+- Converts HTML to clean, semantically structured Markdown.
+- Automatically handles readability filtering and removes advertising/cookie banners.
+
+### Tier 4: Set-of-Marks Visual Grounding (`browser_map` with `visual: "auto"`)
+Use when target pages are canvas-heavy, WebGL, Figma, Google Sheets, or when standard `browser_map` returns < 5 interactive elements.
+- Injects temporary numbered badges `[1]…[N]` over interactive elements & canvas regions.
+- Captures an annotated screenshot + returns a structured mark list.
+- **Zero Page Pollution**: Strips badges immediately after capture.
+- **Action**: Pass `"mark": N` to `browser_click` to click the exact element without re-scanning the DOM.
+
+```json
+{
+  "visual": "auto"
+}
+```
+
+### Tier 5: Runtime State & JavaScript Evaluation (`browser_eval`)
+When DOM nodes are occluded or you need direct access to in-memory window state (e.g. Redux store, localStorage keys, or complex canvas dimensions), use `browser_eval` as an escape hatch:
+```json
+{
+  "expression": "window.__INITIAL_STATE__ || document.title"
+}
+```
+
+---
+
+## 2. Volatile Ref ID & Visual Mark Navigation
+
+Weavetab maps elements to ephemeral handles (`w:NN`) and visual marks (`[1]…[N]`):
+
+### Operational Rules:
+1. **Never Construct Speculative CSS Selectors**: If an element has ref `w:14`, pass `"ref": "w:14"` to `browser_click`, `browser_fill`, `browser_type`.
+2. **Visual Mark Targeting**: On canvas or unlabelled elements from `visual: "auto"`, pass `"mark": N` directly to `browser_click({ mark: N })`.
+3. **Lifespan of Handles**: Ref IDs and marks invalidate on page navigation (`browser_navigate`) or heavy SPA re-renders. 
+4. **Recovery on Invalidation**: If an action fails with `ELEMENT_NOT_FOUND` or `MARK_NOT_FOUND`, re-run `browser_map({ visual: "auto" })` to refresh active handles.

package/browser/form-automation.md

@@ -1,87 +1,84 @@
----
-id: form-automation
-domain: browser
-triggers:
-  - "fill form"
-  - "submit form"
-  - "select dropdown"
-  - "multi field input"
-  - "radio button"
-  - "checkbox"
-tools:
-  - "browser_fill"
-  - "browser_select"
-weavetab: ">=2.5.0-beta.5"
----
-
-# Form Automation: Atomic Multi-Field Execution
-
-Submitting complex web forms one field at a time wastes agent turns and increases the probability of layout shifts. Weavetab provides atomic multi-field batching and native dropdown selectors.
-
----
-
-## 1. Atomic Multi-Field Filling (`browser_fill`)
-
-`browser_fill` populates multiple inputs, textareas, checkboxes, and radio buttons in a single CDP roundtrip.
-
-```json
-{
-  "fields": [
-    {
-      "ref": "w:12",
-      "value": "Anas"
-    },
-    {
-      "ref": "w:14",
-      "value": "Khezaz"
-    },
-    {
-      "ref": "w:16",
-      "value": "contact@weavetab.com"
-    },
-    {
-      "ref": "w:19",
-      "value": true
-    }
-  ]
-}
-```
-
-### Supported Field Value Types:
-- **Text / Search / Email / Tel**: Provide a `string`.
-- **Checkbox**: Provide a `boolean` (`true` to check, `false` to uncheck).
-- **Radio Buttons**: Provide `true` on the matching option ref.
-- **ContentEditable**: Provide a `string` (automatically handles inner text formatting).
-
----
-
-## 2. Dropdown & Select Automation (`browser_select`)
-
-Standard `<select>` elements and custom dropdowns often fail under simple click-and-type automation. `browser_select` dispatches native CDP change events.
-
-```json
-{
-  "ref": "w:31",
-  "values": ["enterprise_tier"]
-}
-```
-
-### Multi-Select Support:
-For `<select multiple>` elements, pass an array of option values:
-
-```json
-{
-  "ref": "w:35",
-  "values": ["us-east-1", "eu-central-1"]
-}
-```
-
----
-
-## 3. Form Submission Best Practices
-
-1. **Pre-Validate State**: Before clicking Submit, confirm that required fields have passed HTML5/client-side validation (no active red borders or validation popups).
-2. **Submit via Enter Key vs Click**:
-   - If the submit button has a dynamic ref or changes during typing, send `"key": "Enter"` via `browser_key` inside the last filled text field.
-   - Otherwise, locate the submit button via `browser_find` and click via `browser_click`.
-3. **Wait for Post-Submission Route**: Always follow form submission with `browser_wait` for URL changes or target DOM confirmation rather than immediately firing subsequent actions.
+---
+id: form-automation
+domain: browser
+triggers:
+  - "fill form"
+  - "submit form"
+  - "select dropdown"
+  - "multi field input"
+  - "radio button"
+  - "checkbox"
+tools:
+  - "browser_fill"
+  - "browser_select"
+weavetab: ">=2.5.0"
+---
+
+# Form Automation: Atomic Multi-Field Execution
+
+Submitting complex web forms one field at a time wastes agent turns and increases the probability of layout shifts. Weavetab provides atomic multi-field batching and native dropdown selectors.
+
+---
+
+## 1. Atomic Multi-Field Filling (`browser_fill`)
+
+`browser_fill` populates multiple inputs, textareas, checkboxes, and radio buttons in a single CDP roundtrip.
+
+```json
+{
+  "fields": [
+    {
+      "ref": "w:12",
+      "value": "Anas"
+    },
+    {
+      "ref": "w:14",
+      "value": "Khezaz"
+    },
+    {
+      "ref": "w:16",
+      "value": "contact@weavetab.com"
+    },
+    {
+      "ref": "w:19",
+      "value": "true"
+    }
+  ]
+}
+```
+
+### Supported Field Value Types:
+Every `value` is a **string**.
+- **Text / Search / Email / Tel**: The literal text to type.
+- **Checkbox / ARIA switch**: A truthy string (`"true"`, `"yes"`, `"checked"`, `"1"`, or `"on"`) checks it; anything else unchecks it.
+- **Radio Buttons**: Set the matching option's ref to a truthy string to select it.
+- **Select**: The option `value` or visible text to choose.
+- **ContentEditable**: The text content to set (inner text formatting handled automatically).
+
+---
+
+## 2. Dropdown & Select Automation (`browser_select`)
+
+Standard `<select>` elements and custom dropdowns often fail under simple click-and-type automation. `browser_select` dispatches native CDP change events.
+
+```json
+{
+  "ref": "w:31",
+  "value": "enterprise_tier"
+}
+```
+
+`value` is a **single string** (required) and matches either the option's `value` or its visible text, trimmed. For a custom ARIA/React dropdown it opens the popover, scans `[role="option"]`/`[role="menuitem"]` candidates, and clicks the best match.
+
+### Multi-Select Support:
+`browser_select` selects one option per call. For a `<select multiple>` element, call it once per option you want selected.
+
+---
+
+## 3. Form Submission Best Practices
+
+1. **Pre-Validate State**: Before clicking Submit, confirm that required fields have passed HTML5/client-side validation (no active red borders or validation popups).
+2. **Submit via Enter Key vs Click**:
+   - If the submit button has a dynamic ref or changes during typing, send `"key": "Enter"` via `browser_key` inside the last filled text field.
+   - Otherwise, locate the submit button via `browser_find` and click via `browser_click`.
+3. **Wait for Post-Submission Route**: Always follow form submission with `browser_wait` for URL changes or target DOM confirmation rather than immediately firing subsequent actions.