Blurt for iPhone: the app that listens, the keyboard that inserts

.claude/agents/cleanup-reviewer.md

@@ -71,6 +71,26 @@ design. Note also that `check.sh` already runs `periphery scan --strict` with
 `retain_public: false`, so plainly-unreferenced symbols are caught — spend your
 effort on what periphery cannot see.
 
+On the iPhone (`App/BlurtiOS/`), equally deliberate:
+
+- **The two losing mic concepts are on purpose.** `VoiceRibs`, `VoiceStreak`,
+  `VoiceElementKind`'s `.ribs`/`.streak`, `SharedStore.voiceElementKind` and the
+  `-BlurtGalleryVoice` switch are marked TEMPORARY: three concepts are built side
+  by side until one is picked (`DESIGN.md` › The voice element), then the losers go
+  together. Don't propose deleting one piecemeal.
+- **The gallery and the probe screens are entry points**, reached by launch
+  arguments (`-BlurtGallery…`, `-BlurtProbeField`) from `scripts/design-capture.sh`,
+  `ios-keyboard-shot.sh`, `ios-keyboard-flows.sh` and `apple-geometry.sh` — not
+  from any view. Likewise the `BlurtiOSProbe` XCUITest helpers.
+- **`BlurtiOSCore` uses `package` access, not `public`,** and its explicit
+  `package init`s exist because a memberwise initializer is only ever internal.
+  Seams with one production use (`KeyboardModel.transport`, `.urlOpener`,
+  `.proxyOverride`, `SharedStore.override`) are there for the tests.
+- **`SimulatorAudioSource` is the simulator's microphone**, not a duplicate of
+  `WindowedAudioSource`: `AVCaptureSession` carries no audio in the simulator.
+- The iPhone periphery scan is CI's and `ios-check.sh`'s, with `--retain-public`,
+  so it reports the iPhone code's own dead declarations — `package` ones included.
+
 ## Method
 
 Verify every claim by reading the real code; never report a suspicion. For an

.claude/agents/macos-hig-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: macos-hig-reviewer
-description: Reviews SwiftUI/AppKit UI changes against macOS Human Interface Guidelines — modality, alerts vs inline validation, grouped-form structure, controls, and native idioms. Use after editing views in App/Blurt (wizard, settings, overlay).
+description: Reviews SwiftUI/AppKit UI changes against macOS Human Interface Guidelines — modality, alerts vs inline validation, grouped-form structure, controls, and native idioms. Use after editing views in App/Blurt (wizard, settings, overlay). Mac only — not for App/BlurtiOS, whose views follow App/BlurtiOS/DESIGN.md.
 tools: Read, Grep, Glob
 ---
 

.claude/agents/swift6-concurrency-reviewer.md

@@ -1,13 +1,17 @@
 ---
 name: swift6-concurrency-reviewer
-description: Reviews Swift changes for Swift 6 strict-concurrency correctness (actor isolation, Sendable, @MainActor, data races) and Blurt's documented audio/pipeline invariants. Use after editing engine or app code that touches actors, async, the mic capture path, or the dictation pipeline.
+description: Reviews Swift changes for Swift 6 strict-concurrency correctness (actor isolation, Sendable, @MainActor, data races) and Blurt's documented audio/pipeline invariants. Use after editing engine, Mac app or iPhone (App/BlurtiOS) code that touches actors, async, the mic capture path, the dictation pipeline, or the keyboard's hand-off with the app.
 tools: Read, Grep, Glob, Bash
 ---
 
-You are a Swift 6 strict-concurrency reviewer for Blurt, a macOS dictation
-app. The engine (`Sources/BlurtEngine/`) is a `swift-tools-version:6.2`
-package with **no external dependencies**; the app shell (`App/Blurt/`) is
-AppKit/SwiftUI.
+You are a Swift 6 strict-concurrency reviewer for Blurt, a dictation app for
+macOS and iPhone. The engine (`Sources/BlurtEngine/`) is a `swift-tools-version:6.2`
+package with **no external dependencies**; the Mac shell (`App/Blurt/`) is
+AppKit/SwiftUI. The iPhone app (`App/BlurtiOS/`) is two processes over one App
+Group — the app (listens and transcribes) and a keyboard extension (inserts the
+words) — with their shared logic in the `BlurtiOSCore` static framework. Every
+iPhone target defaults to the main actor (`SWIFT_DEFAULT_ACTOR_ISOLATION`), so
+anything that runs elsewhere is spelled `nonisolated`.
 
 ## What to review
 
@@ -51,6 +55,29 @@ Look at the changes (default to the working diff via `git diff` and
   `BlurtUITests` XCUITest bundle is the exception), and must never touch the real
   Keychain (`APIKeyStore`) — use an isolated service.
 
+### On the iPhone (`App/BlurtiOS/`)
+
+- **The keyboard never hears anything:** no `AVFoundation`/`AVFAudio` in
+  `BlurtKeyboard/`, `Shared/` or `BlurtiOSCore/` (the keyboard links the core).
+  Capture lives only in the app (`WindowedAudioSource`, `SimulatorAudioSource`).
+- **Payloads that cross processes or the capture path are `nonisolated`** —
+  `SharedStore`, `PhaseSnapshot`, `KeyboardCommand`, `DictationResult` and the
+  rest in `SharedState.swift`. Flag one that drifts back to the main-actor default.
+- **System callbacks arrive off the main actor:** a `DarwinObserver` handler and
+  `requestSupplementaryLexicon`'s callback (an XPC queue) are `@Sendable` and hop
+  with `Task { @MainActor in … }`; a main-actor closure there traps at runtime.
+- **The keyboard never cancels words behind the user's back:** a `.cancel` over a
+  recording or a transcription comes only from the × key or the term field opened
+  over a highlighted word. Ordering bugs between the keyboard's picture (the last
+  phase it read) and the app's real state are where this breaks — flag a cancel
+  sent on a stale `.recording`/`.processing` snapshot.
+- **An automatic window close ends the session before the feed:** the release has
+  to find the audio, so `ListeningWindow.onClosingOnItsOwn` is awaited before
+  `source.close()`.
+- **`BlurtiOSTests` run serially** — they swap the global `SharedStore.override`;
+  an async test suspended mid-await must not see another suite's. Flag a change
+  that re-enables parallel testing for that bundle.
+
 ## How to report
 
 Verify before asserting: read the surrounding code, and if useful run

.claude/settings.json

@@ -22,6 +22,10 @@
       "Bash(scripts/check.sh --portable)",
       "Bash(./scripts/check.sh --portable)",
       "Bash(scripts/dev-build.sh)",
+      "Bash(scripts/ios-sim.sh*)",
+      "Bash(scripts/ios-test.sh*)",
+      "Bash(scripts/ios-check.sh*)",
+      "Bash(scripts/ios-typecheck.sh*)",
       "Bash(prettier *)",
       "Bash(actionlint)",
       "Bash(actionlint *)",

.claude/skills/check/SKILL.md

@@ -123,3 +123,16 @@ hides every lint finding behind it — expect to fix a batch, not a queue.
   missing tool. A local run that ends `ok (UI suite + leak scan NOT run …)` is
   green for everything it covered — just don't claim the integration suite
   passed. That answer comes from `check.yml` on the PR.
+
+## The iPhone app
+
+`check.sh` covers `App/BlurtiOS` with the dependency guard, the invariants and the linters, and —
+off CI, when an iPhone simulator on this Xcode's iOS runtime exists — `scripts/ios-check.sh`: the
+tests with `BlurtiOSCore`'s coverage gate, `swiftlint analyze`, the probe build and periphery over
+the iPhone project. Without that runtime it is skipped with a note (the closing `ok` line says so)
+and CI's `ios-build` job, which runs the same script, is the authority; `check.sh` then runs
+`scripts/ios-typecheck.sh` instead, which typechecks the iPhone targets against the Mac Catalyst
+frameworks — the stand-in for a Mac with only the Command Line Tools. Locally, `scripts/ios-test.sh` runs `BlurtiOSTests` on a
+simulator when Xcode is installed and enforces `BlurtiOSCore`'s line-coverage floor (`MIN_IOS_COVERAGE`, 88%;
+`BLURT_IOS_SANITIZER=thread` or `address` runs the TSan / ASan pass CI's `ios-sanitizers` job
+runs), and `scripts/ios-sim.sh` builds and launches the app there.

.claude/skills/project-guardrails/SKILL.md

@@ -37,7 +37,7 @@ genuinely correct, and reaching for it means it's time to stop and ask.
   a second time inside the capture lock and held a duplicate of the whole
   utterance (~3.7 MB at the cap) until release. Don't reintroduce a buffered
   copy "just in case" — there is no retry-from-buffer path, by design.
-- **Don't pre-open the mic to make presses feel faster.** `MicCapture.warmUp()`
+- **(macOS shell) Don't pre-open the mic to make presses feel faster.** `MicCapture.warmUp()`
   is stateless on purpose — build a session, drop it — and there is no warm or
   prepared recorder to reuse. Measured on hardware: building a session (or the
   retired `prepareToRecord()`) leaves the device closed and costs ~15 ms, while
@@ -129,7 +129,7 @@ only one of stt_prompt or prompt; they are the same field`, before the audio is
   default does not describe the behaviour. Note the plural is the documented
   spelling, but the singular `language_code` is accepted too (a 200, not an
   unknown-key 400), so both are live and `KeytermsWireTests` pins both absent.
-- **Injection is always a clipboard paste** (save → write → ⌘V → settle →
+- **(macOS shell) Injection is always a clipboard paste** (save → write → ⌘V → settle →
   restore), degrading to "left it on the clipboard" when the target is lost. No
   keystroke-by-keystroke typing path, no length threshold.
 
@@ -179,3 +179,27 @@ only one of stt_prompt or prompt; they are the same field`, before the audio is
   hardened runtime and a **secure timestamp** (`--options runtime --timestamp`),
   or notarization rejects the build. `release-build.sh` re-signs frameworks for
   this — don't remove it.
+
+## iPhone (App/BlurtiOS)
+
+- **The keyboard never hears anything.** iOS lets no keyboard use the microphone; the app
+  listens and transcribes, the keyboard is a remote control over the App Group that inserts
+  the words. No `AVFoundation` in `BlurtKeyboard/`, `Shared/` or `BlurtiOSCore/` (the keyboard
+  links it) (mechanized).
+- The app's microphone is a _listening window_, opened once while the app is in front and
+  kept open, not a per-press capture — the two rows marked "(macOS shell)" above do not apply.
+- Insertion is the keyboard's `textDocumentProxy`; the clipboard is only the fallback when no
+  keyboard is there to take the words, and the phase then says "Copied", never "Pasted".
+- **Logic lives in `BlurtiOSCore`, UI in the targets** — the Mac's engine/shell split. The
+  core has no SwiftUI, no views and no audio; its API is `package`, not `public` (periphery
+  still sees dead code); it is static, linked by both targets. It alone is coverage-gated at
+  88%. A UI hook the model needs is a shell-side extension, never SwiftUI in the core.
+- **The keyboard never cancels words behind the user's back.** A cancel over a recording or a
+  transcription comes only from the × key or the term field opened over a highlighted word —
+  not from leaving the screen, a swipe across the orb, or the plain +. The fuzz test enforces it.
+- **No private Settings URLs** (`App-Prefs:`): `openSettingsURLString` only, and the copy names
+  the whole path (Apps › Blurt › Keyboards).
+- **No bundled brand fonts** — removed over their licence; `BlurtType`'s roles use system faces.
+- **`BlurtiOSTests` run serially** (scheme + `-parallel-testing-enabled NO`): they swap a global
+  `SharedStore.override`, which `.serialized` alone doesn't protect across suites.
+- The full list, with every number, is `App/BlurtiOS/DESIGN.md`.

.github/workflows/check.yml

@@ -213,6 +213,96 @@ jobs:
           if-no-files-found: error
           retention-days: 14
 
+  # The engine is a two-platform package, and `check` only ever compiles it for
+  # macOS: `swift test` builds for the host, and every job above runs on one.
+  # A macOS-only symbol that escapes its `#if os(macOS)` fence therefore passes
+  # `check` and breaks the iOS app, which is why this job exists and why `gate`
+  # treats it as required. It builds the library alone, for the simulator SDK —
+  # `xcodebuild` rather than `swift build`, because cross-compiling needs the
+  # SDK/destination handling xcodebuild owns, and it resolves the package
+  # straight from the checkout, no project needed. `generic/platform=iOS
+  # Simulator` builds against the runner's default (latest installed) simulator
+  # SDK without naming a device or pinning an iOS version. The scheme is the
+  # package's own `BlurtEngine` product scheme, so only the library builds; the
+  # test target stays a macOS (`swift test`) concern.
+  ios-build:
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
+    runs-on: macos-26
+    # The simulator build plus the unit tests take ~12 minutes on macos-26 and
+    # the periphery scan rebuilds after them; 15 cut the scan off mid-run.
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout blurt
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          path: blurt
+          persist-credentials: false
+
+      - name: Build BlurtEngine for iOS
+        working-directory: blurt
+        run: |
+          xcodebuild -scheme BlurtEngine \
+            -destination 'generic/platform=iOS Simulator' \
+            -derivedDataPath "$RUNNER_TEMP/BlurtEngine-iOS" \
+            build
+
+      - name: Install XcodeGen
+        # Just the one formula, not `brew bundle --file=Brewfile`: the iPhone
+        # app's project is the only thing this job generates, and installing the
+        # other eleven tools would cost more than the build it precedes. xcodegen
+        # is in the Brewfile too, so this is the version check.sh uses.
+        run: brew install xcodegen
+
+      - name: Install the iPhone gates' tools
+        # swiftlint for `swiftlint analyze`, periphery for the unused-code scan,
+        # xcbeautify for the build output; all in the Brewfile too, so these are
+        # the versions check.sh uses. The project itself is generated, not
+        # committed (people open App/Blurt's; this one is regenerated a second
+        # before every build by ios-test.sh, so it can never go stale).
+        run: brew install swiftlint periphery xcbeautify
+
+      - name: Build the iPhone app and its keyboard, and run its quality gates
+        working-directory: blurt
+        # scripts/ios-check.sh — the iPhone's check.sh: BlurtiOSTests (warnings
+        # as errors, BlurtiOSCore's coverage gate) on whichever iPhone simulator
+        # the runner has (scripts/ios-lib.sh picks), then `swiftlint analyze`
+        # over that from-scratch build's log, then periphery. Ad hoc signing: the
+        # simulator accepts it and, unlike no signing, it embeds the App Group
+        # entitlement.
+        run: BLURT_DERIVED_DATA="$RUNNER_TEMP/BlurtiOS" scripts/ios-check.sh
+
+  # The iPhone suite under each sanitizer, as check.sh runs the engine's. A job
+  # of its own, one runner per sanitizer, rather than more steps in ios-build:
+  # each is a full instrumented rebuild, and ios-build is already near its
+  # timeout. The coverage gate runs in ios-build's plain pass only.
+  ios-sanitizers:
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
+    runs-on: macos-26
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        sanitizer: [thread, address]
+
+    steps:
+      - name: Checkout blurt
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          path: blurt
+          persist-credentials: false
+
+      - name: Install XcodeGen and xcbeautify
+        run: brew install xcodegen xcbeautify
+
+      - name: Run the iPhone unit tests under the ${{ matrix.sanitizer }} sanitizer
+        working-directory: blurt
+        env:
+          BLURT_IOS_SANITIZER: ${{ matrix.sanitizer }}
+        run: BLURT_DERIVED_DATA="$RUNNER_TEMP/BlurtiOS" scripts/ios-test.sh
+
   # Always-runs summary job, so a *skipped* `check` can't be mistaken for a pass.
   # GitHub reports a skipped required check to branch protection as successful, so
   # anything that makes `check` skip — the `changes` filter erroring, a `needs`
@@ -223,30 +313,40 @@ jobs:
   # NOTE: this only protects the repo once branch protection requires `gate`
   # instead of (or as well as) `check` — that's a repo settings change.
   gate:
-    needs: [changes, check]
+    needs: [changes, check, ios-build, ios-sanitizers]
     if: always()
     runs-on: ubuntu-latest
     steps:
-      - name: Assert the macOS gate ran or was intentionally skipped
+      - name: Assert the macOS, iOS and iOS-sanitizer gates ran or were intentionally skipped
         env:
           CHECK_RESULT: ${{ needs.check.result }}
+          IOS_RESULT: ${{ needs.ios-build.result }}
+          IOS_SANITIZERS_RESULT: ${{ needs.ios-sanitizers.result }}
           CHANGES_RESULT: ${{ needs.changes.result }}
           CODE_CHANGED: ${{ needs.changes.outputs.code }}
         run: |
-          echo "changes=$CHANGES_RESULT code=$CODE_CHANGED check=$CHECK_RESULT"
+          echo "changes=$CHANGES_RESULT code=$CODE_CHANGED check=$CHECK_RESULT ios-build=$IOS_RESULT ios-sanitizers=$IOS_SANITIZERS_RESULT"
           if [ "$CHANGES_RESULT" != "success" ]; then
             echo "error: the changes filter did not succeed, so the gate cannot be trusted" >&2
             exit 1
           fi
-          case "$CHECK_RESULT" in
-            success) echo "macOS gate passed" ;;
-            skipped)
-              if [ "$CODE_CHANGED" = "false" ]; then
-                echo "docs-only change; macOS gate intentionally skipped"
-              else
-                echo "error: check was skipped but code changed" >&2
-                exit 1
-              fi
-              ;;
-            *) echo "error: macOS gate result was '$CHECK_RESULT'" >&2; exit 1 ;;
-          esac
+          # Same rule for both platform gates: green, or skipped only because the
+          # change was docs-only. Written once so the iOS gate can't drift into
+          # a looser reading than the macOS one.
+          assert_gate() {
+            case "$2" in
+              success) echo "$1 gate passed" ;;
+              skipped)
+                if [ "$CODE_CHANGED" = "false" ]; then
+                  echo "docs-only change; $1 gate intentionally skipped"
+                else
+                  echo "error: $1 gate was skipped but code changed" >&2
+                  exit 1
+                fi
+                ;;
+              *) echo "error: $1 gate result was '$2'" >&2; exit 1 ;;
+            esac
+          }
+          assert_gate macOS "$CHECK_RESULT"
+          assert_gate iOS "$IOS_RESULT"
+          assert_gate "iOS sanitizers" "$IOS_SANITIZERS_RESULT"

.github/workflows/codeql.yml

@@ -95,6 +95,15 @@ jobs:
             -derivedDataPath "$DERIVED" \
             -resolvePackageDependencies
 
+      # The iPhone app's project is generated, not committed (see check.yml's
+      # ios-build), so generate it before tracing starts. It has no remote
+      # packages to resolve — only the local engine.
+      - name: Generate the iPhone app's project (untraced)
+        working-directory: App/BlurtiOS
+        run: |
+          brew install xcodegen
+          xcodegen generate --quiet
+
       - name: Initialize CodeQL
         uses: github/codeql-action/init@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4
         with:
@@ -122,6 +131,27 @@ jobs:
             CODE_SIGNING_ALLOWED=NO \
             build
 
+      # The iPhone app, its keyboard and BlurtiOSCore, traced in the same
+      # database: CodeQL analyses whatever the job compiles between init and
+      # analyze, so the Mac build alone would leave App/BlurtiOS unscanned.
+      # Simulator, signing off — nothing here needs a device or a team. One
+      # architecture: CodeQL extracts every compile, and a second slice would
+      # compile and extract every file again for nothing new.
+      - name: Build Swift (iPhone)
+        working-directory: App/BlurtiOS
+        run: |
+          xcodebuild \
+            -project BlurtiOS.xcodeproj \
+            -scheme BlurtiOS \
+            -configuration Debug \
+            -destination 'generic/platform=iOS Simulator' \
+            -derivedDataPath "$DERIVED-ios" \
+            ARCHS=arm64 ONLY_ACTIVE_ARCH=YES \
+            CODE_SIGN_IDENTITY="-" \
+            CODE_SIGNING_REQUIRED=NO \
+            CODE_SIGNING_ALLOWED=NO \
+            build
+
       - name: Perform CodeQL Analysis
         uses: github/codeql-action/analyze@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4
         with: