@weavetab/skills 1.0.1 → 2.5.0-beta.4

package/dist/bundled/weavetab-browser.md

@@ -0,0 +1,501 @@
+# Weavetab Domain Profile: BROWSER
+
+Generated for @weavetab/skills v2.5.0-beta.4
+
+
+## dom-strategy
+
+# 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.
+
+
+## form-automation
+
+# 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.
+
+
+## interaction-pipeline
+
+# Interaction Pipeline: Physical & Synthetic Input Engine
+
+Weavetab executes browser interactions via direct Chrome DevTools Protocol (CDP) dispatch, bypassing synthetic JavaScript event limitations and anti-automation tripwires.
+
+---
+
+## 1. Clicking Elements (`browser_click`)
+
+Execute deterministic clicks on DOM elements using volatile handles (`ref`), CSS selectors, or exact coordinates.
+
+```json
+{
+  "ref": "w:23",
+  "clickCount": 1,
+  "button": "left"
+}
+```
+
+### Advanced Modifiers:
+- **Double Click**: Set `"clickCount": 2` for inline editing or selecting text blocks.
+- **Context Menu**: Set `"button": "right"` to trigger native context menus.
+- **Modifier Keys**: Pass `"modifiers": ["Control"]` or `["Meta"]` for multi-selection or opening links in background tabs.
+
+---
+
+## 2. Text Input (`browser_type`)
+
+Simulate natural keystrokes into input fields, textareas, and `contenteditable` elements.
+
+```json
+{
+  "ref": "w:18",
+  "text": "Enterprise Search Query",
+  "clear": true,
+  "delay": 20
+}
+```
+
+> [!CAUTION]
+> **Secret Boundary Enforcement**:
+> NEVER use `browser_type` for passwords, API tokens, or payment card data. Always route sensitive credentials through [`security/secret-containment-protocol.md`](file:///c:/Users/fy2ne/Music/Weavetab/skills/security/secret-containment-protocol.md) via `browser_type_secret`.
+
+---
+
+## 3. Physical Pointer Trajectories (`browser_pointer`)
+
+Handle complex drag-and-drop interactions, canvas sketching, hover-activated navigation flyouts, and custom sliders.
+
+### Hover / Mouse Move:
+```json
+{
+  "action": "move",
+  "x": 450,
+  "y": 180
+}
+```
+
+### Drag & Drop Pipeline:
+```json
+// Step 1: Move to origin & press mouse
+{ "action": "move", "x": 200, "y": 300 }
+{ "action": "down", "button": "left" }
+
+// Step 2: Smooth trajectory to destination
+{ "action": "move", "x": 600, "y": 300 }
+
+// Step 3: Release
+{ "action": "up", "button": "left" }
+```
+
+---
+
+## 4. Keystrokes & Shortcuts (`browser_key`)
+
+Trigger keyboard shortcuts, navigation keys, and dialog dismissals.
+
+```json
+{
+  "key": "Enter"
+}
+```
+
+### High-Frequency Key Combos:
+- **Select All & Delete**: Send `"key": "a"`, `"modifiers": ["Control"]` (or `["Meta"]` on macOS), followed by `"key": "Backspace"`.
+- **Dismiss Overlays**: Send `"key": "Escape"`.
+- **Form Tab Navigation**: Send `"key": "Tab"`.
+
+---
+
+## 5. OS File Upload Bypass (`browser_upload`)
+
+Native operating system file picker dialogs block autonomous agent execution because they operate outside the browser DOM. Weavetab bypasses this entirely using CDP's `DOM.setFileInputFiles`.
+
+```json
+{
+  "ref": "w:41",
+  "files": [
+    "C:/Users/fy2ne/Documents/contract.pdf",
+    "C:/Users/fy2ne/Documents/financial_report.xlsx"
+  ]
+}
+```
+
+- **Targeting**: Supply the volatile handle `ref` or CSS selector for the `<input type="file">`.
+- **Hidden Inputs**: `browser_upload` automatically handles `display: none` file inputs commonly used in custom drag-and-drop upload widgets.
+
+---
+
+## 6. Viewport & Element Scrolling (`browser_scroll`)
+
+Scroll the entire page viewport or scroll specific scrollable containers:
+
+```json
+{
+  "direction": "down",
+  "amount": 500
+}
+```
+
+Or scroll a specific element container:
+```json
+{
+  "ref": "w:12",
+  "direction": "down",
+  "amount": 300
+}
+```
+
+---
+
+## 7. Native Dialog Handling (`browser_dialog`)
+
+Handle native JavaScript `alert`, `confirm`, `prompt`, or `beforeunload` dialogs that block page execution:
+
+```json
+{
+  "action": "accept",
+  "promptText": "Confirmed"
+}
+```
+
+---
+
+## 8. High-Speed Action Batches (`browser_burst`)
+
+Execute multiple sequential micro-actions in a single CDP roundtrip without waiting for intermediate LLM turns:
+
+```json
+{
+  "steps": [
+    { "tool": "browser_fill", "ref": "w:10", "value": "search query" },
+    { "tool": "click_and_wait", "ref": "w:15" }
+  ]
+}
+```
+*(Accepts both `steps` and `actions`, with arguments either nested under `args` or specified flat on the step object).*
+
+---
+
+## 9. Visual Element Highlighting & Consideration (`browser_highlight`)
+
+Draw visual consideration, target lock, danger/success, or shimmer overlays without mutating the DOM. Supports multi-element candidate evaluation:
+
+```json
+{
+  "refs": ["w:12", "w:15", "w:23"],
+  "style": "consideration",
+  "label": "Evaluating form options",
+  "duration": 2000
+}
+```
+
+### Presentation Styles:
+- `"consideration"`: Soft pulsing cyan/blue outline (`#38bdf8`) with ambient glow — ideal when weighing multiple interactive candidates.
+- `"target"`: High-contrast amber lock-on ring (`#f59e0b`) before executing high-impact clicks.
+- `"danger"`: Red warning border (`#ef4444`) for destructive buttons (Delete, Reset, Purge).
+- `"success"`: Emerald glow (`#10b981`) confirming completed actions.
+- `"shimmer"`: Rapid purple accent wave (default for quick inspection).
+
+---
+
+## 10. System Clipboard Bridging (`browser_clipboard`)
+
+Read or write system clipboard text during automation:
+
+```json
+{
+  "action": "write",
+  "text": "AuthToken_xyz987"
+}
+```
+
+
+## tab-and-window
+
+# Tab & Window Lifecycle Management
+
+Multi-tab workflows (OAuth popups, payment gateways, documentation references, desktop application windows) require deterministic tab switching, window focusing, and failure recovery. `browser_tabs` controls all CDP page and window targets.
+
+---
+
+## 1. Tab Discovery & Target Enumeration
+
+Inspect all active targets, open URLs, and page titles:
+
+```json
+{
+  "action": "list"
+}
+```
+
+To list targets inside a specific desktop app (e.g. Discord, Slack):
+```json
+{
+  "action": "list",
+  "app": "discord"
+}
+```
+
+> [!TIP]
+> Always pass `"app": "<name>"` when inspecting desktop applications. This guarantees that Weavetab does not launch or query the web browser.
+
+---
+
+## 2. Opening Tabs & Smart Reuse
+
+Open a target URL. By default, `reuse: true` will focus an existing tab if the URL is already loaded:
+
+```json
+{
+  "action": "open",
+  "url": "https://github.com"
+}
+```
+
+To force opening a brand-new duplicate tab instead of reusing:
+```json
+{
+  "action": "open",
+  "url": "https://github.com",
+  "reuse": false
+}
+```
+
+---
+
+## 3. Context Switching
+
+Switch active agent focus between open tabs:
+
+```json
+{
+  "action": "switch",
+  "tabId": "TARGET_PAGE_ID"
+}
+```
+
+---
+
+## 4. Closing Tabs & Batch Cleanup
+
+Close a single tab:
+```json
+{
+  "action": "close",
+  "tabId": "TARGET_PAGE_ID"
+}
+```
+
+Close multiple tabs simultaneously in a single round-trip:
+```json
+{
+  "action": "close",
+  "tabIds": ["TARGET_1", "TARGET_2", "TARGET_3"]
+}
+```
+
+---
+
+## 5. Native Window Management
+
+List native OS windows:
+```json
+{
+  "action": "list_windows"
+}
+```
+
+Bring a specific native window to the foreground:
+```json
+{
+  "action": "focus_window",
+  "windowId": 1
+}
+```
+
+---
+
+## 6. Duplicate Consolidation & Auto-Heal
+
+Deduplicate redundant tabs across the session:
+```json
+{
+  "action": "consolidate"
+}
+```
+
+If a target page crashes or detaches due to memory limits:
+```json
+{
+  "action": "heal"
+}
+```
+
+The auto-heal routine re-establishes CDP protocol sessions, reconnects event listeners, and synchronizes the active page target.

package/dist/bundled/weavetab-desktop.md

@@ -0,0 +1,176 @@
+# Weavetab Domain Profile: DESKTOP
+
+Generated for @weavetab/skills v2.5.0-beta.4
+
+
+## desktop-targeting
+
+# Desktop App Targeting & Multi-Window Routing
+
+Once a desktop application is detected via `browser_detect`, every standard Weavetab tool can be scoped directly to that desktop application without opening or disturbing the user's web browser.
+
+---
+
+## 1. Direct App Parameter Routing
+
+Pass `"app": "<application_name>"` to target the Electron application.
+
+### Example: Reading Discord Channels
+```json
+// Tool: browser_map
+{
+  "app": "discord",
+  "scope": "main_content"
+}
+```
+
+### Example: Sending a Message in Discord
+```json
+// Tool: browser_type
+{
+  "app": "discord",
+  "ref": "w:88",
+  "text": "Deployment v2.5.0-beta.3 completed successfully."
+}
+```
+
+### Example: Listing Discord Tabs/Windows
+```json
+// Tool: browser_tabs
+{
+  "action": "list",
+  "app": "discord"
+}
+```
+
+> [!IMPORTANT]
+> Always pass `"app": "discord"` (or the target app name) to `browser_tabs` when working with desktop apps. This prevents Weavetab from accidentally launching or switching to the web browser.
+
+---
+
+## 2. Smart Domain Auto-Routing & Sticky Context
+
+Weavetab features automatic target resolution to eliminate accidental browser popups:
+
+### A. Automatic Domain Matching
+If you call `browser_navigate` or `browser_tabs(action: "open")` with a known domain (e.g. `discord.com`, `slack.com`, `linear.app`, `notion.so`), Weavetab automatically routes the command to the configured Electron desktop application.
+
+### B. Sticky App Sessions
+When you interact with an Electron application (e.g., clicking or typing in Discord), Weavetab remembers the active application context. If a subsequent tool call omits `app` and no web browser instance is active, Weavetab stays attached to the active desktop app rather than spawning an unwanted Chrome window.
+
+### C. Explicit Browser Override
+If you specifically want to open a URL in the web browser instead of a desktop application, pass `"app": "browser"`.
+
+---
+
+## 3. Multi-Window Focus Management
+
+Some Electron apps open secondary windows (e.g. popout editors, settings panels, or call windows).
+
+1. Use `browser_tabs(action: "list", app: "discord")` to view all open windows and page targets for that specific app.
+2. Switch focus between windows using `browser_tabs(action: "switch", tabId: "<id>", app: "discord")`.
+3. To bring a specific native window to the foreground, use `browser_tabs(action: "focus_window", windowId: <id>, app: "discord")`.
+
+
+## electron-discovery
+
+# Electron Discovery & Environment Handshake
+
+Modern desktop applications (Discord, Slack, VS Code, Notion, Obsidian, Figma) are built on Chromium and Electron. Weavetab can inspect and drive these native applications through standard CDP interfaces without third-party drivers or OS-level accessibility hacks.
+
+`browser_detect` is the **critical initialization handshake** tool. Every agent should call `browser_detect` before interacting with the user's desktop environment to gain immediate situational awareness.
+
+---
+
+## 1. Running Discovery via `browser_detect`
+
+Call `browser_detect` with empty parameters `{}`:
+
+```json
+{}
+```
+
+### Response Schema:
+```json
+{
+  "available": [
+    {
+      "engine": "chromium",
+      "name": "Google Chrome",
+      "path": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
+    }
+  ],
+  "current": "chromium",
+  "configuredApps": [
+    {
+      "name": "discord",
+      "status": "running_no_debug",
+      "configuredPath": "C:\\Users\\username\\AppData\\Local\\Discord\\app-1.0.9256\\Discord.exe"
+    },
+    {
+      "name": "slack",
+      "status": "connected",
+      "port": 9222,
+      "configuredPath": "C:\\Users\\username\\AppData\\Local\\slack\\app-4.38.125\\slack.exe",
+      "activeTabs": [
+        {
+          "id": "PAGE_1",
+          "title": "general - Weavetab Slack",
+          "url": "https://app.slack.com/client/..."
+        }
+      ]
+    },
+    {
+      "name": "vscode",
+      "status": "offline",
+      "configuredPath": "C:\\Users\\username\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe"
+    }
+  ],
+  "toolCoverage": {
+    "chromium": 100,
+    "firefox": 78,
+    "webkit": 55
+  }
+}
+```
+
+---
+
+## 2. Understanding Application Status
+
+Each configured desktop app reports one of three distinct lifecycle statuses:
+
+| Status | Meaning | Agent Action |
+| :--- | :--- | :--- |
+| **`connected`** | App is running with CDP remote debugging active. Weavetab has an active session. | Immediately interact using any tool with `"app": "<name>"`. Tabs and port are available. |
+| **`running_no_debug`** | The app process is currently open on the user's OS, but was launched normally by the user without `--remote-debugging-port`. | Do NOT send click/type commands. To attach, inform the user or close and launch via `browser_navigate(app: "<name>")` so Weavetab supplies the debugging port. |
+| **`offline`** | The application is not currently running on the OS. | Launch and attach in one step by calling `browser_navigate(app: "<name>")`. |
+
+---
+
+## 3. Dynamic Squirrel Updates on Windows
+
+On Windows, Squirrel-managed applications (Discord, Slack, Teams) update dynamically into versioned sibling directories (e.g. `Discord\app-1.0.9256\Discord.exe`). 
+
+Weavetab automatically handles this:
+- If a configured path points to an outdated version or the parent folder, Weavetab scans the directory, resolves the highest semantic version folder (`app-1.0.xxxx`), and launches the valid executable.
+- The dynamically resolved path is reported in `browser_detect` under `configuredPath`.
+
+---
+
+## 4. Launching Desktop Apps Manually with Debugging
+
+If the user prefers to launch apps manually from a terminal or shortcut with remote debugging enabled:
+
+```bash
+# Discord
+Discord.exe --remote-debugging-port=9222
+
+# Slack
+slack.exe --remote-debugging-port=9223
+
+# VS Code
+code.exe --remote-debugging-port=9225
+```
+
+Once launched with `--remote-debugging-port`, `browser_detect` immediately reflects the application as connectable.