vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/expo-dom/SKILL.md

@@ -0,0 +1,417 @@
+---
+name: expo-dom
+description: Framework (OSS). Use Expo DOM components to run web code in a webview on native and as-is on web. Migrate web code to native incrementally. For the end-to-end migration of a whole web app, use the expo-web-to-native skill.
+version: 1.0.0
+license: MIT
+---
+
+## What are DOM Components?
+
+DOM components allow web code to run verbatim in a webview on native platforms while rendering as-is on web. This enables using web-only libraries like `recharts`, `react-syntax-highlighter`, or any React web library in your Expo app without modification.
+
+## When to Use DOM Components
+
+Use DOM components when you need:
+
+- **Web-only libraries** — Charts (recharts, chart.js), syntax highlighters, rich text editors, or any library that depends on DOM APIs
+- **Migrating web code** — Bring existing React web components to native without rewriting
+- **Complex HTML/CSS layouts** — When CSS features aren't available in React Native
+- **iframes or embeds** — Embedding external content that requires a browser context
+- **Canvas or WebGL** — Web graphics APIs not available natively
+
+## When NOT to Use DOM Components
+
+Avoid DOM components when:
+
+- **Native performance is critical** — Webviews add overhead
+- **Simple UI** — React Native components are more efficient for basic layouts
+- **Deep native integration** — Use local modules instead for native APIs
+- **Layout routes** — `_layout` files cannot be DOM components
+
+## Basic DOM Component
+
+Create a new file with the `'use dom';` directive at the top:
+
+```tsx
+// components/WebChart.tsx
+"use dom";
+
+export default function WebChart({
+  data,
+}: {
+  data: number[];
+  dom: import("expo/dom").DOMProps;
+}) {
+  return (
+    <div style={{ padding: 20 }}>
+      <h2>Chart Data</h2>
+      <ul>
+        {data.map((value, i) => (
+          <li key={i}>{value}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## Rules for DOM Components
+
+1. **Must have `'use dom';` directive** at the top of the file
+2. **Single default export** — One React component per file
+3. **Own file** — Cannot be defined inline or combined with native components
+4. **Serializable props only** — Strings, numbers, booleans, arrays, plain objects
+5. **Include CSS in the component file** — DOM components run in isolated context
+
+## The `dom` Prop
+
+Every DOM component receives a special `dom` prop for webview configuration. Always type it in your props:
+
+```tsx
+"use dom";
+
+interface Props {
+  content: string;
+  dom: import("expo/dom").DOMProps;
+}
+
+export default function MyComponent({ content }: Props) {
+  return <div>{content}</div>;
+}
+```
+
+### Common `dom` Prop Options
+
+```tsx
+// Disable body scrolling
+<DOMComponent dom={{ scrollEnabled: false }} />
+
+// Flow under the notch (disable safe area insets)
+<DOMComponent dom={{ contentInsetAdjustmentBehavior: "never" }} />
+
+// Control size manually
+<DOMComponent dom={{ style: { width: 300, height: 400 } }} />
+
+// Combine options
+<DOMComponent
+  dom={{
+    scrollEnabled: false,
+    contentInsetAdjustmentBehavior: "never",
+    style: { width: '100%', height: 500 }
+  }}
+/>
+```
+
+## Exposing Native Actions to the Webview
+
+Pass async functions as props to expose native functionality to the DOM component:
+
+```tsx
+// app/index.tsx (native)
+import { Alert } from "react-native";
+import DOMComponent from "@/components/dom-component";
+
+export default function Screen() {
+  return (
+    <DOMComponent
+      showAlert={async (message: string) => {
+        Alert.alert("From Web", message);
+      }}
+      saveData={async (data: { name: string; value: number }) => {
+        // Save to native storage, database, etc.
+        console.log("Saving:", data);
+        return { success: true };
+      }}
+    />
+  );
+}
+```
+
+```tsx
+// components/dom-component.tsx
+"use dom";
+
+interface Props {
+  showAlert: (message: string) => Promise<void>;
+  saveData: (data: {
+    name: string;
+    value: number;
+  }) => Promise<{ success: boolean }>;
+  dom?: import("expo/dom").DOMProps;
+}
+
+export default function DOMComponent({ showAlert, saveData }: Props) {
+  const handleClick = async () => {
+    await showAlert("Hello from the webview!");
+    const result = await saveData({ name: "test", value: 42 });
+    console.log("Save result:", result);
+  };
+
+  return <button onClick={handleClick}>Trigger Native Action</button>;
+}
+```
+
+## Using Web Libraries
+
+DOM components can use any web library:
+
+```tsx
+// components/syntax-highlight.tsx
+"use dom";
+
+import SyntaxHighlighter from "react-syntax-highlighter";
+import { docco } from "react-syntax-highlighter/dist/esm/styles/hljs";
+
+interface Props {
+  code: string;
+  language: string;
+  dom?: import("expo/dom").DOMProps;
+}
+
+export default function SyntaxHighlight({ code, language }: Props) {
+  return (
+    <SyntaxHighlighter language={language} style={docco}>
+      {code}
+    </SyntaxHighlighter>
+  );
+}
+```
+
+```tsx
+// components/chart.tsx
+"use dom";
+
+import {
+  LineChart,
+  Line,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+} from "recharts";
+
+interface Props {
+  data: Array<{ name: string; value: number }>;
+  dom: import("expo/dom").DOMProps;
+}
+
+export default function Chart({ data }: Props) {
+  return (
+    <LineChart width={400} height={300} data={data}>
+      <CartesianGrid strokeDasharray="3 3" />
+      <XAxis dataKey="name" />
+      <YAxis />
+      <Tooltip />
+      <Line type="monotone" dataKey="value" stroke="#8884d8" />
+    </LineChart>
+  );
+}
+```
+
+## CSS in DOM Components
+
+CSS imports must be in the DOM component file since they run in isolated context:
+
+```tsx
+// components/styled-component.tsx
+"use dom";
+
+import "@/styles.css"; // CSS file in same directory
+
+export default function StyledComponent({
+  dom,
+}: {
+  dom: import("expo/dom").DOMProps;
+}) {
+  return (
+    <div className="container">
+      <h1 className="title">Styled Content</h1>
+    </div>
+  );
+}
+```
+
+Or use inline styles / CSS-in-JS:
+
+```tsx
+"use dom";
+
+const styles = {
+  container: {
+    padding: 20,
+    backgroundColor: "#f0f0f0",
+  },
+  title: {
+    fontSize: 24,
+    color: "#333",
+  },
+};
+
+export default function StyledComponent({
+  dom,
+}: {
+  dom: import("expo/dom").DOMProps;
+}) {
+  return (
+    <div style={styles.container}>
+      <h1 style={styles.title}>Styled Content</h1>
+    </div>
+  );
+}
+```
+
+## Expo Router in DOM Components
+
+The expo-router `<Link />` component and router API work inside DOM components:
+
+```tsx
+"use dom";
+
+import { Link, useRouter } from "expo-router";
+
+export default function Navigation({
+  dom,
+}: {
+  dom: import("expo/dom").DOMProps;
+}) {
+  const router = useRouter();
+
+  return (
+    <nav>
+      <Link href="/about">About</Link>
+      <button onClick={() => router.push("/settings")}>Settings</button>
+    </nav>
+  );
+}
+```
+
+### Router APIs That Require Props
+
+These hooks don't work directly in DOM components because they need synchronous access to native routing state:
+
+- `useLocalSearchParams()`
+- `useGlobalSearchParams()`
+- `usePathname()`
+- `useSegments()`
+- `useRootNavigation()`
+- `useRootNavigationState()`
+
+**Solution:** Read these values in the native parent and pass as props:
+
+```tsx
+// app/[id].tsx (native)
+import { useLocalSearchParams, usePathname } from "expo-router";
+import DOMComponent from "@/components/dom-component";
+
+export default function Screen() {
+  const { id } = useLocalSearchParams();
+  const pathname = usePathname();
+
+  return <DOMComponent id={id as string} pathname={pathname} />;
+}
+```
+
+```tsx
+// components/dom-component.tsx
+"use dom";
+
+interface Props {
+  id: string;
+  pathname: string;
+  dom?: import("expo/dom").DOMProps;
+}
+
+export default function DOMComponent({ id, pathname }: Props) {
+  return (
+    <div>
+      <p>Current ID: {id}</p>
+      <p>Current Path: {pathname}</p>
+    </div>
+  );
+}
+```
+
+## Detecting DOM Environment
+
+Check if code is running in a DOM component:
+
+```tsx
+"use dom";
+
+import { IS_DOM } from "expo/dom";
+
+export default function Component({
+  dom,
+}: {
+  dom?: import("expo/dom").DOMProps;
+}) {
+  return <div>{IS_DOM ? "Running in DOM component" : "Running natively"}</div>;
+}
+```
+
+## Assets
+
+Prefer requiring assets instead of using the public directory:
+
+```tsx
+"use dom";
+
+// Good - bundled with the component
+const logo = require("../assets/logo.png");
+
+export default function Component({
+  dom,
+}: {
+  dom: import("expo/dom").DOMProps;
+}) {
+  return <img src={logo} alt="Logo" />;
+}
+```
+
+## Usage from Native Components
+
+Import and use DOM components like regular components:
+
+```tsx
+// app/index.tsx
+import { View, Text } from "react-native";
+import WebChart from "@/components/web-chart";
+import CodeBlock from "@/components/code-block";
+
+export default function HomeScreen() {
+  return (
+    <View style={{ flex: 1 }}>
+      <Text>Native content above</Text>
+
+      <WebChart data={[10, 20, 30, 40, 50]} dom={{ style: { height: 300 } }} />
+
+      <CodeBlock
+        code="const x = 1;"
+        language="javascript"
+        dom={{ scrollEnabled: true }}
+      />
+
+      <Text>Native content below</Text>
+    </View>
+  );
+}
+```
+
+## Platform Behavior
+
+| Platform | Behavior                            |
+| -------- | ----------------------------------- |
+| iOS      | Rendered in WKWebView               |
+| Android  | Rendered in WebView                 |
+| Web      | Rendered as-is (no webview wrapper) |
+
+On web, the `dom` prop is ignored since no webview is needed.
+
+## Tips
+
+- DOM components hot reload during development
+- Keep DOM components focused — don't put entire screens in webviews
+- Use native components for navigation chrome, DOM components for specialized content
+- Test on all platforms — web rendering may differ slightly from native webviews
+- Large DOM components may impact performance — profile if needed
+- The webview has its own JavaScript context — cannot directly share state with native

package/dist/global-skills/expo-dom/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Expo DOM Components"
+  short_description: "Use Expo DOM components to run web React code in native webviews and unchanged on web"
+  default_prompt: "Use $expo-dom to migrate web components into Expo via 'use dom', configure DOM props, expose native actions safely, use web-only libraries, and keep DOM components separate from native routes."

package/dist/global-skills/expo-examples/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: expo-examples
+description: Framework (OSS). Expo's official example projects - the expo/examples repo of ~70 `with-*` integrations (Stripe, Clerk, Supabase, OpenAI, maps, Reanimated, SQLite, Skia, NativeWind, and more). Use when integrating a third-party library or service into an existing Expo app and you want the canonical, version-matched pattern to adapt, or when scaffolding a new project from one with `npx create-expo --example`.
+allowed-tools: "Read,Bash(gh api:*),Bash(git clone:*),Bash(npx create-expo:*),Bash(npx degit:*),Bash(bun create:*)"
+version: 1.0.0
+license: MIT
+---
+
+# Expo Examples
+
+[expo/examples](https://github.com/expo/examples) is Expo's official library of ~70 **integration examples** — directories named `with-<library>` (e.g. `with-stripe`, `with-maps`), each built around **one** library or service. These are not full apps: they're **managed** projects (no `ios/`/`android/` dirs — native setup is via config plugins), and the typical one is a **single screen of ~100–200 lines**. Mine them for the canonical integration *pattern* — the dependency set, `app.json` config plugins, and minimal wiring Expo maintains against the current SDK — and adapt that into the user's app. Don't expect to lift an application architecture from them.
+
+Reach for an example before hand-rolling an integration. (Kinds — full-stack, showcases, starters — are noted in `./references/catalog.md`.)
+
+## Two modes
+
+1. **Inspiration / adapt** (most common) — the user already has a project. Find the matching example, read its key files, and apply the *pattern* to their code.
+2. **Scaffold** — greenfield. Start a fresh project directly from the example.
+
+## Workflow
+
+### 1. Find the right example
+
+Map the user's need to an example name (e.g. payments → `with-stripe`, auth → `with-clerk`). `./references/catalog.md` is a categorized snapshot for fast triage — but it drifts, so confirm against the live list:
+
+```bash
+# Live example names:
+gh api repos/expo/examples/contents --jq '.[] | select(.type=="dir" and (.name|startswith(".")|not)) | .name'
+# Aliases (renamed) + deprecated (dead/moved) examples — check before recommending:
+gh api repos/expo/examples/contents/meta.json --jq '.content' | base64 -d
+```
+
+`meta.json` is the source of truth for what's renamed or dead (deprecated examples are removed from the repo tree but still listed here, each with a `message`). If an example is in its `deprecated` map, don't recommend it — follow the `message` to the modern path. If it's in `aliases`, use the `destination`.
+
+### 2a. Inspiration mode — study without touching the user's project
+
+The common case: the user already has an app and wants to see how Expo does something. Read the example as **reference** and apply the patterns by hand — never scaffold an example on top of their project.
+
+**First, list the whole example in one call.** Integration code is often nested (e.g. Stripe's server routes live in `app/api/`), so a one-level listing misses the important files:
+
+```bash
+gh api 'repos/expo/examples/git/trees/master?recursive=1' \
+  --jq '.tree[].path | select(startswith("with-stripe/"))'
+```
+
+**Then read the high-signal files first:** `README.md` (setup) → `package.json` (deps) → `app.json` (config plugins / permissions) → the integration code the manifest revealed → `.env` (required secrets). Per file:
+
+```bash
+gh api repos/expo/examples/contents/with-stripe/utils/stripe-server.ts --jq '.content' | base64 -d
+# No gh? Raw URL (branch is master):
+curl -s https://raw.githubusercontent.com/expo/examples/master/with-stripe/utils/stripe-server.ts
+```
+
+**Reading more than a couple of files?** Many integrations are spread across server routes, a client provider, and config (Stripe is). Skip the per-file calls — pull the whole example into a **throwaway/gitignored dir (not the user's project)** and read it freely with Grep/Read, then apply by hand:
+
+```bash
+npx degit expo/examples/with-stripe /tmp/expo-ref/with-stripe   # clean copy, no git history
+# fallback without degit (sparse-checkout, no full ~64 MB clone):
+git clone --depth 1 --filter=blob:none --sparse https://github.com/expo/examples.git /tmp/expo-ref/examples \
+  && (cd /tmp/expo-ref/examples && git sparse-checkout set with-stripe)
+```
+
+Read from there with Grep/Read; delete the scratch dir when done.
+
+### 2b. Scaffold mode — new project from an example
+
+```bash
+npx create-expo --example with-stripe   # short form:  npx create-expo -e with-stripe
+bun create expo --example with-stripe    # with bun
+```
+
+### 3. Adapt into the user's app — non-destructively (critical)
+
+When the user already has an app, **add only what the example introduces; never overwrite their setup.**
+
+- **Version-align — don't copy pinned versions.** Examples track the **latest** SDK, so their `package.json` pins won't match an older project. Add only the *missing* deps with `npx expo install <pkg>` (it resolves SDK-correct versions) instead of copying exact versions.
+- **Merge config, don't replace it.** Add only the `app.json`/`app.config.*` plugins and permissions the example introduces that the user lacks — keep their existing config block intact.
+- **Port the integration code.**
+- **Recreate env vars** from the example's `.env` shape — it holds placeholders, never working secrets.
+
+**Done when** the integration code is ported and every dependency, config plugin, permission, and env var it needs is accounted for in the user's app — not when it merely *looks* wired up.
+
+## Gotchas
+
+- **Default branch is `master`,** not `main` (matters for raw URLs and sparse checkout).
+- **Single-click deploy.** Every example has a launch URL: `https://launch.expo.dev/?github=https://github.com/expo/examples/tree/master/<example>`.
+
+## Related skills
+
+- Tailwind / NativeWind styling → `expo-tailwind-setup`
+- Native UI components (@expo/ui package) → `expo-ui`
+- Styling and native-feeling screens → `expo-native-ui`
+- Navigation and routing → `expo-router`
+- Authoring a native module → `expo-module`
+- Upgrade the SDK before adopting a latest-SDK example → `expo-upgrade`
+
+## References
+
+- `./references/catalog.md` — categorized snapshot of the example library for fast triage.

package/dist/global-skills/expo-examples/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Expo Examples"
+  short_description: "Adapt or scaffold from the expo/examples repo of with-* integrations (Stripe, Clerk, Supabase, maps, SQLite, and more)"
+  default_prompt: "Use $expo-examples when integrating a third-party library or service into an Expo app to find the canonical with-* example to adapt, or to scaffold a new project with npx create-expo --example."

package/dist/global-skills/expo-examples/references/catalog.md

@@ -0,0 +1,105 @@
+# Example catalog (snapshot)
+
+A categorized view of [expo/examples](https://github.com/expo/examples) for fast triage. Each entry is a **single-concern integration demo** (one library/service, managed project, usually one screen) — not a full app. This snapshot drifts — the **live repo is the source of truth**. Confirm the exact name against `gh api repos/expo/examples/contents` and check `meta.json` for aliases/deprecations (see SKILL.md step 1) before recommending or scaffolding.
+
+Use any name with `npx create-expo --example <name>` (scaffold) or inspect it via `gh api repos/expo/examples/contents/<name>/<file>`.
+
+Most are single-screen integrations; a few differ:
+
+- **Full-stack** (include Expo Router `+api` routes — a backend too): `with-stripe`, `with-clerk`, `with-better-auth`, `with-openai`, `with-router-ai`, `with-graphql`, `with-s3`, `with-satori`.
+- **Larger showcases:** `with-shadcn`, `with-router-tv`, `with-router-menus`, `with-react-navigation`, `with-webgpu`.
+- **Starters (not integrations):** `blank`, `stickersmash`.
+
+## Auth & identity
+- `with-clerk` — Clerk authentication
+- `with-auth0` — Auth0 login
+- `with-better-auth` — Better Auth
+- `with-magic` — Magic passwordless auth
+- `with-facebook-auth` — Facebook login
+- `with-firebase-saml-login` — Firebase SAML SSO
+
+## Payments
+- `with-stripe` — Stripe payments (native + web)
+
+## Backend, data & storage
+- `with-convex` — Convex realtime backend
+- `with-legend-state-supabase` — Supabase + Legend-State sync
+- `with-firebase-storage-upload` — Firebase Storage uploads
+- `with-aws-storage-upload`, `with-s3` — AWS / S3 file uploads
+- `with-apollo`, `with-graphql` — GraphQL clients
+- `with-formdata-image-upload` — multipart image upload
+
+## Local database & state
+- `with-sqlite` — expo-sqlite
+- `with-libsql` — libSQL / Turso
+- `with-tinybase` — TinyBase local-first store
+- `with-zustand` — Zustand state management
+
+## Navigation & routing
+- `with-router` — Expo Router basics
+- `with-react-navigation` — React Navigation (stacks + tabs)
+- `with-drawer-navigation` — drawer navigator
+- `with-router-menus` — native context menus with Router
+- `with-router-uniwind` — Router + Uniwind styling
+- `with-router-ai` — Router + AI chat UI
+- `with-router-tv` — Router on TV
+- `with-react-router` — React Router (web)
+
+## Styling & UI
+- `with-tailwindcss` — Tailwind / NativeWind (see also `expo-tailwind-setup` skill)
+- `with-styled-components` — styled-components
+- `with-shadcn` — shadcn-style components
+- `with-moti` — Moti animations
+- `with-custom-font` — custom fonts
+- `with-svg` — react-native-svg
+- `with-icons` — icon sets
+- `with-splash-screen` — custom splash screen
+- `with-video-background` — full-screen video background
+
+## Animation & graphics
+- `with-reanimated` — Reanimated
+- `with-skia` — React Native Skia 2D graphics
+- `with-three`, `with-react-three-fiber` — three.js / R3F 3D
+- `with-webgpu` — WebGPU
+- `with-processing` — Processing-style sketches
+- `with-react-flow` — node/flow diagrams
+- `with-victory-native` — charts
+
+## AI & ML
+- `with-openai` — OpenAI API
+- `with-router-ai` — AI chat app with Expo Router
+- `with-google-vision` — Google Cloud Vision
+- `with-tfjs-camera` — TensorFlow.js on the camera
+
+## Media & device
+- `with-camera` — expo-camera
+- `with-maps` — react-native-maps
+- `with-webrtc` — WebRTC
+- `with-pdf` — render / view PDFs
+
+## Web & rendering
+- `with-nextjs` — Next.js + Expo
+- `with-rsc` — React Server Components
+- `with-react-strict-dom` — React Strict DOM
+- `with-react-compiler` — React Compiler
+- `with-html` — render raw HTML
+- `with-satori` — OG image generation with Satori
+- `with-workbox` — service worker / PWA
+- `with-webbrowser-redirect` — expo-web-browser auth redirect
+
+## Platform: TV, widgets
+- `with-tv` — Apple TV / Android TV
+- `with-widgets` — iOS / Android home-screen widgets
+
+## Tooling, testing & monorepo
+- `with-typescript` — TypeScript baseline
+- `with-yarn-workspaces` — Yarn monorepo
+- `with-storybook` — Storybook
+- `with-maestro` — Maestro E2E tests
+- `with-sentry` — Sentry error monitoring
+- `with-socket-io` — Socket.IO realtime
+- `with-github-remote-build-cache-provider` — remote build cache on GitHub
+
+## Starters
+- `blank` — minimal app
+- `stickersmash` — the tutorial app