/preview-screens

name: preview-screens
description: Use when the user wants to preview generated screens in a browser without starting Metro / a simulator — for example after /create-mobile-app finishes or after /edit-app regenerates a screen.
user-invocable: true
allowed-tools: Read, Write, Glob, Grep, Bash
model: sonnet

**Shared instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — read first.

Preview Screens

Generates a self-contained HTML file that renders every screen in the app as a phone-frame mockup (375 × 812) with tab navigation and a dark/light toggle. The agent reads TSX files, understands the Tamagui component tree, and produces equivalent HTML/CSS — no programmatic TSX parsing.

When to use

• After generating screens, to see a quick visual preview without running Metro/Expo
• To share a screenshot-ready mockup with stakeholders
• To verify layout before deploying

When NOT to use

• To run the actual app → use `npm run dev`
• To modify screens → use `/edit-app`; `screen-builder` is an internal agent invoked by orchestrator skills

Workflow

1. Locate project → 2. Discover screens → 3. Read reference mapping → 4. Read & convert each screen → 5. Assemble preview.html → 6. Write file → 7. Open in browser

---

Step 1 — Locate project

Determine the working directory:

• If `$ARGUMENTS` contains `--working-dir <path>`, use that.
• Otherwise use the current working directory.

Validate the project:

Glob pattern="power.config.json" path="<working_dir>"

If missing, check for `package.json`. If neither exists, report the error and stop.

Read `memory-bank.md` if present to get the project name for the page title:

Grep pattern="^# " path="<working_dir>/memory-bank.md"

Fallback: read `name` from `package.json`.

Step 2 — Discover screens

**Telemetry checkpoint: `discover_app_screens`**

Find all TSX files under the app directory:

Glob pattern="app/**/*.tsx" path="<working_dir>"

**Exclude** these patterns — they are not screens:

• `_layout.tsx` (navigation layouts)
• `+not-found.tsx` (Expo Router error boundary)
• Files in directories starting with `.`
• `index.tsx` at the app root if it only contains an auth redirect (read it to check)

**Derive screen names** from file paths:

• `app/(app)/home.tsx` → "Home"
• `app/(app)/recipes/index.tsx` → "Recipes"
• `app/(app)/recipes/[id].tsx` → "Recipe Detail"
• `app/login.tsx` → "Login"
• `app/oauth-callback.tsx` → skip (not a visible screen)

If `native-app-plan.md` exists in the working directory, read its `## Screens` section for human-friendly labels.

Build an ordered list: `[ { path, screenName, screenId } ]`.

**Default tab ordering — Home first, then two details, then the rest.** Step 5 marks the first entry as `active`, so the order below directly controls which screen the user lands on when `preview.html` opens.

Sort the list with this priority:

1. **Home / dashboard first.** The first screen matching any of these paths (in this priority): `app/(app)/home.tsx`, `app/(app)/index.tsx`, `app/(app)/dashboard.tsx`, `app/index.tsx` (only if it's a real home screen — not the auth redirect you already filtered out in Step 2). If `native-app-plan.md` flags one screen as the home/landing screen, prefer that. 2. **Then up to two detail screens.** A "detail" screen is any TSX whose route segment uses a dynamic param — file path contains `[` and `]` (e.g. `app/(app)/recipes/[id].tsx`, `app/(app)/orders/[orderId]/edit.tsx`). Take the first two in the order they were discovered (alphabetical by path is fine). 3. **Then everything else** in discovery order.

If there are fewer than two detail screens, just include whatever exists and continue with the rest — do not pad with non-detail screens to force a count of 3.

Do not drop any screens — this rule only reorders. Every discovered screen still gets a tab.

Step 3 — Read reference mapping

Load the Tamagui-to-HTML mapping reference:

Read file_path="${PLUGIN_ROOT}/shared/references/tamagui-html-mapping.md"

Internalize:

• Component → HTML element + CSS mappings (Section 1)
• Token → pixel values for spacing, font-size, color (Section 2)
• Conversion guidelines — placeholder rules, icon substitutions, what to skip (Section 3)
• Phone frame HTML template (Section 4) — this is the outer shell

Also check if the project has custom brand tokens:

Glob pattern="tamagui.config.ts" path="<working_dir>"

If found, read it and extract any custom color tokens (look for `tokens: { color: { ... } }`). Add them as additional CSS custom properties in the generated HTML.

Step 4 — Read and convert each screen

**Telemetry checkpoint: `render_screen_preview_frames`**

**Print before starting:** > "→ Reading + converting <N> screens to HTML/CSS (one print per screen as I go)."

For each screen in the ordered list from Step 2:

1. **Read the full TSX file.**

2. **Identify the component tree.** Walk the JSX return statement and note every Tamagui component, its props, and its children.

3. **Generate equivalent HTML/CSS** using the mapping from Step 3:

• `YStack` → `<div style="display:flex; flex-direction:column; ...">`
• Map every shorthand prop to its CSS equivalent (`flex={1}` → `flex:1`, `bg="$color2"` → `background:var(--color2)`, etc.)
• Map token values to pixels (`p="$4"` → `padding:16px`)
• Replace `<Ionicons name="..." />` icons with Unicode equivalents (see mapping reference Section 3, Guideline 4 — the icon substitution table uses Ionicons names)

4. **Handle dynamic content:**

• `.map()` over arrays → generate 3–4 representative placeholder items
• `useQuery` / `useMutation` → show the populated state only (skip loading/error branches)
• Form `defaultValues` → pre-fill inputs with those values

Native PDF/pen controls need honest static approximations:

• PDF viewer actions → render a compact report/PDF block with a filename, generated timestamp, storage label (f