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

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/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: () => {}
+  };
+}

package/dist/native/buildAndroid/assets.js

@@ -494,7 +494,7 @@ function createAssetsPhase(ctx) {
       let manifestContent = fs.readFileSync(manifestPath, "utf8");
       const metadataNames = ["default_notification_channel_id", "default_notification_icon", "default_notification_color", "com.google.firebase.messaging.default_notification_channel_id", "com.google.firebase.messaging.default_notification_icon", "com.google.firebase.messaging.default_notification_sound"];
       for (const metadataName of metadataNames) {
-        const metadataRegex = new RegExp(`\\s*<meta-data\\s+[\\s\\S]*?android:name="${metadataName}"[\\s\\S]*?\\/>`, "gi");
+        const metadataRegex = new RegExp(`\\s*<meta-data\\s+[^>]*?android:name="${metadataName}"[^>]*?\\/>`, "gi");
         manifestContent = manifestContent.replace(metadataRegex, "");
       }
       const serviceRegex = /\s*<!--\s*Push Notification Service\s*-->\s*<service[^>]*android:name="[^"]*PushNotificationUtils"[\s\S]*?<\/service>/gi;

package/dist/native/buildAndroid/index.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const path = require("path");
+const fs = require("fs");
 const {
   runCommand,
   runInteractiveCommand
@@ -75,6 +76,35 @@ function createAndroidBuild(config) {
     moveApkToOutputPath,
     buildSignedAAB
   } = createBuildPhase(ctx);
+  function syncAIPackageIfEnabled(wvConfig, progress) {
+    const aiEnabled = wvConfig?.ai?.enabled === true;
+    if (!aiEnabled) return;
+    const appNodeModules = path.join(process.cwd(), "node_modules");
+    const aiPackageSrc = path.join(appNodeModules, "catalyst-ai");
+    if (!fs.existsSync(aiPackageSrc)) {
+      progress.log("ai.enabled=true but catalyst-ai not found in node_modules — skipping native AI sync", "warning");
+      return;
+    }
+    const destDir = path.join(pwd, "node_modules", "catalyst-ai");
+    fs.mkdirSync(destDir, {
+      recursive: true
+    });
+    copyDirSync(aiPackageSrc, destDir);
+    progress.log("catalyst-ai synced to dist/native/node_modules for Gradle", "success");
+  }
+  function copyDirSync(src, dest) {
+    fs.mkdirSync(dest, {
+      recursive: true
+    });
+    for (const entry of fs.readdirSync(src, {
+      withFileTypes: true
+    })) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const s = path.join(src, entry.name); // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
+      const d = path.join(dest, entry.name); // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
+      entry.isDirectory() ? copyDirSync(s, d) : fs.copyFileSync(s, d);
+    }
+  }
   async function buildAndroidApp() {
     let androidConfig = null;
     let targetDevice = null;
@@ -133,6 +163,7 @@ function createAndroidBuild(config) {
       });
       await processNotifications(wvConfig);
       progress.log(`Build optimization: ${buildOptimisation ? "Enabled" : "Disabled"}`, "info");
+      syncAIPackageIfEnabled(wvConfig, progress);
       progress.complete("copyAssets");
       let movedApkPath = null;
       if (buildType === "release") {
@@ -352,6 +383,7 @@ function createAndroidBuild(config) {
         log: (message, status = "info") => progress.log(message, status)
       });
       await processNotifications(wvConfig);
+      syncAIPackageIfEnabled(wvConfig, progress);
       progress.log("✅ buildAndroidForTesting complete — project ready for gradlew test", "success");
       return {
         success: true

package/dist/native/buildIos/assets.js

@@ -123,7 +123,7 @@ module.exports = function createAssetsPhase(ctx) {
 
   // ─── Notification assets ─────────────────────────────────────────────────
 
-  async function validateNotificationAsset(filePath, assetType) {
+  function validateNotificationAsset(filePath, assetType) {
     const stats = fs.statSync(filePath);
     const fileSizeKB = stats.size / 1024;
     if (assetType === "icon" && fileSizeKB > 100) progress.log(`Warning: Notification icon ${path.basename(filePath)} is ${fileSizeKB.toFixed(1)}KB (recommended <100KB for optimal performance)`, "warning");else if (assetType === "sound" && fileSizeKB > 1024) progress.log(`Warning: Notification sound ${path.basename(filePath)} is ${fileSizeKB.toFixed(1)}KB (recommended <1MB)`, "warning");

package/dist/server/expressServer.js

@@ -12,8 +12,52 @@ const { cyan, yellow, green } = pc
 
 import { validateMiddleware, safeCall } from "./utils/validator.js"
 import { botDetectionMiddleware } from "./utils/botDetectionMiddleware.js"
+import { cjsRequire } from "./utils/cjsRequire.js"
 const { addMiddlewares } = await import(path.join(process.env.src_path, "server/server.js"))
 
+// Mount AI route if catalyst-ai is installed
+function mountAIRouter(app) {
+    let aiPackagePath
+    try {
+        aiPackagePath = cjsRequire.resolve("catalyst-ai/route", {
+            paths: [process.env.src_path || process.cwd()],
+        })
+    } catch (resolveErr) {
+        if (resolveErr.code !== "MODULE_NOT_FOUND") {
+            console.error("[catalyst-core/ai] Unexpected error resolving catalyst-ai:", resolveErr)
+        } else {
+            console.debug("[catalyst-core/ai] catalyst-ai not installed — AI routes unavailable")
+        }
+        return
+    }
+
+    try {
+        const aiRouter = cjsRequire(aiPackagePath)
+        let aiConfig = {}
+        try {
+            const parsedConfig = JSON.parse(process.env.AI_CONFIG || "{}")
+            if (parsedConfig && typeof parsedConfig === "object" && !Array.isArray(parsedConfig)) {
+                aiConfig = parsedConfig
+            } else {
+                console.warn("[catalyst-core/ai] AI_CONFIG must be a JSON object, ignoring it")
+            }
+        } catch (e) {
+            console.warn(`[catalyst-core/ai] Invalid AI_CONFIG JSON, ignoring: ${e.message}`)
+        }
+
+        if (aiConfig.enabled === false) {
+            console.log("[catalyst-core/ai] AI_CONFIG.enabled is false, skipping AI router")
+            return
+        }
+
+        const aiBasePath = aiConfig.basePath || "/ai"
+        console.log(`[catalyst-core/ai] mounting AI router at ${aiBasePath}`)
+        app.use(aiBasePath, aiRouter)
+    } catch (mountErr) {
+        console.error("[catalyst-core/ai] Failed to mount AI router:", mountErr)
+    }
+}
+
 // OpenTelemetry is opt-in (OTEL_ENABLE) — mirrors server/renderer/handler.jsx.
 // Passthrough no-op middleware when disabled or packages aren't installed.
 let responseFlushMiddleware = () => (_req, _res, next) => next()
@@ -106,6 +150,8 @@ async function createServer() {
     // All the middlewares defined by the user will run here.
     if (validateMiddleware(addMiddlewares)) addMiddlewares(app)
 
+    mountAIRouter(app)
+
     // response.compress + response.flush spans straddle compression — they
     // attribute the time past the `handler` span (gzip/brotli, then egress).
     // MUST be mounted immediately before compression() so its outer res.end

package/dist/server/renderer/handler.jsx

@@ -23,6 +23,7 @@ import {
     generateModulePreloadLinkElements,
 } from "./extract.js"
 import path from "path"
+import { Transform } from "node:stream"
 
 import CustomDocument from "@catalyst/template/server/document"
 
@@ -242,13 +243,17 @@ const _renderMarkUp = async (
         res.status(status)
 
         return new Promise((resolve, reject) => {
-            const { pipe } = renderToPipeableStream(<CompleteDocument />, {
-                onShellReady() {
-                    res.setHeader("content-type", "text/html")
-                    pipe(res)
+            // Single completion path: React's pipe() auto-ends `tail`, and
+            // `flush()` appends the deferred asset tags before that end
+            // signal propagates to `res` via the plain pipe below. This
+            // avoids the onShellReady/onAllReady race where React's own
+            // stream-end and a manual res.end() compete to close `res`
+            // (see issue #320).
+            const tail = new Transform({
+                transform(chunk, _enc, cb) {
+                    cb(null, chunk)
                 },
-
-                onAllReady() {
+                flush(cb) {
                     // Deferred assets — injected after body (non-blocking)
                     const deferredAssets = chunkExtractor
                         ? chunkExtractor.getDeferredAssets()
@@ -256,10 +261,10 @@ const _renderMarkUp = async (
 
                     // Tell client which components were SSR'd so split() can
                     // eagerly import them (prevents Suspense fallback flash)
-                    res.write(`<script>window.__CATALYST_IS_BOT__=${isBot ? "true" : "false"};</script>`)
+                    this.push(`<script>window.__CATALYST_IS_BOT__=${isBot ? "true" : "false"};</script>`)
                     if (chunkExtractor) {
                         const renderedKeys = chunkExtractor.getRenderedComponentKeys()
-                        res.write(
+                        this.push(
                             `<script>window.__SSR_RENDERED_COMPONENTS__=new Set(${JSON.stringify(renderedKeys)})</script>`
                         )
                     }
@@ -270,13 +275,24 @@ const _renderMarkUp = async (
                         isBot
                     )
                     if (newCssPaths.length) {
-                        res.write(`<style>${readCssFromDisk(newCssPaths, buildDir)}</style>`)
+                        this.push(`<style>${readCssFromDisk(newCssPaths, buildDir)}</style>`)
                     }
                     if (!isBot) {
-                        res.write(generateScriptStrings(deferredAssets.js))
+                        this.push(generateScriptStrings(deferredAssets.js))
                     }
 
-                    res.end()
+                    cb()
+                },
+            })
+            tail.pipe(res)
+
+            const { pipe } = renderToPipeableStream(<CompleteDocument />, {
+                onShellReady() {
+                    res.setHeader("content-type", "text/html")
+                    pipe(tail)
+                },
+
+                onAllReady() {
                     cleanupSafeArea()
                     resolve()
                 },
@@ -285,6 +301,7 @@ const _renderMarkUp = async (
                     console.error("Error in renderToPipeableStream:", error)
                     safeCall(onRenderError, { req, res, store, error })
                     cleanupSafeArea()
+                    tail.destroy(error)
                     reject(error)
                 },
             })

package/dist/vite/vite.config.js

@@ -1,7 +1,7 @@
 import { defineConfig, transformWithEsbuild } from "vite"
 import react from "@vitejs/plugin-react"
 import svgr from "vite-plugin-svgr"
-import { builtinModules } from "node:module"
+import { builtinModules, createRequire } from "node:module"
 
 /**
  * Treat all .scss imports as CSS modules (webpack compat).
@@ -131,6 +131,50 @@ const allAliases = { ..._moduleAliases, ...catalyst_moduleAliases }
 
 import { imageUrl, fontUrl } from "./scssParams.js"
 
+// Tailwind v4's zero-config scanner (`@tailwindcss/postcss`) walks up from
+// `dirname(from)` — the directory of the file PostCSS is currently compiling —
+// unless given an explicit `base`. Vite passes each CSS file's own resolved
+// path as `from`, so for catalyst-core's conventional layout (global
+// stylesheet under `src/static/css`, components under `src/js`, no shared
+// parent short of the app root) the scanner never reaches component files and
+// silently drops every class actually used in JSX. Webpack's postcss-loader
+// doesn't populate `from` the same way, which is why this only regresses
+// under Vite. We resolve the app's own postcss.config.js ourselves and patch
+// in `base: process.env.src_path` so the scan root covers the whole app.
+// Only the `{ pluginName: options }` shorthand can be patched this way —
+// array-form configs (`[require(...)()]`) have already closed over their
+// options — so anything else is left alone and Vite falls back to its normal
+// auto-loaded postcss.config.js resolution.
+const resolvePostcssPlugins = () => {
+    const configPath = path.join(process.env.src_path, "postcss.config.js")
+    if (!fs.existsSync(configPath)) return null
+
+    const appRequire = createRequire(configPath)
+
+    try {
+        const userConfig = appRequire(configPath)
+        const pluginsConfig = userConfig?.plugins
+
+        if (!pluginsConfig || Array.isArray(pluginsConfig) || typeof pluginsConfig !== "object") {
+            return null
+        }
+
+        return Object.entries(pluginsConfig).map(([name, options]) => {
+            const plugin = appRequire(name)
+            const finalOptions =
+                name === "@tailwindcss/postcss" && (!options || options.base === undefined)
+                    ? { ...options, base: process.env.src_path }
+                    : options
+            return plugin(finalOptions)
+        })
+    } catch (error) {
+        console.warn(`Failed to patch postcss config at ${configPath}:`, error.message)
+        return null
+    }
+}
+
+const postcssPlugins = resolvePostcssPlugins()
+
 const alias = () => {
     if (!allAliases || typeof allAliases !== "object") {
         return {}
@@ -177,6 +221,37 @@ export const getClientEnvVariables = () => {
         process.env["PUBLIC_STATIC_ASSET_URL"]
     )
 
+    // Derive AI_PUBLIC_CONFIG: only the browser block from AI_CONFIG, no API keys
+    let aiConfig = {}
+    try {
+        const parsedConfig = JSON.parse(process.env.AI_CONFIG || "{}")
+        if (parsedConfig && typeof parsedConfig === "object" && !Array.isArray(parsedConfig)) {
+            aiConfig = parsedConfig
+        } else {
+            console.warn("[catalyst-core] AI_CONFIG must be a JSON object, ignoring it")
+        }
+    } catch (e) {
+        console.warn(`[catalyst-core] Invalid AI_CONFIG JSON, ignoring: ${e.message}`)
+    }
+    const aiPublicConfig = aiConfig.browser ? { browser: aiConfig.browser } : {}
+    envVarDefinitions[`process.env.AI_PUBLIC_CONFIG`] = JSON.stringify(JSON.stringify(aiPublicConfig))
+
+    // Detect which catalyst-* AI packages are installed for the app, including
+    // hoisted/workspace installs — not just a direct app-local node_modules copy.
+    // Results are injected as __CATALYST_PACKAGES__.* literals so dead code
+    // referencing missing packages can be branched around at runtime.
+    const appRequire = createRequire(path.join(process.env.src_path || process.cwd(), "package.json"))
+    let aiPackageInstalled = false
+    try {
+        appRequire.resolve("catalyst-ai")
+        aiPackageInstalled = true
+    } catch {
+        aiPackageInstalled = false
+    }
+    envVarDefinitions["__CATALYST_PACKAGES__"] = JSON.stringify({
+        ai: aiPackageInstalled,
+    })
+
     return envVarDefinitions
 }
 
@@ -377,6 +452,7 @@ export default defineConfig({
             localsConvention: "camelCase",
             generateScopedName: "[name]__[local]___[hash:base64:5]",
         },
+        ...(postcssPlugins ? { postcss: { plugins: postcssPlugins } } : {}),
         preprocessorOptions: {
             scss: {
                 additionalData: (content) =>

package/mcp_v2/knowledge-base.json

@@ -170,15 +170,63 @@
     {
         "section": "build_system",
         "title": "iOS Build Pipeline",
-        "content": "1) Generate ConfigConstants.swift from WEBVIEW_CONFIG 2) Launch simulator 3) Clean Xcode project 4) Compile with Xcode 5) Install app + launch. Located in: src/native/iosnativeWebView/",
+        "content": "npm run buildApp:ios generates ConfigConstants.swift and plugin metadata from WEBVIEW_CONFIG, syncs selected public/ios assets into the package-owned Xcode project, detects a physical device or launches a simulator, cleans Xcode artifacts, compiles with the Debug configuration, and installs and launches the .app. It does not bundle the full Catalyst web client and does not create an App Store archive. The generated project is located under the resolved catalyst-core package at dist/native/iosnativeWebView/iosnativeWebView.xcodeproj.",
         "layer": "Build",
         "source": "static",
-        "tags": ["ios", "build"]
+        "tags": ["ios", "build", "buildApp:ios", "debug", "xcode"],
+        "github_files": [
+            "packages/catalyst-core/src/native/buildAppIos.js",
+            "packages/catalyst-core/src/native/buildIos/build.js"
+        ]
+    },
+    {
+        "section": "build_system",
+        "title": "Catalyst iOS Production Release Flow (0.2.x and 0.3.x)",
+        "content": "Catalyst 0.2.x and 0.3.x use the same iOS production-release flow: (1) deploy the production web application and verify its HTTPS URL, (2) finalize WEBVIEW_CONFIG, bundle ID, app version/build, plugins, permissions, capabilities, icons, splash assets, access-control rules, and privacy declarations, (3) run npm run buildApp:ios from the consuming app root to prepare the package-owned native project and perform its Debug build, (4) open the resolved catalyst-core package's dist/native/iosnativeWebView/iosnativeWebView.xcodeproj, (5) confirm the iosnativeWebView scheme's Archive action uses Release, configure Release signing and capabilities, choose a generic iOS device destination, and run Product -> Archive, (6) Validate App and upload with Distribute App -> TestFlight & App Store, then (7) finish TestFlight testing, App Store Connect metadata, build selection, and App Review submission. buildApp:ios does not create the final App Store artifact.",
+        "layer": "Build",
+        "source": "static",
+        "tags": [
+            "ios",
+            "release",
+            "production",
+            "0.2.x",
+            "0.3.x",
+            "buildApp:ios",
+            "xcode",
+            "archive",
+            "app-store",
+            "testflight"
+        ],
+        "github_files": [
+            "docs/content/08-Deployment/03-iOS-Production-Release.md",
+            "packages/catalyst-core/src/native/iosnativeWebView/iosnativeWebView.xcodeproj/xcshareddata/xcschemes/iosnativeWebView.xcscheme"
+        ]
+    },
+    {
+        "section": "build_system",
+        "title": "Generated iOS Project Signing and Persistence",
+        "content": "The generated Xcode project is package-owned state. Its shared xcconfig is regenerated with development-oriented code-signing defaults, and the bundled push entitlement can use aps-environment=development. Before an App Store archive, review the Release team, distribution signing, provisioning, capabilities, and entitlements in Xcode. Run the final npm run buildApp:ios before release-only Xcode changes: later Catalyst generation, package upgrades, or dependency installation can replace or regenerate native config constants, shared Xcode configuration, plist and entitlement content, generated plugin code/resources, selected project-file entries, and assets. Do not treat manual edits inside the generated project as durable app configuration.",
+        "layer": "Build",
+        "source": "static",
+        "tags": [
+            "ios",
+            "release",
+            "signing",
+            "provisioning",
+            "entitlements",
+            "push-notifications",
+            "generated-project",
+            "regeneration"
+        ],
+        "github_files": [
+            "packages/catalyst-core/src/native/buildIos/config.js",
+            "packages/catalyst-core/src/native/iosnativeWebView/iosnativeWebView/iosnativeWebView.entitlements"
+        ]
     },
     {
         "section": "build_system",
         "title": "Legacy 0.2.x Build NPM Scripts",
-        "content": "All catalyst npm scripts to add to package.json scripts block (each maps to: catalyst <scriptName>): devBuild \u2014 dev web build. devServe \u2014 dev server. buildApp \u2014 builds native app (both platforms). buildApp:android \u2014 Android native app build. buildApp:ios \u2014 iOS native app build. buildApp:android:release \u2014 Android release build. buildApp:ios:release \u2014 iOS release build. setupEmulator \u2014 sets up both emulators. setupEmulator:android \u2014 sets up Android AVD. setupEmulator:ios \u2014 sets up iOS simulator. NOTE: build:android / build:android:release / build:ios do NOT exist in catalyst \u2014 common mistake. The correct commands are buildApp:android and buildApp:ios. Missing any script = that npm run command fails.",
+        "content": "All catalyst npm scripts to add to package.json scripts block (each maps to: catalyst <scriptName>): devBuild \u2014 dev web build. devServe \u2014 dev server. buildApp \u2014 builds native apps. buildApp:android \u2014 Android native app build. buildApp:ios \u2014 iOS native project preparation and Debug build. buildApp:android:release \u2014 Android release build. setupEmulator \u2014 sets up both emulators. setupEmulator:android \u2014 sets up Android AVD. setupEmulator:ios \u2014 sets up iOS simulator. There is no separate buildApp:ios:release flow: run buildApp:ios, then create the production archive from the generated Xcode project's Release Archive action. NOTE: build:android / build:android:release / build:ios do NOT exist in catalyst \u2014 common mistake. Missing any script = that npm run command fails.",
         "layer": "Build",
         "source": "static",
         "tags": ["build", "scripts", "package.json", "native"]
@@ -434,7 +482,7 @@
     {
         "section": "config_structure",
         "title": "WEBVIEW_CONFIG Required Fields",
-        "content": "WEBVIEW_CONFIG field reference (from buildAppAndroid.js + buildAppIos.js source):\n\nTOP-LEVEL (both platforms):\n- port (string, required) \u2014 web server port e.g. \"3005\"\n- LOCAL_IP (string, required) \u2014 machine LAN IP e.g. \"192.168.0.11\". NOT localhost \u2014 emulator cannot resolve it\n- appInfo (string, required) \u2014 build identifier e.g. \"android-5Feb2026-v2.1.0\". Missing = iOS build breaks\n- useHttps (boolean, optional) \u2014 default false\n- cachePattern (string, optional) \u2014 comma-separated globs e.g. \"*.css\"\n- accessControl.enabled (boolean, optional) \u2014 default false\n- accessControl.allowedUrls (array, required if enabled) \u2014 URL patterns\n\nANDROID (WEBVIEW_CONFIG.android):\n- sdkPath (string, REQUIRED) \u2014 abs path to Android SDK. Build exits immediately without it\n- emulatorName (string, REQUIRED for debug) \u2014 AVD name. Run: emulator -list-avds\n- appName (string, optional) \u2014 default \"Catalyst Application\"\n- packageName (string, optional) \u2014 e.g. com.company.app. Derived from appName if missing\n- buildType (string, optional) \u2014 \"debug\" or \"release\". Default \"debug\"\n- keystore or keystoreConfig (required for release buildType only)\n- buildOptimisation (boolean, optional) \u2014 default false\n- cachePattern (string, optional)\n\nIOS (WEBVIEW_CONFIG.ios):\n- appBundleId (string, optional) \u2014 default \"com.debug.webview\". Must set for distribution\n- appName (string, optional) \u2014 default \"Catalyst Application\"\n- simulatorName (string, optional) \u2014 auto-detected if missing. e.g. \"iPhone 17 Pro\"\n- buildType (string, optional, CASE-SENSITIVE) \u2014 \"Debug\" or \"Release\". NOT lowercase \u2014 common mistake\n- deviceUDID (string, optional) \u2014 physical device builds only\n- developmentTeam (string, required if deviceUDID set) \u2014 Apple Developer Team ID\n- cachePattern (string, optional)",
+        "content": "WEBVIEW_CONFIG field reference (from buildAppAndroid.js + buildAppIos.js source):\n\nTOP-LEVEL (both platforms):\n- port (string, required) \u2014 web server port e.g. \"3005\"\n- LOCAL_IP (string, required) \u2014 machine LAN IP e.g. \"192.168.0.11\". NOT localhost \u2014 emulator cannot resolve it\n- appInfo (string, required) \u2014 build identifier e.g. \"android-5Feb2026-v2.1.0\". Missing = iOS build breaks\n- useHttps (boolean, optional) \u2014 default false\n- cachePattern (string, optional) \u2014 comma-separated globs e.g. \"*.css\"\n- accessControl.enabled (boolean, optional) \u2014 default false\n- accessControl.allowedUrls (array, required if enabled) \u2014 URL patterns\n\nANDROID (WEBVIEW_CONFIG.android):\n- sdkPath (string, REQUIRED) \u2014 abs path to Android SDK. Build exits immediately without it\n- emulatorName (string, REQUIRED for debug) \u2014 AVD name. Run: emulator -list-avds\n- appName (string, optional) \u2014 default \"Catalyst Application\"\n- packageName (string, optional) \u2014 e.g. com.company.app. Derived from appName if missing\n- buildType (string, optional) \u2014 \"debug\" or \"release\". Default \"debug\"\n- keystore or keystoreConfig (required for release buildType only)\n- buildOptimisation (boolean, optional) \u2014 default false\n- cachePattern (string, optional)\n\nIOS (WEBVIEW_CONFIG.ios):\n- appBundleId (string, optional) \u2014 default \"com.debug.webview\". Must set for distribution\n- appName (string, optional) \u2014 default \"Catalyst Application\"\n- simulatorName (string, optional) \u2014 auto-detected if missing. e.g. \"iPhone 17 Pro\"\n- buildType (string, optional) \u2014 may label copied Debug output but does not select the Xcode build configuration or create an App Store archive\n- deviceUDID (string, optional) \u2014 physical device builds only\n- developmentTeam (string, required if deviceUDID set) \u2014 Apple Developer Team ID\n- cachePattern (string, optional)\n\nFor iOS production, run buildApp:ios to prepare the generated project, then archive the iosnativeWebView scheme using its Release Archive action in Xcode.",
         "layer": "Config",
         "source": "static",
         "tags": ["config", "WEBVIEW_CONFIG", "android", "ios", "required", "fields"]

package/mcp_v2/mcp.js

@@ -62,21 +62,53 @@ if (projectInfo.notInstalled) {
     process.exit(1)
 }
 
-if (!fs.existsSync(DB_PATH)) {
+const dbMissing = !fs.existsSync(DB_PATH)
+const dbEmpty = !dbMissing && fs.statSync(DB_PATH).size === 0
+
+if (dbMissing || dbEmpty) {
+    try {
+        require("./setup")
+    } catch (setupErr) {
+        process.stderr.write(
+            JSON.stringify({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32000,
+                    message: `context.db ${dbEmpty ? "is empty" : "not found"} at ${DB_PATH}. Auto-setup failed: ${setupErr.message}. Run manually: node ${path.join(MCP_DIR, "setup.js")}`,
+                },
+                id: null,
+            }) + "\n"
+        )
+        // process.exit(1) instead of exitCode+return: this is top-level script code
+        // (not inside a function), and ESLint here rejects top-level return even
+        // though Node's CommonJS wrapper allows it. Matches the exit pattern used
+        // by the other startup-validation failures above (L49, L62).
+        process.exit(1)
+    }
+}
+
+let db
+try {
+    db = new Database(DB_PATH, { readonly: false })
+} catch (e) {
+    const isVersionMismatch =
+        e.code === "ERR_DLOPEN_FAILED" ||
+        e.message.includes("compiled against a different Node.js version") ||
+        e.message.includes("NODE_MODULE_VERSION")
     process.stderr.write(
         JSON.stringify({
             jsonrpc: "2.0",
             error: {
                 code: -32000,
-                message: `context.db not found at ${DB_PATH}. Run setup first: node ${path.join(MCP_DIR, "setup.js")}`,
+                message: isVersionMismatch
+                    ? `Native module mismatch for Node ${process.version}. Run: npm rebuild better-sqlite3`
+                    : `Failed to open context.db: ${e.message}`,
             },
             id: null,
         }) + "\n"
     )
     process.exit(1)
 }
-
-const db = new Database(DB_PATH, { readonly: false })
 const CONVERSION_TASKS = JSON.parse(fs.readFileSync(TASKS_PATH, "utf8"))
 
 // ── Module init ───────────────────────────────────────────────────────────────

package/mcp_v2/tools/build.js

@@ -149,19 +149,19 @@ const MASTER_FLOWS = {
             step: 1,
             cmd: null,
             label: "Pre-check: config",
-            detail: 'Reads WEBVIEW_CONFIG.ios. Requires: appBundleId, simulatorName, buildType (default "debug").',
+            detail: "Reads WEBVIEW_CONFIG and WEBVIEW_CONFIG.ios. Confirm the development URL, appBundleId, simulatorName, plugins, and selected public/ios assets.",
         },
         {
             step: 2,
-            cmd: "catalyst build",
-            label: "Build web assets",
-            detail: "Compiles web app. iOS build embeds these.",
+            cmd: "npm run buildApp:ios",
+            label: "iOS simulator build",
+            detail: "Generates native configuration and plugin code in the package-owned Xcode project, syncs selected assets, compiles with Xcode's Debug configuration, installs the .app, and launches it.",
         },
         {
             step: 3,
-            cmd: "npm run buildApp:ios",
-            label: "iOS simulator build",
-            detail: "Runs buildAppIos.js: generates ConfigConstants.swift from config (bundleId, URL, port, protocol), launches simulator (simulatorName), cleans Xcode artifacts, compiles with xcodebuild, installs .app, launches.",
+            cmd: null,
+            label: "Remote web application",
+            detail: "The iOS shell loads the configured remote URL. buildApp:ios does not bundle the full Catalyst web client, so the target web application must be reachable.",
         },
         {
             step: 4,
@@ -175,27 +175,44 @@ const MASTER_FLOWS = {
         {
             step: 1,
             cmd: null,
+            label: "Deploy the production web application",
+            detail: "Deploy the web application first and confirm its production URL is reachable over HTTPS. The iOS shell loads this remote URL; it does not embed the full web client bundle.",
+        },
+        {
+            step: 2,
+            cmd: null,
             label: "Pre-check: config",
-            detail: 'buildType must be "Release" (capital R — case-sensitive). appBundleId required. If googleSignIn enabled, GoogleService-Info.plist must be present.',
+            detail: "Finalize WEBVIEW_CONFIG, appBundleId, app name, version, incremented build number, access-control rules, plugins, permissions, capabilities, icons, splash assets, and privacy declarations.",
         },
-        { step: 2, cmd: "catalyst build", label: "Build web assets", detail: "Production build." },
         {
             step: 3,
             cmd: "npm run buildApp:ios",
-            label: "iOS release build",
-            detail: "Same script — build type is driven by WEBVIEW_CONFIG.ios.buildType. Generates ConfigConstants.swift with production URL and bundleId. Xcode compiles Release scheme.",
+            label: "Prepare the native project",
+            detail: "Run from the consuming Catalyst app root. This generates native configuration and plugin code, syncs selected assets, and performs a Debug native build. It does not create an App Store archive.",
         },
         {
             step: 4,
             cmd: null,
-            label: "Archive + export IPA",
-            detail: "Post-build: archive via Xcode Organizer or xcodebuild -exportArchive. Requires Apple distribution certificate + provisioning profile configured in Xcode.",
+            label: "Open the generated Xcode project",
+            detail: "Open node_modules/catalyst-core/dist/native/iosnativeWebView/iosnativeWebView.xcodeproj (or the resolved package equivalent). Confirm the iosnativeWebView scheme's Archive action uses Release.",
         },
         {
             step: 5,
             cmd: null,
-            label: "App Store submission",
-            detail: "Upload IPA via Transporter or Xcode Organizer. TestFlight for beta before release.",
+            label: "Configure signing and archive",
+            detail: "Select the correct Apple Developer team, distribution signing, capabilities, entitlements, bundle ID, version, and build. Choose a generic iOS device destination, then Product → Archive.",
+        },
+        {
+            step: 6,
+            cmd: null,
+            label: "Validate and upload",
+            detail: "In Xcode Organizer, run Validate App, then Distribute App → TestFlight & App Store and upload the build.",
+        },
+        {
+            step: 7,
+            cmd: null,
+            label: "Complete the release",
+            detail: "Wait for App Store Connect processing, test through TestFlight, complete store metadata and privacy disclosures, select the processed build, and submit it for App Review.",
         },
     ],
 }
@@ -495,6 +512,7 @@ function getProjectContext(root) {
         iosBuildType: (wv.ios?.buildType || "debug").toLowerCase(),
         hasKeystore: !!wv.android?.keystoreConfig,
         hasGoogleSignIn: !!wv.googleSignIn?.enabled,
+        hasNotifications: !!wv.notifications?.enabled,
         hasEcosystem: fileExists("ecosystem.config.js"),
         port: wv.port,
         useHttps: !!wv.useHttps,
@@ -618,7 +636,7 @@ function handle_get_build_flow({ platform, mode, symptom } = {}) {
             )
         }
 
-        const isRelease = m === "release" || ctx.iosBuildType === "release"
+        const isRelease = m === "release"
         flow_key = isRelease ? "ios_release" : "ios_debug"
 
         if (!ctx.wv.ios?.appBundleId) {
@@ -634,13 +652,23 @@ function handle_get_build_flow({ platform, mode, symptom } = {}) {
                 "googleSignIn.enabled=true but iosClientId may be missing — check WEBVIEW_CONFIG.googleSignIn.iosClientId."
             )
         }
-        if (isRelease && ctx.iosBuildType !== "release") {
+        if (isRelease && !ctx.useHttps) {
             warnings.push(
-                'ios.buildType is not "Release" (case-sensitive). Release builds require exactly "Release" — not "release".'
+                "WEBVIEW_CONFIG.useHttps is not enabled — the App Store flow requires a reachable HTTPS production web application."
+            )
+        }
+        if (isRelease && ctx.hasNotifications) {
+            warnings.push(
+                "Push notifications are enabled — review the generated aps-environment entitlement and Release provisioning before archiving."
             )
         }
 
         notes.push(`buildType detected: ${ctx.wv.ios?.buildType || "not set (defaults to debug)"}`)
+        if (isRelease) {
+            notes.push(
+                "ios.buildType does not select the App Store build configuration; buildApp:ios still performs a Debug build. Archive the generated project with the scheme's Release action."
+            )
+        }
         if (ctx.wv.ios?.appBundleId) notes.push(`appBundleId: ${ctx.wv.ios.appBundleId}`)
         if (ctx.wv.ios?.simulatorName) notes.push(`simulatorName: ${ctx.wv.ios.simulatorName}`)
         if (ctx.hasGoogleSignIn) notes.push("googleSignIn: enabled")

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "catalyst-core",
-    "version": "0.3.0-beta.1",
+    "version": "0.3.0-beta.2",
     "type": "module",
     "main": "./dist/index.jsx",
     "description": "Web framework that provides great performance out of the box",
@@ -31,7 +31,7 @@
         "lint": "eslint .",
         "lint-staged": "lint-staged",
         "prettify": "prettier . --write",
-        "prepare": "rm -rf ./dist && cp -r ./src ./dist && babel src/native --out-dir dist/native --config-file ./babel.native.config.cjs --ignore '**/.build/**' && babel src/sentry.js --out-file dist/sentry.cjs --config-file ./babel.native.config.cjs",
+        "prepare": "node ../../scripts/safe-rimraf.js ./dist && cp -r ./src ./dist && babel src/native --out-dir dist/native --config-file ./babel.native.config.cjs --ignore '**/.build/**' && babel src/sentry.js --out-file dist/sentry.cjs --config-file ./babel.native.config.cjs",
         "prepublishOnly": "npm run prepare",
         "test:fixture": "sh ../../scripts/test-catalyst-core.sh"
     },