catalyst-core 1.0.0 → 1.0.1-canary.2

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

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useAI = useAI;
+var _aiProviders = require("./aiProviders.js");
 /* global __CATALYST_PACKAGES__ */
 
 function getBrowserConfig() {
@@ -16,12 +17,10 @@ function getBrowserConfig() {
     return null;
   }
 }
-function resolveMode(provider) {
-  if (provider === "transformers") return "local";
-  if (provider === "native") return "native";
-  return "cloud";
-}
 function isNativeAIAvailable() {
+  // catalyst-ai knows both platforms (Android's NativeBridge, iOS's injected plugin manifest).
+  // Older catalyst-ai versions don't export it, so fall back to the Android-only check.
+  if (_pkg && typeof _pkg.isNativeAIAvailable === "function") return _pkg.isNativeAIAvailable();
   const nb = typeof window !== "undefined" && window.NativeBridge;
   return nb && typeof nb.isAIAvailable === "function" && nb.isAIAvailable();
 }
@@ -43,7 +42,8 @@ const _pkg = typeof window !== "undefined" && (typeof __CATALYST_PACKAGES__ ===
 })() : null;
 
 // provider: "transformers" → useWebAI   (catalyst-ai)
-//           "native"       → useNativeAI (catalyst-ai, falls back to useCloudAI if bridge unavailable)
+//           "native" | "litert" | "foundation-models"
+//                          → useNativeAI (catalyst-ai, falls back to useCloudAI if bridge unavailable)
 //           anything else  → useCloudAI  (catalyst-ai, default)
 // The shape of this hook is owned by the catalyst-ai package and sits outside
 // the native hook contract entirely, so its options and result stay loose here.
@@ -53,12 +53,13 @@ function useAI(options = {}) {
   } = options;
   const config = getBrowserConfig();
   const resolvedProvider = provider || config?.provider;
-  const mode = resolveMode(resolvedProvider);
+  const mode = (0, _aiProviders.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"
+    enabled: mode === "native",
+    engine: (0, _aiProviders.resolveNativeEngine)(resolvedProvider, options.engine, config)
   }) : emptyHook();
   if (typeof window === "undefined") return emptyHook();
   if (!_pkg) {

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

@@ -5,7 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useNativeTransition = void 0;
 var _react = require("react");
-var _reactRouter = require("react-router");
+var _useSafeNavigate = require("./useSafeNavigate.js");
 var _NativeBridge = _interopRequireDefault(require("../utils/NativeBridge.js"));
 var _NativeInterfaces = require("../constants/NativeInterfaces.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
@@ -40,7 +40,7 @@ const MIN_TIMEOUT = 800;
  * @param defaults - Default transition options applied to every navigate call
  */
 const useNativeTransition = (defaults = {}) => {
-  const router = (0, _reactRouter.useNavigate)();
+  const router = (0, _useSafeNavigate.useSafeNavigate)();
   const isNative = typeof window !== "undefined" && _NativeBridge.default.isAvailable();
   const [transitioning, setTransitioning] = (0, _react.useState)(false);
   const overlayRef = (0, _react.useRef)(null);

package/dist/native/bridge/hooks/useSafeNavigate.d.ts

@@ -0,0 +1,10 @@
+import { useNavigate } from "react-router";
+/**
+ * useNavigate() that is safe to call while server rendering.
+ *
+ * Server rendering never navigates, so it skips useNavigate there. In dev SSR src/native is compiled to
+ * CommonJS while the server's StaticRouter is ESM, which can load a second copy of react-router with no
+ * Router context; useNavigate would then throw and take the request, and the dev server, down. `window`
+ * is fixed per environment, so the hook order is stable.
+ */
+export declare const useSafeNavigate: () => ReturnType<typeof useNavigate>;

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

@@ -0,0 +1,22 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useSafeNavigate = void 0;
+var _reactRouter = require("react-router");
+// Stand-in for useNavigate() during server rendering, where nothing can navigate.
+const ssrNavigate = () => {};
+
+/**
+ * useNavigate() that is safe to call while server rendering.
+ *
+ * Server rendering never navigates, so it skips useNavigate there. In dev SSR src/native is compiled to
+ * CommonJS while the server's StaticRouter is ESM, which can load a second copy of react-router with no
+ * Router context; useNavigate would then throw and take the request, and the dev server, down. `window`
+ * is fixed per environment, so the hook order is stable.
+ */
+const useSafeNavigate = () =>
+// eslint-disable-next-line react-hooks/rules-of-hooks
+typeof window === "undefined" ? ssrNavigate : (0, _reactRouter.useNavigate)();
+exports.useSafeNavigate = useSafeNavigate;

package/dist/native/buildAppIos.js

@@ -10,7 +10,8 @@ const {
 } = require("./pluginComposerIos.js");
 const {
   resolveInternalPluginsRoot,
-  resolvePluginConfig
+  resolvePluginConfig,
+  resolveAIPluginSource
 } = require("./internalPluginUtils.js");
 const {
   formatBuildError
@@ -36,9 +37,14 @@ async function main() {
   } = build;
   try {
     progress.log("Starting build process...", "info");
-    const pluginConfig = resolvePluginConfig(WEBVIEW_CONFIG);
+    const aiPlugin = resolveAIPluginSource(WEBVIEW_CONFIG, process.cwd(), (message, status = "info") => progress.log(message, status));
+    const pluginConfig = {
+      ...resolvePluginConfig(WEBVIEW_CONFIG),
+      ...aiPlugin.toggles
+    };
     const pluginComposition = composeIosPlugins({
       corePluginsRoot: resolveInternalPluginsRoot(catalystCorePath),
+      externalPluginRoots: aiPlugin.roots,
       iosProjectPath: PROJECT_DIR,
       pluginConfig,
       log: (message, status = "info") => progress.log(message, status)

package/dist/native/buildIos/plugins.js

@@ -38,7 +38,9 @@ function formatSwiftPackageRequirement(dependency) {
   throw new Error(`Unsupported iOS package requirement type: ${dependency.requirement.type}`);
 }
 function formatSwiftPackageEntries(dependencies) {
-  return dependencies.map(d => `        .package(url: "${d.url}", ${formatSwiftPackageRequirement(d)})`);
+  return dependencies.map(d =>
+  // Local packages (requirement.type "path") are addressed by directory, not URL + version.
+  d.requirement.type === "path" ? `        .package(path: ${JSON.stringify(d.url)})` : `        .package(url: "${d.url}", ${formatSwiftPackageRequirement(d)})`);
 }
 function formatSwiftProductEntries(dependencies) {
   return dependencies.flatMap(d => d.products.map(p => `                .product(name: "${p}", package: "${d.package}")`));

package/dist/native/internalPluginUtils.js

@@ -64,6 +64,45 @@ function readIosUrlSchemes(value, fieldName, sourcePath) {
     };
   });
 }
+function readLocalIosDependency(entry, entryField, sourcePath) {
+  const pluginDir = path.dirname(sourcePath);
+  const relativePath = mustBeNonEmptyString(entry.path, `${entryField}.path`, sourcePath);
+  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - containment within pluginDir is enforced immediately below.
+  const resolved = path.resolve(pluginDir, relativePath);
+  if (resolved !== pluginDir && !resolved.startsWith(`${pluginDir}${path.sep}`)) {
+    throw new Error(`'${entryField}.path' must stay within the plugin directory: ${relativePath} in ${sourcePath}`);
+  }
+  if (!isDir(resolved)) {
+    throw new Error(`'${entryField}.path' does not exist: ${relativePath} in ${sourcePath}`);
+  }
+  // The lexical check above does not see symlinks: re-check containment on canonical paths so a link
+  // inside the plugin cannot point the Swift package outside it, and return the canonical path.
+  const realPluginDir = fs.realpathSync(pluginDir);
+  const realResolved = fs.realpathSync(resolved);
+  if (realResolved !== realPluginDir && !realResolved.startsWith(`${realPluginDir}${path.sep}`)) {
+    throw new Error(`'${entryField}.path' resolves outside the plugin directory: ${relativePath} in ${sourcePath}`);
+  }
+  if (entry.from != null || entry.exact != null || entry.url != null) {
+    throw new Error(`'${entryField}' with 'path' must not also set 'url', 'from' or 'exact' in ${sourcePath}`);
+  }
+  const products = readStringArray(entry.products, `${entryField}.products`, sourcePath, {
+    required: true,
+    nonEmpty: true
+  });
+  if (new Set(products).size !== products.length) {
+    throw new Error(`Duplicate product(s) found in '${entryField}.products' in ${sourcePath}`);
+  }
+  return {
+    // The absolute path doubles as the identity key the composer merges dependencies on.
+    url: realResolved,
+    package: entry.package == null ? path.basename(realResolved) : mustBeNonEmptyString(entry.package, `${entryField}.package`, sourcePath),
+    products,
+    requirement: {
+      type: "path",
+      version: "local"
+    }
+  };
+}
 function readIosDependencies(value, fieldName, sourcePath) {
   if (value == null) {
     return [];
@@ -76,6 +115,13 @@ function readIosDependencies(value, fieldName, sourcePath) {
     if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
       throw new Error(`'${entryField}' must be an object in ${sourcePath}`);
     }
+
+    // A dependency is either a remote package ({ url, from|exact }) or a Swift package shipped inside
+    // the plugin itself ({ path }, relative to the plugin directory). Local packages let a plugin
+    // pin a vendored copy instead of cloning a large or LFS-backed upstream repo.
+    if (entry.path != null) {
+      return readLocalIosDependency(entry, entryField, sourcePath);
+    }
     const url = mustBeNonEmptyString(entry.url, `${entryField}.url`, sourcePath);
     const packageIdentity = entry.package == null ? derivePackageIdentityFromUrl(url, `${entryField}.url`, sourcePath) : mustBeNonEmptyString(entry.package, `${entryField}.package`, sourcePath);
     const products = readStringArray(entry.products, `${entryField}.products`, sourcePath, {
@@ -224,7 +270,39 @@ function resolvePluginConfig(WEBVIEW_CONFIG) {
   }
   return pluginConfig;
 }
+
+/**
+ * catalyst-ai ships its native iOS module as a plugin (plugins/ai in the npm package). It is
+ * composed only when the app opts in with WEBVIEW_CONFIG.ai.enabled, mirroring Android's
+ * syncAIPackageIfEnabled. Returns the extra plugin roots plus the toggle to merge into the
+ * plugin config; when the package is missing it warns and leaves the build untouched.
+ */
+function resolveAIPluginSource(WEBVIEW_CONFIG, projectRoot, log = () => {}) {
+  if (WEBVIEW_CONFIG?.ai?.enabled !== true) {
+    return {
+      roots: [],
+      toggles: {}
+    };
+  }
+
+  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - fixed package-relative path under the app's node_modules.
+  const aiPluginsRoot = path.join(projectRoot, "node_modules", "catalyst-ai", "plugins");
+  if (!isDir(aiPluginsRoot)) {
+    log("ai.enabled=true but catalyst-ai not found in node_modules — skipping native AI plugin", "warning");
+    return {
+      roots: [],
+      toggles: {}
+    };
+  }
+  return {
+    roots: [aiPluginsRoot],
+    toggles: {
+      ai: true
+    }
+  };
+}
 module.exports = {
+  resolveAIPluginSource,
   discoverInternalPlugins,
   parsePluginManifest,
   resolvePluginConfig,

package/dist/native/iosnativeWebView/CoreLogic/Sources/CatalystCoreLogic/Utils/FrameworkServerUtils+NativeAI.swift

@@ -0,0 +1,221 @@
+//
+//  FrameworkServerUtils+NativeAI.swift
+//  iosnativeWebView
+//
+//  Native-AI routes (/ai/stream, /ai/generate) and their supplier API, split out of FrameworkServerUtils.swift
+//  to keep that file within the lint limits. Kotlin equivalent: the AI routes in startKtorServer().
+//
+
+import Foundation
+import Network
+import os
+
+private let logger = Logger(subsystem: Bundle.main.bundleIdentifier ?? "com.app", category: "FrameworkServer")
+
+extension FrameworkServerUtils {
+    // MARK: - Native AI API
+
+    /// Installs the engine that answers `POST /ai/stream` and `POST /ai/generate`. Each request calls the supplier
+    /// with the (system-prompt-prefixed) prompt, the request's `genConfig` and its conversation id. While it is
+    /// `nil` (the default, and after passing `nil`) both routes answer "not ready" (`AI-005`) instead of running.
+    /// Set by the AI plugin once its engine has loaded.
+    public func setNativeAiSupplier(_ supplier: NativeAISupplier?) {
+        aiLock.lock(); defer { aiLock.unlock() }
+        nativeAiSupplier = supplier
+    }
+
+    /// Sets the system prompt the server prepends (as `"<prompt>\n\n<user prompt>"`) to every AI request before it
+    /// reaches the supplier. Pass an empty string to prepend nothing, for engines that keep their instructions in
+    /// their own session. Read per request, so changes apply to the next one.
+    public func setNativeSystemPrompt(_ systemPrompt: String) {
+        aiLock.lock(); defer { aiLock.unlock() }
+        nativeSystemPrompt = systemPrompt
+    }
+
+    /// URL JS posts to for streaming; scheme follows whatever the listener actually runs (HTTP/HTTPS),
+    /// built the same way as served-file URLs.
+    public func nativeAIStreamURL() -> String? {
+        guard isServerRunning else { return nil }
+        let scheme = isHTTPS ? "https" : "http"
+        return "\(scheme)://localhost:\(serverPort)/framework-\(sessionId)/ai/stream"
+    }
+
+
+    // MARK: - Native AI routes
+    // Kotlin equivalent: the post("/ai/stream"), post("/ai/generate") and options(...) routes in
+    // startKtorServer(). The engine behind the supplier lives in catalyst-ai, not here.
+
+    private func aiSnapshot() -> (supplier: NativeAISupplier?, systemPrompt: String) {
+        aiLock.lock(); defer { aiLock.unlock() }
+        return (nativeAiSupplier, nativeSystemPrompt)
+    }
+
+    /// The server prepends the engine-provided system prompt, exactly like Android.
+    /// Engines that manage their own instructions simply never call setNativeSystemPrompt.
+    private func composePrompt(_ request: NativeAIRequest, systemPrompt: String) -> String {
+        systemPrompt.isEmpty ? request.prompt : "\(systemPrompt)\n\n\(request.prompt)"
+    }
+
+    func sendAIPreflight(on connection: NWConnection) {
+        sendHTTPResponse(on: connection, statusCode: 200, body: Data(), headers: [
+            "Access-Control-Allow-Methods": "POST, OPTIONS",
+            "Access-Control-Max-Age": "86400",
+        ])
+    }
+
+    func cancelAIStream(for connection: NWConnection) {
+        requestStateLock.lock()
+        let task = aiStreamTasks.removeValue(forKey: ObjectIdentifier(connection))
+        requestStateLock.unlock()
+        task?.cancel()
+    }
+
+    /// A client that stops reading must not keep the model running: if a write is not accepted within this long,
+    /// the connection is dropped, which fails the send, ends the stream and cancels generation upstream.
+    static let aiWriteTimeout: TimeInterval = 30
+
+    private func sendRaw(_ data: Data, on connection: NWConnection) async -> Bool {
+        await withCheckedContinuation { continuation in
+            let deadline = DispatchWorkItem { connection.cancel() }
+            DispatchQueue.global().asyncAfter(deadline: .now() + Self.aiWriteTimeout, execute: deadline)
+            connection.send(content: data, completion: .contentProcessed { error in
+                deadline.cancel()
+                if let error = error {
+                    logger.debug("AI stream send failed: \(error.localizedDescription)")
+                }
+                continuation.resume(returning: error == nil)
+            })
+        }
+    }
+
+    private func sseHeaders() -> Data {
+        var head = "HTTP/1.1 200 OK\r\n"
+        head += "Access-Control-Allow-Origin: \(allowedOrigin)\r\n"
+        head += "Access-Control-Allow-Methods: POST, OPTIONS\r\n"
+        head += "Access-Control-Allow-Headers: *\r\n"
+        head += "Content-Type: text/event-stream\r\n"
+        head += "Cache-Control: no-cache\r\n"
+        head += "X-Accel-Buffering: no\r\n"
+        head += "Connection: close\r\n"
+        head += "\r\n"
+        return Data(head.utf8)
+    }
+
+    func startAIStream(_ request: NativeAIRequest, on connection: NWConnection) {
+        cancelConnectionTimeout(for: connection)
+        let key = ObjectIdentifier(connection)
+
+        // Held across Task creation so the task's own cleanup cannot run before it is registered.
+        requestStateLock.lock()
+        aiStreamTasks[key] = Task { [weak self] in
+            guard let self = self else { connection.cancel(); return }
+            await self.runAIStream(request, on: connection)
+            self.cancelAIStream(for: connection)
+            connection.cancel()
+        }
+        requestStateLock.unlock()
+    }
+
+    private func runAIStream(_ request: NativeAIRequest, on connection: NWConnection) async {
+        guard await sendRaw(sseHeaders(), on: connection) else { return }
+
+        let (supplier, systemPrompt) = aiSnapshot()
+        let prompt = composePrompt(request, systemPrompt: systemPrompt)
+
+        guard let supplier = supplier else {
+            _ = await sendRaw(NativeAISSE.error("Native AI not initialised — call initAI() first", code: NativeAIErrorCode.streamNotReady), on: connection)
+            return
+        }
+        guard !request.prompt.isEmpty else {
+            _ = await sendRaw(NativeAISSE.error("prompt is empty", code: NativeAIErrorCode.invalidRequestBody), on: connection)
+            return
+        }
+
+        do {
+            let stream = try await supplier(prompt, request.genConfig, request.conversationId)
+            guard await sendRaw(NativeAISSE.conversationId(stream.conversationId), on: connection) else { return }
+            for try await token in stream.tokens {
+                // A failed send means the client disconnected; leaving the loop terminates the
+                // token stream, which is what stops generation upstream.
+                guard await sendRaw(NativeAISSE.token(token), on: connection) else { return }
+            }
+            _ = await sendRaw(NativeAISSE.done(), on: connection)
+        } catch is CancellationError {
+            logger.debug("Native AI stream cancelled (client disconnected)")
+        } catch {
+            let code = (error as? NativeAIError)?.code ?? NativeAIErrorCode.requestFailed
+            logger.error("Native AI stream error [\(code)] conversation=\(request.conversationId ?? "<new>"): \(error.localizedDescription)")
+            _ = await sendRaw(NativeAISSE.error(error.localizedDescription, code: code), on: connection)
+        }
+    }
+
+    private static let aiGenerateTimeout: TimeInterval = 120
+
+    /// Drains the token stream fully, then answers with one JSON body: { output, conversationId, tokenCount }.
+    func runAIGenerate(_ request: NativeAIRequest, on connection: NWConnection) {
+        cancelConnectionTimeout(for: connection)
+        let key = ObjectIdentifier(connection)
+
+        requestStateLock.lock()
+        aiStreamTasks[key] = Task { [weak self] in
+            guard let self = self else { connection.cancel(); return }
+            await self.respondAIGenerate(request, on: connection)
+            self.cancelAIStream(for: connection)
+        }
+        requestStateLock.unlock()
+    }
+
+    private func respondAIGenerate(_ request: NativeAIRequest, on connection: NWConnection) async {
+        func fail(_ status: Int, _ message: String, _ code: String) {
+            let body = (try? JSONSerialization.data(withJSONObject: ["error": message, "code": code])) ?? Data()
+            sendHTTPResponse(on: connection, statusCode: status, body: body, headers: ["Content-Type": "application/json"])
+        }
+
+        let (supplier, systemPrompt) = aiSnapshot()
+        guard let supplier = supplier else {
+            fail(503, "Native AI not initialised — call initAI() first", NativeAIErrorCode.streamNotReady)
+            return
+        }
+        guard !request.prompt.isEmpty else {
+            fail(400, "prompt is empty", NativeAIErrorCode.invalidRequestBody)
+            return
+        }
+
+        let prompt = composePrompt(request, systemPrompt: systemPrompt)
+        do {
+            let result: (output: String, conversationId: String, tokenCount: Int) = try await withThrowingTaskGroup(of: (String, String, Int)?.self) { group in
+                group.addTask {
+                    let stream = try await supplier(prompt, request.genConfig, request.conversationId)
+                    var output = ""
+                    var count = 0
+                    for try await token in stream.tokens { output += token; count += 1 }
+                    return (output, stream.conversationId, count)
+                }
+                group.addTask {
+                    try await Task.sleep(nanoseconds: UInt64(Self.aiGenerateTimeout * 1_000_000_000))
+                    return nil
+                }
+                defer { group.cancelAll() }
+                guard let first = try await group.next(), let value = first else {
+                    throw NativeAIError(message: "generate timed out after \(Int(Self.aiGenerateTimeout))s")
+                }
+                return value
+            }
+            let body = try JSONSerialization.data(withJSONObject: [
+                "output": result.output,
+                "conversationId": result.conversationId,
+                "tokenCount": result.tokenCount,
+            ])
+            sendHTTPResponse(on: connection, statusCode: 200, body: body, headers: ["Content-Type": "application/json"])
+        } catch is CancellationError {
+            connection.cancel()
+        } catch let error as NativeAIError where error.message.hasPrefix("generate timed out") {
+            fail(504, error.message, error.code)
+        } catch {
+            let code = (error as? NativeAIError)?.code ?? NativeAIErrorCode.requestFailed
+            logger.error("Native AI generate error [\(code)] conversation=\(request.conversationId ?? "<new>"): \(error.localizedDescription)")
+            fail(500, error.localizedDescription, code)
+        }
+    }
+
+}