Compose Preview Catalogs

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.

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. 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.

Say something on a design — a reply into `threadId`, or a new thread when it is omitted. Pin a new thread with `markId` (a stroke on the reference overlay), `nodeId` (a node in the design), or `x`/`y` in frame fractions, so the person reading it can see what you meant. The comment is attributed to your own grant; you cannot post as somebody else.

Dry-run recovery of a design whose stored catalog pin no longer resolves. The server selects the exact currently served pin for the same catalog system and returns a CatalogUpgradePreviewV1 with changes, issues and the hashes required by a later `upgradeCatalog` mutation through ui_builder_apply. This call never writes.

Put a picture behind an `assetKey`, so an `asset/image` node naming that key draws it instead of a placeholder. Send the PNG, JPEG, GIF or WebP bytes base64-encoded in `imageBase64`; the server stores them by content digest and pins {mediaType, contentDigest, source: uploaded} into the design's `assets` map under the key. This moves the design's revision, and the reply carries the new one to quote as `baseRevision`. Idempotent by content — the same bytes under the same key change nothing. Put the picture first, then insert the `asset/image` node with ui_builder_apply: the reducer refuses a key that is neither pinned in the design nor in the catalog's own registry. A pinned key whose bytes a lane cannot show renders as a visible placeholder, never as an error.

React to one comment with an emoji, or take the reaction back with `on: false`. The lightest thing you can say: 👀 on a comment you have just picked up, 👍 on a fix somebody made, where a reply would be noise in a thread a person has to read. `commentId` is the `id` of a comment inside a thread, from ui_builder_list_comments. Reacting also acknowledges that thread for you, so it counts as the lightest acknowledgement; it says nothing about whether the question is settled.

Record a review verdict — `approve` or `reject` — on one revision of a design, with an optional note. Kept beside the design, like comments: it never moves the revision. Recorded as an agent's decision, so a person waiting with ui_builder_await_decision's default `from: "human"` is not answered by it. Pass your own `decisionId` to make a retry idempotent.

Record your own model's verdicts on ui_builder_guidelines_prompt as the design's latest design-guidelines result, so the editor's Issues panel and other agents show them. Pass the `revision` and rule ids the prompt asked (`rules.asked[].id`), and one verdict per rule you answered: `pass`, `fail` or `not_applicable`, with `confidence` 0..1, the `nodeIds` it is about and a one-sentence `reason`. `ranBy` is taken from your credential. Returns what ui_builder_get_guidelines returns.

Give a design a new title. The title is the one thing about a design nothing else could change: it is set at creation, shown in every listing and the editor, and not part of any mutation. Anybody who may write the design may rename it. The revision does not move — a title is not design content — so `baseRevision` is not needed and an edit in flight is unaffected. Not the released envelope: the contract has no rename, so the reply is the design's listing entry with its new title.

See one design on several devices in ONE picture: a contact sheet with a captioned cell per device × theme × font scale, plus each cell's device, size and box on the sheet. Nothing is saved — the design's environment is swapped on a scratch copy for each cell. Name `devices` by preset (phone_small, phone, phone_landscape, foldable_folded, foldable_unfolded, tablet_portrait, tablet_landscape, wear_small_round, wear_large_round, wear_square, tv_1080p) or as {widthDp, heightDp, label?, round?}; or a `formFactor` (phone, foldable, tablet, wear, tv, adaptive) for its default set; with neither you get the design's own form factor — phone, foldable and tablet for a mobile catalog, the round watches for Wear. Add `themes: ["light","dark"]` and `fontScales: [1, 2]` to cross them; at most 16 cells. The sheet is a short-lived signed https link kept under 3.5 MB, so a chat surface can show it inline; `inline: true` puts the bytes in the reply as well.

Compile a design and render it with real Compose on this host, rather than in the browser's Wasm canvas — the way to see what a design looks like on Android. Returns the first frame, the token the live frame stream is opened with, and the design node ids the render is tagged with, so `catalog_get_preview_data` can report each node's bounds and a client can put selectable regions over the image. This host has a native render lane. The reply is not an McpResponseEnvelopeV1: the released contract defines no request type for a native render.

Replace one stored design from a complete DesignDocumentV1 copy — the authoritative save-back and re-import operation. The document must name the same design and the same canonical home you read from ui_builder_get_design; `baseRevision` must still be current. The runtime validates the complete document and quotas, preserves server-owned identity, access and creation time, retains the old revision, and broadcasts a whole snapshot. Retry with the same `operationId`; never invent a new id after a lost response. Unless the person already chose to save back or re-import onto this home, 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 returns the outcome of the write they chose.

Close a comment thread once it is answered, or reopen one by passing `resolved: false`. The resolution is attributed to you and is reversible.

Make a retained revision the design's current content again, **forward**: it is committed as a new revision and nothing after it is lost, so a restore is undone by restoring again. `baseRevision` must be the current revision (a restore that raced an edit is refused as stale). `dryRun: true` writes nothing and returns the diff the restore would apply. Needs write access to the design.

Find catalog components by name, role or trait (case-insensitive substring), e.g. `TextField`, `Button`, `Card`. Returns the same summary as ui_builder_list_catalogs (id, role, traits, slots, properties, and the catalog pin) for only the matches, so you don't pay for the whole catalog.

Record the pull request that implements a design: its URL, its `status` (draft, open, merged, closed), the design `revision` it implements, and — once you have compared the PR's rendered previews with the design — `previewMatch` {status: match|mismatch|unknown, evidence: a URL to the comparison, note}. Replaces the whole record; pass only `designId` to clear it. Writing the same record again changes nothing and wakes nobody. Needs write access to the design.

Say what a design is for. **Replaces the whole record**: send every link you want kept, and omit one to clear it — so read ui_builder_get_links first if you are adding to what is already there. `issue`, `reference`, `pr` and `thread` are absolute http or https URLs, at most 2 KB each; `previous` is a design id on this host, not a URL. Anything else is refused with the reason. Sending an empty record clears it. Record the `pr` when you open one for a design you built here: it is what lets the next session, and the person who filed the issue, find one from the other.

Attach the picture a design is being built against — a Figma frame, a screenshot of a shipped screen, a mock — as its reference overlay, or `clear` it. The same overlay the browser editor's Frame, density and reference panel shows, so a person opening the design sees what you attached. Kept beside the design and never part of it: no node holds it, no export sees it, the revision does not move. Send PNG, JPEG, WebP or SVG bytes in `imageBase64`. For a Figma frame, fetch the picture with your Figma tools (a screenshot of the node) and pass the frame's URL as `sourceUrl`; this host fetches nothing itself. State the export scale as `density` (2 for a Figma 2x export) or in the name (`card@2x.png`): without it a screen-shaped picture is read across the frame's width and anything else at the design's own density. The reply says what the picture is against the frame — size in dp, density, whether it is a screen or a region — and whether pixel comparison means anything. Marks drawn in the editor are kept; the alignment is reset, as a new picture in the editor does. A user-supplied image is stored on this host: say so, and attach it only with their permission.

Share a design with somebody else, or take that sharing back. `actorId` is the other party's actor id as this server spells it — `github:<login>` for a signed-in person, `operator` for the token holder, `agent:<fingerprint>` for another agent's grant; ui_builder_design_access lists the ones a design already carries. A `viewer` may read and export, an `editor` may also change the design, and neither may share it on. Only the design's owner may share it, and an agent acting under an approved grant shares as the person who approved that grant. Pass visibility instead of actorId to choose private or public (read only). Private keeps existing invited collaborators.

Check a design without saving it: a whole `document`, a stored design by `designId`, or `operations` against a stored design exactly as ui_builder_apply would apply them. Runs the same checks the real call does — document shape, catalog pin, the catalog's own validation, the mutation reducer — and then the Compose export gate, which is the list the editor's problems panel shows. Returns `{valid, problems:[{severity, source, code, message, nodeId?, field?, operationIndex?}]}`; `valid` is false exactly when a problem is an error. Nothing is written, no revision moves and nobody watching the design is notified. The shapes are published as the resources compose-preview://schemas/ui-builder-document-v1.json and compose-preview://schemas/design-mutation-v1.json.

See a design the way a person in the editor sees it: a PNG of the canvas with the overlays drawn on — the `selection` outline, the `reference` picture when one is attached, the discussion's `comments` pins, and the layout `bounds` — and beside it JSON with the revision, each visible node's id and box, each pin's thread and position, all in the returned image's pixels. The picture is a short-lived signed https link by default; `inline: true` puts the bytes in the reply as well. The frame is the PNG export (`renderer: "export"`, the editor's own renderer), which reports no node boxes; `renderer: "native"` draws real Compose on a host with a native render lane, reports every node's box so the selection can be outlined, and needs the ui-builder-export capability. A node with no box is reported, never drawn at a guessed position. Not an McpResponseEnvelopeV1.