Writing a spec

Three ways in, all producing the same reviewable YAML — and none of them ask you to invent a locator.

1. Click through it — playhead record

playhead record http://localhost:3000 -o demo.yaml

A browser opens. Use your app the way a person would: click the nav, fill the form, pick from the dropdown. Press Enter in the terminal when you are done, and Playhead hands you a spec of what you just did.

Each interaction becomes a step whose locator is read off the element you actually touched, then checked against the live page immediately. Clicking an icon inside a button records the button. Typing produces one step with the final value, not one per keystroke.

2. One command — playhead demo

playhead demo http://localhost:3000 "browse the catalog" -o out

Author, validate, render, open. With ANTHROPIC_API_KEY set, an agent drafts the steps toward your goal; without one, Playhead explores the app and scaffolds a grounded spec instead. Either way you end up with a spec you can edit.

3. Explore and write it yourself

playhead explore http://localhost:3000

Every addressable element on the current screen, as a locator that has been validated to resolve. Related controls are grouped under their toolbar, and containers that make good camera targets are listed separately:

## dialog
  — Canvas controls —
    ● [button] testid=graph-canvas-toolbar-fit
    ● [button] role=button[name="Zoom in"]
    ● [button] role=button[name="Zoom out"]

## focus targets (containers — use as focus: on a step)
  ● testid=graph-canvas-toolbar   (Canvas controls)

Explore reads through shadow DOM, so apps built from web components are fully addressable. It only ever describes the current screen — run it again after a navigation to see the next one.

Explore what the render will see

playhead explore https://app.example.com --spec demo.yaml

Without a spec, explore loads the page cold: signed out, cookie banner in the way. Pass --spec and it borrows the spec’s session, network rules and setup: steps first, so you catalog your app instead of the consent dialog.

Check before you render

playhead validate demo.yaml --fix

Validate walks the spec against the live app in one pass and reports every problem at once, with the nearest matching element as a suggestion. --fix applies the two kinds of fix a machine can be certain about — pinning an ambiguous locator with >> nth=0, and correcting an obvious typo — then re-validates to prove them. It declines to guess at anything else.