create-disposabl-app 0.1.0 → 0.1.2

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/native-turbo-modules.md

@@ -0,0 +1,210 @@
+---
+title: Fast Native Modules
+impact: HIGH
+tags: turbo-modules, native, swift, kotlin, c++
+---
+
+# Skill: Fast Native Modules
+
+Build performant Turbo Modules using modern languages and background threading.
+
+## Quick Pattern
+
+**Incorrect (sync method blocks JS thread):**
+
+```swift
+@objc func heavyWork() -> NSNumber {
+    Thread.sleep(forTimeInterval: 2)  // Blocks JS for 2s!
+    return 42
+}
+```
+
+**Correct (async on background thread):**
+
+```swift
+@objc func heavyWork(
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: RCTPromiseRejectBlock
+) {
+    DispatchQueue.global().async {
+        let result = self.compute()
+        resolve(result)
+    }
+}
+```
+
+## When to Use
+
+- Creating new native modules
+- Optimizing existing module performance
+- Heavy computation needs to run off JS thread
+- Cross-platform C++ code needed
+
+## Prerequisites
+
+- React Native Builder Bob for scaffolding
+
+```bash
+npx create-react-native-library@latest my-library
+```
+
+## Step-by-Step Instructions
+
+### 1. Scaffold with Builder Bob
+
+```bash
+npx create-react-native-library@latest awesome-library
+# Follow prompts: choose Turbo Module, select languages
+```
+
+Creates ready-to-publish library with:
+- iOS (Obj-C/Swift) support
+- Android (Kotlin) support
+- TypeScript definitions
+- Codegen setup
+
+For local modules:
+
+```bash
+npx create-react-native-library@latest awesome-library --local
+```
+
+### 2. Run on Background Thread (iOS)
+
+```swift
+@objc func heavyOperation(
+    _ input: Double,
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: RCTPromiseRejectBlock
+) {
+    DispatchQueue.global().async {
+        // Heavy work on background thread
+        let result = self.expensiveComputation(input)
+        resolve(result)
+    }
+}
+```
+
+### 3. Run on Background Thread (Android)
+
+```kotlin
+class AwesomeLibraryModule(reactContext: ReactApplicationContext) :
+    NativeAwesomeLibrarySpec(reactContext) {
+    
+    private val moduleScope = CoroutineScope(Dispatchers.Default + SupervisorJob())
+    
+    override fun heavyOperation(input: Double, promise: Promise?) {
+        moduleScope.launch {
+            // Heavy work on coroutine
+            val result = expensiveComputation(input)
+            promise?.resolve(result)
+        }
+    }
+    
+    override fun invalidate() {
+        super.invalidate()
+        moduleScope.cancel()  // Prevent memory leaks!
+    }
+}
+```
+
+Use structured concurrency: keep a module-owned `CoroutineScope`, cancel it in `invalidate()`, avoid `GlobalScope.launch`, use `SupervisorJob` so one failed operation does not cancel unrelated in-flight work, and choose `Dispatchers.Default` for CPU work or `Dispatchers.IO` for disk/network/database work.
+
+### 4. Use C++ for Cross-Platform Code
+
+Create C++ Turbo Module for shared logic:
+
+```cpp
+// MyCppModule.h
+#pragma once
+
+#include <ReactCommon/TurboModule.h>
+
+namespace facebook::react {
+
+class MyCppModule : public TurboModule {
+public:
+    MyCppModule(std::shared_ptr<CallInvoker> jsInvoker);
+    
+    double multiply(double a, double b);
+};
+
+} // namespace facebook::react
+```
+
+Follow the registration mechanism documented for the React Native version you target. Avoid copying old `+load` registration workarounds unless current RN docs or template output still require them.
+
+## Threading Summary
+
+| Method Type | Default Thread | Best Practice |
+|-------------|----------------|---------------|
+| Sync | JS thread | Keep fast (<16ms) |
+| Async | Native modules thread | OK for moderate work |
+| Heavy async | Custom background | Use DispatchQueue/Coroutines |
+
+## Language Interop Costs
+
+| Interface | Overhead | Notes |
+|-----------|----------|-------|
+| Obj-C / Obj-C++ ↔ C++ | Low | Common iOS interop path |
+| Swift ↔ C++ | Version-dependent | Verify supported Swift/Xcode/RN setup |
+| Kotlin ↔ C++ (JNI) | Higher | Batch calls and avoid per-item crossings |
+| C++ Turbo Module | Low | JSI direct access when correctly registered |
+
+**Tip**: C++ Turbo Modules skip JNI at runtime since JS holds direct C++ function references via JSI.
+
+## Code Example: Complete Async Operation
+
+```typescript
+// TypeScript interface
+export interface Spec extends TurboModule {
+    multiply(a: number, b: number): number;  // Sync
+    heavyOperation(input: number): Promise<number>;  // Async
+}
+```
+
+```kotlin
+// Android implementation
+override fun heavyOperation(input: Double, promise: Promise?) {
+    moduleScope.launch {
+        try {
+            val result = withContext(Dispatchers.Default) {
+                // Simulate heavy work
+                delay(1000)
+                input * 2
+            }
+            promise?.resolve(result)
+        } catch (e: Exception) {
+            promise?.reject("ERROR", e.message)
+        }
+    }
+}
+```
+
+```swift
+// iOS implementation
+@objc func heavyOperation(
+    _ input: Double,
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+) {
+    DispatchQueue.global(qos: .userInitiated).async {
+        // Simulate heavy work
+        Thread.sleep(forTimeInterval: 1.0)
+        let result = input * 2
+        resolve(result)
+    }
+}
+```
+
+## Common Pitfalls
+
+- **Sync methods that block**: Keep sync methods trivial and deterministic; make anything that can block, allocate heavily, perform I/O, or wait on locks async/background work
+- **Forgetting to cancel coroutine scope**: Causes memory leaks
+- **Not handling errors in async**: Always try/catch with reject
+- **Accessing UI from background**: Dispatch to main thread
+
+## Related Skills
+
+- [native-threading-model.md](./native-threading-model.md) - Thread details
+- [native-memory-patterns.md](./native-memory-patterns.md) - Memory in native code

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/native-view-flattening.md

@@ -0,0 +1,180 @@
+---
+title: View Flattening
+impact: MEDIUM
+tags: views, flattening, collapsable, hierarchy
+---
+
+# Skill: View Flattening
+
+Understand and debug React Native's view flattening optimization.
+
+## Quick Pattern
+
+**Problem (children get flattened unexpectedly):**
+
+```jsx
+<NativeTabBar>
+  <Tab1 />  // May be flattened, breaking native component
+  <Tab2 />
+</NativeTabBar>
+```
+
+**Solution (prevent flattening):**
+
+```jsx
+<NativeTabBar>
+  <Tab1 collapsable={false} />
+  <Tab2 collapsable={false} />
+</NativeTabBar>
+```
+
+## When to Use
+
+- Native component receives unexpected number of children
+- Layout debugging with native components
+- Building native components that accept children
+- Understanding React Native rendering
+
+> **Note**: This skill involves visual view hierarchy tools (Xcode Debug View Hierarchy, Android Layout Inspector). Use `agent-device` for screen evidence; install it through the environment's approved/trusted path or ask the user if verification needs it and it is missing. Native hierarchy inspection may still require Xcode, Android Studio, or human review. Record native child counts and component names in text when asking an agent to reason about them.
+
+## What is View Flattening?
+
+React Native's renderer automatically removes "layout-only" views that:
+- Only affect layout (no visual rendering)
+- Don't need to exist in native view hierarchy
+
+**Benefits**: Reduced memory, faster rendering, shallower view tree.
+
+## The Problem with Native Components
+
+```tsx
+// You expect 3 children
+<MyNativeComponent>
+  <Child1 />
+  <Child2 />
+  <Child3 />
+</MyNativeComponent>
+```
+
+If a child wrapper is flattened, native code may receive a different child count or shape than the JS tree suggests.
+
+## Preventing Flattening with `collapsable`
+
+```tsx
+<MyNativeComponent>
+  <Child1 collapsable={false} />
+  <Child2 collapsable={false} />
+  <Child3 collapsable={false} />
+</MyNativeComponent>
+```
+
+The direct views marked `collapsable={false}` are preserved as native children.
+
+## Debugging View Hierarchy
+
+![View Hierarchy Flattening](images/view-hierarchy-flattening.png)
+
+Use native debugging tools to see the actual view hierarchy:
+
+### Xcode (iOS)
+
+1. Run app via Xcode
+2. Click **"Debug View Hierarchy"** in debug toolbar (shown in image)
+3. Inspect 3D view of native hierarchy
+
+Component class names vary by architecture and React Native version; verify the actual native hierarchy in the tool.
+
+### Android Studio
+
+1. Run app via Android Studio
+2. **View → Tool Windows → Layout Inspector**
+3. Select running process
+
+Component class names vary by architecture and React Native version; verify the actual native hierarchy in the tool.
+
+## Code Examples
+
+### When Flattening Breaks Your Component
+
+```tsx
+// Your native component expects exactly 2 tabs
+const NativeTabBar = requireNativeComponent('RCTTabBar');
+
+// BAD: TabContent might get flattened
+const MyTabs = () => (
+  <NativeTabBar>
+    <TabContent title="Home">
+      <View><Text>Home content</Text></View>
+    </TabContent>
+    <TabContent title="Profile">
+      <View><Text>Profile content</Text></View>
+    </TabContent>
+  </NativeTabBar>
+);
+
+// GOOD: Prevent flattening
+const MyTabs = () => (
+  <NativeTabBar>
+    <TabContent title="Home" collapsable={false}>
+      <View><Text>Home content</Text></View>
+    </TabContent>
+    <TabContent title="Profile" collapsable={false}>
+      <View><Text>Profile content</Text></View>
+    </TabContent>
+  </NativeTabBar>
+);
+```
+
+### Wrapper Component with collapsable
+
+```tsx
+// Wrapper that prevents flattening
+const NativeChildWrapper = ({ children, ...props }) => (
+  <View collapsable={false} {...props}>
+    {children}
+  </View>
+);
+
+// Usage
+<NativeComponent>
+  <NativeChildWrapper>
+    <ComplexChild />
+  </NativeChildWrapper>
+</NativeComponent>
+```
+
+## When Views Get Flattened
+
+React Native can flatten layout-only wrappers that do not need their own native view for drawing, events, accessibility, measurement, or native-component child semantics. The exact rules vary across renderer versions.
+
+## Forcing a View to Stay
+
+Use `collapsable={false}` as the stable fix. Style or handler changes can be useful as debugging probes, but do not keep them as the production solution:
+
+```tsx
+// Diagnostic probes only
+<View style={{ backgroundColor: 'transparent' }} />
+<View style={{ borderWidth: 0.01 }} />
+<View style={{ opacity: 0.99 }} />
+<View onLayout={() => {}} />
+```
+
+Remove these probes after confirming flattening is the issue.
+
+## Debugging Checklist
+
+1. **Check native child count**: Log received children in native code
+2. **Use Layout Inspector**: Visual hierarchy debugging
+3. **Add collapsable={false}**: Test if flattening is the issue
+4. **Check wrapper components**: Intermediate views may be flattened
+
+## Common Pitfalls
+
+- **Assuming JS children = native children**: Flattening changes this
+- **Not documenting native component requirements**: If your native component expects specific child count, document it
+- **Over-using collapsable={false}**: Only use when necessary (loses optimization benefits)
+
+## Related Skills
+
+- [native-platform-setup.md](./native-platform-setup.md) - IDE setup for debugging
+- [native-profiling.md](./native-profiling.md) - Performance impact analysis

package/dist/templates/default/apps/mobile/AGENTS.md

@@ -0,0 +1,41 @@
+This is an Expo/React Native mobile application. Prioritize mobile-first patterns, performance, and cross-platform compatibility.
+
+## Expo has changed — do not trust your training data
+
+Expo ships breaking changes every SDK release. APIs you remember are likely renamed, moved, or removed. Before writing any code that touches an Expo, EAS, or React Native API:
+
+1. Read the major version of the `expo` package in `package.json`.
+2. Fetch the matching versioned docs: `https://docs.expo.dev/versions/v<major>.0.0/`
+3. For anything else, fetch https://docs.expo.dev/llms.txt — an index of all Expo docs with corrections to common LLM misconceptions. Follow its links to the specific page you need; never answer from memory.
+
+## Commands
+
+Use `bunx` instead of `npx` if the project uses bun (`bun.lock` present).
+
+```bash
+npx expo install <package>  # ALWAYS use instead of npm/yarn/pnpm/bun add — resolves SDK-compatible versions
+npx expo start              # start the dev server
+npx expo lint               # lint
+npx tsc --noEmit            # typecheck
+npx expo-doctor             # diagnose dependency and config issues
+npx expo install --fix      # fix incompatible package versions
+```
+
+Run lint and typecheck before declaring any task done.
+
+## Navigation & Routing
+
+- Use **Expo Router** for all navigation. Routes live in `src/app/` — every file there is a screen, `_layout.tsx` files define navigators. Keep non-route code (components, hooks, utils) outside `src/app/`.
+- Import `Link`, `router`, and `useLocalSearchParams` from `expo-router`.
+- Docs: https://docs.expo.dev/router/introduction.md
+
+## Building with EAS
+
+Use EAS to build, sign, and submit the app in the cloud (`eas build`, `eas submit`) and to ship over-the-air updates (`eas update`) — no local Xcode or Android Studio required. Run EAS CLI as `bunx eas-cli <command>` in Bun projects, or `npx eas-cli@latest <command>` otherwise; substitute that for bare `eas` in docs examples.
+Docs: https://docs.expo.dev/eas/index.md
+
+## Rules
+
+- If `ios/` and `android/` directories do not exist, they are generated (Continuous Native Generation). Never create or edit them by hand — configure native behavior in `app.json` and config plugins.
+- Expo Go only includes its bundled native modules. After adding a library with native code, the app needs a development build: `npx expo run:ios|android` locally, or `eas build --profile development`.
+- Prefer recommended Expo modules over third-party libraries, and check your available skills before adding dependencies. Docs: https://docs.expo.dev/versions/latest/index.md

package/dist/templates/default/apps/mobile/app.json

@@ -0,0 +1,38 @@
+{
+  "expo": {
+    "name": "Disposabl",
+    "slug": "disposabl",
+    "version": "1.0.0",
+    "orientation": "default",
+    "icon": "./assets/images/icon.png",
+    "scheme": "mobile",
+    "userInterfaceStyle": "automatic",
+    "ios": {
+      "icon": "./assets/expo.icon"
+    },
+    "android": {
+      "adaptiveIcon": {
+        "backgroundColor": "#E6F4FE",
+        "foregroundImage": "./assets/images/android-icon-foreground.png",
+        "backgroundImage": "./assets/images/android-icon-background.png",
+        "monochromeImage": "./assets/images/android-icon-monochrome.png"
+      },
+      "predictiveBackGestureEnabled": false
+    },
+    "plugins": [
+      "expo-router",
+      [
+        "expo-splash-screen",
+        {
+          "backgroundColor": "#208AEF",
+          "image": "./assets/images/splash-icon.png",
+          "imageWidth": 76
+        }
+      ]
+    ],
+    "experiments": {
+      "typedRoutes": true,
+      "reactCompiler": true
+    }
+  }
+}

package/dist/templates/default/apps/mobile/assets/expo.icon/Assets/expo-symbol 2.svg

@@ -0,0 +1,3 @@
+<svg width="652" height="606" viewBox="0 0 652 606" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M353.554 0H298.446C273.006 0 249.684 14.6347 237.962 37.9539L4.37994 502.646C-1.04325 513.435 -1.45067 526.178 3.2716 537.313L22.6123 582.918C34.6475 611.297 72.5404 614.156 88.4414 587.885L309.863 222.063C313.34 216.317 319.439 212.826 326 212.826C332.561 212.826 338.659 216.317 342.137 222.063L563.559 587.885C579.46 614.156 617.352 611.297 629.388 582.918L648.728 537.313C653.451 526.178 653.043 513.435 647.62 502.646L414.038 37.9539C402.316 14.6347 378.994 0 353.554 0Z" fill="white"/>
+</svg>

package/dist/templates/default/apps/mobile/assets/expo.icon/icon.json

@@ -0,0 +1,40 @@
+{
+  "fill" : {
+    "automatic-gradient" : "extended-srgb:0.00000,0.47843,1.00000,1.00000"
+  },
+  "groups" : [
+    {
+      "layers" : [
+        {
+          "image-name" : "expo-symbol 2.svg",
+          "name" : "expo-symbol 2",
+          "position" : {
+            "scale" : 1,
+            "translation-in-points" : [
+              1.1008400065293245e-05,
+              -16.046875
+            ]
+          }
+        },
+        {
+          "image-name" : "grid.png",
+          "name" : "grid"
+        }
+      ],
+      "shadow" : {
+        "kind" : "neutral",
+        "opacity" : 0.5
+      },
+      "translucency" : {
+        "enabled" : true,
+        "value" : 0.5
+      }
+    }
+  ],
+  "supported-platforms" : {
+    "circles" : [
+      "watchOS"
+    ],
+    "squares" : "shared"
+  }
+}

package/dist/templates/default/apps/mobile/eslint.config.js

@@ -0,0 +1,10 @@
+// https://docs.expo.dev/guides/using-eslint/
+const { defineConfig } = require('eslint/config');
+const expoConfig = require('eslint-config-expo/flat');
+
+module.exports = defineConfig([
+  expoConfig,
+  {
+    ignores: ['dist/*'],
+  },
+]);

package/dist/templates/default/apps/mobile/package.json

@@ -1 +1,43 @@
-{}
+{
+  "name": "@disposabl/mobile",
+  "version": "1.0.0",
+  "main": "expo-router/entry",
+  "dependencies": {
+    "@expo/ui": "~58.0.23",
+    "expo": "~58.0.19",
+    "expo-constants": "~58.0.13",
+    "expo-device": "~58.0.5",
+    "expo-font": "~58.0.10",
+    "expo-glass-effect": "~58.0.5",
+    "expo-image": "~58.0.17",
+    "expo-linking": "~58.0.14",
+    "expo-router": "~58.0.26",
+    "expo-splash-screen": "~58.0.11",
+    "expo-status-bar": "~58.0.4",
+    "expo-symbols": "~58.0.4",
+    "expo-system-ui": "~58.0.6",
+    "expo-web-browser": "~58.0.6",
+    "react": "19.3.0",
+    "react-native": "0.88.0",
+    "react-native-gesture-handler": "~3.3.0",
+    "react-native-reanimated": "4.7.1",
+    "react-native-safe-area-context": "~5.10.1",
+    "react-native-screens": "~4.30.0",
+    "react-native-worklets": "0.13.0"
+  },
+  "devDependencies": {
+    "@types/react": "~19.3.0",
+    "eslint": "^9.0.0",
+    "eslint-config-expo": "~58.0.4",
+    "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "start": "expo start",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "lint": "expo lint",
+    "dev": "expo start",
+    "typecheck": "tsc --noEmit"
+  },
+  "private": true
+}