@npaw/forge-react-native 9.6.1

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

@@ -0,0 +1,674 @@
+/**
+ * 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: Platform-free F3 sections auto-capture state machine. Consumes
+ *               section/item visibility snapshots from UIKit/SwiftUI samplers and
+ *               emits raw_section_visible/raw_section_hidden pairs, sustained
+ *               raw_content_impression confirmations, and focus-driven
+ *               raw_content_dwell events through an injected emission closure.
+ *               Time and timers flow through an injectable scheduler seam so
+ *               tests control the clock; dedupe, caps, and ordering follow the
+ *               cross-platform F3 parity rules (hidden-flush before dedupe reset
+ *               on screen change, explicit order over first-seen order, and
+ *               visibility percentages sampled at confirmation time).
+ */
+
+import Foundation
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#endif
+
+/// Injectable clock + one-shot timer seam for the sections engine. Production
+/// uses ``ForgeMainQueueSectionsScheduler``; tests drive a manual clock.
+public protocol SectionsScheduling: AnyObject {
+    func nowMs() -> Int64
+    @discardableResult
+    func schedule(afterMs: Int64, _ block: @escaping () -> Void) -> SectionsScheduledTask
+}
+
+/// Cancellable handle for a scheduled sections callback.
+public protocol SectionsScheduledTask: AnyObject {
+    func cancel()
+}
+
+/// Default production scheduler: wall clock plus main-queue one-shot timers.
+public final class ForgeMainQueueSectionsScheduler: SectionsScheduling {
+    public init() {}
+
+    public func nowMs() -> Int64 {
+        ForgeClock.nowMs()
+    }
+
+    @discardableResult
+    public func schedule(afterMs: Int64, _ block: @escaping () -> Void) -> SectionsScheduledTask {
+        let work = DispatchWorkItem(block: block)
+        let delayMs = Int(clamping: max(0, afterMs))
+        DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(delayMs), execute: work)
+        return WorkItemTask(work: work)
+    }
+
+    private final class WorkItemTask: SectionsScheduledTask {
+        private let work: DispatchWorkItem
+
+        init(work: DispatchWorkItem) {
+            self.work = work
+        }
+
+        func cancel() {
+            work.cancel()
+        }
+    }
+}
+
+/// Engine knobs mapped from the kernel capture plan sections block. Values are
+/// clamped into safe ranges so a hostile plan cannot produce negative timers.
+public struct SectionsKnobs: Equatable {
+    public var visibilityThresholdPct: Int
+    public var impressionMinVisibleMs: Int64
+    public var dwellMs: Int64
+    public var maxTrackedItems: Int
+    public var maxSections: Int
+
+    public init(
+        visibilityThresholdPct: Int = 50,
+        impressionMinVisibleMs: Int64 = 1000,
+        dwellMs: Int64 = 1000,
+        maxTrackedItems: Int = 200,
+        maxSections: Int = 20
+    ) {
+        self.visibilityThresholdPct = min(100, max(0, visibilityThresholdPct))
+        self.impressionMinVisibleMs = max(0, impressionMinVisibleMs)
+        self.dwellMs = max(0, dwellMs)
+        self.maxTrackedItems = max(0, maxTrackedItems)
+        self.maxSections = max(0, maxSections)
+    }
+
+    public init(plan: ForgeCapturePlan.Sections) {
+        self.init(
+            visibilityThresholdPct: plan.visibilityThresholdPct,
+            impressionMinVisibleMs: plan.impressionMinVisibleMs,
+            dwellMs: plan.dwellMs,
+            maxTrackedItems: plan.maxTrackedItems,
+            maxSections: plan.maxSections
+        )
+    }
+}
+
+/// Origin of a snapshot feed. Each source owns its reported set: a section or
+/// item disappears when its source stops reporting it (full-set `apply`) or
+/// removes it explicitly (SwiftUI `onDisappear`).
+public enum SectionsFeedSource: String, CaseIterable {
+    case uikit
+    case swiftui
+}
+
+/// Latest observed state of one section container.
+public struct SectionSnapshot: Equatable {
+    public var key: String
+    public var name: String
+    /// Explicit order from registration/marker; `nil` uses first-seen order.
+    public var order: Int?
+    /// Visible-area ratio 0-100.
+    public var visibilityPct: Int
+    /// Sampler-known visible item count; the engine emits the maximum of this
+    /// value and the item count it derives from its own item store.
+    public var itemCount: Int
+
+    public init(key: String, name: String, order: Int?, visibilityPct: Int, itemCount: Int) {
+        self.key = key
+        self.name = name
+        self.order = order
+        self.visibilityPct = visibilityPct
+        self.itemCount = itemCount
+    }
+}
+
+/// Latest observed state of one content item.
+public struct ItemSnapshot: Equatable {
+    public var key: String
+    public var contentId: String?
+    public var position: Int
+    public var sectionKey: String?
+    /// Visible-area ratio 0-100.
+    public var visibilityPct: Int
+    public var title: String?
+
+    public init(
+        key: String,
+        contentId: String?,
+        position: Int,
+        sectionKey: String?,
+        visibilityPct: Int,
+        title: String? = nil
+    ) {
+        self.key = key
+        self.contentId = contentId
+        self.position = position
+        self.sectionKey = sectionKey
+        self.visibilityPct = visibilityPct
+        self.title = title
+    }
+}
+
+/// Pure sections state machine (no UIKit): visible/hidden pairing, sustained
+/// impressions, single-slot dwell, per-screen dedupe, and capped tracking.
+/// All emissions leave through the injected closure outside the internal lock.
+public final class SectionsEngine {
+    public typealias Emission = (_ kind: String, _ params: [String: String]) -> Void
+
+    private struct SectionRuntime {
+        var name: String
+        var order: Int
+        var visibleEmitted: Bool
+    }
+
+    private struct ImpressionCandidate {
+        let armedAtMs: Int64
+        /// Dedupe key captured at arm time so section-state changes between
+        /// arm and fire cannot drift the key and double-fire.
+        let dedupeKey: String
+        let task: SectionsScheduledTask
+    }
+
+    private struct DwellSlot {
+        let itemKey: String
+        let armedAtMs: Int64
+        /// Dedupe key captured at arm time (same drift protection as
+        /// impressions).
+        let dedupeKey: String
+        let task: SectionsScheduledTask
+    }
+
+    private let lock = NSRecursiveLock()
+    private let scheduler: SectionsScheduling
+    private let emitClosure: Emission
+    private let logClosure: (String) -> Void
+    private var knobs: SectionsKnobs
+
+    private var sectionFeeds: [SectionsFeedSource: [SectionSnapshot]] = [:]
+    private var itemFeeds: [SectionsFeedSource: [ItemSnapshot]] = [:]
+    private var sectionStates: [String: SectionRuntime] = [:]
+    private var nextFirstSeenOrder = 0
+    private var impressionCandidates: [String: ImpressionCandidate] = [:]
+    private var firedImpressionKeys: Set<String> = []
+    /// Per-screen dedupe keys frozen at first dedupe-relevant use per item, so
+    /// a late-registering section cannot drift `"|id"` into `"Rail|id"` and
+    /// re-fire an already-counted impression/dwell for the same item.
+    private var capturedDedupeKeys: [String: String] = [:]
+    private var dwellSlot: DwellSlot?
+    private var firedDwellKeys: Set<String> = []
+    private var trackedSectionKeys: Set<String> = []
+    private var trackedItemKeys: Set<String> = []
+    private var capLogEmittedThisScreen = false
+
+    public init(
+        knobs: SectionsKnobs,
+        scheduler: SectionsScheduling = ForgeMainQueueSectionsScheduler(),
+        emit: @escaping Emission,
+        log: @escaping (String) -> Void = { _ in }
+    ) {
+        self.knobs = knobs
+        self.scheduler = scheduler
+        self.emitClosure = emit
+        self.logClosure = log
+    }
+
+    // MARK: - Feeds
+
+    /// Replaces the full reported set for one source (UIKit sampler path).
+    /// Sections/items previously reported by the source and absent from this
+    /// call count as gone.
+    public func apply(source: SectionsFeedSource, sections: [SectionSnapshot], items: [ItemSnapshot]) {
+        mutateAndEmit {
+            self.sectionFeeds[source] = sections
+            self.itemFeeds[source] = items
+            return self.recomputeLocked()
+        }
+    }
+
+    /// Upserts one section for a source (SwiftUI appear/update path).
+    public func update(source: SectionsFeedSource, section: SectionSnapshot) {
+        mutateAndEmit {
+            var feed = self.sectionFeeds[source] ?? []
+            if let index = feed.firstIndex(where: { $0.key == section.key }) {
+                feed[index] = section
+            } else {
+                feed.append(section)
+            }
+            self.sectionFeeds[source] = feed
+            return self.recomputeLocked()
+        }
+    }
+
+    /// Upserts one item for a source (SwiftUI appear/update path).
+    public func update(source: SectionsFeedSource, item: ItemSnapshot) {
+        mutateAndEmit {
+            var feed = self.itemFeeds[source] ?? []
+            if let index = feed.firstIndex(where: { $0.key == item.key }) {
+                feed[index] = item
+            } else {
+                feed.append(item)
+            }
+            self.itemFeeds[source] = feed
+            return self.recomputeLocked()
+        }
+    }
+
+    /// Drops one section reported by a source (SwiftUI disappear path).
+    public func remove(source: SectionsFeedSource, sectionKey: String) {
+        mutateAndEmit {
+            self.sectionFeeds[source] = (self.sectionFeeds[source] ?? []).filter { $0.key != sectionKey }
+            return self.recomputeLocked()
+        }
+    }
+
+    /// Drops one item reported by a source (SwiftUI disappear path).
+    public func remove(source: SectionsFeedSource, itemKey: String) {
+        mutateAndEmit {
+            self.itemFeeds[source] = (self.itemFeeds[source] ?? []).filter { $0.key != itemKey }
+            return self.recomputeLocked()
+        }
+    }
+
+    /// Recomputes transitions from the current stores (used after screen
+    /// context settles and after knob hot-apply).
+    public func revalidate() {
+        mutateAndEmit { self.recomputeLocked() }
+    }
+
+    /// Hot-applies new knobs; threshold changes re-evaluate visible/hidden and
+    /// candidate arming immediately. Already-armed timers keep their original
+    /// deadline and re-verify against the new threshold at fire.
+    public func updateKnobs(_ knobs: SectionsKnobs) {
+        mutateAndEmit {
+            self.knobs = knobs
+            return self.recomputeLocked()
+        }
+    }
+
+    // MARK: - Dwell (focus driven)
+
+    /// Arms the single dwell slot for a tracked item; a different armed item is
+    /// superseded silently. Arming an already-armed item keeps its deadline.
+    public func armDwell(itemKey: String) {
+        mutateAndEmit {
+            if self.dwellSlot?.itemKey == itemKey { return [] }
+            self.cancelDwellLocked()
+            guard let item = self.mergedItemLocked(itemKey), self.trackedItemKeys.contains(itemKey) else {
+                return []
+            }
+            let dedupeKey = self.dedupeKeyLocked(for: item)
+            if self.firedDwellKeys.contains(dedupeKey) { return [] }
+            let task = self.scheduler.schedule(afterMs: self.knobs.dwellMs) { [weak self] in
+                self?.confirmDwell(itemKey: itemKey)
+            }
+            self.dwellSlot = DwellSlot(
+                itemKey: itemKey,
+                armedAtMs: self.scheduler.nowMs(),
+                dedupeKey: dedupeKey,
+                task: task
+            )
+            return []
+        }
+    }
+
+    /// Cancels the armed dwell slot (focus moved off tracked content).
+    public func clearDwell() {
+        mutateAndEmit {
+            self.cancelDwellLocked()
+            return []
+        }
+    }
+
+    // MARK: - Screen lifecycle
+
+    /// Screen-change parity rule: emit `raw_section_hidden` for still-visible
+    /// sections FIRST, then reset dedupe, caps, dwell, candidates, and order
+    /// assignment. Source stores are kept; the next revalidate re-emits
+    /// whatever remains visible under the new screen context.
+    public func onScreenChanged() {
+        mutateAndEmit {
+            var emissions: [(String, [String: String])] = []
+            // Total ordering (section key breaks order ties) so the hidden
+            // flush is deterministic when sections share an explicit order.
+            let stillVisible = self.sectionStates
+                .filter(\.value.visibleEmitted)
+                .sorted { ($0.value.order, $0.key) < ($1.value.order, $1.key) }
+            for (_, state) in stillVisible {
+                emissions.append(self.sectionHiddenEmissionLocked(state))
+            }
+            self.sectionStates.removeAll()
+            self.nextFirstSeenOrder = 0
+            self.impressionCandidates.values.forEach { $0.task.cancel() }
+            self.impressionCandidates.removeAll()
+            self.firedImpressionKeys.removeAll()
+            self.capturedDedupeKeys.removeAll()
+            self.cancelDwellLocked()
+            self.firedDwellKeys.removeAll()
+            self.trackedSectionKeys.removeAll()
+            self.trackedItemKeys.removeAll()
+            self.capLogEmittedThisScreen = false
+            return emissions
+        }
+    }
+
+    /// Silent teardown for uninstall: cancels timers and clears every store
+    /// without emitting.
+    public func reset() {
+        mutateAndEmit {
+            self.impressionCandidates.values.forEach { $0.task.cancel() }
+            self.impressionCandidates.removeAll()
+            self.cancelDwellLocked()
+            self.sectionFeeds.removeAll()
+            self.itemFeeds.removeAll()
+            self.sectionStates.removeAll()
+            self.nextFirstSeenOrder = 0
+            self.firedImpressionKeys.removeAll()
+            self.capturedDedupeKeys.removeAll()
+            self.firedDwellKeys.removeAll()
+            self.trackedSectionKeys.removeAll()
+            self.trackedItemKeys.removeAll()
+            self.capLogEmittedThisScreen = false
+            return []
+        }
+    }
+
+    // MARK: - Enrichment lookups
+
+    /// Context of the armed dwell slot for interaction enrichment
+    /// (tvOS remote-key/select), or `nil` when nothing is armed.
+    public func dwellEnrichment() -> [String: String]? {
+        lock.lock()
+        defer { lock.unlock() }
+        guard let slot = dwellSlot, let item = mergedItemLocked(slot.itemKey) else { return nil }
+        return itemEnrichmentFieldsLocked(item)
+    }
+
+    /// Section/item context for a resolved item key, or `nil` when untracked.
+    public func itemEnrichment(itemKey: String) -> [String: String]? {
+        lock.lock()
+        defer { lock.unlock() }
+        guard let item = mergedItemLocked(itemKey) else { return nil }
+        return itemEnrichmentFieldsLocked(item)
+    }
+
+    /// Section context for a resolved section key, or `nil` when untracked.
+    public func sectionEnrichment(sectionKey: String) -> [String: String]? {
+        lock.lock()
+        defer { lock.unlock() }
+        guard let state = sectionStates[sectionKey] else { return nil }
+        return ["section": state.name, "sectionOrder": String(state.order)]
+    }
+
+    // MARK: - Timer confirmations
+
+    private func confirmImpression(itemKey: String) {
+        mutateAndEmit {
+            guard let candidate = self.impressionCandidates.removeValue(forKey: itemKey) else { return [] }
+            // Re-verify at fire: the item must still be reported and still at
+            // or above the threshold; the emitted pct is the confirmation-time
+            // value, not the arming-time value.
+            guard let item = self.mergedItemLocked(itemKey), self.qualifiesLocked(item.visibilityPct) else {
+                return []
+            }
+            // Dedupe on the arm-time key, never a recomputed one.
+            guard !self.firedImpressionKeys.contains(candidate.dedupeKey) else { return [] }
+            self.firedImpressionKeys.insert(candidate.dedupeKey)
+            var params: [String: String] = [
+                "position": String(item.position),
+                "visibilityPct": String(item.visibilityPct),
+            ]
+            if let sectionFields = self.sectionFieldsLocked(for: item) {
+                params.merge(sectionFields) { current, _ in current }
+            }
+            if let contentId = item.contentId {
+                params["contentId"] = contentId
+            }
+            if let title = item.title {
+                params["contentTitle"] = title
+            }
+            return [(RawEventName.contentImpression, params)]
+        }
+    }
+
+    private func confirmDwell(itemKey: String) {
+        mutateAndEmit {
+            guard let slot = self.dwellSlot, slot.itemKey == itemKey else { return [] }
+            self.dwellSlot = nil
+            // Re-verify at fire: the item must still be reported and visible.
+            guard let item = self.mergedItemLocked(itemKey), item.visibilityPct > 0 else { return [] }
+            // Dedupe on the arm-time key, never a recomputed one.
+            guard !self.firedDwellKeys.contains(slot.dedupeKey) else { return [] }
+            self.firedDwellKeys.insert(slot.dedupeKey)
+            var params: [String: String] = [
+                "position": String(item.position),
+                "dwellMs": String(max(0, self.scheduler.nowMs() - slot.armedAtMs)),
+            ]
+            if let sectionName = self.sectionNameLocked(for: item) {
+                params["section"] = sectionName
+            }
+            if let contentId = item.contentId {
+                params["contentId"] = contentId
+            }
+            return [(RawEventName.contentDwell, params)]
+        }
+    }
+
+    // MARK: - Core recompute
+
+    private func recomputeLocked() -> [(String, [String: String])] {
+        var emissions: [(String, [String: String])] = []
+        let sections = mergedSectionsLocked()
+        let items = mergedItemsLocked()
+        let sectionKeys = Set(sections.map(\.key))
+        let itemKeys = Set(items.map(\.key))
+
+        // Section tracking, ordering, and visible/hidden transitions.
+        for snapshot in sections {
+            if !trackedSectionKeys.contains(snapshot.key) {
+                guard trackedSectionKeys.count < knobs.maxSections else {
+                    logCapOnceLocked()
+                    continue
+                }
+                trackedSectionKeys.insert(snapshot.key)
+            }
+            var state = sectionStates[snapshot.key] ?? SectionRuntime(
+                name: snapshot.name,
+                order: snapshot.order ?? nextFirstSeenOrderLocked(),
+                visibleEmitted: false
+            )
+            state.name = snapshot.name
+            // Explicit order wins over first-seen order, including a later
+            // explicit order arriving for a first-seen section.
+            if let explicit = snapshot.order {
+                state.order = explicit
+            }
+            let visible = qualifiesLocked(snapshot.visibilityPct)
+            if visible, !state.visibleEmitted {
+                state.visibleEmitted = true
+                emissions.append((
+                    RawEventName.sectionVisible,
+                    [
+                        "section": state.name,
+                        "sectionOrder": String(state.order),
+                        "visibilityPct": String(snapshot.visibilityPct),
+                        "itemCount": String(itemCountLocked(sectionKey: snapshot.key, snapshotCount: snapshot.itemCount, items: items)),
+                    ]
+                ))
+            } else if !visible, state.visibleEmitted {
+                state.visibleEmitted = false
+                emissions.append(sectionHiddenEmissionLocked(state))
+            }
+            sectionStates[snapshot.key] = state
+        }
+
+        // Sections that stopped being reported entirely: hidden if visible.
+        // Runtime state is kept so re-appearing sections keep a stable
+        // first-seen order for the rest of the screen.
+        for (key, state) in sectionStates where !sectionKeys.contains(key) && state.visibleEmitted {
+            var updated = state
+            updated.visibleEmitted = false
+            sectionStates[key] = updated
+            emissions.append(sectionHiddenEmissionLocked(updated))
+        }
+
+        // Item tracking and impression sustain arming/cancelling.
+        for item in items {
+            if !trackedItemKeys.contains(item.key) {
+                guard trackedItemKeys.count < knobs.maxTrackedItems else {
+                    logCapOnceLocked()
+                    continue
+                }
+                trackedItemKeys.insert(item.key)
+            }
+            let qualifies = qualifiesLocked(item.visibilityPct)
+            if qualifies {
+                let dedupeKey = dedupeKeyLocked(for: item)
+                if impressionCandidates[item.key] == nil, !firedImpressionKeys.contains(dedupeKey) {
+                    let key = item.key
+                    let task = scheduler.schedule(afterMs: knobs.impressionMinVisibleMs) { [weak self] in
+                        self?.confirmImpression(itemKey: key)
+                    }
+                    impressionCandidates[item.key] = ImpressionCandidate(
+                        armedAtMs: scheduler.nowMs(),
+                        dedupeKey: dedupeKey,
+                        task: task
+                    )
+                }
+            } else if let candidate = impressionCandidates.removeValue(forKey: item.key) {
+                // Sustain broken before the deadline: cancel the candidate.
+                candidate.task.cancel()
+            }
+        }
+
+        // Items that stopped being reported: their sustain is broken too.
+        for (key, candidate) in impressionCandidates where !itemKeys.contains(key) {
+            candidate.task.cancel()
+            impressionCandidates.removeValue(forKey: key)
+        }
+
+        return emissions
+    }
+
+    // MARK: - Locked helpers
+
+    private func mutateAndEmit(_ body: () -> [(String, [String: String])]) {
+        lock.lock()
+        let emissions = body()
+        lock.unlock()
+        for (kind, params) in emissions {
+            emitClosure(kind, params)
+        }
+    }
+
+    private func mergedSectionsLocked() -> [SectionSnapshot] {
+        var seen = Set<String>()
+        var merged: [SectionSnapshot] = []
+        for source in SectionsFeedSource.allCases {
+            for snapshot in sectionFeeds[source] ?? [] where !seen.contains(snapshot.key) {
+                seen.insert(snapshot.key)
+                merged.append(snapshot)
+            }
+        }
+        return merged
+    }
+
+    private func mergedItemsLocked() -> [ItemSnapshot] {
+        var seen = Set<String>()
+        var merged: [ItemSnapshot] = []
+        for source in SectionsFeedSource.allCases {
+            for item in itemFeeds[source] ?? [] where !seen.contains(item.key) {
+                seen.insert(item.key)
+                merged.append(item)
+            }
+        }
+        return merged
+    }
+
+    private func mergedItemLocked(_ key: String) -> ItemSnapshot? {
+        for source in SectionsFeedSource.allCases {
+            if let item = (itemFeeds[source] ?? []).first(where: { $0.key == key }) {
+                return item
+            }
+        }
+        return nil
+    }
+
+    private func cancelDwellLocked() {
+        dwellSlot?.task.cancel()
+        dwellSlot = nil
+    }
+
+    private func qualifiesLocked(_ visibilityPct: Int) -> Bool {
+        visibilityPct > 0 && visibilityPct >= knobs.visibilityThresholdPct
+    }
+
+    private func nextFirstSeenOrderLocked() -> Int {
+        defer { nextFirstSeenOrder += 1 }
+        return nextFirstSeenOrder
+    }
+
+    private func itemCountLocked(sectionKey: String, snapshotCount: Int, items: [ItemSnapshot]) -> Int {
+        let derived = items.filter { $0.sectionKey == sectionKey && $0.visibilityPct > 0 }.count
+        return max(snapshotCount, derived)
+    }
+
+    private func sectionHiddenEmissionLocked(_ state: SectionRuntime) -> (String, [String: String]) {
+        (
+            RawEventName.sectionHidden,
+            ["section": state.name, "sectionOrder": String(state.order)]
+        )
+    }
+
+    private func sectionNameLocked(for item: ItemSnapshot) -> String? {
+        guard let sectionKey = item.sectionKey else { return nil }
+        return sectionStates[sectionKey]?.name
+    }
+
+    private func sectionFieldsLocked(for item: ItemSnapshot) -> [String: String]? {
+        guard let sectionKey = item.sectionKey, let state = sectionStates[sectionKey] else { return nil }
+        return ["section": state.name, "sectionOrder": String(state.order)]
+    }
+
+    private func itemEnrichmentFieldsLocked(_ item: ItemSnapshot) -> [String: String] {
+        var fields: [String: String] = ["position": String(item.position)]
+        if let sectionFields = sectionFieldsLocked(for: item) {
+            fields.merge(sectionFields) { current, _ in current }
+        }
+        if let contentId = item.contentId {
+            fields["contentId"] = contentId
+        }
+        return fields
+    }
+
+    /// Dedupe key parity contract: `section|contentId` per screen, falling
+    /// back to the stable item key when the item carries no content id. The
+    /// key is captured on first dedupe-relevant use per item and reused for
+    /// the rest of the screen: without the freeze, a section registering
+    /// after its item already fired would drift `"|id"` into `"Rail|id"` and
+    /// the same item could fire a second impression/dwell on re-crossing.
+    private func dedupeKeyLocked(for item: ItemSnapshot) -> String {
+        if let captured = capturedDedupeKeys[item.key] {
+            return captured
+        }
+        let key = "\(sectionNameLocked(for: item) ?? "")|\(item.contentId ?? item.key)"
+        capturedDedupeKeys[item.key] = key
+        return key
+    }
+
+    private func logCapOnceLocked() {
+        guard !capLogEmittedThisScreen else { return }
+        capLogEmittedThisScreen = true
+        logClosure(
+            "sections capture caps reached (maxSections=\(knobs.maxSections), maxTrackedItems=\(knobs.maxTrackedItems)); further targets ignored for this screen"
+        )
+    }
+}