Skip to content

tutorial.md

Latest commit

 

History

History
77 lines (53 loc) · 3.26 KB

tutorial.md

File metadata and controls

77 lines (53 loc) · 3.26 KB
Raw

Edit a live spaday application

In this tutorial, we will run the Studio pilot, select a component, and change it without reloading the application canvas.

Install the development environment

From the repository root, run:

make develop
make build

The build creates the Studio browser bundle inside the Python package.

Start Studio

Run:

spaday-studio --project orbit.studio.json

Open http://127.0.0.1:8020. You should see a component tree on the left, an operations dashboard in the center, and an inspector on the right. The header should show Revision 0 and Canonical. Studio creates orbit.studio.json from the example document.

Select and edit the headline

Click the large headline in the canvas. The inspector should identify h1 · headline.

Replace its text with:

Ship the interface while it is running.

Click Preview changes. The headline changes, but the header still shows Revision 0 and marks the canvas as a private draft. Click Commit. The header changes to Revision 1; unaffected canvas elements keep their DOM identity throughout both updates.

Make a structural edit

Select main · app at the top of the component tree. Choose p · <p> under the html catalog and click Add component. Choose the destination slot when the selected component exposes named slots. A new paragraph appears at the bottom of the draft canvas. Click Commit to advance the revision.

Select the new paragraph and click Move up or Remove. You can stack several operations in the same private draft before committing it. Each accepted document arrives as a new authoritative transports revision and is reconciled through Spaday's keyed tree patch.

Use Move down to restore its position or Duplicate to copy the selected subtree with new Studio IDs. After a commit, Undo and Redo create new authoritative revisions. Reload the browser while a draft is open to restore that actor's private preview.

Add runtime behavior

Select a component and expand Bindings or Events. Add a direct field binding, field toggle, or field assignment for common cases. Open Advanced JSON for computed bindings, composed actions, and the complete wire surface. The JSON editors use transports' character-level sequence CRDT. Another Studio tab on the same revision sees edits and cursor positions as they happen. Invalid intermediate JSON stays in the buffer and cannot enter the project document.

Use Runtime state for the initial Store fields referenced by bindings and actions. Preview state validates the JSON and stages semantic set_state and unset_state operations. The canvas keeps one Store instance while the tree changes, so two-way bindings and actions can update it normally.

Export the accepted application

Click Export Python in the header. The downloaded spaday_app.py contains a standard spaday page() function for the current canonical revision. Your edits also remain in orbit.studio.json, so stopping and restarting the same command restores the project.

You now have a running structured-document editing loop. Continue with use an installed component package or preview an edit through MCP to drive the same canvas from an agent client.