ios: gap-loop follow-ups, upload ticks, the nearer unseen end and request stretches (#39, #31, #83, #75)

ios/HouseScan/Contract/ScanContract.swift

@@ -604,6 +604,12 @@ struct ClearanceZone: Identifiable, Equatable, Sendable {
     var depth: Float
 }
 
+/// An unexplored end of the walk: its side and where the scan stopped, meters of s.
+struct UnseenEnd: Equatable, Sendable {
+    var side: WallSide
+    var s: Float
+}
+
 struct ResultPresentation: Equatable, Sendable {
     enum Decision: String, Equatable, Sendable {
         case pass
@@ -635,8 +641,9 @@ struct ResultPresentation: Equatable, Sendable {
     var checks: [CheckRow]
     var clearances: [ClearanceZone]
     var missing: [MissingEvidence]
-    /// A side of the meter the walk didn't reach, so a closer spot may exist there.
-    var unseenSide: WallSide? = nil
+    /// Where the scan stopped on a side it didn't finish, nearer the meter than the spot, so a
+    /// closer spot may lie past it (`PlacementResult.closerUnseenEnd`).
+    var unseenEnd: UnseenEnd? = nil
     /// True when no server answered and the result is the offline sample used by tests and
     /// demos. The UI must say so on screen.
     var isSample: Bool
@@ -790,6 +797,9 @@ final class ScanViewState {
     /// camera can't tell open sky from an eave, so the homeowner answers.
     var overheadQuestion = false
     var upload: UploadState = .idle
+    /// How many views the finished check's answer will still ask for without a tap, counting a
+    /// server request on screen: what "One more view to finish" and "2 more views to finish" promise.
+    var followUps = 0
     var result: ResultPresentation?
     /// The spot check of the result's spot: the question during `.spotConfirm`, and the answer
     /// that stands for the spot on the result.
@@ -864,8 +874,13 @@ protocol ScanActions: AnyObject {
     func finishWalk()
     /// Features confirmed; the engine runs the gap check, then uploads.
     func confirmFeatures()
-    /// "I can't get there": the gap is recorded for installer review.
+    /// "I can't get there": the gap is recorded for installer review. On a request the finished
+    /// check sent back, the check's next request follows; the result shows once none is left.
     func skipGap()
+    /// "Show my result" on a request the finished check sent back: the view is recorded for
+    /// installer review like a skipped one, and after one more upload the result shows instead
+    /// of the check's next request.
+    func showResultNow()
     /// "I can't get to this part of the wall", during the walk: the cells the guidance is asking
     /// for become `.skipped` and the guidance moves on to the next task. While the walk asks to
     /// walk a side, that side's end goes where `ScanViewState.endPreview` shows, as an unexplored

ios/HouseScan/Runtime/Autopilot.swift

@@ -434,18 +434,46 @@ final class Autopilot {
     /// for it; a replay shows only what it recorded, so when they don't settle the request the
     /// autopilot says "I can't get there", as a homeowner would. An overhead request is answered
     /// like the one before the upload.
+    /// With `-autopilotShowResult`, "Show my result" on the first one instead.
     private func driveServerRequest(_ replay: ReplayPlayer) async {
         guard let request = engine.state.gap else { return }
         log("server request \(request.id) over \(format(request.span))")
-        if request.reason == .overhead {
-            await answerOverheadGap()
+        let skippedBefore = engine.skippedGaps.count
+        let action: String
+        if engine.options.autopilotShowResult {
+            await pause(hold)
+            await engine.waitForGate(.gapRequest)
+            engine.showResultNow()
+            log("server request \(request.id): show my result")
+            action = "showResult"
         } else {
-            await playGapFrames(replay)
+            if request.reason == .overhead {
+                await answerOverheadGap()
+            } else {
+                await playGapFrames(replay)
+            }
+            action = engine.skippedGaps.count > skippedBefore ? "skipped" : "answered"
         }
+        recordServerRequestForTest(id: request.id, action: action)
         // A settled request stays on screen for a moment before the next upload.
         _ = await waitUntil(timeout: 10) { self.engine.state.phase != .gapRequest || self.engine.state.gap?.id != request.id }
     }
 
+    /// The requests the server's answers raised, in order, with how each ended ("answered",
+    /// "skipped" or "showResult"): with `-autopilotGate`, written to the gate folder as
+    /// `server-requests.json` after each, for the UI test to check the follow-up loop (issue #39).
+    private var serverRequestsForTest: [[String: Any]] = []
+
+    private func recordServerRequestForTest(id: Int, action: String) {
+        serverRequestsForTest.append(["id": id, "action": action])
+        guard let gate = engine.options.autopilotGate else { return }
+        do {
+            try JSONSerialization.data(withJSONObject: serverRequestsForTest).write(to: gate.appending(path: "server-requests.json"))
+        } catch {
+            log("could not write server-requests.json to the gate folder: \(error)")
+        }
+    }
+
     /// Waits while the engine plays the replay's frames for the current request. A replay shows
     /// only what it recorded, so when they don't settle the request the autopilot says "I can't
     /// get there", as a homeowner would.

ios/HouseScan/Runtime/LaunchOptions.swift

@@ -20,6 +20,8 @@ import OSLog
 ///   marking the ends (`Autopilot.endWalkByCantGetThere`).
 /// - `-autopilotSomethingThere`: the autopilot answers the first spot check "Something's there"
 ///   instead of "It's clear", so the scan is checked again without that area.
+/// - `-autopilotShowResult`: the autopilot taps "Show my result" on the first request the
+///   server's answer raises, so no further request is raised (issue #39).
 struct LaunchOptions: Equatable {
     var replayFolder: URL?
     var autopilot = false
@@ -29,6 +31,7 @@ struct LaunchOptions: Equatable {
     var autopilotGate: URL?
     var autopilotCantGetThere = false
     var autopilotSomethingThere = false
+    var autopilotShowResult = false
 
     init(
         arguments: [String] = ProcessInfo.processInfo.arguments,
@@ -44,6 +47,7 @@ struct LaunchOptions: Equatable {
         autopilot = arguments.contains("-autopilot")
         autopilotCantGetThere = arguments.contains("-autopilotCantGetThere")
         autopilotSomethingThere = arguments.contains("-autopilotSomethingThere")
+        autopilotShowResult = arguments.contains("-autopilotShowResult")
         serverURL = (value(after: "-serverURL") ?? defaultServerURL).flatMap(Self.serverURL)
         sampleResult = arguments.contains("-sampleResult")
         if let gate = value(after: "-autopilotGate") { autopilotGate = URL(fileURLWithPath: gate, isDirectory: true) }

ios/HouseScan/Runtime/ScanEngine+Actions.swift

@@ -355,6 +355,11 @@ extension ScanEngine: ScanActions {
         skipCurrentGap()
     }
 
+    func showResultNow() {
+        guard state.phase == .gapRequest else { return }
+        stopGapRequests()
+    }
+
     func cannotAccessArea() {
         switch state.phase {
         case .gapRequest:

ios/HouseScan/Runtime/ScanEngine+Export.swift

@@ -193,7 +193,9 @@ extension ScanEngine {
         let plans = result.missingEvidence.map { item in
             gapPlanner.plan(for: item, leftEnd: coverage?.leftEnd, rightEnd: coverage?.rightEnd, limitEnds: coverage?.limitEnds ?? [])
         }
-        let settles = plans.map { plan in plan.map { !skippedGaps.contains($0) && captureCanSettle($0) } ?? false }
+        let settles = plans.map { plan in
+            plan.map { plan in !skippedGaps.contains { plan.asksForSameView(as: $0) } && captureCanSettle(plan) } ?? false
+        }
         return Self.presentation(of: result, isSample: isSample, wall: sceneWall) { item in
             result.missingEvidence.firstIndex(of: item).map { settles[$0] } ?? false
         }
@@ -276,14 +278,11 @@ extension ScanEngine {
             )
         }
 
-        var unseen: WallSide?
-        if let pastEnd = result.missingEvidence.first(where: { $0.kind == .pastEnd })?.side {
-            unseen = pastEnd == .left ? .left : .right
-        } else if result.ends.left.kind == .unexplored, result.ends.left.beyondReach != true {
-            // An end beyond cable reach can't hold the battery whatever lies past it.
-            unseen = .left
-        } else if result.ends.right.kind == .unexplored, result.ends.right.beyondReach != true {
-            unseen = .right
+        // The unexplored end nearer the meter than the spot, if any, not the first past_end
+        // request: the server lists those left first, whether or not a spot past the end could
+        // beat the one it chose (issue #83).
+        let unseen = result.closerUnseenEnd().map { end in
+            UnseenEnd(side: end.side == .left ? .left : .right, s: meters(end.sFt))
         }
 
         return ResultPresentation(
@@ -301,7 +300,7 @@ extension ScanEngine {
             checks: checks,
             clearances: clearances,
             missing: missing,
-            unseenSide: unseen,
+            unseenEnd: unseen,
             isSample: isSample
         )
     }

ios/HouseScan/Runtime/ScanEngine.swift

@@ -101,11 +101,12 @@ final class ScanEngine {
     /// The end the past_end request cleared: where it was, its kind and when it was marked, put
     /// back or moved on when the request ends without it marked again (`settleClearedEnd`).
     private var clearedEnd: (s: Float, kind: EndKind, t: Double?)?
-    /// Server requests raised without a tap since the review was confirmed (`nextAutomaticGap`),
-    /// oldest first. Each is raised once; the result still offers it as a capture.
+    /// Server requests raised without a tap since the review was confirmed (`automaticGapQueue`),
+    /// oldest first. Each is raised once, whether its view was taken or the homeowner couldn't
+    /// get there; the result still offers it as a capture.
     private var automaticGaps: [GapPlan] = []
-    /// Set when the homeowner says they can't get to a server request's view: after the upload
-    /// that follows, the result shows instead of the next request.
+    /// Set when the homeowner taps "Show my result" on a server request (`stopGapRequests`):
+    /// after the upload that follows, the result shows instead of the next request.
     private var automaticGapsStopped = false
     /// At most this many server requests are raised without a tap per confirmed review, so a
     /// server that keeps finding new gaps can't hold the homeowner in the loop. A guess, not
@@ -116,6 +117,16 @@ final class ScanEngine {
     /// the answer opens the camera: 1.5 s, about the time to read four words and see the new
     /// step appear, and what the UI lane asked for. Not measured with homeowners.
     static let followUpHold: Double = 1.5
+    /// The least time the upload screen shows "Check clearances" at work before it ticks: 0.6 s,
+    /// enough to see the step start. The server answers in the request that carries the scene,
+    /// often a moment after the last byte, and the step was never drawn (issue #31). A guess
+    /// like `followUpHold`, not measured with homeowners.
+    static let analyzingMinimum: Double = 0.6
+    /// How long the upload screen shows every step ticked before the result replaces it: 0.8 s,
+    /// about the time to see "Clearances checked" land. A guess like `followUpHold`, not measured.
+    static let resultHold: Double = 0.8
+    /// When the upload screen moved to "Check clearances" in this upload, for `analyzingMinimum`.
+    private var analyzingSince: ContinuousClock.Instant?
 
     // LiDAR
     /// The bands the see-behind step is about, while `state.guidance` is `.seeBehind`: those with
@@ -1394,15 +1405,14 @@ final class ScanEngine {
         RuntimeLog.engine.info("overhead: kept a view reaching \(reach.map(\.out).min() ?? 0) m over s=\(reach.first?.span.lowerBound ?? 0)...\(reach.last?.span.upperBound ?? 0)")
     }
 
-    /// Ends the current request without the view it asked for ("I can't get there", or something
-    /// overhead): recorded for installer review, then on to the upload. "I can't get there" on a
-    /// server request also ends the requests raised without a tap: after that upload the result
-    /// shows. Something overhead is an answer, not a refusal, so the loop goes on.
+    /// Ends the current request without the view it asked for ("I can't get there", something
+    /// overhead, or "Show my result"): recorded for installer review, then on to the upload. The
+    /// answer that follows raises the next item it lists, never this one again
+    /// (`automaticGapQueue`); only "Show my result" (`stopGapRequests`) ends the requests.
     func skipCurrentGap(because reason: String = "the homeowner can't get there", refused: Bool = true) {
         guard let plan = gapPlan else { return }
         // Something overhead is an answer: the request goes to review without its view.
         resolveGuidance(refused ? .cannotReach : .skipped)
-        if refused, state.gap?.origin == .server { automaticGapsStopped = true }
         // Only a cell request marks cells: skipping a deeper, walked or overhead view says
         // nothing about the band the strip draws.
         if plan.need == .cells { coverage?.markSkipped(plan.band, plan.span) }
@@ -1412,6 +1422,15 @@ final class ScanEngine {
         afterGapResolved()
     }
 
+    /// "Show my result" on a server request: this view goes to installer review like one the
+    /// homeowner can't get to, and after the upload that follows the result shows instead of
+    /// the answer's next request.
+    func stopGapRequests() {
+        guard gapPlan != nil, state.gap?.origin == .server else { return }
+        automaticGapsStopped = true
+        skipCurrentGap(because: "the homeowner asked for the result", refused: false)
+    }
+
     // MARK: Upload
 
     func startUpload() {
@@ -1467,16 +1486,20 @@ final class ScanEngine {
             saveBundle(scene: scene, snapshot: snapshot)
             guard !Task.isCancelled else { return }
             state.upload = .uploading(fraction: 0)
+            // Each attempt's "Check clearances" starts when its bytes are sent (issue #31).
+            analyzingSince = nil
             let result: PlacementResult
             let data: Data
             do {
                 data = try await resultClient.submit(scene: scene) { [weak self] fraction in
                     Task { @MainActor in
                         guard let self, scan == self.generation, case .uploading = self.state.upload else { return }
+                        if fraction >= 1 { self.analyzingSince = ContinuousClock.now }
                         self.state.upload = fraction >= 1 ? .analyzing : .uploading(fraction: fraction)
                     }
                 }
                 guard scan == generation else { return }
+                if analyzingSince == nil { analyzingSince = ContinuousClock.now }
                 state.upload = .analyzing
                 result = try PlacementResult.decode(data)
             } catch is CancellationError {
@@ -1510,12 +1533,19 @@ final class ScanEngine {
             break
         }
         guard let result = placement else { return }
+        // "Check clearances" stays up for `analyzingMinimum` however fast the answer came, so the
+        // step and then its tick are drawn (issue #31).
+        let dwell = UploadPacing.remaining(since: analyzingSince, minimum: .seconds(Self.analyzingMinimum), now: ContinuousClock.now)
+        if dwell > .zero {
+            guard (try? await Task.sleep(for: dwell)) != nil, scan == generation, state.phase == .uploading else { return }
+        }
         writeScanStamp(answer: result)
         state.result = presentation(of: result, isSample: resultClient.isSample)
+        state.followUps = automaticGapQueue(result).count
         state.upload = .done
         await waitForGate(.uploading)
         guard scan == generation else { return }
-        if let next = nextAutomaticGap(result) {
+        if let next = automaticGapQueue(result).first {
             // The upload screen says "One more view to finish" once the answer is in
             // (`state.result` set, upload `.done`, both kept through the request): long
             // enough to read before the camera takes over.
@@ -1526,29 +1556,40 @@ final class ScanEngine {
             beginServerGap(next.item, plan: next.plan)
             return
         }
+        // Every step ticked, "Clearances checked" last, for `resultHold` before the result
+        // replaces the screen: going on in the same turn never drew the tick (issue #31).
+        guard (try? await Task.sleep(for: .seconds(Self.resultHold))) != nil,
+              scan == generation, state.phase == .uploading else { return }
         // The result appears only after the server answered (checklist R6), and after the
         // homeowner checked its spot (`presentAnswer`).
         presentAnswer()
     }
 
-    /// The first item of the answer's missing evidence a capture can settle (the result's
-    /// "capturable"), not skipped and not yet raised in this pass; nil once the homeowner said
-    /// they can't get to one, or after `maxAutomaticGaps` requests.
-    private func nextAutomaticGap(_ result: PlacementResult) -> (item: PlacementMissingEvidence, plan: GapPlan)? {
+    /// The answer's items this pass will still raise without a tap, in order, with their
+    /// requests: those a capture can settle (the result's "capturable"), not skipped and not yet
+    /// raised in this pass (`GapPlanner.serverRequests`), up to `maxAutomaticGaps` requests.
+    /// Empty once the homeowner tapped "Show my result". `asking`, a request about to be raised,
+    /// counts as raised.
+    private func automaticGapQueue(_ result: PlacementResult, asking: GapPlan? = nil) -> [(item: PlacementMissingEvidence, plan: GapPlan)] {
         // A request raised while the phone has lost its place could only time out: show the result.
-        guard !automaticGapsStopped, automaticGaps.count < Self.maxAutomaticGaps, !state.tracking.hasLostItsPlace,
-              sourceState.mayCapture, let map = coverage else { return nil }
-        for item in result.missingEvidence {
-            guard let plan = gapPlanner.plan(for: item, leftEnd: map.leftEnd, rightEnd: map.rightEnd, limitEnds: map.limitEnds),
-                  !skippedGaps.contains(plan), !automaticGaps.contains(plan), captureCanSettle(plan) else { continue }
-            return (item, plan)
+        guard !automaticGapsStopped, !state.tracking.hasLostItsPlace, sourceState.mayCapture, let map = coverage else { return [] }
+        let asked = automaticGaps + (asking.map { [$0] } ?? [])
+        // A new view cannot settle an area the homeowner has already said is obstructed.
+        // Filter before the request limit so refused areas do not consume the remaining slots.
+        let capturable = result.missingEvidence.filter { item in
+            gapPlanner.plan(for: item, leftEnd: map.leftEnd, rightEnd: map.rightEnd, limitEnds: map.limitEnds)
+                .map { captureCanSettle($0) } ?? false
         }
-        return nil
+        return gapPlanner.serverRequests(
+            in: capturable, leftEnd: map.leftEnd, rightEnd: map.rightEnd, limitEnds: map.limitEnds,
+            asked: asked, skipped: skippedGaps, limit: Self.maxAutomaticGaps - automaticGaps.count)
     }
 
     /// Starts the capture for an item of the server's missing evidence, whether tapped on the
     /// result or raised after an upload.
     func beginServerGap(_ item: PlacementMissingEvidence, plan: GapPlan) {
+        // Counted before a past_end request clears its end, which would change the other requests.
+        state.followUps = 1 + (placement.map { automaticGapQueue($0, asking: plan).count } ?? 0)
         var pastEnd: WallSide?
         if item.kind == .pastEnd, let side = item.side {
             // The walk has to go past the end it stopped at; that end is no longer a limit. It