# QuokkaPix Agent Interactivity Guide

QuokkaPix is a browser-only image editor. Agents should use browser automation or the in-browser `window.QuokkaPixAgent` API. There is no public server processing API; image files must be uploaded through the browser and are processed locally during normal use.

## Discovery

- Agent manifest: `/agent-manifest.json`
- LLM summary: `/llms.txt`
- HTML guide: `/agents.html`
- ARD catalog: `/.well-known/ai-catalog.json`

## Stable Selectors

- Root/status element: `.page-shell`
- File input: `[data-agent="file-picker"]` or `[data-agent-action="upload"]`
- Start button: `[data-agent="process-trigger"]` or `[data-agent-action="start"]`
- Cancel button: `[data-agent="cancel-trigger"]`
- Single file download: `[data-agent="download-link"]`
- ZIP download: `[data-agent="zip-download-link"]`
- Preview/open result link: `[data-agent="preview-link"]`

Avoid relying on CSS class names or visible button text. Prefer `data-agent`, `data-agent-action`, `data-agent-output`, `data-agent-status`, `data-process-status` and the runtime API.

## Runtime API

```js
window.QuokkaPixAgent.getContract()
window.QuokkaPixAgent.getState()
window.QuokkaPixAgent.applySettings(payload)
window.QuokkaPixAgent.buildUrl(payload)
window.QuokkaPixAgent.start()
window.QuokkaPixAgent.cancel()
window.QuokkaPixAgent.clear()
window.QuokkaPixAgent.getPaymentPolicy()
window.QuokkaPixAgent.setUnlockToken(token)
window.QuokkaPixAgent.verifyUnlockToken()
window.QuokkaPixAgent.clearUnlockToken()
window.QuokkaPixAgent.getEvents()
window.QuokkaPixAgent.clearEvents()
```

## Experimental WebMCP

QuokkaPix also registers draft WebMCP tools when the browser exposes `document.modelContext.registerTool`. This is an experimental browser-native layer, not a server MCP endpoint.

Registered tool names:

- `quokkapix.get_contract`
- `quokkapix.get_state`
- `quokkapix.get_payment_policy`
- `quokkapix.apply_settings`
- `quokkapix.set_unlock_token`
- `quokkapix.start`
- `quokkapix.cancel`

If WebMCP is unavailable, use `window.QuokkaPixAgent` and stable `data-agent` selectors. Image files still must be supplied through the browser file input or dropzone.

## Agent Payments

Human UI, reward ads and normal user workflows are unchanged. Agent payments apply only when the page is used in `agent=1` mode.

- Single image agent run: free.
- Single image scenario: free.
- Agent batch or batch scenario up to 50 files: `0.01 USDC`.
- No extra charge for background removal; image processing still happens in the user's browser.
- Payment provider: Coinbase x402.
- Payment options endpoint: `/api/agent-payment/options`.
- Paid unlock endpoint: `/api/agent-unlock/coinbase-x402`.
- Verify endpoint: `/api/agent-unlock/verify`.

Paid workflow:

1. Read `window.QuokkaPixAgent.getPaymentPolicy()` or fetch `/api/agent-payment/options`.
2. Call one paid unlock endpoint with an x402-capable client.
3. Read `unlockToken` from the paid JSON response.
4. Open the editor in `/#agent=1`, upload files through the browser file input, then call `window.QuokkaPixAgent.setUnlockToken(unlockToken)`.
5. Optional: call `window.QuokkaPixAgent.verifyUnlockToken()` to check the token without consuming it.
6. Start processing. The paid unlock is consumed only when the agent starts a paid batch/scenario run.

## Workflow

1. Navigate to `https://quokkapix.com/#agent=1` with the desired hash parameters, or call `window.QuokkaPixAgent.applySettings(...)`.
2. Upload image files through `[data-agent="file-picker"]`.
3. Wait for `.page-shell[data-agent-status="ready"]`.
4. Start with `window.QuokkaPixAgent.start()` or `[data-agent="process-trigger"]`.
5. Poll `.page-shell[data-process-status]` or `window.QuokkaPixAgent.getState()`.
6. Wait for one of: `done`, `error`, `cancelled`.
7. Download from `[data-agent="download-link"][data-status="ready"]` or `[data-agent="zip-download-link"][data-status="ready"]`.

## Status Values

- `waiting-for-files`: no image is selected.
- `ready`: files and settings are ready.
- `processing`: processing is running.
- `success`: `data-process-status` alias for completed output.
- `done`: `data-agent-status` value for completed output.
- `cancelled`: processing was cancelled.
- `blocked`: current settings cannot start.
- `error`: processing failed.

## Capabilities

Agents should call `window.QuokkaPixAgent.getState().capabilities` before choosing formats or workflows. Capabilities include supported output formats, worker support, HEIC worker availability, cancellation support, background model status, GIF limitations and file limits.

## Important Limitations

- Files cannot be provided by local path in URL parameters.
- Background removal does not support GIF input.
- Output AVIF/WebP availability depends on the current browser.
- Agent batch runs require a valid paid unlock token instead of the human reward ad flow.
- There is no server-side processing API to call directly.