hex/ios/HEXMobile/Assets.xcassets/LaunchBackground.colorset
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Ryan Vogel 9427d069bf
iOS: onboarding follows the desktop flow (#2136)
* iOS: launch screen in the app's first-frame black

The launch screen's LaunchBackground was a dark teal (sRGB 7,17,20, shown
as about 2,17,19) for the ~1.5 s before the app's first frame, which is
HexTheme.bgDeep (0x0A0B0D). It now uses bgDeep's exact components, so
launch hands over to the app without a colour jump.

Verified: built for Simulator; fresh-install launch recorded.

* iOS: onboarding follows the desktop's pages, with the polish fixes

Dax found the iPhone onboarding annoying; Ryan and Dax asked for the
desktop's flow. The three pages (Welcome, Set up Hex, Try the keyboard)
become the desktop's six, in its order and copy style:

1. Setting up Hex: the speech model starts downloading as onboarding
   opens (whichever engine transcriberFactory picks). Before, only home's
   "Set up" started a Parakeet download, so onboarding said "You're all
   set" while home said "Finish setup · 1 step". A launch that found
   Parakeet ended mid-load stays failed (ParakeetLoadGuard) until Try
   again. Moves on after a beat; a failed start holds it with Try again.
2. With Hex: a short demo, a reply dictated with the Hex key. Skip.
3. Let Hex hear you: Microphone and Hex keyboard rows with a one-line
   detail that stays (steady heights) and one-line copy ("With Full
   Access", no mid-phrase wrap). A done row shows only its check (the
   Keyboard row used to keep its Open Settings pill). The pill and the
   page's button say Continue before iOS's prompt (App Review 5.1.1(iv)),
   Continue never needs the microphone, and the page moves on once both
   rows are done. No Skip.
4. Almost ready: only while the model downloads, with its progress;
   Continue without a model only after a failure or 30 s without progress.
5. Your turn: the practice. The field keeps the keyboard up (the old
   page unfocused it ~150 ms after the first letter) and counts once a
   dictation arrives (lastInsertedResultID changes) or three words are
   typed with Full Access. An empty dictation says "Hex didn't hear any
   words. Try again a little louder." on this page only; the keyboard
   notes it in the App Group (keyboard.lastEmptyDictationAt) and still
   shows nothing itself. Skip.
6. Hex is ready: only once every step (model included) is done, else
   "Almost ready" with what's left. Start using Hex never waits.

The download's pill (language and percent) sits in the top bar until the
model is ready; Skip shows on the demo and the practice only. The page
counter and Back are gone, as on the desktop. Saved pages from earlier
builds resume on their new equivalents. Snapshot scenes are renamed
onboarding-setup/-demo/-permissions(-done)/-waiting/-failed/-try(-done,
-empty,-off)/-ready, plus onboarding-tour. zh-Hans strings added.

Verified: xcodebuild test on an iOS 27.2 simulator (385 tests, 0
failures, 1 skipped), including new KeyboardBridgeTests for the empty
dictation note, the practice rule, and saved-page migration; English and
Chinese snapshots of every page; a fresh-install recording.

* iOS onboarding: the practice field takes focus when Hex comes back

Coming back from Settings with both permission rows done moves straight
on to Your turn, but the page opened before Hex was active again, so its
field never took focus and the keyboard stayed down. The page now
focuses the field again when the scene becomes active (unless it already
has focus).

Verified: fresh-install recording on an iOS 27.2 simulator: back from
Settings, Your turn opens with the keyboard up.

* iOS: Ready waits for the model the Hex key itself dictates with

On iOS 26 the keyboard transcribes inside itself with Apple Speech,
whatever Hex uses. When Hex dictates with Parakeet (an English iPhone
without SpeechTranscriber, or a cached Parakeet model), onboarding and
home said Ready while the keyboard's Apple Speech model wasn't there,
and the first Hex key tap said "Open Hex to download English."

KeyboardSpeechPreparation (owned by ContentView, started at launch)
prepares the keyboard's engine:
- Hex dictates with Apple Speech: Hex's model is the same one, so it
  follows Hex's.
- Otherwise it resolves the keyboard's language (AppleSpeechLanguages,
  as the keyboard does) and installs it with AppleSpeechAssets.install,
  the keyboard's own call, which also clears keyboardNeedsHex.
- Apple has no model for it on this iPhone, or Speech lists nothing: it
  marks keyboardNeedsHex, so the Hex key opens Hex (which dictates with
  its own model) from the first tap instead of after a failed one.
  Re-marked at each launch, as the mark lasts a day.
- A failed download (connection) shows on onboarding with Try again.

Why not have the keyboard use Hex's Parakeet: it can't load within a
keyboard extension's memory limit, and handing every dictation to Hex
leaves the app being typed in each time. In-keyboard Apple Speech stays
the path, with the handoff only where Apple has no model.

Onboarding's model stage combines both (OnboardingModel.combine): ready
only when both are, a failure first, fractions averaged only when the
keyboard actually downloads. Home's status line and the setup sheet's
Speech model row count it the same way.

Verified: xcodebuild test, iOS 27.2 simulator: 386 tests, 0 failures,
1 skipped (new: the combine rules). In the simulator (no Apple Speech
assets: "not subscribed to assistant.en_US") it marks the handoff and
onboarding goes on to Parakeet's Ready; a real iPhone must confirm the
Apple Speech download path.

* iOS onboarding: the desktop's motion, the pill flying between places

The desktop onboarding's motion (onboarding_kit/landing.rs, pill.rs):
- Each page's parts roll in 8 pt with a fade on a 0.34 s zero-bounce
  spring, 0.05 s apart (onboardingStagger), and the leaving page lifts
  away 8 pt on 0.26 s. Replaces the old 28 pt sideways page slide.
- The download pill flies from under Setting up Hex to the top bar and
  stays there across pages (matchedGeometryEffect), on the desktop's
  0.42 s flight spring.
- Reduce Motion: parts fade without moving or staggering, the pill
  cross-fades, pages fade.
Stills (--snap-state) show every part at once.

"Watch another one" stays off: on the desktop it fills a long download
on Almost ready; on iPhone the demo is ~6 s and moves on by itself, so a
replay control would only add a label.

Verified: xcodebuild test (386, 0 failures, 1 skipped); fresh-install
recording on an iOS 27.2 simulator, frames checked at each page change.

* iOS onboarding: steady progress and an untruncated pill in flight

Two things the recording showed:
- In the simulator the keyboard's Apple Speech download starts, then
  can't be had and hands off to Hex; that short attempt still counted as
  half of onboarding's progress, so the percent jumped from 0% to 50%.
  A handoff no longer counts as a download.
- The pill flew with its frame, so the small pill's language truncated
  ("Engli… 2%") for about half a second after landing. It now flies by
  position only; each pill keeps its own size.

Verified: fresh-install recording on an iOS 27.2 simulator, frames at
15 fps around the Setting up Hex to demo change, and the percent climbing
from 0% in steps.
2026-11-21 03:27:38 +00:00
..
Contents.json iOS: onboarding follows the desktop flow (#2136) 2026-11-21 03:27:38 +00:00