webreel

What this skill does

# webreel

webreel is a CLI for recording scripted browser demonstrations as MP4, GIF, or WebM files. It drives a headless Chrome instance, captures frames at ~60fps, and encodes them with ffmpeg. Cursor animation, keystroke HUD overlays, and sound effects are built in.

## IMPORTANT: Sandbox installation

`webreel` is **pre-installed globally** in this sandbox (custom build with bug fixes).

- Do **NOT** run `npm install webreel`, `npx webreel`, or any other installation command.
- Use the `webreel` CLI directly: `webreel record`, `webreel preview`, `webreel validate`.
- Chrome and ffmpeg are also pre-installed. Do NOT run `webreel install`.

## Commands

| Command                      | Description                              |
| ---------------------------- | ---------------------------------------- |
| `webreel record [videos...]` | Record video(s) from config              |
| `webreel preview [video]`    | Run in visible browser without recording |
| `webreel validate`           | Check config for errors                  |
| `webreel record --verbose`   | Log each step as it executes             |
| `webreel record --dry-run`   | Print resolved config without recording  |

---

# Configuration

Videos are defined in a `webreel.config.json` file:

```json
{
  "$schema": "https://webreel.dev/schema/v1.json",
  "viewport": { "width": 1920, "height": 1080 },
  "clickDwell": 500,
  "videos": {
    "demo": {
      "url": "http://localhost:3000",
      "output": "demo.mp4",
      "zoom": 2,
      "waitFor": ".loaded",
      "steps": [...]
    }
  }
}
```

### Top-level fields

| Field        | Type                | Description                                                 |
| ------------ | ------------------- | ----------------------------------------------------------- |
| `$schema`    | string              | Schema URL for IDE autocompletion                           |
| `viewport`   | `{ width, height }` | Default viewport dimensions                                 |
| `clickDwell` | number              | **Set to 500.** Milliseconds cursor holds before each click |
| `theme`      | object              | Cursor and HUD customization                                |
| `videos`     | object              | Map of video name → video config (required)                 |

### Per-video fields

| Field      | Type   | Description                                                      |
| ---------- | ------ | ---------------------------------------------------------------- |
| `url`      | string | Target URL (absolute or relative to baseUrl)                     |
| `output`   | string | Output filename (extension determines format: .mp4, .gif, .webm) |
| `viewport` | object | Override viewport for this video                                 |
| `zoom`     | number | CSS zoom level (e.g., 2 for 2x)                                  |
| `waitFor`  | string | CSS selector to wait for before starting steps                   |
| `steps`    | array  | Array of step objects (required)                                 |

---

# Element targeting

Several steps target DOM elements. Use ONE of:

| Field      | Description                                                 |
| ---------- | ----------------------------------------------------------- |
| `text`     | Match by visible text content                               |
| `selector` | Match by CSS selector                                       |
| `within`   | (optional) CSS selector to scope search to a parent element |

Use `text` OR `selector`, not both. `within` is always optional.

---

# Step types reference

Every step requires an `action` field. Optional common fields:

- `description` (string) — human-readable note (not used at runtime, but useful for pause timing comments)

**Do NOT use `delay` or `defaultDelay`** — see config patterns below.

## pause

Wait for a fixed duration. **Use 5x multiplier** (see config patterns).

| Field | Type   | Required |
| ----- | ------ | -------- |
| `ms`  | number | yes      |

```json
{ "action": "pause", "ms": 5000, "description": "~1s on screen" }
```

## click

Click a DOM element. **MUST be preceded by moveTo + pause** (see config patterns).

| Field       | Type     | Required |
| ----------- | -------- | -------- |
| `text`      | string   | no       |
| `selector`  | string   | no       |
| `within`    | string   | no       |
| `modifiers` | string[] | no       |

Provide `text` or `selector` (at least one).

```json
{ "action": "click", "text": "Submit" }
{ "action": "click", "selector": "#save-btn" }
{ "action": "click", "text": "Item 3", "modifiers": ["shift"] }
{ "action": "click", "text": "Delete", "within": ".modal" }
```

## type

Type text into an input. **Set charDelay: 120 or higher.**

| Field       | Type   | Required                        |
| ----------- | ------ | ------------------------------- |
| `text`      | string | yes                             |
| `selector`  | string | no                              |
| `within`    | string | no                              |
| `charDelay` | number | no (but **always set to 120+**) |

```json
{
  "action": "type",
  "text": "[email protected]",
  "selector": "#email",
  "charDelay": 120
}
```

## key

Press a keyboard shortcut.

| Field    | Type                    | Required |
| -------- | ----------------------- | -------- |
| `key`    | string                  | yes      |
| `target` | string or ElementTarget | no       |

Key combo syntax: `"cmd+s"`, `"ctrl+shift+p"`, `"Enter"`, `"Escape"`, `"ArrowDown"`.

```json
{ "action": "key", "key": "cmd+s" }
{ "action": "key", "key": "Enter" }
```

## moveTo

Move cursor to an element without clicking. **Use before every click.**

| Field      | Type   | Required |
| ---------- | ------ | -------- |
| `text`     | string | no       |
| `selector` | string | no       |
| `within`   | string | no       |

```json
{ "action": "moveTo", "text": "Settings" }
{ "action": "moveTo", "selector": "#submit-btn" }
```

## hover

Hover over an element (triggers CSS :hover and mouseenter).

| Field      | Type   | Required |
| ---------- | ------ | -------- |
| `text`     | string | no       |
| `selector` | string | no       |
| `within`   | string | no       |

```json
{ "action": "hover", "selector": ".tooltip-trigger" }
```

## scroll

Scroll the page or a specific element.

| Field      | Type   | Required |
| ---------- | ------ | -------- |
| `x`        | number | no       |
| `y`        | number | no       |
| `text`     | string | no       |
| `selector` | string | no       |
| `within`   | string | no       |

```json
{ "action": "scroll", "y": 400 }
{ "action": "scroll", "y": 300, "selector": ".scrollable-panel" }
```

## wait

Wait for an element to appear in the DOM.

| Field      | Type   | Required |
| ---------- | ------ | -------- |
| `selector` | string | no       |
| `text`     | string | no       |
| `within`   | string | no       |
| `timeout`  | number | no       |

```json
{ "action": "wait", "selector": ".results-loaded", "timeout": 5000 }
{ "action": "wait", "text": "Success" }
```

## navigate

Navigate to a new URL.

| Field | Type   | Required |
| ----- | ------ | -------- |
| `url` | string | yes      |

```json
{ "action": "navigate", "url": "/settings" }
```

## drag

Drag from one element to another.

| Field  | Type          | Required |
| ------ | ------------- | -------- |
| `from` | ElementTarget | yes      |
| `to`   | ElementTarget | yes      |

```json
{
  "action": "drag",
  "from": { "text": "Task A", "within": ".column-todo" },
  "to": { "selector": ".card-list", "within": ".column-done" }
}
```

## select

Select a value in a `<select>` dropdown.

| Field      | Type   | Required |
| ---------- | ------ | -------- |
| `selector` | string | no       |
| `text`     | string | no       |
| `within`   | string | no       |
| `value`    | string | yes      |

```json
{ "action": "select", "selector": "#country", "value": "us" }
``