readme.knowledge.md

# Engineering Knowledge

Project-specific lessons learned while building the idp.global Swift app. Intentionally small and opinionated — append only when a finding will save time on a future task.

## iOS 26 Liquid Glass and progressive blur at screen edges

Context: the pairing welcome screen needed a floating bottom action bar with "native Apple chrome" look — a rounded Liquid Glass pill containing the Scan/NFC buttons, with content gracefully fading as it approaches the top and bottom edges of the screen.

### What we shipped

Simple and reliable: linear-gradient edge fades + a `glassEffect`-backed container for the buttons. See `swift/Sources/Features/Auth/LoginRootView.swift` (`PairingWelcomeView`, `EdgeFade`, `PairingActionDock`).

- Scroll content at the back, `.ignoresSafeArea(.container, edges: .vertical)` so content can scroll under both edges.
- A `GeometryReader` exposes `proxy.safeAreaInsets.top`; a `Color.clear.frame(height: topInset + 8)` spacer at the top of the scroll pushes the hero below the status bar at rest.
- Top and bottom `EdgeFade` views layered above the scroll: each is a `LinearGradient` from `Color.idpGroupedBackground` (opaque at the edge) to clear (away from the edge), `.allowsHitTesting(false)`, ignoring safe area. The top fade height is `topInset` (status bar only) so it doesn't creep into the hero.
- `PairingActionDock` is two buttons using the project-wide `PrimaryActionStyle` / `SecondaryActionStyle` (shadcn near-black primary + outlined secondary), wrapped in `.padding(16).glassEffect(.regular, in: RoundedRectangle(cornerRadius: 20, style: .continuous))`, then `.padding(.horizontal, 16).padding(.bottom, 12)` for outer spacing. Native floating glass pill without tint-colored button chrome.

### What we tried that didn't match what we wanted

Keep these in mind before reaching for them again:

- `scrollEdgeEffectStyle(.soft, for: .all)` on a `ScrollView`. Too subtle to read as blur; mostly invisible at rest. It is a style hint for the scroll edge effect, not a blur renderer.
- `safeAreaBar(edge: .bottom)` (the iOS 26 replacement for `safeAreaInset` that auto-adds progressive blur). Apple's default blur intensity is very light — "zero control over radius/tint/fade length" — and it doesn't look like the heavy Notes/Safari chrome effect people expect.
- `safeAreaInset(edge: .bottom) { dock.glassEffect(...) }`. Works visually but the glass only covers the inset's intrinsic size, so there's a gap in the home-indicator strip unless you add a hack `.background { Rectangle().glassEffect().ignoresSafeArea(.bottom) }`.
- `.toolbar { ToolbarItem(placement: .bottomBar) { dock } }`. The toolbar placement flattens a custom VStack of full-width stacked buttons into a single icon-only toolbar item. Unusable for two stacked full-width action buttons.
- `.backgroundExtensionEffect()`. Mirrors (reflects) the content into the safe area. Content literally appears upside-down at the edge — wrong tool for this.
- Gradient-masked `UIVisualEffectView` (`.regularMaterial` etc.) stacked layers. Reads as "fade to white" in light mode because `systemThickMaterial` is basically opaque; the actual blur is hidden under the material tint.
- Duplicating the content inside `.overlay` with `.blur(radius:)` + gradient mask. Produces real blur but duplicating a `ScrollView` gives two independent scroll states, and blurring content that extends into the status bar area leaks colored halos (e.g., the hero glyph became a purple smear at the top).
- `.toolbar(.hidden, for: .navigationBar)`. Kills the top chrome host. Any automatic top scroll-edge effect relies on there being a nav/toolbar/safe-area-bar host at that edge — if you hide it, you lose the top blur even when the rest of the pipeline is correct.

### If you actually need a real progressive Gaussian blur

`swift/Sources/Core/Design/GlassChrome.swift` keeps a `VariableBlurView` helper (adapted from `nikstar/VariableBlur`, MIT). It wraps `UIVisualEffectView` and installs the private `CAFilter` `variableBlur` filter with a linear-gradient mask image, producing a real variable-radius Gaussian blur. Strings (`"CAFilter"`, `"filterWithType:"`) are obfuscated via `.reversed()` so trivial static scanners don't flag the symbol — same pattern the upstream packages use.

Tuning notes from the round of iteration:

- Ramp speed is controlled by **layer height**, not `maxBlurRadius`. To make the ramp slower, make the `VariableBlurView` taller (e.g., 380pt). Cranking `maxBlurRadius` just makes the final-pixel blur heavier, not more gradual.
- For the top edge, height should be approximately `safeAreaInsets.top + ~20–30pt`. Bigger than that and the blur bleeds into content (the hero glyph shows up as a colored halo above itself).
- Place the bottom `VariableBlurView` between the scroll and the dock in a `ZStack(alignment: .bottom)`. The scroll needs `.ignoresSafeArea(.container, edges: .vertical)` so content passes behind both the blur layer and the chrome.

### Project conventions for this pattern

- Use `Color.idpGroupedBackground` as the fade target, not `.white` — it adapts to dark mode via the design tokens in `swift/Sources/Core/Design/IdPTokens.swift`.
- Primary/secondary actions use `PrimaryActionStyle` (near-black) / `SecondaryActionStyle` (outlined) from `swift/Sources/Core/Design/ButtonStyles.swift`. Don't use `.buttonStyle(.glassProminent).tint(IdP.tint)` — the resulting purple pill doesn't match the rest of the app's shadcn-style chrome.
- Shadcn card scale: `IdP.cardRadius` (= 12), `IdP.controlRadius` (= 8). Icon/number chips in steps are 24pt rounded-rects at cornerRadius 6. Hero glyph is 40pt at `IdP.controlRadius`. Avoid oversized radii (22+) and chunky circles — `AppSectionCard` + `ShadcnBadge` + the `MonogramAvatar`-style glyph are the canonical building blocks (see `HomeCards.swift`, `AppComponents.swift`).
- `AppScrollScreen` (in `swift/Sources/App/AppTheme.swift`) is the standard scroll container. It does not own safe-area handling; apply `.ignoresSafeArea(.container, edges: .vertical)` at the call site if you need content to extend behind edges. Don't bake it into `AppScrollScreen` — other screens rely on it respecting the safe area.

## tsswift remote-builder workflow for UI screenshots

`tsswift screenshots` and `tsswift review` are not supported over a remote builder, so the automated review pipelines won't work. For UI verification during a task:

- `pnpm exec tsswift run --path swift/IDPGlobal.xcodeproj --platform ios` (or `ipad`) builds on the remote, installs, and launches.
- To grab a screenshot: `ssh <builder> "xcrun simctl io <udid> screenshot /tmp/x.png"` then `scp` it back. Booted iPhone/iPad UDIDs are listed via `xcrun simctl list devices booted` on the builder.
- To drive the app into a specific screen without a real camera or tap automation, add a launch argument (see `--show-pair-scanner` in `AppViewModel.bootstrap`): the harness has no tap primitive, so launch-arg state toggles are the cheapest way to put the app into a specific UI state for screenshots.

`xcrun simctl ui` does not have a tap/touch primitive. `idb` is not installed on the remote. The remote also does not allow AppleScript keystroke sending. Don't waste time trying those paths.
-											give the welcome screen glass chrome and shadcn polish
										
										
											2026-04-20 20:45:47 +00:00
+								# Engineering Knowledge
 								Project-specific lessons learned while building the idp.global Swift app. Intentionally small and opinionated — append only when a finding will save time on a future task.
 								## iOS 26 Liquid Glass and progressive blur at screen edges
 								Context: the pairing welcome screen needed a floating bottom action bar with "native Apple chrome" look — a rounded Liquid Glass pill containing the Scan/NFC buttons, with content gracefully fading as it approaches the top and bottom edges of the screen.
 								### What we shipped
 								Simple and reliable: linear-gradient edge fades + a `glassEffect`-backed container for the buttons. See `swift/Sources/Features/Auth/LoginRootView.swift` (`PairingWelcomeView`, `EdgeFade`, `PairingActionDock`).
 								- Scroll content at the back, `.ignoresSafeArea(.container, edges: .vertical)` so content can scroll under both edges.
 								- A `GeometryReader` exposes `proxy.safeAreaInsets.top`; a `Color.clear.frame(height: topInset + 8)` spacer at the top of the scroll pushes the hero below the status bar at rest.
 								- Top and bottom `EdgeFade` views layered above the scroll: each is a `LinearGradient` from `Color.idpGroupedBackground` (opaque at the edge) to clear (away from the edge), `.allowsHitTesting(false)`, ignoring safe area. The top fade height is `topInset` (status bar only) so it doesn't creep into the hero.
 								- `PairingActionDock` is two buttons using the project-wide `PrimaryActionStyle` / `SecondaryActionStyle` (shadcn near-black primary + outlined secondary), wrapped in `.padding(16).glassEffect(.regular, in: RoundedRectangle(cornerRadius: 20, style: .continuous))`, then `.padding(.horizontal, 16).padding(.bottom, 12)` for outer spacing. Native floating glass pill without tint-colored button chrome.
 								### What we tried that didn't match what we wanted
 								Keep these in mind before reaching for them again:
 								- `scrollEdgeEffectStyle(.soft, for: .all)` on a `ScrollView`. Too subtle to read as blur; mostly invisible at rest. It is a style hint for the scroll edge effect, not a blur renderer.
 								- `safeAreaBar(edge: .bottom)` (the iOS 26 replacement for `safeAreaInset` that auto-adds progressive blur). Apple's default blur intensity is very light — "zero control over radius/tint/fade length" — and it doesn't look like the heavy Notes/Safari chrome effect people expect.
 								- `safeAreaInset(edge: .bottom) { dock.glassEffect(...) }`. Works visually but the glass only covers the inset's intrinsic size, so there's a gap in the home-indicator strip unless you add a hack `.background { Rectangle().glassEffect().ignoresSafeArea(.bottom) }`.
 								- `.toolbar { ToolbarItem(placement: .bottomBar) { dock } }`. The toolbar placement flattens a custom VStack of full-width stacked buttons into a single icon-only toolbar item. Unusable for two stacked full-width action buttons.
 								- `.backgroundExtensionEffect()`. Mirrors (reflects) the content into the safe area. Content literally appears upside-down at the edge — wrong tool for this.
 								- Gradient-masked `UIVisualEffectView` (`.regularMaterial` etc.) stacked layers. Reads as "fade to white" in light mode because `systemThickMaterial` is basically opaque; the actual blur is hidden under the material tint.
 								- Duplicating the content inside `.overlay` with `.blur(radius:)` + gradient mask. Produces real blur but duplicating a `ScrollView` gives two independent scroll states, and blurring content that extends into the status bar area leaks colored halos (e.g., the hero glyph became a purple smear at the top).
 								- `.toolbar(.hidden, for: .navigationBar)`. Kills the top chrome host. Any automatic top scroll-edge effect relies on there being a nav/toolbar/safe-area-bar host at that edge — if you hide it, you lose the top blur even when the rest of the pipeline is correct.
 								### If you actually need a real progressive Gaussian blur
 								`swift/Sources/Core/Design/GlassChrome.swift` keeps a `VariableBlurView` helper (adapted from `nikstar/VariableBlur`, MIT). It wraps `UIVisualEffectView` and installs the private `CAFilter` `variableBlur` filter with a linear-gradient mask image, producing a real variable-radius Gaussian blur. Strings (`"CAFilter"`, `"filterWithType:"`) are obfuscated via `.reversed()` so trivial static scanners don't flag the symbol — same pattern the upstream packages use.
 								Tuning notes from the round of iteration:
 								- Ramp speed is controlled by **layer height**, not `maxBlurRadius`. To make the ramp slower, make the `VariableBlurView` taller (e.g., 380pt). Cranking `maxBlurRadius` just makes the final-pixel blur heavier, not more gradual.
 								- For the top edge, height should be approximately `safeAreaInsets.top + ~20–30pt`. Bigger than that and the blur bleeds into content (the hero glyph shows up as a colored halo above itself).
 								- Place the bottom `VariableBlurView` between the scroll and the dock in a `ZStack(alignment: .bottom)`. The scroll needs `.ignoresSafeArea(.container, edges: .vertical)` so content passes behind both the blur layer and the chrome.
 								### Project conventions for this pattern
 								- Use `Color.idpGroupedBackground` as the fade target, not `.white` — it adapts to dark mode via the design tokens in `swift/Sources/Core/Design/IdPTokens.swift`.
 								- Primary/secondary actions use `PrimaryActionStyle` (near-black) / `SecondaryActionStyle` (outlined) from `swift/Sources/Core/Design/ButtonStyles.swift`. Don't use `.buttonStyle(.glassProminent).tint(IdP.tint)` — the resulting purple pill doesn't match the rest of the app's shadcn-style chrome.
 								- Shadcn card scale: `IdP.cardRadius` (= 12), `IdP.controlRadius` (= 8). Icon/number chips in steps are 24pt rounded-rects at cornerRadius 6. Hero glyph is 40pt at `IdP.controlRadius`. Avoid oversized radii (22+) and chunky circles — `AppSectionCard` + `ShadcnBadge` + the `MonogramAvatar`-style glyph are the canonical building blocks (see `HomeCards.swift`, `AppComponents.swift`).
 								- `AppScrollScreen` (in `swift/Sources/App/AppTheme.swift`) is the standard scroll container. It does not own safe-area handling; apply `.ignoresSafeArea(.container, edges: .vertical)` at the call site if you need content to extend behind edges. Don't bake it into `AppScrollScreen` — other screens rely on it respecting the safe area.
 								## tsswift remote-builder workflow for UI screenshots
 								`tsswift screenshots` and `tsswift review` are not supported over a remote builder, so the automated review pipelines won't work. For UI verification during a task:
 								- `pnpm exec tsswift run --path swift/IDPGlobal.xcodeproj --platform ios` (or `ipad`) builds on the remote, installs, and launches.
 								- To grab a screenshot: `ssh <builder> "xcrun simctl io <udid> screenshot /tmp/x.png"` then `scp` it back. Booted iPhone/iPad UDIDs are listed via `xcrun simctl list devices booted` on the builder.
 								- To drive the app into a specific screen without a real camera or tap automation, add a launch argument (see `--show-pair-scanner` in `AppViewModel.bootstrap`): the harness has no tap primitive, so launch-arg state toggles are the cheapest way to put the app into a specific UI state for screenshots.
 								`xcrun simctl ui` does not have a tap/touch primitive. `idb` is not installed on the remote. The remote also does not allow AppleScript keystroke sending. Don't waste time trying those paths.