# Panel Studio: how to use this with LLMs

Panel Studio designs are ordinary, versioned JSON. Use the same .panel.json file
for AI editing, Git review, the visual editor and Merlin. No separate AI format.
Live editor: https://panels.synthcity.org/
Source checkout: panel-studio (private repository access required for the CLI).

## Quick start (Node 22+, from the checkout)

npm ci
npm run panel -- help
npm run panel -- new 606 --out kit.panel.json
npm run panel -- inspect kit.panel.json
npm run panel -- patch kit.panel.json changes.json --out updated.panel.json
npm run panel -- validate updated.panel.json
npm run panel -- export updated.panel.json --out preview.html

For clean machine-readable stdout, invoke node tools/panel.mjs directly; npm may
print its own banner. CLI paths resolve from the working directory. Runtime code
is loaded from the checkout, never from a design file. No network service needed.

Open preview.html in a browser to visually review the result. It contains the UI
and parameter bridge, not an audio engine. Import updated.panel.json using the
folder button in Panel Studio. Import is an undoable editor action. Browser drafts
and disk files do not synchronize automatically; export the latest browser draft
before applying file edits. File import preserves parameter definitions/bindings.

## Stable IDs and focused changes

Inspect returns JSON {ok, revision, design}. Images are summarized rather than
printing base64 payloads. This inspection result is NOT a loadable design: use the
original file with patch. Do not replace existing IDs merely to rename controls.
new blank creates an unbound empty panel; new 606 includes real 606 parameters.

Example changes.json (first inspect to discover the actual IDs):
[
  {"op":"item.set","id":"starter-4","set":{"label":"Decay","accent":"#aabaff"}},
  {"op":"artwork.ensure","id":"starter-4","template":"legacy"},
  {"op":"layer.set","itemId":"starter-4","layerId":"legacy-2","set":{"rotation":15}}
]

Operations execute on a clone in order; the complete result is validated before
any output is written. Errors include a zero-based operation index when possible.
Use --expect SHA256 with the revision from inspect/validate to reject edits based
on stale input. --out is mandatory for file-producing commands. Existing outputs
are refused unless --force is supplied. Writes use a temporary file and atomic
replacement. --out - writes the artifact to stdout; one JSON input can be - for
stdin. Failure writes {ok:false,error} to stderr and returns exit status 1.

## Operation API v1

- document.set: set name, width, height, background or plugin.
- item.add: unique id, kind, optional set. Generates defaults; binding starts null.
- item.set: id (or itemId), set fields; id and kind are immutable.
- item.remove: id (or itemId).
- artwork.ensure: id, optional template legacy | precision-knob | blank.
  No-op if artwork already exists. Legacy preserves the current control design.
- artwork.set: id, set viewWidth, viewHeight, properties or component metadata.
- layer.add: itemId, unique layerId, kind, optional set. Generates default fields.
- layer.set: itemId, layerId, set fields; id and kind are immutable.
- layer.remove: itemId, layerId. Removes associated exposed-property references.

set is a shallow field replacement, NOT a recursive merge. Supply the full gradient,
effects array, plugin definition or properties array when updating that field.
Use full JSON editing for layer/item ordering or changing a controller's type,
then validate. Automation can edit locked items; locks constrain pointer editing.

Item kinds: knob, slider, switch, pad, label, panel, image.
Layer kinds: ellipse, rect, arc, ticks, text, path, bitmap.
Item fields: name, x, y, w, h, label, binding, note, fill, color, accent, radius,
fontSize, stroke, locked, image, layerValues, rotation.
Layer fields and bounds: see panel-v3.schema.json. Shapes use logical pixels.
Paints: #RRGGBB or fill/accent/color (instance tokens), or none.
Value animation uses motion/from/to; the host owns the parameter value.
Parameter binding uses numeric IDs from design.plugin.parameters, never labels.

## Images without base64 editing

node tools/panel.mjs embed kit.panel.json logo ./logo.png --out with-logo.panel.json
node tools/panel.mjs embed kit.panel.json knob ./sheet.png --layer sprite \
  --width 1024 --height 1024 --out with-sprite.panel.json

First add an image item, or a bitmap layer, using patch. Layer source dimensions
must be supplied in pixels. Set frames and columns with layer.set for sprite
sheets. PNG/JPEG/WebP only, under 2.2 MB for CLI embedding. Assets remain embedded
in portable output. Never paste remote URLs, SVG markup or scripts into designs.

## Schemas and compatibility

https://panels.synthcity.org/schemas/panel-v3.schema.json
https://panels.synthcity.org/schemas/component-v2.schema.json
https://panels.synthcity.org/schemas/operations-v1.schema.json

node tools/panel.mjs schema panel
node tools/panel.mjs schema component
node tools/panel.mjs schema operations

The CLI uses the editor's validator and renderer, including semantic checks beyond
JSON Schema. Existing layout v1/v2/v3 files load; patch emits v3. Component packages
have an independent v1/v2 contract. Unknown future versions are rejected.
lib/automation.ts exposes createDesign, inspectDesign and applyOperations for
TypeScript integrations. The CLI adds filesystem I/O and revision guards.

## Suggested agent task

"Read llms.txt. Inspect my .panel.json, preserve IDs and parameter bindings, then
make the requested visual changes through an operation batch. Write a new file,
validate it, export HTML and review it in a browser. Report the changed item/layer
IDs and output paths. Do not claim the UI is correct from JSON validation alone."

A remote editing API, live browser synchronization and an MCP server are not
implemented. An MCP adapter can wrap the same operation API later; CLI-capable
agents can already use this workflow without another service or credentials.