catalyst-core 1.0.2-canary.2 → 1.0.2

package/changelog.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [1.0.2] - unreleased
+
+This release adds two opt-in features, an animated HTML splash screen for universal apps and experimental WebMCP support, and gives every CLI command the same terminal output. There are no breaking API changes.
+
+### HTML splash screen
+
+A universal app can ship `public/splashscreen.html`. When `WEBVIEW_CONFIG.splashScreen` is set, the native splash image hands over to that page, which stays up until the app's first page has loaded. The new optional `splashScreen.minDuration` keeps it on screen for at least that many milliseconds, and it is dismissed after 10 seconds regardless. The file must be self-contained, and on Android it cannot make network requests. Without the file, the splash works as before.
+
+### WebMCP (experimental)
+
+The new `catalyst-core/webmcp` subpath lets an app expose its actions to AI agents running in the browser. `useTool()` registers a tool from a component, a `tool` field on a route derives one from the route, and `WebMcpProvider` adds the built-in `navigate`, `get_current_route` and `get_page_info` tools. `catalyst-core/webmcp/shim` installs an opt-in `document.modelContext` shim. The API may change in a minor release.
+
+### New root export
+
+The root entry of `catalyst-core` adds `useRouterState`, which returns `{ location, params, navigate, matchedRoutes }` through Catalyst's router context. `catalyst-core/webmcp` uses it to read router state without importing `react-router` from a subpath. The root entry now exports nine names; nothing was removed.
+
+### CLI output
+
+`catalyst start`, `build`, `serve`, the native build and setup commands, and `create-catalyst-app` now print a short header, one line per step with its timing, and one diagnostic block on failure with the error code, location, hint and docs link. The full bundler and native build output moved behind `--verbose`, and `--debug` adds stacks and the environment. `catalyst --help`, `--version` and a "did you mean" suggestion for mistyped commands are new. Once `catalyst serve` has started the production server, the app's own output passes through unchanged.
+
+### Fixes
+
+- `catalyst serve` refuses to serve a build whose inlined values (`PUBLIC_STATIC_ASSET_URL`, `PUBLIC_STATIC_ASSET_PATH`, `CLIENT_ENV_VARIABLES`) differ from the current `config/config.json`, with `PREFLIGHT-022`. It also reports a missing build or a taken port before starting.
+- Fast Refresh now works for components written as JSX in `.js` files instead of reloading the page.
+- `MetaTag` no longer depends on `react-helmet-async`, which is removed from the dependencies. Route metadata from `setMetaData` renders through React 19's `<head>` support, and server-rendered head tags no longer outlive their page after client navigation.
+- `catalyst-core` no longer imports `prop-types` at runtime without declaring it.
+- `Otel.init()` no longer throws `ReferenceError: logger is not defined` when the app has not called `configureLogger()`. It logs to `console` until a global logger is set.
+- Signing passwords are redacted from the output of a failed signed build or `keytool` run.
+- File logs written by `configureLogger()` keep structured fields for plain objects again.
+
+### create-catalyst-app
+
+New apps declare `"type": "module"`, and the Tailwind template's config is `postcss.config.cjs`. `catalyst-core` loads either `postcss.config.cjs` or `postcss.config.js`, so existing apps need no change. `create-catalyst-app` declares `node >= 20.12.0` and runs across that range.
+
 ## [1.0.0] - 2026-09-29
 
 This release freezes the public API. The root entry of `catalyst-core` now exports exactly eight names and nothing else: `RouterDataProvider`, `useCurrentRouteData`, `useRouterData`, `MetaTag`, `split`, `hydrationReady`, `Head`, and `Body`. Anything previously reachable through the root entry but not in that list is no longer public. Applications that import a removed name will fail at build time rather than silently resolving to `undefined`.

package/dist/cli/appConfig.js

@@ -18,6 +18,7 @@ const { diagnostic } = require("./diagnostic.js")
  * @param {string} [cwd] - app root; defaults to the current working directory
  */
 function loadAppConfig(cwd = process.cwd()) {
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - cwd is the local project directory; the file name is a fixed literal.
     const configPath = path.join(cwd, "config", "config.json")
 
     let raw

package/dist/native/buildIos/build.js

@@ -4,7 +4,8 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const {
-  execSync
+  execSync,
+  execFileSync
 } = require("child_process");
 const {
   runInteractiveCommand
@@ -222,7 +223,9 @@ module.exports = function createBuildPhase(ctx) {
       // The app root, not process.cwd(): the iOS build chdirs into the
       // Xcode project inside node_modules, so the artifact landed there
       // and was wiped by the next npm install.
-      const destinationDir = path.join(ctx.appRoot || process.cwd(), BUILD_OUTPUT_PATH,
+      const destinationDir = path.join(
+      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - appRoot is the local project root from the CLI context.
+      ctx.appRoot || process.cwd(), BUILD_OUTPUT_PATH,
       // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - BUILD_OUTPUT_PATH is trusted application config.
       "native", "ios", currentDate, buildType // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - buildType is "debug" or "release" from config.
       );
@@ -249,9 +252,10 @@ module.exports = function createBuildPhase(ctx) {
     progress.status("waiting for install");
     for (let i = 0; i < 30; i++) {
       try {
-        execSync(`xcrun simctl get_app_container booted "${APP_BUNDLE_ID}"`, {
+        // No shell: the bundle id is passed as an argv entry, never interpolated.
+        execFileSync("xcrun", ["simctl", "get_app_container", "booted", APP_BUNDLE_ID], {
           stdio: ["ignore", "pipe", "ignore"]
-        }); // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - APP_BUNDLE_ID is generated from trusted native config.
+        });
         break;
       } catch (error) {
         if (i === 29) throw new Error("Timeout: App installation took too long.");
@@ -272,9 +276,9 @@ module.exports = function createBuildPhase(ctx) {
     progress.status("waiting for launch");
     for (let i = 0; i < 10; i++) {
       try {
-        const launchResult = execSync(`xcrun simctl launch booted "${APP_BUNDLE_ID}"`, {
+        const launchResult = execFileSync("xcrun", ["simctl", "launch", "booted", APP_BUNDLE_ID], {
           stdio: ["ignore", "pipe", "ignore"]
-        }).toString(); // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+        }).toString();
         if (launchResult.includes("already launched")) {
           break;
         }

package/dist/native/utils.js

@@ -87,11 +87,11 @@ function runCommand(command, {
   // Redacted before it reaches the log file too -- the log is a build
   // artifact that gets attached to bug reports and uploaded by CI.
   try {
-    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - Native setup/build uses fixed internal command strings; preserve existing shell behavior.
     // stderr is captured, not inherited. Many tools (java -version, for
     // one) write to stderr on success, and an inherited fd puts that text
     // at column 0 -- straight through whatever the spinner is drawing.
     // The caller decides what, if anything, is worth showing.
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - Native setup/build uses fixed internal command strings; preserve existing shell behavior.
     return (0, _child_process.execSync)(command, {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
@@ -187,8 +187,11 @@ async function promptUser(question, {
  */
 function detectAndroidSdk(env = process.env) {
   const home = _os.default.homedir();
-  const candidates = [env.ANDROID_HOME, env.ANDROID_SDK_ROOT, _path.default.join(home, "Library", "Android", "sdk"), _path.default.join(home, "Android", "Sdk"), env.LOCALAPPDATA && _path.default.join(env.LOCALAPPDATA, "Android", "Sdk")].filter(Boolean);
+  const candidates = [env.ANDROID_HOME, env.ANDROID_SDK_ROOT, _path.default.join(home, "Library", "Android", "sdk"), _path.default.join(home, "Android", "Sdk"),
+  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - Paths come from env vars, the user's own SDK location or the project dir, never remote input.
+  env.LOCALAPPDATA && _path.default.join(env.LOCALAPPDATA, "Android", "Sdk")].filter(Boolean);
   const adb = process.platform === "win32" ? "adb.exe" : "adb";
+  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - Paths come from env vars, the user's own SDK location or the project dir, never remote input.
   return candidates.find(dir => _fs.default.existsSync(_path.default.join(dir, "platform-tools", adb))) || null;
 }
 
@@ -196,7 +199,7 @@ function detectAndroidSdk(env = process.env) {
 function listAvds(sdkPath) {
   if (!sdkPath) return [];
   try {
-    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - sdkPath is a local SDK directory from config or auto-detection.
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process, javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - sdkPath is a local SDK directory from config or auto-detection, never remote input.
     const out = (0, _child_process.execSync)(`"${_path.default.join(expandHome(sdkPath), "emulator", "emulator")}" -list-avds`, {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
@@ -212,6 +215,7 @@ function listAvds(sdkPath) {
 function expandHome(dir) {
   if (typeof dir !== "string") return dir;
   if (dir === "~") return _os.default.homedir();
+  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - Paths come from env vars, the user's own SDK location or the project dir, never remote input.
   return dir.startsWith("~/") || dir.startsWith("~\\") ? _path.default.join(_os.default.homedir(), dir.slice(2)) : dir;
 }
 
@@ -224,6 +228,7 @@ const ANDROID_SDK_HINT = exports.ANDROID_SDK_HINT = 'Install Android Studio, or
  * in gradle with "SDK location not found" despite a configured sdkPath.
  */
 function ensureLocalProperties(projectDir, sdkPath) {
+  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - Paths come from env vars, the user's own SDK location or the project dir, never remote input.
   const file = _path.default.join(projectDir, "local.properties");
   const line = `sdk.dir=${expandHome(sdkPath).replace(/\\/g, "\\\\")}`;
   let content = "";

package/dist/scripts/build.js

@@ -170,6 +170,7 @@ function reportBundleFailures(failures, cwd) {
                 message: shortenPaths(cause.message, cwd),
                 code,
                 scope: `${cause.bundles.join(" + ")} bundle`,
+                // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - cause.file is a build-tool diagnostic path, only used to display a location.
                 file: cause.file ? path.resolve(cwd, cause.file.replace(/^(\.\.\/)+/, "")) : undefined,
                 line: cause.line,
                 // esbuild reports columns 0-based; the frame's caret is 1-based.

package/dist/vite/vite.config.js

@@ -283,6 +283,7 @@ const getScssResourcesImport = () => {
  * half of them opened with 23 warning lines it could do nothing about.
  */
 function resolvableFrom(candidates, appRoot) {
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - appRoot is the local project root resolved by the CLI.
     const resolver = createRequire(path.join(appRoot, "package.json"))
     return candidates.filter((name) => {
         try {

package/dist/webmcp/WebMcpProvider.jsx

@@ -127,7 +127,7 @@ export function WebMcpProvider({ children, routes, filterNavigable }) {
             if (res.ok) owners.push(key)
             else
                 // eslint-disable-next-line no-console
-                console.warn(`[webmcp] declarative tool "${spec.name}" failed to register:`, res.error)
+                console.warn('[webmcp] declarative tool "%s" failed to register:', spec.name, res.error)
         }
 
         // Framework: navigate + get_current_route + get_page_info.
@@ -146,7 +146,8 @@ export function WebMcpProvider({ children, routes, filterNavigable }) {
             else
                 // eslint-disable-next-line no-console
                 console.warn(
-                    `[webmcp] framework tool "${spec.name}" failed to register — a route tool may already use that name:`,
+                    '[webmcp] framework tool "%s" failed to register — a route tool may already use that name:',
+                    spec.name,
                     res.error
                 )
         }

package/dist/webmcp/useTool.js

@@ -89,7 +89,7 @@ export function useTool(spec, deps) {
         } else {
             setState({ status: "error", receipt: null, error: res.error })
             // eslint-disable-next-line no-console
-            console.warn(`[webmcp] useTool("${s.name}") failed to register:`, res.error)
+            console.warn('[webmcp] useTool("%s") failed to register:', s.name, res.error)
         }
 
         return () => {

package/mcp_v2/conversion-tasks.json

@@ -206,12 +206,13 @@
         "detect_pattern": "field_check + file_exists",
         "how_to_check": [
             "file: config/config.json",
-            "field: splashScreen must exist at top level (NOT inside WEBVIEW_CONFIG)",
-            "file: public/android/splashscreen.png must exist",
-            "file: public/ios/splashscreen.png must exist"
+            "field: WEBVIEW_CONFIG.splashScreen must exist (NOT at the top level of config.json)",
+            "file (optional): public/android/splashscreen.{png|jpg|jpeg|gif|bmp|webp}",
+            "file (optional): public/ios/splashscreen.{png|jpg|jpeg}",
+            "file (optional, 1.0.2+): public/splashscreen.html"
         ],
-        "fix_guide": "1) Add to top level of config/config.json (NOT inside WEBVIEW_CONFIG): splashScreen: { android: { path: 'public/android/splashscreen.png' }, ios: { path: 'public/ios/splashscreen.png' } }. 2) Place splash images at those paths. Recommended sizes: Android 1080x1920px, iOS 1242x2688px.",
-        "verify_hint": "Build and install the app on a device/emulator. On cold launch (after force-closing), you should see the splash image for ~1-2 seconds before the app loads. If you see a white flash instead, either the asset path is wrong or splashScreen is inside WEBVIEW_CONFIG instead of at the top level of config.json.",
+        "fix_guide": "1) Add WEBVIEW_CONFIG.splashScreen to config/config.json, e.g. { backgroundColor: '#ffffff', duration: 1000, imageWidth: 120, imageHeight: 120 }. There is no path field: images are found by filename. 2) Place the images at public/android/splashscreen.<ext> and public/ios/splashscreen.<ext>; without one, Android shows the launcher icon and iOS a loader. 3) Optional on catalyst-core 1.0.2+: add a self-contained public/splashscreen.html (inline CSS/JS, data: URI images, no network) for an animated splash shown after the native image until the first page loads; set splashScreen.minDuration (ms) to hold it longer. duration is ignored in that mode.",
+        "verify_hint": "Build and install the app on a device/emulator. On cold launch (after force-closing), you should see the splash image for ~1-2 seconds before the app loads. If you see no splash, check that splashScreen sits inside WEBVIEW_CONFIG (not at the top level of config.json) and that the image filename is splashscreen.<ext>.",
         "depends_on": ["T1_CONFIG"]
     },
     {

package/mcp_v2/knowledge-base.json

@@ -490,7 +490,7 @@
     {
         "section": "config_structure",
         "title": "splashScreen Config Structure",
-        "content": "splashScreen sits INSIDE WEBVIEW_CONFIG (not at top-level config.json). All fields are optional \u2014 omitting splashScreen entirely = native build proceeds but shows blank splash. Fields: backgroundColor (string hex, default '#ffffff'), duration (number ms, iOS only \u2014 controls how long splash shows), imageWidth (number px, default 120), imageHeight (number px, default 120), cornerRadius (number px, iOS only, default 20). Example: WEBVIEW_CONFIG.splashScreen = { backgroundColor: '#ffffff', duration: 2000, imageWidth: 400, imageHeight: 200, cornerRadius: 20 }. Asset placement: put image at public/android/splashscreen.{png|jpg|jpeg|gif|bmp|webp} for Android, public/ios/splashscreen.{png|jpg|jpeg} for iOS. Asset is auto-discovered by filename \u2014 NO path field in config. Missing asset file = build proceeds with no splash image (no error). backgroundColor is applied to Android themes.xml (windowSplashScreenBackground). Pfizer example: splashScreen: { imageHeight: 200, imageWidth: 400 } (backgroundColor omits = defaults to white).",
+        "content": "splashScreen sits INSIDE WEBVIEW_CONFIG (not at the top level of config.json); the Android and iOS builds read only WEBVIEW_CONFIG.splashScreen. All fields are optional. Omitting splashScreen turns the Catalyst splash off and the app goes straight to the WebView. Fields: backgroundColor (string hex, default '#ffffff'), duration (number ms; Android defaults to 1000; on iOS, when unset, the splash is dismissed once the WebView finishes loading; ignored when public/splashscreen.html exists), minDuration (number ms, default 0, catalyst-core 1.0.2+; the minimum time the HTML splash stays up; a negative or non-number value is ignored with a build warning), imageWidth (number px, default 120), imageHeight (number px, default 120), cornerRadius (number px, default 20; 0 for square corners). Example: WEBVIEW_CONFIG.splashScreen = { backgroundColor: '#ffffff', duration: 2000, imageWidth: 400, imageHeight: 200, cornerRadius: 20 }. Asset placement: put image at public/android/splashscreen.{png|jpg|jpeg|gif|bmp|webp} for Android, public/ios/splashscreen.{png|jpg|jpeg} for iOS. Asset is auto-discovered by filename \u2014 NO path field in config. Missing image = build proceeds; Android shows the launcher icon, iOS a loader. backgroundColor is applied to Android themes.xml (windowSplashScreenBackground). Optional animated splash (1.0.2+): public/splashscreen.html, see 'HTML Splash Screen (1.0.2)'. Pfizer example: splashScreen: { imageHeight: 200, imageWidth: 400 } (backgroundColor omits = defaults to white).",
         "layer": "Config",
         "source": "static",
         "tags": ["splashscreen", "splash", "config", "webview_config", "android", "ios", "native", "assets"]
@@ -958,7 +958,7 @@
     {
         "section": "observability",
         "title": "OpenTelemetry Setup in Catalyst",
-        "content": "Catalyst provides built-in OpenTelemetry support via catalyst-core/otel. Server-side only.\n\nUSAGE: Call Otel.init() inside preServerInit() in server/index.js. Guard with an ENABLE flag and skip in development.\n\nimport Otel from 'catalyst-core/otel'\n\nexport const preServerInit = () => {\n  const otelConfig = JSON.parse(process.env.OTEL)\n  if (otelConfig.ENABLE && process.env.NODE_ENV !== 'development') {\n    Otel.init({\n      serviceName: 'my-catalyst-app',\n      serviceVersion: process.env.RELEASE_TAG,\n      environment: process.env.ENV_NAME,\n      traceUrl: otelConfig.ENDPOINT,\n      instrumentations: [ new HttpInstrumentation({ ... }) ],\n    })\n  }\n}\n\nCONFIG SHAPE (all optional, defaults shown):\n- serviceName: 'catalyst-server'\n- serviceVersion: '1.0.0'\n- environment: 'development'\n- traceUrl: 'http://localhost:4318/v1/traces'\n- metricUrl: 'http://localhost:4318/v1/metrics'\n- traceHeaders: {}\n- metricHeaders: {}\n- exportIntervalMillis: 10000\n- exportTimeoutMillis: 10000\n- instrumentations: [getNodeAutoInstrumentations()] by default\n\nAUTO METRICS: init() automatically collects process_cpu_usage_percent, process_memory_usage_bytes, process_memory_heap_used_bytes, process_memory_heap_total_bytes \u2014 no extra config needed.\n\nGRACEFUL SHUTDOWN: SIGTERM and SIGINT handlers registered automatically \u2014 sdk.shutdown() is called on process exit.\n\nRETURN VALUE: { sdk, meter } \u2014 use meter (OTel Meter instance) to create your own custom metrics via meter.createObservableGauge(), createCounter(), etc.\n\nPEER DEPS: Install @opentelemetry/* packages yourself \u2014 not bundled by catalyst-core.",
+        "content": "Catalyst provides built-in OpenTelemetry support via catalyst-core/otel. Server-side only.\n\nUSAGE: Call Otel.init() inside preServerInit() in server/index.js. Guard with an ENABLE flag and skip in development.\n\nimport Otel from 'catalyst-core/otel'\n\nexport const preServerInit = () => {\n  const otelConfig = JSON.parse(process.env.OTEL)\n  if (otelConfig.ENABLE && process.env.NODE_ENV !== 'development') {\n    Otel.init({\n      serviceName: 'my-catalyst-app',\n      serviceVersion: process.env.RELEASE_TAG,\n      environment: process.env.ENV_NAME,\n      traceUrl: otelConfig.ENDPOINT,\n      instrumentations: [ new HttpInstrumentation({ ... }) ],\n    })\n  }\n}\n\nCONFIG SHAPE (all optional, defaults shown):\n- serviceName: 'catalyst-server'\n- serviceVersion: '1.0.0'\n- environment: 'development'\n- traceUrl: 'http://localhost:4318/v1/traces'\n- metricUrl: 'http://localhost:4318/v1/metrics'\n- traceHeaders: {}\n- metricHeaders: {}\n- exportIntervalMillis: 10000\n- exportTimeoutMillis: 10000\n- instrumentations: [getNodeAutoInstrumentations()] by default\n\nAUTO METRICS: init() automatically collects process_cpu_usage_percent, process_memory_usage_bytes, process_memory_heap_used_bytes, process_memory_heap_total_bytes \u2014 no extra config needed.\n\nGRACEFUL SHUTDOWN: SIGTERM and SIGINT handlers registered automatically \u2014 sdk.shutdown() is called on process exit.\n\nRETURN VALUE: { sdk, meter } \u2014 use meter (OTel Meter instance) to create your own custom metrics via meter.createObservableGauge(), createCounter(), etc.\n\nPEER DEPS: Install @opentelemetry/* packages yourself \u2014 not bundled by catalyst-core.\n\nLOGGING: init() logs through the app-wide logger that configureLogger() from catalyst-core/logger installs. Before 1.0.2, calling Otel.init() in an app that never called configureLogger() threw ReferenceError: logger is not defined. From 1.0.2 it falls back to console until a global logger is set, and picks up a logger configured later. On older versions, call configureLogger() before Otel.init().",
         "layer": "Observability",
         "source": "static",
         "tags": [
@@ -1257,7 +1257,7 @@
     {
         "section": "framework_identity",
         "title": "Catalyst Runtime Generations",
-        "content": "Always determine the installed catalyst-core version before giving web runtime guidance. Catalyst 0.2.x is the legacy webpack generation and uses @tata1mg/router plus @loadable/component. Catalyst 0.3.x, beginning with 0.3.0-beta.1, is the Vite/ESM generation: router APIs are exported by catalyst-core and split()/hydrationReady() replace loadable APIs. Catalyst 1.0.0 is the API freeze (there is no 0.4.0 release); see 'Upgrading catalyst-core 0.3.x to 1.0.0'. Do not combine instructions from different generations. If no version can be detected, ask which version the project targets.",
+        "content": "Always determine the installed catalyst-core version before giving web runtime guidance. Catalyst 0.2.x is the legacy webpack generation and uses @tata1mg/router plus @loadable/component. Catalyst 0.3.x, beginning with 0.3.0-beta.1, is the Vite/ESM generation: router APIs are exported by catalyst-core and split()/hydrationReady() replace loadable APIs. Catalyst 1.0.0 is the API freeze (there is no 0.4.0 release); see 'Upgrading catalyst-core 0.3.x to 1.0.0'. Do not combine instructions from different generations. If no version can be detected, ask which version the project targets. Patch releases after 1.0.0 (1.0.1, 1.0.2) keep the frozen API; see 'Upgrading catalyst-core 1.0.x to 1.0.2'.",
         "layer": "Framework",
         "source": "static",
         "tags": ["versions", "0.2.x", "0.3.x", "1.0.0", "migration", "webpack", "vite"],
@@ -1281,10 +1281,22 @@
     {
         "section": "build_system",
         "title": "Catalyst 0.3.x CLI Commands",
-        "content": "Current web commands are catalyst start, catalyst build, catalyst serve, and catalyst serve:inspect. devBuild and devServe are legacy 0.2.x commands and are not accepted by the 0.3.x CLI. Native commands remain buildApp, buildApp:ios, buildApp:android, setupEmulator, setupEmulator:ios, and setupEmulator:android.",
+        "content": "Current web commands are catalyst start, catalyst build, catalyst serve, and catalyst serve:inspect. devBuild and devServe are legacy 0.2.x commands and are not accepted by the 0.3.x CLI. Native commands remain buildApp, buildApp:ios, buildApp:android, setupEmulator, setupEmulator:ios, and setupEmulator:android. catalyst-core 1.0.2 OUTPUT: every command prints a short header, one line per step with timing, and one diagnostic block on failure. Flags: --verbose shows every step and, on failure, the full tool output (bundler, Gradle); --debug also prints stacks and the environment. Child processes inherit the mode through CATALYST_OUTPUT_MODE=verbose|debug. Failures carry registry codes from the error catalog (for example BUNDLE-000, ANDROID-000, IOS-000, CCA-001); use the explain_error tool for any code. catalyst serve (1.0.2+) exits when there is no build in BUILD_OUTPUT_PATH and refuses a stale build with PREFLIGHT-022 when PUBLIC_STATIC_ASSET_URL, PUBLIC_STATIC_ASSET_PATH or a CLIENT_ENV_VARIABLES value in config/config.json changed after catalyst build (the build records them in <BUILD_OUTPUT_PATH>/.catalyst-build.json; a build from an older version has no record, so serve warns and skips the check until you rebuild). Fix: run catalyst build again, then catalyst serve. catalyst serve passes the app's own stdout/stderr through unchanged, so JSON log shippers keep working. Scripts that parsed the old CLI text output must be updated.",
         "layer": "Build",
         "source": "static",
-        "tags": ["0.3.x", "cli", "start", "build", "serve", "native"],
+        "tags": [
+            "0.3.x",
+            "1.0.2",
+            "cli",
+            "start",
+            "build",
+            "serve",
+            "native",
+            "verbose",
+            "debug",
+            "stale-build",
+            "PREFLIGHT-022"
+        ],
         "github_files": ["packages/catalyst-core/bin/catalyst.js"]
     },
     {
@@ -1303,7 +1315,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 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.",
+        "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 exported exactly eight names in 1.0.0: RouterDataProvider, useCurrentRouteData, useRouterData, MetaTag, split, hydrationReady, Head, Body. 1.0.2 adds a ninth, useRouterState (returns { location, params, navigate, matchedRoutes } through Catalyst's router context; used by catalyst-core/webmcp; throws outside RouterDataProvider). App components should still use react-router's useLocation/useParams/useNavigate. 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 +1389,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.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.",
+        "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: in 1.0.0 the root entry exports exactly RouterDataProvider, useCurrentRouteData, useRouterData, MetaTag, split, hydrationReady, Head, Body (1.0.2 adds useRouterState). 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": [
@@ -1457,5 +1469,110 @@
         "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"
+    },
+    {
+        "section": "config_structure",
+        "title": "HTML Splash Screen (1.0.2)",
+        "content": "Available from catalyst-core 1.0.2 on Android and iOS. Add public/splashscreen.html (the root of public/, not public/android or public/ios; one file shared by both platforms) to show an HTML/CSS animation while the app loads. It takes effect only when WEBVIEW_CONFIG.splashScreen is set; without that key the file is ignored.\n\nSEQUENCE: native splash image (public/<platform>/splashscreen.<ext>) \u2192 the HTML splash \u2192 the app. The HTML splash sits above the main WebView, which loads underneath, and is dismissed once the first page has finished loading and minDuration has passed. Hard cap: it is dismissed after 10 seconds even if the page is still loading.\n\nCONFIG: WEBVIEW_CONFIG.splashScreen.minDuration (ms, default 0) keeps the animation on screen at least that long. A negative or non-number value is ignored (0) with a build warning. duration is ignored in HTML mode. Example: { \"WEBVIEW_CONFIG\": { \"splashScreen\": { \"backgroundColor\": \"#ffffff\", \"minDuration\": 1200 } } }.\n\nFILE RULES: one self-contained file: inline CSS and JS, images as data: URIs. Paint your own opaque, full-screen background (the native image sits underneath). No network requests (Android blocks network loads in the splash WebView). No native bridge (no JS interfaces are exposed). Prefer CSS transform and opacity animations, since the app is loading at the same time.\n\nBUILD: iOS embeds the file in the app binary at build time and warns above 1 MB; Android copies it to assets/splash/. Rebuild the native app after editing it. Delete the file to go back to the image-only splash (the Android build also removes its copy). check_config reports the file and validates minDuration.",
+        "layer": "Config",
+        "source": "static",
+        "tags": [
+            "1.0.2",
+            "splashscreen",
+            "splash",
+            "splashscreen.html",
+            "html-splash",
+            "animated-splash",
+            "minDuration",
+            "native",
+            "android",
+            "ios"
+        ],
+        "github_files": [
+            "docs/content/02-Guides and Tutorials/02-First Universal App/03-Configuration.mdx",
+            "packages/catalyst-core/src/native/buildIos/config.js",
+            "packages/catalyst-core/src/native/androidProject/app/src/main/java/io/yourname/androidproject/SplashOverlay.kt"
+        ]
+    },
+    {
+        "section": "webmcp",
+        "title": "WebMCP (experimental, 1.0.2) \u2014 Setup",
+        "content": "WebMCP lets a page expose tools (named actions with a JSON-schema input) to an AI agent running in the browser. Catalyst ships it from catalyst-core 1.0.2 as catalyst-core/webmcp. EXPERIMENTAL: useTool, WebMcpProvider, the route `tool` field, the webmcp:* document events and inspect/invokeTool may change in a minor release. NOT the same as this MCP server: this server helps AI coding tools understand a Catalyst project (Node, build time); WebMCP runs in the app's browser tab and exposes the app's own actions to agents.\n\nSETUP: call installShim() from catalyst-core/webmcp/shim once, before the provider mounts. Catalyst targets this opt-in DOM shim; native browser document.modelContext is intentionally unsupported for now. Then wrap the app in WebMcpProvider inside RouterDataProvider, passing the app's own route table:\n\nimport { WebMcpProvider } from 'catalyst-core/webmcp'\nimport { installShim } from 'catalyst-core/webmcp/shim'\nimport routes from './routes'\ninstallShim()\nexport const App = ({ children }) => (\n  <WebMcpProvider routes={routes} filterNavigable={(route) => !route.path.startsWith('/docs/')}>{children}</WebMcpProvider>\n)\n\nfilterNavigable is optional and keeps large page sets out of the navigate tool's enum.\n\nBUILT-IN TOOLS (registered by the provider): navigate, get_current_route, get_page_info (built from the page's setMetaData). Agent side (shim): document.modelContext.getTools() and document.modelContext.executeTool(name, args).\n\nEXPORTS of catalyst-core/webmcp: WebMcpProvider, useTool, WebMcpError, WEBMCP_ERROR_CODES, inspect, invokeTool, isNative, plus helpers (flattenRoutes, declarativeToolFor, frameworkTools, toolNameFromPath, paramNames, fillPath, buildInputSchema, pageInfoTool, flattenHeadElements). catalyst-core/webmcp/shim exports installShim. A dev panel is app-level: listen for webmcp:register, webmcp:unregister, webmcp:execute:start and webmcp:execute:end on document and call inspect()/invokeTool(). Full guide: docs/content/20-WebMCP.md; example app: examples/webmcp-poc.",
+        "layer": "Runtime",
+        "source": "static",
+        "tags": [
+            "1.0.2",
+            "webmcp",
+            "web-mcp",
+            "agents",
+            "ai-agent",
+            "modelContext",
+            "WebMcpProvider",
+            "installShim",
+            "shim",
+            "experimental",
+            "tools"
+        ],
+        "github_files": [
+            "docs/content/20-WebMCP.md",
+            "packages/catalyst-core/src/webmcp/index.js",
+            "packages/catalyst-core/src/webmcp/shim.js"
+        ]
+    },
+    {
+        "section": "webmcp",
+        "title": "WebMCP \u2014 Authoring Tools (route tool, useTool, errors)",
+        "content": "Three ways to author WebMCP tools (catalyst-core 1.0.2+, experimental):\n\n1. DECLARATIVE, on the route: add `tool` to a route and Catalyst derives the name from the path (static segments joined by '_', '/' is 'home'), the input schema (path params required, `searchParams` optional) and an execute that navigates. Route tools default to annotations { readOnlyHint: true } and are available app-wide.\n{ path: '/products', component: ProductList, tool: { description: 'Browse the catalogue, optionally filtered.', searchParams: { category: { type: 'string', enum: ['footwear', 'apparel'] } } } }\n\n2. IMPERATIVE, in a component: useTool(spec) registers an action tool for the component's lifetime and removes it on unmount or when the user leaves the route. spec = { name, description, inputSchema, annotations?, execute }. Returns { status, receipt, error }; the receipt is a registration handle, not an execution result.\nuseTool({ name: 'add_to_cart', description: 'Add the current product to the cart.', inputSchema: { type: 'object', properties: { quantity: { type: 'number', minimum: 1 } } }, execute: async ({ quantity = 1 }) => { dispatch(addItem({ id, quantity })); return { added: true } } })\n\n3. STATEFUL, with deps: useTool(spec, deps) refreshes description, inputSchema, annotations and execute in place when a dep changes (for example an enum of cart item ids), so a call already in flight still completes.\n\nERRORS: throw new WebMcpError with a code from WEBMCP_ERROR_CODES (TOOL_NOT_FOUND, INVALID_ARGS, EXECUTE_FAILED, ABORTED, DUPLICATE_TOOL; values are prefixed WEBMCP_, e.g. 'WEBMCP_INVALID_ARGS'). Arguments in the schema's `required` array are checked before execute runs.\n\nRULES: do side effects inside the tool (agents ignore 'now call X' hints in results). Mark intent with annotations: { readOnlyHint: true } for reads, { consequentialHint: true } for irreversible actions such as checkout. Keep names unique: route tool names must not collide with navigate, get_current_route or get_page_info; a collision logs a warning and the later tool is dropped.",
+        "layer": "Runtime",
+        "source": "static",
+        "tags": [
+            "1.0.2",
+            "webmcp",
+            "useTool",
+            "route-tool",
+            "declarative",
+            "WebMcpError",
+            "WEBMCP_ERROR_CODES",
+            "readOnlyHint",
+            "consequentialHint",
+            "experimental",
+            "tools"
+        ],
+        "github_files": [
+            "docs/content/20-WebMCP.md",
+            "packages/catalyst-core/src/webmcp/useTool.js",
+            "packages/catalyst-core/src/webmcp/declarative.js",
+            "packages/catalyst-core/src/webmcp/errors.js"
+        ]
+    },
+    {
+        "section": "version_migration",
+        "title": "Upgrading catalyst-core 1.0.x to 1.0.2",
+        "content": "1.0.2 is a patch release on the frozen 1.0 API; most applications need no code change. Read the installed catalyst-core version from package.json first; apps on 0.3.x follow 'Upgrading catalyst-core 0.3.x to 1.0.0' first.\n\n1. DEPENDENCIES: set catalyst-core to 1.0.2. Node stays >=22.12; react and react-dom stay 19.0.0; react-router stays ^7.18.2.\n\n2. react-helmet-async REMOVED: catalyst-core no longer depends on it. MetaTag and setMetaData work unchanged; the tags are now rendered through React 19 document metadata, and the server-rendered copies are removed once the client copies are in, so stale head tags no longer survive navigation. If the application imports react-helmet-async itself (it used to arrive transitively), add it to the application's own dependencies.\n\n3. CLI OUTPUT: start, build, serve and the native builds print a short header, one line per step and one diagnostic block on failure; --verbose and --debug show more (see 'Catalyst 0.3.x CLI Commands'). Update any script that parsed the old text output. catalyst serve now refuses a stale build (PREFLIGHT-022): after changing PUBLIC_STATIC_ASSET_URL, PUBLIC_STATIC_ASSET_PATH or CLIENT_ENV_VARIABLES values, rebuild before serving. Run catalyst build once after upgrading so serve can run that check.\n\n4. FIXES, nothing to do: Fast Refresh works for JSX in .js files; Otel.init() no longer throws without configureLogger() (falls back to console); Head and Body no longer import prop-types at runtime, so apps that do not install prop-types no longer crash in SSR.\n\n5. NEW, OPT-IN: an animated HTML splash via public/splashscreen.html plus WEBVIEW_CONFIG.splashScreen.minDuration ('HTML Splash Screen (1.0.2)'); WebMCP via catalyst-core/webmcp, experimental ('WebMCP (experimental, 1.0.2) \u2014 Setup').\n\n6. NEW APPS ONLY: apps created by the create-catalyst-app released with catalyst-core 1.0.2 declare \"type\": \"module\" in package.json, and the Tailwind template ships postcss.config.cjs. catalyst-core reads postcss.config.cjs or postcss.config.js, so existing apps need no change. create-catalyst-app runs on Node >=20.12. NEW ROOT EXPORT: useRouterState is added to the root entry (now nine names); existing imports are unaffected.",
+        "layer": "Framework",
+        "source": "static",
+        "tags": [
+            "migration",
+            "upgrade",
+            "update",
+            "bump",
+            "1.0.2",
+            "1.0.1",
+            "1.0.x",
+            "patch",
+            "react-helmet-async",
+            "helmet",
+            "verbose",
+            "stale-build",
+            "PREFLIGHT-022",
+            "splashscreen.html",
+            "webmcp",
+            "latest",
+            "useRouterState"
+        ],
+        "github_files": [
+            "packages/catalyst-core/changelog.md",
+            "docs/content/12-Migration/02-Version-Upgrades.md"
+        ]
     }
 ]

package/mcp_v2/test/config.test.ts

@@ -50,3 +50,62 @@ describe("check_config: on-device AI", () => {
         expect(aiFields(r)).toEqual([])
     })
 })
+
+function makeSplashProject(config: unknown, files: string[] = []): string {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-cfg-"))
+    fs.mkdirSync(path.join(root, "config"))
+    fs.writeFileSync(path.join(root, "config", "config.json"), JSON.stringify(config))
+    for (const f of files) {
+        fs.mkdirSync(path.dirname(path.join(root, f)), { recursive: true })
+        fs.writeFileSync(path.join(root, f), "")
+    }
+    return root
+}
+
+const findings = (r: ReturnType<typeof handle_check_config>) => [...r.issues, ...r.warnings, ...r.passed]
+
+describe("check_config: splash screen", () => {
+    it("reads splashScreen from WEBVIEW_CONFIG and treats missing images as fine", () => {
+        const r = handle_check_config({
+            project_path: makeSplashProject({
+                WEBVIEW_CONFIG: { splashScreen: { backgroundColor: "#fff" } },
+            }),
+        })
+        expect(r.passed.some((p) => p.field === "WEBVIEW_CONFIG.splashScreen")).toBe(true)
+        expect(r.issues.some((i) => /splash/i.test(i.field))).toBe(false)
+    })
+
+    it("flags a top-level splashScreen as misplaced", () => {
+        const r = handle_check_config({
+            project_path: makeSplashProject({ WEBVIEW_CONFIG: {}, splashScreen: { duration: 1000 } }),
+        })
+        expect(
+            r.warnings.some((w) => w.field === "WEBVIEW_CONFIG.splashScreen" && /top level/.test(w.message!))
+        ).toBe(true)
+    })
+
+    it("recognises public/splashscreen.html", () => {
+        const r = handle_check_config({
+            project_path: makeSplashProject({ WEBVIEW_CONFIG: { splashScreen: { minDuration: 1200 } } }, [
+                "public/splashscreen.html",
+            ]),
+        })
+        expect(r.passed.some((p) => p.field === "public/splashscreen.html")).toBe(true)
+    })
+
+    it("warns on an invalid minDuration", () => {
+        for (const minDuration of [-1, "1200"]) {
+            const r = handle_check_config({
+                project_path: makeSplashProject({ WEBVIEW_CONFIG: { splashScreen: { minDuration } } }),
+            })
+            expect(r.warnings.some((w) => w.field === "WEBVIEW_CONFIG.splashScreen.minDuration")).toBe(true)
+        }
+    })
+
+    it("accepts a valid minDuration silently", () => {
+        const r = handle_check_config({
+            project_path: makeSplashProject({ WEBVIEW_CONFIG: { splashScreen: { minDuration: 0 } } }),
+        })
+        expect(findings(r).some((f) => f.field === "WEBVIEW_CONFIG.splashScreen.minDuration")).toBe(false)
+    })
+})

package/mcp_v2/tools/build.js

@@ -23,7 +23,7 @@ const MASTER_FLOWS = {
             step: 1,
             cmd: "catalyst start",
             label: "Start dev server",
-            detail: "Starts the Vite middleware-mode development server and Catalyst SSR server on NODE_SERVER_PORT. Hot reload and React Fast Refresh are enabled.",
+            detail: "Starts the Vite middleware-mode development server and Catalyst SSR server on NODE_SERVER_PORT. Hot reload and React Fast Refresh are enabled, including for JSX in .js files (1.0.2+). Since 1.0.2 the terminal shows a short header and one line per step; add --verbose for every step and the full tool output, or --debug for stacks and the environment.",
         },
         {
             step: 2,
@@ -38,13 +38,13 @@ const MASTER_FLOWS = {
             step: 1,
             cmd: "catalyst build",
             label: "Production build",
-            detail: "Runs parallel Vite client and SSR builds. Outputs client assets to build/client, the renderer to build/server, Vite manifests under build/.vite, and offline runtime files at the build root.",
+            detail: "Runs parallel Vite client and SSR builds. Outputs client assets to build/client, the renderer to build/server, Vite manifests under build/.vite, and offline runtime files at the build root. Since 1.0.2 it prints one line per step with timing and, on failure, the extracted errors with file, line and a hint; --verbose or --debug add the error code (BUNDLE-000), its docs link and the bundler's full output. It also writes <BUILD_OUTPUT_PATH>/.catalyst-build.json with the config values inlined into the bundles.",
         },
         {
             step: 2,
             cmd: "catalyst serve",
             label: "Serve built app (local)",
-            detail: "Serves from build/ — same as production but local. Use for smoke-testing the build before deploy.",
+            detail: "Serves from build/ — same as production but local. Use for smoke-testing the build before deploy. Since 1.0.2 it exits if there is no build, and refuses a stale build (PREFLIGHT-022) when PUBLIC_STATIC_ASSET_URL, PUBLIC_STATIC_ASSET_PATH or a CLIENT_ENV_VARIABLES value changed in config/config.json after the build; rebuild, then serve. The app's own output passes through unchanged.",
         },
     ],
 
@@ -101,7 +101,7 @@ const MASTER_FLOWS = {
             step: 3,
             cmd: "npm run buildApp:android",
             label: "Android debug build",
-            detail: "Runs buildAppAndroid.js: validates ADB + emulator path from sdkPath, launches emulator (emulatorName), copies web assets to androidProject/, runs Gradle debug build, installs APK.",
+            detail: "Runs buildAppAndroid.js: validates ADB + emulator path from sdkPath, launches emulator (emulatorName), copies web assets to androidProject/, runs Gradle debug build, installs APK. Since 1.0.2 Gradle runs behind one progress line that shows the current task; on failure --verbose or --debug add the ANDROID-000 report with the full Gradle output.",
         },
         {
             step: 4,
@@ -301,7 +301,7 @@ const MASTER_DIAGRAMS = {
             "LOCAL_IP — override auto-detected IP for device builds",
             "accessControl.allowedUrls — whitelist for outbound requests from WebView",
             "googleSignIn.enabled / clientId / iosClientId",
-            "splashScreen — duration, backgroundColor, logo asset",
+            "splashScreen — duration, minDuration, backgroundColor, image size; optional animated public/splashscreen.html (1.0.2+)",
             "notifications.enabled — push notification permission prompt",
             "android.buildOptimisation — enables build caching",
             "android.keystoreConfig — signing for release builds",
@@ -760,7 +760,7 @@ function handle_get_architecture_diagram({ feature, symptom } = {}) {
         project_context.push(`iOS configured: ${ctx.hasIos}`)
         if (ctx.hasGoogleSignIn) project_context.push("googleSignIn: enabled")
         const { readJson } = makeProjectHelpers(catalystRoot.dir)
-        const splash = (readJson("config/config.json") || {}).splashScreen
+        const splash = (readJson("config/config.json") || {}).WEBVIEW_CONFIG?.splashScreen
         if (splash)
             project_context.push(`splashScreen: configured (duration: ${splash.duration || "default"})`)
     }

package/mcp_v2/tools/config.js

@@ -389,28 +389,45 @@ function handle_check_config({ project_path, platform = "both" } = {}) {
         }
     }
 
-    // ── splashScreen (top-level, not inside WEBVIEW_CONFIG) ────────────────────
-    if (!config.splashScreen) {
+    // ── splashScreen (inside WEBVIEW_CONFIG; the native builds read only that) ──
+    const splash = wc.splashScreen
+    const hasSplashHtml = fs.existsSync(path.join(root, "public", "splashscreen.html"))
+    if (!splash) {
         warnings.push({
-            field: "splashScreen",
-            message:
-                'splashScreen key missing from top level of config/config.json. Native app will show a blank white screen during JS load. Add splashScreen: { android: { path: "public/android/splashscreen.png" }, ios: { path: "public/ios/splashscreen.png" } }.',
+            field: "WEBVIEW_CONFIG.splashScreen",
+            message: config.splashScreen
+                ? "splashScreen is at the top level of config/config.json, where the native builds never read it. Move it into WEBVIEW_CONFIG.splashScreen."
+                : `WEBVIEW_CONFIG.splashScreen not set, so the native splash screen is off${hasSplashHtml ? " and public/splashscreen.html is ignored" : ""}. Add WEBVIEW_CONFIG.splashScreen (e.g. { "backgroundColor": "#ffffff" }) to turn it on.`,
         })
     } else {
-        const missingSplash = ["public/android/splashscreen.png", "public/ios/splashscreen.png"].filter(
-            (f) => {
-                const filePath = projectPath(root, f)
-                return !filePath || !fs.existsSync(filePath)
-            }
-        )
-        if (missingSplash.length) {
-            issues.push({
-                field: "splashScreen",
-                severity: "error",
-                message: `splashScreen configured but asset files missing: ${missingSplash.join(", ")}. Native build will fail when packaging.`,
+        // Images are optional: Android falls back to the launcher icon, iOS to a loader.
+        const found = (dir, exts) =>
+            exts
+                .map((ext) => `public/${dir}/splashscreen.${ext}`)
+                // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - root is the local project root; f comes from a fixed candidate list.
+                .find((f) => fs.existsSync(path.join(root, f)))
+        const androidImage = found("android", ["png", "jpg", "jpeg", "gif", "bmp", "webp"])
+        const iosImage = found("ios", ["png", "jpg", "jpeg"])
+        passed.push({
+            field: "WEBVIEW_CONFIG.splashScreen",
+            note: `android image: ${androidImage || "none (launcher icon)"}, ios image: ${iosImage || "none (loader)"}`,
+        })
+        // Same rule as the iOS build (buildIos/config.js): anything else is ignored with a warning.
+        const { minDuration } = splash
+        if (
+            minDuration !== undefined &&
+            !(typeof minDuration === "number" && Number.isFinite(minDuration) && minDuration >= 0)
+        ) {
+            warnings.push({
+                field: "WEBVIEW_CONFIG.splashScreen.minDuration",
+                message: `splashScreen.minDuration must be a non-negative number of milliseconds. Got ${JSON.stringify(minDuration)}; the build ignores it and uses 0.`,
+            })
+        }
+        if (hasSplashHtml) {
+            passed.push({
+                field: "public/splashscreen.html",
+                note: `HTML splash on (catalyst-core 1.0.2+): shown after the native image until the first page loads, for at least minDuration (${minDuration || 0} ms), at most 10 s; duration is ignored`,
             })
-        } else {
-            passed.push({ field: "splashScreen", note: "config and both asset files present" })
         }
     }
 

package/mcp_v2/tools/conversion.js

@@ -390,23 +390,17 @@ function handle_get_conversion_status({ project_path, include_not_applicable = f
                     native_risk: "No config — splash screen config cannot be read.",
                     reason: "config/config.json not found",
                 }
-            if (!config.splashScreen)
+            if (!webviewConfig || !webviewConfig.splashScreen)
                 return {
                     status: "gap",
                     native_risk:
-                        "Without splashScreen config, native app shows a blank white screen during JS load. Not a crash, but poor UX and noticeable on slow devices.",
-                    reason: "splashScreen key missing from top level of config/config.json (not inside WEBVIEW_CONFIG)",
-                }
-            const missing = ["public/android/splashscreen.png", "public/ios/splashscreen.png"].filter(
-                (f) => !fileExists(f)
-            )
-            if (missing.length)
-                return {
-                    status: "gap",
-                    native_risk:
-                        "Splash config exists but asset files missing — build will fail when packaging the native app.",
-                    reason: `Splash asset files missing: ${missing.join(", ")}`,
+                        "Without WEBVIEW_CONFIG.splashScreen the Catalyst splash is skipped and the app goes straight to the WebView while JS loads. Not a crash, but poor UX on slow devices.",
+                    reason: config.splashScreen
+                        ? "splashScreen is at the top level of config/config.json; the native builds read only WEBVIEW_CONFIG.splashScreen"
+                        : "WEBVIEW_CONFIG.splashScreen missing from config/config.json",
                 }
+            // Images are optional (Android falls back to the launcher icon, iOS to a loader), so a
+            // missing image is not a gap.
             return { status: "completed" }
         },
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "catalyst-core",
-    "version": "1.0.2-canary.2",
+    "version": "1.0.2",
     "type": "module",
     "main": "./dist/index.jsx",
     "description": "Web framework that provides great performance out of the box",
@@ -83,10 +83,10 @@
         "react-redux": "^9.2.0",
         "react-refresh": "^0.14.0",
         "redux": "^4.2.1",
-        "sanitize-html": "^2.17.6",
+        "sanitize-html": "^2.18.1",
         "sass": "^1.89.2",
         "ua-parser-js": "^1.0.37",
-        "vite": "^6.4.3",
+        "vite": "^6.4.5",
         "vite-plugin-svgr": "^5.0.0",
         "winston": "^3.11.0",
         "winston-daily-rotate-file": "^5.0.0"
@@ -125,7 +125,7 @@
         "eslint-plugin-security": "^3.0.0",
         "husky": "^9.0.11",
         "jsdom": "30.0.1",
-        "lint-staged": "^15.2.2",
+        "lint-staged": "^17.6.0",
         "prettier": "^3.2.5",
         "react-router": "^7.18.2",
         "typescript": "^7.0.2",