Add C4A-Script support and documentation

- Generate OneShot js code geenrator - Introduced a new C4A-Script tutorial example for login flow using Blockly. - Updated index.html to include Blockly theme and event editor modal for script editing. - Created a test HTML file for testing Blockly integration. - Added comprehensive C4A-Script API reference documentation covering commands, syntax, and examples. - Developed core documentation for C4A-Script, detailing its features, commands, and real-world examples. - Updated mkdocs.yml to include new C4A-Script documentation in navigation.
2025-06-07 23:07:19 +08:00
parent ca03acbc82
commit 08a2cdae53
46 changed files with 6914 additions and 326 deletions
--- a/docs/md_v2/api/c4a-script-reference.md
+++ b/docs/md_v2/api/c4a-script-reference.md
@@ -0,0 +1,992 @@
+# C4A-Script API Reference
+
+Complete reference for all C4A-Script commands, syntax, and advanced features.
+
+## Command Categories
+
+### 🧭 Navigation Commands
+
+Navigate between pages and manage browser history.
+
+#### `GO <url>`
+Navigate to a specific URL.
+
+**Syntax:**
+```c4a
+GO <url>
+```
+
+**Parameters:**
+- `url` - Target URL (string)
+
+**Examples:**
+```c4a
+GO https://example.com
+GO https://api.example.com/login
+GO /relative/path
+```
+
+**Notes:**
+- Supports both absolute and relative URLs
+- Automatically handles protocol detection
+- Waits for page load to complete
+
+---
+
+#### `RELOAD`
+Refresh the current page.
+
+**Syntax:**
+```c4a
+RELOAD
+```
+
+**Examples:**
+```c4a
+RELOAD
+```
+
+**Notes:**
+- Equivalent to pressing F5 or clicking browser refresh
+- Waits for page reload to complete
+- Preserves current URL
+
+---
+
+#### `BACK`
+Navigate back in browser history.
+
+**Syntax:**
+```c4a
+BACK
+```
+
+**Examples:**
+```c4a
+BACK
+```
+
+**Notes:**
+- Equivalent to clicking browser back button
+- Does nothing if no previous page exists
+- Waits for navigation to complete
+
+---
+
+#### `FORWARD`
+Navigate forward in browser history.
+
+**Syntax:**
+```c4a
+FORWARD
+```
+
+**Examples:**
+```c4a
+FORWARD
+```
+
+**Notes:**
+- Equivalent to clicking browser forward button
+- Does nothing if no next page exists
+- Waits for navigation to complete
+
+### ⏱️ Wait Commands
+
+Control timing and synchronization with page elements.
+
+#### `WAIT <time>`
+Wait for a specified number of seconds.
+
+**Syntax:**
+```c4a
+WAIT <seconds>
+```
+
+**Parameters:**
+- `seconds` - Number of seconds to wait (number)
+
+**Examples:**
+```c4a
+WAIT 3
+WAIT 1.5
+WAIT 10
+```
+
+**Notes:**
+- Accepts decimal values
+- Useful for giving dynamic content time to load
+- Non-blocking for other browser operations
+
+---
+
+#### `WAIT <selector> <timeout>`
+Wait for an element to appear on the page.
+
+**Syntax:**
+```c4a
+WAIT `<selector>` <timeout>
+```
+
+**Parameters:**
+- `selector` - CSS selector for the element (string in backticks)
+- `timeout` - Maximum seconds to wait (number)
+
+**Examples:**
+```c4a
+WAIT `#content` 10
+WAIT `.loading-spinner` 5
+WAIT `button[type="submit"]` 15
+WAIT `.results .item:first-child` 8
+```
+
+**Notes:**
+- Fails if element doesn't appear within timeout
+- More reliable than fixed time waits
+- Supports complex CSS selectors
+
+---
+
+#### `WAIT "<text>" <timeout>`
+Wait for specific text to appear anywhere on the page.
+
+**Syntax:**
+```c4a
+WAIT "<text>" <timeout>
+```
+
+**Parameters:**
+- `text` - Text content to wait for (string in quotes)
+- `timeout` - Maximum seconds to wait (number)
+
+**Examples:**
+```c4a
+WAIT "Loading complete" 10
+WAIT "Welcome back" 5
+WAIT "Search results" 15
+```
+
+**Notes:**
+- Case-sensitive text matching
+- Searches entire page content
+- Useful for dynamic status messages
+
+### 🖱️ Mouse Commands
+
+Simulate mouse interactions and movements.
+
+#### `CLICK <selector>`
+Click on an element specified by CSS selector.
+
+**Syntax:**
+```c4a
+CLICK `<selector>`
+```
+
+**Parameters:**
+- `selector` - CSS selector for the element (string in backticks)
+
+**Examples:**
+```c4a
+CLICK `#submit-button`
+CLICK `.menu-item:first-child`
+CLICK `button[data-action="save"]`
+CLICK `a[href="/dashboard"]`
+```
+
+**Notes:**
+- Waits for element to be clickable
+- Scrolls element into view if necessary
+- Handles overlapping elements intelligently
+
+---
+
+#### `CLICK <x> <y>`
+Click at specific coordinates on the page.
+
+**Syntax:**
+```c4a
+CLICK <x> <y>
+```
+
+**Parameters:**
+- `x` - X coordinate in pixels (number)
+- `y` - Y coordinate in pixels (number)
+
+**Examples:**
+```c4a
+CLICK 100 200
+CLICK 500 300
+CLICK 0 0
+```
+
+**Notes:**
+- Coordinates are relative to viewport
+- Useful when element selectors are unreliable
+- Consider responsive design implications
+
+---
+
+#### `DOUBLE_CLICK <selector>`
+Double-click on an element.
+
+**Syntax:**
+```c4a
+DOUBLE_CLICK `<selector>`
+```
+
+**Parameters:**
+- `selector` - CSS selector for the element (string in backticks)
+
+**Examples:**
+```c4a
+DOUBLE_CLICK `.file-icon`
+DOUBLE_CLICK `#editable-cell`
+DOUBLE_CLICK `.expandable-item`
+```
+
+**Notes:**
+- Triggers dblclick event
+- Common for opening files or editing inline content
+- Timing between clicks is automatically handled
+
+---
+
+#### `RIGHT_CLICK <selector>`
+Right-click on an element to open context menu.
+
+**Syntax:**
+```c4a
+RIGHT_CLICK `<selector>`
+```
+
+**Parameters:**
+- `selector` - CSS selector for the element (string in backticks)
+
+**Examples:**
+```c4a
+RIGHT_CLICK `#context-target`
+RIGHT_CLICK `.menu-trigger`
+RIGHT_CLICK `img.thumbnail`
+```
+
+**Notes:**
+- Opens browser/application context menu
+- Useful for testing context menu interactions
+- May be blocked by some applications
+
+---
+
+#### `SCROLL <direction> <amount>`
+Scroll the page in a specified direction.
+
+**Syntax:**
+```c4a
+SCROLL <direction> <amount>
+```
+
+**Parameters:**
+- `direction` - Direction to scroll: `UP`, `DOWN`, `LEFT`, `RIGHT`
+- `amount` - Number of pixels to scroll (number)
+
+**Examples:**
+```c4a
+SCROLL DOWN 500
+SCROLL UP 200
+SCROLL LEFT 100
+SCROLL RIGHT 300
+```
+
+**Notes:**
+- Smooth scrolling animation
+- Useful for infinite scroll pages
+- Amount can be larger than viewport
+
+---
+
+#### `MOVE <x> <y>`
+Move mouse cursor to specific coordinates.
+
+**Syntax:**
+```c4a
+MOVE <x> <y>
+```
+
+**Parameters:**
+- `x` - X coordinate in pixels (number)
+- `y` - Y coordinate in pixels (number)
+
+**Examples:**
+```c4a
+MOVE 200 100
+MOVE 500 400
+```
+
+**Notes:**
+- Triggers hover effects
+- Useful for testing mouseover interactions
+- Does not click, only moves cursor
+
+---
+
+#### `DRAG <x1> <y1> <x2> <y2>`
+Drag from one point to another.
+
+**Syntax:**
+```c4a
+DRAG <x1> <y1> <x2> <y2>
+```
+
+**Parameters:**
+- `x1`, `y1` - Starting coordinates (numbers)
+- `x2`, `y2` - Ending coordinates (numbers)
+
+**Examples:**
+```c4a
+DRAG 100 100 500 300
+DRAG 0 200 400 200
+```
+
+**Notes:**
+- Simulates click, drag, and release
+- Useful for sliders, resizing, reordering
+- Smooth drag animation
+
+### ⌨️ Keyboard Commands
+
+Simulate keyboard input and key presses.
+
+#### `TYPE "<text>"`
+Type text into the currently focused element.
+
+**Syntax:**
+```c4a
+TYPE "<text>"
+```
+
+**Parameters:**
+- `text` - Text to type (string in quotes)
+
+**Examples:**
+```c4a
+TYPE "Hello, World!"
+TYPE "user@example.com"
+TYPE "Password123!"
+```
+
+**Notes:**
+- Requires an input element to be focused
+- Types character by character with realistic timing
+- Supports special characters and Unicode
+
+---
+
+#### `TYPE $<variable>`
+Type the value of a variable.
+
+**Syntax:**
+```c4a
+TYPE $<variable>
+```
+
+**Parameters:**
+- `variable` - Variable name (without quotes)
+
+**Examples:**
+```c4a
+SETVAR email = "user@example.com"
+TYPE $email
+```
+
+**Notes:**
+- Variable must be defined with SETVAR first
+- Variable values are strings
+- Useful for reusable credentials or data
+
+---
+
+#### `PRESS <key>`
+Press and release a special key.
+
+**Syntax:**
+```c4a
+PRESS <key>
+```
+
+**Parameters:**
+- `key` - Key name (see supported keys below)
+
+**Supported Keys:**
+- `Tab`, `Enter`, `Escape`, `Space`
+- `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`
+- `Delete`, `Backspace`
+- `Home`, `End`, `PageUp`, `PageDown`
+
+**Examples:**
+```c4a
+PRESS Tab
+PRESS Enter
+PRESS Escape
+PRESS ArrowDown
+```
+
+**Notes:**
+- Simulates actual key press and release
+- Useful for form navigation and shortcuts
+- Case-sensitive key names
+
+---
+
+#### `KEY_DOWN <key>`
+Hold down a modifier key.
+
+**Syntax:**
+```c4a
+KEY_DOWN <key>
+```
+
+**Parameters:**
+- `key` - Modifier key: `Shift`, `Control`, `Alt`, `Meta`
+
+**Examples:**
+```c4a
+KEY_DOWN Shift
+KEY_DOWN Control
+```
+
+**Notes:**
+- Must be paired with KEY_UP
+- Useful for key combinations
+- Meta key is Cmd on Mac, Windows key on PC
+
+---
+
+#### `KEY_UP <key>`
+Release a modifier key.
+
+**Syntax:**
+```c4a
+KEY_UP <key>
+```
+
+**Parameters:**
+- `key` - Modifier key: `Shift`, `Control`, `Alt`, `Meta`
+
+**Examples:**
+```c4a
+KEY_UP Shift
+KEY_UP Control
+```
+
+**Notes:**
+- Must be paired with KEY_DOWN
+- Releases the specified modifier key
+- Good practice to always release held keys
+
+---
+
+#### `CLEAR <selector>`
+Clear the content of an input field.
+
+**Syntax:**
+```c4a
+CLEAR `<selector>`
+```
+
+**Parameters:**
+- `selector` - CSS selector for input element (string in backticks)
+
+**Examples:**
+```c4a
+CLEAR `#search-box`
+CLEAR `input[name="email"]`
+CLEAR `.form-input:first-child`
+```
+
+**Notes:**
+- Works with input, textarea elements
+- Faster than selecting all and deleting
+- Triggers appropriate change events
+
+---
+
+#### `SET <selector> "<value>"`
+Set the value of an input field directly.
+
+**Syntax:**
+```c4a
+SET `<selector>` "<value>"
+```
+
+**Parameters:**
+- `selector` - CSS selector for input element (string in backticks)
+- `value` - Value to set (string in quotes)
+
+**Examples:**
+```c4a
+SET `#email` "user@example.com"
+SET `#age` "25"
+SET `textarea#message` "Hello, this is a test message."
+```
+
+**Notes:**
+- Directly sets value without typing animation
+- Faster than TYPE for long text
+- Triggers change and input events
+
+### 🔀 Control Flow Commands
+
+Add conditional logic and loops to your scripts.
+
+#### `IF (EXISTS <selector>) THEN <command>`
+Execute command if element exists.
+
+**Syntax:**
+```c4a
+IF (EXISTS `<selector>`) THEN <command>
+```
+
+**Parameters:**
+- `selector` - CSS selector to check (string in backticks)
+- `command` - Command to execute if condition is true
+
+**Examples:**
+```c4a
+IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`
+IF (EXISTS `#popup-modal`) THEN CLICK `.close-button`
+IF (EXISTS `.error-message`) THEN RELOAD
+```
+
+**Notes:**
+- Checks for element existence at time of execution
+- Does not wait for element to appear
+- Can be combined with ELSE
+
+---
+
+#### `IF (EXISTS <selector>) THEN <command> ELSE <command>`
+Execute command based on element existence.
+
+**Syntax:**
+```c4a
+IF (EXISTS `<selector>`) THEN <command> ELSE <command>
+```
+
+**Parameters:**
+- `selector` - CSS selector to check (string in backticks)
+- First `command` - Execute if condition is true
+- Second `command` - Execute if condition is false
+
+**Examples:**
+```c4a
+IF (EXISTS `.user-menu`) THEN CLICK `.logout` ELSE CLICK `.login`
+IF (EXISTS `.loading`) THEN WAIT 5 ELSE CLICK `#continue`
+```
+
+**Notes:**
+- Exactly one command will be executed
+- Useful for handling different page states
+- Commands must be on same line
+
+---
+
+#### `IF (NOT EXISTS <selector>) THEN <command>`
+Execute command if element does not exist.
+
+**Syntax:**
+```c4a
+IF (NOT EXISTS `<selector>`) THEN <command>
+```
+
+**Parameters:**
+- `selector` - CSS selector to check (string in backticks)
+- `command` - Command to execute if element doesn't exist
+
+**Examples:**
+```c4a
+IF (NOT EXISTS `.logged-in`) THEN GO /login
+IF (NOT EXISTS `.results`) THEN CLICK `#search-button`
+```
+
+**Notes:**
+- Inverse of EXISTS condition
+- Useful for error handling
+- Can check for missing required elements
+
+---
+
+#### `IF (<javascript>) THEN <command>`
+Execute command based on JavaScript condition.
+
+**Syntax:**
+```c4a
+IF (`<javascript>`) THEN <command>
+```
+
+**Parameters:**
+- `javascript` - JavaScript expression that returns boolean (string in backticks)
+- `command` - Command to execute if condition is true
+
+**Examples:**
+```c4a
+IF (`window.innerWidth < 768`) THEN CLICK `.mobile-menu`
+IF (`document.readyState === "complete"`) THEN CLICK `#start`
+IF (`localStorage.getItem("user")`) THEN GO /dashboard
+```
+
+**Notes:**
+- JavaScript executes in browser context
+- Must return boolean value
+- Access to all browser APIs and globals
+
+---
+
+#### `REPEAT (<command>, <count>)`
+Repeat a command a specific number of times.
+
+**Syntax:**
+```c4a
+REPEAT (<command>, <count>)
+```
+
+**Parameters:**
+- `command` - Command to repeat
+- `count` - Number of times to repeat (number)
+
+**Examples:**
+```c4a
+REPEAT (SCROLL DOWN 300, 5)
+REPEAT (PRESS Tab, 3)
+REPEAT (CLICK `.load-more`, 10)
+```
+
+**Notes:**
+- Executes command exactly count times
+- Useful for pagination, scrolling, navigation
+- No delay between repetitions (add WAIT if needed)
+
+---
+
+#### `REPEAT (<command>, <condition>)`
+Repeat a command while condition is true.
+
+**Syntax:**
+```c4a
+REPEAT (<command>, `<condition>`)
+```
+
+**Parameters:**
+- `command` - Command to repeat
+- `condition` - JavaScript condition to check (string in backticks)
+
+**Examples:**
+```c4a
+REPEAT (SCROLL DOWN 500, `document.querySelector(".load-more")`)
+REPEAT (PRESS ArrowDown, `window.scrollY < document.body.scrollHeight`)
+```
+
+**Notes:**
+- Condition checked before each iteration
+- JavaScript condition must return boolean
+- Be careful to avoid infinite loops
+
+### 💾 Variables and Data
+
+Store and manipulate data within scripts.
+
+#### `SETVAR <name> = "<value>"`
+Create or update a variable.
+
+**Syntax:**
+```c4a
+SETVAR <name> = "<value>"
+```
+
+**Parameters:**
+- `name` - Variable name (alphanumeric, underscore)
+- `value` - Variable value (string in quotes)
+
+**Examples:**
+```c4a
+SETVAR username = "john@example.com"
+SETVAR password = "secret123"
+SETVAR base_url = "https://api.example.com"
+SETVAR counter = "0"
+```
+
+**Notes:**
+- Variables are global within script scope
+- Values are always strings
+- Can be used with TYPE command using $variable syntax
+
+---
+
+#### `EVAL <javascript>`
+Execute arbitrary JavaScript code.
+
+**Syntax:**
+```c4a
+EVAL `<javascript>`
+```
+
+**Parameters:**
+- `javascript` - JavaScript code to execute (string in backticks)
+
+**Examples:**
+```c4a
+EVAL `console.log("Script started")`
+EVAL `window.scrollTo(0, 0)`
+EVAL `localStorage.setItem("test", "value")`
+EVAL `document.title = "Automated Test"`
+```
+
+**Notes:**
+- Full access to browser JavaScript APIs
+- Useful for custom logic and debugging
+- Return values are not captured
+- Be careful with security implications
+
+### 📝 Comments and Documentation
+
+#### `# <comment>`
+Add comments to scripts for documentation.
+
+**Syntax:**
+```c4a
+# <comment text>
+```
+
+**Examples:**
+```c4a
+# This script logs into the application
+# Step 1: Navigate to login page
+GO /login
+
+# Step 2: Fill credentials
+TYPE "user@example.com"
+```
+
+**Notes:**
+- Comments are ignored during execution
+- Useful for documentation and debugging
+- Can appear anywhere in script
+- Supports multi-line documentation blocks
+
+### 🔧 Procedures (Advanced)
+
+Define reusable command sequences.
+
+#### `PROC <name> ... ENDPROC`
+Define a reusable procedure.
+
+**Syntax:**
+```c4a
+PROC <name>
+  <commands>
+ENDPROC
+```
+
+**Parameters:**
+- `name` - Procedure name (alphanumeric, underscore)
+- `commands` - Commands to include in procedure
+
+**Examples:**
+```c4a
+PROC login
+  CLICK `#email`
+  TYPE $email
+  CLICK `#password`
+  TYPE $password
+  CLICK `#submit`
+ENDPROC
+
+PROC handle_popups
+  IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`
+  IF (EXISTS `.newsletter-modal`) THEN CLICK `.close`
+ENDPROC
+```
+
+**Notes:**
+- Procedures must be defined before use
+- Support nested command structures
+- Variables are shared with main script scope
+
+---
+
+#### `<procedure_name>`
+Call a defined procedure.
+
+**Syntax:**
+```c4a
+<procedure_name>
+```
+
+**Examples:**
+```c4a
+# Define procedure first
+PROC setup
+  GO /login
+  WAIT `#form` 5
+ENDPROC
+
+# Call procedure
+setup
+login
+```
+
+**Notes:**
+- Procedure must be defined before calling
+- Can be called multiple times
+- No parameters supported (use variables instead)
+
+## Error Handling Best Practices
+
+### 1. Always Use Waits
+```c4a
+# Bad - element might not be ready
+CLICK `#button`
+
+# Good - wait for element first
+WAIT `#button` 5
+CLICK `#button`
+```
+
+### 2. Handle Optional Elements
+```c4a
+# Check before interacting
+IF (EXISTS `.popup`) THEN CLICK `.close`
+IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`
+
+# Then proceed with main flow
+CLICK `#main-action`
+```
+
+### 3. Use Descriptive Variables
+```c4a
+# Set up reusable data
+SETVAR admin_email = "admin@company.com"
+SETVAR test_password = "TestPass123!"
+SETVAR staging_url = "https://staging.example.com"
+
+# Use throughout script
+GO $staging_url
+TYPE $admin_email
+```
+
+### 4. Add Debugging Information
+```c4a
+# Log progress
+EVAL `console.log("Starting login process")`
+GO /login
+
+# Verify page state
+IF (`document.title.includes("Login")`) THEN EVAL `console.log("On login page")`
+
+# Continue with login
+TYPE $username
+```
+
+## Common Patterns
+
+### Login Flow
+```c4a
+# Complete login automation
+SETVAR email = "user@example.com"
+SETVAR password = "mypassword"
+
+GO /login
+WAIT `#login-form` 5
+
+# Handle optional cookie banner
+IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`
+
+# Fill and submit form
+CLICK `#email`
+TYPE $email
+PRESS Tab
+TYPE $password
+CLICK `button[type="submit"]`
+
+# Wait for redirect
+WAIT `.dashboard` 10
+```
+
+### Infinite Scroll
+```c4a
+# Load all content with infinite scroll
+GO /products
+
+# Scroll and load more content
+REPEAT (SCROLL DOWN 500, `document.querySelector(".load-more")`)
+
+# Alternative: Fixed number of scrolls
+REPEAT (SCROLL DOWN 800, 10)
+WAIT 2
+```
+
+### Form Validation
+```c4a
+# Handle form with validation
+SET `#email` "invalid-email"
+CLICK `#submit`
+
+# Check for validation error
+IF (EXISTS `.error-email`) THEN SET `#email` "valid@example.com"
+
+# Retry submission
+CLICK `#submit`
+WAIT `.success-message` 5
+```
+
+### Multi-step Process
+```c4a
+# Complex multi-step workflow
+PROC navigate_to_step
+  CLICK `.next-button`
+  WAIT `.step-content` 5
+ENDPROC
+
+# Step 1
+WAIT `.step-1` 5
+SET `#name` "John Doe"
+navigate_to_step
+
+# Step 2
+SET `#email` "john@example.com"
+navigate_to_step
+
+# Step 3
+CLICK `#submit-final`
+WAIT `.confirmation` 10
+```
+
+## Integration with Crawl4AI
+
+Use C4A-Script with Crawl4AI for dynamic content interaction:
+
+```python
+from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
+
+# Define interaction script
+script = """
+# Handle dynamic content loading
+WAIT `.content` 5
+IF (EXISTS `.load-more-button`) THEN CLICK `.load-more-button`
+WAIT `.additional-content` 5
+
+# Accept cookies if needed
+IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-all`
+"""
+
+config = CrawlerRunConfig(
+    c4a_script=script,
+    wait_for=".content",
+    screenshot=True
+)
+
+async with AsyncWebCrawler() as crawler:
+    result = await crawler.arun("https://example.com", config=config)
+    print(result.markdown)
+```
+
+This reference covers all available C4A-Script commands and patterns. For interactive learning, try the [tutorial](../examples/c4a_script/tutorial/) or [live demo](https://docs.crawl4ai.com/c4a-script/demo).
--- a/docs/md_v2/core/c4a-script.md
+++ b/docs/md_v2/core/c4a-script.md
@@ -0,0 +1,395 @@
+# C4A-Script: Visual Web Automation Made Simple
+
+## What is C4A-Script?
+
+C4A-Script is a powerful, human-readable domain-specific language (DSL) designed for web automation and interaction. Think of it as a simplified programming language that anyone can read and write, perfect for automating repetitive web tasks, testing user interfaces, or creating interactive demos.
+
+### Why C4A-Script?
+
+**Simple Syntax, Powerful Results**
+```c4a
+# Navigate and interact in plain English
+GO https://example.com
+WAIT `#search-box` 5
+TYPE "Hello World"
+CLICK `button[type="submit"]`
+```
+
+**Visual Programming Support**
+C4A-Script comes with a built-in Blockly visual editor, allowing you to create scripts by dragging and dropping blocks - no coding experience required!
+
+**Perfect for:**
+- **UI Testing**: Automate user interaction flows
+- **Demo Creation**: Build interactive product demonstrations  
+- **Data Entry**: Automate form filling and submissions
+- **Testing Workflows**: Validate complex user journeys
+- **Training**: Teach web automation without code complexity
+
+## Getting Started: Your First Script
+
+Let's create a simple script that searches for something on a website:
+
+```c4a
+# My first C4A-Script
+GO https://duckduckgo.com
+
+# Wait for the search box to appear
+WAIT `input[name="q"]` 10
+
+# Type our search query
+TYPE "Crawl4AI"
+
+# Press Enter to search
+PRESS Enter
+
+# Wait for results
+WAIT `.results` 5
+```
+
+That's it! In just a few lines, you've automated a complete search workflow.
+
+## Interactive Tutorial & Live Demo
+
+Want to learn by doing? We've got you covered:
+
+**🚀 [Live Demo](https://docs.crawl4ai.com/c4a-script/demo)** - Try C4A-Script in your browser right now!
+
+**📁 [Tutorial Examples](/examples/c4a_script/)** - Complete examples with source code
+
+**🛠️ [Local Tutorial](/examples/c4a_script/tutorial/)** - Run the interactive tutorial on your machine
+
+### Running the Tutorial Locally
+
+The tutorial includes a Flask-based web interface with:
+- **Live Code Editor** with syntax highlighting
+- **Visual Blockly Editor** for drag-and-drop programming
+- **Recording Mode** to capture your actions and generate scripts
+- **Timeline View** to see and edit your automation steps
+
+```bash
+# Clone and navigate to the tutorial
+cd docs/examples/c4a_script/tutorial/
+
+# Install dependencies
+pip install flask
+
+# Launch the tutorial server
+python app.py
+
+# Open http://localhost:5000 in your browser
+```
+
+## Core Concepts
+
+### Commands and Syntax
+
+C4A-Script uses simple, English-like commands. Each command does one specific thing:
+
+```c4a
+# Comments start with #
+COMMAND parameter1 parameter2
+
+# Most commands use CSS selectors in backticks
+CLICK `#submit-button`
+
+# Text content goes in quotes
+TYPE "Hello, World!"
+
+# Numbers are used directly
+WAIT 3
+```
+
+### Selectors: Finding Elements
+
+C4A-Script uses CSS selectors to identify elements on the page:
+
+```c4a
+# By ID
+CLICK `#login-button`
+
+# By class
+CLICK `.submit-btn`
+
+# By attribute
+CLICK `button[type="submit"]`
+
+# By text content
+CLICK `button:contains("Sign In")`
+
+# Complex selectors
+CLICK `.form-container input[name="email"]`
+```
+
+### Variables and Dynamic Content
+
+Store and reuse values with variables:
+
+```c4a
+# Set a variable
+SETVAR username = "john@example.com"
+SETVAR password = "secret123"
+
+# Use variables (prefix with $)
+TYPE $username
+PRESS Tab
+TYPE $password
+```
+
+## Command Categories
+
+### 🧭 Navigation Commands
+Move around the web like a user would:
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `GO` | Navigate to URL | `GO https://example.com` |
+| `RELOAD` | Refresh current page | `RELOAD` |
+| `BACK` | Go back in history | `BACK` |
+| `FORWARD` | Go forward in history | `FORWARD` |
+
+### ⏱️ Wait Commands
+Ensure elements are ready before interacting:
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `WAIT` | Wait for time/element/text | `WAIT 3` or `WAIT \`#element\` 10` |
+
+### 🖱️ Mouse Commands
+Click, drag, and move like a human:
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `CLICK` | Click element or coordinates | `CLICK \`button\`` or `CLICK 100 200` |
+| `DOUBLE_CLICK` | Double-click element | `DOUBLE_CLICK \`.item\`` |
+| `RIGHT_CLICK` | Right-click element | `RIGHT_CLICK \`#menu\`` |
+| `SCROLL` | Scroll in direction | `SCROLL DOWN 500` |
+| `DRAG` | Drag from point to point | `DRAG 100 100 500 300` |
+
+### ⌨️ Keyboard Commands  
+Type text and press keys naturally:
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `TYPE` | Type text or variable | `TYPE "Hello"` or `TYPE $username` |
+| `PRESS` | Press special keys | `PRESS Tab` or `PRESS Enter` |
+| `CLEAR` | Clear input field | `CLEAR \`#search\`` |
+| `SET` | Set input value directly | `SET \`#email\` "user@example.com"` |
+
+### 🔀 Control Flow
+Add logic and repetition to your scripts:
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `IF` | Conditional execution | `IF (EXISTS \`#popup\`) THEN CLICK \`#close\`` |
+| `REPEAT` | Loop commands | `REPEAT (SCROLL DOWN 300, 5)` |
+
+### 💾 Variables & Advanced
+Store data and execute custom code:
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `SETVAR` | Create variable | `SETVAR email = "test@example.com"` |
+| `EVAL` | Execute JavaScript | `EVAL \`console.log('Hello')\`` |
+
+## Real-World Examples
+
+### Example 1: Login Flow
+```c4a
+# Complete login automation
+GO https://myapp.com/login
+
+# Wait for page to load
+WAIT `#login-form` 5
+
+# Fill credentials
+CLICK `#email`
+TYPE "user@example.com"
+PRESS Tab
+TYPE "mypassword"
+
+# Submit form
+CLICK `button[type="submit"]`
+
+# Wait for dashboard
+WAIT `.dashboard` 10
+```
+
+### Example 2: E-commerce Shopping
+```c4a
+# Shopping automation with variables
+SETVAR product = "laptop"
+SETVAR budget = "1000"
+
+GO https://shop.example.com
+WAIT `#search-box` 3
+
+# Search for product
+TYPE $product
+PRESS Enter
+WAIT `.product-list` 5
+
+# Filter by price
+CLICK `.price-filter`
+SET `#max-price` $budget
+CLICK `.apply-filters`
+
+# Select first result
+WAIT `.product-item` 3
+CLICK `.product-item:first-child`
+```
+
+### Example 3: Form Automation with Conditions
+```c4a
+# Smart form filling with error handling
+GO https://forms.example.com
+
+# Check if user is already logged in
+IF (EXISTS `.user-menu`) THEN GO https://forms.example.com/new
+IF (NOT EXISTS `.user-menu`) THEN CLICK `#login-link`
+
+# Fill form
+WAIT `#contact-form` 5
+SET `#name` "John Doe"
+SET `#email` "john@example.com"
+SET `#message` "Hello from C4A-Script!"
+
+# Handle popup if it appears
+IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`
+
+# Submit
+CLICK `#submit-button`
+WAIT `.success-message` 10
+```
+
+## Visual Programming with Blockly
+
+C4A-Script includes a powerful visual programming interface built on Google Blockly. Perfect for:
+
+- **Non-programmers** who want to create automation
+- **Rapid prototyping** of automation workflows  
+- **Educational environments** for teaching automation concepts
+- **Collaborative development** where visual representation helps communication
+
+### Features:
+- **Drag & Drop Interface**: Build scripts by connecting blocks
+- **Real-time Sync**: Changes in visual mode instantly update the text script
+- **Smart Block Types**: Blocks are categorized by function (Navigation, Actions, etc.)
+- **Error Prevention**: Visual connections prevent syntax errors
+- **Comment Support**: Add visual comment blocks for documentation
+
+Try the visual editor in our [live demo](https://docs.crawl4ai.com/c4a-script/demo) or [local tutorial](/examples/c4a_script/tutorial/).
+
+## Advanced Features
+
+### Recording Mode
+The tutorial interface includes a recording feature that watches your browser interactions and automatically generates C4A-Script commands:
+
+1. Click "Record" in the tutorial interface
+2. Perform actions in the browser preview
+3. Watch as C4A-Script commands are generated in real-time
+4. Edit and refine the generated script
+
+### Error Handling and Debugging
+C4A-Script provides clear error messages and debugging information:
+
+```c4a
+# Use comments for debugging
+# This will wait up to 10 seconds for the element
+WAIT `#slow-loading-element` 10
+
+# Check if element exists before clicking
+IF (EXISTS `#optional-button`) THEN CLICK `#optional-button`
+
+# Use EVAL for custom debugging
+EVAL `console.log("Current page title:", document.title)`
+```
+
+### Integration with Crawl4AI
+C4A-Script integrates seamlessly with Crawl4AI's web crawling capabilities:
+
+```python
+from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
+
+# Use C4A-Script for interaction before crawling
+script = """
+GO https://example.com
+CLICK `#load-more-content`
+WAIT `.dynamic-content` 5
+"""
+
+config = CrawlerRunConfig(
+    js_code=script,
+    wait_for=".dynamic-content"
+)
+
+async with AsyncWebCrawler() as crawler:
+    result = await crawler.arun("https://example.com", config=config)
+    print(result.markdown)
+```
+
+## Best Practices
+
+### 1. Always Wait for Elements
+```c4a
+# Bad: Clicking immediately
+CLICK `#button`
+
+# Good: Wait for element to appear
+WAIT `#button` 5
+CLICK `#button`
+```
+
+### 2. Use Descriptive Comments
+```c4a
+# Login to user account
+GO https://myapp.com/login
+WAIT `#login-form` 5
+
+# Enter credentials
+TYPE "user@example.com"
+PRESS Tab
+TYPE "password123"
+
+# Submit and wait for redirect
+CLICK `#submit-button`
+WAIT `.dashboard` 10
+```
+
+### 3. Handle Variable Conditions
+```c4a
+# Handle different page states
+IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`
+IF (EXISTS `.popup-modal`) THEN CLICK `.close-modal`
+
+# Proceed with main workflow
+CLICK `#main-action`
+```
+
+### 4. Use Variables for Reusability
+```c4a
+# Define once, use everywhere
+SETVAR base_url = "https://myapp.com"
+SETVAR test_email = "test@example.com"
+
+GO $base_url/login
+SET `#email` $test_email
+```
+
+## Getting Help
+
+- **📖 [Complete Examples](/examples/c4a_script/)** - Real-world automation scripts
+- **🎮 [Interactive Tutorial](/examples/c4a_script/tutorial/)** - Hands-on learning environment  
+- **📋 [API Reference](/api/c4a-script-reference/)** - Detailed command documentation
+- **🌐 [Live Demo](https://docs.crawl4ai.com/c4a-script/demo)** - Try it in your browser
+
+## What's Next?
+
+Ready to dive deeper? Check out:
+
+1. **[API Reference](/api/c4a-script-reference/)** - Complete command documentation
+2. **[Tutorial Examples](/examples/c4a_script/)** - Copy-paste ready scripts
+3. **[Local Tutorial Setup](/examples/c4a_script/tutorial/)** - Run the full development environment
+
+C4A-Script makes web automation accessible to everyone. Whether you're a developer automating tests, a designer creating interactive demos, or a business user streamlining repetitive tasks, C4A-Script has the tools you need.
+
+*Start automating today - your future self will thank you!* 🚀