The Studio Code View
RUAL Studio shows a blueprint two ways: the canvas, and its Blueprint Language source in a code editor. An edit in the code view is checked by the same compile as the source API and staged on the canvas as unsaved edits, which you review and save there.
Canvas and Code are two views of one blueprint
The blueprint header has a Canvas | Code switch. Code opens the source over the canvas; the canvas stays loaded underneath, so switching back is instant. Each time you switch to Code without an edit in progress, the view exports the blueprint again, as the canvas shows it (unsaved edits included), so the source always matches what you were just looking at.
The code view is new. When the blueprint header shows no Canvas and Code switch, your Studio does not include it yet.
Edit a blueprint in the code view
- Open the blueprint and switch to Code.
- Edit the source. The title bar shows Edited as soon as the text differs from the export.
- Press Check (Cmd+Enter on a Mac, Ctrl+Enter elsewhere). Errors and warnings are marked on their lines, and the status bar summarises the diff, for example
8 new, 3 changed. - Fix every marked error and Check again until it says Compiles cleanly. or Compiles, with warnings on the marked lines.
- Press Stage to canvas (Cmd+S or Ctrl+S). The status bar says Staged 11 changes on the canvas. Review and save them there. and the source reloads with the new blocks' real identities.
- Switch to Canvas, review the staged edits, simulate if that helps, and save. Nothing is live before that save.
The toolbar
The title reads Blueprint Language, followed by the size of the export (for example 24 blocks · 4.5% of its JSON) and the Edited or Read only badge.
| Button | What it does | When it is available |
|---|---|---|
| Positions | Shows or hides each block's canvas position as a // @xy X,Y pragma, and exports again. Pragmas are coloured apart from ordinary comments. The choice is remembered in your browser; positions are on by default. |
Not while the source is edited: stage or reload first. |
| Place unpositioned | Lays out only the blocks that have no position, around everything else, and stages those positions as unsaved edits. Answers Every block already has a position. when there is nothing to place. | With edit rights, when the source is not edited. |
| Reload | Exports the blueprint again as the canvas shows it now, replacing the editor's text. | Always. |
| Check | Compiles the source against the canvas (a dry run), marks errors and warnings on their lines and shows the diff as counts of new, changed, moved and removed blocks. Writes nothing. | Always, read-only included. Cmd+Enter or Ctrl+Enter. |
| Stage to canvas | Compiles the source and stages the diff on the canvas as unsaved edits, then reloads the source. | With edit rights, when the source is edited. Cmd+S or Ctrl+S. |
While a stage, a placement or a reload is running, the editor does not take typing: each of them ends by replacing the text. The editor also stays locked until an export has loaded, so an empty editor can never be staged.
Read only without edit rights
Staging writes unsaved edits like any canvas edit, so it needs the setting_edit_blueprints permission. Without it, and while you look at an older revision, the view is read only: you can read, Check and reload the source, but Place unpositioned and Stage to canvas are hidden.
What a refused stage says
A stage writes all of its changes or none. When it is refused, the status bar says why and your edit stays in the editor:
| Cause | Status bar |
|---|---|
| The source has errors | Fix 2 errors before staging. |
Blocks the edit touches changed on the canvas after the source was loaded (SOURCE_STALE) |
1 block this edit touches changed on the canvas since the source was loaded. Nothing was staged: copy your edit, reload, and apply it again. |
Another user has unsaved edits on a block the edit touches (FOREIGN_OVERLAY) |
Another user has staged changes on 1 block this edit touches. Nothing was staged: they save or discard first. |
| The edit adds blocks and the account may not create blocks | This edit adds blocks, and your account may not create blocks in this blueprint. Nothing was staged. |
A write failed and was undone (rolled_back) |
1 block could not be written, so nothing was staged. Your edit is kept; try Stage again. |
| The source equals the canvas | Nothing to stage: the source matches the canvas. |
The counts in these messages follow the answer: 1 block, 3 blocks and so on.
The code view uses the public source API
Every button is one request to the cluster, the same requests an AI agent makes:
| Button | Request |
|---|---|
| Opening Code, Reload, Positions | GET /api/v1/blueprints/{guid}/source?view=staged&positions=1 (positions=0 with Positions off) |
| Check | POST /api/v1/blueprints/{guid}/source?dry_run=1&view=staged with the source and the lock of the export |
| Stage to canvas | POST /api/v1/blueprints/{guid}/source?stage=1&view=staged with the source, the lock, the export's update_hashes and source_view |
| Place unpositioned | POST /api/v1/blueprintactions/layout/{guid} with {"unpositioned": true} |
Frequently asked
How do I edit a RUAL blueprint as code in the Studio?
Open the blueprint, switch the header from Canvas to Code, and edit the Blueprint Language source. Press Check (Cmd or Ctrl+Enter) to compile it and see errors on their lines, then Stage to canvas (Cmd or Ctrl+S) to put the change on the canvas as unsaved edits, and save it there.
Why is the RUAL code view read only?
Staging from the code view writes unsaved edits like any canvas edit, so it needs the setting_edit_blueprints permission. Without it, or while you look at an older revision, you can read and Check the source but Stage to canvas and Place unpositioned are hidden.