Mockup review

Mockup review gates visual implementation on human sign-off. Use it for UI work — layouts, components, or whole screens — before writing the real code.

Flow

1. Keep HTML in memory or under ~/.diffing/ only — never write mockup files into the consumer repo
2. submit → share mockup URL → park (async default)
3. Human reviews at /mockup/<id> at desktop/tablet/mobile, pins comments, Submit review
4. Agent inspects open comments → patches one screen → batch replies/resolves

Comment scope

Every comment is scoped to version + screen + viewport (desktop | tablet | mobile — the layout width at click time; legacy comments anchor on desktop). Handoff XML, inspect filters, and the UI all use the same scope, so a comment is only addressed in the exact view where it was written.

CLI

diffing mockup submit - [--title T] [--id ID] [--model M] [--screen id=path]... [--wait]
diffing mockup await [--timeout 570]          # sync / resume
diffing mockup list|show|versions
diffing mockup inspect <summary|comments|comment|screen|preview> [<id>] [--status open] [--screen S] [--viewport V] [--version N] [--context none|anchor|source]
diffing mockup apply-suggestion <comment-id> [--expected-version N]
diffing mockup screen <upsert|remove|patch|replace-region> <id> <screen-id> [--file P|--text T --region R --replacement R] [--expected-version N]
diffing mockup threads <reply|edit|delete|resolve|unresolve> <comment-id> [<reply-id>] [--body "…"] [--model M]

• inspect — compact, paginated reads; context=anchor (default) adds locator fields, source adds contextHtml/full screen html. Filter comments by status/screen/viewport/version; bodies truncate at 400 chars.
• screen — one-screen upsert / remove / exact-text patch. Each success bumps the version; --expected-version N aborts with 409 on conflict (nothing applied).
• threads — atomic batch: all ops validated before any applies, all-or-nothing, never bumps the version. Prefer for multi-op replies.

Efficient agent recipe

diffing mockup inspect comments <id> --status open              # 1. open threads
diffing mockup inspect screen <id> --screen main --context source  # 2. exact source of one screen
diffing mockup screen patch <id> main --text '<h1>Old</h1>' --replacement '<h1>New</h1>' --expected-version 3  # 3. patch one screen
diffing mockup threads reply <c1> --body "fixed" --model "…"    # 4. batch reply/resolve
diffing mockup threads resolve <c1>

Resubmit full revisions with the same --id so history stays one conversation.

MCP

submit_mockup, await_mockup_review, list_mockups, get_mockup, get_mockup_versions, get_mockup_version — plus the redesign’s preferred tools:

Tool	Purpose
inspect_mockup	Bounded reads (view=summary/comments/comment/screen/preview, filters by status/screenId/viewport/version, `context=none
revise_mockup	One-screen op=upsert/remove/patch/replace-region with expectedVersion guard
update_mockup_threads	Atomic thread batch (reply/edit/delete/resolve/unresolve)
unresolve_mockup_comment	Re-open a resolved thread
apply_mockup_suggestion	Apply a ```suggestion fence to that comment’s screen
get_mockup_handoff	Compact implementation packet after approved
get_design_system	Read tokens/guidelines before authoring

Verdicts

Decision	Agent action
approved	Implement the reviewed mockup; account for open comments
changes-requested	Do not implement. Revise the HTML, batch-reply + resolve addressed threads, resubmit same mockupId
rejected	Stop. Do not implement
comment-only	Reply only; do not edit product files
pending	Park (async) or one sync await if asked

Handoff XML

The default <mockup-review> is compact and open-only: open comments on the current version only, terse attrs, no instruction block, no markup payload. Each <comment> carries kind="section|block|point", screen="<id>", mockup-version="<n>", viewport="…", and its anchor fields. x=/y=/rect are viewport-relative and not stable across screens or viewport sizes — pull the markup via inspect_mockup (context=source) or mockup inspect screen … --context source instead.

Comment anchors

section (a [data-diffing] region via target=), block (a computed selector= + section-relative fingerprint= that survives edits elsewhere), or point (x/y percent). Severity is the same triage as code review: blocking | nit | question | praise.

Mockup UI (human)

Feature	Behavior
Scope	Viewport toggle (desktop/tablet/mobile) + screen tabs with per-screen open counts; comments pinned only for the exact version+screen+viewport in view
Rails	Left list and right comments rail drag-resize (widths persisted); rail collapses to a bottom sheet on narrow windows
History	Header version switcher; read-only historical versions (comments disabled); rail shows an explicit prior-version unresolved group that jumps to that version
Threads	Collapsible cards, replies, edit/delete, resolve
Submit review	Approve / Request changes / Reject / Comment only; popover reports scoped vs total open counts; releases mockup await
Live edit	e opens a line-numbered HTML editor; autosave current version; Save as new version bumps; pencil disabled on historical versions
Apply suggestion	Thread Apply for ```suggestion fences (409 on version conflict)
Ask AI	Opt-in only. Rail starts closed. Comment chips, Generate this screen, Rewrite region, and Attach preview run on click. Opening the page never starts inference. --model on CLI is provenance.

Keep the tree clean

Never write mockup HTML or .diffing/ directories into the consumer project. Screens are mirrored to ~/.diffing/<repo>-<hash>/mockup-sources/<id>/; or submit from stdin:

cat mockup.html | diffing mockup submit --model "your-model"