feat: onboarding flow with permission-gated stage machine

[quiet-node]

Summary

• Implements the full onboarding state machine: launch checks live permissions first, routes to permissions screen if either is missing, advances to intro screen once both are granted, and shows the Ask Bar after "Get Started"
• Fixes screen recording permission false positive where the status went green immediately after opening System Settings (root cause: CGWindowListCopyWindowInfo(0, 0) always returns non-null; fix: CGPreflightScreenCaptureAccess)
• Aligns intro screen visual style with the permissions screen (matching card, amber glow, typography)
• "Get Started" now immediately shows the Ask Bar without requiring a relaunch (restores NSPanel level and calls show_overlay directly)

Flow

Launch
  -> check accessibility + screen recording
  -> missing? -> permissions screen
  -> both granted + stage != complete? -> intro screen
  -> stage == complete -> Ask Bar directly

Permissions screen
  -> polls check_screen_recording_tcc_granted every ~1s
  -> Quit & Reopen triggers app_handle.restart()
  -> on relaunch, permissions now granted -> intro screen shown

Intro screen
  -> Get Started -> writes stage=complete to DB, shows Ask Bar

Test plan

• Fresh install: launches to permissions screen when either permission missing
• Grant accessibility only: screen recording row stays red, no false positive
• Grant both, quit and reopen: shows intro screen
• Click Get Started: Ask Bar opens immediately, no relaunch needed
• Subsequent launches with both granted + stage=complete: goes straight to Ask Bar
• Revoke screen recording mid-session, relaunch: returns to permissions screen
• bun run test && bun run validate-build pass clean

🤖 Generated with Claude Code

[quiet-node]

Code review

Found 3 issues:

1. notify_frontend_ready ignores compute_startup_stage and calls live permission APIs at startup — onboarding.rs defines compute_startup_stage with an explicit doc comment: "Reads only the persisted stage — no permission API calls. macOS 15 broke CGPreflightScreenCaptureAccess..." But notify_frontend_ready never calls it; instead it calls is_accessibility_granted() and is_screen_recording_granted() inline. On macOS 15, where CGPreflightScreenCaptureAccess can return false after a successful grant, this means a user who completed onboarding gets bounced back to the permissions screen on every relaunch — a permanent loop. compute_startup_stage was specifically written to prevent this and is dead code.

thuki/src-tauri/src/lib.rs

Lines 378 to 413 in e634285

	if LAUNCH_SHOW_PENDING.swap(false, Ordering::SeqCst) {
	#[cfg(target_os = "macos")]
	{
	let ax = permissions::is_accessibility_granted();
	// Use CGPreflightScreenCaptureAccess for the startup check: it is
	// fast (no blocking) and accurate after a process restart, which is
	// the only path that reaches this code with a fresh TCC decision.
	// check_screen_recording_tcc_granted (SCShareableContent) is used
	// only during onboarding polling where live state is needed without
	// requiring a restart.
	let sr = permissions::is_screen_recording_granted();
	if let Ok(conn) = db.0.lock() {
	if !ax || !sr {
	// Permissions missing. Reset stage to "permissions" so
	// the next launch after granting will advance to intro.
	// This also handles revocation after a completed onboarding.
	let _ = onboarding::set_stage(&conn, &onboarding::OnboardingStage::Permissions);
	show_onboarding_window(&app_handle, onboarding::OnboardingStage::Permissions);
	return;
	}
	// Both permissions granted. Read the persisted stage.
	let stage = onboarding::get_stage(&conn)
	.unwrap_or(onboarding::OnboardingStage::Permissions);
	match stage {
	onboarding::OnboardingStage::Complete => {
	// Onboarding finished previously — fall through to
	// show the normal overlay.
	}
	_ => {
	// Stage is "permissions" (first launch after grant)
	// or "intro" (resumed). Advance to intro and show it.
	let _ = onboarding::set_stage(&conn, &onboarding::OnboardingStage::Intro);
	show_onboarding_window(&app_handle, onboarding::OnboardingStage::Intro);

2. check_screen_recording_tcc_granted now uses CGPreflightScreenCaptureAccess for polling, which the PR's own comments say is unreliable on macOS 15 — PermissionsStep polls this command every ~500ms to detect when Screen Recording is granted and show the "Quit & Reopen" prompt. But the PR's own quit_and_relaunch doc comment says "CGPreflightScreenCaptureAccess, which can return false on macOS 15 even after a successful grant," and onboarding.rs repeats this. So on macOS 15, the polling loop will never detect the grant — the "Quit & Reopen" button never appears and the user is stuck.

thuki/src-tauri/src/permissions.rs

Lines 83 to 97 in e634285

	/// Returns whether Screen Recording permission has been granted.
	#[tauri::command]
	#[cfg(target_os = "macos")]
	#[cfg_attr(coverage_nightly, coverage(off))]
	pub fn check_screen_recording_permission() -> bool {
	is_screen_recording_granted()
	}
	/// Opens System Settings to the Screen Recording privacy pane so the user
	/// can enable the permission without navigating there manually.
	#[tauri::command]
	#[cfg(target_os = "macos")]
	#[cfg_attr(coverage_nightly, coverage(off))]
	pub fn open_screen_recording_settings() -> Result<(), String> {
	std::process::Command::new("open")

3. finish_onboarding is exempt from coverage but is not a thin wrapper (CLAUDE.md says "Functions excluded from coverage with #[cfg_attr(coverage_nightly, coverage(off))] must be thin wrappers (Tauri commands, filesystem I/O) whose logic is tested through the functions they delegate to") — The function locks the DB, writes the stage, drops the lock, then in a run_on_main_thread closure resizes the window, calls init_panel, and calls show_overlay. None of that orchestration logic is exercised by any test.

thuki/src-tauri/src/lib.rs

Lines 424 to 460 in e634285

	}
	}
	// ─── Onboarding completion ───────────────────────────────────────────────────
	/// Called when the user clicks "Get Started" on the intro screen.
	/// Marks onboarding complete in the DB, restores the window to overlay mode,
	/// and immediately shows the Ask Bar — no relaunch required.
	#[tauri::command]
	#[cfg_attr(coverage_nightly, coverage(off))]
	fn finish_onboarding(
	db: tauri::State<history::Database>,
	app_handle: tauri::AppHandle,
	) -> Result<(), String> {
	let conn = db.0.lock().map_err(|e| format!("db lock poisoned: {e}"))?;
	onboarding::set_stage(&conn, &onboarding::OnboardingStage::Complete)
	.map_err(|e| format!("db write failed: {e}"))?;
	drop(conn);
	// Restore panel to overlay configuration and show the Ask Bar.
	// Must run on the macOS main thread because NSPanel APIs are not thread-safe.
	let handle = app_handle.clone();
	let _ = app_handle.run_on_main_thread(move || {
	// Resize the window back to the collapsed overlay dimensions before
	// positioning, so the overlay appears at the correct size.
	if let Some(window) = handle.get_webview_window("main") {
	let _ = window.set_size(tauri::Size::Logical(tauri::LogicalSize::new(
	OVERLAY_LOGICAL_WIDTH,
	OVERLAY_LOGICAL_HEIGHT_COLLAPSED,
	)));
	}
	// Restore NSPanel level, shadow, and style that show_onboarding_window
	// changed for the onboarding appearance.
	#[cfg(target_os = "macos")]
	init_panel(&handle);
	show_overlay(&handle, crate::context::ActivationContext::empty());
	});

---

🤖 Generated with Claude Code

_{If this code review was useful, please react with 👍. Otherwise, react with 👎.}