@rune-kit/rune 2.8.0 → 2.11.0

package/extensions/mobile/skills/ota-updates.md

@@ -1,97 +1,97 @@
----
-name: "ota-updates"
-pack: "@rune/mobile"
-description: "OTA update strategy — EAS Update, runtime version management, rollback, staged rollouts, bytecode compatibility."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# ota-updates
-
-OTA update strategy — EAS Update, runtime version management, rollback, staged rollouts, bytecode compatibility.
-
-#### Workflow
-
-**Step 1 — Detect OTA setup**
-Use Grep to find: `expo-updates`, `Updates.checkForUpdateAsync`, `runtimeVersion` in `app.json`/`app.config.js`, `eas.json` update channel configuration, custom `UpdatesProvider`.
-
-**Step 2 — Audit OTA safety**
-Check for:
-- **Runtime version match**: OTA update only applies to builds with exactly matching `runtimeVersion`. A native dependency change bumps runtime version and invalidates all pending OTA updates. Verify `runtimeVersion` strategy (semver auto vs manual)
-- **Hermes bytecode compatibility**: Each RN version compiles to specific bytecode version. OTA built against RN 0.79 crashes on binary built with RN 0.78. NEVER OTA across RN version boundaries
-- **Update timing**: Updates apply on next cold start, NOT instantly. Users with app in background don't receive updates. For emergency fixes, need custom `UpdatesProvider` with in-session check
-- **Rollback gaps**: `eas update:rollback` has syntax bugs with specific flag combinations. Use branch-based rollback: republish previous update to same channel
-- **Rollout math**: 10% rollout = 10% of cold-start checks, NOT 10% of users. If 80% of users never cold-start in a week, actual reach is ~2%
-- **Native code limitation**: OTA ships JS bundle only. Bugs requiring native changes need full App Store submission
-
-**Step 3 — Emit OTA strategy**
-Emit: channel-based configuration (production/staging/preview), runtime version strategy, update check implementation with error handling, and rollback procedure.
-
-#### Example
-
-```json
-// eas.json — channel-based OTA configuration
-{
-  "build": {
-    "production": {
-      "channel": "production",
-      "distribution": "store",
-      "autoIncrement": true
-    },
-    "preview": {
-      "channel": "preview",
-      "distribution": "internal"
-    }
-  }
-}
-```
-
-```typescript
-// app.config.ts — runtime version strategy
-export default {
-  expo: {
-    runtimeVersion: {
-      policy: 'fingerprintExperimental', // Auto-bumps when native deps change
-    },
-    updates: {
-      url: 'https://u.expo.dev/your-project-id',
-      fallbackToCacheTimeout: 3000, // Don't block startup > 3s
-    },
-  },
-};
-```
-
-```typescript
-// Custom update check with error handling and staged rollout
-import * as Updates from 'expo-updates';
-
-async function checkForUpdate() {
-  if (__DEV__) return; // Skip in development
-
-  try {
-    const update = await Updates.checkForUpdateAsync();
-    if (!update.isAvailable) return;
-
-    // Download in background — don't block user
-    const result = await Updates.fetchUpdateAsync();
-    if (!result.isNew) return;
-
-    // Option A: Apply on next cold start (default, safe)
-    // User gets update automatically next time they fully close + reopen
-
-    // Option B: Prompt user to restart (for important fixes)
-    Alert.alert(
-      'Update Available',
-      'A new version is ready. Restart to apply?',
-      [
-        { text: 'Later', style: 'cancel' },
-        { text: 'Restart', onPress: () => Updates.reloadAsync() },
-      ]
-    );
-  } catch (error) {
-    // OTA failures should NEVER crash the app
-    // Log to error tracking, don't show to user
-    console.error('OTA check failed:', error);
-  }
-}
-```
+---
+name: "ota-updates"
+pack: "@rune/mobile"
+description: "OTA update strategy — EAS Update, runtime version management, rollback, staged rollouts, bytecode compatibility."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# ota-updates
+
+OTA update strategy — EAS Update, runtime version management, rollback, staged rollouts, bytecode compatibility.
+
+#### Workflow
+
+**Step 1 — Detect OTA setup**
+Use Grep to find: `expo-updates`, `Updates.checkForUpdateAsync`, `runtimeVersion` in `app.json`/`app.config.js`, `eas.json` update channel configuration, custom `UpdatesProvider`.
+
+**Step 2 — Audit OTA safety**
+Check for:
+- **Runtime version match**: OTA update only applies to builds with exactly matching `runtimeVersion`. A native dependency change bumps runtime version and invalidates all pending OTA updates. Verify `runtimeVersion` strategy (semver auto vs manual)
+- **Hermes bytecode compatibility**: Each RN version compiles to specific bytecode version. OTA built against RN 0.79 crashes on binary built with RN 0.78. NEVER OTA across RN version boundaries
+- **Update timing**: Updates apply on next cold start, NOT instantly. Users with app in background don't receive updates. For emergency fixes, need custom `UpdatesProvider` with in-session check
+- **Rollback gaps**: `eas update:rollback` has syntax bugs with specific flag combinations. Use branch-based rollback: republish previous update to same channel
+- **Rollout math**: 10% rollout = 10% of cold-start checks, NOT 10% of users. If 80% of users never cold-start in a week, actual reach is ~2%
+- **Native code limitation**: OTA ships JS bundle only. Bugs requiring native changes need full App Store submission
+
+**Step 3 — Emit OTA strategy**
+Emit: channel-based configuration (production/staging/preview), runtime version strategy, update check implementation with error handling, and rollback procedure.
+
+#### Example
+
+```json
+// eas.json — channel-based OTA configuration
+{
+  "build": {
+    "production": {
+      "channel": "production",
+      "distribution": "store",
+      "autoIncrement": true
+    },
+    "preview": {
+      "channel": "preview",
+      "distribution": "internal"
+    }
+  }
+}
+```
+
+```typescript
+// app.config.ts — runtime version strategy
+export default {
+  expo: {
+    runtimeVersion: {
+      policy: 'fingerprintExperimental', // Auto-bumps when native deps change
+    },
+    updates: {
+      url: 'https://u.expo.dev/your-project-id',
+      fallbackToCacheTimeout: 3000, // Don't block startup > 3s
+    },
+  },
+};
+```
+
+```typescript
+// Custom update check with error handling and staged rollout
+import * as Updates from 'expo-updates';
+
+async function checkForUpdate() {
+  if (__DEV__) return; // Skip in development
+
+  try {
+    const update = await Updates.checkForUpdateAsync();
+    if (!update.isAvailable) return;
+
+    // Download in background — don't block user
+    const result = await Updates.fetchUpdateAsync();
+    if (!result.isNew) return;
+
+    // Option A: Apply on next cold start (default, safe)
+    // User gets update automatically next time they fully close + reopen
+
+    // Option B: Prompt user to restart (for important fixes)
+    Alert.alert(
+      'Update Available',
+      'A new version is ready. Restart to apply?',
+      [
+        { text: 'Later', style: 'cancel' },
+        { text: 'Restart', onPress: () => Updates.reloadAsync() },
+      ]
+    );
+  } catch (error) {
+    // OTA failures should NEVER crash the app
+    // Log to error tracking, don't show to user
+    console.error('OTA check failed:', error);
+  }
+}
+```

package/extensions/mobile/skills/push-notifications.md

@@ -1,111 +1,111 @@
----
-name: "push-notifications"
-pack: "@rune/mobile"
-description: "Push notification setup — FCM v1, APNs, Expo Notifications, permission handling, scheduling, debugging delivery failures."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# push-notifications
-
-Push notification setup — FCM v1, APNs, Expo Notifications, permission handling, scheduling, debugging delivery failures.
-
-#### Workflow
-
-**Step 1 — Detect notification setup**
-Use Grep to find: `expo-notifications`, `@react-native-firebase/messaging`, `firebase.messaging`, push token registration, notification listeners. Check `app.json` plugins for `expo-notifications` config. Check for `google-services.json` (Android) and `GoogleService-Info.plist` (iOS).
-
-**Step 2 — Audit FCM v1 migration**
-Check for:
-- FCM Legacy API usage (server key string instead of service account JSON): Legacy API is fully shut down since June 2024
-- `google-services.json` must be FCM v1 version — old files from Legacy API still circulate in repos
-- `MismatchSenderId` error: FCM server key and `google-services.json` project_number must match same Firebase project
-- Multiple Firebase environments: dev/staging/prod need separate `google-services.json` files with environment-specific project numbers
-
-**Step 3 — Audit iOS-specific gotchas**
-Check for:
-- `aps-environment` entitlement: works in dev builds but fails in production if `expo-notifications` not in `app.json` plugins array
-- `getDevicePushTokenAsync()` race condition: silently never resolves on SDK 53+ for some users (GitHub #37516). Must call after app is fully initialized, not in root layout mount
-- iOS requires paid Apple Developer account ($99/yr) for APNs — no way to test push on Simulator or free account
-- iOS 18: explicit permission prompt required before scheduling local notifications — call `requestPermissionsAsync()` first
-- Push notifications removed from Expo Go on Android (SDK 53+). Must use development build
-
-**Step 4 — Audit permission handling**
-Check that permission is requested at contextual moment (not app launch), fallback UI shown when denied, and `Settings.openURL` offered for re-enabling from Settings.
-
-**Step 5 — Emit notification pipeline**
-Emit: server-side push via FCM v1 HTTP API with service account auth, client-side token registration with retry, notification listener setup with cleanup, and scheduled notification with proper permission check.
-
-#### Example
-
-```typescript
-// Server — FCM v1 push (NOT legacy). Requires service account JSON
-import { GoogleAuth } from 'google-auth-library';
-
-const auth = new GoogleAuth({
-  keyFile: 'service-account.json', // NOT a server key string
-  scopes: ['https://www.googleapis.com/auth/firebase.messaging'],
-});
-
-async function sendPush(token: string, title: string, body: string, data?: Record<string, string>) {
-  const client = await auth.getClient();
-  const projectId = 'your-project-id';
-
-  const response = await client.request({
-    url: `https://fcm.googleapis.com/v1/projects/${projectId}/messages:send`,
-    method: 'POST',
-    data: {
-      message: {
-        token,
-        notification: { title, body },
-        data: data ?? {},
-        android: { priority: 'high' },
-        apns: {
-          payload: { aps: { sound: 'default', badge: 1 } },
-          headers: { 'apns-priority': '10' },
-        },
-      },
-    },
-  });
-  return response.data;
-}
-```
-
-```typescript
-// Client — Expo Notifications with proper lifecycle
-import * as Notifications from 'expo-notifications';
-import * as Device from 'expo-device';
-
-// Configure BEFORE any notification arrives
-Notifications.setNotificationHandler({
-  handleNotification: async () => ({
-    shouldShowAlert: true,
-    shouldPlaySound: true,
-    shouldSetBadge: true,
-  }),
-});
-
-async function registerForPush(): Promise<string | null> {
-  if (!Device.isDevice) {
-    console.warn('Push notifications require a physical device');
-    return null;
-  }
-
-  const { status: existing } = await Notifications.getPermissionsAsync();
-  let finalStatus = existing;
-
-  if (existing !== 'granted') {
-    // Request at contextual moment, NOT app launch
-    const { status } = await Notifications.requestPermissionsAsync();
-    finalStatus = status;
-  }
-
-  if (finalStatus !== 'granted') return null;
-
-  // Must be called AFTER app is fully initialized (not in root layout mount)
-  const { data: token } = await Notifications.getExpoPushTokenAsync({
-    projectId: 'your-expo-project-id', // Required for EAS
-  });
-  return token;
-}
-```
+---
+name: "push-notifications"
+pack: "@rune/mobile"
+description: "Push notification setup — FCM v1, APNs, Expo Notifications, permission handling, scheduling, debugging delivery failures."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# push-notifications
+
+Push notification setup — FCM v1, APNs, Expo Notifications, permission handling, scheduling, debugging delivery failures.
+
+#### Workflow
+
+**Step 1 — Detect notification setup**
+Use Grep to find: `expo-notifications`, `@react-native-firebase/messaging`, `firebase.messaging`, push token registration, notification listeners. Check `app.json` plugins for `expo-notifications` config. Check for `google-services.json` (Android) and `GoogleService-Info.plist` (iOS).
+
+**Step 2 — Audit FCM v1 migration**
+Check for:
+- FCM Legacy API usage (server key string instead of service account JSON): Legacy API is fully shut down since June 2024
+- `google-services.json` must be FCM v1 version — old files from Legacy API still circulate in repos
+- `MismatchSenderId` error: FCM server key and `google-services.json` project_number must match same Firebase project
+- Multiple Firebase environments: dev/staging/prod need separate `google-services.json` files with environment-specific project numbers
+
+**Step 3 — Audit iOS-specific gotchas**
+Check for:
+- `aps-environment` entitlement: works in dev builds but fails in production if `expo-notifications` not in `app.json` plugins array
+- `getDevicePushTokenAsync()` race condition: silently never resolves on SDK 53+ for some users (GitHub #37516). Must call after app is fully initialized, not in root layout mount
+- iOS requires paid Apple Developer account ($99/yr) for APNs — no way to test push on Simulator or free account
+- iOS 18: explicit permission prompt required before scheduling local notifications — call `requestPermissionsAsync()` first
+- Push notifications removed from Expo Go on Android (SDK 53+). Must use development build
+
+**Step 4 — Audit permission handling**
+Check that permission is requested at contextual moment (not app launch), fallback UI shown when denied, and `Settings.openURL` offered for re-enabling from Settings.
+
+**Step 5 — Emit notification pipeline**
+Emit: server-side push via FCM v1 HTTP API with service account auth, client-side token registration with retry, notification listener setup with cleanup, and scheduled notification with proper permission check.
+
+#### Example
+
+```typescript
+// Server — FCM v1 push (NOT legacy). Requires service account JSON
+import { GoogleAuth } from 'google-auth-library';
+
+const auth = new GoogleAuth({
+  keyFile: 'service-account.json', // NOT a server key string
+  scopes: ['https://www.googleapis.com/auth/firebase.messaging'],
+});
+
+async function sendPush(token: string, title: string, body: string, data?: Record<string, string>) {
+  const client = await auth.getClient();
+  const projectId = 'your-project-id';
+
+  const response = await client.request({
+    url: `https://fcm.googleapis.com/v1/projects/${projectId}/messages:send`,
+    method: 'POST',
+    data: {
+      message: {
+        token,
+        notification: { title, body },
+        data: data ?? {},
+        android: { priority: 'high' },
+        apns: {
+          payload: { aps: { sound: 'default', badge: 1 } },
+          headers: { 'apns-priority': '10' },
+        },
+      },
+    },
+  });
+  return response.data;
+}
+```
+
+```typescript
+// Client — Expo Notifications with proper lifecycle
+import * as Notifications from 'expo-notifications';
+import * as Device from 'expo-device';
+
+// Configure BEFORE any notification arrives
+Notifications.setNotificationHandler({
+  handleNotification: async () => ({
+    shouldShowAlert: true,
+    shouldPlaySound: true,
+    shouldSetBadge: true,
+  }),
+});
+
+async function registerForPush(): Promise<string | null> {
+  if (!Device.isDevice) {
+    console.warn('Push notifications require a physical device');
+    return null;
+  }
+
+  const { status: existing } = await Notifications.getPermissionsAsync();
+  let finalStatus = existing;
+
+  if (existing !== 'granted') {
+    // Request at contextual moment, NOT app launch
+    const { status } = await Notifications.requestPermissionsAsync();
+    finalStatus = status;
+  }
+
+  if (finalStatus !== 'granted') return null;
+
+  // Must be called AFTER app is fully initialized (not in root layout mount)
+  const { data: token } = await Notifications.getExpoPushTokenAsync({
+    projectId: 'your-expo-project-id', // Required for EAS
+  });
+  return token;
+}
+```

package/extensions/mobile/skills/react-native.md

@@ -1,82 +1,82 @@
----
-name: "react-native"
-pack: "@rune/mobile"
-description: "React Native patterns — New Architecture migration, navigation, state management, native modules, performance optimization, Expo vs bare workflow decisions."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# react-native
-
-React Native patterns — New Architecture migration, navigation, state management, native modules, performance optimization, Expo vs bare workflow decisions.
-
-#### Workflow
-
-**Step 1 — Detect React Native setup**
-Use Grep to find framework markers: `react-native` in package.json (extract version — 0.82+ = New Architecture mandatory), `expo` config (extract SDK version — 53+ = New Arch default), navigation library (`@react-navigation/native` v6 vs v7, `expo-router` v3 vs v4), state management (`zustand`, `redux`, `jotai`), and native module usage. Read `app.json`/`app.config.js` for Expo configuration.
-
-**Step 2 — Audit New Architecture readiness**
-Check for:
-- `react-native` >= 0.82 or Expo SDK >= 55: New Architecture is mandatory, no opt-out
-- `setNativeProps` usage: incompatible with New Architecture, must migrate to Reanimated or Animated API
-- Third-party libraries using legacy Bridge (`NativeModules.X` directly instead of TurboModules): check each against `reactnative.directory` compatibility list
-- `react-native-reanimated` version: must be >= 3.8 to avoid Android animation stutter on New Architecture (GitHub #7435)
-- Kotlin version in `android/build.gradle`: Reanimated + Kotlin 1.9.25 fails EAS Build (GitHub #7674)
-- State batching: New Architecture enables React 18 concurrent batching — components relying on intermediate state between updates silently break
-
-**Step 3 — Audit performance patterns**
-Check for: FlatList without `keyExtractor` or with inline `renderItem` (re-renders), images using `react-native-fast-image` (not compatible with New Architecture — migrate to `expo-image`), heavy re-renders from context (missing `useMemo`/`useCallback`), navigation listeners not cleaned up, large JS bundle without lazy loading (`React.lazy` + `Suspense`), `removeClippedSubviews` causing blank cells on fast scroll.
-
-**Step 4 — Audit navigation patterns (React Navigation v7 / Expo Router v4)**
-Check for:
-- `navigate()` calls: v7 changed semantics — now pushes new screen even if route exists in stack (v6 navigated to existing instance). Audit all `navigation.navigate()` calls
-- `useNavigation()` hook: causes re-renders on every route change in Expo Router v4, not just current route (GitHub #35383). Replace with `useRouter()` for navigation-only usage
-- Non-unique navigator names: deep links silently fail to resolve (GitHub #9267)
-- Authentication + deep link race condition: `NavigationContainer` not ready when initial URL received. Must capture URL, wait for auth, then navigate
-
-**Step 5 — Emit optimized patterns**
-For each issue, emit the fix: memoized FlatList item components, `expo-image` migration, proper navigation with typed routes, optimized state selectors, and Hermes engine configuration. For New Architecture migration, emit a phased plan: audit → update libraries → enable → test → fix regressions.
-
-#### Example
-
-```tsx
-// BEFORE: FlatList anti-patterns + legacy image library
-import FastImage from 'react-native-fast-image'; // ❌ Not New Arch compatible
-<FlatList
-  data={items}
-  renderItem={({ item }) => (
-    <View>
-      <FastImage source={{ uri: item.image }} />
-      <Text>{item.name}</Text>
-    </View>
-  )}
-/>
-
-// AFTER: New Architecture compatible, memoized, proper image caching
-import { Image } from 'expo-image'; // ✅ New Arch compatible
-import { FlashList } from '@shopify/flash-list'; // ✅ Better than FlatList
-
-const ItemCard = React.memo<{ item: Item; onPress: () => void }>(({ item, onPress }) => (
-  <Pressable onPress={onPress}>
-    <Image
-      source={item.image}
-      style={styles.image}
-      contentFit="cover"
-      placeholder={item.blurhash}
-      transition={200}
-    />
-    <Text>{item.name}</Text>
-  </Pressable>
-));
-
-const renderItem = useCallback(({ item }: { item: Item }) => (
-  <ItemCard item={item} onPress={() => router.push(`/product/${item.id}`)} />
-), [router]);
-
-<FlashList
-  data={items}
-  renderItem={renderItem}
-  estimatedItemSize={88} // Required — measure actual item height
-  keyExtractor={item => item.id}
-/>
-```
+---
+name: "react-native"
+pack: "@rune/mobile"
+description: "React Native patterns — New Architecture migration, navigation, state management, native modules, performance optimization, Expo vs bare workflow decisions."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# react-native
+
+React Native patterns — New Architecture migration, navigation, state management, native modules, performance optimization, Expo vs bare workflow decisions.
+
+#### Workflow
+
+**Step 1 — Detect React Native setup**
+Use Grep to find framework markers: `react-native` in package.json (extract version — 0.82+ = New Architecture mandatory), `expo` config (extract SDK version — 53+ = New Arch default), navigation library (`@react-navigation/native` v6 vs v7, `expo-router` v3 vs v4), state management (`zustand`, `redux`, `jotai`), and native module usage. Read `app.json`/`app.config.js` for Expo configuration.
+
+**Step 2 — Audit New Architecture readiness**
+Check for:
+- `react-native` >= 0.82 or Expo SDK >= 55: New Architecture is mandatory, no opt-out
+- `setNativeProps` usage: incompatible with New Architecture, must migrate to Reanimated or Animated API
+- Third-party libraries using legacy Bridge (`NativeModules.X` directly instead of TurboModules): check each against `reactnative.directory` compatibility list
+- `react-native-reanimated` version: must be >= 3.8 to avoid Android animation stutter on New Architecture (GitHub #7435)
+- Kotlin version in `android/build.gradle`: Reanimated + Kotlin 1.9.25 fails EAS Build (GitHub #7674)
+- State batching: New Architecture enables React 18 concurrent batching — components relying on intermediate state between updates silently break
+
+**Step 3 — Audit performance patterns**
+Check for: FlatList without `keyExtractor` or with inline `renderItem` (re-renders), images using `react-native-fast-image` (not compatible with New Architecture — migrate to `expo-image`), heavy re-renders from context (missing `useMemo`/`useCallback`), navigation listeners not cleaned up, large JS bundle without lazy loading (`React.lazy` + `Suspense`), `removeClippedSubviews` causing blank cells on fast scroll.
+
+**Step 4 — Audit navigation patterns (React Navigation v7 / Expo Router v4)**
+Check for:
+- `navigate()` calls: v7 changed semantics — now pushes new screen even if route exists in stack (v6 navigated to existing instance). Audit all `navigation.navigate()` calls
+- `useNavigation()` hook: causes re-renders on every route change in Expo Router v4, not just current route (GitHub #35383). Replace with `useRouter()` for navigation-only usage
+- Non-unique navigator names: deep links silently fail to resolve (GitHub #9267)
+- Authentication + deep link race condition: `NavigationContainer` not ready when initial URL received. Must capture URL, wait for auth, then navigate
+
+**Step 5 — Emit optimized patterns**
+For each issue, emit the fix: memoized FlatList item components, `expo-image` migration, proper navigation with typed routes, optimized state selectors, and Hermes engine configuration. For New Architecture migration, emit a phased plan: audit → update libraries → enable → test → fix regressions.
+
+#### Example
+
+```tsx
+// BEFORE: FlatList anti-patterns + legacy image library
+import FastImage from 'react-native-fast-image'; // ❌ Not New Arch compatible
+<FlatList
+  data={items}
+  renderItem={({ item }) => (
+    <View>
+      <FastImage source={{ uri: item.image }} />
+      <Text>{item.name}</Text>
+    </View>
+  )}
+/>
+
+// AFTER: New Architecture compatible, memoized, proper image caching
+import { Image } from 'expo-image'; // ✅ New Arch compatible
+import { FlashList } from '@shopify/flash-list'; // ✅ Better than FlatList
+
+const ItemCard = React.memo<{ item: Item; onPress: () => void }>(({ item, onPress }) => (
+  <Pressable onPress={onPress}>
+    <Image
+      source={item.image}
+      style={styles.image}
+      contentFit="cover"
+      placeholder={item.blurhash}
+      transition={200}
+    />
+    <Text>{item.name}</Text>
+  </Pressable>
+));
+
+const renderItem = useCallback(({ item }: { item: Item }) => (
+  <ItemCard item={item} onPress={() => router.push(`/product/${item.id}`)} />
+), [router]);
+
+<FlashList
+  data={items}
+  renderItem={renderItem}
+  estimatedItemSize={88} // Required — measure actual item height
+  keyExtractor={item => item.id}
+/>
+```