@codyswann/lisa 2.111.0 → 2.112.0

package/plugins/src/expo/skills/add-app-clip/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: add-app-clip
+description: Add an iOS App Clip target to an Expo app. Use when the user mentions App Clip, AASA, apple-app-site-association, appclips, smart app banner, or wants to ship a lightweight iOS Clip invoked from a URL alongside their parent app.
+---
+
+# Add an App Clip to an Expo App
+
+Adds an iOS App Clip target to an Expo project. The Clip lives in `targets/clip/`, ships alongside the parent app, and is invoked from a URL on the app's domain via an Apple App Site Association (AASA) file.
+
+The parent app's bundle ID becomes `com.<username>.<app-name>` and the Clip's is automatically derived as `<parent>.clip` (e.g. `com.bacon.may20.clip`).
+
+## 1. Set `bundleIdentifier` and `appleTeamId`
+
+`bun create target` warns if these are missing. Add to `app.json`:
+
+```json
+{
+  "expo": {
+    "ios": {
+      "bundleIdentifier": "com.<username>.<app-name>",
+      "appleTeamId": "XX57RJ5UTD"
+    }
+  }
+}
+```
+
+## 2. Add the App Clip target
+
+```sh
+bun create target clip
+```
+
+This installs [`@bacons/apple-targets`](https://github.com/EvanBacon/expo-apple-targets), adds it to the `plugins` array in `app.json`, and writes:
+
+- `targets/clip/expo-target.config.js` — the target's config plugin
+- `targets/clip/Info.plist` — Clip Info.plist
+- `targets/clip/AppDelegate.swift`, `Assets.xcassets`, etc.
+
+Pick a good icon or reuse the existing one defined in the app — check it with `bunx expo config` under the `icon` or `ios.icon` key.
+
+## 3. Wire up associated domains
+
+The parent app and the Clip each need the Associated Domains entitlement pointing at the domain that hosts the AASA file.
+
+In `app.json`, add both `applinks:` (parent) and `appclips:` (Clip invocation) entries:
+
+```json
+{
+  "expo": {
+    "ios": {
+      "associatedDomains": [
+        "applinks:may20.expo.app",
+        "appclips:may20.expo.app"
+      ]
+    }
+  }
+}
+```
+
+In `targets/clip/expo-target.config.js`, declare the Clip's entitlement:
+
+```js
+/** @type {import('@bacons/apple-targets/app.plugin').ConfigFunction} */
+module.exports = (config) => ({
+  type: "clip",
+  icon: "https://github.com/expo.png",
+  entitlements: {
+    "com.apple.developer.associated-domains": ["appclips:may20.expo.app"],
+  },
+});
+```
+
+> If you skip this, `expo prebuild` will print: `Apple App Clip may require the associated domains entitlement but none were found`.
+
+## 4. Register bundle IDs and create the App Store entry
+
+```sh
+bunx setup-safari
+```
+
+This logs in to the Apple Developer account, registers `com.bacon.may20`, creates the App Store Connect entry, and prints:
+
+- A starter `apple-app-site-association` JSON
+- A `<meta name="apple-itunes-app">` tag with the iTunes app id
+- Team ID, iTunes ID, and Bundle ID
+
+## 5. Host the AASA file
+
+App Clips are invoked when iOS fetches `https://<your-domain>/.well-known/apple-app-site-association` and finds a matching `appclips` entry.
+
+```sh
+mkdir -p public/.well-known
+touch public/.well-known/apple-app-site-association
+```
+
+Paste the JSON `setup-safari` printed, but **add an `appclips` block** for the Clip's full app ID (`<TeamID>.<ClipBundleID>`). The output of `setup-safari` only covers the parent app:
+
+```json
+{
+  "applinks": {
+    "details": [
+      {
+        "appIDs": ["XX57RJ5UTD.com.bacon.may20"],
+        "components": [{ "/": "*", "comment": "Matches all routes" }]
+      }
+    ]
+  },
+  "appclips": {
+    "apps": ["XX57RJ5UTD.com.bacon.may20.clip"]
+  },
+  "activitycontinuation": {
+    "apps": ["XX57RJ5UTD.com.bacon.may20"]
+  },
+  "webcredentials": {
+    "apps": ["XX57RJ5UTD.com.bacon.may20"]
+  }
+}
+```
+
+Notes:
+
+- The file has **no extension** and **no `Content-Type` requirements** beyond being served as-is. Expo Router static export serves files in `public/` verbatim.
+- The `appclips` block is what lets a URL on the domain launch the Clip.
+- `webcredentials` is used for sharing credentials between the website, parent app, and the App Clip.
+- `activitycontinuation` is optional and used for sharing the link between mobile and desktop. Must be used with `Head` from expo-router — see https://docs.expo.dev/router/advanced/apple-handoff/
+- Notation and route-disabling details: https://sosumi.ai/documentation/xcode/supporting-associated-domains
+
+## 6. Add the Smart App Banner meta tag
+
+Create `src/app/+html.tsx` (Expo Router's HTML shell) and add the tag from `setup-safari`. Create the versioned template if it doesn't exist:
+
+```sh
+bunx expo customize src/app/+html.tsx
+```
+
+Add the meta tag to the `<head>`:
+
+```tsx
+import { ScrollViewStyleReset } from "expo-router/html";
+
+export default function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="apple-itunes-app" content="app-id=6771566491" />
+        <ScrollViewStyleReset />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+To make the website show the App Clip card instead of the install card, use:
+
+```html
+<meta
+  name="apple-itunes-app"
+  content="app-id=6771566491, app-clip-bundle-id=com.bacon.may20.clip, app-clip-display=card"
+/>
+```
+
+## 7. Deploy the website
+
+The AASA file must be live before iOS will trust the association. Use [EAS Hosting](https://docs.expo.dev/eas/hosting/):
+
+```sh
+bunx expo export -p web
+eas deploy --prod
+```
+
+This publishes the site (including `/.well-known/apple-app-site-association`) at `https://<slug>.expo.app`. Verify:
+
+```sh
+curl https://may20.expo.app/.well-known/apple-app-site-association
+```
+
+## 8. Mirror permissions
+
+Inspect the parent app's permissions after prebuild:
+
+```sh
+npx expo config --type introspect
+```
+
+Look at the `infoPlist` object — mirror the permission keys in the App Clip's `Info.plist` so matching APIs can be used from the Clip.
+
+Set `deploymentTarget: "17.6"` in the Clip's target config — App Clips have a higher minimum size limit in iOS 17.6.
+
+If the app uses push notifications or location services, add to the App Clip's `Info.plist` to request the necessary permissions:
+
+```xml
+<key>NSAppClip</key>
+<dict>
+  <key>NSAppClipRequestEphemeralUserNotification</key>
+  <false/>
+  <key>NSAppClipRequestLocationConfirmation</key>
+  <true/>
+</dict>
+```
+
+## 9. Build and submit to TestFlight
+
+```sh
+bunx testflight
+```
+
+This will:
+
+1. Generate an `eas.json` if missing.
+2. Set up credentials for **both** targets (parent + Clip). Each gets its own provisioning profile but can share a single Distribution Certificate.
+3. Sync capabilities — note `Enabled: Associated Domains` for the Clip target.
+4. Build, upload, and schedule a TestFlight submission.
+
+## 10. Configure App Clip metadata
+
+Pull existing App Store metadata to local:
+
+```sh
+eas metadata:pull
+```
+
+Add `apple.appClip` to `store.config.json`. Up to 3 invocation URLs can launch the Clip from a web page:
+
+```json
+{
+  "configVersion": 0,
+  "apple": {
+    "appClip": {
+      "defaultExperience": {
+        "action": "PLAY",
+        "releaseWithAppStoreVersion": true,
+        "reviewDetail": {
+          "invocationUrls": ["https://may20.expo.app/", null, null]
+        },
+        "info": {
+          "en-US": {
+            "subtitle": "Instantly native with Expo",
+            "headerImage": "store/apple/app-clip/en-US/asc-app-clip.png"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The `headerImage` must be a 1800x1200 PNG with no opacity.
+
+Push back to the store:
+
+```sh
+eas metadata:push
+```
+
+Apple's recommended App Clip metadata guidelines: https://sosumi.ai/documentation/appclip/configuring-the-launch-experience-of-your-app-clip
+
+## What you get
+
+- Parent app target: `com.bacon.may20`
+- App Clip target: `com.bacon.may20.clip`, lives in `targets/clip/`
+- AASA hosted at `https://may20.expo.app/.well-known/apple-app-site-association`
+- Smart App Banner meta tag on every web route
+- Every route linked to its native counterpart
+- TestFlight build of the parent app with the Clip embedded
+
+Once Apple invokes the Clip from a URL on the domain, iOS opens `targets/clip/`'s entry point which loads the React Native app.
+
+## Native detection (optional)
+
+To let JS detect when it's running inside an App Clip and present an install prompt for the full app, create a local Expo module (`bunx create-expo-module --local`) that exposes `navigator.appClip.prompt()`.
+
+See [./references/native-module.md](./references/native-module.md) for the Swift module, TypeScript interface, and usage.
+
+## References
+
+- ./references/native-module.md — Local Expo module to detect App Clip context and present the SKOverlay install prompt

package/plugins/src/expo/skills/add-app-clip/references/native-module.md

@@ -0,0 +1,96 @@
+# Native App Clip detection
+
+Create a local Expo module so JS can detect when the app is running inside an App Clip and present the install prompt for the full app.
+
+```sh
+bunx create-expo-module --local
+```
+
+## Swift module
+
+```swift
+import ExpoModulesCore
+import StoreKit
+
+internal class MissingCurrentWindowSceneException: Exception {
+  override var reason: String {
+    "Cannot determine the current window scene in which to present the App Clip install overlay."
+  }
+}
+
+internal class MissingContainerURLException: Exception {
+  override var reason: String {
+    "Cannot determine the container URL."
+  }
+}
+
+public class AppClipModule: Module {
+  private static let isAppClip: Bool = {
+    if let infoPlist = Bundle.main.infoDictionary, let _ = infoPlist["NSAppClip"] as? [String: Any] {
+      return true
+    }
+    return false
+  }()
+
+  public func definition() -> ModuleDefinition {
+    Name("AppClip")
+
+    Constant("isAppClip") {
+      AppClipModule.isAppClip
+    }
+
+    // Display overlay to advertise full app.
+    // https://developer.apple.com/documentation/app_clips/recommending_your_app_to_app_clip_users
+    AsyncFunction("prompt") {
+      if #available(iOS 16, *) {
+        guard let currentScene = UIApplication.shared.connectedScenes.first as? UIWindowScene else {
+          throw MissingCurrentWindowSceneException()
+        }
+
+        let config = SKOverlay.AppClipConfiguration(position: .bottom)
+        let overlay = SKOverlay(configuration: config)
+        overlay.present(in: currentScene)
+      }
+    }.runOnQueue(DispatchQueue.main)
+  }
+}
+```
+
+## TypeScript interface
+
+```ts
+import { NativeModule, requireOptionalNativeModule } from "expo";
+
+declare class AppClipModule extends NativeModule<{}> {
+  prompt(): void;
+  isAppClip?: boolean;
+}
+
+const AppClipNative = requireOptionalNativeModule<AppClipModule>("AppClip");
+
+if (AppClipNative?.isAppClip) {
+  navigator.appClip = {
+    prompt: AppClipNative.prompt,
+  };
+}
+
+declare global {
+  interface Navigator {
+    /**
+     * Only available in an App Clip context.
+     * @expo
+     */
+    appClip?: {
+      /** Open the SKOverlay */
+      prompt: () => void;
+    };
+  }
+}
+
+export {};
+```
+
+## Usage
+
+- Detect App Clip context: `if (navigator.appClip) { ... }`
+- Prompt to install the full app: `navigator.appClip?.prompt()`

package/plugins/src/expo/skills/building-native-ui/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: building-native-ui
+description: Complete guide for building beautiful apps with Expo Router. Covers fundamentals, styling, components, navigation, animations, patterns, and native tabs.
+version: 1.0.1
+license: MIT
+---
+
+# Expo UI Guidelines
+
+## References
+
+Consult these resources as needed:
+
+```
+references/
+  animations.md          Reanimated: entering, exiting, layout, scroll-driven, gestures
+  controls.md            Native iOS: Switch, Slider, SegmentedControl, DateTimePicker, Picker
+  form-sheet.md          Form sheets in expo-router: configuration, footers and background interaction. 
+  gradients.md           CSS gradients via experimental_backgroundImage (New Arch only)
+  icons.md               SF Symbols via expo-image (sf: source), names, animations, weights
+  media.md               Camera, audio, video, and file saving
+  route-structure.md     Route conventions, dynamic routes, groups, folder organization
+  search.md              Search bar with headers, useSearch hook, filtering patterns
+  storage.md             SQLite, AsyncStorage, SecureStore
+  tabs.md                NativeTabs, migration from JS tabs, iOS 26 features
+  toolbar-and-headers.md Stack headers and toolbar buttons, menus, search (iOS only)
+  visual-effects.md      Blur (expo-blur) and liquid glass (expo-glass-effect)
+  webgpu-three.md        3D graphics, games, GPU visualizations with WebGPU and Three.js
+  zoom-transitions.md    Apple Zoom: fluid zoom transitions with Link.AppleZoom (iOS 18+)
+```
+
+## Running the App
+
+**CRITICAL: Always try Expo Go first before creating custom builds.**
+
+Most Expo apps work in Expo Go without any custom native code. Before running `npx expo run:ios` or `npx expo run:android`:
+
+1. **Start with Expo Go**: Run `npx expo start` and scan the QR code with Expo Go
+2. **Check if features work**: Test your app thoroughly in Expo Go
+3. **Only create custom builds when required** - see below
+
+### When Custom Builds Are Required
+
+You need `npx expo run:ios/android` or `eas build` ONLY when using:
+
+- **Local Expo modules** (custom native code in `modules/`)
+- **Apple targets** (widgets, app clips, extensions via `@bacons/apple-targets`)
+- **Third-party native modules** not included in Expo Go
+- **Custom native configuration** that can't be expressed in `app.json`
+
+### When Expo Go Works
+
+Expo Go supports a huge range of features out of the box:
+
+- All `expo-*` packages (camera, location, notifications, etc.)
+- Expo Router navigation
+- 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.
+
+## Code Style
+
+- Be cautious of unterminated strings. Ensure nested backticks are escaped; never forget to escape quotes correctly.
+- Always use import statements at the top of the file.
+- Always use kebab-case for file names, e.g. `comment-card.tsx`
+- Always remove old route files when moving or restructuring navigation
+- Never use special characters in file names
+- Configure tsconfig.json with path aliases, and prefer aliases over relative imports for refactors.
+
+## Routes
+
+See `./references/route-structure.md` for detailed route conventions.
+
+- Routes belong in the `app` directory.
+- Never co-locate components, types, or utilities in the app directory. This is an anti-pattern.
+- Ensure the app always has a route that matches "/", it may be inside a group route.
+
+## Library Preferences
+
+- Never use modules removed from React Native such as Picker, WebView, SafeAreaView, or AsyncStorage
+- 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`
+- `react-native-safe-area-context` not react-native SafeAreaView
+- `process.env.EXPO_OS` not `Platform.OS`
+- `React.use` not `React.useContext`
+- `expo-image` Image component instead of intrinsic element `img`
+- `expo-glass-effect` for liquid glass backdrops
+
+## Responsiveness
+
+- Always wrap root component in a scroll view for responsiveness
+- 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
+- ALWAYS prefer `useWindowDimensions` over `Dimensions.get()` to measure screen size
+
+## Behavior
+
+- 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
+- Prefer `headerSearchBarOptions` in Stack.Screen options to add a search bar
+- 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
+
+# Styling
+
+Follow Apple Human Interface Guidelines.
+
+## General Styling Rules
+
+- Prefer flex gap over margin and padding styles
+- Prefer padding over margin where possible
+- 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
+- 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)
+- CSS and Tailwind are not supported - use inline styles
+
+## Text Styling
+
+- Add the `selectable` prop to every `<Text/>` element displaying important data or error messages
+- Counters should use `{ fontVariant: 'tabular-nums' }` for alignment
+
+## Shadows
+
+Use CSS `boxShadow` style prop. NEVER use legacy React Native shadow or elevation styles.
+
+```tsx
+<View style={{ boxShadow: "0 1px 2px rgba(0, 0, 0, 0.05)" }} />
+```
+
+'inset' shadows are supported.
+
+# Navigation
+
+## Link
+
+Use `<Link href="/path" />` from 'expo-router' for navigation between routes.
+
+```tsx
+import { Link } from 'expo-router';
+
+// Basic link
+<Link href="/path" />
+
+// Wrapping custom components
+<Link href="/path" asChild>
+  <Pressable>...</Pressable>
+</Link>
+```
+
+Whenever possible, include a `<Link.Preview>` to follow iOS conventions. Add context menus and previews frequently to enhance navigation.
+
+## Stack
+
+- ALWAYS use `_layout.tsx` files to define stacks
+- Use Stack from 'expo-router/stack' for native navigation stacks
+
+### Page Title
+
+Set the page title in Stack.Screen options:
+
+```tsx
+<Stack.Screen options={{ title: "Home" }} />
+```
+
+## Context Menus
+
+Add long press context menus to Link components:
+
+```tsx
+import { Link } from "expo-router";
+
+<Link href="/settings" asChild>
+  <Link.Trigger>
+    <Pressable>
+      <Card />
+    </Pressable>
+  </Link.Trigger>
+  <Link.Menu>
+    <Link.MenuAction
+      title="Share"
+      icon="square.and.arrow.up"
+      onPress={handleSharePress}
+    />
+    <Link.MenuAction
+      title="Block"
+      icon="nosign"
+      destructive
+      onPress={handleBlockPress}
+    />
+    <Link.Menu title="More" icon="ellipsis">
+      <Link.MenuAction title="Copy" icon="doc.on.doc" onPress={() => {}} />
+      <Link.MenuAction
+        title="Delete"
+        icon="trash"
+        destructive
+        onPress={() => {}}
+      />
+    </Link.Menu>
+  </Link.Menu>
+</Link>;
+```
+
+## Link Previews
+
+Use link previews frequently to enhance navigation:
+
+```tsx
+<Link href="/settings">
+  <Link.Trigger>
+    <Pressable>
+      <Card />
+    </Pressable>
+  </Link.Trigger>
+  <Link.Preview />
+</Link>
+```
+
+Link preview can be used with context menus.
+
+## Modal
+
+Present a screen as a modal:
+
+```tsx
+<Stack.Screen name="modal" options={{ presentation: "modal" }} />
+```
+
+Prefer this to building a custom modal component.
+
+## Sheet
+
+Present a screen as a dynamic form sheet:
+
+```tsx
+<Stack.Screen
+  name="sheet"
+  options={{
+    presentation: "formSheet",
+    sheetGrabberVisible: true,
+    sheetAllowedDetents: [0.5, 1.0],
+    contentStyle: { backgroundColor: "transparent" },
+  }}
+/>
+```
+
+- Using `contentStyle: { backgroundColor: "transparent" }` makes the background liquid glass on iOS 26+.
+
+## Common route structure
+
+A standard app layout with tabs and stacks inside each tab:
+
+```
+app/
+  _layout.tsx — <NativeTabs />
+  (index,search)/
+    _layout.tsx — <Stack />
+    index.tsx — Main list
+    search.tsx — Search view
+```
+
+```tsx
+// app/_layout.tsx
+import { NativeTabs, Icon, Label } from "expo-router/unstable-native-tabs";
+import { Theme } from "../components/theme";
+
+export default function Layout() {
+  return (
+    <Theme>
+      <NativeTabs>
+        <NativeTabs.Trigger name="(index)">
+          <Icon sf="list.dash" />
+          <Label>Items</Label>
+        </NativeTabs.Trigger>
+        <NativeTabs.Trigger name="(search)" role="search" />
+      </NativeTabs>
+    </Theme>
+  );
+}
+```
+
+Create a shared group route so both tabs can push common screens:
+
+```tsx
+// app/(index,search)/_layout.tsx
+import { Stack } from "expo-router/stack";
+import { PlatformColor } from "react-native";
+
+export default function Layout({ segment }) {
+  const screen = segment.match(/\((.*)\)/)?.[1]!;
+  const titles: Record<string, string> = { index: "Items", search: "Search" };
+
+  return (
+    <Stack
+      screenOptions={{
+        headerTransparent: true,
+        headerShadowVisible: false,
+        headerLargeTitleShadowVisible: false,
+        headerLargeStyle: { backgroundColor: "transparent" },
+        headerTitleStyle: { color: PlatformColor("label") },
+        headerLargeTitle: true,
+        headerBlurEffect: "none",
+        headerBackButtonDisplayMode: "minimal",
+      }}
+    >
+      <Stack.Screen name={screen} options={{ title: titles[screen] }} />
+      <Stack.Screen name="i/[id]" options={{ headerLargeTitle: false }} />
+    </Stack>
+  );
+}
+```