From c51ddb3d6eae5daf088559982ac7698dfa78356d Mon Sep 17 00:00:00 2001
From: Shai Almog <67850168+shai-almog@users.noreply.github.com>
Date: Wed, 28 Oct 2026 14:54:45 +0200
Subject: [PATCH 1/5] JavaScript port: loading screen with the app icon and
 light/dark colours (#6117)

Build hints javascript.splash.* set the colours, appearance mode and logo;
the theme is written into <head> so a dark app never opens on white, and
platformHint.javascript.splashAppearance remembers the app's own choice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../impl/html5/HTML5Implementation.java       |  28 +++
 .../impl/html5/JSOImplementations.java        |  11 ++
 .../working-with-javascript.html              |   9 -
 .../Working-With-Javascript.asciidoc          |  38 +++-
 .../builders/JavaScriptBuildHints.java        |  26 +++
 .../builders/JavaScriptBuildHintsTest.java    |  23 +++
 .../build/shared/BuildHintsDesktop.java       |  72 ++++++++
 .../translator/JavascriptBundleWriter.java    | 169 ++++++++++++++++++
 .../src/javascript/index.html                 |  38 +++-
 .../JavascriptPageSettingsTest.java           |  52 ++++++
 10 files changed, 450 insertions(+), 16 deletions(-)

diff --git a/Ports/JavaScriptPort/src/main/java/com/codename1/impl/html5/HTML5Implementation.java b/Ports/JavaScriptPort/src/main/java/com/codename1/impl/html5/HTML5Implementation.java
index 7b53f4effe7..e2c0528d312 100644
--- a/Ports/JavaScriptPort/src/main/java/com/codename1/impl/html5/HTML5Implementation.java
+++ b/Ports/JavaScriptPort/src/main/java/com/codename1/impl/html5/HTML5Implementation.java
@@ -5349,6 +5349,31 @@ private JavaScriptRuntimeEnvironment createRuntimeEnvironment(final WindowExt wi
         );
     }
 
+    /// Remembers the application's light/dark choice for the loading screen of the NEXT launch:
+    /// `light` or `dark`, or null/anything else to follow the browser again. The page reads the
+    /// key in `<head>` before any Java runs (`JavascriptBundleWriter.splashTheme` in the
+    /// ByteCodeTranslator, which also names the key); a build whose `javascript.splash.appearance`
+    /// is `light` or `dark` ignores it.
+    private static void setSplashAppearance(String value) {
+        // The cast stays outside the try: a CHECKCAST is unchecked on ParparVM, so a handler
+        // around it would never run (scripts/check-cast-semantics.sh).
+        WindowExt win = (WindowExt) Window.current();
+        try {
+            JSOImplementations.JSStorage storage = win.getLocalStorage();
+            if (storage == null) {
+                return;
+            }
+            if ("light".equals(value) || "dark".equals(value)) {
+                storage.setItem("cn1.splashAppearance", value);
+            } else {
+                storage.removeItem("cn1.splashAppearance");
+            }
+        } catch (RuntimeException e) {
+            // Storage disabled (private mode, a sandboxed frame): the splash follows the browser.
+            Log.e(e);
+        }
+    }
+
     @JSBody(params={"msg"}, script="window.onbeforeunload=function(){return msg;}")
     private native static void setBeforeUnloadMessage(String msg);
     
@@ -5357,6 +5382,9 @@ private JavaScriptRuntimeEnvironment createRuntimeEnvironment(final WindowExt wi
     
     @Override
     public void setPlatformHint(String key, String value) {
+        if ("platformHint.javascript.splashAppearance".equalsIgnoreCase(key)) {
+            setSplashAppearance(value);
+        }
         if ("platformHint.javascript.beforeUnloadMessage".equalsIgnoreCase(key)) {
             if (value == null) {
                 removeBeforeUnload();
diff --git a/Ports/JavaScriptPort/src/main/java/com/codename1/impl/html5/JSOImplementations.java b/Ports/JavaScriptPort/src/main/java/com/codename1/impl/html5/JSOImplementations.java
index 0147e4d636e..adaeba3d29d 100644
--- a/Ports/JavaScriptPort/src/main/java/com/codename1/impl/html5/JSOImplementations.java
+++ b/Ports/JavaScriptPort/src/main/java/com/codename1/impl/html5/JSOImplementations.java
@@ -66,7 +66,18 @@ public interface JSFontMetrics extends JSObject {
         JSObject getBounds();
     }
     
+    /// The page's `window.localStorage`, for the few values the page itself reads before any
+    /// Java runs (the loading screen's remembered appearance).
+    public interface JSStorage extends JSObject {
+        void setItem(String key, String value);
+
+        void removeItem(String key);
+    }
+
     public interface WindowExt extends JSObject {
+
+        @JSProperty
+        abstract JSStorage getLocalStorage();
         
         
         @JSProperty
diff --git a/docs/demos/javascript/src/main/snippets/developer-guide/working-with-javascript.html b/docs/demos/javascript/src/main/snippets/developer-guide/working-with-javascript.html
index 093262deb4f..551391157dd 100644
--- a/docs/demos/javascript/src/main/snippets/developer-guide/working-with-javascript.html
+++ b/docs/demos/javascript/src/main/snippets/developer-guide/working-with-javascript.html
@@ -1,14 +1,5 @@
 // Generated from docs/developer-guide source blocks. Edit the guide snippets here, not inline.
 
-// tag::working-with-javascript-html-001[]
-<div id="cn1-splash">
-    <img class="icon" src="icon.png"/>
-
-    <img class="progress" src="progress.gif"/>
-    <p>...Loading...</p>
-</div>
-// end::working-with-javascript-html-001[]
-
 // tag::working-with-javascript-html-002[]
 <script src="//maps.googleapis.com/maps/api/js?v=3.exp&key=XYZ"></script>
 // end::working-with-javascript-html-002[]
diff --git a/docs/developer-guide/Working-With-Javascript.asciidoc b/docs/developer-guide/Working-With-Javascript.asciidoc
index a489cc6c3d1..65daf2ce0a1 100644
--- a/docs/developer-guide/Working-With-Javascript.asciidoc
+++ b/docs/developer-guide/Working-With-Javascript.asciidoc
@@ -262,15 +262,45 @@ This tells Apache to proxy all requests for '/app' to the domain https://www.mye
 [id="splash_screen", reftext="Customizing the Splash Screen"]
 === Customizing the splash screen
 
-Since your application may include many resource files, videos, etc., the build-server will generate a splash screen for your app to display while it's loading. This basically shows a progress indicator with your app's icon.
+While the application downloads and starts, the page shows a loading screen: the app icon, an animated progress bar and a "Loading" label. It stays up until the first form is shown.
 
-You can customize this splash screen by modifying the HTML source inside the *cn1-splash* `div` tag of your app's index.html file:
+Build hints set its look, so the settings survive every build instead of being edited into each generated bundle:
 
-[source,html]
+[cols="1,1,3",options="header"]
+|===
+|Build hint |Default |Meaning
+
+|`javascript.splash.appearance`
+|`auto`
+|`auto` follows the browser's light/dark preference. `light` or `dark` always uses that set of colors, for an app with a single appearance.
+
+|`javascript.splash.background`, `javascript.splash.textColor`, `javascript.splash.accentColor`
+|`#ffffff`, `#666666`, `#0072ff`
+|The page background, the label and the progress bar in the light appearance.
+
+|`javascript.splash.darkBackground`, `javascript.splash.darkTextColor`, `javascript.splash.darkAccentColor`
+|`#121212`, `#b3b3b3`, `#4da3ff`
+|The same three in the dark appearance.
+
+|`javascript.splash.logo`
+|The app icon
+|A different image, as a path relative to the bundle's `index.html`, or `none` for no image.
+|===
+
+Colors are hex values (`#rgb`, `#rrggbb`, with optional alpha) or CSS color names. The page applies them before it paints anything, and the background stays behind the app until the first form covers it, so a dark app no longer opens on a white page.
+
+An app that lets the user choose its own appearance can have the next launch's loading screen match that choice, even when it differs from the browser's preference:
+
+[source,java]
 ----
-include::../demos/javascript/src/main/snippets/developer-guide/working-with-javascript.html[tag=working-with-javascript-html-001,indent=0]
+CN.setProperty("platformHint.javascript.splashAppearance", "dark"); // or "light"
+CN.setProperty("platformHint.javascript.splashAppearance", null);   // follow the browser again
 ----
 
+The choice is kept in the browser's local storage and applies only in `auto` mode.
+
+For anything the hints don't cover, the markup is the `cn1-splash` `div` in the generated `index.html`; edit it there if you host the bundle yourself.
+
 [id="debugging", reftext="Debugging in Chrome"]
 === Debugging
 
diff --git a/maven/build-engine/src/main/java/com/codename1/builders/JavaScriptBuildHints.java b/maven/build-engine/src/main/java/com/codename1/builders/JavaScriptBuildHints.java
index 746b00ba83f..5151b8ce87e 100644
--- a/maven/build-engine/src/main/java/com/codename1/builders/JavaScriptBuildHints.java
+++ b/maven/build-engine/src/main/java/com/codename1/builders/JavaScriptBuildHints.java
@@ -89,6 +89,19 @@ public final class JavaScriptBuildHints {
         "javascript.native.theme", "javascript.desktopTheme"
     };
 
+    /// The `javascript.splash.*` hints that style the loading screen, each passed to the
+    /// translator as `codename1.<hint>` (see `JavascriptBundleWriter.SplashSettings`, which
+    /// validates them).
+    static final String[] SPLASH_HINTS = {
+        "javascript.splash.appearance", "javascript.splash.background",
+        "javascript.splash.textColor", "javascript.splash.accentColor",
+        "javascript.splash.darkBackground", "javascript.splash.darkTextColor",
+        "javascript.splash.darkAccentColor", "javascript.splash.logo"
+    };
+
+    /// The 192px icon `JavaScriptPwa` writes into every bundle.
+    static final String SPLASH_DEFAULT_LOGO = "_icons/icon-192.png";
+
     private JavaScriptBuildHints() {
     }
 
@@ -126,6 +139,19 @@ static List<String> translatorOptions(BuildRequest request) {
         if (darkReader != null) {
             out.add("-Dcodename1.javascript.darkreaderLock=" + !"false".equalsIgnoreCase(darkReader.trim()));
         }
+        for (String hint : SPLASH_HINTS) {
+            String value = request.getArg(hint, null);
+            if (value != null && value.trim().length() > 0) {
+                out.add("-Dcodename1." + hint + "=" + value.trim());
+            }
+        }
+        // The loading screen shows the application's icon unless the developer named another
+        // logo (or none). JavaScriptPwa writes the icon to this path after the translator runs,
+        // from the same request.getIcon(); without an icon it writes a placeholder square, which
+        // identifies nothing, so then there is no logo.
+        if (request.getArg("javascript.splash.logo", null) == null && request.getIcon() != null) {
+            out.add("-Dcodename1.javascript.splash.logo=" + SPLASH_DEFAULT_LOGO);
+        }
         return out;
     }
 
diff --git a/maven/build-engine/src/test/java/com/codename1/builders/JavaScriptBuildHintsTest.java b/maven/build-engine/src/test/java/com/codename1/builders/JavaScriptBuildHintsTest.java
index 9f079da8cb1..b7d25274ba5 100644
--- a/maven/build-engine/src/test/java/com/codename1/builders/JavaScriptBuildHintsTest.java
+++ b/maven/build-engine/src/test/java/com/codename1/builders/JavaScriptBuildHintsTest.java
@@ -107,6 +107,29 @@ void translatorGetsTheTitleAndOnlyTheOptOutsThatWereSet() {
         assertTrue(opts.contains("-Dcodename1.javascript.darkreaderLock=false"), opts.toString());
     }
 
+    @Test
+    void splashHintsReachTheTranslatorAndTheIconIsTheDefaultLogo() {
+        BuildRequest r = request("javascript.splash.appearance", " dark ",
+                "javascript.splash.darkBackground", "#1e1e1e");
+        List<String> opts = JavaScriptBuildHints.translatorOptions(r);
+        assertTrue(opts.contains("-Dcodename1.javascript.splash.appearance=dark"), opts.toString());
+        assertTrue(opts.contains("-Dcodename1.javascript.splash.darkBackground=#1e1e1e"), opts.toString());
+        // No icon: the PWA step writes a placeholder square, which is not worth showing.
+        assertFalse(opts.toString().contains("splash.logo"), opts.toString());
+
+        r.setIcon(new byte[] {1});
+        opts = JavaScriptBuildHints.translatorOptions(r);
+        assertTrue(opts.contains("-Dcodename1.javascript.splash.logo=" + JavaScriptBuildHints.SPLASH_DEFAULT_LOGO),
+                opts.toString());
+
+        r = request("javascript.splash.logo", "none");
+        r.setIcon(new byte[] {1});
+        opts = JavaScriptBuildHints.translatorOptions(r);
+        assertTrue(opts.contains("-Dcodename1.javascript.splash.logo=none"), opts.toString());
+        assertFalse(opts.contains("-Dcodename1.javascript.splash.logo=" + JavaScriptBuildHints.SPLASH_DEFAULT_LOGO),
+                opts.toString());
+    }
+
     @Test
     void noHintsShipsOnlyTheLegacyPair() {
         assertEquals(set("iOS7Theme", "android_holo_light"), ship(request()));
diff --git a/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java b/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java
index 1a44124a328..ec2bd6db845 100644
--- a/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java
+++ b/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java
@@ -111,6 +111,78 @@ static void register(List<Hint> h) {
                         + "lock in its default Dynamic mode only; its Filter, Filter+ and Static modes "
                         + "ignore it. Set to `false` to omit the tag."));
 
+        h.add(new Hint("javascript.splash.appearance")
+                .group(HintGroup.JAVASCRIPT)
+                .values("SplashAppearance", "auto", "light", "dark")
+                .def("auto")
+                .platform("javascript")
+                .doc("Which colours the loading screen uses. `auto` (the default) follows the "
+                        + "browser's light/dark preference, or the choice the app remembered with "
+                        + "`Display.setProperty(\"platformHint.javascript.splashAppearance\", \"dark\")`. "
+                        + "`light` and `dark` always use that set, for apps with one appearance."));
+
+        h.add(new Hint("javascript.splash.background")
+                .group(HintGroup.JAVASCRIPT)
+                .type(HintType.STRING)
+                .def("#ffffff")
+                .platform("javascript")
+                .doc("The loading screen's background in light appearance, as a hex colour (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                        + "page paints until the first form shows."));
+
+        h.add(new Hint("javascript.splash.textColor")
+                .group(HintGroup.JAVASCRIPT)
+                .type(HintType.STRING)
+                .def("#666666")
+                .platform("javascript")
+                .doc("The loading screen's text colour in light appearance, as a hex colour (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                        + "page paints until the first form shows."));
+
+        h.add(new Hint("javascript.splash.accentColor")
+                .group(HintGroup.JAVASCRIPT)
+                .type(HintType.STRING)
+                .def("#0072ff")
+                .platform("javascript")
+                .doc("The loading screen's progress bar colour in light appearance, as a hex colour (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                        + "page paints until the first form shows."));
+
+        h.add(new Hint("javascript.splash.darkBackground")
+                .group(HintGroup.JAVASCRIPT)
+                .type(HintType.STRING)
+                .def("#121212")
+                .platform("javascript")
+                .doc("The loading screen's background in dark appearance, as a hex colour (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                        + "page paints until the first form shows."));
+
+        h.add(new Hint("javascript.splash.darkTextColor")
+                .group(HintGroup.JAVASCRIPT)
+                .type(HintType.STRING)
+                .def("#b3b3b3")
+                .platform("javascript")
+                .doc("The loading screen's text colour in dark appearance, as a hex colour (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                        + "page paints until the first form shows."));
+
+        h.add(new Hint("javascript.splash.darkAccentColor")
+                .group(HintGroup.JAVASCRIPT)
+                .type(HintType.STRING)
+                .def("#4da3ff")
+                .platform("javascript")
+                .doc("The loading screen's progress bar colour in dark appearance, as a hex colour (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                        + "page paints until the first form shows."));
+
+        h.add(new Hint("javascript.splash.logo")
+                .group(HintGroup.JAVASCRIPT)
+                .type(HintType.STRING)
+                .platform("javascript")
+                .doc("The image the loading screen shows above the progress bar, as a path relative to "
+                        + "the bundle's `index.html` (letters, digits, `/`, `.`, `-` and `_`). Defaults to the "
+                        + "app icon; `none` shows no image."));
+
         h.add(new Hint("javascript.desktopTheme")
                 .group(HintGroup.JAVASCRIPT)
                 .type(HintType.STRING)
diff --git a/vm/ByteCodeTranslator/src/com/codename1/tools/translator/JavascriptBundleWriter.java b/vm/ByteCodeTranslator/src/com/codename1/tools/translator/JavascriptBundleWriter.java
index e7e196e75a5..1a3022eac13 100644
--- a/vm/ByteCodeTranslator/src/com/codename1/tools/translator/JavascriptBundleWriter.java
+++ b/vm/ByteCodeTranslator/src/com/codename1/tools/translator/JavascriptBundleWriter.java
@@ -1693,6 +1693,7 @@ private static void writeIndex(File outputDirectory) throws IOException {
                 System.getProperty(PAGE_TITLE_PROPERTY),
                 Boolean.parseBoolean(Util.systemProperty(ALLOW_TRANSLATION_PROPERTY, "false")),
                 !"false".equalsIgnoreCase(Util.systemProperty(DARKREADER_LOCK_PROPERTY, "true")));
+        index = applySplashSettings(index, SplashSettings.fromSystemProperties());
         Util.writeUtf8(new File(outputDirectory, "index.html"), index);
     }
 
@@ -1741,6 +1742,174 @@ static String applyPageSettings(String index, String title, boolean allowTransla
                 .replace("__APP_TITLE__", escapeHtml(pageTitle));
     }
 
+    /// Prefix of the translator properties the `javascript.splash.*` build hints become.
+    static final String SPLASH_PROPERTY_PREFIX = "codename1.javascript.splash.";
+
+    /// Local storage key an application writes, through the
+    /// `platformHint.javascript.splashAppearance` property, to have the next launch's loading
+    /// screen follow its own light/dark choice instead of the browser's. `HTML5Implementation`
+    /// writes it; the inline script [#splashTheme(SplashSettings)] emits reads it before the
+    /// first paint.
+    static final String SPLASH_APPEARANCE_STORAGE_KEY = "cn1.splashAppearance";
+
+    /// The loading screen's look: the logo and the colours for each appearance. Every value is
+    /// validated here, because each one is written verbatim into the page's CSS or markup.
+    static final class SplashSettings {
+        /// `auto` (follow the browser, or the app's remembered choice), `light` or `dark`.
+        final String appearance;
+        final String background;
+        final String text;
+        final String accent;
+        final String darkBackground;
+        final String darkText;
+        final String darkAccent;
+        /// A URL relative to the bundle root, or null for no logo.
+        final String logo;
+
+        SplashSettings(String appearance, String background, String text, String accent,
+                String darkBackground, String darkText, String darkAccent, String logo) {
+            this.appearance = appearance(appearance);
+            this.background = color("background", background, "#ffffff");
+            this.text = color("textColor", text, "#666666");
+            this.accent = color("accentColor", accent, "#0072ff");
+            this.darkBackground = color("darkBackground", darkBackground, "#121212");
+            this.darkText = color("darkTextColor", darkText, "#b3b3b3");
+            this.darkAccent = color("darkAccentColor", darkAccent, "#4da3ff");
+            this.logo = logo(logo);
+        }
+
+        static SplashSettings defaults() {
+            return new SplashSettings(null, null, null, null, null, null, null, null);
+        }
+
+        static SplashSettings fromSystemProperties() {
+            return new SplashSettings(prop("appearance"), prop("background"), prop("textColor"),
+                    prop("accentColor"), prop("darkBackground"), prop("darkTextColor"),
+                    prop("darkAccentColor"), prop("logo"));
+        }
+
+        private static String prop(String name) {
+            return System.getProperty(SPLASH_PROPERTY_PREFIX + name);
+        }
+
+        private static String appearance(String value) {
+            if (value == null || value.trim().length() == 0) {
+                return "auto";
+            }
+            String v = value.trim();
+            if (v.equalsIgnoreCase("auto") || v.equalsIgnoreCase("light") || v.equalsIgnoreCase("dark")) {
+                return asciiLower(v);
+            }
+            throw new IllegalArgumentException("javascript.splash.appearance must be auto, light or dark, not '"
+                    + value + "'");
+        }
+
+        /// A hex colour (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) or a CSS colour keyword. Nothing
+        /// else: `rgb(...)` and friends would need a parser to be sure they cannot close the
+        /// declaration, and the hex forms express every colour they can.
+        private static String color(String hint, String value, String def) {
+            if (value == null || value.trim().length() == 0) {
+                return def;
+            }
+            String v = value.trim();
+            boolean ok;
+            if (v.charAt(0) == '#') {
+                int n = v.length() - 1;
+                ok = n == 3 || n == 4 || n == 6 || n == 8;
+                for (int i = 1; ok && i < v.length(); i++) {
+                    char c = v.charAt(i);
+                    ok = (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F');
+                }
+            } else {
+                ok = true;
+                for (int i = 0; ok && i < v.length(); i++) {
+                    char c = v.charAt(i);
+                    ok = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
+                }
+            }
+            if (!ok) {
+                throw new IllegalArgumentException("javascript.splash." + hint
+                        + " must be a hex colour such as #1e1e1e or a CSS colour name, not '" + value + "'");
+            }
+            return v;
+        }
+
+        /// `none` (or nothing) for no logo; otherwise a path inside the bundle. Restricted to
+        /// plain path characters so it can go into a `src` attribute as it is, and never `..`
+        /// or a scheme, so it cannot point the page at another origin.
+        private static String logo(String value) {
+            if (value == null || value.trim().length() == 0 || value.trim().equalsIgnoreCase("none")) {
+                return null;
+            }
+            String v = value.trim();
+            boolean ok = v.charAt(0) != '/' && v.indexOf("..") < 0;
+            for (int i = 0; ok && i < v.length(); i++) {
+                char c = v.charAt(i);
+                ok = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9')
+                        || c == '/' || c == '.' || c == '-' || c == '_';
+            }
+            if (!ok) {
+                throw new IllegalArgumentException("javascript.splash.logo must be a path inside the web "
+                        + "bundle (letters, digits, '/', '.', '-', '_'), not '" + value + "'");
+            }
+            return v;
+        }
+    }
+
+    private static String asciiLower(String s) {
+        StringBuilder out = new StringBuilder(s.length());
+        for (int i = 0; i < s.length(); i++) {
+            char c = s.charAt(i);
+            out.append(c >= 'A' && c <= 'Z' ? (char) (c + ('a' - 'A')) : c);
+        }
+        return out.toString();
+    }
+
+    /// Fills the loading screen's placeholders: its colours and its logo.
+    ///
+    /// This adds an inline `<style>` and, in `auto` mode, an inline `<script>`. Both are fine for
+    /// the Content-Security-Policy: [JavascriptSecurityHeaders] hashes the page after this writes
+    /// it. A template the developer replaced without the placeholders is left alone.
+    static String applySplashSettings(String index, SplashSettings splash) {
+        String logo = splash.logo == null ? ""
+                : "<img class=\"cn1-splash-logo\" src=\"" + splash.logo + "\" alt=\"\">";
+        return index
+                .replace("<!--__SPLASH_THEME__-->", splashTheme(splash))
+                .replace("<!--__SPLASH_LOGO__-->", logo);
+    }
+
+    /// The `--cn1-splash-*` variables for the chosen appearance mode.
+    ///
+    /// In `auto` mode the browser's `prefers-color-scheme` decides, unless the application
+    /// remembered a choice of its own ([#SPLASH_APPEARANCE_STORAGE_KEY]); the script that reads
+    /// it runs in `<head>`, before the body exists, so the first frame is already the right
+    /// colour. The variables also colour `html`, which stays behind the canvas until the first
+    /// form paints over it -- the gap where a dark app used to flash white.
+    static String splashTheme(SplashSettings s) {
+        String light = vars(s.background, s.text, s.accent);
+        String dark = vars(s.darkBackground, s.darkText, s.darkAccent);
+        StringBuilder out = new StringBuilder();
+        if ("auto".equals(s.appearance)) {
+            out.append("<script>try{var a=localStorage.getItem(\"").append(SPLASH_APPEARANCE_STORAGE_KEY)
+                    .append("\");if(a===\"light\"||a===\"dark\"){document.documentElement.setAttribute(")
+                    .append("\"data-cn1-appearance\",a);}}catch(e){}</script>\n");
+            out.append("<style>\n:root{").append(light).append("}\n")
+                    .append("@media (prefers-color-scheme: dark){:root:not([data-cn1-appearance=\"light\"]){")
+                    .append(dark).append("}}\n")
+                    .append(":root[data-cn1-appearance=\"dark\"]{").append(dark).append("}\n")
+                    .append("</style>");
+        } else {
+            out.append("<style>\n:root{").append("dark".equals(s.appearance) ? dark : light)
+                    .append("}\n</style>");
+        }
+        return out.toString();
+    }
+
+    private static String vars(String background, String text, String accent) {
+        return "--cn1-splash-background:" + background + ";--cn1-splash-text:" + text
+                + ";--cn1-splash-accent:" + accent + ";";
+    }
+
     private static String escapeHtml(String text) {
         StringBuilder out = new StringBuilder(text.length());
         for (int i = 0; i < text.length(); i++) {
diff --git a/vm/ByteCodeTranslator/src/javascript/index.html b/vm/ByteCodeTranslator/src/javascript/index.html
index 2a4b0587370..cda1f49a17e 100644
--- a/vm/ByteCodeTranslator/src/javascript/index.html
+++ b/vm/ByteCodeTranslator/src/javascript/index.html
@@ -5,26 +5,57 @@
 <!--__HEAD_META__-->
 <title>__APP_TITLE__</title>
 <link rel="stylesheet" href="style.css">
+<!--__SPLASH_THEME__-->
 <style>
   /* Indeterminate progress bar shown until HTML5Implementation.hideSplash
      runs and the host-bridge ``__cn1_hide_splash__`` handler removes
      #cn1-splash. Pure CSS so it animates regardless of whether the worker
      is still downloading translated_app.js or busy initialising the
      framework -- both phases sit on the splash and the old static
-     "Loading..." left users wondering whether the page had hung. */
+     "Loading..." left users wondering whether the page had hung.
+     The colours are the --cn1-splash-* variables the build writes from the
+     javascript.splash.* hints just above (JavascriptBundleWriter.splashTheme),
+     so a dark app never opens on a white page. */
+  html {
+    background: var(--cn1-splash-background, #ffffff);
+  }
+  #cn1-splash {
+    color: var(--cn1-splash-text, #666666);
+  }
+  #cn1-splash .cn1-splash-logo {
+    display: block;
+    width: 6em;
+    height: 6em;
+    max-width: 40vw;
+    max-height: 40vw;
+    margin: 0 auto 1.2em;
+    border-radius: 22%;
+    object-fit: contain;
+  }
   #cn1-splash .cn1-progress {
     width: 16em;
     max-width: 60vw;
     height: 6px;
     border-radius: 3px;
-    background: #eee;
+    /* The track is the text colour at low opacity, painted by ::before:
+       works on every browser (color-mix() would not before 2023) and reads
+       as the empty part of the bar on any background. */
+    position: relative;
     overflow: hidden;
     margin: 1em auto 0.6em;
   }
+  #cn1-splash .cn1-progress::before {
+    content: "";
+    position: absolute;
+    top: 0; left: 0; right: 0; bottom: 0;
+    background: currentColor;
+    opacity: 0.2;
+  }
   #cn1-splash .cn1-progress-bar {
+    position: relative;
     width: 33%;
     height: 100%;
-    background: linear-gradient(90deg, #0072ff, #00c6ff);
+    background: var(--cn1-splash-accent, #0072ff);
     border-radius: 3px;
     animation: cn1-progress-slide 1.4s ease-in-out infinite;
   }
@@ -36,6 +67,7 @@
 </head>
 <body>
 <div id="cn1-splash">
+  <!--__SPLASH_LOGO__-->
   <div class="cn1-progress" role="progressbar" aria-label="Loading application">
     <div class="cn1-progress-bar"></div>
   </div>
diff --git a/vm/tests/src/test/java/com/codename1/tools/translator/JavascriptPageSettingsTest.java b/vm/tests/src/test/java/com/codename1/tools/translator/JavascriptPageSettingsTest.java
index 7c56b3f3731..957a242f694 100644
--- a/vm/tests/src/test/java/com/codename1/tools/translator/JavascriptPageSettingsTest.java
+++ b/vm/tests/src/test/java/com/codename1/tools/translator/JavascriptPageSettingsTest.java
@@ -90,6 +90,58 @@ void settingsLeaveTheContentSecurityPolicyUnchanged() throws Exception {
         assertEquals(JavascriptSecurityHeaders.hashesOf(raw, "style"), JavascriptSecurityHeaders.hashesOf(filled, "style"));
     }
 
+    @Test
+    void defaultSplashFollowsTheBrowserAndTheRememberedChoice() throws Exception {
+        String html = JavascriptBundleWriter.applySplashSettings(template(),
+                JavascriptBundleWriter.SplashSettings.defaults());
+        assertTrue(html.contains("@media (prefers-color-scheme: dark)"), html);
+        assertTrue(html.contains(":root[data-cn1-appearance=\"dark\"]"), html);
+        assertTrue(html.contains("localStorage.getItem(\"" + JavascriptBundleWriter.SPLASH_APPEARANCE_STORAGE_KEY + "\")"), html);
+        // The theme is set in <head>, before the splash markup exists, so nothing paints white first.
+        assertTrue(html.indexOf("--cn1-splash-background") < html.indexOf("<body>"), html);
+        assertFalse(html.contains("cn1-splash-logo\" src"), html);
+        assertFalse(html.contains("__SPLASH_"), html);
+    }
+
+    @Test
+    void singleAppearanceSplashHasNoMediaQueryAndNoScript() throws Exception {
+        String html = JavascriptBundleWriter.applySplashSettings(template(),
+                new JavascriptBundleWriter.SplashSettings("Dark", "#fff", null, null, "#1e1e1e", "white", "#F80", "_icons/icon-192.png"));
+        assertFalse(html.contains("prefers-color-scheme"), html);
+        assertFalse(html.contains("localStorage"), html);
+        assertTrue(html.contains("--cn1-splash-background:#1e1e1e;--cn1-splash-text:white;--cn1-splash-accent:#F80;"), html);
+        assertTrue(html.contains("<img class=\"cn1-splash-logo\" src=\"_icons/icon-192.png\" alt=\"\">"), html);
+    }
+
+    @Test
+    void splashValuesThatCouldEscapeTheirContextAreRejected() {
+        String[] badColors = {"red;}body{display:none", "#12", "#ggg", "rgb(0,0,0)", "url(x)"};
+        for (String bad : badColors) {
+            assertThrows(IllegalArgumentException.class, () -> new JavascriptBundleWriter.SplashSettings(
+                    null, bad, null, null, null, null, null, null), bad);
+        }
+        String[] badLogos = {"\"><script>", "../secret.png", "/etc/x.png", "https://evil/x.png", "a b.png"};
+        for (String bad : badLogos) {
+            assertThrows(IllegalArgumentException.class, () -> new JavascriptBundleWriter.SplashSettings(
+                    null, null, null, null, null, null, null, bad), bad);
+        }
+        assertThrows(IllegalArgumentException.class, () -> new JavascriptBundleWriter.SplashSettings(
+                "sepia", null, null, null, null, null, null, null));
+    }
+
+    @Test
+    void splashInlineBlocksAreHashedIntoThePolicy() throws Exception {
+        String html = JavascriptBundleWriter.applySplashSettings(template(),
+                JavascriptBundleWriter.SplashSettings.defaults());
+        String csp = JavascriptSecurityHeaders.contentSecurityPolicy(html, "");
+        for (String hash : JavascriptSecurityHeaders.hashesOf(html, "script")) {
+            assertTrue(csp.contains(hash), csp);
+        }
+        for (String hash : JavascriptSecurityHeaders.hashesOf(html, "style")) {
+            assertTrue(csp.contains(hash), csp);
+        }
+    }
+
     private static void assertNoPlaceholderLeft(String html) {
         assertFalse(html.contains("__HTML_ATTRS__"), html);
         assertFalse(html.contains("__HEAD_META__"), html);

From 5e2b3beda3a8eac3b608510c543a68956208a403 Mon Sep 17 00:00:00 2001
From: Shai Almog <67850168+shai-almog@users.noreply.github.com>
Date: Wed, 28 Oct 2026 14:59:14 +0200
Subject: [PATCH 2/5] JavaScript splash: light unless a dark colour is named,
 real colour names, transparent page once started

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../Working-With-Javascript.asciidoc          |  6 +--
 .../builders/JavaScriptBuildHints.java        |  3 +-
 .../build/shared/BuildHintsDesktop.java       |  5 +-
 .../translator/JavascriptBundleWriter.java    | 52 +++++++++++++++----
 .../src/javascript/browser_bridge.js          |  6 +++
 .../src/javascript/index.html                 |  4 ++
 .../JavascriptPageSettingsTest.java           | 17 ++++--
 7 files changed, 74 insertions(+), 19 deletions(-)

diff --git a/docs/developer-guide/Working-With-Javascript.asciidoc b/docs/developer-guide/Working-With-Javascript.asciidoc
index 65daf2ce0a1..98334d9501b 100644
--- a/docs/developer-guide/Working-With-Javascript.asciidoc
+++ b/docs/developer-guide/Working-With-Javascript.asciidoc
@@ -271,8 +271,8 @@ Build hints set its look, so the settings survive every build instead of being e
 |Build hint |Default |Meaning
 
 |`javascript.splash.appearance`
-|`auto`
-|`auto` follows the browser's light/dark preference. `light` or `dark` always uses that set of colors, for an app with a single appearance.
+|`auto` once any dark color is set, otherwise `light`
+|`auto` follows the browser's light/dark preference. `light` or `dark` always uses that set of colors, for an app with a single appearance. An app that sets none of these hints keeps a light loading screen, so a light app never opens dark.
 
 |`javascript.splash.background`, `javascript.splash.textColor`, `javascript.splash.accentColor`
 |`#ffffff`, `#666666`, `#0072ff`
@@ -287,7 +287,7 @@ Build hints set its look, so the settings survive every build instead of being e
 |A different image, as a path relative to the bundle's `index.html`, or `none` for no image.
 |===
 
-Colors are hex values (`#rgb`, `#rrggbb`, with optional alpha) or CSS color names. The page applies them before it paints anything, and the background stays behind the app until the first form covers it, so a dark app no longer opens on a white page.
+Colors are hex values (`#rgb`, `#rrggbb`, with optional alpha) or CSS color names. The page applies them before it paints anything, and keeps the background until the first form is shown, so a dark app no longer opens on a white page.
 
 An app that lets the user choose its own appearance can have the next launch's loading screen match that choice, even when it differs from the browser's preference:
 
diff --git a/maven/build-engine/src/main/java/com/codename1/builders/JavaScriptBuildHints.java b/maven/build-engine/src/main/java/com/codename1/builders/JavaScriptBuildHints.java
index 5151b8ce87e..c84810dc559 100644
--- a/maven/build-engine/src/main/java/com/codename1/builders/JavaScriptBuildHints.java
+++ b/maven/build-engine/src/main/java/com/codename1/builders/JavaScriptBuildHints.java
@@ -149,7 +149,8 @@ static List<String> translatorOptions(BuildRequest request) {
         // logo (or none). JavaScriptPwa writes the icon to this path after the translator runs,
         // from the same request.getIcon(); without an icon it writes a placeholder square, which
         // identifies nothing, so then there is no logo.
-        if (request.getArg("javascript.splash.logo", null) == null && request.getIcon() != null) {
+        String logo = request.getArg("javascript.splash.logo", null);
+        if ((logo == null || logo.trim().length() == 0) && request.getIcon() != null) {
             out.add("-Dcodename1.javascript.splash.logo=" + SPLASH_DEFAULT_LOGO);
         }
         return out;
diff --git a/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java b/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java
index ec2bd6db845..d5e8d41a050 100644
--- a/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java
+++ b/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java
@@ -114,9 +114,10 @@ static void register(List<Hint> h) {
         h.add(new Hint("javascript.splash.appearance")
                 .group(HintGroup.JAVASCRIPT)
                 .values("SplashAppearance", "auto", "light", "dark")
-                .def("auto")
                 .platform("javascript")
-                .doc("Which colours the loading screen uses. `auto` (the default) follows the "
+                .doc("Which colours the loading screen uses. Defaults to `auto` when any "
+                        + "`javascript.splash.dark*` colour is set and to `light` otherwise, so an app "
+                        + "that never asked for a dark loading screen does not get one. `auto` follows the "
                         + "browser's light/dark preference, or the choice the app remembered with "
                         + "`Display.setProperty(\"platformHint.javascript.splashAppearance\", \"dark\")`. "
                         + "`light` and `dark` always use that set, for apps with one appearance."));
diff --git a/vm/ByteCodeTranslator/src/com/codename1/tools/translator/JavascriptBundleWriter.java b/vm/ByteCodeTranslator/src/com/codename1/tools/translator/JavascriptBundleWriter.java
index 1a3022eac13..66607c21c39 100644
--- a/vm/ByteCodeTranslator/src/com/codename1/tools/translator/JavascriptBundleWriter.java
+++ b/vm/ByteCodeTranslator/src/com/codename1/tools/translator/JavascriptBundleWriter.java
@@ -1768,7 +1768,12 @@ static final class SplashSettings {
 
         SplashSettings(String appearance, String background, String text, String accent,
                 String darkBackground, String darkText, String darkAccent, String logo) {
-            this.appearance = appearance(appearance);
+            // With no appearance and no dark colour named, the splash stays light: an existing
+            // light app must not gain a dark loading screen ahead of its white first form just
+            // because the browser prefers dark. Naming any dark colour is what says the app has
+            // a dark appearance, and makes `auto` the default.
+            boolean darkNamed = notBlank(darkBackground) || notBlank(darkText) || notBlank(darkAccent);
+            this.appearance = appearance(appearance, darkNamed ? "auto" : "light");
             this.background = color("background", background, "#ffffff");
             this.text = color("textColor", text, "#666666");
             this.accent = color("accentColor", accent, "#0072ff");
@@ -1792,9 +1797,13 @@ private static String prop(String name) {
             return System.getProperty(SPLASH_PROPERTY_PREFIX + name);
         }
 
-        private static String appearance(String value) {
+        private static boolean notBlank(String v) {
+            return v != null && v.trim().length() > 0;
+        }
+
+        private static String appearance(String value, String def) {
             if (value == null || value.trim().length() == 0) {
-                return "auto";
+                return def;
             }
             String v = value.trim();
             if (v.equalsIgnoreCase("auto") || v.equalsIgnoreCase("light") || v.equalsIgnoreCase("dark")) {
@@ -1821,20 +1830,43 @@ private static String color(String hint, String value, String def) {
                     ok = (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F');
                 }
             } else {
-                ok = true;
-                for (int i = 0; ok && i < v.length(); i++) {
-                    char c = v.charAt(i);
-                    ok = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
-                }
+                // A name has to be a real one: a misspelt name, or a keyword such as `inherit`,
+                // makes the variable invalid where it is used, and the page falls back to a
+                // transparent background with no error anywhere.
+                ok = CSS_COLOR_NAMES.indexOf("," + asciiLower(v) + ",") >= 0;
             }
             if (!ok) {
                 throw new IllegalArgumentException("javascript.splash." + hint
-                        + " must be a hex colour such as #1e1e1e or a CSS colour name, not '" + value + "'");
+                        + " must be a hex colour such as #1e1e1e or a CSS named colour, not '" + value + "'");
             }
             return v;
         }
 
-        /// `none` (or nothing) for no logo; otherwise a path inside the bundle. Restricted to
+        /// The CSS named colours (CSS Color Module Level 4), plus `transparent`.
+        private static final String CSS_COLOR_NAMES = ",transparent,aliceblue,antiquewhite,aqua,"
+                + "aquamarine,azure,beige,bisque,black,blanchedalmond,blue,blueviolet,brown,burlywood,"
+                + "cadetblue,chartreuse,chocolate,coral,cornflowerblue,cornsilk,crimson,cyan,darkblue,"
+                + "darkcyan,darkgoldenrod,darkgray,darkgreen,darkgrey,darkkhaki,darkmagenta,"
+                + "darkolivegreen,darkorange,darkorchid,darkred,darksalmon,darkseagreen,darkslateblue,"
+                + "darkslategray,darkslategrey,darkturquoise,darkviolet,deeppink,deepskyblue,dimgray,"
+                + "dimgrey,dodgerblue,firebrick,floralwhite,forestgreen,fuchsia,gainsboro,ghostwhite,"
+                + "gold,goldenrod,gray,green,greenyellow,grey,honeydew,hotpink,indianred,indigo,ivory,"
+                + "khaki,lavender,lavenderblush,lawngreen,lemonchiffon,lightblue,lightcoral,lightcyan,"
+                + "lightgoldenrodyellow,lightgray,lightgreen,lightgrey,lightpink,lightsalmon,"
+                + "lightseagreen,lightskyblue,lightslategray,lightslategrey,lightsteelblue,lightyellow,"
+                + "lime,limegreen,linen,magenta,maroon,mediumaquamarine,mediumblue,mediumorchid,"
+                + "mediumpurple,mediumseagreen,mediumslateblue,mediumspringgreen,mediumturquoise,"
+                + "mediumvioletred,midnightblue,mintcream,mistyrose,moccasin,navajowhite,navy,oldlace,"
+                + "olive,olivedrab,orange,orangered,orchid,palegoldenrod,palegreen,paleturquoise,"
+                + "palevioletred,papayawhip,peachpuff,peru,pink,plum,powderblue,purple,rebeccapurple,"
+                + "red,rosybrown,royalblue,saddlebrown,salmon,sandybrown,seagreen,seashell,sienna,"
+                + "silver,skyblue,slateblue,slategray,slategrey,snow,springgreen,steelblue,tan,teal,"
+                + "thistle,tomato,turquoise,violet,wheat,white,whitesmoke,yellow,yellowgreen,";
+
+        /// `none` (or nothing) for no logo; otherwise a path inside the bundle. The file is not
+        /// checked: the translator runs before the bundle is complete (the default icon is
+        /// written by the builder afterwards). A missing one costs nothing visible, since the
+        /// `<img>` carries `alt=""` and browsers draw nothing for an empty-alt image that fails. Restricted to
         /// plain path characters so it can go into a `src` attribute as it is, and never `..`
         /// or a scheme, so it cannot point the page at another origin.
         private static String logo(String value) {
diff --git a/vm/ByteCodeTranslator/src/javascript/browser_bridge.js b/vm/ByteCodeTranslator/src/javascript/browser_bridge.js
index 6036e185a70..a018945aea1 100644
--- a/vm/ByteCodeTranslator/src/javascript/browser_bridge.js
+++ b/vm/ByteCodeTranslator/src/javascript/browser_bridge.js
@@ -4118,6 +4118,12 @@
         w.parent.postMessage({ type: 'cn1-app-ready' }, '*');
       }
     } catch (_pmErr) { /* cross-origin parent -- ignore */ }
+    // The page background is the splash colour only while the splash is up; from the
+    // first form on, the page is transparent again as it always was, so an embed and any
+    // area the canvas leaves uncovered show what they showed before (index.html).
+    if (doc.documentElement) {
+      doc.documentElement.setAttribute('data-cn1-started', '');
+    }
     var splash = doc.getElementById('cn1-splash');
     if (!splash) {
       return null;
diff --git a/vm/ByteCodeTranslator/src/javascript/index.html b/vm/ByteCodeTranslator/src/javascript/index.html
index cda1f49a17e..9f275120358 100644
--- a/vm/ByteCodeTranslator/src/javascript/index.html
+++ b/vm/ByteCodeTranslator/src/javascript/index.html
@@ -19,6 +19,10 @@
   html {
     background: var(--cn1-splash-background, #ffffff);
   }
+  /* Set by the host's __cn1_hide_splash__ handler once the first form shows. */
+  html[data-cn1-started] {
+    background: none;
+  }
   #cn1-splash {
     color: var(--cn1-splash-text, #666666);
   }
diff --git a/vm/tests/src/test/java/com/codename1/tools/translator/JavascriptPageSettingsTest.java b/vm/tests/src/test/java/com/codename1/tools/translator/JavascriptPageSettingsTest.java
index 957a242f694..e5ba8f7be6e 100644
--- a/vm/tests/src/test/java/com/codename1/tools/translator/JavascriptPageSettingsTest.java
+++ b/vm/tests/src/test/java/com/codename1/tools/translator/JavascriptPageSettingsTest.java
@@ -91,9 +91,19 @@ void settingsLeaveTheContentSecurityPolicyUnchanged() throws Exception {
     }
 
     @Test
-    void defaultSplashFollowsTheBrowserAndTheRememberedChoice() throws Exception {
+    void anAppThatAskedForNothingKeepsALightSplash() throws Exception {
+        // An existing light app must not open dark because the browser prefers dark.
         String html = JavascriptBundleWriter.applySplashSettings(template(),
                 JavascriptBundleWriter.SplashSettings.defaults());
+        assertFalse(html.contains("prefers-color-scheme"), html);
+        assertTrue(html.contains("--cn1-splash-background:#ffffff;"), html);
+        assertFalse(html.contains("__SPLASH_"), html);
+    }
+
+    @Test
+    void namingADarkColourFollowsTheBrowserAndTheRememberedChoice() throws Exception {
+        String html = JavascriptBundleWriter.applySplashSettings(template(),
+                new JavascriptBundleWriter.SplashSettings(null, null, null, null, "#1e1e1e", null, null, null));
         assertTrue(html.contains("@media (prefers-color-scheme: dark)"), html);
         assertTrue(html.contains(":root[data-cn1-appearance=\"dark\"]"), html);
         assertTrue(html.contains("localStorage.getItem(\"" + JavascriptBundleWriter.SPLASH_APPEARANCE_STORAGE_KEY + "\")"), html);
@@ -115,7 +125,7 @@ void singleAppearanceSplashHasNoMediaQueryAndNoScript() throws Exception {
 
     @Test
     void splashValuesThatCouldEscapeTheirContextAreRejected() {
-        String[] badColors = {"red;}body{display:none", "#12", "#ggg", "rgb(0,0,0)", "url(x)"};
+        String[] badColors = {"red;}body{display:none", "#12", "#ggg", "rgb(0,0,0)", "url(x)", "blak", "inherit"};
         for (String bad : badColors) {
             assertThrows(IllegalArgumentException.class, () -> new JavascriptBundleWriter.SplashSettings(
                     null, bad, null, null, null, null, null, null), bad);
@@ -132,7 +142,8 @@ void splashValuesThatCouldEscapeTheirContextAreRejected() {
     @Test
     void splashInlineBlocksAreHashedIntoThePolicy() throws Exception {
         String html = JavascriptBundleWriter.applySplashSettings(template(),
-                JavascriptBundleWriter.SplashSettings.defaults());
+                new JavascriptBundleWriter.SplashSettings("auto", null, null, null, null, null, null, null));
+        assertTrue(JavascriptSecurityHeaders.hashesOf(html, "script").size() > 0, html);
         String csp = JavascriptSecurityHeaders.contentSecurityPolicy(html, "");
         for (String hash : JavascriptSecurityHeaders.hashesOf(html, "script")) {
             assertTrue(csp.contains(hash), csp);

From 8b664f8784076c461a2cce1088d2ff290bd94bbd Mon Sep 17 00:00:00 2001
From: Shai Almog <67850168+shai-almog@users.noreply.github.com>
Date: Wed, 28 Oct 2026 14:59:54 +0200
Subject: [PATCH 3/5] JavaScript port: mark the page started on the in-page
 splash path too

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Ports/JavaScriptPort/src/main/webapp/port.js | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Ports/JavaScriptPort/src/main/webapp/port.js b/Ports/JavaScriptPort/src/main/webapp/port.js
index 182606143d2..9d15a732616 100644
--- a/Ports/JavaScriptPort/src/main/webapp/port.js
+++ b/Ports/JavaScriptPort/src/main/webapp/port.js
@@ -4983,6 +4983,8 @@ const html5HideSplashWorkerSymbol = "cn1_com_codename1_impl_html5_HTML5Implement
     if (typeof document !== "undefined"
             && typeof globalThis !== "undefined" && typeof globalThis.jQuery === "function") {
       try {
+        // Same as the host handler: the page drops the splash background once started.
+        document.documentElement.setAttribute("data-cn1-started", "");
         globalThis.jQuery("div#cn1-splash").fadeOut(100, function() {
           globalThis.jQuery(this).remove();
         });

From 40ee93c3c6d3f836a593020875ed2a195aeab0a4 Mon Sep 17 00:00:00 2001
From: Shai Almog <67850168+shai-almog@users.noreply.github.com>
Date: Wed, 28 Oct 2026 17:39:23 +0200
Subject: [PATCH 4/5] docs: move the splash appearance sample into a demo
 snippet

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ...WithJavascriptSplashAppearanceSnippet.java | 35 +++++++++++++++++++
 .../Working-With-Javascript.asciidoc          |  3 +-
 2 files changed, 36 insertions(+), 2 deletions(-)
 create mode 100644 docs/demos/common/src/main/java/com/codenameone/developerguide/snippets/generated/WorkingWithJavascriptSplashAppearanceSnippet.java

diff --git a/docs/demos/common/src/main/java/com/codenameone/developerguide/snippets/generated/WorkingWithJavascriptSplashAppearanceSnippet.java b/docs/demos/common/src/main/java/com/codenameone/developerguide/snippets/generated/WorkingWithJavascriptSplashAppearanceSnippet.java
new file mode 100644
index 00000000000..796d3cc2478
--- /dev/null
+++ b/docs/demos/common/src/main/java/com/codenameone/developerguide/snippets/generated/WorkingWithJavascriptSplashAppearanceSnippet.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+
+package com.codenameone.developerguide.snippets.generated;
+
+import com.codename1.ui.CN;
+
+class WorkingWithJavascriptSplashAppearanceSnippet {
+    void snippet() {
+        // tag::working-with-javascript-splash-appearance[]
+        CN.setProperty("platformHint.javascript.splashAppearance", "dark"); // or "light"
+        CN.setProperty("platformHint.javascript.splashAppearance", null);   // follow the browser again
+        // end::working-with-javascript-splash-appearance[]
+    }
+}
diff --git a/docs/developer-guide/Working-With-Javascript.asciidoc b/docs/developer-guide/Working-With-Javascript.asciidoc
index 98334d9501b..e15f8b75041 100644
--- a/docs/developer-guide/Working-With-Javascript.asciidoc
+++ b/docs/developer-guide/Working-With-Javascript.asciidoc
@@ -293,8 +293,7 @@ An app that lets the user choose its own appearance can have the next launch's l
 
 [source,java]
 ----
-CN.setProperty("platformHint.javascript.splashAppearance", "dark"); // or "light"
-CN.setProperty("platformHint.javascript.splashAppearance", null);   // follow the browser again
+include::../demos/common/src/main/java/com/codenameone/developerguide/snippets/generated/WorkingWithJavascriptSplashAppearanceSnippet.java[tag=working-with-javascript-splash-appearance,indent=0]
 ----
 
 The choice is kept in the browser's local storage and applies only in `auto` mode.

From 9c9727e4e45d8cf3562d9330594bdff964a5de32 Mon Sep 17 00:00:00 2001
From: Shai Almog <67850168+shai-almog@users.noreply.github.com>
Date: Wed, 28 Oct 2026 18:57:02 +0200
Subject: [PATCH 5/5] docs: spell the splash hint descriptions the way the
 guide does

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../build/shared/BuildHintsDesktop.java       | 30 +++++++++----------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java b/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java
index d5e8d41a050..3ff9998de98 100644
--- a/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java
+++ b/maven/build-hint-catalog/src/main/java/com/codename1/build/shared/BuildHintsDesktop.java
@@ -115,9 +115,9 @@ static void register(List<Hint> h) {
                 .group(HintGroup.JAVASCRIPT)
                 .values("SplashAppearance", "auto", "light", "dark")
                 .platform("javascript")
-                .doc("Which colours the loading screen uses. Defaults to `auto` when any "
-                        + "`javascript.splash.dark*` colour is set and to `light` otherwise, so an app "
-                        + "that never asked for a dark loading screen does not get one. `auto` follows the "
+                .doc("Which colors the loading screen uses. Defaults to `auto` when any "
+                        + "`javascript.splash.dark*` color is set and to `light` otherwise, so an app "
+                        + "that never asked for a dark loading screen doesn't get one. `auto` follows the "
                         + "browser's light/dark preference, or the choice the app remembered with "
                         + "`Display.setProperty(\"platformHint.javascript.splashAppearance\", \"dark\")`. "
                         + "`light` and `dark` always use that set, for apps with one appearance."));
@@ -127,8 +127,8 @@ static void register(List<Hint> h) {
                 .type(HintType.STRING)
                 .def("#ffffff")
                 .platform("javascript")
-                .doc("The loading screen's background in light appearance, as a hex colour (`#rgb`, `#rrggbb`, "
-                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                .doc("The loading screen's background in light appearance, as a hex color (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS color name. Applied from the first frame the "
                         + "page paints until the first form shows."));
 
         h.add(new Hint("javascript.splash.textColor")
@@ -136,8 +136,8 @@ static void register(List<Hint> h) {
                 .type(HintType.STRING)
                 .def("#666666")
                 .platform("javascript")
-                .doc("The loading screen's text colour in light appearance, as a hex colour (`#rgb`, `#rrggbb`, "
-                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                .doc("The loading screen's text color in light appearance, as a hex color (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS color name. Applied from the first frame the "
                         + "page paints until the first form shows."));
 
         h.add(new Hint("javascript.splash.accentColor")
@@ -145,8 +145,8 @@ static void register(List<Hint> h) {
                 .type(HintType.STRING)
                 .def("#0072ff")
                 .platform("javascript")
-                .doc("The loading screen's progress bar colour in light appearance, as a hex colour (`#rgb`, `#rrggbb`, "
-                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                .doc("The loading screen's progress bar color in light appearance, as a hex color (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS color name. Applied from the first frame the "
                         + "page paints until the first form shows."));
 
         h.add(new Hint("javascript.splash.darkBackground")
@@ -154,8 +154,8 @@ static void register(List<Hint> h) {
                 .type(HintType.STRING)
                 .def("#121212")
                 .platform("javascript")
-                .doc("The loading screen's background in dark appearance, as a hex colour (`#rgb`, `#rrggbb`, "
-                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                .doc("The loading screen's background in dark appearance, as a hex color (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS color name. Applied from the first frame the "
                         + "page paints until the first form shows."));
 
         h.add(new Hint("javascript.splash.darkTextColor")
@@ -163,8 +163,8 @@ static void register(List<Hint> h) {
                 .type(HintType.STRING)
                 .def("#b3b3b3")
                 .platform("javascript")
-                .doc("The loading screen's text colour in dark appearance, as a hex colour (`#rgb`, `#rrggbb`, "
-                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                .doc("The loading screen's text color in dark appearance, as a hex color (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS color name. Applied from the first frame the "
                         + "page paints until the first form shows."));
 
         h.add(new Hint("javascript.splash.darkAccentColor")
@@ -172,8 +172,8 @@ static void register(List<Hint> h) {
                 .type(HintType.STRING)
                 .def("#4da3ff")
                 .platform("javascript")
-                .doc("The loading screen's progress bar colour in dark appearance, as a hex colour (`#rgb`, `#rrggbb`, "
-                        + "with optional alpha) or a CSS colour name. Applied from the first frame the "
+                .doc("The loading screen's progress bar color in dark appearance, as a hex color (`#rgb`, `#rrggbb`, "
+                        + "with optional alpha) or a CSS color name. Applied from the first frame the "
                         + "page paints until the first form shows."));
 
         h.add(new Hint("javascript.splash.logo")