Reading the document

Before an agent changes a design, it reads what is there: an overview from get_app_state, and any detail it needs with Get inside an execute snippet.

The overview: get_app_state

get_app_state takes the document's filePath and returns an overview of it. Agents that Potlot starts from the app already get the current canvas in their prompt, so they can skip this call.

Field	What it holds
`pages`, `page`	The document's pages, and the one the agent works on.
`children`	The top-level layers of that page, each with `id`, `name`, `type` and its computed `box`.
`counts`	How many top-level layers of each type the page has.
`pendings`	Image generations that have not finished yet.
`providers`	Which image and SVG generation providers are configured.
`renderer`	`available` is false when Potlot has no Chrome to render with.
`problems`	Problems found in the document, when there are any.

Reading layers with Get

For detail, the agent runs Get in an execute snippet and prints what it needs with Print. Called with a path, Get returns the layer as plain document data, the same shape Insert, Copy, Update and Replace accept. Children past the requested depth appear as "...".

javascript

Print(Get(screenId, {depth: 1}))
Print(Get(screenId, {depth: 2, resolveVariables: true, theme: {mode: "dark"}}))

Option	Effect
`depth`	`0` returns the layer alone; deeper children are elided.
`resolveVariables`	Replaces each `$name` with its value.
`theme`	The theme to resolve themed variables with.
`resolveInstances`	Expands component instances into their layers.
`resolveScripts`	Runs `script` layers and returns what they generate.

Visitors

Pass a function and Get calls it for every layer in the tree, collecting whatever it returns other than undefined. Arguments are recognized by type, so the path, the function and the options can come in any order. A visitor sees instances expanded.

The second argument, ctx, carries the layer's rendered bounds, its depth and index, the parent's context as parentCtx, and skipChildren() to stop descending. ctx.problems describes clipping, such as a layer partly cut off by its parent.

javascript

Get(screenId, (n, c) => c.problems && Print(n.name, "in", c.parentCtx?.node.name, ":", c.problems))
Print(Get(screenId, (n, c) => n.type === "text" && c.bounds.width > 600 ? n.name : undefined))

Use visitors for structural checks such as sizes, clipping and overlaps. They cost far fewer tokens than screenshots.

Pages, variables and text styles

GetPages() lists pages with id, name, number of frames, active and background. A document without pages returns one page with id "document".
GetVariables() returns variables and, when there are any, themes.
GetTextStyles() returns the text styles by name.