cAppDeveloper docsUse Studio to customise a Sidecar's declared interface and mapped controls, preview the real rendered surface and retain a versioned design. Studio is the Sidecar editor in cApp; it is not the separate AI Studio Sidecar or an unrestricted editor for every application screen.
Before you begin
Choose a component that declares an editable Studio surface and mapped regions/functions. Open the intended project for a project-specific change, or deliberately choose global scope. Inspect an unfamiliar imported package before loading or trusting its custom code.
Have the component's normal preview/build prerequisites available. A compiled preview is an interactive runtime surface, not necessarily a passive picture: begin with appearance edits and do not activate controls that may have external effects without understanding them.
Open the component you want to change
In Library, choose More → Studio; the Studio catalogue also lets you choose a component directly. Confirm its name and selected Scope before editing. Opening a component does not by itself add it to every application's package.
| Scope | Use it for | Effect on other scopes |
|---|---|---|
| Global defaults | A shared starting appearance/configuration for this Sidecar | Projects may override the fields they explicitly customise |
| This project | A change owned by the current project | Does not rewrite the global default or other projects |
The effective design combines the package's canonical design, explicit global changes and explicit project changes. Merely opening a default field does not turn every default into an override. A project-specific value takes precedence over the corresponding global setting.
Project scope is a project override, not a promise of independent Studio histories for every application component inside that project. Check the effective result for each app that uses the same Sidecar. Library's app-scoped selection and Studio's project/global authoring scopes are different concepts.
Make a first appearance change
- Open the Sidecar and choose This project for a contained trial.
- Choose the target Platform and Viewport, then Build live preview.
- In Select mode, click a mapped element. Edit its supported label or appearance in the inspector rather than targeting arbitrary surrounding app elements.
- Use Appearance for supported design tokens, Functions for mapped controls, and Blocks for supported additional visual elements.
- Switch to Interact only to test the intended control behaviour. Check a narrow viewport as well as the desktop layout.
- Inspect the save indicator and choose Checkpoint. Use Export JSON to retain an editable copy before larger changes.
For example, change a mapped heading or button label, adjust spacing/colour through supported appearance controls, and verify the control still invokes the original action. A decorative Button block is not automatically a new privileged runtime function.
Build the live preview when you need it
Opening Studio does not automatically compile a new preview. Build live preview starts the shared build-renderer path. Ordinary mapped edits can update an already mounted preview; Rebuild live preview is available when a fresh render is required.
Select targets editable mapped elements. Interact sends interaction to the live surface. Drag & drop repositions supported mapped items; Fit / Actual size changes how the viewport is displayed, not the packaged device's resolution. Platform and viewport previews remain development tools, not proof of an installed native implementation.
If construction fails, open Diagnostics and inspect the failing compile or surface-loading stage. Copy report and Download JSON provide a bounded record; review local paths, identifiers and contextual messages before sharing it. A component without stable function mappings may have nothing to select in part of its surface even though its runtime works.
Keep edits scoped
Functions edits mapped labels, placement, order and supported visibility/enabled states. Locked runtime functions stay protected. A hidden control does not revoke the underlying application permission, and changing a label does not redefine a method's API or authorization.
Additional Blocks and appearance changes belong to the selected Studio document. Reset element appearance resets the selected element's styling, not the whole project's source or release history. Recheck the effective global/project design after a reset.
Custom CSS is applied after the component stylesheet. For a light-DOM surface, prefix selectors with the Sidecar's declared root selector so the change does not restyle the surrounding application. Do not invent a generic root selector; use the selected component's declared surface.
Custom JavaScript is project-trusted code. Its document must have both Run JavaScript and I trust this project code enabled to authorise execution, and preview/runtime execution policy still applies. Keep them off for an unreviewed import. Parsing valid JSON is not a code review, and a scoped helper API does not make arbitrary JavaScript harmless. Published versions retain the exact source, so review code before releasing it.
Save, export and release
Studio distinguishes recovery, drafts and immutable versions:
| Action or state | What it means |
|---|---|
| Local recovery | A local editing recovery copy; inspect the indicator before assuming durable service storage exists |
| Autosave / Checkpoint | A draft written to the selected scope's journal when that storage is available |
| Export JSON | A portable copy of the Studio document, not the entire Sidecar package or a native installer |
| Import JSON | Loads a document into the selected editor; review scope, code and effective changes before using it |
| Publish version | Creates an immutable Studio release and makes it current in that scope |
| Use in History | Selects an existing immutable version |
| Restore as new draft | Recovers a journal sequence without rewriting the old journal entry |
Edits autosave; closing the editor is not a reliable “discard changes” operation. Watch the footer for Journalled sequence or an error. A local recovery message is not the same as a confirmed durable save. Preserve an export before switching scope or making a large import.
In History, choose Publish version, enter a new version and useful release notes, then inspect the current version. Publishing Studio records local authored configuration; it does not upload the public documentation, publish to Showroom or update an installed app.
Select/configure the Sidecar for the app, then follow the normal compile/package workflow to ship the effective design. New source or compiler-owned changes need a new compile; packaging-only customisation still needs a new package. Test that installed package instead of assuming the editor preview was deployed.
Recover or switch a design
Use Undo/Redo for the current editing session. For earlier durable work, open History and choose Restore as new draft on the required journal sequence. This creates new editing state and leaves older history intact. Checkpoint, preview and publish a new version when the recovered draft is ready.
To use a retained release, choose Use on that version and check the effective selection before packaging. A current draft, a selected immutable Studio version and an older installed application can legitimately show different content. Record which one you are comparing.
Troubleshooting
| Symptom | Next check |
|---|---|
| The wrong project changed | Check Scope, the active project and which apps use that Sidecar. Global edits and project overrides are distinct. |
| Global changes do not appear in one project | Inspect the project's explicit overrides and selected version. |
| Nothing is editable in part of the preview | Check Select mode and declared element/function mappings; arbitrary DOM editing is not promised. |
| Preview never starts or fails | Build it explicitly, inspect target prerequisites and open Diagnostics for the failing stage. |
| JavaScript does not run | Check both trust/enable flags and applicable runtime/preview policy; do not enable unknown code just to test the switch. |
| Save shows local recovery or an error | Check service-backed storage and scope; export the document before closing or changing context. |
| Installed appearance is unchanged | Confirm the intended current Studio state reached a new package and that the updated app was installed. |
What success looks like
The Sidecar's intended appearance and controls work in preview, the correct scope has a recorded draft/version, and the packaged application reflects the change without affecting unrelated surfaces. Continue with Library selection, release checks and application-surface tests.