Skip to content

feat(island-downloads): download progress beside the camera island - #548

Open
nikoelt wants to merge 10 commits into
mactools-app:mainfrom
nikoelt:pr/island-downloads
Open

nikoelt wants to merge 10 commits into
mactools-app:mainfrom
nikoelt:pr/island-downloads

Conversation

@nikoelt

@nikoelt nikoelt commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Builds on #546: its commit comes first in this branch, so please review this after it. Closes #544.

Problem and result

A download's progress is hidden in the browser window. On the MacBook Pro with the camera island, this opt-in plugin:

  • Shows an arrow and percentage on either side of the island while a file downloads into a folder the person chooses.
  • Lists the last 24 hours on a Downloads page in the panel.
  • Posts a notification when a file finishes. Clicking it shows the file in Finder.

Changes

  • New plugin Plugins/IslandDownloads:
    • Watches the chosen folder (remembered as a bookmark) and in-flight Progress publications.
    • Measures free menu bar space through Accessibility on its own queue, so the progress never covers a menu or status item. Its menu bar observations are registered and removed on that queue too, with a 0.25-second timeout.
    • Nothing is watched until a folder is chosen, and notification permission is asked for only then.
    • A download of unknown size that stops being published without being cancelled counts as finished when its final file is new or changed.
  • Scope and safety:
    • Runs only on the camera island with macOS 27; off everywhere else.
    • Uses no network, and reads no file contents.
    • Builds as Swift 6 with strict concurrency.
    • Translated into all 12 languages.
  • Licensing: adapted from Vorssaint (GPL-3.0-or-later). The source, revision and paths are recorded in ThirdPartyNotices/manifest.json, and the license text is added.
  • Depends on fix(app): keep Spotlight, Shortcuts and notification clicks from opening Settings #546, which makes MacTools show a notification's file when it is clicked rather than opening Settings, so minHostVersion is 2.2.4.

Verification

  • DownloadIslandLayoutTests (only free menu bar space is used) and NotchDownloadCompletionTests (unknown-size completion, an unchanged existing file, cancelled and known-size downloads), within the full XCTest suite: pass, 3,331 tests, 0 failures (6 skipped by upstream's own settings)
  • make script-tests, including the third-party notices tests: pass (changelog, localization, website data, backup inventory, and 275 tooling tests)
  • Checked by hand on the camera-island MacBook Pro, before the review fixes: progress beside the island while a 1 GB file downloads, never over menus, and the finished notice.
  • Not yet checked by hand: the Downloads page with an entry, and the finished notification revealing the file.
  • Not checked on another Mac: none was available. The plugin turns itself off unless the Mac runs macOS 27 and the built-in display's cutout is the island's shape.

UI evidence

Progress beside the island, clear of the menus:

Progress beside the island

Progress while downloading
Full-quality video

Progress finishing
Full-quality video

The finished notice:

The finished notice

Captured during a real download of a public 1 GB test file. The recordings are built from rapid stills.

Checklist

  • Core behavior and relevant risks are verified using existing tests, focused additions, or manual checks; results or limitations are recorded.
  • UI evidence is attached where applicable; shared components, themes, localization, and accessibility are respected.
  • User-facing documentation and changelog fragments are updated when required.
  • Plugin metadata, runtime contracts, action policies, and minimum-host compatibility agree.
  • Licensing and third-party notices are complete; no credentials, local configuration, or unrelated generated files are included.

🤖 Generated with Claude Code

nikoelt and others added 2 commits November 17, 2026 17:09
An opt-in plugin for the MacBook Pro camera island (macOS 27): an arrow
and percentage show on either side of the island while a file downloads
into a folder the person chooses, never over a menu or status item; a
Downloads page in the panel lists the last 24 hours; and a notification
says when a file finishes, showing it in Finder when clicked.

Adapted from Vorssaint (GPL-3.0-or-later), recorded in the third-party
notices. Builds as Swift 6, uses no network, and stays off on every
other Mac.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ng Settings

Spotlight and Shortcuts run MacTools actions through the system App
Intents service (linkd), which reopens the app and later asks it to quit.
Neither is a person asking for Settings, and quitting stopped features
such as Keep Awake; MacTools now ignores both. A click on one of MacTools'
own notifications also reopens the app: it no longer opens Settings, and
a notification that names a file (a finished download) shows that file
in Finder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ggbond268

Copy link
Copy Markdown
Collaborator

Thanks for the work on this! I reviewed 4381e19 and recommend fixing these three issues before merging:

  1. AX listener setup and cleanup can block the host UI. Observer registration and removal still run on the main actor, and the new application element has no explicit short timeout. A slow or unresponsive MenuBarAgent can therefore stall MacTools and other plugins. Please move these operations to the AX background queue, set short messaging timeouts, and prevent stale setup results from reattaching after shutdown.

  2. Unknown-size downloads can miss their completion notification. When totalUnitCount is zero, the finished flag stays false, and unpublishing reuses the same check. Without a separate completion announcement or an observed partial-file rename, a finished file can receive no completion event. Please add an unknown-size completion path using cancellation state and verified final-file evidence, while preserving the checks against unrelated existing files.

  3. Startup does not follow the stated device and folder-selection requirements. Activation starts watching the default Downloads folder and requests notification permission before a folder is chosen, including on unsupported Macs; only the progress indicator is hardware-gated. Please apply the support check before starting the service, and wait for the user to choose a folder before monitoring it and requesting notification permission.

The existing layout tests and temporary-file boundary checks pass. I reproduced the unknown-size completion issue with synthetic Progress objects and temporary files. The main-thread and startup issues were confirmed from the code; no system-service hang was induced.

nikoelt and others added 6 commits November 18, 2026 19:29
Registering and removing the menu bar observations messages MenuBarAgent,
so it now runs on the plugin's AX queue with a 0.25-second timeout instead
of on the main thread. Only the callbacks arrive on main. A setup that
finishes after a stop is undone rather than attached, and one that fails
is tried again on the next start.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The delegate was set when the runtime started, after instance
coordination, so a click on a notification that launched MacTools could
arrive with no delegate and the file was not shown. It is now set in
applicationWillFinishLaunching, as Apple requires; the click handler
needs nothing from the runtime.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The delegate was set when the runtime started, after instance
coordination, so a click on a notification that launched MacTools could
arrive with no delegate and the file was not shown. It is now set in
applicationWillFinishLaunching, as Apple requires; the click handler
needs nothing from the runtime.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…older

Activation started watching ~/Downloads and asked for notification
permission on any Mac. Now nothing runs and the plugin reports itself
unavailable unless the camera island with macOS 27 is present (support is
remembered, so a closed lid doesn't stop it, and checked again when screens
change). No folder is watched until one is chosen, and notification
permission is asked for only once a folder is chosen and completion
notices are on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A publisher that never knows a download's size (Firefox reports a total
of 0) never marks it finished, so unpublishing it gave no completion. A
download of unknown size that is unpublished without being cancelled has
now ended; the file at its destination still decides whether it finished,
as for any download: new or changed there, and not a partial file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Clicking a completion notice shows the file in Finder only on a host with
the notification handling from the app-system-events change, which no
released host has yet; the minimum host is now the next one, 2.2.4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nikoelt

nikoelt commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, all three are addressed:

  1. AX on the main thread. Registering and removing the menu bar observations now runs on the plugin's AX queue with a 0.25-second messaging timeout; only the callbacks arrive on main. A setup that finishes after a stop is undone rather than attached, and a failed one is retried on the next start. (bc71958)
  2. Unknown-size completion. A download of unknown size that is unpublished without being cancelled has now ended; the file at its destination still decides, as for any download: new or changed there, and not a partial file. The existing baseline checks are unchanged. (f6eda0e)
  3. Startup gating. Nothing runs, and its widget reports itself unavailable, unless the camera island with macOS 27 is present. Support is remembered once seen, so a closed lid doesn't stop it, and checked again when screens change. No folder is watched until one is chosen, and notification permission is asked for only once a folder is chosen and completion notices are on. (5f54dcf)

Also: the #546 delegate fix is on this branch too (95e7305), and minHostVersion is 2.2.4, since clicking a completion notice depends on it. (61c1f7a)

Tests: new unit tests with synthetic Progress objects and temporary files cover the unknown-size completion, an unchanged existing file, and cancelled or known-size downloads. The plugin's tests and the full XCTest suite pass on the branch (3,266 tests, 0 failures; 6 skipped by upstream's own settings), and make script-tests passes.

@nikoelt

nikoelt commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Follow-up: this branch had a merge conflict with main. I merged the current main, through the updated #546 branch, into it. The only conflict was docs/plugins/preferences-backup-inventory.md, regenerated with scripts/plugins/generate-preferences-backup-inventory.py. The full XCTest suite passes on the merged branch (3,331 tests, 0 failures; 6 skipped by upstream's own settings), and make script-tests passes.

@ggbond268

Copy link
Copy Markdown
Collaborator

Thanks for the updates! I rechecked e0de6d5 and confirmed the three previous issues are addressed: AX listener setup/cleanup now runs off the main thread with a timeout, unknown-size completion uses final-file evidence, and monitoring/notification permission wait for a supported device and an explicitly chosen folder.

One layout issue remains with long folder names. At a 320 pt widget width, the folder menu pushes the “Downloads” title out and extends beyond the right edge. I reproduced this with an offscreen preview using synthetic data. The menu's .fixedSize() prevents it from shrinking, so the existing middle truncation cannot take effect.

Please remove the horizontal fixed sizing, constrain the menu to the available header space, and reserve room for the title. Keep middle truncation and the full folder name in the tooltip.

Please also use PluginTypography and pluginComponentTheme.text for ordinary widget text and neutral foreground colors, replacing hardcoded font sizes and the separate black/white agentInk styling. This will keep the Downloads page consistent with the rest of MacTools and its selected theme.

Thanks again for addressing the earlier feedback!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] Show download progress beside the Dynamic Island

2 participants