# AquarellEQ browser command coverage The feature map below describes actual visible controls and their equivalent commands. Discover current arguments with window.aquarellAgent.describe(); inspect visualizer.getCapabilities for the active world and layout. | Feature | Pages | Commands | Exact equivalence and limits | | --- | --- | --- | --- | | Homepage AI music invitation, visible starting prompt and Copy prompt | home | `site.getInfo`, `site.copyPrompt`, `site.showSection`, `site.navigate` | site.getInfo.agentPrompt returns the exact visible prompt, section ID, Orbit/guide link destinations and copy feedback. site.copyPrompt invokes the same clipboard action as the button and reports denial/unavailability without success. Reveal make-music-with-ai with showSection; Open Orbit is navigate(page:orbit). Read the returned Agent guide link with an ordinary GET, equivalent to following its text-document link. Reading the prompt never copies or creates music. | | Discover page state, tools, staged files and binary attachment lifecycle | home, watercolor, fire, nebula, crystals, mushrooms, orbit | `site.getInfo`, `agent.describe`, `agent.getState`, `agent.listFiles`, `agent.stageFile`, `agent.releaseFile` | Read existing page/provider state and schemas without starting audio or a renderer. Direct api.attachFile retains a supplied File/Blob; stageFile is the bounded JSON/base64 alternative, and release removes the retained handle. | | Inspect current visual world, transport and export panel | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.getState`, `visualizer.getCapabilities`, `visualizer.getPlayback`, `visualizer.getExport` | Read stable settings/composition/source/panel state and live bounds; transient playhead has its own read and does not churn revisions. Binary/browser objects are not serialized. | | Reveal the existing FAQ or studio guide | home, watercolor, fire, nebula, crystals, mushrooms | `site.showGuide` | Scrolls the actual homepage FAQ section or dedicated studio guide. FAQ expansion remains the separate explicit setDisclosure action. | | Homepage hero thumbnail hover/focus selection | home | `site.previewVisualizer` | Calls the existing feature action: image/srcset/alt, destination, selection and counter change together. | | Silent animated card hover/keyboard preview | home | `site.setCardPreview` | Uses the existing video controller. One active preview; reduced motion, Save Data, visibility and viewport gates remain effective. | | Header/hero/card/guide/chooser navigation | home, watercolor, fire, nebula, crystals, mushrooms, orbit | `site.navigate` | Public page navigation; optional visualizer retains /orbit/?style=... and section retains public anchor destinations. Same-page section requests avoid replacing the session. | | Skip to content, visualizer grid, how-it-works, studio and guide anchors | home, watercolor, fire, nebula, crystals, mushrooms | `site.showSection`, `site.navigate` | Uses existing content targets and native scroll/history. Read site.getInfo for actual section IDs. | | FAQ summary expansion/collapse | home, watercolor, fire, nebula, crystals, mushrooms | `site.setDisclosure` | Explicitly sets the actual details element. IDs and open state are discovered through site.getInfo. | | Light, Dark and System appearance | home, watercolor, fire, nebula, crystals, mushrooms, orbit | `site.setTheme` | Same shared preference, theme button/choices, rendering appearance and persistence; System continues following the device. | | Every exposed renderer parameter, palettes, symmetry and Watercolor EQ | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.getCapabilities`, `visualizer.setSettings` | Exact live keys/ranges/steps from the current world. Includes integer Nebula quality and Crystal/Mushroom camera/reflection. All keys validate before any patch is applied. | | Restore the original feeling | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.resetSettings` | Same visual-default reset and persistence. Like the UI reset, preserves source, music, appearance, title/artist and background. | | Song title and artist overlay | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.setText` | Same text inputs, trim behavior and 100-character limits; current text is included in PNG/MP4 composition. | | Background picker, imported image and Remove | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.openBackgroundPicker`, `visualizer.importBackground`, `visualizer.clearBackground` | Same PNG/JPEG/WebP loader, 20 MiB limit, atomic decode and URL cleanup. Native picker still needs a gesture/user selection. | | Text & background summary and settings-panel close | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.setPanel` | textBackground controls its existing disclosure; closing it preserves the settings parent. settings controls the parent. Actual visibility is reported, and blocked opens reject. | | Palette, appearance, world, settings and mobile menu open/close | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.setPanel` | Uses existing menus/pickers and the actual controls moved into mobile layouts. Available panel names reflect the current viewport; value selection uses setSettings/setTheme/setRenderer. | | Source chooser, examples dialog and Close/Keep making music | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.setPanel` | Explicit source/examples open-close. Orbit's source dialog points to dedicated studios, retaining its editable live music. | | Open audio/video and file drag/drop | watercolor, fire, nebula, crystals, mushrooms | `visualizer.openSourcePicker`, `visualizer.importSource` | Picker request or staged original File/Blob uses the same decoder. Media types are in capabilities. Decode failure/cancel preserves the old source; blocked playback leaves the new source paused. | | Six bundled example song buttons | watercolor, fire, nebula, crystals, mushrooms | `visualizer.loadExample` | Same example IDs, fetch/import/progress/cancel paths; reads do not fetch audio. | | Play/Pause, center/horizon button and Space | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.setPlaying` | Explicit source/session play-pause. Idle chooser is separately setPanel(source). Stopping a live microphone stops its real tracks. | | Listening volume and Mute/Unmute | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.setVolume`, `visualizer.setMuted` | Same monitoring controls; Orbit visual volume auto-unmutes like its slider. Dedicated microphones are not routed to speakers, matching disabled volume/mute controls. | | Playback position and Loop track | watercolor, fire, nebula, crystals, mushrooms | `visualizer.getPlayback`, `visualizer.seek`, `visualizer.setLoop` | Same finite file timeline and repeat flag. Bounds validate against actual duration; microphone has no finite seek/loop timeline. | | Use/Stop microphone and pending grant cancellation | watercolor, fire, nebula, crystals, mushrooms | `visualizer.setMicrophone`, `visualizer.cancelOperation` | Real browser permission/device/analysis path. Late grants are stopped; read or registration does not request permission. | | Fullscreen buttons, F/Escape and artwork click/tap to leave | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.setFullscreen`, `visualizer.setImmersive` | Native fullscreen and clean artwork layout are explicit separate requests. UI's unsupported-fullscreen fallback is setImmersive. Exiting either uses the same layout cleanup. | | Export panel file type, format, paper, loops and close | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.getExport`, `visualizer.setExportOptions`, `visualizer.setPanel` | Can select without rendering and inspect current options. Watercolor paper only; Orbit media/eligible loops only. Closing during rendering is cancelOperation, matching the UI Close button's cancellation behavior. | | Save a frame / composed PNG | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.renderFrame` | Same current renderer/composition capture. Orbit requires visual view, as its visible button does; agent output is an owned artifact job. | | Export full track / finite evolving Orbit WAV or MP4 | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.export` | Same exporter and selected/current options. Dedicated finite files export full duration; Orbit eligible 1–32 loops include ending within 240 s. Mic is live-only. Captures preserve enabled evolution without changing editable music. | | Download a render started by the visible UI | watercolor, fire, nebula, crystals, mushrooms, orbit | `visualizer.getExport`, `visualizer.downloadExport` | Reads the existing UI result metadata and activates its actual download anchor, without rerendering or claiming disk completion. | | Download/release agent-rendered artifacts and cancel UI/agent work | home, watercolor, fire, nebula, crystals, mushrooms, orbit | `site.downloadArtifact`, `agent.getJob`, `agent.cancelJob`, `agent.releaseArtifact` | Actual job progress, rendered bytes and local Blob handles. UI and agent media jobs share reservations and retain them through native cleanup; cancellation is not Undo. | | Orbit Visualize / Back / visualizer selection / Save editable music | orbit | `visualizer.setView`, `visualizer.setRenderer`, `visualizer.openSave` | Same guarded view/world/session actions. openSave invokes the actual Save editable music handler and the pocket collection's canonical settled reveal/focus; opening it does not create a saved copy. Its result names the semantic pocketCollection target without assuming a canonical DOM ID. | | Failed import/export retry, visual reset and automatic WebGL restoration | watercolor, fire, nebula, crystals, mushrooms | `visualizer.importSource`, `visualizer.importBackground`, `visualizer.export`, `visualizer.resetSettings` | Retry the same existing operation after failure/cancel and actual cleanup. WebGL context restoration uses the renderer's existing automatic handler; no manual recovery button exists. | | Orbit background/export retry and visual reset | orbit | `visualizer.importBackground`, `visualizer.export`, `visualizer.resetSettings` | Retry after actual failure/cancel cleanup; changing/reopening a world uses setRenderer and automatic WebGL restore remains active. Editable music/project imports use the canonical orbit.* commands below. | The image background uses fixed centered cover fitting and scene-dependent blending. There are no user controls for background drag, crop, zoom, rotation, opacity or text position. Renderer canvases have no pointer/touch camera or drawing gestures: camera elevation is a slider where offered. Dimensions, horizon/ring geometry, 30 fps and codec bitrate are implementation/export-format settings, not additional UI controls. Browser chrome (permissions, native picker selection, security settings, download completion) remains outside page control. # Orbit editor command coverage This is the operation-by-operation map between Orbit's editor and its agent interface. The same `orbit.*` commands are available through `window.orbitAgent.execute(...)` and the browser's discovered WebMCP tools. On AquarellEQ, `window.aquarellAgent` shares that registry and adds the active site's visualizer tools. Discover the current page with `describe()`; see [the agent guide](/ai-usage.txt) for calls, results, retries, files and jobs. The mapping covers musical operations and editor interface lifecycles. A semantic equivalent changes the same music or setting without requiring an agent to imitate a drag, click a sequence of buttons, or type into an intermediate form. For example, one ring twist is a signed step rotation, and excluding keys is an explicit allowed-key list. Opening a tool does not apply its effect. Interface commands expose the actual editor rather than constructing a second editor for agents. `dist/agent-orbit.mjs` is the authoritative schema catalogue. `dist/agent-orbit-bridge.mjs` validates musical relationships and routes operations through `createOrbitAgentHooks()` in `dist/app.mjs`. The editor continues to own its audio clock, Undo checkpoints, local persistence and rendering. Source owners below identify the UI or shared semantic functions to check when changing either interface. ## Read the current session | Visible information or task | Agent command | Source owner and parity detail | | --- | --- | --- | | Current music, instrument IDs, transport, selected instrument, pending changes and live Tone & space point | `orbit.getState` | App `snapshot()`, `clock()` and `hostStatus()`. `data.playback.field` is the live point; stored `music.field` is an anchor. Reading does not start playback. | | Voice/kit/key choices, note dimensions and active interface limits | `orbit.getCapabilities` | Engine constants, bridge capability data and editor UI controller. Use returned IDs rather than translating visible labels. | | Ready-made loop names, detail, feature descriptions and complete music | `orbit.listPresets` | `scenes.mjs`: `STARTING_POINTS`; app `renderLaunch()`. Reading is separate from trying a loop. | | Saved local loops and occupied slots | `orbit.getCollection` | App `bank` and pocket-card rendering; bridge returns explicit zero-based slots, including vacant entries. The pocket collection is the sole saved-loop list. | | Song title, repeat setting, section IDs, lengths and captured music | `orbit.getArrangement` | App `renderJourney()`; `journey.mjs`. Reading does not start the arrangement. | | Kept comparison and latest saved draft | `orbit.getComparison` | App `renderPinned()`; `explore.mjs`: comparison state. Reading does not switch versions. | | Complete editable backup | `orbit.getProject` | App `projectNow()`; `project.mjs`: `captureProject()`. Includes current music, collection, arrangement, comparison and supported performance preferences. | | Current editable-loop listen URL | `orbit.getShare` | `sharing.mjs`: `shareHash()`; bridge `shareURL()`. Returns a URL locally without a clipboard write or upload. | | Eligible WAV loop counts and finished durations | `orbit.getExportOptions` | `host.mjs`: `getExportOptions()` and timing functions. `evolve` uses the same evolution option as export. | | Goal descriptions, categories, selected goal, actual progress and guide state | `orbit.getAchievements` | `DiscoveryTrail.snapshot()` and `progress()`; app `renderExperiment()`/`renderDiscoveryBook()`. Reading never awards a goal. | | Follow's Before/After step counts and written/heard rings | `orbit.getRhythmPreview` | `engine.mjs`: `reactionPreview()` and `keepReaction()`. Requires `target`; computes the exact preview without advancing notes, keys, playback or random choices. | | Open dialogs, details, notices, volume popup, floating guide and pending restore | `orbit.getInterface` | `agent-editor-ui.mjs`: controller `read()`, backed by real DOM state and allowlisted IDs. Unavailable surfaces are reported explicitly. | The shared `agent.getState` observation is deliberately compact: complete current music plus collection/arrangement/comparison metadata and revision counters. Full resource reads above return captured music when needed. Continuous playhead/field movement is excluded from revision observations so a clock tick does not invalidate every edit. ## Transport, mix, instruments and notes | UI operation | Agent command or equivalent | Source owner and parity detail | | --- | --- | --- | | Main Play/Pause | `orbit.setTransport({playing})` | App `togglePlayback()`/`pause()` through hook `setPlaying()`. Explicit state setter; browser audio activation still applies. | | Tempo | `orbit.setTempo({bpm})` | App tempo control and shared engine state. Integer 48–112 BPM. | | Master level, mute and Swing | `orbit.setMix({volume,muted,swing})` | App master controls. Percent values; omitted fields remain unchanged. Raising volume follows the editor's unmute behavior unless `muted` is explicitly supplied. | | Add Melody, Drums or Bass | `orbit.addInstrument({kind,...})` | App Add dialog; engine kind/voice/kit constants. String Pluck is Melody voice `pluck`. Returns a stable instrument ID. | | Remove one instrument | `orbit.removeInstrument({id})` | App remove lifecycle. Updates relationships and selection, stops affected notes, retains at least one instrument and supports Undo. | | Voice, drum kit, instrument level, mute | `orbit.setInstrument({id,voice,kit,volume,muted})` | App card controls and level popup. Voice only applies to Melody; kit only to Drums. Changing sound releases affected sounding notes. Raising the level unmutes the instrument unless `muted` is explicitly supplied. | | Select the instrument used by live controls | `orbit.selectInstrument({id,openPlay})` | App selection and `setKeyboardActive()`. Selection does not imply Solo. | | Plant or erase one note | `orbit.setNote({id,ring,step,enabled})` | App paint/keyboard note editing; `NoteStroke`. Explicit state prevents retrying a request from toggling a note twice. | | Draw or replace the complete four-ring phrase | `orbit.setNotes({id,notes})` | App `paintCell()`/note-edit lifecycle. Four arrays of unique steps 0–15; unrelated instruments remain unchanged. | | Twist one ring by dragging or keyboard | `orbit.transformNotes({id,operation:'rotate',ring,offset})` | App `beginTwist()`/`moveTwist()`/`finishTwist()` and `finishKeyTwist()`; `explore.mjs`: `rotateOrbital()`. Signed offsets wrap 16 steps, retain note count and leave other rings untouched. | | Set an exact evenly spaced note count on one ring | `orbit.transformNotes({id,operation:'spread',ring,count,offset})` | App `shapeOrbital()`; `explore.mjs`: `spreadElectrons()`. Count 0–16; optional starting offset defaults to zero. Count zero clears only that ring. | | New pattern once | `orbit.transformNotes({id,operation:'random'})` | Card New pattern; engine `randomNotes()`. Separate from automatic evolution. | | Clear notes | `orbit.transformNotes({id,operation:'clear'})` | App Clear notes. Clears all four written rings. | | Shift left/right, Echo, Make space | `orbit.transformNotes` with `left`, `right`, `echo` or `space` | `play.mjs`: `reshapeNotes()`. Left/right shift all rings one step; echo adds answers four steps later; space keeps alternate notes in each ring. These operations do not accept ring/count/offset. | | Undo, including contextual/toast Undo | `orbit.undo` | App `undo()` and `remember()`. Same history and pending-transition recovery. Unchanged explicit setters do not manufacture another musical checkpoint. | Instrument/section IDs come from reads, not displayed ordinals. Rings and steps are zero-based; ring 0 is highest and ring 3 lowest for pitched instruments. A copied Follow rhythm must become editable or be disconnected before written-note editing or recording. The schema rejects unknown arguments and out-of-range values; the bridge rejects incompatible relationships before committing music. ## All automatic movement | UI operation | Agent command or equivalent | Source owner and parity detail | | --- | --- | --- | | Change each loop toggle and Amount | `orbit.setInstrument({id,autoRandomize,mutation})` | Card automation controls; engine `advanceLoop()`/`mutateNotes()`. Amount is 10–100; 90–100 produces a fresh pattern. Other instruments retain their own automation. | | Choose shared key | `orbit.setHarmony({mood})` | Shared-key controls; engine `PALETTES`. Current IDs: `daydream` C major, `sunroom` A minor, `afterhours` D minor. | | Change key automatically | `orbit.setHarmony({autoKey})` | App `syncKeySchedule()` and engine `advanceKey()`. Uses the shared musical clock. | | Automatic-key interval and drift | `orbit.setHarmony({keyEvery,keyDrift})` | Engine `keyChangeSteps()`. Intervals 0.25, 0.5 or 1 loop; drift 0–100. Full-loop timing stays steady like the UI. | | Include/exclude keys from automatic choices | `orbit.setHarmony({keyPool})` | App `data-key-include` controls. Supply the complete allowed list, with at least one ID. `['daydream','afterhours']` excludes A minor from future choices. Excluding the current key does not immediately select a different key. | | Tone & space graph drag or fine-tune sliders | `orbit.setTimbre({tone,haze})` | App `editField()`/`finishFieldEdit()`, field graph/sliders. Percent positions; a manual-only edit stops automatic movement. | | Automatic Tone & space movement | `orbit.setTimbre({motion:{enabled}})` | App movement toggle and `field.mjs` sampler. Enabling a stopped path without `seed` reseeds like the UI. | | Movement interval, curvature and reproducible path | `orbit.setTimbre({motion:{every,curve,seed}})` | App `holdField()` and field sampler. Intervals 0.25/0.5/1, curvature 0–100, optional uint32 seed. Retiming/disabling freezes the currently heard point before reanchoring. The seed controls this path, not all random features. | | Original | `orbit.resetTimbre` | App Original/`editField(DEFAULT_FIELD)`. Restores the default graph point, disables motion, retains its configured interval and curvature. | These are separate systems. Turning off note evolution does not turn off key changes or Timbre movement. Saved loops, backups and evolving exports preserve their supported settings. Finite arrangement captures freeze a steady musical moment, as the arrangement UI does. Live playback can continue without a fixed ending; export duration remains bounded. ## Follow, Turns and live performance | UI operation | Agent command or equivalent | Source owner and parity detail | | --- | --- | --- | | Apply/change/enable/disable Follow on a card or shared panel | `orbit.setFollow({target,source,mode,enabled})` | `card-connections.mjs` apply lifecycle; `reactions.mjs`: `upsertReaction()`. Modes `room` = gaps, `meet` = matching beats, `mirror` = copied rhythm. Multiple followers and acyclic chains remain intact. Disabled connections retain configured lead/mode. | | Swap lead and follower | `orbit.swapFollow({target})` | App Follow Swap and `removeReaction()` + `upsertReaction()`. One atomic edit and one Undo step; unrelated connections remain. Conflicting occupied followers, cycles and incompatible Turns are rejected. | | Turn heard rhythm into editable notes | `orbit.keepFollowNotes({id})` | App `keepReactionNotes()`; engine `keepReaction()`. Works for every enabled Follow mode, selects the target, ends the connection and releases temporary performance like the shared UI. | | Choose Turns members, enable/disable, interval | `orbit.setTurns({enabled,members,every})` | Card controls and app `renderMolecule()`/`syncMoleculeSchedule()`; engine `sanitizeMolecule()`. Disabled drafts allow zero/one member; enabled groups need at least two. Order follows instrument order. Disabling retains the group. | | Pass the same rhythm | `orbit.matchTurns` | App Match rhythm; engine `matchMolecule()`. First included instrument supplies the written rhythm. | | Resolve a Follow/Turns conflict | Explicit `orbit.setFollow({target,enabled:false})` or `orbit.setTurns({enabled:false})`, then apply desired setting | Card conflict actions. No silent removal of another connection or turns group. | | Start/stop recording | `orbit.setPerformance({id,recording})` | App recording button/hook `setPerformance()` and `overdubNotes()`. Starting can start playback; stopping recording leaves loop playback active. | | Keep played notes repeating | `orbit.setPerformance({latch})` | App Repeat notes toggle and `PlayPads`. Requires an audible instrument and an active loop (or a recording start in the same request). | | Held-note pattern and rate | `orbit.setPerformance({pattern,every})` | App repeat-pattern controls; `play.mjs`: `PAD_PATTERNS`, `PAD_SPACING`, `padOrder()`. Patterns together/climb/fall/bounce; rates 1/2/4 steps. | | Press/release a pad or play a keyboard note | `orbit.playPad({id,ring,pressed,durationMs})` | App `pressPad()`/`releasePad()`; `PlayPads`. Recording uses the same clock. A timed press requires latch off; physical release can leave a latched note repeating. | | Stop held notes | `orbit.stopHeldNotes` | App `#pad-release` lifecycle. Clears held/latched notes and agent pad timers, preserving recording, latch preference, Solo and nucleus gestures. | | Release all temporary performance | `orbit.releasePerformance` | App `releasePads(true)`, preview/charge/jam release. Broader than Stop held notes: also disarms recording and ends other temporary performance gestures. | | Hold/release Fill or Break | `orbit.performanceGesture({kind,active})` | App `pressTrick()`/`releaseTrick()`; `JamGestures`. `kind` is `fill` or `break`. Releasing Break schedules the mix return at the loop boundary; there is no separate dropped-state toggle. | | Solo preview | `orbit.solo({id,active})` | App instrument preview lifecycle. Release restores the preceding mix and playing/paused state. | | Hold/release nucleus swell | `orbit.charge({id,active})` | App `beginCharge()`/`endCharge()`. Requires the editor view; does not alter saved notes or instrument type. | Draft source/mode/partner choices in an unsubmitted Follow or Turns form do not alter the music. Agent setters apply the requested relationship explicitly, after checking it as a whole. Likewise, gesture hints, keyboard focus rings and drag previews are interface feedback; the commands perform their complete musical action without simulating those intermediate pointer states. ## Try, save, arrange and compare | UI operation | Agent command or equivalent | Source owner and parity detail | | --- | --- | --- | | Try a ready-made loop | `orbit.loadPreset({index,play})` | App launch cards and scene handoff; `STARTING_POINTS`. Retains earlier loop as a recoverable trial. Playing sessions can queue the next full-loop boundary. | | Random song | `orbit.randomSong({seed,play})` | `random-song.mjs`: `makeRandomSong()`. Optional uint32 seed recreates the composition. Uses trial/recovery lifecycle. | | Cancel a queued change | `orbit.cancelQueued` | App `cancelScene()`. Retains the music already playing. | | Return to your earlier loop | `orbit.returnToLoop` | App trial controls; `scenes.mjs`: `restoreTrialLoop()`. Can queue a musical return when already playing. | | Save editable local copy or replace saved slot | `orbit.saveLoop({slot,name})` | Pocket Save this loop and per-card Edit → Replace; app `saveCurrentLoop()` and bank lifecycle. Omitted slot chooses the next available slot; explicit slot replaces only that copy with the current loop. | | Load saved loop | `orbit.loadLoop({slot,play})` | App saved-loop cards and scene handoff. Does not delete the saved copy. | | Rename saved loop | `orbit.renameLoop({slot,name})` | Edit on a pocket card opens that saved loop's controls, including its name. Changes the saved name while preserving captured music and live music. | | Remove saved loop | `orbit.removeLoop({slot})` | Pocket card's Edit controls and app `removeSavedLoop()`. Undo recovery and slot identity are retained; holes do not renumber later slots. | | Song name/repeat | `orbit.setArrangement({name,repeat})` | App journey name/repeat controls and `journeyChanged()`. Editing is locked during arrangement playback. | | Add current, ready-made or saved loop as section | `orbit.captureSection({source,index,loops,name})` | App `addSongSection()`; `captureScene()`. Sources current/preset/saved; index applies to preset/saved. Up to four independent captures; lengths 1/2/4 loops. | | Rename/resize/reorder section or Use current loop | `orbit.updateSection({id,name,loops,position,useCurrentLoop})` | App section actions. Stable section ID; zero-based destination position; replacement affects only that section. | | Remove one section or clear song | `orbit.removeSection({id})`, `orbit.clearArrangement` | App journey remove/clear controls. Existing Undo and current editable loop remain. | | Load ready-made song | `orbit.loadExampleArrangement` | App example-song button; `journey.mjs`: `exampleJourney()`. Replaces arrangement with ordinary Undo. | | Play song / Keep playing this section | `orbit.setArrangementPlayback({playing})` | App `startJourney()`/`stopJourney()`, `JourneyPlayer`. False exits arrangement sequencing while the current loop continues. Pause all playback with `setTransport({playing:false})`. | | Keep version before experimenting | `orbit.keepComparison` | App `pinCurrent()`; `explore.mjs`: `pinGroove()`. Stores a comparison moment with Undo. | | Hear kept version or latest draft | `orbit.useComparison({version})` | App `comparePinned()`; `compareGroove()` and queued handoff. Explicit `kept`/`draft`, so retries do not toggle sides. | | Remove kept comparison | `orbit.clearComparison` | App comparison clear and `sanitizePin()`. Does not remove saved loops or arrangement sections. | Pocket saved loops are separate editable copies on the current browser/device. **Edit** on one card reveals a single rename/Load/Replace/Remove row; it does not open a second collection list. `orbit.openTool({tool:'saved',slot})` reveals that card's editor using its zero-based slot from `getCollection`; `slot` is valid only for the saved tool. `getInterface` reports `collectionEditor.slot` and the existing `saved-loop-manager` disclosure state. The disclosure now belongs to `pocket-collection`. Direct collection commands retain the same IDs, storage and Undo semantics without requiring the controls to be open. ## Naming, listening, imports and exports | UI operation | Agent command or equivalent | Source owner and parity detail | | --- | --- | --- | | Name current loop, cover drawing and palette | `orbit.setCreation({name,cover,color})` | App creation controls; `creation.mjs`: `sanitizeCreation()`/`coverArtwork()`. Separate from saved-copy and arrangement names. | | Copy listen link | `orbit.copyShareLink` | Existing clipboard lifecycle; `orbit.getShare` is the data-only alternative. Browser permission failure is returned explicitly. | | Open/close listen preview or play/pause it | `orbit.previewShare({open,playing})`; `orbit.setDialog({dialog:'sharedListening',open})` for visibility alone | App `openShared()` and dialog-close lifecycle; `listen.mjs`: `SharedListener`. Closing follows normal editor playback resume. | | Remix listened music | `orbit.remixShared` | App `remixSharedLoop()`. Preserves earlier editable music using the ordinary recovery lifecycle. | | Import editable loop from listen URL/hash or JSON | `orbit.importLoop({shareURL,snapshot,play})` | `sharing.mjs`: `readShareHash()` and scene handoff. Exactly one source; parse locally, no remote URL fetch. Imported loop is a recoverable trial. | | Restore project JSON or staged backup file directly | `orbit.importProject({project,fileId})` | `project.mjs`: `readProject()`; app `applyProject()`. Exactly one source; existing format/size validation precedes one project Undo checkpoint. Malformed files do not replace current state. | | Open editable-project file picker | `orbit.openProjectPicker` | App existing `#project-file` flow. Browser selection may require activation; returns queued selection, not a completed import. | | Review, confirm or cancel selected project backup | `orbit.getInterface`, `orbit.confirmProjectRestore`; `orbit.setDialog({dialog:'projectRestore',open:false})` to cancel | App `pendingProject` and `restorePendingProject()`. A selected file is validated before review; confirm requires the open pending review. Cancellation clears pending restore without replacing music. | | Download WAV, MIDI, instrument PNG or editable project | `orbit.export({format,loops,evolve})` | Shared audio/engine/image/project exporters through bridge `exportJob()`. Returns a running job; loops/evolve apply to WAV. No duplicated transient export-form preference API is needed to request an exact output. | | Download full arranged-song WAV | `orbit.exportArrangement` | App journey export; `audio.mjs`: `renderJourney()`. One finite pass over captured sections. | | Track/cancel rendering and obtain/release file | `agent.getJob`, `agent.cancelJob`, `agent.releaseArtifact` | Shared runtime jobs/artifacts. The completed job contains artifact metadata and its URL. Completion means bytes were rendered, not proof of a completed filesystem download. Native editor WAV and arrangement renders use the same media reservation and appear as UI jobs; `agent.cancelJob` can cancel them, and their reservation lasts through renderer cleanup. Browser-local handles expire when released or the document ends. | | Stage/release a browser file | `agent.stageFile`, `agent.releaseFile`; direct `api.attachFile()` | Shared runtime file staging, also used by hosted media/background import. File IDs are local handles, not operating-system paths or uploaded URLs. | **Downloads & backups** is the place for portable project backup/restore and loop downloads. A `.orbit.json` backup contains the whole editable workspace: current music, pocket collection, song sections and comparison. WAV audio, MIDI notes/drums and PNG artwork are separate download formats. A listen link carries the current editable loop rather than the whole project. Local collection storage can be lost when browser data is cleared; a downloaded project backup is the portable editable copy. WAV exports and hosted Orbit video exports enforce the finished four-minute limit, including applicable tail/container allowance. Query eligible counts rather than assume every count fits every tempo. Standalone loop WAV offers up to 16 loops; AquarellEQ can offer eligible counts through 32. Live music stays open-ended. Export captures do not advance or rewrite the live editable composition. ## Tools, dialogs, disclosures, appearance and learning | UI operation | Agent command or equivalent | Source owner and parity detail | | --- | --- | --- | | Shared editor tools and pocket collection | `orbit.openTool({tool})` | App `showFeature()` and collection navigation. Tool IDs timbre/tryLoops/arrange/saved/compare/share/achievements; reveals existing controls without performing their action. Optional `slot` with `saved` focuses that pocket card's Edit controls. | | Card Play & record, Follow, Turns, options and volume popup | `orbit.openTool({tool,id})` | App `setKeyboardActive()`, `openCardTool()`, `createCardConnections()` and volume popup lifecycle. IDs play/follow/turns/options/volume; omitted id uses selected instrument. | | Contextual panel X / volume-popup dismissal | `orbit.closeTool`; `orbit.dismissNotice({notice:'levelPopup'})` | App workspace/level close lifecycle. Closing Play & record releases its held/repeating notes and recording. | | Help | `orbit.openHelp`; `orbit.setDialog({dialog:'help',open})` | App `openHelp()`/`closeHelp()`. Uses accessible native dialog, including ordinary fragment-close behavior. | | Add instrument and WAV export dialogs, without applying changes | `orbit.setDialog({dialog,open})` | `agent-editor-ui.mjs` dialog allowlist and app lifecycle hooks. IDs addInstrument/audioExport; direct add/export commands perform the underlying operation. | | Native expand/collapse sections, including Help topics | `orbit.setDetails({sectionId,open})` | UI controller `EDITOR_DISCLOSURES` and app transition helper. Discover IDs from `getInterface`; opening reveals the parent; closing does not open a hidden parent. Arbitrary selectors are rejected. | | Welcome, achievement reward and toast dismissal | `orbit.dismissNotice({notice})` | UI controller and app timers/visibility lifecycle. IDs welcome/achievementReward/toast. No earned progress or musical edit is undone. Toast Undo is the separate `orbit.undo` operation. | | Light/Dark/System appearance | `orbit.setTheme({preference})` | Standalone preference storage or hosted shared AquarellEQ preference. Same site appearance controller; no second hosted theme state. | | Select a goal and optionally reveal its control | `orbit.showAchievement({id,reveal})` | App `selectDiscovery()`/`revealAchievementControl()`; actual catalogue IDs. Does not perform the goal or fabricate earned progress. | | Next goal / reward Next / floating-guide Next | `orbit.nextAchievement({keepGuideOpen})` | App `nextDiscovery()` and guide lifecycle. Same next-unearned ordering; `keepGuideOpen:true` retains floating guide for its Next goal action. | | Free play/goal visibility, achievement category, floating guide open/close | `orbit.setGuide({visible,group,open})` | App achievement state. Patch fields are independent; group supports `all` and current catalogue categories. Guide display also depends on selected-goal visibility. | The interface allowlists are advertised by `getInterface` and `getCapabilities.interface`. Current dialog IDs are help/addInstrument/audioExport/projectRestore/sharedListening; current disclosure definitions live in `EDITOR_DISCLOSURES`, not caller-supplied CSS. Closing an export dialog is different from cancelling an already-started export job. ## Host navigation and visualizers Orbit's editor is the canonical provider for its music; hosted AquarellEQ adds page-specific visualizer, source, composition, navigation and export providers to the same API. Use the active `describe()` output and AquarellEQ's agent guide for those command schemas. The Orbit Visualize link, return-to-editor/save-backup navigation and homepage links use the host's actual navigation operations. They are not additional changes to the music model or invented HTTP API endpoints. Navigating ends the old document session and requires rediscovery on the destination page. ## Maintaining this map When a UI control changes, check its app/shared semantic owner, bridge route, schema, interface state if applicable, and this mapping together. Every packaged Orbit command must appear in this document, and direct/WebMCP registration must use the same descriptor. Keep new parameters explicit; retain unrelated instruments/resources and reject invalid IDs, bounds, cycles and conflicts before committing state. The focused checks live in `test/agent-orbit.test.mjs` (catalogue/schema/provider), `test/agent-orbit-bridge.test.mjs` (real engine/relationship/resource semantics), `test/agent-app-hooks.test.mjs` (native editor lifecycle), `test/agent-editor-ui.test.mjs` (allowlisted interface lifecycle), `test/agent-media.test.mjs` (native UI/agent export reservation and cancellation), `test/agent-api.test.mjs` (JSON/results/revisions/files/jobs) and `test/agent-webmcp.test.mjs` (shared tool transport). Engine, Explore, field-motion, Follow, play, journey and project tests cover their canonical semantics. These checks verify operations and invariants; they do not claim identical pointer traces, layout timing or browser permission availability.