@npaw/forge-react-native 9.6.1

package/ios/ForgeApple/Sources/NPAWForgeCapture/SectionsCapture.swift

@@ -0,0 +1,1176 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: F3 sections capture coordinator plus the UIKit registry/sampler.
+ *               The platform-free coordinator owns the SectionsEngine lifecycle
+ *               (installed while the plan SECTIONS bit is on, knobs hot-applied),
+ *               screen-change flush ordering, SwiftUI snapshot feeds, dwell slot
+ *               arming (tvOS focus and the C2 iPadOS hover seam) including the
+ *               one-shot pending-arm retry consumed by the next full-set feed
+ *               and wiped by dwell clears, and interaction enrichment. The
+ *               UIKit-gated tracker owns weak view registrations
+ *               (explicit Tier 3 API, Tier 1 accessibilityIdentifier markers,
+ *               Tier 2 remote native-id lists), scroll KVO/orientation/foreground
+ *               sampling signals with a 1 s safety timer and 100 ms throttled
+ *               evaluation, per-registration iPadOS hover recognizers hit-testing
+ *               the pointer to tracked items, and window-space visibility
+ *               geometry behind an injectable reader seam.
+ */
+
+import Foundation
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#endif
+#if canImport(UIKit)
+import UIKit
+#endif
+
+/// Owns the sections engine for one automatic-capture handle. Thread-safe:
+/// plan reconciliation and screen changes come from the main thread, feeds
+/// come from samplers/modifiers, and enrichment can come from any caller.
+public final class ForgeSectionsCoordinator {
+    private let lock = NSRecursiveLock()
+    private let emit: SectionsEngine.Emission
+    private let log: (String) -> Void
+    private var scheduler: SectionsScheduling
+    private var engine: SectionsEngine?
+    private var knobs: SectionsKnobs?
+    private var storedNativeSectionIds: Set<String> = []
+    private var storedNativeItemIds: Set<String> = []
+    /// One-shot pending-arm retry slot: a focus/hover arm can race the
+    /// throttled store refresh (the resolved key absent from the engine store
+    /// at arm time, making the engine arm a no-op), so the next full-set feed
+    /// re-issues the arm exactly once after the fresh feed lands. Cleared by
+    /// `clearDwell`/`hoverDidResolve(nil)` and on engine uninstall.
+    private var pendingDwellArmKey: String?
+    /// Discovery-order positions for marker/SwiftUI items that carry no
+    /// explicit position; reset on every screen change.
+    private var assignedPositions: [String: [String: Int]] = [:]
+    /// Persistent SwiftUI snapshot stores, independent of the engine
+    /// lifetime: modifiers feed them at any time (append order preserved for
+    /// first-seen ordering), a fresh engine install seeds from them so
+    /// cold-start feeds arriving before the first plan are not lost, and a
+    /// plan-off uninstall keeps them so a reinstall reseeds still-mounted
+    /// views without waiting for a re-mount.
+    private var swiftuiSectionStore: [SectionSnapshot] = []
+    private var swiftuiItemStore: [ItemSnapshot] = []
+
+    #if canImport(UIKit)
+    /// Public registration facade (Tier 3 explicit tracking). Registrations
+    /// are accepted at any time; sampling runs only while the plan keeps the
+    /// SECTIONS family installed.
+    public private(set) lazy var tracker = ForgeSectionsTracker(coordinator: self)
+    #endif
+
+    init(
+        emit: @escaping SectionsEngine.Emission,
+        log: @escaping (String) -> Void = { message in
+            NSLog("[NPAW-Forge-Apple] [Capture] %@", message)
+        },
+        scheduler: SectionsScheduling = ForgeMainQueueSectionsScheduler()
+    ) {
+        self.emit = emit
+        self.log = log
+        self.scheduler = scheduler
+    }
+
+    var isInstalled: Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return engine != nil
+    }
+
+    var nativeSectionIds: Set<String> {
+        lock.lock()
+        defer { lock.unlock() }
+        return storedNativeSectionIds
+    }
+
+    var nativeItemIds: Set<String> {
+        lock.lock()
+        defer { lock.unlock() }
+        return storedNativeItemIds
+    }
+
+    /// Test seam: swaps the scheduler used for the next engine install.
+    func setSchedulerForTesting(_ scheduler: SectionsScheduling) {
+        lock.lock()
+        self.scheduler = scheduler
+        lock.unlock()
+    }
+
+    /// Plan reconcile: SECTIONS bit on installs the engine (and the UIKit
+    /// sampler), knob changes hot-apply, and bit off uninstalls everything
+    /// and silently resets engine state (the persistent SwiftUI stores are
+    /// kept so a reinstall reseeds still-mounted views). Runs on the main
+    /// thread.
+    func reconcile(features: EffectiveCaptureFeatures) {
+        var activateSampler = false
+        var deactivateSampler = false
+        var engineToSeed: SectionsEngine?
+        var seedSections: [SectionSnapshot] = []
+        var seedItems: [ItemSnapshot] = []
+        lock.lock()
+        if features.sections, let plan = features.sectionsPlan {
+            let newKnobs = SectionsKnobs(plan: plan)
+            storedNativeSectionIds = Set(plan.sectionNativeIds)
+            storedNativeItemIds = Set(plan.itemNativeIds)
+            if let engine {
+                if knobs != newKnobs {
+                    engine.updateKnobs(newKnobs)
+                }
+            } else {
+                let installed = SectionsEngine(knobs: newKnobs, scheduler: scheduler, emit: emit, log: log)
+                engine = installed
+                engineToSeed = installed
+                seedSections = swiftuiSectionStore
+                seedItems = swiftuiItemStore
+                activateSampler = true
+            }
+            knobs = newKnobs
+        } else if engine != nil {
+            engine?.reset()
+            engine = nil
+            knobs = nil
+            assignedPositions.removeAll()
+            pendingDwellArmKey = nil
+            deactivateSampler = true
+        }
+        lock.unlock()
+        // Seed the fresh engine from the persistent SwiftUI stores (outside
+        // the coordinator lock: emissions leave synchronously). Feeds that
+        // arrived while no engine was installed start the visible/impression
+        // flow here instead of waiting for a re-mount.
+        engineToSeed?.apply(source: .swiftui, sections: seedSections, items: seedItems)
+        #if canImport(UIKit)
+        if activateSampler {
+            tracker.activate()
+        }
+        if deactivateSampler {
+            tracker.deactivate()
+        }
+        #endif
+    }
+
+    /// Full teardown for handle uninstall: sampler off, engine silently
+    /// reset, persistent SwiftUI stores dropped.
+    func shutdown() {
+        lock.lock()
+        engine?.reset()
+        engine = nil
+        knobs = nil
+        assignedPositions.removeAll()
+        pendingDwellArmKey = nil
+        swiftuiSectionStore.removeAll()
+        swiftuiItemStore.removeAll()
+        lock.unlock()
+        #if canImport(UIKit)
+        tracker.deactivate()
+        #endif
+    }
+
+    // MARK: - Screen lifecycle
+
+    /// Called before the new screen context lands: flushes
+    /// `raw_section_hidden` for still-visible sections under the OLD screen
+    /// context first, then resets per-screen dedupe/order state.
+    func onScreenWillChange() {
+        lock.lock()
+        assignedPositions.removeAll()
+        let engineRef = engine
+        lock.unlock()
+        engineRef?.onScreenChanged()
+    }
+
+    /// Called after the new screen context is current: re-adopts markers and
+    /// re-emits whatever is visible under the new screen. The engine
+    /// revalidate stays synchronous on the calling thread (it emits from the
+    /// engine stores and preserves the flush-before-re-emit ordering); the
+    /// marker rescan walks UIApplication windows, so off-main callers hop it
+    /// to the main queue instead of doing UIKit work here.
+    func onScreenDidChange() {
+        guard let engineRef = currentEngine() else { return }
+        #if canImport(UIKit)
+        if Thread.isMainThread {
+            tracker.rescanWindowForMarkers()
+            tracker.scheduleEvaluateOnMain()
+        } else {
+            DispatchQueue.main.async { [weak self] in
+                guard let self, self.isInstalled else { return }
+                self.tracker.rescanWindowForMarkers()
+                self.tracker.scheduleEvaluateOnMain()
+            }
+        }
+        #endif
+        engineRef.revalidate()
+    }
+
+    // MARK: - Snapshot feeds
+
+    /// Full-set feed used by the UIKit sampler. After the fresh feed lands,
+    /// the one-shot pending dwell arm is consumed: a focus/hover arm that
+    /// raced the throttled refresh gets exactly one replay (re-arming an
+    /// already-armed key keeps its original deadline).
+    func applyFeed(source: SectionsFeedSource, sections: [SectionSnapshot], items: [ItemSnapshot]) {
+        guard let engineRef = currentEngine() else { return }
+        engineRef.apply(source: source, sections: sections, items: items)
+        lock.lock()
+        let pending = pendingDwellArmKey
+        pendingDwellArmKey = nil
+        lock.unlock()
+        if let pending {
+            engineRef.armDwell(itemKey: pending)
+        }
+    }
+
+    func updateSection(source: SectionsFeedSource, _ section: SectionSnapshot) {
+        if source == .swiftui {
+            mutateSwiftUIStores { sections, _ in
+                if let index = sections.firstIndex(where: { $0.key == section.key }) {
+                    sections[index] = section
+                } else {
+                    sections.append(section)
+                }
+            }
+        }
+        currentEngine()?.update(source: source, section: section)
+    }
+
+    func removeSection(source: SectionsFeedSource, key: String) {
+        if source == .swiftui {
+            mutateSwiftUIStores { sections, _ in
+                sections.removeAll { $0.key == key }
+            }
+        }
+        currentEngine()?.remove(source: source, sectionKey: key)
+    }
+
+    func updateItem(source: SectionsFeedSource, _ item: ItemSnapshot) {
+        if source == .swiftui {
+            mutateSwiftUIStores { _, items in
+                if let index = items.firstIndex(where: { $0.key == item.key }) {
+                    items[index] = item
+                } else {
+                    items.append(item)
+                }
+            }
+        }
+        currentEngine()?.update(source: source, item: item)
+    }
+
+    func removeItem(source: SectionsFeedSource, key: String) {
+        if source == .swiftui {
+            mutateSwiftUIStores { _, items in
+                items.removeAll { $0.key == key }
+            }
+        }
+        currentEngine()?.remove(source: source, itemKey: key)
+    }
+
+    /// Mutates the persistent SwiftUI stores under the coordinator lock. The
+    /// stores always track the latest reported SwiftUI set — with or without
+    /// an installed engine — so they are ready to seed the next install.
+    private func mutateSwiftUIStores(
+        _ body: (inout [SectionSnapshot], inout [ItemSnapshot]) -> Void
+    ) {
+        lock.lock()
+        body(&swiftuiSectionStore, &swiftuiItemStore)
+        lock.unlock()
+    }
+
+    /// Stable discovery-order position for items without an explicit one.
+    func assignedPosition(sectionKey: String, itemKey: String) -> Int {
+        lock.lock()
+        defer { lock.unlock() }
+        var positions = assignedPositions[sectionKey] ?? [:]
+        if let existing = positions[itemKey] {
+            return existing
+        }
+        let next = positions.count
+        positions[itemKey] = next
+        assignedPositions[sectionKey] = positions
+        return next
+    }
+
+    // MARK: - Dwell + enrichment
+
+    /// Arms the single-slot dwell and records the key in the one-shot
+    /// pending-arm slot so the next full-set feed replays an arm that raced
+    /// the throttled store refresh. No-op while the engine is uninstalled.
+    func armDwell(itemKey: String) {
+        lock.lock()
+        let engineRef = engine
+        if engineRef != nil {
+            pendingDwellArmKey = itemKey
+        }
+        lock.unlock()
+        engineRef?.armDwell(itemKey: itemKey)
+    }
+
+    /// Clears the dwell slot AND the pending-arm retry slot (a cleared focus/
+    /// hover must never be resurrected by a later feed).
+    func clearDwell() {
+        lock.lock()
+        pendingDwellArmKey = nil
+        let engineRef = engine
+        lock.unlock()
+        engineRef?.clearDwell()
+    }
+
+    /// C2 iPadOS hover seam: pointer-hover resolution outcome → dwell-slot
+    /// transition. A resolved item key arms the single-slot dwell (the same
+    /// engine path the tvOS focus observer drives); `nil` — hover ended,
+    /// cancelled, or nothing resolvable under the pointer — clears it. The
+    /// engine's supersede + re-verify-at-fire semantics are untouched.
+    /// Platform-free so the decision logic stays testable without UIKit.
+    func hoverDidResolve(itemKey: String?) {
+        if let itemKey {
+            armDwell(itemKey: itemKey)
+        } else {
+            clearDwell()
+        }
+    }
+
+    /// Merges the armed dwell-slot context (section, sectionOrder, contentId,
+    /// position) into interaction data without overwriting caller keys.
+    func enrichFromDwellSlot(into data: inout [String: String]) {
+        guard let fields = currentEngine()?.dwellEnrichment() else { return }
+        for (key, value) in fields where data[key] == nil {
+            data[key] = value
+        }
+    }
+
+    func itemEnrichment(itemKey: String) -> [String: String]? {
+        currentEngine()?.itemEnrichment(itemKey: itemKey)
+    }
+
+    func sectionEnrichment(sectionKey: String) -> [String: String]? {
+        currentEngine()?.sectionEnrichment(sectionKey: sectionKey)
+    }
+
+    #if canImport(UIKit)
+    /// Resolves a view through the registry and merges {section, sectionOrder,
+    /// contentId, position} into interaction data without overwriting caller
+    /// keys. No-op while the sections family is uninstalled.
+    func enrich(view: UIView, into data: inout [String: String]) {
+        guard isInstalled, let fields = tracker.enrichmentFields(for: view) else { return }
+        for (key, value) in fields where data[key] == nil {
+            data[key] = value
+        }
+    }
+    #endif
+
+    private func currentEngine() -> SectionsEngine? {
+        lock.lock()
+        defer { lock.unlock() }
+        return engine
+    }
+}
+
+#if canImport(UIKit)
+
+/// Optional per-index-path metadata for tracked collection/table sections.
+public struct ForgeSectionItemMetadata {
+    public var contentId: String?
+    public var title: String?
+    public var position: Int?
+
+    public init(contentId: String? = nil, title: String? = nil, position: Int? = nil) {
+        self.contentId = contentId
+        self.title = title
+        self.position = position
+    }
+}
+
+/// Injectable window-space visibility seam so tests (and exotic hosts) can
+/// replace the geometry math.
+public protocol SectionsGeometryReading: AnyObject {
+    /// Visible-area ratio 0-100 for a view inside its window; 0 when the view
+    /// is hidden, effectively transparent, zero-sized, or not in a window.
+    func visibilityPct(of view: UIView) -> Int
+}
+
+/// Default geometry: converts bounds to window coordinates, intersects with
+/// the window bounds and every `clipsToBounds` ancestor (visible-area
+/// approximation), and reports 0 for hidden/alpha~0/detached views.
+final class WindowSectionsGeometryReader: SectionsGeometryReading {
+    func visibilityPct(of view: UIView) -> Int {
+        guard let window = view.window, !view.isHidden, view.alpha > 0.05 else { return 0 }
+        let frame = view.convert(view.bounds, to: nil)
+        guard frame.width > 0, frame.height > 0 else { return 0 }
+        var visible = frame.intersection(window.bounds)
+        var ancestor = view.superview
+        while let current = ancestor, current !== window {
+            if current.isHidden || current.alpha <= 0.05 { return 0 }
+            if current.clipsToBounds {
+                visible = visible.intersection(current.convert(current.bounds, to: nil))
+            }
+            if visible.isNull || visible.isEmpty { return 0 }
+            ancestor = current.superview
+        }
+        guard !visible.isNull, !visible.isEmpty else { return 0 }
+        let ratio = (visible.width * visible.height) / (frame.width * frame.height)
+        return max(0, min(100, Int((ratio * 100).rounded())))
+    }
+}
+
+/// Bounded traversal limits for marker adoption and per-section item scans.
+/// Every scan visits at most ``maxNodes`` views and descends at most
+/// ``maxDepth`` levels, so pathological hierarchies cannot stall the sampler.
+enum SectionsScanBounds {
+    static let maxDepth = 20
+    static let maxNodes = 1500
+}
+
+/// UIKit registry + sampler for the sections engine. Main-thread affine like
+/// the rest of the UIKit capture surface: call the public API on main.
+/// Registrations are weak (`NSMapTable.weakToStrongObjects`), sampling reads
+/// `indexPathsForVisibleItems`/`indexPathsForVisibleRows` at evaluate time
+/// (no delegate proxying, no swizzling), and all observation tokens are owned
+/// by the registration/sampler so deactivation is deallocate-safe.
+public final class ForgeSectionsTracker {
+    private static let evaluateThrottleMs: Int64 = 100
+
+    private final class Registration {
+        let key: String
+        weak var view: UIView?
+        var name: String
+        var order: Int?
+        var itemMetadata: ((IndexPath) -> ForgeSectionItemMetadata?)?
+        var offsetObservation: NSKeyValueObservation?
+        /// C2 iPadOS hover recognizer owned by the registration (installed on
+        /// the section container while the sampler is active; removed on
+        /// untrack/deactivate). Stored as the base class so tvOS — where
+        /// `UIHoverGestureRecognizer` does not exist — compiles unchanged.
+        var hoverRecognizer: UIGestureRecognizer?
+        let adopted: Bool
+
+        init(
+            key: String,
+            view: UIView,
+            name: String,
+            order: Int?,
+            itemMetadata: ((IndexPath) -> ForgeSectionItemMetadata?)?,
+            adopted: Bool
+        ) {
+            self.key = key
+            self.view = view
+            self.name = name
+            self.order = order
+            self.itemMetadata = itemMetadata
+            self.adopted = adopted
+        }
+    }
+
+    private final class OrphanItem {
+        let key: String
+        weak var view: UIView?
+        let contentId: String
+        let markerPosition: Int?
+
+        init(key: String, view: UIView, contentId: String, markerPosition: Int?) {
+            self.key = key
+            self.view = view
+            self.contentId = contentId
+            self.markerPosition = markerPosition
+        }
+    }
+
+    struct ResolvedItem {
+        let itemKey: String
+        let sectionKey: String?
+        let sectionName: String?
+        let sectionOrder: Int?
+        let contentId: String?
+        let position: Int?
+    }
+
+    private weak var coordinator: ForgeSectionsCoordinator?
+    /// Weak-keyed registration lookup: dead views drop their entries.
+    private let registrationMap = NSMapTable<UIView, Registration>.weakToStrongObjects()
+    /// Deterministic sampling order; compacted when weak views die.
+    private var orderedRegistrations: [Registration] = []
+    private var orphanItems: [OrphanItem] = []
+    private var notificationTokens: [NSObjectProtocol] = []
+    private var safetyTimer: DispatchSourceTimer?
+    private var lastEvaluateAtMs: Int64 = 0
+    private var evaluatePending = false
+    private var appActive = true
+    private(set) var active = false
+
+    /// Injectable geometry seam; replace before activation for custom hosts.
+    public var geometryReader: SectionsGeometryReading = WindowSectionsGeometryReader()
+
+    #if os(iOS)
+    /// NSObject action target relaying hover gestures into the non-NSObject
+    /// tracker. The recognizer retains the relay while the relay holds the
+    /// tracker weakly, so no retain cycle can form through the view.
+    private final class HoverRelay: NSObject {
+        private weak var tracker: ForgeSectionsTracker?
+
+        init(tracker: ForgeSectionsTracker) {
+            self.tracker = tracker
+        }
+
+        @objc func handleHover(_ recognizer: UIHoverGestureRecognizer) {
+            tracker?.handleHover(recognizer)
+        }
+    }
+
+    private lazy var hoverRelay = HoverRelay(tracker: self)
+    #endif
+
+    init(coordinator: ForgeSectionsCoordinator) {
+        self.coordinator = coordinator
+    }
+
+    deinit {
+        // Deallocate-safe teardown: KVO invalidation, dispatch-source cancel,
+        // and NotificationCenter removal are all thread-safe.
+        orderedRegistrations.forEach { $0.offsetObservation?.invalidate() }
+        safetyTimer?.cancel()
+        notificationTokens.forEach(NotificationCenter.default.removeObserver)
+    }
+
+    // MARK: - Public registration API (Tier 3)
+
+    /// Tracks any container view as a section.
+    public func track(view: UIView, name: String, order: Int? = nil) {
+        register(view: view, name: name, order: order, itemMetadata: nil, adopted: false)
+    }
+
+    /// Tracks a collection view; visible cells become items at sample time.
+    public func track(
+        collectionView: UICollectionView,
+        name: String,
+        order: Int? = nil,
+        itemMetadata: ((IndexPath) -> ForgeSectionItemMetadata?)? = nil
+    ) {
+        register(view: collectionView, name: name, order: order, itemMetadata: itemMetadata, adopted: false)
+    }
+
+    /// Tracks a table view; visible rows become items at sample time.
+    public func track(
+        tableView: UITableView,
+        name: String,
+        order: Int? = nil,
+        itemMetadata: ((IndexPath) -> ForgeSectionItemMetadata?)? = nil
+    ) {
+        register(view: tableView, name: name, order: order, itemMetadata: itemMetadata, adopted: false)
+    }
+
+    /// Stops tracking a previously registered section view.
+    public func untrack(view: UIView) {
+        if let registration = registrationMap.object(forKey: view) {
+            registration.offsetObservation?.invalidate()
+            registration.offsetObservation = nil
+            removeHoverRecognizer(for: registration)
+            registrationMap.removeObject(forKey: view)
+            orderedRegistrations.removeAll { $0 === registration }
+        }
+        updateTimerState()
+        scheduleEvaluateOnMain()
+    }
+
+    // MARK: - Sampler lifecycle (driven by the coordinator)
+
+    func activate() {
+        guard !active else { return }
+        active = true
+        appActive = currentAppActive()
+        installNotifications()
+        for registration in orderedRegistrations {
+            installScrollObservation(for: registration)
+            installHoverRecognizer(for: registration)
+        }
+        rescanWindowForMarkers()
+        updateTimerState()
+        scheduleEvaluateOnMain()
+    }
+
+    func deactivate() {
+        guard active else { return }
+        active = false
+        notificationTokens.forEach(NotificationCenter.default.removeObserver)
+        notificationTokens.removeAll()
+        for registration in orderedRegistrations {
+            registration.offsetObservation?.invalidate()
+            registration.offsetObservation = nil
+            removeHoverRecognizer(for: registration)
+        }
+        // Purge dead registrations now: this also releases their integrator
+        // metadata closures instead of leaving them reachable through the
+        // weak map until its next internal rehash. (The one-shot pending
+        // dwell arm lives in the coordinator and clears on engine uninstall.)
+        compactRegistrations()
+        stopTimer()
+        evaluatePending = false
+    }
+
+    // MARK: - Marker adoption (Tier 1 + Tier 2)
+
+    /// Bounded key-window scan (at install and screen change) adopting
+    /// standalone `forge-section:` containers, native-id sections, and orphan
+    /// `forge-item:` views living outside every registered section.
+    func rescanWindowForMarkers() {
+        guard active, let coordinator, coordinator.isInstalled else { return }
+        guard let window = keyWindow() else { return }
+        let sectionIds = coordinator.nativeSectionIds
+        let itemIds = coordinator.nativeItemIds
+        orphanItems.removeAll { $0.view == nil }
+        var visited = 0
+        var queue: [(view: UIView, depth: Int)] = [(window, 0)]
+        while !queue.isEmpty, visited < SectionsScanBounds.maxNodes {
+            let (view, depth) = queue.removeFirst()
+            visited += 1
+            switch ForgeSectionMarkerParser.classify(
+                identifier: view.accessibilityIdentifier,
+                sectionNativeIds: sectionIds,
+                itemNativeIds: itemIds
+            ) {
+            case let .section(name, order):
+                if registrationMap.object(forKey: view) == nil {
+                    register(view: view, name: name, order: order, itemMetadata: nil, adopted: true)
+                }
+            case let .item(contentId, position):
+                if let contentId,
+                   enclosingRegisteredSection(of: view) == nil,
+                   !orphanItems.contains(where: { $0.view === view }) {
+                    orphanItems.append(OrphanItem(
+                        key: Self.orphanItemKey(contentId: contentId, view: view),
+                        view: view,
+                        contentId: contentId,
+                        markerPosition: position
+                    ))
+                }
+            case nil:
+                break
+            }
+            if depth < SectionsScanBounds.maxDepth {
+                for subview in view.subviews {
+                    queue.append((subview, depth + 1))
+                }
+            }
+        }
+        updateTimerState()
+    }
+
+    // MARK: - Evaluation
+
+    func scheduleEvaluateOnMain() {
+        if Thread.isMainThread {
+            throttledEvaluate()
+        } else {
+            DispatchQueue.main.async { [weak self] in
+                self?.throttledEvaluate()
+            }
+        }
+    }
+
+    private func throttledEvaluate() {
+        guard active else { return }
+        let now = ForgeClock.elapsedRealtimeMs()
+        let elapsed = now - lastEvaluateAtMs
+        if elapsed >= Self.evaluateThrottleMs {
+            lastEvaluateAtMs = now
+            evaluate()
+        } else if !evaluatePending {
+            evaluatePending = true
+            let delayMs = Int(max(1, Self.evaluateThrottleMs - elapsed))
+            DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(delayMs)) { [weak self] in
+                guard let self, self.evaluatePending else { return }
+                self.evaluatePending = false
+                self.lastEvaluateAtMs = ForgeClock.elapsedRealtimeMs()
+                self.evaluate()
+            }
+        }
+    }
+
+    private func evaluate() {
+        guard active, let coordinator, coordinator.isInstalled else { return }
+        compactRegistrations()
+        var sections: [SectionSnapshot] = []
+        var items: [ItemSnapshot] = []
+        for registration in orderedRegistrations {
+            guard let view = registration.view else { continue }
+            if registration.offsetObservation == nil {
+                installScrollObservation(for: registration)
+            }
+            let pct = geometryReader.visibilityPct(of: view)
+            let itemCount = sampleItems(for: registration, view: view, into: &items)
+            sections.append(SectionSnapshot(
+                key: registration.key,
+                name: registration.name,
+                order: registration.order,
+                visibilityPct: pct,
+                itemCount: itemCount
+            ))
+        }
+        let hadOrphans = !orphanItems.isEmpty
+        orphanItems.removeAll { $0.view == nil }
+        if hadOrphans, orphanItems.isEmpty {
+            // The last orphan died: without this, a target-less tracker keeps
+            // the 1 s safety timer ticking until the next explicit signal.
+            updateTimerState()
+        }
+        for orphan in orphanItems {
+            guard let view = orphan.view else { continue }
+            items.append(ItemSnapshot(
+                key: orphan.key,
+                contentId: orphan.contentId,
+                position: orphan.markerPosition
+                    ?? coordinator.assignedPosition(sectionKey: "orphan", itemKey: orphan.key),
+                sectionKey: nil,
+                visibilityPct: geometryReader.visibilityPct(of: view)
+            ))
+        }
+        // The coordinator applies the feed and then consumes its one-shot
+        // pending dwell arm, replaying a focus/hover arm that raced the
+        // throttled refresh exactly once.
+        coordinator.applyFeed(source: .uikit, sections: sections, items: items)
+    }
+
+    private func sampleItems(for registration: Registration, view: UIView, into items: inout [ItemSnapshot]) -> Int {
+        var count = 0
+        if let collectionView = view as? UICollectionView {
+            for indexPath in collectionView.indexPathsForVisibleItems.sorted() {
+                guard let cell = collectionView.cellForItem(at: indexPath) else { continue }
+                items.append(itemSnapshot(for: cell, indexPath: indexPath, registration: registration))
+                count += 1
+            }
+            return count
+        }
+        if let tableView = view as? UITableView {
+            for indexPath in tableView.indexPathsForVisibleRows ?? [] {
+                guard let cell = tableView.cellForRow(at: indexPath) else { continue }
+                items.append(itemSnapshot(for: cell, indexPath: indexPath, registration: registration))
+                count += 1
+            }
+            return count
+        }
+        // Plain container: bounded subtree scan for marker/native-id items.
+        guard let coordinator else { return 0 }
+        let itemIds = coordinator.nativeItemIds
+        var visited = 0
+        var queue: [(view: UIView, depth: Int)] = view.subviews.map { ($0, 1) }
+        while !queue.isEmpty, visited < SectionsScanBounds.maxNodes {
+            let (candidate, depth) = queue.removeFirst()
+            visited += 1
+            if case let .item(contentId, markerPosition) = ForgeSectionMarkerParser.classify(
+                identifier: candidate.accessibilityIdentifier,
+                sectionNativeIds: [],
+                itemNativeIds: itemIds
+            ), let contentId {
+                let key = "\(registration.key)#\(contentId)"
+                items.append(ItemSnapshot(
+                    key: key,
+                    contentId: contentId,
+                    position: markerPosition
+                        ?? coordinator.assignedPosition(sectionKey: registration.key, itemKey: key),
+                    sectionKey: registration.key,
+                    visibilityPct: geometryReader.visibilityPct(of: candidate)
+                ))
+                count += 1
+            }
+            if depth < SectionsScanBounds.maxDepth {
+                for subview in candidate.subviews {
+                    queue.append((subview, depth + 1))
+                }
+            }
+        }
+        return count
+    }
+
+    private func itemSnapshot(for cell: UIView, indexPath: IndexPath, registration: Registration) -> ItemSnapshot {
+        let metadata = registration.itemMetadata?(indexPath)
+        let marker = cellMarker(for: cell)
+        let contentId = metadata?.contentId ?? marker?.contentId
+        let position = metadata?.position ?? marker?.position ?? indexPath.item
+        return ItemSnapshot(
+            key: "\(registration.key)#\(indexPath.section).\(indexPath.item)",
+            contentId: contentId,
+            position: position,
+            sectionKey: registration.key,
+            visibilityPct: geometryReader.visibilityPct(of: cell),
+            title: metadata?.title
+        )
+    }
+
+    private func cellMarker(for cell: UIView) -> (contentId: String?, position: Int?)? {
+        guard let coordinator else { return nil }
+        let itemIds = coordinator.nativeItemIds
+        let identifiers = [cell.accessibilityIdentifier, cell.subviews.first?.accessibilityIdentifier]
+        for identifier in identifiers {
+            if case let .item(contentId, position) = ForgeSectionMarkerParser.classify(
+                identifier: identifier,
+                sectionNativeIds: [],
+                itemNativeIds: itemIds
+            ) {
+                return (contentId, position)
+            }
+        }
+        return nil
+    }
+
+    // MARK: - Focus dwell + enrichment resolution
+
+    private func handleFocusUpdate(_ note: Notification) {
+        guard active, let coordinator, coordinator.isInstalled else { return }
+        let context = note.userInfo?[UIFocusSystem.focusUpdateContextUserInfoKey] as? UIFocusUpdateContext
+        let focusedView = (context?.nextFocusedItem as? UIView) ?? context?.nextFocusedView
+        guard let focusedView, let resolved = resolveItem(for: focusedView) else {
+            coordinator.clearDwell()
+            return
+        }
+        // Arm first (the coordinator records the one-shot pending arm), then
+        // refresh the store so the dwell re-verify at fire sees the item; if
+        // the key was still absent at arm time, the next evaluate's feed
+        // replays the arm once from the coordinator's pending slot.
+        coordinator.armDwell(itemKey: resolved.itemKey)
+        scheduleEvaluateOnMain()
+    }
+
+    /// {section, sectionOrder, contentId, position} for a resolved view, from
+    /// the engine store when available and directly from the registry as a
+    /// fallback before the first evaluate.
+    func enrichmentFields(for view: UIView) -> [String: String]? {
+        guard let coordinator else { return nil }
+        if let resolved = resolveItem(for: view) {
+            if let fields = coordinator.itemEnrichment(itemKey: resolved.itemKey) {
+                return fields
+            }
+            var fields: [String: String] = [:]
+            if let sectionKey = resolved.sectionKey {
+                if let sectionFields = coordinator.sectionEnrichment(sectionKey: sectionKey) {
+                    fields.merge(sectionFields) { current, _ in current }
+                } else if let name = resolved.sectionName {
+                    fields["section"] = name
+                    if let order = resolved.sectionOrder {
+                        fields["sectionOrder"] = String(order)
+                    }
+                }
+            }
+            if let contentId = resolved.contentId {
+                fields["contentId"] = contentId
+            }
+            fields["position"] = String(resolved.position ?? 0)
+            return fields
+        }
+        if let registration = enclosingRegisteredSection(of: view) {
+            if let fields = coordinator.sectionEnrichment(sectionKey: registration.key) {
+                return fields
+            }
+            var fields = ["section": registration.name]
+            if let order = registration.order {
+                fields["sectionOrder"] = String(order)
+            }
+            return fields
+        }
+        return nil
+    }
+
+    private func resolveItem(for view: UIView) -> ResolvedItem? {
+        guard let coordinator else { return nil }
+        let itemIds = coordinator.nativeItemIds
+        var current: UIView? = view
+        while let candidate = current {
+            if let cell = candidate as? UICollectionViewCell,
+               let collectionView = enclosingView(of: cell, as: UICollectionView.self),
+               let registration = registrationMap.object(forKey: collectionView),
+               let indexPath = collectionView.indexPath(for: cell) {
+                let metadata = registration.itemMetadata?(indexPath)
+                return ResolvedItem(
+                    itemKey: "\(registration.key)#\(indexPath.section).\(indexPath.item)",
+                    sectionKey: registration.key,
+                    sectionName: registration.name,
+                    sectionOrder: registration.order,
+                    contentId: metadata?.contentId ?? cellMarker(for: cell)?.contentId,
+                    position: metadata?.position ?? indexPath.item
+                )
+            }
+            if let cell = candidate as? UITableViewCell,
+               let tableView = enclosingView(of: cell, as: UITableView.self),
+               let registration = registrationMap.object(forKey: tableView),
+               let indexPath = tableView.indexPath(for: cell) {
+                let metadata = registration.itemMetadata?(indexPath)
+                return ResolvedItem(
+                    itemKey: "\(registration.key)#\(indexPath.section).\(indexPath.item)",
+                    sectionKey: registration.key,
+                    sectionName: registration.name,
+                    sectionOrder: registration.order,
+                    contentId: metadata?.contentId ?? cellMarker(for: cell)?.contentId,
+                    position: metadata?.position ?? indexPath.row
+                )
+            }
+            if case let .item(contentId, markerPosition) = ForgeSectionMarkerParser.classify(
+                identifier: candidate.accessibilityIdentifier,
+                sectionNativeIds: [],
+                itemNativeIds: itemIds
+            ), let contentId {
+                if let registration = enclosingRegisteredSection(of: candidate) {
+                    let key = "\(registration.key)#\(contentId)"
+                    return ResolvedItem(
+                        itemKey: key,
+                        sectionKey: registration.key,
+                        sectionName: registration.name,
+                        sectionOrder: registration.order,
+                        contentId: contentId,
+                        position: markerPosition
+                    )
+                }
+                return ResolvedItem(
+                    itemKey: Self.orphanItemKey(contentId: contentId, view: candidate),
+                    sectionKey: nil,
+                    sectionName: nil,
+                    sectionOrder: nil,
+                    contentId: contentId,
+                    position: markerPosition
+                )
+            }
+            current = candidate.superview
+        }
+        return nil
+    }
+
+    private func enclosingRegisteredSection(of view: UIView) -> Registration? {
+        var current: UIView? = view.superview
+        while let candidate = current {
+            if let registration = registrationMap.object(forKey: candidate) {
+                return registration
+            }
+            current = candidate.superview
+        }
+        return nil
+    }
+
+    /// Orphan item keys carry the marked view's identity so two orphan views
+    /// sharing a contentId never collide on the same engine key. The suffix
+    /// is process-stable, and the scan and resolve paths derive it from the
+    /// same view instance, so enrichment lookups keep matching the feed.
+    private static func orphanItemKey(contentId: String, view: UIView) -> String {
+        "orphan#\(contentId)#\(String(UInt(bitPattern: ObjectIdentifier(view)), radix: 16))"
+    }
+
+    private func enclosingView<T: UIView>(of view: UIView, as type: T.Type) -> T? {
+        var current: UIView? = view.superview
+        while let candidate = current {
+            if let match = candidate as? T {
+                return match
+            }
+            current = candidate.superview
+        }
+        return nil
+    }
+
+    // MARK: - Registration internals
+
+    private func register(
+        view: UIView,
+        name: String,
+        order: Int?,
+        itemMetadata: ((IndexPath) -> ForgeSectionItemMetadata?)?,
+        adopted: Bool
+    ) {
+        if let existing = registrationMap.object(forKey: view) {
+            existing.name = name
+            existing.order = order ?? existing.order
+            if let itemMetadata {
+                existing.itemMetadata = itemMetadata
+            }
+        } else {
+            let registration = Registration(
+                key: "section-\(UUID().uuidString)",
+                view: view,
+                name: name,
+                order: order,
+                itemMetadata: itemMetadata,
+                adopted: adopted
+            )
+            registrationMap.setObject(registration, forKey: view)
+            orderedRegistrations.append(registration)
+            if active {
+                installScrollObservation(for: registration)
+                installHoverRecognizer(for: registration)
+            }
+        }
+        updateTimerState()
+        scheduleEvaluateOnMain()
+    }
+
+    private func compactRegistrations() {
+        let dead = orderedRegistrations.filter { $0.view == nil }
+        guard !dead.isEmpty else { return }
+        dead.forEach {
+            $0.offsetObservation?.invalidate()
+            $0.offsetObservation = nil
+            // The recognizer died with its weak view; drop the reference.
+            $0.hoverRecognizer = nil
+            // NSMapTable can keep the dead registration shell alive until its
+            // next internal rehash: release the integrator's metadata closure
+            // now so a dead view-controller graph does not stay reachable.
+            $0.itemMetadata = nil
+        }
+        orderedRegistrations.removeAll { $0.view == nil }
+        updateTimerState()
+    }
+
+    private func installScrollObservation(for registration: Registration) {
+        guard active, registration.offsetObservation == nil, let view = registration.view else { return }
+        let scrollView = (view as? UIScrollView) ?? enclosingView(of: view, as: UIScrollView.self)
+        guard let scrollView else { return }
+        registration.offsetObservation = scrollView.observe(\.contentOffset, options: [.new]) { [weak self] _, _ in
+            self?.scheduleEvaluateOnMain()
+        }
+    }
+
+    // MARK: - Hover dwell (C2, iPadOS pointer/trackpad/pencil)
+
+    #if os(iOS)
+    /// Attaches one `UIHoverGestureRecognizer` to the registered section
+    /// container. The recognizer only fires for hover-capable pointers
+    /// (trackpad/pencil), so no capability check is needed; on touch-only
+    /// devices it simply never fires. tvOS keeps the focus-engine path
+    /// (`UIHoverGestureRecognizer` is iOS-only).
+    private func installHoverRecognizer(for registration: Registration) {
+        guard active, registration.hoverRecognizer == nil, let view = registration.view else { return }
+        let recognizer = UIHoverGestureRecognizer(
+            target: hoverRelay,
+            action: #selector(HoverRelay.handleHover(_:))
+        )
+        // Hover never involves touches; stay inert for the app's gestures.
+        recognizer.cancelsTouchesInView = false
+        view.addGestureRecognizer(recognizer)
+        registration.hoverRecognizer = recognizer
+    }
+
+    /// C2 hover handler: hit-tests the pointer location inside the section
+    /// container to the deepest tracked item (the same registry resolution
+    /// the click/dwell enrichment uses) and drives the coordinator's hover
+    /// seam — arm on a resolved item, clear on hover end or when nothing
+    /// tracked is under the pointer. Engine semantics (single-slot supersede,
+    /// re-verify at fire, per-screen dedupe) are reused unchanged.
+    fileprivate func handleHover(_ recognizer: UIHoverGestureRecognizer) {
+        guard active, let coordinator, coordinator.isInstalled else { return }
+        guard let containerView = recognizer.view else {
+            coordinator.hoverDidResolve(itemKey: nil)
+            return
+        }
+        switch recognizer.state {
+        case .began, .changed:
+            let location = recognizer.location(in: containerView)
+            let hitView = containerView.hitTest(location, with: nil)
+            let resolved = hitView.flatMap { resolveItem(for: $0) }
+            // Arm/clear first (the coordinator owns the one-shot pending-arm
+            // slot), then refresh the store so the dwell re-verify at fire
+            // sees the item (same ordering as the tvOS focus observer); the
+            // next evaluate's feed replays the arm once if the key was still
+            // absent at arm time.
+            coordinator.hoverDidResolve(itemKey: resolved?.itemKey)
+            if resolved != nil {
+                scheduleEvaluateOnMain()
+            }
+        default:
+            coordinator.hoverDidResolve(itemKey: nil)
+        }
+    }
+    #else
+    /// tvOS (and any other non-iOS UIKit host): hover dwell does not exist;
+    /// the focus observer drives the dwell slot instead.
+    private func installHoverRecognizer(for registration: Registration) {}
+    #endif
+
+    /// Detaches a registration's hover recognizer. Compiles on tvOS as a
+    /// data-only cleanup (the recognizer is never installed there).
+    private func removeHoverRecognizer(for registration: Registration) {
+        guard let recognizer = registration.hoverRecognizer else { return }
+        registration.view?.removeGestureRecognizer(recognizer)
+        registration.hoverRecognizer = nil
+    }
+
+    // MARK: - Signals
+
+    private func installNotifications() {
+        let center = NotificationCenter.default
+        notificationTokens.append(center.addObserver(
+            forName: UIApplication.didBecomeActiveNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            self?.appActive = true
+            self?.updateTimerState()
+            self?.scheduleEvaluateOnMain()
+        })
+        notificationTokens.append(center.addObserver(
+            forName: UIApplication.willResignActiveNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            self?.appActive = false
+            self?.updateTimerState()
+        })
+        #if os(iOS)
+        notificationTokens.append(center.addObserver(
+            forName: UIDevice.orientationDidChangeNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            self?.scheduleEvaluateOnMain()
+        })
+        #endif
+        notificationTokens.append(center.addObserver(
+            forName: UIFocusSystem.didUpdateNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] note in
+            self?.handleFocusUpdate(note)
+        })
+    }
+
+    /// 1 s repeating safety timer covering layout changes without scroll;
+    /// runs only while at least one section/orphan is tracked, the app is
+    /// active, and the sections family is installed.
+    private func updateTimerState() {
+        let hasTargets = !orderedRegistrations.isEmpty || !orphanItems.isEmpty
+        let shouldRun = active && appActive && hasTargets && (coordinator?.isInstalled ?? false)
+        if shouldRun, safetyTimer == nil {
+            let timer = DispatchSource.makeTimerSource(queue: .main)
+            timer.schedule(deadline: .now() + 1.0, repeating: 1.0, leeway: .milliseconds(200))
+            timer.setEventHandler { [weak self] in
+                self?.scheduleEvaluateOnMain()
+            }
+            timer.resume()
+            safetyTimer = timer
+        } else if !shouldRun {
+            stopTimer()
+        }
+    }
+
+    private func stopTimer() {
+        safetyTimer?.cancel()
+        safetyTimer = nil
+    }
+
+    private func currentAppActive() -> Bool {
+        if Thread.isMainThread {
+            return UIApplication.shared.applicationState == .active
+        }
+        return true
+    }
+
+    private func keyWindow() -> UIWindow? {
+        let windows = UIApplication.shared.connectedScenes
+            .compactMap { $0 as? UIWindowScene }
+            .flatMap(\.windows)
+        return windows.first(where: \.isKeyWindow) ?? windows.first
+    }
+}
+
+#endif