---
name: runmacro-workflow
summary: Generate 100% valid RunMacro browser automation workflow JSON (schema runmacro.workflow_import.v1) for direct import into the RunMacro "Import Workflow JSON" dialog.
---

# RunMacro Workflow Import Specification for AI Agents

This document teaches AI agents (ChatGPT, Custom GPTs, Gemini Gems, Claude) how to generate valid, robust, production-ready workflow JSON files that can be pasted directly into RunMacro's **"Import Workflow JSON"** (Nhập workflow JSON) dialog without any schema or validation errors.

---

## 1. Ten Absolute Golden Rules (Strict Enforcement)

Every JSON output **MUST** strictly follow all 10 rules below. Violating any one will cause RunMacro to reject the import immediately.

1. **Exact Schema Version**:
   - `"schema_version"` MUST be exactly `"runmacro.workflow_import.v1"`.

2. **Exact Mode**:
   - `"mode"` MUST be exactly `"browser"`.

3. **Only 3 Allowed Root Keys**:
   - The root JSON object MUST contain **ONLY** these 3 keys: `"schema_version"`, `"mode"`, `"nodes"`.
   - ❌ **NEVER** add extra root keys such as `"name"`, `"description"`, `"steps"`, `"actions"`, `"version"`, `"author"`. Any unknown key triggers an immediate `[import.unknown_field]` rejection.

4. **All Commands Inside `nodes` Array**:
   - Every execution step must be placed inside the `"nodes"` array.

5. **Exact Command Node Structure**:
   ```json
   {
     "kind": "command",
     "public_type": "<command_name>",
     "public_version": 1,
     "arguments": { ... }
   }
   ```

6. **MANDATORY: 6,000ms Delay Immediately After Opening a URL (`SMART_RECORD_NAVIGATE_DELAY_MS`)**:
   - After every `browser.open_url` command, you **MUST** immediately insert a `flow.delay` node with exactly 6000ms:
     ```json
     { "kind": "command", "public_type": "flow.delay", "public_version": 1, "arguments": { "ms": 6000 } }
     ```
   - *Technical reason*: The browser needs at least 6 seconds to establish a CDP session, load JavaScript bundles, and render the DOM. Without this delay, the next command runs against an empty DOM and fails with `not_found`.

7. **MANDATORY: 2,000ms–3,000ms Settle Delay After Enter / Search Submit**:
   - After pressing Enter (`keyboard.key_press` with `"key": "Enter"`) or clicking a search/submit button, you **MUST** insert a `flow.delay` of 2000ms–3000ms to allow the page to load results.

8. **MANDATORY: Multi-Candidate Fallback Selectors (2 to 4 Candidates)**:
   - **NEVER** guess only a single CSS selector.
   - Always provide **2 to 4 fallback candidates** in `selectorCandidates`, ordered by priority:
     - `priority 10`: Semantic attribute selector (`name`, `id`, `aria-label`).
     - `priority 20`: Tag + attribute or fallback ID selector.
     - `priority 30`: Parent–child or Web Component structure (e.g. `ytd-searchbox input`).
     - `priority 40`: Broad class-based or CSS path selector.

9. **MANDATORY: Verify Page Navigation by URL, Not by Element Selector**:
   - When verifying a page transition, use `browser.smart_assert_url_contains` with a stable URL landmark (strip dynamic query params like tokens, timestamps).
   - Do not rely on element existence to confirm navigation — ads and pop-ups can block elements unpredictably.

10. **Pure JSON Output Only**:
    - Return ONLY a valid JSON block (wrapped in a single ```json fence). Do not include greeting text, commentary, or explanations outside the JSON block.

---

## 2. Supported Command Catalog (`public_type`)

All commands use `"public_version": 1`.

### A. Navigation & Tab Management

| `public_type` | `arguments` | Description |
| :--- | :--- | :--- |
| `browser.open_url` | `{"url": "https://...", "open_mode": "current"}` | Open URL in current tab (`"current"`) or new tab (`"new"`). Always followed by a 6,000ms delay. |
| `browser.reload` | `{"ignore_cache": false}` | Reload current tab. |
| `browser.new_tab` | `{"url": "about:blank"}` | Open a new tab with the specified URL. |
| `browser.switch_tab` | `{"tab_index": 1}` | Switch to a tab by 1-based index. |
| `browser.close_tab` | `{}` | Close the active tab. |
| `browser.back` | `{}` | Navigate back in browser history. |
| `browser.forward` | `{}` | Navigate forward in browser history. |

---

### B. Smart DOM Interaction (`browser.smart_*`)

All smart interaction commands use a `selector_profile` containing multiple fallback candidates:

```json
"selector_profile": {
  "selectorCandidates": [
    { "type": "css", "value": "input[name='q']", "strategy": "ai_css", "priority": 10 },
    { "type": "css", "value": "textarea[name='q']", "strategy": "ai_css", "priority": 20 },
    { "type": "css", "value": "form input[type='text']", "strategy": "ai_css", "priority": 30 }
  ]
}
```

| `public_type` | `arguments` | Description |
| :--- | :--- | :--- |
| `browser.smart_type` | `{"selector_profile": {...}, "text": "value to type"}` | Type text into an input or textarea element. |
| `browser.smart_click` | `{"selector_profile": {...}}` | Left-click an element. |
| `browser.smart_double_click` | `{"selector_profile": {...}}` | Double-click an element. |
| `browser.smart_right_click` | `{"selector_profile": {...}}` | Right-click an element. |
| `browser.smart_hover` | `{"selector_profile": {...}}` | Hover over an element (triggers dropdowns/tooltips). |
| `browser.smart_check` | `{"selector_profile": {...}}` | Check a checkbox or radio button. |
| `browser.smart_uncheck` | `{"selector_profile": {...}}` | Uncheck a checkbox. |
| `browser.smart_toggle` | `{"selector_profile": {...}}` | Toggle a checkbox state. |
| `browser.smart_select_by_value` | `{"selector_profile": {...}, "text": "opt_val"}` | Select an `<option>` by its `value` attribute (passed via `text`). |
| `browser.smart_select_by_text` | `{"selector_profile": {...}, "text": "Display Label"}` | Select an `<option>` by its visible label text. |
| `browser.smart_scroll` | `{"selector_profile": {...}, "scroll_delta_y": 800}` | Scroll down (`scroll_delta_y` > 0) or up (`scroll_delta_y` < 0) by pixels. Also supports `scroll_delta_x` for horizontal. |
| `browser.smart_get_text` | `{"selector_profile": {...}, "result_var": "my_var"}` | Extract element text content into a named workflow variable. |
| `browser.smart_get_attribute` | `{"selector_profile": {...}, "attribute": "href", "result_var": "link_url"}` | Extract an element attribute value into a workflow variable. |
| `browser.smart_extract_table` | `{"selector_profile": {...}, "result_var": "table_data", "timeout_ms": 30000}` | Scrape entire HTML table or structured product grid into a JSON/text variable. |
| `browser.smart_extract_text` | `{"selector_profile": {...}, "result_var": "page_text"}` | Extract inner text of an element into a variable. |
| `browser.smart_extract_attribute` | `{"selector_profile": {...}, "attribute": "src", "result_var": "img_url"}` | Extract element attribute into a variable. |
| `browser.smart_extract_html` | `{"selector_profile": {...}, "result_var": "raw_html"}` | Extract raw inner HTML markup into a variable. |
| `browser.smart_wait_visible` | `{"selector_profile": {...}, "timeout_ms": 15000}` | Wait until the element is visible on screen. |
| `browser.smart_wait_exists` | `{"selector_profile": {...}, "timeout_ms": 15000}` | Wait until the element exists in the DOM. |
| `browser.smart_wait_hidden` | `{"selector_profile": {...}, "timeout_ms": 15000}` | Wait until the element disappears from the screen. |

---

### C. Keyboard & Flow Control (Loops & Jumps)

| `public_type` | `arguments` | Description |
| :--- | :--- | :--- |
| `keyboard.key_press` | `{"key": "Enter"}` | Press a keyboard key (`"Enter"`, `"Tab"`, `"Escape"`, `"Backspace"`, `"Space"`, `"ArrowDown"`, etc.). |
| `keyboard.paste_text` | `{"text": "text to paste"}` | Paste text directly without keystroke delays. |
| `flow.delay` | `{"ms": 5000}` | Pause execution for the specified milliseconds (`6000` = 6s, `30000` = 30s). |
| `flow.pause` | `{}` | Pause execution until the user manually resumes. |
| `flow.label` | `{"label_name": "PAGE_LOOP"}` | Define a named bookmark/label target for loops or jumps. |
| `flow.goto` | `{"target_label": "PAGE_LOOP"}` | Unconditionally jump back to a defined `flow.label`. |
| `flow.if_loop` | `{"max_loops": 100}` | Loop counter condition. Repeats up to `max_loops` times (e.g. 100 pages), then falls through when limit is reached. |

---

### D. File Operations & Data Results Storage

| `public_type` | `arguments` | Description |
| :--- | :--- | :--- |
| `file.create_folder` | `{"folder_path": "data", "exist_ok": true}` | Create a storage folder (e.g. `"data"` or `"data/exports"`). Safely continues if folder exists. |
| `text_results.append_text_file` | `{"file_path": "data/output.txt", "text": "{{page_items}}", "add_newline": true}` | Append text or extracted JSON to a text/log file. Supports `{{variable}}` substitution. |
| `text_results.append_csv_row` | `{"file_path": "data/products.csv", "enable_custom": true, "columns": [{"name": "Title", "value": "{{product_title}}"}, {"name": "Price", "value": "{{product_price}}"}]}` | Append a structured row to a CSV file. |
| `text_results.write_text_file` | `{"file_path": "data/summary.json", "text": "{{table_data}}", "mode": "overwrite"}` | Write or overwrite a text file. |

---

### E. Assertions & Verification

| `public_type` | `arguments` | Description |
| :--- | :--- | :--- |
| `browser.smart_assert_url_contains` | `{"expected_text": "youtube.com", "timeout_ms": 8000, "fail_action": "stop"}` | Assert that the current URL contains the expected string. Stops on failure. |
| `browser.smart_assert_element_exists` | `{"selector_profile": {...}, "timeout_ms": 5000, "fail_action": "stop"}` | Assert that a DOM element exists. |
| `browser.smart_assert_element_text_contains` | `{"selector_profile": {...}, "expected_text": "Success", "timeout_ms": 5000, "fail_action": "stop"}` | Assert that an element's text contains the expected substring. |
| `browser.smart_assert_text_contains` | `{"selector_profile": {...}, "text": "Success"}` | SmartHtml element text assertion. |

---

### F. Variables & Calculations

| `public_type` | `arguments` | Description |
| :--- | :--- | :--- |
| `variable.assign` | `{"var_name": "current_page", "source": "static", "source_value": "1"}` | Assign static text or variable value into a named variable. |
| `variable.calculate` | `{"var_name": "current_page", "expression": "{{current_page}} + 1"}` | Perform arithmetic calculation and store back to variable. |

---

### G. Group & Conditional Nodes

Alongside `kind: "command"`, RunMacro supports structural grouping and conditional branching:

#### Group Node
```json
{
  "kind": "group",
  "name": "Login to account",
  "children": [
    { "kind": "command", "public_type": "browser.smart_type", "public_version": 1, "arguments": { ... } }
  ]
}
```

#### If Node (Conditional)
```json
{
  "kind": "if",
  "condition": {
    "public_type": "browser.smart_if_element_exists",
    "public_version": 1,
    "arguments": {
      "selector_profile": {
        "selectorCandidates": [
          { "type": "css", "value": "button.close-popup", "strategy": "ai_css", "priority": 10 }
        ]
      }
    }
  },
  "then": [
    {
      "kind": "command",
      "public_type": "browser.smart_click",
      "public_version": 1,
      "arguments": {
        "selector_profile": {
          "selectorCandidates": [
            { "type": "css", "value": "button.close-popup", "strategy": "ai_css", "priority": 10 }
          ]
        }
      }
    }
  ],
  "else": []
}
```

---

## 3. Selector Fallback Cheat Sheet (Common Platforms)

### YouTube
- **Search box**:
  - P10: `input[name='search_query']`
  - P20: `input#search`
  - P30: `ytd-searchbox input`
  - P40: `input.ytSearchboxComponentInput`
- **First video title (search results)**:
  - P10: `ytd-video-renderer a#video-title`
  - P20: `a#video-title`
  - P30: `ytd-video-renderer a#thumbnail`
- **Skip Ad button**:
  - P10: `button.ytp-ad-skip-button-modern`
  - P20: `button.ytp-ad-skip-button`
  - P30: `.ytp-skip-ad-button`
- **Like button**:
  - P10: `like-button-view-model button`
  - P20: `button[aria-label*='like']`
  - P30: `button[aria-label*='Like']`

### Google Search
- **Search input**:
  - P10: `textarea[name='q']`
  - P20: `input[name='q']`
  - P30: `textarea[aria-label='Search']`
  - P40: `textarea[aria-label='Tìm kiếm']`
- **First search result**:
  - P10: `div#search a h3`
  - P20: `#rso a h3`
  - P30: `div.g a`

### Facebook
- **Email / Phone input**:
  - P10: `input#email`
  - P20: `input[name='email']`
  - P30: `input[type='text'][autocomplete='username']`
- **Password input**:
  - P10: `input#pass`
  - P20: `input[name='pass']`
  - P30: `input[type='password']`
- **Login button**:
  - P10: `button[name='login']`
  - P20: `button#loginbutton`
  - P30: `button[type='submit']`

### eBay (E-Commerce)
- **Search input**:
  - P10: `input[name='_nkw']`
  - P20: `input#gh-ac`
  - P30: `input.gh-tb`
- **Search button**:
  - P10: `input#gh-btn`
  - P20: `button#gh-search-btn`
- **Next page button (Pagination)**:
  - P10: `a.pagination__next`
  - P20: `a[aria-label*='next' i]`
  - P30: `nav.pagination a.pagination__next`
- **Product list / item grid**:
  - P10: `ul.srp-results`
  - P20: `div.srp-river-results`

---

## 4. Production-Ready Examples

### Example 1: Search YouTube and Watch First Video for 30 Seconds
```json
{
  "schema_version": "runmacro.workflow_import.v1",
  "mode": "browser",
  "nodes": [
    {
      "kind": "command",
      "public_type": "browser.open_url",
      "public_version": 1,
      "arguments": {
        "url": "https://www.youtube.com/",
        "open_mode": "current"
      }
    },
    {
      "kind": "command",
      "public_type": "flow.delay",
      "public_version": 1,
      "arguments": {
        "ms": 6000
      }
    },
    {
      "kind": "command",
      "public_type": "browser.smart_type",
      "public_version": 1,
      "arguments": {
        "selector_profile": {
          "selectorCandidates": [
            { "type": "css", "value": "input[name='search_query']", "strategy": "ai_css", "priority": 10 },
            { "type": "css", "value": "input#search", "strategy": "ai_css", "priority": 20 },
            { "type": "css", "value": "ytd-searchbox input", "strategy": "ai_css", "priority": 30 },
            { "type": "css", "value": "input.ytSearchboxComponentInput", "strategy": "ai_css", "priority": 40 }
          ]
        },
        "text": "lofi hip hop chill beats"
      }
    },
    {
      "kind": "command",
      "public_type": "keyboard.key_press",
      "public_version": 1,
      "arguments": {
        "key": "Enter"
      }
    },
    {
      "kind": "command",
      "public_type": "flow.delay",
      "public_version": 1,
      "arguments": {
        "ms": 3000
      }
    },
    {
      "kind": "command",
      "public_type": "browser.smart_click",
      "public_version": 1,
      "arguments": {
        "selector_profile": {
          "selectorCandidates": [
            { "type": "css", "value": "ytd-video-renderer a#video-title", "strategy": "ai_css", "priority": 10 },
            { "type": "css", "value": "a#video-title", "strategy": "ai_css", "priority": 20 },
            { "type": "css", "value": "ytd-video-renderer a#thumbnail", "strategy": "ai_css", "priority": 30 }
          ]
        }
      }
    },
    {
      "kind": "command",
      "public_type": "flow.delay",
      "public_version": 1,
      "arguments": {
        "ms": 30000
      }
    }
  ]
}
```

### Example 2: Google Search with URL Assertion
```json
{
  "schema_version": "runmacro.workflow_import.v1",
  "mode": "browser",
  "nodes": [
    {
      "kind": "command",
      "public_type": "browser.open_url",
      "public_version": 1,
      "arguments": {
        "url": "https://www.google.com/",
        "open_mode": "current"
      }
    },
    {
      "kind": "command",
      "public_type": "flow.delay",
      "public_version": 1,
      "arguments": {
        "ms": 6000
      }
    },
    {
      "kind": "command",
      "public_type": "browser.smart_type",
      "public_version": 1,
      "arguments": {
        "selector_profile": {
          "selectorCandidates": [
            { "type": "css", "value": "textarea[name='q']", "strategy": "ai_css", "priority": 10 },
            { "type": "css", "value": "input[name='q']", "strategy": "ai_css", "priority": 20 },
            { "type": "css", "value": "textarea[aria-label='Search']", "strategy": "ai_css", "priority": 30 },
            { "type": "css", "value": "textarea[aria-label='Tìm kiếm']", "strategy": "ai_css", "priority": 40 }
          ]
        },
        "text": "RunMacro browser automation"
      }
    },
    {
      "kind": "command",
      "public_type": "keyboard.key_press",
      "public_version": 1,
      "arguments": {
        "key": "Enter"
      }
    },
    {
      "kind": "command",
      "public_type": "flow.delay",
      "public_version": 1,
      "arguments": {
        "ms": 3000
      }
    },
    {
      "kind": "command",
      "public_type": "browser.smart_assert_url_contains",
      "public_version": 1,
      "arguments": {
        "expected_text": "google.com/search",
        "timeout_ms": 8000,
        "fail_action": "stop"
      }
    }
  ]
}
```

### Example 3: E-Commerce Search (eBay), Extract Data & 100-Page Pagination Loop
```json
{
  "schema_version": "runmacro.workflow_import.v1",
  "mode": "browser",
  "nodes": [
    {
      "kind": "command",
      "public_type": "file.create_folder",
      "public_version": 1,
      "arguments": {
        "folder_path": "data",
        "exist_ok": true
      }
    },
    {
      "kind": "command",
      "public_type": "browser.open_url",
      "public_version": 1,
      "arguments": {
        "url": "https://www.ebay.com/",
        "open_mode": "current"
      }
    },
    {
      "kind": "command",
      "public_type": "flow.delay",
      "public_version": 1,
      "arguments": {
        "ms": 6000
      }
    },
    {
      "kind": "command",
      "public_type": "browser.smart_type",
      "public_version": 1,
      "arguments": {
        "selector_profile": {
          "selectorCandidates": [
            { "type": "css", "value": "input[name='_nkw']", "strategy": "ai_css", "priority": 10 },
            { "type": "css", "value": "input#gh-ac", "strategy": "ai_css", "priority": 20 },
            { "type": "css", "value": "input.gh-tb", "strategy": "ai_css", "priority": 30 }
          ]
        },
        "text": "tivi"
      }
    },
    {
      "kind": "command",
      "public_type": "keyboard.key_press",
      "public_version": 1,
      "arguments": {
        "key": "Enter"
      }
    },
    {
      "kind": "command",
      "public_type": "flow.delay",
      "public_version": 1,
      "arguments": {
        "ms": 3000
      }
    },
    {
      "kind": "command",
      "public_type": "flow.label",
      "public_version": 1,
      "arguments": {
        "label_name": "PAGE_LOOP"
      }
    },
    {
      "kind": "command",
      "public_type": "browser.smart_scroll",
      "public_version": 1,
      "arguments": {
        "selector_profile": {
          "selectorCandidates": [
            { "type": "css", "value": "body", "strategy": "ai_css", "priority": 10 }
          ]
        },
        "scroll_delta_y": 1500
      }
    },
    {
      "kind": "command",
      "public_type": "flow.delay",
      "public_version": 1,
      "arguments": {
        "ms": 2000
      }
    },
    {
      "kind": "command",
      "public_type": "browser.smart_extract_table",
      "public_version": 1,
      "arguments": {
        "selector_profile": {
          "selectorCandidates": [
            { "type": "css", "value": "ul.srp-results", "strategy": "ai_css", "priority": 10 },
            { "type": "css", "value": "div.srp-river-results", "strategy": "ai_css", "priority": 20 }
          ]
        },
        "result_var": "page_items"
      }
    },
    {
      "kind": "command",
      "public_type": "text_results.append_text_file",
      "public_version": 1,
      "arguments": {
        "file_path": "data/ebay_tivi.txt",
        "text": "{{page_items}}",
        "add_newline": true
      }
    },
    {
      "kind": "command",
      "public_type": "browser.smart_click",
      "public_version": 1,
      "arguments": {
        "selector_profile": {
          "selectorCandidates": [
            { "type": "css", "value": "a.pagination__next", "strategy": "ai_css", "priority": 10 },
            { "type": "css", "value": "a[aria-label*='next' i]", "strategy": "ai_css", "priority": 20 },
            { "type": "css", "value": "nav.pagination a.pagination__next", "strategy": "ai_css", "priority": 30 }
          ]
        }
      }
    },
    {
      "kind": "command",
      "public_type": "flow.delay",
      "public_version": 1,
      "arguments": {
        "ms": 4000
      }
    },
    {
      "kind": "command",
      "public_type": "flow.if_loop",
      "public_version": 1,
      "arguments": {
        "max_loops": 100
      }
    },
    {
      "kind": "command",
      "public_type": "flow.goto",
      "public_version": 1,
      "arguments": {
        "target_label": "PAGE_LOOP"
      }
    }
  ]
}