# Mockup

Browser-based visual review for Pi.

The `mockup` tool presents one to four HTML-fragment options, collects selections, notes, and annotations, and keeps one browser page across uninterrupted iterations.
Its tool row exposes the active URL and uses Pi's native Ctrl+O and click expansion.

Before creating or revising fragments, agents load the registered [HTML guidance skill](guidance/mockup-html/SKILL.md).
The skill defines the ShadowRoot runtime, interaction support, target fidelity, accessibility, and network assumptions.

Accepted and interrupted iterations are cached under the platform-native Pi cache directory.
The tool never writes project files.

## Settings

`mockup.openBrowser` (boolean, default `true`) controls whether the browser lane opens the review page automatically.
When off, the tool still serves the page and shows its URL.
Set it in `~/.pi/agent/settings.json` or `.pi/settings.json` as `{ "mockup": { "openBrowser": false } }`.

`PI_MOCKUP_NO_OPEN` overrides settings with inverted meaning: `1` or `true` disables opening, `0` or `false` enables it.
There is no CLI flag.

Precedence: `PI_MOCKUP_NO_OPEN`, trusted project settings, user settings, default.
Project settings are ignored until the project is trusted.
The setting is resolved on every browser-lane execution.

Settings files accept only JSON booleans.
An invalid value from any source raises a warning, is not replaced by a lower-priority source, and keeps the browser closed for that run.
Tests never open a browser when `NODE_ENV=test` or `VITEST` is set.

## Debugging

Opt-in metadata-only tracing follows [debug contract](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `runtime.load.start`, `runtime.load.finish`, `runtime.load.error`.