Home

Setpiece Wiki

Setpiece is a macOS 14+ menu bar app that arranges every visible window into a preset or user-defined layout via click, hotkey, or the settings window. V0.4 adds Workspaces — one-click context switchers that bundle a layout, apps to launch/quit, Focus mode, and auto-triggers (monitor connect, time-of-day, calendar event).

This wiki covers how to develop, ship, and extend Setpiece. End-user installation lives in the main repo README and docs/INSTALL.md.

繁體中文版本： 首頁

What's in v0.4

• Workspaces (headline) — bundle layout + apps + Focus mode + auto-triggers. 4 seeds (Coding / Meeting / Reading / Streaming) bound to ⌘⌥1–4. 5 trigger types: manual, monitor connect/disconnect, time-of-day, calendar event.
• 10 layout presets — the original 7 (Full / Halves / Thirds / Quads / Main + Side / LeftSplit + Right / Left + RightSplit) plus 3 V0.4 vertical seeds (Main + Side Vertical / Halves Vertical / Thirds Vertical) on ⌘⌃8 / ⌘⌃9 / ⌘⌃0. Default hotkeys moved from ⌘⇧ to ⌘⌃ to dodge macOS screenshot shortcuts (⌘⇧3/4/5).
• Layout thumbnails — every layout reference in the menu bar and Settings renders a live mini-preview of its slot proportions.
• Multilingual UI — full English + 繁體中文(港); partial 繁體中文(台) + 日本語. 133 string keys in Localizable.xcstrings.
• Drag-to-swap (from V0.3) — drag any placed window onto another to swap; hold ⌥ to free-move, Esc to cancel.
• Smooth animation (from V0.2) — position+size interpolation with adjustable duration (100–500ms) and easing.
• Custom layouts + hotkeys (from V0.2) — 11 grid templates, block-save hotkey conflict policy covering both Layouts and Workspaces.

Pages

• Architecture — why SceneCore + SceneApp are split, where each concept lives (V0.2 Animation/Settings, V0.3 Interaction, V0.4 Workspace + Triggers), coordinate convention.
• Development Setup — get a working checkout: Xcode, swift test (157 tests), running under debugger.
• Contributing — branching model, TDD workflow, Conventional Commits + Co-Authored-By trailer, PR expectations.
• Release Process — cut a new version: tag, DMG (./scripts/build-dmg.sh 0.4.0), GitHub Release, smoke test.
• Roadmap — V0.2/V0.3/V0.4 shipped items and V0.5 candidates.
• Troubleshooting — common build/runtime issues + fixes (AX permission running-process cache, TCC cdhash quirk after rebuild).
• FAQ — design choices, macOS quirks, hotkey reassignment rationale, licensing notes.

Quick links

• Latest release: v0.4.0 — Workspaces, thumbnails, vertical seeds, multilingual UI (bundles V0.2 + V0.3 + V0.4)
• Issue tracker: Issues
• Core library tests: swift test — 157 tests, no Xcode required