From 334d33597036909918ee57f502312fd9c546fc09 Mon Sep 17 00:00:00 2001 From: Nihar <117209695+niharnm@users.noreply.github.com> Date: Wed, 9 Sep 2026 08:54:17 -0700 Subject: [PATCH 1/2] Align product roadmap with multi-utility delivery --- README.md | 12 ++- ROADMAP.md | 160 ++++++++++++++++++++++++++-------------- guide/product-status.md | 74 +++++++++++++++++++ 3 files changed, 191 insertions(+), 55 deletions(-) create mode 100644 guide/product-status.md diff --git a/README.md b/README.md index 7c5ab30..0c0bf5a 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,9 @@ Contributors

-Native macOS utilities in one menu bar app. Sound provides independent app volume, output routing, ISO 226 equal-loudness compensation, and AutoEQ headphone correction. Awake requests that macOS prevent automatic idle sleep for a chosen duration. Away covers each display with a customizable privacy curtain and requires Mac authentication or a Semper PIN to exit. External Displays provides supported brightness, contrast, volume, and input controls, while Scenes group reversible settings. +Control windows, files, displays, power, and sound from one native macOS menu bar app. Add the utilities you need, use them independently, or combine settings with Scenes and Presentation. Away provides an authenticated privacy curtain. + +The current download, v1.0.0, contains Sound. The other modules are integrated in this repository and are in development toward the next release. The [product status guide](guide/product-status.md) records each module's state. [semper.systems](https://www.semper.systems/) @@ -34,6 +36,10 @@ Semper is an open-source project founded and led by [**Nihar Manchikakapudi**](h Open the disk image and drag **Semper** into **Applications**. Requires macOS 15.4 or later. +The current release is v1.0.0, published 2026-08-26, and contains the Sound +utility. The other modules described above are not in this download; building +from source runs current development code. + With [Homebrew](https://brew.sh): ```bash @@ -115,6 +121,10 @@ in your keychain so macOS can recognize later source updates as the same app. ## Documentation & Guides +- [Product Status](guide/product-status.md) +- [Module Shell](guide/module-shell.md) +- [Direct Utilities: Workspace Restore, File Shelf, Safe Eject](guide/direct-utilities.md) +- [Awake Sessions](guide/awake-sessions.md) - [URL Schemes](guide/url-schemes.md) - [App Shortcuts](guide/app-shortcuts.md) - [Experiments](guide/experiments.md) diff --git a/ROADMAP.md b/ROADMAP.md index 1627d01..32fac9e 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,63 +1,111 @@ # Semper roadmap -Semper publishes signed macOS releases. This roadmap describes the work needed -to keep distribution dependable and grow the project without hiding -experimental behavior. +Semper is one menu bar app with nine utility modules: Sound, Awake, Displays, +Workspace Restore, File Shelf, Safe Eject, Scenes, Away, and Presentation. All +nine are integrated on `main`. The downloadable release is v1.0.0, which +contains Sound only. This roadmap orders the work to deliver the whole suite as +dependable signed releases without hiding experimental behavior. Per-module +state lives in the [product status guide](guide/product-status.md). ## Current priorities -### 1. Release maintenance - -- Test signed and notarized builds on a clean Mac before publication. -- Verify install, permission, relaunch, update, and uninstall behavior for each - release. -- Publish accurate release notes and known device limits. -- Keep the website, README, Homebrew cask, and update feed tied to the same - release artifact. - -### 2. Modules and utility foundation - -- Keep Sound and Awake independent while they share the same menu bar shell. -- Add new utilities only when they have a clear local use case and no hidden account requirement. -- Keep module actions testable without live audio or power-management side effects. - -### 3. Audio reliability - -- Add focused tests around tap lifecycle, crossfades, output gating, and device - reconnect behavior. -- Collect reproducible reports for apps with custom audio engines. -- Preserve real-time callback safety and resource teardown order. - -### 4. Device compatibility - -- Record verified behavior for built-in, Bluetooth, USB, HDMI, DisplayPort, - DDC, aggregate, and virtual devices. -- Improve handling for devices that report controls they do not actually - support. -- Document where software volume or ignored-app behavior is the correct - fallback. - -### 5. Interface and accessibility - -- Audit keyboard navigation, focus order, VoiceOver labels, contrast, reduced - motion, and visible capability states. -- Keep the menu-bar popup and settings behavior consistent. -- Add tests for state transitions that do not require live audio hardware. - -### 6. Contributor documentation - -- Keep starter issues small, testable, and unclaimed until someone begins. -- Add architecture notes for high-risk audio paths. -- Turn verified device reports and recurring support answers into guides. +### 1. Ship the integrated multi-utility suite + +- Complete native acceptance of the integrated build: signed clean-Mac install, + real permission prompts, hardware behavior, accessibility, update, and + uninstall. The [status guide](guide/product-status.md) records the gates. +- Publish the next release only when the website, README, release notes, + Homebrew cask, and update feed describe the same artifact. +- Keep the released-versus-development boundary explicit everywhere. + +### 2. Shell, navigation, permissions, and lifecycle + +- Keep one predictable shell: Home summaries, action search, favorites, and + module add, pause, resume, and remove. +- Adding a module must continue to start no service and request no permission. + First explicit use creates the runtime and states its permission reason. +- Denied or revoked permissions, limited runtimes, and failed cleanup stay + visible with a recovery path. Quit drains composed sessions before the + services they use. See the [module shell guide](guide/module-shell.md). +- Finish the current interaction gaps first: keyboard-accessible file selection + in File Shelf and cancellation while Presentation prepares or starts. + +### 3. Window Layout + +The next planned increment. It is not implemented today. + +- Manual placement commands: left half, right half, maximize to the usable + screen area, center, and restore the last placement. +- Built in its own branch on the existing Workspace Restore window helpers. +- Manual actions only: no automatic tiling and no window watching. +- Preserve the intended window when the menu bar takes focus. Verify each + placement and keep later manual adjustments intact when restoring. +- Test half and maximized windows through later center and restore actions + without weakening Workspace Restore's fullscreen protections. + +### 4. Cross-module workflows + +- Scenes and Presentation compose the other modules: preview before apply, + verified writes, reverse-order recovery, and visible partial failures. +- Composition stays a feature, not a requirement. Every module must remain + useful on its own. + +### 5. Module depth guided by user jobs and reuse + +- Sound and Displays: grow verified device compatibility and document correct + fallbacks for devices that misreport controls. +- Workspace Restore: arrangement reliability across displays, Spaces, and + restarts. +- File Shelf and Safe Eject: behavior improvements from reproducible reports, + keeping original files and volumes safe. +- After File Shelf's file picker, add **Resize Image Copy** for one selected + local JPEG or PNG. Offer 1024 or 2048 pixels on the longest edge without + enlargement, show output dimensions, and save a separate copy. Preserve + orientation, color and transparency, explain metadata handling, and support + cancellation. No batch processing, uploads, or original-file replacement. +- Awake and Away: keep power assertions and the curtain testable and honest + about what they do not block. +- A new utility needs a clear local user job, no account requirement, the + shared lifecycle and disclosure rules, and reuse of existing services where + reasonable. + +### 6. Quality, accessibility, and contributor documentation + +- Preserve real-time audio callback safety. Add focused tests around tap + lifecycle, crossfades, output gating, and device reconnect behavior. +- Audit keyboard navigation, focus order, VoiceOver labels, contrast, and + reduced motion across all module surfaces. +- Turn verified device reports and recurring support answers into guides, and + keep starter issues small, testable, and unclaimed until someone begins. + +## Reference utilities + +Focused specialist tools set the expectations each Semper module must meet: + +- [Rectangle](https://github.com/rxhanson/Rectangle) for window placement +- [MonitorControl](https://github.com/MonitorControl/MonitorControl) for + external display control +- [Amphetamine](https://apps.apple.com/us/app/amphetamine/id937984704) for + awake sessions +- [Dropover](https://dropoverapp.com/) for a file shelf +- [Vorssaint utilities](https://github.com/vorssaint/vorssaint-utils) for a + broad free modular suite +- [FineTune](https://github.com/ronitsingh10/FineTune) for per-app audio with + AutoEQ and ISO 226 loudness compensation + +Semper has not benchmarked against these tools and claims no superiority. The +case for Semper is one shell with shared lifecycle, disclosure, and recovery +rules, and modules that can work together. ## Contribution levels - **Starter:** documentation, pure-function tests, accessibility labels, and isolated UI state. - **Intermediate:** parser behavior, settings state, device classification, - and failure recovery with tests. -- **Advanced:** process taps, aggregate devices, HAL callback code, crossfades, - DSP lifecycle, and output safety. + module lifecycle transitions, and failure recovery with tests. +- **Advanced:** process taps, aggregate devices, HAL callback code, DSP + lifecycle, DDC transport, Accessibility window operations, Disk Arbitration, + power assertions, and curtain input filtering. Use [good first issues](https://github.com/niharnm/Semper/contribute) for a first pull request. Advanced work should begin with a GitHub issue or @@ -66,11 +114,15 @@ discussion and include a hardware test plan. ## Current boundaries - Supported platform: macOS 15.4 or later. -- Available today: Sound controls, timed or indefinite Awake sessions, source - builds, unit tests, the static website, and signed macOS releases through - GitHub and Homebrew. +- Downloadable today: v1.0.0, published 2026-08-26, with Sound. Source builds, + unit tests, the static website, and signed releases through GitHub and + Homebrew are current. +- Integrated on `main` and in no download yet: Awake, Displays, Workspace + Restore, File Shelf, Safe Eject, Scenes, Away, and Presentation. +- Planned additions: Window Layout and File Shelf's Resize Image Copy action. - Hardware-dependent: process taps, device routing, DDC, Bluetooth call mode, - media keys, and permission behavior. + media keys, Accessibility window operations, volume ejection, and permission + behavior. - Release-dependent: automatic updates require a current signed feed, and broad - device compatibility claims require verified hardware reports. + compatibility claims require verified hardware reports. - Out of scope today: Windows, Linux, iOS, cloud accounts, and audio recording. diff --git a/guide/product-status.md b/guide/product-status.md new file mode 100644 index 0000000..8145386 --- /dev/null +++ b/guide/product-status.md @@ -0,0 +1,74 @@ +# Semper product status + +Semper is one menu bar app with nine utility modules. This page is the shared +record of what each module does, where it stands, and what remains before +release. It changes in the same commit as the work that changes a status. + +Snapshot: `main` at fb9a3d5, 2026-09-09. Latest downloadable release: v1.0.0, +published 2026-08-26, containing Sound only. + +## States + +- **Released**: included in a published signed release users can download. +- **Integrated**: merged on `main` in the shared shell with automated tests. + Not included in the public binary release; native acceptance remains separate. +- **Planned**: agreed scope with no implementation on `main`. + +## Modules + +| Module | User job | State | Remaining before release | Evidence | +| --- | --- | --- | --- | --- | +| Sound | Control app and device audio: per-app volume, output routing, EQ, equal-loudness compensation | Released, v1.0.0 | Later Sound changes remain subject to the next release's shared acceptance gates | [Source](../Semper/Audio), [AutoEQ](autoeq.md), [audio safety](realtime-audio-safety.md) | +| Awake | Keep the Mac awake for a chosen duration, with app and battery stop conditions | Integrated | Shared gates, plus assertion, expiry, and stop-condition checks on hardware | [Source](../Semper/Awake), [guide](awake-sessions.md) | +| Displays | Read and set supported external display brightness, contrast, volume, and input | Integrated | Shared gates, plus DDC checks on real displays | [Source](../Semper/Displays), [guide](module-shell.md#displays) | +| Workspace Restore | Return selected app windows to a saved arrangement | Integrated | Shared gates, plus Accessibility permission flows, multi-display, and Spaces checks | [Source](../Semper/Workspace), [guide](direct-utilities.md) | +| File Shelf | Hold temporary files, links, images, and text between apps | Integrated | Shared gates, plus drop-source, missing-file, and persistence checks | [Source](../Semper/Shelf), [guide](direct-utilities.md) | +| Safe Eject | Review removable volumes to eject and check each observed result | Integrated | Shared gates, plus disposable-drive single and batch eject checks | [Source](../Semper/Storage), [guide](direct-utilities.md) | +| Scenes | Save and apply settings across utilities together, with a restore point | Integrated | Shared gates, plus capture, apply, and recovery checks on hardware | [Source](../Semper/Scenes), [guide](module-shell.md) | +| Away | Cover every display with a privacy curtain that requires authentication to exit | Integrated | Shared gates, plus input-filter permission, authentication, and multi-display checks | [Source](../Semper/Away), [guide](module-shell.md#away) | +| Presentation | Run a timed session that applies selected display, sound, and window targets | Integrated | Shared gates, plus a full session with reverse-order recovery on hardware | [Source](../Semper/Presentation), [guide](module-shell.md#presentation) | + +## Next increments + +These changes are not on the snapshot of `main` above and are not released. + +| Increment | State | Acceptance before integration | +| --- | --- | --- | +| Presentation preparation/start cancellation | Draft [PR #102](https://github.com/niharnm/Semper/pull/102) | Visible cancellation, owned-work cleanup, recovery and failure tests, then native interaction checks | +| File Shelf Choose Files | Planned | Keyboard-accessible native selection using the existing import path; cancelled selection leaves the shelf unchanged | +| Window Layout | Planned | Manual halves, maximize, center and previous-placement restore using [Workspace helpers](../Semper/Workspace); verify target identity, constrained windows and later manual changes | +| File Shelf Resize Image Copy | Planned | Separate local JPEG/PNG copy; correct dimensions, orientation, color and transparency; original unchanged; explicit metadata policy, save failures and cancellation | + +## Shared release gates + +Integrated modules pass automated tests that use injected fixtures. Those tests +do not establish signed-install, permission, hardware, accessibility, update, +or notarization readiness. See the +[verification scope](module-shell.md#verification-scope) and the +[remaining integrated checks](direct-utilities.md#remaining-integrated-checks). + +Before an integrated module is called released, one signed build must pass on +hardware: clean-Mac install, real permission prompts including denial and +revocation recovery, module add, pause, remove, and quit with active work, +keyboard and VoiceOver access, and updater behavior. + +Binary publication also requires completed signing and notarization checks, +source-rights and third-party-notice review, and verified install, update and +rollback behavior. These are release gates, not claims that they have passed. + +## Update contract + +Status moves only with evidence, never by assumption: + +- A feature change lands with its implementation, tests, and guide updates in + the same change set. +- Integrated requires the code merged on `main`. Released requires a published + signed artifact containing it. An acceptance item is marked done only after + the check was run and its result recorded. +- The website, README, and release notes use the same verified feature states. + Planned and development work may appear before release when clearly labeled; + the download description lists only what its artifact contains. +- Whoever changes a state updates the snapshot line above in the same change. + +Passing tests alone advance nothing, and a compiled build proves compilation, +not behavior on hardware. From 9c6e91f347f74db7a4a41a86dd57df83377b4756 Mon Sep 17 00:00:00 2001 From: Nihar <117209695+niharnm@users.noreply.github.com> Date: Wed, 9 Sep 2026 09:06:08 -0700 Subject: [PATCH 2/2] Complete shared release gate requirements --- guide/product-status.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/guide/product-status.md b/guide/product-status.md index 8145386..c0fc13c 100644 --- a/guide/product-status.md +++ b/guide/product-status.md @@ -50,12 +50,15 @@ or notarization readiness. See the Before an integrated module is called released, one signed build must pass on hardware: clean-Mac install, real permission prompts including denial and revocation recovery, module add, pause, remove, and quit with active work, -keyboard and VoiceOver access, and updater behavior. +keyboard and VoiceOver access, updater behavior, and uninstall cleanup. Binary publication also requires completed signing and notarization checks, source-rights and third-party-notice review, and verified install, update and rollback behavior. These are release gates, not claims that they have passed. +Before publication, the website, README, release notes, Homebrew cask, and +update feed must refer to the same verified release artifact. + ## Update contract Status moves only with evidence, never by assumption: