vybekiit 0.7.26 → 0.7.27

package/dist/global-skills/expo-migrate-module/references/migration-map.md

@@ -19,7 +19,7 @@ public final class CameraModule: Module {
 public final class CameraModule: Module {}
 ```
 
-Always carry a custom 1.0 name into `@ExpoModule("...")`. A stale `Name(...)` can override or conflict with the 2.0 name depending on the core revision. In mixed mode, remove `Name(...)` only after verifying the installed `_jsName` contract.
+Always carry a custom 1.0 name into `@ExpoModule("...")`. A stale `Name(...)` can override or conflict with the 2.0 name depending on the core revision. In mixed mode, remove `Name(...)` only after verifying that the module still resolves under its expected JS name.
 
 ## Functions
 
@@ -108,9 +108,56 @@ func download(url: URL) -> Task<DownloadResult, any Error> {
 
 This shape requires the `JavaScriptEncodable` conformance for `Task` in the checked-out core (encode-only; a JS promise does not decode back into a `Task`). Verify it exists before using this shape; prefer shape 1 or 2 when it is absent.
 
-Do not assume scheduling is unchanged. 2.0 async members are `@JavaScriptActor`-isolated and begin on the JS thread until their first real suspension. A 1.0 `.runOnQueue(...)` function or a workload that relied on automatic background execution must not be migrated as-is. Never move blocking I/O directly onto the JS actor.
+#### Threading: the architectural difference
 
-For a queue-pinned 1.0 function, prefer restructuring the work onto the Swift Concurrency model (structured concurrency, an actor, or a detached task for blocking work). When that is not feasible because the queue itself is the contract, for example a library that must be called from one serial queue, convert to an `async` method that dispatches to that queue inside a checked continuation:
+This is the highest-risk part of an async migration, because the code compiles and the JS signature is unchanged while the work moves onto a different thread.
+
+The two versions schedule async work from opposite starting points:
+
+| | 1.0 `AsyncFunction` | 2.0 `async` `@JS` |
+| --- | --- | --- |
+| Where the body starts | off the JS thread, from the first statement | on the JS thread |
+| When it leaves the JS thread | never runs there | at the first real suspension point |
+| A body with no `await` | still runs off the JS thread | runs entirely on the JS thread |
+
+A 2.0 async member is `@JavaScriptActor`-isolated and stays on the JS thread until it actually suspends. So the dangerous case is a function marked `async` whose body never awaits anything, or awaits only after doing substantial work. In 1.0 that body was off the JS thread from the start; migrated verbatim to 2.0, it now blocks the JS thread for its full duration. Nothing in the JS contract reveals this: the function still returns a promise.
+
+Audit every `AsyncFunction` you migrate for what the body does before its first `await`:
+
+- No `await` at all, or synchronous work ahead of the first `await`: the work is on the JS thread. Treat it as a regression unless the body is trivial.
+- Blocking I/O, file or database access, image or crypto work, or an unbounded loop: never leave this on the JS actor.
+- `.runOnQueue(...)` in 1.0: the queue was the contract. See the continuation pattern below.
+
+To restore the 1.0 behavior, use the `@JS` macro's `.concurrent` option (macros plugin `0.10.0`):
+
+```swift
+// Body runs off the JS thread, like a 1.0 AsyncFunction.
+@JS(.concurrent)
+func process(input: String) async throws -> String {
+  return try self.processor.process(input)
+}
+
+// The option is variadic, so it combines with an explicit JS name.
+@JS("doWork", .concurrent)
+func performWork() async throws {}
+```
+
+Only the body moves. Arguments are still decoded on the JS thread and the result is still encoded back on it, so `.concurrent` changes execution, not the JS contract. This makes it the preferred fix for a migrated function that relied on 1.0 background execution: the intent is explicit and the body stays as written.
+
+Two constraints:
+
+- `.concurrent` is valid only on an `async` function. On anything else it is diagnosed on the `@JS` attribute.
+- You must still write `async` yourself. The macro cannot add it, but the diagnostic for a synchronous function carries a fix-it that inserts it.
+
+**Check availability first.** The plugin side shipped in `0.10.0`, but this also needs a `JSOptions` type and a second `@JS` overload in core, because the options-only spelling cannot reuse the unlabeled JS-name slot. Core has lagged the plugin on every 2.0 feature so far, and where it still declares `@JS(_ jsName: String? = nil)` alone, `@JS(.concurrent)` does not compile. Read the checked-out declaration:
+
+```bash
+grep -rn 'public macro JS' <expo-modules-core>
+```
+
+If it takes only a name, use the explicit patterns below instead.
+
+For a queue-pinned function, or when `.concurrent` is unavailable, prefer restructuring the work onto the Swift Concurrency model (structured concurrency, an actor, or a detached task for blocking work). When that is not feasible because the queue itself is the contract, for example a library that must be called from one serial queue, convert to an `async` method that dispatches to that queue inside a checked continuation:
 
 ```swift
 // 1.0
@@ -217,10 +264,6 @@ final class Download: SharedObject {
 
   @JS
   var progress: Double { currentProgress }
-
-  // Installs on the JS class (constructor) object, not the prototype.
-  @JS
-  static let maxConcurrent = 4
 }
 
 @ExpoModule(classes: [Download.self])
@@ -229,10 +272,62 @@ final class DownloadModule: Module {}
 
 Drop the leading owner argument used by instance DSL closures; use `self` in the real instance method. Preserve constructor arity and JS member names.
 
-Migrate only when the checked-out core supplies the shared-object decoration and construction hooks. Static properties migrate as Swift `static` or `class` properties and install on the JS class (constructor) object rather than the prototype; verify constructor-side routing for static functions before migrating them, since instance support does not imply static-function support. Never create both a 1.0 `Class(...)` entry and a 2.0 registration for the same class without confirming that core intentionally merges them.
+Migrate only when the checked-out core supplies the shared-object decoration and construction hooks. Never create both a 1.0 `Class(...)` entry and a 2.0 registration for the same class without confirming that core intentionally merges them.
 
 Static members belong to shared objects, not modules: a module is exported to JS as an instance, so Swift `static` members on a `Module` class are not useful there. Keep module-level values as instance `@JS` members.
 
+#### Static members
+
+A static member installs on the JS class object itself, so JS reaches it as `Download.supportedSchemes()`, not through an instance. The 1.0 DSL has dedicated components for this: `StaticFunction` and `StaticAsyncFunction`. Unlike `Function`, they do not receive the instance as their first argument. There is no static *property* component in 1.0, so a static value was exposed as a `StaticFunction` returning it.
+
+```swift
+// 1.0
+Class(Download.self) {
+  Constructor { (url: URL) in Download(url: url) }
+
+  // Instance function: receives the owner as its first argument.
+  Function("pause") { (download: Download) in
+    download.pause()
+  }
+
+  // Static: no owner argument, callable as Download.supportedSchemes()
+  StaticFunction("supportedSchemes") { () -> [String] in
+    Download.supportedSchemes
+  }
+}
+```
+
+```swift
+// 2.0
+@SharedObject
+final class Download: SharedObject {
+  @JS
+  init(url: URL) { self.url = url }
+
+  @JS
+  func pause() {}
+
+  @JS
+  static func supportedSchemes() -> [String] {
+    return Self.schemes
+  }
+}
+```
+
+`StaticFunction` and `StaticAsyncFunction` both collapse into a `static` (or `class`) Swift declaration, with `async` carrying the distinction, exactly as `Function`/`AsyncFunction` do for instance members. Because 1.0 had no static property component, a `StaticFunction` that only returns a stored value can become a `@JS static var` in 2.0. That changes the JS contract from a call to a property access, so do it only when the user asks; a syntax migration keeps it a function.
+
+What decides whether any of this works is the binding path: instance members bind onto the class prototype, while `static`/`class` members bind onto the constructor object through a separate, `constructor:`-labeled decoration hook. The two are independent capabilities.
+
+**Support status.** The macros plugin has emitted the `constructor:` binding since `0.7.0`, but core shipped the `prototype:` overload well ahead of it. Where only `prototype:` is declared, a `@JS static` member expands and then fails to link. Verify before migrating any static member:
+
+```bash
+grep -rn '_decorateSharedObject' <expo-modules-core>
+```
+
+If only the `prototype:` overload is declared, keep every `StaticFunction`/`StaticAsyncFunction` entry in the 1.0 `Class(...)` block. Mixed mode is the expected outcome here: migrate the constructor and instance members, leave the static entries on the DSL, and say in the handoff that static members stayed behind because the installed core does not bind them yet.
+
+Static functions and static properties travel this same path, so neither is available ahead of the other. When the hook is present, confirm it by calling the member on the JS class rather than on an instance; an instance-side test passes whether or not static binding works.
+
 ## Records
 
 Attach `@Record`, remove field wrappers, and encode requiredness in the declaration:
@@ -256,11 +351,67 @@ Preserve the 1.0 contract exactly. For example, migrate `@Field var source: URL?
 
 Every stored property is part of the 2.0 record surface. If the old type contains stored bookkeeping that was not a 1.0 field, move it out of the record or leave the type on 1.0; there is no field opt-out. Verify that each field supports the required `JavaScriptDecodable`/`JavaScriptEncodable` direction.
 
-Do not adopt `@Union` until that macro and its coding witnesses exist in the target.
+## Unions
+
+`@Union` (macros plugin `0.10.0`) is the typed, N-case alternative to 1.0's `Either` types. It applies to a non-generic `enum` whose every case carries exactly one associated value:
+
+```swift
+// 1.0: JS `string | SourceOptions`, unwrapped by probing each side.
+@JS
+func load(_ source: Either<String, SourceOptions>) throws {
+  if let text: String = source.get() {
+    load(url: URL(string: text))
+  } else if let options: SourceOptions = source.get() {
+    load(url: options.url, headers: options.headers)
+  }
+}
+```
+
+```swift
+// 2.0: the same JS type, as a named enum.
+@Union
+enum Source {
+  case text(String)
+  case options(SourceOptions)   // a @Record
+}
+
+@JS
+func load(_ source: Source) throws {
+  switch source {               // exhaustive; each payload keeps its static type
+  case .text(let text):
+    load(url: URL(string: text))
+  case .options(let options):
+    load(url: options.url, headers: options.headers)
+  }
+}
+```
+
+The JS-visible type is unchanged: case order defines the accepted alternatives, so `Either<String, SourceOptions>` maps to cases in that same order. Decoding tries each case's payload in declaration order and the first match wins, which matters for overlapping types (`Int`/`Double`, `URL`/`String`): keep the 1.0 `Either` order, since reordering silently changes which case a given JS value lands in.
+
+Besides `switch`, a value unwraps by payload type without naming the case, which is the closest analogue to 1.0's `get()`:
+
+```swift
+let text = try source.as(String.self)              // throws on a mismatch
+let options = try? source.as(SourceOptions.self)   // SourceOptions?
+```
+
+A type the union does not carry is a compile error, not a runtime `nil`. A mismatch on a held value throws, where 1.0's `get()` returned `nil`, so a migrated probe chain must become a `switch` or a `try?`.
+
+Constraints, each a compile error: a generic enum, no cases, a case with no payload or more than one, a default value on the payload, and two cases with the identical payload spelling.
+
+**Check availability first.** The plugin side shipped in `0.10.0`, but this also needs the `Union` macro declaration and the `UnionCaseMismatch` exception in core:
+
+```bash
+grep -rn 'public macro Union\|UnionCaseMismatch' <expo-modules-core>
+```
+
+Keep `Either` types on the 1.0 DSL until both exist in the target. Treat adopting `@Union` as an API-shape change to raise with the user rather than a mechanical step: it renames nothing in JS, but it does restructure Swift call sites.
 
 ## Views and lifecycle
 
-Keep UIKit `View`, `Prop`, view `Events`, and `OnViewDidUpdateProps` DSL entries until the target includes the complete `@ViewProps`/`@ExpoView` core contract. Macro declarations or expansion tests alone do not prove the runtime update path exists.
+Views are not covered by 2.0 yet. Keep UIKit `View`, `Prop`, view `Events`, and `OnViewDidUpdateProps` DSL entries on 1.0. Macro declarations or expansion tests alone do not prove the runtime update path exists.
+
+The planned shape is a class marked `@ExpoView` whose props and event callbacks are declared once in a typed `@ViewProps` struct, instead of split between the native view and a hand-written JS prop type. Until that lands complete, a module with views migrates its non-view members and keeps the view on the DSL. That is a normal mixed-mode result, not a failed migration.
 
 Module lifecycle is core-owned rather than macro-generated. The DSL components map to hook methods with no-op defaults:
 
@@ -289,7 +440,7 @@ Before deleting `definition()`, verify that it contains no:
 - views or view events
 - lifecycle or app-context listeners
 - queue-pinned functions
-- shared-object static functions or other unsupported definitions
+- `StaticFunction`/`StaticAsyncFunction` entries, unless core declares the `constructor:` decoration hook
 
 ## Contract checklist
 

package/dist/global-skills/expo-native-ui/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: expo-native-ui
-description: Framework (OSS). Build beautiful, native-feeling Expo screens. Covers Apple HIG styling, semantic colors, native controls, SF Symbols, media, animations, visual effects, gradients, storage, and responsive layout. For routing and navigation, use the expo-router skill.
+description: Framework (OSS). Build beautiful, native-feeling Expo screens. Covers Apple HIG styling, semantic colors, native controls, SF Symbols, media, visual effects, gradients, storage, and responsive layout. For routing and navigation, use the expo-router skill; for motion and animation, use the expo-animation skill.
 version: 1.1.1
 license: MIT
 ---
 
 # Expo Native UI Guidelines
 
-For routes, links, stacks, tabs, modals, sheets, and headers, use the `expo-router` skill.
+For routes, links, stacks, tabs, modals, sheets, and headers, use the `expo-router` skill. For any motion — entering/exiting, gestures, springs, keyboard-driven UI — use the `expo-animation` skill.
 
-> **Before picking any UI component, check `expo-ui` first.** `@expo/ui` provides native equivalents — BottomSheet, Button, Picker, Slider, Menu, Section, Switch, SegmentedControl, and more — rendered as real SwiftUI on iOS and Jetpack Compose on Android, available in Expo Go on SDK 56+ with no custom build. Load the **`expo-ui`** skill to find the right component before falling back to React Native built-ins or community libraries. This skill (`expo-native-ui`) covers the surrounding structure: Expo Router navigation, layout, styling, and animations.
+> **Before picking any UI component, check `expo-ui` first.** `@expo/ui` provides native equivalents — BottomSheet, Button, Picker, Slider, Menu, Section, Switch, SegmentedControl, and more — rendered as real SwiftUI on iOS and Jetpack Compose on Android, available in Expo Go on SDK 56+ with no custom build. Load the **`expo-ui`** skill to find the right component before falling back to React Native built-ins or community libraries. This skill (`expo-native-ui`) covers the surrounding structure: Expo Router navigation, layout, styling, and visual effects.
 
 ## References
 
@@ -17,10 +17,9 @@ Consult these resources as needed:
 
 ```
 references/
-  animations.md          Reanimated: entering, exiting, layout, scroll-driven, gestures
   controls.md            Native iOS: Switch, Slider, SegmentedControl, DateTimePicker, Picker
   gradients.md           CSS gradients via experimental_backgroundImage (New Arch only)
-  icons.md               SF Symbols via expo-image (sf: source), names, animations, weights
+  icons.md               SF Symbols via expo-symbols SymbolView: names, weights, animations; Material icons on Android
   media.md               Camera, audio, video, and file saving
   storage.md             SQLite, AsyncStorage, SecureStore
   visual-effects.md      Blur (expo-blur) and liquid glass (expo-glass-effect)
@@ -48,12 +47,11 @@ You need `npx expo run:ios/android` or `eas build` ONLY when using:
 
 ### When Expo Go Works
 
-Expo Go supports a huge range of features out of the box:
+Expo Go supports a wide range of features out of the box:
 
-- All `expo-*` packages (camera, location, notifications, etc.)
-- Expo Router navigation
+- Most `expo-*` packages (camera, location, sensors, sqlite, etc.) — but not all: remote push notifications don't work in Expo Go on Android since SDK 53, and some packages need native capabilities Expo Go doesn't bundle (e.g. WebGPU — see `references/webgpu-three.md`)
+- Expo Router navigation and deep links
 - Most UI libraries (reanimated, gesture handler, etc.)
-- Push notifications, deep links, and more
 
 **If you're unsure, try Expo Go first.** Creating custom builds adds complexity, slower iteration, and requires Xcode/Android Studio setup.
 
@@ -72,7 +70,7 @@ Expo Go supports a huge range of features out of the box:
 - Never use legacy expo-permissions
 - `expo-audio` not `expo-av`
 - `expo-video` not `expo-av`
-- `expo-image` with `source="sf:name"` for SF Symbols, not `expo-symbols` or `@expo/vector-icons`
+- `expo-symbols` (`SymbolView`) for SF Symbols on iOS, not `@expo/vector-icons` — see `references/icons.md`. SF Symbols are Apple-only: on Android every icon needs a Material source (`md` prop on NativeTabs triggers; in-screen options under "Android: Material Icons" in icons.md), never SF-only iconography
 - `react-native-safe-area-context` not react-native SafeAreaView
 - `process.env.EXPO_OS` not `Platform.OS`
 - `React.use` not `React.useContext`
@@ -83,7 +81,7 @@ Expo Go supports a huge range of features out of the box:
 
 ## Responsiveness
 
-- Always wrap root component in a scroll view for responsiveness
+- Wrap screens with scrollable content in a ScrollView. Screens whose root is a FlatList/FlashList must not add an outer ScrollView (the list is the scroll container), and full-bleed screens (camera, map, canvas) need neither
 - Use `<ScrollView contentInsetAdjustmentBehavior="automatic" />` instead of `<SafeAreaView>` for smarter safe area insets
 - `contentInsetAdjustmentBehavior="automatic"` should be applied to FlatList and SectionList as well
 - Use flexbox instead of Dimensions API
@@ -93,15 +91,21 @@ Expo Go supports a huge range of features out of the box:
 
 - Use expo-haptics conditionally on iOS to make more delightful experiences
 - Use views with built-in haptics like `<Switch />` from React Native and `@react-native-community/datetimepicker`
-- When a route belongs to a Stack, its first child should almost always be a ScrollView with `contentInsetAdjustmentBehavior="automatic"` set
-- When adding a `ScrollView` to the page it should almost always be the first component inside the route component
+- When a Stack route has scrollable content, make the ScrollView (or FlatList) the first component inside the route, with `contentInsetAdjustmentBehavior="automatic"` set
 - Use the `<Text selectable />` prop on text containing data that could be copied
 - Consider formatting large numbers like 1.4M or 38k
 - Never use intrinsic elements like 'img' or 'div' unless in a webview or Expo DOM component
+- Every screen that loads data has four states (loading, error, empty, content) - never show the empty state while the first load is still resolving; the rules live in the `expo-data-fetching` skill
+- On scrollable forms and search results, use `keyboardShouldPersistTaps="handled"` so controls receive the first tap and unhandled taps can dismiss the keyboard. Use `"always"` only when unhandled taps should also keep it open
+- A form's primary action must never sit under the keyboard. For UI that tracks the keyboard's real frame, load the `expo-animation` skill's keyboard recipe (`react-native-keyboard-controller`) - never `Keyboard.addListener` plus a timing animation
+- Every enabled control must perform its advertised action: search filters results, Save commits edits, and settings affect behavior. Empty handlers and success alerts are not implementations; local state is enough when the user requested a prototype
+- For async saves, preserve drafts and handle pending/failure states per `expo-data-fetching`; do not dismiss a form before its save succeeds
+
+Before calling a screen complete, walk through its primary task, including one failure and recovery when it loads or saves data. Check keyboard access and back/dismiss behavior. Try long titles, missing images, no search results, and large system text; required actions must remain reachable. Report what you exercised and what you could not run.
 
 # Styling
 
-Follow Apple Human Interface Guidelines.
+Follow each platform's own design language: Apple Human Interface Guidelines on iOS, Material Design 3 on Android. Never dress one platform in the other's uniform - no FAB or ripple in iOS layouts; no hand-built iOS chrome (back-chevrons, large-title text, iOS-styled switches) on Android.
 
 ## General Styling Rules
 
@@ -110,7 +114,7 @@ Follow Apple Human Interface Guidelines.
 - Always account for safe area, either with stack headers, tabs, or ScrollView/FlatList `contentInsetAdjustmentBehavior="automatic"`
 - Ensure both top and bottom safe area insets are accounted for
 - Inline styles not StyleSheet.create unless reusing styles is faster
-- Add entering and exiting animations for state changes
+- For any motion or animation work, load the `expo-animation` skill — it owns the animate-or-not decision, timing values, and interruption rules
 - Use `{ borderCurve: 'continuous' }` for rounded corners unless creating a capsule shape
 - ALWAYS use a navigation stack title instead of a custom text element on the page
 - When padding a ScrollView, use `contentContainerStyle` padding and gap instead of padding on the ScrollView itself (reduces clipping)
@@ -148,6 +152,11 @@ export const colors = {
     android: Color.android.dynamic.surface,
     default: "#ffffff",
   })!,
+  secondarySystemBackground: Platform.select({
+    ios: Color.ios.secondarySystemBackground,
+    android: Color.android.dynamic.surfaceVariant,
+    default: "#f2f2f7",
+  })!,
   systemBlue: Platform.select({
     ios: Color.ios.systemBlue,
     android: Color.android.dynamic.primary,
@@ -165,7 +174,7 @@ import { colors } from "@/theme/colors";
 ```
 
 - iOS re-resolves these colors automatically when the system theme changes. On Android, call `useColorScheme()` inside any component that renders them so it re-renders when the theme flips (required when React Compiler memoizes the component).
-- Don't pass `Color` / `PlatformColor` values into Reanimated styles — use static colors there (see `references/animations.md`).
+- Don't pass `Color` / `PlatformColor` values into Reanimated styles — they are opaque native color objects, not strings; use static colors there.
 - `Platform.select({...})!` returns `string | OpaqueColorValue`. Most React Native style props accept `ColorValue` (`string | OpaqueColorValue`) so this works fine. But some third-party props only accept `string` (e.g. `tintColor` on `expo-image`). Cast when needed: `colors.label as string`.
 
 ## Text Styling

package/dist/global-skills/expo-native-ui/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Expo Native UI"
-  short_description: "Build beautiful, native-feeling Expo screens: HIG styling, semantic colors, controls, SF Symbols, media, animation, and visual effects"
-  default_prompt: "Use $expo-native-ui to style native-feeling Expo screens, choose semantic colors and native controls, add media, animations, and visual effects, and decide when Expo Go is enough before creating native builds."
+  short_description: "Build beautiful, native-feeling Expo screens: HIG styling, semantic colors, controls, SF Symbols, media, and visual effects"
+  default_prompt: "Use $expo-native-ui to style native-feeling Expo screens, choose semantic colors and native controls, add media and visual effects, and decide when Expo Go is enough before creating native builds."

package/dist/global-skills/expo-native-ui/references/controls.md

@@ -17,17 +17,7 @@ const [enabled, setEnabled] = useState(false);
 <Switch value={enabled} onValueChange={setEnabled} />;
 ```
 
-### Customization
-
-```tsx
-<Switch
-  value={enabled}
-  onValueChange={setEnabled}
-  trackColor={{ false: "#767577", true: "#81b0ff" }}
-  thumbColor={enabled ? "#f5dd4b" : "#f4f3f4"}
-  ios_backgroundColor="#3e3e3e"
-/>
-```
+Don't recolor the Switch — native styling adapts to dark mode automatically.
 
 ## Segmented Control
 
@@ -83,21 +73,6 @@ const [value, setValue] = useState(0.5);
 />;
 ```
 
-### Customization
-
-```tsx
-<Slider
-  value={value}
-  onValueChange={setValue}
-  minimumValue={0}
-  maximumValue={100}
-  step={1}
-  minimumTrackTintColor="#007AFF"
-  maximumTrackTintColor="#E5E5EA"
-  thumbTintColor="#007AFF"
-/>
-```
-
 ### Discrete Steps
 
 ```tsx
@@ -174,39 +149,22 @@ const [date, setDate] = useState(new Date());
 />
 ```
 
-## Stepper
-
-Increment/decrement numeric values.
-
-```tsx
-import { Stepper } from "react-native";
-import { useState } from "react";
-
-const [count, setCount] = useState(0);
-
-<Stepper
-  value={count}
-  onValueChange={setCount}
-  minimumValue={0}
-  maximumValue={10}
-/>;
-```
-
 ## TextInput
 
 Native text input with various keyboard types.
 
 ```tsx
 import { TextInput } from "react-native";
+import { colors } from "@/theme/colors";
 
 <TextInput
   placeholder="Enter text..."
-  placeholderTextColor="#999"
+  placeholderTextColor={colors.secondaryLabel as string}
   style={{
     padding: 12,
     fontSize: 16,
     borderRadius: 8,
-    backgroundColor: "#f0f0f0",
+    backgroundColor: colors.secondarySystemBackground,
   }}
 />
 ```
@@ -265,6 +223,7 @@ const [selected, setSelected] = useState("js");
 ## Best Practices
 
 - **Haptics**: Switch and DateTimePicker have built-in haptics — don't add extra
+- **No native Stepper**: React Native has no `Stepper` component — compose increment/decrement from two Buttons or a numeric TextInput
 - **Accessibility**: Native controls have proper accessibility labels by default
 - **Dark Mode**: Avoid custom colors — native styling adapts automatically
 - **Spacing**: Use consistent padding around controls (12-16pt)

package/dist/global-skills/expo-native-ui/references/icons.md

@@ -1,6 +1,6 @@
 # Icons (SF Symbols)
 
-Use SF Symbols for native feel. Never use FontAwesome or Ionicons.
+Use SF Symbols on iOS for native feel. SF Symbols are an Apple asset and never render on Android - every icon needs a Material counterpart (see "Android: Material Icons" below). Never use FontAwesome or Ionicons on either platform, and never emoji as icons.
 
 ## Basic Usage
 
@@ -198,6 +198,25 @@ Some symbols support multiple colors:
 />
 ```
 
+## Android: Material Icons
+
+On Android an SF Symbol source renders nothing - an app that ships SF-only iconography ships blank icons. Give every icon a Material source:
+
+- **Tab bars**: pass `md` (Material Symbol name) beside `sf` on NativeTabs triggers - `<NativeTabs.Trigger.Icon sf="gear" md="settings" />` (SDK 55+, see the `expo-router` skill).
+- **In screens**: `@expo/vector-icons` Material families, gated by platform:
+
+```tsx
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+
+process.env.EXPO_OS === "ios" ? (
+  <SymbolView name="gear" tintColor={colors.label} style={{ width: 24, height: 24 }} />
+) : (
+  <MaterialIcons name="settings" size={24} color={colors.label} />
+);
+```
+
+One icon family per platform - never a mixed set, never SF names on Android or Material glyphs on iOS.
+
 ## Finding Symbol Names
 
 1. Use the SF Symbols app on macOS (free from Apple)
@@ -206,7 +225,7 @@ Some symbols support multiple colors:
 
 ## Best Practices
 
-- Always use SF Symbols over vector icon libraries
+- On iOS, always use SF Symbols over vector icon libraries; on Android, use Material icons (see above)
 - Match symbol weight to nearby text weight
 - Use `.fill` variants for selected/active states
 - Use the cross-platform `colors` helper (see SKILL.md "Colors") for tint to support dark mode

package/dist/global-skills/expo-native-ui/references/media.md

@@ -6,17 +6,17 @@
 - Ensure to flip the camera with `mirror` to emulate social apps
 - Use liquid glass buttons on cameras
 - Icons: `arrow.triangle.2.circlepath` (flip), `photo` (gallery), `bolt` (flash)
-- Eagerly request camera permission
-- Lazily request media library permission
+- Gate the camera behind an explanation screen with a Grant button (as below) — never fire the permission prompt on mount
+- Lazily request media library permission (at first save/pick)
+
+The example uses the `GlassButton` helper defined in `visual-effects.md` (Glass Buttons section).
 
 ```tsx
 import React, { useRef, useState } from "react";
-import { View, TouchableOpacity, Text, Alert } from "react-native";
+import { View, Pressable, Text } from "react-native";
 import { CameraView, CameraType, useCameraPermissions } from "expo-camera";
-import * as MediaLibrary from "expo-media-library";
 import * as ImagePicker from "expo-image-picker";
 import * as Haptics from "expo-haptics";
-import { SymbolView } from "expo-symbols";
 import { colors } from "@/theme/colors";
 import { GlassView } from "expo-glass-effect";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
@@ -32,9 +32,9 @@ function Camera({ onPicture }: { onPicture: (uri: string) => Promise<void> }) {
       <View style={{ flex: 1, justifyContent: "center", alignItems: "center", backgroundColor: colors.systemBackground }}>
         <Text style={{ color: colors.label, padding: 16 }}>Camera access is required</Text>
         <GlassView isInteractive tintColor={colors.systemBlue} style={{ borderRadius: 12 }}>
-          <TouchableOpacity onPress={requestPermission} style={{ padding: 12, borderRadius: 12 }}>
+          <Pressable onPress={requestPermission} style={{ padding: 12, borderRadius: 12 }}>
             <Text style={{ color: "white" }}>Grant Permission</Text>
-          </TouchableOpacity>
+          </Pressable>
         </GlassView>
       </View>
     );
@@ -64,7 +64,7 @@ function Camera({ onPicture }: { onPicture: (uri: string) => Promise<void> }) {
       <CameraView ref={cameraRef} mirror style={{ flex: 1 }} facing={type} />
       <View style={{ position: "absolute", left: 0, right: 0, bottom: bottom, gap: 16, alignItems: "center" }}>
         <GlassView isInteractive style={{ padding: 8, borderRadius: 99 }}>
-          <TouchableOpacity onPress={takePhoto} style={{ width: 64, height: 64, borderRadius: 99, backgroundColor: "white" }} />
+          <Pressable onPress={takePhoto} style={{ width: 64, height: 64, borderRadius: 99, backgroundColor: "white" }} />
         </GlassView>
         <View style={{ flexDirection: "row", justifyContent: "space-around", paddingHorizontal: 8 }}>
           <GlassButton onPress={selectPhoto} icon="photo" />
@@ -98,31 +98,26 @@ import {
   setAudioModeAsync,
   useAudioRecorderState,
 } from 'expo-audio';
-import { useEffect } from 'react';
 import { Alert, Button } from 'react-native';
 
 function App() {
   const audioRecorder = useAudioRecorder(RecordingPresets.HIGH_QUALITY);
   const recorderState = useAudioRecorderState(audioRecorder);
 
+  // Request the microphone on first record, not on mount — no prompt before user intent
   const record = async () => {
+    const status = await AudioModule.requestRecordingPermissionsAsync();
+    if (!status.granted) {
+      Alert.alert('Permission to access microphone was denied');
+      return;
+    }
+    await setAudioModeAsync({ playsInSilentMode: true, allowsRecording: true });
     await audioRecorder.prepareToRecordAsync();
     audioRecorder.record();
   };
 
   const stop = () => audioRecorder.stop();
 
-  useEffect(() => {
-    (async () => {
-      const status = await AudioModule.requestRecordingPermissionsAsync();
-      if (status.granted) {
-        setAudioModeAsync({ playsInSilentMode: true, allowsRecording: true });
-      } else {
-        Alert.alert('Permission to access microphone was denied');
-      }
-    })();
-  }, []);
-
   return (
     <Button
       title={recorderState.isRecording ? 'Stop' : 'Start'}

package/dist/global-skills/expo-native-ui/references/visual-effects.md

@@ -142,24 +142,22 @@ function GlassButton({ icon, onPress }) {
 
 ### Checking Availability
 
+Check both guards: `isLiquidGlassAvailable()` (OS support) and `isGlassEffectAPIAvailable()` — some iOS 26 beta versions lack the API and crash without the second check.
+
 ```tsx
-import { isLiquidGlassAvailable } from "expo-glass-effect";
+import { isLiquidGlassAvailable, isGlassEffectAPIAvailable } from "expo-glass-effect";
 
-if (isLiquidGlassAvailable()) {
-  // Use GlassView
-} else {
-  // Fallback to BlurView or solid background
-}
+const canUseGlass = isLiquidGlassAvailable() && isGlassEffectAPIAvailable();
 ```
 
 ### Fallback Pattern
 
 ```tsx
-import { GlassView, isLiquidGlassAvailable } from "expo-glass-effect";
+import { GlassView, isLiquidGlassAvailable, isGlassEffectAPIAvailable } from "expo-glass-effect";
 import { BlurView } from "expo-blur";
 
 function AdaptiveGlass({ children, style }) {
-  if (isLiquidGlassAvailable()) {
+  if (isLiquidGlassAvailable() && isGlassEffectAPIAvailable()) {
     return <GlassView style={style}>{children}</GlassView>;
   }
 
@@ -171,6 +169,8 @@ function AdaptiveGlass({ children, style }) {
 }
 ```
 
+When the user has Reduce Transparency enabled (`AccessibilityInfo.isReduceTransparencyEnabled()`), skip glass *and* blur — render a solid `colors.systemBackground` surface instead.
+
 ## Sheet with Glass Background
 
 Make sheet backgrounds liquid glass on iOS 26+:
@@ -190,8 +190,9 @@ Make sheet backgrounds liquid glass on iOS 26+:
 ## Best Practices
 
 - Use `systemMaterial` tints for automatic dark mode support
-- Always set `overflow: 'hidden'` on BlurView for rounded corners
-- Use `isInteractive` on GlassView for buttons and pressables
-- Check `isLiquidGlassAvailable()` and provide fallbacks
+- Always set `overflow: 'hidden'` on BlurView for rounded corners — but never on a `GlassView` or its ancestors: glass clips itself via `borderRadius` (+ `borderCurve`), and outside clipping cuts off the rim highlight and press bulge
+- Use `isInteractive` on GlassView only for actual controls (buttons, pressables) — leave background surfaces non-interactive
+- Check `isLiquidGlassAvailable()` **and** `isGlassEffectAPIAvailable()`, provide fallbacks, and respect Reduce Transparency with a solid surface
+- Never animate opacity on a `GlassView` or an ancestor — animate content around a stable glass surface, or switch `glassEffectStyle` on the mounted view to change its look
 - Avoid nesting blur views (performance impact)
 - Keep blur intensity reasonable (50-100) for readability