@codeyam/codeyam-cli 0.1.0-staging.b8b17a5 → 0.1.0-staging.ba3f279

package/codeyam-cli/templates/expo-react-native/MOBILE_SETUP.md

@@ -29,14 +29,13 @@ npm start
 
 ```
 app/                    # Expo Router file-based routes
-  _layout.tsx           # Root layout (status bar, navigation)
-  (tabs)/               # Tab-based navigation group
-    _layout.tsx         # Tab bar configuration
-    index.tsx           # Home tab
-    settings.tsx        # Settings tab
+  _layout.tsx           # Root layout (SafeAreaProvider, StatusBar)
+  index.tsx             # Home screen (single entry point)
 components/             # Reusable components
 lib/
+  theme.ts              # Design tokens (colors, spacing, typography)
   storage.ts            # AsyncStorage wrapper for persistent data
+__tests__/              # Test files (keep outside app/ — Expo Router treats all app/ files as routes)
 ```
 
 ## Key Patterns
@@ -78,6 +77,206 @@ Use Tailwind classes on React Native components:
 </View>
 ```
 
+## CodeYam Scenario Data
+
+### AsyncStorage Seeding
+
+AsyncStorage uses `localStorage` on web, so CodeYam's existing localStorage injection works automatically. Use the `localStorage` field in scenario JSON to pre-populate storage:
+
+```json
+{
+  "name": "With Saved Items",
+  "url": "/",
+  "dimensions": ["iPhone 16"],
+  "localStorage": {
+    "items": "[{\"id\":\"1\",\"title\":\"Buy groceries\",\"done\":false},{\"id\":\"2\",\"title\":\"Walk the dog\",\"done\":true}]"
+  }
+}
+```
+
+Values must be JSON strings (matching how AsyncStorage stores them). Your `storage.get()` calls will read this data normally.
+
+### API Mocking
+
+For apps that fetch from APIs, use relative URLs so CodeYam's proxy can intercept and mock them:
+
+```tsx
+// Use relative URLs — these go through the CodeYam proxy
+const response = await fetch('/api/items');
+```
+
+Then provide mock routes in your scenario data:
+
+```json
+{
+  "name": "With API Data",
+  "url": "/",
+  "dimensions": ["iPhone 16"],
+  "routes": {
+    "/api/items": {
+      "body": [{ "id": 1, "title": "First item" }],
+      "status": 200
+    }
+  }
+}
+```
+
+### Device Presets
+
+Mobile projects default to these screen sizes:
+
+| Preset            | Width | Height |
+| ----------------- | ----- | ------ |
+| iPhone 16         | 393   | 852    |
+| iPhone 16 Pro Max | 430   | 932    |
+| iPhone SE         | 375   | 667    |
+| Pixel 8           | 412   | 915    |
+| iPad mini         | 744   | 1133   |
+
+## Design Tokens (lib/theme.ts)
+
+All design tokens live in `lib/theme.ts` — this is the **single source of truth** for colors, spacing, typography, and border radius. Import and use in every component:
+
+```tsx
+import { theme } from '@/lib/theme';
+
+<View
+  style={{ backgroundColor: theme.colors.bgBase, padding: theme.spacing.lg }}
+>
+  <Text
+    style={{ fontSize: theme.fontSize.lg, color: theme.colors.textPrimary }}
+  >
+    Hello
+  </Text>
+</View>;
+```
+
+**Do NOT:**
+
+- Use CSS custom properties (`var(--token)`) — they don't work in React Native
+- Hardcode color strings or pixel values in components
+- Create a separate `globals.css` token system — `lib/theme.ts` is the only source
+
+When a design system is selected, populate `lib/theme.ts` with its tokens.
+
+## Testing
+
+Tests use Jest with the `jest-expo` preset. Run with:
+
+```bash
+npx jest                          # Run all tests
+npx jest app/hooks/useCounter.ts  # Run specific test file
+```
+
+The Jest config is in `package.json`. The `transformIgnorePatterns` is pre-configured to handle Expo and React Native module transforms — you should not need to modify it.
+
+## Building for a Real iOS Device
+
+### Prerequisites
+
+- **Xcode 16.x** (Xcode 16.4 or later recommended)
+- **Apple Developer account** (free is fine for personal devices)
+- Device connected via USB or on the same Wi-Fi network
+
+### Steps
+
+1. Generate the native iOS project:
+
+```bash
+npx expo prebuild --clean
+```
+
+2. Add Swift 5 enforcement to the generated Podfile. Open `ios/Podfile` and add this inside the `post_install` block, after `react_native_post_install(...)`:
+
+```ruby
+    # Fix Swift 6.1 (Xcode 16.4) strict concurrency errors
+    installer.pods_project.targets.each do |target|
+      target.build_configurations.each do |config|
+        config.build_settings['SWIFT_VERSION'] = '5.0'
+      end
+    end
+```
+
+3. Reinstall pods with the fix:
+
+```bash
+cd ios && pod install && cd ..
+```
+
+4. Build and run on your device:
+
+```bash
+npx expo run:ios --device
+```
+
+### Troubleshooting
+
+- **"invalid code signature" / "profile has not been explicitly trusted"**: Your iPhone doesn't trust the developer profile yet. On your iPhone: **Settings → General → VPN & Device Management** → tap your Apple ID → **Trust**. Then relaunch the app.
+- **"No script URL provided"**: Metro bundler isn't running or the device can't reach it. Start Metro with `npx expo start` in a separate terminal, then relaunch the app. Your phone and Mac must be on the same Wi-Fi network.
+- **"Missing factory in ExpoAppDelegate"** crash: The native project is stale. Run `npx expo prebuild --clean` to regenerate it.
+- **"ambiguous implicit access level for import"** error: The `patch-package` fix wasn't applied. Run `npm install` to reapply, then `cd ios && pod install`.
+
+### Notes
+
+- The `ios/` and `android/` directories are gitignored — they're generated by `expo prebuild` and shouldn't be committed.
+- The `patches/` directory IS committed — it contains a fix for Xcode 16.4 Swift compatibility that auto-applies on `npm install`.
+
+## Web vs Native Differences
+
+The CodeYam editor previews your app via **Expo Web** (react-native-web in a browser). Some differences from native iOS/Android devices are expected:
+
+| Aspect           | Web Preview                                            | Native Device                                           |
+| ---------------- | ------------------------------------------------------ | ------------------------------------------------------- |
+| **Fonts**        | System fonts, may differ in weight/metrics/line-height | Loaded custom fonts (if added via expo-font)            |
+| **SafeAreaView** | No effect (no notch in browser)                        | Applies real safe area insets for notch, home indicator |
+| **Platform.OS**  | Returns `'web'`                                        | Returns `'ios'` or `'android'`                          |
+| **Shadows**      | Uses CSS `box-shadow` (works well)                     | Uses RN shadow props (iOS) or `elevation` (Android)     |
+| **Gestures**     | Mouse drag events                                      | Touch/swipe with inertia                                |
+| **StatusBar**    | No visible effect                                      | Controls device status bar appearance                   |
+| **Haptics**      | No-op                                                  | Real haptic feedback via `expo-haptics`                 |
+| **Pressable**    | `backgroundColor`/`borderStyle` work on Pressable      | Must use View wrapper (see below)                       |
+
+### Pressable Styling on Native
+
+`<Pressable>` with `backgroundColor`, `borderRadius`, or `borderStyle: 'dashed'` renders correctly in the web preview but **fails silently on native devices** — the background/border simply won't appear.
+
+**Fix:** Put visual styles on a wrapping `<View>` and use `onPressIn`/`onPressOut` for press feedback:
+
+```tsx
+const [pressed, setPressed] = useState(false);
+
+<View
+  style={{
+    backgroundColor: theme.colors.bgInverse,
+    borderRadius: 60,
+    overflow: 'hidden',
+  }}
+>
+  <Pressable
+    onPress={onPress}
+    onPressIn={() => setPressed(true)}
+    onPressOut={() => setPressed(false)}
+    style={{
+      opacity: pressed ? 0.8 : 1,
+      alignItems: 'center',
+      padding: theme.spacing.lg,
+    }}
+  >
+    <Text style={{ color: theme.colors.accent }}>+</Text>
+  </Pressable>
+</View>;
+```
+
+For dashed borders, put `borderStyle`, `borderWidth`, and `borderColor` on the outer `<View>`, not on `<Pressable>`.
+
+**The web preview is for layout and data verification.** Test final visual polish on a real device or simulator:
+
+```bash
+npm run ios       # iOS Simulator
+npm run android   # Android Emulator
+npm start         # Pick platform from Expo menu
+```
+
 ## Building for Production
 
 ```bash

package/codeyam-cli/templates/expo-react-native/app/_layout.tsx

@@ -1,12 +1,15 @@
 import '../global.css';
 import { Stack } from 'expo-router';
 import { StatusBar } from 'expo-status-bar';
+import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
 
 export default function RootLayout() {
   return (
-    <>
-      <Stack screenOptions={{ headerShown: false }} />
+    <SafeAreaProvider>
+      <SafeAreaView style={{ flex: 1 }}>
+        <Stack screenOptions={{ headerShown: false }} />
+      </SafeAreaView>
       <StatusBar style="auto" />
-    </>
+    </SafeAreaProvider>
   );
 }

package/codeyam-cli/templates/expo-react-native/app/index.tsx

@@ -0,0 +1,36 @@
+import { View, Text } from 'react-native';
+import { theme } from '@/lib/theme';
+
+export default function HomeScreen() {
+  return (
+    <View
+      style={{
+        flex: 1,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: theme.colors.bgBase,
+        padding: theme.spacing.lg,
+      }}
+    >
+      <Text
+        style={{
+          fontSize: theme.fontSize['2xl'],
+          fontWeight: theme.fontWeight.bold,
+          color: theme.colors.textPrimary,
+          marginBottom: theme.spacing.sm,
+        }}
+      >
+        Welcome
+      </Text>
+      <Text
+        style={{
+          fontSize: theme.fontSize.base,
+          color: theme.colors.textSecondary,
+          textAlign: 'center',
+        }}
+      >
+        Your Expo app is ready. Start building!
+      </Text>
+    </View>
+  );
+}

package/codeyam-cli/templates/expo-react-native/app.json

@@ -4,6 +4,7 @@
     "slug": "codeyam-expo-app",
     "version": "1.0.0",
     "scheme": "codeyam-expo-app",
+    "icon": "./assets/icon.png",
     "platforms": ["ios", "android", "web"],
     "web": {
       "bundler": "metro",
@@ -13,6 +14,16 @@
     "plugins": ["expo-router"],
     "experiments": {
       "typedRoutes": true
+    },
+    "ios": {
+      "bundleIdentifier": "com.codeyam.expo-app"
+    },
+    "android": {
+      "adaptiveIcon": {
+        "foregroundImage": "./assets/adaptive-icon.png",
+        "backgroundColor": "#f8fafc"
+      },
+      "package": "com.codeyam.expoapp"
     }
   }
 }

package/codeyam-cli/templates/expo-react-native/babel.config.js

@@ -5,5 +5,6 @@ module.exports = function (api) {
       ['babel-preset-expo', { jsxImportSource: 'nativewind' }],
       'nativewind/babel',
     ],
+    plugins: ['react-native-reanimated/plugin'],
   };
 };

package/codeyam-cli/templates/expo-react-native/gitignore

@@ -2,6 +2,8 @@ node_modules/
 .expo/
 dist/
 web-build/
+ios/
+android/
 *.jks
 *.p8
 *.p12

package/codeyam-cli/templates/expo-react-native/global.css

@@ -1,3 +1,10 @@
+/* NativeWind / Tailwind utility layer.
+ *
+ * Design tokens are defined in lib/theme.ts — that is the single source
+ * of truth for colors, spacing, typography, and border radius.
+ * Do NOT define CSS custom properties here for design tokens.
+ * React Native components cannot read CSS variables.
+ */
 @tailwind base;
 @tailwind components;
 @tailwind utilities;

package/codeyam-cli/templates/expo-react-native/lib/theme.ts

@@ -0,0 +1,73 @@
+/**
+ * Design tokens — single source of truth for all styling.
+ *
+ * When a design system is selected (via .codeyam/design-system.md),
+ * populate these values from the design system's color palette,
+ * typography scale, and spacing rhythm.
+ *
+ * Import in every component:
+ *   import { theme } from '@/lib/theme';
+ *   <View style={{ backgroundColor: theme.colors.bgBase }}>
+ *
+ * Do NOT use CSS custom properties (var(--token)) in React Native.
+ * Do NOT hardcode color strings or pixel values in components.
+ */
+
+export const theme = {
+  colors: {
+    bgBase: '#f8fafc',
+    bgSurface: '#ffffff',
+    bgSurfaceRaised: '#ffffff',
+    bgInverse: '#1e293b',
+
+    textPrimary: '#0f172a',
+    textSecondary: '#475569',
+    textMuted: '#94a3b8',
+
+    border: '#e2e8f0',
+
+    accent: '#005C75',
+    accentLight: '#e0f2fe',
+  },
+
+  spacing: {
+    xs: 4,
+    sm: 8,
+    md: 12,
+    lg: 16,
+    xl: 24,
+    '2xl': 32,
+    '3xl': 48,
+  },
+
+  fontSize: {
+    xs: 12,
+    sm: 14,
+    base: 16,
+    lg: 18,
+    xl: 20,
+    '2xl': 24,
+    '3xl': 30,
+    '4xl': 36,
+  },
+
+  fontWeight: {
+    normal: '400' as const,
+    medium: '500' as const,
+    semibold: '600' as const,
+    bold: '700' as const,
+  },
+
+  fontFamily: {
+    sans: 'System',
+    mono: 'monospace',
+  },
+
+  borderRadius: {
+    sm: 4,
+    md: 8,
+    lg: 12,
+    xl: 16,
+    full: 9999,
+  },
+};

package/codeyam-cli/templates/expo-react-native/package.json

@@ -7,32 +7,48 @@
     "setup": "npm install",
     "dev": "expo start --web",
     "start": "expo start",
-    "android": "expo start --android",
-    "ios": "expo start --ios",
-    "build:web": "expo export --platform web"
+    "android": "expo run:android",
+    "ios": "expo run:ios",
+    "build:web": "expo export --platform web",
+    "test": "jest",
+    "postinstall": "patch-package"
   },
   "dependencies": {
-    "expo": "~55.0.5",
-    "expo-router": "~55.0.4",
-    "expo-status-bar": "~55.0.4",
-    "expo-linking": "~55.0.7",
-    "expo-constants": "~55.0.7",
-    "react": "19.2.0",
-    "react-dom": "19.2.0",
-    "react-native": "0.83.2",
+    "expo": "~54.0.0",
+    "expo-router": "~6.0.23",
+    "expo-status-bar": "~3.0.9",
+    "expo-linking": "~8.0.11",
+    "expo-constants": "~18.0.13",
+    "expo-font": "~14.0.11",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-native": "0.81.5",
     "react-native-web": "^0.21.0",
     "react-native-safe-area-context": "~5.6.2",
-    "react-native-screens": "~4.23.0",
+    "react-native-screens": "~4.16.0",
+    "react-native-reanimated": "^4.3.0",
+    "react-native-worklets": "^0.8.1",
+    "react-refresh": "^0.18.0",
     "@react-navigation/native": "^7.1.33",
     "@expo/vector-icons": "^15.0.2",
     "@react-native-async-storage/async-storage": "2.2.0",
     "nativewind": "^4.2.2",
     "tailwindcss": "^3.4.19",
-    "react-native-reanimated": "4.2.1"
+    "patch-package": "^8.0.0"
   },
   "devDependencies": {
-    "@types/react": "~19.2.2",
-    "babel-preset-expo": "^55.0.10",
-    "typescript": "~5.9.2"
+    "@types/react": "~19.1.10",
+    "babel-preset-expo": "~54.0.10",
+    "sharp": "^0.33.0",
+    "typescript": "~5.9.2",
+    "jest": "^29.7.0",
+    "jest-expo": "~54.0.17",
+    "@testing-library/react-native": "^13.2.0"
+  },
+  "jest": {
+    "preset": "jest-expo",
+    "transformIgnorePatterns": [
+      "node_modules/(?!((jest-)?react-native|@react-native(-community)?)|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|react-navigation|@react-navigation/.*|nativewind|react-native-reanimated|react-native-worklets)"
+    ]
   }
 }

package/codeyam-cli/templates/expo-react-native/patches/expo-modules-autolinking+3.0.24.patch

@@ -0,0 +1,29 @@
+diff --git a/node_modules/expo-modules-autolinking/build/platforms/apple/apple.js b/node_modules/expo-modules-autolinking/build/platforms/apple/apple.js
+index 47487c0..58a6069 100644
+--- a/node_modules/expo-modules-autolinking/build/platforms/apple/apple.js
++++ b/node_modules/expo-modules-autolinking/build/platforms/apple/apple.js
+@@ -113,7 +113,7 @@ async function generatePackageListFileContentAsync(modules, className, entitleme
+  * but only these that are written in Swift and use the new API for creating Expo modules.
+  */
+
+-import ExpoModulesCore
++public import ExpoModulesCore
+ ${generateCommonImportList(swiftModules)}
+ ${generateDebugOnlyImportList(debugOnlySwiftModules)}
+ @objc(${className})
+@@ -137,13 +137,13 @@ ${generateReactDelegateHandlers(reactDelegateHandlerModules, debugOnlyReactDeleg
+ `;
+ }
+ function generateCommonImportList(swiftModules) {
+-    return swiftModules.map((moduleName) => `import ${moduleName}`).join('\n');
++    return swiftModules.map((moduleName) => `public import ${moduleName}`).join('\n');
+ }
+ function generateDebugOnlyImportList(swiftModules) {
+     if (!swiftModules.length) {
+         return '';
+     }
+-    return (wrapInDebugConfigurationCheck(0, swiftModules.map((moduleName) => `import ${moduleName}`).join('\n')) + '\n');
++    return (wrapInDebugConfigurationCheck(0, swiftModules.map((moduleName) => `public import ${moduleName}`).join('\n')) + '\n');
+ }
+ function generateModuleClasses(classNames, debugOnlyClassName) {
+     const commonClassNames = formatArrayOfClassNames(classNames);

package/codeyam-cli/templates/isolation-route/expo-router.tsx.template

@@ -0,0 +1,54 @@
+/**
+ * CodeYam Isolation Route — Expo Router
+ *
+ * Place this file at: app/isolated-components/ComponentName.tsx
+ * URL: /isolated-components/ComponentName?s=ScenarioName
+ *
+ * This route renders a single component with scenario-specific props,
+ * enabling isolated component preview and screenshot capture.
+ */
+
+import { useLocalSearchParams } from 'expo-router';
+import { View, Text } from 'react-native';
+import { theme } from '@/lib/theme';
+// import YourComponent from '@/app/components/YourComponent';
+
+// Define scenarios: map scenario names to component props
+const scenarios: Record<string, Record<string, unknown>> = {
+  Default: {
+    // props for the default scenario
+  },
+  // Add more scenarios here
+};
+
+export default function ComponentIsolation() {
+  const { s } = useLocalSearchParams<{ s: string }>();
+  const scenarioName = s || 'Default';
+  const props = scenarios[scenarioName];
+
+  if (!props) {
+    return (
+      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+        <Text style={{ fontFamily: theme.fontFamily.mono, color: '#e74c3c' }}>
+          Unknown scenario: {scenarioName}
+        </Text>
+      </View>
+    );
+  }
+
+  return (
+    <View
+      style={{
+        flex: 1,
+        justifyContent: 'center',
+        alignItems: 'center',
+        backgroundColor: theme.colors.bgBase,
+      }}
+    >
+      <View nativeID="codeyam-capture" style={{ maxWidth: 384 }}>
+        {/* <YourComponent {...props} /> */}
+        <Text>Replace with your component</Text>
+      </View>
+    </View>
+  );
+}

package/codeyam-cli/templates/nextjs-prisma-sqlite/seed-adapter.ts

@@ -37,49 +37,62 @@ async function main() {
   const data = JSON.parse(raw);
   const seed = data.seed || data;
 
-  console.log(`Seeding tables: ${Object.keys(seed).join(', ')}`);
+  // Discover ALL models from the Prisma schema — not just the tables in the seed data.
+  // This ensures FK-dependent tables (e.g., Passenger → Flight) are cleared even when
+  // the seed only contains the parent table's data.
+  const allModels = Prisma.dmmf.datamodel.models.map(
+    (m) => m.name.charAt(0).toLowerCase() + m.name.slice(1),
+  );
 
-  // Wipe all tables in reverse order (to respect foreign keys)
-  const tableNames = Object.keys(seed);
-  for (const table of [...tableNames].reverse()) {
-    try {
-      await (prisma as any)[table].deleteMany();
-      console.log(`  Cleared ${table}`);
-    } catch (err) {
-      console.warn(
-        `  Could not clear ${table}: ${err instanceof Error ? err.message : err}`,
-      );
+  // Run everything in a single transaction for atomicity and speed.
+  // SQLite auto-commits each statement by default — wrapping in a transaction
+  // avoids per-statement fsync and is significantly faster for bulk operations.
+  await prisma.$transaction(async (tx) => {
+    // Disable foreign key checks during wipe+insert — allows deleting in any
+    // order and avoids FK constraint errors during the brief window between
+    // clearing parent and child tables.
+    await tx.$executeRawUnsafe('PRAGMA foreign_keys = OFF');
+
+    // Wipe ALL tables in the schema (not just seeded ones)
+    for (const table of [...allModels].reverse()) {
+      try {
+        await (tx as any)[table].deleteMany();
+      } catch {
+        // Table may not exist in current schema — skip
+      }
     }
-  }
 
-  // Reset auto-increment counters so IDs start from 1 after each re-seed.
-  // Without this, SQLite IDs keep climbing (1, 2, ... then 9, 10, ...)
-  // across scenario switches, causing hardcoded URLs like /drinks/1 to 404.
-  for (const table of tableNames) {
+    // Batch-reset auto-increment counters for ALL tables.
+    // Without this, SQLite IDs keep climbing across scenario switches,
+    // causing hardcoded URLs like /drinks/1 to 404.
+    const seqNames = allModels
+      .flatMap((t) => [`'${t}'`, `'${t.charAt(0).toUpperCase() + t.slice(1)}'`])
+      .join(', ');
     try {
-      // Prisma uses PascalCase model names; sqlite_sequence stores the actual table name.
-      // Try both the seed key (which matches the Prisma model) and common casings.
-      await prisma.$executeRawUnsafe(
-        `DELETE FROM sqlite_sequence WHERE name = '${table}' OR name = '${table.charAt(0).toUpperCase() + table.slice(1)}'`,
+      await tx.$executeRawUnsafe(
+        `DELETE FROM sqlite_sequence WHERE name IN (${seqNames})`,
       );
     } catch {
-      // sqlite_sequence may not exist if no autoincrement columns — safe to ignore
+      // sqlite_sequence may not exist — safe to ignore
     }
-  }
 
-  // Insert seed data
-  for (const [table, rows] of Object.entries(seed)) {
-    if (!Array.isArray(rows) || rows.length === 0) continue;
-    try {
-      await (prisma as any)[table].createMany({ data: rows });
-      console.log(`  Seeded ${rows.length} rows into ${table}`);
-    } catch (err) {
-      console.error(
-        `  Failed to seed ${table}: ${err instanceof Error ? err.message : err}`,
-      );
-      process.exit(1);
+    // Insert seed data
+    for (const [table, rows] of Object.entries(seed)) {
+      if (!Array.isArray(rows) || rows.length === 0) continue;
+      try {
+        await (tx as any)[table].createMany({ data: rows });
+        console.log(`  Seeded ${rows.length} rows into ${table}`);
+      } catch (err) {
+        console.error(
+          `  Failed to seed ${table}: ${err instanceof Error ? err.message : err}`,
+        );
+        process.exit(1);
+      }
     }
-  }
+
+    // Re-enable foreign key checks
+    await tx.$executeRawUnsafe('PRAGMA foreign_keys = ON');
+  });
 
   console.log('Seed complete');
 }