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 experimental Dark theme switches the whole application chrome to a dark presentation.

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

### 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, experimental → 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.