@shaykec/app-agent 1.0.4 → 1.0.5

package/.claude/skills/ui-tester/SKILL.md

@@ -432,6 +432,65 @@ Update `output/{app-name}/reports/summary.json` — read the file, append this s
 - Set `"filesWritten"` to the total count of files created/modified
 - Set `"duration"` to the total elapsed time
 
+## Preview Capture
+
+During testing, save screenshots and element tree data for the web preview feature. This enables `--preview <app-name>` to generate a clickable prototype.
+
+### When to Capture
+
+After inspecting each screen (in Phase 1, Step 2), save the screenshot and extract interactive element bounding boxes.
+
+### How to Capture
+
+1. **Create the preview directory** if it doesn't exist: `output/{app-name}/preview/`
+
+2. **For each screen you inspect**, save the screenshot:
+   - Use `inspect()` as normal — it returns a screenshot and element tree
+   - Save the screenshot image to `output/{app-name}/preview/{screen-id}.png`
+     - `screen-id` should be a kebab-case identifier: `home`, `explore`, `item-detail`, `settings`, `profile`, etc.
+   - From the element tree, extract bounding boxes of interactive elements (buttons, list items, tabs, etc.)
+   - Record which screen each interactive element navigates to (based on what you observed during testing)
+
+3. **After all screens are tested**, write `output/{app-name}/preview/screens.json`:
+
+```json
+{
+  "appName": "{App Display Name}",
+  "platform": "{ios|android}",
+  "template": "{template name if known}",
+  "designBrand": "{brand name if known}",
+  "screens": [
+    {
+      "id": "{screen-id}",
+      "label": "{Human Readable Screen Name}",
+      "screenshot": "{screen-id}.png",
+      "hotspots": [
+        {
+          "x": 0, "y": 0, "w": 0, "h": 0,
+          "target": "{target-screen-id}",
+          "label": "{Element Label}"
+        }
+      ]
+    }
+  ],
+  "initialScreen": "{first-screen-id}"
+}
+```
+
+### Hotspot Rules
+
+- `x`, `y`, `w`, `h` are bounding box coordinates in screenshot pixel space
+- `target` is the `id` of the screen that element navigates to (must match a screen in the `screens` array)
+- Only include hotspots for elements that navigate to another screen in the app (tabs, list items, back buttons)
+- Omit hotspots for elements that don't navigate (toggles, text fields, action sheets)
+- If you don't know the target screen for an element, omit that hotspot
+
+### Important
+
+- This capture is **in addition to** normal testing — do NOT skip any testing steps
+- The preview directory and files are only used for the web preview feature
+- If preview capture fails for any reason, log a warning but do NOT fail the test
+
 ## Important Rules
 
 - ONLY use ai-tester MCP tools for device interaction — NOT shell commands like `xcrun simctl`

package/.cursor/skills/android-customizer/SKILL.md

@@ -144,19 +144,26 @@ Templates now include an **offline-first data layer**. Understand these componen
   - `reset()` function references correct defaults
 - `data/SyncManager.kt` — if entity types were renamed, update domain methods
 
-**ViewModel/Screen patterns** (how screens consume data):
+**Screen/ViewModel patterns** (how screens consume data):
+
+Screens and ViewModels use the `DataRepository` interface abstraction, not `MockDataProvider` directly:
 ```kotlin
-// Screens collect StateFlow
-val products by MockDataProvider.products.collectAsState()
+// Screens get the repository from DataSourceResolver
+val repository = remember { DataSourceResolver.repository }
+val items by repository.items.collectAsState()
+val categories by repository.categories.collectAsState()
 
-// ViewModels read from MockDataProvider
-val products = MockDataProvider.products.value
+// CRUD via the repository
+repository.addItem(newItem)
+repository.deleteItem(item)
+repository.toggleFavorite(item)
 
-// CRUD via SyncManager
+// If SyncManager exists, it wraps the repository
 SyncManager.addProduct(newProduct)
-SyncManager.deleteProduct(id)
 ```
 
+When customizing screens or ViewModels, ALWAYS use `DataSourceResolver.repository`, never `MockDataProvider` directly. This ensures the app works with any data source (mock, localStorage, Firebase, Supabase, custom API).
+
 **OfflineBanner integration** — add to main navigation:
 ```kotlin
 Column {
@@ -176,26 +183,53 @@ class MyApplication : Application() {
 }
 ```
 
-### Step 7 — MockDataProvider Verification
+### Step 7 — Data Layer Verification
+
+Verify the data layer uses the correct patterns:
 
-Verify MockDataProvider uses the correct patterns:
+**DataRepository interface:**
+```kotlin
+interface DataRepository {
+    val items: StateFlow<List<Item>>     // Domain entities
+    val categories: StateFlow<List<Category>>
+    val favoriteItems: StateFlow<List<Item>>
+    fun loadData()
+    fun addItem(item: Item)
+    // ... all CRUD + query methods
+}
+```
 
+**MockDataProvider (implements DataRepository):**
 ```kotlin
-object MockDataProvider {
+object MockDataProvider : DataRepository {
     private val _products = MutableStateFlow(defaultProducts)
-    val products: StateFlow<List<Product>> = _products.asStateFlow()
+    override val products: StateFlow<List<Product>> = _products.asStateFlow()
     
     val defaultProducts = listOf(...)  // Seed data
     
-    fun addProduct(product: Product) { ... }  // CRUD
+    override fun addProduct(product: Product) { ... }  // CRUD
     fun reset() { ... }  // Reset to defaults
 }
 ```
 
-- Verify seed data matches the new domain
-- Ensure CRUD functions reference correct entity types
-- Verify `reset()` works correctly
-- Check that helper functions use `.value` to read from StateFlows
+**DataSourceResolver:**
+```kotlin
+object DataSourceResolver {
+    val repository: DataRepository
+        get() = when (AppConfig.DataSource.active) {
+            AppConfig.DataSource.SourceType.LOCAL_STORAGE -> MockDataProvider  // TODO: LocalStorageProvider
+            AppConfig.DataSource.SourceType.MOCK -> MockDataProvider
+        }
+}
+```
+
+Verify:
+- DataRepository interface matches MockDataProvider's public members
+- MockDataProvider implements DataRepository with `override` on all members
+- DataSourceResolver returns the correct implementation
+- Screens use `DataSourceResolver.repository`, not `MockDataProvider` directly
+- Seed data matches the new domain
+- CRUD functions reference correct entity types
 
 ## Report Output
 

package/.cursor/skills/appconfig-customization/SKILL.md

@@ -67,6 +67,21 @@ Work through each category in order:
 - If the design-system skill has not run yet, choose colours appropriate for the app's domain
 - Dark mode support — keep enabled (dark mode is handled by platform theme files)
 
+#### CUSTOMIZE:DATASOURCE
+- `DataSource.active` — set the active data source type
+- Default is `.mock` during initial customization (so screens show populated data for testing)
+- Set to `.localStorage` for the final shipped app (so users start with empty state)
+- Other options (`.firebase`, `.supabase`, `.custom`) require BaaS shared modules to be integrated
+- Example:
+  ```swift
+  // iOS
+  static let active: SourceType = .mock  // Use .localStorage for production
+  ```
+  ```kotlin
+  // Android
+  val active: SourceType = SourceType.MOCK  // Use LOCAL_STORAGE for production
+  ```
+
 #### CUSTOMIZE:CATEGORIES (if applicable)
 - Update category lists to match the app's domain
 - E.g., for a pet grooming booking app: "Grooming", "Bath", "Nail Trim", "Full Package"

package/.cursor/skills/customization-planner/SKILL.md

@@ -144,7 +144,23 @@ Based on the app domain and the existing MockDataProvider structure:
 - **Categories:** List of 6-8 domain categories with names and icons
 - **Sample items:** For each category, 3-5 items with realistic names, descriptions, and values
 - Keep the same item counts as the template
-- Note any entity type renames needed for SyncManager
+- Note any entity type renames needed for DataRepository protocol, DataSourceResolver, and SyncManager
+- **Data source:** Default data source is `localStorage` (Core Data / Room). Mock data is for testing/dev.
+
+### Step 5b — Produce Data Repository Spec
+
+Document how the DataRepository protocol needs to be updated for the new domain:
+
+```
+DATA REPOSITORY:
+  Entity renames:
+    - Item → {DomainEntity} (e.g., Item → Recipe)
+    - Category → {DomainCategory} (e.g., Category → CuisineType)
+  Protocol updates:
+    - Property renames: items → {domainPlural} (e.g., items → recipes)
+    - Method renames: addItem → add{Entity} (e.g., addItem → addRecipe)
+  DataSource default: .mock  (agent sets .mock during customization; switch to .localStorage for shipped app)
+```
 
 ### Step 6 — Produce Module Integration Plan
 

package/.cursor/skills/ios-customizer/SKILL.md

@@ -137,18 +137,31 @@ Templates now include an **offline-first data layer**. Understand these componen
 - `Data/SyncManager.swift` — if entity types were renamed, update domain methods
 
 **ViewModel patterns** (how views consume data):
+
+ViewModels use the `DataRepository` protocol abstraction, not `MockDataProvider` directly:
 ```swift
-// ViewModels observe MockDataProvider.shared
-@ObservedObject var store = MockDataProvider.shared
+// ViewModels depend on the DataRepository protocol
+private let repository: any DataRepository
+
+init(repository: any DataRepository = DataSourceResolver.repository) {
+    self.repository = repository
+}
+
+// Read data via the protocol
+let items = repository.items
+let categories = repository.categories
 
-// Or use EnvironmentObject if injected
-@EnvironmentObject var store: MockDataProvider
+// CRUD via the protocol
+repository.addItem(newItem)
+repository.deleteItem(item)
+repository.toggleFavorite(item)
 
-// CRUD via SyncManager
+// If SyncManager exists, it wraps the repository
 SyncManager.shared.addProduct(newProduct)
-SyncManager.shared.deleteProduct(id)
 ```
 
+When customizing ViewModels, ALWAYS use `repository` (from `DataSourceResolver`), never `MockDataProvider.shared` directly. This ensures the app works with any data source (mock, localStorage, Firebase, Supabase, custom API).
+
 **OfflineBanner integration** — add to main navigation views:
 ```swift
 VStack(spacing: 0) {
@@ -157,12 +170,25 @@ VStack(spacing: 0) {
 }
 ```
 
-### Step 6 — MockDataProvider Verification
+### Step 6 — Data Layer Verification
+
+Verify the data layer uses the correct patterns:
 
-Verify the MockDataProvider uses the correct patterns:
+**DataRepository protocol:**
+```swift
+protocol DataRepository: AnyObject {
+    var items: [Item] { get }       // Domain entities
+    var categories: [Category] { get }
+    var favoriteItems: [Item] { get }
+    func loadData()
+    func addItem(_ item: Item)
+    // ... all CRUD + query methods
+}
+```
 
+**MockDataProvider (conforms to DataRepository):**
 ```swift
-class MockDataProvider: ObservableObject {
+class MockDataProvider: ObservableObject, DataRepository {
     static let shared = MockDataProvider()
     
     @Published var products: [Product]  // Reactive, mutable
@@ -174,10 +200,25 @@ class MockDataProvider: ObservableObject {
 }
 ```
 
-- Verify seed data matches the new domain
-- Ensure CRUD methods reference correct entity types
-- Verify `reset()` works correctly
-- Check that `@Published` properties are being observed by ViewModels
+**DataSourceResolver:**
+```swift
+enum DataSourceResolver {
+    static var repository: any DataRepository {
+        switch AppConfig.DataSource.active {
+        case .localStorage: return MockDataProvider.shared  // TODO: LocalStorageProvider
+        case .mock: return MockDataProvider.shared
+        }
+    }
+}
+```
+
+Verify:
+- DataRepository protocol matches MockDataProvider's public interface
+- MockDataProvider conforms to DataRepository
+- DataSourceResolver returns the correct implementation
+- ViewModels use `DataSourceResolver.repository`, not `MockDataProvider.shared` directly
+- Seed data matches the new domain
+- CRUD methods reference correct entity types
 
 ## Report Output
 

package/.cursor/skills/mock-data-update/SKILL.md

@@ -27,7 +27,7 @@ Templates use an **offline-first architecture** with these components:
 
 ## Instructions
 
-### Step 1 — Read the Current MockDataProvider
+### Step 1 — Read the Current MockDataProvider and DataRepository
 
 Read `MockDataProvider.swift` (iOS) or `MockDataProvider.kt` (Android). Understand:
 - What data models exist (products, services, users, transactions, etc.)
@@ -38,6 +38,8 @@ Read `MockDataProvider.swift` (iOS) or `MockDataProvider.kt` (Android). Understa
 - What properties each model has
 - How the data is structured (arrays, dictionaries, nested objects)
 
+Also read `DataRepository.swift` (iOS) or `DataRepository.kt` (Android) — the protocol/interface that MockDataProvider conforms to. You'll need to update it if entity types are renamed.
+
 ### Step 2 — Plan Domain-Specific Data
 
 Based on the user's app description, plan realistic sample data. Examples:
@@ -80,9 +82,13 @@ For each collection:
 6. **Use realistic dates** — recent dates, not 1970 or 2099
 7. **Use realistic image placeholder names** — even if images don't exist, name them descriptively
 
-### Step 4 — Update SyncManager Domain Methods (if entity types changed)
+### Step 4 — Update DataRepository Protocol and SyncManager (if entity types changed)
+
+If the domain entity types have changed names (e.g., "product" → "drink"):
 
-If the domain entity types have changed names (e.g., "product" → "drink"), update the SyncManager's domain methods to match. This is only needed if entity types were renamed. If they kept the same names, no changes needed.
+1. **DataRepository** — Update the `DataRepository.swift/.kt` protocol/interface to use the new entity type names. The protocol must always mirror MockDataProvider's public interface.
+2. **DataSourceResolver** — If the protocol name changed, update the resolver's return type.
+3. **SyncManager** — Update domain methods to match the new entity names. Only needed if entity types were renamed.
 
 ### Step 5 — Verify Consistency
 
@@ -117,6 +123,8 @@ After rewriting the mock data, update `output/{app-name}/reports/summary.json`
 - **NEVER change the infrastructure files** (NetworkMonitor, LocalPersistence, OfflineBanner)
 - **NEVER change model property names** — only change VALUES in seed data
 - **DO update `default*` / `makeDefault*` seed data properties** — these are what you customize
+- **DO update DataRepository** if entity types are renamed — the protocol must mirror MockDataProvider
+- **DO update DataSourceResolver** if the protocol reference changes
 - Keep data realistic and professional — this data shows in the UI during demos
 - Maintain approximately the same data volume as the original template
 - If the template uses image asset names, update them to be descriptive but don't worry about actual image files

package/.cursor/skills/ui-tester/SKILL.md

@@ -466,6 +466,65 @@ Update `output/{app-name}/reports/summary.json` — read the file, append this s
 - Set `"filesWritten"` to the total count of files created/modified
 - Set `"duration"` to the total elapsed time
 
+## Preview Capture
+
+During testing, save screenshots and element tree data for the web preview feature. This enables `--preview <app-name>` to generate a clickable prototype.
+
+### When to Capture
+
+After inspecting each screen (in Phase 1, Step 2), save the screenshot and extract interactive element bounding boxes.
+
+### How to Capture
+
+1. **Create the preview directory** if it doesn't exist: `output/{app-name}/preview/`
+
+2. **For each screen you inspect**, save the screenshot:
+   - Use `inspect()` as normal — it returns a screenshot and element tree
+   - Save the screenshot image to `output/{app-name}/preview/{screen-id}.png`
+     - `screen-id` should be a kebab-case identifier: `home`, `explore`, `item-detail`, `settings`, `profile`, etc.
+   - From the element tree, extract bounding boxes of interactive elements (buttons, list items, tabs, etc.)
+   - Record which screen each interactive element navigates to (based on what you observed during testing)
+
+3. **After all screens are tested**, write `output/{app-name}/preview/screens.json`:
+
+```json
+{
+  "appName": "{App Display Name}",
+  "platform": "{ios|android}",
+  "template": "{template name if known}",
+  "designBrand": "{brand name if known}",
+  "screens": [
+    {
+      "id": "{screen-id}",
+      "label": "{Human Readable Screen Name}",
+      "screenshot": "{screen-id}.png",
+      "hotspots": [
+        {
+          "x": 0, "y": 0, "w": 0, "h": 0,
+          "target": "{target-screen-id}",
+          "label": "{Element Label}"
+        }
+      ]
+    }
+  ],
+  "initialScreen": "{first-screen-id}"
+}
+```
+
+### Hotspot Rules
+
+- `x`, `y`, `w`, `h` are bounding box coordinates in screenshot pixel space
+- `target` is the `id` of the screen that element navigates to (must match a screen in the `screens` array)
+- Only include hotspots for elements that navigate to another screen in the app (tabs, list items, back buttons)
+- Omit hotspots for elements that don't navigate (toggles, text fields, action sheets)
+- If you don't know the target screen for an element, omit that hotspot
+
+### Important
+
+- This capture is **in addition to** normal testing — do NOT skip any testing steps
+- The preview directory and files are only used for the web preview feature
+- If preview capture fails for any reason, log a warning but do NOT fail the test
+
 ## Important Rules
 
 - ONLY use ai-tester MCP tools for device interaction — NOT shell commands like `xcrun simctl`

package/dist/cli.d.ts

@@ -7,18 +7,27 @@ export interface CliFlags {
     list?: boolean;
     run?: string;
     engine?: Engine;
+    noPreview?: boolean;
 }
 export interface CliParseResult {
     input: UserInput;
     flags: CliFlags;
 }
-/** Result when a management command (--list, --run, --test) is detected */
+/** Result when a management command (--list, --run, --test, --preview, --screenshot) is detected */
 export interface ManagementCommand {
-    command: "list" | "run" | "test";
+    command: "list" | "run" | "test" | "preview" | "screenshot";
     appName?: string;
     engine?: Engine;
     model?: Model;
 }
+/** Result from interactive mode: either a build input or a management command */
+export type InteractiveResult = {
+    kind: "build";
+    input: UserInput;
+} | {
+    kind: "management";
+    command: ManagementCommand;
+};
 /**
  * Check if the user passed a management command (--list, --run).
  * These don't require --description / --platform and skip the build flow entirely.
@@ -29,11 +38,16 @@ export declare function parseManagementCommand(): ManagementCommand | null;
  * Returns UserInput + CliFlags if all required args are present, null otherwise.
  */
 export declare function parseCliArgs(): CliParseResult | null;
+/**
+ * Show an interactive picker for apps in output/.
+ * Scans output/ directories, reads summary.json, and presents a select menu.
+ */
+export declare function pickApp(): Promise<string>;
 /**
  * Collect user input interactively via the terminal.
- * Returns the app description, target platform, and model choice.
+ * Returns either a build input or a management command.
  */
-export declare function collectUserInput(): Promise<UserInput>;
+export declare function collectUserInput(): Promise<InteractiveResult>;
 /** Display a summary of what will be built and ask for confirmation */
 export declare function confirmInput(input: UserInput): Promise<boolean>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA2B,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGrF,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAE9B,mDAAmD;AACnD,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,iBAAiB,GAAG,IAAI,CAuDjE;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,cAAc,GAAG,IAAI,CAuFpD;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,SAAS,CAAC,CA2I3D;AAmHD,uEAAuE;AACvE,wBAAsB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAmDrE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA2B,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIrF,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAE9B,mDAAmD;AACnD,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,oGAAoG;AACpG,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEvD;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,iBAAiB,GAAG,IAAI,CAyEjE;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,cAAc,GAAG,IAAI,CA2FpD;AAED;;;GAGG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CA4D/C;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAqLnE;AAmHD,uEAAuE;AACvE,wBAAsB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAmDrE"}