create-proto 0.8.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-proto",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "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.8.9"
+    "@sherizan/proto-cli": "^0.8.17"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/template/AGENTS.md

@@ -1,57 +1,51 @@
 # 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.
+You're the design tool inside a Prototo project. The designer prompts in plain language; you build native iOS screens. The iOS Simulator is the canvas. Designers never touch files: they prompt, you write.
 
 ## Read first
-- `DESIGN.md` — design tokens and the project's decisions
-- `/screens/` — what already exists
+- `DESIGN.md` — tokens and the project's decisions. Keep it alive: update it when colors, type, spacing, shape or accent change, and add a one-line entry to its Screens section for every new screen.
+- `/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:
+**Native iOS first** (Apple handles Liquid Glass, SF Symbols, accessibility, Dynamic Type):
+- `expo-router/unstable-native-tabs` — native `UITabBar` (shape below). Never build a custom tab bar.
+- `expo-router` `Stack` with `headerLargeTitle: true` + a per-route `title`. Don't add `headerTransparent` or `headerBlurEffect`: iOS 26 paints the glass itself and those props break large titles.
+- `expo-symbols` `SymbolView` for SF Symbols (private-use codepoints in `Text` don't render).
+- `@expo/ui/swift-ui` (`Button`, `Toggle`, `Form`, `Section`…) · `expo-glass-effect` `GlassView`.
 
-- `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):
+**Prototo primitives** from `../components/proto` (read-only; open a source file only if this table 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?` |
+| `Screen` | `scrollable?` (default true), `gradient?` (true = light accent wash rising from the bottom, or a colour) |
+| `Stack` | `gap?`, `padding?`, `align?: 'start'\|'center'\|'end'` (unset = stretch), `style?` |
+| `Row` | `gap?`, `align?` (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?` |
+| `Card` | `glass?` (iOS 26 material, plain View on older iOS), `padding?` |
+| `Button` | native Liquid Glass. `label`, `variant?: 'primary'\|'secondary'\|'ghost'\|'destructive'`, `onPress?`, `disabled?`, `systemImage?` (SF Symbol name), `image?` (picture URL for a brand mark) |
+| `Toggle` / `Slider` / `Stepper` | native SwiftUI, accent-tinted. `Toggle`: `label`, `value`, `onChange?` · `Slider`: `value`, `onChange?`, `min?`, `max?`, `step?`, `label?` · `Stepper`: `label`, `value`, `onChange`, `min?`, `max?`, `step?` |
+| `Divider` | `label?` |
+| `Input` | RN `TextInputProps` |
+| `Modal` | native bottom sheet, sizes to its content. `title`, `visible`, `onClose?` |
+| `Picker` | native segmented control. `options: string[]`, `value`, `onChange?`, `label?`, `variant?: 'segmented'\|'menu'\|'wheel'` |
+| `DatePicker` | native compact picker. `value: Date`, `onChange?`, `label?`, `mode?: 'date'\|'time'\|'dateTime'`, `min?`, `max?` |
+| `Menu` | native pull-down. `label`, `systemImage?`, `items: { label, onPress?, destructive?, systemImage? }[]` |
+| `Alert` | native alert, controlled. `title`, `message?`, `visible`, `onClose?`, `actions: { label, onPress?, destructive?, cancel? }[]` |
 | `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`.
+**Motion + graphics** — always import through these subpaths, never the underlying library:
+- `../components/proto/motion` — `Motion.View`, `Motion.Pressable`. **Default** for fades, slides, scale on tap, state-change animations.
+- `../components/proto/gestures` — `AnimatedView`, `useSharedValue`, `useAnimatedStyle`, `withSpring`, `Gesture`, `GestureDetector`. Only when animation follows a drag, swipe, scroll or continuous value.
+- `../components/proto/lottie` — plays designer-supplied files: `<Lottie source={require('../assets/lottie/<name>.json')} />`.
+- `../components/proto/svg` — static vector art; `import Logo from '../assets/logo.svg'` works too.
+- `../components/proto/canvas` — computed or animated drawing (confetti, charts, custom shapes).
 
-**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`.
+**Sensors** — `expo-sensors` (`Accelerometer`, `Gyroscope`, `DeviceMotion`, `Magnetometer`, `Barometer`, `Pedometer`). Guard with `isAvailableAsync()` and render a still fallback: the Simulator never fires motion, only a real iPhone does (via a published link in the Prototo app). Call `requestPermissionsAsync()` before `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.
+**Custom** — when nothing fits, write it with React Native in `/components/shared/`. The designer's vision wins.
 
-## 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.
+**Adding a package** — `npx proto add <package>` only (never `npm install` / `pnpm add`; bare `proto` isn't on PATH). It says when a package needs native code Prototo doesn't bundle.
 
 ## File layout
 
@@ -66,9 +60,12 @@ To add any npm package (a font, an icon set, a utility), run `npx proto add <pac
 
 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' }} />`
+- A title in `app/_layout.tsx`: `<Stack.Screen name="settings" options={{ title: 'Settings' }} />`
+- Route filenames are lowercase kebab-case.
+
+**Linking screens** — Prototo draws the prototype's flow (Export flow) from the code, so write navigation where it can read it: `router.push('/settings')` inline in the `onPress`, or `<Link href="/settings">`, in the screen file itself (or in that screen's `<Stack.Screen options>` for a header button). A handler defined elsewhere, a link inside a shared component, or a `[param]` route still works, but that arrow won't start at its button.
 
-**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`):
+**NativeTabs** — exact shape for this project's `expo-router` (`Icon`/`Label` are nested under `Trigger`, not flat imports):
 
 ```tsx
 import { NativeTabs } from 'expo-router/unstable-native-tabs';
@@ -80,106 +77,34 @@ export default function Layout() {
         <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.
+## Theme, dark mode, accessibility
+- Colors come from `useTheme()` (`theme.surface.*`, `theme.text.*`, `theme.border.*`): light/dark is automatic, so no hardcoded hex. `colorScheme: 'light' | 'dark'` in `proto.config.js` pins a scheme.
+- Custom brand colors, fonts or constants live **once** in `/components/shared/theme.ts` (define light + dark variants if needed). Never paste a palette into more than one screen; lift any you find.
+- Text scales with Dynamic Type: never disable it, avoid fixed heights on text containers.
+- `a11y` from `../components/proto`: tap targets ≥ `a11y.minTapTarget` (44pt), contrast ≥ `a11y.minTextContrast`, in light and dark.
+
+## Check your work (Proto MCP tools)
+The `prototo` MCP server connects while the preview runs. (Under Codex it appears once the designer trusts the project; if it's missing, ask them to relaunch Codex and trust it.)
+- **Something's broken / red?** Call `get_metro_errors` first. Never ask the designer to paste an error.
+- **After every screen write:** `compile_check` with the screen name, fix what it reports, then `get_simulator_screenshot` and inspect for overlap, clipping, low contrast, cramped or uneven spacing, wrong colors. Iterate until it looks right; don't make the designer your QA.
+- **After editing `app/_layout.tsx` or any navigator:** `reload_app` first. Root layouts don't Fast-Refresh and a stale screenshot looks plausible.
+- No MCP? `npx proto shot` writes `.proto/last-shot.png`; read it. If the tools say nothing is running, ask the designer to restart the preview.
+
+## Data
+- Placeholder values: wrap in `mock()` from `../components/proto` (`mock({ wave: '0.8m' })`). It returns the value unchanged and marks it as fake. No code comments for this.
+- "Use real data": keep the mock value as the starting state and fallback, fetch in an effect with an `alive` guard, show a skeleton or the fallback while loading, keep the fallback on error (never surface a raw error). Fetch + shaping logic goes in `/components/shared/<name>Data.ts`.
+- Keyless APIs: Open-Meteo, REST Countries, Open Library, PokéAPI, Art Institute of Chicago, TheMealDB, Wikipedia REST. A key goes in `proto.config.js`, nowhere else.
+
+## Sharing
+A published link (`prototo.app/p/<token>`) runs the prototype natively in the free Prototo iPhone app, with everything above: gestures, haptics, glass, motion, live data. Build what the designer asks; nothing needs dumbing down. Limits: only native modules Prototo bundles (`npx proto add` tells you), and the project must be on the current Prototo runtime. If a command says it's older, run `npx proto upgrade` (never Expo or npm commands for this), then publish again so the existing link opens on the new app.
+
+## Rules
+- Read a file, then make targeted edits; don't rewrite whole files for small changes.
+- Generated screens have no code comments.
+- Never edit `/components/proto/`, `.proto/`, `app.config.js`, `babel.config.js`, `metro.config.js`.
+- Never tell the designer to open or edit a file.

package/template/components/proto/Alert.tsx

@@ -0,0 +1,79 @@
+import { useEffect } from 'react';
+import { Alert as RNAlert, Platform } from 'react-native';
+import { Alert as SwiftUIAlert, Button as SwiftUIButton, Host, Text as SwiftUIText } from '@expo/ui/swift-ui';
+import { frame, opacity } from '@expo/ui/swift-ui/modifiers';
+
+export type AlertAction = {
+  label: string;
+  onPress?: () => void;
+  destructive?: boolean;
+  cancel?: boolean;
+};
+
+export type AlertProps = {
+  title: string;
+  message?: string;
+  visible: boolean;
+  onClose?: () => void;
+  actions: AlertAction[];
+};
+
+const roleOf = (action: AlertAction) =>
+  action.destructive ? 'destructive' : action.cancel ? 'cancel' : undefined;
+
+/**
+ * Apple's own alert. Controlled by `visible`; onClose fires after any action or dismiss.
+ */
+export function Alert({ title, message, visible, onClose, actions }: AlertProps) {
+  useEffect(() => {
+    if (Platform.OS === 'ios' || !visible) return;
+    // ponytail: iOS-first product; Android uses the system alert, which closes itself.
+    RNAlert.alert(
+      title,
+      message,
+      actions.map((action) => ({
+        text: action.label,
+        style: roleOf(action) ?? 'default',
+        onPress: () => {
+          action.onPress?.();
+          onClose?.();
+        },
+      })),
+      { onDismiss: onClose },
+    );
+  }, [visible]);
+
+  if (Platform.OS !== 'ios') return null;
+
+  return (
+    <Host matchContents>
+      <SwiftUIAlert
+        title={title}
+        isPresented={visible}
+        onIsPresentedChange={(open) => {
+          if (!open) onClose?.();
+        }}
+      >
+        {/* ponytail: SwiftUI hangs the alert off a trigger view; an invisible one keeps it controlled by `visible`. */}
+        <SwiftUIAlert.Trigger>
+          <SwiftUIText modifiers={[frame({ width: 0, height: 0 }), opacity(0)]}> </SwiftUIText>
+        </SwiftUIAlert.Trigger>
+        {message ? (
+          <SwiftUIAlert.Message>
+            <SwiftUIText>{message}</SwiftUIText>
+          </SwiftUIAlert.Message>
+        ) : null}
+        <SwiftUIAlert.Actions>
+          {actions.map((action) => (
+            <SwiftUIButton
+              key={action.label}
+              label={action.label}
+              role={roleOf(action)}
+              onPress={action.onPress}
+            />
+          ))}
+        </SwiftUIAlert.Actions>
+      </SwiftUIAlert>
+    </Host>
+  );
+}

package/template/components/proto/Button.tsx

@@ -1,52 +1,85 @@
-import { Pressable, View, type TextStyle, type ViewStyle } from 'react-native';
-import type { ReactNode } from 'react';
-import Animated, { useSharedValue, useAnimatedStyle, withTiming } from 'react-native-reanimated';
+import { Platform, Pressable, type ViewStyle } from 'react-native';
+import { useContext, type ComponentProps } from 'react';
+import { Host, Button as SwiftUIButton, Image as SwiftUIImage, Label as SwiftUILabel } from '@expo/ui/swift-ui';
+import {
+  buttonStyle,
+  controlSize,
+  disabled as disabledModifier,
+  frame,
+  resizable,
+  tint,
+} from '@expo/ui/swift-ui/modifiers';
 import * as Haptics from 'expo-haptics';
 import { useTheme, useAccent } from './useTheme';
 import { Text } from './Text';
+import { RowContext } from './Row';
 
 export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive';
+export type SFSymbol = NonNullable<ComponentProps<typeof SwiftUIButton>['systemImage']>;
 
 export type ButtonProps = {
   label: string;
   variant?: ButtonVariant;
   onPress?: () => void;
   disabled?: boolean;
-  icon?: ReactNode;
-  style?: ViewStyle;
-  textStyle?: TextStyle;
+  systemImage?: SFSymbol;
+  image?: string;
 };
 
-export function Button({
-  label,
-  variant = 'primary',
-  onPress,
-  disabled = false,
-  icon,
-  style,
-  textStyle,
-}: ButtonProps) {
+const STYLE = {
+  primary: 'glassProminent',
+  secondary: 'glass',
+  ghost: 'borderless',
+  destructive: 'glassProminent',
+} as const;
+
+/**
+ * Apple's own button: Liquid Glass on iOS 26 (SwiftUI `buttonStyle`), tinted with the
+ * prototype's accent. `systemImage` is an SF Symbol name shown before the label; `image` is a
+ * picture URL (https or data) for a brand mark instead.
+ */
+export function Button({ label, variant = 'primary', onPress, disabled = false, systemImage, image }: ButtonProps) {
   const theme = useTheme();
   const accent = useAccent();
-  const scale = useSharedValue(1);
-
-  const animated = useAnimatedStyle(() => ({
-    transform: [{ scale: scale.value }],
-  }));
+  const inRow = useContext(RowContext);
 
-  const handlePressIn = () => {
-    if (disabled) return;
-    scale.value = withTiming(0.96, { duration: 80 });
-  };
-  const handlePressOut = () => {
-    if (disabled) return;
-    scale.value = withTiming(1, { duration: 120 });
-  };
   const handlePress = () => {
     Haptics.selectionAsync().catch(() => {});
     onPress?.();
   };
 
+  if (Platform.OS === 'ios') {
+    return (
+      // ponytail: a fixed-height host, like Slider, fills a Stack; matchContents measures the
+      // button unconstrained (SwiftUI fixedSize) so inside a Row it hugs its label instead.
+      <Host
+        matchContents={inRow ? { horizontal: true } : undefined}
+        style={inRow ? { height: 50 } : { alignSelf: 'stretch', height: 50 }}
+      >
+        <SwiftUIButton
+          role={variant === 'destructive' ? 'destructive' : undefined}
+          onPress={handlePress}
+          modifiers={[
+            buttonStyle(STYLE[variant]),
+            controlSize('large'),
+            tint(variant === 'destructive' ? theme.text.destructive : accent),
+            disabledModifier(disabled),
+          ]}
+        >
+          {/* ponytail: the frame goes on the label so the glass stretches with it; SwiftUI's
+              `.infinity` has no JSON form, a huge maxWidth stretches the same way. */}
+          <SwiftUILabel
+            title={label}
+            systemImage={systemImage}
+            icon={image ? <SwiftUIImage uiImage={image} modifiers={[resizable(), frame({ width: 18, height: 18 })]} /> : undefined}
+            modifiers={[frame({ maxWidth: 100000 })]}
+          />
+        </SwiftUIButton>
+      </Host>
+    );
+  }
+
+  // ponytail: iOS-first product; Android keeps a plain themed Pressable.
   const palette: Record<ButtonVariant, { bg: string; fg: string }> = {
     primary: { bg: accent, fg: '#FFFFFF' },
     secondary: { bg: theme.surface.secondary, fg: theme.text.primary },
@@ -54,8 +87,7 @@ export function Button({
     destructive: { bg: theme.text.destructive, fg: '#FFFFFF' },
   };
   const { bg, fg } = palette[variant];
-
-  const baseStyle: ViewStyle = {
+  const style: ViewStyle = {
     backgroundColor: bg,
     borderRadius: theme.radius.button,
     paddingVertical: theme.space.sm + 4,
@@ -64,17 +96,11 @@ export function Button({
     justifyContent: 'center',
     opacity: disabled ? 0.5 : 1,
   };
-
   return (
-    <Pressable disabled={disabled} onPressIn={handlePressIn} onPressOut={handlePressOut} onPress={handlePress}>
-      <Animated.View style={[baseStyle, animated, style]}>
-        <View style={{ flexDirection: 'row', alignItems: 'center', gap: theme.space.sm }}>
-          {icon}
-          <Text size="label" style={[{ color: fg }, textStyle]}>
-            {label}
-          </Text>
-        </View>
-      </Animated.View>
+    <Pressable disabled={disabled} onPress={handlePress} style={style}>
+      <Text size="label" style={{ color: fg }}>
+        {label}
+      </Text>
     </Pressable>
   );
 }

package/template/components/proto/DatePicker.tsx

@@ -0,0 +1,52 @@
+import { Platform } from 'react-native';
+import { Host, DatePicker as SwiftUIDatePicker } from '@expo/ui/swift-ui';
+import { datePickerStyle, tint } from '@expo/ui/swift-ui/modifiers';
+import { useAccent } from './useTheme';
+import { Text } from './Text';
+
+export type DatePickerMode = 'date' | 'time' | 'dateTime';
+
+export type DatePickerProps = {
+  value: Date;
+  onChange?: (date: Date) => void;
+  label?: string;
+  mode?: DatePickerMode;
+  min?: Date;
+  max?: Date;
+};
+
+const COMPONENTS = {
+  date: ['date'],
+  time: ['hourAndMinute'],
+  dateTime: ['date', 'hourAndMinute'],
+} as const;
+
+/**
+ * Apple's own compact date picker (label left, tappable value right).
+ */
+export function DatePicker({ value, onChange, label, mode = 'date', min, max }: DatePickerProps) {
+  const accent = useAccent();
+
+  if (Platform.OS !== 'ios') {
+    // ponytail: iOS-first product; Android shows the value read-only.
+    return (
+      <Text size="body">
+        {label ? `${label}: ` : ''}
+        {value.toLocaleString()}
+      </Text>
+    );
+  }
+
+  return (
+    <Host style={{ alignSelf: 'stretch', height: 44 }}>
+      <SwiftUIDatePicker
+        title={label}
+        selection={value}
+        range={{ start: min, end: max }}
+        displayedComponents={[...COMPONENTS[mode]]}
+        onDateChange={(next) => onChange?.(next)}
+        modifiers={[datePickerStyle('compact'), tint(accent)]}
+      />
+    </Host>
+  );
+}

package/template/components/proto/Menu.tsx

@@ -0,0 +1,62 @@
+import { Alert as RNAlert, Platform } from 'react-native';
+import { Host, Menu as SwiftUIMenu, Button as SwiftUIButton } from '@expo/ui/swift-ui';
+import { tint } from '@expo/ui/swift-ui/modifiers';
+import { useAccent } from './useTheme';
+import { Button, type SFSymbol } from './Button';
+
+export type MenuItem = {
+  label: string;
+  onPress?: () => void;
+  destructive?: boolean;
+  systemImage?: SFSymbol;
+};
+
+export type MenuProps = {
+  label: string;
+  systemImage?: SFSymbol;
+  items: MenuItem[];
+};
+
+/**
+ * Apple's own pull-down menu: a button that opens a list of actions.
+ */
+export function Menu({ label, systemImage, items }: MenuProps) {
+  const accent = useAccent();
+
+  if (Platform.OS !== 'ios') {
+    // ponytail: iOS-first product; Android lists the actions in a system alert.
+    return (
+      <Button
+        label={label}
+        variant="ghost"
+        onPress={() =>
+          RNAlert.alert(
+            label,
+            undefined,
+            items.map((item) => ({
+              text: item.label,
+              onPress: item.onPress,
+              style: item.destructive ? 'destructive' : 'default',
+            })),
+          )
+        }
+      />
+    );
+  }
+
+  return (
+    <Host matchContents>
+      <SwiftUIMenu label={label} systemImage={systemImage} modifiers={[tint(accent)]}>
+        {items.map((item) => (
+          <SwiftUIButton
+            key={item.label}
+            label={item.label}
+            systemImage={item.systemImage}
+            role={item.destructive ? 'destructive' : undefined}
+            onPress={item.onPress}
+          />
+        ))}
+      </SwiftUIMenu>
+    </Host>
+  );
+}

package/template/components/proto/Modal.tsx

@@ -1,6 +1,8 @@
-import { Modal as RNModal, View } from 'react-native';
+import { Modal as RNModal, Platform, View, useWindowDimensions } from 'react-native';
 import { SafeAreaView } from 'react-native-safe-area-context';
 import type { ReactNode } from 'react';
+import { BottomSheet, Group, Host, RNHostView } from '@expo/ui/swift-ui';
+import { presentationDragIndicator } from '@expo/ui/swift-ui/modifiers';
 import { useTheme } from './useTheme';
 import { Text } from './Text';
 
@@ -12,25 +14,45 @@ export type ModalProps = {
 };
 
 /**
- * Modal presented as iOS 26's native page sheet (UISheetPresentationController):
- * native spring-in, backdrop dim, the screen behind receding, and swipe-to-dismiss
- * — no hand-rolled overlay. onClose fires on both the swipe-dismiss (onRequestClose)
- * and programmatic close.
+ * Apple's own bottom sheet (SwiftUI `sheet` with a grabber), sized to its content.
+ * onClose fires on swipe-dismiss and on programmatic close.
  */
 export function Modal({ title, visible, onClose, children }: ModalProps) {
   const theme = useTheme();
+  const { width } = useWindowDimensions();
+
+  const body = (
+    // ponytail: the hosted RN view is measured in both axes, so it gets the window width by hand
+    // (sheets are edge to edge on iPhone; on iPad this over-measures and the sheet clips).
+    <View style={{ width, padding: theme.space.lg, paddingBottom: theme.space.xl, gap: theme.space.md }}>
+      <Text size="headline">{title}</Text>
+      {children}
+    </View>
+  );
+
+  if (Platform.OS === 'ios') {
+    return (
+      <Host matchContents>
+        <BottomSheet
+          isPresented={visible}
+          onIsPresentedChange={(open) => {
+            if (!open) onClose?.();
+          }}
+          fitToContents
+        >
+          <Group modifiers={[presentationDragIndicator('visible')]}>
+            <RNHostView matchContents>{body}</RNHostView>
+          </Group>
+        </BottomSheet>
+      </Host>
+    );
+  }
+
+  // ponytail: iOS-first product; Android keeps the page sheet.
   return (
-    <RNModal
-      visible={visible}
-      animationType="slide"
-      presentationStyle="pageSheet"
-      onRequestClose={onClose}
-    >
+    <RNModal visible={visible} animationType="slide" presentationStyle="pageSheet" onRequestClose={onClose}>
       <SafeAreaView style={{ flex: 1, backgroundColor: theme.surface.primary }} edges={['bottom']}>
-        <View style={{ flex: 1, padding: theme.space.lg, gap: theme.space.md }}>
-          <Text size="headline">{title}</Text>
-          {children}
-        </View>
+        {body}
       </SafeAreaView>
     </RNModal>
   );

package/template/components/proto/Picker.tsx

@@ -0,0 +1,57 @@
+import { Platform, Pressable } from 'react-native';
+import { Host, Picker as SwiftUIPicker, Text as SwiftUIText } from '@expo/ui/swift-ui';
+import { pickerStyle, tag, tint } from '@expo/ui/swift-ui/modifiers';
+import { useAccent, useTheme } from './useTheme';
+import { Row } from './Row';
+import { Text } from './Text';
+
+export type PickerVariant = 'segmented' | 'menu' | 'wheel';
+
+export type PickerProps = {
+  options: string[];
+  value: string;
+  onChange?: (value: string) => void;
+  label?: string;
+  variant?: PickerVariant;
+};
+
+/**
+ * Apple's own picker: segmented control by default, or a pull-down menu / wheel.
+ */
+export function Picker({ options, value, onChange, label, variant = 'segmented' }: PickerProps) {
+  const theme = useTheme();
+  const accent = useAccent();
+
+  if (Platform.OS === 'ios') {
+    return (
+      <Host style={{ alignSelf: 'stretch', height: variant === 'wheel' ? 200 : 36 }}>
+        <SwiftUIPicker
+          label={label}
+          selection={value}
+          onSelectionChange={(next) => onChange?.(String(next))}
+          modifiers={[pickerStyle(variant), tint(accent)]}
+        >
+          {options.map((option) => (
+            <SwiftUIText key={option} modifiers={[tag(option)]}>
+              {option}
+            </SwiftUIText>
+          ))}
+        </SwiftUIPicker>
+      </Host>
+    );
+  }
+
+  // ponytail: iOS-first product; Android shows a plain row of options.
+  return (
+    <Row gap={theme.space.md} align="center">
+      {label ? <Text size="body">{label}</Text> : null}
+      {options.map((option) => (
+        <Pressable key={option} onPress={() => onChange?.(option)}>
+          <Text size="label" color={option === value ? 'accent' : 'secondary'}>
+            {option}
+          </Text>
+        </Pressable>
+      ))}
+    </Row>
+  );
+}

package/template/components/proto/Row.tsx

@@ -1,5 +1,8 @@
 import { View, type ViewProps } from 'react-native';
-import type { ReactNode } from 'react';
+import { createContext, type ReactNode } from 'react';
+
+// Lets controls know they sit in a row, so they hug their content instead of filling the width.
+export const RowContext = createContext(false);
 
 export type RowProps = {
   gap?: number;
@@ -22,7 +25,7 @@ export function Row({ gap = 0, align = 'start', style, children }: RowProps) {
         style,
       ]}
     >
-      {children}
+      <RowContext.Provider value>{children}</RowContext.Provider>
     </View>
   );
 }

package/template/components/proto/Screen.tsx

@@ -1,10 +1,12 @@
 import { KeyboardAvoidingView, Platform, ScrollView, View } from 'react-native';
 import { SafeAreaView } from 'react-native-safe-area-context';
 import type { ReactNode } from 'react';
-import { useTheme } from './useTheme';
+import { LinearGradient } from 'expo-linear-gradient';
+import { useTheme, useAccent } from './useTheme';
 
 export type ScreenProps = {
   scrollable?: boolean;
+  gradient?: boolean | string;
   children?: ReactNode;
 };
 
@@ -21,10 +23,24 @@ export type ScreenProps = {
  * Background lives on the outermost element so it covers bounce / inset areas.
  * For Liquid Glass surfaces inside (cards, sheets), use Card with glass={true}
  * — it wraps expo-glass-effect's GlassView, iOS 26's native material.
+ *
+ * gradient: a light wash of the accent (or the given colour) rising from the bottom edge and
+ * fading out towards the top. Sits behind the content.
  */
-export function Screen({ scrollable = true, children }: ScreenProps) {
+export function Screen({ scrollable = true, gradient, children }: ScreenProps) {
   const theme = useTheme();
+  const accent = useAccent();
   const padding = theme.space.md;
+  const washColor = gradient === true ? accent : gradient;
+  // A 6-digit hex fades from its own zero-alpha; plain 'transparent' greys out mid-way.
+  const washStart = washColor && /^#[0-9a-f]{6}$/i.test(washColor) ? `${washColor}00` : 'transparent';
+  const wash = washColor ? (
+    <LinearGradient
+      pointerEvents="none"
+      colors={[washStart, washColor]}
+      style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, opacity: 0.1 }}
+    />
+  ) : null;
 
   if (scrollable) {
     return (
@@ -33,6 +49,7 @@ export function Screen({ scrollable = true, children }: ScreenProps) {
         contentContainerStyle={{ padding, gap: padding }}
         contentInsetAdjustmentBehavior="automatic"
       >
+        {wash}
         {children}
       </ScrollView>
     );
@@ -43,6 +60,7 @@ export function Screen({ scrollable = true, children }: ScreenProps) {
       style={{ flex: 1, backgroundColor: theme.surface.primary }}
       edges={['top', 'bottom', 'left', 'right']}
     >
+      {wash}
       <KeyboardAvoidingView
         style={{ flex: 1 }}
         behavior={Platform.OS === 'ios' ? 'padding' : undefined}

package/template/components/proto/index.ts

@@ -3,7 +3,7 @@ export { Stack, type StackProps } from './Stack';
 export { Row, type RowProps } from './Row';
 export { Text, type TextProps, type TextSize, type TextColor } from './Text';
 export { Card, type CardProps } from './Card';
-export { Button, type ButtonProps, type ButtonVariant } from './Button';
+export { Button, type ButtonProps, type ButtonVariant, type SFSymbol } from './Button';
 export { Toggle, type ToggleProps } from './Toggle';
 export { Slider, type SliderProps } from './Slider';
 export { Stepper, type StepperProps } from './Stepper';
@@ -11,6 +11,10 @@ export { Divider, type DividerProps } from './Divider';
 export { Input, type InputProps } from './Input';
 export { Lottie, type LottieProps } from './Lottie';
 export { Modal, type ModalProps } from './Modal';
+export { Picker, type PickerProps, type PickerVariant } from './Picker';
+export { DatePicker, type DatePickerProps, type DatePickerMode } from './DatePicker';
+export { Menu, type MenuProps, type MenuItem } from './Menu';
+export { Alert, type AlertProps, type AlertAction } from './Alert';
 export { useTheme, useAccent } from './useTheme';
 export { ProtoConfigProvider, useProtoConfig } from './ProtoConfigContext';
 export { mock } from './mock';

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

@@ -16,6 +16,7 @@ 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 };
+type LinksRequest = { id: number };
 
 // 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
@@ -23,7 +24,18 @@ type NavigateRequest = { id: number; path: string };
 function navigateTo(req: NavigateRequest) {
   let ok = false;
   try {
-    const { router } = require('expo-router') as { router: { navigate: (href: string) => void } };
+    const { router } = require('expo-router') as {
+      router: {
+        navigate: (href: string) => void;
+        canDismiss?: () => boolean;
+        dismissAll?: () => void;
+      };
+    };
+    // unwind the current stack first: navigating from a sheet to the screen
+    // under it pushed a second copy, and the flow walk (#89) wants each screen
+    // once, in its resting place. Only when there is something to dismiss: an
+    // unhandled POP_TO_TOP shows a red dev toast that lands in the screenshots.
+    if (router.canDismiss?.()) router.dismissAll?.();
     router.navigate(req.path);
     ok = true;
   } catch {
@@ -94,6 +106,137 @@ function inspectAt(view: View | null, req: InspectRequest) {
     // falls back to a label-only reference
   }
 }
+// Flow export (#89): every tappable on the mounted screen, with where it sits,
+// so the flow's arrows can start at the button. A `<Link href>` names its
+// target outright; a `router.push` inside an onPress can't be read here, so
+// its debug stack goes along and `proto flow` matches it to the source. Walks
+// the fiber tree from the renderer's roots (DevTools hook again), measures the
+// first host view under each candidate. Screens under the top one stay mounted
+// (a stack keeps its history, tabs keep every tab) and measure to the same
+// place, so `proto flow` keeps only the links whose source is the screen's own
+// file. Fails open: no answer = no anchors.
+type Fiber = DebugFiber & {
+  tag?: number;
+  memoizedProps?: { href?: unknown; onPress?: unknown } | null;
+  stateNode?: unknown;
+  child?: Fiber | null;
+  sibling?: Fiber | null;
+  return?: Fiber | null;
+  alternate?: Fiber | null;
+};
+type Hook = {
+  renderers: Map<number, Renderer>;
+  getFiberRoots?: (id: number) => Set<{ current: Fiber }>;
+};
+type Measurable = {
+  measureInWindow: (cb: (x: number, y: number, w: number, h: number) => void) => void;
+};
+type FoundLink = {
+  href?: string;
+  stacks: string[];
+  frame: { x: number; y: number; w: number; h: number };
+};
+const MAX_LINKS = 60;
+
+// Fabric keeps the public instance a level or two under the fiber's stateNode.
+function measurableOf(node: unknown): Measurable | null {
+  const sn = node as { canonical?: { publicInstance?: unknown }; publicInstance?: unknown } | null;
+  for (const c of [sn, sn?.canonical?.publicInstance, sn?.publicInstance]) {
+    if (c && typeof (c as Measurable).measureInWindow === 'function') return c as Measurable;
+  }
+  return null;
+}
+
+function hostViewOf(fiber: Fiber): Measurable | null {
+  for (let f: Fiber | null | undefined = fiber, i = 0; f && i < 8; f = f.child, i++) {
+    if (f.tag === 5) return measurableOf(f.stateNode);
+  }
+  return null;
+}
+
+function collectLinks(req: LinksRequest) {
+  const post = (links: FoundLink[]) =>
+    fetch('http://127.0.0.1:3001/links/result', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id: req.id, links }),
+    }).catch(() => {});
+  try {
+    const hook = (globalThis as { __REACT_DEVTOOLS_GLOBAL_HOOK__?: Hook })
+      .__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    if (!hook) {
+      void post([]);
+      return;
+    }
+    const { width, height } = Dimensions.get('window');
+    const candidates: { fiber: Fiber; href?: string }[] = [];
+    const seen = new Set<unknown>();
+    for (const id of hook.renderers.keys()) {
+      for (const root of hook.getFiberRoots?.(id) ?? []) {
+        const stack: Fiber[] = [root.current];
+        while (stack.length && candidates.length < MAX_LINKS) {
+          const f = stack.pop() as Fiber;
+          const props = f.memoizedProps;
+          const href =
+            typeof props?.href === 'string' && props.href.startsWith('/') ? props.href : undefined;
+          if (href || typeof props?.onPress === 'function') {
+            // the same onPress rides down Button → Pressable → host; keep the outermost
+            const key = href ?? props?.onPress;
+            if (!seen.has(key)) {
+              seen.add(key);
+              candidates.push({ fiber: f, href });
+            }
+          }
+          if (f.sibling) stack.push(f.sibling);
+          if (f.child) stack.push(f.child);
+        }
+      }
+    }
+    const measured = candidates.map(
+      (c) =>
+        new Promise<FoundLink | null>((resolve) => {
+          const host = hostViewOf(c.fiber);
+          if (!host) return resolve(null);
+          const measure = () => new Promise<number[]>((r) => host.measureInWindow((...m) => r(m)));
+          // measured twice, a beat apart: a frame still moving (a sheet being
+          // dismissed, a screen scaling back) is not a place to anchor an arrow
+          void (async () => {
+            const a = await measure();
+            await new Promise((r) => setTimeout(r, 200));
+            const b = await measure();
+            if (a.some((v, i) => Math.abs(v - (b[i] ?? 0)) > 1)) return resolve(null);
+            const [x, y, w, h] = b as [number, number, number, number];
+            if (!(w > 0 && h > 0) || y + h <= 0 || y >= height) return resolve(null); // off screen
+            const stacks: string[] = [];
+            let fiber: DebugFiber | null | undefined = c.fiber;
+            for (let i = 0; fiber && i < 12; i++) {
+              const s = fiber._debugStack?.stack;
+              if (typeof s === 'string') stacks.push(s);
+              fiber = fiber._debugOwner;
+            }
+            // clipped to the screen: a card half below the fold anchors at its visible part
+            const [x0, y0, x1, y1] = [
+              Math.max(0, x),
+              Math.max(0, y),
+              Math.min(width, x + w),
+              Math.min(height, y + h),
+            ];
+            resolve({
+              ...(c.href ? { href: c.href } : {}),
+              stacks,
+              frame: { x: x0 / width, y: y0 / height, w: (x1 - x0) / width, h: (y1 - y0) / height },
+            });
+          })();
+        }),
+    );
+    const timeout = new Promise<null>((r) => setTimeout(() => r(null), 1200));
+    void Promise.all(measured.map((m) => Promise.race([m, timeout]))).then((links) =>
+      post(links.filter((l): l is FoundLink => l !== null)),
+    );
+  } catch {
+    void post([]);
+  }
+}
 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
@@ -117,6 +260,7 @@ export default function TouchDots({ children }: { children: ReactNode }) {
   const rootRef = useRef<View>(null);
   const inspected = useRef(0);
   const navigated = useRef(0);
+  const linked = useRef(0);
 
   // Poll `proto start`'s local server for the record flag (the Simulator
   // shares the host loopback). Any failure just means "not recording".
@@ -130,6 +274,7 @@ export default function TouchDots({ children }: { children: ReactNode }) {
           recording?: boolean;
           inspect?: InspectRequest;
           navigate?: NavigateRequest;
+          links?: LinksRequest;
         };
         if (!alive) return;
         setRecording(body.recording === true);
@@ -141,6 +286,10 @@ export default function TouchDots({ children }: { children: ReactNode }) {
           navigated.current = body.navigate.id;
           navigateTo(body.navigate);
         }
+        if (body.links && body.links.id !== linked.current) {
+          linked.current = body.links.id;
+          collectLinks(body.links);
+        }
       } catch {
         if (alive) setRecording(false);
       }

package/template/gitignore

@@ -3,6 +3,7 @@ node_modules/
 .metro-cache/
 .proto/last-shot.png
 .proto/metro-errors.json
+.proto/metro-reset
 .proto/tsconfig.mcp.json
 dist/
 *.log

package/template/pnpm-workspace.yaml

@@ -1,3 +1,5 @@
 node-linker: hoisted
 allowBuilds:
   cloudflared: true
+minimumReleaseAgeExclude:
+  - '@sherizan/proto-cli'