An auto tiler for macOS
parcel docs window-rules.md
4.2 kB · 34 lines
Markdown
at main

Window rules #

Settings → Apps shows the built-in float list and learned minimum sizes. Turn a default exclusion off to tile that app's normal windows. Safety checks still leave fullscreen and minimized windows alone.

The menu's Tile app switch replaces the app-wide tiling override for the frontmost app; choosing its default removes that override. Always float saves an app/title rule only when it is new. Exact titles avoid accidentally floating every window from the same project; untitled windows match the app and available role instead. Apps without a bundle identifier need a manually authored app-name rule.

Undo is available from the confirmation, the menu, Settings → Apps, and the configurable undo-last-rule shortcut (Prefix + F17 by default). It removes only the last rule added through Settings or Always float, never an existing duplicate. Later file edits invalidate that Undo, even if a replacement rule has the same values. The confirmation pauses while hovered, focused, busy, or using VoiceOver. Choose 12 seconds, 60 seconds, or until dismissed in Apps.

Always float defaults to Prefix + Shift + F. A prefix that already includes Shift uses Prefix + F16 instead, so ordinary floating keeps its shortcut. Rebind either action in Settings → Shortcuts.

[classification]
disabled-default-float-apps = ["com.apple.calculator"]

[[rules]]
bundle-id = "org.example.editor"
title-contains = "Project"
action = "tile"
layout = "side"
space = 2
move-to-space = true

All supplied matchers must match. Later rules override supplied actions and placements. layout chooses the destination workspace layout when a matching window arrives or its assignment changes, not on every title refresh. New matching arrivals and config reloads can replace a workspace layout you selected manually; omit layout to keep manual choices. space names an existing native desktop (1–16), not a stored Space ID. It does not move anything unless that same rule explicitly sets move-to-space = true (off by default). A later Space assignment replaces both the destination and its consent.

Opted-in moves apply only to newly observed windows after startup. Windows already present at launch stay on their desktops, including after a config reload or retile. Moving briefly switches desktops, drags the title bar using your mouse and keyboard, then returns to the original desktop and restores the cursor. The verified native path never creates desktops. Unavailable desktops, disabled shortcuts, and cleanup failures reach the app's notices.

Moves wait while automatic tiling is off, access is lost, or the display is suspended. Held buttons, modifiers, keys, or typing within 300 ms defer the attempt until input is quiet. Removing the rule or revoking consent cancels pending work. Completed assignments are versioned in ~/Library/Application Support/dev.vinnymac.parcel/rule-space-moves.json, scoped to the current boot and keyed by process/window and destination so a relaunch cannot repeat them. Old boot records expire because macOS can reuse those identifiers. Inspect that JSON or reset it with RuleSpaceMoveStore.reset() while Parcel is stopped; resetting history does not make startup windows eligible.

prcl why WINDOW includes the matched disposition, layout, Space number, and facts. Use prcl minimums list to inspect learned sizes and prcl minimums reset [bundle] to forget them. Native app-reported minimum sizes are retained.

Native tab support is conservative; see Native tabs. Picture-in-picture-shaped AX floating panels are ignored by default and retain their size while unmanaged. Explicit user rules can override that classification. This is not a claim of general video-player or host-app PiP detection; ordinary titled documents remain managed. Event scripts are described in Callbacks.

The default app exclusions remain curated. FaceTime and ColorSync Utility are not added without verified live AX coverage; normal call and document windows may reasonably be tiled. New exclusions need that evidence before changing the default policy.