Pre-push review: T-2330/work-thumbnails

diff --git a/Asterism/Asterism/ContentView.swift b/Asterism/Asterism/ContentView.swiftindex fdff87c..7d678e4 100644--- a/Asterism/Asterism/ContentView.swift+++ b/Asterism/Asterism/ContentView.swift@@ -498,6 +498,11 @@ struct ContentView: View {             // it reaches both trees, everything they push, and the sheets, which             // inherit the presenting view's environment.             .environment(\.siteNames, model.siteNames)+            // `work-thumbnails` Q70: the cover loader, written beside the site+            // names and for their reason — one write at the top of the window+            // reaches both trees, everything they push and every sheet, and no+            // row signature changes to carry it.+            .environment(\.thumbnailLoader, model.thumbnailLoader)     }      private var presentedContent: some View {

diff --git a/Asterism/Asterism/Support/PlatformModifiers.swift b/Asterism/Asterism/Support/PlatformModifiers.swiftindex 0f79508..cda96cd 100644--- a/Asterism/Asterism/Support/PlatformModifiers.swift+++ b/Asterism/Asterism/Support/PlatformModifiers.swift@@ -1,4 +1,5 @@ import ConstellationKit+import PhotosUI import SwiftUI import UniformTypeIdentifiers @@ -77,6 +78,28 @@ extension View {     } } +// MARK: - Full-screen presentation++extension View {+    /// A presentation that covers the whole screen on iOS and is a sheet on the+    /// Mac, where `fullScreenCover` does not exist and a window-filling sheet+    /// is the native shape of "look at this on its own". The cover viewer's+    /// seam (`work-thumbnails`).+    @ViewBuilder+    func coveringPresentation<Content: View>(+        isPresented: Binding<Bool>, @ViewBuilder content: @escaping () -> Content+    ) -> some View {+        #if os(iOS)+        fullScreenCover(isPresented: isPresented, content: content)+        #else+        sheet(isPresented: isPresented) {+            content()+                .frame(minWidth: 600, minHeight: 800)+        }+        #endif+    }+}+ // MARK: - Toolbar placements  extension ToolbarItemPlacement {@@ -291,6 +314,71 @@ extension View {     } } +// MARK: - The crop step's Mac zoom (`work-thumbnails` Req 5.1, Q35)++/// A scroll wheel or trackpad scroll over one view, as a multiplicative zoom+/// factor.+///+/// The crop step is one SwiftUI view on both platforms (Q35) and pinch is the+/// only zoom a phone has. A Mac has a wheel as well, and there is no SwiftUI+/// spelling for it at all — so the `NSEvent` monitor lives here, at the seam,+/// rather than forking the crop view.+///+/// **Local, and bounded to the view's own frame.** A local monitor sees every+/// scroll the app receives, including ones over the list behind the sheet, so+/// the handler asks where the event happened before it acts and returns the+/// event untouched when it happened anywhere else. It is installed on appear and+/// removed on disappear, so a dismissed sheet leaves nothing behind.+private struct ScrollWheelZoom: ViewModifier {+    /// The factor to multiply the current zoom by. 1 is no change.+    let onZoom: (CGFloat) -> Void++    #if os(macOS)+    @State private var monitor: Any?+    /// The view's frame in the window's own coordinates, kept current so the+    /// monitor can decide whether an event is its business.+    @State private var frame: CGRect = .zero++    func body(content: Content) -> some View {+        content+            .onGeometryChange(for: CGRect.self) { proxy in+                proxy.frame(in: .global)+            } action: { frame = $0 }+            .onAppear {+                guard monitor == nil else { return }+                monitor = NSEvent.addLocalMonitorForEvents(matching: .scrollWheel) { event in+                    guard let contentView = event.window?.contentView else { return event }+                    // `locationInWindow` has its origin at the bottom left and+                    // SwiftUI's `.global` at the top left, so one of them has to+                    // be turned over before they can be compared.+                    let point = CGPoint(+                        x: event.locationInWindow.x,+                        y: contentView.bounds.height - event.locationInWindow.y)+                    guard frame.contains(point) else { return event }+                    // A wheel notch is a few points of delta; 1% of it per point+                    // is a zoom that feels like the pinch beside it.+                    onZoom(1 + event.scrollingDeltaY * 0.01)+                    return nil+                }+            }+            .onDisappear {+                if let monitor { NSEvent.removeMonitor(monitor) }+                monitor = nil+            }+    }+    #else+    /// iOS has pinch and nothing else to wire: a no-op, never an approximation.+    func body(content: Content) -> some View { content }+    #endif+}++extension View {+    /// Zooms this view with the Mac's scroll wheel; nothing on iOS.+    func scrollWheelZoom(_ onZoom: @escaping (CGFloat) -> Void) -> some View {+        modifier(ScrollWheelZoom(onZoom: onZoom))+    }+}+ // MARK: - Documents in and out  #if os(macOS)@@ -341,6 +429,89 @@ private func exportContentType(of file: URL?) -> UTType { } #endif +/// The cover picker, one arm per platform (`work-thumbnails` Req 3.2).+///+/// **`PhotosUI` is imported here and nowhere else** — `PlatformSeamTests` pins+/// that, the way it pins `UIKit` — because the framework is the iOS arm's and+/// nothing portable should be able to reach for it.+private struct ImagePicker: ViewModifier {+    @Binding var isPresented: Bool+    let onSelection: (Data) -> Void+    let onCancel: () -> Void++    #if os(iOS)+    /// The picker's selection, which is a *reference* to an asset rather than+    /// its bytes: the load below is what turns it into one.+    @State private var item: PhotosPickerItem?++    func body(content: Content) -> some View {+        content+            .photosPicker(isPresented: $isPresented, selection: $item, matching: .images)+            .onChange(of: item) { _, picked in+                guard let picked else { return }+                // Cleared before the load, not after: the picker writes the same+                // item again if the reader picks the same photo twice, and an+                // item left standing would make the second pick no change at all.+                item = nil+                Task {+                    // Req 3.6 is the codec's, not the picker's: what arrives+                    // here is the file, and `workingImage` is what bounds it.+                    guard let data = try? await picked.loadTransferable(type: Data.self) else {+                        onCancel()+                        return+                    }+                    onSelection(data)+                }+            }+    }+    #else+    func body(content: Content) -> some View {+        content+            .fileImporter(+                isPresented: $isPresented,+                // Req 3.2's five, spelled out: an open panel that accepted+                // `.image` would offer files the codec cannot read.+                allowedContentTypes: [.jpeg, .png, .heic, .gif, .webP],+                allowsMultipleSelection: false,+                onCompletion: { result in+                    switch result {+                    case .success(let urls):+                        guard let url = urls.first else {+                            onCancel()+                            return+                        }+                        // **The read is off the main actor.** A cover can be a+                        // camera-sized file and `Data(contentsOf:)` on the+                        // actor the window draws on is a stall the reader sees;+                        // the codec's decode (Req 3.6) is what bounds what+                        // happens to the bytes afterwards, not what it costs to+                        // get them.+                        //+                        // The security scope is a **process**-wide grant rather+                        // than a thread-local one, so it stays open across the+                        // hop — opened here, closed when the read has answered,+                        // and the bytes handed back on the main actor.+                        Task {+                            let scoped = url.startAccessingSecurityScopedResource()+                            let data = await Task.detached(priority: .userInitiated) {+                                try? Data(contentsOf: url)+                            }.value+                            if scoped { url.stopAccessingSecurityScopedResource() }+                            guard let data else {+                                onCancel()+                                return+                            }+                            onSelection(data)+                        }+                    case .failure:+                        onCancel()+                    }+                },+                onCancellation: onCancel)+    }+    #endif+}+ extension View {     /// Hands a staged file to the platform's sharing surface: the system share     /// sheet on iOS, the save panel on the Mac (Req 4.5).@@ -379,6 +550,27 @@ extension View {         #endif     } +    /// Takes a cover image in from the platform's own picker+    /// (`work-thumbnails` Req 3.2, Req 2.6).+    ///+    /// A `ViewModifier` rather than a body here, because the iOS arm needs+    /// `@State` of its own: `.photosPicker` writes a `PhotosPickerItem` and the+    /// bytes are loaded off it afterwards.+    ///+    /// Photos on iPhone and iPad, a file open panel on the Mac (Q7) — the two+    /// native answers, not one approximated on the other. `onSelection` is+    /// handed the bytes; `onCancel` runs on every other way out, which is what+    /// retires the editor's session token.+    func imagePicker(+        isPresented: Binding<Bool>,+        onSelection: @escaping (Data) -> Void,+        onCancel: @escaping () -> Void+    ) -> some View {+        modifier(+            ImagePicker(+                isPresented: isPresented, onSelection: onSelection, onCancel: onCancel))+    }+     /// Takes a JSON backup in from the platform's file picker.     func documentImporter(         isPresented: Binding<Bool>,

diff --git a/Asterism/Asterism/Support/UITestMarker.swift b/Asterism/Asterism/Support/UITestMarker.swiftindex c01dc99..1e2915e 100644--- a/Asterism/Asterism/Support/UITestMarker.swift+++ b/Asterism/Asterism/Support/UITestMarker.swift@@ -30,6 +30,32 @@ enum LayoutMarker {     static func entryDetail(_ entryID: UUID) -> String {         "entry-detail-\(entryID.uuidString)"     }++    /// A row's cover slot (`work-thumbnails` Req 6.1, 6.3).+    ///+    /// The cover is decorative and says nothing about the row, so this is the+    /// only way a UI suite can assert that a covered row has one and an+    /// uncovered row has none.+    static let workThumbnail = "work-thumbnail"+    /// The work detail header's cover, which is the same picture at a different+    /// size and has to be nameable apart from the rows behind it.+    static let workDetailCover = "work-detail-cover"+    /// The Cover field's own preview inside the editor, which is a third slot+    /// for the same picture and must not answer a query for either of the two+    /// above.+    static let workDetailCoverPreview = "work-detail-cover-preview"+    /// The cover on its own, opened by a long press on the header (Req 6.5).+    /// A marker layer for the same reason the header's is: the picture is+    /// decorative, so the viewer has nothing else a suite could find it by.+    static let workDetailCoverViewer = "work-detail-cover-viewer"+    /// The viewer's close button, which *is* labelled — named here so the+    /// production side and the suite spell it once.+    static let workDetailCoverViewerClose = "work-detail-cover-viewer-close"+    /// Find cover's candidate sheet (`work-thumbnails` Req 4.7). A marker layer+    /// rather than an identifier on the sheet's content, because two of its+    /// three states are a single sentence and a container's identifier is+    /// inherited by the one element inside it.+    static let coverCandidateSheet = "cover-candidate-sheet" }  /// The `@AppStorage` keys the Mac's relaunch restore reads and writes (Req 7.2,

diff --git a/Asterism/Asterism/Thumbnails/CoverCandidateSheet.swift b/Asterism/Asterism/Thumbnails/CoverCandidateSheet.swiftnew file mode 100644index 0000000..1ed7294--- /dev/null+++ b/Asterism/Asterism/Thumbnails/CoverCandidateSheet.swift@@ -0,0 +1,217 @@+import AsterismCore+import ConstellationKit+import CoreGraphics+import SwiftUI++/// Find cover's candidate list (`work-thumbnails` Reqs 4.7–4.9, 4.11, 4.12).+///+/// **Nothing here writes**, and nothing here fetches: the run belongs to+/// `WorkDetailModel`, which owns the task so that leaving edit mode or leaving+/// the page can cancel it as surely as dismissing this sheet can (Req 4.11).+/// What the sheet does is show what came back and take the reader's pick.+///+/// Each row says the two things that tell one candidate from another — the+/// hostname it came from and its pixel size — and speaks them, with its+/// position, as "n of m, hostname, w by h" (Req 4.7). The first is preselected,+/// so a reader who agrees with the ranking taps Use and nothing else.+struct CoverCandidateSheet: View {+    let state: WorkDetailModel.CoverCandidateSheetState+    /// Req 4.15: whether Scan page is still worth offering. False once the+    /// reader has made a body run — there is nothing left to scan — and false+    /// while a run is in flight, which is the state a second run must not be+    /// started from. Both halves are the model's: the sheet draws what it is+    /// told (`WorkDetailModel.offersCoverPageScan`).+    let offersPageScan: Bool+    let onUse: (CoverCandidate) -> Void+    let onScanPage: () -> Void+    let onCancel: () -> Void++    /// The chosen row, or nil while the reader has chosen nothing — which is+    /// where ``chosen``'s fallback to the first candidate does the preselecting+    /// (Req 4.7). Seeding this from the list as well would be the same rule+    /// twice, and the seeding half of it had to be careful not to fire again+    /// and undo the reader's own choice.+    ///+    /// A Scan page replaces the list under it (Req 4.15), so this can name a+    /// candidate that is no longer offered. The same fallback answers that: a+    /// stale id resolves to the new ranking's head.+    @State private var selected: String?++    private var candidates: [CoverCandidate] {+        if case .candidates(let candidates) = state { return candidates }+        return []+    }++    private var chosen: CoverCandidate? {+        candidates.first { $0.id == selected } ?? candidates.first+    }++    var body: some View {+        NavigationStack {+            content+                .scrollContentBackground(.hidden)+                .macListChrome()+                .navigationTitle("Find cover")+                .inlineNavigationTitle()+                // A named empty layer, **not** an identifier on the content: an+                // identifier on a container is inherited by every descendant,+                // and when the content is one sentence — the none and offline+                // arms — that sentence takes this name instead of its own. Cost+                // one UI-test cycle; the rule is in `docs/agent-notes/testing.md`.+                .background(alignment: .topLeading) {+                    Color.clear.uiTestMarker(LayoutMarker.coverCandidateSheet)+                }+                .toolbar {+                    ToolbarItem(placement: .cancellationAction) {+                        Button("Cancel", role: .cancel) { onCancel() }+                            .accessibilityIdentifier("cover-candidate-cancel")+                    }+                    // Req 4.15, beside Use and in the same slot, declared first+                    // so the primary action keeps the trailing position: the+                    // reader disagreeing with the head is the whole of Q85, and+                    // the disagreement has to be one tap from the picture that+                    // prompted it.+                    ToolbarItem(placement: .confirmationAction) {+                        if offersPageScan {+                            Button("Scan page") { onScanPage() }+                                .accessibilityIdentifier("cover-candidate-scan-page")+                        }+                    }+                    // In the toolbar rather than on a bottom inset: an inset's+                    // content did not reach the accessibility tree at all on+                    // iOS 26, so the button existed and no journey could find+                    // it. The confirmation slot is where this sheet's sibling+                    // (the crop step) puts its Use, too.+                    ToolbarItem(placement: .confirmationAction) {+                        if let chosen {+                            Button("Use this cover") { onUse(chosen) }+                                .accessibilityIdentifier("cover-candidate-use")+                        }+                    }+                }+        }+    }++    @ViewBuilder+    private var content: some View {+        switch state {+        case .loading:+            // Said instead of the empty sentence, never beside it:+            // "no cover was found" is a claim about the pages, and until the+            // run returns this sheet cannot make it.+            ProgressView("Looking for a cover…")+                .accessibilityIdentifier("cover-candidate-loading")+                .frame(maxWidth: .infinity, maxHeight: .infinity)+        case .none:+            // Req 4.8: one line, and not an error of the library.+            message(+                "No cover was found on this work's pages.",+                identifier: "cover-candidate-none",+                // Req 4.15: a reader who has just been told nothing was found+                // should not have to notice a toolbar button to try the one+                // thing that is left.+                offersScan: true)+        case .offline:+            // Req 4.9: a different sentence, because a reader who is offline+            // would otherwise be told their work has no cover art. No scan+            // offered: reading more of a page nobody could reach is no answer.+            message(+                "You appear to be offline, so the pages could not be read.",+                identifier: "cover-candidate-offline",+                offersScan: false)+        case .candidates(let candidates):+            List {+                ForEach(Array(candidates.enumerated()), id: \.element.id) { index, candidate in+                    row(candidate, position: index + 1, of: candidates.count)+                }+            }+        }+    }++    /// Req 4.8 and Req 4.9's one line.+    ///+    /// A plain `Text` rather than a `ContentUnavailableView`: the identifier on+    /// a `Text` inside that view's label closure did not reach the tree, which+    /// is the same family as the container-identifier rule in+    /// `docs/agent-notes/testing.md` — and there is one sentence to say here,+    /// not a title and a description.+    ///+    /// The Req 4.15 action is repeated under the no-cover sentence, and only+    /// that one: a reader who has just been told nothing was found should not+    /// have to notice a toolbar button to reach the one thing left to try,+    /// while a reader who is offline has nothing to gain by reading more of a+    /// page nobody could reach.+    private func message(+        _ text: String, identifier: String, offersScan: Bool+    ) -> some View {+        VStack(spacing: 16) {+            Text(text)+                .font(.callout)+                .multilineTextAlignment(.center)+                .foregroundStyle(AsterismColors.secondaryText)+                .accessibilityIdentifier(identifier)+            if offersScan, offersPageScan {+                Button("Scan page") { onScanPage() }+                    .buttonStyle(.bordered)+                    .accessibilityIdentifier("cover-candidate-none-scan")+            }+        }+        .padding(24)+        .frame(maxWidth: .infinity, maxHeight: .infinity)+    }++    /// One candidate. A `Button` rather than a `List` selection, because+    /// selection in a `List` and a tap on a row fight on iOS+    /// (`UIJourneySupport`'s standing rule) and this sheet has to be drivable.+    private func row(_ candidate: CoverCandidate, position: Int, of total: Int) -> some View {+        Button {+            selected = candidate.id+        } label: {+            HStack(alignment: .top, spacing: 12) {+                // Through the shared slot and the shared cache, drawn fitted at+                // twice a row's box: a 1280×460 banner has to *read* as a+                // banner here, which is the whole of Q85's "the reader can see+                // both". Filling a portrait frame showed it as a sliver of+                // itself and made the decision the sheet exists for+                // unanswerable.+                ThumbnailBytesSlot(+                    namespace: "cover-candidate",+                    identity: ThumbnailIdentity(shape: .portrait, digest: candidate.digest),+                    bytes: candidate.preview,+                    identifier: "cover-candidate-preview-\(position)",+                    baseSize: Self.previewSize)+                VStack(alignment: .leading, spacing: 4) {+                    Text(candidate.hostname)+                        .font(AsterismTypography.serifRowTitle)+                    Text("\(Int(candidate.pixelSize.width)) × \(Int(candidate.pixelSize.height))")+                        .font(.footnote)+                        .foregroundStyle(AsterismColors.secondaryText)+                }+                Spacer(minLength: 0)+                Image(systemName: chosen?.id == candidate.id ? "checkmark.circle.fill" : "circle")+                    .foregroundStyle(+                        chosen?.id == candidate.id+                            ? AsterismColors.cyan : AsterismColors.secondaryText)+            }+            .frame(minHeight: AsterismLayout.minHitTarget)+        }+        .buttonStyle(.plain)+        // Req 4.7's spoken form. The picture itself says nothing: what+        // distinguishes two candidates to a reader who cannot see them is+        // where they came from and how big they are.+        .accessibilityLabel(+            """+            \(position) of \(total), \(candidate.hostname), \+            \(Int(candidate.pixelSize.width)) by \(Int(candidate.pixelSize.height))+            """)+        .accessibilityAddTraits(chosen?.id == candidate.id ? [.isSelected] : [])+        .accessibilityIdentifier("cover-candidate-\(position)")+    }++    /// The box a candidate is drawn inside: the slot's proportions at twice a+    /// row's width, which is big enough to tell two covers apart and small+    /// enough that eight of them are a list.+    private static let previewSize = CGSize(+        width: AsterismLayout.coverSize.width * 2,+        height: AsterismLayout.coverSize.height * 2)+}

diff --git a/Asterism/Asterism/Thumbnails/CoverViewerView.swift b/Asterism/Asterism/Thumbnails/CoverViewerView.swiftnew file mode 100644index 0000000..a0faab1--- /dev/null+++ b/Asterism/Asterism/Thumbnails/CoverViewerView.swift@@ -0,0 +1,77 @@+import AsterismCore+import SwiftUI++/// The work's cover at its stored resolution, on its own, reached by a long+/// press on the detail header (`work-thumbnails` Req 6.5, Q88).+///+/// Read-only: it asks the shared loader for the cover at the stored pixel+/// size — the largest picture the library holds — through the same on-demand+/// read every slot uses, so nothing is decoded that a row could not have+/// decoded, and nothing is written. A cover whose bytes will not load closes+/// the viewer with nothing shown, the same silence Req 6.4 asks of a row.+struct CoverViewerView: View {+    let workID: UUID+    let identity: ThumbnailIdentity+    let title: String++    @Environment(\.thumbnailLoader) private var loader+    @Environment(\.displayScale) private var displayScale+    @Environment(\.dismiss) private var dismiss++    @State private var loaded: CGImage?++    var body: some View {+        ZStack {+            // The marker goes on the backdrop, not on the whole view: an+            // `accessibilityElement()` wrapped around the container would take+            // the close button out of the tree with it, which is the standing+            // rule in `docs/agent-notes/testing.md`.+            Color.black.ignoresSafeArea()+                .uiTestMarker(LayoutMarker.workDetailCoverViewer)+            if let loaded {+                Image(decorative: loaded, scale: displayScale)+                    .resizable()+                    .scaledToFit()+                    .padding(16)+            } else {+                // Until the read answers. A read that answers nothing dismisses+                // below, so this is never the resting state.+                ProgressView()+                    .tint(.white)+            }+        }+        .contentShape(Rectangle())+        .onTapGesture { dismiss() }+        .overlay(alignment: .topTrailing) {+            Button {+                dismiss()+            } label: {+                Image(systemName: "xmark.circle.fill")+                    .font(.title)+                    .foregroundStyle(.white.opacity(0.85))+                    .padding(16)+            }+            .buttonStyle(.plain)+            .accessibilityLabel("Close")+            .accessibilityIdentifier(LayoutMarker.workDetailCoverViewerClose)+        }+        .accessibilityElement(children: .contain)+        .accessibilityLabel("Cover of \(title)")+        .task { await load() }+    }++    /// A cover that cannot be read closes the viewer, whether the loader is+    /// absent or the read answered nothing — the doc comment's promise, and the+    /// same silence Req 6.4 asks of a row. Leaving the viewer up with nothing in+    /// it would be the app saying something went wrong without saying what.+    private func load() async {+        guard let loader else {+            dismiss()+            return+        }+        let stored = identity.shape.pixelSize+        let pixelSize = CGSize(width: stored.width, height: stored.height)+        loaded = await loader.image(workID: workID, identity: identity, pixelSize: pixelSize)+        if loaded == nil { dismiss() }+    }+}

diff --git a/Asterism/Asterism/Thumbnails/CropGeometry.swift b/Asterism/Asterism/Thumbnails/CropGeometry.swiftnew file mode 100644index 0000000..dbd65c7--- /dev/null+++ b/Asterism/Asterism/Thumbnails/CropGeometry.swift@@ -0,0 +1,170 @@+import AsterismCore+import CoreGraphics++/// The crop step's arithmetic, with no view and no state of its own (Reqs+/// 5.1–5.5).+///+/// The reader pans and zooms a picture behind a fixed frame. Two things have to+/// stay true while they do: the image always **fills the frame on at least one+/// axis** — from the cover scale, where it fills both, down to the fit scale,+/// where it touches one and leaves a centred gap on the other — and what is+/// inside the frame is exactly what gets encoded, the gap left out so the+/// stored image is shorter or narrower than its box and the slots draw the+/// row's background through it (Q89, Decision 3). Both are stated here as pure+/// functions over two sizes, so the gestures in `ThumbnailCropView` only ever+/// propose a scale or an offset and take back the clamped one.+///+/// **Coordinates.** `sourceSize` is the working image's own pixel size;+/// `frameSize` is the frame's size in the view's points. A point `p` of the+/// image is drawn at+///+///     screen = (p - sourceSize / 2) * scale + offset + frameCentre+///+/// — the image centred in the frame, scaled, then translated. `cropRect` is that+/// mapping inverted over the frame's four corners, so its origin is **top left**+/// in image pixels, which is the orientation `ThumbnailCodec.encode` takes.+struct CropGeometry: Equatable {+    /// The working image's pixel size.+    let sourceSize: CGSize+    /// The frame's size in the view's points.+    let frameSize: CGSize++    init(sourceSize: CGSize, frameSize: CGSize) {+        // A zero on either side would divide by zero in every function below.+        // Neither is reachable from the view — a working image that decoded has+        // pixels and a frame laid out has points — so this is a floor rather+        // than a case.+        self.sourceSize = CGSize(+            width: max(sourceSize.width, 1), height: max(sourceSize.height, 1))+        self.frameSize = CGSize(+            width: max(frameSize.width, 1), height: max(frameSize.height, 1))+    }++    /// The smallest scale at which the image still covers the whole frame.+    ///+    /// This is where the crop step **opens**, not its floor: ``fitScale`` is the+    /// floor, and between the two a corner of the frame shows through on one+    /// axis, which Req 5.1 allows since Q89. A source smaller than the frame+    /// simply gets a cover scale above 1 and is scaled up (Req 5.5) — no size is+    /// refused.+    var coverScale: CGFloat {+        max(frameSize.width / sourceSize.width, frameSize.height / sourceSize.height)+    }++    /// The smallest scale the reader may zoom out to: the image fits inside the+    /// frame, touching it on at least one axis, so a picture whose shape is+    /// close to the frame's can be shown whole with a gap on the other axis.+    /// The gap is not encoded: the stored image is shorter or narrower than+    /// the box, and the slots draw it fitted.+    var fitScale: CGFloat {+        min(frameSize.width / sourceSize.width, frameSize.height / sourceSize.height)+    }++    /// A proposed zoom, clamped to at least ``fitScale``. The crop step opens+    /// at ``coverScale``; this is the floor below it.+    func clamped(scale proposed: CGFloat) -> CGFloat {+        max(proposed, fitScale)+    }++    /// A proposed pan, clamped so the frame stays covered at `scale`.+    ///+    /// The slack on each axis is the drawn image's overhang, halved: at the+    /// cover scale one axis has none at all, which is why a picture of exactly+    /// the frame's aspect ratio does not move, and below it an axis the image+    /// no longer fills has none either, so the gap stays centred.+    func clamped(offset proposed: CGSize, scale: CGFloat) -> CGSize {+        let drawn = CGSize(+            width: sourceSize.width * scale, height: sourceSize.height * scale)+        let slackX = max((drawn.width - frameSize.width) / 2, 0)+        let slackY = max((drawn.height - frameSize.height) / 2, 0)+        return CGSize(+            width: min(max(proposed.width, -slackX), slackX),+            height: min(max(proposed.height, -slackY), slackY))+    }++    /// What is inside the frame, in the source image's own pixels, origin top+    /// left — the rectangle `ThumbnailCodec.encode` is handed (Req 5.3).+    ///+    /// The caller is expected to have clamped `scale` and `offset` first; this+    /// does not clamp, because the value it returns has to be the honest inverse+    /// of what the reader is looking at.+    func cropRect(scale: CGFloat, offset: CGSize) -> CGRect {+        let width = frameSize.width / scale+        let height = frameSize.height / scale+        return CGRect(+            x: sourceSize.width / 2 - width / 2 - offset.width / scale,+            y: sourceSize.height / 2 - height / 2 - offset.height / scale,+            width: width,+            height: height)+    }++    /// The scale and offset that put `crop` under the frame — ``cropRect``+    /// inverted.+    ///+    /// The default frame is the one case the view needs it for: the largest+    /// centred rectangle of the shape, which is `cropRect(scale: coverScale,+    /// offset: .zero)`. It is public to the file rather than private because a+    /// round trip through the two is the only way to state that the mapping is+    /// one, which is what the tests assert.+    func placement(for crop: CGRect) -> (scale: CGFloat, offset: CGSize) {+        let scale = frameSize.width / max(crop.width, 1)+        return (+            scale,+            CGSize(+                width: (sourceSize.width / 2 - crop.midX) * scale,+                height: (sourceSize.height / 2 - crop.midY) * scale)+        )+    }++    // MARK: - Shapes++    /// The shape the crop step opens in (Req 5.2): the one whose largest centred+    /// frame keeps the larger share of the source's area, **portrait on ties**.+    ///+    /// The share is a closed expression rather than a search. For a frame of+    /// aspect ratio `a` inside a source of aspect ratio `t = W/H`, the largest+    /// centred frame is bounded by the source's height when `t > a` and by its+    /// width otherwise, so the share is `a / t` in the first case and `t / a` in+    /// the second — which is `min(a, t) / max(a, t)` either way.+    ///+    /// Square wins only when it wins by a real margin: two shares that differ by+    /// floating-point dust are a tie, and a tie is portrait. A source of aspect+    /// ratio `√(2∕3)` is the exact tie and the reason the tolerance is not zero.+    static func defaultShape(forSourceSize size: CGSize) -> ThumbnailShape {+        let portrait = areaShare(frameAspect: aspect(of: .portrait), sourceSize: size)+        let square = areaShare(frameAspect: aspect(of: .square), sourceSize: size)+        return square - portrait > 1e-9 ? .square : .portrait+    }++    /// A shape's aspect ratio, from the one place the shapes state their+    /// dimensions.+    ///+    /// `defaultShape` used to hard-code `2/3` while ``frameSize(for:fitting:)``+    /// derived the same number from `pixelSize` — so a change to the stored box+    /// would have moved the frame and left the shape choice deciding about the+    /// old one.+    static func aspect(of shape: ThumbnailShape) -> CGFloat {+        let (width, height) = shape.pixelSize+        return CGFloat(width) / CGFloat(height)+    }++    /// The fraction of the source's area the largest centred frame of that+    /// aspect ratio covers.+    private static func areaShare(frameAspect: CGFloat, sourceSize: CGSize) -> CGFloat {+        let width = max(sourceSize.width, 1)+        let height = max(sourceSize.height, 1)+        let sourceAspect = width / height+        return min(frameAspect, sourceAspect) / max(frameAspect, sourceAspect)+    }++    /// The frame's size in points: the largest rectangle of `shape`'s aspect+    /// ratio that fits inside `available`.+    static func frameSize(for shape: ThumbnailShape, fitting available: CGSize) -> CGSize {+        let aspect = aspect(of: shape)+        let width = max(available.width, 1)+        let height = max(available.height, 1)+        return width / height > aspect+            ? CGSize(width: height * aspect, height: height)+            : CGSize(width: width, height: width / aspect)+    }+}

diff --git a/Asterism/Asterism/Thumbnails/ThumbnailCropView.swift b/Asterism/Asterism/Thumbnails/ThumbnailCropView.swiftnew file mode 100644index 0000000..8dc56f9--- /dev/null+++ b/Asterism/Asterism/Thumbnails/ThumbnailCropView.swift@@ -0,0 +1,285 @@+import AsterismCore+import ConstellationKit+import CoreGraphics+import SwiftUI++/// A source image on its way to the crop step (Req 3.5).+///+/// `Identifiable` because the crop step is presented with `.sheet(item:)` —+/// reading the image out of the model inside a presentation closure is the+/// family of bug `duplicate-reconciliation` Q101 records. The `id` is the+/// editor's **session token**, so a crop confirmed after the reader cancelled or+/// picked again carries a token the model no longer holds and is dropped+/// (Req 3.7).+struct ThumbnailCropSource: Identifiable {+    let id: UUID+    /// The working image: already downsampled to at most 2,400 px and with its+    /// orientation baked in (`ThumbnailCodec.workingImage`).+    let image: CGImage++    var pixelSize: CGSize {+        CGSize(width: image.width, height: image.height)+    }+}++/// The crop step (Reqs 5.1–5.5, Q35).+///+/// One SwiftUI view for every platform: no system cropper covers both, and the+/// one place the Mac needs something of its own — the scroll wheel — is behind+/// `PlatformModifiers.scrollWheelZoom`.+///+/// **Nothing here writes.** Confirm hands a `ThumbnailDraft` back to the editor's+/// draft, which the ordinary Save writes (Req 2.2); Cancel hands back nothing+/// and the draft state is whatever it was (Req 5.4).+///+/// **It is completable without a gesture** (Q32, Req 5.3): the shape switch is a+/// labelled control, and confirming without touching anything encodes the+/// default frame — the largest centred rectangle of the opening shape.+struct ThumbnailCropView: View {+    let source: ThumbnailCropSource+    let onConfirm: (ThumbnailDraft) -> Void+    let onCancel: () -> Void++    /// Req 5.2's opening shape, derived from the picture rather than fixed.+    @State private var shape: ThumbnailShape+    /// nil means "the reader has not zoomed", which resolves to the cover scale+    /// — and resolves again, to a different number, when the shape changes.+    @State private var scale: CGFloat?+    @State private var offset: CGSize = .zero+    /// What the live gesture is measured from. Set on the first change of a+    /// gesture and dropped at its end, so a second drag starts where the first+    /// one stopped.+    @State private var dragBase: CGSize?+    @State private var zoomBase: CGFloat?+    /// The space the frame is laid out inside, reported by the layout.+    @State private var availableSize: CGSize = .zero+    /// Set while the confirmed crop is being encoded off the main actor. The+    /// encode is the most pixel work any single tap in this app does, so the+    /// step says it is working rather than freezing mid-gesture.+    @State private var isEncoding = false++    init(+        source: ThumbnailCropSource,+        onConfirm: @escaping (ThumbnailDraft) -> Void,+        onCancel: @escaping () -> Void+    ) {+        self.source = source+        self.onConfirm = onConfirm+        self.onCancel = onCancel+        _shape = State(initialValue: CropGeometry.defaultShape(forSourceSize: source.pixelSize))+    }++    // MARK: - Derived geometry++    private var frameSize: CGSize {+        CropGeometry.frameSize(for: shape, fitting: availableSize)+    }++    private var geometry: CropGeometry {+        CropGeometry(sourceSize: source.pixelSize, frameSize: frameSize)+    }++    /// The zoom actually in force: the reader's, or the cover scale where they+    /// have not zoomed — clamped either way, because the shape can change under+    /// a zoom the new frame no longer covers.+    private var currentScale: CGFloat {+        geometry.clamped(scale: scale ?? geometry.coverScale)+    }++    // MARK: - Body++    var body: some View {+        NavigationStack {+            VStack(spacing: 16) {+                cropArea+                shapeControl+            }+            .padding(16)+            .frame(maxWidth: .infinity, maxHeight: .infinity)+            .navigationTitle("Cover")+            .inlineNavigationTitle()+            .toolbar {+                ToolbarItem(placement: .cancellationAction) {+                    Button("Cancel", role: .cancel) { onCancel() }+                        .accessibilityIdentifier("thumbnail-crop-cancel")+                        .disabled(isEncoding)+                }+                ToolbarItem(placement: .confirmationAction) {+                    Button("Use") { confirm() }+                        .accessibilityIdentifier("thumbnail-crop-confirm")+                        .disabled(isEncoding)+                }+            }+        }+    }++    /// The picture behind the frame, and the frame's own edge.+    ///+    /// The whole thing is **one** accessibility element (Req 5.3): pan and zoom+    /// are gestures, so a reader who cannot make one needs the element to say+    /// what it is and the hint to say what the gestures would do — and then the+    /// Use button above accepts the default frame without either.+    private var cropArea: some View {+        ZStack {+            Image(decorative: source.image, scale: 1)+                .resizable()+                .frame(+                    width: source.pixelSize.width * currentScale,+                    height: source.pixelSize.height * currentScale)+                .offset(x: offset.width, y: offset.height)+        }+        .frame(width: frameSize.width, height: frameSize.height)+        .clipShape(RoundedRectangle(cornerRadius: AsterismLayout.coverRadius, style: .continuous))+        .overlay {+            RoundedRectangle(cornerRadius: AsterismLayout.coverRadius, style: .continuous)+                .strokeBorder(AsterismColors.cardBorder, lineWidth: 1)+        }+        // The encode is off the main actor, so the picture stays on screen and+        // stays laid out; what the reader needs is that the tap was taken and+        // that a second pan will not move a frame already being encoded.+        .overlay {+            if isEncoding {+                ProgressView().controlSize(.large)+            }+        }+        .allowsHitTesting(!isEncoding)+        .frame(maxWidth: .infinity, maxHeight: .infinity)+        .contentShape(Rectangle())+        .gesture(SimultaneousGesture(panGesture, zoomGesture))+        .scrollWheelZoom { factor in applyZoom(factor) }+        // The space the frame is sized against. Read from the flexible box+        // above rather than through a `GeometryReader`, so the frame the layout+        // draws and the frame `confirm()` maps through are one value.+        .onGeometryChange(for: CGSize.self) { $0.size } action: { availableSize = $0 }+        .accessibilityElement()+        .accessibilityLabel("Crop frame")+        .accessibilityHint(+            "Drag to move the picture and pinch to zoom. Use accepts the frame as it is.")+        .accessibilityIdentifier("thumbnail-crop-frame")+    }++    /// Req 5.2's labelled switch. Changing the shape drops the reader's zoom and+    /// pan: the new frame has a different cover scale, and carrying a placement+    /// across would open the other shape somewhere the reader never put it.+    private var shapeControl: some View {+        ConstellationSegmentedControl(+            values: ThumbnailShape.allCases,+            selection: Binding(+                get: { shape },+                set: { newShape in+                    guard newShape != shape else { return }+                    shape = newShape+                    scale = nil+                    offset = .zero+                }),+            containerLabel: "Shape",+            title: ThumbnailPresentation.name,+            identifier: { "thumbnail-crop-shape-\($0.rawValue)" })+            .constellationCaptionedField("Shape")+    }++    // MARK: - Gestures++    private var panGesture: some Gesture {+        DragGesture()+            .onChanged { value in+                let base = dragBase ?? offset+                dragBase = base+                offset = geometry.clamped(+                    offset: CGSize(+                        width: base.width + value.translation.width,+                        height: base.height + value.translation.height),+                    scale: currentScale)+            }+            .onEnded { _ in dragBase = nil }+    }++    private var zoomGesture: some Gesture {+        MagnifyGesture()+            .onChanged { value in+                let base = zoomBase ?? currentScale+                zoomBase = base+                setScale(base * value.magnification)+            }+            .onEnded { _ in zoomBase = nil }+    }++    private func applyZoom(_ factor: CGFloat) {+        setScale(currentScale * factor)+    }++    /// One place the two zooms meet: clamp the scale, then re-clamp the pan+    /// against it, because zooming out shrinks the overhang the pan was allowed.+    private func setScale(_ proposed: CGFloat) {+        let clamped = geometry.clamped(scale: proposed)+        scale = clamped+        offset = geometry.clamped(offset: offset, scale: clamped)+    }++    // MARK: - Confirm++    /// **Off the main actor** (Req 1.2's encode is the heaviest single tap in+    /// the app: a full draw of the working image into the shape's box — 600×900+    /// at most, less on an axis the reader zoomed a gap onto (Decision 3) — and+    /// then up to+    /// five JPEG passes down the quality ladder). Running it inline froze the+    /// sheet for the whole of it, with the model's preview decode queued behind+    /// it on the same actor.+    ///+    /// Nothing about where it runs changes what it is: the result is still a+    /// value handed back to the editor's draft, and the store is still written+    /// once, by Save (Req 2.2).+    ///+    /// `isEncoding` is raised before the first suspension and **never lowered**:+    /// it is what disables the controls and the gestures for the length of the+    /// encode, and the step's one way forward is `onConfirm`, which dismisses+    /// the sheet. Lowering it beside the hand-off would have left the frame tappable+    /// for the turn between.+    private func confirm() {+        guard !isEncoding else { return }+        isEncoding = true+        let crop = geometry.cropRect(scale: currentScale, offset: offset)+        let shape = shape+        // `CGImage` is immutable once ImageIO has built it; the wrapper is how+        // that is said to the compiler, and the decode cache says it the same+        // way.+        let source = DecodedThumbnail(image: source.image)+        Task {+            let draft = await Task.detached(priority: .userInitiated) {+                ThumbnailCodec.encode(source.image, crop: crop, shape: shape)+            }.value+            // **Left set.** Clearing it first opened a turn in which the sheet+            // was still on screen, hit-testing again and with `confirm()`'s own+            // guard down, so a second tap could start a second encode of the+            // same frame. `onConfirm` retires the crop source and the sheet goes+            // with it; the flag dies with the view rather than being handed+            // back.+            onConfirm(draft)+        }+    }+}++/// What a shape is called on screen and to VoiceOver.+///+/// One home, because the crop step's segment labels and the Cover field's+/// spoken value are the same two words and must stay the same two words.+///+/// `nonisolated` for `SiteNames`' reason (Q23 there): this is a pure lookup, and+/// one of its callers is `ConstellationSegmentedControl`'s `title` closure,+/// which is not main-actor isolated. Under the project's+/// `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor` an unannotated one warns there.+nonisolated enum ThumbnailPresentation {+    static func name(_ shape: ThumbnailShape) -> String {+        switch shape {+        case .portrait: "Portrait"+        case .square: "Square"+        }+    }++    /// The Cover menu's accessibility value (Req 2.1): what the field currently+    /// holds, said rather than shown.+    static func accessibilityValue(_ shape: ThumbnailShape?) -> String {+        guard let shape else { return "No cover" }+        return "\(name(shape)) cover"+    }+}

diff --git a/Asterism/Asterism/Thumbnails/ThumbnailImageCache.swift b/Asterism/Asterism/Thumbnails/ThumbnailImageCache.swiftnew file mode 100644index 0000000..e1e13e7--- /dev/null+++ b/Asterism/Asterism/Thumbnails/ThumbnailImageCache.swift@@ -0,0 +1,200 @@+import AsterismCore+import CoreGraphics+import Foundation+import SwiftUI++/// An immutable decoded image on its way from a background decode to the main+/// actor.+///+/// A `CGImage` built by ImageIO and never drawn into again is safe to hand+/// across an isolation boundary; the type simply does not say so. One wrapper,+/// used only here, rather than an `@unchecked` conformance on a framework type.+struct DecodedThumbnail: @unchecked Sendable {+    let image: CGImage+}++/// The bounded decode cache every surface that draws a cover reads through+/// (Req 7.2, Q33, Q36, Q70).+///+/// **Three things in one object, because they are one seam.** It is the cache;+/// it is the loader (it holds the library reference, so a row does not); and it+/// is the environment value `\.thumbnailLoader`, so `WorkRow`, `RecentEntryRow`,+/// the detail header and the resolution sheet reach it without a single row+/// signature changing.+///+/// **Keyed by work, digest and drawn pixel size.** The digest is what keeps a+/// replaced or removed cover from being drawn stale — a new picture is a new key+/// and the old entry is simply never asked for again. The size is what keeps the+/// header's 160×240 decode and a row's 56×84 one from colliding (Q86). The work id is+/// what keeps a row from borrowing another work's bytes.+///+/// **Decoding is off the main actor and only the insert is on it.** A 600×900+/// JPEG decode inside a list's body pass is a dropped frame per row; the detached+/// task is what keeps it out of one.+@MainActor @Observable+final class ThumbnailImageCache {++    /// Q36: a row decode at 3× is 86 KB at the default text size and 194 KB at+    /// the 1.5× cap, a header decode 778 KB — so 24 MB holds a header plus 120+    /// to 250 rows, and `NSCache` evicts under pressure without any code here.+    static let costLimit = 24 * 1_024 * 1_024++    /// The generation the loader is mirroring, assigned by `AppLibraryModel`+    /// from its `snapshotGeneration`.+    ///+    /// Observed, and part of every slot's `task(id:)`: a sync arrival that+    /// delivers an asset the record had arrived without changes nothing about+    /// the identity, so without this the slot would never look again (Req 1.8).+    private(set) var generation = 0++    @ObservationIgnored private let table = NSCache<NSString, CGImage>()+    @ObservationIgnored private var library: (any LibraryProviding)?+    /// The decode, injectable so the tests can observe where it runs and the+    /// previews can answer without ImageIO.+    @ObservationIgnored private let decoder: @Sendable (Data, Int) -> DecodedThumbnail?++    init(+        library: (any LibraryProviding)? = nil,+        decoder: @escaping @Sendable (Data, Int) -> DecodedThumbnail? = {+            ThumbnailCodec.displayImage(from: $0, maxPixelSize: $1).map(DecodedThumbnail.init)+        }+    ) {+        self.library = library+        self.decoder = decoder+        table.totalCostLimit = Self.costLimit+    }++    /// Points into pixels. The drawn size and the screen's scale together are+    /// what the decode is sized by, so they are together in the key.+    static func pixelSize(points: CGSize, displayScale: CGFloat) -> CGSize {+        let scale = max(displayScale, 1)+        return CGSize(+            width: (points.width * scale).rounded(.up),+            height: (points.height * scale).rounded(.up))+    }++    /// The cache key: work, digest, pixel size. Spelled once, here, because the+    /// read and the insert have to agree about it exactly.+    static func key(workID: UUID, digest: String, pixelSize: CGSize) -> String {+        key(namespace: workID.uuidString, digest: digest, pixelSize: pixelSize)+    }++    /// The same key with the owner spelled by the caller.+    ///+    /// Every display path names a work by its UUID. The duplicate-resolution+    /// sheet is the one surface that does not have one: it is choosing between+    /// *variants* of a set, which are named by content digest, so it names its+    /// own namespace and shares the table with everything else.+    static func key(namespace: String, digest: String, pixelSize: CGSize) -> String {+        "\(namespace)|\(digest)|\(Int(pixelSize.width))x\(Int(pixelSize.height))"+    }++    // MARK: - The loader seam++    /// Points the loader at the library that just opened, and drops it when one+    /// closes. Every entry from the previous library goes with it: a disposable+    /// UI-test root reuses work ids.+    func attach(library: (any LibraryProviding)?) {+        self.library = library+        table.removeAllObjects()+        generation = 0+    }++    /// Mirrors `AppLibraryModel.snapshotGeneration`.+    func update(generation: Int) {+        guard generation != self.generation else { return }+        self.generation = generation+    }++    // MARK: - Reads++    /// What is already decoded at this size, if anything — the synchronous read+    /// every slot makes on every appearance, so a row that scrolls back into+    /// view draws its cover in the same frame rather than flashing empty.+    func cachedImage(workID: UUID, identity: ThumbnailIdentity, pixelSize: CGSize) -> CGImage? {+        cachedImage(+            namespace: workID.uuidString, digest: identity.digest, pixelSize: pixelSize)+    }++    func cachedImage(namespace: String, digest: String, pixelSize: CGSize) -> CGImage? {+        table.object(+            forKey: Self.key(namespace: namespace, digest: digest, pixelSize: pixelSize)+                as NSString)+    }++    /// The cover at the size it will be drawn, decoded on demand.+    ///+    /// Answers nil for every one of Req 1.8's tolerated states — the bytes are+    /// missing, they are not the digest's, their dimensions are not the shape's,+    /// or there is no library — and **never caches a nil**: the asset may still+    /// be in transit, and the next generation has to be able to ask again.+    func image(+        workID: UUID, identity: ThumbnailIdentity, pixelSize: CGSize+    ) async -> CGImage? {+        if let cached = cachedImage(workID: workID, identity: identity, pixelSize: pixelSize) {+            return cached+        }+        guard let library else { return nil }+        let bytes: Data?+        do {+            bytes = try await library.thumbnailBytes(workID: workID, digest: identity.digest)+        } catch {+            // A failed read is a cover that is not shown, never a failed screen+            // (Req 6.4). The repository has already logged why.+            return nil+        }+        guard let bytes else { return nil }+        return await image(+            namespace: workID.uuidString, digest: identity.digest, pixelSize: pixelSize,+            bytes: bytes)+    }++    /// The same decode over bytes the caller already holds — the duplicate+    /// resolution sheet, whose variant choices carry their own bytes out of the+    /// commit-time read (Req 1.6).+    ///+    /// It shares the table, so a cover the sheet draws and the row behind it+    /// draws is decoded once between them rather than once each — and, more to+    /// the point, once rather than **once per body pass**, which is what calling+    /// `ThumbnailCodec.previewImage` inline used to cost.+    func image(+        namespace: String, digest: String, pixelSize: CGSize, bytes: Data+    ) async -> CGImage? {+        if let cached = cachedImage(namespace: namespace, digest: digest, pixelSize: pixelSize) {+            return cached+        }+        let maxPixelSize = Int(max(pixelSize.width, pixelSize.height).rounded(.up))+        let decoder = self.decoder+        // Off the main actor, and only this. The insert below is back on it.+        let decoded = await Task.detached(priority: .userInitiated) {+            decoder(bytes, maxPixelSize)+        }.value+        guard let decoded else { return nil }+        insert(decoded.image, namespace: namespace, digest: digest, pixelSize: pixelSize)+        return decoded.image+    }++    /// Cost is the decoded bitmap's own bytes, which is what the 24 MB limit is+    /// about — not the JPEG it came from.+    private func insert(+        _ image: CGImage, namespace: String, digest: String, pixelSize: CGSize+    ) {+        table.setObject(+            image,+            forKey: Self.key(namespace: namespace, digest: digest, pixelSize: pixelSize)+                as NSString,+            cost: image.bytesPerRow * image.height)+    }+}++extension EnvironmentValues {+    /// The cover loader, installed once by `AppLibraryModel` (Q70).+    ///+    /// On the `\.siteNames` precedent and for its reason: rows hold a snapshot+    /// and no model, and threading a loader through every row initialiser would+    /// change a dozen signatures to carry one value none of them acts on.+    ///+    /// The default is **nil**, which draws no covers at all — the right answer+    /// for a preview or a presentation path that never received one.+    @Entry var thumbnailLoader: ThumbnailImageCache?+}

diff --git a/Asterism/Asterism/Thumbnails/ThumbnailSlot.swift b/Asterism/Asterism/Thumbnails/ThumbnailSlot.swiftnew file mode 100644index 0000000..f792414--- /dev/null+++ b/Asterism/Asterism/Thumbnails/ThumbnailSlot.swift@@ -0,0 +1,268 @@+import AsterismCore+import ConstellationKit+import CoreGraphics+import SwiftUI++/// The geometry a cover slot draws by (Req 6.2), stated once for both slots.+///+/// The 56×84 box, the 1.5× Dynamic Type cap and "a square is drawn at the+/// slot's width" were spelled twice, and two spellings of one geometry is two+/// chances for a row's decode and a picker's to key the cache differently.+struct CoverSlotGeometry {+    let shape: ThumbnailShape+    /// The slot at the default text size. `AsterismLayout.coverSize` on a row,+    /// `coverHeaderSize` on the detail header.+    let baseSize: CGSize+    /// Req 6.2's linear scaling with the body text size, capped. Taken from a+    /// `@ScaledMetric` probe rather than a scaled width, so one metric serves+    /// both axes and the cap applies to the ratio.+    let typeScale: CGFloat+    let displayScale: CGFloat++    init(shape: ThumbnailShape, baseSize: CGSize, typeSizeProbe: CGFloat, displayScale: CGFloat) {+        self.shape = shape+        self.baseSize = baseSize+        self.typeScale = min(typeSizeProbe / 100, 1.5)+        self.displayScale = displayScale+    }++    /// Req 6.2: a portrait cover fills the slot; a square one draws at the+    /// slot's **width**, which leaves it shorter. Rows centre it (Q87).+    var drawnSize: CGSize {+        let width = baseSize.width * typeScale+        return switch shape {+        case .portrait: CGSize(width: width, height: baseSize.height * typeScale)+        case .square: CGSize(width: width, height: width)+        }+    }++    var pixelSize: CGSize {+        ThumbnailImageCache.pixelSize(points: drawnSize, displayScale: displayScale)+    }+}++/// A decoded cover, drawn the way Decision 3 says every cover is drawn: fitted+/// rather than filled, with the corner and the border **on the picture** so a+/// stored gap is not outlined.+///+/// One image chain rather than one per slot: a cover that filled in one place+/// and fitted in another would be two different pictures of the same work.+private struct CoverImage: View {+    let image: CGImage+    let drawnSize: CGSize+    let cornerRadius: CGFloat+    /// The row and header slots outline the picture; the pickers, which draw it+    /// against a sheet rather than against a list row, do not.+    let bordered: Bool++    @Environment(\.displayScale) private var displayScale++    var body: some View {+        Image(decorative: image, scale: displayScale)+            .resizable()+            .scaledToFit()+            .clipShape(RoundedRectangle(cornerRadius: cornerRadius, style: .continuous))+            .overlay {+                if bordered {+                    RoundedRectangle(cornerRadius: cornerRadius, style: .continuous)+                        .strokeBorder(AsterismColors.cardBorder, lineWidth: 1)+                }+            }+            .frame(width: drawnSize.width, height: drawnSize.height)+    }+}++/// The one component that draws a stored cover (Reqs 6.1–6.4, 7.2).+///+/// The work row, the Recent row, the work detail header and the pickers all use+/// it, so Req 6.2's geometry — the 56×84 slot, the 1.5× Dynamic Type cap, and a+/// square drawn at the slot's width — is stated once, here, rather than at four+/// call sites that could drift.+///+/// **The picture is drawn fitted, not filled** (Decision 3): a cover stored+/// shorter or narrower than its box sits centred in the slot with the row's own+/// background through the gap, and the corner and the border go on the picture+/// rather than on the slot so the gap is not outlined.+///+/// **Decorative** (Req 6.3): the cover adds nothing to the row's spoken content.+/// `uiTestMarker` names it for the UI suites in debug builds and hides it+/// outright in a shipping one, which is the same bargain the layout markers make.+///+/// **It never makes a row wait.** The row's text is drawn immediately; the slot+/// holds its space while the bytes load and gives it back if they never come, so+/// a work whose cover is missing or will not decode falls back to the glyph+/// layout with nothing said (Req 6.4, Req 1.8).+struct ThumbnailSlot: View {+    let workID: UUID+    let identity: ThumbnailIdentity+    /// The slot at the default text size. `AsterismLayout.coverSize` on a row,+    /// `coverHeaderSize` on the detail header.+    var baseSize: CGSize = AsterismLayout.coverSize+    var cornerRadius: CGFloat = AsterismLayout.coverSlotRadius+    /// The gap to whatever sits after the slot. **The slot's own**, so a slot+    /// that gives its space back costs the row nothing at all — a container's+    /// spacing would survive the collapse and leave the glyph layout indented.+    var trailingGap: CGFloat = 10+    var marker: String = LayoutMarker.workThumbnail++    @Environment(\.thumbnailLoader) private var loader+    @Environment(\.displayScale) private var displayScale++    /// Req 6.2's linear scaling with the body text size. A probe rather than a+    /// scaled width, so one `@ScaledMetric` serves both axes and the cap is+    /// applied to the ratio.+    @ScaledMetric(relativeTo: .body) private var typeSizeProbe: CGFloat = 100++    @State private var loaded: CGImage?+    /// Set once the load has answered nothing. Distinct from `loaded == nil`,+    /// which is also the state before the load has run at all.+    @State private var isMissing = false++    private var geometry: CoverSlotGeometry {+        CoverSlotGeometry(+            shape: identity.shape, baseSize: baseSize, typeSizeProbe: typeSizeProbe,+            displayScale: displayScale)+    }++    private var drawnSize: CGSize { geometry.drawnSize }+    private var pixelSize: CGSize { geometry.pixelSize }++    /// The cache is consulted on **every** appearance, before the task runs, so+    /// a row scrolled back into view draws in the same frame it appears in.+    private var image: CGImage? {+        loaded+            ?? loader?.cachedImage(workID: workID, identity: identity, pixelSize: pixelSize)+    }++    var body: some View {+        content+            .uiTestMarker(marker)+            // `identity` covers a replaced or removed cover; the generation+            // covers bytes that arrived after the record did (Req 1.8).+            .task(id: taskID) { await load() }+    }++    @ViewBuilder+    private var content: some View {+        if let image {+            CoverImage(+                image: image, drawnSize: drawnSize, cornerRadius: cornerRadius,+                bordered: true)+                .padding(.trailing, trailingGap)+        } else if isMissing {+            // Req 6.4: the row re-lays out to exactly what it would have been+            // without a cover at all.+            Color.clear.frame(width: 0, height: 0)+        } else {+            // The space the cover is about to occupy. Holding it is what keeps+            // a list from reflowing under the reader a frame after it appears;+            // the row's text is already drawn either way.+            Color.clear+                .frame(width: drawnSize.width, height: drawnSize.height)+                .padding(.trailing, trailingGap)+        }+    }++    /// Both axes, because the cache key carries both. A square cover and a+    /// portrait one are drawn at the same width and different heights, so a+    /// shape change under one digest — Req 1.8's third tolerated state, where a+    /// per-field merge pairs one device's shape with another's bytes — would+    /// otherwise leave the task un-rerun and the slot holding the old decode.+    private var taskID: String {+        """+        \(workID.uuidString)|\(identity.digest)\+        |\(Int(pixelSize.width))x\(Int(pixelSize.height))|\(loader?.generation ?? 0)+        """+    }++    private func load() async {+        guard let loader else {+            isMissing = true+            return+        }++        if let cached = loader.cachedImage(+            workID: workID, identity: identity, pixelSize: pixelSize) {+            loaded = cached+            isMissing = false+            return+        }+        let image = await loader.image(+            workID: workID, identity: identity, pixelSize: pixelSize)+        loaded = image+        isMissing = image == nil+    }+}++/// A cover the caller already holds the bytes of, drawn at slot size.+///+/// Three surfaces are in this shape, and none of them can go through+/// `ThumbnailSlot`'s on-demand read: the duplicate-resolution sheet is choosing+/// between *variants*, named by a content digest rather than by a work id; the+/// Cover field's preview is showing a crop that is not written yet (Req 2.2);+/// and a Find cover candidate belongs to no work at all until the reader picks+/// it. What they share is the decode — it goes through the same cache, keyed on+/// its own namespace, which is what keeps a 600 px JPEG from being decoded again+/// on every body pass.+///+/// The picture is drawn **fitted**, like every other cover (Decision 3): a+/// candidate that is a 1280×460 banner reads as a banner in the list, which is+/// the whole of Q85's "the reader can see both".+///+/// Unlike a row's slot this one is **not** decorative: here the picture *is* the+/// difference the reader is being asked about, so it says which shape it is —+/// the half of the decision a reader who cannot see it can still act on.+struct ThumbnailBytesSlot: View {+    /// What owns these bytes, for the cache key. A `VariantID`'s raw value on+    /// the resolution sheet.+    let namespace: String+    let identity: ThumbnailIdentity+    let bytes: Data+    let identifier: String+    var baseSize: CGSize = AsterismLayout.coverSize+    var cornerRadius: CGFloat = AsterismLayout.coverSlotRadius++    @Environment(\.thumbnailLoader) private var loader+    @Environment(\.displayScale) private var displayScale+    @ScaledMetric(relativeTo: .body) private var typeSizeProbe: CGFloat = 100++    @State private var loaded: CGImage?++    private var geometry: CoverSlotGeometry {+        CoverSlotGeometry(+            shape: identity.shape, baseSize: baseSize, typeSizeProbe: typeSizeProbe,+            displayScale: displayScale)+    }++    private var drawnSize: CGSize { geometry.drawnSize }+    private var pixelSize: CGSize { geometry.pixelSize }++    private var image: CGImage? {+        loaded+            ?? loader?.cachedImage(+                namespace: namespace, digest: identity.digest, pixelSize: pixelSize)+    }++    var body: some View {+        Group {+            if let image {+                CoverImage(+                    image: image, drawnSize: drawnSize, cornerRadius: cornerRadius,+                    bordered: false)+                    .accessibilityLabel(+                        ThumbnailPresentation.accessibilityValue(identity.shape))+                    .accessibilityIdentifier(identifier)+            } else {+                Color.clear.frame(width: drawnSize.width, height: drawnSize.height)+            }+        }+        // Both axes, for `ThumbnailSlot.taskID`'s reason.+        .task(+            id: "\(namespace)|\(identity.digest)|\(Int(pixelSize.width))x\(Int(pixelSize.height))"+        ) {+            loaded = await loader?.image(+                namespace: namespace, digest: identity.digest, pixelSize: pixelSize,+                bytes: bytes)+        }+    }+}

diff --git a/Asterism/Asterism/Thumbnails/ThumbnailSource.swift b/Asterism/Asterism/Thumbnails/ThumbnailSource.swiftnew file mode 100644index 0000000..b4e8268--- /dev/null+++ b/Asterism/Asterism/Thumbnails/ThumbnailSource.swift@@ -0,0 +1,28 @@+import Foundation++/// Where a source image came from, for the one sentence a failure owes the+/// reader (Req 3.4).+///+/// The requirement asks the message to **name the origin**, because "that could+/// not be read" says nothing about what to try next: a photo that will not+/// decode and a clipboard that never held an image are different problems with+/// different answers.+nonisolated enum ThumbnailSource: Equatable, Sendable {+    /// The Photos picker, on iPhone and iPad.+    case photos+    /// The file open panel, on the Mac.+    case file+    /// Paste.+    case clipboard+    /// A candidate downloaded from the work's own page (phase 2).+    case page++    var failureMessage: String {+        switch self {+        case .photos: "That photo could not be read as an image."+        case .file: "That file could not be read as an image."+        case .clipboard: "The clipboard does not hold an image."+        case .page: "That page's image could not be read."+        }+    }+}

diff --git a/Asterism/Asterism/UITestLaunchSupport.swift b/Asterism/Asterism/UITestLaunchSupport.swiftindex 9ddaf4b..38081c4 100644--- a/Asterism/Asterism/UITestLaunchSupport.swift+++ b/Asterism/Asterism/UITestLaunchSupport.swift@@ -80,6 +80,19 @@ enum UITestFixtureKind: Equatable {     /// no row holds. `seeded-series` and `seeded-works-options` are left alone:     /// their suites assert exact orders and counts that a credit would move.     case creators+    /// A two-work library the cover surfaces have something to say about+    /// (`work-thumbnails`): one work with a 600x900 cover and an entry, so the+    /// works list, the Recent feed, the work detail header and the editor all+    /// show the same picture, and one work with none, so "this row has no slot"+    /// is a claim about a row in the same list. `seeded-series`,+    /// `seeded-creators` and `seeded-works-options` are left alone: their suites+    /// assert exact orders and counts that a third work would move.+    case coveredWork+    /// The same two works, with the covered one's **bytes** taken back off and+    /// its shape and digest left in place — Req 1.8's tolerated state, which a+    /// per-field sync merge or an asset still in flight produces. Every surface+    /// has to present it as no cover at all, with nothing said (Req 6.4).+    case coveredWorkMissingBytes      /// Whether the seeded shape needs a second open before its diagnoses are     /// complete. `.invalidSiteTuple` is produced only by the full@@ -131,6 +144,10 @@ enum UITestLaunchSupport {     /// The four works, three creators, five roles and six credits the creator     /// journeys run over.     static let seededCreatorsScenario = "seeded-creators"+    /// The covered and uncovered work the cover journeys run over.+    static let seededCoveredWorkScenario = "seeded-covered-work"+    /// The same pair with the cover's bytes absent (Req 1.8, Req 6.4).+    static let seededCoveredWorkMissingBytesScenario = "seeded-covered-work-missing-bytes"     /// One scenario per tolerated state, plus the illegal-tuple state that     /// carries the re-teach route and the empty-library shape Q15 hoists the     /// banner for. Keyed by the fixture's own raw value so a new shape needs no@@ -276,6 +293,71 @@ enum UITestLaunchSupport {     }     #endif +    /// `work-thumbnails`: which scripted cover fetcher this launch runs with.+    /// Absent means the real pipeline, which is what every production launch+    /// uses — and what no UI test may use, because a UI test has no network and+    /// must not have one (design, Testing Strategy).+    static let coverFetchKey = "ASTERISM_UI_TEST_COVER_FETCH"++    #if DEBUG || ASTERISM_PERFORMANCE_TESTING+    /// The cover fetcher this launch's Find cover runs against, or nil when the+    /// launch asked for nothing.+    ///+    /// Gated because `StubCoverFetcher` is: a release binary has no business+    /// carrying a fetcher that answers a work's pages with a canned picture.+    static func coverFetcher(+        environmentProvider: any ProcessEnvironmentProviding = SystemProcessEnvironment()+    ) -> (any CoverFetching)? {+        switch environmentProvider.environment[coverFetchKey] {+        case "canned":+            return StubCoverFetcher(candidateResult: .candidates([cannedCoverCandidate]))+        case "none":+            return StubCoverFetcher(candidateResult: .none)+        case "offline":+            return StubCoverFetcher(candidateResult: .offline)+        case "banner-then-cover":+            // Q85's whole case, scripted: the head offers the site's banner+            // and only Scan page reaches the cover.+            return StubCoverFetcher(+                candidateResult: .candidates([cannedCoverBannerCandidate]),+                pageBodyCandidateResult: .candidates([cannedCoverCandidate]))+        default:+            return nil+        }+    }++    /// The one candidate the canned fetcher offers: a real 600×900 JPEG the+    /// crop step can open and the codec can encode, at the size a cover+    /// actually comes in. Built rather than committed, for Q43's reason.+    ///+    /// A **different band colour** from the seeded work's own cover, so a+    /// journey looking at the editor after a Find cover is looking at a picture+    /// it can tell from the one the fixture started with.+    static let cannedCoverCandidate: CoverCandidate = {+        let bytes = LibraryRepository.coveredWorkThumbnail(band: 0.86).bytes+        return CoverCandidate(+            url: URL(string: "https://\(LibraryRepository.coveredWorkHostname)/covers/lantern.jpg")!,+            hostname: LibraryRepository.coveredWorkHostname,+            pixelSize: CGSize(width: 600, height: 900),+            bytes: bytes,+            preview: bytes)+    }()++    /// The **banner** the head arm offers before the reader taps Scan page+    /// (Q85): landscape, in its own colours, from the same host. Two candidates+    /// a journey can tell apart by shape alone is what makes the Scan page+    /// assertion about the list rather than about a count.+    static let cannedCoverBannerCandidate: CoverCandidate = {+        let bytes = LibraryRepository.coveredWorkBanner()+        return CoverCandidate(+            url: URL(string: "https://\(LibraryRepository.coveredWorkHostname)/banner.jpg")!,+            hostname: LibraryRepository.coveredWorkHostname,+            pixelSize: CGSize(width: 1_280, height: 460),+            bytes: bytes,+            preview: bytes)+    }()+    #endif+     static func request(         environmentProvider: any ProcessEnvironmentProviding = SystemProcessEnvironment(),         temporaryDirectory: URL = FileManager.default.temporaryDirectory@@ -306,6 +388,10 @@ enum UITestLaunchSupport {             fixture = .series         case seededCreatorsScenario:             fixture = .creators+        case seededCoveredWorkScenario:+            fixture = .coveredWork+        case seededCoveredWorkMissingBytesScenario:+            fixture = .coveredWorkMissingBytes         case let scenario where scenario.hasPrefix(seededScaleM4ToleratedPrefix):             guard let state = M4ToleratedFixtureState(                 rawValue: String(scenario.dropFirst(seededScaleM4ToleratedPrefix.count)))

diff --git a/Asterism/Asterism/ViewModels/AppLibraryModel.swift b/Asterism/Asterism/ViewModels/AppLibraryModel.swiftindex 130c6bf..8fe5596 100644--- a/Asterism/Asterism/ViewModels/AppLibraryModel.swift+++ b/Asterism/Asterism/ViewModels/AppLibraryModel.swift@@ -45,6 +45,16 @@ public final class AppLibraryModel {     /// type. Empty until the first refresh completes, which is the same     /// hostnames-only reading every surface had before this feature.     private(set) var siteNames: SiteNames = .empty+    /// The bounded decode cache every surface that draws a cover reads through+    /// (`work-thumbnails` Req 7.2, Q70), handed to the screens as the+    /// environment value `\.thumbnailLoader`.+    ///+    /// One instance for the life of the model, re-pointed at each library that+    /// opens rather than rebuilt: the environment write in `ContentView` names+    /// this property, and a replaced object would leave every view holding the+    /// previous one. It mirrors `snapshotGeneration` below, which is what lets a+    /// slot ask again for bytes that arrived after their record did (Req 1.8).+    let thumbnailLoader = ThumbnailImageCache()     /// How many refresh cycles have completed, bumped once per cycle with the     /// snapshots it publishes (`stats-page` Q27, Q29, Q37).     ///@@ -157,8 +167,8 @@ public final class AppLibraryModel {     /// The resolved configuration after successful bootstrap.     private var resolvedConfiguration: LibraryConfiguration?     private var repository: (any LibraryProviding)?-    /// Retains the concrete repository for backup export (conforms to BackupV12SnapshotProviding).-    private var backupRepository: (any BackupV12SnapshotProviding)?+    /// Retains the concrete repository for backup export (conforms to BackupV13SnapshotProviding).+    private var backupRepository: (any BackupV13SnapshotProviding)?     /// A pre-bootstrap failure used to fail closed on invalid debug launch input.     private let startupFailureMessage: String?     /// Seeds only a fresh, explicit temporary configuration used by UI tests.@@ -274,6 +284,8 @@ public final class AppLibraryModel {         self.resolvedConfiguration = configuration         self.repository = readyRepository         self.state = .ready+        // The bootstrap's `attach` in one line, for a model that never runs one.+        thumbnailLoader.attach(library: readyRepository)     }      /// Constructs a model that can only render an unavailable state.@@ -372,6 +384,10 @@ public final class AppLibraryModel {             }             self.repository = repo             self.backupRepository = repo+            // `work-thumbnails` Q70: the cover loader is the one seam that+            // holds a library reference on behalf of the rows, so it is pointed+            // at the repository that just opened, here, beside them.+            thumbnailLoader.attach(library: repo)             // `rule-suggestion`: the run's suggestion state, built over the             // repository that just opened. Nothing is attempted until an             // activation sweeps or an editor opens.@@ -499,6 +515,11 @@ public final class AppLibraryModel {         // guard below, so a teardown with nothing open still forgets them.         suggestions = nil         characterExtraction = nil+        // `work-thumbnails` Q70: the cover loader holds a reference to the+        // repository being released and a table of images decoded out of it.+        // Both go with it — a disposable UI-test root reuses work ids, so an+        // entry carried across would be another library's picture.+        thumbnailLoader.attach(library: nil)         guard let repository else { return }         await repository.shutdown()         self.repository = nil@@ -981,6 +1002,11 @@ public final class AppLibraryModel {             // options are sorted by the names published beside them.             worksFilterOptions = WorksFilterOptions(works: works.works, siteNames: siteNames)             snapshotGeneration += 1+            // `work-thumbnails` Req 1.8: a slot's load is keyed on this, so a+            // cover whose bytes arrived after its record did is asked for again+            // on the cycle that publishes the arrival — without the identity+            // having changed, which it never does.+            thumbnailLoader.update(generation: snapshotGeneration)             return snapshotGeneration         } catch {             Self.logger.error("Snapshot refresh failed: \(String(describing: error), privacy: .public)")@@ -1023,8 +1049,15 @@ public final class AppLibraryModel {     /// `entryDetailModel`, for the same reason.     public func workDetailModel(for id: UUID) -> WorkDetailModel? {         guard let repo = repository else { return nil }+        #if DEBUG || ASTERISM_PERFORMANCE_TESTING+        let coverFetcher: any CoverFetching =+            UITestLaunchSupport.coverFetcher() ?? CoverCandidateFetcher()+        #else+        let coverFetcher: any CoverFetching = CoverCandidateFetcher()+        #endif         return WorkDetailModel(             workID: id, library: repo, capabilities: capabilities,+            coverFetcher: coverFetcher,             onMutation: { [weak self] in                 await self?.clearConflicts(resolvedBy: id)                 await self?.refreshDiagnosesAndSnapshots()@@ -2083,7 +2116,7 @@ public final class AppLibraryModel {         guard let repo = backupRepository, let config = resolvedConfiguration else { return nil }         let stagingDir = config.rootDirectory             .appending(path: "Library/Caches/BackupExports")-        let exporter = BackupV12Exporter(+        let exporter = BackupV13Exporter(             repository: repo,             stagingDirectory: stagingDir         )@@ -2241,7 +2274,8 @@ public final class AppLibraryModel {                     + "below the light.",                 workStatus: reloaded.workStatus, readingStatus: reloaded.readingStatus,                 verdict: reloaded.verdict,-                membership: reloaded.membership))+                membership: reloaded.membership,+                thumbnail: .keep))         Self.logger.debug("Seeded the character-extraction UI test fixture")     } @@ -2349,7 +2383,8 @@ public final class AppLibraryModel {             draft: WorkMetadataDraft(                 displayTitle: title, typeAssignment: type, genreTags: tags, genericNotes: "",                 workStatus: workStatus, readingStatus: readingStatus, verdict: verdict,-                membership: reloaded.membership))+                membership: reloaded.membership,+                thumbnail: .keep))     }      /// `series-and-related-works`: the smallest library the series screens, the@@ -2454,7 +2489,8 @@ public final class AppLibraryModel {                 genreTags: [], genericNotes: "",                 workStatus: reloaded.workStatus, readingStatus: readingStatus,                 verdict: readingStatus == .abandoned ? "The fog plot went nowhere." : "",-                membership: membership))+                membership: membership,+                thumbnail: .keep))         return work.id     } @@ -2591,7 +2627,8 @@ public final class AppLibraryModel {                 // two mean the same thing on a work that has none, and nil is                 // what every non-editor caller sends (Q85's other side).                 credits: credits.isEmpty-                    ? nil : CreditsDraft(seenRowIDs: [], credits: credits)))+                    ? nil : CreditsDraft(seenRowIDs: [], credits: credits),+                thumbnail: .keep))         return work.id     } @@ -2732,6 +2769,25 @@ public final class AppLibraryModel {             return         } +        if fixture == .coveredWork || fixture == .coveredWorkMissingBytes {+            #if DEBUG || ASTERISM_PERFORMANCE_TESTING+            // `work-thumbnails`: a wholly legal two-work library, seeded in Core+            // through the repository's own write paths — the cover is written by+            // `updateWork`, exactly as the editor writes one. The missing-bytes+            // variant then takes the blob back off, leaving Req 1.8's tolerated+            // tuple for the readers to answer for.+            try await repository.seedCoveredWorkFixture(+                withBytes: fixture == .coveredWork)+            Self.logger.debug("Seeded the covered-work UI test fixture")+            return+            #else+            throw LibraryRepositoryError.invalidInput(+                operation: "preparing UI test fixture",+                reason: "the covered-work fixture requires a debug build"+            )+            #endif+        }+         if fixture == .composed {             // Production opens through the app-role opener, so the composed             // fixture seeds through the ordinary bootstrap, which creates and

diff --git a/Asterism/Asterism/ViewModels/BackgroundExportTriggerModel.swift b/Asterism/Asterism/ViewModels/BackgroundExportTriggerModel.swiftdeleted file mode 100644index 93a9b6a..0000000--- a/Asterism/Asterism/ViewModels/BackgroundExportTriggerModel.swift+++ /dev/null@@ -1,66 +0,0 @@-#if DEBUG-import AsterismCore-import Foundation--/// The `Development`-only control that runs one background export pass on-/// demand (Req 4.2, Q6).-///-/// Grants cannot be exercised on a simulator, and Xcode's simulated launch needs-/// a debugger attached to a running process — so without this the pass could not-/// be checked on a device at all without waiting for iOS to decide to hand one-/// over.-///-/// It calls `AppLibraryModel.runBackgroundExport()`, which is the **same**-/// method the refresh handler calls, so what the button exercises is the pass-/// rather than a copy of it.-///-/// The whole file is behind `#if DEBUG`, which is Q17's gate and the whole of-/// Req 4.2: `DEBUG` is set on the `Development` configuration only, so a-/// `Personal` build has neither this type nor the row that shows it.-///-/// **Not a platform fork**, which the design's prose asked for.-/// `ipad-and-mac-layouts` Req 4.5 keeps every `#if os(` in four named files and-/// `PlatformSeamTests` enforces it, so one here would be a second view layer-/// starting. Nothing is lost: `runBackgroundExport()` is platform-neutral, and a-/// `Development` Mac gets a button that runs the same pass against its resident-/// library. What the Mac has no share of is the *scheduler* (Q16), which lives-/// elsewhere and stays iOS-only.-@MainActor-@Observable-final class BackgroundExportTriggerModel {-    enum State: Equatable {-        case idle-        case running-        /// The outcome, worded. Every sentence this surface shows comes from-        /// here rather than from the view, per `SettingsView`'s convention.-        case finished(String)-    }--    private(set) var state: State = .idle--    /// One pass. Injected rather than reached through the model, so this type-    /// knows nothing about how a library is opened.-    private let pass: () async -> BackgroundExportOutcome--    init(pass: @escaping () async -> BackgroundExportOutcome) {-        self.pass = pass-    }--    /// Runs one pass and reports what it did.-    ///-    /// A second tap while one is in flight does nothing: `runBackgroundExport()`-    /// would join the pass already running, and two rows reporting one pass is-    /// two claims about it.-    func run() async {-        guard state != .running else { return }-        state = .running-        state = .finished(Self.sentence(for: await pass()))-    }--    /// The pass's own vocabulary (Req 4.1) — the same words the Console record-    /// carries, so a developer reading one recognises the other.-    static func sentence(for outcome: BackgroundExportOutcome) -> String {-        "Last pass: \(outcome.logDescription)"-    }-}-#endif

diff --git a/Asterism/Asterism/ViewModels/DebugActionTriggerModel.swift b/Asterism/Asterism/ViewModels/DebugActionTriggerModel.swiftnew file mode 100644index 0000000..fcfe6ab--- /dev/null+++ b/Asterism/Asterism/ViewModels/DebugActionTriggerModel.swift@@ -0,0 +1,58 @@+#if DEBUG+import Foundation++/// The state machine behind a `Development`-only Settings action: run it, say it+/// is running, then say what it did.+///+/// Two rows were two copies of this — the background-export trigger (Req 4.2,+/// Q6 of `specs/background-export/`) and the thumbnail store probe+/// (`work-thumbnails` Req 7.3, Q42, Q67). Both hold three states, both refuse a+/// second tap while one is in flight, and both word their outcome here rather+/// than in the view, which is `SettingsView`'s convention. What differed between+/// them was the action and the sentence, and both of those are arguments.+///+/// The whole file is behind `#if DEBUG`, which is Q17's gate: `DEBUG` is set on+/// the `Development` configuration only, so a `Personal` build has neither this+/// type nor the rows that show it.+///+/// **Not a platform fork**, which the background-export design's prose asked+/// for. `ipad-and-mac-layouts` Req 4.5 keeps every `#if os(` in four named files+/// and `PlatformSeamTests` enforces it, so one here would be a second view layer+/// starting. Nothing is lost: both actions are platform-neutral, and a+/// `Development` Mac gets a button that runs the same pass against its resident+/// library. What the Mac has no share of is the background *scheduler* (Q16),+/// which lives elsewhere and stays iOS-only.+@MainActor+@Observable+final class DebugActionTriggerModel {+    enum State: Equatable {+        case idle+        case running+        /// The outcome, worded. Every sentence the row shows comes from here.+        case finished(String)+    }++    private(set) var state: State = .idle++    /// The action, and its own account of what it did. Injected rather than+    /// reached through a model, so this type knows nothing about how a library+    /// is opened or how a probe is built — and a test can stand one in without+    /// either.+    private let action: () async -> String++    init(action: @escaping () async -> String) {+        self.action = action+    }++    /// Runs the action once and reports what it did.+    ///+    /// A second tap while one is in flight does nothing: the background export+    /// would join the pass already running, and two rows reporting one pass is+    /// two claims about it.+    func run() async {+        guard state != .running else { return }+        state = .running+        state = .finished(await action())+    }+}+#endif

diff --git a/Asterism/Asterism/ViewModels/SeriesModels.swift b/Asterism/Asterism/ViewModels/SeriesModels.swiftindex 4acc4ac..47e2af2 100644--- a/Asterism/Asterism/ViewModels/SeriesModels.swift+++ b/Asterism/Asterism/ViewModels/SeriesModels.swift@@ -600,7 +600,8 @@ public final class SeriesDetailModel {                     workStatus: work.workStatus,                     readingStatus: work.readingStatus,                     verdict: work.verdict,-                    membership: membership))+                    membership: membership,+                    thumbnail: .keep))             if case .conflict(let conflict) = outcome {                 message = EntryDetailModel.conflictMessage(conflict)                 return false

diff --git a/Asterism/Asterism/ViewModels/SettingsBackupImportModel.swift b/Asterism/Asterism/ViewModels/SettingsBackupImportModel.swiftindex 2bed2d4..2e1535a 100644--- a/Asterism/Asterism/ViewModels/SettingsBackupImportModel.swift+++ b/Asterism/Asterism/ViewModels/SettingsBackupImportModel.swift@@ -113,12 +113,32 @@ public final class SettingsBackupImportModel {         case readyToImport(preview: Preview)         /// Committing.         case committing-        /// Import completed successfully.-        case completed(LibraryRecordCounts)+        /// Import completed successfully. The report is what the import could+        /// not take whole — empty in the ordinary case+        /// (`work-thumbnails` Q62).+        case completed(LibraryRecordCounts, report: BackupImportReport)         /// An error occurred.         case failed(message: String)     } +    /// Req 8.4's line, drawn under the counts on the completed screen, or nil+    /// when there is nothing to say — which is every ordinary import.+    ///+    /// It is **not** an error: the import succeeded and those works are in the+    /// library, without the cover the archive's copy claimed. Naming them is the+    /// whole point (Q14): a reader cannot edit an archive, so the only thing+    /// left to tell them is which works to re-pick a cover for.+    public static func droppedCoversMessage(_ report: BackupImportReport) -> String? {+        let titles = report.droppedThumbnails+        guard !titles.isEmpty else { return nil }+        let listed = titles.map { "“\($0)”" }.joined(separator: ", ")+        return titles.count == 1+            ? "One work came back without its cover, because the backup's copy would not "+                + "open: \(listed). Pick a new one in its editor."+            : "\(titles.count) works came back without their covers, because the backup's "+                + "copies would not open: \(listed). Pick new ones in their editors."+    }+     public struct Preview: Equatable, Sendable {         public let metadata: BackupImportMetadata         public let importCounts: LibraryRecordCounts@@ -207,9 +227,9 @@ public final class SettingsBackupImportModel {             let result = try await committer.confirmImport(                 plan: plan, archiveName: currentArchiveName)             switch result {-            case .committed(let counts):+            case .committed(let counts, let report):                 Self.logger.debug("Settings import: committed")-                state = .completed(counts)+                state = .completed(counts, report: report)                 // A refresh, not a re-bootstrap: the import ran on the live                 // container, so there is no second graph to go and open — and                 // re-opening under mirroring constructs a second live mirrored

diff --git a/Asterism/Asterism/ViewModels/SettingsBackupModel.swift b/Asterism/Asterism/ViewModels/SettingsBackupModel.swiftindex 8698d7d..5de502f 100644--- a/Asterism/Asterism/ViewModels/SettingsBackupModel.swift+++ b/Asterism/Asterism/ViewModels/SettingsBackupModel.swift@@ -5,20 +5,20 @@ import OSLog // MARK: - Backup Exporting Protocol  /// Test seam abstracting the exporter's operations needed by the Settings-/// surface. Conforms `BackupV12Exporter` to this protocol via extension below.+/// surface. Conforms `BackupV13Exporter` to this protocol via extension below. ///-/// Settings exports 12/13 (`place-extraction` Req 5.1): the archive+/// Settings exports 13/14 (`work-thumbnails` Req 8.1): the archive /// carries the reader's named places and their suppressions, a Work's site /// memberships, the reader's dismissed pairs, citations that name a rule by UUID /// alone, and the Work's two statuses and verdict. It is also the only format /// the app reads, so there is one exporter and one importer. public protocol BackupExporting: Sendable {-    func export(metadata: BackupV12Metadata) async throws -> BackupExportResult+    func export(metadata: BackupV13Metadata) async throws -> BackupExportResult     func cleanup(_ result: BackupExportResult)     func scavengeStaleFiles() } -extension BackupV12Exporter: BackupExporting {}+extension BackupV13Exporter: BackupExporting {}  // MARK: - Settings Backup View Model @@ -79,7 +79,7 @@ public final class SettingsBackupModel {         currentResult = nil          do {-            let metadata = BackupV12Metadata(+            let metadata = BackupV13Metadata(                 appBuild: Self.currentAppBuild(),                 exportedAt: Date()             )@@ -92,7 +92,7 @@ public final class SettingsBackupModel {             state = .failed             // Privacy-safe: log only the error category, never user content             errorMessage = Self.privacySafeMessage(for: error)-            if let exportError = error as? BackupV12ExportError,+            if let exportError = error as? BackupV13ExportError,                case .tornGroups = exportError {                 routesToCheckLibrary = true             }@@ -140,7 +140,7 @@ public final class SettingsBackupModel {         switch error {         case is BackupCodecError:             "Backup export failed due to an encoding error. Please try again."-        case let error as BackupV12ExportError:+        case let error as BackupV13ExportError:             exportMessage(for: error)         default:             "Backup export failed. Please try again."@@ -155,21 +155,36 @@ public final class SettingsBackupModel {     /// nothing throws is a dead requirement (Q100). It now does, and it carries     /// exactly the two things the requirement asks for.     ///-    /// **Two arms, not three** (Decision 14). The deleted one directed the-    /// reader to retry while something settled; no such state can block an-    /// export, because a torn group is divergent by definition and a divergent-    /// set never resolves without the reader.+    /// **Two arms, not three** (`duplicate-reconciliation` Decision 14). The+    /// deleted one directed the reader to retry while something settled; no+    /// such state can block an export, because a torn group is divergent by+    /// definition and a divergent set never resolves without the reader.     ///     /// The `tornGroups` arm now also covers a torn **character** group     /// (`character-extraction` Req 6.5, Q105). It needs no new sentence: the     /// payload carries a count and a route, not a record kind, and Check Library     /// is where every torn group is resolved.-    private static func exportMessage(for error: BackupV12ExportError) -> String {+    private static func exportMessage(for error: BackupV13ExportError) -> String {         switch error {         case .tornGroups(let payload):             tornGroupsMessage(payload)         case .referencesStillArriving:             "Some records are still arriving from iCloud. Try again once syncing has settled."+        // `work-thumbnails` Req 8.3 and Q14, and the one place this surface+        // names a record. The generic sentence below is the right one for a+        // status raw a newer build wrote — there is nothing the reader can do+        // about it — but a cover is theirs to remove, and a refusal they cannot+        // act on is the dead end `duplicate-reconciliation` Decision 14 removed+        // the third arm over. Q14 is why this refuses rather than dropping the+        // cover silently: on export the reader has an escape. So the work's+        // title is shown, on the reader's own device, in the one message whose+        // whole purpose is to send them to that work. Nothing else about the+        // record travels: not the bytes, not the digest, not the shape.+        case .unrepresentableValue(let record, let field, _)+        where field == BackupV13ExportError.thumbnailField:+            "\(record) has a cover this backup cannot carry. Remove the cover in the work's "+                + "editor and export again — or, if the work is flagged as a duplicate, "+                + "resolve it first and the cover you keep will be backed up."         case .unrepresentableValue:             "A record holds something this backup format cannot represent. It was probably "                 + "written by a newer version of Asterism."@@ -200,16 +215,35 @@ public final class SettingsBackupModel {     }      /// Returns a short diagnostic category for structured logging (never includes user data).-    private static func diagnosticCategory(for error: Error) -> String {+    internal static func diagnosticCategory(for error: Error) -> String {         switch error {         case let e as BackupCodecError:             "codec: \(e)"-        case let e as BackupV12ExportError:-            "export: \(e)"+        case let e as BackupV13ExportError:+            exportDiagnosticCategory(e)         case let e as LibraryRepositoryError:             "repository: \(e)"         default:             "unknown: \(type(of: error))"         }     }++    /// The export refusals, by **category** rather than by message.+    ///+    /// `BackupV13ExportError.description` is written for the reader and names+    /// the record: `Work “<title>”` for a cover (`work-thumbnails` Req 8.3) and+    /// `Site <hostname>` for an unrepresentable site mode. The line above is+    /// logged `privacy: .public`, so interpolating that description would put a+    /// work's title, or the reader's reading habits by hostname, into a log any+    /// process on the device can read. The refusal that names a record+    /// therefore logs its **field** — a compile-time constant — and the reader+    /// gets the title on screen, where it belongs.+    private static func exportDiagnosticCategory(_ error: BackupV13ExportError) -> String {+        switch error {+        case .unrepresentableValue(_, let field, _):+            "export: unrepresentable \(field)"+        default:+            "export: \(error)"+        }+    } }

diff --git a/Asterism/Asterism/ViewModels/WorkDetailModel.swift b/Asterism/Asterism/ViewModels/WorkDetailModel.swiftindex c76737e..e557d55 100644--- a/Asterism/Asterism/ViewModels/WorkDetailModel.swift+++ b/Asterism/Asterism/ViewModels/WorkDetailModel.swift@@ -1,7 +1,9 @@ import AsterismCore+import CoreGraphics import Foundation import Observation import OSLog+import UniformTypeIdentifiers  @MainActor @Observable public final class WorkDetailModel {@@ -370,13 +372,20 @@ public final class WorkDetailModel {         }     } -    private let workID: UUID+    /// The work this screen is about. Readable because the Cover field draws a+    /// `.stored` cover through the shared loader, which is keyed by work id+    /// (`work-thumbnails` Req 7.2).+    let workID: UUID     private let library: any LibraryProviding     /// The locale a position is read and written in (Reqs 2.2, 2.7). Taken at     /// construction, as `SeriesDetailModel` and `MarkdownExportModel` take     /// theirs.     private let locale: Locale     private let capabilities: AsterismCapabilities+    /// Find cover's and the paste branch's outbound requests, injected so that+    /// neither this model's unit suite nor a UI-test launch ever touches a+    /// network (`work-thumbnails` Req 4.1, design Testing Strategy).+    private let coverFetcher: any CoverFetching     private let onMutation: @Sendable () async -> Void     /// Where a refused write goes (Req 2.10, Q47): the draft stays here, the     /// conflict goes to the model that owns the banner and the listing.@@ -388,6 +397,10 @@ public final class WorkDetailModel {         library: any LibraryProviding,         locale: Locale = .current,         capabilities: AsterismCapabilities = .current,+        /// Find cover and the paste-URL branch's one seam+        /// (`work-thumbnails` Req 4.1). Defaulted to the real pipeline, so only+        /// a test or a UI-test launch ever states it.+        coverFetcher: any CoverFetching = CoverCandidateFetcher(),         onMutation: @escaping @Sendable () async -> Void,         onConflict: @escaping @Sendable (WriteConflict) async -> Void = { _ in }     ) {@@ -395,6 +408,7 @@ public final class WorkDetailModel {         self.library = library         self.locale = locale         self.capabilities = capabilities+        self.coverFetcher = coverFetcher         self.onMutation = onMutation         self.onConflict = onConflict     }@@ -409,6 +423,7 @@ public final class WorkDetailModel {             // shows.             (presentation, chapterRowsByChapter) = (detail, Self.chapterOrder(detail.chapterRows))             let snapshot = detail.work+            coverFetchPages = Self.coverFetchPages(of: snapshot)             removableHostnames = Self.removableHostnames(of: snapshot)             draftTitle = snapshot.displayTitle             draftAssignment = snapshot.typeDisplay.assignment@@ -418,6 +433,11 @@ public final class WorkDetailModel {             draftWorkStatus = snapshot.workStatus             draftReadingStatus = snapshot.readingStatus             draftVerdict = snapshot.verdict+            // `work-thumbnails`: the cover draft is reassigned **only outside+            // edit mode**. A reload while the editor is open — the one a record+            // step's commit runs — would otherwise throw away a crop the reader+            // has confirmed but not yet saved, which is the only copy of itself.+            if !isEditing { restoreThumbnailDraft(from: snapshot) }             autoRevertedReading = false             restoreSeriesDraftFromSnapshot()             seriesOptions = await seriesPickerOptions(carrying: snapshot.series)@@ -857,6 +877,540 @@ public final class WorkDetailModel {             })     } +    // MARK: - The cover draft (`work-thumbnails` Reqs 2.1–2.5, 3.4, 3.5, 3.7)++    /// What the editor is holding about the work's cover.+    ///+    /// Three states, and the middle one is the reason there are three: the+    /// editor **never holds the stored bytes**, so "leave it exactly as it is"+    /// has to be sayable without them. That is what maps to `ThumbnailWrite`'s+    /// `.keep`, and what keeps an unrelated save from reading a single byte of+    /// cover (Q37, Q49).+    enum ThumbnailDraftState: Equatable {+        /// No cover, on a work that had none — or one the reader has removed.+        case none+        /// The saved cover, untouched. Its identity only; never its bytes.+        case stored(ThumbnailIdentity)+        /// A new crop waiting for Save (Req 2.2).+        case replaced(ThumbnailDraft)++        var identity: ThumbnailIdentity? {+            switch self {+            case .none: nil+            case .stored(let identity): identity+            case .replaced(let draft): draft.identity+            }+        }+    }++    /// The draft. `private(set)`: every change goes through one of the four+    /// methods below, because each of them also has a session token to retire+    /// or a message to clear.+    private(set) var draftThumbnail: ThumbnailDraftState = .none++    /// What the draft is compared against — seeded from the snapshot, restored+    /// by a cancel, and the thing a Save's `.clear` is decided by. Stored rather+    /// than derived from `work`, so the fallback edit basis still has an answer+    /// on a screen whose read failed after edit mode was entered.+    private(set) var thumbnailBaseline: ThumbnailDraftState = .none++    /// The decoded preview of a `.replaced` draft, so the Cover field does not+    /// re-decode a 600×900 JPEG on every body pass. A `.stored` cover is drawn+    /// through the shared loader instead, like every other surface.+    private(set) var draftThumbnailPreview: CGImage?++    /// Req 3.7. Retired on a cancel, on an abandoned pick and on every new pick,+    /// so a picker result, download or decode that lands after the reader has+    /// moved on carries a token this no longer holds and is dropped.+    private(set) var thumbnailSessionToken = UUID()++    /// Req 3.4's one sentence, naming where the image that would not decode came+    /// from. Not `errorMessage`: nothing failed about the record, and the+    /// editor's message row is for refusals of writes.+    private(set) var thumbnailMessage: String?++    /// The source image waiting for the crop step, or nil when none is+    /// (Req 3.5). Presented with `.sheet(item:)`.+    private(set) var pendingCrop: ThumbnailCropSource?++    /// Req 2.1's spoken value for the Cover menu.+    var coverAccessibilityValue: String {+        ThumbnailPresentation.accessibilityValue(draftThumbnail.identity?.shape)+    }++    /// Req 2.1: Remove is offered whenever the draft has a cover — **including**+    /// one whose bytes will not decode, which is exactly why `.stored` needs no+    /// bytes to exist.+    var offersThumbnailRemoval: Bool { draftThumbnail != .none }++    /// Whether the cover half of the draft differs from what the read holds.+    var hasUnsavedThumbnailChange: Bool { draftThumbnail != thumbnailBaseline }++    /// Opens a pick. Retires the previous session, so a picker still resolving+    /// from an abandoned one can no longer reach the draft (Req 3.7).+    @discardableResult+    func beginThumbnailPick() -> UUID {+        thumbnailMessage = nil+        pendingCrop = nil+        thumbnailSessionToken = UUID()+        return thumbnailSessionToken+    }++    /// The reader backed out of the picker. Same retirement, no message: nothing+    /// went wrong.+    func cancelThumbnailPick() {+        pendingCrop = nil+        pendingCoverPick = nil+        thumbnailSessionToken = UUID()+    }++    /// A picked, pasted or fetched image, on its way to the crop step (Req 3.5).+    ///+    /// A stale token is dropped silently (Req 3.7); an undecodable image gets+    /// the one sentence its origin owes and **leaves the draft exactly as it+    /// was** (Req 3.4).+    func acceptPickedImage(_ data: Data, token: UUID, source: ThumbnailSource) {+        guard token == thumbnailSessionToken else { return }+        guard let image = ThumbnailCodec.workingImage(from: data) else {+            thumbnailMessage = source.failureMessage+            return+        }+        thumbnailMessage = nil+        pendingCrop = ThumbnailCropSource(id: token, image: image)+    }++    /// The crop step confirmed. The encoded draft goes into the draft and+    /// **nowhere else** until Save (Req 2.2).+    ///+    /// The draft itself is assigned synchronously, before the first suspension:+    /// the reader has confirmed, and the checkmark must be raised whether or not+    /// the field's preview ever decodes. What is awaited is only the picture the+    /// Cover field wears, decoded **off the main actor** — the second full image+    /// pass of one tap, and there is no reason for it to be on the actor the+    /// sheet dismisses on.+    ///+    /// Req 3.7 is re-checked after the await: a decode that lands after the+    /// reader has cancelled or picked again may not draw over what replaced it.+    func acceptCroppedThumbnail(_ draft: ThumbnailDraft, token: UUID) async {+        guard token == thumbnailSessionToken else { return }+        pendingCrop = nil+        thumbnailMessage = nil+        draftThumbnail = .replaced(draft)+        draftThumbnailPreview = nil++        let bytes = draft.bytes+        let decoded = await Task.detached(priority: .userInitiated) {+            ThumbnailCodec.previewImage(from: bytes).map(DecodedThumbnail.init)+        }.value+        guard token == thumbnailSessionToken else { return }+        draftThumbnailPreview = decoded?.image+    }++    /// Req 5.4: the draft is whatever it was before the step began.+    func cancelCrop() {+        pendingCrop = nil+        pendingCoverPick = nil+        thumbnailSessionToken = UUID()+    }++    /// Req 2.1's Remove. A draft change like any other — nothing is written+    /// until Save, and Save writes `.clear` only where the baseline had a cover.+    func removeThumbnail() {+        guard draftThumbnail != .none else { return }+        pendingCrop = nil+        thumbnailMessage = nil+        draftThumbnail = .none+        draftThumbnailPreview = nil+        pendingCoverPick = nil+        thumbnailSessionToken = UUID()+    }++    func clearThumbnailMessage() {+        thumbnailMessage = nil+    }++    /// Req 3.3's paste, as `PasteButton` delivers it.+    ///+    /// The first payload that carries image bytes wins and goes to the crop+    /// step. Failing that the payloads are searched for a link — as a URL, or+    /// inside text, which is how a page copied out of Safari usually arrives —+    /// and the link takes the one-request branch of Q22 and Q26. Only a+    /// clipboard holding neither is refused outright.+    func acceptPastedProviders(_ providers: [NSItemProvider], token: UUID) async {+        guard token == thumbnailSessionToken else { return }+        for provider in providers {+            guard+                let typeIdentifier = provider.registeredTypeIdentifiers.first(where: {+                    UTType($0)?.conforms(to: .image) == true+                }),+                let data = await imageData(from: provider, typeIdentifier: typeIdentifier)+            else { continue }+            acceptPickedImage(data, token: token, source: .clipboard)+            return+        }+        guard token == thumbnailSessionToken else { return }+        if let link = await pastedLink(in: providers) {+            await fetchPastedCoverURL(link, token: token)+            return+        }+        guard token == thumbnailSessionToken else { return }+        thumbnailMessage = ThumbnailSource.clipboard.failureMessage+    }++    private func imageData(+        from provider: NSItemProvider, typeIdentifier: String+    ) async -> Data? {+        await withCheckedContinuation { continuation in+            provider.loadDataRepresentation(forTypeIdentifier: typeIdentifier) { data, _ in+                continuation.resume(returning: data)+            }+        }+    }++    /// The first `http(s)` link any payload carries, whether it arrived as a URL+    /// or as text around one.+    ///+    /// Through `SharePayloadExtractor.firstHTTPURL`, made public for this+    /// (Req 3.3): a shared note and a pasted note should not disagree about+    /// where the link in a paragraph starts.+    private func pastedLink(in providers: [NSItemProvider]) async -> String? {+        for provider in providers {+            for identifier in provider.registeredTypeIdentifiers {+                guard let type = UTType(identifier),+                      type.conforms(to: .url) || type.conforms(to: .text) else { continue }+                guard let text = await pastedText(from: provider, typeIdentifier: identifier),+                      let link = SharePayloadExtractor.firstHTTPURL(in: text) else { continue }+                return link+            }+        }+        return nil+    }++    /// One payload as text. `loadItem` rather than `loadDataRepresentation`,+    /// because a `public.url` payload arrives as a `URL` or an `NSString` as+    /// often as it arrives as bytes, and all three say the same thing.+    private func pastedText(+        from provider: NSItemProvider, typeIdentifier: String+    ) async -> String? {+        await withCheckedContinuation { continuation in+            provider.loadItem(forTypeIdentifier: typeIdentifier) { item, _ in+                switch item {+                case let url as URL: continuation.resume(returning: url.absoluteString)+                case let string as String: continuation.resume(returning: string)+                case let data as Data:+                    continuation.resume(returning: String(data: data, encoding: .utf8))+                default: continuation.resume(returning: nil)+                }+            }+        }+    }++    // MARK: - Find cover (`work-thumbnails` Reqs 3.1, 3.3, 4.1–4.12)++    /// What the candidate sheet has to show.+    ///+    /// `none` and `offline` are two different sentences rather than one error+    /// (Req 4.8, Req 4.9): a page that offered no cover is an ordinary outcome+    /// and has nothing to do with the library.+    enum CoverCandidateSheetState: Equatable {+        case loading+        case candidates([CoverCandidate])+        case none+        case offline+    }++    private(set) var coverCandidateState: CoverCandidateSheetState = .loading+    private(set) var isPresentingCoverCandidates = false++    /// Whether the reader has asked this run to read the pages' bodies+    /// (Req 4.15). It is what hides Scan page afterwards: there is nothing more+    /// to scan, and a second tap would re-fetch the same pages for the same+    /// answer.+    ///+    /// A body arm that fired **automatically** does not set it. That decision+    /// is made per page inside the fetcher — a page whose head declared nothing+    /// falls through on its own (Req 4.14) — while this sheet is one run over+    /// up to three pages, and the model has no per-page answer to offer.+    private(set) var coverScanIncludedPageBody = false++    /// The pasted page this run is showing candidates for, kept so that Scan+    /// page can re-run **that** page rather than the work's own (Req 4.16).+    /// Nil for an ordinary Find cover, whose pages are `coverFetchPages`.+    private var pendingCoverPage: FetchedPageMetadata?++    /// Req 4.15: whether the sheet draws the action at all.+    ///+    /// Two conditions, both here rather than one here and one in the sheet: the+    /// reader has already made a body run and there is nothing left to scan, or+    /// a run is in flight and a second one must not be started from it. "When+    /// the action is available" is one rule and reads as one.+    var offersCoverPageScan: Bool {+        !coverScanIncludedPageBody && coverCandidateState != .loading+    }++    /// The candidate the reader chose, held between the sheet closing and its+    /// `onDismiss`. Nothing presents from inside another sheet's closure+    /// (Q101 of `duplicate-reconciliation`), so the pick waits here for one+    /// turn and the crop step is raised after the candidate sheet has gone.+    private var pendingCoverPick: Data?++    /// The one fetch the editor owns. Cancelled by dismissing the sheet, by+    /// leaving edit mode and by leaving the page (Req 4.11) — three doors, one+    /// handle, because a fetch that outlived any of them would be a request the+    /// reader has no way to see or stop.+    /// Readable rather than private so the suite can await the run it started+    /// instead of polling for its effect — the run is the thing under test.+    @ObservationIgnored private(set) var coverFetchTask: Task<Void, Never>?++    /// Req 3.3's refusal for a pasted link that answered with neither a page nor+    /// an image, or did not answer at all.+    static let pastedCoverURLRefusal = "That link did not give a page or an image."++    /// Whether a pasted link is being fetched right now.+    ///+    /// The paste branch is the one request with **nothing on screen in front of+    /// it**: Find cover raises the candidate sheet before it starts and the crop+    /// step draws its own spinner, but a pasted URL is one bounded request that+    /// can take the full 5 s with the menu already dismissed. Without this the+    /// Cover field sits unchanged for that whole time and a reader's only+    /// reading of it is that the paste did nothing.+    ///+    /// Cleared on every outcome — the crop step, the candidate sheet, a refusal,+    /// a cancellation — because each of those is something the reader can see in+    /// its own right.+    private(set) var isFetchingPastedCoverURL = false++    /// Req 4.1's pages: each membership's work URL in membership order, at most+    /// three; failing that, the URL of the most recently shared entry.+    ///+    /// Through `BoundedCoverFetcher.requestURL` rather than `URL(string:)`, so+    /// what this returns is what will actually be requested — `https`, with an+    /// `http` page upgraded (Q27) and anything that is neither dropped.+    /// Stored rather than computed: it is read on every body pass of the Cover+    /// field (through `offersFindCover`), and it parses up to three URLs each+    /// time. It is a function of the snapshot, so it is derived where the+    /// snapshot lands.+    private(set) var coverFetchPages: [URL] = []++    private static func coverFetchPages(of work: WorkSnapshot) -> [URL] {+        let fromMemberships = work.memberships+            .compactMap(\.workURLString)+            .compactMap(BoundedCoverFetcher.requestURL(from:))+        if !fromMemberships.isEmpty {+            return Array(fromMemberships.prefix(CoverCandidateFetcher.maxPages))+        }+        // Q28: `lastSharedAt` is what Recent orders by, and the id breaks a tie+        // so that two devices reading the same library pick the same page.+        let newest = work.entries.max { lhs, rhs in+            (lhs.lastSharedAt, lhs.id.uuidString) < (rhs.lastSharedAt, rhs.id.uuidString)+        }+        return [newest?.rawURLString]+            .compactMap { $0 }+            .compactMap(BoundedCoverFetcher.requestURL(from:))+    }++    /// Req 4.2: the menu item is **absent**, not failing, when there is nothing+    /// to fetch.+    var offersFindCover: Bool { !coverFetchPages.isEmpty }++    /// Opens the candidate sheet and starts the run behind it (Req 3.1).+    func beginFindCover() {+        let pages = coverFetchPages+        guard !pages.isEmpty else { return }+        let token = beginThumbnailPick()+        pendingCoverPick = nil+        pendingCoverPage = nil+        coverScanIncludedPageBody = false+        coverCandidateState = .loading+        isPresentingCoverCandidates = true+        let fetcher = coverFetcher+        let title = work?.displayTitle+        startCoverFetch { [weak self] in+            let result = await fetcher.fetch(+                pages: pages, workTitle: title, includingPageBody: false)+            guard !Task.isCancelled else { return }+            self?.publishCoverCandidates(result, token: token)+        }+    }++    /// Req 4.15's Scan page: the same pages again, with the body arm on for+    /// every one of them, replacing the list the sheet is showing.+    ///+    /// On the same session token and through the same `coverFetchTask`, so+    /// Req 4.11's three doors still close it, and nothing about the draft moves+    /// — this is a read-only projection like the run that preceded it+    /// (Req 4.12).+    func rescanPagesIncludingBody() {+        guard isPresentingCoverCandidates, !coverScanIncludedPageBody else { return }+        let fetcher = coverFetcher+        let title = work?.displayTitle++        // Req 4.16: a pasted page is re-scanned as itself, without a second+        // request for it; an ordinary run goes back to the work's own pages.+        // Which run it is, is the only thing that differs — what happens+        // around it is stated once, below.+        let run: @Sendable () async -> CoverCandidateResult+        if let page = pendingCoverPage {+            run = { await fetcher.fetch(fetchedPage: page, includingPageBody: true) }+        } else {+            let pages = coverFetchPages+            guard !pages.isEmpty else { return }+            run = {+                await fetcher.fetch(pages: pages, workTitle: title, includingPageBody: true)+            }+        }++        let token = thumbnailSessionToken+        coverScanIncludedPageBody = true+        coverCandidateState = .loading+        startCoverFetch { [weak self] in+            let result = await run()+            guard !Task.isCancelled else { return }+            self?.publishCoverCandidates(result, token: token)+        }+    }++    /// Req 4.11. The same call serves the sheet's own dismissal, `cancelEditing`+    /// and the page's `onDisappear`: whichever of them happens first, the+    /// requests stop.+    func cancelCoverFetch() {+        coverFetchTask?.cancel()+        coverFetchTask = nil+        isPresentingCoverCandidates = false+        // Cleared here as well as in the run's own `defer`: a cancelled request+        // still has to unwind, and the reader who cancelled it should not be+        // left watching a spinner for something nobody is waiting on.+        isFetchingPastedCoverURL = false+        // And the downloads go with the sheet. Eight candidates of up to 4 MB+        // each, plus their previews, is tens of megabytes the editor was still+        // holding after the sheet had closed — until the reader left the work+        // entirely. `.loading` is where a fresh run starts anyway.+        //+        // **`pendingCoverPick` is deliberately not cleared here.** This method+        // is the sheet's dismissal handler as well as its cancel, so the pick+        // that is on its way to `presentChosenCover()` passes straight through+        // it. It is retired with the session instead — every place that mints a+        // new `thumbnailSessionToken` drops it — which is where an abandoned+        // pick really dies.+        coverCandidateState = .loading+    }++    /// Req 4.7: the pick closes the sheet and the crop step follows from its+    /// dismissal, never from inside its closure.+    ///+    /// The candidate is a value the caller holds, so its bytes survive+    /// `cancelCoverFetch()` releasing the rest of the list.+    func chooseCoverCandidate(_ candidate: CoverCandidate) {+        guard isPresentingCoverCandidates else { return }+        pendingCoverPick = candidate.bytes+        cancelCoverFetch()+    }++    /// Called from the candidate sheet's `onDismiss`. A dismissal that chose+    /// nothing leaves everything as it was (Req 4.8).+    func presentChosenCover() {+        guard let bytes = pendingCoverPick else { return }+        pendingCoverPick = nil+        acceptPickedImage(bytes, token: thumbnailSessionToken, source: .page)+    }++    private func startCoverFetch(_ run: @escaping @MainActor () async -> Void) {+        coverFetchTask?.cancel()+        coverFetchTask = Task { await run() }+    }++    private func publishCoverCandidates(_ result: CoverCandidateResult, token: UUID) {+        guard token == thumbnailSessionToken, isPresentingCoverCandidates else { return }+        switch result {+        case .candidates(let candidates):+            coverCandidateState = candidates.isEmpty ? .none : .candidates(candidates)+        case .none:+            coverCandidateState = .none+        case .offline:+            coverCandidateState = .offline+        }+    }++    /// Q22 and Q26: **one** request for a pasted link, branched on what came+    /// back. HTML continues as a Find cover page without a second request, an+    /// image goes straight to the crop step, anything else is refused.+    private func fetchPastedCoverURL(_ url: String, token: UUID) async {+        thumbnailMessage = nil+        isFetchingPastedCoverURL = true+        pendingCoverPage = nil+        coverScanIncludedPageBody = false+        let fetcher = coverFetcher+        let title = work?.displayTitle+        startCoverFetch { [weak self] in+            // The backstop for every way out of the block below, cancellation+            // included. The `.page` branch clears it earlier, on its own line.+            defer { self?.isFetchingPastedCoverURL = false }+            do {+                let outcome = try await fetcher.fetch(url: url, workTitle: title)+                guard !Task.isCancelled, let self else { return }+                switch outcome {+                case .image(let download):+                    acceptPickedImage(download.data, token: token, source: .page)+                case .page(let metadata):+                    guard token == thumbnailSessionToken else { return }+                    coverCandidateState = .loading+                    isPresentingCoverCandidates = true+                    // Kept so Scan page can re-run this page rather than the+                    // work's own, and without asking for it twice (Req 4.16).+                    pendingCoverPage = metadata+                    // The sheet is up and says `Looking for a cover…` itself, so+                    // the field's row has nothing left to add.+                    isFetchingPastedCoverURL = false+                    let result = await fetcher.fetch(+                        fetchedPage: metadata, includingPageBody: false)+                    guard !Task.isCancelled else { return }+                    publishCoverCandidates(result, token: token)+                case .refused:+                    refusePastedCoverURL(token: token)+                }+            } catch is CancellationError {+                // The reader left; there is nothing to say about it.+            } catch {+                self?.refusePastedCoverURL(token: token)+            }+        }+        await coverFetchTask?.value+    }++    private func refusePastedCoverURL(token: UUID) {+        guard token == thumbnailSessionToken else { return }+        thumbnailMessage = Self.pastedCoverURLRefusal+    }++    /// Takes the cover half of the draft back to the snapshot's, and retires the+    /// session with it. Called from the load and from the cancel.+    private func restoreThumbnailDraft(from snapshot: WorkSnapshot?) {+        thumbnailBaseline = snapshot?.thumbnail.map { .stored($0) } ?? .none+        draftThumbnail = thumbnailBaseline+        draftThumbnailPreview = nil+        pendingCrop = nil+        // Every token retirement drops an unconsumed pick with it: a pick+        // belongs to the session that made it, and this is the one a cancel or+        // a reload goes through.+        pendingCoverPick = nil+        thumbnailMessage = nil+        thumbnailSessionToken = UUID()+    }++    /// Q49: what a Save does to the three columns.+    ///+    /// `.stored` is `.keep` — the editor has no bytes to write and the stored+    /// tuple is already right. `.none` is `.clear` only where the baseline had a+    /// cover; on a work that never had one it is `.keep`, so an ordinary save of+    /// an uncovered work writes nothing about covers at all.+    private var thumbnailWrite: ThumbnailWrite {+        switch draftThumbnail {+        case .stored: .keep+        case .replaced(let draft): .set(draft)+        case .none: thumbnailBaseline == .none ? .keep : .clear+        }+    }+     // MARK: - Related works (Reqs 8.1–8.4, Q24)      private func seedLinkTypeDrafts(_ links: [WorkLinkSnapshot]) {@@ -970,6 +1524,7 @@ public final class WorkDetailModel {         do {             let detail = try await library.workDetail(id: workID)             (presentation, chapterRowsByChapter) = (detail, Self.chapterOrder(detail.chapterRows))+            coverFetchPages = Self.coverFetchPages(of: detail.work)             seedLinkTypeDrafts(detail.links)         } catch {             Self.logger.error(@@ -1259,6 +1814,9 @@ public final class WorkDetailModel {             // `work-creators` Req 3.5: the credits commit in the same             // transaction as the rest, so they raise the checkmark with them.             || hasUnsavedCreditChange+            // `work-thumbnails` Req 2.5: a cover set, replaced or removed is an+            // unsaved change of the draft, exactly as an edited title is.+            || hasUnsavedThumbnailChange     }      // MARK: - View mode and edit mode (Decision 5)@@ -1281,6 +1839,11 @@ public final class WorkDetailModel {     public func beginEditing() {         guard !isReadOnly else { return }         clearLastRefusal()+        // `work-thumbnails` Req 2.1: the Cover field opens on what the work+        // holds. Seeded here as well as at the load, because the load is what+        // deliberately leaves the draft alone while the editor is open — so+        // entering the editor has to be the other place it is stated.+        restoreThumbnailDraft(from: work)         isEditing = true     } @@ -1316,6 +1879,10 @@ public final class WorkDetailModel {         restoreDraftsFromSnapshot()         draftWorkURL = baselineWorkURL         clearLastRefusal()+        // Req 4.11: leaving edit mode stops every fetch still in flight. The+        // draft restore above has already retired the session token, so a+        // result that beats the cancellation could not reach the draft either.+        cancelCoverFetch()         // A refusal the discarded draft earned goes with it — but the standing         // explanation of why this Work has no suggestion is not a refusal, and         // stays.@@ -1372,6 +1939,13 @@ public final class WorkDetailModel {         // Dropped before the reload, so the re-adopt below is allowed to replace         // the drafts with what the store now holds.         isEditing = false+        // Req 4.11, the third door: a Save leaves edit mode exactly as the X+        // does, so it owes the same cancellation. The paste-URL branch is the+        // one that can be in flight with **no sheet in front of it**, and a+        // result landing after the commit would raise the crop step or the+        // candidate sheet over view mode, on a work the reader has already+        // saved.+        cancelCoverFetch()         if hasRecordChanges {             // `place-extraction` Q55: the app is told **before** the reload. The             // coordinator's `reconcile()` is reached only through@@ -1387,6 +1961,10 @@ public final class WorkDetailModel {     }      private func restoreDraftsFromSnapshot() {+        // `work-thumbnails` Req 2.3: **before** the guard, so a cancel on a+        // screen whose read has gone still discards the crop the reader made+        // rather than leaving it standing in a closed editor.+        restoreThumbnailDraft(from: work)         guard let work else { return }         draftTitle = work.displayTitle         draftAssignment = work.typeDisplay.assignment@@ -1902,7 +2480,11 @@ public final class WorkDetailModel {                 // reproduces the read writes no credit row (the repository only                 // stamps a *changed* role set), and a `nil` here would mean "do                 // not touch the credits", which is a different statement.-                credits: creditsDraft+                credits: creditsDraft,+                // Req 2.2: the cover rides this commit like every other field.+                // `.keep` on a save that did not touch it, which is what keeps+                // an ordinary save from reading a byte of cover (Q37, Q49).+                thumbnail: thumbnailWrite             )             let basis = work.map(WorkEditBasis.init(work:))                 ?? WorkEditBasis(@@ -1918,7 +2500,12 @@ public final class WorkDetailModel {                     workStatus: draftWorkStatus,                     readingStatus: draftReadingStatus,                     verdict: draftVerdict,-                    membership: work?.membership)+                    membership: work?.membership,+                    // `work-thumbnails`: stated from the **baseline**, for the+                    // status fields' reason (Q47). The draft may hold a crop+                    // that is not stored anywhere yet; what the edit started+                    // from is what a conflict is measured against.+                    thumbnail: thumbnailBaseline.identity)             let outcome = try await library.updateWork(id: workID, basis: basis, draft: draft)             if case .conflict(let conflict) = outcome {                 // No optimistic mutation and no draft reset: the edit is the

diff --git a/Asterism/Asterism/Views/DuplicateResolutionView.swift b/Asterism/Asterism/Views/DuplicateResolutionView.swiftindex c15e8b1..effd47e 100644--- a/Asterism/Asterism/Views/DuplicateResolutionView.swift+++ b/Asterism/Asterism/Views/DuplicateResolutionView.swift@@ -250,6 +250,24 @@ struct DuplicateResolutionView: View {     @ViewBuilder     private func workVariantContent(_ variant: WorkVariantChoice) -> some View {         VStack(alignment: .leading, spacing: 4) {+            // V14 (`work-thumbnails` Req 1.6): the sheet has to *show* the+            // pictures. Every other differing field is a caption, and "a+            // different cover" is the one decision a caption cannot put to the+            // reader. Only when the copies disagree about it — a set torn by a+            // note does not want two identical covers printed into it.+            if model.differingFields.contains(.thumbnail),+               let identity = variant.thumbnail,+               let bytes = variant.thumbnailBytes {+                // Through the shared loader, at the same slot size and corner+                // the rows draw: decoding inline here ran `previewImage` on the+                // main actor once per variant on **every body pass**, and drew+                // a 600 px decode into the row's own box.+                ThumbnailBytesSlot(+                    namespace: variant.id.rawValue,+                    identity: identity,+                    bytes: bytes,+                    identifier: "duplicate-variant-thumbnail")+            }             Text(variant.displayTitle)                 .font(AsterismTypography.serifRowTitle)                 .accessibilityIdentifier("duplicate-variant-title")

diff --git a/Asterism/Asterism/Views/RecentView.swift b/Asterism/Asterism/Views/RecentView.swiftindex a0bd8b9..ae17e24 100644--- a/Asterism/Asterism/Views/RecentView.swift+++ b/Asterism/Asterism/Views/RecentView.swift@@ -907,7 +907,22 @@ struct RecentEntryRow: View {         row.isActionable || row.attention != nil || row.duplicateRoute != nil     } +    /// The row's content, with the work's cover at the card's leading edge where+    /// the work has one (`work-thumbnails` Reqs 6.1, 6.2).+    ///+    /// **Inside the button's label**, so a tap on the cover opens the entry like+    /// a tap anywhere else on the row — the cover is part of the row, not a+    /// second control standing beside it.     private var entryContent: some View {+        HStack(alignment: .center, spacing: 0) {+            if let thumbnail = row.workThumbnail, let workID = row.entry.workID {+                ThumbnailSlot(workID: workID, identity: thumbnail)+            }+            entryTextContent+        }+    }++    private var entryTextContent: some View {         VStack(alignment: .leading, spacing: 4) {             HStack {                 // Show Work display title if available, else capture title

diff --git a/Asterism/Asterism/Views/SettingsBackupImportView.swift b/Asterism/Asterism/Views/SettingsBackupImportView.swiftindex d1cb780..ae12e19 100644--- a/Asterism/Asterism/Views/SettingsBackupImportView.swift+++ b/Asterism/Asterism/Views/SettingsBackupImportView.swift@@ -44,8 +44,8 @@ struct SettingsBackupImportView: View {                 previewView(preview)             case .committing:                 committingView-            case .completed(let counts):-                completedView(counts)+            case .completed(let counts, let report):+                completedView(counts, report: report)             case .failed(let message):                 failedView(message)             }@@ -146,7 +146,9 @@ struct SettingsBackupImportView: View {      // MARK: - Completed -    private func completedView(_ counts: LibraryRecordCounts) -> some View {+    private func completedView(+        _ counts: LibraryRecordCounts, report: BackupImportReport+    ) -> some View {         VStack(spacing: 12) {             HStack {                 Image(systemName: "checkmark.circle.fill")@@ -157,6 +159,17 @@ struct SettingsBackupImportView: View {                 .font(.caption)                 .foregroundStyle(.secondary) +            // Req 8.4, after the counts (Q62): the import succeeded, so this is+            // a note rather than an error — but the reader is the only one who+            // can put those covers back, and only if they are told which works.+            if let dropped = SettingsBackupImportModel.droppedCoversMessage(report) {+                Text(dropped)+                    .font(.caption)+                    .foregroundStyle(.secondary)+                    .multilineTextAlignment(.center)+                    .accessibilityIdentifier("settings-import-dropped-covers")+            }+             Button("Done") { model.dismiss() }                 .frame(minHeight: AsterismLayout.minHitTarget)                 .accessibilityIdentifier("settings-import-done-button")

diff --git a/Asterism/Asterism/Views/SettingsView.swift b/Asterism/Asterism/Views/SettingsView.swiftindex 0ab3b2c..38257da 100644--- a/Asterism/Asterism/Views/SettingsView.swift+++ b/Asterism/Asterism/Views/SettingsView.swift@@ -82,7 +82,7 @@ struct SettingsView: View {     /// Req 4.2's Development-only trigger, injected as the pass itself rather     /// than as its model.     ///-    /// A closure because `BackgroundExportTriggerModel` lives behind `#if DEBUG`+    /// A closure because `DebugActionTriggerModel` lives behind `#if DEBUG`     /// and an initializer parameter cannot itself be `#if`-gated;     /// `BackgroundExportOutcome` is unconditional, so this signature compiles in     /// every configuration and the *row* is what the gate withholds.@@ -93,7 +93,13 @@ struct SettingsView: View {     /// `syncModel` is: Settings' inputs are rebuilt on every re-render of the     /// presenting view, and a model rebuilt with them would forget the outcome     /// it was showing.-    @State private var backgroundExportTrigger: BackgroundExportTriggerModel?+    @State private var backgroundExportTrigger: DebugActionTriggerModel?++    /// The thumbnail store probe (`work-thumbnails` Req 7.3, Q42). Owned here+    /// for the same reason; it needs no input from the app, so nothing is+    /// injected and the row shows in every `Development` build.+    @State private var thumbnailProbeTrigger = DebugActionTriggerModel(+        action: Self.thumbnailProbeSentence)     #endif      init(@@ -134,7 +140,12 @@ struct SettingsView: View {         self.runBackgroundExport = runBackgroundExport         #if DEBUG         _backgroundExportTrigger = State(-            initialValue: runBackgroundExport.map { BackgroundExportTriggerModel(pass: $0) })+            initialValue: runBackgroundExport.map { pass in+                // The pass's own vocabulary (Req 4.1) — the same words the+                // Console record carries, so a developer reading one recognises+                // the other.+                DebugActionTriggerModel(action: { "Last pass: \(await pass().logDescription)" })+            })         #endif     } @@ -261,6 +272,7 @@ struct SettingsView: View {                     syncRows                     diagnosticsRow                     backgroundExportRow+                    thumbnailProbeRow                 } label: {                     Text("Debug")                         .font(.subheadline)@@ -586,54 +598,106 @@ struct SettingsView: View {         }     } -    // MARK: - Background export trigger (Req 4.2)+    // MARK: - Development-only debug actions -    /// One row, following `backupRow`'s state switch: the button, the pass-    /// running, then what it did. Empty in `Personal`, which defines no `DEBUG`-    /// and is therefore handed no trigger to show (Req 4.2, Q17).+    /// Req 4.2's trigger. Empty in `Personal`, which defines no `DEBUG` and is+    /// therefore handed no trigger to show (Req 4.2, Q17).     @ViewBuilder     private var backgroundExportRow: some View {         #if DEBUG         if let backgroundExportTrigger {-            switch backgroundExportTrigger.state {-            case .idle:-                Button {-                    Task { await backgroundExportTrigger.run() }-                } label: {-                    Label("Run background export", systemImage: "arrow.up.circle")-                }-                .accessibilityIdentifier("settings-background-export-run")+            debugActionRow(+                title: "Run background export",+                systemImage: "arrow.up.circle",+                progress: "Running a pass…",+                runIdentifier: "settings-background-export-run",+                progressIdentifier: "settings-background-export-progress",+                resultIdentifier: "settings-background-export-result",+                model: backgroundExportTrigger)+        }+        #endif+    } -            case .running:-                HStack {-                    ProgressView()-                        .accessibilityIdentifier("settings-background-export-progress")-                    Text("Running a pass…")-                        .foregroundStyle(.secondary)-                }+    /// The thumbnail store probe (`work-thumbnails` Req 7.3). Its report is+    /// several lines, which is why the finished state's text is left to wrap.+    @ViewBuilder+    private var thumbnailProbeRow: some View {+        #if DEBUG+        debugActionRow(+            title: "Probe thumbnail store",+            systemImage: "memorychip",+            progress: "Probing…",+            runIdentifier: "settings-thumbnail-probe-run",+            progressIdentifier: "settings-thumbnail-probe-progress",+            resultIdentifier: "settings-thumbnail-probe-result",+            model: thumbnailProbeTrigger)+        #endif+    } -            case .finished(let sentence):-                VStack(alignment: .leading, spacing: 8) {-                    // The identifier goes on the `Text` rather than on this-                    // stack: a container's identifier is inherited by every-                    // descendant and would take the button's name with it-                    // (`docs/agent-notes/testing.md`).-                    Text(sentence)-                        .font(.callout)-                        .accessibilityIdentifier("settings-background-export-result")-                    Button {-                        Task { await backgroundExportTrigger.run() }-                    } label: {-                        Text("Run background export")-                    }-                    .buttonStyle(.borderless)-                    .accessibilityIdentifier("settings-background-export-run")+    #if DEBUG+    /// One row, following `backupRow`'s state switch: the button, the action+    /// running, then what it did.+    ///+    /// The two Debug-disclosure actions were the same twenty lines twice, down+    /// to the comment explaining why the identifier goes on the `Text` — so they+    /// are one function whose arguments are the words and the three names the+    /// UI suites query by.+    @ViewBuilder+    private func debugActionRow(+        title: String,+        systemImage: String,+        progress: String,+        runIdentifier: String,+        progressIdentifier: String,+        resultIdentifier: String,+        model: DebugActionTriggerModel+    ) -> some View {+        switch model.state {+        case .idle:+            Button {+                Task { await model.run() }+            } label: {+                Label(title, systemImage: systemImage)+            }+            .accessibilityIdentifier(runIdentifier)++        case .running:+            HStack {+                ProgressView()+                    .accessibilityIdentifier(progressIdentifier)+                Text(progress)+                    .foregroundStyle(.secondary)+            }++        case .finished(let sentence):+            VStack(alignment: .leading, spacing: 8) {+                // The identifier goes on the `Text` rather than on this stack: a+                // container's identifier is inherited by every descendant and+                // would take the button's name with it+                // (`docs/agent-notes/testing.md`).+                Text(sentence)+                    .font(.callout)+                    .textSelection(.enabled)+                    .accessibilityIdentifier(resultIdentifier)+                Button {+                    Task { await model.run() }+                } label: {+                    Text(title)                 }+                .buttonStyle(.borderless)+                .accessibilityIdentifier(runIdentifier)             }         }-        #endif     } +    /// The probe, run and worded. A static function rather than a closure at the+    /// property so the `@State` initializer stays one line.+    private static func thumbnailProbeSentence() async -> String {+        do { return try await ThumbnailStoreProbe.run().sentence }+        catch { return "Probe failed: \(error.localizedDescription)" }+    }+    #endif+     // MARK: - Backup Row      @ViewBuilder

diff --git a/Asterism/Asterism/Views/WorkDetailView.swift b/Asterism/Asterism/Views/WorkDetailView.swiftindex 61a4d1b..f725e6b 100644--- a/Asterism/Asterism/Views/WorkDetailView.swift+++ b/Asterism/Asterism/Views/WorkDetailView.swift@@ -3,6 +3,8 @@ import AsterismCore import AsterismIntelligence import ConstellationKit import SwiftUI+// For the Cover menu's `PasteButton` content types (`work-thumbnails` Req 3.3).+import UniformTypeIdentifiers  /// Work detail in the §6 shape (Req 5.1): header, rating pulse, "Open last /// noted chapter", generic notes, then the chapter-notes list.@@ -35,6 +37,8 @@ struct WorkDetailView: View {     /// (Q33) and a multi-site Work chooses one from a menu.     @State private var reviewingIdentityHostname: PresentedHostname?     @State private var showingURLReteach = false+    /// The cover on its own, from a long press on the header (`work-thumbnails`).+    @State private var isShowingCoverViewer = false     /// Which site the "Remove from site" confirmation is about (Req 7.2). The     /// hostname travels on the presented value for the reason every other dialog     /// on this screen does: SwiftUI runs the dismissal before the button's@@ -118,6 +122,12 @@ struct WorkDetailView: View {     /// Bumped by a save that ended in a refusal, so the screen scrolls to it     /// even when it is the same refusal, in the same place, as the last one.     @State private var refusalScrollRequests = 0+    /// `work-thumbnails` Req 3.2: whether the platform's image picker is up.+    @State private var isPresentingCoverPicker = false+    /// The session the picker was opened for (Req 3.7). Captured at the tap, so+    /// a result that arrives after the reader cancelled or picked again is+    /// carrying a token the model has already retired.+    @State private var coverPickToken = UUID()      init(         model: WorkDetailModel,@@ -385,6 +395,11 @@ struct WorkDetailView: View {                 model: model,                 editingCharacter: $expandedEditCharacterID,                 editingPlace: $expandedEditPlaceID))+        .modifier(+            WorkThumbnailPresentations(+                model: model,+                isPresentingPicker: $isPresentingCoverPicker,+                pickToken: $coverPickToken))         .markdownExportShare(             model: exportModel, sheetIdentifier: "work-detail-export-share-sheet")         // Req 7.1's two dispositions plus cancel. `presenting:` hands the@@ -480,6 +495,32 @@ struct WorkDetailView: View {     private func viewHeaderSection(_ work: WorkSnapshot) -> some View {         Section {             VStack(alignment: .leading, spacing: 12) {+                // `work-thumbnails` Req 6.2, Q40, Q86: the cover above the title,+                // at 160×240 and up to 240×360 at the largest body size (Q93),+                // centred, so the title keeps its full width. Decorative+                // like every other slot — the header already says what the work+                // is called.+                if let thumbnail = work.thumbnail {+                    ThumbnailSlot(+                        workID: work.id, identity: thumbnail,+                        baseSize: AsterismLayout.coverHeaderSize,+                        cornerRadius: AsterismLayout.coverRadius,+                        trailingGap: 0,+                        marker: LayoutMarker.workDetailCover)+                    .frame(maxWidth: .infinity, alignment: .center)+                    // A long press opens the cover on its own at its stored+                    // size. Simultaneous rather than `onLongPressGesture`,+                    // whose recogniser claims the taps of every control in the+                    // same List row and took the site link glyph with it.+                    .simultaneousGesture(+                        LongPressGesture(minimumDuration: 0.5)+                            .onEnded { _ in isShowingCoverViewer = true })+                    .coveringPresentation(isPresented: $isShowingCoverViewer) {+                        CoverViewerView(+                            workID: work.id, identity: thumbnail, title: work.displayTitle)+                    }+                }+                 // No `lineLimit`: this is the one place the whole title is                 // readable, which is the point of it being here (Q58).                 Text(work.displayTitle)@@ -719,6 +760,7 @@ struct WorkDetailView: View {                 workURLField                 workTypeField                 workGenreField+                coverField             }             .frame(maxWidth: .infinity, alignment: .leading)             .padding(12)@@ -837,6 +879,132 @@ struct WorkDetailView: View {         .constellationCaptionedField("Genre")     } +    /// The work's cover (`work-thumbnails` Reqs 2.1–2.6, Q39).+    ///+    /// One captioned row of the Work card, beside Title, URL, Type and Genre —+    /// the current picture (or the site glyph where there is none) as the label+    /// of a menu of the things that can be done to it.+    ///+    /// **Nothing here writes.** Every item changes the draft the toolbar+    /// checkmark commits: a pick opens the crop step, a crop lands in the draft+    /// and Remove empties it. Find cover joins this menu with the fetch pipeline.+    @ViewBuilder+    private var coverField: some View {+        VStack(alignment: .leading, spacing: 8) {+            Menu {+                // Req 3.1, and Req 4.2's absence: a work with neither a work URL+                // nor an entry has nothing to fetch, and the item is not offered+                // rather than offered and failing.+                if model.offersFindCover {+                    Button("Find cover…") { model.beginFindCover() }+                        .accessibilityIdentifier("work-detail-cover-find")+                }++                Button(RuntimePlatform.isMac ? "Choose file…" : "Choose from Photos…") {+                    coverPickToken = model.beginThumbnailPick()+                    isPresentingCoverPicker = true+                }+                .accessibilityIdentifier("work-detail-cover-choose")++                // Q46: the system control, because it is the only paste that+                // never raises the pasteboard permission prompt. On iOS it+                // disables itself when the pasteboard holds none of these types,+                // which is why Req 3.3's refusal message is a Mac-only sentence+                // (Q50).+                PasteButton(supportedContentTypes: [.image, .url, .plainText]) { providers in+                    let token = model.beginThumbnailPick()+                    Task { await model.acceptPastedProviders(providers, token: token) }+                }+                .accessibilityIdentifier("work-detail-cover-paste")++                // Req 2.1: offered whenever the draft has a cover, **including**+                // one whose bytes will not decode — `.stored` needs none.+                if model.offersThumbnailRemoval {+                    Button("Remove", role: .destructive) { model.removeThumbnail() }+                        .accessibilityIdentifier("work-detail-cover-remove")+                }+            } label: {+                coverPreview+                    // The menu's hit target does not depend on the picture.+                    // A `.stored` cover whose bytes never arrived draws a slot+                    // that gives its space back (Req 6.4), and the menu wearing+                    // it collapsed with it — leaving a reader holding exactly+                    // the row Req 2.1's Remove exists for unable to tap+                    // anything at all (Q96).+                    .frame(+                        minWidth: AsterismLayout.minHitTarget,+                        minHeight: AsterismLayout.minHitTarget,+                        alignment: .leading)+                    .contentShape(Rectangle())+            }+            .disabled(model.isReadOnly)+            .accessibilityLabel("Cover")+            .accessibilityValue(model.coverAccessibilityValue)+            .accessibilityIdentifier("work-detail-cover-menu")++            // Req 3.3: a pasted link is one bounded request of up to 5 seconds+            // with nothing else on screen — no candidate sheet, no crop step —+            // so the field says it is working, the way the crop step's own+            // encode does. It goes the moment the fetch resolves, whichever way+            // it resolves.+            if model.isFetchingPastedCoverURL {+                HStack(spacing: 8) {+                    ProgressView().controlSize(.small)+                    Text("Reading that link…")+                        .font(.footnote)+                        .foregroundStyle(AsterismColors.secondaryText)+                }+                .accessibilityElement(children: .combine)+                .accessibilityIdentifier("work-detail-cover-fetching")+            }++            // Req 3.4's one sentence, under the field it is about — not in the+            // screen's message row, which is where a refused *write* goes.+            if let message = model.thumbnailMessage {+                Text(message)+                    .font(.footnote)+                    .foregroundStyle(AsterismColors.amberText)+                    .accessibilityIdentifier("work-detail-cover-message")+            }+        }+        .constellationCaptionedField("Cover")+    }++    /// What the menu is worn by: the draft's cover at slot size, or the site+    /// glyph where the work has none.+    @ViewBuilder+    private var coverPreview: some View {+        switch model.draftThumbnail {+        case .replaced(let draft):+            // Through the same slot the header and the rows draw, so a square+            // crop and one the reader zoomed out of look here exactly as they+            // will look once saved (Decision 3). Drawing it filled in a fixed+            // portrait box showed the reader a picture the app was never going+            // to store.+            ThumbnailBytesSlot(+                namespace: "draft",+                identity: draft.identity,+                bytes: draft.bytes,+                identifier: LayoutMarker.workDetailCoverPreview)+        case .stored(let identity):+            // Through the shared loader like every other surface: the editor+            // holds no bytes, and a cover it could not read draws the glyph+            // with nothing said (Req 6.4).+            ThumbnailSlot(+                workID: model.workID, identity: identity, trailingGap: 0,+                marker: LayoutMarker.workDetailCoverPreview)+        case .none:+            coverGlyph+        }+    }++    private var coverGlyph: some View {+        SiteGlyph(+            hostname: model.work?.primaryHostname ?? "",+            size: AsterismLayout.coverSize.width)+            .accessibilityHidden(true)+    }+     /// Where the reader is with the work, in one card (Reqs 1.2, 2.2, 2.3).     ///     /// Both capsules contain a segment called "Finished" and nothing else on the@@ -2431,6 +2599,69 @@ private struct WorkCreditPresentations: ViewModifier {     } } +/// The cover's two presentations: the platform's image picker and the crop step+/// (`work-thumbnails` Reqs 3.2, 3.5, 5.1–5.4).+///+/// Its own modifier on `WorkCreditPresentations`' shape and for its reason: one+/// modifier is one expression, and this screen's chain has already been past+/// what the type checker will finish once.+///+/// **Nothing presents from inside another sheet's closure** (Q101 of+/// `duplicate-reconciliation`): the picker hands its bytes to the model, the+/// model publishes `pendingCrop`, and the crop sheet is `.sheet(item:)` on that+/// — so the crop step is never raised from inside the picker's callback.+private struct WorkThumbnailPresentations: ViewModifier {+    let model: WorkDetailModel+    @Binding var isPresentingPicker: Bool+    @Binding var pickToken: UUID++    func body(content: Content) -> some View {+        content+            .imagePicker(+                isPresented: $isPresentingPicker,+                onSelection: { data in+                    model.acceptPickedImage(+                        data, token: pickToken,+                        // The label the reader tapped and the sentence a failure+                        // gets are the same platform fact (Q7).+                        source: RuntimePlatform.isMac ? .file : .photos)+                },+                onCancel: { model.cancelThumbnailPick() })+            // Req 4.11: the run stops when the sheet goes, and it stops again+            // when the page does — a push away from the editor is not a+            // dismissal and would otherwise leave the requests running.+            .onDisappear { model.cancelCoverFetch() }+            .sheet(+                isPresented: Binding(+                    get: { model.isPresentingCoverCandidates },+                    set: { if !$0 { model.cancelCoverFetch() } }),+                // The crop step is raised **from the dismissal**, never from+                // inside the sheet's own closure (Q101 of+                // `duplicate-reconciliation`).+                onDismiss: { model.presentChosenCover() }+            ) {+                CoverCandidateSheet(+                    state: model.coverCandidateState,+                    offersPageScan: model.offersCoverPageScan,+                    onUse: { model.chooseCoverCandidate($0) },+                    onScanPage: { model.rescanPagesIncludingBody() },+                    onCancel: { model.cancelCoverFetch() })+            }+            .sheet(+                item: Binding(+                    get: { model.pendingCrop },+                    set: { if $0 == nil { model.cancelCrop() } })+            ) { source in+                ThumbnailCropView(+                    source: source,+                    onConfirm: { draft in+                        Task { await model.acceptCroppedThumbnail(draft, token: source.id) }+                    },+                    onCancel: { model.cancelCrop() })+            }+    }+}+ /// The record editor a collection line opens (`character-extraction` Req 5.3, /// `place-extraction` Req 3.2). ///

diff --git a/Asterism/Asterism/Views/WorkMergeView.swift b/Asterism/Asterism/Views/WorkMergeView.swiftindex 09954a5..a9d52e7 100644--- a/Asterism/Asterism/Views/WorkMergeView.swift+++ b/Asterism/Asterism/Views/WorkMergeView.swift@@ -422,6 +422,12 @@ struct WorkMergeView: View {         // distinction the outcome does not have. Which series and which place in         // it is `discardedValue`'s job, on the row that drops one.         case .targetSeries, .sourceSeries: "Series"+        // V14 (`work-thumbnails` Req 1.5). One label for both sides, for the+        // series' reason: the merged work carries **one** cover, so naming the+        // side it came from would describe a distinction the outcome does not+        // have. "Cover" is the reader's word for it — it is what the editor's+        // field is called — not "thumbnail", which is the store's.+        case .targetThumbnail, .sourceThumbnail: "Cover"         }     } 

diff --git a/Asterism/Asterism/Views/WorksView.swift b/Asterism/Asterism/Views/WorksView.swiftindex 68a39f8..77acbf2 100644--- a/Asterism/Asterism/Views/WorksView.swift+++ b/Asterism/Asterism/Views/WorksView.swift@@ -871,6 +871,26 @@ struct WorkRow: View {     private var isAbandoned: Bool { work.readingStatus == .abandoned }      var body: some View {+        // `work-thumbnails` Req 6.1: the cover, where the work has one. The row+        // is otherwise exactly what it was — a work with no cover keeps today's+        // layout, which is most works in this library (Q12).+        //+        // `spacing: 0` and the gap inside the slot: a slot that gives its space+        // back when the bytes will not load has to cost the row *nothing*, and a+        // container's spacing would survive the collapse.+        HStack(alignment: .center, spacing: 0) {+            if let thumbnail = work.thumbnail {+                ThumbnailSlot(workID: work.id, identity: thumbnail)+            }+            rowContent+        }+        .frame(minHeight: AsterismLayout.minHitTarget)+        // Req 5.2: the whole row steps back, the way an ignored teach chip does+        // — the design language's one knock-down, not a second amount.+        .opacity(isAbandoned ? ConstellationRecipes.knockdownOpacity : 1)+    }++    private var rowContent: some View {         VStack(alignment: .leading, spacing: 4) {             // Req 11.3: single-line work names truncate, never wrap.             Text(work.displayTitle)@@ -950,10 +970,6 @@ struct WorkRow: View {                     .accessibilityIdentifier("work-entry-count")             }         }-        .frame(minHeight: AsterismLayout.minHitTarget)-        // Req 5.2: the whole row steps back, the way an ignored teach chip does-        // — the design language's one knock-down, not a second amount.-        .opacity(isAbandoned ? ConstellationRecipes.knockdownOpacity : 1)     }      /// One status mark. `.caption` semibold is `constellationPill`'s own text

diff --git a/Asterism/AsterismTests/AppLibraryModelTests.swift b/Asterism/AsterismTests/AppLibraryModelTests.swiftindex 5ed461c..5efa54c 100644--- a/Asterism/AsterismTests/AppLibraryModelTests.swift+++ b/Asterism/AsterismTests/AppLibraryModelTests.swift@@ -741,7 +741,7 @@ struct AppLibraryModelSyncArrivalTests {     @Test("An arrival during an import is forwarded for the repository to defer (Q46)")     func arrivalDuringImportIsForwardedNotDropped() async throws {         let mock = MockLibraryProvider()-        mock.confirmImportResult = .success(.committed(.zero))+        mock.confirmImportResult = .success(.committed(.zero, report: .empty))         let model = AppLibraryModel(readyRepository: mock)         // The arrival lands between the import's chunk saves — the window the         // repository's bulk-operation flag exists for. The deferral and its

diff --git a/Asterism/AsterismTests/ConflictRecentEntryDetailPresentationTests.swift b/Asterism/AsterismTests/ConflictRecentEntryDetailPresentationTests.swiftindex f87fd85..b5251cc 100644--- a/Asterism/AsterismTests/ConflictRecentEntryDetailPresentationTests.swift+++ b/Asterism/AsterismTests/ConflictRecentEntryDetailPresentationTests.swift@@ -156,7 +156,7 @@ struct ConflictRecentEntryDetailPresentationTests {         let work = TestFixtures.makeWork(id: UUID(), displayTitle: "Test Work")         mock.workDetailResult = .success(TestFixtures.makeWorkDetail(work: work)) -        let model = WorkDetailModel(workID: work.id, library: mock, onMutation: {})+        let model = makeWorkDetailModel(workID: work.id, library: mock, onMutation: {})         await model.load()          // Loading the work invokes workDetail() — that's the live read (M5

diff --git a/Asterism/AsterismTests/CropGeometryTests.swift b/Asterism/AsterismTests/CropGeometryTests.swiftnew file mode 100644index 0000000..d61a1d4--- /dev/null+++ b/Asterism/AsterismTests/CropGeometryTests.swift@@ -0,0 +1,275 @@+import AsterismCore+import CoreGraphics+import Testing++@testable import Asterism++/// The crop step's arithmetic (`work-thumbnails` Reqs 5.1, 5.2, 5.5).+///+/// `CropGeometry` is the whole of what the crop step can get wrong: a frame the+/// image stops filling on either axis, a gap that drifts off centre, a crop+/// rectangle that is not what the reader was looking at, and an opening shape+/// that wastes most of the picture. None of it needs a view, so none of it is+/// tested through one.+///+/// Q89 moved the floor from the cover scale to the fit scale, so "covered" is no+/// longer the invariant: **filled on at least one axis** is.+@Suite("Crop geometry")+struct CropGeometryTests {++    /// 1,200×800 behind a 300×450 portrait frame. Wider than the frame, so the+    /// cover scale is set by the height: 450/800 = 0.5625.+    private let landscape = CropGeometry(+        sourceSize: CGSize(width: 1_200, height: 800),+        frameSize: CGSize(width: 300, height: 450))++    // MARK: - Scale++    @Test("The cover scale is the larger of the two axis ratios")+    func coverScaleIsTheLargerRatio() {+        #expect(abs(landscape.coverScale - 0.5625) < 1e-9)++        // Taller than the frame: the width sets it instead.+        let portraitSource = CropGeometry(+            sourceSize: CGSize(width: 600, height: 2_000),+            frameSize: CGSize(width: 300, height: 450))+        #expect(abs(portraitSource.coverScale - 0.5) < 1e-9)+    }++    /// Q89: the floor is the **fit** scale, where the whole picture is inside+    /// the frame and touches it on one axis. The cover scale is where the step+    /// opens, not where it stops.+    @Test("A proposed scale below the fit scale is clamped up to it, not to the cover scale")+    func scaleClampsToTheFitScale() {+        // 1,200×800 inside a 300×450 frame: the width binds, 300/1,200 = 0.25.+        #expect(abs(landscape.fitScale - 0.25) < 1e-9)+        #expect(landscape.fitScale < landscape.coverScale)++        #expect(landscape.clamped(scale: 0.1) == landscape.fitScale)+        #expect(landscape.clamped(scale: 0) == landscape.fitScale)+        #expect(landscape.clamped(scale: -3) == landscape.fitScale)+        // Between the two the reader's zoom is their own, which is the whole of+        // what Q89 opened up.+        #expect(landscape.clamped(scale: 0.4) == 0.4)+        #expect(landscape.clamped(scale: 2) == 2)+    }++    /// A picture of exactly the frame's aspect ratio has nothing to zoom out+    /// into: the two scales coincide and the floor is unchanged from before+    /// Q89.+    @Test("For a source of the frame's shape the fit scale is the cover scale")+    func fitAndCoverCoincideOnAMatchingShape() {+        let matching = CropGeometry(+            sourceSize: CGSize(width: 600, height: 900),+            frameSize: CGSize(width: 300, height: 450))+        #expect(abs(matching.fitScale - matching.coverScale) < 1e-12)+        #expect(matching.clamped(scale: 0.01) == matching.coverScale)+    }++    /// Req 5.5: a picture smaller than the frame is scaled up, never refused.+    @Test("A source smaller than the frame gets a cover scale above one")+    func smallSourceScalesUp() {+        let tiny = CropGeometry(+            sourceSize: CGSize(width: 60, height: 90),+            frameSize: CGSize(width: 300, height: 450))+        #expect(abs(tiny.coverScale - 5) < 1e-9)+        // Same shape as the frame, so the fit scale is the cover scale and the+        // clamp still scales a tiny source all the way up.+        #expect(tiny.clamped(scale: 1) == 5)+    }++    // MARK: - Offset++    @Test("The offset clamps so the frame stays covered")+    func offsetClampsToTheOverhang() {+        // At the cover scale the drawn image is 675×450: 375 pt of horizontal+        // overhang, none vertically.+        let clamped = landscape.clamped(+            offset: CGSize(width: 900, height: 40), scale: landscape.coverScale)+        #expect(abs(clamped.width - 187.5) < 1e-9)+        #expect(clamped.height == 0)++        let negative = landscape.clamped(+            offset: CGSize(width: -900, height: -40), scale: landscape.coverScale)+        #expect(abs(negative.width + 187.5) < 1e-9)+        #expect(negative.height == 0)+    }++    @Test("An offset inside the overhang is left alone")+    func offsetInsideTheOverhangIsUnchanged() {+        let proposed = CGSize(width: 100, height: 60)+        let clamped = landscape.clamped(offset: proposed, scale: 1)+        #expect(clamped == proposed)+    }++    /// Q89: below the cover scale one axis is no longer filled, and the clamp+    /// gives that axis no slack at all — so the gap the reader opened stays+    /// centred and cannot be pushed to one side.+    @Test("Below the cover scale the pan clamp centres the gapped axis")+    func panClampCentresTheGappedAxis() {+        // At the floor the drawn image is 300×200 inside a 300×450 frame:+        // nothing overhangs on either axis, so nothing moves at all.+        let atFloor = landscape.fitScale+        #expect(landscape.clamped(offset: CGSize(width: 900, height: 900), scale: atFloor) == .zero)+        #expect(+            landscape.clamped(offset: CGSize(width: -900, height: -900), scale: atFloor) == .zero)++        // Between the two scales the gapped axis is still pinned while the+        // covered one pans: drawn 420×280, so 60 pt of horizontal slack and+        // none vertically.+        let between = landscape.clamped(offset: CGSize(width: 900, height: 900), scale: 0.35)+        #expect(abs(between.width - 60) < 1e-9)+        #expect(between.height == 0)+    }++    /// The invariant the clamp exists for, restated for Q89: a clamped placement+    /// never lets the crop leave the source on an axis the image still fills,+    /// where it does leave it the overhang is symmetric, and it never leaves on+    /// **both** — because the fit scale is the floor. The overhang is the gap+    /// `ThumbnailCodec.encode` then declines to store (Decision 3).+    @Test("A clamped placement overhangs at most one axis, symmetrically")+    func clampedPlacementOverhangsAtMostOneAxisSymmetrically() {+        for rawScale in [0.01, 0.25, 0.3, 0.5625, 1.0, 3.0] {+            let scale = landscape.clamped(scale: rawScale)+            for raw in [CGSize(width: 5_000, height: 5_000),+                        CGSize(width: -5_000, height: -5_000),+                        CGSize(width: 0, height: 0)] {+                let offset = landscape.clamped(offset: raw, scale: scale)+                let crop = landscape.cropRect(scale: scale, offset: offset)+                let overLeft = max(-crop.minX, 0)+                let overRight = max(crop.maxX - landscape.sourceSize.width, 0)+                let overTop = max(-crop.minY, 0)+                let overBottom = max(crop.maxY - landscape.sourceSize.height, 0)+                #expect(abs(overLeft - overRight) < 1e-6, "\(crop) at \(scale) is off-centre")+                #expect(abs(overTop - overBottom) < 1e-6, "\(crop) at \(scale) is off-centre")+                #expect(+                    overLeft + overRight < 1e-6 || overTop + overBottom < 1e-6,+                    "\(crop) at \(scale) left the source on both axes")+            }+        }+    }++    /// The floor's crop in full: exactly the source on the axis the image fills,+    /// and symmetrically past it on the other.+    @Test("At the fit scale the crop extends past the source on one axis only")+    func cropAtTheFitScaleOverhangsOneAxis() {+        let crop = landscape.cropRect(scale: landscape.fitScale, offset: .zero)+        // The width binds, so the crop is exactly the source's 1,200 wide…+        #expect(abs(crop.minX) < 1e-9)+        #expect(abs(crop.maxX - 1_200) < 1e-9)+        // …and 450/0.25 = 1,800 tall around an 800 px source, centred: 500 px+        // of gap above and 500 below.+        #expect(abs(crop.height - 1_800) < 1e-9)+        #expect(abs(crop.minY + 500) < 1e-9)+        #expect(abs(crop.maxY - 1_300) < 1e-9)+    }++    // MARK: - The crop rectangle++    /// Req 5.3's default frame: confirming without adjusting anything encodes+    /// the largest centred rectangle of the shape.+    ///+    /// Q89 lowered the floor but not the opening placement — `ThumbnailCropView`+    /// still opens at `coverScale` — so this crop is inside the source on both+    /// axes and encodes to the shape's full box, with no gap in it.+    @Test("At the cover scale with no offset the crop is the largest centred frame")+    func defaultFrameIsTheLargestCentredRectangle() {+        let crop = landscape.cropRect(scale: landscape.coverScale, offset: .zero)+        // 300/0.5625 = 533.33 wide, the full 800 tall, centred.+        #expect(abs(crop.width - 300 / 0.5625) < 1e-6)+        #expect(abs(crop.height - 800) < 1e-9)+        #expect(abs(crop.midX - 600) < 1e-9)+        #expect(abs(crop.midY - 400) < 1e-9)+        // Wholly inside the source: the default crop is never a gapped one.+        #expect(crop.minX >= -1e-9)+        #expect(crop.minY >= -1e-9)+        #expect(crop.maxX <= landscape.sourceSize.width + 1e-9)+        #expect(crop.maxY <= landscape.sourceSize.height + 1e-9)+    }++    @Test("The crop rectangle maps the frame into source pixels, origin top left")+    func cropRectangleIsTheFrameInSourcePixels() {+        // Scale 1: the frame is 300×450 source pixels. Offset +60 moves the+        // *image* right, so the frame sits 60 px further left in the picture.+        let crop = landscape.cropRect(scale: 1, offset: CGSize(width: 60, height: -20))+        #expect(abs(crop.width - 300) < 1e-9)+        #expect(abs(crop.height - 450) < 1e-9)+        #expect(abs(crop.minX - (600 - 150 - 60)) < 1e-9)+        #expect(abs(crop.minY - (400 - 225 + 20)) < 1e-9)+    }++    @Test("A known crop round-trips through placement and back")+    func knownCropRoundTrips() {+        let crop = CGRect(x: 120, y: 40, width: 480, height: 720)+        let geometry = CropGeometry(+            sourceSize: CGSize(width: 1_200, height: 800),+            frameSize: CGSize(width: 240, height: 360))+        let placement = geometry.placement(for: crop)+        let round = geometry.cropRect(scale: placement.scale, offset: placement.offset)+        #expect(abs(round.minX - crop.minX) < 1e-6)+        #expect(abs(round.minY - crop.minY) < 1e-6)+        #expect(abs(round.width - crop.width) < 1e-6)+        #expect(abs(round.height - crop.height) < 1e-6)+    }++    // MARK: - The opening shape (Req 5.2)++    /// The table the requirement is: whichever shape's largest centred frame+    /// keeps more of the picture, and portrait where they keep the same.+    ///+    /// Written as one test with an expectation per row rather than as a+    /// parameterised case: a tuple-argument `@Test(arguments:)` compiles and+    /// then silently does not run (`docs/agent-notes/testing.md`).+    @Test("The default shape keeps the larger share of the source")+    func defaultShapeKeepsTheLargerShare() {+        func shape(_ width: CGFloat, _ height: CGFloat) -> ThumbnailShape {+            CropGeometry.defaultShape(+                forSourceSize: CGSize(width: width, height: height))+        }+        // Exactly portrait: the whole picture fits the portrait frame.+        #expect(shape(600, 900) == .portrait)+        // Exactly square.+        #expect(shape(500, 500) == .square)+        // Wide: a square frame keeps more than a 2:3 one.+        #expect(shape(1_600, 900) == .square)+        #expect(shape(1_200, 800) == .square)+        // Tall: portrait keeps more.+        #expect(shape(900, 1_200) == .portrait)+        #expect(shape(300, 3_000) == .portrait)+        // Just inside the tie on each side.+        #expect(shape(810, 1_000) == .portrait)+        #expect(shape(830, 1_000) == .square)+    }++    /// The exact tie is a source of aspect ratio √(2∕3) ≈ 0.8165, where a+    /// portrait frame bounded by the width and a square frame bounded by the+    /// height keep the same share. Req 5.2 hands it to portrait.+    @Test("A tie goes to portrait")+    func tieGoesToPortrait() {+        let height: CGFloat = 1_000+        let width = height * (2.0 / 3.0).squareRoot()+        #expect(+            CropGeometry.defaultShape(forSourceSize: CGSize(width: width, height: height))+                == .portrait)+    }++    // MARK: - The frame in points++    @Test("The frame is the largest rectangle of the shape inside the space offered")+    func frameFitsTheSpaceOffered() {+        let wide = CropGeometry.frameSize(+            for: .portrait, fitting: CGSize(width: 1_000, height: 300))+        #expect(abs(wide.height - 300) < 1e-9)+        #expect(abs(wide.width - 200) < 1e-9)++        let tall = CropGeometry.frameSize(+            for: .portrait, fitting: CGSize(width: 300, height: 1_000))+        #expect(abs(tall.width - 300) < 1e-9)+        #expect(abs(tall.height - 450) < 1e-9)++        let square = CropGeometry.frameSize(+            for: .square, fitting: CGSize(width: 400, height: 250))+        #expect(abs(square.width - 250) < 1e-9)+        #expect(abs(square.height - 250) < 1e-9)+    }+}