waypoint-expo-template 1.0.0 → 2.0.0

package/README.md

@@ -1,68 +1,31 @@
 # waypoint-expo-template
 
-The Expo/React Native preview-app scaffold code-builders' `coder` specialist
-bootstraps every new app from. Published to npm as `waypoint-expo-template`;
-a `bootstrap_app_cli` `run_tool` call in the sandbox does `npm pack
-waypoint-expo-template@latest`, extracts the tarball into `/workspace`,
-substitutes the app's name, and runs `npm install` — real npm install of
-this package's own dependencies, not a copied file tree.
+The Expo app that `bootstrap_app_cli` installs into a fresh workspace. It is a
+`create-expo-app` scaffold, reduced to the smallest thing that renders inside a
+Waypoint device-preview tile.
 
-## Why this exists
-
-The `coder` specialist has no shell — it cannot run `create-expo-app` or
-`npx expo install` itself. This package **is** the output of those real
-commands (`npx create-expo-app@latest --template blank-typescript`, then
-`npx expo install react-dom react-native-web @expo/metro-runtime`), so the
-agent gets a genuinely correct, currently-supported Expo SDK 57 scaffold
-without needing to run anything — and without anyone hand-picking dependency
-versions, which is how a real session once shipped an incompatible set and
-crashed Metro on startup.
-
-Two things are added on top of the stock Expo output — the minimum needed
-for this platform's preview canvas, not a rewrite of it:
-
-- `src/lib/previewBridge.ts` — the postMessage IPC contract with the canvas
-  host (not something `create-expo-app` produces).
-- `App.tsx` calls `reportRoutes(buildRouteManifest(...))` on mount and hard-
-  fails on an unrecognized route, instead of silently rendering a fallback
-  screen — both verified, live, to be the difference between a working
-  preview and one that renders the same screen for every route with the
-  canvas showing no navigation edges at all.
-
-Everything else — `package.json`, `app.json`, `index.ts`, `tsconfig.json`,
-`assets/` — is unmodified `create-expo-app` output.
-
-## What you get after bootstrapping
+## What is here
 
 ```
-package.json            # name substituted to the app's own name
-app.json                # expo.name/expo.slug substituted; web.output: "single"
-index.ts                # @expo/metro-runtime imported first (required for HMR)
-tsconfig.json
-assets/                 # Expo's default icon set
-App.tsx                 # single "home" route; add cases as screens are added
-src/
-  lib/previewBridge.ts  # host protocol — only buildRouteManifest() should change
-  screens/
-    HomeScreen.tsx       # replace with real content
-    HomeScreen.preview.md
+src/app/_layout.tsx    plain Stack, headers off
+src/app/index.tsx      the entry screen — `/` by expo-router convention
+src/navigation.ts      which control leads where (links only)
 ```
 
-From there, the agent writes the app's actual business logic — screens,
-ports, navigation — following the `expo-app` and `workflow-preview` skills.
+## What is deliberately NOT here
 
-## Publishing
+No preview manifests, no compile step, no canvas protocol module, and no
+declared screen list or control coordinates.
 
-CI publishes automatically (`.github/workflows/expo-template.yml`) on every
-push to `main` that touches this package, whenever `package.json`'s version
-differs from what's on npm — bump the version and push; no manual publish
-step, and the bootstrap tool always resolves whatever is currently tagged
-`latest`, so it never needs a code change when a new version ships.
+The preview canvas derives its flow graph itself: screens come from the route
+files under `src/app`, positions are measured from the running app, and button
+presses are observed directly because the preview iframe is same-origin. The
+app is just an app. See ADR-039.
 
-To test a change locally before pushing:
+## Adding a screen
 
-```
-cd packages/expo-template
-npm install
-npx tsc --noEmit
-```
+1. `src/app/<name>.tsx` — put a `testID` on every control that navigates
+2. add a `links` entry in `src/navigation.ts` for each of those controls
+3. `npx tsc --noEmit`
+
+There is no step 4. Nothing to compile, nothing to regenerate.

package/app.json

@@ -1,26 +1,42 @@
 {
   "expo": {
-    "name": "expo-template",
-    "slug": "expo-template",
+    "name": "waypoint-expo-template",
+    "slug": "waypoint-expo-template",
     "version": "1.0.0",
     "orientation": "portrait",
-    "icon": "./assets/icon.png",
-    "userInterfaceStyle": "light",
+    "icon": "./assets/images/icon.png",
+    "scheme": "waypointexpotemplate",
+    "userInterfaceStyle": "automatic",
     "ios": {
-      "supportsTablet": true
+      "icon": "./assets/expo.icon"
     },
     "android": {
       "adaptiveIcon": {
         "backgroundColor": "#E6F4FE",
-        "foregroundImage": "./assets/android-icon-foreground.png",
-        "backgroundImage": "./assets/android-icon-background.png",
-        "monochromeImage": "./assets/android-icon-monochrome.png"
+        "foregroundImage": "./assets/images/android-icon-foreground.png",
+        "backgroundImage": "./assets/images/android-icon-background.png",
+        "monochromeImage": "./assets/images/android-icon-monochrome.png"
       },
       "predictiveBackGestureEnabled": false
     },
     "web": {
-      "favicon": "./assets/favicon.png",
-      "output": "single"
+      "output": "static",
+      "favicon": "./assets/images/favicon.png"
+    },
+    "plugins": [
+      "expo-router",
+      [
+        "expo-splash-screen",
+        {
+          "backgroundColor": "#208AEF",
+          "image": "./assets/images/splash-icon.png",
+          "imageWidth": 76
+        }
+      ]
+    ],
+    "experiments": {
+      "typedRoutes": true,
+      "reactCompiler": true
     }
   }
 }

package/assets/expo.icon/Assets/expo-symbol 2.svg

@@ -0,0 +1,3 @@
+<svg width="652" height="606" viewBox="0 0 652 606" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M353.554 0H298.446C273.006 0 249.684 14.6347 237.962 37.9539L4.37994 502.646C-1.04325 513.435 -1.45067 526.178 3.2716 537.313L22.6123 582.918C34.6475 611.297 72.5404 614.156 88.4414 587.885L309.863 222.063C313.34 216.317 319.439 212.826 326 212.826C332.561 212.826 338.659 216.317 342.137 222.063L563.559 587.885C579.46 614.156 617.352 611.297 629.388 582.918L648.728 537.313C653.451 526.178 653.043 513.435 647.62 502.646L414.038 37.9539C402.316 14.6347 378.994 0 353.554 0Z" fill="white"/>
+</svg>

package/assets/expo.icon/icon.json

@@ -0,0 +1,40 @@
+{
+  "fill" : {
+    "automatic-gradient" : "extended-srgb:0.00000,0.47843,1.00000,1.00000"
+  },
+  "groups" : [
+    {
+      "layers" : [
+        {
+          "image-name" : "expo-symbol 2.svg",
+          "name" : "expo-symbol 2",
+          "position" : {
+            "scale" : 1,
+            "translation-in-points" : [
+              1.1008400065293245e-05,
+              -16.046875
+            ]
+          }
+        },
+        {
+          "image-name" : "grid.png",
+          "name" : "grid"
+        }
+      ],
+      "shadow" : {
+        "kind" : "neutral",
+        "opacity" : 0.5
+      },
+      "translucency" : {
+        "enabled" : true,
+        "value" : 0.5
+      }
+    }
+  ],
+  "supported-platforms" : {
+    "circles" : [
+      "watchOS"
+    ],
+    "squares" : "shared"
+  }
+}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "waypoint-expo-template",
-  "version": "1.0.0",
-  "description": "Expo preview-app scaffold for code-builders' coder specialist — bootstrapped into a fresh sandbox workspace via npm, not vendored/copied. See src/lib/previewBridge.ts and App.tsx for the Waypoint-specific host IPC wiring; everything else is unmodified `create-expo-app --template blank-typescript` output plus the web-enablement packages `npx expo install` adds.",
-  "main": "index.ts",
-  "publishConfig": {
-    "access": "public"
-  },
+  "main": "expo-router/entry",
+  "version": "2.0.0",
   "dependencies": {
-    "@expo/metro-runtime": "~57.0.15",
-    "expo": "~57.0.20",
+    "expo": "~57.0.21",
+    "expo-constants": "~57.0.17",
+    "expo-font": "~57.0.3",
+    "expo-linking": "~57.0.9",
+    "expo-router": "~57.0.20",
+    "expo-splash-screen": "~57.0.8",
     "expo-status-bar": "~57.0.1",
+    "expo-system-ui": "~57.0.3",
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "react-native": "0.86.3",
-    "react-native-web": "^0.21.2"
+    "react-native-safe-area-context": "~5.7.0",
+    "react-native-screens": "~4.26.0",
+    "react-native-web": "~0.21.0"
   },
   "devDependencies": {
     "@types/react": "~19.2.2",
@@ -23,7 +26,7 @@
     "start": "expo start",
     "android": "expo start --android",
     "ios": "expo start --ios",
-    "web": "expo start --web",
-    "compile": "node scripts/compile-preview.js"
-  }
+    "web": "expo start --web"
+  },
+  "description": "Expo app template for Waypoint app previews."
 }

package/src/app/_layout.tsx

@@ -0,0 +1,16 @@
+import { Stack } from 'expo-router';
+
+/**
+ * A plain Stack, deliberately.
+ *
+ * `create-expo-app` scaffolds a tab layout. A tab bar is wrong here: every
+ * screen is rendered inside a device-preview tile on the canvas, and a
+ * persistent tab bar would appear in all of them and offer a second way to
+ * navigate that the flow graph knows nothing about.
+ *
+ * `headerShown: false` for the same reason — the canvas labels each tile
+ * itself, so a header would be a duplicate title inside the device frame.
+ */
+export default function RootLayout() {
+  return <Stack screenOptions={{ headerShown: false }} />;
+}

package/src/app/index.tsx

@@ -0,0 +1,22 @@
+import { StyleSheet, Text, View } from 'react-native';
+
+/**
+ * The entry screen — `src/app/index.tsx` is `/` by expo-router's own
+ * convention, which is also how the preview canvas knows it is the flow's
+ * starting point. Nothing declares that.
+ *
+ * Replace this with the real first screen. Put a `testID` on any control that
+ * navigates, and declare where it leads in `src/navigation.ts`.
+ */
+export default function Index() {
+  return (
+    <View style={styles.container} testID="screen-index">
+      <Text style={styles.text}>Home</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, alignItems: 'center', justifyContent: 'center', backgroundColor: '#ffffff' },
+  text: { fontSize: 18 },
+});

package/src/navigation.ts

@@ -0,0 +1,34 @@
+/**
+ * Which control leads where — and nothing else.
+ *
+ * The screens themselves are NOT declared here. With file-based routing they
+ * are the files under `src/app`: `index.tsx` is `/`, `settings.tsx` is
+ * `/settings`, and the preview canvas reads that directly. Writing the list
+ * down again would create a second copy that can disagree with the first.
+ *
+ * What the filesystem cannot show is which button leads where — that lives
+ * inside a handler, and `router.push('/settings')` behind an async call is
+ * not something anything can read statically. This file is that missing edge.
+ *
+ * Each entry:
+ *   from  the screen the control is on   (its route id: `/` is `index`,
+ *                                         `/user/settings` is `user-settings`)
+ *   via   the control's `testID`         (must match the prop in the component)
+ *   to    the screen it leads to
+ *   label optional; names the edge on the canvas
+ *
+ * Declare links in the direction the user travels, INCLUDING back. A link
+ * returning to an earlier screen is written plainly — the canvas materializes
+ * the return frame itself. Do not add a duplicate "return" screen for it.
+ *
+ * Never declare where a control sits. Positions are measured from the running
+ * app, so restyling a button needs no change here.
+ */
+export const links: Array<{
+  from: string;
+  via: string;
+  to: string;
+  label?: string;
+}> = [
+  // { from: 'index', via: 'btn-open-settings', to: 'settings', label: 'Open settings' },
+];

package/tsconfig.json

@@ -1,6 +1,20 @@
 {
   "extends": "expo/tsconfig.base",
   "compilerOptions": {
-    "strict": true
-  }
+    "strict": true,
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ],
+      "@/assets/*": [
+        "./assets/*"
+      ]
+    }
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    ".expo/types/**/*.ts",
+    "expo-env.d.ts"
+  ]
 }

package/App.tsx

@@ -1,61 +0,0 @@
-import { useState, useEffect } from 'react';
-import { StyleSheet, View } from 'react-native';
-import { StatusBar } from 'expo-status-bar';
-import { getAppParams, onHostMessage, postToHost, buildRouteManifest, reportRoutes, type HostMessage } from './src/lib/previewBridge';
-import { HomeScreen } from './src/screens/HomeScreen';
-
-// Add each new screen's id here as you create one (see src/lib/previewBridge.ts
-// and the workflow-preview skill for the accompanying *.preview.md manifest).
-type ScreenRoute = 'home';
-
-export default function App() {
-  const [params] = useState(() => getAppParams());
-  const initialRoute = (params.route?.replace(/^\//, '') || 'home') as ScreenRoute;
-  const [currentScreen, setCurrentScreen] = useState<ScreenRoute>(initialRoute);
-
-  useEffect(() => {
-    postToHost({ type: 'expo-app:ready', appId: params.appId ?? undefined });
-    // Required — without this the preview canvas falls back to a static
-    // source scan that cannot see this navigation pattern's links and
-    // derives differently-cased route paths from screen filenames. Keep
-    // this call as you add screens; only buildRouteManifest() itself needs
-    // editing.
-    reportRoutes(buildRouteManifest(params.appId));
-    return onHostMessage((message: HostMessage) => {
-      if (message.type === 'expo-app:navigate' && typeof message.route === 'string') {
-        setCurrentScreen(message.route.replace(/^\//, '') as ScreenRoute);
-      }
-    });
-  }, [params]);
-
-  // Navigation helper — updates state AND notifies host.
-  const navigateTo = (screen: ScreenRoute) => {
-    setCurrentScreen(screen);
-    postToHost({ type: 'expo-app:navigation-change', route: `/${screen}` });
-  };
-
-  const renderScreen = () => {
-    switch (currentScreen) {
-      case 'home':
-        return <HomeScreen />;
-      default:
-        // Hard fail — never silently render a fallback screen for an
-        // unmatched route. A route reaching here is a real bug (a case is
-        // missing for a route reportRoutes/navigateTo/the host actually
-        // named) and must surface immediately, not render an unrelated
-        // screen with no visible error.
-        throw new Error(`Unhandled ScreenRoute: "${currentScreen}" — no case in App.tsx's renderScreen() switch.`);
-    }
-  };
-
-  return (
-    <View style={styles.container}>
-      <StatusBar style="auto" />
-      {renderScreen()}
-    </View>
-  );
-}
-
-const styles = StyleSheet.create({
-  container: { flex: 1, backgroundColor: '#ffffff' },
-});

package/index.ts

@@ -1,13 +0,0 @@
-// Must be the first import — pulls Metro's Fast Refresh client into the web
-// bundle. Without it the bundle contains no HMR client at all and edits
-// never reach the running preview (verified: the bundle grows measurably
-// and gains an HMRClient once this import is present).
-import '@expo/metro-runtime';
-import { registerRootComponent } from 'expo';
-
-import App from './App';
-
-// registerRootComponent calls AppRegistry.registerComponent('main', () => App);
-// It also ensures that whether you load the app in Expo Go or in a native build,
-// the environment is set up appropriately
-registerRootComponent(App);

package/preview.json

@@ -1,42 +0,0 @@
-{
-  "name": "waypoint-expo-template-workflow",
-  "version": "1",
-  "preset": "iphone-16-pro",
-  "nodes": [
-    {
-      "id": "preview-home",
-      "type": "devicePreview",
-      "position": {
-        "x": 0,
-        "y": 0
-      },
-      "data": {
-        "type": "devicePreview",
-        "route": "/home",
-        "label": "Home",
-        "isInitial": true,
-        "presetId": "iphone-16-pro",
-        "hideControls": true,
-        "actionPorts": [],
-        "action": {
-          "after": [
-            {
-              "stepId": "await-nav-home",
-              "actionType": "step/await-navigation",
-              "semantics": {
-                "label": "Await navigation from Home",
-                "description": "Pause and wait for user to trigger a navigation event from this screen"
-              },
-              "config": {
-                "screenId": "home",
-                "route": "/home"
-              }
-            }
-          ]
-        },
-        "apiCalls": []
-      }
-    }
-  ],
-  "edges": []
-}