waypoint-expo-template 1.0.0 → 2.1.0

package/README.md

@@ -1,68 +1,45 @@
 # 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
+## What is here
 
-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.
+```
+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)
 
-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:
+platform/              platform-owned — do not edit
+app.config.js          two lines; delegates to platform/
+```
 
-- `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.
+`platform/` holds the files the platform maintains, not you. Today that is the
+base URL: the preview is embedded in the control plane under
+`/api/v1/preview/<appId>/`, and expo-router matches routes against the
+browser's pathname, so it has to be told that prefix or every screen renders
+"Unmatched Route". It comes from `EXPO_BASE_URL`, set when the platform starts
+Metro — unset (running the app yourself) the base is empty and it serves at the
+root, as normal.
 
-Everything else — `package.json`, `app.json`, `index.ts`, `tsconfig.json`,
-`assets/` — is unmodified `create-expo-app` output.
+`app.config.js` has to sit at the root because Expo resolves its dynamic config
+from `<projectRoot>/app.config` and nowhere else. It contains no logic.
 
-## What you get after bootstrapping
+## What is deliberately NOT 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
-```
+No preview manifests, no compile step, no canvas protocol module, and no
+declared screen list or control coordinates.
 
-From there, the agent writes the app's actual business logic — screens,
-ports, navigation — following the `expo-app` and `workflow-preview` skills.
+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.
 
-## Publishing
+## Adding a screen
 
-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.
+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`
 
-To test a change locally before pushing:
-
-```
-cd packages/expo-template
-npm install
-npx tsc --noEmit
-```
+There is no step 4. Nothing to compile, nothing to regenerate.

package/app.config.js

@@ -0,0 +1,10 @@
+// Expo resolves its dynamic config from `<projectRoot>/app.config` and nowhere
+// else — @expo/config's getDynamicConfigFilePath does
+// `resolveFrom(projectRoot, './app.config')`. So this file cannot live in
+// platform/; it stays here as the entry point Expo requires, and holds no
+// logic of its own.
+//
+// Everything the platform maintains is in platform/. Do not edit either.
+const { withPlatformBaseUrl } = require('./platform/base-url');
+
+module.exports = ({ config }) => withPlatformBaseUrl(config);

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.1.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/platform/base-url.js

@@ -0,0 +1,53 @@
+/**
+ * The subpath this app is served under, when the platform is serving it.
+ *
+ * WHY THIS EXISTS
+ *
+ * The preview is embedded in the control plane as a SAME-ORIGIN iframe
+ * (ADR-033), served under `/api/v1/preview/<appId>/`. Same-origin is not
+ * incidental: the canvas reads this app's DOM directly to measure controls,
+ * observe presses and detect readiness (ADR-039), and all three throw across
+ * origins. So the app cannot be given its own origin to escape the prefix —
+ * it has to be told the prefix instead.
+ *
+ * expo-router resolves routes against `window.location.pathname`. Without a
+ * base it compares that whole prefixed path against the route files and
+ * matches nothing, so EVERY screen — the entry one included — renders
+ * "Unmatched Route". Verified live before this existed.
+ *
+ * ON `experiments`
+ *
+ * `experiments.baseUrl` is Expo's only mechanism for subpath hosting, and it
+ * is typed and documented in @expo/config-types ("Export a website relative
+ * to a subpath of a domain"). This project already depends on that namespace
+ * — `typedRoutes` in app.json — which in Expo is a grab-bag of build-pipeline
+ * flags rather than a staging area.
+ *
+ * The exposure is a rename on an SDK upgrade. The symptom is unmistakable
+ * (every route renders "Unmatched Route") and the fix is this one field;
+ * check @expo/config-types' ExpoConfig for where it moved.
+ */
+
+/**
+ * Empty unless the platform set it. An app run directly (`npm run web`) has
+ * no prefix and serves at the origin root, which is what an empty base means.
+ * The variable is set by the harness when it starts Metro, from the pod's own
+ * app id — never written into the workspace, because the base URL is a
+ * deployment fact the platform owns and app.json belongs to you.
+ */
+function resolveBaseUrl() {
+  return process.env.EXPO_BASE_URL || '';
+}
+
+/** Applies the base to an Expo config, leaving everything else untouched. */
+function withPlatformBaseUrl(config) {
+  return {
+    ...config,
+    experiments: {
+      ...config.experiments,
+      baseUrl: resolveBaseUrl(),
+    },
+  };
+}
+
+module.exports = { resolveBaseUrl, withPlatformBaseUrl };

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": []
-}