# ``ParcelConfig`` Read, validate, and edit TOML without losing the reader's comments. ## Start small The app creates `~/.config/parcel/parcel.toml` on first launch. Omitted settings use defaults; display overrides inherit the global layout, including individual gap and reserved-edge values. ```toml #:schema https://tangled.org/vinnymac.dev/parcel/raw/main/docs/parcel.schema.json version = 1 [layout] default = "side" portrait-layout = "rows" ratio = 0.5 gaps = { inner = 8, outer = 8 } [layout.displays."47CA9DB1-A0EB-446B-B774-79FC512EAE4D"] default = "columns" [keybindings] focus-left = "hyper-h" stack = false "space-focus 2" = "hyper-2" "window-to-space 2 --follow" = "ctrl-alt-shift-2" space-back-and-forth = "hyper-tab" [[rules]] bundle-id = "org.example.notes" title-contains = "Draft" action = "float" ``` Display keys are UUIDs. Rule matchers combine with AND; the last matching rule wins. Each rule needs a matcher and an outcome: `action`, `display`, or `position`. Use either `title-contains` or `title-regex`, not both. The older `float-rules` table is still accepted. ## Layout and Space commands Layout names are `grid`, `columns`, `rows`, `side`, `tree`, `bsp`, and `accordion`. `layout.portrait-layout` defaults to `rows` on displays taller than they are wide; landscape and square displays use `layout.default`. Display overrides accept both settings and inherit omitted values. These choose a new workspace's layout. Rotating a display adapts the selected layout without replacing a runtime choice. Reloading a changed orientation-specific default applies it to matching workspaces. `window-cap` accepts whole numbers from `0` through `100` and defaults to `3`. Positive requests are limited by each layout's display-dependent capability without changing the stored request; `0` explicitly opts out of both limits. Extra windows follow `when-full`: `stack` joins the active tile, while `float` leaves new overflow windows floating. The configurable count presets `set-window-cap 1` through `set-window-cap 5` set the runtime request; their default shortcuts are Control–Option–Command plus `1` through `5`. Presets above the current capability are accepted, with only the effective cap limited. Reloads preserve custom splits and runtime ratio/cap choices when those configuration values have not changed. Select layouts with `layout-grid`, `layout-columns`, `layout-rows`, `layout-side`, `layout-tree`, `layout-bsp`, or `layout-accordion`. Tree editing uses `split-horizontal` and `split-vertical` to choose the next insertion's axis. `join-left`, `join-right`, `join-up`, and `join-down` reinsert the focused stack beside a neighbor. Transform the tree with `balance`, `rotate`, `mirror-horizontal`, or `mirror-vertical`; adjust its split with `ratio-increase` and `ratio-decrease`. The unbound main-size presets are `ratio-half`, `ratio-three-fifths`, and `ratio-two-thirds`. Native Space commands are `space-focus N`, `space-next`, `space-previous`, `space-back-and-forth`, `window-to-space N`, `window-to-space-next`, and `window-to-space-previous`. The three window-move commands accept `--follow`. They use enabled Mission Control shortcuts. Desktop numbers are the system's 1–16 numbers, not Space IDs; targets must be on the active display. Moves return unless you use `--follow`. Space commands have no default bindings. Quote command keys that contain arguments. `general.prefix` changes default bindings only. Explicit chords are absolute; `hyper` expands to Control, Option, Command, and Shift. Chords use physical ANSI keys and print in `ctrl-alt-cmd-shift-fn` order; `opt` prints as `alt`, and the minus key prints as `minus`. Bind a command to `false` to remove its shortcut. Count shortcuts add Command to the prefix and use `1` through `5`. Snap halves use the prefix plus `6` through `9`, keeping inherited defaults distinct for every modifier prefix. Quote count commands in TOML, such as `"set-window-cap 2" = "fn-2"`. Most snap actions are unbound by default. The schema lists bindable commands; `DefaultKeybindings.bindings()` lists their default shortcuts. Mouse gestures use nonempty, distinct modifier sets: `cmd` for swapping and `alt-cmd` for stacking by default. These do not use the keyboard prefix. Motion preferences never override the system's Reduce Motion setting. ## Focus modes Focus, No peek, and Clean Space start off and apply to the current native Space. Their configurable defaults are prefix+Z, prefix+D, and prefix+P. ```toml #:schema https://tangled.org/vinnymac.dev/parcel/raw/main/docs/parcel.schema.json [focus-modes] no-peek-level = 0.25 no-peek-blur = true clean-space-color = "graphite" [keybindings] focus-toggle = "ctrl-alt-z" no-peek-toggle = "ctrl-alt-d" clean-space-toggle = "ctrl-alt-p" ``` No peek accepts levels from 0.1 to 0.9. Backdrops are `graphite`, `mist`, or `stone`. Settings writes the same keys. Toggle modes through the shortcuts, menu, Settings, or CLI; enabled state is temporary, not a startup preference. ## Named binding modes ```toml #:schema https://tangled.org/vinnymac.dev/parcel/raw/main/docs/parcel.schema.json [keybindings] "enter-mode resize" = "ctrl-alt-f20" [mode.resize] ratio-increase = "right" ratio-decrease = "left" "enter-mode move" = "m" exit-mode = "escape" [mode.move] move-left = "h" "window-to-space-next --follow" = "n" "enter-mode resize" = "r" exit-mode = false ``` A mode name is case-sensitive and uses ASCII letters, digits, underscores, or hyphens. `default` is reserved, regardless of case. References may precede their mode tables, and empty mode tables are allowed. Each named mode starts with `DefaultKeybindings.modeExit`; override `exit-mode` or set it to `false` to remove it. Other commands have no inherited bindings in a named mode. `false` disables an action, including a mode entry. Entry targets must name a declared mode even when disabled. Entering another mode switches directly to it; `exit-mode` returns to the default bindings and is only valid inside a named mode. Default bindings, including mode entries, must resolve to distinct chords. The same holds within each named mode, including its default exit shortcut. Chords may be reused in different modes. Invalid mode names, actions, targets, values, and conflicts reject the configuration with source locations. Unknown ordinary keys under `[keybindings]` continue to warn. `BindingAction` represents a command, a named-mode entry, or a mode exit. `keybindings` and `defaultModeEntries` hold default-mode shortcuts; `modes` holds each named mode's action-to-chord map. Direct model construction stores those maps as supplied; TOML validation supplies the inherited exit binding. Call `validateBindingModes()` before applying a directly constructed or mutated configuration. It throws `ConfigDiagnostic` for invalid names, targets, or conflicting supplied chords without adding bindings or changing the model. Direct named modes may omit an exit shortcut. ## Read, edit, and reload ```swift var document = try TOMLDocument(parsing: source) let result = ConfigValidator.validate(document) try document.setValue(.integer(12), forKey: ["layout", "gaps", "inner"]) let updatedSource = document.render() ``` Leaf edits preserve surrounding text. Replacing a whole collection replaces its formatting too. Edits reparse before committing, so a failed edit leaves the document alone. Dates and times must be quoted as text. Diagnostic lines and columns are one-based and count Unicode scalars. `ConfigStore` is an actor. Call `createDefaultFileIfMissing()` during app startup to write `defaultFileContents`; it never replaces an existing file and throws on IO failures. `reload()` only reads. Subscribe to `updates()` for snapshots, or use `startWatching(debounceInterval:)` for debounced filesystem updates. Call `stopWatching()` when the owner is done. Invalid reads keep the last good configuration. Unknown keys warn; wrong types, bad ranges, unsupported versions, and conflicting shortcuts reject the edit. Setting names use dashes. Underscore spellings are unknown keys: they warn with a dashed-key suggestion and leave that preference unchanged. They are not aliases. ## Editor schema and strings `ConfigJSONSchema.string` exports draft 2020-12 JSON Schema. `publishedURL` is the editor hint's canonical address. `prcl schema` prints the schema locally, with a final newline. Regenerate `docs/parcel.schema.json` with `swift run prcl schema > docs/parcel.schema.json`; a test prevents drift. Portable validators check structure. Parcel also checks chord grammar, native regular expressions, declared mode targets, and effective shortcut conflicts. Edit diagnostics in the module's String Catalogs. The build plugin compiles localized resources under `.build`; generated strings are not committed.