catalyst-core 0.3.0-beta.1 → 0.3.0-beta.3

package/dist/globals.d.ts

@@ -0,0 +1,7 @@
+// Injected by webpack DefinePlugin in base.babel.js at build time.
+// Reflects which @catalyst/* packages are present in the app's node_modules.
+declare const __CATALYST_PACKAGES__: {
+    readonly ai: boolean
+    readonly webAILocal: boolean
+    readonly nativeAILocal: boolean
+}

package/dist/native/androidProject/app/build.gradle.kts

@@ -60,6 +60,22 @@ fun isNotificationsEnabled(): Boolean {
     }
 }
 
+fun isAIEnabled(): Boolean {
+    return try {
+        if (configPath == null) return false
+        val configFile = File(configPath!!)
+        if (!configFile.exists()) return false
+
+        val json = JSONObject(configFile.readText())
+        if (!json.has("WEBVIEW_CONFIG")) return false
+
+        val webviewConfig = json.getJSONObject("WEBVIEW_CONFIG")
+        webviewConfig.optJSONObject("ai")?.optBoolean("enabled", false) ?: false
+    } catch (e: Exception) {
+        false
+    }
+}
+
 fun getLocalIpAddress(): String {
     return NetworkInterface.getNetworkInterfaces().toList()
         .flatMap { it.inetAddresses.toList() }
@@ -151,6 +167,7 @@ android {
 
     kotlinOptions {
         jvmTarget = "11"
+        freeCompilerArgs += "-Xskip-metadata-version-check"
     }
 
     buildFeatures {
@@ -168,8 +185,9 @@ android {
             excludes.add("META-INF/io.netty.versions.properties")
         }
         jniLibs {
-            // Enable 16KB page size alignment for all native libraries
-            useLegacyPackaging = false
+            // libLiteRtClGlAccelerator.so must be extracted to disk for GPU dlopen().
+            // This must live in the app module — AGP ignores useLegacyPackaging in library modules.
+            useLegacyPackaging = isAIEnabled()
         }
     }
 
@@ -186,7 +204,7 @@ android {
         }
     }
 
-    // Conditional source sets based on notifications config
+    // Conditional source sets based on feature config
     sourceSets {
         getByName("main") {
             if (isNotificationsEnabled()) {
@@ -196,6 +214,20 @@ android {
                 logger.info("SourceSet selected: noFcm (notifications disabled)")
                 java.srcDirs("src/noFcm/java")
             }
+            // AI has no source-set swap — CatalystAIBridge self-registers via ServiceLoader
+            // when @catalyst/cloud-ai is on the classpath.
+        }
+    }
+}
+
+configurations.all {
+    resolutionStrategy.eachDependency {
+        if (requested.group == "org.jetbrains.kotlin" &&
+            (requested.name == "kotlin-stdlib" ||
+             requested.name == "kotlin-stdlib-jdk7" ||
+             requested.name == "kotlin-stdlib-jdk8" ||
+             requested.name == "kotlin-reflect")) {
+            useVersion("2.0.21")
         }
     }
 }
@@ -217,7 +249,16 @@ dependencies {
     implementation("io.ktor:ktor-server-core:3.0.3")
     implementation("io.ktor:ktor-server-netty:3.0.3")
     implementation("io.ktor:ktor-server-content-negotiation:3.0.3")
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
+    implementation("io.ktor:ktor-server-sse:3.0.3")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
+
+    // Native AI — compileOnly always (for types), implementation only when ai.enabled=true (for runtime bundling)
+    if (project.findProject(":catalyst-cloud-ai") != null) {
+        compileOnly(project(":catalyst-cloud-ai"))
+        if (isAIEnabled()) {
+            implementation(project(":catalyst-cloud-ai"))
+        }
+    }
 
     // Security detection dependencies
     implementation("com.scottyab:rootbeer-lib:0.1.1")  // Root detection

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/NativeBridge.kt

@@ -16,12 +16,15 @@ import androidx.credentials.exceptions.GetCredentialCancellationException
 import androidx.credentials.exceptions.GetCredentialException
 import com.google.android.libraries.identity.googleid.GetSignInWithGoogleOption
 import com.google.android.libraries.identity.googleid.GoogleIdTokenCredential
+// LiteRT imports removed — AI logic lives in catalyst-ai (CatalystAIBridge plugin)
 import io.yourname.androidproject.MainActivity
 import io.yourname.androidproject.utils.*
 import kotlinx.coroutines.*
 import org.json.JSONArray
 import org.json.JSONObject
+import java.io.File
 import java.util.Properties
+import java.util.ServiceLoader
 import java.util.concurrent.atomic.AtomicBoolean
 
 private data class FilePickerOptions(
@@ -151,6 +154,61 @@ class NativeBridge(
     
     private var networkMonitor: NetworkMonitor? = null
 
+    // AI plugin — loaded via reflection so NativeBridge.kt compiles with no compile-time dep on
+    // :catalyst-ai. When the module is absent the try block returns null gracefully.
+    private val aiBridge: Any? = try {
+        @Suppress("UNCHECKED_CAST")
+        run {
+            val bridgeClass = Class.forName("io.catalyst.nativeai.AIBridge")
+            val callbacksClass = Class.forName("io.catalyst.nativeai.AIBridgeCallbacks")
+            @Suppress("UNCHECKED_CAST")
+            val loader = ServiceLoader.load(bridgeClass as Class<Any>)
+            val bridge = loader.iterator().takeIf { it.hasNext() }?.next() ?: return@run null
+
+            val callbacksProxy = java.lang.reflect.Proxy.newProxyInstance(
+                bridgeClass.classLoader,
+                arrayOf(callbacksClass)
+            ) { _, method, args ->
+                val a = args ?: emptyArray()
+                when (method.name) {
+                    "onReady" -> {
+                        val payload = org.json.JSONObject().apply {
+                            put("url", a[0]); put("port", a[1]); put("sessionId", a[2])
+                        }
+                        BridgeUtils.notifyWebJson(webView, BridgeUtils.WebEvents.ON_AI_READY, payload)
+                    }
+                    "onProgress" -> {
+                        val payload = org.json.JSONObject().apply {
+                            put("phase", a[0]); put("percent", a[1])
+                            put("bytesLoaded", a[2]); put("bytesTotal", a[3]); put("detail", a[4])
+                        }
+                        BridgeUtils.notifyWebJson(webView, BridgeUtils.WebEvents.ON_AI_PROGRESS, payload)
+                    }
+                    "onLog" -> {
+                        val payload = org.json.JSONObject().apply { put("message", a[0]) }
+                        BridgeUtils.notifyWebJson(webView, BridgeUtils.WebEvents.ON_AI_LOG, payload)
+                    }
+                    "onError" -> BridgeUtils.notifyWebError(webView, BridgeUtils.WebEvents.ON_AI_ERROR, a[0] as String)
+                    "isFrameworkServerRunning" -> FrameworkServerUtils.isRunning()
+                    "getFrameworkServerPort" -> FrameworkServerUtils.getServerPort()
+                    "getFrameworkServerSessionId" -> FrameworkServerUtils.getSessionId()
+                    "setNativeAiSupplier" -> {
+                        @Suppress("UNCHECKED_CAST")
+                        FrameworkServerUtils.setNativeAiSupplier(
+                            a[0] as suspend (String, org.json.JSONObject, String?) -> Pair<String, kotlinx.coroutines.flow.Flow<String>>
+                        )
+                    }
+                    "setNativeSystemPrompt" -> FrameworkServerUtils.setNativeSystemPrompt(a[0] as String)
+                    else -> null
+                }
+            }
+
+            bridge.javaClass.getMethod("attach", android.app.Activity::class.java, android.webkit.WebView::class.java, callbacksClass)
+                .invoke(bridge, mainActivity, webView, callbacksProxy)
+            bridge
+        }
+    } catch (_: Throwable) { null }
+
     // Video stream manager
     private var nativeCameraManager: NativeCameraManager? = null
     private var webViewOriginalBackground: Int = android.graphics.Color.WHITE
@@ -1301,6 +1359,34 @@ class NativeBridge(
         }
     }
 
+    // -------------------------------------------------------------------------
+    // Native AI bridge methods — delegated to AIBridge plugin (ServiceLoader)
+    // -------------------------------------------------------------------------
+
+    @JavascriptInterface
+    fun isAIAvailable(): Boolean = aiBridge != null
+
+    @JavascriptInterface
+    fun initAI(optionsRaw: String?) {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_AI_ERROR, "initialize AI") {
+            aiBridge?.javaClass?.getMethod("initAI", String::class.java)?.invoke(aiBridge, optionsRaw)
+        }
+    }
+
+    @JavascriptInterface
+    fun generateNative(optionsRaw: String?) {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_AI_ERROR, "generate with native AI") {
+            aiBridge?.javaClass?.getMethod("generateNative", String::class.java)?.invoke(aiBridge, optionsRaw)
+        }
+    }
+
+    @JavascriptInterface
+    fun clearNativeConversation() {
+        BridgeUtils.safeExecute(webView, BridgeUtils.WebEvents.ON_AI_ERROR, "clear native conversation") {
+            aiBridge?.javaClass?.getMethod("clearConversation")?.invoke(aiBridge)
+        }
+    }
+
     /**
      * Cleanup method to be called when the bridge is being destroyed
      */

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/utils/BridgeUtils.kt

@@ -97,6 +97,14 @@ object BridgeUtils {
         ON_TRANSITION_CANCELLED("ON_TRANSITION_CANCELLED"),
         ON_TRANSITION_TIMEOUT("ON_TRANSITION_TIMEOUT"),
 
+        // Native AI events
+        ON_AI_READY("ON_AI_READY"),
+        ON_AI_ERROR("ON_AI_ERROR"),
+        ON_AI_TOKEN("ON_AI_TOKEN"),
+        ON_AI_DONE("ON_AI_DONE"),
+        ON_AI_PROGRESS("ON_AI_PROGRESS"),
+        ON_AI_LOG("ON_AI_LOG"),
+
         // Perf telemetry
         CATALYST_PERF_EVENT("CATALYST_PERF_EVENT"),
     }

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/utils/FrameworkServerUtils.kt

@@ -7,15 +7,21 @@ import io.ktor.http.*
 import io.ktor.server.application.*
 import io.ktor.server.engine.*
 import io.ktor.server.netty.*
+import io.ktor.server.request.*
 import io.ktor.server.response.*
 import io.ktor.server.routing.*
+import io.ktor.http.ContentType
+import io.ktor.server.response.respondTextWriter
+import io.ktor.server.sse.*
 import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.Flow
+import org.json.JSONObject
 import java.io.File
 import java.io.IOException
 import java.net.InetSocketAddress
 import java.nio.channels.ServerSocketChannel
 import java.security.SecureRandom
-import java.util.*
+import java.util.UUID
 import java.util.concurrent.ConcurrentHashMap
 
 /**
@@ -36,6 +42,7 @@ object FrameworkServerUtils {
     private const val FRAMEWORK_PORT_RANGE_START = 3000
     private const val FRAMEWORK_PORT_RANGE_END = 3099
     private const val SESSION_TIMEOUT_MS = 30 * 60 * 1000L // 30 minutes
+    private const val AI_GENERATE_TIMEOUT_MS = 120 * 1000L // 2 minutes
     
     // Server state
     private var server: EmbeddedServer<NettyApplicationEngine, NettyApplicationEngine.Configuration>? = null
@@ -49,7 +56,14 @@ object FrameworkServerUtils {
     // File management
     private val servedFiles = ConcurrentHashMap<String, ServedFile>()
     private var cacheDirectory: File? = null
-    
+
+    // Native AI — supplier set by NativeBridge before POST /ai/stream is called
+    // Returns (conversationId, tokenFlow) so the route can emit conversationId as an SSE event
+    private var nativeAiSupplier: (suspend (prompt: String, genConfig: JSONObject, conversationId: String?) -> Pair<String, Flow<String>>)? = null
+
+    // System prompt injected into every native AI request (built from attachmentComponents at initAI time)
+    private var nativeSystemPrompt: String = ""
+
     // Coroutine scope for server operations
     private val serverScope = CoroutineScope(Dispatchers.IO + SupervisorJob())
     
@@ -60,7 +74,7 @@ object FrameworkServerUtils {
         val fileId: String,
         val createdAt: Long = System.currentTimeMillis()
     )
-    
+
     /**
      * Initialize and start the framework server
      * @param context Android context for file operations
@@ -223,7 +237,21 @@ object FrameworkServerUtils {
      * Get current session ID
      */
     fun getSessionId(): String = sessionId
-    
+
+    /**
+     * Register the native AI supplier. Called by NativeBridge once LiteRT-LM is ready.
+     * The supplier receives the prompt, gen-config, and optional incomingConversationId,
+     * and returns (activeConversationId, tokenFlow) so stateful sessions can be chained.
+     */
+    fun setNativeAiSupplier(supplier: suspend (prompt: String, genConfig: JSONObject, conversationId: String?) -> Pair<String, Flow<String>>) {
+        nativeAiSupplier = supplier
+    }
+
+    fun setNativeSystemPrompt(systemPrompt: String) {
+        nativeSystemPrompt = systemPrompt
+        Log.d(TAG, "System prompt set (${systemPrompt.length} chars)")
+    }
+
     // Private implementation methods
     
     private fun initializeCacheDirectory(context: Context) {
@@ -291,7 +319,145 @@ object FrameworkServerUtils {
     
     private fun startKtorServer() {
         server = embeddedServer(Netty, port = serverPort) {
+            install(SSE)
             routing {
+                // Native AI streaming endpoint — POST body: { "prompt": "...", "genConfig": {...} }
+                // Writes SSE manually over chunked response (Ktor SSE plugin only supports GET).
+                post("/framework-$sessionId/ai/stream") {
+                    call.response.header(HttpHeaders.AccessControlAllowOrigin, allowedOrigin)
+                    call.response.header(HttpHeaders.AccessControlAllowHeaders, "*")
+                    call.response.header(HttpHeaders.ContentType, "text/event-stream")
+                    call.response.header(HttpHeaders.CacheControl, "no-cache")
+                    call.response.header("X-Accel-Buffering", "no")
+
+                    val body = try {
+                        JSONObject(call.receiveText())
+                    } catch (e: Exception) {
+                        JSONObject()
+                    }
+                    val userPrompt = body.optString("prompt", "")
+                    val genConfig = body.optJSONObject("genConfig") ?: JSONObject()
+                    val incomingConvId = body.optString("conversationId", "").takeIf { it.isNotBlank() }
+                    if (nativeSystemPrompt.isNotBlank()) Log.d(TAG, "Injecting system prompt (${nativeSystemPrompt.length} chars)")
+                    val prompt = if (nativeSystemPrompt.isNotBlank()) "$nativeSystemPrompt\n\n$userPrompt" else userPrompt
+
+                    call.respondTextWriter(contentType = ContentType.Text.EventStream) {
+                        val supplier = nativeAiSupplier
+                        if (supplier == null) {
+                            write("data: {\"error\":\"Native AI not initialised — call initAI() first\"}\n\n")
+                            flush()
+                        } else if (prompt.isBlank()) {
+                            write("data: {\"error\":\"prompt is empty\"}\n\n")
+                            flush()
+                        } else {
+                            try {
+                                val (activeConvId, tokenFlow) = supplier(prompt, genConfig, incomingConvId)
+                                write("data: {\"conversationId\":${JSONObject.quote(activeConvId)}}\n\n")
+                                flush()
+                                tokenFlow.collect { token ->
+                                    write("data: {\"token\":${JSONObject.quote(token)}}\n\n")
+                                    flush()
+                                }
+                                write("data: {\"done\":true}\n\n")
+                                flush()
+                            } catch (e: java.io.IOException) {
+                                // Client disconnected — channel closed, nothing to write
+                                Log.d(TAG, "Native AI stream: client disconnected (${e.message})")
+                            } catch (e: Exception) {
+                                Log.e(TAG, "Native AI stream error", e)
+                                try {
+                                    write("data: {\"error\":${JSONObject.quote(e.message ?: "stream error")}}\n\n")
+                                    flush()
+                                } catch (_: java.io.IOException) {
+                                    // Channel already closed, ignore
+                                }
+                            }
+                        }
+                    }
+                }
+
+                // OPTIONS preflight for ai/stream
+                options("/framework-$sessionId/ai/stream") {
+                    call.response.header(HttpHeaders.AccessControlAllowOrigin, allowedOrigin)
+                    call.response.header(HttpHeaders.AccessControlAllowMethods, "POST, OPTIONS")
+                    call.response.header(HttpHeaders.AccessControlAllowHeaders, "*")
+                    call.response.header(HttpHeaders.AccessControlMaxAge, "86400")
+                    call.respond(HttpStatusCode.OK)
+                }
+
+                // Native AI non-streaming endpoint — POST body: { "prompt": "...", "genConfig": {...} }
+                // Drains nativeAiSupplier's tokenFlow fully, then returns a single JSON response.
+                post("/framework-$sessionId/ai/generate") {
+                    call.response.header(HttpHeaders.AccessControlAllowOrigin, allowedOrigin)
+                    call.response.header(HttpHeaders.AccessControlAllowHeaders, "*")
+
+                    val body = try {
+                        JSONObject(call.receiveText())
+                    } catch (e: Exception) {
+                        JSONObject()
+                    }
+                    val userPrompt = body.optString("prompt", "")
+                    val genConfig = body.optJSONObject("genConfig") ?: JSONObject()
+                    val incomingConvId = body.optString("conversationId", "").takeIf { it.isNotBlank() }
+                    if (nativeSystemPrompt.isNotBlank()) Log.d(TAG, "Injecting system prompt (${nativeSystemPrompt.length} chars)")
+                    val prompt = if (nativeSystemPrompt.isNotBlank()) "$nativeSystemPrompt\n\n$userPrompt" else userPrompt
+
+                    val supplier = nativeAiSupplier
+                    if (supplier == null) {
+                        call.respondText(
+                            JSONObject().put("error", "Native AI not initialised — call initAI() first").toString(),
+                            ContentType.Application.Json,
+                            HttpStatusCode.ServiceUnavailable
+                        )
+                        return@post
+                    }
+                    if (prompt.isBlank()) {
+                        call.respondText(
+                            JSONObject().put("error", "prompt is empty").toString(),
+                            ContentType.Application.Json,
+                            HttpStatusCode.BadRequest
+                        )
+                        return@post
+                    }
+
+                    try {
+                        val (activeConvId, tokenFlow) = supplier(prompt, genConfig, incomingConvId)
+                        val output = StringBuilder()
+                        var tokenCount = 0
+                        withTimeout(AI_GENERATE_TIMEOUT_MS) {
+                            tokenFlow.collect { token -> output.append(token); tokenCount++ }
+                        }
+                        val responseJson = JSONObject()
+                            .put("output", output.toString())
+                            .put("conversationId", activeConvId)
+                            .put("tokenCount", tokenCount)
+                        call.respondText(responseJson.toString(), ContentType.Application.Json, HttpStatusCode.OK)
+                    } catch (e: TimeoutCancellationException) {
+                        Log.e(TAG, "Native AI generate timed out after ${AI_GENERATE_TIMEOUT_MS}ms", e)
+                        call.respondText(
+                            JSONObject().put("error", "generate timed out after ${AI_GENERATE_TIMEOUT_MS / 1000}s").toString(),
+                            ContentType.Application.Json,
+                            HttpStatusCode.GatewayTimeout
+                        )
+                    } catch (e: Exception) {
+                        Log.e(TAG, "Native AI generate error", e)
+                        call.respondText(
+                            JSONObject().put("error", (e.message ?: "generate error")).toString(),
+                            ContentType.Application.Json,
+                            HttpStatusCode.InternalServerError
+                        )
+                    }
+                }
+
+                // OPTIONS preflight for ai/generate
+                options("/framework-$sessionId/ai/generate") {
+                    call.response.header(HttpHeaders.AccessControlAllowOrigin, allowedOrigin)
+                    call.response.header(HttpHeaders.AccessControlAllowMethods, "POST, OPTIONS")
+                    call.response.header(HttpHeaders.AccessControlAllowHeaders, "*")
+                    call.response.header(HttpHeaders.AccessControlMaxAge, "86400")
+                    call.respond(HttpStatusCode.OK)
+                }
+
                 get("/framework-$sessionId/file-{fileId}") {
                     val fileId = call.parameters["fileId"]
                     
@@ -385,22 +551,16 @@ object FrameworkServerUtils {
         val expiredFiles = servedFiles.filter { (_, servedFile) ->
             currentTime - servedFile.createdAt > SESSION_TIMEOUT_MS
         }
-        
         if (expiredFiles.isNotEmpty()) {
             Log.d(TAG, "Cleaning up ${expiredFiles.size} expired files")
-            
-            expiredFiles.forEach { (fileId, _) ->
-                removeServedFile(fileId)
-            }
+            expiredFiles.forEach { (fileId, _) -> removeServedFile(fileId) }
         }
+
     }
     
     private fun cleanupAllFiles() {
         Log.d(TAG, "Cleaning up all served files (${servedFiles.size} files)")
-        
-        servedFiles.keys.toList().forEach { fileId ->
-            removeServedFile(fileId)
-        }
+        servedFiles.keys.toList().forEach { fileId -> removeServedFile(fileId) }
         
         // Clean cache directory
         cacheDirectory?.listFiles()?.forEach { file ->

package/dist/native/androidProject/settings.gradle.kts

@@ -33,3 +33,13 @@ dependencyResolutionManagement {
 
 rootProject.name = "Catalyst Application"
 include(":app")
+
+// @catalyst/cloud-ai — include when the package is installed.
+// The npm package ships an /android library module for native AI; wire it here so Gradle picks it up.
+// After running: npm install @catalyst/cloud-ai && npm run sync-packages -- --packages cloud-ai
+// Also set ai.enabled=true in your app config to enable useLegacyPackaging for GPU dlopen().
+val cloudAiDir = File(rootDir, "../node_modules/@catalyst/cloud-ai/android")
+if (cloudAiDir.exists()) {
+    include(":catalyst-cloud-ai")
+    project(":catalyst-cloud-ai").projectDir = cloudAiDir
+}

package/dist/native/androidSetup.js

@@ -209,13 +209,15 @@ async function checkEmulator(ADB_PATH) {
 }
 async function startEmulator(EMULATOR_PATH, androidConfig) {
   progress.log(`Starting emulator: ${androidConfig.emulatorName}...`);
-  // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - EMULATOR_PATH is derived from SDK configuration and emulatorName is local native setup config.
-  // eslint-disable-next-line security/detect-child-process
-  (0, _child_process.exec)(`${EMULATOR_PATH} -avd ${androidConfig.emulatorName} -read-only > /dev/null &`, error => {
-    if (error) {
-      progress.log(`Error starting emulator: ${error}`, "error");
-    }
+  // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - spawn with an argv array (no shell), so androidConfig.emulatorName can't be interpreted as shell syntax even though it comes from a locally-editable config file.
+  const child = (0, _child_process.spawn)(EMULATOR_PATH, ["-avd", androidConfig.emulatorName, "-read-only"], {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.on("error", error => {
+    progress.log(`Error starting emulator: ${error}`, "error");
   });
+  child.unref();
 }
 async function updateLocalProperties(sdkPath) {
   progress.start("properties");

package/dist/native/bridge/constants/NativeInterfaces.js

@@ -48,7 +48,10 @@ const NATIVE_COMMANDS = exports.NATIVE_COMMANDS = {
   // Security commands
   SET_SCREEN_SECURE: "setScreenSecure",
   GET_SCREEN_SECURE: "getScreenSecure",
-  CLEAR_WEB_DATA: "clearWebData"
+  CLEAR_WEB_DATA: "clearWebData",
+  // Native AI commands
+  INIT_AI: "initAI",
+  GENERATE_NATIVE: "generateNative"
 };
 
 // Callback Interfaces: Native → Web (incoming events/callbacks)
@@ -105,6 +108,13 @@ const NATIVE_CALLBACKS = exports.NATIVE_CALLBACKS = {
   ON_SCREEN_SECURE_ERROR: "ON_SCREEN_SECURE_ERROR",
   ON_WEB_DATA_CLEARED: "ON_WEB_DATA_CLEARED",
   ON_WEB_DATA_CLEAR_ERROR: "ON_WEB_DATA_CLEAR_ERROR",
+  // Native AI callbacks
+  ON_AI_READY: "ON_AI_READY",
+  ON_AI_TOKEN: "ON_AI_TOKEN",
+  ON_AI_DONE: "ON_AI_DONE",
+  ON_AI_ERROR: "ON_AI_ERROR",
+  ON_AI_PROGRESS: "ON_AI_PROGRESS",
+  ON_AI_LOG: "ON_AI_LOG",
   // Perf telemetry callbacks (native → web)
   CATALYST_PERF_EVENT: "CATALYST_PERF_EVENT"
 };
@@ -150,6 +160,10 @@ const INTERFACE_CATEGORIES = exports.INTERFACE_CATEGORIES = {
   TRANSITION: {
     commands: [NATIVE_COMMANDS.START_TRANSITION, NATIVE_COMMANDS.COMMIT_TRANSITION, NATIVE_COMMANDS.CANCEL_TRANSITION],
     callbacks: [NATIVE_CALLBACKS.ON_TRANSITION_COMMITTED, NATIVE_CALLBACKS.ON_TRANSITION_CANCELLED, NATIVE_CALLBACKS.ON_TRANSITION_TIMEOUT]
+  },
+  AI: {
+    commands: [NATIVE_COMMANDS.INIT_AI, NATIVE_COMMANDS.GENERATE_NATIVE],
+    callbacks: [NATIVE_CALLBACKS.ON_AI_READY, NATIVE_CALLBACKS.ON_AI_TOKEN, NATIVE_CALLBACKS.ON_AI_DONE, NATIVE_CALLBACKS.ON_AI_ERROR, NATIVE_CALLBACKS.ON_AI_PROGRESS, NATIVE_CALLBACKS.ON_AI_LOG]
   }
 };
 

package/dist/native/bridge/hooks/index.js

@@ -27,6 +27,12 @@ Object.defineProperty(exports, "sanitizeFilePickerOptions", {
     return _useFilePicker.sanitizeFilePickerOptions;
   }
 });
+Object.defineProperty(exports, "useAI", {
+  enumerable: true,
+  get: function () {
+    return _useAI.useAI;
+  }
+});
 Object.defineProperty(exports, "useCamera", {
   enumerable: true,
   get: function () {
@@ -111,6 +117,7 @@ Object.defineProperty(exports, "useVideoStream", {
     return _useVideoStream.useVideoStream;
   }
 });
+var _useAI = require("./useAI.js");
 var _useGoogleSignIn = require("./useGoogleSignIn.js");
 var _useCamera = require("./useCamera.js");
 var _useIntent = require("./useIntent.js");

package/dist/native/bridge/hooks/useAI.js

@@ -0,0 +1,94 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useAI = useAI;
+/* global __CATALYST_PACKAGES__ */
+
+function getBrowserConfig() {
+  try {
+    const raw = process.env.AI_PUBLIC_CONFIG;
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    return parsed?.browser || null;
+  } catch (_) {
+    return null;
+  }
+}
+function resolveMode(provider) {
+  if (provider === "transformers") return "local";
+  if (provider === "native") return "native";
+  return "cloud";
+}
+function isNativeAIAvailable() {
+  const nb = typeof window !== "undefined" && window.NativeBridge;
+  return nb && typeof nb.isAIAvailable === "function" && nb.isAIAvailable();
+}
+
+// __CATALYST_PACKAGES__ is substituted by webpack's DefinePlugin / Vite's `define` in
+// client bundles only. catalyst-core is externalized (nodeExternals) from the SSR
+// bundle, so on the server this file is loaded directly by Node — including via Vite's
+// ssrLoadModule, which executes real ESM with no bundler transform and no `require`
+// shim. useAI() always discards the SSR result anyway (returns emptyHook() when
+// `window` is undefined), so only ever attempt the client-side `require` — a bare
+// `require()` reached during SSR would throw ReferenceError rather than a catchable
+// MODULE_NOT_FOUND, since this package is "type": "module".
+const _pkg = typeof window !== "undefined" && (typeof __CATALYST_PACKAGES__ === "undefined" || __CATALYST_PACKAGES__.ai) ? (() => {
+  try {
+    return require(/* webpackIgnore: true */"catalyst-ai");
+  } catch (_) {
+    return null;
+  }
+})() : null;
+
+// provider: "transformers" → useWebAI   (catalyst-ai)
+//           "native"       → useNativeAI (catalyst-ai, falls back to useCloudAI if bridge unavailable)
+//           anything else  → useCloudAI  (catalyst-ai, default)
+function useAI(options = {}) {
+  const {
+    provider
+  } = options;
+  const config = getBrowserConfig();
+  const resolvedProvider = provider || config?.provider;
+  const mode = resolveMode(resolvedProvider);
+  const cloudResult = _pkg ? _pkg.useCloudAI(options) : emptyHook();
+  const webResult = _pkg ? _pkg.useWebAI(options) : emptyHook();
+  const nativeResult = _pkg ? _pkg.useNativeAI({
+    ...options,
+    enabled: mode === "native"
+  }) : emptyHook();
+  if (typeof window === "undefined") return emptyHook();
+  if (!_pkg) {
+    console.error("\n[catalyst-core] useAI requires catalyst-ai.\n" + "Run: npm install catalyst-ai\n");
+    return emptyHook();
+  }
+  if (mode === "local") return webResult;
+  if (mode === "native" && isNativeAIAvailable()) return nativeResult;
+  return cloudResult;
+}
+
+// Returned when catalyst-ai is missing — keeps hook shape stable so callers don't crash
+function emptyHook() {
+  return {
+    output: "",
+    streaming: false,
+    loading: false,
+    error: null,
+    modelReady: false,
+    downloadProgress: null,
+    nativeDownloadProgress: null,
+    nativeLogs: [],
+    metrics: null,
+    isLocal: false,
+    isNative: false,
+    isWeb: false,
+    generate: () => {},
+    cancel: () => {},
+    reset: () => {},
+    clearError: () => {},
+    conversationId: null,
+    getSessionMetrics: () => null,
+    resetSessionMetrics: () => {}
+  };
+}