> ## 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.

# Headful Debugging (VNC)

Figranium includes powerful **Headful Debugging** capabilities that allow you to see and interact with the automation as it runs. This is powered by a VNC server running alongside the Playwright container.

## **Why Headful?**

* **Debugging**: Step through tasks visually to identify why a selector fails.
* **Manual Intervention**: Solve CAPTCHAs or complete complex 2FA flows that automation cannot handle.
* **Exploration**: Browse sites naturally to discover selectors and API endpoints.
* **Recording**: Create high-fidelity video demonstrations of your automation.

## **Starting a Headful Session**

1. **Editor**: Open a task in the editor.
2. **Run**: Click **Open Browser** in the editor panel to log in or debug visually.

The browser window will open inside the VNC viewer embedded in the UI.

## **Controls**

The VNC interface provides a standard desktop environment:

* **Mouse/Keyboard**: Full interaction support.
* **Clipboard**: Copy/paste text between your host and the remote browser.
* **Resolution**: The viewport resizes dynamically (default 1920x1080).

## **Popups and multi-page navigation**

Headful sessions automatically track the active browser page across popups and new tabs. When a site opens a popup — for example, an OAuth login window or a payment gateway — Figranium switches to the new page so you can interact with it in the VNC viewer. When that page closes, the session returns to the previous page.

This means workflows that span multiple pages work without any extra configuration:

* **OAuth and SSO flows**: Complete third-party login prompts that open in a popup.
* **Payment windows**: Interact with payment providers that redirect through a new tab.
* **Multi-tab browsing**: Open links in new tabs and switch between them naturally.

If all pages in a session are closed, the headful session remains active and waits for a new page to open.

## **Persistence**

Headful sessions use a dedicated persistent browser profile directory (`data/browser-profile-headful`). Cookies are automatically synced to agent and scrape runs via `data/headful-storage-state.json`:

* **Sync interval**: Every 30 seconds while a headful session is active.
* **Sync on close**: Cookies are also saved when the headful session is stopped via **Close Browser**.
* **Agent & scrape pickup**: Each non-stateless agent or scrape run injects the saved cookies at startup, so they pick up any session established in headful.

This means the typical workflow still works:

1. **Login once**: Log in manually in the headful browser.
2. **Automate**: Run an Agent or Scrape task — it will automatically have those cookies available.

**Note**: Only non-expired cookies are synced. If `headful-storage-state.json` does not exist yet (no headful session has run), agent and scrape runs simply start with their own profile cookies.

**Stateless Option**: Enable `statelessExecution` to launch a clean, incognito-like session that won't save cookies and won't receive headful cookies.

## **Element picking**

The headful browser doubles as a selector discovery tool. When you click the **Highlight Tool** icon in an action block's selector field, Figranium opens a headful session with **inspect mode already active** — no extra step required.

1. The crosshair overlay appears automatically in the VNC viewer.
2. Hover over any element to see it highlighted with a tooltip showing the top selector candidates.
3. Click the element to confirm your selection.

Figranium generates up to five selector alternatives, ranked from most readable to most structural. The best candidate auto-fills the selector field, and the alternatives appear as clickable pills below the input so you can compare and switch without re-picking.

See [CSS Selectors — Built-in Highlight Tool](/docs/selectors#built-in-highlight-tool) for details on the ranking algorithm.

## **Variable support**

Headful sessions resolve [task variables](/docs/variables) in the starting URL. For example, if your task defines a variable `site`, you can set the headful URL to:

```text theme={null}
https://{$site}.example.com/dashboard
```

Figranium replaces the variable with its current value before navigating.

## **API integration**

You can start a headful session programmatically:

```text theme={null}
curl -X POST http://localhost:11345/headful \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
```

The response includes the VNC connection URL.

## **Stopping**

Click **Close Browser** in the Editor to terminate the session and close the browser. This ensures resources are freed.