@codeyam/codeyam-cli 0.1.0-staging.dbc742d → 0.1.0-staging.df25827

package/codeyam-cli/templates/editor-step-hook.py

@@ -15,34 +15,70 @@ from datetime import datetime, timezone
 
 STEP_LABELS = {
     1: "Plan",
-    2: "Prototype",
-    3: "Confirm",
-    4: "Deconstruct",
-    5: "Extract",
-    6: "Glossary",
-    7: "Analyze",
-    8: "App Scenarios",
-    9: "User Scenarios",
-    10: "Verify",
-    11: "Journal",
-    12: "Review",
-    13: "Present",
+    2: "Prepare",
+    3: "Prototype",
+    4: "Verify Prototype",
+    5: "Confirm",
+    6: "Deconstruct",
+    7: "Extract",
+    8: "Glossary",
+    9: "Analyze",
+    10: "App Scenarios",
+    11: "User Scenarios",
+    12: "Verify",
+    13: "Journal",
+    14: "Review",
+    15: "Present",
+    16: "Commit",
+    17: "Finalize",
+    18: "Push",
 }
 
 STEP_RESTRICTIONS = {
     1: "Do NOT write any code. Plan and describe only. Wait for user confirmation.",
-    2: "Do NOT create scenarios or run codeyam analyze. Build fast — working prototype with real data.",
-    3: "Present a selection menu (AskUserQuestion) for confirmation. Do NOT refactor or create scenarios until approved.",
-    4: "Do NOT write any code. Read every file, identify all extractable pieces, write a numbered plan. Planning only.",
-    5: "Execute the extraction plan from step 4. Components first (no tests), then library functions via TDD. Page files must contain ZERO direct JSX.",
-    6: "Do NOT write application code or scenarios. Update the glossary only.",
-    7: "Create isolation routes for visual components, run tests for library functions. Register component scenarios via codeyam editor register.",
-    8: "Do NOT modify application code. Create and register app-level scenarios only.",
-    9: "Do NOT modify application code. Create user-persona scenarios only (or skip if no users).",
-    10: "Verify component isolation screenshots AND editor scenarios. After ANY code fix, re-register affected components. Fix only — do NOT add features.",
-    11: "Create or update the journal entry for this feature. Do NOT create a duplicate — check if one exists first.",
-    12: "Verify ALL screenshots exist and NO client-side errors (/api/editor-client-errors). Run codeyam editor audit. Do not proceed until all checks pass.",
-    13: "Show the results panel, present summary, then selection menu (AskUserQuestion): Save or make changes.",
+    2: "Do NOT write any code or build features. Set up the project and prepare the database only.",
+    3: "Do NOT create scenarios or run codeyam analyze. Build fast — working prototype with real data.",
+    4: "Verify the prototype works. Do NOT add features — only fix broken functionality.",
+    5: "Present a selection menu (AskUserQuestion) for confirmation. Do NOT refactor or create scenarios until approved.",
+    6: "Do NOT write any code. Read every file, identify all extractable pieces, write a numbered plan. Planning only. Every opportunity to extract code into a function, helper, or sub-component MUST be taken. Then plan to extract from the extracted code until each piece does one clearly defined thing.",
+    7: "Execute the extraction plan from step 6. Components first (no tests), then library functions via TDD. Page files must contain ZERO direct JSX. After extraction: re-read every file — extract further until each piece does one thing. Verify every test file covers all conditional branches.",
+    8: "Do NOT write application code or scenarios. Update the glossary only.",
+    9: "Create isolation routes for visual components, run tests for library functions. Register component scenarios via codeyam editor register.",
+    10: "Do NOT modify application code. Create and register app-level scenarios only.",
+    11: "Do NOT modify application code. Create user-persona scenarios only (or skip if no users).",
+    12: "Verify component isolation screenshots AND editor scenarios. After ANY code fix, re-register affected components. Fix only — do NOT add features.",
+    13: "Create or update the journal entry for this feature. Do NOT create a duplicate — check if one exists first.",
+    14: "Verify ALL screenshots exist and NO client-side errors (/api/editor-client-errors). Run codeyam editor audit. Do not proceed until all checks pass.",
+    15: "Show the results panel, present summary, then selection menu (AskUserQuestion): Save or make changes.",
+    16: "Hide the results panel and commit all changes. Do NOT push — that happens in step 18.",
+    17: "Update the journal entry with the commit SHA and amend the commit to include the journal update.",
+    18: "Check for a git remote and offer to push. After push (or skip), call the feature-complete API and STOP.",
+}
+
+MIGRATION_STEP_LABELS = {
+    1: "Survey",
+    2: "App Scenarios",
+    3: "Component Scenarios",
+    4: "Preview",
+    5: "Discuss",
+    6: "Decompose",
+    7: "Extract",
+    8: "Recapture",
+    9: "Journal",
+    10: "Present",
+}
+
+MIGRATION_STEP_RESTRICTIONS = {
+    1: "Survey the page and start the dev server. Read all files and map data flow. Do NOT register scenarios yet.",
+    2: "Set up seed adapter if needed, then register application scenarios for the ACTUAL page route with seed data.",
+    3: "Create isolation routes and register component scenarios for individual visual components.",
+    4: "Verify screenshots and show results to the user. Do NOT modify application code.",
+    5: "Assess complexity and ask user about decomposition. Wait for user decision before proceeding.",
+    6: "Plan-only. Identify all extractions, mark existing components as REUSE. Do NOT write code.",
+    7: "Execute the extraction plan. Components first, then functions via TDD.",
+    8: "Update glossary, re-register scenarios after code changes, verify screenshots. Fix issues only.",
+    9: "Create the journal entry for this page's migration.",
+    10: "Show results, present summary, commit or make changes. After commit run `codeyam editor migrate complete` then `codeyam editor migrate next`.",
 }
 
 
@@ -81,6 +117,13 @@ def detect_event():
 
 
 def main():
+    # Only run in editor Build sessions. The env var is set by the terminal
+    # server when launching Claude in editor mode. Without this guard, hooks
+    # fire in every Claude session in the project (scenario editing, bare
+    # claude, etc.) and inject unwanted step restrictions.
+    if not os.environ.get("CODEYAM_EDITOR_ACTIVE"):
+        return
+
     project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
     state_path = os.path.join(project_dir, ".codeyam", "editor-step.json")
     prompt_path = os.path.join(project_dir, ".codeyam", "editor-user-prompt.txt")
@@ -88,17 +131,34 @@ def main():
     # Detect event early so we can capture the user prompt even before state exists
     event_type, event_data = detect_event()
 
-    # Capture the very first user prompt (before state file may exist).
-    # Save to a separate file so it persists across state transitions.
-    if event_type == "user_prompt" and not os.path.exists(prompt_path):
+    # Capture the user's feature request prompt.
+    # Write when: (a) no prompt file yet, (b) no state file (between features),
+    # or (c) previous feature is done (step >= 18). This ensures the prompt
+    # is refreshed for each new feature instead of persisting stale text.
+    # Skip slash commands (e.g. /codeyam-editor) — they aren't user prompts.
+    if event_type == "user_prompt":
         prompt_text = event_data.get("prompt", "").strip()
-        if prompt_text:
-            try:
-                os.makedirs(os.path.dirname(prompt_path), exist_ok=True)
-                with open(prompt_path, "w") as f:
-                    f.write(prompt_text)
-            except Exception:
-                pass  # Best-effort
+        if prompt_text and not prompt_text.startswith("/"):
+            should_capture = not os.path.exists(prompt_path)
+            if not should_capture:
+                # Overwrite stale prompt when between features
+                if not os.path.exists(state_path):
+                    should_capture = True
+                else:
+                    try:
+                        with open(state_path, "r") as f:
+                            prev = json.load(f)
+                        if prev.get("step", 0) >= 18:
+                            should_capture = True
+                    except Exception:
+                        pass
+            if should_capture:
+                try:
+                    os.makedirs(os.path.dirname(prompt_path), exist_ok=True)
+                    with open(prompt_path, "w") as f:
+                        f.write(prompt_text)
+                except Exception:
+                    pass  # Best-effort
 
     if not os.path.exists(state_path):
         return
@@ -112,24 +172,61 @@ def main():
     step = state.get("step")
     label = state.get("label", "Unknown")
     feature = state.get("feature", "")
+    migration = state.get("migration")  # Optional migration context
 
     if not step:
         return
 
+    # ── Task tracking ──────────────────────────────────────────────────
+    # Track whether TaskCreate was called between step transitions.
+    # If Claude advances to the next step without creating a task, block it.
+    task_tracking_path = os.path.join(project_dir, ".codeyam", "editor-task-tracking.json")
+
+    if event_type == "post_tool_use":
+        tool_name = event_data.get("tool_name", "")
+
+        # Record when TaskCreate is called
+        if tool_name == "TaskCreate":
+            try:
+                tracking = {}
+                if os.path.exists(task_tracking_path):
+                    with open(task_tracking_path, "r") as f:
+                        tracking = json.load(f)
+                tracking["taskCreated"] = True
+                with open(task_tracking_path, "w") as f:
+                    json.dump(tracking, f)
+            except Exception:
+                pass
+
     # Log the hook firing
     log_data = {"step": step, "label": label, "feature": feature, "hook": event_type}
+    if migration:
+        log_data["migration"] = True
     if event_type == "post_tool_use":
         log_data["tool"] = event_data.get("tool_name", "")
     log_event(project_dir, "hook", log_data)
 
-    restriction = STEP_RESTRICTIONS.get(step, "")
-    next_cmd = f"codeyam editor {step + 1}" if step < 13 else "codeyam editor 1"
+    # Use migration-specific labels/restrictions when in migration mode
+    if migration:
+        restriction = MIGRATION_STEP_RESTRICTIONS.get(step, "")
+        next_cmd = f"codeyam editor migrate {step + 1}" if step < 10 else "codeyam editor migrate next"
+    else:
+        restriction = STEP_RESTRICTIONS.get(step, "")
+        next_cmd = f"codeyam editor {step + 1}" if step < 18 else "(feature complete — UI handles transition)"
 
     # UserPromptSubmit: concise workflow reminder injected before Claude processes the user's message
     if event_type == "user_prompt":
+        mode_label = "Migration Mode" if migration else "Editor Mode"
+        page_info = ""
+        if migration:
+            page_name = migration.get("pageName", "")
+            page_idx = migration.get("pageIndex", 0)
+            total = migration.get("totalPages", 0)
+            page_info = f" — Page {page_idx + 1}/{total} ({page_name})"
+
         lines = [
             f'<user-prompt-submit-hook>',
-            f'Editor Mode — Step {step} ({label}): "{feature}"',
+            f'{mode_label} — Step {step} ({label}): "{feature}"{page_info}',
         ]
 
         # Include the active scenario so Claude knows what the user is looking at
@@ -149,15 +246,26 @@ def main():
         except (IOError, json.JSONDecodeError):
             pass
 
-        if step == 13:
+        if migration and step == 8:
+            lines.append(
+                "If the user is requesting changes (even indirectly), "
+                "run `codeyam editor change` BEFORE making any modifications. "
+                "The change workflow ensures Working Session Results are shown to the user. "
+                "If the user chose to commit, run `codeyam editor migrate next` to advance to the next page."
+            )
+        elif step in (15, 16, 17, 18) and not migration:
             lines.append(
                 "If the user is requesting changes (even indirectly), "
                 "run `codeyam editor change` BEFORE making any modifications "
                 "(code, scenarios, data, styles — everything). "
                 "The change command gives you the post-change checklist. "
                 "The change workflow ensures Working Session Results are shown to the user. "
-                "If the user chose to commit, run `codeyam editor steps` after committing "
-                "to start the next feature."
+                "If the user chose to commit, run `codeyam editor 16` to advance to the commit step."
+            )
+        elif migration:
+            lines.append(
+                f"You are on migration step {step}. Follow the `codeyam editor migrate` workflow. "
+                f"Do NOT skip ahead or make changes outside the current step."
             )
         else:
             lines.append(
@@ -170,8 +278,9 @@ def main():
         print("\n".join(lines))
         return
 
+    mode_label = "Migration Mode" if migration else "Editor Mode"
     lines = [
-        f'Editor Mode \u2014 Step {step} ({label}): "{feature}"',
+        f'{mode_label} \u2014 Step {step} ({label}): "{feature}"',
     ]
     if restriction:
         lines.append(restriction)
@@ -182,18 +291,40 @@ def main():
         BOLD_CYAN = "\033[1;36m"
         DIM = "\033[2m"
         RESET = "\033[0m"
-        tracker = [f"{DIM}  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510{RESET}"]
-        for i in range(1, 14):
-            lbl = STEP_LABELS[i].ljust(28)
-            num = f" {i}" if i < 10 else f"{i}"
-            content = f"{num}. {lbl}"
-            if i < step:
-                tracker.append(f"{DIM}  \u2502{RESET}{GREEN}  \u2713  {content}{RESET}{DIM}\u2502{RESET}")
-            elif i == step:
-                tracker.append(f"{DIM}  \u2502{RESET}{BOLD_CYAN}  \u2192  {content}{RESET}{DIM}\u2502{RESET}")
-            else:
-                tracker.append(f"{DIM}  \u2502  \u25cb  {content}\u2502{RESET}")
-        tracker.append(f"{DIM}  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518{RESET}")
+
+        if migration:
+            # Migration progress tracker (10 steps)
+            page_name = migration.get("pageName", "")
+            page_idx = migration.get("pageIndex", 0)
+            total = migration.get("totalPages", 0)
+            tracker = [f"{DIM}  Migration: Page {page_idx + 1}/{total} ({page_name}){RESET}"]
+            tracker.append(f"{DIM}  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510{RESET}")
+            for i in range(1, 11):
+                lbl = MIGRATION_STEP_LABELS[i].ljust(28)
+                num = f" {i}" if i < 10 else f"{i}"
+                cntnt = f"{num}. {lbl}"
+                if i < step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{GREEN}  \u2713  {cntnt}{RESET}{DIM}\u2502{RESET}")
+                elif i == step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{BOLD_CYAN}  \u2192  {cntnt}{RESET}{DIM}\u2502{RESET}")
+                else:
+                    tracker.append(f"{DIM}  \u2502  \u25cb  {cntnt}\u2502{RESET}")
+            tracker.append(f"{DIM}  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518{RESET}")
+        else:
+            # Standard progress tracker (18 steps)
+            tracker = [f"{DIM}  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510{RESET}"]
+            for i in range(1, 19):
+                lbl = STEP_LABELS[i].ljust(28)
+                num = f" {i}" if i < 10 else f"{i}"
+                content = f"{num}. {lbl}"
+                if i < step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{GREEN}  \u2713  {content}{RESET}{DIM}\u2502{RESET}")
+                elif i == step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{BOLD_CYAN}  \u2192  {content}{RESET}{DIM}\u2502{RESET}")
+                else:
+                    tracker.append(f"{DIM}  \u2502  \u25cb  {content}\u2502{RESET}")
+            tracker.append(f"{DIM}  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518{RESET}")
+
         lines.append("Present this progress tracker to the user (copy verbatim):")
         lines.extend(tracker)
         lines.append(
@@ -201,7 +332,7 @@ def main():
             "\u2713 (done) or \u2717 (skipped + reason)."
         )
 
-    if event_type == "stop" and step == 13:
+    if event_type == "stop" and ((step in (15, 16) and not migration) or (step == 8 and migration)):
         import subprocess as _sp
         try:
             _result = _sp.run(
@@ -218,10 +349,16 @@ def main():
                 "\n\033[1;31m⚠️  You have uncommitted changes but haven't shown Working Session Results.\033[0m"
             )
             lines.append(
-                "\033[31mRun `codeyam editor change` if you haven't already, then complete the "
-                "checklist and run `codeyam editor 13` to show results to the user.\033[0m"
+                f"\033[31mRun `codeyam editor change` if you haven't already, then complete the "
+                f"checklist and run `{'codeyam editor migrate 8' if migration else 'codeyam editor 15'}` to show results to the user.\033[0m"
             )
 
+    if event_type == "stop":
+        lines.append(
+            f"\n\033[2mReminder: Only use `codeyam editor` subcommands in the Build terminal. "
+            f"Follow `codeyam editor steps` when changing code.\033[0m"
+        )
+
     lines.append(f"When this step is complete, run: {next_cmd}")
 
     print("\n".join(lines))

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'],
   };
 };