Controls and configuration

Gizmos return a declarative view. Scape renders standard fields and buttons, groups editor settings under Configure, and handles focus, pending state, errors and deletion.

Actions and switches

A control names an action and payload. The reducer still validates the request.

{ id: 'ring', label: 'Ring', placement: 'action',
  action: { name: 'ring', payload: {} } }

placement: 'action' places a control in the main action row with the default play icon. Its label remains the accessible name and tooltip. Placement never changes permission or exposes protected fields.

A participant switch uses icon: 'toggle' with a boolean pressed. Use a meaningful label such as “Turn off” or “Turn on”. See Lamp.

Fields

Views support text fields and finite selects. A control can reference field IDs; the host collects their values into the submitted payload.

fields: [{
  id: 'direction', label: 'Direction', kind: 'select', value: state.direction,
  options: [
    { value: 'right', label: 'Right' },
    { value: 'left', label: 'Left' },
  ],
}],
controls: [{
  id: 'direction', label: 'Set direction', fields: ['direction'],
  trigger: 'change', action: { name: 'configure', payload: {} },
}],

Automatic trigger: 'change' controls save when a select changes and render no separate Save button. All referenced fields must be selects; a field can belong to only one automatic control. These controls cannot also request confirmation, a toggle icon, or action-row placement.

Without trigger, fields submit through an ordinary button. Failed saves preserve or restore appropriate state; your reducer should return a useful validation error.

Portable settings

Declare configuration to identify the editor action and fields that may be copied to later placements. remember can reuse accepted settings during a placement session; open can open Configure initially for settings-first objects. The default is closed.

Configuration goes through the normal action and permission checks. It is not a whole-state export. Use configuration types to see the exact contract.

Text and previews

worldText(state) supplies bounded plain text. textEditor reuses the host's anchored editor for one string field; it targets an editor action. Sign is the built-in composition of these capabilities. Text is not HTML or executable UI.

worldTextRange optionally limits label visibility to a distance greater than zero and at most 32 cells. It works independently of world picking or navigation. Omit it for normal always-visible world text.

A control with kind: 'preview' resolves through previews. A preview is local, does not broadcast, and does not mutate shared state. Piano uses a local preview to audition a note.

Let the host own the panel

Do not add duplicate Configure, Close or Delete controls. Scape owns those affordances and the removal permission checks. Keep labels concise and useful for people using a keyboard or screen reader.

Views allow at most 16 fields and 32 controls; selects contain 1–64 unique values. See limits and API declarations.