ios: draw the AR result with the Canvas until RealityKit is seen drawing it

ios/HouseScan/Contract/ScanContract.swift

@@ -794,8 +794,9 @@ final class ScanViewState {
     /// The spot check of the result's spot: the question during `.spotConfirm`, and the answer
     /// that stands for the spot on the result.
     var spotCheck: SpotCheck?
-    /// True while the AR result is drawn into the live camera, where people and objects in front
-    /// of it hide it. The AR screen then draws no overlay of its own.
+    /// True while the engine sees the AR scene drawing the result in the live camera
+    /// (`ResultOverlayPolicy`). The AR screen then draws no overlay of its own; otherwise it
+    /// draws `BatteryOverlay`.
     var resultInCamera = false
     /// False once the camera failed after the scan was sent: the answer stays, but "See it on
     /// your wall" is neither shown nor offered until a new scan starts the camera again.

ios/HouseScan/Runtime/LiveCapture.swift

@@ -56,7 +56,11 @@ final class LiveCapture {
 
     /// The AR result in the camera view, while one is shown (`showResult`).
     private var result: AnchorEntity?
-    private var occludesPeople = false
+    /// An empty entity in the result at the point it has to put on screen (the battery's
+    /// middle), for `resultIsDrawn`.
+    private var resultFocus: Entity?
+    /// The last `resultIsDrawn` findings logged, so they are logged when they change.
+    private var lastDrawnReport: String?
 
     init(onFrame: @escaping @MainActor @Sendable (SourceFrame) -> Void, onEvent: @escaping @MainActor @Sendable (LiveEvent) -> Void) {
         arView = ARView(frame: .zero, cameraMode: .ar, automaticallyConfigureSession: false)
@@ -66,8 +70,9 @@ final class LiveCapture {
         arView.renderOptions.insert(.disableMotionBlur)
     }
 
-    /// People occlusion runs only while the AR result is on screen: the capture has no virtual
-    /// content for it to hide.
+    /// People occlusion is off: no caller asks for it. Turning it on while the AR result showed
+    /// re-ran the session under the result's freshly added anchor entity, and build 4.1 drew no
+    /// result on the phone it was tested on (#67). Whether and how to bring it back is #41.
     private static func configuration(occludingPeople: Bool = false) -> ARWorldTrackingConfiguration {
         let configuration = ARWorldTrackingConfiguration()
         // .gravity, not .gravityAndHeading: compass heading drifts near a house's metal and wiring.
@@ -111,7 +116,7 @@ final class LiveCapture {
 
     func start() {
         RuntimeLog.engine.info("LiDAR: scene depth \(Self.supportsDepth ? "on" : "not available", privacy: .public), mesh \(Self.supportsMesh ? "on" : "not available", privacy: .public)")
-        arView.session.run(Self.configuration(occludingPeople: occludesPeople))
+        arView.session.run(Self.configuration())
     }
 
     func pause() {
@@ -121,7 +126,7 @@ final class LiveCapture {
     /// Starts world tracking over with a fresh map, after relocalization failed. The old mesh goes
     /// with the old anchors.
     func restart() {
-        arView.session.run(Self.configuration(occludingPeople: occludesPeople), options: [.resetTracking, .removeExistingAnchors])
+        arView.session.run(Self.configuration(), options: [.resetTracking, .removeExistingAnchors])
         delegate.shared.withLock { $0.meterAnchorID = nil }
     }
 
@@ -130,22 +135,63 @@ final class LiveCapture {
     /// when the anchor was at `pose` (`MeterAnchorTracking.pose`, the pose the engine's wall
     /// agrees with). It is attached in that pose's frame, so a turn ARKit has made to the anchor
     /// since carries the model with it. Cancelling the anchor's current turn instead drew the
-    /// wall as it stood before the turn. People and, on a phone with LiDAR, the scene mesh hide
-    /// it where they stand in front of it. False when the meter has no anchor in the session;
-    /// nothing is shown then.
-    func showResult(_ model: Entity, builtFor pose: simd_float4x4) -> Bool {
+    /// wall as it stood before the turn. On a phone with LiDAR the scene mesh hides it where
+    /// something stands in front of it. `focus` is the point the model has to put on screen, in
+    /// the model's coordinates (`resultIsDrawn`).
+    ///
+    /// True means the model was handed to RealityKit, not that anything is drawn: build 4.1 took
+    /// it for that and hid the screen's own drawing on a phone where nothing appeared (#67).
+    /// False when the meter has no anchor in the session; nothing is shown then.
+    func showResult(_ model: Entity, builtFor pose: simd_float4x4, focus: SIMD3<Float>) -> Bool {
         removeResult()
         guard let id = delegate.shared.withLock({ $0.meterAnchorID }),
-              arView.session.currentFrame?.anchors.contains(where: { $0.identifier == id }) == true else { return false }
+              arView.session.currentFrame?.anchors.contains(where: { $0.identifier == id }) == true else {
+            RuntimeLog.engine.info("AR result not shown: the meter's anchor is not in the session")
+            return false
+        }
         let holder = AnchorEntity(.anchor(identifier: id))
+        // See-through until the engine hands the result to the AR scene (`setResultOwned`): a
+        // new model starts behind the screen's own drawing, and only one of them may show.
+        holder.components.set(OpacityComponent(opacity: 0))
         model.orientation = simd_quatf(pose).inverse
+        let marker = Entity()
+        marker.position = focus
+        model.addChild(marker)
         holder.addChild(model)
         arView.scene.addAnchor(holder)
         result = holder
+        resultFocus = marker
+        lastDrawnReport = nil
         setOcclusion(true)
         return true
     }
 
+    /// Whether RealityKit holds the shown result now, and whether it can be drawing it: `held`
+    /// when its anchor entity is anchored to the meter's ARKit anchor and enabled, `drawn` when
+    /// the result's focus point also lands in front of the camera and inside the view. Both are
+    /// read the same whether the model is see-through or shown (`setResultOwned`). A check of
+    /// the chain, not of pixels: RealityKit says nothing about what it drew. `drawn` confirms the
+    /// model; `held` keeps it once confirmed (`ResultOverlayPolicy`). The findings are logged
+    /// when they change.
+    func resultIsDrawn() -> (drawn: Bool, held: Bool) {
+        guard let result, let resultFocus else { return (false, false) }
+        let id = delegate.shared.withLock { $0.meterAnchorID }
+        let inSession = id.map { id in arView.session.currentFrame?.anchors.contains(where: { $0.identifier == id }) == true } ?? false
+        let anchored = result.isAnchored
+        let enabled = result.isEnabledInHierarchy
+        let world = resultFocus.position(relativeTo: nil)
+        let inCamera = arView.cameraTransform.matrix.inverse * SIMD4(world, 1)
+        let point = inCamera.z < 0 ? arView.project(world) : nil
+        let onScreen = point.map { arView.bounds.contains($0) } ?? false
+        let report = "anchor in session \(inSession), anchored \(anchored), enabled \(enabled), on screen \(onScreen)"
+        if report != lastDrawnReport {
+            lastDrawnReport = report
+            let at = point.map { String(format: "(%.0f, %.0f) in %.0f x %.0f", Double($0.x), Double($0.y), Double(arView.bounds.width), Double(arView.bounds.height)) } ?? "none"
+            RuntimeLog.engine.info("AR result: \(report, privacy: .public), projected at \(at, privacy: .public)")
+        }
+        return (anchored && enabled && onScreen, anchored && enabled)
+    }
+
     func hideResult() {
         removeResult()
         setOcclusion(false)
@@ -156,23 +202,29 @@ final class LiveCapture {
         result?.isEnabled = visible
     }
 
+    /// Whether the AR scene owns the result (`ResultOverlayPolicy.usesRealityKit`): the model
+    /// shows only then, and is see-through otherwise, while the screen draws it. See-through
+    /// rather than disabled, so it stays anchored and enabled and `resultIsDrawn` can still
+    /// confirm it. The opacity applies to the model and everything under it.
+    func setResultOwned(_ owned: Bool) {
+        result?.components.set(OpacityComponent(opacity: owned ? 1 : 0))
+    }
+
     private func removeResult() {
         result?.removeFromParent()
         result = nil
+        resultFocus = nil
     }
 
+    /// The LiDAR mesh hides the result where something real stands in front of it. A RealityKit
+    /// setting only: the session is not re-run (see `configuration`).
     private func setOcclusion(_ on: Bool) {
-        if Self.supportsMesh {
-            if on {
-                arView.environment.sceneUnderstanding.options.insert(.occlusion)
-            } else {
-                arView.environment.sceneUnderstanding.options.remove(.occlusion)
-            }
+        guard Self.supportsMesh else { return }
+        if on {
+            arView.environment.sceneUnderstanding.options.insert(.occlusion)
+        } else {
+            arView.environment.sceneUnderstanding.options.remove(.occlusion)
         }
-        guard Self.supportsPeopleOcclusion, occludesPeople != on else { return }
-        occludesPeople = on
-        // Without reset options the session keeps its tracking, anchors and mesh.
-        arView.session.run(Self.configuration(occludingPeople: on))
     }
 
     /// ARKit's mesh in world meters, with one `ARMeshClassification` raw value per triangle (0,

ios/HouseScan/Runtime/ScanEngine.swift

@@ -125,6 +125,14 @@ final class ScanEngine {
     // Tracking recovery
     private var relocalizingSince: Double?
 
+    // AR result
+    /// Watches whether the AR scene draws the result (`watchResultInCamera`) while "See it on
+    /// your wall" is up on the live camera.
+    private var resultWatch: Task<Void, Never>?
+    /// Which layer draws the result, and the wall the model in the AR scene was built for
+    /// (`showResultInCamera`, `watchResultInCamera`).
+    private var resultPolicy = ResultOverlayPolicy()
+
     // Upload
     let resultClient: any ResultClient
     private var uploadTask: Task<Void, Never>?
@@ -358,6 +366,8 @@ final class ScanEngine {
             RuntimeLog.capture.info("tracking \(Self.name(self.state.tracking), privacy: .public) -> \(Self.name(frame.tracking), privacy: .public)")
             if state.tracking == .normal { breakWalkedPath(because: "tracking left normal") }
             state.tracking = frame.tracking
+            // The model stays see-through until the next look hands it the result
+            // (`setResultInCamera`), so enabling it here never shows it over the screen's drawing.
             live?.setResultVisible(frame.tracking == .normal)
         }
         if let planes = frame.groundPlanes { groundPlanes = planes }
@@ -1204,20 +1214,85 @@ final class ScanEngine {
         refreshSpotPhoto()
     }
 
-    /// "See it on your wall" on the live camera: the result goes into the AR scene on the meter's
-    /// anchor, where people and objects in front of it hide it. A replay, or a meter without an
-    /// anchor, leaves it to the screen's overlay.
+    /// "See it on your wall" on the live camera. The screen draws the result over the camera
+    /// itself (`BatteryOverlay`) unless the AR scene is seen drawing it (`watchResultInCamera`).
+    /// Build 4.1 trusted the AR scene as soon as it had the model and showed no battery at all
+    /// (#67). Only a phone with LiDAR tries the AR scene, where the mesh can hide the result
+    /// behind things in front of it; without LiDAR the screen draws it, as build 3.1 did. A
+    /// replay, or a meter without an anchor, leaves it to the screen too.
     private func showResultInCamera(rising: Bool) {
-        guard let live, let wall = state.wall, let result = state.result, let pose = meterTracking?.pose,
-              state.spatialResultAvailable else { return }
+        guard LiveCapture.supportsMesh, let live, let wall = state.wall, let result = state.result,
+              let pose = meterTracking?.pose, state.spatialResultAvailable else { return }
+        if rising || resultWatch == nil { watchResultInCamera() }
+        // Each rebuild takes the model out of the scene and puts a new one in, so a wall that
+        // moved by a centimeter or two keeps the one it has. A new model starts on the screen's
+        // drawing and has to be seen drawn again (`ResultOverlayPolicy.needsModel`, review of
+        // #100); it goes in see-through (`LiveCapture.showResult`), so only one layer shows.
+        guard resultPolicy.needsModel(for: Self.modelShape(wall), rising: rising) else { return }
+        setResultInCamera(resultPolicy.usesRealityKit)
         let model = ResultARModel.build(wall: wall, result: result)
-        state.resultInCamera = live.showResult(model, builtFor: pose)
-        guard state.resultInCamera else { return }
+        // The battery's middle, or the meter without a spot, in the model's coordinates.
+        let focus = (result.spotCenter(on: wall) ?? wall.meter) - wall.meter
+        guard live.showResult(model, builtFor: pose, focus: focus) else {
+            resultPolicy.modelRemoved()
+            return
+        }
         live.setResultVisible(state.tracking == .normal)
         if rising { ResultARModel.rise(model) }
     }
 
+    /// What the AR result's model is built from, for `ResultOverlayPolicy.needsModel`: the
+    /// meter, the ground, the ends and each piece of wall.
+    private static func modelShape(_ wall: WallGeometry) -> ResultModelShape {
+        var shape = ResultModelShape(
+            points: [wall.meter], values: [wall.groundY, wall.leftEnd, wall.rightEnd],
+            directions: [wall.along, wall.outward]
+        )
+        for piece in wall.cornerSegments {
+            shape.points.append(piece.anchor)
+            shape.values += [piece.span.lowerBound, piece.span.upperBound, piece.anchorS]
+            shape.directions += [piece.along, piece.outward]
+        }
+        return shape
+    }
+
+    /// Looks at the AR scene about ten times a second while "See it on your wall" is up, and
+    /// lets the screen's drawing step aside once the scene is seen drawing the result, for as
+    /// long as the scene holds it (`ResultOverlayPolicy`). On its own clock, not in `ingest`: it
+    /// has to notice a scene that stopped holding it whether frames arrive or not.
+    private func watchResultInCamera() {
+        resultWatch?.cancel()
+        resultWatch = Task { [weak self] in
+            while !Task.isCancelled {
+                guard let self else { return }
+                guard self.state.phase == .resultAR, let live = self.live else {
+                    // Nothing left to watch: the screen draws the result (review of #100).
+                    self.setResultInCamera(false)
+                    return
+                }
+                let look = live.resultIsDrawn()
+                self.setResultInCamera(self.resultPolicy.update(drawn: look.drawn, held: look.held, time: self.screenTime))
+                try? await Task.sleep(for: .milliseconds(100))
+            }
+        }
+    }
+
+    /// Which layer draws the result: the AR scene (true) or the screen's overlay (false). The
+    /// AR scene's model shows only while it owns the result (`LiveCapture.setResultOwned`), and
+    /// both change here together, so the two layers are never both on screen: not while a new
+    /// model waits to be seen, and not while tracking comes back and `ingest` enables the model
+    /// before the next look (review of #100).
+    private func setResultInCamera(_ usesRealityKit: Bool) {
+        live?.setResultOwned(usesRealityKit)
+        guard state.resultInCamera != usesRealityKit else { return }
+        RuntimeLog.engine.info("AR result drawn by \(usesRealityKit ? "the AR scene" : "the screen overlay", privacy: .public)")
+        state.resultInCamera = usesRealityKit
+    }
+
     private func hideResultInCamera() {
+        resultWatch?.cancel()
+        resultWatch = nil
+        resultPolicy = ResultOverlayPolicy()
         live?.hideResult()
         state.resultInCamera = false
     }

ios/HouseScan/UI/Camera/WayfindingOverlay.swift

@@ -90,8 +90,9 @@ struct WayfindingOverlay: View {
     }
 }
 
-/// The aim ring, or a chevron at the screen edge pointing toward it.
-private struct TargetMarker: View {
+/// The aim ring, or a chevron at the screen edge pointing toward it. Also the chevron toward
+/// the battery spot on "See it on your wall" (`ResultARScreen`).
+struct TargetMarker: View {
     enum Placement: Equatable {
         case onScreen(CGPoint, radius: CGFloat)
         case offScreen(CGPoint, angle: Angle)

ios/HouseScan/UI/Components/CameraChrome.swift

@@ -15,6 +15,9 @@ struct CameraChrome<Bottom: View>: View {
     /// Taps on the open camera area, in the camera view's coordinates (full screen, which is
     /// the window's global space). Nil when the screen has nothing to tap.
     var onCameraTap: ((CGPoint) -> Void)?
+    /// Where the card and the bottom controls cover the camera, measured as laid out at the
+    /// current text size. Nil when the screen doesn't need it.
+    var cover: Binding<ChromeCover>?
     @ViewBuilder var bottom: Bottom
 
     var body: some View {
@@ -52,15 +55,27 @@ struct CameraChrome<Bottom: View>: View {
             }
             .frame(minHeight: 36)
             InstructionCard(instruction: instruction, tone: tone, reply: reply, eyebrow: eyebrow)
+                .onGeometryChange(for: CGFloat.self) { $0.frame(in: .global).maxY } action: { value in if let cover { cover.wrappedValue.cardBottom = value } }
             Spacer(minLength: 0)
             bottom
+                .onGeometryChange(for: CGFloat.self) { $0.frame(in: .global).minY } action: { value in if let cover { cover.wrappedValue.controlsTop = value } }
         }
         .padding(.horizontal, Metrics.edge)
         .padding(.top, 4)
         .padding(.bottom, 8)
     }
 }
 
+/// Where `CameraChrome` covers the camera, in the window's coordinates: the instruction card's
+/// bottom edge and the bottom controls' top edge. The camera between them is what the homeowner
+/// can see. Measured, not assumed: at the largest text sizes the card grows far past its usual
+/// 220 pt (review of #100). Nil until laid out. Measured with `onGeometryChange` rather than a
+/// preference key, whose change handler can't set view state under Swift 6's checks.
+struct ChromeCover: Equatable {
+    var cardBottom: CGFloat?
+    var controlsTop: CGFloat?
+}
+
 /// Reads the full-screen camera view size so buttons can send "the reticle" (nil point)
 /// with the right `viewSize`.
 struct CameraSizeReader: View {

ios/HouseScan/UI/Preview/DemoEngine.swift

@@ -18,6 +18,8 @@ final class DemoEngine: ScanActions {
     /// through the engine's own mapping, in place of the hand-made samples.
     private let resultFile: String?
     private let rejectUpload: Bool
+    /// `-uiDemoSpotOffScreen`: on "See it on your wall", the phone aims away from the spot.
+    private let spotOffScreen: Bool
     /// Which request the gap screen shows (`-uiDemoGap`); the phone's ground request by default.
     private let gapKind: String?
     /// The tilt-up step was answered or skipped.
@@ -73,6 +75,7 @@ final class DemoEngine: ScanActions {
         resultFile = nil
         #endif
         rejectUpload = arguments.contains("-uiDemoRejected")
+        spotOffScreen = arguments.contains("-uiDemoSpotOffScreen")
         gapKind = value("-uiDemoGap")
         state.feed = DemoScene.image.map(CameraFeed.still) ?? .none
         state.isReplay = true
@@ -234,6 +237,7 @@ final class DemoEngine: ScanActions {
             placeMeter()
             finishedWalkState()
             showResult()
+            if spotOffScreen { state.projection = DemoScene.awayFromSpotProjection }
             state.phase = .resultAR
         case .unsupported:
             state.failure = .arUnsupported