Documentation Index
Fetch the complete documentation index at: https://figranium.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
Figranium provides robust control flow mechanisms to handle dynamic web pages, conditional logic, pagination, and multi-step processes.
Conditional Execution (If / Else / End)
The If block executes a sequence of actions only when a condition is met.
Structure
Every if block must be closed with an end block. An optional else block can be placed between them.
{ "type": "if", "value": "<condition>" },
// actions if condition is true
{ "type": "else" },
// actions if condition is false (optional)
{ "type": "end" }
Condition Types
1. JavaScript Expression
A JS expression evaluated in the browser page context. Must return a truthy/falsy value.
exists('.error-message') // checks if element exists
text('.status') === 'Success' // checks element text
url().includes('/dashboard') // checks current URL
{$count} > 5 // compares a variable
block.output !== '' // checks previous block result
| Helper | Description |
|---|
exists(selector) | Returns true if the element is found in the DOM |
text(selector) | Returns the text content of the first matching element |
url() | Returns the current page URL |
vars.name | Access a runtime variable by name |
block.output | The result of the previous action block |
html | The full page HTML as a string |
| Field | Description |
|---|
conditionVarType | string, number, or boolean |
conditionVar | Variable name or {$varName} reference |
conditionOp | Comparison operator (see table below) |
conditionValue | The value to compare against |
| Type | Operators |
|---|
| String | equals, not_equals, contains, starts_with, ends_with, matches (regex) |
| Number | equals, not_equals, gt, gte, lt, lte |
| Boolean | is_true, is_false |
Example: Login Check
Check whether the user is already logged in, and skip the login form if so:
{ "type": "navigate", "value": "https://app.example.com" },
{ "type": "if", "value": "exists('.user-avatar')" },
{ "type": "stop", "value": "success" },
{ "type": "else" },
{ "type": "click", "selector": "#login-button" },
{ "type": "type", "selector": "#email", "value": "{$email}" },
{ "type": "type", "selector": "#password", "value": "{$password}" },
{ "type": "click", "selector": "[type='submit']" },
{ "type": "end" }
Nested Conditions
You can nest if blocks inside each other. Each nested block requires its own end:
{ "type": "if", "value": "exists('.product')" },
{ "type": "if", "value": "text('.stock-status') === 'In Stock'" },
{ "type": "click", "selector": ".add-to-cart" },
{ "type": "else" },
{ "type": "set", "varName": "outOfStock", "value": "true" },
{ "type": "end" },
{ "type": "end" }
While Loop
Executes a block of actions repeatedly as long as the condition remains true.
{ "type": "while", "value": "exists('.next-page')" },
// actions to repeat
{ "type": "end" }
- Pagination: Click “next page” until there are no more pages.
- Polling: Wait for a specific element or state to appear.
- Retry logic: Re-attempt an action until it succeeds.
Example: Scraping paginated results
{ "type": "navigate", "value": "https://example.com/listings" },
{ "type": "while", "value": "exists('.pagination .next:not(.disabled)')" },
{ "type": "javascript", "value": "/* collect items on this page */" },
{ "type": "click", "selector": ".pagination .next" },
{ "type": "wait", "value": "1500" },
{ "type": "end" }
{ "type": "set", "varName": "pageNum", "value": "1" },
{ "type": "while", "value": "exists('.next') && {$pageNum} <= 10" },
{ "type": "start", "value": "scrape-page-task-id" },
{ "type": "click", "selector": ".next" },
{ "type": "set", "varName": "pageNum", "value": "{$pageNum} + 1" },
{ "type": "end" }
Foreach Loop
Iterates over all elements matching a CSS selector, executing the block once per element.
{ "type": "foreach", "selector": ".product-card" },
// actions scoped to each element
{ "type": "end" }
| Variable | Description |
|---|
loop.index | Zero-based index of the current iteration |
loop.text | The full text content of the current element |
loop.html | The full HTML of the current element |
loop.item | Reference to the current element (for click/interact without a selector) |
{ "type": "foreach", "selector": ".todo-item input[type='checkbox']:not(:checked)" },
{ "type": "click" },
{ "type": "end" }
{ "type": "foreach", "selector": "table tbody tr" },
{ "type": "javascript", "value": "return { row: loop.index, text: loop.text }" },
{ "type": "end" }
Repeat N Times
Executes a block a fixed number of times regardless of any condition.
{ "type": "repeat", "value": "5" },
// actions to repeat
{ "type": "end" }
loop.index variable is available inside repeat blocks (zero-based).
Example: Submit a form 3 times
{ "type": "repeat", "value": "3" },
{ "type": "click", "selector": "#submit-btn" },
{ "type": "wait", "value": "2000" },
{ "type": "end" }
Error Handling (On Error)
The On Error block acts like a try/catch. If any action in the main flow throws an error (timeout, element not found, network failure), execution jumps to the error handler block.
{ "type": "on_error" },
// recovery actions
{ "type": "end" }
{ "type": "navigate", "value": "https://example.com" },
{ "type": "click", "selector": ".login-button" },
{ "type": "on_error" },
{ "type": "if", "value": "exists('.captcha-frame')" },
{ "type": "stop", "value": "error" },
{ "type": "end" },
{ "type": "end" }
{ "type": "on_error" },
{ "type": "end" },
{ "type": "click", "selector": "#cookie-accept", "timeout": 3000 },
on_error/end block before an optional action effectively makes that action non-fatal.
See Error Handling for a deeper guide on retry patterns and resilient task design.
Stop Task
Immediately terminates the current task execution with a given status.
{ "type": "stop", "value": "success" }
{ "type": "stop", "value": "error" }
stop inside conditionals to short-circuit execution when a goal is already met or when an unrecoverable state is detected.