cmux-next iOS: every vertical list scrolls at full frame rate

Packages/iOS/CmuxTabsKit/README.md

@@ -40,7 +40,12 @@ transport or models.
   putting that frame in its card; `resumeLiveContent(_:)` restarts it when
   the grid is left, so the zoom still starts from the same pixels.
   `overviewVisibilityChanged(_:)` and `overviewScrollingChanged(_:)` tell
-  you when to stop or hold card updates. Return false from `isContentReady` while a
+  you when to stop or hold card updates, and `overviewIdleChanged(_:)` when
+  the grid rests (settled, not scrolling): the time to draw a costly card
+  into a picture. The grid builds only the cards within a few screens of
+  the visible rect (one per frame, nearest first) and releases far ones, so
+  `card(for:)` runs for a card when it nears the screen, not for every tab
+  at once; keep it a cheap view of what you already have. Return false from `isContentReady` while a
   tab's content would still be blank (a terminal attaching) and its card
   covers it.
 - **Close buttons and titles.** They arrive and leave as in Safari (measured

Packages/iOS/CmuxTabsKit/Sources/CmuxTabsKit/API/TabsDataSource.swift

@@ -67,6 +67,10 @@ public protocol TabsDataSource: AnyObject, Observable {
     /// The grid started (true) or stopped (false) scrolling: hold card
     /// updates until it stops, so none lands in a scroll frame.
     func overviewScrollingChanged(_ scrolling: Bool)
+    /// The grid settled and is not scrolling (true), or a zoom, a scroll or
+    /// the page took over (false): deferred card work (rendering a card's
+    /// snapshot) runs only while this is true. Default: nothing.
+    func overviewIdleChanged(_ idle: Bool)
     /// The grid settled with `id` active. Return true after making the
     /// tab's card show the live content's current frame (`thumbnail` or
     /// `card`) and pausing the live content (it keeps showing that frame):
@@ -152,6 +156,7 @@ extension TabsDataSource {
     public func overviewWillAppear() {}
     public func overviewVisibilityChanged(_ visible: Bool) {}
     public func overviewScrollingChanged(_ scrolling: Bool) {}
+    public func overviewIdleChanged(_ idle: Bool) {}
     public func showStaticCard(for id: TabsKitTab.ID) -> Bool { false }
     public func resumeLiveContent(_ id: TabsKitTab.ID) {}
     public func goBack(_ id: TabsKitTab.ID) {}

Packages/iOS/CmuxTabsKit/Sources/CmuxTabsKit/Logic/OverviewLayout.swift

@@ -121,3 +121,49 @@ struct OverviewLayout: Equatable, Sendable {
     }
 }
 
+
+/// Which grid cards are built (in the view tree), as a collection view keeps
+/// only the cells near the screen: a card costs a full page of content laid
+/// out and scaled, so a grid of 80 tabs never builds 80.
+///
+/// Bands are in screens around the visible rect: cards on screen are needed
+/// at once, cards within `keep` screens are built ahead one per frame (the
+/// nearest first), and a built card is released only past `release`
+/// screens, so scrolling back and forth does not build a card again.
+struct CardResidencyPlan: Equatable, Sendable {
+    var keep: CGFloat = 3
+    var release: CGFloat = 4
+
+    /// What to change for the grid at scroll `offset` with `built` cards.
+    struct Step: Equatable, Sendable {
+        /// Unbuilt cards on screen (build now when the grid must show them).
+        var visible: [Int] = []
+        /// The nearest unbuilt card within the keep band (build next).
+        var next: Int?
+        /// Built cards past the release band.
+        var release: [Int] = []
+    }
+
+    func step(layout: OverviewLayout, offset: CGFloat, isBuilt: (Int) -> Bool) -> Step {
+        let h = layout.size.height
+        let top = max(0, offset)
+        let screen = (min: top, max: top + h)
+        var step = Step()
+        var best: (index: Int, distance: CGFloat)?
+        for i in 0..<layout.count {
+            let r = layout.card(i)
+            let minY = r.minY, maxY = r.maxY + OverviewLayout.titleRow
+            let distance = maxY < screen.min ? screen.min - maxY : minY > screen.max ? minY - screen.max : 0
+            let built = isBuilt(i)
+            if built {
+                if distance > release * h { step.release.append(i) }
+            } else if distance == 0 {
+                step.visible.append(i)
+            } else if distance <= keep * h, distance < (best?.distance ?? .infinity) {
+                best = (i, distance)
+            }
+        }
+        step.next = step.visible.first ?? best?.index
+        return step
+    }
+}

Packages/iOS/CmuxTabsKit/Sources/CmuxTabsKit/UI/CardResidency.swift

@@ -0,0 +1,221 @@
+#if os(iOS)
+import Observation
+import QuartzCore
+import SwiftUI
+
+/// One card's residency: whether its view is in the tree. Each card observes
+/// only its own slot, so building or releasing a card re-runs that card,
+/// never the grid and the other cards.
+@MainActor
+@Observable
+final class CardSlot {
+    var built = false
+}
+
+/// Builds grid cards near the screen and releases far ones
+/// (`CardResidencyPlan`). Cards on screen are built at once while the grid
+/// shows (the zoom lands on real cards, a scroll never shows a blank one);
+/// the rest are built one per frame, nearest first, only while the grid
+/// rests; a hidden grid builds only its on-screen cards, one per frame.
+/// Scrolling never re-runs the grid's body: the offset comes in through
+/// `scrolled(to:)` and changes only the slots that flip.
+@MainActor
+final class CardResidency {
+    private var slots: [String: CardSlot] = [:]
+    private var ids: [String] = []
+    private var layout: OverviewLayout?
+    private var offset: CGFloat = 0
+    private var visible = false
+    private var settled = true
+    private let plan = CardResidencyPlan()
+    private let clock = FrameClock()
+    private var ticking = false
+    /// Cards built so far (tests and the rig's log).
+    private(set) var builds = 0
+    private var building = false { didSet { publishBusy() } }
+    /// The offset changed within the last `restFrames` frames: any scroll,
+    /// a finger's, a deceleration's or one set from code (which the scroll
+    /// phase does not report).
+    private var moving = false { didSet { publishBusy() } }
+    /// Moving or building ahead.
+    private(set) var busy = false
+    /// Scrolled by a finger or a deceleration (the scroll phase).
+    private var scrolling = false
+    /// Whether the grid rests: settled, not scrolling, not moving, nothing
+    /// left to build. Sent to `idleSink` on change; never observed by a
+    /// view, so a scroll that starts or stops re-runs no body.
+    private(set) var idle = false
+    /// Receives idle changes (the data source's `overviewIdleChanged`). Set
+    /// to a closure that holds the source weakly.
+    var idleSink: (Bool) -> Void = { _ in } {
+        // A sink installed after the first update hears the current state.
+        didSet { if idle { idleSink(true) } }
+    }
+    private let motionClock = FrameClock()
+    private var stillFrames = 0
+    /// Frames without an offset change before the grid counts as at rest.
+    static let restFrames = 6
+
+    private func publishBusy() {
+        let now = building || moving
+        guard now != busy else { return }
+        busy = now
+        publishIdle()
+    }
+
+    private func publishIdle() {
+        let now = settled && visible && !scrolling && !busy
+        guard now != idle else { return }
+        idle = now
+        idleSink(now)
+    }
+
+    func setScrolling(_ scrolling: Bool) {
+        self.scrolling = scrolling
+        publishIdle()
+    }
+
+    func slot(_ id: String) -> CardSlot {
+        if let slot = slots[id] { return slot }
+        let slot = CardSlot()
+        slots[id] = slot
+        return slot
+    }
+
+    func update(ids: [String], layout: OverviewLayout) {
+        self.ids = ids
+        self.layout = layout
+        let listed = Set(ids)
+        for id in slots.keys where !listed.contains(id) { slots[id] = nil }
+        reconcile(urgent: visible)
+    }
+
+    func scrolled(to offset: CGFloat) {
+        guard abs(offset - self.offset) > 0.5 else { return }
+        self.offset = offset
+        stillFrames = 0
+        if !moving {
+            moving = true
+            motionClock.start { [weak self] _ in
+                guard let self else { return false }
+                self.stillFrames += 1
+                guard self.stillFrames >= Self.restFrames else { return true }
+                self.moving = false
+                return false
+            }
+        }
+        // A card on screen is never shown blank: built in this frame (the
+        // grid scrolled to reveal the zooming card, or a fling outran the
+        // building ahead).
+        reconcile(urgent: visible)
+    }
+
+    /// The grid is about to show (or was covered): visible cards are built
+    /// now, so the first frame of the zoom shows them; the rest follow.
+    func setVisible(_ visible: Bool) {
+        self.visible = visible
+        reconcile(urgent: visible)
+        publishIdle()
+    }
+
+    func setSettled(_ settled: Bool) {
+        self.settled = settled
+        tick()
+        publishIdle()
+    }
+
+    private func isBuilt(_ index: Int) -> Bool {
+        index < ids.count && slots[ids[index]]?.built == true
+    }
+
+    private func reconcile(urgent: Bool) {
+        guard let layout else { return }
+        let step = plan.step(layout: layout, offset: offset, isBuilt: isBuilt)
+        for i in step.release where i < ids.count { slots[ids[i]]?.built = false }
+        if urgent {
+            for i in step.visible where i < ids.count { build(ids[i]) }
+        }
+        tick()
+    }
+
+    private func build(_ id: String) {
+        let slot = slot(id)
+        guard !slot.built else { return }
+        slot.built = true
+        builds += 1
+    }
+
+    /// One card per frame while there is one to build: the keep band while
+    /// the grid is at rest, only the on-screen cards while it is hidden or
+    /// zooming (they are ready when it opens; nothing else is built then).
+    private func tick() {
+        guard !ticking, nextToBuild() != nil else { return }
+        ticking = true
+        building = true
+        clock.start { [weak self] _ in
+            guard let self, let id = self.nextToBuild() else {
+                self?.ticking = false
+                self?.building = false
+                return false
+            }
+            self.build(id)
+            return true
+        }
+    }
+
+    private func nextToBuild() -> String? {
+        guard let layout else { return nil }
+        let step = plan.step(layout: layout, offset: offset, isBuilt: isBuilt)
+        let next = visible && settled ? step.next : step.visible.first
+        return next.flatMap { $0 < ids.count ? ids[$0] : nil }
+    }
+}
+
+/// A grid card, in the tree only while its slot is built (or a gesture or
+/// the zoom holds it). The card's view is made in this body, so an unbuilt
+/// card costs the grid's body nothing (a built value per card was made for
+/// all 80 cards on every zoom frame). An unbuilt card is still in the
+/// accessibility tree: a bare element in its slot, named after its tab, that
+/// opens it, so swiping through the cards with VoiceOver reaches every tab
+/// (scrolling to one builds it).
+struct ResidentCard<Content: View>: View {
+    let slot: CardSlot
+    let held: Bool
+    let standIn: CardStandIn
+    let content: () -> Content
+
+    init(slot: CardSlot, held: Bool, standIn: CardStandIn, @ViewBuilder content: @escaping () -> Content) {
+        self.slot = slot
+        self.held = held
+        self.standIn = standIn
+        self.content = content
+    }
+
+    var body: some View {
+        if slot.built || held {
+            content()
+        } else {
+            standIn
+        }
+    }
+}
+
+/// An unbuilt card's accessibility element: no pixels, no touches.
+struct CardStandIn: View {
+    var label: String
+    var rect: CGRect
+    var open: () -> Void
+
+    var body: some View {
+        Color.clear
+            .frame(width: rect.width, height: rect.height + OverviewLayout.titleRow)
+            .offset(x: rect.minX, y: rect.minY)
+            .allowsHitTesting(false)
+            .accessibilityElement()
+            .accessibilityLabel(Text(label))
+            .accessibilityAddTraits(.isButton)
+            .accessibilityAction(named: "Open", open)
+            .accessibilityAction(.default, open)
+    }
+}
+#endif