Imported from csxq0605/macos-live-app-previews (AGENTS.md). Install upstream with npx skills add csxq0605/macos-live-app-previews. Copyright stays with the author.

PaneFlow Engineering Guide

PaneFlow is a lightweight, local-first macOS window preview and switching utility. It runs as a menu-bar application (LSUIElement: true) and combines SwiftUI settings with AppKit window, Dock, accessibility, and capture integration.

Platform and toolchain

• Swift 5.10.
• macOS 13.0 minimum for the application target.
• SwiftUI for settings and preview content; AppKit for panels, menus, Dock integration, and window lifecycle.
• Accessibility APIs for window discovery and actions; ScreenCaptureKit for window thumbnails and live previews.
• Build, test, and run through the root Xcode project only. Do not introduce SwiftPM as an alternative application build or use command-line xcodebuild for routine project work.
• The installed local build lives at /Users/csxq/Applications/PaneFlow.app.

Product invariants

• Product display name: PaneFlow.
• Bundle identifier: dev.csxq.PaneFlow.
• Development team: C9D38MC4JM.
• Signing identity: Apple Development: suwangjie.mun@foxmail.com (Z5BUQ95YC2).
• Preserve the fixed development signature. Do not replace it with ad-hoc signing; stable signing is required for persistent Accessibility and Screen Recording permissions.
• Keep the app local-first: no analytics, accounts, cloud sync, automatic updater, public promotion, or hidden network fallback.
• The only intentional product link is the personal repository configured in the local information view.

Versioning

• PaneFlow owns an independent version sequence. Do not reuse or inherit version numbers from any upstream project.
• The initial PaneFlow release is marketing version 1.0.0 with build number 1.
• Use semantic versioning for MARKETING_VERSION: increment the patch component for fixes, the minor component for backward-compatible features, and the major component for incompatible product changes.
• Keep CURRENT_PROJECT_VERSION as an integer build number and increment it for every newly installed or distributed build, including rebuilds of the same marketing version that need to be distinguished.
• Keep Debug and Release values synchronized in PaneFlow.xcodeproj/project.pbxproj.
• The local information view must read the marketing version from the application bundle rather than containing a hard-coded version string.
• Any version change must update the project-level version regression test, build through Xcode, and verify CFBundleShortVersionString and CFBundleVersion in both the Xcode product and /Users/csxq/Applications/PaneFlow.app.

Building and testing

1. Open the root .xcodeproj in Xcode.
2. Select the application scheme and My Mac destination.
3. Use Product → Build or Cmd+B to build.
4. Use Product → Test or Cmd+U to run the complete test target.
5. Use Product → Run or Cmd+R for runtime checks.

When replacing the installed app, copy the successful Xcode product to /Users/csxq/Applications/PaneFlow.app, register it with LaunchServices, verify its signature, and confirm the installed executable hash matches the Xcode product.

Adding Swift files

Every new .swift file must be registered in the root Xcode project's project.pbxproj.

1. Generate one UUID for PBXFileReference and one for PBXBuildFile.
2. Add the PBXFileReference with the correct path and file type.
3. Add the PBXBuildFile referencing that file.
4. Add the file reference to the correct PBXGroup.
5. Add the build file to PBXSourcesBuildPhase for the application target.
6. Confirm the file appears in Xcode and participates in the intended target.

Do not create new source files without completing all six steps.

Preferences and settings search

All user preferences are declared in consts.swift under extension Defaults.Keys.

Every new or renamed setting must be searchable:

1. Add .settingsSearchTarget("tab.settingName") to the control.
2. Add a matching SettingsSearchItem to Views/Settings/Search/SettingsSearchCatalog.swift.
3. Use the exact same identifier in the control and catalog.
4. Use String(localized:) with the exact view literal for the catalog title and description.
5. Keep catalog keywords as internal English search tokens.
6. If the six-page information architecture changes, update the merged destination mapping in SettingsView.swift and SettingsSearchEngine.swift.

The maintained settings destinations are Overview, Dock Preview, Window Switching, Widgets & Filters, Appearance, and Advanced. Do not reintroduce separate legacy destinations when a feature belongs in one of these merged pages.

Theme CSS

• ThemeCSS.swift is the only parser for imported theme files.
• Imported CSS is a safe token format, not executable web CSS.
• Reject selectors outside the supported root blocks, imports, URLs, scripts, unknown properties, malformed colors, and out-of-range values.
• Theme values must continue to drive both the settings console and preview surfaces.
• Preserve System, Light, and Dark appearance selection with Porcelain Flow and Midnight Flow defaults.
• Any new theme preference must be declared in Defaults and indexed in settings search.

Privacy and permissions

• Accessibility permission is used for Dock hover detection, window discovery, focus, window actions, and switcher shortcuts.
• Screen Recording permission is used for thumbnails and live previews; compact text-only behavior must remain available without it.
• Calendar permission is optional and used only when the calendar widget is enabled.
• Do not transmit window titles, thumbnails, calendar data, media data, file listings, or user settings off-device.
• Permission changes must be verified against the installed fixed-signature app, not an Xcode project file or ad-hoc bundle.

Localization

• Use String(localized:comment:) for user-facing strings where context helps translators.
• Do not edit Localizable.xcstrings manually; it is managed by the localization workflow.
• Maintain macOS 13 compatibility. Use the single-parameter onChange { newValue in } form.
• Keep personal settings copy consistent in Chinese and avoid introducing untranslated English UI accidentally.

Code structure

• UI state belongs in coordinators or focused models, not in large views.
• Window operations go through WindowUtil static methods.
• Reusable settings controls belong under Views/Settings/Shared Components/.
• Keep the six-page navigation and legacy-to-merged search mapping centralized in SettingsView.swift.
• AppKit interop should remain narrow and explicit.
• Preserve menu-bar-only behavior except while the settings window is active.
• Avoid verbose comments. Comment only non-obvious platform behavior or synchronization constraints.
• Do not remove license headers from source files.

Repository identity

• PaneFlow is the only product identity permitted in tracked paths, source, tests, documentation, project metadata, and licensing.
• Do not introduce names, links, comparison copy, migration notes, or historical references belonging to upstream products.
• Keep the repository identity regression test enabled. It must continue to scan tracked paths and tracked UTF-8 content for the retired product token without storing that token literally in the repository.
• Keep docs/superpowers/ local and ignored. Development plans and specifications from that directory must never be committed or uploaded.

Key modules

Verification requirements

• Run the complete Xcode test target after code or project changes.
• Run plutil -lint on a modified project.pbxproj and git diff --check on all edits.
• Verify the final application with codesign --verify --deep --strict and inspect its identifier, authority, team, and designated requirement.
• Confirm the installed app runs from /Users/csxq/Applications/PaneFlow.app and displays no permission warning after authorization.
• Use Computer Use to inspect every affected settings destination and capture screenshots for visual changes.
• For theme changes, verify Porcelain Flow, Midnight Flow, System mode, valid CSS import, reset behavior, and invalid CSS rejection.
• Never claim completion from source inspection alone; use fresh build, test, signing, installed-runtime, and UI evidence appropriate to the change.