ArjenSchwarz/asterism commit 3cec3245 files 28 simulator units 1,841 passed full UI 280 passed / 2 expected skips

Pre-push review: T-2483 Settings

Retained native Mac Settings pages, grouped mobile configuration, and scoped backup cleanup.

At a glance

  • 12 Mac UI journeys and two toolbar-owner unit checks previously passed; their unchanged behaviors retain that evidence.

  • Final source: 1,841 simulator units; phone 247 passed plus two expected physical-only measurement skips; iPad 33 passed. No missing test identifiers.

  • Unchanged Core/fast scope reuses 4,060 Core passes with 55 normal opt-in skips, and 456 fast declarations / 552 expanded executions. No physical deployment or merge.

Verdict

Ready to push

Both review findings are fixed. Full simulator units, phone acceptance and iPad acceptance passed on unchanged production/test inputs. Signed Mac compilation passed. Earlier Mac UI results are reused only for unchanged window, toolbar and navigation behavior; direct model tests cover the cleanup-policy refinement.

Review findings

2 raised · 2 fixed · 0 skipped

Jump to findings →

Tests

Pass rate: 100% (2121 of 2121)

New tests: 13

Diff coverage: n/a

Jump to tests →

Commits

Three-level explanation

What changed On iPhone and iPad, Sites, Work types and Creator roles sit together in the Library section. On Mac, General, Sites, Work types, Creator roles and Maintenance are direct settings tabs. General contains About, Backup and Debug, with Debug collapsed when opened. Maintenance contains detached-link notes and the existing capture controls.

Each Mac tab remembers where you were and keeps unfinished edits when you switch away and return. Backup cleanup now runs only for All and General, where backup actions are available. Other pages skip that scan.

Why it matters People can find related settings together and move between Mac settings pages without losing a detail view or draft. Unrelated pages also avoid scanning the backup folder on every redraw.

Key concepts A retained tab keeps its screen and navigation history alive while another tab is selected. Backup scavenging checks for old staged files left behind by a previous session.

Changes overview The Mac Settings window uses one app-owned native window and toolbar tab controller, with one retained SwiftUI host and navigation stack per page. The three configuration tabs open their existing lists directly. General owns About, Backup and collapsed Debug; Maintenance owns detached-note and capture recovery. Mobile keeps the Library rows in their existing order.

The scavengesOnInit option defaults to true through SettingsBackupModel and AppLibraryModel.settingsBackupModel. SettingsScreen enables it only for .all and .general; the exporter readiness guard remains intact. SettingsBackupModelTests.skipsScavengingOnInitWhenDisabled pins the disabled behavior, and the existing test still pins the default.

Implementation approach One native controller owns the Mac toolbar and retains the page hosts. Page-scoped SettingsToolbarActions use owner tokens: when an old page disappears late, it can clear only its own Back/Save/Cancel actions, not actions installed by the newly selected page. The hosting controllers set sceneBridgingOptions to empty so SwiftUI does not install a competing toolbar bridge.

Routes back to the main window use the existing pending-route mechanism. ContentView consumes the pending destination only after saved-state restoration and library readiness, preserving startup ordering.

Trade-offs Native window and tab ownership adds Mac-specific wiring, while keeping models, mutations and persistence unchanged. The scavenging flag adds no new cleanup mechanism and preserves prior behavior for callers that use its default.

Technical deep dive SettingsScreen passes a page-derived Boolean through AppLibraryModel.settingsBackupModel and SettingsBackupModel to BackupExportStage's existing scavengesOnInit switch. The repository/exporter availability guard remains the gate before model construction. Only .all and .general trigger the synchronous staging-directory scan; default-true parameters preserve other call sites.

MacSettingsWindow owns the NSWindowController and NSTabViewController; each tab retains its hosting controller and independent navigation stack. Empty sceneBridgingOptions prevents child SwiftUI hosts from installing a toolbar bridge that would contend with the AppKit toolbar. SettingsToolbarActions are scoped by owner tokens, so delayed disappearance cleanup from an old page cannot clear the current page's Back or staged-order Save/Cancel handlers. Main-window navigation remains deferred through the pending route until ContentView has completed restoration and library readiness.

Architecture impact The layout change retains existing app model and routing ownership and introduces no schema, persistence or CloudKit changes. The scan policy is localized at the page boundary, matching the ownership of backup presenters in General.

Potential issues and verification status Final-source validation passed 1,841 simulator units, 247 phone UI cases with two expected physical-only measurement skips, and all 33 iPad acceptance cases. The Mac app and tests compiled, and app/extension signatures verified. Earlier Mac UI evidence covers unchanged window, toolbar and navigation behavior; the direct model regression verifies the cleanup-policy change.

Important changes — detailed

Retain native Settings pages

Asterism/Asterism/Support/MacSettingsWindow.swift

Why it matters. Switching tabs and reopening Settings preserve navigation and drafts.

What to look at. MacSettingsWindow.show; MacSettingsTabsController

Takeaway. Retain one hosting controller per independently stateful native page.
Rationale. Decision 2 assigns one window/toolbar owner after the SwiftUI-owned tab approach lost state and conflicted with toolbar bridging.

Keep native toolbar actions with their page

Asterism/Asterism/Support/SettingsToolbarActions.swift

Why it matters. Late disappearance callbacks cannot remove a newer Back or Save/Cancel action.

What to look at. SettingsToolbarActions; NativeSettingsBackControl

Takeaway. Owner tokens make asynchronous lifecycle cleanup conditional on the state it owns.
Rationale. The native toolbar is shared while navigation and editor actions belong to individual retained pages.

Group configuration and recovery controls

Asterism/Asterism/Views/SettingsView.swift

Why it matters. Mobile readers find configuration together; native tabs open the actual lists directly.

What to look at. SettingsPage; SettingsView.body

Takeaway. Separate page presentation while reusing existing models and mutations.
Rationale. Requirements 1-3 and Q3 keep General/all presentation ownership separate from Maintenance.

Consume routes after main-window restoration

Asterism/Asterism/ContentView.swift

Why it matters. A Settings destination must win over the last saved sidebar selection.

What to look at. takeMacSettingsRoute

Takeaway. An explicit route can wait for restoration and readiness without being consumed prematurely.
Rationale. The accepted native window can outlive the main window; menu-first and sidebar-first return journeys verify the ordering.

Avoid unrelated backup staging scans

Asterism/Asterism/Layout/SettingsScreen.swift

Why it matters. Configuration and Maintenance pages need not perform synchronous backup-file cleanup.

What to look at. SettingsScreen.body; AppLibraryModel.settingsBackupModel; SettingsBackupModel.init

Takeaway. Use an existing lifecycle policy at the owning page boundary while retaining backward-compatible defaults.
Rationale. Efficiency review traced model construction to a directory scan. The disabled-policy regression and unchanged default test directly cover the fix.

Use native mouse input in the Mac journey

Asterism/AsterismUITests/SettingsLayoutUITests.swift

Why it matters. The real reorder handler must run before asserting draft retention and cancellation.

What to look at. testNativeTabsKeepConfigurationDraftsAndIndependentNavigation

Takeaway. XCTest mouse click-and-drag and touch press-and-drag are different input APIs.
Rationale. The original onMove implementation passed with the native mouse driver; experimental drop adapters were removed.

Key decisions

One native window and toolbar owner

Decision 2 retains one native controller and a SwiftUI host per page, avoiding competing toolbar ownership and keeping page-local state.

Window-scoped native tab titles

Decision 1 uses native toolbar button titles because the platform omits custom tab identifiers. Every behavioral assertion remains.

Page-scoped presentation and cleanup

Q3 assigns backup/import/Empty Library/sync presentation to all/General and capture deletion to all/Maintenance. The reviewed cleanup refinement follows the same ownership boundary.

Review findings

SeverityAreaFindingResolution
majorSettingsScreen backup model constructionNon-General Mac pages synchronously scavenged the backup staging directory despite having no backup controls.Pass the existing default-true scavengesOnInit policy through the model factories; enable only for all/General. Preserve readiness and the default cleanup behavior; add a disabled-policy regression test.
minorSettings decision logDecision 2 names an obsolete location for MacSettingsCommands.Update the pointer to Support/MacSettingsWindow.swift before publication.

Tests

Source: local run at 2026-10-25T04:39:42.681019+11:00 · snapshot 3cec324541bab988303042fea5f4491418bf1e3b

Baseline: none

Execution: passed · JUnit: 3 files · Coverage: none · Baseline: absent

Coverage scope: as the project configures it

Totals: 2121 passed · 0 failed · 2 skipped · 0 errored · 0 flaky

New and removed tests

Derived by declaration name, from the diff (no baseline run).

Blast radius

Files that import a changed file on the left, changed files in the centre, files a changed file imports on the right. Snapshot working-tree against base 8114426ebd87bab2b9a5040b61d2339fd7ca140b.

Dependents none found Changed Dependencies none found Asterism/Asterism Asterism/Asterism/Layout Asterism/Asterism/Support Asterism/Asterism/ViewModels Asterism/Asterism/Views Asterism/AsterismTests Asterism/AsterismUITests Asterism/Asterism/AsterismApp.swift…sm/Asterism/AsterismApp.swift Asterism/Asterism/ContentView.swift…sm/Asterism/ContentView.swift Asterism/Asterism/Localizable.xcstrings…sterism/Localizable.xcstrings Asterism/Asterism/Layout/AsterismCommands.swift…Layout/AsterismCommands.swift Asterism/Asterism/Layout/SettingsScreen.swift…m/Layout/SettingsScreen.swift Asterism/Asterism/Support/MacSettingsWindow.swift…pport/MacSettingsWindow.swift Asterism/Asterism/Support/SettingsToolbarActions.swift…/SettingsToolbarActions.swift Asterism/Asterism/ViewModels/AppLibraryModel.swift…wModels/AppLibraryModel.swift Asterism/Asterism/ViewModels/SettingsBackupModel.swift…els/SettingsBackupModel.swift Asterism/Asterism/Views/CreatorRolesView.swift…/Views/CreatorRolesView.swift Asterism/Asterism/Views/SettingsView.swift…rism/Views/SettingsView.swift Asterism/Asterism/Views/SitesView.swift…sterism/Views/SitesView.swift Asterism/Asterism/Views/WorkTypesView.swift…ism/Views/WorkTypesView.swift Asterism/AsterismTests/SettingsBackupModelTests.swift…ettingsBackupModelTests.swift Asterism/AsterismTests/SettingsToolbarActionsTests.swift…ingsToolbarActionsTests.swift Asterism/AsterismUITests/AssociationNotesUITests.swift…AssociationNotesUITests.swift Asterism/AsterismUITests/SettingsLayoutUITests.swift…s/SettingsLayoutUITests.swift
addedmodifieddeletedrenamedunchangedcollapsed package group or +N more⚑N test files with an edge to the node

Per-file diffs

28 files: 17 code · 11 docs. Click to expand.

Code (17)

Asterism/Asterism/AsterismApp.swift Modified +10 / -20
diff --git a/Asterism/Asterism/AsterismApp.swift b/Asterism/Asterism/AsterismApp.swiftindex b5bdf03e..6cc282bd 100644--- a/Asterism/Asterism/AsterismApp.swift+++ b/Asterism/Asterism/AsterismApp.swift@@ -35,6 +35,9 @@ struct AsterismApp: App {     /// place, so the state has to outlive whichever of them is on screen. Built     /// in `init` for the model's reason: the open intents route through it.     @State private var navigation: AppNavigation+    #if os(macOS)+    @State private var settingsWindow = MacSettingsWindow()+    #endif     /// The announcement seen state (`today-announcements` Q22), for both of the     /// reasons above and one more: a `UserDefaults` write triggers no     /// Observation, so the Mac's Settings window storing the version has to be@@ -96,6 +99,7 @@ struct AsterismApp: App {         // than opening another.         Window("Asterism", id: Self.mainWindowID) {             ContentView(model: model, navigation: navigation, announcements: announcements)+                .environment(settingsWindow)                 // Req 2.4: the two-column layout with the list at 320 pt still                 // fits here. `contentMinSize` below is what makes the window                 // honour it rather than letting the reader squash the content.@@ -105,33 +109,19 @@ struct AsterismApp: App {         .windowResizability(.contentMinSize)         .commands { AsterismCommands() } -        // Req 4.4: the standard Settings window, opened by ⌘, and by the-        // sidebar's Settings row. The same screen the iPad shows in a sheet,-        // in its own stack so its `NavigationLink`s push inside this window.-        Settings {-            NavigationStack {-                SettingsScreen(model: model, navigation: navigation, dismissSheet: nil)-            }-            // Q18: this scene is built outside `ContentView`, so it inherits-            // nothing from that write — the lookup is put in here too, and the-            // seen state with it (`today-announcements` Q22): it is the same-            // instance the main window holds, so Release notes opened here-            // removes the row over there.-            .environment(\.siteNames, model.siteNames)-            .environment(announcements)-            // `app-intents` Q30: a draft open in this window blocks an open-            // intent as surely as one in the main window.-            .environment(\.intentEditSessions, navigation)+        .commands {+            MacSettingsCommands(+                settingsWindow: settingsWindow, model: model,+                navigation: navigation, announcements: announcements)         }-        .defaultSize(width: 640, height: 560)         #else         WindowGroup {             ContentView(model: model, navigation: navigation, announcements: announcements)         }         // Req 6.1's shortcuts, which iPadOS also lists in the held-⌘ overlay.         // Settings is the one command that is the iPad's alone (Q4): the Mac-        // gets its item from the `Settings` scene, and replacing `.appSettings`-        // there would remove the system's own to put the same one back.+        // uses the retained native window owner; this focused command replaces `.appSettings`+        // only in the iOS scene.         .commands { AsterismCommands() }         .commands { AppSettingsCommands() }         // The background export grant (Req 1.1, 3.5). The handler runs on a
Asterism/Asterism/ContentView.swift Modified +33 / -11
diff --git a/Asterism/Asterism/ContentView.swift b/Asterism/Asterism/ContentView.swiftindex 9465b88c..93c521da 100644--- a/Asterism/Asterism/ContentView.swift+++ b/Asterism/Asterism/ContentView.swift@@ -8,7 +8,7 @@ import SwiftUI /// current width, and every sheet the app presents. /// /// **The navigation state is not here any more** (Q14, Q21). `AppNavigation`-/// owns it and `AsterismApp` owns that, because the macOS `Settings` scene+/// owns it and `AsterismApp` owns that, because the macOS Settings window /// routes into this window and a second scene cannot reach a view's `@State`. /// What stays is the library model's lifecycle, the loading/unavailable/ready /// switch, and the sheets — which sit *above* the tree so that a size-class@@ -16,7 +16,7 @@ import SwiftUI struct ContentView: View {     @State private var model: AppLibraryModel     /// `@Bindable`, not `@State` (design §Root composition). `AsterismApp` owns-    /// this object — the macOS `Settings` scene binds to the same one — so this+    /// this object — the macOS Settings window binds to the same one — so this     /// view *binds* to it rather than taking ownership. `@State` would keep the     /// first instance it was handed for the life of the view and quietly ignore     /// a later one, which is the wrong answer for state a second scene also@@ -72,10 +72,9 @@ struct ContentView: View {     #endif      #if os(macOS)-    /// Req 4.4: the standard Settings window. macOS-only API, not merely a-    /// macOS-only behaviour — there is no `openSettings` to compile against on-    /// iOS.-    @Environment(\.openSettings) private var openSettings+    /// Native Settings shares the app-owned window; routes back use this scene action.+    @Environment(\.openWindow) private var openWindow+    @Environment(MacSettingsWindow.self) private var settingsWindow: MacSettingsWindow?     #endif      // MARK: - Relaunch restore (Req 7.2, Q23)@@ -392,7 +391,15 @@ struct ContentView: View {             // app; otherwise the `.ready` edge below takes it.             navigation.reconcileLibraryLayout(isWide: usesWideLibrary)             takeIntentRoute()+            #if os(macOS)+            takeMacSettingsRoute()+            #endif         }+        #if os(macOS)+        .onChange(of: navigation.pendingRoute != nil) { _, hasRoute in+            if hasRoute { takeMacSettingsRoute() }+        }+        #endif         .onChange(of: navigation.worksPath) { _, path in             guard usesCompactTree else { return }             if let destination = path.compactMap({ route -> WorksDestination? in@@ -411,7 +418,12 @@ struct ContentView: View {         // `app-intents` Req 4.6: a route set while the library was opening or         // unavailable is taken once it is ready.         .onChange(of: model.state) { _, state in-            if state == .ready { takeIntentRoute() }+            if state == .ready {+                takeIntentRoute()+                #if os(macOS)+                takeMacSettingsRoute()+                #endif+            }         }         // And one set while it already is: an open intent against a resident         // app (Reqs 4.1, 4.2).@@ -893,7 +905,7 @@ struct ContentView: View {             navigation: navigation,             // Req 4.4: `openSettings()` on the Mac, the sheet on the iPad.             showSettings: showSettings,-            showsSettingsRow: !RuntimePlatform.isMac+            showsSettingsRow: true         )     } @@ -918,7 +930,7 @@ struct ContentView: View {             toggleSidebar: navigation.toggleSidebar,             selectTab: { navigation.selectedTab = $0 },             // ⌘, is the iPad's command only — the Mac's comes from the-            // `Settings` scene — but the action is published on both, because+            // native Settings commands — but the action is published on both, because             // it is the sidebar row's action too.             showSettings: showSettings         )@@ -994,7 +1006,7 @@ struct ContentView: View {     /// The iPad's Settings sheet.     ///     /// macOS never presents it: Settings is a window there, opened from ⌘, and-    /// from the sidebar's row through `openSettings()`. The content itself is+    /// from the sidebar's row through the native window owner. The content itself is     /// the same `SettingsScreen` the Mac's window holds; what this adds is the     /// sheet's own way out.     @ViewBuilder@@ -1036,7 +1048,10 @@ struct ContentView: View {     /// Settings window on the Mac, the sheet on the iPad.     private func showSettings() {         #if os(macOS)-        openSettings()+        let action = openWindow+        settingsWindow?.show(+            model: model, navigation: navigation, announcements: announcements,+            openMainWindow: { action(id: AsterismApp.mainWindowID) })         #else         navigation.showingSettings = true         #endif@@ -1047,6 +1062,13 @@ struct ContentView: View {     private func takePendingRoute() {         navigation.takePendingRoute(in: model.todayPresentation.duplicateWorkload)     }++    #if os(macOS)+    private func takeMacSettingsRoute() {+        guard hasRestoredSelection, model.state == .ready else { return }+        takePendingRoute()+    }+    #endif }  // An explicit configuration, not the production initializer (Q19): a preview
Asterism/Asterism/Layout/AsterismCommands.swift Modified +2 / -3
diff --git a/Asterism/Asterism/Layout/AsterismCommands.swift b/Asterism/Asterism/Layout/AsterismCommands.swiftindex 92e60125..365a4981 100644--- a/Asterism/Asterism/Layout/AsterismCommands.swift+++ b/Asterism/Asterism/Layout/AsterismCommands.swift@@ -12,9 +12,8 @@ import SwiftUI /// /// Portable: `Layout/` carries no platform conditionals. The one command that /// *is* platform-specific is Settings, and it is a separate `Commands` value-/// below that only the iOS scene includes — macOS builds its own from the-/// `Settings` scene, and replacing `.appSettings` there would take the-/// system's item away to put the same item back.+/// below that only the iOS scene includes. The Mac scene uses+/// `MacSettingsCommands` to open the shared native Settings window. struct AsterismCommands: Commands {     @FocusedValue(\.navigationActions) private var actions 
Asterism/Asterism/Layout/SettingsScreen.swift Modified +12 / -4
diff --git a/Asterism/Asterism/Layout/SettingsScreen.swift b/Asterism/Asterism/Layout/SettingsScreen.swiftindex 8a37a073..6a23505d 100644--- a/Asterism/Asterism/Layout/SettingsScreen.swift+++ b/Asterism/Asterism/Layout/SettingsScreen.swift@@ -20,12 +20,14 @@ import SwiftUI /// Portable, like everything in `Layout/`: what differs between the platforms /// arrives as `dismissSheet` rather than as a conditional. struct SettingsScreen: View {+    var page: SettingsPage = .all     let model: AppLibraryModel     @Bindable var navigation: AppNavigation      /// How to leave Settings on this host, or nil where Settings is a window of     /// its own and there is nothing to dismiss.     let dismissSheet: (() -> Void)?+    var openMainWindow: (() -> Void)? = nil      /// Only ever called on the arm where `dismissSheet` is nil — the Mac, where     /// the main window may not even be frontmost when a route lands in it.@@ -33,7 +35,9 @@ struct SettingsScreen: View {      @ViewBuilder     var body: some View {-        if let backupModel = model.settingsBackupModel() {+        if let backupModel = model.settingsBackupModel(+            scavengesOnInit: page == .all || page == .general+        ) {             settingsContent(backupModel)         } else {             // ⌘, opens this window whatever the library is doing, and a Settings@@ -46,6 +50,7 @@ struct SettingsScreen: View {      private func settingsContent(_ backupModel: SettingsBackupModel) -> some View {         SettingsView(+            page: page,             model: backupModel,             importModel: model.settingsBackupImportModel(),             isAwaitingFirstSync: model.recentSyncPresentation.isAwaitingFirstSync,@@ -153,12 +158,15 @@ struct SettingsScreen: View {     /// dismissing does not appear.     ///     /// On the Mac Settings is a separate window, so nothing is covering the-    /// route's sheet: the main window is brought forward — it may not even be-    /// frontmost — and the route is taken at once. The Settings window stays-    /// where it is, which is what a Mac reader expects of it.+    /// route's sheet. The native owner opens or brings forward the main window;+    /// ContentView takes the pending route after restoration and library readiness.+    /// The Settings window stays available.     private func leaveSettings() {         if let dismissSheet {             dismissSheet()+        } else if let openMainWindow {+            // The main view consumes the route after restoring its saved state.+            openMainWindow()         } else {             openWindow(id: AsterismApp.mainWindowID)             navigation.takePendingRoute(in: model.todayPresentation.duplicateWorkload)
Asterism/Asterism/Localizable.xcstrings Modified +5 / -1
diff --git a/Asterism/Asterism/Localizable.xcstrings b/Asterism/Asterism/Localizable.xcstringsindex fec210b1..c3f01e0f 100644--- a/Asterism/Asterism/Localizable.xcstrings+++ b/Asterism/Asterism/Localizable.xcstrings@@ -809,6 +809,10 @@       "comment" : "Label for the x-axis of a bar graph.",       "isCommentAutoGenerated" : true     },+    "Day" : {+      "comment" : "Title of the \"Day\" parameter for the Notes from Today intent.",+      "isCommentAutoGenerated" : true+    },     "Debug" : {       "comment" : "The heading for the Debug section of the settings view.",       "isCommentAutoGenerated" : true@@ -1721,7 +1725,7 @@     "Reading that link…" : {      },-    "Reads the notes you made on chapters today." : {+    "Reads the notes you made on chapters today or on a chosen day." : {       "comment" : "Description of the Notes from Today intent.",       "isCommentAutoGenerated" : true     },
Asterism/Asterism/Support/MacSettingsWindow.swift Added +178 / -0
diff --git a/Asterism/Asterism/Support/MacSettingsWindow.swift b/Asterism/Asterism/Support/MacSettingsWindow.swiftnew file mode 100644index 00000000..e436c68b--- /dev/null+++ b/Asterism/Asterism/Support/MacSettingsWindow.swift@@ -0,0 +1,178 @@+#if os(macOS)+import AppKit+import AsterismPresentation+import Observation+import SwiftUI++/// One native Settings window and one retained SwiftUI graph per page.+@MainActor+@Observable+final class MacSettingsWindow {+    static let identifier = "settings-window"+    @ObservationIgnored private var controller: NSWindowController?++    func show(+        model: AppLibraryModel,+        navigation: AppNavigation,+        announcements: AnnouncementSeenState,+        openMainWindow: @escaping () -> Void+    ) {+        if controller == nil {+            let tabs = MacSettingsTabsController()+            tabs.tabStyle = .toolbar+            tabs.transitionOptions = []+            for page in SettingsPage.tabs {+                let toolbar = SettingsToolbarActions()+                toolbar.didChange = { [weak tabs] in tabs?.refreshToolbar() }+                tabs.pageActions[page] = toolbar+                let root = MacSettingsPageRoot(+                    page: page, model: model, navigation: navigation,+                    announcements: announcements, openMainWindow: openMainWindow, toolbar: toolbar)+                let host = NSHostingController(rootView: root)+                host.sceneBridgingOptions = []+                let item = NSTabViewItem(viewController: host)+                item.identifier = page.rawValue+                item.label = String(localized: String.LocalizationValue(page.title))+                item.image = NSImage(systemSymbolName: page.symbol, accessibilityDescription: item.label)+                tabs.addTabViewItem(item)+            }+            let window = NSWindow(+                contentRect: NSRect(x: 0, y: 0, width: 640, height: 560),+                styleMask: [.titled, .closable, .miniaturizable, .resizable],+                backing: .buffered, defer: false)+            window.identifier = NSUserInterfaceItemIdentifier(Self.identifier)+            window.setAccessibilityIdentifier(Self.identifier)+            window.title = String(localized: "Settings")+            window.contentMinSize = NSSize(width: 640, height: 480)+            window.isReleasedWhenClosed = false+            window.tabbingMode = .disallowed+            window.contentViewController = tabs+            window.center()+            controller = NSWindowController(window: window)+        }+        controller?.showWindow(nil)+        controller?.window?.makeKeyAndOrderFront(nil)+        NSApplication.shared.activate()+    }+}++private struct MacSettingsPageRoot: View {+    let page: SettingsPage+    let model: AppLibraryModel+    let navigation: AppNavigation+    let announcements: AnnouncementSeenState+    let openMainWindow: () -> Void+    let toolbar: SettingsToolbarActions++    var body: some View {+        NavigationStack {+            SettingsScreen(+                page: page, model: model, navigation: navigation,+                dismissSheet: nil, openMainWindow: openMainWindow)+        }+        .environment(\.nativeSettingsToolbar, toolbar)+        .environment(\.siteNames, model.siteNames)+        .environment(announcements)+        .environment(\.intentEditSessions, navigation)+    }+}++private final class MacSettingsTabsController: NSTabViewController {+    var pageActions: [SettingsPage: SettingsToolbarActions] = [:]+    private static let backID = NSToolbarItem.Identifier("settings-native-back")+    private static let cancelID = NSToolbarItem.Identifier("settings-native-cancel")+    private static let saveID = NSToolbarItem.Identifier("settings-native-save")++    private var actions: SettingsToolbarActions? {+        guard tabViewItems.indices.contains(selectedTabViewItemIndex),+              let raw = tabViewItems[selectedTabViewItemIndex].identifier as? String,+              let page = SettingsPage(rawValue: raw) else { return nil }+        return pageActions[page]+    }++    override func viewDidAppear() {+        super.viewDidAppear()+        refreshToolbar()+    }++    override func tabView(_ tabView: NSTabView, didSelect tabViewItem: NSTabViewItem?) {+        super.tabView(tabView, didSelect: tabViewItem)+        refreshToolbar()+    }++    override func toolbarAllowedItemIdentifiers(_ toolbar: NSToolbar) -> [NSToolbarItem.Identifier] {+        super.toolbarAllowedItemIdentifiers(toolbar) + [Self.backID, Self.cancelID, Self.saveID]+    }++    override func toolbar(+        _ toolbar: NSToolbar, itemForItemIdentifier identifier: NSToolbarItem.Identifier,+        willBeInsertedIntoToolbar flag: Bool+    ) -> NSToolbarItem? {+        let selector: Selector+        switch identifier {+        case Self.backID: selector = #selector(performBack(_:))+        case Self.cancelID: selector = #selector(performCancel(_:))+        case Self.saveID: selector = #selector(performSave(_:))+        default: return super.toolbar(toolbar, itemForItemIdentifier: identifier, willBeInsertedIntoToolbar: flag)+        }+        let item = NSToolbarItem(itemIdentifier: identifier)+        let button = NSButton(title: "", target: self, action: selector)+        button.bezelStyle = .texturedRounded+        button.imagePosition = .imageOnly+        button.frame = NSRect(x: 0, y: 0, width: 32, height: 28)+        item.view = button+        return item+    }++    func refreshToolbar() {+        guard isViewLoaded, let toolbar = view.window?.toolbar else { return }+        let entries: [(NSToolbarItem.Identifier, SettingsToolbarActions.Action?)] = [+            (Self.backID, actions?.back), (Self.cancelID, actions?.cancel), (Self.saveID, actions?.save)+        ]+        for (identifier, action) in entries {+            if action == nil, let index = toolbar.items.firstIndex(where: { $0.itemIdentifier == identifier }) {+                toolbar.removeItem(at: index)+            }+        }+        for (identifier, action) in entries {+            guard let action else { continue }+            if !toolbar.items.contains(where: { $0.itemIdentifier == identifier }) {+                toolbar.insertItem(withItemIdentifier: identifier, at: identifier == Self.backID ? 0 : toolbar.items.count)+            }+            guard let item = toolbar.items.first(where: { $0.itemIdentifier == identifier }),+                  let button = item.view as? NSButton else { continue }+            item.label = identifier == Self.backID ? String(localized: "Back")+                : (identifier == Self.cancelID ? String(localized: "Cancel") : String(localized: "Save"))+            item.paletteLabel = action.label+            button.image = NSImage(systemSymbolName: action.symbol, accessibilityDescription: action.label)+            button.toolTip = action.label+            button.setAccessibilityLabel(action.label)+            button.setAccessibilityIdentifier(action.identifier)+        }+    }++    @objc private func performBack(_ sender: Any?) { actions?.back?.perform() }+    @objc private func performCancel(_ sender: Any?) { actions?.cancel?.perform() }+    @objc private func performSave(_ sender: Any?) { actions?.save?.perform() }+}++struct MacSettingsCommands: Commands {+    let settingsWindow: MacSettingsWindow+    let model: AppLibraryModel+    let navigation: AppNavigation+    let announcements: AnnouncementSeenState+    @Environment(\.openWindow) private var openWindow++    var body: some Commands {+        CommandGroup(replacing: .appSettings) {+            Button("Settings…") {+                let action = openWindow+                settingsWindow.show(+                    model: model, navigation: navigation, announcements: announcements,+                    openMainWindow: { action(id: AsterismApp.mainWindowID) })+            }+            .keyboardShortcut(",", modifiers: .command)+        }+    }+}+#endif
Asterism/Asterism/Support/SettingsToolbarActions.swift Added +75 / -0
diff --git a/Asterism/Asterism/Support/SettingsToolbarActions.swift b/Asterism/Asterism/Support/SettingsToolbarActions.swiftnew file mode 100644index 00000000..6dbd94eb--- /dev/null+++ b/Asterism/Asterism/Support/SettingsToolbarActions.swift@@ -0,0 +1,75 @@+import Foundation+import SwiftUI++/// Semantic actions for a Settings page hosted by the native window owner.+/// Ordinary SwiftUI scenes keep their existing toolbar behavior when this is nil.+@MainActor+final class SettingsToolbarActions {+    struct Action {+        let identifier: String+        let label: String+        let symbol: String+        let perform: () -> Void+    }++    private var backOwner: UUID?+    private var editorOwner: UUID?+    private(set) var back: Action?+    private(set) var cancel: Action?+    private(set) var save: Action?+    var didChange: (() -> Void)?++    func setBack(owner: UUID, action: @escaping () -> Void) {+        backOwner = owner+        back = Action(identifier: "settings-navigation-back", label: String(localized: "Back"),+                      symbol: "chevron.left", perform: action)+        didChange?()+    }++    func clearBack(owner: UUID) {+        guard backOwner == owner else { return }+        backOwner = nil+        back = nil+        didChange?()+    }++    func setEditor(owner: UUID, cancel: Action, save: Action) {+        editorOwner = owner+        self.cancel = cancel+        self.save = save+        didChange?()+    }++    func clearEditor(owner: UUID) {+        guard editorOwner == owner else { return }+        editorOwner = nil+        cancel = nil+        save = nil+        didChange?()+    }+}++extension EnvironmentValues {+    @Entry var nativeSettingsToolbar: SettingsToolbarActions? = nil+}++private struct NativeSettingsBackControl: ViewModifier {+    @Environment(\.nativeSettingsToolbar) private var toolbar+    @Environment(\.dismiss) private var dismiss+    @State private var owner = UUID()++    func body(content: Content) -> some View {+        content+            .onAppear {+                let action = dismiss+                toolbar?.setBack(owner: owner) { action() }+            }+            .onDisappear { toolbar?.clearBack(owner: owner) }+    }+}++extension View {+    func nativeSettingsBackControl() -> some View {+        modifier(NativeSettingsBackControl())+    }+}
Asterism/Asterism/ViewModels/AppLibraryModel.swift Modified +2 / -2
diff --git a/Asterism/Asterism/ViewModels/AppLibraryModel.swift b/Asterism/Asterism/ViewModels/AppLibraryModel.swiftindex 7d5cd789..cd8de832 100644--- a/Asterism/Asterism/ViewModels/AppLibraryModel.swift+++ b/Asterism/Asterism/ViewModels/AppLibraryModel.swift@@ -2964,9 +2964,9 @@ public final class AppLibraryModel {     }      /// Provides a settings backup model backed by the current repository.-    public func settingsBackupModel() -> SettingsBackupModel? {+    public func settingsBackupModel(scavengesOnInit: Bool = true) -> SettingsBackupModel? {         guard let exporter = backupExporter() else { return nil }-        return SettingsBackupModel(exporter: exporter)+        return SettingsBackupModel(exporter: exporter, scavengesOnInit: scavengesOnInit)     }      /// The backup exporter both rows that export a backup are built over — the
Asterism/Asterism/ViewModels/SettingsBackupModel.swift Modified +4 / -4
diff --git a/Asterism/Asterism/ViewModels/SettingsBackupModel.swift b/Asterism/Asterism/ViewModels/SettingsBackupModel.swiftindex c7485a19..3aa42a16 100644--- a/Asterism/Asterism/ViewModels/SettingsBackupModel.swift+++ b/Asterism/Asterism/ViewModels/SettingsBackupModel.swift@@ -299,10 +299,10 @@ public final class SettingsBackupModel {      // MARK: - Init -    /// Creates the model over a stage, which scavenges any stale backup files-    /// from prior sessions as it is built.-    public init(exporter: any BackupExporting) {-        stage = BackupExportStage(exporter: exporter)+    /// Creates the model over a stage, which scavenges stale backup files+    /// from prior sessions by default.+    public init(exporter: any BackupExporting, scavengesOnInit: Bool = true) {+        stage = BackupExportStage(exporter: exporter, scavengesOnInit: scavengesOnInit)     }      // MARK: - Export
Asterism/Asterism/Views/CreatorRolesView.swift Modified +25 / -4
diff --git a/Asterism/Asterism/Views/CreatorRolesView.swift b/Asterism/Asterism/Views/CreatorRolesView.swiftindex 6d352e73..fd24067d 100644--- a/Asterism/Asterism/Views/CreatorRolesView.swift+++ b/Asterism/Asterism/Views/CreatorRolesView.swift@@ -12,6 +12,8 @@ import SwiftUI /// toggle that turns dragging on. struct CreatorRolesListView: View {     @State private var model: CreatorRolesModel+    @State private var nativeToolbarOwner = UUID()+    @Environment(\.nativeSettingsToolbar) private var nativeToolbar      init(model: CreatorRolesModel) {         _model = State(initialValue: model)@@ -32,6 +34,26 @@ struct CreatorRolesListView: View {         .listEditToolbarButton(identifier: "settings-creator-roles-edit-button")         .toolbar { orderToolbarItems }         .task { await model.load() }+        .onAppear { updateNativeOrderActions() }+        .onChange(of: model.hasUnsavedOrder) { _, _ in updateNativeOrderActions() }+        .onDisappear { nativeToolbar?.clearEditor(owner: nativeToolbarOwner) }+    }++    private func updateNativeOrderActions() {+        guard let nativeToolbar else { return }+        guard model.hasUnsavedOrder else {+            nativeToolbar.clearEditor(owner: nativeToolbarOwner)+            return+        }+        let model = model+        nativeToolbar.setEditor(+            owner: nativeToolbarOwner,+            cancel: .init(identifier: "settings-creator-roles-order-cancel",+                          label: String(localized: "Discard the new order"), symbol: "xmark",+                          perform: { model.cancelOrder() }),+            save: .init(identifier: "settings-creator-roles-order-save",+                        label: String(localized: "Save the new order"), symbol: "checkmark",+                        perform: { Task { await model.saveOrder() } }))     }      // MARK: - The order's two ways out (Req 2.5, T-2328)@@ -127,10 +149,7 @@ struct CreatorRolesListView: View {                 ForEach(model.rows) { row in                     roleRow(row)                 }-                // Req 2.5. The drag stages the order and writes nothing-                // (T-2328, Q99 of `work-creators`); the toolbar's Save sends the whole active-                // order, because the repository numbers what it is given-                // rather than applying a pair of indices (Q58).+                // The drag stages the order; only Save writes it.                 .onMove { source, destination in                     model.move(from: source, to: destination)                 }@@ -160,6 +179,7 @@ struct CreatorRolesListView: View {     private func roleRow(_ row: CreatorRolesModel.Row) -> some View {         NavigationLink {             CreatorRoleDetailView(model: model.detailModel(for: row))+                .nativeSettingsBackControl()         } label: {             HStack(spacing: 10) {                 // A removed role wears the type pill knocked down, which is the@@ -180,6 +200,7 @@ struct CreatorRolesListView: View {         }         .accessibilityIdentifier("creator-role-row-\(row.id.uuidString)")         .accessibilityLabel(row.creditLine.map { "\(row.name), \($0)" } ?? row.name)+     } } 
Asterism/Asterism/Views/SettingsView.swift Modified +131 / -107
diff --git a/Asterism/Asterism/Views/SettingsView.swift b/Asterism/Asterism/Views/SettingsView.swiftindex ae73e685..5cc5871e 100644--- a/Asterism/Asterism/Views/SettingsView.swift+++ b/Asterism/Asterism/Views/SettingsView.swift@@ -3,8 +3,40 @@ import AsterismCore import ConstellationKit import SwiftUI -/// Settings surface presenting backup export and import actions.+/// A settings root selected by its host. Mobile shows all sections; native Mac+/// tabs select direct destinations or one of the operational pages.+enum SettingsPage: String, Hashable {+    case all, general, sites, maintenance+    case workTypes = "work-types"+    case creatorRoles = "creator-roles"++    static let tabs: [Self] = [.general, .sites, .workTypes, .creatorRoles, .maintenance]++    var title: String {+        switch self {+        case .all: "Settings"+        case .general: "General"+        case .sites: "Sites"+        case .workTypes: "Work types"+        case .creatorRoles: "Creator roles"+        case .maintenance: "Maintenance"+        }+    }++    var symbol: String {+        switch self {+        case .all, .general: "gearshape"+        case .sites: "globe"+        case .workTypes: "tag"+        case .creatorRoles: "person.text.rectangle"+        case .maintenance: "wrench.and.screwdriver"+        }+    }+}++/// Settings sections and their existing action presenters. struct SettingsView: View {+    private let page: SettingsPage     @State private var model: SettingsBackupModel     @State private var importModel: SettingsBackupImportModel?     /// Collapsed on every open (T-2117, Q5): Debug is an occasional surface,@@ -128,6 +160,7 @@ struct SettingsView: View {     #endif      init(+        page: SettingsPage = .all,         model: SettingsBackupModel,         importModel: SettingsBackupImportModel? = nil,         isAwaitingFirstSync: Bool = false,@@ -151,6 +184,7 @@ struct SettingsView: View {         runBackgroundExport: (() async -> BackgroundExportOutcome)? = nil,         emptyLibrary: EmptyLibraryRowModel? = nil     ) {+        self.page = page         _model = State(initialValue: model)         _importModel = State(initialValue: importModel)         _syncModel = State(initialValue: syncModel)@@ -184,13 +218,33 @@ struct SettingsView: View {         #endif     } +    @ViewBuilder     var body: some View {+        switch page {+        case .all:+            captureActions(generalContent)+        case .general:+            generalContent+        case .maintenance:+            captureActions(settingsList)+        case .sites:+            if let sitesModel, let siteDetailModel {+                SitesListView(model: sitesModel, detailModel: siteDetailModel)+            }+        case .workTypes:+            if let workTypesModel { WorkTypesListView(model: workTypesModel) }+        case .creatorRoles:+            if let creatorRolesModel { CreatorRolesListView(model: creatorRolesModel) }+        }+    }++    private var generalContent: some View {         #if DEBUG         // `empty-library`: the row's dialog and its sharing surface, attached to         // the `List` rather than to the row — the lazy-row rule every other         // presentation on this screen follows. Compiled out of `Personal` with         // the row itself (Req 1.1).-        listContent+        backupContent             .confirmationDialog(                 EmptyLibraryModel.confirmationTitle,                 isPresented: Binding(@@ -225,50 +279,37 @@ struct SettingsView: View {                 identifier: "settings-empty-library-share-sheet",                 onCompletion: { outcome in emptyLibraryModel?.handleShareOutcome(outcome) })         #else-        listContent+        backupContent         #endif     } -    private var listContent: some View {+    private var settingsList: some View {         List {-            // Sites leads (T-2117): site management is the reader-facing-            // control; the sync status that used to sit here is debug-tier now-            // and lives in the collapsed section at the bottom.-            sitesSection--            workTypesSection--            creatorRolesSection-            if let detachedAssociationNotesModel {+            if page == .all { librarySection }+            if page == .all || page == .general {+                aboutSection                 Section {-                    NavigationLink {-                        DetachedAssociationNotesView(model: detachedAssociationNotesModel, snapshotGeneration: snapshotGeneration, onSaved: onAssociationNoteSaved)-                    } label: { Label("Detached link notes", systemImage: "note.text") }-                    .accessibilityIdentifier("settings-detached-association-notes")-                }-            }--            aboutSection--            Section {-                interruptedImportRow-                interruptedEmptyRow-                backupRow-                if let importModel {-                    SettingsBackupImportView(-                        model: importModel, isAwaitingFirstSync: isAwaitingFirstSync,-                        onConfirmArriving: { showingArrivingImportConfirmation = true })+                    interruptedImportRow+                    interruptedEmptyRow+                    backupRow+                    if let importModel {+                        SettingsBackupImportView(+                            model: importModel, isAwaitingFirstSync: isAwaitingFirstSync,+                            onConfirmArriving: { showingArrivingImportConfirmation = true })+                    }+                } header: {+                    ConstellationSectionHeader("Backup", accent: .violet)                 }-            } header: {-                ConstellationSectionHeader("Backup", accent: .violet)             }--            pendingCapturesSection--            debugSection+            if page == .all || page == .maintenance { maintenanceSection }+            if page == .all || page == .general { debugSection }         }-        .navigationTitle("Settings")+        .navigationTitle(page.title)         .accessibilityIdentifier("settings-view")+    }++    private var backupContent: some View {+        settingsList         // Attached to the List, not to any Section. When the sync rows had a         // top-level Section of their own, giving that Section `.task` and an         // accessibility identifier removed every one of its rows from the@@ -324,6 +365,13 @@ struct SettingsView: View {             identifier: "settings-backup-share-sheet",             onCompletion: { outcome in model.handleShareOutcome(outcome) }         )+    }++    /// Only the pages that draw captures own this confirmation. General owns+    /// the backup/Debug presenters separately, so mounted Mac tabs cannot+    /// present the same shared Empty Library operation twice.+    private func captureActions<Content: View>(_ content: Content) -> some View {+        content         // Req 6.10's delete asks first, like every other destructive action in the         // app. `presenting:` hands the destructive button the row the dialog was         // built from, because SwiftUI runs the dismissal below — which clears the@@ -377,6 +425,7 @@ struct SettingsView: View {                         document(guide, in: announcements)                             .navigationTitle(guide.documentTitle)                             .inlineNavigationTitle()+                            .nativeSettingsBackControl()                     } label: {                         Label(guide.documentTitle, systemImage: "book")                     }@@ -387,6 +436,7 @@ struct SettingsView: View {                         document(note, in: announcements)                             .navigationTitle(note.documentTitle)                             .inlineNavigationTitle()+                            .nativeSettingsBackControl()                             // On the destination rather than on the row: a row                             // that stored on *tap* would store when a swipe-back                             // cancelled the push. Nothing equivalent hangs off@@ -550,31 +600,32 @@ struct SettingsView: View {      // MARK: - Preserved captures (pending-capture-queue) -    /// Its own `Captures` section, directly below the Backup section that carries-    /// the interrupted-import notice (Q44 of this spec's log answers Req 2.5's-    /// "alongside" with adjacency rather than co-location). The rows match that-    /// notice's affordance — the same icon-and-sentence shape, because both say-    /// the same kind of thing: this happened and the library is not yet what you-    /// expect.-    ///-    /// The two differ on one point, deliberately. The interrupted-import notice-    /// cannot be dismissed, because an import that stopped partway did not become-    /// complete by being ignored; the waiting count is the same — the captures are-    /// still there. The **drain report** below them can be, because it describes-    /// something that already happened (Req 10.6).-    ///-    /// Q37's vocabulary throughout: waiting, set aside, refused. Nothing merely-    /// waiting is ever called set aside.+    /// Recovery and preserved-capture controls share one Maintenance section.+    /// Existing capture visibility, wording and confirmation semantics remain+    /// with their rows; a detached-note model alone also keeps the section visible.     @ViewBuilder-    private var pendingCapturesSection: some View {-        if pendingCaptureWaitingNotice != nil || drainReportNotice != nil-            || !setAsideCaptures.isEmpty {+    private var maintenanceSection: some View {+        if detachedAssociationNotesModel != nil || pendingCaptureWaitingNotice != nil+            || drainReportNotice != nil || !setAsideCaptures.isEmpty {             Section {+                if let detachedAssociationNotesModel {+                    NavigationLink {+                        DetachedAssociationNotesView(+                            model: detachedAssociationNotesModel,+                            snapshotGeneration: snapshotGeneration,+                            onSaved: onAssociationNoteSaved)+                            .nativeSettingsBackControl()+                    } label: {+                        Label("Detached link notes", systemImage: "note.text")+                    }+                    .accessibilityIdentifier("settings-detached-association-notes")+                }                 waitingCapturesRow                 drainReportRows                 setAsideCaptureRows             } header: {-                ConstellationSectionHeader("Captures", accent: .violet)+                ConstellationSectionHeader("Maintenance", accent: .violet)+                    .accessibilityIdentifier("settings-maintenance-section")             }         }     }@@ -695,64 +746,34 @@ struct SettingsView: View {         }     } -    // MARK: - Sites (Req 6.1)+    // MARK: - Library configuration -    /// First on the screen (T-2117): site management is what a reader opens-    /// Settings for; backup sits below it and the diagnostics behind Debug.     @ViewBuilder-    private var sitesSection: some View {-        if let sitesModel, let siteDetailModel {+    private var librarySection: some View {+        if (sitesModel != nil && siteDetailModel != nil)+            || workTypesModel != nil || creatorRolesModel != nil {             Section {-                NavigationLink {-                    SitesListView(model: sitesModel, detailModel: siteDetailModel)-                } label: {-                    Label("Sites", systemImage: "globe")+                if let sitesModel, let siteDetailModel {+                    NavigationLink {+                        SitesListView(model: sitesModel, detailModel: siteDetailModel)+                    } label: { Label("Sites", systemImage: "globe") }+                    .accessibilityIdentifier("settings-sites-button")                 }-                .accessibilityIdentifier("settings-sites-button")-            } header: {-                ConstellationSectionHeader("Sites", accent: .violet)-            }-        }-    }--    // MARK: - Work types (configurable-work-types Req 1.1)--    /// Between Sites and Backup: it is reader-facing site-and-library-    /// configuration like Sites, and it is not a diagnostic.-    @ViewBuilder-    private var workTypesSection: some View {-        if let workTypesModel {-            Section {-                NavigationLink {-                    WorkTypesListView(model: workTypesModel)-                } label: {-                    Label("Work types", systemImage: "tag")+                if let workTypesModel {+                    NavigationLink {+                        WorkTypesListView(model: workTypesModel)+                    } label: { Label("Work types", systemImage: "tag") }+                    .accessibilityIdentifier("settings-work-types-button")                 }-                .accessibilityIdentifier("settings-work-types-button")-            } header: {-                ConstellationSectionHeader("Work types", accent: .violet)-            }-        }-    }--    // MARK: - Creator roles (work-creators Req 2.1)--    /// Between Work types and Backup, for the reason Work types sits where it-    /// does: it is reader-facing library configuration, and it is not a-    /// diagnostic. The two lists are siblings — one names what a work *is*, the-    /// other what a creator *did* — so they are neighbours.-    @ViewBuilder-    private var creatorRolesSection: some View {-        if let creatorRolesModel {-            Section {-                NavigationLink {-                    CreatorRolesListView(model: creatorRolesModel)-                } label: {-                    Label("Creator roles", systemImage: "person.text.rectangle")+                if let creatorRolesModel {+                    NavigationLink {+                        CreatorRolesListView(model: creatorRolesModel)+                    } label: { Label("Creator roles", systemImage: "person.text.rectangle") }+                    .accessibilityIdentifier("settings-creator-roles-button")                 }-                .accessibilityIdentifier("settings-creator-roles-button")             } header: {-                ConstellationSectionHeader("Creator roles", accent: .violet)+                ConstellationSectionHeader("Library", accent: .violet)+                    .accessibilityIdentifier("settings-library-section")             }         }     }@@ -767,6 +788,7 @@ struct SettingsView: View {         if let diagnosticsModel {             NavigationLink {                 LibraryDiagnosticsView(model: diagnosticsModel)+                    .nativeSettingsBackControl()             } label: {                 Label("Check Library", systemImage: "stethoscope")             }@@ -877,6 +899,7 @@ struct SettingsView: View {                         if routesToCheckLibrary, let diagnosticsModel {                             NavigationLink {                                 LibraryDiagnosticsView(model: diagnosticsModel)+                                    .nativeSettingsBackControl()                             } label: {                                 Text("Check Library")                             }@@ -1019,6 +1042,7 @@ struct SettingsView: View {                     if model.routesToCheckLibrary, let diagnosticsModel {                         NavigationLink {                             LibraryDiagnosticsView(model: diagnosticsModel)+                                .nativeSettingsBackControl()                         } label: {                             Text("Check Library")                         }
Asterism/Asterism/Views/SitesView.swift Modified +1 / -0
diff --git a/Asterism/Asterism/Views/SitesView.swift b/Asterism/Asterism/Views/SitesView.swiftindex a384dfd2..cdebab17 100644--- a/Asterism/Asterism/Views/SitesView.swift+++ b/Asterism/Asterism/Views/SitesView.swift@@ -60,6 +60,7 @@ struct SitesListView: View {             // straight back to it.             if let detail = detailModel(row.site, { await model.load() }) {                 SiteDetailView(model: detail)+                    .nativeSettingsBackControl()             }         } label: {             HStack(spacing: 10) {
Asterism/Asterism/Views/WorkTypesView.swift Modified +1 / -0
diff --git a/Asterism/Asterism/Views/WorkTypesView.swift b/Asterism/Asterism/Views/WorkTypesView.swiftindex 8ec0f3de..be7469ed 100644--- a/Asterism/Asterism/Views/WorkTypesView.swift+++ b/Asterism/Asterism/Views/WorkTypesView.swift@@ -115,6 +115,7 @@ struct WorkTypesListView: View {     private func typeRow(_ row: WorkTypesModel.Row) -> some View {         NavigationLink {             WorkTypeDetailView(model: model.detailModel(for: row))+                .nativeSettingsBackControl()         } label: {             HStack(spacing: 10) {                 // Q23: a removed type wears the type pill knocked down, which is
Asterism/AsterismTests/SettingsBackupModelTests.swift Modified +7 / -0
diff --git a/Asterism/AsterismTests/SettingsBackupModelTests.swift b/Asterism/AsterismTests/SettingsBackupModelTests.swiftindex 8a28a4c7..1e7501aa 100644--- a/Asterism/AsterismTests/SettingsBackupModelTests.swift+++ b/Asterism/AsterismTests/SettingsBackupModelTests.swift@@ -526,6 +526,13 @@ struct SettingsBackupModelTests {         let _ = SettingsBackupModel(exporter: mock)         #expect(mock.scavengeCallCount == 1)     }++    @Test("Can skip stale file scavenging on initialization")+    @MainActor func skipsScavengingOnInitWhenDisabled() {+        let mock = MockBackupExporting()+        let _ = SettingsBackupModel(exporter: mock, scavengesOnInit: false)+        #expect(mock.scavengeCallCount == 0)+    } }  // MARK: - Test Doubles
Asterism/AsterismTests/SettingsToolbarActionsTests.swift Added +46 / -0
diff --git a/Asterism/AsterismTests/SettingsToolbarActionsTests.swift b/Asterism/AsterismTests/SettingsToolbarActionsTests.swiftnew file mode 100644index 00000000..25752b14--- /dev/null+++ b/Asterism/AsterismTests/SettingsToolbarActionsTests.swift@@ -0,0 +1,46 @@+import Foundation+import Testing++@testable import Asterism++/// App-side callback lifetimes; no window, store or persistent preferences.+@Suite("Native Settings toolbar action ownership")+@MainActor+struct SettingsToolbarActionsTests {+    @Test("a disappearing old destination cannot clear the current Back action")+    func lateBackCleanupPreservesCurrentDestination() {+        let actions = SettingsToolbarActions()+        let old = UUID(), current = UUID()+        var invoked: [String] = []+        var changes = 0+        actions.didChange = { changes += 1 }+        actions.setBack(owner: old) { invoked.append("old") }+        actions.setBack(owner: current) { invoked.append("current") }+        actions.clearBack(owner: old)+        #expect(changes == 2)+        actions.back?.perform()+        #expect(invoked == ["current"])+        actions.clearBack(owner: current)+        #expect(actions.back == nil)+        #expect(changes == 3)+    }++    @Test("late editor cleanup preserves the current Save and Cancel handlers")+    func lateEditorCleanupPreservesCurrentDraft() {+        let actions = SettingsToolbarActions()+        let old = UUID(), current = UUID()+        var invoked: [String] = []+        func action(_ name: String) -> SettingsToolbarActions.Action {+            .init(identifier: name, label: name, symbol: "checkmark", perform: { invoked.append(name) })+        }+        actions.setEditor(owner: old, cancel: action("old cancel"), save: action("old save"))+        actions.setEditor(owner: current, cancel: action("current cancel"), save: action("current save"))+        actions.clearEditor(owner: old)+        actions.cancel?.perform()+        actions.save?.perform()+        #expect(invoked == ["current cancel", "current save"])+        actions.clearEditor(owner: current)+        #expect(actions.cancel == nil)+        #expect(actions.save == nil)+    }+}
Asterism/AsterismUITests/AssociationNotesUITests.swift Modified +1 / -0
diff --git a/Asterism/AsterismUITests/AssociationNotesUITests.swift b/Asterism/AsterismUITests/AssociationNotesUITests.swiftindex 60f3b134..5aff2133 100644--- a/Asterism/AsterismUITests/AssociationNotesUITests.swift+++ b/Asterism/AsterismUITests/AssociationNotesUITests.swift@@ -1226,6 +1226,7 @@ final class AssociationNotesUITests: XCTestCase {     private func openDetachedNotes() {         #if os(macOS)         app.typeKey(",", modifierFlags: .command)+        activate(app.windows["settings-window"].toolbars.buttons["Maintenance"])         #else         activate(app.buttons["settings-button"])         #endif
Asterism/AsterismUITests/SettingsLayoutUITests.swift Added +327 / -0
diff --git a/Asterism/AsterismUITests/SettingsLayoutUITests.swift b/Asterism/AsterismUITests/SettingsLayoutUITests.swiftnew file mode 100644index 00000000..ada231c3--- /dev/null+++ b/Asterism/AsterismUITests/SettingsLayoutUITests.swift@@ -0,0 +1,327 @@+import XCTest++/// T-2483: real platform settings roots, using the existing UUID-scoped stores.+final class SettingsLayoutUITests: XCTestCase {+    private let app = XCUIApplication()++    override func setUp() { continueAfterFailure = false; terminateAndWaitForExit(app) }+    override func tearDown() { terminateAndWaitForExit(app) }++    private func openSettings(scenario: String) {+        app.configureSyntheticLaunch(scenario: scenario)+        app.launch()+        waitFor(app.anyElement("recent-list"), "The isolated library opens", timeout: 60)+        #if os(macOS)+        app.typeKey(",", modifierFlags: .command)+        waitFor(settingsWindow.toolbars.buttons["General"], "Native Settings offers its General tab")+        #else+        let phoneRoute = app.buttons["settings-button"]+        let settingsRoute = phoneRoute.exists ? phoneRoute : app.buttons["sidebar-settings"]+        waitFor(settingsRoute, "Settings is reachable on phone and iPad").tap()+        waitFor(app.anyElement("settings-view"), "The combined mobile Settings opens")+        #endif+    }++    private func activate(_ element: XCUIElement) {+        #if os(macOS)+        waitFor(element, "The actual settings control exists")+        element.click()+        #else+        scrollUntilTappableAndTap(element, in: app, "The settings control is reachable")+        #endif+    }++    #if os(macOS)+    private var settingsWindow: XCUIElement {+        app.windows["settings-window"]+    }+    private func selectSettingsTab(_ title: String) {+        let titles = ["General", "Sites", "Work types",+                      "Creator roles", "Maintenance"]+        guard titles.contains(title) else { XCTFail("Unknown settings tab"); return }+        activate(settingsWindow.toolbars.buttons[title])+    }+    #endif++    func testConfigurationGroupingAndDestinations() {+        openSettings(scenario: "seeded-composed")+        let destinations = [+            ("Sites", "settings-sites-button", "settings-sites-list"),+            ("Work types", "settings-work-types-button", "settings-work-types-list"),+            ("Creator roles", "settings-creator-roles-button", "settings-creator-roles-list")+        ]+        #if os(macOS)+        for (title, link, root) in destinations {+            selectSettingsTab(title)+            waitFor(settingsWindow.descendants(matching: .any).matching(identifier: root).firstMatch,+                    "The native tab immediately displays its destination")+            XCTAssertFalse(settingsWindow.buttons[link].exists, "No link-only landing row remains")+        }+        selectSettingsTab("General")+        XCTAssertTrue(settingsWindow.buttons["settings-export-backup-button"].exists,+                      "General retains backup controls")+        XCTAssertFalse(settingsWindow.buttons["settings-detached-association-notes"].exists,+                       "Detached notes belong to Maintenance")+        #else+        let header = waitFor(app.anyElement("settings-library-section"), "One Library section groups the rows")+        var previous = header.frame.midY+        for (_, link, _) in destinations {+            let row = waitFor(app.buttons[link], "The original configuration row is available")+            XCTAssertGreaterThan(row.frame.midY, previous, "Configuration rows retain their specified order")+            previous = row.frame.midY+        }+        XCTAssertEqual(app.descendants(matching: .any).matching(identifier: "settings-library-section").count, 1)+        for (_, link, root) in destinations {+            activate(app.buttons[link])+            waitFor(app.anyElement(root), "Each original destination still opens")+            app.goBack()+            waitFor(app.anyElement("settings-library-section"), "Back returns to the grouped section")+        }+        #endif+    }++    func testDetachedNotesBelongToMaintenanceAndStillOpen() {+        openSettings(scenario: "seeded-association-notes")+        #if os(macOS)+        selectSettingsTab("Maintenance")+        #endif+        let header = app.anyElement("settings-maintenance-section")+        #if !os(macOS)+        scrollUntilPresent(header, in: app, "Maintenance is reachable below Backup")+        #endif+        waitFor(header, "Maintenance groups recovery content")+        activate(app.buttons["settings-detached-association-notes"])+        waitFor(app.staticTexts["Earlier chapter link note"], "Detached notes retain their saved text")+        XCTAssertEqual(app.buttons.matching(identifier: "detached-association-note-recover").count, 1,+                       "The existing coherent recovery route is preserved")+    }++    func testPreservedCapturesBelongToMaintenance() {+        openSettings(scenario: "seeded-pending-captures")+        #if os(macOS)+        selectSettingsTab("Maintenance")+        #endif+        let header = app.anyElement("settings-maintenance-section")+        #if !os(macOS)+        scrollUntilPresent(header, in: app, "Maintenance is reachable below Backup")+        #endif+        waitFor(header, "Maintenance contains preserved captures")+        #if !os(macOS)+        scrollUntilPresent(app.anyElement("settings-drain-report"), in: app, "The full report is reachable")+        #endif+        waitFor(app.anyElement("settings-drain-report"), "The prior drain report remains available")+        #if !os(macOS)+        scrollUntilPresent(app.buttons["settings-drain-report-entry"], in: app, "The report entry route is reachable")+        #endif+        waitFor(app.buttons["settings-drain-report-entry"], "The report retains its open-entry route")+        #if !os(macOS)+        scrollUntilPresent(app.buttons["settings-drain-report-dismiss"], in: app, "Dismiss is reachable")+        #endif+        waitFor(app.buttons["settings-drain-report-dismiss"], "The report retains Dismiss")+        #if !os(macOS)+        scrollUntilPresent(app.anyElement("settings-set-aside-capture"), in: app, "Set-aside captures are reachable")+        #endif+        waitFor(app.anyElement("settings-set-aside-capture"), "Set-aside captures retain their original row")+        XCTAssertFalse(+            app.staticTexts.matching(NSPredicate(+                format: "label ENDSWITH 'CAPTURES' OR value ENDSWITH 'CAPTURES'"+            )).firstMatch.exists,+            "Captures is no longer a separate styled section header")+    }++    #if !os(macOS)+    func testConfigurationRowsRemainReachableAtLargestText() {+        app.launchArguments += [+            "-UIPreferredContentSizeCategoryName", "UICTContentSizeCategoryAccessibilityXXXL"+        ]+        openSettings(scenario: "seeded-creators")+        for (rowID, rootID) in [+            ("settings-sites-button", "settings-sites-list"),+            ("settings-work-types-button", "settings-work-types-list"),+            ("settings-creator-roles-button", "settings-creator-roles-list")+        ] {+            let row = app.buttons[rowID]+            scrollUntilTappableAndTap(row, in: app, "Configuration is reachable at accessibility text size")+            waitFor(app.anyElement(rootID), "The original destination opens at accessibility text size")+            app.goBack()+            waitFor(app.anyElement("settings-view"), "Back returns to the same settings surface")+        }+    }+    #endif++    #if os(macOS)+    func testNativeTabsKeepConfigurationDraftsAndIndependentNavigation() {+        openSettings(scenario: "seeded-creators")+        selectSettingsTab("Work types")+        let name = settingsWindow.textFields["settings-work-types-name-field"]+        activate(name)+        name.typeText("Unsaved type")+        selectSettingsTab("Sites")+        let site = settingsWindow.buttons.matching(NSPredicate(format: "identifier BEGINSWITH 'site-row-'")).firstMatch+        activate(site)+        waitFor(app.anyElement("site-detail-view"), "The direct Sites root navigates into a site")+        selectSettingsTab("Work types")+        XCTAssertEqual(name.value as? String, "Unsaved type", "A tab switch keeps the unsaved name")+        selectSettingsTab("Sites")+        XCTAssertTrue(app.anyElement("site-detail-view").exists, "Each tab keeps its own navigation stack")+        activate(settingsWindow.buttons["settings-navigation-back"])+        waitFor(settingsWindow.descendants(matching: .any).matching(identifier: "settings-sites-list").firstMatch,+                "Native Back returns to the Sites root")+        selectSettingsTab("Creator roles")+        let rows = settingsWindow.buttons.matching(NSPredicate(format: "identifier BEGINSWITH 'creator-role-row-'"))+        waitFor(rows.firstMatch, "The actual role list loads")+        let before = rows.allElementsBoundByIndex.map(\.label)+        XCTAssertGreaterThan(before.count, 2)+        let first = rows.element(boundBy: 0)+        let last = rows.element(boundBy: 2)+        XCTAssertFalse(first.frame.isEmpty, "The native drag source has visible geometry")+        XCTAssertFalse(last.frame.isEmpty, "The native drop target has visible geometry")+        // macOS needs mouse events; press(forDuration:) synthesizes touch events.+        first.coordinate(withNormalizedOffset: .zero)+            .withOffset(CGVector(dx: 20, dy: first.frame.height / 2))+            .click(forDuration: 0.4,+                   thenDragTo: last.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)),+                   withVelocity: .slow, thenHoldForDuration: 0.5)+        let save = settingsWindow.buttons["settings-creator-roles-order-save"]+        waitFor(save, "Dragging stages a reorder before saving")+        let staged = rows.allElementsBoundByIndex.map(\.label)+        XCTAssertNotEqual(staged, before)+        selectSettingsTab("General")+        selectSettingsTab("Creator roles")+        XCTAssertEqual(rows.allElementsBoundByIndex.map(\.label), staged, "The staged order survives tab switching")+        XCTAssertTrue(save.exists, "The draft still offers its original Save")+        activate(settingsWindow.buttons["settings-creator-roles-order-cancel"])+        XCTAssertEqual(rows.allElementsBoundByIndex.map(\.label), before, "Cancel restores the stored order")+        XCTAssertFalse(save.exists, "Cancellation clears the pending reorder")+    }+    func testNativeSettingsEntryRoutesAndCloseReopenRetainState() {+        app.configureSyntheticLaunch(scenario: "seeded-creators")+        app.launch()+        waitFor(app.anyElement("recent-list"), "The isolated library opens", timeout: 60)+        activate(app.windows["main"].buttons["sidebar-settings"])+        waitFor(settingsWindow.toolbars.buttons["General"], "The sidebar opens native Settings")+        XCTAssertFalse(settingsWindow.buttons["settings-empty-library-run"].exists,+                       "Debug starts collapsed")+        selectSettingsTab("Work types")+        let name = settingsWindow.textFields["settings-work-types-name-field"]+        activate(name)+        name.typeText("Retained after close")+        selectSettingsTab("Sites")+        activate(settingsWindow.buttons.matching(NSPredicate(format: "identifier BEGINSWITH 'site-row-'" )).firstMatch)+        waitFor(app.anyElement("site-detail-view"), "The Sites stack has an open detail")+        closeNativeSettings()++        app.typeKey(",", modifierFlags: .command)+        waitFor(settingsWindow, "The shortcut reopens the same Settings window")+        XCTAssertTrue(app.anyElement("site-detail-view").exists, "Close/reopen keeps the Sites stack")+        selectSettingsTab("Work types")+        XCTAssertEqual(name.value as? String, "Retained after close", "Close/reopen keeps the unsaved name")+        openNativeSettingsFromMenu()+        XCTAssertEqual(app.windows.matching(identifier: "settings-window").count, 1,+                       "Menu, shortcut and sidebar share one window")+        XCTAssertEqual(name.value as? String, "Retained after close", "Focusing Settings does not rebuild its page")+    }++    func testNativeSettingsReturnsToClosedMainWindowAfterSidebarEntry() {+        verifyNativeMainWindowReturn(firstOpenFromMenu: false)+    }++    func testNativeSettingsReturnsToClosedMainWindowAfterMenuEntry() {+        verifyNativeMainWindowReturn(firstOpenFromMenu: true)+    }++    func testNativeConfigurationDetailsAndAboutKeepBackControls() {+        openSettings(scenario: "seeded-creators")+        for (title, prefix, detail, root) in [+            ("Work types", "work-type-row-", "work-type-detail-view", "settings-work-types-list"),+            ("Creator roles", "creator-role-row-", "creator-role-detail-view", "settings-creator-roles-list")+        ] {+            selectSettingsTab(title)+            activate(settingsWindow.buttons.matching(NSPredicate(format: "identifier BEGINSWITH %@", prefix)).firstMatch)+            waitFor(app.anyElement(detail), "The existing configuration detail opens")+            activate(settingsWindow.buttons["settings-navigation-back"])+            waitFor(app.anyElement(root), "Native Back returns to the configuration list")+        }+        selectSettingsTab("General")+        for identifier in ["settings-getting-started", "settings-release-notes"] {+            activate(settingsWindow.buttons[identifier])+            waitFor(settingsWindow.buttons["settings-navigation-back"], "The document retains native Back")+            XCTAssertFalse(settingsWindow.buttons["settings-export-backup-button"].exists,+                           "The document is pushed within its page")+            activate(settingsWindow.buttons["settings-navigation-back"])+            waitFor(settingsWindow.buttons["settings-export-backup-button"], "Back returns to General")+        }+    }++    func testNativeMaintenanceDeleteCancellationPreservesCapture() {+        openSettings(scenario: "seeded-pending-captures")+        selectSettingsTab("Maintenance")+        activate(settingsWindow.buttons["settings-set-aside-capture-delete"])+        let confirmation = app.buttons["settings-set-aside-capture-delete-confirm"]+        waitFor(confirmation, "Deleting a synthetic capture still requires confirmation")+        app.typeKey(XCUIKeyboardKey.escape.rawValue, modifierFlags: [])+        XCTAssertTrue(confirmation.waitForNonExistence(timeout: 10), "Escape cancels the confirmation")+        waitFor(settingsWindow.descendants(matching: .any).matching(identifier: "settings-set-aside-capture").firstMatch,+                "Cancellation leaves the capture intact")+    }++    private func openNativeSettingsFromMenu() {+        activate(app.menuBars.menuBarItems["Asterism"])+        activate(app.menuItems["Settings…"])+        waitFor(settingsWindow, "The menu opens native Settings")+    }++    private func closeNativeSettings() {+        activate(settingsWindow.buttons["_XCUI:CloseWindow"])+        XCTAssertTrue(settingsWindow.waitForNonExistence(timeout: 10), "Settings closes without terminating the app")+    }++    private func verifyNativeMainWindowReturn(firstOpenFromMenu: Bool) {+        app.configureSyntheticLaunch(scenario: "seeded-pending-captures")+        app.launch()+        waitFor(app.anyElement("recent-list"), "The isolated library opens", timeout: 60)+        if firstOpenFromMenu {+            openNativeSettingsFromMenu()+        } else {+            activate(app.windows["main"].buttons["sidebar-settings"])+            waitFor(settingsWindow, "The sidebar opens Settings")+        }+        // Keep Settings open: closing every window ends this single-Window app.+        activate(app.windows["main"].buttons["sidebar-stats"])+        waitFor(app.anyElement("stats-root"), "The saved main-window selection is Stats")+        activate(app.windows["main"].buttons["_XCUI:CloseWindow"])+        XCTAssertTrue(app.windows["main"].waitForNonExistence(timeout: 10), "The main window closes")+        XCTAssertTrue(settingsWindow.exists, "Settings stays available while the main window is closed")+        openNativeSettingsFromMenu()+        selectSettingsTab("Maintenance")+        activate(settingsWindow.buttons["settings-drain-report-entry"])+        let main = waitFor(app.windows["main"], "Settings reopens the main window")+        waitFor(main.buttons["entry-detail-update-button"], "The pending capture route wins over saved Stats", timeout: 30)+        XCTAssertFalse(main.descendants(matching: .any).matching(identifier: "stats-root").firstMatch.exists,+                       "Restoration does not overwrite the Settings destination")+        XCTAssertTrue(settingsWindow.exists, "Routing leaves Settings available")+    }++    #endif+}++#if os(macOS)+// UIJourneySupport belongs to the mobile test sources. These two primitive+// equivalents keep the native driver local without changing its assertions.+private extension SettingsLayoutUITests {+    @discardableResult+    func waitFor(+        _ element: XCUIElement, _ message: String, timeout: TimeInterval = 30,+        file: StaticString = #filePath, line: UInt = #line+    ) -> XCUIElement {+        XCTAssertTrue(element.waitForExistence(timeout: timeout), message, file: file, line: line)+        return element+    }+}++private extension XCUIApplication {+    func anyElement(_ identifier: String) -> XCUIElement {+        descendants(matching: .any).matching(identifier: identifier).firstMatch+    }+}+#endif

Docs (11)

CHANGELOG.md Modified +2 / -0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2932a3b9..33fca3c7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).  ### Changed +- **Settings layout (T-2483):** group Sites, Work types and Creator roles under Library on iOS/iPadOS, and expose each destination directly in a retained native Mac Settings window. Preserve page drafts, navigation, Back and Save/Cancel across tab changes and window reopening; routes back reopen the main window after restoring its state. Move Detached link notes and preserved captures into Maintenance, keeping their existing actions and confirmations. Avoid backup staging cleanup on Mac tabs that have no backup controls.+ - **Release qualification (T-2468):** record the owner-accepted duplicate/capture performance failures and missing current full-performance pass as release exceptions, retaining all measurements, assertions and source qualifications; further optimisation remains deferred.  - **Selected library history (T-2468):** scope creator-detail history reads to the selected works and avoid unused singleton capture variants while retaining complete validation for writes. Clarify how saved chapter notes link known characters and places and how authored link notes are recovered.
docs/agent-notes/testing.md Modified +6 / -0
diff --git a/docs/agent-notes/testing.md b/docs/agent-notes/testing.mdindex cb88e6e4..6d0cab24 100644--- a/docs/agent-notes/testing.md+++ b/docs/agent-notes/testing.md@@ -1998,3 +1998,9 @@ never start with a whole-bundle selector to obtain a narrower selection. Do not remove default serial settings. Match the selected source identifiers to raw case results/result-bundle inventory before recording success; a missing name, zero execution or an unexpected skip makes selection verification incomplete.++## Native Mac XCTest drags use mouse events (T-2483)++For native Mac `List.onMove`, use `XCUICoordinate.click(forDuration:thenDragTo:withVelocity:thenHoldForDuration:)`. The similarly shaped `press(forDuration:thenDragTo:)` is declared in `XCUICoordinate`'s **TouchEvents** category, while `click` is in **MouseEvents** (Xcode's `XCUIAutomation.framework/Headers/XCUICoordinate.h`). In the Settings role-order journey, the touch call executed without moving the row or entering the model's move handler. Switching only the driver to native mouse input passed with the original `.onMove`; custom drop adapters were unnecessary and removed.++`SettingsLayoutUITests.testNativeTabsKeepConfigurationDraftsAndIndependentNavigation` is the working example: start near the first row's left gutter, perform the mouse drag to the last row, then require the staged Save action, tab retention and cancellation. Keep the behavioral witnesses; a completed drag command alone proves nothing.
docs/asterism-design.md Modified +2 / -0
diff --git a/docs/asterism-design.md b/docs/asterism-design.mdindex 41365a98..9623b45a 100644--- a/docs/asterism-design.md+++ b/docs/asterism-design.md@@ -331,6 +331,8 @@ Both live under the Works tab too (`specs/work-creators/`), on the same route pa  ### 5.3 Settings (gear) +T-2483 (`specs/settings-layout/`): on iOS/iPadOS, Sites, Work types and Creator roles are navigation rows in one Library section. An app-owned native Mac Settings window provides General, Sites, Work types, Creator roles and Maintenance toolbar tabs; retained page hosts show configuration lists directly and preserve independent navigation and drafts across tab switches and window reopening. Native Back and staged-order Save/Cancel use the existing page actions. General holds About, Backup and collapsed Debug. Detached link notes and the existing preserved-capture controls share Maintenance on both platforms, with their existing recovery, report and confirmation behavior.+ Sites list: every stored site — untaught and taught — with mode and display name (Q10 of `specs/polish-and-export/`); tap to re-teach. Work types list. **Creator roles** (`specs/work-creators/`): the reader's own vocabulary for what a creator did on a work, seeded with `author`, `artist` and `translator` at the first open of a library and never re-seeded after that — a list the reader empties stays empty. The section lists the active roles **in the reader's order**, which is the order every credit's roles are drawn in everywhere else, and the order is set by dragging rows; beneath them sit the roles the reader removed, each with the number of credits still holding it. Removal hides a role rather than deleting it — the credits keep the identifier, and adding the name again restores that same role at the end of the list with the newly typed spelling. A role's own screen renames it, which reaches every credit holding it without writing one of them. Full-library backup export (§10). Deliberately buried.  ### 5.4 Stats
specs/OVERVIEW.md Modified +1 / -0
diff --git a/specs/OVERVIEW.md b/specs/OVERVIEW.mdindex af188024..908bb8d9 100644--- a/specs/OVERVIEW.md+++ b/specs/OVERVIEW.md@@ -2,6 +2,7 @@  | Name | Creation Date | Status | Summary | |------|---------------|--------|---------|+| [Settings Layout](settings-layout/requirements.md) | 2026-10-24 | Implemented — publication gates passed | T-2483. Group mobile configuration rows, provide direct Mac settings tabs, and collect detached notes/captures in Maintenance. | | [Character–Chapter Associations](#characterchapter-associations) | 2026-10-18 | In Progress — UI acceptance qualified; performance release exceptions accepted | T-2468. Persist grounded chapter-note links and exact pair annotations; shared known-character/place Save matching and duplicate-resolution continuity have focused verification. | | [Performance Signpost Names](#performance-signpost-names) | 2026-10-15 | In Progress — source implemented; acceptance blocked by host memory/scheduler pressure | T-2115. Replace milestone helper/category names with presentation and teaching names, preserve interval behavior, and guard emitter/metric agreement on the host. Physical sample verification remains owner-run. | | [Chosen-Day Notes](#chosen-day-notes) | 2026-10-15 | Complete — owner validated; phone UI gate qualified | T-2428. Optional day in the existing notes Shortcuts action, preserving default-today/latest-share results and typed values. |
specs/settings-layout/decision_log.md Added +68 / -0
diff --git a/specs/settings-layout/decision_log.md b/specs/settings-layout/decision_log.mdnew file mode 100644index 00000000..4071df13--- /dev/null+++ b/specs/settings-layout/decision_log.md@@ -0,0 +1,68 @@+# Settings Layout Decisions (T-2483)++| ID | Decision | Reason |+|---|---|---|+| Q1 | The inspected screenshot groups Sites, Work types and Creator roles into Library on mobile. | These are the three visibly circled configuration rows; retain their destination names and order. |+| Q2 | Native Mac tabs are General, Sites, Work types, Creator roles and Maintenance, each with its own navigation stack. | The three lists are direct roots; existing About/Backup/Debug and recovery controls remain reachable without adding a new data owner. |+| Q3 | Only all/general own backup/import/Empty Library presenters and sync work; only all/maintenance own capture deletion. | Multiple mounted native pages must not observe and present the same shared operation. |+| Q4 | Root configuration drafts and staged role order remain in their existing view-owned models across tab switches. | Rearranging navigation must not discard an unsaved name/order; existing Cancel remains the way to discard. |+| Q5 | This is implementation authorised directly by the owner, including new ticket creation; no extra naming or plan approval is requested. | Explicit user request overrides the generic smolspec naming/implementation gates. No schema/public/auth changes. |++## Decision 1: Locate native Settings tabs by title++**Date**: 2026-10-24+**Status**: accepted++### Context++Native macOS Settings turns the tabs into toolbar buttons. Runtime accessibility trees show their titles but no custom identifiers, both with identifiers on tab labels and on SwiftUI Tab content. Radio-button and custom-identifier queries therefore fail before exercising the page behavior.++### Decision++Keep the native toolbar tabs. Locate their buttons by title, scoped to the Settings window and its toolbar. The original scope was `com_apple_SwiftUI_Settings_window`; Decision 2 replaces that window with the app-owned `settings-window` while retaining the title-based contract. Preserve all destination, navigation, draft, recovery, save/cancel and reorder assertions. The owner explicitly approved this adjustment.++### Rationale++Tests should operate the native controls actually exposed by the platform. Scoping avoids matching unrelated controls or another window with the same title.++### Alternatives Considered++- Keep custom-identifier queries: rejected because both tested SwiftUI attachment positions omit the identifiers from the native toolbar.+- Replace native tabs or add AppKit customization solely for identifiers: rejected because it adds production UI complexity for a test locator.++### Consequences++- Native Settings presentation and all behavior assertions remain intact.+- Tab queries depend on the displayed test-language titles and must change if those labels change.+- Custom identifiers remain available on application-owned page content and section headers.++## Decision 2: Isolate native Settings window ownership++**Date**: 2026-10-24+**Status**: accepted++### Context++The approved title locators allowed all six Mac cases to execute: five passed, and the draft/navigation case exposed incorrect tab routing after a Site-detail push. Explicit selection values, stack identities, fixed tabs and the original tagged-tab implementation reproduced the failure. A temporary diagnostic that hid the native Back item restored tab routing but then exposed loss of the unsaved work-type name. The diagnostic was removed; Back remains available.++A retained `NSTabViewController` embedded inside SwiftUI's Settings scene was also tested. It crashed during a page transition: `SwiftUI.BarAppearanceBridge` attempted to remove an unregistered `displayMode` observer from `NSToolbar`. That experiment was removed and its patch/logs preserved. No acceptance or commit is claimed.++### Decision++Replace only the Mac SwiftUI Settings scene with one app-owned native Settings window. Its `NSTabViewController` owns the toolbar and retains a SwiftUI host/navigation stack for each existing page. Keep the menu's Settings command and Command-comma shortcut, sidebar entry, independent drafts, native Back/Save/Cancel controls and all existing behavior assertions. No library, schema or persistence change is involved.++Wire `AsterismApp`, the Mac Settings command in `Support/MacSettingsWindow.swift`, and `ContentView`'s existing Settings-opening route to that one window owner. Pass the existing app model, announcements, site names and main-window routing action explicitly into each retained page. Closing Settings must preserve the existing reopen semantics; app termination must release the window and hosts.++### Rationale++A single native window owner avoids competing SwiftUI/AppKit toolbar controllers. Retained hosts are intended to preserve page-local models and navigation across tab changes. This is a hypothesis to verify, not an already-proven fix.++### Alternatives considered++- Keep the current SwiftUI Settings/TabView composition: currently fails the retained draft/navigation regression.+- Hide native Back or relax the draft assertions: rejected because that removes required navigation or persistence of unsaved work.+- Embed a native toolbar controller within SwiftUI Settings: tested and rejected because of the toolbar-observer exception.++### Consequences and verification++The user-visible native-tab design stays the same, but window ownership and opening routes change. The owner approved this design and implementation explicitly. The previous SwiftUI Settings scene already created a native macOS window; this decision changes its ownership and retained state, not its native status. Verification must include all six Mac cases, the additional detached-note helper consumer, menu/shortcut/sidebar entry, close/reopen, draft/reorder Cancel, and routes back to the main window. Signed Mac compilation, unchanged Core qualification, simulator units and relevant mobile checks remain required according to dependency impact. No push, merge or physical deployment is included.
specs/settings-layout/design.md Added +49 / -0
diff --git a/specs/settings-layout/design.md b/specs/settings-layout/design.mdnew file mode 100644index 00000000..b67950dd--- /dev/null+++ b/specs/settings-layout/design.md@@ -0,0 +1,49 @@+# Settings layout design++## Ownership and integration++`Support/MacSettingsWindow.swift` contains the macOS-only window owner, native Settings command and retained page root. `AsterismApp` owns one `MacSettingsWindow` for the app session and supplies it to the main view and command. The SwiftUI `Settings` scene is removed; the main SwiftUI `Window` remains unchanged. Both are native macOS windows; the new Settings window's `NSWindowController` is its sole toolbar/window owner.++The owner lazily creates one `NSWindow` with an `NSTabViewController` using toolbar tabs. Each tab retains its own `NSHostingController<MacSettingsPageRoot>`. A root contains the existing `NavigationStack` and `SettingsScreen(page:)`. Closing the window does not release it or the hosts; reopening orders that same window forward. No manual toolbar observer or private API is used.++`MacSettingsPageRoot` reads the shared observable app model in its SwiftUI body, so site-name updates reach the existing pages. It supplies the existing announcement and intent-edit-session environment objects. It passes an explicit main-window opening closure into `SettingsScreen`; it does not copy an entire SwiftUI environment across hosting boundaries. View/model state stays inside each retained host and is not reconstructed on every show.++## Entry routes++| Existing entry | Integration |+| --- | --- |+| Mac Settings menu / Command-comma | `MacSettingsCommands` replaces `.appSettings` and calls the owner. It receives the scene's `OpenWindowAction` for subsequent main-window routes. |+| `ContentView.showSettings()` / sidebar | Enable the Settings row on Mac, read the same owner from the environment, and call it with the existing app objects and main-window action. |+| iOS `AppSettingsCommands` / sheet | Unchanged. |+| `SettingsScreen.leaveSettings()` | Use the supplied main-window action on Mac without consuming the pending route. `ContentView` consumes it after saved-state restoration and library readiness. Sheet dismissal remains unchanged on iOS. |+| Preview / other `SettingsScreen` callers | Optional action defaults to the existing environment-based behavior. |++The native window exposes `settings-window` as its accessibility identifier. The approved title-based toolbar selectors remain scoped to that window. The new source is included through the app's synchronized source group; it is excluded at compilation on iOS with a file-level platform guard.++## Contracts++- `show(...)` is idempotent: existing window/hosts are reused, not duplicated or refreshed with replacement models.+- Menu availability does not depend on the main window being focused. An unopened library still yields the existing unavailable message.+- The owner holds the window and hosts for the app session; page callbacks do not capture the owner. No state is copied into or out of user preference plists.+- The existing page implementation controls all mutations, validation and presentations. Window ownership adds none.++## Verification++First run the existing native draft/navigation case without changing its behavior assertions. Then run all six Mac cases plus the third consumer of the detached-note helper. Add rendered tests for menu/shortcut/sidebar entry, single-window reuse, close/reopen, main-window closed/open return and initial collapsed Debug. Validate actual executed identifiers and the finalized original xcresult bundle; MCP summaries previously repeated stale results.++Run the affected simulator units and mobile journeys if shared caller changes affect them; retain already-qualified unchanged package gates by hash. Verify the signed Mac app and embedded extension, identity declarations and whitespace. Full publication UI gates remain a pre-push phase and no push is requested.++## Implementation risks++- Risk: nested SwiftUI navigation still interacts incorrectly with the native toolbar | Verify: the existing draft/navigation regression first | If wrong: retain evidence and reassess the window/controller boundary before implementing more routes.+- Risk: an escaping scene action fails after the main window closes | Verify: close the main window, open Settings from the menu, and exercise a route back to it before final acceptance.++## Native toolbar and input contracts++Child `NSHostingController`s leave `sceneBridgingOptions` empty. Apple's toolbar bridge would overwrite an AppKit toolbar, so `MacSettingsTabsController` remains the only toolbar owner. Page-scoped `SettingsToolbarActions` supplies Back and staged-order Save/Cancel; destination owner tokens prevent a late disappearance callback from clearing a newer action. `nativeSettingsBackControl()` publishes the existing SwiftUI dismiss action. Creator-role Save/Cancel invoke the original model methods and preserve their identifiers. Mobile views have no native-toolbar context and keep their existing toolbar behavior.++The rendered Mac drag uses XCTest's mouse `click(forDuration:thenDragTo:)` API. `press(forDuration:thenDragTo:)` belongs to its touch-events API and did not deliver a native move. The existing `.onMove` implementation is retained; diagnostic custom drop adapters were removed.++For the main-window return cases, Settings remains open while the main window closes. Closing both windows invokes the existing primary-Window termination behavior and is not a resident-window route. Settings-only close/reopen retention is tested separately; this change does not redefine app quit behavior.++The backup model keeps its existing default-on staging cleanup. `SettingsScreen` enables that cleanup only for `.all` and `.general`; other pages retain the same repository-availability guard and model construction without scanning a backup directory they do not use. The disabled policy and existing default are covered directly by model tests.
specs/settings-layout/implementation.md Added +46 / -0
diff --git a/specs/settings-layout/implementation.md b/specs/settings-layout/implementation.mdnew file mode 100644index 00000000..d2f6a186--- /dev/null+++ b/specs/settings-layout/implementation.md@@ -0,0 +1,46 @@+# T-2483 implementation explanation++## Beginner level++### What changed+On iPhone and iPad, Sites, Work types and Creator roles sit together in the Library section. On Mac, General, Sites, Work types, Creator roles and Maintenance are direct settings tabs. General contains About, Backup and Debug, with Debug collapsed when opened. Maintenance contains detached-link notes and the existing capture controls.++Each Mac tab remembers where you were and keeps unfinished edits when you switch away and return. Backup cleanup now runs only for All and General, where backup actions are available. Other pages skip that scan.++### Why it matters+People can find related settings together and move between Mac settings pages without losing a detail view or draft. Unrelated pages also avoid scanning the backup folder on every redraw.++### Key concepts+A retained tab keeps its screen and navigation history alive while another tab is selected. Backup scavenging checks for old staged files left behind by a previous session.++## Intermediate level++### Changes overview+The Mac Settings window uses one app-owned native window and toolbar tab controller, with one retained SwiftUI host and navigation stack per page. The three configuration tabs open their existing lists directly. General owns About, Backup and collapsed Debug; Maintenance owns detached-note and capture recovery. Mobile keeps the Library rows in their existing order.++The `scavengesOnInit` option defaults to `true` through `SettingsBackupModel` and `AppLibraryModel.settingsBackupModel`. `SettingsScreen` enables it only for `.all` and `.general`; the exporter readiness guard remains intact. `SettingsBackupModelTests.skipsScavengingOnInitWhenDisabled` pins the disabled behavior, and the existing test still pins the default.++### Implementation approach+One native controller owns the Mac toolbar and retains the page hosts. Page-scoped `SettingsToolbarActions` use owner tokens: when an old page disappears late, it can clear only its own Back/Save/Cancel actions, not actions installed by the newly selected page. The hosting controllers set `sceneBridgingOptions` to empty so SwiftUI does not install a competing toolbar bridge.++Routes back to the main window use the existing pending-route mechanism. `ContentView` consumes the pending destination only after saved-state restoration and library readiness, preserving startup ordering.++### Trade-offs+Native window and tab ownership adds Mac-specific wiring, while keeping models, mutations and persistence unchanged. The scavenging flag adds no new cleanup mechanism and preserves prior behavior for callers that use its default.++## Expert level++### Technical deep dive+`SettingsScreen` passes a page-derived Boolean through `AppLibraryModel.settingsBackupModel` and `SettingsBackupModel` to `BackupExportStage`'s existing `scavengesOnInit` switch. The repository/exporter availability guard remains the gate before model construction. Only `.all` and `.general` trigger the synchronous staging-directory scan; default-true parameters preserve other call sites.++`MacSettingsWindow` owns the `NSWindowController` and `NSTabViewController`; each tab retains its hosting controller and independent navigation stack. Empty `sceneBridgingOptions` prevents child SwiftUI hosts from installing a toolbar bridge that would contend with the AppKit toolbar. `SettingsToolbarActions` are scoped by owner tokens, so delayed disappearance cleanup from an old page cannot clear the current page's Back or staged-order Save/Cancel handlers. Main-window navigation remains deferred through the pending route until `ContentView` has completed restoration and library readiness.++### Architecture impact+The layout change retains existing app model and routing ownership and introduces no schema, persistence or CloudKit changes. The scan policy is localized at the page boundary, matching the ownership of backup presenters in General.++### Potential issues and verification status+Final-source validation passed 1,841 simulator units, 247 phone UI cases with two expected physical-only measurement skips, and all 33 iPad acceptance cases. The Mac app and tests compiled, and app/extension signatures verified. Earlier Mac UI evidence covers unchanged window, toolbar and navigation behavior; the direct model regression verifies the cleanup-policy change.++## Completeness Assessment++All requirements are implemented: mobile grouping, native Mac tabs, retained page state, General and Maintenance ownership, toolbar action isolation, and main-window route readiness. The review fix scopes startup scavenging while retaining the default and readiness guard. Full simulator unit, phone UI and iPad acceptance gates passed; signed Mac compilation and unchanged native UI evidence complete the verification scope. No requirement is partially implemented or missing. No merge or physical deployment is part of this work.
specs/settings-layout/requirements.md Added +13 / -0
diff --git a/specs/settings-layout/requirements.md b/specs/settings-layout/requirements.mdnew file mode 100644index 00000000..c0f7589a--- /dev/null+++ b/specs/settings-layout/requirements.md@@ -0,0 +1,13 @@+# Settings layout requirements (T-2483)++These requirements carry forward the approved smolspec and the owner's approval of Decision 2. The previous SwiftUI Settings scene already presented a native macOS window; Decision 2 changes ownership, not whether the window is native.++1. **Mobile grouping.** iOS/iPadOS must retain one Library section containing Sites, Work types and Creator roles, in that order, with existing destinations and identifiers.+2. **Native Mac window.** One app-owned AppKit Settings window must expose General, Sites, Work types, Creator roles and Maintenance as native toolbar tabs. The three configuration tabs open their existing lists directly.+3. **Independent state.** Each Mac page must retain its own SwiftUI view/model and navigation state across tab switches. Unsaved names, staged creator-role order and an open Site detail must survive switching away and back. Existing Save/Cancel semantics must remain.+4. **Opening and lifetime.** The Settings menu item, Command-comma and sidebar entry must open or focus the same window. Closing and reopening within the app session must reuse its page state; app termination ends that state. While Settings remains open, closing the main window must leave Settings available through its menu and shortcut; closing all windows retains the existing app-termination behavior. Routes back to the main window must reopen/focus it and use the existing pending-route mechanism.+5. **Maintenance.** Detached link notes and the existing waiting/report/set-aside capture controls must appear in Maintenance under their existing visibility conditions on both platforms. Recovery, copy, save/cancel and delete confirmation behavior must remain.+6. **General.** About, Backup and Debug remain in General on Mac. Debug starts collapsed. Only the appropriate page owns its dialogs and export/import presenters, avoiding duplicate presentation from retained pages.+7. **Accessibility.** Existing application-owned identifiers and readable native controls must remain. Native tab buttons are located by title inside the Settings window and toolbar, as approved in Decision 1. Behavior assertions must not be weakened to accommodate implementation failures.+8. **Shared app context.** Pages must use the app's existing library model, navigation, announcement seen state and site-name values. No new database, schema, persistence or CloudKit behavior is introduced. The existing unavailable-library presentation remains.+9. **Verification.** Native tests must cover direct roots, tab/navigation/draft retention, reorder cancellation, close/reopen, menu/shortcut/sidebar entry, main-window return and affected recovery paths. Tests use UUID-scoped synthetic libraries with nil CloudKit. Required commit gates follow AGENTS.md; physical deployment, push and merge are out of scope.
specs/settings-layout/smolspec.md Added +33 / -0
diff --git a/specs/settings-layout/smolspec.md b/specs/settings-layout/smolspec.mdnew file mode 100644index 00000000..eca4868f--- /dev/null+++ b/specs/settings-layout/smolspec.md@@ -0,0 +1,33 @@+# Settings Layout (T-2483)++The initial small spec below is superseded by the accepted [requirements](requirements.md) and [design](design.md). Runtime evidence triggered the architectural escalation; the owner approved explicit native window ownership in Decision 2.++## Overview+Settings groups its library configuration controls together on iOS and iPadOS, and exposes those configuration destinations directly in native macOS tabs. Detached link notes joins preserved capture controls in Maintenance. This is a reversible presentation change over the existing models and routes, following the owner's inspected screenshot.++## Requirements+- iOS/iPadOS MUST show Sites, Work types and Creator roles as three existing navigation rows within one Library section, in that order.+- macOS MUST offer General, Sites, Work types, Creator roles and Maintenance settings tabs. The three configuration tabs MUST immediately display their existing destination lists, rather than landing on a link-only row. General MUST contain About, Backup and Debug. Each tab MUST own its navigation stack so navigating within a tab does not replace other tabs' roots.+- Maintenance MUST contain Detached link notes and the waiting, drain-report and set-aside capture controls whenever their existing model/content conditions allow. Captures MUST no longer be a separate section. Maintenance MUST be available on both platforms.+- Existing destination functionality, model ownership, identifiers, validation, deletion confirmations, async routing, note saving, backup/import/export, About and Debug behavior MUST remain intact. Debug MUST remain collapsed by default in the General tab on macOS and in Settings on iOS.+- Native section headers, tab labels and controls MUST remain readable with accessibility text sizes and keep existing actionable identifiers. New section headers MUST have stable identifiers without masking child controls. Native macOS Settings toolbar tabs MUST be located by their titles within the system Settings window; macOS does not expose the supplied custom tab identifiers. These title lookups MUST preserve every existing behavior assertion.+- Focused validation MUST cover mobile Library grouping and all three push destinations; Mac direct configuration roots and tab return after entering detail, partially typed names and staged creator-role reorder/cancel; Maintenance optional content, capture delete cancellation/report routing and detached-note save/cancel; and readable accessibility-size controls.+- Only synthetic isolated libraries MUST be used in validation. No merge or physical device installation is part of this task.++## Initial Implementation Approach (superseded by Decision 2)+- `Asterism/Asterism/Views/SettingsView.swift`: add a small presentation-page enum (all/general/sites/workTypes/creatorRoles/maintenance). Render the three existing list views as direct roots for their pages; all/general alone own backup/import/Empty Library presenters and sync work; all/maintenance alone own capture deletion. Keep presenters on the stable list and preserve existing state ownership. Combine the three navigation rows into Library; combine the detached-note row and capture rows into Maintenance. Keep optional-model visibility rules.+- `Asterism/Asterism/Layout/SettingsScreen.swift`: pass the requested page (default all) through existing model and route wiring; retain unavailable-library handling and leaveSettings semantics.+- `Asterism/Asterism/AsterismApp.swift`: inside the existing macOS Settings scene, use native TabView with a separate NavigationStack/SettingsScreen for each page. Keep shared environment values and the existing Settings scene/window identity.+- Reuse `SitesListView` in `Views/SitesView.swift`, `WorkTypesListView` in `Views/WorkTypesView.swift`, and `CreatorRolesListView` in `Views/CreatorRolesView.swift` without changing their data behavior.+- Add focused cross-platform rendered settings journeys; update the existing Mac detached-note journey's route to select Maintenance. Run affected settings consumers on iOS and verify direct native Mac tab roots and navigation.+- Out of scope: schema/storage/model changes, new settings, permissions/signing changes, performance optimisation, redesigned destinations, merge/push/deployment.++## Risks and Assumptions+- Risk: container identifiers can mask children | Mitigation: identify header labels/tab controls, preserving leaf identifiers; follow the recalled DisclosureGroup accessibility note.+- Risk: re-parented list actions lose presentation ownership | Mitigation: keep existing dialogs/exporters on the stable list and test report navigation, delete confirmation and detached-note save/cancel.+- Risk: Mac tab navigation reuses a stale stack | Mitigation: each native tab owns its stack; test switching away/back after entering a destination.+- Assumption: the screenshot's three circled controls are Sites, Work types and Creator roles; confirmed by viewing the materialized PNG pixels on24October2026.+- Scope assessment: none of the three escalation triggers applies. Existing models/views settle behavior, no persisted/public/auth boundary changes, and a single revert reverses the layout. Owner explicitly requested ticket creation and implementation; no extra naming/implementation approval is needed.++## Escalation Note+This change was scoped as a smolspec. If implementation reveals ambiguity only the user can resolve, an irreversible boundary (public API, persisted schema, auth path), or a contested architectural choice, stop and escalate to the full spec workflow rather than deciding it inline.
specs/settings-layout/tasks.md Added +18 / -0
diff --git a/specs/settings-layout/tasks.md b/specs/settings-layout/tasks.mdnew file mode 100644index 00000000..1e0d3615--- /dev/null+++ b/specs/settings-layout/tasks.md@@ -0,0 +1,18 @@+---+references:+    - specs/settings-layout/smolspec.md+    - specs/settings-layout/requirements.md+    - specs/settings-layout/design.md+    - specs/settings-layout/decision_log.md+---+# Settings Layout (T-2483)++- [x] 1. Library settings form one iOS section and Maintenance contains detached notes plus existing capture controls; preserve identifiers/dialogs and verify section placement with focused rendered journeys. <!-- id:8l3c2ai -->++- [x] 2. Native macOS settings tabs show the three destination lists directly, preserve per-tab navigation and existing routes, and verify direct content plus tab switching. <!-- id:8l3c2aj -->+  - Decision 2 accepted by the owner. One retained NSWindowController/NSTabViewController owns native Settings; per-page hosts retain navigation and drafts, semantic Back/Save/Cancel retain existing handlers, and main-window routes wait for restoration/readiness. Final 12 Mac UI journeys plus two owner-token unit tests passed.+  - Blocked-by: 8l3c2ai (Library settings form one iOS section and Maintenance contains detached notes plus existing capture controls; preserve identifiers/dialogs and verify section placement with focused rendered journeys.)++- [x] 3. Affected settings navigation, edits, capture confirmations and detached-note recovery retain their original assertions on isolated phone/iPad/Mac validation; record actual outcomes and any access blockers. <!-- id:8l3c2ak -->+  - Publication qualification passed: full app units 1,841; full phone UI 249 accounted for (247 passed, two expected physical-only measurement skips); full iPad acceptance 33 passed. Direct policy regression covers the reviewed cleanup fix; prior 12 Mac UI and two unit checks are reused only for unchanged window/navigation/toolbar behavior. Final Mac compile/signatures, identity and whitespace passed. Core/fast 612-input scope unchanged. See verification.md and implementation.md.+  - Blocked-by: 8l3c2ai (Library settings form one iOS section and Maintenance contains detached notes plus existing capture controls; preserve identifiers/dialogs and verify section placement with focused rendered journeys.), 8l3c2aj (Native macOS settings tabs show the three destination lists directly, preserve per-tab navigation and existing routes, and verify direct content plus tab switching.)
specs/settings-layout/verification.md Added +64 / -0
diff --git a/specs/settings-layout/verification.md b/specs/settings-layout/verification.mdnew file mode 100644index 00000000..c7511cc8--- /dev/null+++ b/specs/settings-layout/verification.md@@ -0,0 +1,64 @@+# T-2483 verification++Qualified on 25 October 2026 in `feature/T-2483-settings-layout`, based on `8114426ebd87bab2b9a5040b61d2339fd7ca140b`. The owner approved native title locators (Decision 1) and explicit window ownership (Decision 2). The initial section records implementation/commit qualification. The publication review below records the subsequent full acceptance gates and their source scope. No merge or physical installation is included.++## Implemented and reviewed scope++Mobile Settings groups Sites, Work types and Creator roles under Library. Maintenance combines detached notes and preserved-capture controls, retaining existing destinations, conditions, presenters and confirmations.++Mac Settings uses one retained `NSWindowController` and `NSTabViewController`, with an independent SwiftUI host/navigation stack per page. The native toolbar owns its tabs, Back and staged-order Save/Cancel; page-scoped action owner tokens prevent late disappearance callbacks from clearing newer actions. Existing model mutations remain unchanged. Menu, Command-comma and sidebar share the window. Main-window routes wait for restoration and library readiness before consuming the pending destination.++Independent design/contract reviews found no remaining actionable issue. The contract review specifically checked both first-opener routes, restored-state ordering, observation and toolbar cleanup. The final runtime checks below passed on that reviewed production source.++## Final results++| Gate | Actual result | Evidence prefix |+| --- | --- | --- |+| Mac main-window return, menu-first and sidebar-first | 2 passed; no failures/skips | `mac-return2` |+| Mac grouping, detached notes, Back, delete cancellation, close/reopen/entry routes; toolbar owner-token units | 5 UI + 2 units passed; no failures/skips | `mac-finalA` |+| Mac navigation/draft/reorder journey, preserved captures and three detached-note consumers | 5 UI passed; no failures/skips | `mac-finalB` |+| Full simulator app unit bundle | 1,840 passed; no failures/skips | `phone-units-final` |+| Phone Settings layout/accessibility and Sites consumers | 7 passed; no failures/skips | `phone-uiA` |+| Phone Creator roles editing/removal/restoration/reordering | 4 passed; no failures/skips | `phone-uiB` |+| Phone Work types navigation/editing/validation | 3 passed; no failures/skips | `phone-uiC` |+| iPad Settings grouping, destinations, Maintenance and largest text | 4 passed; no failures/skips | `ipad-final` |+| Unfiltered serial Core, reused unchanged scope | 4,060 passed; 55 normal opt-in skips; no failures/errors | `core-final-reuse.json` plus retained Core receipt |+| Fast cohort, reused unchanged scope | 456 declarations / 552 expanded executions passed | retained `fast-input-scope-proof.json` |+| Mac app and embedded extension | Signed build succeeded; strict signatures verified with host trust-store access | final Mac products / build diagnostics |+| Static validators | `make verify-identity` and `git diff --check` passed | final local checks |++All final app/UI execution used direct Xcode MCP with **Asterism Development**. The full simulator-unit selection included all 1,840 discovered app tests. MCP counted 1,945 result entries including parameterized children; the finalized original bundle reports 1,840 test cases, which exactly match discovery. Phone and iPad checks used dedicated isolated simulators. Each UI journey uses its synthetic isolated fixture. No Personal app was launched.++Every expected identifier was reconciled against the original finalized xcresult tree: none missing, unexpected, failed or skipped. All 1,506 recorded source/document inputs remained unchanged across the final Mac, phone and iPad runs. Subsequent changes only finalize documentation and Rune task status. All 612 Package/script/Makefile inputs also match the retained unfiltered Core/fast receipts; those unchanged broad gates were not repeated. The two new toolbar ownership tests belong to the app's native unit bundle, outside the Core/Presentation-only fast manifest; they passed on both Mac and simulator.++Core's warning comparison retains the same 25 source signatures with none added. Final Mac and simulator build results recorded one and 19 warnings respectively, in unchanged source/toolchain/generated macro diagnostics, with none attributed to changed files. The preceding incremental simulator build had no warnings and is not a comparable cold-build baseline. No unrelated warning repair was undertaken.++## Resolved failures and preserved evidence++- Native toolbar tabs expose buttons by title, not the custom SwiftUI tab identifiers. The owner approved window-scoped title lookup without removing behavior assertions.+- SwiftUI-owned tabs misrouted navigation and lost root drafts. Temporary tab-identity, coordinate and embedded-controller experiments were removed. The embedded controller crashed in SwiftUI toolbar observation; Decision 2 moved ownership to an independent native window.+- XCTest touch `press(...thenDragTo:)` did not enter the native role move handler. Native mouse `click(forDuration:thenDragTo:...)` passed using the original `.onMove`; custom drop adapters and diagnostic logs were removed.+- Two new return-path tests initially closed both windows and then queried a menu after the primary-Window app quit. Their corrected setup leaves Settings open while closing main, explicitly requires Settings to remain available, and verifies the requested destination wins over saved Stats. Closing/reopening Settings separately also passes. App quit behavior is unchanged.+- Earlier automation initialization failures executed zero cases. A later 12-case transport timeout was reconciled against the completed original bundle (10 pass, two setup failures); no duplicate run was launched. No security settings were changed.++Private execution evidence is preserved outside Git: each final prefix has its original `.xcresult`, summary/test tree and MCP receipt. `final-identifier-reconciliation.json`, `final-source-check.json`, `core-final-reuse.json` and `final-warning-comparison.json` state the exact qualification. Earlier failures, crash logs, removed experiment patches and the previous verification history remain separately preserved. All owned runners were confirmed drained before releasing the shared build/test slot; No additional Mac foreground activity was needed during publication qualification.++## Publication review — 25 October 2026++The reuse and quality reviews found no actionable issue. The spec review corrected the command source pointer in Decision 2. Efficiency review found an avoidable staging-directory scan while constructing backup models for non-General Mac pages. The existing `scavengesOnInit` policy now passes through the model factories, enabled only for `.all`/`.general`. The default behavior and library-availability guard are unchanged; a new model test checks that the disabled policy makes zero scavenging calls. Independent review confirmed the fix.++| Final-source publication gate | Result |+| --- | --- |+| Complete simulator app unit bundle | **1,841 passed**, zero failures/skips; every discovered identifier reconciled |+| Full phone UI acceptance | **249 accounted for: 247 passed, two expected physical-only measurement skips**, zero failures |+| Full iPad acceptance (WideLayout and WideLayoutAccessibility) | **33 passed**, zero failures/skips |+| Mac app and test-target compile | Passed; app and embedded extension strict signatures verified |+| Identity and whitespace validation | Passed |++The native Xcode selections match the repository's publication scopes: all phone UI suites except the two iPad-only suites, followed by those complete iPad suites. The two physical M4 measurement methods explicitly skip on a simulator; both scale-seeding checks remained selected and passed. No assertions or runtime checks were weakened. XCTest spells the launch-test identifier without trailing empty parentheses; reconciliation normalizes only that spelling difference. Both long UI requests exceeded the MCP response deadline, but the original runners continued. Their finalized original result bundles, not transport errors, establish the completed outcomes; neither run was duplicated.++All 1,506 recorded inputs remained unchanged through final-source unit and full phone/iPad execution. Later changes only finalize documentation. The unchanged 612 Package/script/Makefile inputs retain the earlier Core/fast qualification. The final app build has 23 warnings in unchanged source/toolchain/generated diagnostics, with none attributed to changed files.++The earlier **12 Mac UI journeys and two Mac unit results are reused for unchanged window, navigation, toolbar and rendering behavior**. They are not claimed as final-source reruns. Independent verification-scope review confirmed that a tab-switching UI rerun would not observe the changed scavenging policy: the direct model tests check that policy, the default-behavior test remains intact, and the final Mac build checks platform compilation. No additional Mac foreground use was needed.++The three-level implementation explanation accompanies this record. The self-contained review HTML is generated and archived separately; raw result bundles, screenshots, logs and machine identifiers remain outside Git. Local environment paths and simulator identifiers were removed from the unpublished documentation before publication.