Skip to content

Align Semper roadmap and feature status for utility expansion #103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
niharnm merged 2 commits into from
Sep 9, 2026
Merged

Align Semper roadmap and feature status for utility expansion #103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
334d335
Align product roadmap with multi-utility delivery
niharnm Sep 9, 2026
9c6e91f
Complete shared release gate requirements
niharnm Sep 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@
<a href="https://github.com/niharnm/Semper/graphs/contributors"><img src="https://img.shields.io/github/contributors/niharnm/Semper" alt="Contributors"/></a>
</p>

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/)

Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand Down
160 changes: 106 additions & 54 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Comment thread
niharnm marked this conversation as resolved.
- 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
Expand All @@ -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.
77 changes: 77 additions & 0 deletions guide/product-status.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# 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, 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:

- 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.
Loading