@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-patterns/references/platform-and-sharing.md

@@ -1,700 +1,618 @@
-# Platform And Sharing
+# Platform and Sharing
 
-## Contents
-- [Transferable, Drag & Drop, and ShareLink](#transferable-drag-drop-and-sharelink)
-- [Media Patterns](#media-patterns)
-- [Top Bar Overlays](#top-bar-overlays)
-- [Title Menus](#title-menus)
-- [Input Toolbar](#input-toolbar)
-- [Menu Bar Commands](#menu-bar-commands)
-- [macOS Settings](#macos-settings)
-
-## Transferable, Drag & Drop, and ShareLink
-
-### Intent
+Moving data in and out of the app (`Transferable`, `ShareLink`, drag and drop,
+the pasteboard), media previews, top bar overlays, title menus, input bars,
+menu bar commands and the macOS Settings window.
 
-Adopt the `Transferable` protocol to enable sharing, drag and drop, copy/paste, and `ShareLink` with a unified API. Available iOS 16+.
+## Contents
 
-> **Docs:** [Transferable](https://sosumi.ai/documentation/coretransferable/transferable) · [Choosing a transfer representation](https://sosumi.ai/documentation/coretransferable/choosing-a-transfer-representation-for-a-model-type)
+1. [Transferable](#1-transferable)
+2. [ShareLink](#2-sharelink)
+3. [Drag and Drop](#3-drag-and-drop)
+4. [Pasteboard](#4-pasteboard)
+5. [Transferable Recipes](#5-transferable-recipes)
+6. [Transferable Pitfalls](#6-transferable-pitfalls)
+7. [Media Previews and Viewer](#7-media-previews-and-viewer)
+8. [Top Bar Overlays](#8-top-bar-overlays)
+9. [Title Menus](#9-title-menus)
+10. [Input Toolbar](#10-input-toolbar)
+11. [Menu Bar Commands](#11-menu-bar-commands)
+12. [macOS Settings](#12-macos-settings)
+
+## 1. Transferable
+
+`Transferable` (iOS 16+) is one protocol behind sharing, drag and drop, copy
+and paste, and `ShareLink`. Apple docs:
+[Transferable](https://developer.apple.com/documentation/coretransferable/transferable),
+the [representation guide](https://developer.apple.com/documentation/coretransferable/choosing-a-transfer-representation-for-a-model-type).
+
+A type conforms by providing
+`static var transferRepresentation: some TransferRepresentation`.
 
-### Transferable protocol overview
+```swift
+import CoreTransferable
+import UniformTypeIdentifiers
 
-`Transferable` describes how a type converts to and from transfer representations (clipboard, drag, share sheet). Conform by implementing a static `transferRepresentation` property.
+struct Recipe: Codable, Identifiable {
+    var id = UUID()
+    var name: String
+    var steps: String
+}
 
-```swift
-struct Note: Codable, Identifiable {
-    let id: UUID
-    var title: String
-    var body: String
+extension UTType {
+    static let recipe = UTType(exportedAs: "com.example.cookbook.recipe")
 }
 
-extension Note: Transferable {
+extension Recipe: Transferable {
     static var transferRepresentation: some TransferRepresentation {
-        CodableRepresentation(contentType: .note)
-        ProxyRepresentation(exporting: \.body) // fallback: plain text
+        CodableRepresentation(contentType: .recipe)
+        ProxyRepresentation(exporting: \.steps)
     }
 }
-
-extension UTType {
-    static let note = UTType(exportedAs: "com.example.note")
-}
 ```
 
-Representation order matters  -  place the most specific first, with broader fallbacks after.
+Order matters. The receiver takes the first representation it understands, so
+list the richest format first and broader fallbacks (plain text here) after it.
 
-### Built-in conformances
+### Types that already conform
 
-These types already conform to `Transferable` out of the box:
-
-| Type | Content type |
-|------|-------------|
+| Type | Content types |
+|---|---|
 | `String` | `.plainText`, `.utf8PlainText` |
 | `Data` | `.data` |
 | `URL` | `.url` |
-| `AttributedString` | `.rtf` |
-| `Image` (SwiftUI) | `.image` |
-| `Color` (SwiftUI) | `.color` |
-
-### TransferRepresentation types
+| `AttributedString` | rich text |
+| SwiftUI `Image` | `.image` |
+| SwiftUI `Color` | `.color` |
 
-#### CodableRepresentation
+### Representation kinds
 
-For types conforming to `Codable`. Serializes to JSON by default:
+- `CodableRepresentation(contentType:)` for `Codable` types. It encodes as
+  JSON unless you pass another encoder.
+- `ProxyRepresentation` hands off to another `Transferable` type. Good for a
+  quick text or URL fallback. `ProxyRepresentation(exporting: \.name)` only
+  exports; `ProxyRepresentation(exporting: \.link, importing: { Bookmark(link: $0) })`
+  works in both directions through a URL.
+- `DataRepresentation(contentType:exporting:importing:)` gives full control of
+  the bytes:
 
 ```swift
-static var transferRepresentation: some TransferRepresentation {
-    CodableRepresentation(contentType: .myType)
-}
-```
-
-#### ProxyRepresentation
-
-Delegate to another `Transferable` type. Ideal for quick text or URL fallbacks:
-
-```swift
-ProxyRepresentation(exporting: \.title)            // export only
-ProxyRepresentation(\.url)                          // import + export via URL
-```
-
-#### DataRepresentation
-
-Full control over binary serialization:
-
-```swift
-DataRepresentation(contentType: .png) { image in
-    try image.pngData()
-} importing: { data in
-    try MyImage(data: data)
+extension Sticker: Transferable {
+    static var transferRepresentation: some TransferRepresentation {
+        DataRepresentation(contentType: .png) { sticker in
+            try sticker.encodedPNG()
+        } importing: { data in
+            try Sticker(pngData: data)
+        }
+    }
 }
 ```
 
-Use `DataRepresentation(exportedContentType:)` for export-only representations.
-
-#### FileRepresentation
-
-For large content best transferred as files:
+- `DataRepresentation(exportedContentType:exporting:)` is the export-only
+  version.
+- `FileRepresentation(contentType:exporting:importing:)` moves large content as
+  files. The received file is temporary, so copy it before using it:
 
 ```swift
-FileRepresentation(contentType: .movie) { video in
-    SentTransferredFile(video.fileURL)
-} importing: { receivedFile in
-    let dest = FileManager.default.temporaryDirectory.appendingPathComponent(receivedFile.file.lastPathComponent)
-    try FileManager.default.copyItem(at: receivedFile.file, to: dest)
-    return Video(url: dest)
+extension Recording: Transferable {
+    static var transferRepresentation: some TransferRepresentation {
+        FileRepresentation(contentType: .mpeg4Audio) { recording in
+            SentTransferredFile(recording.fileURL)
+        } importing: { received in
+            let target = FileManager.default.temporaryDirectory
+                .appending(path: received.file.lastPathComponent)
+            let files = FileManager.default
+            try? files.removeItem(at: target)
+            try files.copyItem(at: received.file, to: target)
+            return Recording(fileURL: target)
+        }
+    }
 }
 ```
 
-### ShareLink
+## 2. ShareLink
 
-Present the system share sheet with a `Transferable` item:
+`ShareLink` presents the system share sheet. Its item must be `Transferable`.
+`SharePreview` supplies a title and, optionally, an image and an icon.
 
 ```swift
-ShareLink(item: note, preview: SharePreview(note.title)) {
-    Label("Share", systemImage: "square.and.arrow.up")
+ShareLink(item: recipe, preview: SharePreview(recipe.name)) {
+    Label("Share recipe", systemImage: "square.and.arrow.up")
 }
 
-// Multiple items
-ShareLink(items: selectedNotes) { note in
-    SharePreview(note.title)
+ShareLink(items: selectedRecipes) { recipe in
+    SharePreview(recipe.name)
 }
 
-// Simple string sharing
-ShareLink(item: "Check out this app!", subject: Text("Cool App"))
+ShareLink(item: "Dinner at 8", subject: Text("Tonight"))
 ```
 
-`ShareLink` requires the item to conform to `Transferable`. The preview provides a title, optional image, and optional icon for the share sheet.
-
-### Drag and drop
+## 3. Drag and Drop
 
-#### Making views draggable
+- `.draggable(value)` makes a view a drag source; the value must be
+  `Transferable`.
+- `.draggable(value) { preview }` supplies a custom drag preview.
 
 ```swift
-struct NoteCard: View {
-    let note: Note
-
-    var body: some View {
-        Text(note.title)
-            .draggable(note) // Note must be Transferable
-    }
-}
-```
-
-Use `.draggable(note) { DragPreview(note) }` to provide a custom drag preview.
-
-#### Drop destination
-
-```swift
-struct NoteBoard: View {
-    @State private var notes: [Note] = []
+struct RecipeBoard: View {
+    @State private var pinned: [Recipe] = []
+    @State private var isHovering = false
 
     var body: some View {
         VStack {
-            ForEach(notes) { NoteCard(note: $0) }
+            ForEach(pinned) { Text($0.name) }
         }
-        .dropDestination(for: Note.self) { droppedNotes, location in
-            notes.append(contentsOf: droppedNotes)
+        .frame(maxWidth: .infinity, minHeight: 200)
+        .background(isHovering ? Color.accentColor.opacity(0.15) : Color.clear)
+        .dropDestination(for: Recipe.self) { recipes, _ in
+            pinned.append(contentsOf: recipes)
             return true
-        } isTargeted: { isOver in
-            // Highlight drop zone
+        } isTargeted: { hovering in
+            isHovering = hovering
         }
     }
 }
 ```
 
-For reordering within a list, combine `.draggable` with `.dropDestination` or use `onMove` on `ForEach` inside `List`.
-
-#### Handling multiple types
-
-Accept multiple content types with separate `.dropDestination` modifiers or use `DropDelegate` for advanced logic:
+- To reorder rows, either pair `.draggable` and `.dropDestination` yourself,
+  or let a `List` do it through `onMove` on its `ForEach`.
+- Several accepted types: add one `.dropDestination` per type, or use a
+  `DropDelegate` for more complex rules.
 
 ```swift
-.dropDestination(for: String.self) { strings, _ in
-    notes.append(contentsOf: strings.map { Note(id: UUID(), title: $0, body: "") })
+.dropDestination(for: String.self) { texts, _ in
+    pinned.append(contentsOf: texts.map { Recipe(name: $0, steps: "") })
     return true
 }
 ```
 
-### Pasteboard integration
+## 4. Pasteboard
 
-For direct clipboard access outside SwiftUI's drag/drop system, use `UIPasteboard`:
+Outside drag and drop, iOS code can use `UIPasteboard` directly:
 
 ```swift
-// Copy
-UIPasteboard.general.string = note.title
-
-// Paste
-if let text = UIPasteboard.general.string {
-    // use text
-}
+UIPasteboard.general.string = recipe.steps
+let pasted: String? = UIPasteboard.general.string
 ```
 
-For `Transferable` types with custom content types, export to `Data` first:
+For a custom `Transferable` type, export the data first:
 
 ```swift
-let data = try await note.exported(as: .note)
-UIPasteboard.general.setData(data, forPasteboardType: UTType.note.identifier)
+let data = try await recipe.exported(as: .recipe)
+let board = UIPasteboard.general
+board.setData(data, forPasteboardType: UTType.recipe.identifier)
 ```
 
-Prefer SwiftUI's `.copyable`, `.cuttable`, and `.pasteDestination` modifiers (iOS 16+) over direct `UIPasteboard` usage when possible  -  they integrate with the Edit menu and keyboard shortcuts automatically.
+On iOS, `PasteButton(payloadType:onPaste:)` (iOS 16+) pastes without the
+system permission prompt. On macOS, the SwiftUI modifiers `.copyable(_:)`,
+`.cuttable(for:action:)` and `.pasteDestination(for:action:validator:)`
+(macOS 13+) connect to the Edit menu and its keyboard shortcuts; prefer them
+there over `NSPasteboard`. These three modifiers are not available on iOS.
 
-### Common patterns
+## 5. Transferable Recipes
 
-#### Transferable enum with multiple representations
+One enum, one plain-text representation:
 
 ```swift
-enum SharedContent: Transferable {
-    case text(String)
-    case url(URL)
+enum Clip: Transferable {
+    case note(String)
+    case link(URL)
 
     static var transferRepresentation: some TransferRepresentation {
-        ProxyRepresentation { content in
-            switch content {
-            case .text(let s): return s
-            case .url(let u): return u.absoluteString
+        ProxyRepresentation { clip in
+            switch clip {
+            case .note(let text): text
+            case .link(let url): url.absoluteString
             }
         }
     }
 }
 ```
 
-#### Export-only conformance
-
-When your type should be sharable but not importable:
+Export only, as a PDF:
 
 ```swift
-extension Report: Transferable {
+extension Statement: Transferable {
     static var transferRepresentation: some TransferRepresentation {
-        DataRepresentation(exportedContentType: .pdf) { report in
-            try report.renderPDF()
+        DataRepresentation(exportedContentType: .pdf) { statement in
+            try await statement.renderPDF()
         }
     }
 }
 ```
 
-### Pitfalls
-
-- Always declare custom `UTType` identifiers in Info.plist under Exported/Imported Type Identifiers.
-- Representation order matters  -  the first matching representation wins. Put the richest format first.
-- `FileRepresentation` files are temporary; copy them if you need to persist.
-- `Transferable` conformance must be on the main type, not an extension in a different module, to avoid linker issues.
-- Test drag and drop on device  -  Simulator haptics and drop targeting differ from hardware.
-
-## Media Patterns
+## 6. Transferable Pitfalls
 
-### Intent
+- Every custom `UTType` needs an Info.plist entry: Exported Type Identifiers
+  for types the app defines, Imported Type Identifiers for types it only
+  reads.
+- Files delivered through `FileRepresentation` are temporary. Copy them to keep
+  them.
+- Declare the conformance in the module that defines the type. A conformance
+  added from another module is retroactive and can clash with one the owner
+  adds later.
+- Test drag and drop on a device. The Simulator does not match hardware for
+  haptics and drop targeting.
 
-Use consistent patterns for loading images, previewing media, and presenting a full-screen viewer.
+## 7. Media Previews and Viewer
 
-### Core patterns
+Goal: one consistent way to load images, show inline previews and open a
+full-screen viewer.
 
-- Use `AsyncImage` for simple remote images. `LazyImage` is from the third-party Nuke library if you need advanced caching and prefetching.
-- Prefer a lightweight preview component for inline media.
-- Use a shared viewer state (e.g., `QuickLook`) to present a full-screen media viewer.
-- Use `openWindow` for desktop/visionOS and a sheet for iOS.
-
-### Example: inline media preview
+- `AsyncImage` covers simple remote images. For caching and prefetching, a
+  library such as Nuke provides `LazyImage`.
+- Inline media uses a light preview component.
+- The full-screen viewer is driven by shared viewer state, for example a
+  `MediaViewer` object in the environment.
+- On macOS and visionOS open the viewer with `openWindow`; on iOS use a sheet.
 
 ```swift
-struct MediaPreviewRow: View {
-  @Environment(QuickLook.self) private var quickLook
-
-  let attachments: [MediaAttachment]
-
-  var body: some View {
-    ScrollView(.horizontal, showsIndicators: false) {
-      HStack {
-        ForEach(attachments) { attachment in
-          Button {
-            quickLook.prepareFor(
-              selectedMediaAttachment: attachment,
-              mediaAttachments: attachments
-            )
-          } label: {
-            LazyImage(url: attachment.previewURL) { state in
-              if let image = state.image {
-                image.resizable().aspectRatio(contentMode: .fill)
-              } else {
-                ProgressView()
-              }
+struct AttachmentStrip: View {
+    @Environment(MediaViewer.self) private var viewer
+    let attachments: [Attachment]
+
+    var body: some View {
+        ScrollView(.horizontal, showsIndicators: false) {
+            HStack {
+                ForEach(attachments) { item in
+                    Button {
+                        viewer.open(item, among: attachments)
+                    } label: {
+                        AsyncImage(url: item.thumbnailURL) { image in
+                            image.resizable().aspectRatio(contentMode: .fill)
+                        } placeholder: {
+                            ProgressView()
+                        }
+                        .frame(width: 120, height: 120)
+                        .clipped()
+                    }
+                    .buttonStyle(.plain)
+                }
             }
-            .frame(width: 120, height: 120)
-            .clipped()
-          }
-          .buttonStyle(.plain)
         }
-      }
     }
-  }
 }
-```
 
-### Example: global media viewer sheet
-
-```swift
-struct AppRoot: View {
-  @State private var quickLook = QuickLook.shared
-
-  var body: some View {
-    content
-      .environment(quickLook)
-      .sheet(item: $quickLook.selectedMediaAttachment) { selected in
-        MediaUIView(selectedAttachment: selected, attachments: quickLook.mediaAttachments)
-      }
-  }
+@main
+struct AlbumApp: App {
+    @State private var viewer = MediaViewer.shared
+
+    var body: some Scene {
+        WindowGroup {
+            LibraryView()
+                .environment(viewer)
+                .sheet(item: Bindable(viewer).current) { item in
+                    FullScreenMedia(item: item)
+                }
+        }
+    }
 }
 ```
 
-### Design choices to keep
-
-- Keep previews lightweight; load full media in the viewer.
-- Use shared viewer state so any view can open media without prop-drilling.
-- Use a single entry point for the viewer (sheet/window) to avoid duplicates.
-
-### Pitfalls
-
-- Avoid loading full-size images in list rows; use resized previews.
-- Don't present multiple viewer sheets at once; keep a single source of truth.
+Guidelines:
 
-## Top Bar Overlays
+- Keep previews light; load full-resolution media only inside the viewer.
+- Shared viewer state lets any view open media without passing it down
+  through every layer.
+- One entry point (a sheet or a window) avoids duplicate viewers.
 
-### Intent
+Pitfalls:
 
-Provide a custom top selector or pill row that sits above scroll content, using `safeAreaBar(.top)` on iOS 26 and a compatible fallback on earlier OS versions.
+- Rows that decode original-resolution images. Downscale for the preview.
+- Two viewer sheets open together because two views each own one. One state
+  object, one presenter.
 
-### iOS 26+ approach
+## 8. Top Bar Overlays
 
-Use `safeAreaBar(edge: .top)` to attach the view to the safe area bar.
+Goal: a custom selector or pill row above scrolling content. On iOS 26 use
+`safeAreaBar`; earlier releases need a fallback.
 
 ```swift
-if #available(iOS 26.0, *) {
-  content
-    .safeAreaBar(edge: .top) {
-      TopSelectorView()
-        .padding(.horizontal, .layoutPadding)
+struct FeedScreen: View {
+    @State private var section: FeedSection = .following
+
+    var body: some View {
+        feedList
+            .modifier(TopSelector(section: $section))
     }
 }
-```
-
-### Fallback for earlier iOS
 
-Use `.safeAreaInset(edge: .top)` and hide the toolbar background to avoid double layers.
+struct TopSelector: ViewModifier {
+    @Binding var section: FeedSection
 
-```swift
-content
-  .toolbarBackground(.hidden, for: .navigationBar)
-  .safeAreaInset(edge: .top, spacing: 0) {
-    VStack(spacing: 0) {
-      TopSelectorView()
-        .padding(.vertical)
-        .padding(.horizontal, .layoutPadding)
-        .background(Color.primary.opacity(0.06))
-        .background(Material.ultraThin)
-      Divider()
+    func body(content: Self.Content) -> some View {
+        if #available(iOS 26.0, *) {
+            content.safeAreaBar(edge: .top) {
+                SectionPicker(section: $section)
+                    .padding(.horizontal, Spacing.medium)
+            }
+        } else {
+            content
+                .toolbarBackground(.hidden, for: .navigationBar)
+                .safeAreaInset(edge: .top, spacing: 0) {
+                    VStack(spacing: 0) {
+                        SectionPicker(section: $section)
+                            .padding(.vertical, 8)
+                            .background(Color.primary.opacity(0.05))
+                            .background(Material.ultraThin)
+                        Divider()
+                    }
+                }
+        }
     }
-  }
+}
 ```
 
-### Design choices to keep
-
-- Use `safeAreaBar` when available; it integrates better with the navigation bar.
-- Use a subtle background + divider in the fallback to keep separation from content.
-- Keep the selector height compact to avoid pushing content too far down.
+Hiding the toolbar background in the fallback prevents two stacked
+backgrounds.
 
-### Pitfalls
+Guidelines:
 
-- Don't stack multiple top insets; it can create extra padding.
-- Avoid heavy, opaque backgrounds that fight the navigation bar.
+- Prefer `safeAreaBar` where available; it blends with the navigation bar.
+- The fallback separates itself from content with a faint background and a
+  divider.
+- Keep the selector short so content does not move far down.
 
-## Title Menus
+Pitfalls:
 
-### Intent
+- Several top insets stacked on each other add extra padding.
+- Heavy, opaque backgrounds that clash with the navigation bar.
 
-Use a title menu in the navigation bar to provide context‑specific filtering or quick actions without adding extra chrome.
+## 9. Title Menus
 
-### Core patterns
+Goal: a menu on the navigation title for filtering or quick context actions,
+with no extra chrome.
 
-- Use `ToolbarTitleMenu` to attach a menu to the navigation title.
-- Keep the menu content compact and grouped with dividers.
-
-### Example: title menu for filters
+- `ToolbarTitleMenu` (iOS 16+) attaches a menu to the title.
+- Keep its content short and group it with `Divider()`.
 
 ```swift
-@ToolbarContentBuilder
-private var toolbarView: some ToolbarContent {
-  ToolbarTitleMenu {
-    Button("Latest") { timeline = .latest }
-    Button("Resume") { timeline = .resume }
-    Divider()
-    Button("Local") { timeline = .local }
-    Button("Federated") { timeline = .federated }
-  }
-}
-```
-
-### Example: attach to a view
+struct TasksScreen: View {
+    @State private var filter: TaskFilter = .open
 
-```swift
-NavigationStack {
-  TimelineView()
-    .toolbar {
-      toolbarView
+    var body: some View {
+        NavigationStack {
+            TaskList(filter: filter)
+                .navigationTitle(filter.title)
+                .toolbar { titleMenu }
+        }
     }
-}
-```
-
-### Example: title + menu together
 
-```swift
-struct TimelineScreen: View {
-  @State private var timeline: TimelineFilter = .home
-
-  var body: some View {
-    NavigationStack {
-      TimelineView()
-        .toolbar {
-          ToolbarItem(placement: .principal) {
-            VStack(spacing: 2) {
-              Text(timeline.title)
-                .font(.headline)
-              Text(timeline.subtitle)
-                .font(.caption)
-                .foregroundStyle(.secondary)
-            }
-          }
-
-          ToolbarTitleMenu {
-            Button("Home") { timeline = .home }
-            Button("Local") { timeline = .local }
-            Button("Federated") { timeline = .federated }
-          }
+    @ToolbarContentBuilder
+    private var titleMenu: some ToolbarContent {
+        ToolbarTitleMenu {
+            Button("Open") { filter = .open }
+            Button("Done") { filter = .done }
+            Divider()
+            Button("Everything") { filter = .all }
         }
-        .navigationBarTitleDisplayMode(.inline)
     }
-  }
 }
 ```
 
-### Example: title + subtitle with menu
+A title with a subtitle under it:
 
 ```swift
-ToolbarItem(placement: .principal) {
-  VStack(spacing: 2) {
-    Text(title)
-      .font(.headline)
-    Text(subtitle)
-      .font(.caption)
-      .foregroundStyle(.secondary)
-  }
+.toolbar {
+    ToolbarItem(placement: .principal) {
+        VStack(spacing: 2) {
+            Text(project.name).font(.headline)
+            Text("\(project.openCount) open").font(.caption).foregroundStyle(.secondary)
+        }
+    }
+    titleMenu
 }
+.navigationBarTitleDisplayMode(.inline)
 ```
 
-### Design choices to keep
-
-- Only show the title menu when filtering or context switching is available.
-- Keep the title readable; avoid long labels that truncate.
-- Use secondary text below the title if extra context is needed.
+Guidelines:
 
-### Pitfalls
+- Show the title menu only when there is something to filter or switch.
+- Keep the title short enough that it is not truncated.
+- Put extra context in the secondary line under the title.
 
-- Don't overload the menu with too many options.
-- Avoid using title menus for destructive actions.
+Pitfalls:
 
-## Input Toolbar
+- Too many options in the menu.
+- Destructive actions in a title menu.
 
-### Intent
+## 10. Input Toolbar
 
-Use a bottom-anchored input bar for chat, composer, or quick actions without fighting the keyboard.
+Goal: an input bar pinned to the bottom (chat, composer, quick actions) that
+moves with the keyboard.
 
-### Core patterns
-
-- Use `.safeAreaInset(edge: .bottom)` to anchor the toolbar above the keyboard.
-- Keep the main content in a `ScrollView` or `List`.
-- Drive focus with `@FocusState` and set initial focus when needed.
-- Avoid embedding the input bar inside the scroll content; keep it separate.
-
-### Example: scroll view + bottom input
+- Anchor it with `.safeAreaInset(edge: .bottom)` so it sits above the keyboard.
+- The messages or items scroll in a `ScrollView` or `List`.
+- `@FocusState` decides when the field is active; focusing it on appear is
+  often right for a composer.
+- Keep the bar out of the scrolling content.
 
 ```swift
 @MainActor
-struct ConversationView: View {
-  @FocusState private var isInputFocused: Bool
-  @State private var scrollPosition = ScrollPosition(edge: .bottom)
-  @State private var draft = ""
-
-  var body: some View {
-    ScrollView {
-      LazyVStack {
-        ForEach(messages) { message in
-          MessageRow(message: message)
+struct ChatThread: View {
+    @State private var draft = ""
+    @State private var position = ScrollPosition(edge: .bottom)
+    @FocusState private var isComposing: Bool
+    let messages: [Message]
+    let onSend: (String) -> Void
+
+    var body: some View {
+        ScrollView {
+            LazyVStack {
+                ForEach(messages) { MessageBubble(message: $0) }
+            }
+            .scrollTargetLayout()
+        }
+        .scrollPosition($position)
+        .scrollDismissesKeyboard(.interactively)
+        .safeAreaInset(edge: .bottom) {
+            HStack {
+                TextField("Message", text: $draft)
+                    .focused($isComposing)
+                    .onSubmit(send)
+                Button("Send", systemImage: "arrow.up.circle.fill", action: send)
+            }
+            .padding()
+            .background(.bar)
         }
-      }
-      .scrollTargetLayout()
-      .padding(.horizontal, .layoutPadding)
+        .onAppear { isComposing = true }
     }
-    .scrollPosition($scrollPosition)
-    .safeAreaInset(edge: .bottom) {
-      InputBar(text: $draft)
-        .focused($isInputFocused)
+
+    private func send() {
+        onSend(draft)
+        draft = ""
     }
-    .scrollDismissesKeyboard(.interactively)
-    .onAppear { isInputFocused = true }
-  }
 }
 ```
 
-### Design choices to keep
-
-- Keep the input bar visually separated from the scrollable content.
-- Use `.scrollDismissesKeyboard(.interactively)` for chat-like screens.
-- Ensure send actions are reachable via keyboard return or a clear button.
-
-### Pitfalls
-
-- Avoid placing the input view inside the scroll stack; it will jump with content.
-- Avoid nested scroll views that fight for drag gestures.
-
-## Menu Bar Commands
+`ScrollPosition` and `scrollPosition(_:)` with it need iOS 18.
 
-### Contents
+Guidelines:
 
-- [Intent](#intent)
-- [Core patterns](#core-patterns)
-- [Example: basic command menu](#example-basic-command-menu)
-- [Example: insert and replace groups](#example-insert-and-replace-groups)
-- [Example: focused menu state](#example-focused-menu-state)
-- [Menu bar and Settings](#menu-bar-and-settings)
-- [Pitfalls](#pitfalls)
+- Keep the bar visually distinct from the scrolling content.
+- Chat-style screens use `.scrollDismissesKeyboard(.interactively)`.
+- Sending must work from the return key and from a clear button.
 
-### Intent
+Pitfalls:
 
-Use this when adding or customizing the macOS/iPadOS menu bar with SwiftUI commands.
+- An input field placed inside the scroll stack moves with the content.
+- Nested scroll views fighting over the drag gesture.
 
-### Core patterns
+## 11. Menu Bar Commands
 
-- Add commands at the `Scene` level with `.commands { ... }`.
-- Use `SidebarCommands()` when your UI includes a navigation sidebar.
-- Use `CommandMenu` for app-specific menus and group related actions.
-- Use `CommandGroup` to insert items before/after system groups or replace them.
-- Use `FocusedValue` for context-sensitive menu items that depend on the active scene.
+Applies when adding to or customising the menu bar on macOS and iPadOS with
+SwiftUI commands.
 
-### Example: basic command menu
-
-```swift
-@main
-struct MyApp: App {
-  var body: some Scene {
-    WindowGroup {
-      ContentView()
-    }
-    .commands {
-      CommandMenu("Actions") {
-        Button("Run", action: run)
-          .keyboardShortcut("R")
-        Button("Stop", action: stop)
-          .keyboardShortcut(".")
-      }
-    }
-  }
-
-  private func run() {}
-  private func stop() {}
-}
-```
-
-### Example: insert and replace groups
+- Attach commands to a `Scene` with `.commands { }`.
+- Add `SidebarCommands()` when the UI has a navigation sidebar.
+- `CommandMenu` creates an app-specific menu of related actions.
+- `CommandGroup` inserts items before or after a system group, or replaces it.
+- `FocusedValue` makes items depend on the active scene.
 
 ```swift
 WindowGroup {
-  ContentView()
+    ContentView()
 }
 .commands {
-  CommandGroup(before: .systemServices) {
-    Button("Check for Updates") { /* open updater */ }
-  }
-
-  CommandGroup(after: .newItem) {
-    Button("New from Clipboard") { /* create item */ }
-  }
-
-  CommandGroup(replacing: .help) {
-    Button("User Manual") { /* open docs */ }
-  }
+    SidebarCommands()
+    CommandMenu("Library") {
+        Button("Rescan", action: rescan).keyboardShortcut("R")
+        Button("Stop Scan", action: stopScan).keyboardShortcut(".")
+    }
+    CommandGroup(before: .systemServices) {
+        Button("Diagnostics", action: showDiagnostics)
+    }
+    CommandGroup(after: .newItem) {
+        Button("New Playlist", action: newPlaylist)
+    }
+    CommandGroup(replacing: .help) {
+        Button("Library Guide", action: openGuide)
+    }
 }
 ```
 
-### Example: focused menu state
+Context-sensitive commands read a focused value that the active scene
+publishes:
 
 ```swift
-@Observable
-final class DataModel {
-  var items: [String] = []
+@MainActor @Observable
+final class LibraryModel {
+    func addPlaylist() { }
 }
 
-struct ContentView: View {
-  @State private var model = DataModel()
+struct LibraryWindow: View {
+    @State private var model = LibraryModel()
 
-  var body: some View {
-    List(model.items, id: \.self) { item in
-      Text(item)
+    var body: some View {
+        LibraryView(model: model)
+            .focusedSceneValue(model)
     }
-    .focusedSceneValue(model)
-  }
 }
 
-struct ItemCommands: Commands {
-  @FocusedValue(DataModel.self) private var model: DataModel?
+struct LibraryCommands: Commands {
+    @FocusedValue(LibraryModel.self) private var model: LibraryModel?
 
-  var body: some Commands {
-    CommandGroup(after: .newItem) {
-      Button("New Item") {
-        model?.items.append("Untitled")
-      }
-      .disabled(model == nil)
+    var body: some Commands {
+        CommandGroup(after: .newItem) {
+            Button("Add Playlist") { model?.addPlaylist() }
+                .disabled(model == nil)
+        }
     }
-  }
 }
 ```
 
-### Menu bar and Settings
-
-- Defining a `Settings` scene adds the Settings menu item on macOS automatically.
-- If you need a custom entry point inside the app, use `OpenSettingsAction` or `SettingsLink`.
+On macOS, the app menu gains its Settings item as soon as the `App` declares a
+`Settings` scene. To open settings from inside the app, use `SettingsLink` or the
+`openSettings` environment action (`OpenSettingsAction`).
 
-### Pitfalls
+Pitfalls:
 
-- Avoid registering the same keyboard shortcut in multiple command groups.
-- Don't use menu items as the only discoverable entry point for critical features.
+- The same shortcut assigned in several command groups.
+- A critical feature reachable only through a menu item.
 
-## macOS Settings
+## 12. macOS Settings
 
-### Intent
+Applies when building the macOS Settings window with the SwiftUI `Settings`
+scene.
 
-Use this when building a macOS Settings window backed by SwiftUI's `Settings` scene.
-
-### Core patterns
-
-- Declare the Settings scene in the `App` and compile it only for macOS.
-- Keep settings content in a dedicated root view (`SettingsView`) and drive values with `@AppStorage`.
-- Use `TabView` to group settings sections when you have more than one category.
-- Use `Form` inside each tab to keep controls aligned and accessible.
-- Use `OpenSettingsAction` or `SettingsLink` for in-app entry points to the Settings window.
-
-### Example: settings scene
+- Declare `Settings { PreferencesView() }` in the `App`, wrapped in
+  `#if os(macOS)` so it compiles only for macOS.
+- Give settings their own root view and back values with `@AppStorage`.
+- More than one category: group them with a `TabView`.
+- Use a `Form` inside each tab for aligned, accessible controls.
+- Open settings from the app with `SettingsLink` or `OpenSettingsAction`.
 
 ```swift
 @main
-struct MyApp: App {
-  var body: some Scene {
-    WindowGroup {
-      ContentView()
-    }
-    #if os(macOS)
-    Settings {
-      SettingsView()
+struct ReaderApp: App {
+    var body: some Scene {
+        WindowGroup { LibraryView() }
+        #if os(macOS)
+        Settings { PreferencesView() }
+        #endif
     }
-    #endif
-  }
 }
-```
-
-### Example: tabbed settings view
 
-```swift
 @MainActor
-struct SettingsView: View {
-  @AppStorage("showPreviews") private var showPreviews = true
-  @AppStorage("fontSize") private var fontSize = 12.0
-
-  var body: some View {
-    TabView {
-      Tab("General", systemImage: "gear") {
-        Form {
-          Toggle("Show Previews", isOn: $showPreviews)
-          Slider(value: $fontSize, in: 9...96) {
-            Text("Font Size (\(fontSize, specifier: "%.0f") pts)")
-          }
-        }
-      }
+struct PreferencesView: View {
+    @AppStorage("showThumbnails") private var showThumbnails = true
+    @AppStorage("readerTextSize") private var readerTextSize = 14.0
 
-      Tab("Advanced", systemImage: "star") {
-        Form {
-          Toggle("Enable Advanced Mode", isOn: .constant(false))
+    var body: some View {
+        TabView {
+            Tab("General", systemImage: "gearshape") {
+                Form {
+                    Toggle("Show thumbnails", isOn: $showThumbnails)
+                }
+            }
+            Tab("Reading", systemImage: "textformat.size") {
+                Form {
+                    Slider(value: $readerTextSize, in: 9...96) {
+                        Text("Text size: \(readerTextSize, specifier: "%.0f")")
+                    }
+                }
+            }
         }
-      }
+        .scenePadding()
+        .frame(maxWidth: 420, minHeight: 240)
     }
-    .scenePadding()
-    .frame(maxWidth: 420, minHeight: 240)
-  }
 }
 ```
 
-### Skip navigation
+`Tab` inside the settings `TabView` needs macOS 15; for macOS 14 use
+`.tabItem { Label(...) }` on each child instead.
+
+Guidelines:
 
-- Avoid wrapping `SettingsView` in a `NavigationStack` unless you truly need deep push navigation.
-- Prefer tabs or sections; Settings is already presented as a separate window and should feel flat.
-- If you must show hierarchical settings, use a single `NavigationSplitView` with a sidebar list of categories.
+- Do not wrap the settings view in a `NavigationStack` unless deep push
+  navigation is genuinely needed.
+- Settings is its own window and should feel flat: tabs or sections.
+- For hierarchical settings, use one `NavigationSplitView` with a sidebar of
+  categories.
 
-### Pitfalls
+Pitfalls:
 
-- Don't reuse iOS-only settings layouts (full-screen stacks, toolbar-heavy flows).
-- Avoid large custom view hierarchies inside `Form`; keep rows focused and accessible.
+- Reusing iOS settings layouts on the Mac (full-screen stacks, toolbar-heavy
+  flows).
+- Deep custom hierarchies stuffed into a `Form`. Each row should hold one
+  simple, accessible control.