ios: guided wall scan from the meter to a battery spot

.github/labels.json

@@ -24,6 +24,11 @@
     "color": "b60205",
     "description": "Not ready to merge. State what must change before it is ready."
   },
+  {
+    "name": "full-ui",
+    "color": "5319e7",
+    "description": "iOS CI also runs the every-state accessibility audit (about 10 more minutes)."
+  },
   {
     "name": "size:XS",
     "color": "0e8a16",

.github/workflows/ios.yml

@@ -2,35 +2,55 @@ name: iOS
 
 on:
   push:
-    branches: [main]
+    branches: [main, t3/ios-mvf]
     paths:
       - "ios/**"
+      - "!ios/**/*.md"
       - ".github/workflows/ios.yml"
   pull_request:
+    # ready_for_review: drafts are skipped below, so run once a draft is marked ready.
+    # labeled: adding full-ui reruns the pull request with the accessibility audit.
+    types: [opened, synchronize, reopened, ready_for_review, labeled]
     paths:
       - "ios/**"
+      - "!ios/**/*.md"
       - ".github/workflows/ios.yml"
+  # Runs every test, the audit included, on any branch.
+  workflow_dispatch:
 
 permissions:
   contents: read
 
 concurrency:
-  group: ios-${{ github.ref }}
+  # Adding any label other than full-ui gets a group of its own, so it cannot cancel a real run.
+  group: ios-${{ github.ref }}${{ github.event.action == 'labeled' && github.event.label.name != 'full-ui' && format('-{0}', github.run_id) || '' }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   ios-build:
     name: iOS build
+    # A free account runs 5 macOS jobs at once, shared by every open pull request, so drafts and
+    # labels other than full-ui don't take a slot.
+    if: >-
+      github.event_name != 'pull_request' ||
+      (!github.event.pull_request.draft &&
+       (github.event.action != 'labeled' || github.event.label.name == 'full-ui'))
     # macos-26 (arm64) is the newest GA macOS image. The xcode-27 image is still a preview.
     runs-on: macos-26
-    timeout-minutes: 30
+    timeout-minutes: 45
     env:
       # Newest stable Xcode on macos-26 per images/macos/macos-26-arm64-Readme.md (image 20260907).
       DEVELOPER_DIR: /Applications/Xcode_26.6.app/Contents/Developer
+      # iPhone 17 on iOS 26.5 ships with Xcode 26.6 on macos-26 (images/macos/macos-26-arm64-Readme.md).
+      SIM_NAME: iPhone 17
+      SIM_OS: "26.5"
       # Homebrew only installs the latest XcodeGen. The release zip gives an exact version,
       # and the drift check below needs the same version the committed project was made with.
       XCODEGEN_VERSION: 2.46.0
       XCODEGEN_SHA256: 4d9e34b62172d645eed6457cac13fc222569974098ef4ee9c3368bedf0196806
+      # The every-state accessibility audit relaunches the app 65 times (about 10 min). Pull
+      # requests skip it unless labelled full-ui; pushes and manual runs always include it.
+      FULL_UI: ${{ github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'full-ui') }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -45,6 +65,45 @@ jobs:
           xcodebuild -version
           swift --version
 
+      # Booting takes 2 to 3 minutes and needs nothing from the build, so it runs alongside the
+      # steps below; the UI test step waits for it.
+      - name: Boot the Simulator in the background
+        run: |
+          runtime="com.apple.CoreSimulator.SimRuntime.iOS-${SIM_OS//./-}"
+          udid="$(xcrun simctl list devices available -j \
+            | jq -r --arg runtime "$runtime" --arg name "$SIM_NAME" \
+              '(.devices[$runtime] // [])[] | select(.name == $name) | .udid' | head -n 1)"
+          if [ -z "$udid" ]; then
+            echo "::error::No $SIM_NAME on iOS $SIM_OS on this runner image. Pick one from the image readme."
+            xcrun simctl list devices available
+            exit 1
+          fi
+          echo "SIM_UDID=$udid" >> "$GITHUB_ENV"
+          nohup xcrun simctl bootstatus "$udid" -b > "$RUNNER_TEMP/simulator-boot.log" 2>&1 &
+
+      # The package's drift test compares the vendored server schemas with the server's own copies:
+      # the checkout's files once that branch merges, else the t3/server branch, which the shallow
+      # checkout leaves out. One of the two is required:
+      # a failed fetch fails the run, and HOUSESCAN_REQUIRE_UPSTREAM makes the tests fail rather
+      # than skip, so CI can't go green without comparing. The checkout counts only when it holds
+      # every compared file: a folder alone isn't enough (main has a server/ without schemas).
+      - name: Fetch the server contract
+        run: |
+          fetch_unless_present() {
+            local branch="$1"; shift
+            local missing=0
+            for file in "$@"; do [ -f "$file" ] || missing=1; done
+            if [ "$missing" = 0 ]; then
+              echo "$* are in the checkout; the drift tests read them."
+              return
+            fi
+            if ! git fetch --no-tags --depth=1 origin "+refs/heads/$branch:refs/remotes/origin/$branch"; then
+              echo "::error::Neither the checkout nor $branch holds $*, so the vendored copies can't be compared."
+              exit 1
+            fi
+          }
+          fetch_unless_present t3/server server/schemas/scene.schema.json server/schemas/result.schema.json server/tests/fixtures/example-scene.json
+
       - name: Install XcodeGen
         run: |
           curl -fsSL -o "$RUNNER_TEMP/xcodegen.zip" \
@@ -69,7 +128,45 @@ jobs:
             exit 1
           fi
 
+      - name: Test HouseScanKit
+        # The capture logic is a plain Swift package; its tests run on macOS without a Simulator.
+        env:
+          HOUSESCAN_REQUIRE_UPSTREAM: "1"
+        run: swift test --package-path ios/HouseScanKit -Xswiftc -warnings-as-errors
+
+      # CI builds once from clean, so the index Xcode keeps for editing is wasted work.
       - name: Build
         run: >-
           xcodebuild -project ios/HouseScan.xcodeproj -scheme HouseScan -configuration Debug
-          -destination "generic/platform=iOS" CODE_SIGNING_ALLOWED=NO build
+          -destination "generic/platform=iOS" CODE_SIGNING_ALLOWED=NO COMPILER_INDEX_STORE_ENABLE=NO
+          HOUSESCAN_GIT_COMMIT="${GITHUB_SHA::12}" build
+
+      - name: Wait for the Simulator
+        timeout-minutes: 10
+        run: |
+          xcrun simctl bootstatus "$SIM_UDID" -b
+          echo "Booted $SIM_NAME on iOS $SIM_OS ($SIM_UDID)."
+
+      - name: UI test the whole flow in the Simulator
+        # Replays the committed synthetic wall (ios/HouseScanUITests/Fixtures/synthetic-wall) with
+        # -autopilot and the bundled sample result.
+        run: |
+          skip=()
+          if [ "$FULL_UI" != "true" ]; then
+            skip=(-skip-testing:HouseScanUITests/ScreenStatesUITests/testEveryStatePassesTheAccessibilityAudit)
+            echo "::notice::Skipped the every-state accessibility audit (about 10 min). Add the full-ui label to run it on this pull request."
+          fi
+          xcodebuild -project ios/HouseScan.xcodeproj -scheme HouseScan -configuration Debug \
+            -destination "id=$SIM_UDID" \
+            -resultBundlePath "$RUNNER_TEMP/HouseScanUITests.xcresult" \
+            -only-testing:HouseScanUITests "${skip[@]}" \
+            COMPILER_INDEX_STORE_ENABLE=NO HOUSESCAN_GIT_COMMIT="${GITHUB_SHA::12}" test
+
+      - name: Keep UI test screenshots
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: ui-test-results
+          path: ${{ runner.temp }}/HouseScanUITests.xcresult
+          if-no-files-found: ignore
+          retention-days: 7

CONTRIBUTING.md

@@ -28,11 +28,13 @@ The `size:*` label describes the effective diff. It is a review signal, not a me
 | --- | --- | --- |
 | Server checks | `server/` changes | `make server` |
 | Web checks | `web/` changes | `make web` |
-| iOS build | `ios/` changes | `make ios` |
+| iOS build | `ios/` changes outside Markdown, on non-draft pull requests | `make ios` |
 | Sync label definitions | `.github/labels.json` changes on `main` | none |
 | Label PR size | a pull request opens or updates | none |
 | TestFlight | someone runs it from the Actions tab | none |
 
+The iOS UI tests skip the every-state accessibility audit on pull requests, because it adds about 10 minutes and macOS runners are scarce. Add the `full-ui` label when a pull request changes screens or copy; pushes to `t3/ios-mvf` and `main` always run it.
+
 `make check` runs the three local suites. They need uv, Node 24 with pnpm, and Xcode 26 or newer; each directory's README has details. No check is required by branch rules yet. Don't call one required until the rules require its status.
 
 Keep workflows that run pull-request code away from production credentials and destructive external systems. A green CI run is evidence for the checks it ran, not proof that a capture works on a real house.

Makefile

@@ -22,7 +22,8 @@ web:
 # CI also regenerates the project and fails on drift; run `make ios-project` for that.
 ios:
 	xcodebuild -project ios/HouseScan.xcodeproj -scheme HouseScan -configuration Debug \
-		-destination "generic/platform=iOS" CODE_SIGNING_ALLOWED=NO build
+		-destination "generic/platform=iOS" CODE_SIGNING_ALLOWED=NO \
+		HOUSESCAN_GIT_COMMIT="$$(git rev-parse --short=12 HEAD 2>/dev/null || echo unknown)" build
 
 # Regenerates ios/HouseScan.xcodeproj from ios/project.yml. Point XCODEGEN at another binary
 # if the one on PATH is not $(XCODEGEN_VERSION): make ios-project XCODEGEN=/path/to/xcodegen

ios/.gitignore

@@ -8,3 +8,7 @@ xcuserdata/
 # Build output when building with -derivedDataPath or into the source tree.
 DerivedData/
 build/
+
+# SwiftPM build output of the capture package.
+HouseScanKit/.build/
+HouseScanKit/.swiftpm/

ios/Config/Info.plist

@@ -20,17 +20,33 @@
 	<string>$(MARKETING_VERSION)</string>
 	<key>CFBundleVersion</key>
 	<string>$(CURRENT_PROJECT_VERSION)</string>
+	<key>HouseScanGitCommit</key>
+	<string>$(HOUSESCAN_GIT_COMMIT)</string>
+	<key>HouseScanServerURL</key>
+	<string>$(HOUSESCAN_SERVER_URL)</string>
+	<key>ITSAppUsesNonExemptEncryption</key>
+	<false/>
 	<key>LSRequiresIPhoneOS</key>
 	<true/>
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsLocalNetworking</key>
+		<true/>
+	</dict>
 	<key>NSCameraUsageDescription</key>
 	<string>House Scan uses the camera to measure the outside wall around your electric meter.</string>
+	<key>NSMotionUsageDescription</key>
+	<string>House Scan records your phone's motion and air pressure during the scan, so it can be measured more accurately. It stays on this phone unless you share the scan.</string>
 	<key>UIApplicationSceneManifest</key>
 	<dict>
 		<key>UIApplicationSupportsMultipleScenes</key>
 		<false/>
 	</dict>
 	<key>UILaunchScreen</key>
-	<dict/>
+	<dict>
+		<key>UIColorName</key>
+		<string>Canvas</string>
+	</dict>
 	<key>UIRequiredDeviceCapabilities</key>
 	<array>
 		<string>arkit</string>

ios/Config/Shared.xcconfig

@@ -7,4 +7,15 @@
 
 BUNDLE_ID_PREFIX = dev.housescanning
 
+// The placement server the app uploads to when no -serverURL launch argument is given; Info.plist
+// carries it as HouseScanServerURL. xcconfig reads // as a comment, so $() splits the slashes.
+// Set it empty in Local.xcconfig to fall back to the bundled sample result.
+HOUSESCAN_SERVER_URL = https:/$()/house-scanning-server.vercel.app
+
 #include? "Local.xcconfig"
+
+// The commit the app was built from, for the scan stamp (HouseScanGitCommit in Info.plist). A
+// build setting, not a build script: the TestFlight job refuses scripts in the build while the
+// signing key exists. CI and `make ios` pass the real commit (HOUSESCAN_GIT_COMMIT=<sha>); a build
+// that doesn't, such as one from Xcode's Run button, says "unknown".
+HOUSESCAN_GIT_COMMIT = unknown