catalyst-core 1.0.1 → 1.0.2-canary.2

package/dist/native/buildIos/index.js

@@ -2,15 +2,25 @@
 
 const {
   execFile,
-  execFileSync
+  execFileSync,
+  spawn
 } = require("child_process");
 const fs = require("fs");
 const path = require("path");
+const {
+  displayPath
+} = require("../../cli/theme.js");
 const TerminalProgress = require("../terminalProgress.js").default;
+const {
+  buildFailure
+} = require("../../cli/diagnostic.js");
 const createConfigPhase = require("./config.js");
 const createPluginsPhase = require("./plugins.js");
 const createAssetsPhase = require("./assets.js");
 const createBuildPhase = require("./build.js");
+
+// Matches runInteractiveCommand: keep the tail, not the whole transcript.
+const MAX_STREAMED_OUTPUT_BYTES = 1024 * 1024;
 const catalystCorePath = path.dirname(require.resolve("catalyst-core/package.json"));
 const pwd = path.join(catalystCorePath, "dist/native");
 const MANAGED_BASELINE_SUFFIX = ".catalyst-base";
@@ -34,46 +44,126 @@ function createIosBuild(config) {
   const PROJECT_NAME = path.basename(PROJECT_DIR);
   const IPHONE_MODEL = iosConfig.simulatorName;
   const steps = {
-    config: "Generating Required Configuration for build",
-    deviceDetection: "Detecting Physical Device",
-    launchSimulator: "Launch iOS Simulator",
-    clean: "Clean Build Artifacts",
-    assets: "Process Notification Assets",
-    build: "Build IOS Project",
-    findApp: "Locate Built Application",
-    install: "Install Application",
-    launch: "Launch Application"
-  };
-  const progressConfig = {
-    titlePaddingTop: 2,
-    titlePaddingBottom: 1,
-    stepPaddingLeft: 4,
-    stepSpacing: 1,
-    errorPaddingLeft: 6,
-    bottomMargin: 2
+    config: "Generate build configuration",
+    deviceDetection: "Detect physical device",
+    launchSimulator: "Launch iOS simulator",
+    clean: "Clean build artifacts",
+    assets: "Process notification assets",
+    build: "Build iOS project",
+    findApp: "Locate built application",
+    install: "Install application",
+    launch: "Launch application"
   };
-  const progress = new TerminalProgress(steps, "Catalyst iOS Build", progressConfig);
+  const progress = new TerminalProgress(steps, "catalyst buildApp", {
+    subject: "ios"
+  });
 
   // ─── Low-level helpers shared across modules ──────────────────────────────
 
   function runCommand(command, options = {}) {
     return new Promise((resolve, reject) => {
-      execFile(shellCommand, shellArgs(command), {
-        maxBuffer: 1024 * 1024 * 10,
+      execFile(shellCommand, shellArgs(command),
+      // Unbounded: a 10MB cap turned a large-but-successful build into
+      // a spurious ERR_CHILD_PROCESS_STDIO_MAXBUFFER failure.
+      {
+        maxBuffer: Infinity,
         ...options
-      }, (error, stdout, stderr) => {
+      }, (error, stdout) => {
         if (error) {
-          console.error(`Command failed: ${command}`);
-          console.error(`Error: ${error.message}`);
-          console.error(`stderr: ${stderr}`);
+          // Let one layer above print this once. It used to print
+          // three lines here and the callers printed the same
+          // failure again -- ~6 lines across 4 layers per error.
+          // execFile already appends stderr to error.message, so
+          // appending it again here showed it twice.
           reject(error);
           return;
         }
-        if (stderr) console.warn(`Warning: ${stderr}`);
+        // Tools write plenty of non-fatal chatter to stderr, so a
+        // successful command reporting "Warning: ..." was noise.
         resolve(stdout.trim());
       });
     });
   }
+
+  /**
+   * The phase from an xcodebuild line, or null for lines worth ignoring.
+   * "CompileSwift normal arm64 /path/ContentView.swift" becomes
+   * "CompileSwift ContentView.swift".
+   */
+  function xcodePhase(line) {
+    const match = /^(CompileSwift|CompileC|Ld|CodeSign|ProcessInfoPlistFile|CpResource|Touch)\b(.*)$/.exec(line.trim());
+    if (!match) return null;
+    const file = (match[2].trim().split(/\s+/).pop() || "").split("/").pop();
+    return file ? `${match[1]} ${file}` : match[1];
+  }
+
+  /**
+   * Streaming sibling of runCommand, for the long xcodebuild calls.
+   *
+   * Buffered execFile means nothing appears until the build finishes -- for
+   * xcodebuild that is minutes of apparent hang. Rather than scroll its
+   * hundreds of lines (nobody reads them on success, and the error path
+   * re-derives what it needs from error.output), the current phase is shown
+   * on the spinner's own row. The full output is still resolved for callers
+   * that parse it.
+   */
+  function runCommandStreaming(command) {
+    return new Promise((resolve, reject) => {
+      progress.pause();
+
+      // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - Internal build command strings, same source as runCommand.
+      const child = spawn(shellCommand, shellArgs(command), {
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      let output = "";
+      const partial = {
+        stdout: "",
+        stderr: ""
+      };
+      const consume = (data, stream) => {
+        const text = data.toString();
+
+        // Same 1MB tail cap as runInteractiveCommand. Without it a long
+        // xcodebuild retained every byte it ever printed.
+        output += text;
+        if (output.length > MAX_STREAMED_OUTPUT_BYTES) {
+          output = output.slice(-MAX_STREAMED_OUTPUT_BYTES);
+        }
+        const lines = (partial[stream] + text).split("\n");
+        partial[stream] = lines.pop();
+        for (const line of lines) progress.status(xcodePhase(line));
+      };
+      const flush = () => {
+        for (const stream of ["stdout", "stderr"]) {
+          partial[stream] = "";
+        }
+      };
+      child.stdout.on("data", data => consume(data, "stdout"));
+      child.stderr.on("data", data => consume(data, "stderr"));
+      child.on("error", error => {
+        flush();
+        progress.resume();
+        reject(error);
+      });
+      child.on("close", code => {
+        flush();
+        progress.resume();
+        if (code === 0) {
+          resolve(output.trim());
+          return;
+        }
+
+        // Carry the whole output so the reporter can mine the real
+        // compiler errors out of it. A 5-line tail was arbitrary --
+        // xcodebuild puts the cause in the middle and summary noise
+        // at the end.
+        const error = new Error(`Command failed with exit code ${code}`);
+        error.code = code;
+        error.output = output;
+        reject(error);
+      });
+    });
+  }
   function getXcodeProjectFilePath() {
     return path.join(PROJECT_DIR, `${PROJECT_NAME}.xcodeproj`, "project.pbxproj");
   }
@@ -113,6 +203,8 @@ function createIosBuild(config) {
   const ctx = {
     WEBVIEW_CONFIG,
     BUILD_OUTPUT_PATH,
+    // Captured before the build chdirs into the Xcode project.
+    appRoot: process.cwd(),
     iosConfig,
     isGoogleSignInEnabled,
     PROJECT_DIR,
@@ -124,6 +216,7 @@ function createIosBuild(config) {
     PUBLIC_PATH,
     progress,
     runCommand,
+    runCommandStreaming,
     getXcodeProjectFilePath,
     ensureManagedBaseline,
     restoreManagedFileFromBaseline,
@@ -179,12 +272,11 @@ function createIosBuild(config) {
       await generateXCConfig();
       await copySplashscreenAssets();
       await copyAppIcon();
-      progress.log("Changing directory to: " + PROJECT_DIR, "info");
       process.chdir(PROJECT_DIR);
       const physicalDevice = await detectPhysicalDevices();
       let APP_PATH, targetInfo;
       if (physicalDevice) {
-        progress.log("🔥 Building for physical device workflow", "success");
+        progress.log("Building for physical device workflow", "success");
         targetInfo = {
           type: "physical",
           name: physicalDevice.name,
@@ -196,23 +288,10 @@ function createIosBuild(config) {
           await buildProjectForPhysicalDevice(SCHEME_NAME, APP_BUNDLE_ID, path.join(process.env.HOME, "Library/Developer/Xcode/DerivedData"), PROJECT_NAME, physicalDevice);
           progress.complete("build");
         } catch (error) {
-          progress.fail("build", error.message);
-          progress.printTreeContent("Physical Device Build Failed", ["Build failed. Please check:", {
-            text: "Code signing certificates are properly installed",
-            indent: 1,
-            prefix: "├─ ",
-            color: "yellow"
-          }, {
-            text: "Provisioning profile matches your bundle ID",
-            indent: 1,
-            prefix: "├─ ",
-            color: "yellow"
-          }, {
-            text: "Device is connected and trusted",
-            indent: 1,
-            prefix: "└─ ",
-            color: "yellow"
-          }]);
+          // The diagnostic in the catch below shows what xcodebuild
+          // said, with a signing hint when that is the cause; a fixed
+          // checklist here only guessed.
+          error.stage = error.stage || "Building for the device";
           throw error;
         }
         progress.start("findApp");
@@ -221,12 +300,11 @@ function createIosBuild(config) {
           progress.log("Found app at: " + APP_PATH, "success");
           progress.complete("findApp");
         } catch (error) {
-          progress.fail("findApp", error.message);
+          error.stage = error.stage || "Locating the built app";
           throw error;
         }
         await installAndLaunchOnPhysicalDevice(APP_PATH, physicalDevice);
       } else {
-        progress.log("📱 Building for simulator workflow", "info");
         targetInfo = {
           type: "simulator",
           name: IPHONE_MODEL
@@ -240,34 +318,35 @@ function createIosBuild(config) {
         const MOVED_APP_PATH = await moveAppToBuildOutput(APP_PATH);
         APP_PATH = MOVED_APP_PATH;
       }
-      progress.printTreeContent("Build Summary", ["Build completed successfully:", {
-        text: `Target: ${targetInfo.type === "physical" ? "📱 Physical Device" : "📱 Simulator"}`,
-        indent: 1,
-        prefix: "├─ ",
-        color: "green"
-      }, {
-        text: `Device: ${targetInfo.name}`,
-        indent: 1,
-        prefix: "├─ ",
+      // Same aligned key/value shape as the Android summary and the
+      // Config tree the setup commands print.
+      const deviceName = `${targetInfo.name}${targetInfo.type === "physical" ? "" : " simulator"}`;
+      progress.printTreeContent("Build", [{
+        text: `device     ${deviceName}`,
         color: "gray"
       }, {
-        text: `App Path: ${APP_PATH}`,
-        indent: 1,
-        prefix: "├─ ",
+        text: `artifact   ${displayPath(APP_PATH, originalDir)}`,
         color: "gray"
       }, {
-        text: `URL: ${url}`,
-        indent: 1,
-        prefix: "└─ ",
+        text: `loads      ${url}`,
         color: "gray"
       }]);
+      progress.summary(`Installed on ${deviceName}`, "Run catalyst start to serve the app");
       return {
         success: true,
         targetInfo,
         appPath: APP_PATH
       };
     } catch (error) {
-      progress.log("Build failed: " + error.message, "error");
+      // Mark the step, then show what actually broke -- once. The ✗ line
+      // carries no message: the diagnostic below is the message.
+      if (progress.currentStep) progress.fail(progress.currentStep.id);
+      process.stderr.write(buildFailure({
+        error,
+        stage: error.stage || "iOS build",
+        code: "IOS-000",
+        cwd: originalDir
+      }));
       throw error;
     } finally {
       process.chdir(originalDir);
@@ -306,7 +385,7 @@ function createIosBuild(config) {
           throw buildError;
         }
       }
-      progress.log("✅ build-for-testing complete — test bundle ready for xctest runner", "success");
+      progress.log("build-for-testing complete — test bundle ready for xctest runner", "success");
       return {
         success: true
       };

package/dist/native/buildIos/plugins.js

@@ -127,7 +127,7 @@ module.exports = function createPluginsPhase(ctx) {
       coreDependencies.forEach(d => mergePackageDependency(packageDependencyMap, d, "core target"));
       notificationsDependencies.forEach(d => mergePackageDependency(packageDependencyMap, d, "notifications target"));
       const packageDependencies = [...packageDependencyMap.values()].sort((l, r) => l.url.localeCompare(r.url));
-      progress.log(`🔧 Generating Package.swift (notifications: ${isNotificationsEnabled})`, "info");
+      progress.log(`Generating Package.swift (notifications: ${isNotificationsEnabled})`, "info");
       const configHash = crypto.createHash("md5").update(JSON.stringify({
         notifications: isNotificationsEnabled,
         googleSignIn: isGoogleSignInEnabled,
@@ -152,7 +152,6 @@ module.exports = function createPluginsPhase(ctx) {
         progress.log("Package.swift missing, will generate it now", "info");
       }
       if (shouldUpdate) {
-        progress.log("Generating Package.swift dynamically", "info");
         let packageContent = `// swift-tools-version: 5.9
 // Auto-generated Package.swift - DO NOT EDIT MANUALLY
 // Generated based on config: notifications.enabled = ${isNotificationsEnabled}
@@ -222,24 +221,25 @@ ${formatSwiftProductEntries(notificationsDependencies).join(",\n")}
             stdio: "ignore"
           }); // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
           const projectPath = path.join(PROJECT_DIR, `${PROJECT_NAME}.xcodeproj`); // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
+          // Piped, not inherited: inherited stdio put xcodebuild's
+          // 19-line package graph on screen at column 0, outside the
+          // gutter. Captured instead, so a failure can still show it.
           execSync(`cd "${PROJECT_DIR}" && xcodebuild -resolvePackageDependencies -project "${projectPath}" -scheme "${SCHEME_NAME}"`,
           // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - PROJECT_DIR, projectPath, and SCHEME_NAME are generated from trusted iOS project config.
           {
-            stdio: "inherit"
+            stdio: ["ignore", "pipe", "pipe"]
           });
-          progress.log("Package dependencies resolved successfully", "success");
         } catch (error) {
           if (isNotificationsEnabled) {
-            progress.log(`❌ CRITICAL: Package resolution failed. Firebase dependencies required for notifications could not be resolved.`, "error");
+            progress.log(`CRITICAL: Package resolution failed. Firebase dependencies required for notifications could not be resolved.`, "error");
             throw new Error(`Package resolution failed: ${error.message}. This is required when notifications are enabled.`);
           } else {
             progress.log(`Warning: Package resolution may have failed: ${error.message}`, "warning");
           }
         }
       }
-      progress.log("✅ Package.swift ready", "success");
     } catch (error) {
-      progress.log(`❌ Failed to generate Package.swift: ${error.message}`, "error");
+      progress.log(`Failed to generate Package.swift: ${error.message}`, "error");
       throw error;
     }
   }
@@ -248,7 +248,7 @@ ${formatSwiftProductEntries(notificationsDependencies).join(",\n")}
       const isNotificationsEnabled = WEBVIEW_CONFIG.notifications?.enabled ?? false;
       const projectFilePath = path.join(PROJECT_DIR, `${PROJECT_NAME}.xcodeproj`, "project.pbxproj"); // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
 
-      progress.log(`🔧 Updating Xcode package dependencies (notifications: ${isNotificationsEnabled})`, "info");
+      progress.log(`Updating Xcode package dependencies (notifications: ${isNotificationsEnabled})`, "info");
       let projectContent;
       try {
         projectContent = fs.readFileSync(projectFilePath, "utf8");
@@ -265,7 +265,7 @@ ${formatSwiftProductEntries(notificationsDependencies).join(",\n")}
         projectContent = projectContent.replace(/(packageProductDependencies = \(\s*C99974332E97D56900C25611 \/\* CatalystCore \*\/,)/, `$1\n\t\t\t\t${NOTIF_PRODUCT_ID} /* CatalystNotifications */,`);
         projectContent = projectContent.replace(/(\/\* End XCSwiftPackageProductDependency section \*\/)/, `\t\t${NOTIF_PRODUCT_ID} /* CatalystNotifications */ = {\n\t\t\tisa = XCSwiftPackageProductDependency;\n\t\t\tpackage = C99974322E97D56900C25611 /* XCLocalSwiftPackageReference "." */;\n\t\t\tproductName = CatalystNotifications;\n\t\t};\n$1`);
         fs.writeFileSync(projectFilePath, projectContent, "utf8");
-        progress.log("✅ CatalystNotifications added to Xcode project", "success");
+        progress.log("CatalystNotifications added to Xcode project", "success");
       } else if (!isNotificationsEnabled && hasNotifications) {
         progress.log("Removing CatalystNotifications from Xcode project", "info");
         projectContent = projectContent.replace(/\t\t[A-F0-9]+ \/\* CatalystNotifications in Frameworks \*\/ = {isa = PBXBuildFile; productRef = [A-F0-9]+ \/\* CatalystNotifications \*\/; };\n/g, "");
@@ -273,12 +273,10 @@ ${formatSwiftProductEntries(notificationsDependencies).join(",\n")}
         projectContent = projectContent.replace(/\t\t\t\t[A-F0-9]+ \/\* CatalystNotifications \*\/,\n/g, "");
         projectContent = projectContent.replace(/\t\t[A-F0-9]+ \/\* CatalystNotifications \*\/ = {\n\t\t\tisa = XCSwiftPackageProductDependency;\n\t\t\tpackage = [A-F0-9]+ \/\* XCLocalSwiftPackageReference "." \*\/;\n\t\t\tproductName = CatalystNotifications;\n\t\t};\n/g, "");
         fs.writeFileSync(projectFilePath, projectContent, "utf8");
-        progress.log("✅ CatalystNotifications removed from Xcode project", "success");
-      } else {
-        progress.log("Package dependencies already correct", "info");
+        progress.log("CatalystNotifications removed from Xcode project", "success");
       }
     } catch (error) {
-      progress.log(`❌ Failed to update package dependencies: ${error.message}`, "error");
+      progress.log(`Failed to update package dependencies: ${error.message}`, "error");
       throw error;
     }
   }
@@ -349,7 +347,6 @@ ${formatSwiftProductEntries(notificationsDependencies).join(",\n")}
       });
       await removePluginResourcesFromXcodeProject();
       if (resources.length === 0) {
-        progress.log("No managed plugin resources to sync", "info");
         return;
       }
       for (const resource of resources) {
@@ -371,7 +368,7 @@ ${formatSwiftProductEntries(notificationsDependencies).join(",\n")}
       await addPluginResourcesToXcodeProject(resources);
       progress.log(`Synced ${resources.length} managed plugin resource(s)`, "success");
     } catch (error) {
-      progress.log(`❌ Failed to sync plugin resources: ${error.message}`, "error");
+      progress.log(`Failed to sync plugin resources: ${error.message}`, "error");
       throw error;
     }
   }

package/dist/native/internalPluginUtils.js

@@ -245,7 +245,6 @@ function discoverInternalPlugins(corePluginsRoot, log = () => {}) {
       plugins.push(parsed);
     }
   }
-  log(`Discovered ${plugins.length} internal plugin manifest(s)`, "info");
   return plugins;
 }
 function resolveInternalPluginsRoot(packageRoot) {

package/dist/native/iosnativeWebView/CoreLogic/Sources/CatalystCoreLogic/Constants/ConfigConstants.swift

@@ -51,6 +51,8 @@ public enum ConfigConstants {
     public static let splashScreenEnabled = false
     public static let splashScreenDuration: TimeInterval? = nil
     public static let splashScreenBackgroundColor = "#ffffff"
+    public static let splashScreenHtml: String? = nil
+    public static let splashScreenMinDuration: TimeInterval = 0
 
     #if canImport(UIKit)
     public static let splashScreenImageWidth: CGFloat = 400

package/dist/native/iosnativeWebView/Sources/Core/WebView/SplashHTMLView.swift

@@ -0,0 +1,31 @@
+import SwiftUI
+import WebKit
+import CatalystCoreLogic
+
+/// Decoded public/splashscreen.html, embedded as base64 by the iOS build.
+/// nil when the app has no HTML splash (or the payload can't be decoded).
+enum SplashHTML {
+    static let content: String? = ConfigConstants.splashScreenHtml
+        .flatMap { Data(base64Encoded: $0) }
+        .flatMap { String(data: $0, encoding: .utf8) }
+}
+
+/// Non-interactive, transparent WKWebView that renders the HTML splash above the native splash image.
+struct SplashHTMLView: UIViewRepresentable {
+    func makeUIView(context: Context) -> WKWebView {
+        let webView = WKWebView(frame: .zero)
+        webView.isOpaque = false
+        webView.backgroundColor = .clear
+        webView.scrollView.backgroundColor = .clear
+        webView.scrollView.isScrollEnabled = false
+        webView.scrollView.contentInsetAdjustmentBehavior = .never
+        webView.isUserInteractionEnabled = false
+
+        if let html = SplashHTML.content {
+            webView.loadHTMLString(html, baseURL: nil)
+        }
+        return webView
+    }
+
+    func updateUIView(_ uiView: WKWebView, context: Context) {}
+}

package/dist/native/iosnativeWebView/Sources/Core/WebView/SplashView.swift

@@ -30,15 +30,31 @@ public struct SplashView: View {
                         }
                     }
                 )
+                .overlay(
+                    // HTML splash from public/splashscreen.html, drawn above the native image
+                    Group {
+                        if splashViewModel.isHTMLMode {
+                            SplashHTMLView()
+                                .ignoresSafeArea(.all)
+                        }
+                    }
+                )
                 .onReceive(webViewModel.$loadingProgress) { progress in
+                    // HTML splash dismisses on the initial load only, not on progress
+                    guard !splashViewModel.isHTMLMode else { return }
                     splashViewModel.updateProgress(progress)
                 }
                 .onReceive(webViewModel.$isLoading) { isLoading in
                     // If WebView stops loading and no duration is set, dismiss splash
-                    if !isLoading && ConfigConstants.splashScreenDuration == nil {
+                    if !isLoading && ConfigConstants.splashScreenDuration == nil && !splashViewModel.isHTMLMode {
                         splashViewModel.forceDismiss()
                     }
                 }
+                .onReceive(webViewModel.$hasFinishedInitialLoad) { finished in
+                    if finished {
+                        splashViewModel.initialLoadFinished()
+                    }
+                }
         }
     }
 

package/dist/native/iosnativeWebView/Sources/Core/WebView/SplashViewModel.swift

@@ -13,13 +13,24 @@ public class SplashViewModel: ObservableObject {
     private var durationTimer: Timer?
     private var hasWebViewLoaded = false
 
+    // HTML splash (public/splashscreen.html): ignores duration and progress, dismisses after the
+    // first page load once splashScreenMinDuration has elapsed, capped at htmlSplashMaxDuration.
+    let isHTMLMode = SplashHTML.content != nil
+    private static let htmlSplashMaxDuration: TimeInterval = 10
+    private var minDurationTimer: Timer?
+
     public init() {
         logger.info("SplashViewModel initialized")
-        startDurationTimer()
+        if isHTMLMode {
+            startHTMLSplashCapTimer()
+        } else {
+            startDurationTimer()
+        }
     }
 
     deinit {
         durationTimer?.invalidate()
+        minDurationTimer?.invalidate()
     }
 
     private func startDurationTimer() {
@@ -39,6 +50,33 @@ public class SplashViewModel: ObservableObject {
         }
     }
 
+    private func startHTMLSplashCapTimer() {
+        logger.info("HTML splash: waiting for initial page load (cap \(Self.htmlSplashMaxDuration) seconds)")
+
+        durationTimer = Timer.scheduledTimer(withTimeInterval: Self.htmlSplashMaxDuration, repeats: false) { [weak self] _ in
+            DispatchQueue.main.async {
+                self?.dismissSplash()
+            }
+        }
+    }
+
+    func initialLoadFinished() {
+        guard isHTMLMode, shouldShowSplash, minDurationTimer == nil else { return }
+
+        let remaining = ConfigConstants.splashScreenMinDuration - Date().timeIntervalSince(startTime)
+        guard remaining > 0 else {
+            dismissSplash()
+            return
+        }
+
+        logger.info("HTML splash: initial load finished, holding for \(remaining) seconds")
+        minDurationTimer = Timer.scheduledTimer(withTimeInterval: remaining, repeats: false) { [weak self] _ in
+            DispatchQueue.main.async {
+                self?.dismissSplash()
+            }
+        }
+    }
+
     func updateProgress(_ progress: Double) {
         logger.debug("WebView progress updated: \(progress)")
 
@@ -73,6 +111,8 @@ public class SplashViewModel: ObservableObject {
 
         durationTimer?.invalidate()
         durationTimer = nil
+        minDurationTimer?.invalidate()
+        minDurationTimer = nil
 
         withAnimation(.easeOut(duration: 0.3)) {
             shouldShowSplash = false

package/dist/native/iosnativeWebView/Sources/Core/WebView/WebViewModel.swift

@@ -12,6 +12,8 @@ public class WebViewModel: ObservableObject {
     @Published public var loadingProgress: Double = 0.0
     @Published public var lastLoadedURL: URL?
     @Published public var isLoadingFromCache: Bool = false
+    // One-shot: true after the first page (or offline page) finishes loading; never reset
+    @Published public var hasFinishedInitialLoad = false
 
     // Safe area insets
     @Published public var safeAreaInsets: SafeAreaInsets = .zero

package/dist/native/iosnativeWebView/Sources/Core/WebView/WebViewNavigationDelegate.swift

@@ -339,6 +339,9 @@ class WebViewNavigationDelegate: NSObject, WKNavigationDelegate {
                 viewModel.canGoBack = webView.canGoBack
                 viewModel.setLoading(false, fromCache: false)
             }
+            if !viewModel.hasFinishedInitialLoad {
+                viewModel.hasFinishedInitialLoad = true
+            }
         }
     }
 

package/dist/native/pluginComposerAndroid.js

@@ -226,7 +226,7 @@ function copyAndroidPluginSources(plugins, javaRoot, log) {
   }
   log(`Copied ${copiedCount} Android plugin source file(s)`, "info");
 }
-function copyPluginAssets(plugins, androidProjectPath, log) {
+function copyPluginAssets(plugins, androidProjectPath) {
   // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - The destination path components are fixed.
   const baseAssetsDir = path.join(androidProjectPath, "app", "src", "main", "assets", "plugins");
   fs.rmSync(baseAssetsDir, {
@@ -242,7 +242,6 @@ function copyPluginAssets(plugins, androidProjectPath, log) {
     // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - These are fixed asset directories beneath the discovered internal plugin directory.
     copyTree(path.join(plugin.pluginDir, "assets", "android"), path.join(pluginAssetsDir, "android"));
   }
-  log("Plugin assets copied to app/src/main/assets/plugins", "info");
 }
 function formatKotlinMap(entries, emptyLiteral = "emptyMap()") {
   return entries.length === 0 ? emptyLiteral : `mapOf(\n${entries.join(",\n")}\n    )`;
@@ -396,7 +395,7 @@ function composeAndroidPlugins({
   // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - These are fixed paths within the generated Android project.
   const proguardPath = path.join(androidProjectPath, "app", "proguard-rules.pro");
   copyAndroidPluginSources(selected, javaRoot, log);
-  copyPluginAssets(selected, androidProjectPath, log);
+  copyPluginAssets(selected, androidProjectPath);
   generatePluginRegistryFiles(selected, javaRoot);
   updateAndroidManifestPermissions(manifestPath, selected.flatMap(plugin => plugin.android?.permissions || []), discovered.flatMap(plugin => plugin.android?.permissions || []));
   updateGradleDependencies(gradlePath, selected.flatMap(plugin => plugin.android?.dependencies || []), discovered.flatMap(plugin => plugin.android?.dependencies || []));