catalyst-core 1.0.0 → 1.0.1-canary.2

package/mcp_v2/knowledge-base.json

@@ -697,7 +697,7 @@
     {
         "section": "native_hooks",
         "title": "useSafeArea \u2014 return shape",
-        "content": "useSafeArea() returns: { top: number, right: number, bottom: number, left: number, isNative: boolean, isWeb: boolean, webFallbackActive, webFallbackDisabled, setWebFallback } \u2014 inset values in pixels. isNative=true when running in Android/iOS WebView. isWeb=!isNative. On native: live updates via WebBridge ON_SAFE_AREA_INSETS_UPDATED. No isNative guard needed \u2014 safe to use on both platforms.\n\nWEB FALLBACK: Reads CSS env() variables \u2014 env(safe-area-inset-top/right/bottom/left) \u2014 parsed via a hidden DOM element. Falls back to 0 if env() vars are not set (desktop browsers). Manages webFallback state locally (thin-state hook).",
+        "content": "useSafeArea() returns: { top: number, right: number, bottom: number, left: number, isNative: boolean, isWeb: boolean, webFallbackActive, webFallbackDisabled, setWebFallback } \u2014 inset values in CSS pixels on both platforms; all 0 when WEBVIEW_CONFIG.edgeToEdge.enabled is false (the default). isNative=true when running in Android/iOS WebView. isWeb=!isNative. On native: live updates via WebBridge ON_SAFE_AREA_INSETS_UPDATED. No isNative guard needed \u2014 safe to use on both platforms.\n\nWEB FALLBACK: Reads CSS env() variables \u2014 env(safe-area-inset-top/right/bottom/left) \u2014 parsed via a hidden DOM element. Falls back to 0 if env() vars are not set (desktop browsers). Manages webFallback state locally (thin-state hook).",
         "layer": "Runtime",
         "source": "static",
         "tags": ["native-hooks", "useSafeArea", "return-shape", "web-fallback"]
@@ -1303,7 +1303,7 @@
     {
         "section": "routing",
         "title": "Catalyst 0.3.x Integrated Router",
-        "content": "Catalyst 0.3.x removes the @tata1mg/router package dependency. As of 1.0.0 (the API freeze), catalyst-core does NOT re-export React Router. Its root entry exports exactly eight names: RouterDataProvider, useCurrentRouteData, useRouterData, MetaTag, split, hydrationReady, Head, Body. There is no default export (split was previously also the default). React Router is a peerDependency (^7.18.2): install react-router in the application and import RouterProvider, Outlet, Link, useParams, useNavigate, useLocation, Navigate and every other router name from 'react-router' directly. Metadata utilities (getMetaData, mergeHeadElements, deleteHeadTagsByDataAttribute), RouterContext, serverDataFetcher and useNavigateWithTransition are no longer public. Existing route arrays and preparedRoutes structure remain unchanged. Keeping both router packages can create duplicate runtime contracts and invalid React element errors.",
+        "content": "Catalyst 0.3.x removes the @tata1mg/router package dependency. As of 1.0.0 (the API freeze), catalyst-core does NOT re-export React Router. Its root entry exports exactly eight names: RouterDataProvider, useCurrentRouteData, useRouterData, MetaTag, split, hydrationReady, Head, Body. There is no default export (split was previously also the default). React Router is a peerDependency (^7.18.2): install react-router in the application and import Outlet, Link, useParams, useNavigate, useLocation, Navigate and every other router name from 'react-router' directly. Import RouterProvider in client/index.js from 'react-router/dom', which passes React DOM's flushSync to the router. Metadata utilities (getMetaData, mergeHeadElements, deleteHeadTagsByDataAttribute), RouterContext, serverDataFetcher and useNavigateWithTransition are no longer public. Existing route arrays and preparedRoutes structure remain unchanged. Keeping both router packages can create duplicate runtime contracts and invalid React element errors.",
         "layer": "Runtime",
         "source": "static",
         "tags": [
@@ -1377,7 +1377,7 @@
     {
         "section": "version_migration",
         "title": "Upgrading catalyst-core 0.3.x to 1.0.0",
-        "content": "Upgrade path for an application on catalyst-core 0.3.0-beta.5. Older applications first move to 0.3.x (see 'Legacy 0.2.x Migration Phase 0' and 'Catalyst 0.3.x React Runtime Contract'). 1.0.0 is the API freeze; there is no 0.4.0 release. Do the steps in order.\n\n1. DEPENDENCIES: set catalyst-core to 1.0.0. Add react-router ^7.18.2 as an application dependency: it is now a peer dependency and the server throws at startup if it is missing or outside that range. Keep react and react-dom pinned to 19.0.0. TypeScript applications also need @types/react ^19.0.0.\n\n2. NODE: run node -v. catalyst-core 1.0.0 requires >=22.12; on Node 20, importing catalyst-core/hooks or catalyst-core/WebBridge fails with ERR_REQUIRE_ESM. If the runtime is older, stop and tell the user; do not change the project's Node pin yourself.\n\n3. IMPORTS: the root entry exports exactly RouterDataProvider, useCurrentRouteData, useRouterData, MetaTag, split, hydrationReady, Head, Body. Move every React Router name (Link, Outlet, RouterProvider, useParams, useNavigate, useLocation, Navigate, ...) from 'catalyst-core' to 'react-router'. Replace `import split from 'catalyst-core'` with `import { split } from 'catalyst-core'`; there is no default export. Replace imports from 'catalyst-core/document' with Head and Body from 'catalyst-core'. 'catalyst-core/caching' is removed with no replacement. RouterContext, serverDataFetcher, mergeHeadElements, deleteHeadTagsByDataAttribute, getMetaData, useNavigateWithTransition and sanitizeFilePickerOptions (catalyst-core/hooks) are internal with no replacement: if the application uses one, stop and tell the user instead of inventing a substitute.\n\n4. BUILD AND START: run the build, then start the server once. The build catches removed imports (they fail instead of resolving to undefined); startup catches the react-router range and the Node version.\n\n5. HOOK ERROR FIELDS (not caught by the build): hook errors are now CatalystError instances. Rename reads of error.action to error.suggestedAction and error.nativeError to error.cause; error.recoverable and error.timestamp no longer exist. error.code values are registry codes (RUNTIME-NATIVE-xxx) instead of names like PERMISSION_DENIED, so replace string-literal comparisons with ERROR_CODES from catalyst-core/errors (for example ERROR_CODES.RUNTIME_NATIVE_PERMISSION_DENIED). See 'CatalystError shape (1.0.0)'.\n\n6. OPTIONAL, NON-BREAKING: rename deprecated hook alias keys to the canonical ones (see 'Native hooks \u2014 aliases and deprecations'); aliases keep working until 2.0.\n\nUnchanged: route arrays, preparedRoutes, server hooks, config/config.json keys and module aliases. Full guide: docs/content/12-Migration/02-Version-Upgrades.md.",
+        "content": "Upgrade path for an application on catalyst-core 0.3.x to 1.0.0, the stable release. Read the installed catalyst-core version from package.json first. 0.3.0-beta.5 upgrades directly. 0.3.0-beta.1 to 0.3.0-beta.4 used react-router-dom 6, so those also cross React Router 6 to 7 (step 1). Older applications first move to 0.3.x (see 'Legacy 0.2.x Migration Phase 0' and 'Catalyst 0.3.x React Runtime Contract'). 1.0.0 is the API freeze; there is no 0.4.0 release. Do the steps in order.\n\n1. DEPENDENCIES: set catalyst-core to 1.0.0. Add react-router ^7.18.2 as an application dependency: it is now a peer dependency and the server exits at startup if it is missing or outside that range. Keep react and react-dom pinned to 19.0.0. TypeScript applications also need @types/react ^19.0.0. catalyst-core no longer installs react-router-dom, so change any import from 'react-router-dom' to 'react-router', except RouterProvider, which comes from 'react-router/dom' (step 3).\n\n2. NODE: run node -v. catalyst-core 1.0.0 requires >=22.12; on Node 20, importing catalyst-core/hooks or catalyst-core/WebBridge fails with ERR_REQUIRE_ESM. If the runtime is older, stop and tell the user; do not change the project's Node pin yourself.\n\n3. IMPORTS: the root entry exports exactly RouterDataProvider, useCurrentRouteData, useRouterData, MetaTag, split, hydrationReady, Head, Body. Move every React Router name (Link, Outlet, useParams, useNavigate, useLocation, Navigate, ...) from 'catalyst-core' to 'react-router'. In client/index.js import RouterProvider from 'react-router/dom', not 'react-router': only the /dom export passes React DOM's flushSync to the router, and the wrong one renders without any error. Replace `import split from 'catalyst-core'` with `import { split } from 'catalyst-core'`; there is no default export. Replace imports from 'catalyst-core/document' with Head and Body from 'catalyst-core'. 'catalyst-core/caching' is removed with no replacement. RouterContext, serverDataFetcher, mergeHeadElements, deleteHeadTagsByDataAttribute, getMetaData, useNavigateWithTransition and sanitizeFilePickerOptions (catalyst-core/hooks) are internal with no replacement: if the application uses one, stop and tell the user instead of inventing a substitute.\n\n4. CONFIG: catalyst start, build and serve now run a preflight and exit before starting when config/config.json lacks NODE_SERVER_HOSTNAME, NODE_SERVER_PORT, BUILD_OUTPUT_PATH, PUBLIC_STATIC_ASSET_PATH, PUBLIC_STATIC_ASSET_URL or CLIENT_ENV_VARIABLES, or when package.json _moduleAliases lacks @api, @containers, @server, @config, @css or @routes. Apps created from the templates already have all of them. WEBPACK_DEV_SERVER_HOSTNAME, WEBPACK_DEV_SERVER_PORT and ANALYZE_BUNDLE are no longer read and can be removed.\n\n5. BUILD AND START: run the build, then start the server once. The build catches removed imports (they fail instead of resolving to undefined); startup catches the react-router range and the preflight. Nothing checks the Node version at startup; an old Node fails only when hooks or WebBridge is imported (step 2).\n\n6. HOOK ERROR FIELDS (not caught by the build): hook errors are now CatalystError instances. Rename reads of error.action to error.suggestedAction and error.nativeError to error.cause; error.recoverable and error.timestamp no longer exist. error.code values are registry codes (RUNTIME-NATIVE-xxx) instead of names like PERMISSION_DENIED, so replace string-literal comparisons with ERROR_CODES from catalyst-core/errors (for example ERROR_CODES.RUNTIME_NATIVE_PERMISSION_DENIED). error.category is now 'RUNTIME-NATIVE' instead of PERMISSION, NETWORK, FILE_SYSTEM and the other old values. JSON.stringify(error) no longer includes the message; log error.message. See 'CatalystError shape (1.0.0)'.\n\n7. OPTIONAL, NON-BREAKING: rename deprecated hook alias keys to the canonical ones (see 'Native hooks \u2014 aliases and deprecations'); aliases keep working until 2.0.\n\nUnchanged: route arrays, preparedRoutes, server/index.js, server/server.js and server/document.js contracts, server hooks, and WEBVIEW_CONFIG. Full guide: docs/content/12-Migration/02-Version-Upgrades.md.",
         "layer": "Framework",
         "source": "static",
         "tags": [
@@ -1393,7 +1393,13 @@
             "react-router",
             "peer-dependency",
             "peerDependency",
-            "node"
+            "node",
+            "react-router-dom",
+            "preflight",
+            "module-aliases",
+            "stable",
+            "latest",
+            "0.3.0-beta.5"
         ],
         "github_files": ["docs/content/12-Migration/02-Version-Upgrades.md"]
     },
@@ -1427,5 +1433,29 @@
             "packages/catalyst-core/src/errors/index.js",
             "packages/catalyst-core/src/native/bridge/errors.ts"
         ]
+    },
+    {
+        "section": "native_hooks",
+        "title": "On-Device AI (catalyst-ai) — Setup & Engines",
+        "content": "catalyst-ai runs LLMs ON THE DEVICE inside the native app (no API key, works offline after model download) alongside its cloud providers (openai, gemini). Two on-device engines: (1) LiteRT-LM running Gemma 4 E2B (default model 'gemma-4-E2B', ~2.6 GB downloaded once on first use; Android and iOS; iOS needs iPhone 13 Pro or newer / 6 GB RAM). (2) Apple Foundation Models (iOS 26+ on Apple Intelligence devices only; no download; ~4,000 tokens of context shared by system prompt, history and reply). SETUP: npm install catalyst-ai; in config/config.json set WEBVIEW_CONFIG.ai = { \"enabled\": true } (native plugin is composed ONLY when ai.enabled is true — installing the package alone adds nothing to the build; if ai.enabled but catalyst-ai is missing from node_modules the build warns and skips the plugin); rebuild the native app (catalyst build / run android|ios). iOS adds the LiteRT-LM Swift package (~120 MB, vendored wrapper, no Git LFS) and the com.apple.developer.kernel.increased-memory-limit entitlement — that capability must be allowed for the App ID on a physical device or signing fails. iOS simulator needs an Apple Silicon Mac (no Intel slice); Foundation Models does not work in a simulator older than the host macOS.",
+        "layer": "Runtime",
+        "source": "static",
+        "tags": "ai,catalyst-ai,native ai,on-device,gemma,gemma 4,e2b,litert,litert-lm,foundation models,apple intelligence,useAI,useNativeAI"
+    },
+    {
+        "section": "native_hooks",
+        "title": "On-Device AI — Choosing Gemma 4 E2B or Apple Foundation Models",
+        "content": "Pick the engine per hook or app-wide. PER HOOK: useAI({ provider: 'litert', model: 'gemma-4-E2B' }) pins Gemma 4 E2B via LiteRT-LM; useAI({ provider: 'foundation-models' }) pins Apple Foundation Models (iOS only); useAI({ provider: 'native' }) = auto. useNativeAI accepts { engine: 'auto'|'litert'|'foundation-models', model, modelPath }. APP-WIDE in config/config.json: \"AI_CONFIG\": { \"enabled\": true, \"browser\": { \"provider\": \"foundation-models\" } } (provider 'native' + engine 'litert' is equivalent to provider 'litert'). AUTO POLICY (default): LiteRT-LM if its model is already downloaded -> Apple Foundation Models if available -> LiteRT-LM (downloads the model first). 'auto' never starts the 2.6 GB download on its own just because Foundation Models is available; to force Gemma on such a device pass engine/provider 'litert'. modelPath loads a custom LiteRT-LM model file. The ON_AI_READY payload includes 'engine' so UI can show which is active; download progress arrives as nativeDownloadProgress. Streaming: LiteRT-LM emits deltas; Foundation Models snapshots are converted to deltas by the framework.",
+        "layer": "Runtime",
+        "source": "static",
+        "tags": "ai,catalyst-ai,native ai,on-device,gemma,gemma 4,e2b,litert,litert-lm,foundation models,apple intelligence,useAI,useNativeAI"
+    },
+    {
+        "section": "bridge_architecture",
+        "title": "On-Device AI — Architecture & Security",
+        "content": "iOS: the framework server exposes POST /ai/stream (SSE), /ai/generate and a preflight route that the JS nativeTransport (catalyst-ai/src/nativeTransport.js) calls; the Swift side is the CatalystAI plugin (plugins/ai: AIBridge, CatalystAIBridge, NativeBridgeAI, FoundationModelsAI) discovered through the CatalystPlugin composer (pluginComposerIos.js) from node_modules/catalyst-ai/plugins; events return via WebBridge ON_AI_* and window.CatalystPlugins is injected for synchronous detection. Android: NativeBridgeAI.kt in the catalyst-ai android module, synced when ai.enabled. The AI routes reject non-loopback peers. Cloud routes (/ai/:provider/generate|stream) have NO built-in auth or rate limiting — add them via addMiddlewares in server/server.js before exposing beyond a trusted network. Known deferred hardening: plugin-bridge origin check, loopback-only listener bind, resumable model downloads.",
+        "layer": "Bridge",
+        "source": "static",
+        "tags": "ai,catalyst-ai,native ai,on-device,gemma,gemma 4,e2b,litert,litert-lm,foundation models,apple intelligence,useAI,useNativeAI"
     }
 ]

package/mcp_v2/test/config.test.ts

@@ -0,0 +1,52 @@
+// check_config coverage for the on-device AI (catalyst-ai) settings.
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+const { handle_check_config }: typeof import("../tools/config.js") = require("../tools/config.js")
+
+function makeProject(ai: unknown, aiConfig: unknown, installAi: boolean): string {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-cfg-"))
+    fs.mkdirSync(path.join(root, "config"))
+    const config = { WEBVIEW_CONFIG: { LOCAL_IP: "192.168.0.11", ai }, AI_CONFIG: aiConfig }
+    fs.writeFileSync(path.join(root, "config", "config.json"), JSON.stringify(config))
+    if (installAi) {
+        fs.mkdirSync(path.join(root, "node_modules", "catalyst-ai"), { recursive: true })
+        fs.writeFileSync(path.join(root, "node_modules", "catalyst-ai", "package.json"), "{}")
+    }
+    return root
+}
+
+const aiFields = (r: ReturnType<typeof handle_check_config>) =>
+    [...r.issues, ...r.warnings].filter((f) => /ai/i.test(f.field))
+
+describe("check_config: on-device AI", () => {
+    it("errors when ai.enabled but catalyst-ai is not installed", () => {
+        const r = handle_check_config({ project_path: makeProject({ enabled: true }, {}, false) })
+        expect(r.issues.some((i) => i.field === "WEBVIEW_CONFIG.ai")).toBe(true)
+    })
+
+    it("passes when ai.enabled and catalyst-ai is installed", () => {
+        const r = handle_check_config({ project_path: makeProject({ enabled: true }, {}, true) })
+        expect(r.passed.some((p) => p.field === "WEBVIEW_CONFIG.ai")).toBe(true)
+        expect(r.issues.some((i) => i.field === "WEBVIEW_CONFIG.ai")).toBe(false)
+    })
+
+    it("rejects an unknown engine", () => {
+        const r = handle_check_config({
+            project_path: makeProject({ enabled: true }, { browser: { engine: "gpt" } }, true),
+        })
+        expect(r.issues.some((i) => i.field === "AI_CONFIG.browser.engine")).toBe(true)
+    })
+
+    it("warns when an on-device provider is set but ai.enabled is off", () => {
+        const r = handle_check_config({
+            project_path: makeProject(undefined, { browser: { provider: "litert" } }, true),
+        })
+        expect(r.warnings.some((w) => w.field === "WEBVIEW_CONFIG.ai.enabled")).toBe(true)
+    })
+
+    it("stays silent for apps that do not use AI", () => {
+        const r = handle_check_config({ project_path: makeProject(undefined, {}, false) })
+        expect(aiFields(r)).toEqual([])
+    })
+})

package/mcp_v2/tools/config.d.ts

@@ -0,0 +1,18 @@
+// Hand-written type declaration for config.js (plain CJS, see issue #420);
+// used only by test/config.test.ts. Keep in sync by hand.
+
+export interface ConfigFinding {
+    field: string
+    severity?: string
+    message?: string
+    note?: string
+}
+
+export interface CheckConfigResult {
+    issues: ConfigFinding[]
+    warnings: ConfigFinding[]
+    passed: ConfigFinding[]
+}
+
+export function init(projectInfo: { dir: string }): void
+export function handle_check_config(args?: { project_path?: string; platform?: string }): CheckConfigResult

package/mcp_v2/tools/config.js

@@ -434,6 +434,46 @@ function handle_check_config({ project_path, platform = "both" } = {}) {
         }
     }
 
+    // ── ai (optional, on-device AI via catalyst-ai) ───────────────────────────
+    if (wc.ai && wc.ai.enabled) {
+        const aiPkg = path.join(root, "node_modules", "catalyst-ai", "package.json")
+        if (!fs.existsSync(aiPkg)) {
+            issues.push({
+                field: "WEBVIEW_CONFIG.ai",
+                severity: "error",
+                message:
+                    "ai.enabled=true but catalyst-ai is not installed. The native AI plugin is silently skipped and on-device AI will not work. Run: npm install catalyst-ai",
+            })
+        } else {
+            passed.push({ field: "WEBVIEW_CONFIG.ai", note: "enabled=true and catalyst-ai installed" })
+        }
+        const browser = (config.AI_CONFIG && config.AI_CONFIG.browser) || {}
+        const engine = browser.engine
+        if (engine !== undefined && !["auto", "litert", "foundation-models"].includes(engine)) {
+            issues.push({
+                field: "AI_CONFIG.browser.engine",
+                severity: "error",
+                message: `Unknown engine "${engine}". Use "auto", "litert" (Gemma 4 E2B) or "foundation-models" (Apple, iOS 26+).`,
+            })
+        }
+        if (browser.provider === "foundation-models" && platform === "android") {
+            warnings.push({
+                field: "AI_CONFIG.browser.provider",
+                message:
+                    "foundation-models is iOS-only (iOS 26+, Apple Intelligence devices). Android needs provider 'litert' or 'native'.",
+            })
+        }
+    } else if (
+        config.AI_CONFIG &&
+        config.AI_CONFIG.browser &&
+        /^(native|litert|foundation-models)$/.test(config.AI_CONFIG.browser.provider || "")
+    ) {
+        warnings.push({
+            field: "WEBVIEW_CONFIG.ai.enabled",
+            message: `AI_CONFIG.browser.provider is "${config.AI_CONFIG.browser.provider}" (on-device) but WEBVIEW_CONFIG.ai.enabled is not true — the native AI module is not built into the app.`,
+        })
+    }
+
     return _buildResult({ root, configPath, platform, config, issues, warnings, passed })
 }
 

package/mcp_v2/tools/conversion.js

@@ -92,7 +92,7 @@ function handle_get_conversion_status({ project_path, include_not_applicable = f
                     review_context: {
                         question: "Which catalyst-core version is this project targeting?",
                         what_correct_looks_like:
-                            "0.2.x uses @tata1mg/router; 0.3.x+ removes it and imports Catalyst router APIs from catalyst-core.",
+                            "0.2.x uses @tata1mg/router; 0.3.x removes it and imports router APIs from catalyst-core; 1.0.0+ imports router names from react-router.",
                         what_gap_looks_like:
                             "Router dependencies and imports are mixed across runtime generations.",
                     },
@@ -111,7 +111,7 @@ function handle_get_conversion_status({ project_path, include_not_applicable = f
                     status: "gap",
                     native_risk:
                         "Catalyst 0.3.x owns the router implementation. Keeping @tata1mg/router can install a second routing runtime and produce incompatible React elements.",
-                    reason: "Remove @tata1mg/router and import router APIs from catalyst-core",
+                    reason: "Remove @tata1mg/router and import router APIs from catalyst-core on 0.3.x, or from react-router on 1.0.0+",
                 }
             return { status: "completed", note: "Current 0.3.x integrated router contract detected." }
         },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "catalyst-core",
-    "version": "1.0.0",
+    "version": "1.0.1-canary.2",
     "type": "module",
     "main": "./dist/index.jsx",
     "description": "Web framework that provides great performance out of the box",
@@ -57,7 +57,7 @@
         "test:unit": "node --test \"test/**/*.test.js\"",
         "typecheck": "tsc --noEmit",
         "prettify": "prettier . --write",
-        "prepare": "node ../../scripts/safe-rimraf.js ./dist && node scripts/build-dist.mjs && cp -r ./src/native ./dist/native && babel src/native --out-dir dist/native --config-file ./babel.native.config.cjs --extensions '.js,.jsx,.ts,.tsx' --ignore '**/.build/**' && node scripts/strip-ts-sources.mjs ./dist/native && babel src/sentry.js --out-file dist/sentry.cjs --config-file ./babel.native.config.cjs && tsc -p tsconfig.declarations.json && node ./mcp_v2/scripts/copyErrorsIndex.cjs",
+        "prepare": "node scripts/safe-rimraf.cjs ./dist && node scripts/build-dist.mjs && cp -r ./src/native ./dist/native && babel src/native --out-dir dist/native --config-file ./babel.native.config.cjs --extensions '.js,.jsx,.ts,.tsx' --ignore '**/.build/**' && node scripts/strip-ts-sources.mjs ./dist/native && babel src/sentry.js --out-file dist/sentry.cjs --config-file ./babel.native.config.cjs && tsc -p tsconfig.declarations.json && node ./mcp_v2/scripts/copyErrorsIndex.cjs",
         "prepublishOnly": "npm run prepare",
         "test": "npm run test:types && vitest run",
         "test:watch": "vitest",
@@ -72,9 +72,9 @@
         "@vitejs/plugin-react": "^4.4.1",
         "ansis": "^4.3.1",
         "body-parser": "^1.20.2",
-        "compression": "^1.7.4",
+        "compression": "^1.8.2",
         "cookie-parser": "^1.4.6",
-        "express": "^4.18.2",
+        "express": "^4.22.3",
         "express-static-gzip": "^2.1.7",
         "react": "19.0.0",
         "react-dom": "19.0.0",
@@ -114,7 +114,7 @@
         "@types/node": "^22.20.1",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.5",
-        "@vitest/coverage-v8": "4.1.9",
+        "@vitest/coverage-v8": "4.1.11",
         "eslint": "^8.26.0",
         "eslint-plugin-babel": "^5.3.1",
         "eslint-plugin-react": "^7.34.1",
@@ -126,8 +126,9 @@
         "jsdom": "30.0.1",
         "lint-staged": "^15.2.2",
         "prettier": "^3.2.5",
+        "react-router": "^7.18.2",
         "typescript": "^7.0.2",
-        "vitest": "4.1.9"
+        "vitest": "4.1.11"
     },
     "lint-staged": {
         "*.{js,jsx}": [

package/test/hooks/aiProviders.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest"
+import { resolveMode, resolveNativeEngine } from "../../src/native/bridge/hooks/aiProviders"
+
+describe("useAI provider resolution", () => {
+    it("maps on-device provider names to native mode", () => {
+        for (const provider of ["native", "litert", "foundation-models"]) {
+            expect(resolveMode(provider)).toBe("native")
+        }
+    })
+
+    it("keeps the other modes unchanged", () => {
+        expect(resolveMode("transformers")).toBe("local")
+        expect(resolveMode("openai")).toBe("cloud")
+        expect(resolveMode("gemini")).toBe("cloud")
+        expect(resolveMode(undefined)).toBe("cloud")
+    })
+
+    it("does not treat Object prototype keys as providers", () => {
+        expect(resolveMode("toString")).toBe("cloud")
+        expect(resolveMode("constructor")).toBe("cloud")
+    })
+
+    it("pins the engine from the provider alias", () => {
+        expect(resolveNativeEngine("litert", undefined, undefined)).toBe("litert")
+        expect(resolveNativeEngine("foundation-models", undefined, undefined)).toBe("foundation-models")
+    })
+
+    it("'native' leaves the choice to the platform unless config or an option names an engine", () => {
+        expect(resolveNativeEngine("native", undefined, undefined)).toBeUndefined()
+        expect(resolveNativeEngine("native", undefined, { engine: "foundation-models" })).toBe("foundation-models")
+        expect(resolveNativeEngine("native", "litert", { engine: "foundation-models" })).toBe("litert")
+    })
+})

package/test/hooks/useSafeNavigate.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest"
+import { createElement } from "react"
+import { renderToString } from "react-dom/server"
+import { useSafeNavigate } from "../../src/native/bridge/hooks/useSafeNavigate"
+
+// The node test environment has no `window`, i.e. it is a server render with no Router in scope —
+// exactly the dev-SSR situation where react-router's useNavigate used to throw.
+describe("useSafeNavigate during server rendering", () => {
+    it("renders without a Router and returns a callable navigate", () => {
+        expect(typeof window).toBe("undefined")
+        let navigate: any
+        const Probe = () => {
+            navigate = useSafeNavigate()
+            return createElement("div", null, "ok")
+        }
+
+        expect(renderToString(createElement(Probe))).toContain("ok")
+        expect(typeof navigate).toBe("function")
+        expect(() => navigate("/somewhere")).not.toThrow()
+    })
+})

package/test/native/aiPluginComposition.test.js

@@ -0,0 +1,161 @@
+import test from "node:test"
+import assert from "node:assert/strict"
+import fs from "fs"
+import os from "os"
+import path from "path"
+import { createRequire } from "module"
+import { fileURLToPath } from "url"
+
+// src/native is a CommonJS subtree (see its package.json); load it with require from this ESM test.
+const require = createRequire(import.meta.url)
+const { composeIosPlugins } = require("../../src/native/pluginComposerIos.js")
+const { resolveAIPluginSource, resolveInternalPluginsRoot } = require("../../src/native/internalPluginUtils.js")
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const repoRoot = path.resolve(here, "../../../..")
+const coreRoot = path.resolve(here, "../..")
+const aiPluginsRoot = path.join(repoRoot, "packages", "catalyst-ai", "plugins")
+
+function tempDir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), "catalyst-ai-compose-"))
+}
+
+// A fake app: <project>/node_modules/catalyst-ai/plugins -> the real in-repo plugin directory.
+function fakeAppWithCatalystAI() {
+    const project = tempDir()
+    const pkgDir = path.join(project, "node_modules", "catalyst-ai")
+    fs.mkdirSync(pkgDir, { recursive: true })
+    fs.symlinkSync(aiPluginsRoot, path.join(pkgDir, "plugins"))
+    return project
+}
+
+test("resolveAIPluginSource: nothing happens unless ai.enabled is true", () => {
+    const project = fakeAppWithCatalystAI()
+    for (const config of [{}, { ai: {} }, { ai: { enabled: false } }, undefined]) {
+        assert.deepEqual(resolveAIPluginSource(config, project), { roots: [], toggles: {} })
+    }
+})
+
+test("resolveAIPluginSource: enabled + package present -> plugin root and ai toggle", () => {
+    const project = fakeAppWithCatalystAI()
+    const { roots, toggles } = resolveAIPluginSource({ ai: { enabled: true } }, project)
+    assert.deepEqual(roots, [path.join(project, "node_modules", "catalyst-ai", "plugins")])
+    assert.deepEqual(toggles, { ai: true })
+})
+
+test("resolveAIPluginSource: enabled but catalyst-ai missing -> warns and skips, build continues", () => {
+    const logs = []
+    const result = resolveAIPluginSource({ ai: { enabled: true } }, tempDir(), (message, status) =>
+        logs.push([status, message])
+    )
+    assert.deepEqual(result, { roots: [], toggles: {} })
+    assert.equal(logs.length, 1)
+    assert.equal(logs[0][0], "warning")
+    assert.match(logs[0][1], /catalyst-ai not found/)
+})
+
+test("composeIosPlugins: ai plugin contributes sources, registry entry, LiteRT-LM dependency and entitlement", () => {
+    const iosProjectPath = tempDir()
+    const composition = composeIosPlugins({
+        corePluginsRoot: resolveInternalPluginsRoot(coreRoot),
+        externalPluginRoots: [aiPluginsRoot],
+        iosProjectPath,
+        pluginConfig: { ai: true },
+        log: () => {},
+    })
+
+    assert.equal(composition.pluginCount, 1)
+    assert.deepEqual(
+        composition.iosDependencies.map((d) => ({
+            path: d.url,
+            package: d.package,
+            products: d.products,
+            requirement: d.requirement,
+        })),
+        [
+            {
+                path: path.join(aiPluginsRoot, "ai", "LiteRTLM"),
+                package: "LiteRTLM",
+                products: ["LiteRTLM"],
+                requirement: { type: "path", version: "local" },
+            },
+        ]
+    )
+    assert.deepEqual(composition.entitlements, { "com.apple.developer.kernel.increased-memory-limit": true })
+
+    const index = fs.readFileSync(
+        path.join(iosProjectPath, "Sources", "Core", "Plugins", "GeneratedPluginIndex.swift"),
+        "utf8"
+    )
+    assert.match(index, /"io\.catalyst\.ai": \{ CatalystAIPlugin\(\) \}/)
+    assert.match(index, /"io\.catalyst\.ai": Set\(\["clearConversation", "initAI"\]\)/)
+
+    const copied = path.join(iosProjectPath, "Sources", "Core", "Plugins", "Internal", "io_catalyst_ai")
+    for (const file of [
+        "CatalystAIPlugin.swift",
+        "CatalystAIBridge.swift",
+        "NativeBridgeAI.swift",
+        "FoundationModelsAI.swift",
+        "AIBridge.swift",
+        path.join("Support", "StreamDelta.swift"),
+    ]) {
+        assert.ok(fs.existsSync(path.join(copied, file)), `${file} should be copied into the app`)
+    }
+})
+
+test("composeIosPlugins: ai plugin is NOT composed when the ai toggle is off", () => {
+    const iosProjectPath = tempDir()
+    const composition = composeIosPlugins({
+        corePluginsRoot: resolveInternalPluginsRoot(coreRoot),
+        externalPluginRoots: [aiPluginsRoot],
+        iosProjectPath,
+        pluginConfig: {},
+        log: () => {},
+    })
+    assert.equal(composition.pluginCount, 0)
+    assert.deepEqual(composition.iosDependencies, [])
+    assert.deepEqual(composition.entitlements, {})
+})
+
+test("local-path iOS dependencies: must stay inside the plugin dir and exist", () => {
+    const dir = tempDir()
+    const write = (dependency) => {
+        const pluginDir = fs.mkdtempSync(path.join(dir, "p-"))
+        fs.mkdirSync(path.join(pluginDir, "Local"))
+        fs.mkdirSync(path.join(pluginDir, "ios"))
+        fs.writeFileSync(
+            path.join(pluginDir, "manifest.json"),
+            JSON.stringify({
+                id: "io.test.local",
+                configKey: "local",
+                version: "1.0.0",
+                displayName: "Local",
+                description: "x",
+                category: "test",
+                platforms: ["ios"],
+                commands: ["go"],
+                ios: { className: "LocalPlugin", dependencies: [dependency] },
+            })
+        )
+        return pluginDir
+    }
+    const { parsePluginManifest } = require("../../src/native/internalPluginUtils.js")
+
+    const ok = parsePluginManifest(write({ path: "Local", products: ["Local"] }))
+    assert.equal(ok.ios.dependencies[0].requirement.type, "path")
+    assert.equal(ok.ios.dependencies[0].package, "Local")
+
+    assert.throws(() => parsePluginManifest(write({ path: "../outside", products: ["X"] })), /must stay within the plugin directory/)
+    assert.throws(() => parsePluginManifest(write({ path: "Missing", products: ["X"] })), /does not exist/)
+
+    // A symlink inside the plugin that points outside it must be rejected (lexically it looks contained).
+    const escapeDir = write({ path: "Local", products: ["X"] })
+    const outside = fs.mkdtempSync(path.join(dir, "outside-"))
+    fs.symlinkSync(outside, path.join(escapeDir, "Link"))
+    const manifestPath = path.join(escapeDir, "manifest.json")
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"))
+    manifest.ios.dependencies = [{ path: "Link", products: ["X"] }]
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest))
+    assert.throws(() => parsePluginManifest(escapeDir), /resolves outside the plugin directory/)
+    assert.throws(() => parsePluginManifest(write({ path: "Local", from: "1.0.0", products: ["X"] })), /must not also set/)
+})