You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 6b5b4cb
Browse filesBrowse the repository at this point in the historyBrowse files
On browsers without native support, Studio loads a polyfill so a WebMCP bridge extension can still
67
-
connect. Nothing is downloaded on a browser that has the API already.
68
+
On browsers without native support, Studio loads a bundled polyfill so a WebMCP bridge extension can
69
+
still connect. Nothing is downloaded on a browser that has the API already. When the Studio
70
+
preference is disabled, it registers no tools.
68
71
69
72
## What an agent can do
70
73
71
74
### Read
72
75
73
76
| Tool | Answers |
74
77
| --- | --- |
75
-
|`studio_look`| The open project and composition, the playhead, what you have selected, and every element with a handle|
78
+
|`studio_look`| The open project and composition, the playhead, selection, undo state, and a bounded source-backed scene in nested order|
76
79
|`studio_inspect`| One element in full: resolved styles, text fields, box, animations, and what it will accept |
77
80
|`studio_frame`| A PNG of the composition at any time |
78
81
79
-
`studio_look` gives every element a **handle**. Pass it back to any tool that edits an element.
82
+
Each element returned by `studio_look` has a **handle**. It also reports `sourceFile`, `parentHandle`,
83
+
`depth`, and `childCount`, so an agent can distinguish the same authored ID in two nested scene
84
+
files. Pass a handle back unchanged to every element write. Handles are source-safe addresses, not
85
+
CSS selectors.
80
86
81
87
### Change
82
88
@@ -92,29 +98,49 @@ connect. Nothing is downloaded on a browser that has the API already.
92
98
|`studio_add_keyframe`| Adds a keyframe to an animation |
93
99
|`studio_delete_animation`| Removes an animation |
94
100
95
-
Every edit runs through the same commit path a mouse gesture uses, so it lands in your file with the
96
-
same undo entry and the same save behaviour. There is no separate agent write path.
101
+
Element writes run through the same commit actors Studio uses. When that actor forwards versioned
102
+
durability evidence, the receipt names the source file and content version, and the edit enters the
103
+
same undo history. Actors without that evidence stay at `dispatched`.
97
104
98
105
## Two rules worth knowing
99
106
100
-
**Select first, then edit.** Most editing tools act on the current selection rather than taking an
101
-
element. That is how Studio itself works: click, then type. An agent that edits without selecting
102
-
gets an error telling it to select.
107
+
**Show intent, then address every write explicitly.** Before the first write to a target, call
108
+
`studio_select` so the person in Studio sees the same selection box and inspector as the agent.
109
+
Selection communicates intent; it does not grant write authority. `studio_set_text`,
110
+
`studio_set_style`, `studio_transform`, and the animation tools still require that target's handle
111
+
from `studio_look`, so a later human click cannot redirect an already-addressed write.
103
112
104
-
**Check what came back.** Tools report what actually happened, not what was asked for.
105
-
`studio_transform` reads the element's box back after writing and tells you which operations took
106
-
effect. `studio_frame` reports the time it actually captured. When something could not be verified,
107
-
the tool says so rather than claiming success.
113
+
**Read the receipt stage.** A write result separates acceptance from proof:
114
+
115
+
| Stage | What it proves |
116
+
| --- | --- |
117
+
|`refused`| No commit actor ran. Fix the handle, input, capability, or Studio state before retrying. |
118
+
|`dispatched`| The actor accepted the request, but the tool has no durable version or independent readback. Follow with `studio_inspect` or `studio_frame`. |
119
+
|`saved`| Studio received versioned evidence that the named source file persisted the write. |
120
+
|`verified`| The write was saved and an independent readback observed the result. |
121
+
|`failed`| A commit actor ran and then failed. Inspect `kind`, `reason`, and any `hint`. |
122
+
123
+
`changed` is separate from the stage. A saved no-op is still truthful: the file accepted the request,
124
+
but the value was already present. Style writes include a receipt per property and can be partial.
125
+
Animation handlers currently report `dispatched` after their persistence and live-preview sync
126
+
settle; they do not claim versioned durability or independent readback when the underlying handler
127
+
cannot provide that evidence. A late cancellation request also does not undo an edit that was
128
+
already dispatched or saved.
108
129
109
130
## Working alongside an agent
110
131
111
-
This is built for you and an agent looking at the same composition. Studio shows you every change as
112
-
it happens: an agent selecting an element draws the same selection box, and an edit appears in your
113
-
undo history under its own name.
132
+
This is built for you and an agent looking at the same composition. Studio shows selection normally
133
+
and adds a **Topology Lens** around the addressed element while a transaction is resolving. A new
134
+
target is acquired, repeated edits localize more quickly, and a durable result seals. The lens is
135
+
Studio-only transaction feedback: it is not added to authored HTML, the preview iframe, captured
136
+
frames, or thumbnails.
137
+
138
+
When a write tool finishes successfully, the open Studio preview has already synchronized that
139
+
edit. The person watching does not need to scrub the timeline or refresh the browser to see it.
114
140
115
-
That shared view is doing real work. Some of Studio's write paths report a failure through a toast
116
-
rather than a return value, so **you** are the one who sees it. Leave Studio visible while an agent
117
-
is working.
141
+
After an accepted source-file change, Studio advances the project thumbnail revision and regenerates
142
+
visible composition thumbnails. This lets the sidebar converge on the saved project instead of
143
+
continuing to show cached pre-edit pixels.
118
144
119
145
<Note>
120
146
Studio refuses agent writes while auto-save is paused or an external change to the file is waiting
0 commit comments