catalyst-core 1.0.1 → 1.0.2-canary.2

package/dist/cli/theme.js

@@ -0,0 +1,155 @@
+"use strict"
+
+const os = require("os")
+const path = require("path")
+const pc = require("ansis")
+
+/**
+ * The one visual language shared by every Catalyst command.
+ *
+ * Rules, so anything added later still looks like it belongs:
+ *   - One accent (cyan) for identity and links. Green, red and yellow carry
+ *     state only, never decoration.
+ *   - Single-width glyphs, never emoji. Emoji render double-width in some
+ *     terminals, which breaks every column that follows them.
+ *   - Dim is structure: rules, labels and paths recede so the one thing that
+ *     matters on a line is the bright one.
+ *   - Every line starts at the same gutter, so output reads as a column.
+ *
+ * Authored as CommonJS because src/native/ ships as CJS (see
+ * src/native/package.json) while src/scripts/ is ESM -- CJS is the only form
+ * both halves can consume.
+ */
+
+// Colour codes sit in front of text, so anything that matches against output
+// must strip them first. Defined once here rather than per-module.
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g")
+
+const GUTTER = "  "
+
+const glyph = {
+    pending: "○",
+    running: "◐",
+    done: "✓",
+    fail: "✗",
+    warn: "▲",
+    info: "•",
+    arrow: "›",
+    branch: "├",
+    last: "└",
+    pipe: "│",
+    rule: "─",
+}
+
+// Frames for the running indicator. Braille spinners look busier than they
+// read; these four are calm and legible at any width.
+const SPINNER_FRAMES = ["◐", "◓", "◑", "◒"]
+
+const t = {
+    accent: pc.cyan,
+    dim: pc.gray,
+    ok: pc.green,
+    bad: pc.red,
+    warn: pc.yellow,
+    bold: pc.bold,
+}
+
+/**
+ * True when we may draw in place: a real terminal, not a pipe, not CI.
+ * Vite's gate, so the web and native commands agree on what "interactive"
+ * means. ansis independently handles NO_COLOR/FORCE_COLOR/TERM=dumb.
+ */
+function isInteractive(stream = process.stdout) {
+    return Boolean(stream.isTTY && !process.env.CI)
+}
+
+/**
+ * True when the user asked for more detail: `--verbose`/`--debug` on this
+ * process, or CATALYST_OUTPUT_MODE forwarded by a parent that saw them. The
+ * default view keeps only what someone acts on; the rest is here.
+ */
+function isVerbose(argv = process.argv, env = process.env) {
+    if (argv.includes("--verbose") || argv.includes("--debug")) return true
+    return env.CATALYST_OUTPUT_MODE === "verbose" || env.CATALYST_OUTPUT_MODE === "debug"
+}
+
+let cachedVersion
+/** catalyst-core's own version: ../../package.json from both src/cli and dist/cli. */
+function version() {
+    if (cachedVersion === undefined) {
+        try {
+            cachedVersion = require("../../package.json").version || null
+        } catch (error) {
+            cachedVersion = null
+        }
+    }
+    return cachedVersion
+}
+
+/** The titled rule every command opens with: `catalyst build v1.0.1 › production`. */
+function header(title, subtitle) {
+    const v = version()
+    const line =
+        `${t.bold(t.accent(title))}` +
+        `${v ? t.dim(` v${v}`) : ""}` +
+        `${subtitle ? t.dim(`  ${glyph.arrow}  ${subtitle}`) : ""}`
+    return `\n${GUTTER}${line}\n${GUTTER}${t.dim(glyph.rule.repeat(46))}\n`
+}
+
+/** A dim-key / bright-value row, values column-aligned. */
+function row(key, value, width = 9) {
+    return `${GUTTER}${t.dim(key.padEnd(width))}${value}`
+}
+
+function duration(ms) {
+    if (ms < 1000) return `${ms}ms`
+    if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`
+    return `${Math.floor(ms / 60000)}m ${Math.round((ms % 60000) / 1000)}s`
+}
+
+/**
+ * A path as a person would type it: relative to the app when inside it,
+ * `~/...` when under home, absolute otherwise. Absolute paths into DerivedData
+ * or node_modules pushed the useful tail off the edge of the terminal.
+ */
+function displayPath(file, root = process.cwd()) {
+    if (!file) return file
+    const relative = path.relative(root, file)
+    if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) return relative
+    const home = os.homedir()
+    return file.startsWith(home) ? `~${file.slice(home.length)}` : file
+}
+
+function bytes(n) {
+    if (n < 1024) return `${n} B`
+    if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} kB`
+    return `${(n / 1024 / 1024).toFixed(2)} MB`
+}
+
+// Below this a timing is noise: "0ms" next to a step says nothing a reader
+// can use, and a column of them hides the one step that was actually slow.
+const MIN_SHOWN_MS = 100
+
+/** A completed step: `✓ Label  1.2s` */
+function step(label, ms, state = "done") {
+    const mark =
+        state === "fail" ? t.bad(glyph.fail) : state === "warn" ? t.warn(glyph.warn) : t.ok(glyph.done)
+    return `${GUTTER}${mark} ${label}${ms == null || ms < MIN_SHOWN_MS ? "" : `  ${t.dim(duration(ms))}`}`
+}
+
+module.exports = {
+    ANSI,
+    GUTTER,
+    glyph,
+    SPINNER_FRAMES,
+    t,
+    isInteractive,
+    isVerbose,
+    version,
+    header,
+    row,
+    duration,
+    bytes,
+    displayPath,
+    step,
+}

package/dist/errors/index.js

@@ -138,7 +138,11 @@ const BOX_WIDTH = 70
 function box(bodyLines) {
     const top = pc.red(`┌${"─".repeat(BOX_WIDTH)}`)
     const bottom = pc.red(`└${"─".repeat(BOX_WIDTH)}`)
-    const body = bodyLines.map((line) => (line === "" ? pc.red("│") : `${pc.red("│")} ${line}`))
+    // A multi-line entry (details listing several values) keeps the border on
+    // every line instead of spilling out of the box.
+    const body = bodyLines
+        .flatMap((line) => String(line).split("\n"))
+        .map((line) => (line === "" ? pc.red("│") : `${pc.red("│")} ${line}`))
     return [top, ...body, bottom].join("\n")
 }
 
@@ -163,7 +167,7 @@ function formatCauseChain(cause) {
  */
 function formatVerbose(err) {
     const lines = [
-        pc.bold(`❌ ${err.message}`),
+        pc.bold(err.message),
         `Code: ${err.code}`,
         `Category: ${err.category || "UNKNOWN"}`,
         `Time: ${new Date().toISOString()}`,
@@ -193,7 +197,7 @@ function formatVerbose(err) {
  */
 function formatDebug(err, env) {
     const lines = [
-        pc.bold(`❌ ${err.message}`),
+        pc.bold(err.message),
         `Code: ${err.code}`,
         `Category: ${err.category || "UNKNOWN"}`,
         `Time: ${new Date().toISOString()}`,

package/dist/errors/registry.js

@@ -22,6 +22,7 @@ export const ERROR_CODES = {
     PREFLIGHT_GET_ROUTES_NOT_FUNCTION: "PREFLIGHT-019",
     PREFLIGHT_CUSTOM_DOCUMENT_MISSING: "PREFLIGHT-020",
     PREFLIGHT_CUSTOM_DOCUMENT_NOT_FUNCTION: "PREFLIGHT-021",
+    PREFLIGHT_BUILD_STALE: "PREFLIGHT-022",
 
     PROCESS_SERVER_INIT_FAILED: "PROCESS-001",
     PROCESS_USER_HOOK_FAILED: "PROCESS-002",
@@ -204,6 +205,13 @@ export const ERROR_DEFINITIONS = {
         defaultDetails: "document was found but is not a function/component.",
         suggestedAction: "Ensure document is exported as a React component (function).",
     },
+    [ERROR_CODES.PREFLIGHT_BUILD_STALE]: {
+        category: "PREFLIGHT",
+        defaultMessage: "The build is stale: config/config.json changed since it was built",
+        defaultDetails:
+            "PUBLIC_STATIC_ASSET_URL, PUBLIC_STATIC_ASSET_PATH and the CLIENT_ENV_VARIABLES values are inlined into the bundles at build time, so serving this build would use the old values.",
+        suggestedAction: "Run `npm run build` again, then `npm run serve`.",
+    },
 
     [ERROR_CODES.PROCESS_SERVER_INIT_FAILED]: {
         category: "PROCESS",

package/dist/errors-index.json

@@ -216,6 +216,13 @@
         "suggestedAction": "Ensure document is exported as a React component (function).",
         "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/PREFLIGHT/PREFLIGHT-021.md"
     },
+    "PREFLIGHT-022": {
+        "category": "PREFLIGHT",
+        "message": "The build is stale: config/config.json changed since it was built",
+        "details": "PUBLIC_STATIC_ASSET_URL, PUBLIC_STATIC_ASSET_PATH and the CLIENT_ENV_VARIABLES values are inlined into the bundles at build time, so serving this build would use the old values.",
+        "suggestedAction": "Run `npm run build` again, then `npm run serve`.",
+        "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/PREFLIGHT/PREFLIGHT-022.md"
+    },
     "PROCESS-001": {
         "category": "PROCESS",
         "message": "preServerInit threw an error during server startup",

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { RouterDataProvider, useCurrentRouteData, useRouterData, } from "./web-router/components/RouterDataProvider.jsx";
+export { RouterDataProvider, useCurrentRouteData, useRouterData, useRouterState, } from "./web-router/components/RouterDataProvider.jsx";
 export { MetaTag } from "./web-router/components/MetaTag.jsx";
 export { split, hydrationReady } from "./web-router/components/Split.jsx";
 export { Head } from "./server/renderer/document/Head.jsx";

package/dist/index.jsx

@@ -1,4 +1,4 @@
-export { RouterDataProvider, useCurrentRouteData, useRouterData } from "./web-router/components/RouterDataProvider.jsx";
+export { RouterDataProvider, useCurrentRouteData, useRouterData, useRouterState } from "./web-router/components/RouterDataProvider.jsx";
 export { MetaTag } from "./web-router/components/MetaTag.jsx";
 export { split, hydrationReady } from "./web-router/components/Split.jsx";
 export { Head } from "./server/renderer/document/Head.jsx";

package/dist/logger.js

@@ -13,6 +13,55 @@ const { createLogger, format, transports } = winston
  * @returns loggerInstance
  *
  */
+/**
+ * Render a log argument as text.
+ *
+ * JSON.stringify was wrong in two ways that mattered: an Error serializes to
+ * "{}" (message and stack are non-enumerable), so error logs said nothing at
+ * all, and a circular reference made the logger itself throw -- turning a
+ * logged problem into a crash.
+ */
+function formatLogMessage(msg) {
+    if (typeof msg === "string") return msg
+    if (msg instanceof Error) return msg.stack || `${msg.name}: ${msg.message}`
+
+    try {
+        const seen = new WeakSet()
+        const text = JSON.stringify(msg, (key, value) => {
+            if (value instanceof Error) return value.stack || `${value.name}: ${value.message}`
+            if (typeof value === "bigint") return value.toString()
+            if (typeof value === "object" && value !== null) {
+                if (seen.has(value)) return "[Circular]"
+                seen.add(value)
+            }
+            return value
+        })
+        // stringify returns undefined for functions and symbols.
+        return text === undefined ? String(msg) : text
+    } catch (error) {
+        return String(msg)
+    }
+}
+
+/**
+ * What winston receives for a log argument.
+ *
+ * A plain object goes in as an object, so file logs keep its fields
+ * queryable rather than nesting it as one escaped string under "message".
+ * It is a clone built from the console text -- cycle-safe, Errors as their
+ * stack -- which also keeps winston from writing level and timestamp onto the
+ * caller's own object. Strings, Errors and anything else go in as text.
+ */
+function toLogRecord(msg, text) {
+    if (msg === null || typeof msg !== "object" || Array.isArray(msg) || msg instanceof Error) return text
+    try {
+        const record = JSON.parse(text)
+        return record !== null && typeof record === "object" && !Array.isArray(record) ? record : text
+    } catch (error) {
+        return text
+    }
+}
+
 const configureLogger = (config = {}) => {
     const { enableDebugLogs = true, enableFileLogging = true, enableConsoleLogging = true } = config
 
@@ -55,22 +104,28 @@ const configureLogger = (config = {}) => {
         errorLogger.add(fileTransport("error"))
     }
 
+    // Winston serializes with format.json(), which renders an Error as {} for
+    // the same reason JSON.stringify does, so it gets the formatted text for
+    // those -- and a safe structured copy of a plain object (toLogRecord).
     const Logger = {
         debug: () => {},
         error: (msg) => {
-            console.log(pc.red(pc.bold("ERROR: " + JSON.stringify(msg))))
-            errorLogger.error(msg)
+            const text = formatLogMessage(msg)
+            console.log(pc.red(pc.bold("ERROR: " + text)))
+            errorLogger.error(toLogRecord(msg, text))
         },
         info: (msg) => {
-            console.log(pc.green(pc.bold("INFO: " + JSON.stringify(msg))))
-            infoLogger.info(msg)
+            const text = formatLogMessage(msg)
+            console.log(pc.green(pc.bold("INFO: " + text)))
+            infoLogger.info(toLogRecord(msg, text))
         },
     }
 
     if (enableDebugLogs && JSON.parse(enableDebugLogs)) {
         Logger.debug = (msg) => {
-            console.log(pc.yellow(pc.bold("DEBUG: " + JSON.stringify(msg))))
-            debugLogger.debug(msg)
+            const text = formatLogMessage(msg)
+            console.log(pc.yellow(pc.bold("DEBUG: " + text)))
+            debugLogger.debug(toLogRecord(msg, text))
         }
     }
 

package/dist/native/androidProject/app/build.gradle.kts

@@ -379,7 +379,8 @@ tasks.register<JacocoReport>("jacocoTestReport") {
         // so a plain "$*" is safe here.
         "**/CustomWebView.class", "**/CustomWebView\$*.class", "**/CustomWebViewKt.class",
         "**/MainActivity.class", "**/MainActivity\$*.class",
-        "**/SplashActivity.class", "**/SplashActivity\$*.class",
+        "**/SplashActivity.class", "**/SplashActivity\$*.class", "**/SplashActivityKt.class",
+        "**/SplashOverlay.class", "**/SplashOverlay\$*.class",
         "**/NativeCameraManager.class", "**/NativeCameraManager\$*.class",
         "**/camera/CameraSessionManager.class", "**/camera/CameraSessionManager\$*.class",
         "**/TransitionManager.class", "**/TransitionManager\$*.class",

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/CustomWebview.kt

@@ -68,6 +68,7 @@ class CustomWebView(
     private var visibleOfflineSnapshotUrl: String? = null
     @Volatile private var defaultRequestHeaders: Map<String, String> = emptyMap()
     var onPageStarted: (() -> Unit)? = null
+    var onInitialPageLoaded: (() -> Unit)? = null
 
     // Counters for asset loading statistics
     private var assetLoadAttempts = 0
@@ -1142,6 +1143,7 @@ class CustomWebView(
                 if(!isInitialPageLoaded){
                     isInitialPageLoaded = true
                     metricsMonitor.markAppStartComplete()
+                    onInitialPageLoaded?.invoke()
                 }
                 url?.let { metricsMonitor.trackPageLoadEnd(it) }
 

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/MainActivity.kt

@@ -52,6 +52,7 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
     private var currentUrl: String = ""
     private var edgeToEdgeEnabled = false
     private var latestSafeAreaInsets: SafeAreaInsets = SafeAreaInsets.ZERO
+    private var splashOverlay: SplashOverlay? = null
 
     private fun enableHardwareAcceleration() {
         if (!isHardwareAccelerationEnabled) {
@@ -319,6 +320,11 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
         binding = ActivityMainBinding.inflate(layoutInflater)
         supportActionBar?.hide()
         setContentView(binding.root)
+
+        // HTML splash handed off from SplashActivity (fresh launch only)
+        if (savedInstanceState == null && intent.getBooleanExtra(SplashActivity.EXTRA_HTML_SPLASH, false)) {
+            splashOverlay = SplashOverlay(this, properties).also { it.show() }
+        }
         
         // Initialize keyboard utility (pass webView so keyboard events reach WebPerfCollector)
         keyboardUtil = KeyboardUtil(this, binding.webviewContainer, binding.webview, edgeToEdgeEnabled)
@@ -334,6 +340,7 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
             progressBar = binding.progress,
             properties = properties
         )
+        customWebView.onInitialPageLoaded = { splashOverlay?.onMainPageLoaded() }
 
         // Handle state restoration
         if (savedInstanceState == null) {
@@ -482,6 +489,8 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
     }
 
     override fun onDestroy() {
+        splashOverlay?.release()
+        splashOverlay = null
         io.yourname.androidproject.utils.PerfEventBuffer.reset()
         // Log all performance metrics before destroying
         if (BuildConfig.DEBUG) {

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/SplashActivity.kt

@@ -1,6 +1,7 @@
 package io.yourname.androidproject
 
 import android.app.Activity
+import android.content.Context
 import android.content.Intent
 import android.graphics.Color
 import android.os.Build
@@ -18,6 +19,11 @@ import java.util.Properties
 
 class SplashActivity : AppCompatActivity() {
 
+    companion object {
+        const val EXTRA_HTML_SPLASH = "io.yourname.androidproject.EXTRA_HTML_SPLASH"
+        const val HTML_SPLASH_ASSET = "splash/splashscreen.html"
+    }
+
     private lateinit var binding: ActivitySplashBinding
     private lateinit var properties: Properties
     private var isFinishing = false
@@ -38,50 +44,40 @@ class SplashActivity : AppCompatActivity() {
             return
         }
 
+        // HTML splash: forward straight to MainActivity without drawing, so the system starting
+        // window stays up until MainActivity draws the image + HTML overlay (no gap between two
+        // drawn activities)
+        if (hasHtmlSplash()) {
+            startHtmlSplashMainActivity()
+            return
+        }
+
         if (EdgeToEdgeUtils.isEnabled(properties)) {
             EdgeToEdgeUtils.apply(this, properties)
         }
 
         binding = ActivitySplashBinding.inflate(layoutInflater)
         setContentView(binding.root)
-        
-        configureSplashScreen()
+
+        configureSplashScreen(this, binding, properties)
         startSplashTimer()
     }
 
-    private fun configureSplashScreen() {
-        val backgroundColor = properties.getProperty("splashScreen.backgroundColor", "#ffffff")
-        val imageWidth = properties.getProperty("splashScreen.imageWidth", "120").toIntOrNull() ?: 120
-        val imageHeight = properties.getProperty("splashScreen.imageHeight", "120").toIntOrNull() ?: 120
-        val cornerRadius = properties.getProperty("splashScreen.cornerRadius", "20").toFloatOrNull() ?: 20f
-
-        try {
-            binding.splashContainer.setBackgroundColor(Color.parseColor(backgroundColor))
-        } catch (e: Exception) {
-            binding.splashContainer.setBackgroundColor(Color.WHITE)
-        }
-
-        val widthPx = TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, imageWidth.toFloat(), resources.displayMetrics).toInt()
-        val heightPx = TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, imageHeight.toFloat(), resources.displayMetrics).toInt()
-
-        binding.splashImage.layoutParams.apply {
-            width = widthPx
-            height = heightPx
-        }
-
-        val drawable = ContextCompat.getDrawable(this, 
-            resources.getIdentifier("splashscreen", "drawable", packageName).takeIf { it != 0 } 
-                ?: R.mipmap.ic_launcher
-        ) ?: return
+    private fun hasHtmlSplash(): Boolean = try {
+        assets.open(HTML_SPLASH_ASSET).close()
+        true
+    } catch (e: Exception) {
+        false
+    }
 
-        if (cornerRadius > 0) {
-            val radiusPx = TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, cornerRadius, resources.displayMetrics)
-            val roundedDrawable = RoundedBitmapDrawableFactory.create(resources, drawable.toBitmap(widthPx, heightPx))
-            roundedDrawable.cornerRadius = radiusPx
-            binding.splashImage.setImageDrawable(roundedDrawable)
-        } else {
-            binding.splashImage.setImageDrawable(drawable)
-        }
+    private fun startHtmlSplashMainActivity() {
+        isFinishing = true
+        startActivity(
+            Intent(this, MainActivity::class.java)
+                .putExtra(EXTRA_HTML_SPLASH, true)
+                .addFlags(Intent.FLAG_ACTIVITY_NO_ANIMATION)
+        )
+        finish()
     }
 
     private fun startSplashTimer() {
@@ -114,3 +110,38 @@ class SplashActivity : AppCompatActivity() {
         finish()
     }
 }
+
+internal fun configureSplashScreen(context: Context, binding: ActivitySplashBinding, properties: Properties) {
+    val backgroundColor = properties.getProperty("splashScreen.backgroundColor", "#ffffff")
+    val imageWidth = properties.getProperty("splashScreen.imageWidth", "120").toIntOrNull() ?: 120
+    val imageHeight = properties.getProperty("splashScreen.imageHeight", "120").toIntOrNull() ?: 120
+    val cornerRadius = properties.getProperty("splashScreen.cornerRadius", "20").toFloatOrNull() ?: 20f
+
+    try {
+        binding.splashContainer.setBackgroundColor(Color.parseColor(backgroundColor))
+    } catch (e: Exception) {
+        binding.splashContainer.setBackgroundColor(Color.WHITE)
+    }
+
+    val widthPx = TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, imageWidth.toFloat(), context.resources.displayMetrics).toInt()
+    val heightPx = TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, imageHeight.toFloat(), context.resources.displayMetrics).toInt()
+
+    binding.splashImage.layoutParams.apply {
+        width = widthPx
+        height = heightPx
+    }
+
+    val drawable = ContextCompat.getDrawable(context, 
+        context.resources.getIdentifier("splashscreen", "drawable", context.packageName).takeIf { it != 0 } 
+            ?: R.mipmap.ic_launcher
+    ) ?: return
+
+    if (cornerRadius > 0) {
+        val radiusPx = TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, cornerRadius, context.resources.displayMetrics)
+        val roundedDrawable = RoundedBitmapDrawableFactory.create(context.resources, drawable.toBitmap(widthPx, heightPx))
+        roundedDrawable.cornerRadius = radiusPx
+        binding.splashImage.setImageDrawable(roundedDrawable)
+    } else {
+        binding.splashImage.setImageDrawable(drawable)
+    }
+}

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/SplashOverlay.kt

@@ -0,0 +1,109 @@
+package io.yourname.androidproject
+
+import android.annotation.SuppressLint
+import android.app.Activity
+import android.graphics.Color
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+import android.view.ViewGroup
+import android.webkit.WebView
+import android.webkit.WebViewClient
+import android.widget.FrameLayout
+import io.yourname.androidproject.databinding.ActivitySplashBinding
+import java.util.Properties
+
+/**
+ * HTML splash shown above the main WebView until its first page finishes,
+ * held for at least splashScreen.minDuration ms and capped at MAX_DURATION_MS.
+ */
+class SplashOverlay(private val activity: Activity, private val properties: Properties) {
+
+    companion object {
+        private const val MAX_DURATION_MS = 10_000L
+        private const val FADE_DURATION_MS = 300L
+    }
+
+    private val handler = Handler(Looper.getMainLooper())
+    private val minDuration = properties.getProperty("splashScreen.minDuration")?.toLongOrNull() ?: 0
+    private var root: FrameLayout? = null
+    private var webView: WebView? = null
+    private var shownAt = 0L
+    private var dismissed = false
+
+    @SuppressLint("SetJavaScriptEnabled")
+    fun show() {
+        val splashBinding = ActivitySplashBinding.inflate(activity.layoutInflater)
+        configureSplashScreen(activity, splashBinding, properties)
+
+        // No JS interfaces; only the bundled asset may load
+        val splashWebView = WebView(activity).apply {
+            settings.javaScriptEnabled = true
+            settings.blockNetworkLoads = true
+            settings.allowFileAccess = false
+            settings.allowContentAccess = false
+            setBackgroundColor(Color.TRANSPARENT)
+            // Chromium paints the page background before its content, so keep the native image
+            // in view until the HTML's first frame with content is on screen
+            alpha = 0f
+            webViewClient = object : WebViewClient() {
+                override fun onPageFinished(view: WebView, url: String?) {
+                    view.postVisualStateCallback(0, object : WebView.VisualStateCallback() {
+                        override fun onComplete(requestId: Long) {
+                            view.alpha = 1f
+                        }
+                    })
+                }
+            }
+            loadUrl("file:///android_asset/${SplashActivity.HTML_SPLASH_ASSET}")
+        }
+        val matchParent = ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)
+        val overlayRoot = FrameLayout(activity).apply {
+            addView(splashBinding.root, matchParent)
+            addView(splashWebView, matchParent)
+            // Swallow touches so they don't reach the main WebView underneath
+            isClickable = true
+            isFocusable = true
+        }
+
+        activity.addContentView(overlayRoot, matchParent)
+
+        root = overlayRoot
+        webView = splashWebView
+        shownAt = SystemClock.elapsedRealtime()
+        handler.postDelayed({ dismiss() }, MAX_DURATION_MS)
+    }
+
+    fun onMainPageLoaded() {
+        if (dismissed) return
+        val remaining = minDuration - (SystemClock.elapsedRealtime() - shownAt)
+        handler.postDelayed({ dismiss() }, remaining.coerceAtLeast(0))
+    }
+
+    private fun dismiss() {
+        if (dismissed) return
+        dismissed = true
+        handler.removeCallbacksAndMessages(null)
+        val overlayRoot = root ?: return
+        overlayRoot.animate()
+            .alpha(0f)
+            .setDuration(FADE_DURATION_MS)
+            .withEndAction { destroy() }
+            .start()
+    }
+
+    fun release() {
+        dismissed = true
+        handler.removeCallbacksAndMessages(null)
+        root?.animate()?.cancel()
+        destroy()
+    }
+
+    private fun destroy() {
+        val overlayRoot = root ?: return
+        (overlayRoot.parent as? ViewGroup)?.removeView(overlayRoot)
+        webView?.destroy()
+        webView = null
+        root = null
+    }
+}