Initial scaffold: spec, architecture playbook, and M0 skeleton

2026-08-08 02:02:33 +00:00 · 2026-06-04 22:14:33 +03:00
commit 056644450c
51 changed files with 13754 additions and 0 deletions
@@ -0,0 +1,79 @@
+# 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.