@thelacanians/vue-native-cli 0.4.2 → 0.4.4

package/dist/cli.js

@@ -5,9 +5,12 @@ import { program } from "commander";
 
 // src/commands/create.ts
 import { Command } from "commander";
-import { mkdir, writeFile } from "fs/promises";
-import { join } from "path";
+import { cp, mkdir, writeFile } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync } from "fs";
 import pc from "picocolors";
+var VERSION = "0.4.4";
 var createCommand = new Command("create").description("Create a new Vue Native project").argument("<name>", "project name").option("-t, --template <template>", "project template (blank, tabs, drawer)", "blank").action(async (name, options) => {
   const template = options.template;
   if (!["blank", "tabs", "drawer"].includes(template)) {
@@ -60,9 +63,12 @@ export default defineConfig({
         strict: true,
         jsx: "preserve",
         lib: ["ES2020"],
-        types: []
+        types: [],
+        paths: {
+          vue: ["./node_modules/@thelacanians/vue-native-runtime/dist/index.d.ts"]
+        }
       },
-      include: ["app/**/*"]
+      include: ["app/**/*", "env.d.ts"]
     }, null, 2));
     await generateTemplateFiles(dir, name, template);
     const iosDir = join(dir, "ios");
@@ -79,7 +85,8 @@ options:
 
 packages:
   VueNativeCore:
-    path: ../native/ios
+    url: https://github.com/abdul-hamid-achik/vue-native
+    from: "${VERSION}"
 
 targets:
   ${xcodeProjectName}:
@@ -89,6 +96,7 @@ targets:
       - Sources
     dependencies:
       - package: VueNativeCore
+        product: VueNativeCore
     settings:
       base:
         PRODUCT_BUNDLE_IDENTIFIER: ${bundleId}
@@ -239,13 +247,18 @@ dependencyResolutionManagement {
         google()
         mavenCentral()
         maven { url = uri("https://jitpack.io") }
+        maven {
+            url = uri("https://maven.pkg.github.com/abdul-hamid-achik/vue-native")
+            credentials {
+                username = providers.gradleProperty("gpr.user").orNull ?: System.getenv("GITHUB_ACTOR")
+                password = providers.gradleProperty("gpr.key").orNull ?: System.getenv("GITHUB_TOKEN")
+            }
+        }
     }
 }
 
 rootProject.name = "${name}"
 include(":app")
-include(":VueNativeCore")
-project(":VueNativeCore").projectDir = file("../native/android/VueNativeCore")
 `);
     await writeFile(join(androidAppDir, "build.gradle.kts"), `plugins {
     id("com.android.application")
@@ -285,7 +298,7 @@ android {
 }
 
 dependencies {
-    implementation(project(":VueNativeCore"))
+    implementation("com.vuenative:core:${VERSION}")
 }
 `);
     await writeFile(join(androidSrcDir, "AndroidManifest.xml"), `<?xml version="1.0" encoding="utf-8"?>
@@ -357,7 +370,7 @@ export default defineConfig({
 `);
     await writeFile(join(dir, "env.d.ts"), `/// <reference types="vite/client" />
 declare module '*.vue' {
-  import type { DefineComponent } from 'vue'
+  import type { DefineComponent } from '@thelacanians/vue-native-runtime'
   const component: DefineComponent<{}, {}, any>
   export default component
 }
@@ -385,6 +398,13 @@ local.properties
 *.keystore
 *.jks
 `);
+    const cliDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const bundledNative = join(cliDir, "native");
+    if (existsSync(bundledNative)) {
+      const nativeDir = join(dir, "native");
+      await cp(bundledNative, nativeDir, { recursive: true });
+      console.log(pc.dim("  Bundled native/ copied as fallback.\n"));
+    }
     console.log(pc.green("  Project created successfully!\n"));
     console.log(pc.white("  Next steps:\n"));
     console.log(pc.white(`    cd ${name}`));
@@ -410,7 +430,7 @@ async function generateTemplateFiles(dir, name, template) {
   }
 }
 async function generateBlankTemplate(dir, pagesDir) {
-  await writeFile(join(dir, "app", "main.ts"), `import { createApp } from 'vue'
+  await writeFile(join(dir, "app", "main.ts"), `import { createApp } from '@thelacanians/vue-native-runtime'
 import { createRouter } from '@thelacanians/vue-native-navigation'
 import App from './App.vue'
 import Home from './pages/Home.vue'
@@ -485,7 +505,7 @@ const styles = createStyleSheet({
 `);
 }
 async function generateTabsTemplate(dir, pagesDir) {
-  await writeFile(join(dir, "app", "main.ts"), `import { createApp } from 'vue'
+  await writeFile(join(dir, "app", "main.ts"), `import { createApp } from '@thelacanians/vue-native-runtime'
 import App from './App.vue'
 
 const app = createApp(App)
@@ -598,7 +618,7 @@ const styles = createStyleSheet({
 `);
 }
 async function generateDrawerTemplate(dir, pagesDir) {
-  await writeFile(join(dir, "app", "main.ts"), `import { createApp } from 'vue'
+  await writeFile(join(dir, "app", "main.ts"), `import { createApp } from '@thelacanians/vue-native-runtime'
 import App from './App.vue'
 
 const app = createApp(App)
@@ -735,7 +755,7 @@ const styles = createStyleSheet({
 import { Command as Command2 } from "commander";
 import { spawn, execSync } from "child_process";
 import { readFile } from "fs/promises";
-import { existsSync } from "fs";
+import { existsSync as existsSync2 } from "fs";
 import { join as join2 } from "path";
 import { watch } from "chokidar";
 import { WebSocketServer, WebSocket } from "ws";
@@ -861,10 +881,10 @@ var devCommand = new Command2("dev").description("Start the Vue Native dev serve
   console.log(pc2.white(`  Hot reload server: ${pc2.bold(`ws://localhost:${port}`)}`));
   const iosDir = join2(cwd, "ios");
   const androidDir = join2(cwd, "android");
-  if (existsSync(iosDir)) {
+  if (existsSync2(iosDir)) {
     console.log(pc2.dim(`  iOS app should connect to ws://localhost:${port}`));
   }
-  if (existsSync(androidDir)) {
+  if (existsSync2(androidDir)) {
     console.log(pc2.dim(`  Android emulator should connect to ws://10.0.2.2:${port}`));
   }
   console.log(pc2.dim("  Waiting for app to connect...\n"));
@@ -925,7 +945,7 @@ var devCommand = new Command2("dev").description("Start the Vue Native dev serve
 // src/commands/run.ts
 import { Command as Command3 } from "commander";
 import { spawn as spawn2, execSync as execSync2 } from "child_process";
-import { existsSync as existsSync2, readdirSync, readFileSync } from "fs";
+import { existsSync as existsSync3, readdirSync, readFileSync } from "fs";
 import { join as join3 } from "path";
 import pc3 from "picocolors";
 function findAppPath(_buildDir) {
@@ -933,7 +953,7 @@ function findAppPath(_buildDir) {
     process.env.HOME || "~",
     "Library/Developer/Xcode/DerivedData"
   );
-  if (existsSync2(derivedDataBase)) {
+  if (existsSync3(derivedDataBase)) {
     try {
       const projects = readdirSync(derivedDataBase);
       for (const project of projects.reverse()) {
@@ -942,7 +962,7 @@ function findAppPath(_buildDir) {
           project,
           "Build/Products/Debug-iphonesimulator"
         );
-        if (existsSync2(productsDir)) {
+        if (existsSync3(productsDir)) {
           const entries = readdirSync(productsDir);
           const app = entries.find((e) => e.endsWith(".app"));
           if (app) {
@@ -957,7 +977,7 @@ function findAppPath(_buildDir) {
 }
 function readBundleId(iosDir) {
   const plistPath = join3(iosDir, "Sources", "Info.plist");
-  if (existsSync2(plistPath)) {
+  if (existsSync3(plistPath)) {
     try {
       const content = readFileSync(plistPath, "utf8");
       const match = content.match(
@@ -973,7 +993,7 @@ function readBundleId(iosDir) {
 }
 function findApkPath(androidDir) {
   const apkDir = join3(androidDir, "app", "build", "outputs", "apk", "debug");
-  if (existsSync2(apkDir)) {
+  if (existsSync3(apkDir)) {
     try {
       const entries = readdirSync(apkDir);
       const apk = entries.find((e) => e.endsWith(".apk") && !e.includes("androidTest"));
@@ -1011,7 +1031,7 @@ var runCommand = new Command3("run").description("Build and run the app").argume
 function runIOS(cwd, options) {
   let xcodeProject = null;
   const iosDir = join3(cwd, "ios");
-  if (existsSync2(iosDir)) {
+  if (existsSync3(iosDir)) {
     for (const ext of [".xcworkspace", ".xcodeproj"]) {
       try {
         const entries = readdirSync(iosDir);
@@ -1098,14 +1118,14 @@ function runIOS(cwd, options) {
 }
 function runAndroid(cwd, options) {
   const androidDir = join3(cwd, "android");
-  if (!existsSync2(androidDir)) {
+  if (!existsSync3(androidDir)) {
     console.log(pc3.yellow("  No android/ directory found."));
     console.log(pc3.dim("  To add Android support, create an Android project in the android/ directory."));
     console.log(pc3.dim("  Bundle has been built to dist/vue-native-bundle.js\n"));
     return;
   }
   const gradlew = join3(androidDir, "gradlew");
-  if (!existsSync2(gradlew)) {
+  if (!existsSync3(gradlew)) {
     console.error(pc3.red("  \u2717 gradlew not found in android/ directory"));
     console.log(pc3.dim("  Make sure your Android project has the Gradle wrapper.\n"));
     process.exit(1);

package/native/android/README.md

@@ -0,0 +1,205 @@
+# Vue Native — Android
+
+Android implementation of the Vue Native framework. Runs Vue 3 apps on Android using V8 (J2V8) as the JavaScript engine and Android Views with FlexboxLayout for the UI layer.
+
+## Architecture
+
+```
+Vue Bundle (IIFE)
+     ↓ loaded by JSRuntime (J2V8 / HandlerThread)
+ __VN_flushOperations(json)  ← batched operations
+     ↓ NativeBridge.processOperations() [main thread]
+ ComponentRegistry → NativeComponentFactory
+     ↓ createView / updateProp / insertChild
+ Android Views (FlexboxLayout, TextView, EditText, RecyclerView…)
+     ↓
+ Android screen
+```
+
+## Module Structure
+
+```
+VueNativeCore/
+├── Bridge/
+│   ├── JSRuntime.kt          — V8 engine on a dedicated HandlerThread
+│   ├── NativeBridge.kt       — Processes batched operations on main thread
+│   ├── JSPolyfills.kt        — console, setTimeout, fetch, RAF, performance.now
+│   ├── HotReloadManager.kt   — WebSocket connection to Vite dev server
+│   └── ErrorOverlayView.kt   — Debug error overlay
+├── Components/
+│   ├── NativeComponentFactory.kt  — Factory interface
+│   ├── ComponentRegistry.kt       — Singleton factory registry
+│   ├── VTextNodeView.kt           — Text node view for VText children
+│   └── Factories/
+│       ├── VViewFactory.kt         — FlexboxLayout
+│       ├── VTextFactory.kt         — TextView
+│       ├── VButtonFactory.kt       — Pressable FlexboxLayout
+│       ├── VInputFactory.kt        — EditText with v-model
+│       ├── VScrollViewFactory.kt   — ScrollView + FlexboxLayout content
+│       ├── VListFactory.kt         — RecyclerView with bridge-managed items
+│       ├── VImageFactory.kt        — Coil-based async image loading
+│       ├── VSwitchFactory.kt       — SwitchCompat
+│       ├── VSliderFactory.kt       — SeekBar
+│       ├── VModalFactory.kt        — Dialog overlay
+│       ├── VAlertDialogFactory.kt  — AlertDialog.Builder
+│       ├── VProgressBarFactory.kt  — Horizontal ProgressBar
+│       ├── VSegmentedControlFactory.kt — RadioGroup
+│       ├── VPickerFactory.kt       — DatePicker
+│       ├── VActionSheetFactory.kt  — AlertDialog with item list
+│       ├── VStatusBarFactory.kt    — WindowInsetsController
+│       ├── VWebViewFactory.kt      — WebView
+│       ├── VActivityIndicatorFactory.kt — ProgressBar (circular)
+│       ├── VSafeAreaFactory.kt     — WindowInsets-aware container
+│       └── VKeyboardAvoidingFactory.kt  — Keyboard-aware container
+├── Styling/
+│   └── StyleEngine.kt        — JS style props → Android View properties
+├── Modules/
+│   ├── NativeModule.kt       — Interface for all native modules
+│   ├── NativeModuleRegistry.kt
+│   ├── HapticsModule.kt      — VibrationEffect
+│   ├── AsyncStorageModule.kt — SharedPreferences KV store
+│   ├── ClipboardModule.kt    — ClipboardManager
+│   ├── DeviceInfoModule.kt   — Build info + DisplayMetrics
+│   ├── NetworkModule.kt      — ConnectivityManager.NetworkCallback
+│   ├── AppStateModule.kt     — ProcessLifecycleOwner
+│   ├── LinkingModule.kt      — Intent ACTION_VIEW
+│   ├── ShareModule.kt        — Intent ACTION_SEND
+│   ├── AnimationModule.kt    — ObjectAnimator
+│   ├── KeyboardModule.kt     — InputMethodManager
+│   ├── PermissionsModule.kt  — ContextCompat.checkSelfPermission
+│   ├── GeolocationModule.kt  — FusedLocationProviderClient
+│   ├── NotificationsModule.kt — NotificationCompat + scheduled delivery
+│   ├── HttpModule.kt         — OkHttp wrapper for useHttp() composable
+│   ├── BiometryModule.kt     — BiometricManager capability check
+│   └── CameraModule.kt       — Stub (requires Activity integration)
+├── Helpers/
+│   └── GestureHelper.kt      — Touch event helpers
+├── Tags.kt                   — View tag ID constants
+└── VueNativeActivity.kt      — Base Activity for all Vue Native apps
+```
+
+## Quick Start
+
+### 1. Add VueNativeCore to your project
+
+In your app's `settings.gradle.kts`:
+```kotlin
+include(":VueNativeCore")
+project(":VueNativeCore").projectDir = File("path/to/VueNativeCore")
+```
+
+In your app's `build.gradle.kts`:
+```kotlin
+dependencies {
+    implementation(project(":VueNativeCore"))
+}
+```
+
+### 2. Create your Activity
+
+```kotlin
+class MainActivity : VueNativeActivity() {
+    // Path to your compiled Vue bundle in src/main/assets/
+    override fun getBundleAssetPath(): String = "vue-native-bundle.js"
+
+    // For hot reload during development (optional)
+    // ws://10.0.2.2:5173 connects from emulator to host machine
+    override fun getDevServerUrl(): String? = if (BuildConfig.DEBUG) "ws://10.0.2.2:5173" else null
+}
+```
+
+### 3. Build the Vue bundle
+
+```bash
+cd your-vue-native-app
+bun run build   # or: npx vite build
+```
+
+Copy the output file to `app/src/main/assets/vue-native-bundle.js`.
+
+### 4. Run
+
+Open the Android project in Android Studio and run on an emulator or device.
+
+## Development with Hot Reload
+
+1. Start the Vite dev server:
+   ```bash
+   bun run dev
+   ```
+
+2. Set `getDevServerUrl()` to `"ws://10.0.2.2:5173"` (emulator) or your machine's IP for a real device.
+
+3. The app connects on start and automatically reloads when you save Vue files.
+
+## Thread Model
+
+| Thread | Purpose |
+|--------|---------|
+| `VueNative-JS` (HandlerThread) | All V8 operations — **never access V8 from other threads** |
+| Main Thread | All Android View operations, bridge operation dispatch |
+| IO Thread (Coroutines) | HTTP requests, WebSocket, image loading |
+
+## Adding Custom Native Modules
+
+Implement `NativeModule` and register in your subclass of `VueNativeActivity`:
+
+```kotlin
+class MyModule : NativeModule {
+    override val moduleName = "MyModule"
+
+    override fun invoke(
+        method: String,
+        args: List<Any?>,
+        bridge: NativeBridge,
+        callback: (Any?, String?) -> Unit
+    ) {
+        when (method) {
+            "doSomething" -> {
+                // ... do work ...
+                callback(mapOf("result" to "done"), null)
+            }
+            else -> callback(null, "Unknown method: $method")
+        }
+    }
+}
+```
+
+```kotlin
+class MainActivity : VueNativeActivity() {
+    override fun getBundleAssetPath() = "bundle.js"
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        NativeModuleRegistry.getInstance(this).register(MyModule())
+    }
+}
+```
+
+From Vue/TypeScript:
+```typescript
+import { NativeBridge } from '@thelacanians/vue-native-runtime'
+
+const result = await NativeBridge.invokeNativeModule('MyModule', 'doSomething', [])
+```
+
+## Dependencies
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| `com.eclipsesource.j2v8:j2v8` | 6.2.1 | V8 JavaScript engine |
+| `com.google.android.flexbox:flexbox` | 3.0.0 | CSS Flexbox layout |
+| `io.coil-kt:coil` | 2.7.0 | Async image loading |
+| `com.squareup.okhttp3:okhttp` | 4.12.0 | HTTP (fetch polyfill, hot reload) |
+| `androidx.recyclerview:recyclerview` | 1.3.2 | VList virtualization |
+| `androidx.webkit:webkit` | 1.10.0 | VWebView |
+| `androidx.swiperefreshlayout:swiperefreshlayout` | 1.1.0 | VScrollView pull-to-refresh |
+| `androidx.biometric:biometric` | 1.1.0 | BiometryModule |
+| `com.google.android.gms:play-services-location` | 21.1.0 | GeolocationModule |
+
+## Minimum Requirements
+
+- Android API 21 (Android 5.0 Lollipop)
+- Kotlin 1.9+
+- Gradle 8.6
+- AGP 8.2.2

package/native/android/VueNativeCore/build.gradle.kts

@@ -0,0 +1,100 @@
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+    id("maven-publish")
+}
+
+android {
+    namespace = "com.vuenative.core"
+    compileSdk = 34
+
+    defaultConfig {
+        minSdk = 21
+        targetSdk = 34
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+        consumerProguardFiles("consumer-rules.pro")
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+
+    // Allow lint checks to pass without strict enforcement during development
+    lint {
+        abortOnError = false
+    }
+}
+
+dependencies {
+    // AndroidX Core
+    implementation("androidx.core:core-ktx:1.12.0")
+    implementation("androidx.appcompat:appcompat:1.6.1")
+    implementation("com.google.android.material:material:1.11.0")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
+    implementation("androidx.recyclerview:recyclerview:1.3.2")
+    implementation("androidx.webkit:webkit:1.10.0")
+    implementation("androidx.swiperefreshlayout:swiperefreshlayout:1.1.0")
+
+    // J2V8 — JavaScript engine (V8 for Android)
+    implementation("com.eclipsesource.j2v8:j2v8:6.2.1@aar")
+
+    // FlexboxLayout — CSS Flexbox for Android views
+    implementation("com.google.android.flexbox:flexbox:3.0.0")
+
+    // Coil — Image loading
+    implementation("io.coil-kt:coil:2.7.0")
+
+    // OkHttp — HTTP for fetch polyfill
+    implementation("com.squareup.okhttp3:okhttp:4.12.0")
+
+    // Kotlin Coroutines
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
+
+    // Location (for GeolocationModule)
+    implementation("com.google.android.gms:play-services-location:21.1.0")
+
+    // Biometry (for BiometryModule)
+    implementation("androidx.biometric:biometric:1.1.0")
+
+    // Secure Storage (for SecureStorageModule)
+    implementation("androidx.security:security-crypto:1.1.0-alpha06")
+}
+
+afterEvaluate {
+    publishing {
+        publications {
+            create<MavenPublication>("release") {
+                groupId = "com.vuenative"
+                artifactId = "core"
+                version = "0.4.4"
+                from(components["release"])
+            }
+        }
+        repositories {
+            maven {
+                name = "GitHubPackages"
+                url = uri("https://maven.pkg.github.com/abdul-hamid-achik/vue-native")
+                credentials {
+                    username = System.getenv("GITHUB_ACTOR")
+                    password = System.getenv("GITHUB_TOKEN")
+                }
+            }
+        }
+    }
+}

package/native/android/VueNativeCore/consumer-rules.pro

@@ -0,0 +1,12 @@
+# Consumer ProGuard rules for VueNativeCore library.
+# These rules are applied to apps that depend on VueNativeCore.
+
+# J2V8 — V8 engine JNI bindings must not be stripped
+-keep class com.eclipsesource.v8.** { *; }
+-keepclasseswithmembers class com.eclipsesource.v8.** {
+    native <methods>;
+}
+
+# Keep Vue Native public API
+-keep public class com.vuenative.core.VueNativeActivity { *; }
+-keep public class com.vuenative.core.NativeModule { *; }

package/native/android/VueNativeCore/proguard-rules.pro

@@ -0,0 +1,33 @@
+# J2V8 — keep all V8 classes and JNI methods
+-keep class com.eclipsesource.v8.** { *; }
+-keepclasseswithmembers class com.eclipsesource.v8.** {
+    native <methods>;
+}
+
+# FlexboxLayout
+-keep class com.google.android.flexbox.** { *; }
+
+# Coil image loading
+-dontwarn coil.**
+
+# OkHttp
+-dontwarn okhttp3.**
+-dontwarn okio.**
+-keepnames class okhttp3.internal.publicsuffix.PublicSuffixDatabase
+
+# Kotlin serialization
+-keepattributes *Annotation*, InnerClasses
+-dontnote kotlinx.serialization.AnnotationsKt
+
+# Vue Native Core — keep all public API
+-keep public class com.vuenative.core.VueNativeActivity { *; }
+-keep public class com.vuenative.core.JSRuntime { *; }
+-keep public class com.vuenative.core.NativeBridge { *; }
+-keep public class com.vuenative.core.NativeModule { *; }
+-keep public class com.vuenative.core.NativeModuleRegistry { *; }
+
+# Biometric
+-keep class androidx.biometric.** { *; }
+
+# SwipeRefreshLayout
+-keep class androidx.swiperefreshlayout.** { *; }

package/native/android/VueNativeCore/src/main/AndroidManifest.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- Permissions used by native modules -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.VIBRATE" />
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
+    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.USE_BIOMETRIC" />
+    <uses-permission android:name="android.permission.USE_FINGERPRINT" />
+
+</manifest>

package/native/android/VueNativeCore/src/main/kotlin/com/vuenative/core/Bridge/ErrorOverlayView.kt

@@ -0,0 +1,94 @@
+package com.vuenative.core
+
+import android.content.Context
+import android.graphics.Color
+import android.graphics.Typeface
+import android.util.TypedValue
+import android.view.Gravity
+import android.view.ViewGroup
+import android.widget.Button
+import android.widget.FrameLayout
+import android.widget.LinearLayout
+import android.widget.ScrollView
+import android.widget.TextView
+import androidx.appcompat.app.AppCompatActivity
+
+/**
+ * Full-screen debug error overlay shown in DEBUG builds when a JS error occurs.
+ */
+object ErrorOverlayView {
+
+    fun show(context: Context, error: String) {
+        val activity = context as? AppCompatActivity ?: return
+        activity.runOnUiThread {
+            val decorView = activity.window.decorView as? ViewGroup ?: return@runOnUiThread
+
+            // Remove existing overlay
+            decorView.findViewWithTag<FrameLayout>("vue_native_error_overlay")?.let {
+                decorView.removeView(it)
+            }
+
+            val dp = context.resources.displayMetrics.density
+
+            val overlay = FrameLayout(context).apply {
+                tag = "vue_native_error_overlay"
+                setBackgroundColor(Color.parseColor("#CC1A1A1A"))
+                layoutParams = FrameLayout.LayoutParams(
+                    ViewGroup.LayoutParams.MATCH_PARENT,
+                    ViewGroup.LayoutParams.MATCH_PARENT
+                )
+            }
+
+            val card = LinearLayout(context).apply {
+                orientation = LinearLayout.VERTICAL
+                setBackgroundColor(Color.parseColor("#FF1A1A1A"))
+                setPadding(
+                    (16 * dp).toInt(), (16 * dp).toInt(),
+                    (16 * dp).toInt(), (16 * dp).toInt()
+                )
+            }
+
+            val title = TextView(context).apply {
+                text = "Vue Native JS Error"
+                setTextColor(Color.RED)
+                setTextSize(TypedValue.COMPLEX_UNIT_SP, 16f)
+                setTypeface(null, Typeface.BOLD)
+                setPadding(0, 0, 0, (12 * dp).toInt())
+            }
+
+            val scroll = ScrollView(context).apply {
+                layoutParams = LinearLayout.LayoutParams(
+                    ViewGroup.LayoutParams.MATCH_PARENT, 0, 1f
+                )
+            }
+
+            val errorText = TextView(context).apply {
+                text = error
+                setTextColor(Color.parseColor("#FFCC00"))
+                setTextSize(TypedValue.COMPLEX_UNIT_SP, 12f)
+                setTypeface(Typeface.MONOSPACE)
+                setPadding((8 * dp).toInt(), (8 * dp).toInt(), (8 * dp).toInt(), (8 * dp).toInt())
+            }
+
+            val dismiss = Button(context).apply {
+                text = "Dismiss"
+                setOnClickListener { decorView.removeView(overlay) }
+            }
+
+            scroll.addView(errorText)
+            card.addView(title)
+            card.addView(scroll)
+            card.addView(dismiss)
+
+            val lp = FrameLayout.LayoutParams(
+                FrameLayout.LayoutParams.MATCH_PARENT,
+                (400 * dp).toInt(),
+                Gravity.CENTER
+            ).apply {
+                setMargins((16 * dp).toInt(), 0, (16 * dp).toInt(), 0)
+            }
+            overlay.addView(card, lp)
+            decorView.addView(overlay)
+        }
+    }
+}