# Configuration Settings and `~/.config/parcel/parcel.toml` share the same preferences. On first launch, Parcel creates the file with an editor schema hint; existing files are left alone. Omitted values use defaults. Setup uses your current configuration, not a separate tour preset. **Manual** means Automatic tiling is off; layouts, rules, mouse controls, and configured shortcuts still work. **Retile** explicitly arranges windows while it is off. Adjust layouts, tile counts, gaps, and reserved edges in **Settings → Layout**; edit rules in **Settings → Rules**, and motion in **Settings → Motion**. ```toml #:schema https://tangled.org/vinnymac.dev/parcel/raw/main/docs/parcel.schema.json version = 1 [general] prefix = "ctrl-alt" [layout] default = "grid" portrait-layout = "rows" window-cap = 3 when-full = "stack" gaps = { inner = 8, outer = 8 } [motion] enabled = true transitions = "glide" [keybindings] focus-left = "hyper-h" stack = false ``` Edits reload automatically. Invalid edits report a line and column and keep the last good configuration. Unknown keys warn; wrong types, ranges, versions, and conflicting shortcuts reject the edit. Setting names use dashes, not underscores. ## Layouts and tile counts Layouts are `grid`, `columns`, `rows`, `side`, `tree`, `bsp`, and `accordion`. `portrait-layout` defaults to `rows` on displays taller than they are wide; landscape and square displays use `default`. Display overrides use UUIDs and inherit omitted values, including individual gaps and reserved edges. `ratio` sets the main tile's share when the second tile arrives and accepts values from `0.1` to `0.9`. Settings offers Half, 60%, and Two thirds presets for every layout except Accordion. Later window arrivals can split an existing tile. The default cap is three tiles. `window-cap` accepts whole numbers from `0` through `100`. Positive requests are limited by the layout’s adaptive display capability without changing the stored request. `0` explicitly opts out of both limits. Settings and the menu show the requested and effective counts. At the effective cap, new windows join the active tile. Set `when-full = "float"` to center them instead. Overflow windows stay floating until you tile them or a rule does; title changes and reloads leave them where you put them. Lowering the effective cap merges the last tiles into the previous tile. `set-window-cap 1` through `set-window-cap 5` are configurable count presets. `set-window-cap 0` removes the limit and is unbound by default. Reloads preserve custom splits and runtime ratio/cap choices when those config values haven’t changed. See the [module guide](../Sources/ParcelConfig/ParcelConfig.docc/ParcelConfig.md) for per-display overrides, tree editing, focus modes, and named binding modes. ## Shortcuts and motion `hyper` means Control–Option–Command–Shift. `general.prefix` changes default bindings except Tab View, Settings, and Quit; explicit chords are absolute. Use `false` to unbind a command. Keys are physical ANSI keys, so their positions do not follow the input language. Settings → Shortcuts shows the resolved bindings and flags conflicts. An explicit binding that matches another command’s inherited default is a conflict; disable or rebind that default as well. The default prefix is Control–Option (⌃⌥). These are the complete default bindings: | Action | Shortcut | | --- | --- | | Swap left / right / up / down | ⌃⌥← / ⌃⌥→ / ⌃⌥↑ / ⌃⌥↓ | | Focus left / right / up / down | ⌃⌥⇧← / ⌃⌥⇧→ / ⌃⌥⇧↑ / ⌃⌥⇧↓ | | Move left / right / up / down | ⌃⌥⇧A / ⌃⌥⇧D / ⌃⌥⇧W / ⌃⌥⇧S | | Make primary | ⌃⌥Return | | Window controls | ⌃⌥\ | | Next / previous window | ⌃⌥] / ⌃⌥[ | | Stack / unstack | ⌃⌥Space / ⌃⌥; | | Next / previous stack member | ⌃⌥` / ⌃⌥⇧` | | Grow / shrink / reset sizes | ⌃⌥= / ⌃⌥− / ⌃⌥0 | | Float / tile; always float | ⌃⌥F / ⌃⌥⇧F | | Focus / No Peek / Clean Space | ⌃⌥Z / ⌃⌥D / ⌃⌥P | | Automatic tiling | ⌃⌥T | | Retile | ⌃⌥R | | Grid / Columns / Rows / Side / Tree / BSP / Accordion | ⌃⌥G / ⌃⌥C / ⌃⌥Y / ⌃⌥E / ⌃⌥⇧T / ⌃⌥B / ⌃⌥O | | Horizontal / vertical split | ⌃⌥X / ⌃⌥V | | Join left / right / up / down | ⌃⌥F5 / ⌃⌥F6 / ⌃⌥F7 / ⌃⌥F8 | | Balance / rotate / mirror horizontally / vertically | ⌃⌥F9 / ⌃⌥F10 / ⌃⌥F11 / ⌃⌥F12 | | Window cap 1 / 2 / 3 / 4 / 5 | ⌃⌥⌘1 / ⌃⌥⌘2 / ⌃⌥⌘3 / ⌃⌥⌘4 / ⌃⌥⌘5 | | Snap left / right / top / bottom half | ⌃⌥6 / ⌃⌥7 / ⌃⌥8 / ⌃⌥9 | | Undo / undo last rule | ⌃⌥U / ⌃⌥F17 | | Close / fullscreen / hover focus | ⌃⌥Delete / ⌃⌥M / ⌃⌥I | | Move to display left / right / up / down | ⌃⌥⌘F1 / ⌃⌥⌘F2 / ⌃⌥⌘F3 / ⌃⌥⌘F4 | | Tab View | ⌥Tab | | Settings / Quit | ⌘, / ⌘Q | Tab View works independently of the prefix. Rebind or disable it with `tab-view` in `[keybindings]`. While it is open, Tab and Shift–Tab cycle, arrows move between cards, Return or a click selects, and Escape cancels. Floating and minimized windows appear in separate rows below the tiles. Ignored windows never appear, even when minimized. Dense layouts use a scrollable grid instead of shrinking cards below 180 × 64 points; every card keeps an icon and a truncated title. Keyboard selection scrolls its card into view. Releasing an opening modifier selects; Shift remains available for navigation when another modifier is held. A shortcut without modifiers stays open until Return, a click, or Escape. With VoiceOver enabled, the panel takes keyboard focus and stays open after modifier release. VoiceOver chords, Caps Lock input, and Quick Nav arrows are routed to that panel, not the background app. Use Return, a click, or Escape to finish. Escape returns to the previously focused app. A minimized tiled window returns to its saved tile if that placement is still valid. Otherwise it joins the focused workspace's next layout slot and explains that the layout changed. A queued restore is tied to the original window generation, so a recycled window ID cannot restore a replacement window. If the prefix includes Shift, focus uses H/L/K/J, move right uses F13, previous stack member uses backslash, always float uses F16, and Tree uses F18. Window controls uses F19. Other keys remain the same. Explicit bindings keep their exact modifiers. At a display edge, swap moves to the next display in that direction. If it is full, the destination workspace's `when-full = "stack"` joins the neighboring tile. Otherwise `general.when-display-full = "stack"` also stacks; `"swap"` exchanges windows. To exchange across a full display, choose `when-full = "float"` for that display and `when-display-full = "swap"`. Explicit display moves and new windows keep their existing overflow behavior. Control–Option is also VoiceOver’s default modifier. Several chords overlap VoiceOver commands, including arrows, Return, brackets, Space, and Control–Option–Command–1 through 5. Control–Option–Space can also select the next input source. VoiceOver or macOS may intercept these; choose a different prefix or rebind them. Conflict checks use enabled system shortcuts and the current app’s menus, and do not catalog all VoiceOver commands. Mouse gestures use their own modifier settings, separate from the keyboard prefix. ## Motion ```toml [motion] enabled = true speed = 1 level = "playful" transitions = "glide" ``` - `enabled` controls motion globally and defaults to `true`. Reduce Motion takes precedence: windows move instantly and overlays use a brief fade where needed. - `speed` is a multiplier: `1` is normal, smaller numbers are slower, and larger numbers are faster. Settings offers steps of `0.6`, `0.8`, `1`, `1.4`, and `2`; the TOML file accepts any number from `0.1` through `4` inclusive. - `level` controls motion character, not speed. `calm` removes bounce and moves windows instantly; `playful` is the default; `extra` adds bounce to some effects. - `transitions` controls window movement: `glide` animates windows; `ghost` moves them instantly with an animated outline; `snap` moves them instantly without the outline. `glide` is the default. Feedback sounds are opt-in via `motion.sound` and are suppressed with Reduce Motion. ## Appearance `system` keeps native macOS colors. Six palettes are available: `kiln` (Parcel’s house terracotta, ochre, and teal), `tide`, `grove`, `iris`, `dusk`, and `rose`. `mode` is `system`, `light`, or `dark` and affects Parcel’s windows and chrome, not other apps. Changes apply instantly without moving windows or changing layout. ```toml [appearance] palette = "kiln" mode = "system" border-opacity = 1.0 border-radius = 10.0 active-border-color = "#B65C44" ``` `border-opacity` accepts `0`–`1` (default `1`); `border-radius` accepts `0`–`40` points. Omit `border-radius` to match each window’s native corner radius. Every explicit value, including `10`, uses that radius. Optional overrides use exactly `#RRGGBB`: `active-border-color`, `inactive-border-color`, `glow-color`, `chip-background-color`, `chip-text-color`, `stack-accent-color`, and `clean-space-backdrop-color`. Omitted roles use the palette. With `system`, `focus-modes.clean-space-color` keeps its `graphite`, `mist`, or `stone` backdrop, including under Increase Contrast. Named palettes and explicit backdrop overrides control that color instead; the Focus modes picker explains when it is disabled. Settings lists custom overrides and can reset one role or all of them. Palette preview cards select a palette and summarize both modes for VoiceOver. Custom colors and reduced border opacity are not guaranteed to meet WCAG contrast requirements. Accessibility preferences, including Increase Contrast and Reduce Transparency, take priority and keep borders fully opaque. ## No Peek dimming The menu’s dimming slider and Settings → Focus modes share the global `focus-modes.no-peek-level` preference. It accepts `0.1` through `0.9` and controls the dimming wherever No Peek is enabled. The default is `0.25`, with blur enabled: gentler dimming keeps neighboring window shapes visible while blur obscures their text. Existing explicit levels are kept. ## Editor support Editors that support TOML schema hints can use the [published schema](parcel.schema.json). The schema checks structure; Parcel also checks shortcut conflicts and native expression syntax. To regenerate it without a running app: ```sh mise exec -- swift run prcl schema > docs/parcel.schema.json ``` A test compares the published file byte-for-byte with the exporter. Parser, validation, editing, and hot-reload APIs are in the [ParcelConfig guide](../Sources/ParcelConfig/ParcelConfig.docc/ParcelConfig.md). For more choices, see [window rules](window-rules.md), [callbacks](callbacks.md), and [layout memory](../Sources/ParcelEngine/ParcelEngine.docc/LayoutMemory.md).