cradiy/rovar/rovar-design

Rovar design

Work in the user's running editor. Keep designs editable and iterate on existing elements. Treat the running application's capabilities and schemas as authoritative; there is no pinned protocol version or legacy compatibility mode.

Use reset_component only when the user wants to discard an instance's local overrides and restore its current main component. It also removes local additions and restores interactions. Use incremental update operations for selective edits.

Connect and discover

Read the running editor's discovery records before searching for an executable:

• Linux/macOS: ~/.rovar/instances/rovar-live-*/session.json
• Windows: %USERPROFILE%\.rovar\instances\rovar-live-*\session.json

Each JSON record contains the absolute executable, endpoint, pid, application_version, started_at_unix_ms, and transport. Use the executable and endpoint from the same record. Do not guess build directories, installation paths, or socket names. Honor a path explicitly supplied by the user. If no live record exists, ask the user to start Rovar normally; stale records left by crashes are not proof of a running editor. Do not launch duplicate editors merely to find a session.

Compare this skill's metadata.rovar-version with the record's application_version. The record's skill_sha256 is the SHA-256 of the complete bundled SKILL.md bytes; compare it with this installed file to detect changes within the same app version. If either differs, install the bundled skill from Rovar Settings → AI design and reload the skill before editing. This checks the installed instructions, not a protocol version; continue to discover the live capabilities and schemas.

In the commands below, replace rovar with the recorded executable path, quoted when needed. --list-sessions checks reachability and returns the same metadata. Normal application startup automatically exposes a local interface on Windows, macOS and Linux; no agent startup flag is needed. Web does not expose this transport.

rovar --list-sessions

Use an actual discovered endpoint:

printf '%s\n' '{"request_id":"inspect-session","method":"session.describe"}' |
  rovar --connect /DISCOVERED/PATH/editor.sock
printf '%s\n' '{"request_id":"inspect-tabs","method":"tabs.list"}' |
  rovar --connect /DISCOVERED/PATH/editor.sock
printf '%s\n' '{"request_id":"inspect-apply-schema","method":"schema.get","params":{"method":"document.apply"}}' |
  rovar --connect /DISCOVERED/PATH/editor.sock

Windows PowerShell discovery (choose the intended record before connecting):

Get-ChildItem "$env:USERPROFILE\.rovar\instances\rovar-live-*\session.json" |
    ForEach-Object { Get-Content -Raw -LiteralPath $_.FullName | ConvertFrom-Json }
$rovar = '/EXECUTABLE/FROM/RECORD'
& $rovar --list-sessions | Out-String
$endpoint = '\\.\pipe\rovar-PID-UUID'
'{"request_id":"inspect-session","method":"session.describe"}' |
  & $rovar --connect $endpoint | Out-String

Windows shells may not wait for GUI executables when invoked directly. Keep PowerShell commands in a pipeline, or use Start-Process -Wait -PassThru for explicit exit status. Agent process APIs should redirect stdin/stdout/stderr and wait for exit. No separate CLI executable is needed.

Use UTF-8 for JSON input and output. In Windows PowerShell 5.1, set $OutputEncoding = [System.Text.UTF8Encoding]::new($false) before piping non-ASCII requests. PowerShell 7 uses UTF-8 by default.

--connect reads JSON Lines from stdin and returns JSON Lines on stdout; diagnostics go to stderr. Inspect the JSON error even when the process exits unsuccessfully. Use structured JSON serialization or a request file rather than interpolating design text into shell commands. The CLI accepts multiple request lines.

Inspect each candidate's tabs.list and session.describe to identify the intended window/document; do not choose the first process or tab arbitrarily. If discovery is empty despite a running editor, check that both processes use the same user/home directory. Do not edit persisted .rovar files as a substitute for the live protocol.

Before editing, record the target session_id, document_id, page_id, document revision, selection, busy state, and capabilities. Query schema.get for the methods you will use. Never infer supported properties from what the editor UI can do.

Manage documents

Use tabs.list to inspect all windows and tabs, including empty windows and inactive documents. Tab methods omit envelope session_id and document_id; their parameters use the returned opaque window_id and, where required, tab_id.

• tabs.create: window_id, optional title. Create a document when the design task

calls for one; it uses the window's current local/remote source.

• tabs.open: window_id, absolute .rovar path. External files are imported into

the workspace. An already-open path activates its existing window/tab.

• tabs.activate: window_id, tab_id. Select the intended document and use

tab.session from the response when tab.ready is true. AI can invoke this directly when the task requires loading or showing that document; do not ask the user to switch tabs manually or seek separate approval for an ordinary switch.

• tabs.save: window_id, tab_id. Save a loaded document without switching tabs.
• tabs.close: window_id, tab_id. Use when the task calls for closing that document;

unrelated user tabs should remain open. Closing saves changes first.

Query the method schema before use. Mutations return an acceptance response, not a completed disk operation. Poll tabs.list for loading/saving/closing state and errors. A failed save keeps the tab; a failed open appears in the window's open_errors, identified by tab_id. Do not proceed with editing until session.describe exposes the intended session or a tab snapshot provides ready:true and session. Each loaded tab's session includes session/document/page IDs, revision, and history availability. An unloaded tab has session:null. If create/open/activate returns ready:false, poll tabs.list and use the refreshed scope once ready. On BUSY, inspect pending state rather than flooding retries. After a timeout, retry the exact request ID/body to avoid creating duplicate tabs. There are 256 successful tab-operation receipt slots per process, reported by remaining_tab_receipts; reads consume none. Replayed responses are historical acceptance snapshots, so use tabs.list for current state.

Inspect the design

• session.describe includes loaded background tabs. Select the intended

document/session explicitly and inspect active and busy; do not assume the first session is the visible document. Read, edit, capture, or manage its pages in the background when no view change is needed. Use tabs.activate only to load an unloaded tab or deliberately show it before selection/framing/page activation.

• Use pages.list to discover page UUIDs and counts. Node reads, document.apply,

and captures can target an inactive page without changing the user's canvas. Revisions are document-wide; reread after edits on any page.

• For a selection-based request, resolve the current selection with nodes.get.

Do not guess the selected element from an old screenshot or its name.

• Use nodes.find to locate relevant content and nodes.get to inspect parents,

siblings, geometry, text, and styles before changing them. Names help locate nodes; stable UUIDs identify mutation targets.

• Read paginated results at one revision. If the revision changes, restart the read.
• Capture the affected frame with canvas.capture when visual context matters.

Decode data_base64 to a PNG file and inspect the image; do not print the encoded image into the conversation. This is an export-rendered subtree, not a screenshot of the desktop window or proof of native rendering parity.

Modify incrementally

Prefer small, coherent edits followed by inspection over replacing the entire design. Preserve existing UUIDs, hierarchy, and unrelated user content. Use update for existing elements; create only what is missing and delete only what the task makes obsolete. Do not delete and recreate a frame, page, or all its children on each pass. Rebuild a whole region only when the user requests a redesign or the existing structure cannot express the requested change; keep the replacement scoped to that region.

Use pages.apply for page creation, duplication, renaming, deletion, and ordering; inspect its schema first. Each batch uses base_revision and is one undo entry. Create and duplicate require a name and unique $ref; optional before controls page ordering, otherwise they append. Copies get new node UUIDs and copied component masters become instances. Preserve existing pages unless removal is requested. These operations keep the current page visible unless it is deleted.

Call pages.activate with page_id and revision only when the task requires showing that page or changing its selection/view. It restores the page's saved view without changing document revision. Page mutations and activation share the apply receipt cache: an exact retry acknowledges the earlier result without repeating it. Use a fresh request ID for a deliberate later switch and reread current state after retries.

For a new design, establish the frame and major layout first, inspect the result, then add and refine content. For an existing design, change the specific geometry, typography, spacing, or styling at issue. After each meaningful batch, read the result and capture the affected region before deciding the next adjustment. Let observed results guide subsequent edits instead of repeatedly regenerating the full design.

Use document.apply with a fresh request_id, the inspected scope, and base_revision. Submit related operations as one atomic batch within the limits returned by discovery. Save the exact request until its outcome is known.

• $references resolve earlier creates, duplicates, or instances within one batch only. Use the returned UUIDs

in subsequent batches.

• Coordinates are page units, including children inside frames, independent of zoom

and DPI. Check the current schema for complete compound-property requirements.

• Omit properties that are not changing. A supplied compound property replaces that

property; it is not necessarily a partial patch.

• Respect type-specific constraints: groups have no fill, corner radius applies to

rectangles, and auto-layout controls child positions. Inspect resolved geometry after layout changes. Do not flatten or rebuild a layout merely to move a child.

• Locked content and unsupported node types must remain intact. Do not silently

approximate a requested unsupported feature with a destructive replacement.

Each changed apply is one ordinary undo entry. Its acknowledgement confirms an in-memory edit, not completion of saving or synchronization.