waypoint-expo-template 1.0.0

package/App.tsx

@@ -0,0 +1,61 @@
+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/README.md

@@ -0,0 +1,68 @@
+# 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.
+
+## 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
+
+```
+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
+```
+
+From there, the agent writes the app's actual business logic — screens,
+ports, navigation — following the `expo-app` and `workflow-preview` skills.
+
+## Publishing
+
+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.
+
+To test a change locally before pushing:
+
+```
+cd packages/expo-template
+npm install
+npx tsc --noEmit
+```

package/app.json

@@ -0,0 +1,26 @@
+{
+  "expo": {
+    "name": "expo-template",
+    "slug": "expo-template",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./assets/icon.png",
+    "userInterfaceStyle": "light",
+    "ios": {
+      "supportsTablet": true
+    },
+    "android": {
+      "adaptiveIcon": {
+        "backgroundColor": "#E6F4FE",
+        "foregroundImage": "./assets/android-icon-foreground.png",
+        "backgroundImage": "./assets/android-icon-background.png",
+        "monochromeImage": "./assets/android-icon-monochrome.png"
+      },
+      "predictiveBackGestureEnabled": false
+    },
+    "web": {
+      "favicon": "./assets/favicon.png",
+      "output": "single"
+    }
+  }
+}

package/index.ts

@@ -0,0 +1,13 @@
+// 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/package.json

@@ -0,0 +1,29 @@
+{
+  "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"
+  },
+  "dependencies": {
+    "@expo/metro-runtime": "~57.0.15",
+    "expo": "~57.0.20",
+    "expo-status-bar": "~57.0.1",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-native": "0.86.3",
+    "react-native-web": "^0.21.2"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.2",
+    "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "start": "expo start",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "web": "expo start --web",
+    "compile": "node scripts/compile-preview.js"
+  }
+}

package/preview.json

@@ -0,0 +1,42 @@
+{
+  "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": []
+}

package/scripts/compile-preview.js

@@ -0,0 +1,599 @@
+#!/usr/bin/env node
+
+/**
+ * compile-preview.js
+ *
+ * Generic compiler script that consolidates co-located *.preview.md files
+ * from src/screens into:
+ *   1. preview.json - UI Preview graph for ReactFlow / Storybook canvas
+ *   2. workflow.md  - Standard Workflow DSL that compiles cleanly with workflow-engine CLI
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import { execSync } from 'child_process';
+
+const require = createRequire(path.join(process.cwd(), 'package.json'));
+let yaml;
+try {
+  yaml = require('js-yaml');
+} catch {
+  try {
+    const rootRequire = createRequire(path.resolve(process.cwd(), '..', '..', 'package.json'));
+    yaml = rootRequire('js-yaml');
+  } catch {
+    const engineRequire = createRequire(path.resolve(process.cwd(), '..', '..', 'packages', 'workflow-engine', 'package.json'));
+    yaml = engineRequire('js-yaml');
+  }
+}
+
+const PROJECT_ROOT = process.cwd();
+const SCREENS_DIR = path.join(PROJECT_ROOT, 'src', 'screens');
+const PREVIEW_JSON_FILE = path.join(PROJECT_ROOT, 'preview.json');
+const WORKFLOW_MD_FILE = path.join(PROJECT_ROOT, 'workflow.md');
+
+// Potential workflow-engine CLI locations. The sandbox image bakes the CLI
+// at $HARNESS_TOOLS_BIN_DIR/cli.cjs (see code-builders/harness/Dockerfile) —
+// checked first since that's the only candidate that actually exists inside
+// a sandbox pod; the monorepo-relative candidates only resolve when this
+// script runs from a real checkout (e.g. local dev outside the container).
+const WORKFLOW_ENGINE_CLI_CANDIDATES = [
+  ...(process.env.HARNESS_TOOLS_BIN_DIR
+    ? [path.join(process.env.HARNESS_TOOLS_BIN_DIR, 'cli.cjs')]
+    : []),
+  path.resolve(PROJECT_ROOT, '..', '..', 'packages', 'workflow-engine', 'bin', 'cli.cjs'),
+  path.resolve(PROJECT_ROOT, '..', '..', '..', 'waypoint', 'packages', 'workflow-engine', 'bin', 'cli.cjs'),
+  path.resolve(PROJECT_ROOT, 'node_modules', 'workflow-engine', 'bin', 'cli.cjs'),
+];
+
+const PRESET = {
+  id: 'iphone-16-pro',
+  width: 393,
+  height: 852,
+};
+
+function getAppName() {
+  const pkgPath = path.join(PROJECT_ROOT, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      if (pkg.name) return pkg.name;
+    } catch {}
+  }
+  return path.basename(PROJECT_ROOT);
+}
+
+function extractYamlBlock(content) {
+  const match = content.match(/```(?:yaml|yml)\s*([\s\S]*?)\s*```/) || content.match(/```json\s*([\s\S]*?)\s*```/);
+  if (!match) {
+    throw new Error('No ```yaml or ```json block found in preview manifest');
+  }
+  return yaml.load(match[1]);
+}
+
+function buildWorkflowDsl(appName, manifests) {
+  const initialScreen = manifests.find((m) => m.isInitial) || manifests[0];
+  const wfId = `WF-${appName.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+
+  const states = [];
+  const transitions = [];
+
+  // A first screen with no authored transitions (typically the only screen)
+  // still needs a non-terminal state to act as the workflow's entry point.
+  // Emitting it as terminal-only leaves nothing to transition *from*, which
+  // fails validation three ways at once: no Human-owned transition (WF0226),
+  // the declared capability unused (WF0216), and state-abandoned connected to
+  // nothing (ORPHANED_NODE). So it gets both an entry state and a completion
+  // state, joined by the outcome transition emitted further down.
+  const initialIsTerminal = !initialScreen.transitions || initialScreen.transitions.length === 0;
+
+  // Single source of truth for "what is screen X's state called?".
+  //
+  // The state loop below names a terminal screen `state-<id>-complete` and a
+  // non-terminal one `state-<id>`. Transition targets must use the identical
+  // rule or they point at states that were never emitted. This previously
+  // special-cased the literal screen id `home` — so `home` resolved correctly
+  // and every *other* terminal destination silently did not, producing
+  // WF0222 / EDGE_MISSING_TARGET / ORPHANED_NODE the moment someone added a
+  // terminal screen by any other name. Terminality is a property of the
+  // manifest (does it declare transitions?), never of the screen's name, so
+  // it is derived here and nowhere else.
+  const manifestById = new Map(manifests.map((m) => [m.id, m]));
+  const resolveTargetState = (targetId) => {
+    if (targetId === 'abandoned') return 'state-abandoned';
+    const target = manifestById.get(targetId);
+    // Unknown ids are left in the `state-<id>` form so the workflow-engine
+    // CLI reports the dangling reference against a name the author wrote,
+    // rather than one this compiler invented.
+    if (!target) return `state-${targetId}`;
+    // The initial screen, when terminal, has both an entry and a completion
+    // state; anything navigating *to* it means the entry state.
+    if (initialIsTerminal && target.id === initialScreen.id) return `state-${targetId}`;
+    const targetIsTerminal = !target.transitions || target.transitions.length === 0;
+    return targetIsTerminal ? `state-${targetId}-complete` : `state-${targetId}`;
+  };
+
+  for (const m of manifests) {
+    const isTerminal = !m.transitions || m.transitions.length === 0;
+    if (initialIsTerminal && m.id === initialScreen.id) {
+      states.push({ id: `state-${m.id}`, label: m.label, terminal: false });
+      states.push({ id: `state-${m.id}-complete`, label: `${m.label} Complete`, terminal: true });
+    } else {
+    states.push({
+      id: isTerminal ? `state-${m.id}-complete` : `state-${m.id}`,
+      label: isTerminal ? `${m.label} Complete` : m.label,
+      terminal: isTerminal,
+    });
+    }
+
+    for (const t of m.transitions || []) {
+      if (t.condition) {
+        const cond = t.condition;
+        const options = (t.branches || []).map((b) => ({
+          label: b.label,
+          value: b.label.toLowerCase().replace(/\s+/g, '_'),
+          target: resolveTargetState(b.to),
+        }));
+
+        transitions.push({
+          id: `transition-${cond.id.replace(/^cond-/, '')}`,
+          label: cond.label || cond.id,
+          owner: 'Human',
+          type: 'human',
+          from: `state-${m.id}`,
+          to: options.map((o) => o.target),
+          capabilities: ['CAP-001'],
+          actions: [
+            {
+              action_type: 'step/ask-user',
+              semantics: {
+                label: cond.label || cond.id,
+                description: cond.description || `Evaluate ${cond.label || cond.id}`,
+              },
+              config: {
+                questions: [
+                  {
+                    id: cond.id.replace(/^cond-/, ''),
+                    text: cond.label || cond.id,
+                    type: 'confirm',
+                    options,
+                  },
+                ],
+              },
+            },
+          ],
+        });
+      } else if (t.to) {
+        const targetId = resolveTargetState(t.to);
+        transitions.push({
+          id: `transition-${m.id}-${t.to}`,
+          label: `${m.label} to ${t.to}`,
+          owner: 'Human',
+          type: 'human',
+          from: `state-${m.id}`,
+          to: [targetId],
+          capabilities: ['CAP-001'],
+          actions: [
+            {
+              action_type: 'step/ask-user',
+              semantics: {
+                label: t.label || `Navigate to ${t.to}`,
+                description: `Proceed from ${m.label} to ${t.to}`,
+              },
+              config: {
+                questions: [
+                  {
+                    id: `${m.id}_to_${t.to}`,
+                    text: `Proceed from ${m.label} to ${t.to}?`,
+                    type: 'confirm',
+                  },
+                ],
+              },
+            },
+          ],
+        });
+      }
+    }
+  }
+
+  states.push({
+    id: 'state-abandoned',
+    label: 'Onboarding Failed',
+    terminal: true,
+  });
+
+  // state-abandoned always exists (WF0205 blocks on a missing failure
+  // terminal state), but the synthetic transition *into* it is only valid
+  // in some shapes:
+  //
+  //  - Initial screen had no authored transitions: the old code emitted
+  //    `from: state-<id>` while the state loop had named that state
+  //    `state-<id>-complete`, so the transition referenced a state that did
+  //    not exist -> WF0221 TRANSITION_BAD_FROM_STATE / EDGE_MISSING_SOURCE.
+  //    Simply renaming it would not help, because a terminal state may not
+  //    have outgoing edges (TERMINAL_STATE_HAS_OUTGOING). The state loop
+  //    above now emits a non-terminal entry state for this case, and the
+  //    branch below routes it to completion or abandonment.
+  //  - A manifest already routes to `abandoned` itself. The known-good
+  //    reference app (uds/references/expo-preview-app) works exactly this
+  //    way: its Welcome screen declares a `to: abandoned` branch, and its
+  //    workflow.md contains no synthetic abandoned transition at all.
+  //    Adding one would duplicate a path the author already modelled —
+  //    verified by diffing this compiler's output against that app's
+  //    committed workflow.md, which matches byte for byte only when the
+  //    synthetic transition is suppressed.
+  const hasAuthoredAbandon = manifests.some((m) =>
+    (m.transitions || []).some(
+      (t) => t.to === 'abandoned' || (t.branches || []).some((b) => b.to === 'abandoned'),
+    ),
+  );
+
+  if (initialIsTerminal) {
+    const entryStateId = `state-${initialScreen.id}`;
+    const completeStateId = `state-${initialScreen.id}-complete`;
+    transitions.push({
+      id: `transition-${initialScreen.id}-outcome`,
+      label: `${initialScreen.label} outcome`,
+      owner: 'Human',
+      type: 'human',
+      from: entryStateId,
+      to: [completeStateId, 'state-abandoned'],
+      capabilities: ['CAP-001'],
+      actions: [
+        {
+          action_type: 'step/ask-user',
+          semantics: {
+            label: `${initialScreen.label} outcome`,
+            description: `User finishes or abandons the ${initialScreen.label} flow`,
+          },
+          config: {
+            questions: [
+              {
+                id: `${initialScreen.id}_outcome`,
+                text: `Finished with ${initialScreen.label}?`,
+                type: 'confirm',
+                options: [
+                  { label: 'Done', value: 'done', target: completeStateId },
+                  { label: 'Cancel', value: 'cancel', target: 'state-abandoned' },
+                ],
+              },
+            ],
+          },
+        },
+      ],
+    });
+  } else if (!hasAuthoredAbandon) {
+  const initialStateId = `state-${initialScreen.id}`;
+  transitions.push({
+    id: `transition-${initialScreen.id}-abandoned`,
+    label: `${initialScreen.label} abandoned`,
+    owner: 'Human',
+    type: 'human',
+    from: initialStateId,
+    to: ['state-abandoned'],
+    capabilities: ['CAP-001'],
+    actions: [
+      {
+        action_type: 'step/ask-user',
+        semantics: {
+          label: 'Abandon flow',
+          description: `User abandons the ${initialScreen.label} flow`,
+        },
+        config: {
+          questions: [
+            {
+              id: `${initialScreen.id}_abandoned`,
+              text: `Abandon the ${initialScreen.label} flow?`,
+              type: 'confirm',
+            },
+          ],
+        },
+      },
+    ],
+  });
+  }
+
+  let md = `---
+type: workflow
+id: ${wfId}
+ref: /product/workflows/${wfId}/workflow/workflow.md
+title: ${appName} App Flow
+description: Screen navigation and user interaction workflow for ${appName}
+dsl_version: "1.0"
+workflow_version: 1.0.0
+specification: draft
+relationships:
+  implements: [GOAL-001]
+  uses: []
+  depends_on: []
+  constrained_by: []
+  decided_by: []
+---
+
+## Workflow Summary
+
+\`\`\`yaml
+name: ${appName} App Flow
+description: Screen navigation and user interaction workflow for ${appName}
+\`\`\`
+
+## Business Object
+
+\`\`\`yaml
+name: UserProfile
+\`\`\`
+
+## Business Requirements
+
+The workflow starts when a mobile user launches the application on the ${initialScreen.label} screen.
+
+The user navigates through interactive preview screens to complete their requested flow.
+
+Reaching the complete destination screen is the success outcome and abandoning navigation is the failure outcome.
+
+### Objective
+Deliver an interactive mobile screen flow.
+
+### Actors
+- Mobile App User
+
+## Review Model
+
+\`\`\`yaml
+type: approval_required
+revision_loop:
+  enabled: false
+rejection:
+  terminal: true
+\`\`\`
+
+## Capability Discovery
+
+### CAP-001: Mobile Navigation
+\`\`\`yaml
+id: CAP-001
+name: Mobile Navigation
+purpose: Route user between mobile application screens
+inputs: [user_id]
+outputs: [screen_route]
+dependencies: []
+\`\`\`
+
+## Inputs & Outputs
+
+\`\`\`yaml
+inputs:
+  - user_id
+outputs:
+  - user_profile
+\`\`\`
+
+## States
+
+`;
+
+  for (const st of states) {
+    md += `### ${st.label}\n\n\`\`\`yaml\nid: ${st.id}\nlabel: ${st.label}\nterminal: ${st.terminal}\n\`\`\`\n\n`;
+  }
+
+  md += `## Rules & Logic
+- Follow forward navigation transitions
+
+## Gaps & Clarifications
+- None
+
+## Extension Points
+- None
+
+## Transition Contracts
+
+`;
+
+  for (const tr of transitions) {
+    md += `### ${tr.label}\n\n\`\`\`yaml\n${yaml.dump(tr).trim()}\n\`\`\`\n\n`;
+  }
+
+  return md;
+}
+
+function compilePreviews() {
+  if (!fs.existsSync(SCREENS_DIR)) {
+    console.error(`[compile-preview] Directory not found: ${SCREENS_DIR}`);
+    process.exit(1);
+  }
+
+  const appName = getAppName();
+  const files = fs
+    .readdirSync(SCREENS_DIR)
+    .filter((f) => f.endsWith('.preview.md') || f.endsWith('.preview.mdx'))
+    .sort();
+
+  console.log(`[compile-preview] Found ${files.length} preview manifest(s) in: ${SCREENS_DIR}`);
+
+  const manifests = [];
+  for (const file of files) {
+    const filePath = path.join(SCREENS_DIR, file);
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const manifest = extractYamlBlock(content);
+      manifests.push(manifest);
+    } catch (err) {
+      console.warn(`[compile-preview] Skipping ${file}: ${err.message}`);
+    }
+  }
+
+  // Sort manifests: initial screens first, then alphabetical
+  manifests.sort((a, b) => {
+    if (a.isInitial && !b.isInitial) return -1;
+    if (!a.isInitial && b.isInitial) return 1;
+    return a.id.localeCompare(b.id);
+  });
+
+  const nodes = [];
+  const edges = [];
+  const conditionMap = new Map();
+
+  // 1. Build DevicePreview nodes & edges for preview.json
+  for (const m of manifests) {
+    const actionPorts = (m.ports || []).map((port) => ({
+      id: port.id,
+      label: port.label,
+      top: typeof port.relativeTop === 'number' ? Math.round(port.relativeTop * PRESET.height) : (port.top || 0),
+    }));
+
+    nodes.push({
+      id: `preview-${m.id}`,
+      type: 'devicePreview',
+      position: { x: 0, y: 0 },
+      data: {
+        type: 'devicePreview',
+        route: m.path || `/${m.id}`,
+        label: m.label || m.id,
+        isInitial: !!m.isInitial,
+        presetId: PRESET.id,
+        hideControls: true,
+        actionPorts,
+        action: {
+          after: [
+            {
+              stepId: `await-nav-${m.id}`,
+              actionType: 'step/await-navigation',
+              semantics: {
+                label: `Await navigation from ${m.label || m.id}`,
+                description: `Pause and wait for user to trigger a navigation event from this screen`,
+              },
+              config: {
+                screenId: m.id,
+                route: m.path || `/${m.id}`,
+              },
+            },
+          ],
+        },
+        apiCalls: m.api_calls || [],
+      },
+    });
+
+    for (const t of m.transitions || []) {
+      if (t.condition) {
+        const cond = t.condition;
+        if (!conditionMap.has(cond.id)) {
+          conditionMap.set(cond.id, {
+            id: cond.id,
+            type: 'transition',
+            position: { x: 0, y: 0 },
+            data: {
+              type: 'transition',
+              label: cond.label || cond.id,
+              transitionType: cond.transitionType || 'conditional',
+              description: cond.description || '',
+              action: {
+                after: [
+                  {
+                    stepId: `${cond.id}-action`,
+                    actionType: 'step/condition',
+                    semantics: {
+                      label: cond.label || cond.id,
+                      description: cond.description || `Evaluate ${cond.label || cond.id}`,
+                    },
+                    config: {
+                      condition: cond.id,
+                    },
+                  },
+                ],
+              },
+            },
+          });
+        }
+
+        edges.push({
+          id: `e-preview-${m.id}-${cond.id}`,
+          source: `preview-${m.id}`,
+          target: cond.id,
+          sourceHandle: t.from,
+          type: 'straight',
+        });
+
+        for (const branch of t.branches || []) {
+          if (branch.to !== 'abandoned') {
+            edges.push({
+              id: `e-${cond.id}-preview-${branch.to}`,
+              source: cond.id,
+              target: `preview-${branch.to}`,
+              type: 'straight',
+            });
+          }
+        }
+      } else if (t.to) {
+        const transNodeId = `transition-${m.id}-${t.to}`;
+        nodes.push({
+          id: transNodeId,
+          type: 'transition',
+          position: { x: 0, y: 0 },
+          data: {
+            type: 'transition',
+            label: t.label || `${m.label || m.id} to ${t.to}`,
+            action: {
+              after: [],
+            },
+          },
+        });
+
+        edges.push({
+          id: `e-preview-${m.id}-${transNodeId}`,
+          source: `preview-${m.id}`,
+          target: transNodeId,
+          sourceHandle: t.from,
+          type: 'straight',
+        });
+
+        edges.push({
+          id: `e-${transNodeId}-preview-${t.to}`,
+          source: transNodeId,
+          target: `preview-${t.to}`,
+          type: 'straight',
+        });
+      }
+    }
+  }
+
+  for (const condNode of conditionMap.values()) {
+    nodes.push(condNode);
+  }
+
+  // 2. Write preview.json
+  const previewGraph = {
+    name: `${appName}-workflow`,
+    version: '1',
+    preset: PRESET.id,
+    nodes,
+    edges,
+  };
+
+  fs.writeFileSync(PREVIEW_JSON_FILE, JSON.stringify(previewGraph, null, 2), 'utf-8');
+  console.log(`[compile-preview] ✅ Generated: ${PREVIEW_JSON_FILE}`);
+
+  // 3. Write workflow.md
+  const workflowMd = buildWorkflowDsl(appName, manifests);
+  fs.writeFileSync(WORKFLOW_MD_FILE, workflowMd, 'utf-8');
+  console.log(`[compile-preview] ✅ Generated: ${WORKFLOW_MD_FILE}`);
+
+  // 4. Validate with workflow-engine CLI if available
+  const cliPath = WORKFLOW_ENGINE_CLI_CANDIDATES.find((p) => fs.existsSync(p));
+  if (cliPath) {
+    try {
+      console.log(`[compile-preview] 🔍 Validating workflow.md with workflow-engine CLI...`);
+      execSync(`node "${cliPath}" "${WORKFLOW_MD_FILE}" --workflow`, {
+        encoding: 'utf-8',
+      });
+      console.log(`[compile-preview] ✅ workflow-engine CLI check: PASS`);
+    } catch (err) {
+      console.error(`[compile-preview] ❌ workflow-engine CLI validation failed:\n${err.stdout || err.message}`);
+      process.exit(1);
+    }
+  }
+
+  console.log(`[compile-preview] 🎉 Compilation complete! (${nodes.length} nodes, ${edges.length} edges)`);
+}
+
+compilePreviews();

package/src/lib/previewBridge.ts

@@ -0,0 +1,103 @@
+import { Platform } from 'react-native';
+
+export type HostMessage = {
+  type: string;
+  appId?: string;
+  [key: string]: unknown;
+};
+
+export type AppParams = {
+  appId: string | null;
+  name: string | null;
+  tenantId: string | null;
+  route: string | null;
+};
+
+export type AppRoute = {
+  id: string;
+  path: string;
+  label: string;
+  isInitial?: boolean;
+};
+
+export type AppNavLink = {
+  fromRouteId: string;
+  toRouteId: string;
+  label?: string;
+};
+
+export type AppRouteManifest = {
+  appId: string;
+  routes: AppRoute[];
+  links: AppNavLink[];
+};
+
+/**
+ * The app's real navigation topology, reported to the host at runtime.
+ *
+ * Edit this — and only this — as you add screens. Everything else in this
+ * file is host-protocol plumbing; leave it as-is.
+ */
+export function buildRouteManifest(appId: string | null): AppRouteManifest {
+  return {
+    appId: appId ?? 'waypoint-expo-template',
+    routes: [
+      { id: 'home', path: '/home', label: 'Home', isInitial: true },
+    ],
+    links: [],
+  };
+}
+
+export function reportRoutes(manifest: AppRouteManifest): void {
+  postToHost({ type: 'expo-app:routes', manifest });
+}
+
+const isWeb = Platform.OS === 'web';
+
+export function getAppParams(): AppParams {
+  if (!isWeb) {
+    return { appId: null, name: null, tenantId: null, route: null };
+  }
+  const search = new URLSearchParams(window.location.search);
+  const hash = window.location.hash ? window.location.hash.replace(/^#/, '') : null;
+  const routeParam = search.get('route') || search.get('screen') || hash;
+  return {
+    appId: search.get('appId'),
+    name: search.get('name'),
+    tenantId: search.get('tenant_id'),
+    route: routeParam,
+  };
+}
+
+export function postToHost(payload: HostMessage): void {
+  if (!isWeb) {
+    return;
+  }
+  const target = window.parent;
+  if (target && target !== window) {
+    target.postMessage(payload, '*');
+  }
+}
+
+export function postNavigationTrigger(from: string, to: string, portId?: string): void {
+  postToHost({
+    type: 'expo-app:navigation-trigger',
+    from,
+    to,
+    port_id: portId,
+  });
+}
+
+export function onHostMessage(handler: (message: HostMessage) => void): () => void {
+  if (!isWeb) {
+    return () => {};
+  }
+  const listener = (event: MessageEvent): void => {
+    if (event.source !== window.parent) {
+      return;
+    }
+    handler(event.data as HostMessage);
+  };
+  window.addEventListener('message', listener);
+  return () => window.removeEventListener('message', listener);
+}

package/src/screens/HomeScreen.preview.md

@@ -0,0 +1,22 @@
+---
+id: home
+label: Home
+path: /home
+isInitial: true
+---
+
+# Home Screen
+
+Placeholder starting screen. Replace with the app's real content, and add
+`ports`/`transitions` here as you wire up navigation to new screens.
+
+## Interactive Ports & Navigation
+
+```yaml
+id: home
+label: Home
+path: /home
+isInitial: true
+ports: []
+transitions: []
+```

package/src/screens/HomeScreen.tsx

@@ -0,0 +1,14 @@
+import { StyleSheet, Text, View } from 'react-native';
+
+export function HomeScreen() {
+  return (
+    <View style={styles.container} testID="screen-home">
+      <Text style={styles.text}>Home</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, alignItems: 'center', justifyContent: 'center', backgroundColor: '#ffffff' },
+  text: { fontSize: 18 },
+});

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true
+  }
+}

package/workflow.md

@@ -0,0 +1,144 @@
+---
+type: workflow
+id: WF-WAYPOINT_EXPO_TEMPLATE
+ref: /product/workflows/WF-WAYPOINT_EXPO_TEMPLATE/workflow/workflow.md
+title: waypoint-expo-template App Flow
+description: Screen navigation and user interaction workflow for waypoint-expo-template
+dsl_version: "1.0"
+workflow_version: 1.0.0
+specification: draft
+relationships:
+  implements: [GOAL-001]
+  uses: []
+  depends_on: []
+  constrained_by: []
+  decided_by: []
+---
+
+## Workflow Summary
+
+```yaml
+name: waypoint-expo-template App Flow
+description: Screen navigation and user interaction workflow for waypoint-expo-template
+```
+
+## Business Object
+
+```yaml
+name: UserProfile
+```
+
+## Business Requirements
+
+The workflow starts when a mobile user launches the application on the Home screen.
+
+The user navigates through interactive preview screens to complete their requested flow.
+
+Reaching the complete destination screen is the success outcome and abandoning navigation is the failure outcome.
+
+### Objective
+Deliver an interactive mobile screen flow.
+
+### Actors
+- Mobile App User
+
+## Review Model
+
+```yaml
+type: approval_required
+revision_loop:
+  enabled: false
+rejection:
+  terminal: true
+```
+
+## Capability Discovery
+
+### CAP-001: Mobile Navigation
+```yaml
+id: CAP-001
+name: Mobile Navigation
+purpose: Route user between mobile application screens
+inputs: [user_id]
+outputs: [screen_route]
+dependencies: []
+```
+
+## Inputs & Outputs
+
+```yaml
+inputs:
+  - user_id
+outputs:
+  - user_profile
+```
+
+## States
+
+### Home
+
+```yaml
+id: state-home
+label: Home
+terminal: false
+```
+
+### Home Complete
+
+```yaml
+id: state-home-complete
+label: Home Complete
+terminal: true
+```
+
+### Onboarding Failed
+
+```yaml
+id: state-abandoned
+label: Onboarding Failed
+terminal: true
+```
+
+## Rules & Logic
+- Follow forward navigation transitions
+
+## Gaps & Clarifications
+- None
+
+## Extension Points
+- None
+
+## Transition Contracts
+
+### Home outcome
+
+```yaml
+id: transition-home-outcome
+label: Home outcome
+owner: Human
+type: human
+from: state-home
+to:
+  - state-home-complete
+  - state-abandoned
+capabilities:
+  - CAP-001
+actions:
+  - action_type: step/ask-user
+    semantics:
+      label: Home outcome
+      description: User finishes or abandons the Home flow
+    config:
+      questions:
+        - id: home_outcome
+          text: Finished with Home?
+          type: confirm
+          options:
+            - label: Done
+              value: done
+              target: state-home-complete
+            - label: Cancel
+              value: cancel
+              target: state-abandoned
+```
+