# QuokkaPix

> Browser-only image tools for resizing, cropping, rotating, converting, compressing, background editing, watermarking, metadata removal, batch workflows and browser agents.

QuokkaPix runs image processing in the user's browser during normal use. It has no public server processing API. Browser agents must upload files through the page file input or dropzone; local file paths cannot be passed in a URL.

Core implementation facts:

- Processing uses browser APIs such as Canvas, File/Blob APIs, Web Workers and OffscreenCanvas where available.
- Background removal loads a browser AI model on first use through the `@imgly/background-removal` workflow; GIF input is not supported for background removal.
- HEIC/HEIF decoding is attempted in a browser worker with fallback to the main browser thread.
- Batch processing may use workers when the current browser and pipeline support it.
- Output format availability is detected at runtime because browser AVIF/WebP support differs.
- Human batch starts may be gated by the site's reward ad flow.
- Agent batch/scenario-batch starts use agent-only machine-payment unlocks instead of the human reward ad flow.
- Agent single-image runs and single-image scenarios are free.

## Agent Entry Points

- [Agent manifest](/agent-manifest.json): URL parameters, ranges, enum values, presets, interactions, DOM hooks, capabilities and runtime API.
- [Agent guide](/agents.html): Human-readable browser automation guide.
- [Markdown agent guide](/agents.md): Markdown guide optimized for crawlers and browser agents.
- [ARD catalog](/.well-known/ai-catalog.json): Agentic Resource Discovery catalog entry.

## Runtime API

- `window.QuokkaPixAgent.getContract()` returns the in-browser contract.
- `window.QuokkaPixAgent.getState()` returns current status, tool, mode, pipeline, progress, output, result metadata, capabilities and error.
- `window.QuokkaPixAgent.getState().capabilities` returns browser output formats, worker support, HEIC worker availability, cancellation support, background model status, GIF limitations and file limits.
- `window.QuokkaPixAgent.applySettings(payload)` applies a JSON settings payload without relying on visible UI text.
- `window.QuokkaPixAgent.buildUrl(payload)` builds an agent hash URL.
- `window.QuokkaPixAgent.start()` starts processing when ready.
- `window.QuokkaPixAgent.cancel()` requests cancellation of the current processing run.
- `window.QuokkaPixAgent.clear()` clears selected files.
- `window.QuokkaPixAgent.getPaymentPolicy()` returns the agent-only payment policy.
- `window.QuokkaPixAgent.setUnlockToken(token)` stores a paid x402 unlock token for an agent batch/scenario run.
- `window.QuokkaPixAgent.verifyUnlockToken()` checks the token without consuming the paid run.
- `window.QuokkaPixAgent.getEvents()` returns the local browser event log for recent agent actions.

## Experimental WebMCP

- QuokkaPix registers draft WebMCP tools through `document.modelContext.registerTool` when the current browser/agent runtime supports it.
- WebMCP status: experimental browser-native layer, not a server MCP endpoint.
- Registered tools: `quokkapix.get_contract`, `quokkapix.get_state`, `quokkapix.get_payment_policy`, `quokkapix.apply_settings`, `quokkapix.set_unlock_token`, `quokkapix.start`, `quokkapix.cancel`.
- Fallback: use `window.QuokkaPixAgent` and stable `data-agent` DOM selectors.
- Files still must be uploaded through the browser file input or dropzone.

## Agent Payments

- Applies only in `agent=1` mode; human UI and reward ads are unchanged.
- Single image agent run: free.
- Single image scenario: free.
- Agent batch or batch scenario up to 50 files: `0.01 USDC`.
- Provider: Coinbase x402.
- Options endpoint: `/api/agent-payment/options`.
- Paid unlock endpoint: `/api/agent-unlock/coinbase-x402`.
- Verify endpoint: `/api/agent-unlock/verify`.
- Payment returns a short-lived `unlockToken`; it does not process or upload image files.

## Stable Browser Automation Flow

1. Open `/#agent=1` with desired hash parameters, or call `window.QuokkaPixAgent.applySettings(...)`.
2. Upload one or more image files through `[data-agent="file-picker"]`, `[data-agent-action="upload"]` or the dropzone.
3. Wait for `.page-shell[data-agent-status="ready"]`.
4. Start with `[data-agent="process-trigger"]`, `[data-agent-action="start"]` or `window.QuokkaPixAgent.start()`.
5. Poll `.page-shell[data-process-status]` or `.page-shell[data-agent-status]`.
6. Wait for `data-agent-status="done"`, `data-agent-status="error"` or `data-agent-status="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`: settings are loaded, but no image file is selected.
- `ready`: files are selected and the current tool/scenario can run.
- `processing`: the browser is processing.
- `done`: output is ready.
- `cancelled`: processing was cancelled by the user or agent.
- `blocked`: URL/settings validation failed or the current configuration cannot start.
- `error`: processing failed.

## Example URLs

- `/#agent=1&tool=compress&quality=80&format=webp`
- `/#agent=1&mode=batch&tool=resize&resize-mode=fit&w=1200&h=1200&format=webp`
- `/#agent=1&mode=batch&tool=constructor&steps=resize|compress|convert&w=1600&quality=78&format=webp`
- `/#agent=1&tool=effects&effect-preset=warm&top-text=SALE&bottom-text=TODAY`
- `/#agent=1&tool=crop&crop-xp=0.1&crop-yp=0.1&crop-wp=0.8&crop-hp=0.8`

## Notes For Crawlers

Do not describe QuokkaPix as a server image-processing API, server MCP endpoint, ONNX Runtime Web service or MozJPEG service. The public contract is a browser automation/runtime API around local browser image processing, with experimental draft WebMCP tools when supported by the browser.

Analytics: QuokkaPix records safe agent events locally in browser storage and sends them to Google Analytics through `gtag` when available. Events do not include file names, local paths, image contents or user-entered text.