Feature Plan: State Presets

Overview

A DSL-driven system for saving and loading UI/visibility states, allowing performers to prepare starting configurations and recall them during performance.

Motivation

• Performers approaching a complex score are overwhelmed by visible elements
• Need to prepare "clean start" states with minimal visible elements
• Performers can progressively reveal complexity during performance
• States should sync between clients and persist across sessions

Proposed DSL

state(save:clean_start)              // Save current visibility states
state(load:clean_start)              // Load and apply to all clients
state(load:clean_start, sync:false)  // Load locally only
state(load:clean_start, auto:true)   // Auto-load on startup

Usage in Score

SVG elements with state cue IDs:

<g id="button(click:1) state(save:rehearsal)">...</g>
<g id="button(click:1) state(load:rehearsal)">...</g>

Storage

Per-project state files:

scores/polygonfield/states/clean_start.json
scores/polygonfield/states/rehearsal.json

State File Format

{
  "version": 1,
  "name": "clean_start",
  "created": "2026-04-02T20:00:00Z",
  "states": {
    "polygon1": { "visible": false },
    "polygon2": { "visible": true },
    "mixer_faders": { "visible": false }
  }
}

Implementation Phases

Phase 1: Simple JSON Persistence (Current)

• Single ui_state.json per project
• Saves visibility states on toggle
• Loads on startup
• Syncs between clients via WebSocket

Phase 2: Named Presets

• Multiple named state files
• state(save:name) / state(load:name) DSL
• New state.js cue handler
• Server endpoints: GET/POST /api/state/:project/:name
• WebSocket: state_load_sync message

Phase 3: Extended States (Future)

Could extend to capture:

• Animation running/paused states
• OSC toggle states (on/off per animation)
• controlXY handle positions
• o2p positions

Technical Notes

Files to Modify

1. public/js/cues/state.js (new) - cue handler
2. public/js/cues/animShared.js - hook visibility changes
3. public/js/system/socket.js - sync message handlers
4. server.js - state file endpoints
5. public/js/parser/parser.js - recognize state() expressions

WebSocket Messages

// Save broadcast (informational)
{ type: "state_saved", project: "polygonfield", name: "clean_start" }

// Load sync (all clients apply)
{ type: "state_load", project: "polygonfield", name: "clean_start", states: {...} }

Considerations

• Debounce saves to avoid excessive file writes
• Conflict resolution: last-write-wins for simplicity
• Auto-load: specified in project preferences or via auto:true parameter
• Reset: state(reset:true) could restore default visibility

Status

• [ ] Phase 1: Simple JSON persistence
• [ ] Phase 2: Named presets with DSL
• [ ] Phase 3: Extended states