catalyst-core 1.0.0 → 1.0.1-canary.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/CustomWebview.kt +1 -1
  2. package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/MainActivity.kt +44 -34
  3. package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/SplashActivity.kt +5 -0
  4. package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/utils/EdgeToEdgeUtils.kt +53 -0
  5. package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/utils/KeyboardUtil.kt +30 -2
  6. package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/utils/SafeAreaUtils.kt +15 -20
  7. package/dist/native/androidProject/app/src/test/java/io/yourname/androidproject/WebCacheManagerTest.kt +26 -0
  8. package/dist/native/androidProject/app/src/test/java/io/yourname/androidproject/utils/EdgeToEdgeUtilsTest.kt +87 -0
  9. package/dist/native/androidProject/app/src/test/java/io/yourname/androidproject/utils/SafeAreaUtilsTest.kt +41 -9
  10. package/dist/native/bridge/hooks/aiProviders.d.ts +5 -0
  11. package/dist/native/bridge/hooks/aiProviders.js +27 -0
  12. package/dist/native/bridge/hooks/useAI.js +9 -8
  13. package/dist/native/bridge/hooks/useNativeTransition.js +2 -2
  14. package/dist/native/bridge/hooks/useSafeNavigate.d.ts +10 -0
  15. package/dist/native/bridge/hooks/useSafeNavigate.js +22 -0
  16. package/dist/native/buildAppIos.js +8 -2
  17. package/dist/native/buildIos/plugins.js +3 -1
  18. package/dist/native/internalPluginUtils.js +78 -0
  19. package/dist/native/iosnativeWebView/CoreLogic/Sources/CatalystCoreLogic/Utils/FrameworkServerUtils+NativeAI.swift +221 -0
  20. package/dist/native/iosnativeWebView/CoreLogic/Sources/CatalystCoreLogic/Utils/FrameworkServerUtils+Requests.swift +215 -0
  21. package/dist/native/iosnativeWebView/CoreLogic/Sources/CatalystCoreLogic/Utils/FrameworkServerUtils.swift +105 -100
  22. package/dist/native/iosnativeWebView/CoreLogic/Sources/CatalystCoreLogic/Utils/NativeAI.swift +76 -0
  23. package/dist/native/iosnativeWebView/CoreLogic/Tests/CatalystCoreLogicTests/FrameworkServerUtilsConnectionHandlerTests.swift +133 -0
  24. package/dist/native/iosnativeWebView/CoreLogic/Tests/CatalystCoreLogicTests/FrameworkServerUtilsLoopbackTests.swift +157 -40
  25. package/dist/native/iosnativeWebView/CoreLogic/Tests/CatalystCoreLogicTests/FrameworkServerUtilsNativeAITests.swift +351 -0
  26. package/dist/native/iosnativeWebView/CoreLogic/Tests/CatalystCoreLogicTests/NetworkMonitorTests.swift +17 -10
  27. package/dist/native/iosnativeWebView/Sources/Core/Plugins/PluginBridge.swift +15 -0
  28. package/dist/native/iosnativeWebView/iosnativeWebViewTests/PluginBridgeTests.swift +23 -0
  29. package/dist/native/pluginComposerIos.js +5 -1
  30. package/dist/otel.js +34 -1
  31. package/dist/server/expressServer.js +1 -0
  32. package/dist/server/renderer/handler.jsx +23 -0
  33. package/dist/vite/vite.config.client.js +1 -1
  34. package/dist/vite/vite.config.js +0 -4
  35. package/dist/web-router/components/MetaTag.jsx +6 -13
  36. package/dist/web-router/components/MetaTag.test.jsx +40 -33
  37. package/mcp_v2/conversion-tasks.json +10 -9
  38. package/mcp_v2/knowledge-base.json +34 -4
  39. package/mcp_v2/test/config.test.ts +52 -0
  40. package/mcp_v2/tools/config.d.ts +18 -0
  41. package/mcp_v2/tools/config.js +40 -0
  42. package/mcp_v2/tools/conversion.js +2 -2
  43. package/package.json +6 -10
  44. package/test/hooks/aiProviders.test.ts +33 -0
  45. package/test/hooks/useSafeNavigate.test.ts +21 -0
  46. package/test/native/aiPluginComposition.test.js +161 -0
  47. package/test/server/handler.test.ts +27 -0
@@ -33,7 +33,7 @@ final class NetworkMonitorTests: XCTestCase {
33
33
  /// Waits for a real NWPath from a fresh, short-lived monitor. Not the
34
34
  /// shared NetworkMonitor singleton — an independent NWPathMonitor so
35
35
  /// this test doesn't depend on NetworkMonitor's internal state/timing.
36
- private func waitForRealPath(timeout: TimeInterval = 5) -> NWPath? {
36
+ private func waitForRealPath(timeout: TimeInterval = 30) -> NWPath? {
37
37
  let monitor = NWPathMonitor()
38
38
  let expectation = self.expectation(description: "NWPathMonitor delivered a path")
39
39
  var capturedPath: NWPath?
@@ -49,10 +49,21 @@ final class NetworkMonitorTests: XCTestCase {
49
49
  return capturedPath
50
50
  }
51
51
 
52
- func testMapPathToStatus_RealPathProducesConsistentIsOnline() throws {
53
- guard let path = waitForRealPath() else {
54
- throw XCTSkip("No NWPath delivered within timeout — cannot exercise mapPathToStatus without a live path")
52
+ /// Returns a live path. The wait ends as soon as one arrives, so the generous
53
+ /// timeout only matters on a starved runner. If none arrives: on CI (`CI` set)
54
+ /// the test fails, since a silent skip would drop NetworkMonitor coverage and
55
+ /// make the coverage baseline non-deterministic; elsewhere it skips.
56
+ private func requireRealPath() throws -> NWPath {
57
+ if let path = waitForRealPath() { return path }
58
+ let message = "No NWPath delivered within timeout — cannot exercise mapPathToStatus without a live path"
59
+ if ProcessInfo.processInfo.environment["CI"] != nil {
60
+ throw NSError(domain: "NetworkMonitorTests", code: 1, userInfo: [NSLocalizedDescriptionKey: message])
55
61
  }
62
+ throw XCTSkip(message)
63
+ }
64
+
65
+ func testMapPathToStatus_RealPathProducesConsistentIsOnline() throws {
66
+ let path = try requireRealPath()
56
67
 
57
68
  let status = NetworkMonitor.mapPathToStatus(path)
58
69
 
@@ -61,9 +72,7 @@ final class NetworkMonitorTests: XCTestCase {
61
72
  }
62
73
 
63
74
  func testMapPathToStatus_RealPathTypeMatchesActualInterface() throws {
64
- guard let path = waitForRealPath() else {
65
- throw XCTSkip("No NWPath delivered within timeout — cannot exercise mapPathToStatus without a live path")
66
- }
75
+ let path = try requireRealPath()
67
76
 
68
77
  let status = NetworkMonitor.mapPathToStatus(path)
69
78
 
@@ -86,9 +95,7 @@ final class NetworkMonitorTests: XCTestCase {
86
95
  }
87
96
 
88
97
  func testMapPathToStatus_IsPureAndDeterministicForSamePath() throws {
89
- guard let path = waitForRealPath() else {
90
- throw XCTSkip("No NWPath delivered within timeout — cannot exercise mapPathToStatus without a live path")
91
- }
98
+ let path = try requireRealPath()
92
99
 
93
100
  let first = NetworkMonitor.mapPathToStatus(path)
94
101
  let second = NetworkMonitor.mapPathToStatus(path)
@@ -56,9 +56,24 @@ final class PluginBridge: NSObject {
56
56
  let proxy = WeakScriptMessageHandler(delegate: self)
57
57
  userContentController.add(proxy, name: bridgeName)
58
58
  messageHandlerProxy = proxy
59
+ userContentController.addUserScript(Self.pluginManifestScript(pluginToCommands))
59
60
  isRegistered = true
60
61
  }
61
62
 
63
+ /// Runs before any page script so JS can feature-detect an optional native plugin synchronously
64
+ /// (WKScriptMessage has no return value): `window.CatalystPlugins["io.catalyst.ai"]` is the plugin's
65
+ /// command list when it was composed into this build, and undefined otherwise.
66
+ static func pluginManifestScript(_ pluginToCommands: [String: Set<String>]) -> WKUserScript {
67
+ let manifest = pluginToCommands.mapValues { $0.sorted() }
68
+ let json = (try? JSONSerialization.data(withJSONObject: manifest, options: [.sortedKeys]))
69
+ .flatMap { String(data: $0, encoding: .utf8) } ?? "{}"
70
+ return WKUserScript(
71
+ source: "window.CatalystPlugins = \(json);",
72
+ injectionTime: .atDocumentStart,
73
+ forMainFrameOnly: true
74
+ )
75
+ }
76
+
62
77
  func unregister() {
63
78
  guard isRegistered else { return }
64
79
  webView?.configuration.userContentController.removeScriptMessageHandler(forName: bridgeName)
@@ -19,6 +19,29 @@ final class PluginBridgeTests: XCTestCase {
19
19
  bridge.register()
20
20
  }
21
21
 
22
+ @MainActor
23
+ func testRegister_InjectsPluginManifestAtDocumentStart() throws {
24
+ let scripts = mockWebView.configuration.userContentController.userScripts
25
+ let manifest = try XCTUnwrap(scripts.first { $0.source.hasPrefix("window.CatalystPlugins = ") })
26
+ XCTAssertEqual(manifest.injectionTime, .atDocumentStart)
27
+ XCTAssertTrue(manifest.isForMainFrameOnly)
28
+ }
29
+
30
+ func testPluginManifestScript_ListsPluginsWithSortedCommands() {
31
+ let script = PluginBridge.pluginManifestScript([
32
+ "io.catalyst.ai": ["initAI", "clearConversation"],
33
+ "io.catalyst.device_info": ["getDeviceInfo"],
34
+ ])
35
+ XCTAssertEqual(
36
+ script.source,
37
+ #"window.CatalystPlugins = {"io.catalyst.ai":["clearConversation","initAI"],"io.catalyst.device_info":["getDeviceInfo"]};"#
38
+ )
39
+ }
40
+
41
+ func testPluginManifestScript_NoPlugins_DefinesEmptyObject() {
42
+ XCTAssertEqual(PluginBridge.pluginManifestScript([:]).source, "window.CatalystPlugins = {};")
43
+ }
44
+
22
45
  @MainActor
23
46
  override func tearDown() {
24
47
  bridge.unregister()
@@ -406,11 +406,15 @@ enum GeneratedPluginIndex {
406
406
  }
407
407
  function composeIosPlugins({
408
408
  corePluginsRoot,
409
+ externalPluginRoots = [],
409
410
  iosProjectPath,
410
411
  pluginConfig,
411
412
  log
412
413
  }) {
413
- const discovered = discoverInternalPlugins(corePluginsRoot, log);
414
+ // externalPluginRoots: plugin directories shipped by npm packages (e.g. catalyst-ai's
415
+ // plugins/ai), same manifest format as the internal plugins. They flow through the same
416
+ // validation/toggle/dependency/entitlement path, so a clash with an internal plugin id fails loudly.
417
+ const discovered = [...discoverInternalPlugins(corePluginsRoot, log), ...externalPluginRoots.flatMap(root => discoverInternalPlugins(root, log))];
414
418
  validatePlugins(discovered);
415
419
  const enabled = selectPluginsByConfig(discovered, pluginConfig, log);
416
420
  const selected = selectPluginsForPlatform(enabled, "ios", log);
package/dist/otel.js CHANGED
@@ -294,6 +294,33 @@ export function withObservability(serviceName, fn, name) {
294
294
  }
295
295
  }
296
296
 
297
+ /**
298
+ * Creates a recorder for out-of-band response stream errors.
299
+ *
300
+ * Stream errors (e.g. Node's ERR_STREAM_WRITE_AFTER_END) surface on the
301
+ * response object's "error" event, typically after the span that performed
302
+ * the offending write has already ended, so recording the exception on the
303
+ * active span at error time would be silently dropped. Instead, capture the
304
+ * ambient context while the request span is still active and emit a dedicated
305
+ * error span into the same trace for each stream error (the same parenting
306
+ * approach responseFlushMiddleware uses for its post-end spans).
307
+ *
308
+ * @param {string} serviceName - The name of the service
309
+ * @param {string} name - Span name (optional)
310
+ * @returns {Function} (error) => void, safe to call after the request span ended
311
+ */
312
+ export function createStreamErrorRecorder(serviceName, name = "responseStreamError") {
313
+ const tracer = trace.getTracer(serviceName)
314
+ const parentContext = context.active()
315
+ return function recordStreamError(error) {
316
+ const span = tracer.startSpan(name, undefined, parentContext)
317
+ if (error && error.code) span.setAttribute("error.type", String(error.code))
318
+ span.recordException(error)
319
+ span.setStatus({ code: 2, message: error && error.message ? error.message : String(error) })
320
+ span.end()
321
+ }
322
+ }
323
+
297
324
  /**
298
325
  * Express middleware that emits two spans describing what happens to the
299
326
  * response body AFTER the app calls res.end() — the work that lives past the
@@ -398,4 +425,10 @@ export function responseFlushMiddleware(
398
425
  }
399
426
  }
400
427
 
401
- export default { init, withObservability, withSyncObservability, responseFlushMiddleware }
428
+ export default {
429
+ init,
430
+ withObservability,
431
+ withSyncObservability,
432
+ responseFlushMiddleware,
433
+ createStreamErrorRecorder,
434
+ }
@@ -127,6 +127,7 @@ function serveBuildFile(app, buildPath, urlPath, fileName, headers = {}) {
127
127
  const filePath = path.join(buildPath, fileName);
128
128
  if (!fs.existsSync(filePath)) return next();
129
129
  res.set(headers);
130
+ // nosemgrep: javascript.express.security.audit.express-res-sendfile.express-res-sendfile - filePath is buildPath joined with a hardcoded literal fileName (see serveBuildFile call sites), never request-derived.
130
131
  res.sendFile(filePath);
131
132
  });
132
133
  }
@@ -102,6 +102,7 @@ try {
102
102
  // Passthrough no-ops used when OTEL_ENABLE is not set; replaced below if enabled.
103
103
  let withObservability = (_service, fn) => fn;
104
104
  let withSyncObservability = (_service, fn) => fn;
105
+ let createStreamErrorRecorder = null;
105
106
 
106
107
  // config.json booleans survive the process.env swap in loadEnvironmentVariables(),
107
108
  // so this is genuinely true at runtime when config sets OTEL_ENABLE: true. The cast
@@ -111,6 +112,7 @@ if (process.env.OTEL_ENABLE === true) {
111
112
  const otel = await import("../../otel.js");
112
113
  withObservability = otel.withObservability;
113
114
  withSyncObservability = otel.withSyncObservability;
115
+ createStreamErrorRecorder = otel.createStreamErrorRecorder;
114
116
  } catch {
115
117
  // otel packages not installed — continue without tracing
116
118
  }
@@ -166,6 +168,26 @@ const getComponent = (store, context, req, fetcherData, isBot) => <div id="app">
166
168
  </div>;
167
169
 
168
170
  // ── Render and stream ──────────────────────────────────────────────────
171
+ // Responses that already have a stream-error listener attached. Guarded via
172
+ // WeakSet because renderMarkUp can run twice for one response (the fetcher
173
+ // error path re-renders with a 404) and "error" listeners must not stack.
174
+ const _observedResponses = new WeakSet();
175
+
176
+ // Node swallows response stream errors (e.g. ERR_STREAM_WRITE_AFTER_END) when
177
+ // res has no "error" listener: the write is dropped, nothing is logged, and a
178
+ // truncated document ships silently. Log every stream error through
179
+ // logSSRError (RUNTIME-WEB-001, like every other SSR failure) and, when tracing
180
+ // is enabled, record it as an error span in the request's trace. Must be
181
+ // called while the request span is still active so the span parents correctly.
182
+ const observeResponseStreamErrors = res => {
183
+ if (_observedResponses.has(res)) return;
184
+ _observedResponses.add(res);
185
+ const recordStreamError = createStreamErrorRecorder ? createStreamErrorRecorder(SSR_SERVICE) : null;
186
+ res.on("error", error => {
187
+ logSSRError("RENDER", error);
188
+ if (recordStreamError) recordStreamError(error);
189
+ });
190
+ };
169
191
  const _renderMarkUp = async (errorCode, req, res, metaTags, fetcherData, store, allMatches, context, chunkExtractor) => {
170
192
  const deviceDetails = getUserAgentDetails(req.headers["user-agent"] || "");
171
193
  // Match mweb's wider definition: synthetic monitors (StatusCake) and AI crawlers
@@ -247,6 +269,7 @@ const _renderMarkUp = async (errorCode, req, res, metaTags, fetcherData, store,
247
269
  "content-type": "text/html; charset=utf-8"
248
270
  });
249
271
  res.status(status);
272
+ observeResponseStreamErrors(res);
250
273
  return new Promise((resolve, reject) => {
251
274
  // Single completion path: React's pipe() auto-ends `tail`, and
252
275
  // `flush()` appends the deferred asset tags before that end
@@ -74,7 +74,7 @@ const createClientConfig = async () => {
74
74
  return undefined
75
75
  }
76
76
  if (
77
- /[\\/]node_modules[\\/](react|react-dom|scheduler|react-fast-compare|react-side-effect|react-helmet-async)[\\/]/.test(
77
+ /[\\/]node_modules[\\/](react|react-dom|scheduler)[\\/]/.test(
78
78
  id
79
79
  )
80
80
  ) {
@@ -266,9 +266,7 @@ const browserOptimizeDeps = [
266
266
  "redux",
267
267
  "redux-thunk",
268
268
  "axios",
269
- "react-helmet-async",
270
269
  "react-google-recaptcha",
271
- "react-fast-compare",
272
270
  "history",
273
271
  "lottie-web",
274
272
  // Pre-bundle alongside React so esbuild marks react/react-router as external
@@ -295,7 +293,6 @@ const browserOptimizeDeps = [
295
293
  // first navigation that pulls them in doesn't trigger a full-page reload.
296
294
  "react-loadable-visibility",
297
295
  "react-detect-offline",
298
- "react-side-effect",
299
296
  "react-async-script",
300
297
  "normalize.css",
301
298
  ]
@@ -357,7 +354,6 @@ export const sharedViteConfig = {
357
354
  optimizeDeps: {
358
355
  include: [
359
356
  "invariant",
360
- "react-fast-compare",
361
357
  "shallowequal",
362
358
  "prop-types",
363
359
  "redux-thunk",
@@ -1,8 +1,7 @@
1
1
  import React, { useContext, useState, useEffect } from "react";
2
- import { HelmetProvider, Helmet } from "react-helmet-async";
3
2
  import { OneMgRouterContext } from "../context.jsx";
4
3
  import { useRouterData } from "./RouterDataProvider.jsx";
5
- import { deleteHeadTagsByDataAttribute, getMetaData } from "../utils/metaDataUtils.jsx";
4
+ import { getMetaData } from "../utils/metaDataUtils.jsx";
6
5
  import { useLocation } from "react-router";
7
6
 
8
7
  /**
@@ -14,19 +13,13 @@ export const MetaTag = () => {
14
13
  } = useContext(OneMgRouterContext);
15
14
  const routeData = useRouterData();
16
15
  const location = useLocation();
17
- const [metaTags, setMetaTags] = useState([<meta key={0}></meta>]);
16
+ const [metaTags, setMetaTags] = useState([]);
18
17
  useEffect(() => {
19
18
  const mergedMetaTags = getMetaData(matchedRoutes, routeData);
20
- if (Array.isArray(mergedMetaTags) && mergedMetaTags.length > 0) {
21
- setMetaTags(mergedMetaTags);
22
- }
23
- return () => deleteHeadTagsByDataAttribute("catalyst");
19
+ setMetaTags(Array.isArray(mergedMetaTags) ? mergedMetaTags : []);
24
20
  // eslint-disable-next-line react-hooks/exhaustive-deps
25
21
  }, [location]);
26
- if (Array.isArray(metaTags) && metaTags.length >= 0) {
27
- return <HelmetProvider>
28
- <Helmet>{metaTags}</Helmet>
29
- </HelmetProvider>;
30
- }
31
- return <></>;
22
+
23
+ // React 19 hoists document metadata rendered by components into <head>.
24
+ return <>{metaTags}</>;
32
25
  };
@@ -1,7 +1,7 @@
1
1
  import React from "react"
2
- import { describe, expect, it, vi, afterEach } from "vitest"
2
+ import { describe, expect, it, vi } from "vitest"
3
3
  import { render, waitFor, act } from "@testing-library/react"
4
- import { MemoryRouter, Routes, Route, useNavigate } from "react-router"
4
+ import { MemoryRouter, Routes, Route, useLocation, useNavigate } from "react-router"
5
5
  import { MetaTag } from "./MetaTag.jsx"
6
6
  import { OneMgRouterContext } from "../context.jsx"
7
7
  import { RouterContext } from "./RouterDataProvider.jsx"
@@ -26,10 +26,6 @@ function renderMetaTag({ matchedRoutes = [], routerData = {} } = {}) {
26
26
  }
27
27
 
28
28
  describe("MetaTag", () => {
29
- afterEach(() => {
30
- document.head.innerHTML = ""
31
- })
32
-
33
29
  it("renders without crashing when there are no matched routes", () => {
34
30
  expect(() => renderMetaTag()).not.toThrow()
35
31
  })
@@ -48,53 +44,64 @@ describe("MetaTag", () => {
48
44
  await waitFor(() => {
49
45
  expect(document.head.querySelector('meta[name="description"]')).not.toBeNull()
50
46
  })
51
- expect(document.head.querySelector('meta[name="description"]').getAttribute("content")).toBe(
52
- "hello"
53
- )
47
+ expect(document.head.querySelector('meta[name="description"]').getAttribute("content")).toBe("hello")
54
48
  })
55
49
 
56
- it("keeps the placeholder meta tag when no route provides setMetaData", () => {
50
+ it("renders no metadata when no route provides setMetaData", () => {
57
51
  renderMetaTag({ matchedRoutes: [{ route: { component: {} } }] })
58
- // Component should still render (Helmet/HelmetProvider tree),
59
- // even with the single empty placeholder <meta> from useState.
60
- expect(document.querySelector("head")).not.toBeNull()
52
+ expect(document.head.querySelector("[data-catalyst]")).toBeNull()
61
53
  })
62
54
 
63
- it("re-runs setMetaData and clears previous tags when the location changes", async () => {
64
- // A rerender() with a NEW <MemoryRouter initialEntries> does not
65
- // navigate an already-mounted router -- initialEntries is only
66
- // read on first mount. Confirmed directly: that approach left
67
- // setMetaData called once even after "changing" the path.
68
- // Navigating within one mounted router (via a real useNavigate
69
- // call, triggered here through a button) is what actually
70
- // changes useLocation() and re-fires MetaTag's effect.
71
- const setMetaData = vi.fn(() => [<meta key="d" name="description" content="v1" />])
72
- const matchedRoutes = [{ route: { component: { setMetaData } } }]
55
+ it("clears previous metadata when navigating to a route without setMetaData", async () => {
56
+ const routeWithMetadata = [
57
+ {
58
+ route: {
59
+ component: {
60
+ setMetaData: () => [<meta key="d" name="description" content="with metadata" />],
61
+ },
62
+ },
63
+ },
64
+ ]
65
+
66
+ function RouteMetadata() {
67
+ const location = useLocation()
68
+ const matchedRoutes = location.pathname === "/with-metadata" ? routeWithMetadata : []
69
+
70
+ return (
71
+ <OneMgRouterContext.Provider value={{ matchedRoutes }}>
72
+ <RouterContext.Provider value={{}}>
73
+ <MetaTag />
74
+ </RouterContext.Provider>
75
+ </OneMgRouterContext.Provider>
76
+ )
77
+ }
73
78
 
74
79
  function NavButton() {
75
80
  const navigate = useNavigate()
76
81
  return (
77
- <button type="button" onClick={() => navigate("/b")}>
82
+ <button type="button" onClick={() => navigate("/without-metadata")}>
78
83
  go
79
84
  </button>
80
85
  )
81
86
  }
82
87
 
83
88
  render(
84
- <MemoryRouter initialEntries={["/a"]}>
85
- <OneMgRouterContext.Provider value={{ matchedRoutes }}>
86
- <RouterContext.Provider value={{}}>
87
- <NavButton />
88
- <MetaTag />
89
- </RouterContext.Provider>
90
- </OneMgRouterContext.Provider>
89
+ <MemoryRouter initialEntries={["/with-metadata"]}>
90
+ <NavButton />
91
+ <RouteMetadata />
91
92
  </MemoryRouter>
92
93
  )
93
- await waitFor(() => expect(setMetaData).toHaveBeenCalledTimes(1))
94
+
95
+ await waitFor(() => {
96
+ expect(document.head.querySelector('meta[name="description"]')).not.toBeNull()
97
+ })
94
98
 
95
99
  await act(async () => {
96
100
  document.querySelector("button").click()
97
101
  })
98
- await waitFor(() => expect(setMetaData).toHaveBeenCalledTimes(2))
102
+
103
+ await waitFor(() => {
104
+ expect(document.head.querySelector('meta[name="description"]')).toBeNull()
105
+ })
99
106
  })
100
107
  })
@@ -10,7 +10,7 @@
10
10
  "field: WEBVIEW_CONFIG must be present",
11
11
  "field: API_URL must be present"
12
12
  ],
13
- "fix_guide": "Create config/config.json with: { NODE_SERVER_PORT: 3000, API_URL: 'https://api.example.com', CLIENT_ENV_KEYS: [], PUBLIC_STATIC_ASSET_URL: '', WEBVIEW_CONFIG: { port: 3000, accessControl: { enabled: true, allowedUrls: [] } } }",
13
+ "fix_guide": "Create config/config.json with: { NODE_SERVER_HOSTNAME: 'localhost', NODE_SERVER_PORT: 3005, BUILD_OUTPUT_PATH: 'build', PUBLIC_STATIC_ASSET_PATH: '/assets/', PUBLIC_STATIC_ASSET_URL: 'http://localhost:3005', API_URL: 'https://api.example.com', CLIENT_ENV_VARIABLES: ['API_URL'], WEBVIEW_CONFIG: { port: 3005, accessControl: { enabled: true, allowedUrls: [] } } }. From 1.0.0, catalyst start/build/serve exit before starting when NODE_SERVER_HOSTNAME, NODE_SERVER_PORT, BUILD_OUTPUT_PATH, PUBLIC_STATIC_ASSET_PATH, PUBLIC_STATIC_ASSET_URL or CLIENT_ENV_VARIABLES is missing. Before 1.0.0, also include WEBPACK_DEV_SERVER_HOSTNAME, WEBPACK_DEV_SERVER_PORT and ANALYZE_BUNDLE. On 1.0.0+ they are no longer read and can be removed.",
14
14
  "verify_hint": "Run `npm run start` on Catalyst 0.3.x, or `npm run devServe` on legacy 0.2.x. The server should start without config errors.",
15
15
  "depends_on": []
16
16
  },
@@ -21,9 +21,10 @@
21
21
  "detect_pattern": "package_json_dep",
22
22
  "how_to_check": [
23
23
  "Catalyst 0.2.x: package.json includes @tata1mg/router and Catalyst router APIs import from it",
24
- "Catalyst 0.3.x+: package.json does not include @tata1mg/router and Catalyst router APIs import from catalyst-core"
24
+ "Catalyst 0.3.x: package.json does not include @tata1mg/router and router APIs import from catalyst-core",
25
+ "Catalyst 1.0.0+: package.json does not include @tata1mg/router, includes react-router ^7.18.2, and router names import from react-router"
25
26
  ],
26
- "fix_guide": "Version-specific: for Catalyst 0.2.x install @tata1mg/router and import RouterDataProvider, Outlet, navigation, and data hooks from it. For Catalyst 0.3.x+, remove @tata1mg/router and import those APIs from catalyst-core. Never mix the two router generations.",
27
+ "fix_guide": "Version-specific: for Catalyst 0.2.x install @tata1mg/router and import RouterDataProvider, Outlet, navigation, and data hooks from it. For Catalyst 0.3.x, remove @tata1mg/router and import those APIs from catalyst-core. For Catalyst 1.0.0+, remove @tata1mg/router, add react-router ^7.18.2, import RouterDataProvider, MetaTag and useCurrentRouteData from catalyst-core, and import Outlet, Link, navigation hooks and every other router name from react-router. Never mix router generations.",
27
28
  "verify_hint": "Run the development command for the installed generation. Confirm there are no unresolved router imports, duplicate React-element errors, or blank route outlets.",
28
29
  "depends_on": ["T1_CONFIG"]
29
30
  },
@@ -68,7 +69,7 @@
68
69
  "signal: files with .serverFetcher = or .clientFetcher = (converted pages)",
69
70
  "llm judges: is any useEffect+fetch file a page component that needs conversion?"
70
71
  ],
71
- "fix_guide": "For each page component: remove initial useEffect data loading, attach serverFetcher/clientFetcher statics, and read route data with useCurrentRouteData(). Import the hook from @tata1mg/router on 0.2.x or catalyst-core on 0.3.x+.",
72
+ "fix_guide": "For each page component: remove initial useEffect data loading, attach serverFetcher/clientFetcher statics, and read route data with useCurrentRouteData(). Import the hook from @tata1mg/router on 0.2.x or catalyst-core on 0.3.x and 1.0.0+.",
72
73
  "verify_hint": "Open a migrated page in browser. Open DevTools Network tab — on first load there should be NO XHR/fetch calls for page data (data arrives server-rendered in HTML). View Page Source and confirm the page content (not just a loading skeleton) is present in the raw HTML. If content is missing from source, serverFetcher is not attached or not running.",
73
74
  "depends_on": ["T3_ROUTES_FILE"]
74
75
  },
@@ -81,7 +82,7 @@
81
82
  "file: src/js/routes/utils.js must exist",
82
83
  "pattern: RouterDataProvider must be imported and used in utils.js"
83
84
  ],
84
- "fix_guide": "Create src/js/routes/utils.js using the CCA preparedRoutes pattern. Import RouterDataProvider and MetaTag from @tata1mg/router on 0.2.x or catalyst-core on 0.3.x+. Wrap App and pass routerInitialState plus fetcherArgs when a store is used.",
85
+ "fix_guide": "Create src/js/routes/utils.js using the CCA preparedRoutes pattern. Import RouterDataProvider and MetaTag from @tata1mg/router on 0.2.x or catalyst-core on 0.3.x and 1.0.0+. Wrap App and pass routerInitialState plus fetcherArgs when a store is used.",
85
86
  "verify_hint": "In a page component that uses useCurrentRouteData(), console.log the return value. It should be the data object returned by serverFetcher — not undefined. If undefined, RouterDataProvider is not wrapping the tree or the route entry is missing the component reference.",
86
87
  "depends_on": ["T3_ROUTES_FILE"]
87
88
  },
@@ -92,10 +93,10 @@
92
93
  "detect_pattern": "file_exists + code_pattern",
93
94
  "how_to_check": [
94
95
  "file: src/js/containers/App/index.js must exist",
95
- "pattern: Outlet comes from @tata1mg/router on 0.2.x or catalyst-core on 0.3.x+",
96
+ "pattern: Outlet comes from @tata1mg/router on 0.2.x, catalyst-core on 0.3.x, or react-router on 1.0.0+",
96
97
  "pattern: <Outlet /> must be rendered in the component"
97
98
  ],
98
- "fix_guide": "Render <Outlet /> where route content belongs. Import it from @tata1mg/router on Catalyst 0.2.x or catalyst-core on 0.3.x+. Keep global layout around the outlet.",
99
+ "fix_guide": "Render <Outlet /> where route content belongs. Import it from @tata1mg/router on Catalyst 0.2.x, catalyst-core on 0.3.x, or react-router on 1.0.0+ (catalyst-core no longer re-exports it). Keep global layout around the outlet.",
99
100
  "verify_hint": "Open the app in browser. Global layout (header, footer, nav) should appear on every page. The area where page content changes should not be blank. If page content area is empty, <Outlet /> is missing or placed incorrectly in the App shell.",
100
101
  "depends_on": ["T5_ROUTER_DATA_PROVIDER"]
101
102
  },
@@ -125,10 +126,10 @@
125
126
  "pattern: client/index.js must call WebBridge.init()",
126
127
  "pattern: client/index.js must use hydrateRoot from 'react-dom/client' (not ReactDOM.render or hydrate)",
127
128
  "pattern: client/index.js must import clientRouter from 'catalyst-core/router/ClientRouter'",
128
- "pattern: RouterProvider comes from @tata1mg/router on 0.2.x or catalyst-core on 0.3.x+",
129
+ "pattern: RouterProvider comes from @tata1mg/router on 0.2.x, catalyst-core on 0.3.x, or react-router/dom on 1.0.0+",
129
130
  "pattern: 0.2.x waits for loadableReady; 0.3.x+ waits for hydrationReady"
130
131
  ],
131
- "fix_guide": "Use hydrateRoot and initialize WebBridge before hydration. On 0.2.x, import RouterProvider from @tata1mg/router and wait for loadableReady from @loadable/component. On 0.3.x+, import RouterProvider and hydrationReady from catalyst-core, then call hydrationReady().then(() => hydrateRoot(...)). Do not retain @loadable/component in the Vite runtime.",
132
+ "fix_guide": "Use hydrateRoot and initialize WebBridge before hydration. On 0.2.x, import RouterProvider from @tata1mg/router and wait for loadableReady from @loadable/component. On 0.3.x, import RouterProvider and hydrationReady from catalyst-core. On 1.0.0+, import hydrationReady from catalyst-core and RouterProvider from react-router/dom (not react-router: only the /dom export passes flushSync to the router). Then call hydrationReady().then(() => hydrateRoot(...)). Do not retain @loadable/component in the Vite runtime.",
132
133
  "verify_hint": "Open the app in browser. Open DevTools Console — there should be no 'hydrateRoot' mismatch warnings (if there are, server HTML and client render differ). Open DevTools Elements — the #app or #root div should have React content inside it (not empty). Click an interactive element — if nothing responds, hydration failed. Also confirm global styles are applied (CSS loads).",
133
134
  "depends_on": ["T6_APP_SHELL"]
134
135
  },
@@ -697,7 +697,7 @@
697
697
  {
698
698
  "section": "native_hooks",
699
699
  "title": "useSafeArea \u2014 return shape",
700
- "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).",
700
+ "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).",
701
701
  "layer": "Runtime",
702
702
  "source": "static",
703
703
  "tags": ["native-hooks", "useSafeArea", "return-shape", "web-fallback"]
@@ -1303,7 +1303,7 @@
1303
1303
  {
1304
1304
  "section": "routing",
1305
1305
  "title": "Catalyst 0.3.x Integrated Router",
1306
- "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.",
1306
+ "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.",
1307
1307
  "layer": "Runtime",
1308
1308
  "source": "static",
1309
1309
  "tags": [
@@ -1377,7 +1377,7 @@
1377
1377
  {
1378
1378
  "section": "version_migration",
1379
1379
  "title": "Upgrading catalyst-core 0.3.x to 1.0.0",
1380
- "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.",
1380
+ "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.",
1381
1381
  "layer": "Framework",
1382
1382
  "source": "static",
1383
1383
  "tags": [
@@ -1393,7 +1393,13 @@
1393
1393
  "react-router",
1394
1394
  "peer-dependency",
1395
1395
  "peerDependency",
1396
- "node"
1396
+ "node",
1397
+ "react-router-dom",
1398
+ "preflight",
1399
+ "module-aliases",
1400
+ "stable",
1401
+ "latest",
1402
+ "0.3.0-beta.5"
1397
1403
  ],
1398
1404
  "github_files": ["docs/content/12-Migration/02-Version-Upgrades.md"]
1399
1405
  },
@@ -1427,5 +1433,29 @@
1427
1433
  "packages/catalyst-core/src/errors/index.js",
1428
1434
  "packages/catalyst-core/src/native/bridge/errors.ts"
1429
1435
  ]
1436
+ },
1437
+ {
1438
+ "section": "native_hooks",
1439
+ "title": "On-Device AI (catalyst-ai) — Setup & Engines",
1440
+ "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.",
1441
+ "layer": "Runtime",
1442
+ "source": "static",
1443
+ "tags": "ai,catalyst-ai,native ai,on-device,gemma,gemma 4,e2b,litert,litert-lm,foundation models,apple intelligence,useAI,useNativeAI"
1444
+ },
1445
+ {
1446
+ "section": "native_hooks",
1447
+ "title": "On-Device AI — Choosing Gemma 4 E2B or Apple Foundation Models",
1448
+ "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.",
1449
+ "layer": "Runtime",
1450
+ "source": "static",
1451
+ "tags": "ai,catalyst-ai,native ai,on-device,gemma,gemma 4,e2b,litert,litert-lm,foundation models,apple intelligence,useAI,useNativeAI"
1452
+ },
1453
+ {
1454
+ "section": "bridge_architecture",
1455
+ "title": "On-Device AI — Architecture & Security",
1456
+ "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.",
1457
+ "layer": "Bridge",
1458
+ "source": "static",
1459
+ "tags": "ai,catalyst-ai,native ai,on-device,gemma,gemma 4,e2b,litert,litert-lm,foundation models,apple intelligence,useAI,useNativeAI"
1430
1460
  }
1431
1461
  ]