create-proto 0.7.10 → 0.8.0

package/README.md

@@ -17,7 +17,7 @@ No canvas. No IDE. No engineering concepts.
 ## What this command does
 
 1. Scaffolds the project: `DESIGN.md` (design system source-of-truth), `CLAUDE.md` (Claude Code instructions for Prototo-aware generation), Prototo component library, a starter Welcome screen
-2. Installs dependencies (Expo SDK 55, React Native, Reanimated 4, `@expo/ui`, `expo-glass-effect`, `expo-clipboard`)
+2. Installs dependencies (Expo SDK 57, React Native, Reanimated 4, `@expo/ui`, `expo-glass-effect`, `expo-clipboard`)
 3. Auto-launches Metro and opens the iOS Simulator
 
 Then in another terminal:

package/dist/messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,QAAQ;;sBAED,MAAM,YAAY,MAAM;yBAErB,MAAM;yBACN,MAAM;8BAED,MAAM;;6BAGP,MAAM;;sBAGb,MAAM;6BAEC,MAAM;yBAEV,MAAM;;;;;CAS5B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,QAAQ;;sBAED,MAAM,YAAY,MAAM;yBAErB,MAAM;yBACN,MAAM;8BAED,MAAM;;6BAGP,MAAM;;sBAGb,MAAM;6BAEC,MAAM;yBAEV,MAAM;;;;;CAM5B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC"}

package/dist/messages.js

@@ -7,9 +7,9 @@ export const messages = {
     cancelled: 'Cancelled. Folder removed.',
     usingDefaultName: (name) => `Using name: ${name} (pass a name as the first argument to override).`,
     bootingProto: 'Booting Prototo...',
-    nextSteps: (name) => `Keep this terminal running. It auto-refreshes your prototype.\n\nOpen a new terminal and run:\n  cd ${name} && claude\n\nIn Claude, press Shift+Tab to switch to Auto mode.`,
+    nextSteps: (name) => `Keep this terminal running. It auto-refreshes your prototype.\n\nOpen a new terminal and start your coding agent:\n  cd ${name} && claude   (or: codex)\n\nIn Claude, press Shift+Tab to switch to Auto mode.`,
     protoCliNotFound: (name) => `Couldn't find proto-cli. Run manually: cd ${name} && npx proto start`,
-    howToRestart: (name) => `Proto stopped.\nTo restart Proto: cd ${name} && npx proto start\nTo share a link: cd ${name} && npx proto share\nTo prompt Claude: cd ${name} && claude`,
+    howToRestart: (name) => `Proto stopped.\nTo restart Proto: cd ${name} && npx proto start\nTo share a link: cd ${name} && npx proto share\nTo prompt your agent: cd ${name} && claude (or codex)`,
     noNetwork: "Couldn't reach the package registry. Check your internet and try again.",
     noPermission: "Don't have permission to write here. Try a different folder.",
     noSpace: 'Out of disk space. Free some up and try again.',

package/dist/messages.js.map

@@ -1 +1 @@
-{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,MAAM,EAAE,SAAS;IACjB,SAAS,EAAE,CAAC,IAAY,EAAE,OAAgB,EAAE,EAAE,CAC5C,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,IAAI,OAAO,OAAO,GAAG,CAAC,CAAC,CAAC,cAAc,IAAI,KAAK;IACvF,SAAS,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,gBAAgB,OAAO,GAAG;IAC1D,YAAY,EAAE,CAAC,IAAY,EAAE,EAAE,CAC7B,8FAA8F,IAAI,KAAK;IACzG,iBAAiB,EAAE,CAAC,IAAY,EAAE,EAAE,CAClC,qEAAqE,IAAI,iCAAiC;IAC5G,SAAS,EAAE,4BAA4B;IACvC,gBAAgB,EAAE,CAAC,IAAY,EAAE,EAAE,CACjC,eAAe,IAAI,mDAAmD;IACxE,YAAY,EAAE,oBAAoB;IAClC,SAAS,EAAE,CAAC,IAAY,EAAE,EAAE,CAC1B,uGAAuG,IAAI,kEAAkE;IAC/K,gBAAgB,EAAE,CAAC,IAAY,EAAE,EAAE,CACjC,6CAA6C,IAAI,qBAAqB;IACxE,YAAY,EAAE,CAAC,IAAY,EAAE,EAAE,CAC7B,wCAAwC,IAAI,4CAA4C,IAAI,6CAA6C,IAAI,YAAY;IAC3J,SAAS,EACP,yEAAyE;IAC3E,YAAY,EACV,8DAA8D;IAChE,OAAO,EAAE,gDAAgD;IACzD,aAAa,EACX,mEAAmE;CACtE,CAAC"}
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,MAAM,EAAE,SAAS;IACjB,SAAS,EAAE,CAAC,IAAY,EAAE,OAAgB,EAAE,EAAE,CAC5C,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,IAAI,OAAO,OAAO,GAAG,CAAC,CAAC,CAAC,cAAc,IAAI,KAAK;IACvF,SAAS,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,gBAAgB,OAAO,GAAG;IAC1D,YAAY,EAAE,CAAC,IAAY,EAAE,EAAE,CAC7B,8FAA8F,IAAI,KAAK;IACzG,iBAAiB,EAAE,CAAC,IAAY,EAAE,EAAE,CAClC,qEAAqE,IAAI,iCAAiC;IAC5G,SAAS,EAAE,4BAA4B;IACvC,gBAAgB,EAAE,CAAC,IAAY,EAAE,EAAE,CACjC,eAAe,IAAI,mDAAmD;IACxE,YAAY,EAAE,oBAAoB;IAClC,SAAS,EAAE,CAAC,IAAY,EAAE,EAAE,CAC1B,2HAA2H,IAAI,gFAAgF;IACjN,gBAAgB,EAAE,CAAC,IAAY,EAAE,EAAE,CACjC,6CAA6C,IAAI,qBAAqB;IACxE,YAAY,EAAE,CAAC,IAAY,EAAE,EAAE,CAC7B,wCAAwC,IAAI,4CAA4C,IAAI,iDAAiD,IAAI,uBAAuB;IAC1K,SAAS,EAAE,yEAAyE;IACpF,YAAY,EAAE,8DAA8D;IAC5E,OAAO,EAAE,gDAAgD;IACzD,aAAa,EAAE,mEAAmE;CACnF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-proto",
-  "version": "0.7.10",
+  "version": "0.8.0",
   "description": "Scaffold a new Proto prototype: `npm create proto@latest myapp`. Describe a screen, watch your prototype run natively on iPhone — designer-first, paired with Claude Code.",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "fs-extra": "^11.2.0",
     "qrcode-terminal": "^0.12.0",
     "validate-npm-package-name": "^5.0.1",
-    "@sherizan/proto-cli": "^0.7.14"
+    "@sherizan/proto-cli": "^0.8.9"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/template/.codex/config.toml

@@ -0,0 +1,6 @@
+# Prototo: connects Codex to this project's MCP tools (compile_check,
+# get_metro_errors, get_simulator_screenshot, reload_app). Codex loads this
+# once you trust the project. Claude Code uses .mcp.json for the same server.
+[mcp_servers.prototo]
+command = "npx"
+args = ["proto-mcp"]

package/template/AGENTS.md

@@ -0,0 +1,185 @@
+# Prototo Project — Agent Instructions
+
+You're the design tool inside a Prototo project. The designer prompts you in plain language; you generate native iOS screens. The iOS Simulator is the canvas. Designers never touch files.
+
+## Read first
+- `DESIGN.md` — design tokens and the project's decisions
+- `/screens/` — what already exists
+
+## Building blocks (use whatever fits)
+
+**Native iOS** — the easiest path to system-feel UI. Apple handles Liquid Glass, SF Symbols, accessibility, dynamic type:
+
+- `expo-router/unstable-native-tabs` — native `UITabBar`
+- `expo-router` `Stack` with `headerLargeTitle: true` + `title` set per route — native large-title nav bar. Don't add `headerTransparent` or `headerBlurEffect` — iOS 26's UINavigationBar paints Liquid Glass automatically and those props break the large-title rendering / cause overlapping effects.
+- `expo-symbols` `SymbolView` — SF Symbol icons
+- `@expo/ui/swift-ui` — `Button`, `Toggle`, `Form`, `Section`, etc.
+- `expo-glass-effect` `GlassView` — Liquid Glass surfaces
+
+**Prototo primitives** in `/components/proto` — small set of themed fallbacks. Props cheat sheet (source is read-only; only read a file if something here doesn't match):
+
+| Primitive | Props |
+|---|---|
+| `Screen` | `scrollable?: boolean` (default true) |
+| `Stack` | `gap?`, `padding?`, `align?: 'start'\|'center'\|'end'` (unset = full-width stretch), `style?` |
+| `Row` | `gap?`, `align?: 'start'\|'center'\|'end'` (default 'start'), `style?` |
+| `Text` | `size?: 'title'\|'headline'\|'body'\|'caption'\|'label'`, `color?: 'primary'\|'secondary'\|'accent'\|'destructive'`, `style?` |
+| `Card` | `glass?: boolean`, `padding?: number` |
+| `Button` | `label: string`, `variant?: 'primary'\|'secondary'\|'ghost'\|'destructive'`, `onPress?`, `disabled?`, `icon?`, `style?`, `textStyle?` |
+| `Toggle` | `label: string`, `value: boolean`, `onChange?(value)` |
+| `Slider` | `value: number`, `onChange?`, `min?`, `max?`, `step?`, `label?` |
+| `Stepper` | `label: string`, `value: number`, `onChange(value)`, `min?`, `max?`, `step?` |
+| `Divider` | `label?: string` |
+| `Input` | React Native `TextInputProps` passthrough |
+| `Modal` | `title: string`, `visible: boolean`, `onClose?` |
+| `Lottie` | `source`, `autoPlay?`, `loop?`, `style?` |
+ `Toggle`, `Slider`, and `Stepper` render real native SwiftUI (`@expo/ui`) on iOS, tinted with the app accent. Card's `glass={true}` uses `expo-glass-effect`'s native iOS 26 material; on older iOS it falls back to a plain View.
+
+**Prototo motion + graphics** — four subpath modules in `/components/proto` cover animation and drawing. Pick by what the prompt actually asks for:
+
+- `../components/proto/motion` — `Motion.View` + `Motion.Pressable`. **Default for transitions.** Native platform animations (CAAnimation / ObjectAnimator) with zero JS overhead. Reach for this for "fade in", "slide up", "scale on tap", "animate when this state changes". Driven by `react-native-ease`.
+- `../components/proto/gestures` — `AnimatedView`, `useSharedValue`, `useAnimatedStyle`, `withSpring`, `Gesture`, `GestureDetector`, etc. Use **only** when the animation must read gesture state, scroll position, or interpolate continuously: "drag this card", "swipe to delete", "parallax this header". Driven by `react-native-reanimated` + `react-native-gesture-handler`.
+- `../components/proto/lottie` — `Lottie` component. Plays `.json` files dropped into `/assets/lottie/`. The designer brings the animation file (LottieFiles / After Effects export); you wire it: `<Lottie source={require('../assets/lottie/<name>.json')} />`. Defaults to `autoPlay` and `loop`. Driven by `lottie-react-native`.
+- `../components/proto/canvas` — `Canvas`, `Path`, `Circle`, `Rect`, `LinearGradient`, etc. For custom drawing that doesn't fit RN's box model: confetti bursts, custom charts, badge shapes. Driven by `@shopify/react-native-skia`.
+- `../components/proto/svg` — `Svg`, `Path`, `Circle`, `Rect`, `G`, `LinearGradient`, etc. For vector icons, logos, and illustrations. You can also import an SVG file directly: `import Logo from '../assets/logo.svg'` then `<Logo width={120} height={40} />`. Driven by `react-native-svg`. Use this for static vector art; reach for `canvas` only when you need to animate or compute the drawing.
+
+Never import `react-native-ease`, `react-native-reanimated`, `lottie-react-native`, `@shopify/react-native-skia`, or `react-native-svg` directly in a screen — always route through the `../components/proto/<subpath>` module above. If `motion` can't express what's needed, fall back to `gestures`.
+
+**Device sensors** — `expo-sensors` (`Accelerometer`, `Gyroscope`, `DeviceMotion`, `Magnetometer`, `Barometer`, `Pedometer`) for prototypes that react to tilting, shaking, or steps. Always guard with `isAvailableAsync()` on the class you use and render a still fallback when it's false: the Simulator has no motion hardware, so nothing ever fires there. Motion only comes alive on a real iPhone — tell the designer to `npx proto share` and open the link in the Prototo app to feel it. Call `requestPermissionsAsync()` before subscribing to `DeviceMotion` or `Pedometer`.
+
+**Custom** — when none of the above fit, write the component you need with React Native. Put shared ones in `/components/shared/`. The designer's vision wins; primitives are starting points, not constraints.
+
+## Adding a library
+
+To add any npm package (a font, an icon set, a utility), run `npx proto add <package>` — never `npm install` / `pnpm add` directly (and `proto` alone isn't on PATH — always `npx proto`). `proto add` installs through `expo install`, which picks the version that matches this project and resolves dependencies cleanly, so the project doesn't break. If the package needs native code this Prototo doesn't bundle, `proto add` will say so — that feature won't appear on the device until the Proto team ships an updated Prototo.
+
+## File layout
+
+```
+/app/<route>.tsx       route — one-line re-export
+/app/_layout.tsx       Stack (for native large titles) or NativeTabs (for tabs)
+/screens/<Name>.tsx    screen, PascalCase, default export
+/components/shared/    designer-created custom components
+/components/proto/     Prototo primitives — read-only
+/assets/lottie/        designer-supplied Lottie JSON files (loaded by the Lottie component)
+```
+
+A new screen `screens/Settings.tsx` needs:
+- `app/settings.tsx` re-exporting it (`import Settings from '../screens/Settings'; export default function SettingsRoute() { return <Settings />; }`)
+- A title set in `app/_layout.tsx`: `<Stack.Screen name="settings" options={{ title: 'Settings' }} />`
+
+**Tabs (NativeTabs)** — exact shape for this project's pinned `expo-router` (the flat `Icon`/`Label` imports you may know do NOT exist here; they're nested under `Trigger`):
+
+```tsx
+import { NativeTabs } from 'expo-router/unstable-native-tabs';
+
+export default function Layout() {
+  return (
+    <NativeTabs>
+      <NativeTabs.Trigger name="index">
+        <NativeTabs.Trigger.Icon sf="house.fill" />
+        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
+      </NativeTabs.Trigger>
+      <NativeTabs.Trigger name="profile">
+        <NativeTabs.Trigger.Icon sf="person.fill" />
+        <NativeTabs.Trigger.Label>Profile</NativeTabs.Trigger.Label>
+      </NativeTabs.Trigger>
+    </NativeTabs>
+  );
+}
+```
+
+**Root-layout changes need a cold restart.** Swapping the navigator in `app/_layout.tsx` (Stack ↔ NativeTabs) does NOT apply via Fast Refresh, and the stale UI in a screenshot can look plausible. After editing `_layout.tsx`, call the `reload_app` MCP tool, then screenshot.
+- Route filenames are lowercase kebab-case.
+
+## DESIGN.md is alive
+
+When the designer asks to change colors, typography, spacing, shape, accent, or anything design-systemy, update `DESIGN.md` too. It's the project's source of truth, and other tools (and future you) will read it.
+
+When you add a new screen, add a one-line entry to `DESIGN.md`'s Screens section.
+
+## One palette, one place
+
+The theme colors live in `DESIGN.md` and the proto tokens — read them with `useTheme()` from `../components/proto`. When a design needs custom brand colors, fonts, or constants beyond the theme (e.g. a specific gradient or accent set), define them **once** in a single shared module (`/components/shared/theme.ts`) and import it everywhere that needs them. Never paste the same color/font constants inline into more than one screen — duplicated palettes drift out of sync. If you find a palette already inlined in a screen, lift it into the shared module and import it back.
+
+## Light, dark, and accessibility
+
+- **Dark mode is automatic.** `useTheme()` returns the right palette for the device's light or dark setting and re-renders when it flips. So use theme colors (`theme.surface.*`, `theme.text.*`, `theme.border.*`) instead of hardcoded hex/rgba, and the screen adapts for free. Custom brand colors in the shared theme module won't auto-adapt — if a design needs a dark variant of a brand color, define both and pick with the same light/dark signal. To pin a scheme for a prototype, set `colorScheme: 'light' | 'dark'` in `proto.config.js`.
+- **Text already scales** with the device's text-size setting (iOS Dynamic Type). Don't disable it. Lay out so text can grow a couple of steps without clipping — avoid fixed heights on text containers.
+- **Accessibility floors** live in `a11y` from `../components/proto`: tap targets ≥ `a11y.minTapTarget` (44pt), text contrast ≥ `a11y.minTextContrast`. After visual changes, the `proto shot` check (below) is where you confirm contrast holds — in both light and dark.
+
+## Check your work visually
+
+You can't see the Simulator by default, so after any visual change, look at it:
+
+1. Run `proto shot` — it captures the running Simulator to `.proto/last-shot.png`.
+2. Read that image and inspect it for real defects: overlapping elements, low contrast / unreadable text, clipping, cramped or uneven spacing, off-center layout, wrong colors.
+3. If something's off, fix it and capture again. Iterate until it looks right — don't make the designer be your QA.
+
+Do this especially after layout, color, typography, or spacing changes. If `proto shot` reports no preview is running, the designer needs to run `proto start` first.
+
+## Proto MCP tools
+
+When the designer runs `proto start`, a local MCP server (`prototo`) connects automatically — no setup. It gives you four tools that close the feedback loop, so you can see what you built instead of asking the designer to relay it. (Under Codex, the tools appear once the designer trusts the project — Codex asks on first open. If the prototo tools are missing, say so and ask the designer to relaunch Codex and trust the project; meanwhile `proto shot` still works.)
+
+**At the start of any fix session** (the designer says something is broken, red, or not working):
+
+1. Call `get_metro_errors` first — it returns the current build failures and runtime crashes from the running prototype, with the raw error text and the screen involved. Don't ask the designer to paste or describe an error before checking it.
+
+**After every screen write:**
+
+1. Call `compile_check` with the screen name — it type-checks the project and reports any problems in plain language. Fix anything it surfaces before moving on.
+2. Call `get_simulator_screenshot` — it returns what the prototype actually renders right now. Inspect it for the same defects as above.
+
+**After editing `app/_layout.tsx` or any navigator:** call `reload_app` — root-layout changes don't Fast-Refresh, and a stale screenshot looks plausible.
+
+Never assume a screen rendered correctly — check the screenshot. Never ask the designer to describe an error you can catch with `get_metro_errors` or `compile_check`. If a tool says the Simulator isn't running (or Metro reports clean while the designer still sees an error), the designer needs to run `proto start` first.
+
+(`get_simulator_screenshot` is the automated form of the `proto shot` loop above — prefer the tool when it's available.)
+
+## Mock vs real data
+
+When a screen shows placeholder numbers that aren't yet wired to a real source, wrap them in `mock()` from `../components/proto` — `const conditions = mock({ wave: '0.8m' })`. It returns the value unchanged, so nothing breaks; it just makes stubbed data obvious and greppable so fake numbers never ship believing they're real. When you wire the value to a live source (a `fetch`), drop the `mock()` wrapper. (Don't use code comments to mark mock data — generated screens stay comment-free.)
+
+### Making it real
+
+When the designer says "use real data", follow this shape so every screen handles loading and failure the same way:
+
+1. Keep the `mock()` value as the **starting state** — it's what shows before the fetch resolves and if the network fails. Drop the `mock()` wrapper from the live value once wired.
+2. Fetch in an effect, guarding against the screen unmounting:
+
+   ```tsx
+   const [data, setData] = useState(FALLBACK);
+   const [loading, setLoading] = useState(true);
+   useEffect(() => {
+     let alive = true;
+     fetch(URL)
+       .then((r) => r.json())
+       .then((json) => { if (alive) setData(shape(json)); })
+       .catch(() => {})
+       .finally(() => { if (alive) setLoading(false); });
+     return () => { alive = false; };
+   }, []);
+   ```
+
+3. While `loading`, show a skeleton or the fallback — never a blank screen. On error, keep the fallback (the `.catch` above already does this); don't surface a raw error to the designer.
+4. Put fetch + shaping logic in `/components/shared/<name>Data.ts`, not inline in the screen.
+
+**Keyless APIs** (no key, CORS-open, good for prototypes): Open-Meteo (weather/marine/air), REST Countries, Open Library, PokéAPI, Art Institute of Chicago, TheMealDB, Wikipedia REST. Prefer these so "make it real" stays a one-prompt step. If a source needs a key, tell the designer that key goes in `proto.config.js`, nowhere else.
+
+## Sharing your prototype
+
+Run `proto share` to publish the prototype and get a permanent `prototo.app/p/<token>` link. Recipients open it on iPhone with the free **Prototo** app (the link page walks them through installing it) and the prototype runs **natively on their device** — real gestures, haptics, and Liquid Glass, with `motion`/`gestures`/`canvas`/`svg`/`lottie`, live data, and custom logic exactly as they run on the designer's Simulator. There's nothing to dumb down — build whatever the designer asks for and it all shares.
+
+Two limits worth knowing: the prototype must be built on the **current Prototo runtime** — when `npx proto start` or `npx proto share` says the project is on an older runtime, run `npx proto upgrade` (it updates Prototo and moves the project to the current runtime; never run Expo or npm commands for this yourself), then `npx proto share` again so the existing link opens on the new Prototo app — and it can only use native modules Prototo bundles — `npx proto add` tells you when a package needs native code that isn't available.
+
+## When modifying
+
+Read the file first, then make precise, targeted edits to the parts that change. Keep edits scoped — don't rewrite a whole file when a few lines change.
+
+## Avoid
+
+- Custom tab bars — `expo-router/unstable-native-tabs` is strictly better (real Liquid Glass, real SF Symbols, system blur).
+- SF Symbol private-use Unicode codepoints (`''`, `''`) in plain Text — they don't render. Use `expo-symbols` `SymbolView` or pass the symbol name to a native component.
+- Editing `/components/proto/`, `.proto/`, `app.config.js`, `babel.config.js`, `metro.config.js`.
+- Telling the designer to open or edit a file manually. They prompt; you write.

package/template/CLAUDE.md

@@ -1,183 +1 @@
-# Prototo Project — Claude Code Instructions
-
-You're the design tool inside a Prototo project. The designer prompts you in plain language; you generate native iOS screens. The iOS Simulator is the canvas. Designers never touch files.
-
-## Read first
-- `DESIGN.md` — design tokens and the project's decisions
-- `/screens/` — what already exists
-
-## Building blocks (use whatever fits)
-
-**Native iOS** — the easiest path to system-feel UI. Apple handles Liquid Glass, SF Symbols, accessibility, dynamic type:
-
-- `expo-router/unstable-native-tabs` — native `UITabBar`
-- `expo-router` `Stack` with `headerLargeTitle: true` + `title` set per route — native large-title nav bar. Don't add `headerTransparent` or `headerBlurEffect` — iOS 26's UINavigationBar paints Liquid Glass automatically and those props break the large-title rendering / cause overlapping effects.
-- `expo-symbols` `SymbolView` — SF Symbol icons
-- `@expo/ui/swift-ui` — `Button`, `Toggle`, `Form`, `Section`, etc.
-- `expo-glass-effect` `GlassView` — Liquid Glass surfaces
-
-**Prototo primitives** in `/components/proto` — small set of themed fallbacks. Props cheat sheet (source is read-only; only read a file if something here doesn't match):
-
-| Primitive | Props |
-|---|---|
-| `Screen` | `scrollable?: boolean` (default true) |
-| `Stack` | `gap?`, `padding?`, `align?: 'start'\|'center'\|'end'` (unset = full-width stretch), `style?` |
-| `Row` | `gap?`, `align?: 'start'\|'center'\|'end'` (default 'start'), `style?` |
-| `Text` | `size?: 'title'\|'headline'\|'body'\|'caption'\|'label'`, `color?: 'primary'\|'secondary'\|'accent'\|'destructive'`, `style?` |
-| `Card` | `glass?: boolean`, `padding?: number` |
-| `Button` | `label: string`, `variant?: 'primary'\|'secondary'\|'ghost'\|'destructive'`, `onPress?`, `disabled?`, `icon?`, `style?`, `textStyle?` |
-| `Toggle` | `label: string`, `value: boolean`, `onChange?(value)` |
-| `Slider` | `value: number`, `onChange?`, `min?`, `max?`, `step?`, `label?` |
-| `Stepper` | `label: string`, `value: number`, `onChange(value)`, `min?`, `max?`, `step?` |
-| `Divider` | `label?: string` |
-| `Input` | React Native `TextInputProps` passthrough |
-| `Modal` | `title: string`, `visible: boolean`, `onClose?` |
-| `Lottie` | `source`, `autoPlay?`, `loop?`, `style?` |
- `Toggle`, `Slider`, and `Stepper` render real native SwiftUI (`@expo/ui`) on iOS, tinted with the app accent. Card's `glass={true}` uses `expo-glass-effect`'s native iOS 26 material; on older iOS it falls back to a plain View.
-
-**Prototo motion + graphics** — four subpath modules in `/components/proto` cover animation and drawing. Pick by what the prompt actually asks for:
-
-- `../components/proto/motion` — `Motion.View` + `Motion.Pressable`. **Default for transitions.** Native platform animations (CAAnimation / ObjectAnimator) with zero JS overhead. Reach for this for "fade in", "slide up", "scale on tap", "animate when this state changes". Driven by `react-native-ease`.
-- `../components/proto/gestures` — `AnimatedView`, `useSharedValue`, `useAnimatedStyle`, `withSpring`, `Gesture`, `GestureDetector`, etc. Use **only** when the animation must read gesture state, scroll position, or interpolate continuously: "drag this card", "swipe to delete", "parallax this header". Driven by `react-native-reanimated` + `react-native-gesture-handler`.
-- `../components/proto/lottie` — `Lottie` component. Plays `.json` files dropped into `/assets/lottie/`. The designer brings the animation file (LottieFiles / After Effects export); you wire it: `<Lottie source={require('../assets/lottie/<name>.json')} />`. Defaults to `autoPlay` and `loop`. Driven by `lottie-react-native`.
-- `../components/proto/canvas` — `Canvas`, `Path`, `Circle`, `Rect`, `LinearGradient`, etc. For custom drawing that doesn't fit RN's box model: confetti bursts, custom charts, badge shapes. Driven by `@shopify/react-native-skia`.
-- `../components/proto/svg` — `Svg`, `Path`, `Circle`, `Rect`, `G`, `LinearGradient`, etc. For vector icons, logos, and illustrations. You can also import an SVG file directly: `import Logo from '../assets/logo.svg'` then `<Logo width={120} height={40} />`. Driven by `react-native-svg`. Use this for static vector art; reach for `canvas` only when you need to animate or compute the drawing.
-
-Never import `react-native-ease`, `react-native-reanimated`, `lottie-react-native`, `@shopify/react-native-skia`, or `react-native-svg` directly in a screen — always route through the `../components/proto/<subpath>` module above. If `motion` can't express what's needed, fall back to `gestures`.
-
-**Custom** — when none of the above fit, write the component you need with React Native. Put shared ones in `/components/shared/`. The designer's vision wins; primitives are starting points, not constraints.
-
-## Adding a library
-
-To add any npm package (a font, an icon set, a utility), run `npx proto add <package>` — never `npm install` / `pnpm add` directly (and `proto` alone isn't on PATH — always `npx proto`). `proto add` installs through `expo install`, which picks the version that matches this project and resolves dependencies cleanly, so the project doesn't break. If the package needs native code this Prototo doesn't bundle, `proto add` will say so — that feature won't appear on the device until the Proto team ships an updated Prototo.
-
-## File layout
-
-```
-/app/<route>.tsx       route — one-line re-export
-/app/_layout.tsx       Stack (for native large titles) or NativeTabs (for tabs)
-/screens/<Name>.tsx    screen, PascalCase, default export
-/components/shared/    designer-created custom components
-/components/proto/     Prototo primitives — read-only
-/assets/lottie/        designer-supplied Lottie JSON files (loaded by the Lottie component)
-```
-
-A new screen `screens/Settings.tsx` needs:
-- `app/settings.tsx` re-exporting it (`import Settings from '../screens/Settings'; export default function SettingsRoute() { return <Settings />; }`)
-- A title set in `app/_layout.tsx`: `<Stack.Screen name="settings" options={{ title: 'Settings' }} />`
-
-**Tabs (NativeTabs)** — exact shape for this project's pinned `expo-router` (the flat `Icon`/`Label` imports you may know do NOT exist here; they're nested under `Trigger`):
-
-```tsx
-import { NativeTabs } from 'expo-router/unstable-native-tabs';
-
-export default function Layout() {
-  return (
-    <NativeTabs>
-      <NativeTabs.Trigger name="index">
-        <NativeTabs.Trigger.Icon sf="house.fill" />
-        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
-      </NativeTabs.Trigger>
-      <NativeTabs.Trigger name="profile">
-        <NativeTabs.Trigger.Icon sf="person.fill" />
-        <NativeTabs.Trigger.Label>Profile</NativeTabs.Trigger.Label>
-      </NativeTabs.Trigger>
-    </NativeTabs>
-  );
-}
-```
-
-**Root-layout changes need a cold restart.** Swapping the navigator in `app/_layout.tsx` (Stack ↔ NativeTabs) does NOT apply via Fast Refresh, and the stale UI in a screenshot can look plausible. After editing `_layout.tsx`, call the `reload_app` MCP tool, then screenshot.
-- Route filenames are lowercase kebab-case.
-
-## DESIGN.md is alive
-
-When the designer asks to change colors, typography, spacing, shape, accent, or anything design-systemy, update `DESIGN.md` too. It's the project's source of truth, and other tools (and future you) will read it.
-
-When you add a new screen, add a one-line entry to `DESIGN.md`'s Screens section.
-
-## One palette, one place
-
-The theme colors live in `DESIGN.md` and the proto tokens — read them with `useTheme()` from `../components/proto`. When a design needs custom brand colors, fonts, or constants beyond the theme (e.g. a specific gradient or accent set), define them **once** in a single shared module (`/components/shared/theme.ts`) and import it everywhere that needs them. Never paste the same color/font constants inline into more than one screen — duplicated palettes drift out of sync. If you find a palette already inlined in a screen, lift it into the shared module and import it back.
-
-## Light, dark, and accessibility
-
-- **Dark mode is automatic.** `useTheme()` returns the right palette for the device's light or dark setting and re-renders when it flips. So use theme colors (`theme.surface.*`, `theme.text.*`, `theme.border.*`) instead of hardcoded hex/rgba, and the screen adapts for free. Custom brand colors in the shared theme module won't auto-adapt — if a design needs a dark variant of a brand color, define both and pick with the same light/dark signal. To pin a scheme for a prototype, set `colorScheme: 'light' | 'dark'` in `proto.config.js`.
-- **Text already scales** with the device's text-size setting (iOS Dynamic Type). Don't disable it. Lay out so text can grow a couple of steps without clipping — avoid fixed heights on text containers.
-- **Accessibility floors** live in `a11y` from `../components/proto`: tap targets ≥ `a11y.minTapTarget` (44pt), text contrast ≥ `a11y.minTextContrast`. After visual changes, the `proto shot` check (below) is where you confirm contrast holds — in both light and dark.
-
-## Check your work visually
-
-You can't see the Simulator by default, so after any visual change, look at it:
-
-1. Run `proto shot` — it captures the running Simulator to `.proto/last-shot.png`.
-2. Read that image and inspect it for real defects: overlapping elements, low contrast / unreadable text, clipping, cramped or uneven spacing, off-center layout, wrong colors.
-3. If something's off, fix it and capture again. Iterate until it looks right — don't make the designer be your QA.
-
-Do this especially after layout, color, typography, or spacing changes. If `proto shot` reports no preview is running, the designer needs to run `proto start` first.
-
-## Proto MCP tools
-
-When the designer runs `proto start`, a local MCP server (`prototo`) connects automatically — no setup. It gives you four tools that close the feedback loop, so you can see what you built instead of asking the designer to relay it.
-
-**At the start of any fix session** (the designer says something is broken, red, or not working):
-
-1. Call `get_metro_errors` first — it returns the current build failures and runtime crashes from the running prototype, with the raw error text and the screen involved. Don't ask the designer to paste or describe an error before checking it.
-
-**After every screen write:**
-
-1. Call `compile_check` with the screen name — it type-checks the project and reports any problems in plain language. Fix anything it surfaces before moving on.
-2. Call `get_simulator_screenshot` — it returns what the prototype actually renders right now. Inspect it for the same defects as above.
-
-**After editing `app/_layout.tsx` or any navigator:** call `reload_app` — root-layout changes don't Fast-Refresh, and a stale screenshot looks plausible.
-
-Never assume a screen rendered correctly — check the screenshot. Never ask the designer to describe an error you can catch with `get_metro_errors` or `compile_check`. If a tool says the Simulator isn't running (or Metro reports clean while the designer still sees an error), the designer needs to run `proto start` first.
-
-(`get_simulator_screenshot` is the automated form of the `proto shot` loop above — prefer the tool when it's available.)
-
-## Mock vs real data
-
-When a screen shows placeholder numbers that aren't yet wired to a real source, wrap them in `mock()` from `../components/proto` — `const conditions = mock({ wave: '0.8m' })`. It returns the value unchanged, so nothing breaks; it just makes stubbed data obvious and greppable so fake numbers never ship believing they're real. When you wire the value to a live source (a `fetch`), drop the `mock()` wrapper. (Don't use code comments to mark mock data — generated screens stay comment-free.)
-
-### Making it real
-
-When the designer says "use real data", follow this shape so every screen handles loading and failure the same way:
-
-1. Keep the `mock()` value as the **starting state** — it's what shows before the fetch resolves and if the network fails. Drop the `mock()` wrapper from the live value once wired.
-2. Fetch in an effect, guarding against the screen unmounting:
-
-   ```tsx
-   const [data, setData] = useState(FALLBACK);
-   const [loading, setLoading] = useState(true);
-   useEffect(() => {
-     let alive = true;
-     fetch(URL)
-       .then((r) => r.json())
-       .then((json) => { if (alive) setData(shape(json)); })
-       .catch(() => {})
-       .finally(() => { if (alive) setLoading(false); });
-     return () => { alive = false; };
-   }, []);
-   ```
-
-3. While `loading`, show a skeleton or the fallback — never a blank screen. On error, keep the fallback (the `.catch` above already does this); don't surface a raw error to the designer.
-4. Put fetch + shaping logic in `/components/shared/<name>Data.ts`, not inline in the screen.
-
-**Keyless APIs** (no key, CORS-open, good for prototypes): Open-Meteo (weather/marine/air), REST Countries, Open Library, PokéAPI, Art Institute of Chicago, TheMealDB, Wikipedia REST. Prefer these so "make it real" stays a one-prompt step. If a source needs a key, tell the designer that key goes in `proto.config.js`, nowhere else.
-
-## Sharing your prototype
-
-Run `proto share` to publish the prototype and get a `prototo.app/p/<token>` link. Anyone can open it in a browser — no install — and see the **real prototype running**, streamed live from a cloud iPhone. Full fidelity: gestures, `motion`/`gestures`/`canvas`/`svg`/`lottie`, live data, and custom logic all show up in the shared link exactly as they run on the designer's device. There's nothing to dumb down — build whatever the designer asks for and it all shares.
-
-Two limits worth knowing: the prototype must be built on the **current Prototo** (an older one won't stream — re-scaffold if prompted), and **real-hardware features** (camera, GPS) are simulated on the cloud device rather than reading a real sensor.
-
-## When modifying
-
-Read the file first, then make precise, targeted edits to the parts that change. Keep edits scoped — don't rewrite a whole file when a few lines change.
-
-## Avoid
-
-- Custom tab bars — `expo-router/unstable-native-tabs` is strictly better (real Liquid Glass, real SF Symbols, system blur).
-- SF Symbol private-use Unicode codepoints (`''`, `''`) in plain Text — they don't render. Use `expo-symbols` `SymbolView` or pass the symbol name to a native component.
-- Editing `/components/proto/`, `.proto/`, `app.config.js`, `babel.config.js`, `metro.config.js`.
-- Telling the designer to open or edit a file manually. They prompt; you write.
+@AGENTS.md

package/template/README.md

@@ -5,5 +5,5 @@ Built with Prototo.
 Before running `proto start` on iPhone, install Prototo from the App Store.
 
 Run `proto start` to preview on the iOS Simulator (auto) or your iPhone (scan QR).
-Run `proto share` to get a link anyone can open in their browser, no install needed.
-Run `proto add "describe a screen"` to generate a new screen.
+Run `proto share` to publish a link anyone can open on their iPhone with the free Prototo app.
+To add a screen, describe it to your coding agent in plain language.

package/template/components/proto/touch-dots.tsx

@@ -1,17 +1,99 @@
 // Proto-managed. Draws a round dot wherever you touch WHILE `proto record` is
 // running, so taps are visible in the recorded video (the recorder captures
-// only what the app itself renders). Dev-only twice over: everything is gated
-// on __DEV__, and published shares are production bundles where __DEV__ is
-// false — stakeholders can never see it. Safe to leave alone.
-import { useEffect, useRef, useState, type ReactNode } from 'react';
-import { Animated, View, type GestureResponderEvent } from 'react-native';
+// only what the app itself renders). It also answers Prototo Desktop's
+// point-and-edit: a tapped preview element is resolved to the screen file and
+// line that renders it. And its screen-flow view: a clicked screen opens here. Dev-only twice over: everything is gated on __DEV__,
+// and published shares are production bundles where __DEV__ is false —
+// stakeholders can never see it. Safe to leave alone.
+import { type ReactNode, useEffect, useRef, useState } from 'react';
+import { Animated, Dimensions, type GestureResponderEvent, View } from 'react-native';
 
-const POLL_MS = 1500;
+const POLL_MS = 500;
 const DOT = 36;
 // A quick tap must linger long enough to be readable in the video.
 const FADE_MS = 350;
 
 type Dot = { id: number; x: number; y: number };
+type InspectRequest = { id: number; x: number; y: number };
+type NavigateRequest = { id: number; path: string };
+
+// Flow view: open the route the desktop asked for, then confirm. expo-router is
+// required at run time (every Prototo project has it; this file's own package
+// doesn't), so a missing router is just a "no".
+function navigateTo(req: NavigateRequest) {
+  let ok = false;
+  try {
+    const { router } = require('expo-router') as { router: { navigate: (href: string) => void } };
+    router.navigate(req.path);
+    ok = true;
+  } catch {
+    // unknown route or no router — the desktop already pasted the file
+  }
+  fetch('http://127.0.0.1:3001/navigate/result', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ id: req.id, ok }),
+  }).catch(() => {});
+}
+type DebugFiber = { _debugStack?: { stack?: unknown }; _debugOwner?: DebugFiber | null };
+
+// Point-and-edit. React keeps, in dev, the JSX call site of every element on
+// its fiber (`_debugStack`); walking the owner chain from the tapped view gives
+// the designer's screen file first. `proto start` symbolicates the stacks. The
+// renderer's inspector is reached through the DevTools hook — the same thing
+// React Native's own element inspector does, without the deprecated deep import.
+type InspectorData = { hierarchy?: unknown[]; closestInstance?: DebugFiber | null };
+type Renderer = {
+  rendererConfig?: {
+    getInspectorDataForViewAtPoint?: (
+      view: View | null,
+      x: number,
+      y: number,
+      cb: (data: InspectorData) => boolean,
+    ) => void;
+  };
+};
+
+function inspectAt(view: View | null, req: InspectRequest) {
+  let answered = false;
+  const post = (stacks: string[]) => {
+    if (answered) return;
+    answered = true;
+    fetch('http://127.0.0.1:3001/inspect/result', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id: req.id, stacks }),
+    }).catch(() => {});
+  };
+  try {
+    const hook = (
+      globalThis as { __REACT_DEVTOOLS_GLOBAL_HOOK__?: { renderers: Map<number, Renderer> } }
+    ).__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    const { width, height } = Dimensions.get('window');
+    for (const renderer of hook?.renderers.values() ?? []) {
+      renderer.rendererConfig?.getInspectorDataForViewAtPoint?.(
+        view,
+        req.x * width,
+        req.y * height,
+        (data) => {
+          if (!data.hierarchy?.length) return false;
+          const stacks: string[] = [];
+          let fiber: DebugFiber | null | undefined = data.closestInstance;
+          for (let i = 0; fiber && i < 12; i++) {
+            const stack = fiber._debugStack?.stack;
+            if (typeof stack === 'string') stacks.push(stack);
+            fiber = fiber._debugOwner;
+          }
+          post(stacks);
+          return true;
+        },
+      );
+    }
+  } catch {
+    // no renderer / not a dev build — the CLI times out and the desktop
+    // falls back to a label-only reference
+  }
+}
 type FadingDot = { key: number; x: number; y: number; opacity: Animated.Value };
 
 // Brand-pink fill + white rim: reads on light AND dark content (a white or
@@ -32,6 +114,9 @@ export default function TouchDots({ children }: { children: ReactNode }) {
   const [fading, setFading] = useState<FadingDot[]>([]);
   const dotsRef = useRef<Dot[]>([]);
   const fadeSeq = useRef(0);
+  const rootRef = useRef<View>(null);
+  const inspected = useRef(0);
+  const navigated = useRef(0);
 
   // Poll `proto start`'s local server for the record flag (the Simulator
   // shares the host loopback). Any failure just means "not recording".
@@ -41,8 +126,21 @@ export default function TouchDots({ children }: { children: ReactNode }) {
     const tick = async () => {
       try {
         const res = await fetch('http://127.0.0.1:3001/recording');
-        const body = (await res.json()) as { recording?: boolean };
-        if (alive) setRecording(body.recording === true);
+        const body = (await res.json()) as {
+          recording?: boolean;
+          inspect?: InspectRequest;
+          navigate?: NavigateRequest;
+        };
+        if (!alive) return;
+        setRecording(body.recording === true);
+        if (body.inspect && body.inspect.id !== inspected.current) {
+          inspected.current = body.inspect.id;
+          inspectAt(rootRef.current, body.inspect);
+        }
+        if (body.navigate && body.navigate.id !== navigated.current) {
+          navigated.current = body.navigate.id;
+          navigateTo(body.navigate);
+        }
       } catch {
         if (alive) setRecording(false);
       }
@@ -98,6 +196,7 @@ export default function TouchDots({ children }: { children: ReactNode }) {
     // Plain touch events bubble to this wrapper no matter which child is the
     // responder, so observing them here never steals the prototype's gestures.
     <View
+      ref={rootRef}
       style={{ flex: 1 }}
       onTouchStart={recording ? onMove : undefined}
       onTouchMove={recording ? onMove : undefined}

package/template/package.json

@@ -9,49 +9,50 @@
     "proto": "proto"
   },
   "dependencies": {
-    "@expo/ui": "~56.0.16",
+    "@expo/ui": "~57.0.18",
     "@react-native-async-storage/async-storage": "2.2.0",
     "@shopify/flash-list": "2.0.2",
     "@shopify/react-native-skia": "2.6.2",
-    "expo": "~56.0.0",
-    "expo-asset": "~56.0.16",
-    "expo-audio": "~56.0.11",
-    "expo-camera": "~56.0.7",
-    "expo-clipboard": "~56.0.4",
-    "expo-constants": "~56.0.17",
-    "expo-dev-client": "~56.0.19",
-    "expo-font": "~56.0.5",
-    "expo-glass-effect": "~56.0.4",
-    "expo-haptics": "~56.0.3",
-    "expo-image": "~56.0.10",
-    "expo-image-picker": "~56.0.16",
-    "expo-linear-gradient": "~56.0.4",
-    "expo-linking": "~56.0.13",
-    "expo-location": "~56.0.16",
-    "expo-maps": "~56.0.6",
-    "expo-router": "~56.2.9",
-    "expo-screen-orientation": "~56.0.5",
-    "expo-status-bar": "~56.0.4",
-    "expo-symbols": "~56.0.6",
-    "expo-video": "~56.1.2",
+    "expo": "~57.0.0",
+    "expo-asset": "~57.0.17",
+    "expo-audio": "~57.0.5",
+    "expo-camera": "~57.0.5",
+    "expo-clipboard": "~57.0.2",
+    "expo-constants": "~57.0.18",
+    "expo-dev-client": "~57.0.19",
+    "expo-font": "~57.0.4",
+    "expo-glass-effect": "~57.0.3",
+    "expo-haptics": "~57.0.3",
+    "expo-image": "~57.0.5",
+    "expo-image-picker": "~57.0.18",
+    "expo-linear-gradient": "~57.0.2",
+    "expo-linking": "~57.0.10",
+    "expo-location": "~57.0.18",
+    "expo-maps": "~57.0.3",
+    "expo-router": "~57.0.21",
+    "expo-screen-orientation": "~57.0.2",
+    "expo-sensors": "~57.0.3",
+    "expo-status-bar": "~57.0.1",
+    "expo-symbols": "~57.0.3",
+    "expo-video": "~57.0.4",
     "lottie-react-native": "~7.3.4",
     "react": "19.2.3",
     "react-dom": "19.2.3",
-    "react-native": "0.85.3",
+    "react-native": "0.86.3",
     "react-native-ease": "^0.7.2",
-    "react-native-gesture-handler": "~2.31.1",
-    "react-native-reanimated": "4.3.1",
+    "react-native-gesture-handler": "~2.32.0",
+    "react-native-reanimated": "4.5.1",
     "react-native-safe-area-context": "~5.7.0",
-    "react-native-screens": "4.25.2",
+    "react-native-screens": "4.26.2",
     "react-native-svg": "15.15.4",
     "react-native-webview": "13.16.1",
-    "react-native-worklets": "0.8.3"
+    "react-native-worklets": "0.10.1"
   },
   "devDependencies": {
     "@babel/core": "^7.24.0",
-    "@sherizan/proto-cli": "^0.7.0",
+    "@sherizan/proto-cli": "^0.8.0",
     "@types/react": "~19.2.15",
-    "babel-preset-expo": "~56.0.0",
+    "babel-preset-expo": "~57.0.0",
     "react-native-svg-transformer": "^1.5.0",
     "typescript": "~6.0.3"
   }

package/template/screens/Home.tsx

@@ -14,8 +14,8 @@ import { Screen, Stack, Text, Card, Divider, Lottie } from '../components/proto'
 
 // Prototo Desktop sets EXPO_PUBLIC_PROTO_DESKTOP=1 when it runs `proto start`
 // (Metro inlines it at bundle time). In the desktop the terminal sits beside
-// this preview with Claude already running, and the simulator clipboard never
-// reaches the Mac, so the copy and the Copy affordance both change.
+// this preview with the coding agent already running, and the simulator
+// clipboard never reaches the Mac, so the copy and Copy affordance both change.
 const IN_DESKTOP = process.env.EXPO_PUBLIC_PROTO_DESKTOP === '1';
 
 const EXAMPLES = [
@@ -98,7 +98,7 @@ export default function Home() {
               <Text size="body" color="secondary">
                 {IN_DESKTOP
                   ? 'Type your first prompt in the terminal beside this preview, and watch it appear here.'
-                  : `In a terminal: cd {{APP_NAME}} && claude. Then paste a prompt below.`}
+                  : `In a terminal: cd {{APP_NAME}} && claude (or codex). Then paste a prompt below.`}
               </Text>
             </Stack>
           </Card>