astrolabe/docs/spec/07-settings.md

# 07 · Settings

Astrolabe provides a **Settings** modal where users tune appearance, the spec editor, preview performance, and date formatting. All settings persist locally and apply across sessions on the same device. Settings load at startup; any unknown or missing value falls back to its factory default, so older or partial saved settings never break the app.

## Opening the modal

- An entry in the application header opens the Settings modal.
- The keyboard shortcut **Cmd/Ctrl+,** also opens it.
- The modal is grouped into clearly titled sections: Appearance, Editor, Performance, and Formatting.
- The modal can be dismissed with a Cancel action or the standard modal-close affordance; dismissing without applying discards any pending edits and restores the last saved values.

## Settings

### Appearance

Controls the overall UI theme. Choosing the Dark theme switches the whole application chrome to a dark presentation.

| Setting  | Options     | Default |
| -------- | ----------- | ------- |
| UI theme | Light, Dark | Light   |

The UI theme is also exposed as a **header toggle** for one-click switching; it
reads and writes the same persisted `ui.theme` value as this Appearance control,
so the two always agree. (The toggle shipped in M1.5, ahead of this modal.)

### Editor

These settings configure the spec editor used to edit Vega-Lite specs (see _Spec Editor & Draft/Published Workflow_). They take effect in the editing surface for the snippet spec.

| Setting      | Options / Range                                    | Default |
| ------------ | -------------------------------------------------- | ------- |
| Font size    | 10–18 px (integer)                                 | 12 px   |
| Editor theme | Auto + explicit overrides (provisional — see note) | Auto    |
| Minimap      | On / Off                                           | Off     |
| Word wrap    | On / Off                                           | On      |
| Line numbers | On / Off                                           | On      |
| Tab size     | Integer number of spaces                           | 2       |

- Font size is chosen along a 10–18 range; the current value is shown alongside the control.
- Editor theme controls the syntax/color presentation inside the editor. **Provisional (to be finalized as we implement the editor):** the default is **Auto**, which derives the editor theme from the app UI theme (light app theme → light editor theme, dark → dark), using custom Monaco themes that match the app chrome. The user may override Auto with an explicit editor theme; the exact override list (custom themes, and whether to include High Contrast or the stock Monaco themes) is deferred. Stored as `editor.theme` with an `'auto'` sentinel for the follow-the-app default.
- Minimap toggles the condensed overview strip beside the editor.
- Word wrap toggles soft wrapping of long lines.
- Line numbers toggles the line-number gutter.
- Tab size sets the indentation width applied while editing.

### Performance

| Setting         | Range       | Default |
| --------------- | ----------- | ------- |
| Render debounce | 500–5000 ms | 1500 ms |

- Render debounce is the delay after the user stops typing before the preview re-renders (see _Live Preview_).
- Tradeoff: a lower value makes the preview feel snappier and more immediate but re-renders more often and uses more CPU; a higher value keeps the app calmer and lighter but makes the preview feel laggier behind the spec.
- The current value is shown alongside the control.

### Formatting

Governs how dates are rendered throughout the app, for example the timestamps shown in the _Snippet Library_ list.

| Setting            | Options                 | Default |
| ------------------ | ----------------------- | ------- |
| Date format        | Smart, ISO 8601, Custom | Smart   |
| Custom date format | Free-text format string | (empty) |

- **Smart**: relative, human-friendly rendering (e.g. "Today", "Yesterday", "3d ago", falling back to a full date for older items).
- **ISO 8601**: a full ISO 8601 timestamp.
- **Custom**: dates render using the user-supplied format string.
- The custom format string field is only relevant when Date format is set to Custom; it is shown only in that case (placeholder guidance such as `yyyy-MM-dd HH:mm`).

## Related persisted preferences (documented elsewhere)

The following preferences also persist locally across sessions but are managed outside this modal and are documented in their own sections:

- **Preview fit mode** — how the preview is sized/fit; see _Live Preview_.
- **Snippet sort preference** — the snippet list's sort field and direction; see _Snippet Library_.

## Behaviors

- **Apply / save**: An explicit Apply action writes all changes; they take effect immediately (e.g. the UI theme switches at once).
- **Dirty indication**: While the form differs from the last saved state, the modal shows an "Unsaved changes" indicator.
- **Cancel / dismiss**: Closing without applying reverts the form to the last saved values and leaves stored settings untouched.
- **Reset to defaults**: A Reset action restores every setting to its factory default. It requires explicit confirmation before applying, then saves the defaults.
- **Startup load**: Settings are read on startup and applied to the UI and editor; missing or unrecognized values silently use their defaults.