← Back to Preview Deck

AI agents

Operate Preview Deck from a coding agent. Full-document mutations, async jobs, a human review handoff.

The handoff URL

Every successful agent job returns a handoffUrl shaped like:

/project/<projectId>?aiRun=<jobId>&documentVersion=<n>

Open it in a browser to inspect the run. The editor:

  • Loads the project at the produced documentVersion.
  • Highlights the AI: <label> entry in the project history so you can revert with one click.
  • Surfaces the diff summary (counts of added/updated/removed screenshots, frames, overlays, etc).

Reviewing

  1. Click through every family the project ships to.
  2. Use the project's history panel to compare against the previous version.
  3. If anything is off, give the agent feedback in plain text. The agent will refetch the latest document before mutating again — your manual edits are preserved.

Concurrency expectations

The agent enforces optimistic concurrency via baseDocumentVersion. If the document changed between the agent's read and write (you opened the editor and edited in parallel, or another agent ran), the second write returns 409 revision_conflict. The skill instructs agents to refetch and retry — your edits stay intact.

What to do after feedback

  1. Tell the agent what to change.
  2. The agent refetches via GET /document.
  3. The agent submits a fresh job. The cumulative diff makes one new history entry; the previous AI run remains intact above it.
  4. You review the new handoffUrl and repeat.

Destructive edits

Removing screenshots, families, or layers is gated by an explicit allowDestructive: true flag on the job request. Without it, the API returns 409 destructive_change_denied. The skill instructs agents to ALWAYS confirm with you before resubmitting with the flag.