# 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/`), 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/` 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 && git branch -d `, 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: ```sh 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. |