macOS and iOS — plan
Niman on a Mac, an iPhone and an iPad. Written before any code (2026-10-16), as the plan the port follows, with the owner’s decisions on it at the end. Nothing here was built or run: the host this was written on is Windows, so every Apple-side statement is either read from Apple’s or a package’s documentation or marked to verify — those are what the first spike on a Mac has to settle.
Two rules from AGENTS.md shape all of it:
- The disk is the source of truth: one note is one
.mdin a folder the user owns. iOS has no such folder by default, and a sandboxed Mac app reaches one only through a grant. The storage model is the first problem, not a detail. - Every platform ships every feature, or
docs/user/platforms.mdsays why not, as a decision. Two new platforms double the surfaces a feature has to reach; the plan says per feature what each one gets.
Where the code stands
There is no macos/ or ios/ folder. The Dart code is portable by
construction (package:path, isolates, no /tmp literal, case-insensitive
path handling already counting macOS and iOS in core/files.dart), and a
platform it does not know falls through to a no-op rather than a crash.
That is the good news and the problem: on a Mac today most desktop
features would be silently off, not broken.
The platform gates
The code asks “Linux or Windows?” where it means “a desktop”, and “Android?” where it means “a phone”:
| Gate | Where | What macOS / iOS get today |
|---|---|---|
desktop = isLinux \|\| isWindows |
lib/main.dart:36 |
No single-instance claim, no launch arguments, no file-open forwarding |
| The same test, repeated | ui/shell.dart (close to tray, mouse side buttons, CommandNeed.desktop), ui/window_controller.dart, core/tray.dart, core/drop_in.dart, ui/file_tree_context.dart, ui/open_library.dart, a dozen more |
The desktop chrome, the tray, the drop, the tree’s Show in folder: all off |
createReminderService |
todo/reminders.dart:84 |
NoopReminderService: no reminders at all |
checkForUpdate |
update/update_check.dart:91 |
A Mac would be offered the Linux .tar.gz as its update — a latent bug |
phone = Platform.isAndroid |
transcription/transcription_models.dart:34 |
An iPhone would be offered every whisper model, the 3 GB one included |
packageConverts = isAndroid |
transcription/transcription_queue.dart:40 |
Non-WAV audio refused (“only WAV on this platform”) |
findPdfEngine |
export/pdf_printer.dart:198 |
No engine: the picture fallback, no folder PDF |
findPageBrowser |
capture/browser/page_browser.dart:91 |
No browser fallback for a script-built page |
| Clipboard HTML | capture/paste/platform_clipboard_html.dart |
Paste as Markdown pastes plain text |
| Keep awake | core/keep_awake.dart:30 |
Slides let the screen sleep |
| Spell check | spellcheck/hunspell_spell_checker.dart:21 |
Hunspell looked up by bare name, dictionaries in Linux folders: off |
| OCR engine | ocr/ocr_engine_build.dart:76 |
No target for the ABI: nothing to download |
Some places already list macOS (ui/todo_date_panel.dart:19,
ui/kinds/list_note.dart:197, markdown/render/focus_return.dart:93) and
others pointedly do not (ui/shell.dart’s _desktop), so the platform
answer is not even consistent across files. Touch detection is in better
shape: the defaultTargetPlatform == android || iOS checks in the editor,
the link preview and the tree drag already treat an iPhone as touch.
Native code that has to be written again
Everything Android does natively goes over a named MethodChannel; the
two desktop runners add two more. Each is a contract an Apple runner
implements, or a feature that stays off:
| Channel | Android / Linux / Windows | macOS | iOS |
|---|---|---|---|
niman/storage |
All-files access (Android) | Folder grant (bookmark) | Folder grant (bookmark) |
niman/reminders |
Battery-optimisation health (Android) | — (not needed) | — (not needed) |
niman/screen |
Keep screen on (Android, Linux; Windows by FFI) | IOPMAssertion |
isIdleTimerDisabled |
niman/clipboard |
HTML + source URL, and the copied files (#1249) (Android, Linux; Windows by FFI) | NSPasteboard (file URLs) |
UIPasteboard (item providers, copied to tmp/) |
niman/pdf |
WebView print (Android) | WebKit print | WebKit print |
niman/page_reader |
Hidden WebView (Android) | Hidden WKWebView |
Hidden WKWebView |
niman/drop |
GDK drop, OLE IDropTarget; Android View.OnDragListener (#1250) |
NSDraggingDestination |
UIDropInteraction on the scene’s view (#1250) |
niman/window |
Snap Layouts hit test (Windows) | — (native traffic lights) | — |
niman/share |
Share intents (Android) | Services menu, Open With | Share extension |
niman/shortcuts |
Launcher shortcuts (Android) | Dock menu | Home-screen quick actions |
niman/widgets |
Widget launch targets (Android) | WidgetKit (later) | WidgetKit |
niman/task |
moveTaskToBack for web capture (Android) |
— | — |
niman/update |
APK install (Android) | Opens the .dmg (direct build only) |
— (the App Store updates) |
Most of the Swift is one implementation for both. WebKit, the
pasteboard (behind a thin type switch), the bookmarks and the spell
checkers have the same shape on macOS and iOS. The plan puts them in one
local Flutter plugin in the repository (packages/niman_apple/, Swift,
sharedDarwinSource: true so one darwin/ folder builds into both
runners), not in each runner. The runners keep only what is the window’s:
the drop, the menu bar, the file-open events.
The plugins
| Package | iOS | macOS | Note |
|---|---|---|---|
drift, sqlite3 |
yes | yes | The build hooks ship a prebuilt SQLite for both, FTS5 on by default |
pdfrx |
yes | yes | PDFium as an XCFramework |
record, audioplayers |
yes | yes | NSMicrophoneUsageDescription; on a sandboxed Mac device.audio-input |
flutter_local_notifications |
yes | yes | zonedSchedule on UNUserNotificationCenter; iOS keeps 64 pending |
flutter_secure_storage |
yes | yes | Keychain; keychain-access-groups entitlement, or the legacy keychain on macOS |
file_picker |
yes | yes | Picks a directory on both, but returns a path — no bookmark, and on iOS an old issue reports a copy in a temporary folder (to verify) |
connectivity_plus |
yes | yes | NWPathMonitor; needs Xcode 26.1.1+ |
path_provider, package_info_plus, url_launcher, flutter_timezone |
yes | yes | — |
whisper_ggml |
yes (15.6+) | yes | Pulls ffmpeg_kit_flutter_new_min on Apple too (a community fork; LGPL) |
window_manager 0.5.2 |
— | yes | Close interception and the hidden title bar on macOS: to verify |
nativeapi 0.2.4 |
— | listed | “Work in progress”; a macOS tray source exists, the menu is to verify |
home_widget |
yes | no | WidgetKit on iOS through an App Group; nothing for macOS (its issue #241 closed without it) |
dynamic_color |
no | yes | The accent colour on macOS; iOS takes the fallback palette |
archive, katex_dart, html, xml, yaml, highlight |
pure Dart | pure Dart | — |
No package blocks the port. The gaps are the widgets on macOS,
dynamic_color on iOS (a fallback already exists), and the folder grant,
which no package does for a folder on iOS.
Storage: the library on Apple platforms
Today a library is an absolute path string: picked by
FilePicker.getDirectoryPath (ui/library_picker.dart:57), remembered in
knownLibraries and lastLibraryPath, read and written with plain
dart:io from worker isolates, and its index file is named after a digest
of that path (library_state.dart:1976). Each of those assumptions breaks
somewhere on Apple platforms.
macOS
-
Not sandboxed (direct distribution with a Developer ID): a path is a path. The library works exactly as on Linux,
~/Documents, an external disk and an iCloud Drive folder (~/Library/Mobile Documents/…) included. With Optimise Mac Storage on, an iCloud file may be dataless: a stat is free, the first read downloads it. A full scan only stats, so it stays cheap; opening a note waits for its download. Decided: not sandboxed (2026-10-16). The rest of this section is what a sandbox would ask, kept for the day it is wanted. -
Sandboxed (required by the Mac App Store, and by nothing else): a folder the user picked is reachable while the app runs, and across launches only through a security-scoped bookmark — bookmark data minted at the pick (
files.bookmarks.app-scopeentitlement), resolved at the next launch, opened withstartAccessingSecurityScopedResource. The grant is the process’s, so the worker isolates’dart:iosees the folder like the UI isolate does (to verify, it is how sandbox extensions work but no Flutter app was found saying so).
iOS
An iOS app owns one folder, its container, and reaches any other only through the document picker’s grant. Three places a library can live:
| Where | How Niman reaches it | For | Against |
|---|---|---|---|
The app’s Documents (shown in Files as On My iPhone › Niman with UIFileSharingEnabled and LSSupportsOpeningDocumentsInPlace) |
Plain dart:io, no grant |
Fast, every API works, nothing materialises lazily; the user and other apps see the .md files in Files |
Leaves the phone only through Niman’s WebDAV sync or a manual copy; deleting the app deletes the library |
Niman’s iCloud container (iCloud.dev.niman.niman, shown as iCloud Drive › Niman) |
dart:io under the ubiquity container URL; files may be evicted placeholders, reads need NSFileCoordinator |
The Apple user’s own sync, no server; the same folder on a Mac | Evicted files must be downloaded before a scan can read them — a 1M-note library cannot be read whole; iCloud’s conflict copies are a second conflict model beside the sync’s |
| A folder picked anywhere (iCloud Drive, On My iPhone, a File Provider such as Nextcloud) | Bookmark from UIDocumentPickerViewController, resolved at each launch, coordinated access |
The user’s own folder, the Android model | Third-party File Providers materialise files lazily and unreliably: Obsidian, which tried, documents Dropbox, Google Drive and OneDrive as not working |
The container path moves. An iOS app’s container path changes across reinstalls and can change across updates; the documentation says to keep paths relative to it. The index file named after the absolute path would be thrown away and rebuilt after such an update — a full scan of a large library for nothing. So a library on iOS is remembered as (where, relative path): the container plus a relative path, or a bookmark.
Decided: the app’s container (2026-10-16). The first iOS release keeps its libraries in its own Documents, visible in Files, and leaves the phone through Niman’s WebDAV sync. A folder picked elsewhere and Niman’s iCloud container are not in it; the abstraction below leaves room for both.
What changes in the code
One abstraction, on every platform, so the grant is not an iOS special case scattered through the library code:
LibraryLocationreplaces the bare path inknownLibraries: a path (Linux, Windows, Android, unsandboxed macOS), a container-relative path (iOS), or bookmark data (sandboxed macOS, a picked folder on iOS). The bookmark is device state that cannot be rebuilt from disk, so it lives inAppDatabasebeside the known libraries — the same exception the sync’s state already makes (docs/records/sync.md, Principles). With macOS unsandboxed and iOS in its container (both decided), the first round needs the first two kinds only; the bookmark is the kind a later sandbox or picked folder adds, and nothing else changes when it does.- Opening a library resolves its location to a path and holds the grant
until the library closes. Everything after that point — the scan, the
watcher,
NoteOps, the sync — keeps working on a path, unchanged. - The index file is named after the library’s identity, not its
absolute path: the location’s stable part, so an iOS container move does
not orphan it. (
IndexDatabaseis rebuildable, so getting this wrong costs a scan, never data.) - A stale bookmark (the folder moved or was renamed) is refreshed when it resolves as stale, and a bookmark that no longer resolves sends the library to the picker with its name, as a missing folder does today.
File watching and the rescan
- macOS:
Directory.watch(recursive: true)runs on FSEvents, which is recursive natively and works inside a granted folder. The watcher (library/file_watcher.dart) is used as it is. - iOS:
dart:iodoes not support watching there — the plan assumesFileSystemEntity.isWatchSupportedis false (to verify). The watcher must ask before subscribing, which it does not today (file_watcher.dart:161). Without it, changes from outside (the Files app, the sync, a widget) are found by the reconcile (#302, a directory at a time) on resume and by the five-minute rescan while the app is in the foreground. Inside the app’s container nothing but Niman, Files and the sync writes, so that is enough; a picked iCloud folder adds anNSFilePresenteron the root, which tells a running app what changed. - Unicode normalisation: a name typed on a Mac or shared from another
app can reach the disk decomposed (NFD) while a wikilink typed in Niman is
composed (NFC). APFS treats the two as the same file, so
Fileworks, but string comparison in the index does not:[[Città]]would not findCittà.mdwritten decomposed. Names are compared NFC-normalised. The same can already happen on Linux; Apple makes it common.
Desktop: the Mac
The Mac is the Linux and Windows desktop: the same shell, rail, tree, panes and tabs. What changes is where the Mac puts things.
- The title bar: the native traffic lights stay, over a transparent,
full-size title bar (
window_manager’s hidden style on macOS keeps them), and Niman’s own bar — the sidebar toggle, the tabs — is drawn beside them with their inset. The Windows caption-button hit test (niman/window) has no Mac counterpart; nothing is needed. - The menu bar: a Mac app is expected to have one, and Flutter has
PlatformMenuBar. It is built from the command registry, the one Settings → Commands lists, so a command has one definition and appears in the palette, the keymap and the menu: Niman (About, Settings…⌘,, Hide, Quit), File, Edit, View, Note, Window, Help. - Keys: the defaults use
Ctrlin about 75SingleActivators (ui/app_shortcuts.dart,editor/editor_shortcuts.dart). A primary modifier —⌘on Apple,Ctrlelsewhere — replaces the hard-codedcontrol: true; the find and replace keys already do this (platformModifierIsMeta,app_shortcuts.dart:497), and the source editor already maps⌘C/⌘V/⌘Z. Text motion follows the Mac:⌥←/→by word,⌘←/→to the line’s ends,⌘↑/↓to the note’s. Defaults that collide with the system move:⌘H(Hide),⌘M(Minimise),⌘Q(Quit, which keeps its meaning and its unsaved-edits check),⌘`(next window);F11for Zen becomes⌃⌘F, the Mac’s full-screen key. The key map already storesmeta, so a user’s own bindings carry over. Keys are shown as glyphs (⌘⇧P), not “Meta”. - The tray is the menu bar extra:
nativeapi’s tray on macOS is anNSStatusItem(to verify with its menu), with a template image so it follows the menu bar’s colour. Its menu is the tray’s: Open Niman, the quick actions, Quit. - Closing: on a Mac, closing the window leaves the app running in the
Dock, and
⌘Qquits. That replaces Close to the tray, whose reason — keeping desktop reminders alive — does not apply here: reminders on a Mac are the system’s (below). The setting is not shown on macOS. - One instance is the system’s: macOS opens one copy of an app, so the
lock file and loopback socket (
core/single_instance.dart) are not needed; in a sandbox the socket would also need the network-server entitlement. Opening a file arrives as an Apple Event (application(_:open:)), not as an argument: the runner forwards it toLaunchRequests.openFile. The.mdassociation isCFBundleDocumentTypesinInfo.plist. The quick actions (--quick-note,--journal-today…) become the Dock menu; thenimancommand is a small shell launcher shipped in the disk image, as the.tar.gzships one (open -a Niman --args …). - Dropping files and links on the window: the runner registers the
view for file and URL drags and speaks
niman/drop’s four methods, as the other two runners do, with the frame during a drag. - Show in Finder is
NSWorkspace.activateFileViewerSelecting, which works in a sandbox (open -Rwould not); Open in the default app isurl_launcheras today. - PDF export and web capture: Linux and Windows run a headless
Chromium-family browser. A Mac has Chrome or Edge only sometimes, and a
sandboxed app cannot run them. Both go through WebKit instead, the way
Android goes through its WebView:
niman/pdfprints the export’s HTML into a paginated PDF with selectable text,niman/page_readerloads a page off screen and returns its DOM. The same Swift serves iOS. Chrome found in/Applicationscan still be the first choice on an unsandboxed Mac, if WebKit’s print turns out worse than Chrome’s (to verify: pagination, the columns’ CSS, the math). - Date created: a Mac has the creation time Windows has, and the save’s
rename over the note loses it the same way. The save carries it over as
core/creation_time.dartdoes on Windows (setattrlistthrough FFI), and the scan reads it (st_birthtime) where it reads Windows’ today. - Multi-window: Flutter’s multi-window API is still experimental, so the Mac keeps one window, as the other desktops do (#534’s decision stands).
- The math rasteriser (
preview/math_raster.dart:67) is on for Linux and Windows because their renderers draw paths without MSAA. Whether the Mac needs it is to verify on screen.
Phones and tablets: iOS
An iPhone is the Android phone’s layout and an iPad the Android tablet’s:
the layouts already follow the window’s shortest side, not the OS. An iPad
with a hardware keyboard gets the keymap with ⌘ and the palette’s keys,
as an Android tablet with a keyboard does.
- No processes:
Process.startdoes not exist on iOS. Every feature that runs a program — the headless browser,xdg-open, the updater — has to be behind a gate that iOS answers, and none may be the fallback (page_browser.dart’s else is the process path today; it returns null safely because no engine is found, but by luck). - No downloaded code: iOS will not load a native library the app downloaded, App Store or not. The OCR engine is bundled (below). Data downloads — whisper models, OCR languages — are allowed.
- No self-update: the update check and its settings are off on iOS; the App Store or TestFlight updates the app.
- Quick actions: the long-press menu on the icon
(
UIApplicationShortcutItem) is Android’s launcher shortcuts: the same six ids overniman/shortcuts.
Background work
iOS suspends an app seconds after it leaves the screen, and offers no equivalent to Android’s foreground service. What that does to each feature:
| Feature | Android | iOS |
|---|---|---|
Sync when the app leaves (paused → quick sync) |
Runs | Runs inside a background task (beginBackgroundTask, about 30 s): enough for a quick sync, not a full one |
| Periodic sync | Foreground only already | Same; a BGAppRefreshTask when the system grants one (best effort, maybe never) |
| Web capture from Share | Off screen, under a short foreground service | Queued by the share extension, captured when the app is next opened (decided) |
| Transcription, OCR of a long PDF | Pauses when frozen, resumes | Same: the queue already survives a pause; nothing runs while suspended |
| Reminders | Exact alarms | The system’s notifications (below) — no app code runs |
The share extension
Android’s Share → Niman becomes an iOS share extension (and on a Mac, the
same extension appears in the share menu). An extension is a separate
process with a tight memory limit and no Flutter engine of the app’s. It
does not capture: it writes what was shared — the URL, the title, the
selected text, a file — into the App Group’s inbox and finishes, and the
app processes the inbox the next time it is opened, through the same
niman/share contract core/share_in.dart reads today.
receive_sharing_intent does this, App Group included, but is iOS only;
the extension’s Swift is small enough to own in packages/niman_apple/
and use on the Mac as well.
Widgets
The three Android widgets — Todos, Note, Study — become WidgetKit widgets. The model underneath stays the one the Android widgets use:
- The payload is the same JSON:
widget_payload.dartalready buildstodo_<id>,note_<id>,study_<id>, with the theme. On iOShome_widgetwrites it to the App Group’sUserDefaults(group.dev.niman.niman) instead of Android’s preferences. WidgetKit has no per-instance ids, so the key is per configuration (the library, and the note for the Note widget) rather than per placed widget. - Rendering is SwiftUI, one view per widget family (small, medium, large), drawing the same rows: sections and their counts, the meta line, the checklist.
- Configuration is an App Intent (
AppIntentConfiguration, iOS 17): the library chosen from theknown_librariesmirror the app already writes, and the note for the Note widget. It replacesWidgetConfigActivity. - Taps: a row toggle is an App Intent (
Button(intent:), iOS 17). On Android a tap runs Dart in the background (widgetToggleCallback), which editstodo.txtwith the app’s own code and pushes a new payload. Wherehome_widget’s iOS background intent runs — the app’s process, where Dart can run, or the extension’s, where it cannot — decides whether that stays true (to verify, the first thing the widget spike answers). If only the extension’s, the toggle would needtodo.txt’s rules written a second time in Swift, and the plan does not accept that: the fallback is a tap that opens the app on the task. - The library must be reachable from where the tap runs: a library in the app’s own container is not visible to the widget extension. Another reason the edit should run in the app’s process.
- On the Mac, WidgetKit widgets live on the desktop and in Notification
Center (macOS 14), with the same SwiftUI.
home_widgethas no macOS side, so the Dart side writes the App Group and reloads the timelines overniman/widgets. A widget extension is always sandboxed, and needs the App Group even when the app is not.
Reminders and notifications
flutter_local_notifications schedules through UNUserNotificationCenter
on both, and the system delivers with Niman closed — better than Linux and
Windows, whose reminders are an in-process timer. createReminderService
gains the Apple case: LocalReminderService with the plugin’s backend, as
on Android.
- iOS keeps the 64 most recently scheduled notifications. A library
with more future reminders than that schedules the next 64 by time
(repeating events’ occurrences included, #1228) and tops the list up
whenever the app is opened (there is no background refresh). A phone not opened for a long time can therefore miss the
65th reminder onwards;
docs/user/platforms.mdsays so. macOS documents no such limit. - The Android health checks (
niman/reminders, battery optimisation) have no counterpart; the permission prompt is the only one. - The
calendar.txtreminders (#730) take the same path.
OCR, transcription, spell check
- OCR: the Tesseract engine cannot be downloaded on iOS, and on a Mac a
downloaded library must be signed by the same team to load under the
hardened runtime. Two ways:
- Bundle Tesseract (decided 2026-10-16):
scripts/ocr-engine.shgainsmacos-universal(a.dylib,ld64’s-dead_stripand an exported-symbols list in place of the version script and--gc-sections) andios-arm64(a static library in an XCFramework, found withDynamicLibrary.process()). The locator’s bundled step already exists for this (ocr_engine_locator.dart). The languages are still downloaded. Same engine, same lines, same boxes on every platform. - Apple’s Vision (
VNRecognizeTextRequest): nothing to bundle or download, Italian among its languages, line boxes included; but a second engine, whose results differ from the other platforms’.
- Bundle Tesseract (decided 2026-10-16):
- Transcription:
whisper_ggmlsupports both (Metal and Accelerate). The phone’s reduced model list follows “a phone”, not “Android”. Non-WAV imports are converted with AVFoundation (AVAudioConverter, throughpackages/niman_apple/) rather than the FFmpegwhisper_ggmlpulls on Apple, if that FFmpeg can be left out (to verify, as it could not on Android). Apple’s own on-device speech (SpeechAnalyzer, iOS and macOS 26) is an alternative engine, not part of this plan. - Spell check: Windows already uses the system’s checker
(
windows_spell_checker.dart, COMISpellChecker) rather than hunspell. Apple does the same:NSSpellCheckeron macOS,UITextCheckeron iOS, behind one channel that checks a paragraph per call and returns the misspelt ranges (a call per word would be thousands of round trips). The languages offered are the system’s; the personal dictionary stays.niman/dictionary.txt, applied by Niman on top, as on Windows.
Builds, flavors, signing
- Two flavors, as on Android: Xcode schemes
officialandbeta(Flutter’s--flavormaps to schemes on Apple), with bundle idsdev.niman.nimananddev.niman.niman.beta, app names Niman and Niman (Testing), and App Groupsgroup.dev.niman.nimanandgroup.dev.niman.niman.beta. The beta keeps its own container and support folder by bundle id, soappSupportDirectory’s-testingsibling (core/app_channel.dart:44, already skipped on iOS) is skipped on macOS too.scripts/niman.shgainsmacos [beta]andios [beta]. - An Apple Developer Program membership is needed for almost all of it:
Developer ID signing and notarisation, App Groups (the widgets), the
keychain entitlement, and any install on an iPhone beyond a week-long
personal build.
- macOS without it still works: the
.dmggoes on the GitHub release, signed ad hoc (Apple silicon runs nothing unsigned, and the linker signs ad hoc by itself). What it costs is the first launch: Gatekeeper refuses an app that is not notarised, and since macOS 15 the right-click Open no longer gets past it — the user allows it in System Settings → Privacy & Security → Open Anyway. The secure storage falls back to the legacy keychain, which needs no entitlement: the data protection keychain refuses an ad-hoc build’s writes witherrSecMissingEntitlement(-34018), andSecureSyncSecretStorereads that status (thedetailsof the plugin’s error, not its code) as “not this keychain” and switches (#1244). The cost of the unsigned.dmgis one Keychain prompt — Niman wants to use your confidential information — the first time a build reads an entry another one wrote, since each ad-hoc signature is a new identity. - iOS without it does not exist: no TestFlight, no App Store, no App Group, and a personal build on one’s own iPhone expires after seven days.
- macOS without it still works: the
- macOS, direct: a universal (arm64 + x86_64) app, signed with a
Developer ID certificate under the hardened runtime, notarised with
notarytool, stapled, shipped asniman-X.Y.Z-macos.dmg(and a.zip) on the GitHub release beside the others. The in-app updater downloads the.dmgand opens it —release_asset.dartgains a macOS asset, and the update check never falls back to another platform’s. - macOS, App Store: not planned (decided 2026-10-16: the
.dmgonly). It would be the same app sandboxed, signed for distribution, uploaded with the iOS pipeline, without the in-app updater. - iOS: TestFlight and the App Store are the only realistic routes. An
.ipaon the GitHub release is of no use to anyone and is not attached. TestFlight is the iOS beta: internal testers get every build, external ones after Apple’s beta review. - Version:
+NbecomesCFBundleVersion, which App Store Connect requires to rise on every upload — the same ruleAGENTS.mdalready sets for Android’sversionCode. - App Store paperwork: a privacy manifest (
PrivacyInfo.xcprivacy) with the required-reason APIs Niman touches — file timestamps (every scan stats), disk space,UserDefaultsfor the App Group; the encryption question answered as exempt (HTTPS only: Niman encrypts nothing of its own); the microphone and notification usage strings, in every language the app ships.
CI and release
The repository is public, so GitHub’s macOS runners cost no money; they cost time (three cores, one queue).
check.yml: from phase 2 on, on every PR, a third job onmacos-26(arm64, Xcode 26):flutter test,flutter build macos --debug --flavor beta, the Swift unit tests (xcodebuild testforpackages/niman_apple/, as the Kotlin job runs the Android ones), andapp_bootheadless. The read view’s goldens get amacos/set besidelinux/andwindows/(CoreText rounds glyphs its own way).release.yml: amacosjob — build, sign, notarise, staple,.dmg+.zipintogithub-release’s files — and aniosjob that builds the.ipaand uploads it to TestFlight. New secrets: the Developer ID certificate (.p12, base64) and its password, the team id, an App Store Connect API key (id, issuer,.p8) for notarisation and upload, and the provisioning profiles. Without the secrets themacosjob signs ad hoc and skips notarisation, as the Android job falls back to the debug key; theiosjob does not run.ocr-engine.yml:macos-universalandios-arm64on a macOS runner, on the nextocr-engine-Ntag.- A Mac mini joins the hosts (expected within days of 2026-10-16). The CI builds and tests; debugging a runner, a widget or an entitlement happens there, in Xcode.
Testing
- Dart: the unit and widget suites already run anywhere; the macOS job
runs them on a Mac. Platform branches are tested the way
createReminderService({isAndroid, isDesktop})already is — the host platform injected — so the iOS branches run on any host. That pattern becomes oneHostPlatformvalue (phase 0) instead of a boolean per call site. - Swift: XCTest for the shared plugin — the payload
parsing the widgets do (as
TodoWidgetItemsTest.ktdoes for Android), the pasteboard’s HTML reading. - Integration:
app_booton the macOS runner;sync_e2eon-d macos; on iOS,app_bootin the simulator. - By hand, on devices: an Apple silicon Mac, an iPhone, an iPad with a keyboard. The storage grants, the widgets, the share extension and the background limits only show on a device.
Phases
One feature branch per phase, one PR into main each, a commit per step.
Phase 0 runs on today’s hosts; everything after it needs a Mac.
- Ground work, no Apple code (Windows or Linux):
HostPlatform: desktop, phone, touch, Apple, answered once and injectable; theisLinux || isWindowsgates become desktop.- The primary modifier in every default binding; keys shown as glyphs on Apple.
LibraryLocationwith a path-only implementation; the index named after the library’s identity.- The watcher asks
isWatchSupported; names compared NFC. - The update check offers nothing to a platform it has no asset for.
- The transcription’s phone list keyed on phone.
- Spike on a Mac (a week, throwaway branch):
flutter create --platforms=macos,ios, boot both; answer every to verify above —Directory.watchon iOS, the container’s path across an app update,window_managerandnativeapion macOS,home_widget’s intent process, WebKit’s PDF against Chrome’s, FFmpeg’s removal. The answers are written into this record before phase 2 starts. - macOS: the runner, flavors and entitlements; the desktop gates on;
title bar, menu bar from the command registry, keys, menu bar extra,
close semantics, file-open events, Dock menu, drop;
packages/niman_apple/with WebKit PDF and capture, pasteboard, keep awake, spell check; reminders; bundled OCR engine; creation time; Show in Finder; the updater’s.dmg; CI and the release’s.dmg;docs/user/platforms.mdgains a macOS section. - iOS: the runner, flavors, App Group; storage (the container), the
rescan on resume; quick actions; the
share extension and its inbox; notifications and the 64 cap;
background sync; transcription and OCR; no updater; TestFlight in
release.yml; the iOS section ofplatforms.md. - Widgets: WidgetKit on iOS — the three widgets, configuration, interactive toggles; then the same on macOS.
- The App Store, iOS only: privacy manifest, review, release. The
Mac stays on the
.dmg.
Until phase 4 ends, platforms.md lists macOS and iOS as preview, with
what each still lacks — the decision AGENTS.md asks for, made explicit,
not a platform quietly behind.
Risks
- One Mac, few devices: the Mac mini covers macOS and the iOS simulator. The share extension, the widgets and the background limits show truly only on an iPhone and an iPad (still open, below).
- iCloud and File Provider folders on iOS: lazy materialisation and a million-note scan do not mix. The plan keeps them out of the default and measures before promising them.
- Five platforms per feature: from the first macOS release, every feature has five surfaces to land on. That is the real cost of the port, paid on every PR after it.
- Pre-1.0 desktop packages (
window_manager,nativeapi) carry the Mac’s window and tray; both are pinned exactly already, and the spike tests them first.
What the spike answered (2026-10-20 and 21)
Phase 1 ran on the Mac mini: the macOS port went on to most of phase 2 on
spike/macos, and the iOS runner boots in the simulator on spike/ios.
The to verify items above, answered:
window_manager0.5.2 on macOS: the hidden title bar keeps the traffic lights over a transparent bar, and close interception (setPreventClose) works; the bar leaves the lights their room.nativeapi0.2.4’s tray on macOS: the status item and its menu work; a click opens the menu. Its Dart API does not expose the template image, socnativeapi’s C call does that (a direct dependency, pinned).file_picker: on an unsandboxed Mac its Darwin handler refuses every dialog over entitlements the app has no use for, unlessskipEntitlementsChecks()is called at startup. On iOS it returns the picked folder’s path, with no copy, no security scope and no bookmark.- The sandbox’s folder grant is moot on the Mac:
flutter createturns the App Sandbox on, and the runner turns it off (decision 3). Directory.watchon iOS:isWatchSupportedis false and the call throws; the watcher checks first and leaves the folder to the rescan.- The math rasteriser stays off on a Mac: Impeller on Metal smooths the paths’ edges itself.
- FFmpeg can be left out of the Apple builds: an Android-only copy of
ffmpeg_kit_flutter_new_minreplaces it (its 2.1.0 iOS frameworks also have no arm64 simulator slice), and AVFoundation decodes other formats inpackages/niman_apple. - WebKit’s PDF against Chrome’s: paginated A4 with real text through
the print operation (
createPDFmakes one endless page); pagination, columns and math checked on the Mac. home_widget’s intent process: not answered yet — the widget spike.
And what the plan did not foresee:
- On macOS the Dart UI isolate runs on the main thread, so the system’s spell checker is a synchronous FFI call, as Windows’ COM one is.
- WebKit ends its print on a thread of its own: a channel answered from there reached Dart only at the next event. And a background isolate’s channel replies stalled the same way on a Mac, so the folder export’s isolate asks the UI isolate to print each page.
- Tesseract picks its SIMD sources for one processor: the universal OCR
engine is two builds joined with
lipo. CMake 4 needs Leptonica’s policy version named. - The Mac’s FSEvents reports the watched folder itself, and the read
view’s goldens need a
macos/set (CoreText); the integration files run the real app, in the host’s language. - A Swift package of the app’s own needs the runner at macOS 14.
Decided (2026-10-16)
- A Mac mini joins the hosts within days; the native work happens there.
- macOS ships as a
.dmgon the GitHub release, beside Linux and Windows. No Mac App Store. - Not sandboxed on macOS: a library is a path, as on Linux.
- iOS keeps its libraries in the app’s container, visible in Files, synced through WebDAV. A picked folder and iCloud are not in the first iOS release.
- iOS 17 and macOS 14 at least.
- A universal Mac app (arm64 and x86_64).
- Tesseract, bundled, is the OCR engine on both.
- A share waits in the inbox: the extension queues it, the app captures it when it is next opened.
- The system’s spell checker on macOS and iOS, as on Windows; the personal dictionary stays Niman’s.
- Widgets on the Mac come after the iOS ones, with the same SwiftUI;
until then
platforms.mdsays so. - Closing follows the Mac: the window closes, the app stays in the
Dock,
⌘Qquits; Close to the tray is not shown on macOS; the menu bar extra is on by default. - The macOS CI job runs on every PR from phase 2 on.
- macOS and iOS are preview in
platforms.mduntil the widgets land, then full members of “every platform ships every feature”. - Bundle ids
dev.niman.nimananddev.niman.niman.beta, App Groupsgroup.dev.niman.nimanandgroup.dev.niman.niman.beta.
Still open
- The Apple Developer Program (99 $ a year; as an individual, whose name the store shows, or as an organisation, which needs a D-U-N-S number). Not needed until phase 2’s first release: macOS can ship without it, at the cost of Gatekeeper’s Open Anyway on first launch (see Builds, flavors, signing). iOS cannot ship at all without it, so it is needed before phase 3 reaches anyone’s phone.
- An iPhone and an iPad to test on: the Mac covers the simulator, not the share extension, the widgets or the background limits on a device.