@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/appshot-core/SKILL.md

@@ -0,0 +1,872 @@
+---
+name: appshot-core
+description: "Foundation skill for Appshot. Defines the AICUT project architecture, primitives library, config schema, device presets, and store requirements. Owns the shared extraction phase used by appshot-videos and appshot-images. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "trunghaiy/appshot"
+---
+
+# Appshot Core — Foundation
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+Reference skill for all Appshot skills. Read this before executing `appshot-videos` or `appshot-images`.
+
+## Architecture
+
+- **Remotion 4.0** + React 18 + Tailwind CSS 3.4
+- Config defines app metadata and brand only — scenes are custom `.tsx` files, not config entries
+- Each project has an orchestrator component (e.g., `FooPreview.tsx`) that sequences custom scenes via Remotion `<Sequence>` + `<SceneWrap>`
+- All primitives are brand-aware via a `brand` prop derived from the config's `BrandColors`
+
+## Project Context (auto-injected)
+
+- Package manifest: !`cat package.json 2>/dev/null || cat pubspec.yaml 2>/dev/null || cat app.json 2>/dev/null`
+- App colors: !`find . -maxdepth 4 \( -name 'colors.xml' -o -name 'Colors.swift' -o -name 'colors.ts' -o -name 'theme.ts' -o -name 'Color.kt' -o -name 'tailwind.config.js' -o -name 'tailwind.config.ts' \) 2>/dev/null | head -5 | xargs head -50 2>/dev/null`
+- App icon: !`find . -maxdepth 5 \( -name 'ic_launcher.png' -o -name 'icon.png' \) -type f 2>/dev/null | head -3`
+- Store metadata: !`cat fastlane/metadata/en-US/full_description.txt 2>/dev/null || cat fastlane/metadata/en-US/description.txt 2>/dev/null || cat fastlane/metadata/android/en-US/full_description.txt 2>/dev/null`
+- README excerpt: !`head -80 README.md 2>/dev/null`
+
+## Extraction & Context Caching
+
+Both `appshot-videos` and `appshot-images` use this extraction process. Results are cached to `.appshot-context.json` so extraction only runs once per project.
+
+### Check for cached context
+
+Before scanning, check if `.appshot-context.json` exists in the project root. If it does:
+1. Load and present a summary to the user
+2. Ask: "I found a previous extraction. Confirm this is still correct, or re-scan?"
+3. If confirmed, skip extraction and proceed to the calling skill's next phase
+4. If re-scan requested, run extraction below and overwrite the file
+
+### Extraction steps
+
+#### Step 1: Detect framework
+
+Check for marker files in this order. Stop at the first match.
+
+| Framework | Marker files |
+|---|---|
+| Expo / React Native | `app.json`, `app.config.ts`, `app.config.js` |
+| Flutter | `pubspec.yaml` |
+| iOS (Swift) | `*.xcodeproj/`, `*.xcworkspace/`, `Package.swift` |
+| Android (Kotlin/Java) | `app/src/main/AndroidManifest.xml`, `build.gradle.kts`, `build.gradle` |
+| Next.js | `next.config.js`, `next.config.ts`, `next.config.mjs` |
+| SvelteKit | `svelte.config.js` |
+| Nuxt | `nuxt.config.ts`, `nuxt.config.js` |
+| Astro | `astro.config.mjs`, `astro.config.ts` |
+| Remix | `remix.config.js`, `app/root.tsx` (with @remix-run import) |
+| Vite (React/Vue/Solid) | `vite.config.ts`, `vite.config.js` (check `package.json` for react/vue/solid) |
+
+Use `ls` or `find . -maxdepth 3` to check. If none match, note that no framework was detected and move on — the user may describe their app verbally.
+
+#### Step 2: Extract app identity
+
+**Expo / React Native:**
+- **Name**: `app.json` -> `expo.name` or `name`
+- **Description/tagline**: `app.json` -> `expo.description` or `description`
+- **Bundle ID**: `app.json` -> `expo.ios.bundleIdentifier` or `expo.android.package`
+- **Also check**: `package.json` -> `name`, `description`
+
+**Flutter:**
+- **Name**: `pubspec.yaml` -> `name:`
+- **Description**: `pubspec.yaml` -> `description:`
+- **Also check**: `android/app/src/main/AndroidManifest.xml` -> `android:label`, `ios/Runner/Info.plist` -> `CFBundleDisplayName`
+
+**iOS (Swift):**
+- **Name**: `Info.plist` -> `CFBundleDisplayName` or `CFBundleName`
+- **Bundle ID**: `Info.plist` -> `CFBundleIdentifier`
+- **Also check**: `project.pbxproj` for product name
+
+**Android (Kotlin/Java):**
+- **Name**: `app/src/main/res/values/strings.xml` -> `<string name="app_name">`
+- **Package**: `AndroidManifest.xml` -> `package` attribute
+- **Also check**: `build.gradle.kts` or `build.gradle` -> `applicationId`
+
+**Next.js:**
+- **Name**: `package.json` → `name`; also check `next.config.*` → `env.APP_NAME`
+- **Description/tagline**: `package.json` → `description`; also check `app/layout.tsx` → `metadata.description`
+- **URL**: check `.env` or `.env.local` → `NEXT_PUBLIC_APP_URL`, `NEXT_PUBLIC_SITE_URL`
+
+**SvelteKit:**
+- **Name**: `package.json` → `name`
+- **Description**: `package.json` → `description`; check `src/app.html` → `<title>`, `<meta name="description">`
+
+**Vite (React/Vue):**
+- **Name**: `package.json` → `name`
+- **Description**: `package.json` → `description`; check `index.html` → `<title>`, `<meta name="description">`
+
+#### Step 3: Extract brand colors
+
+Search for color definitions. Read the first match in each framework.
+
+**Expo / React Native** — search paths (in order):
+1. `src/theme.ts` or `src/theme.js`
+2. `src/colors.ts` or `src/constants/colors.ts`
+3. `theme/colors.ts` or `theme/index.ts`
+4. `tailwind.config.js` or `tailwind.config.ts` -> `theme.extend.colors`
+5. `app.json` -> `expo.primaryColor`, `expo.backgroundColor`
+
+Look for: named color exports (`primary`, `secondary`, `background`, `surface`, `accent`, `success`, `danger/error`), hex strings, `rgb()` values.
+
+**Flutter** — search paths:
+1. `lib/theme.dart` or `lib/theme/app_theme.dart`
+2. `lib/theme/colors.dart` or `lib/constants/colors.dart`
+3. `lib/main.dart` -> `ThemeData()`
+
+Look for: `Color(0xFF...)` constants, `primaryColor`, `accentColor`, `colorScheme` definitions.
+
+**iOS (Swift)** — search paths:
+1. `*.xcassets/Colors/**/*.colorset/Contents.json` — parse `components` for RGB
+2. `**/Theme.swift` or `**/Colors.swift` or `**/ColorScheme.swift`
+
+Look for: static `Color` properties, `UIColor` hex initializers, asset catalog color definitions.
+
+**Android** — search paths:
+1. `app/src/main/res/values/colors.xml` — `<color name="primary">#RRGGBB</color>`
+2. `app/src/main/res/values/themes.xml` — `<item name="colorPrimary">`
+3. `**/ui/theme/Color.kt` — Jetpack Compose `Color()` definitions
+
+**Web (all frameworks)** — search paths (in order):
+1. `tailwind.config.js` or `tailwind.config.ts` → `theme.extend.colors`
+2. `src/styles/globals.css` or `src/app/globals.css` → CSS custom properties (`--primary`, `--background`, etc.)
+3. `src/theme.*` or `src/lib/theme.*`
+4. `src/styles/variables.css`
+
+#### Step 4: Find app icon
+
+| Framework | Where to look |
+|---|---|
+| Expo/RN | `app.json` -> `expo.icon` field (usually `./assets/icon.png`) |
+| Flutter | `android/app/src/main/res/mipmap-xxxhdpi/ic_launcher.png` or `ios/Runner/Assets.xcassets/AppIcon.appiconset/` |
+| iOS | `*.xcassets/AppIcon.appiconset/` -> find the largest `.png` |
+| Android | `app/src/main/res/mipmap-xxxhdpi/ic_launcher.png` |
+| Web (all) | `public/favicon.svg`, `public/favicon.ico`, `public/logo.svg`, `public/logo.png`, `app/favicon.ico`, `src/assets/logo.*` |
+
+#### Step 5: Extract features & store metadata
+
+These sources exist across all frameworks:
+
+| Source | Path | What to extract |
+|---|---|---|
+| Fastlane (iOS) | `fastlane/metadata/en-US/description.txt` or `full_description.txt` | Full store description |
+| Fastlane (iOS) | `fastlane/metadata/en-US/subtitle.txt` | App Store subtitle |
+| Fastlane (iOS) | `fastlane/metadata/en-US/keywords.txt` | Search keywords |
+| Fastlane (Android) | `fastlane/metadata/android/en-US/full_description.txt` | Play Store description |
+| Fastlane (Android) | `fastlane/metadata/android/en-US/short_description.txt` | Short description |
+| README | `README.md` | First 80 lines — app description, feature bullets |
+| CLAUDE.md | `CLAUDE.md` | Project description if present |
+
+#### Step 5b: Extract ASO keywords
+
+Apple and Google can now read text in screenshots and videos via visual intelligence. Extract a keyword list so overlay text can naturally incorporate high-value search terms.
+
+**Primary source:** `fastlane/metadata/en-US/keywords.txt` (comma-separated). This is the developer's own keyword strategy — use it as the authoritative list.
+
+**Fallback sources** (if no Fastlane keywords exist): derive 8-12 keyword candidates from:
+1. App Store subtitle (`fastlane/metadata/en-US/subtitle.txt`) — split into individual terms
+2. Store description — extract the most repeated nouns and action verbs
+3. Feature names from extraction — map feature names to user-facing search terms
+4. App category terms from Step 6 signals table
+
+**Output:** A ranked list of keywords, most important first. Include both single words ("habits", "streak") and short phrases ("reading tracker", "book log"). Cap at 12 keywords.
+
+#### Step 6: Infer app category
+
+Based on extracted keywords, description, and feature names, infer the app category:
+
+| Category | Signals |
+|---|---|
+| Habit tracking | streak, habit, daily, routine, consistency, track days |
+| Fitness | workout, exercise, gym, reps, sets, calories, steps |
+| Finance | budget, expense, money, savings, transactions, spending |
+| Productivity | task, todo, note, project, organize, calendar |
+| Social | chat, message, friend, follow, post, share |
+| Education | learn, quiz, study, course, flashcard, practice |
+| Health | meditation, sleep, mood, journal, wellness, mindful |
+| Travel | trip, itinerary, booking, destination, explore |
+| Food | recipe, meal, restaurant, cooking, ingredients |
+| SaaS | dashboard, subscription, plan, pricing, onboarding, workspace, team, analytics |
+| E-commerce | cart, checkout, product, shop, order, payment, inventory |
+| Developer tool | API, SDK, CLI, documentation, playground, sandbox, webhook |
+| Content/publishing | blog, article, post, publish, editor, CMS, newsletter |
+| AI/ML | model, inference, prompt, generate, embed, vector, chat, completion |
+| Community | forum, discussion, thread, community, member, profile |
+
+If no clear match, note "uncategorized" — the user will clarify.
+
+### Deep analysis
+
+Go beyond identity and colors. Understand what the app actually does.
+
+**Screen inventory.** Scan navigation files to discover all screens:
+- React Native / Expo: read `App.tsx`, any `*Navigator.tsx`, `*Router.tsx`, tab bar configs, `react-navigation` setup
+- Flutter: read `lib/main.dart`, router config, `GoRouter` or `MaterialApp` routes
+- iOS: read storyboard references, `UITabBarController` setup, SwiftUI `NavigationStack`/`TabView`
+- Look for: screen names, tab labels, navigation structure (tabs, stacks, drawers)
+
+**Navigation chrome extraction.** For realistic mock screens, extract the navigation patterns the user actually sees:
+- **Navigation type**: tabs, stack, drawer, or combination
+- **Tab bar**: label text for each tab, icon descriptions (e.g., "house icon", "magnifying glass", "person circle"), which tab is default/home
+- **Navigation headers**: title style (large title vs inline), back button presence, right bar button items (e.g., "gear icon", "plus", "bell")
+- **Status bar style**: light content (white text, for dark backgrounds) or dark content (black text, for light backgrounds)
+- **Home indicator**: present on all modern iPhones (bottom bar), absent on older devices
+
+Where to find this:
+- React Native / Expo: `screenOptions`, `tabBarLabel`, `tabBarIcon`, `headerTitle`, `headerRight`, `navigationOptions` in navigator files
+- Flutter: `BottomNavigationBar` items, `AppBar` title/actions, `Scaffold` configuration
+- iOS: `UITabBarItem` setup, `navigationItem.title`, `navigationItem.rightBarButtonItems`, SwiftUI `.tabItem` / `.navigationTitle` / `.toolbar`
+- Android: `BottomNavigationView` menu XML, `Toolbar`/`TopAppBar` setup, Jetpack Compose `NavigationBar` items
+
+**Page/route inventory (web).** Scan router config to discover all pages:
+- Next.js: read `app/` directory structure (each folder with `page.tsx` = route), or `pages/` directory
+- SvelteKit: read `src/routes/` directory structure (each folder with `+page.svelte` = route)
+- Vite/React: read router config (`react-router`, `tanstack-router`), or scan for route definitions
+- Look for: page names, layout structure, protected vs public routes
+
+**Landing page analysis.** If a landing/marketing page exists:
+- Extract hero headline and subheadline
+- Extract feature sections
+- Note CTA text ("Get Started", "Sign Up Free", etc.)
+- Note pricing structure if visible
+
+**Feature analysis.** For each discovered screen, read the component file to understand:
+- What data it displays
+- What actions the user can take
+- What makes it visually interesting or unique
+
+**UI pattern extraction.** Scan component styling to capture the app's visual design language. Mock screens that don't match the real app's look undermine credibility — this data closes the gap.
+
+What to extract:
+- **Border radius**: button radius, card radius, input radius (e.g., "fully rounded buttons", "8px card corners", "pill-shaped inputs")
+- **Spacing rhythm**: padding/margin values used in containers and between elements (e.g., "16px horizontal padding", "24px section gaps")
+- **Typography**: font family (custom or system), heading weights (e.g., 700 vs 800), body size, whether the app uses ALL CAPS for section headers
+- **Button style**: shape (rounded rectangle, pill, circle), size, fill vs outline, icon-only buttons
+- **Card style**: background color, border, shadow depth, glass/blur effects
+- **Icon library**: which icon set (SF Symbols, Material Icons, Lucide, custom SVGs, Ionicons)
+- **Special UI elements**: waveform visualizers, progress rings, gradient backgrounds, tag/chip styles, badge indicators
+
+Where to find this:
+- React Native / Expo: `StyleSheet.create()` blocks, inline `style={}`, NativeWind/Tailwind classes, component library imports (`react-native-paper`, `tamagui`, `gluestack`)
+- Flutter: `BoxDecoration`, `BorderRadius`, `TextStyle`, `ButtonStyle` in widget files and theme data
+- iOS (Swift): `.cornerRadius`, `.font()`, `.padding()`, `UIFont` descriptors, SF Symbol names in SwiftUI/UIKit
+- Android: `shapes.xml`, `styles.xml`, Compose `RoundedCornerShape()`, `MaterialTheme.typography`, Material icon imports
+
+**Value props / differentiators.** Extract from README, store description, CLAUDE.md, marketing copy, or landing page:
+- What problem does this app solve?
+- How is it different from competitors?
+- What is the emotional promise?
+
+**Core action loop.** Identify the single most frequent user action:
+- What does a user do every time they open the app?
+- How many taps/steps does it take?
+- What feedback do they get after completing it?
+
+**Theme detection.** Check if the app supports light/dark modes:
+- Look for theme toggle, `useColorScheme`, `Appearance`, `ThemeProvider`, `darkMode` in config
+- Note which is the default or primary theme
+- Note if the app is dark-theme-only (some brands like Spotify, cinema apps)
+
+### Save context
+
+After extraction and user confirmation, save results to `.appshot-context.json` in the project root:
+
+```json
+{
+  "version": 2,
+  "extractedAt": "ISO timestamp",
+  "app": { "name": "", "tagline": "", "icon": "", "platform": "", "framework": "", "url": "string or null" },
+  "brand": { "primary": "", "primaryLight": "", "background": "", "surface": "", "textPrimary": "", "textSecondary": "", "success": "", "danger": "", "accent": "" },
+  "category": "string",
+  "theme": "light | dark | both",
+  "themeDefault": "light | dark",
+  "navigation": {
+    "type": "tabs | stack | drawer | tabs+stack",
+    "tabs": [{ "label": "", "iconDescription": "", "isDefault": false }],
+    "headerStyle": "largeTitle | inline",
+    "statusBarStyle": "light | dark"
+  },
+  "screens": [{ "name": "", "tab": "", "description": "" }],
+  "pages": [{ "route": "", "name": "", "description": "", "layout": "" }],
+  "landingPage": { "heroHeadline": "string or null", "heroSubheadline": "string or null", "cta": "string or null", "featureSections": ["string"] },
+  "uiPatterns": {
+    "borderRadius": { "button": "string", "card": "string", "input": "string" },
+    "spacing": { "horizontal": "string", "sectionGap": "string" },
+    "typography": { "fontFamily": "string or 'system'", "headingWeight": "number", "bodySize": "string", "capsHeaders": "boolean" },
+    "buttonStyle": "string — e.g., 'pill filled, 56px height' or 'rounded-lg outline'",
+    "cardStyle": "string — e.g., 'dark surface, 16px radius, no border, subtle shadow'",
+    "iconLibrary": "string — e.g., 'SF Symbols' or 'Ionicons' or 'custom SVG'",
+    "specialElements": ["string — e.g., 'waveform visualizer', 'gradient background', 'pill-shaped tags'"]
+  },
+  "features": ["string"],
+  "coreAction": "string",
+  "valueProps": ["string"],
+  "keywords": ["string — ranked ASO keywords, most important first, max 12"],
+  "screenshots": [{
+    "referenceFile": "original file path (for re-reading if needed)",
+    "screen": "matched screen name",
+    "description": "what this screenshot shows",
+    "visualSpec": "structured visual analysis — layout, colors, components, typography, special elements (the actual styling reference for mock UI)"
+  }],
+  "storeDescription": "string or null",
+  "sources": { "name": "source file", "colors": "source file", "keywords": "source file or 'derived'" }
+}
+```
+Notes on schema v2:
+- `screenshots` — empty array if user chose auto-mock; populated if user provided real screenshots
+- `app.framework` valid values: `"expo"` | `"flutter"` | `"ios"` | `"android"` | `"nextjs"` | `"sveltekit"` | `"nuxt"` | `"astro"` | `"remix"` | `"vite"` | `"web"`
+- `app.platform` valid values: `"ios"` | `"android"` | `"both"` | `"web"`
+- `pages` — web route inventory (empty array for mobile apps)
+- `landingPage` — extracted landing page data (null for mobile apps)
+```
+
+### Present findings
+
+Summarize what you found concisely. Always cite the source file so the user can verify.
+
+```
+I scanned your project and found:
+
+- **App:** [name] (from [source file])
+- **Tagline:** [text] (from [source file])
+- **Platform:** [iOS/Android/both] (from [evidence])
+- **Colors:** primary [hex], background [hex], surface [hex], ... (from [source file])
+- **Icon:** [file path]
+- **Category:** [category] based on [keywords/description]
+- **Store description:** [found at path / not found]
+- **Theme:** [light only / dark only / both — default is X]
+
+**Navigation:** [tabs / stack / drawer] — [header style: large title / inline]
+**Tab bar:** [Tab1 (icon)] | [Tab2 (icon)] | [Tab3 (icon)] — default: [Tab1]
+**Status bar:** [dark content / light content]
+
+**Screen inventory:**
+- [Tab 1]: [ScreenName] — [what it shows]
+- [Tab 2]: [ScreenName] — [what it shows]
+- [Modal/Detail]: [ScreenName] — [what it shows]
+- ...
+
+**Page inventory (web):**
+- `/` — [Landing page] — [hero headline, feature sections]
+- `/dashboard` — [Dashboard] — [what it shows]
+- `/settings` — [Settings] — [configuration options]
+- ...
+
+**Landing page:** [hero headline] / [CTA text] / [number of feature sections]
+**URL:** [extracted URL or "not found"]
+
+**Key features:** [bullet list of 3-5 main features extracted from code/docs]
+
+**Core action loop:** [what users do most — e.g., "tap Log -> enter page number -> save (3 taps, ~5 seconds)"]
+
+**Value props:**
+- [Primary differentiator]
+- [Secondary differentiator]
+- [Emotional promise]
+
+**UI patterns:** [font family], [heading weight], [button style], [card style], [border radius], [icon library]
+**Special elements:** [waveform, gradient bg, pill tags, ...]
+
+**ASO keywords:** [keyword1], [keyword2], [keyword3], ... (from [fastlane/keywords.txt / derived])
+
+**Pre-filled config:**
+[Show the AppConfig object with app, brand, and video sections filled in]
+
+Does this look right? Anything to correct before I proceed?
+```
+```
+If fields are missing, note them: "I couldn't find brand colors — do you have a theme file, or should we pick colors together?"
+
+Only after confirmation, proceed to the screenshot collection step below.
+```
+
+### Collect screenshots (optional)
+
+After the extraction is confirmed, ask the user if they want to provide real app screenshots as visual references. Screenshots are **reference material, not content** — they are never embedded in the final output. Instead, the visual reference analysis extracts exact colors, shapes, spacing, and typography from the screenshots, which the skill uses to build animated mock UI that looks like the real app.
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Do you have screenshots of your app to use as screen content?",
+    header: "Screenshots",
+    options: [
+      { label: "Yes, I'll provide screenshots", description: "Highest fidelity — your screenshots are analyzed and the mock UI is built to match exactly." },
+      { label: "No, generate mock screens", description: "Skill builds UI from extracted code patterns. Good for most cases." }
+    ],
+    multiSelect: false
+  }]
+})
+```
+```
+**If the user provides screenshots:**
+
+1. Ask the user to provide screenshot file paths or drop them in the conversation
+2. Read each screenshot image to understand what it shows
+3. Map each screenshot to a screen from the extraction:
+```
+```
+I mapped your screenshots to app screens:
+   
+   - recording.png → Voice Recording screen
+   - transcription.png → Transcription Detail screen  
+   - scan-preview.png → Document Scan screen
+   - home.png → Home / Notes List screen
+   
+   Missing: Settings screen (will use mock UI for this one)
+   
+   Does this mapping look right?
+```
+```
+4. **Run visual reference analysis** on each screenshot (see below)
+5. Note any gaps — screens that have no screenshot. These will fall back to mock UI built from `uiPatterns`.
+6. Save the mapping AND the visual analysis to `screenshots` in `.appshot-context.json`
+```
+
+### Visual reference analysis
+
+**CRITICAL:** This step is mandatory when screenshots are provided. Without it, mock scenes will look generic and not match the real app.
+
+For each provided screenshot, study the image and write a structured visual spec. This spec is used in two ways:
+- **Direct use scenes**: The screenshot is used as-is via `<Img>`, so the spec confirms what it shows
+- **Mock scenes and gap-fill**: When a scene needs mock UI (for animation, missing screenshots, or modified content), the spec is the source of truth for how to style it
+
+**For each screenshot, document:**
+
+## [filename] → [Screen Name]
+
+**Layout:**
+- [top-to-bottom description of what appears: nav bar, content sections, bottom bar]
+- [approximate vertical proportions: "nav bar 8%, content 78%, tab bar 8%, home indicator 6%"]
+
+**Colors (sample from the image):**
+- Background: [exact color, e.g., "#0A1628 — very dark navy, NOT pure black"]
+- Cards/surfaces: [e.g., "#1A2940 — slightly lighter navy with subtle border"]
+- Accent: [e.g., "#3BB8E0 — teal/cyan for CTAs and active states"]
+- Text primary: [e.g., "#E8ECF1 — off-white"]
+- Text secondary: [e.g., "#6B7A8D — muted blue-grey"]
+- Highlight/badge: [e.g., "#E5C044 — warm yellow for 'Voice Recording' badge"]
+
+**Components (describe exactly what you see):**
+- Back button: [e.g., "48px rounded-square (#1A2940 bg), white chevron, no text"]
+- Nav actions: [e.g., "three icon buttons: more (⋯), share (↑), delete (🗑), same rounded-square style"]
+- Type badge: [e.g., "'Voice Recording' in yellow text on dark pill, microphone emoji prefix"]
+- Content cards: [e.g., "rounded-xl (~16px), #1A2940 bg, 1px border #2A3A50, 20px padding"]
+- Buttons: [e.g., "'Enhance · 2 credits' — outlined, teal border, rounded-full, 48px height"]
+- Tab bar: [e.g., "3 tabs with SF Symbol icons above labels, active=teal, inactive=grey, dark bg"]
+
+**Typography:**
+- Headings: [e.g., "32px, weight 700, white — 'May 28 at 11:03 PM'"]
+- Section headers: [e.g., "ALL CAPS, 13px, weight 600, letter-spacing 1px, teal — 'TRANSCRIPTION'"]
+- Body: [e.g., "16px, weight 400, off-white, line-height ~1.5"]
+- Labels: [e.g., "12px, weight 500, muted grey — metadata, tab labels"]
+
+**Special elements:**
+- [e.g., "Waveform: grey rounded-rect container, horizontal bars, blue play button 48px circle"]
+- [e.g., "Speed pills: row of 4 (0.75x, 1x, 1.5x, 2x), active has teal bg, others have dark bg"]
+- [e.g., "Coral/red horizontal divider line below title, 2px height"]
+- [e.g., "Vietnamese flag emoji + 'VI' in language selector pill"]
+```
+**Rules for the analysis:**
+- **Be exhaustive.** List EVERY distinct UI element visible in the screenshot. Count them. If you see 15 elements, document 15 elements. Common elements that get missed: nav bar action buttons (all of them, not just back), tab bar icons, speed/playback controls, CTAs, badge indicators, credit counters, language selectors, divider lines, home indicator.
+- Be precise about colors — sample from the actual image, don't guess. "#0A1628" is very different from "#000000".
+- Describe component shapes exactly: "48px rounded-square with 12px radius" not "rounded button".
+- Note spacing: "20px padding inside cards", "12px gap between elements".
+- Note what is NOT there: "no shadow on cards", "no border on buttons", "no separator between list items".
+- This analysis overrides `uiPatterns` from code extraction when they conflict — the screenshot is the visual truth.
+- **Sizes in the visual spec are phone-logical.** The 886px App Store Preview canvas is 2.25× wider than an iPhone 16 Pro (393px). All sizes must be multiplied by 2.25 when writing scene code: a 48px button becomes 108px, 16px text becomes 36px, 11px tab labels become 25px. The code-guide has a complete scale table.
+
+**Screenshot requirements** (tell the user):
+- Any resolution — these are reference images, not embedded in the output
+- Clean state — no notifications or debug banners (so the analysis captures the real design)
+- One screenshot per distinct screen/feature. Multiple states of the same screen welcome.
+- The skill will analyze your screenshots and build animated mock UI that matches your app's look exactly.
+
+**If the user declines**, set `screenshots: []` and proceed. The skill will generate mock UI from extracted patterns as before.
+
+After this step, proceed to the calling skill's next phase.
+```
+
+## Project Structure
+
+```
+src/
+  app-config.ts         # App metadata, brand colors, video settings
+  Root.tsx              # Remotion entry — registers the composition
+  [AppName]Preview.tsx  # Orchestrator — sequences scenes with <Sequence> + <SceneWrap>
+  scenes/
+    S1_[Name].tsx       # Custom scene components (one per scene)
+    S2_[Name].tsx
+    ...
+  components/           # Shared primitives library (imported from template)
+    PhoneFrame.tsx      # Device frame with bezel, Dynamic Island, spring entrance
+    AmbientBackground.tsx # Animated gradient bg with floating orbs
+    Caption.tsx         # Word-by-word animated caption with frosted pill
+    FadeIn.tsx          # Directional spring fade-in wrapper
+    SceneWrap.tsx       # Fade envelope for scene transitions
+    AppIcon.tsx         # App icon with optional glow pulse
+    TypeWriter.tsx      # Character-by-character text reveal
+    BrowserFrame.tsx    # macOS browser chrome (light/dark)
+    AnimatedCursor.tsx  # Bezier-interpolated cursor with click ripple
+    index.ts
+  config.ts             # Type definitions, device dimensions, defaults
+public/
+  icon.png              # App icon
+  *.png                 # Screenshots, assets
+```
+
+## Config Schema
+
+The config holds app identity, brand colors, and video settings. It does NOT contain scenes — scenes are custom components.
+
+```typescript
+interface AppConfig {
+  app: {
+    name: string;        // Display name
+    tagline: string;     // One-line value prop
+    icon: string;        // Filename in public/
+    platform: "ios" | "android" | "both";
+  };
+  brand: BrandColors;
+  video: {
+    fps: number;         // 30
+    width: number;       // 886
+    height: number;      // 1920
+    device: DevicePreset;
+    backgroundMusic?: string;       // Filename in public/
+    backgroundMusicVolume?: number; // 0-1
+  };
+}
+
+interface BrandColors {
+  primary: string;       // Main brand color (hex)
+  primaryLight: string;  // Tinted background
+  background: string;    // App background
+  surface: string;       // Card/container background
+  textPrimary: string;   // Main text
+  textSecondary: string; // Secondary/muted text
+  success: string;       // Positive states
+  danger: string;        // Destructive/error states
+  accent?: string;       // Optional secondary brand color
+}
+
+## Primitives Library
+
+Every component below is available in `src/components/`. Import from `"../components"`.
+
+### PhoneFrame
+
+Device mockup with bezel, side buttons, and notch/Dynamic Island. Wraps any content to look like a real phone screen.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Screen content |
+| `device` | `DevicePreset` | `"iphone-15"` | Device model |
+| `delay` | `number` | `0` | Entrance animation delay (frames) |
+| `scale` | `number` | `1` | Scale multiplier |
+| `screenBackground` | `string` | `"#FAFAF8"` | Background color inside the screen |
+
+**When to use:** Any scene showing app UI inside a phone. The core visual anchor for mobile app videos.
+
+### AmbientBackground
+
+Animated gradient background with floating blurred orbs. Sets the mood for each scene.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `brand` | `BrandColors` | required | Colors for gradient and orbs |
+| `variant` | `"light" \| "medium" \| "deep" \| "dark"` | `"light"` | Intensity/mood |
+
+**When to use:** Behind every scene. Use `"light"` or `"medium"` for feature/solution scenes, `"dark"` for problem/contrast scenes, `"deep"` for emotional/proof scenes.
+
+### Caption
+
+Bottom-anchored text overlay with word-by-word entrance animation. Dark pill background for readability.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `text` | `string` | required | Caption text (max 8 words) |
+| `delay` | `number` | `0` | Entrance delay (frames) |
+| `fontSize` | `number` | `44` | Font size in px |
+| `maxWidth` | `number` | `820` | Maximum container width |
+
+**When to use:** Every scene should have one. Captions tell the story for sound-off viewers.
+
+### FadeIn
+
+Wraps any element with a directional fade-in animation using Remotion spring.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Content to animate |
+| `delay` | `number` | `0` | Start frame |
+| `direction` | `"up" \| "down" \| "left" \| "right" \| "none"` | `"up"` | Slide direction |
+| `distance` | `number` | `40` | Slide distance in px |
+| `className` | `string` | — | Tailwind classes |
+| `style` | `CSSProperties` | — | Inline styles |
+
+**When to use:** Stagger card reveals, headline entrances, any element that should animate in.
+
+### SceneWrap
+
+Wraps each scene with fade-in/fade-out transitions (12 frames each). Used by the orchestrator.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Scene content |
+| `durationInFrames` | `number` | required | Total scene duration |
+| `fadeIn` | `boolean` | `true` | Enable fade-in |
+| `fadeOut` | `boolean` | `true` | Enable fade-out |
+
+**When to use:** In the orchestrator component, wrap each scene inside `<Sequence>` + `<SceneWrap>`.
+
+### AppIcon
+
+Renders the app icon with optional animated glow effect.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | required | Filename in `public/` or URL |
+| `size` | `number` | `120` | Icon size in px |
+| `glow` | `boolean` | `false` | Enable pulsing glow |
+| `glowColor` | `string` | `"rgba(0,122,255,0.4)"` | Glow color |
+
+**When to use:** CTA/closing scenes. Builds brand recognition.
+
+### TypeWriter
+
+Character-by-character text reveal with optional blinking cursor.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `text` | `string` | required | Full text to type out |
+| `startFrame` | `number` | required | Frame to begin typing |
+| `charsPerFrame` | `number` | `2` | Typing speed |
+| `className` | `string` | — | Tailwind classes |
+| `cursor` | `boolean` | `true` | Show blinking cursor |
+| `cursorColor` | `string` | `"#2196F3"` | Cursor color |
+
+**When to use:** Search bars, text inputs, chat messages, anywhere you want to simulate user typing.
+
+### BrowserFrame
+
+macOS-style browser chrome with traffic lights, address bar, and content area. Light and dark variants.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Page content |
+| `url` | `string` | `"app.example.com"` | Address bar text |
+| `delay` | `number` | `0` | Entrance animation delay (frames) |
+| `scale` | `number` | `1` | Scale multiplier |
+| `variant` | `"light" \| "dark"` | `"light"` | Chrome theme |
+
+### AnimatedCursor
+
+Bezier-interpolated cursor that moves between keyframe positions with click ripple effect.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `keyframes` | `CursorKeyframe[]` | required | `{ frame, x, y, click? }` positions |
+| `visible` | `boolean` | `true` | Show/hide cursor |
+
+## Animation Patterns
+
+The removed primitives (FloatingCard, StatCard, HeatMap, ProgressBar, AppStoreBadge, IconSet) were simple wrappers that constrained the agent with hardcoded sizes. Write these patterns inline instead, scaled appropriately for your canvas:
+
+**Animated counter** (before/after stat):
+```tsx
+const counter = spring({ frame, fps, delay: 10, config: { mass: 0.6, damping: 18, stiffness: 80 } });
+const value = Math.round(interpolate(counter, [0, 1], [beforeValue, afterValue]));
+```
+**Cell-by-cell grid fill** (heatmap/contribution grid):
+```
+```tsx
+{cells.map((cell, i) => {
+  const cellEnter = spring({ frame, fps, delay: baseDelay + i * 0.4, config: { mass: 0.2, damping: 10, stiffness: 180 } });
+  return <div key={i} style={{ opacity: 0.3 + cellEnter * 0.7, transform: `scale(${0.6 + cellEnter * 0.4})` }} />;
+})}
+```
+**Progress bar fill**:
+```
+```tsx
+const progress = interpolate(frame, [delay, delay + 30], [0, targetPercent], { extrapolateRight: "clamp" });
+<div style={{ width: `${progress}%`, height, backgroundColor: color, borderRadius }} />
+```
+**Spring-entrance card** (replaces FloatingCard):
+```
+```tsx
+const entrance = spring({ frame, fps, delay, config: { mass: 0.8, damping: 14, stiffness: 120 } });
+<div style={{ opacity: entrance, transform: `translateY(${(1 - entrance) * 20}px)`, borderRadius, padding, background }}>
+```
+**App Store / Play Store badge** (for Marketing CTA scenes):
+```
+```tsx
+// iOS badge — black rounded rect with Apple SVG
+<div style={{ background: "#000", borderRadius: 14, padding: "14px 28px", display: "flex", alignItems: "center", gap: 12 }}>
+  <svg width="28" height="34" viewBox="0 0 28 34" fill="white">
+    <path d="M23.2 17.8c0-3.6 2.9-5.3 3-5.4-1.6-2.4-4.2-2.7-5.1-2.8-2.1-.2-4.2 1.3-5.3 1.3-1.1 0-2.8-1.2-4.6-1.2C8.5 9.8 6 11.2 4.6 13.5c-2.8 4.9-.7 12.1 2 16.1 1.3 1.9 2.9 4.1 5 4 2-.1 2.8-1.3 5.2-1.3 2.4 0 3.1 1.3 5.2 1.3 2.2 0 3.5-2 4.8-3.9 1.5-2.2 2.1-4.3 2.2-4.4 0-.1-4.2-1.6-4.2-6.4zM19.3 7.5c1.1-1.3 1.8-3.2 1.6-5-1.6.1-3.4 1-4.6 2.3-1 1.2-1.9 3-1.6 4.8 1.7.2 3.5-.9 4.6-2.1z" />
+  </svg>
+  <div>
+    <div style={{ fontSize: 16, color: "rgba(255,255,255,0.8)" }}>Download on the</div>
+    <div style={{ fontSize: 28, fontWeight: 600, color: "#FFF" }}>App Store</div>
+  </div>
+</div>
+
+## Device Presets
+
+| Preset | Screen | Notch | Store |
+|--------|--------|-------|-------|
+| `iphone-16-pro` | 393x852 | Dynamic Island | App Store |
+| `iphone-15` | 375x812 | Dynamic Island | App Store |
+| `ipad-pro-13` | 1024x1366 | None | App Store (iPad) |
+| `pixel-9` | 412x915 | Punch hole | Play Store |
+
+### Store-to-Device Mapping
+
+| Store | Composition ID suffix | Device preset |
+|-------|----------------------|---------------|
+| App Store | `-AppStore` | `iphone-16-pro` |
+| Play Store | `-PlayStore` | `pixel-9` |
+
+For multi-store projects, Root.tsx registers one `<Composition>` per store. Scenes are shared — only the device frame (and navigation chrome style) differ. Canvas stays 886×1920 for both. Note: App Store Preview videos do not include store badges in the CTA (redundant inside the store listing); Marketing videos include an inline store badge in the CTA (see Animation Patterns above for the SVG snippet).
+
+## Output Targets
+
+AppShot supports two output targets with different visual rules:
+
+| Target | Use case | Device frame | Overlay text | Screen content |
+|--------|----------|-------------|-------------|----------------|
+| **App Store Preview** | App Store / Play Store video previews and screenshots | **No device frame.** Full-bleed app screen fills the entire canvas edge-to-edge. | Text overlays appear *on top of* the app screen (semi-transparent pill background for readability). | Must include navigation chrome (status bar, nav bar, tab bar) to look like a real screenshot. |
+| **Marketing** | Social media, website, pitch decks, ads | Device frame (PhoneFrame) wrapping the app screen. | Text and cards appear *beside* or *around* the device frame. | Navigation chrome optional (PhoneFrame provides the "device" context). |
+
+**Why this matters:** Apple rejects App Store previews that include device frames or that don't sufficiently show the app in use. The App Store Preview target ensures compliance. The Marketing target preserves the current polished look for non-store contexts.
+
+**Default:** App Store Preview for `appshot-videos` and `appshot-images`. Marketing for social/web contexts.
+
+When the user selects **App Store Preview** target:
+- Do NOT use PhoneFrame in any scene
+- App UI fills the full 886×1920 canvas (videos) or store-required dimensions (screenshots)
+- Include status bar, navigation bar, tab bar, and home indicator in every mock screen
+- Caption/overlay text uses a semi-transparent pill background so it's readable over the app UI
+- The result should look like a screen recording with text overlays
+
+When the user selects **Marketing** target:
+- Use PhoneFrame at scale 1.5 as before
+- Text, cards, and badges appear outside/around the device frame
+- Navigation chrome inside the phone is nice-to-have but not required
+
+## Store Requirements
+
+### Videos
+
+| Platform | Dimensions | Duration | Format |
+|----------|-----------|----------|--------|
+| iPhone 6.7" | 886x1920 | 15-30s | H.264, MP4/MOV |
+| iPhone 6.1" | 886x1920 | 15-30s | H.264, MP4/MOV |
+| iPad 13" | 1200x1600 | 15-30s | H.264, MP4/MOV |
+| Google Play | 886x1920 | 15-30s | H.264, MP4 |
+
+Default output is 886×1920. This canvas works for both App Store (iPhone 6.7″ native) and Google Play. All sizing rules in appshot-videos are calibrated for this canvas width.
+
+### Screenshots
+
+iOS App Store:
+| Device | Dimensions (portrait) | Required |
+|--------|----------------------|----------|
+| iPhone 6.9" | 1320x2868 | Yes (mandatory primary) |
+| iPhone 6.7" | 1290x2796 | Optional (Apple scales from 6.9") |
+| iPhone 6.5" | 1242x2688 | Optional (legacy) |
+| iPad 13" | 2064x2752 | Required if app supports iPad |
+
+Google Play:
+| Device | Dimensions (portrait) | Notes |
+|--------|----------------------|-------|
+| Phone | 1080x1920 | Recommended standard |
+| 7" Tablet | 1200x1920 | If app targets 7" tablets |
+| 10" Tablet | 1600x2560 | If app targets 10" tablets |
+
+## Project Setup
+
+The skill scaffolds an `appshot-video/` directory inside the target project during Phase 3 code generation. See code-guide.md for the full scaffolding steps.
+
+```bash
+cd appshot-video
+npm run dev     # Preview at localhost:3000
+npm run build   # Render to out/AppPreview.mp4
+```
+
+## Orchestrator Pattern
+
+The orchestrator sequences scenes using Remotion `<Sequence>` and wraps each with `<SceneWrap>` for fade transitions.
+
+```tsx
+import { Composition, Sequence } from "remotion";
+import { SceneWrap } from "./components";
+import { S1_Hook } from "./scenes/S1_Hook";
+import { S2_Feature } from "./scenes/S2_Feature";
+import { S3_CTA } from "./scenes/S3_CTA";
+
+const scenes = [
+  { component: S1_Hook, duration: 120 },
+  { component: S2_Feature, duration: 150 },
+  { component: S3_CTA, duration: 120 },
+];
+
+export const AppPreview: React.FC = () => {
+  let offset = 0;
+  return (
+    <>
+      {scenes.map(({ component: Scene, duration }, i) => {
+        const from = offset;
+        offset += duration;
+        return (
+          <Sequence key={i} from={from} durationInFrames={duration}>
+            <SceneWrap durationInFrames={duration}>
+              <Scene />
+            </SceneWrap>
+          </Sequence>
+        );
+      })}
+    </>
+  );
+};
+
+## Shared Resources
+
+- Copy principles: [copy-principles.md`copy-principles.md`
+- Extraction logic is built into this skill (see Extraction & Context Caching above)
+
+## Source
+
+Rewritten for AICUT from [`trunghaiy/appshot`](https://github.com/trunghaiy/appshot)
+(MIT), skills/appshot-core/SKILL.md. The method is that skill's own; the way it runs is AICUT's.
+
+The repository holds 4 skills; this is the one its entry stands for.