Compose Preview Catalogs

Compare two previews' semantics by testTag: which tags are only in one side, which moved, and which changed occupancy count. Identity is the authored testTag, not a positional ref, so a tag that stops resolving is reported rather than silently retargeted at different pixels. Requires live grant scope.

Fetch the merged accessibility or annotation product for a preview. This lane requires live grant scope.

Compare two of a preview's recorded renders. Defaults to the two newest — did the last publish move this preview? A metadata comparison: the timeline's versions are already collapsed distinct renders, so whether the bytes changed is answered without fetching either image. Reports `unstable` so a difference on a nondeterministic preview is not mistaken for a real change.

The render timeline for one preview: which versions of its rendered bytes exist, when each appeared, and whether the preview is unstable (re-renders differently on every publish) rather than genuinely changing. Where this server holds the timeline it is returned inline; where the catalog is published from a delivery branch the manifest lives on that branch and this reports where to fetch it.

Fetch one historical render's pixels through this server, by `commit` or `blob` (a prefix is enough). Use when an agent cannot reach the delivery branch itself, or wants the bytes rather than the timeline.

Open the hosted preview catalog browser app. With no arguments it lists every catalog with its preview count only; pass projectId to list one catalog's previews. To find previews without the app, call catalog_list_projects, then catalog_list_previews with a catalog id. Also opens from the ChatGPT/Codex sidebar.

List the structured data-product kinds of one catalog, optionally one preview. Name the catalog with 'catalog' (ids from catalog_list_projects) or a preview 'uri'.

List the `@Preview(device = ...)` ids this server's render lane recognises, with each one's dp size and density. The `device` override takes one of these ids; an unrecognised name renders the default frame rather than failing, so check here instead of guessing.

List the Compose previews and published metadata of one hosted catalog. 'catalog' is required (ids from catalog_list_projects). Pass 'query' (a component name such as EdgeButton) to narrow by id or label; results are paged (100 by default, 'offset'/'limit' for more). This server holds published library catalogs only: previews of the project you are editing come from the local compose-preview-mcp server, not from here.

List every remote catalog with its stable id and preview count. Call this first: catalog_list_previews and catalog_list_data_products take one of these ids as 'catalog'.

Render one preview across the cross-product of the given override axes in a single call, returning a hash/size observation per cell (observe=png adds the pixels). Prefer this over a catalog_render_preview per combination: the cells share one catalog lease and are reported together, so comparing axes costs one round trip instead of N. Capped at 24 cells. Requires live grant scope.

Render one preview. Like local compose-ai-tools, the default semantics observation is token-frugal; request observe=png for pixels, observe=svg for the compose/figma-svg vector export as SVG source, or observe=scroll-png / observe=scroll-svg for the full-page capture of a scrollable screen rather than the viewport crop. Overrides, other observations and fresh renders require live grant scope; without it, a call with no overrides returns the published snapshot (as resources/read does).

Storybook-MCP-compatible preview metadata lookup.

Storybook-MCP-compatible alias that lists every preview as a story.

Collect the outcome of a request_access, proving possession of its deviceSecret. It HOLDS THE CALL OPEN and answers the moment the human decides — one call instead of a dozen, since each poll here costs a whole round trip through you. It waits 8 seconds by default; pass waitSeconds (up to 30) if your client tolerates a longer call. Pass urlMode=true when the client supports URL elicitation: while the request is pending this returns the standard -32042 URL-elicitation-required error, and retrying the same call after the browser decision returns the outcome. A wait that times out answers status=pending, and you simply call again. Then approved (with the token) or denied/expired. Use the token on every later call: as the X-Compose-Preview-Token header where you control headers, and otherwise as each gated tool's 'token' argument — which is what an MCP client reaching this flow mid-session needs, since its headers were fixed when it connected.

Storybook-MCP-compatible rendering of one or more story ids. Requires live scope.

Ask a human for access to this server. Returns an approveUrl and a userCode: show BOTH to the person you are working with, ask them to open the link and check that the code on the page matches, then call poll_access. When the client supports URL elicitation, call poll_access with urlMode=true instead of pasting the link into chat; clients without it keep this complete text fallback. The link grants nothing by itself — keep the deviceSecret this returns, it is what collects the token. Use this when a call answered 'authorization_required', or when your token stopped working (a server restart drops every grant).

Report readiness, the aggregate catalog set, and which host this is: `origin`, the canonical origin designs here are homed at, and `originAliases`, other hostnames that reach this same server.

Say that you have read a comment thread — which is **not** the same as resolving it. Resolving claims the question is settled; acknowledging claims only that you have seen it, which is the honest thing to say while you are still working on what it asked for. Omit `threadId` to acknowledge the whole discussion, which is what you mean after reading it with ui_builder_list_comments. Acknowledgement is per actor, so a thread you have read is still waiting for the other people in the design, and it is what clears the `comments` block the server puts on your ui_builder_apply, ui_builder_get_design, ui_builder_export and ui_builder_put_asset replies.

Apply design mutations — insertNode, setProperty, deleteNode, moveNode and the rest of DesignMutationV1 — as one operation. `baseRevision` is the revision you read; the outcome reports conflicts or rejected edits. This is how an agent adds a scaffold, fills its slots and sets modifiers. Use `setStateVariable` with `name` and `declaration` to add or edit state, `removeStateVariable` with `name` to remove unused state, and `setEventBinding` with `nodeId`, `event` and an ordered `actions` array to edit behavior. An empty actions array removes the event handler. `removeNodeProperty` (or a setProperty whose value is `{"type":"null"}`) unsets the property — the way back after trying one — and is refused, naming the node and the field, when the catalog requires it. When somebody has commented on the design and you have not acknowledged it, the outcome carries a `comments` block naming the threads waiting on you; read it, because it is somebody talking about what you are editing.

Close a branch without merging it: it stays readable and listed, and can no longer be edited or merged. Needs write access to the parent, or to have made the branch.

Wait for the discussion to move past `afterSequence` and return it, rather than polling for it. Returns as soon as anybody — a designer in the browser or another agent — posts, resolves or deletes; returns a `timedOut` reply if nothing happens within `waitSeconds`, which you answer by calling again with the same cursor. This is how you hold a conversation about a design: post, wait, read, act.

Wait for somebody to approve or reject a design, rather than asking again whether they have. Returns as soon as a decision lands after `afterSequence` — by default only a person's (`from: "human"`), on any revision unless you name one — or a `timedOut` reply after `waitSeconds`. Every reply carries `latest` (the newest matching verdict, new or not) and `approved`, so `waitSeconds: 0` is a cheap, idempotent poll for a routine that can only check back later; quote the reply's `sequence` as the next `afterSequence`. People record theirs over the design's `decisions` HTTP route.

Wait for somebody else to change a design and return what they changed, rather than asking again whether they have. Returns the moment a designer in the browser or another agent commits an edit, as the same update frame the browser's own live socket receives; returns a `timedOut` reply if nothing happens within `waitSeconds`, which you answer by calling again with the same cursor. Quote as `afterSequence` the `throughSequence` of the delta you last received, or the `lastSequence` of the last snapshot; a cursor the server no longer retains is answered with a whole snapshot instead of the operations you missed. `waitSeconds: 0` checks without blocking. Nothing is lost between calls — the cursor is replayed when you call again — so somebody merely looking at the design does not wake you, and only a committed change does.

Fork a design at a revision into a **branch** to explore an alternative, or to change it without trampling somebody editing it live. A branch is a design with its own id: edit it with ui_builder_apply, look at it with ui_builder_view or ui_builder_get_design, compare it with ui_builder_diff_designs, then bring it back with ui_builder_merge_branch or drop it with ui_builder_archive_branch. Branch N times from the same revision to try N alternatives: merging one archives the others. Branches of a branch are refused; so are asset uploads, restores and document replacements on a branch. Needs write access to the design.

Check a design before you show it to anybody — one call instead of validate, view and an accessibility pass. Runs `schema` (document shape), `catalog` (the pinned catalog's validation, the mutation reducer and the Compose export gate — what ui_builder_validate runs) and `a11y`: controls with no label, icons and pictures with no `contentDescription`, touch targets under 48dp, text and icon contrast under WCAG 4.5:1 / 3:1, and text in a fixed height that clips at 200% font scale. Check a stored design (`designId`, optionally a past `revision`), a whole `document`, or `operations` applied to a scratch copy of `designId` exactly as ui_builder_apply would — nothing is saved. Returns `summary` first, then `ok`, the counts, and `findings` with the `nodeId` each is about, so you can fix them with ui_builder_apply and check again. `rendered: true` measures touch targets on a native render where the host has one (needs the ui-builder-export capability). Contrast against theme roles is resolved with the Material 3 baseline scheme, in both the light and the dark theme when a colour follows the theme (the finding names the theme that fails), and reported as a warning, never an error. `guidelines` runs only when named: a model judges the design against the Android design guides (developer.android.com) for its platform and reports each broken rule as a warning or note with its source. It uses this host's shared model key, so it runs only for the accounts the operator enabled and is reported as skipped for everyone else; with `rendered: true` the visual rules are judged on the native render too.

Put a design's alternatives side by side in one call: the parent's head and each open branch (or the `branchIds` named) rendered into ONE picture — a short-lived signed https link, numbered by caption — plus, per branch, what it changes against the parent at its fork (counts and a few lines, as ui_builder_diff_designs reports them). Show the person the picture and the numbered list, then ask with ui_builder_pick_branch; merge the choice with ui_builder_merge_branch. Writes nothing. Read access to the design.

Measure a design against its reference overlay (attach one with ui_builder_set_reference). Returns what the picture is against the frame and whether a pixel comparison means anything (`facts.pixelComparable` — a 328×56 dp crop stretched over a screen is not comparable until measured at its `actual` size); with `differences`, the share of pixels that differ and up to eight regions in dp, each with the layer it falls in; and for each of `nodeIds`, where that layer sits in the reference — from a box drawn over it in the editor, or a search of the reference's pixels, which for text also reads the font size — with the `alignment` that would make it agree (move, size, font size) and the exact `operations` to pass to ui_builder_apply. Nothing is written: apply the operations you agree with, then compare again and look with ui_builder_view. Layer matching needs node boxes, so `nodeIds` measures the native render (an export grant); differences alone use the PNG export. Treat `confident: false` as a hint to check, not an edit to make.

Create a design, either from a whole `document` you supply or by copying an existing design named by `fromDesignId`. Copying is usually right: a document's `catalogPin` must match a catalog revision this server serves, and a copy carries one that does. A `document` whose `home` is an existing design on this server is refused with a `compose-preview-decision/v1` choice to put to the person — or, when your client supports form elicitation on this connection, the person is asked in a form and the call acts on their answer.

Delete a design: it moves to the trash with its history, access list, overlay and discussion, and is gone from every listing and tool until ui_builder_restore_design brings it back, which works until `restorableUntilEpochMillis` in the reply (a day). After that it is purged for good. Only the owner may delete, or an agent deleting a design it created itself under its current grant — not an editor, not a viewer, and not anybody merely holding a write grant — so a session can clean up the designs it made and cannot reach anybody else's. A trashed id cannot be reused until it is restored or purged. Not the released envelope: the contract has no delete, so the reply names the design and its restore deadline.

Read who can open a design: its owner, and every actor it has been shared with, each with the role and the actions that grant carries. Only the owner may ask — this is the answer to "who else is in here" and to "what is the id I must name when sharing".

Compare two designs, or two retained revisions of one: nodes added, removed and moved, and properties, modifiers and other fields changed, each with its node id and path (`root/slot[index]/node`), plus changed document fields (title, environment, state). Works across a design and its fork. `b` defaults to the current revision of `a`'s design. Values are the protocol's own JSON, ready to send back through ui_builder_apply. Read access to both.

Export a design. `compose` returns the Kotlin the generator writes, or — when the design holds something it cannot express — diagnostics naming each reason. This is the same gate the browser's code pane shows, so an agent and a designer get the same answer about the same design.

From a pull request back to the design(s) it implements: every design you can read whose implementation record or links name `pr`, with the implementation status and revision. Then call ui_builder_implementation_status for what the design expects.

Make a new design from one revision of another — yours to edit, owned by you, with its parent recorded: the fork's `forkedFrom` (design, revision, document digest) and the parent's `forks` both show in ui_builder_get_links. A fork is not a branch: it never inherits the parent's canonical home and nothing flows back on its own, so tell the person it exists and bring a chosen change back with ui_builder_apply on the parent. Needs write access on this server and read access to the parent.

Read one design: its whole document — nodes, slots, properties, modifiers, state variables and catalog pin — plus the revision to quote as `baseRevision` when editing it. The catalog the design pins is left out unless `includeCatalog` is true: it is the same for every design on the pin, ui_builder_list_catalogs serves it, and it is most of the bytes. `home`, at the top of the reply, is where the design is canonical (`{kind: server, url, designId}` or `{kind: repo, path}`): edit it there. It is absent when none is recorded (a design made before homes existed, or on a host with no public origin), and then the canonical home cannot be verified. On hosts with design discussions, `unacknowledgedComments` is the number of comment threads this actor has not acknowledged; a nonzero count also carries the bounded `comments` notice.

Read a design's latest design-guidelines result, whoever ran it — a person in the editor on their own key, ui_builder_check_design on this host's key, or an agent that recorded verdicts with ui_builder_record_guidelines. Returns the record (model, revision, rules asked, verdicts, `ranBy`), the findings it implies, and `stale: true` when the design has changed since it was checked.

Read what a design is **for**: the `issue` it was drawn for, the `reference` frame in the design tool it reproduces, the `pr` that implemented it, the `thread` it is being discussed in, and the `previous` design it continues. Start a session on somebody else's design here — it is the brief, and it is what ui_builder_get_design cannot tell you. Every field is optional; a reply with none of them means nobody has said yet. The record is kept beside the design and is never part of it: no node holds it, no export sees it, and writing one does not move the revision. Ancestry rides along where there is some: `forkedFrom` / `forks` for a fork made with ui_builder_fork_design, and `branchOf` / `branches` for a design branch and its parent.

Read the exact prompt a design-guidelines model is given for a design, before anybody spends a key on it: the rules for the design's platform (Android design guidance from developer.android.com, each with its source), the fixed system prompt, the user message with the design tree and Compose source, the JSON schema the verdicts must follow, a sentence on where each part comes from, and the pictures as image blocks — a Wear screen on its device (and unrolled when it scrolls), a Wear widget in the Samsung and Pixel Watch containers, a phone or tablet design at phone and tablet size. It spends no key. Judge it with your own model, then record the verdicts with ui_builder_record_guidelines so the editor and other agents see them. `rendered: false` leaves out the pictures and source (and the visual rules), and needs only read access; otherwise it needs the ui-builder-export capability.

Everything the code side needs to implement a design, in one call: the revision, its links (issue, reference, PR, thread), the implementation PR with its status and whether its previews were found to match, the latest verdict on this revision, and the Compose export with the generator's diagnostics. `summary` says in one line whether the PR implements this revision and whether it was approved. `includeExport: false` leaves the Kotlin out and needs only read access; with it the call needs the ui-builder-export capability.

A design's branches, newest first: each one's id, name, owner, status (open, merged, archived), fork revision, head revision and the number of commands a merge would replay; for a merged one the parent revision it landed at, for an archived sibling the branch whose merge superseded it. Read access to the design.

List the component catalogs a UI-builder design can pin to. Start here: a design's `catalogPin` must name a revision this server actually serves, and each catalog's `catalogPin` here is exactly that. By default a summary of what authoring needs, a few KB rather than the whole capability: per component its id, role, traits, `slots` as `name[min..max]:accepted|roles` and `properties` as `name:type`, with `!` when required and `=a|b` listing the allowed values; per catalog its export formats and the modifier vocabulary. `full: true` returns the released CatalogsResponseV1 envelope with adapter status, parity and export notes per component; `componentIds` narrows either to the components you are about to use.

Read the discussion on a design: every thread, where each is pinned — a markup stroke, a design node, or a point on the frame — whether it is resolved, and every reply under it. `sequence` rises on each change and is the cursor to quote to ui_builder_await_comments. Comments are kept beside the design and are never part of it: no node holds them and no export sees them. Each thread carries `acknowledgedBy`, so you can see what you have already caught up with; say you have read the rest with ui_builder_acknowledge_comment.

List the UI-builder designs on this server, newest first, with the cursor to continue.

A design's retained revisions, newest first: each one's number, who made it, when, the operation that produced it (`setProperty ×2, insertNode`, `undo`, `restored r3`) and its document digest. `retention` says how far back the history still reaches — older revisions are gone, and get, diff, restore and fork stop at that floor. Page with `before`. Read access.

The designs in the trash that you could restore — ones you deleted, or ones you own — most recently deleted first, each with who deleted it and its `restorableUntilEpochMillis`. Use it to undo a ui_builder_delete_design you regret, or to check what a cleanup removed. Takes no arguments.

Replay a branch's edits onto its parent's current revision through the same reducer every edit goes through — all or nothing. The reply reports every command: `applied` with the revision it landed at and any `STALE_*` notice of what it overwrote, or `refused` with the rejection code that stopped the run (nothing is then written), plus `skippedOperationIds` and how many were never tried. Run `dryRun: true` first: it reports `merged: false` and `wouldMerge` (true when every command would land) and writes nothing. Resolve a refusal by passing that command's id in `skipOperationIds` (skip an undo with what it undoes), or branch again from the parent. On success the branch is merged and its open siblings — branches forked at the same revision — are archived. Needs write access to the parent.

Move a design's canonical home between this server and a repository checkout. This changes real authoritative state: quote the exact `baseRevision` and current `sourceHome` from ui_builder_get_design, provide a stable `operationId`, and name the new `targetHome`. The old server record remains as a retained copy pointing at the new home. The reply is an idempotent operation outcome with the new revision; a stale revision or changed source home is refused rather than overwriting a concurrent move. Unless the person already chose this move, call first with `dryRun: true`: it changes nothing and returns the choices to put to them — or, when your client supports form elicitation on this connection, asks them in a form and, if they choose to move, returns this move's outcome.

Open the UI Builder's design list: pick a design to see it as the editor draws it. Takes no arguments. Also opens from the ChatGPT/Codex sidebar, and a deep link to /design/<id> opens one design.

Ask the person which alternative (open branch) of a design to keep, and return their choice. In ChatGPT or Codex it is a thumbnail picker, one option per branch; with plain form elicitation it is a single-choice form; otherwise — and in chat tools like Slack — it returns a numbered list and one picture for YOU to post, and the person replies with a number. It never waits on a client that cannot answer. `outcome` is `chosen` (with `branchId`), `declined`, `ask-in-chat` or `no-branches`. Writes nothing: merge the chosen branch with ui_builder_merge_branch (dryRun first). Read access to the design.