An auto tiler for macOS
parcel AGENTS.md
8.8 kB · 113 lines
Markdown
at main

AGENTS.md #

What this is #

Parcel tiles windows on macOS 15+: Swift 6, SwiftPM, AppKit/SwiftUI, Apache-2.0. Use Swift for core, UI, scripting/tooling (parcel-dev); small shell glue. Read CONTRIBUTING.md; real apps: Tests/Reality/README.md.

Sources/ modules; one-way dependencies in Package.swift:

  • ParcelCore: pure geometry, tile tree, layouts, commands, (State, Event) → (State, [Effect]) reducer; no AppKit/AX/clocks/IO.
  • ParcelConfig: TOML schema/defaults, line:column validation, keybinding grammar.
  • CPrivateAPI: AX C header; resolve private symbols at runtime.
  • ParcelPlatform: AX, one thread per app, window-server reads, input, permissions.
  • ParcelAnimation: springs/curves, display-link driver, latest-wins coalescing.
  • ParcelEngine: main-actor reactor: events/reducer/effects.
  • ParcelIPC: Unix socket, versioned JSON. ParcelUI: menu bar, settings, onboarding, overlays.
  • ParcelApp: composition root. prcl: CLI. FixtureApp: e2e windows. ParcelUpdate: updates.

Platform boundaries #

Use native Spaces only; never require SIP changes. Only Accessibility is required; Screen Recording is opt-in where needed.

  1. Run AX only on the owning app's thread; never block main on AX.
  2. Give every app element a 250–500 ms messaging timeout; distinguish slow, nil and dead.
  3. Write changed frames size → position → size; ignore events from our writes.
  4. Disable AXEnhancedUserInterface during writes, except with VoiceOver or Switch Control.
  5. Debounce display changes 200–500 ms; key by UUID. Handle sleep, wake and hot-plug.
  6. Reconcile missing AX notifications against the window list on activity/system changes, not an idle timer.
  7. Version learned data (including minimum sizes); make it inspectable and resettable.
  8. Surface missing private APIs, bad config and lost permission to the user.
  9. A private call returning 0 proves nothing; read back its effect before trusting it.

Code conventions #

  • Never name, quote or compare other window managers/tools anywhere in the repo, including commits/tests. Describe ideas; Scripts/check-names.sh guards names.
  • Borrow only MIT/BSD/Apache-2.0/Zlib code/dependencies; no GPL or source-available. Record borrowing in NOTICE.
  • Load .agents/skills/: write-swift before Swift work/reviews (concurrency/testing/performance); swiftui-pro for SwiftUI. .claude/skills/ links there.
  • Keep strict concurrency warning-free. Crash or surface errors; no silent try?, force casts or Any soup; force unwraps only in tests.
  • Terse, conversational docs; few comments explain why.
  • Route motion through ParcelAnimation: windows glide; chrome springs with small overshoots, never robotic/linear. Honour Reduce Motion automatically and motion-off.
  • Configure every product shortcut; hard-coded chords only in the defaults table.
  • Make accessibility/i18n first-class: VoiceOver labels, keyboard reachability, Reduce Transparency, Increase Contrast. User strings belong in String Catalogs.

Workflow #

  1. Work only in assigned worktree/files; minimise/report outside edits. Raise blockers; keep scope.
  2. mise trust && mise run setup. Commit small steps: mise exec -- git commit -s, short plain messages. No AI attribution anywhere.
  3. Check GUI/config/CLI/IPC and reverse/recovery paths; isolate test data/processes. Report results/tests/decisions/follow-ups.
  4. Clean up when done; a full disk stops everyone. Each worktree build is 1–5 GB.
    • Before heavy work: df -h /. Under 20 GB free, clean first and say so.
    • Scratch builds go inside your worktree (.build/<name>), never /tmp/*-build; temp dirs via mktemp -d with a trap 'rm -rf "$work"' EXIT.
    • Finished: commit, then rm -rf .build build (or mise run clean) in your worktree, delete .build/<scratch> dirs as soon as they're spent, and remove your ${TMPDIR:-/tmp} leftovers (ls -dt /tmp/parcel-* /tmp/*-build).
    • Quit what you launched: Parcel, FixtureApp, reality driver, headless browsers, swift test/caffeinate children (pgrep -fl 'Parcel|FixtureApp|swift-test|chrome-headless'). Restore VoiceOver/settings you changed; release the screen lock.
    • Delete test state you wrote under ~/Library/Application Support/dev.vinnymac.parcel, ~/.config/parcel or defaults; prefer isolated paths so there's nothing to delete.
    • After merge, the owner removes the worktree and branch: git worktree remove <path> && git branch -d <branch>, then git worktree prune.
    • Report what you removed and anything you couldn't.

Testing while iterating #

Test every change: Swift Testing (import Testing) for pure logic; window changes need a reality scenario that reads real frames back, or Tests/ParcelE2ETests driving FixtureApp. Extend fitting cases. Format touched Swift first. Gates:

mise exec -- swift build --build-tests
mise run test && mise run lint && mise run test:scripts
make app
  • mise run is primary; make wraps it. Lint: strict format, safety, names, shell/workflows. Script tests: tooling and all Scripts/tests/*.sh.
  • Unit: mise run test, no live windows/benchmarks. swift test discovers all targets; e2e skips once, no launch, unless PARCEL_E2E=1.
  • E2e: Scripts/screen-lock.sh mise run e2e (or make e2e), full target; preflight fails without grant. PARCEL_E2E_PREFLIGHT_ONLY=1: grant only. Only build/Parcel.app needs Accessibility; runner needs neither it nor Screen Recording. Quit your Parcel; harness won't control/quit it. Launch through harness; fixture windows, never yours.
  • Reality: mise run reality locks; real apps, debug-only helper inheriting Parcel's grant. Frames need no Screen Recording. All live lanes (fixture/first-light/tour too) must use Scripts/screen-lock.sh.

Glossary #

Windows and geometry #

Term Meaning
Tile A tile-tree leaf: one layout slot containing a stack, not necessarily one window.
Stack Ordered windows sharing a tile frame, with one selected/front member; others are not automatically minimized.
Workspace Parcel's layout/membership state for a display–native-Space pair; not an emulated desktop.
Space A native macOS Space; desktop command numbers are not internal Space IDs.
Display A UUID-identified screen with full and usable bounds.
Suspended display A connected display whose placement is temporarily withheld while Space/system state is unsafe or unverified; not a disconnected screen.
Managed window Retained in Parcel's management state; may be tiled or floating.
Floating window Managed but excluded from the tile tree; not necessarily always on top.
Ignored window Observed/classified but excluded from management; not closed.
Window cap Limit on tile slots, not total windows; overflow stacks or floats. Config/CLI 0 means unlimited.
Layout The strategy partitioning tile geometry; distinct from a workspace or Space.

Product behavior #

Focus, No peek and Clean Space are independent, per-workspace modes.

Term Meaning
Focus Temporarily expands/raises the selected tiled window into usable bounds minus reserved edges/outer gaps, preserving layout; not keyboard focus, fullscreen or macOS Focus.
No peek Dims background around the focused window and protected auxiliaries, with optional blur; no rearrangement or Screen Recording.
Clean Space Opaque backdrop concealing background clutter around protected windows; does not close windows or empty the Space.
Automatic tiling Event-driven placement. The menu switch turns it off; then nothing moves on its own, but explicit commands still do.
Retile Rebuild and reapply the current arrangement without changing the layout; works while Automatic tiling is off.

Live tests and feedback #

Term Meaning
Reality lane Opt-in real-app acceptance checks; verifies frames independently through the window server, not Parcel's model.
FixtureApp Controllable AppKit app supplying real native test windows, including slow/clamped resize and panels; not a mock.
Reality driver Socket-controlled helper embedded only in reality-enabled debug Parcel bundles; inherits its directly spawning host's Accessibility grant.
Screen lock Shared filesystem mutex serializing live lanes (Scripts/screen-lock.sh); not the macOS session lock.
Echo A notification attributable to Parcel's own frame write, suppressed to prevent feedback loops; not a user-origin event.
Readback Observing an operation's effect after the call, not trusting its status; may establish refusal rather than success.
Quirk An app/window-specific handling exception or capability, coded or learned; distinct from a user rule.