From 5a42af33ecfc5549e60d4aa840ae02fe950e3b83 Mon Sep 17 00:00:00 2001
From: SB Software Agent <agent@sbsoftware.de>
Date: Thu, 26 Feb 2026 23:50:39 +0100
Subject: [PATCH 1/6] CR-126 Add drop-in PWA install component with deferred
 prompt and iOS Safari fallback panel

---
 spec/pwa_install_component_spec.cr |  59 +++++++++
 src/crumble.cr                     |   1 +
 src/pwa_install_component.cr       | 198 +++++++++++++++++++++++++++++
 3 files changed, 258 insertions(+)
 create mode 100644 spec/pwa_install_component_spec.cr
 create mode 100644 src/pwa_install_component.cr

diff --git a/spec/pwa_install_component_spec.cr b/spec/pwa_install_component_spec.cr
new file mode 100644
index 0000000..77d2652
--- /dev/null
+++ b/spec/pwa_install_component_spec.cr
@@ -0,0 +1,59 @@
+require "./spec_helper"
+
+module Crumble::PwaInstallComponentSpec
+  class LayoutWithInstall < ToHtml::Layout
+    ToHtml.instance_template do
+      super do
+        Crumble::PwaInstallComponent.new(ctx: ctx).to_html
+      end
+    end
+
+    def window_title
+      "Pwa Install Component Spec"
+    end
+  end
+end
+
+describe Crumble::PwaInstallComponent do
+  it "renders as a drop-in layout component via #to_html" do
+    html = Crumble::PwaInstallComponentSpec::LayoutWithInstall.new(ctx: test_handler_context).to_html
+
+    html.should contain(%(<div id="crumble-pwa-install" hidden>))
+    html.should contain(%(<button id="crumble-pwa-install-trigger" type="button" aria-haspopup="dialog" aria-controls="crumble-pwa-install-panel">Install app</button>))
+    html.should contain(%(<div id="crumble-pwa-install-panel" hidden>))
+    html.should contain(%(<button id="crumble-pwa-install-panel-close" type="button" aria-label="Close install instructions">Close</button>))
+    html.should contain("To install this app, tap Share, then Add to Home Screen.")
+    html.should contain("#crumble-pwa-install {")
+    html.should contain("background: #f6edac;")
+    html.should contain("#crumble-pwa-install-trigger {")
+    html.should contain("background: #757575;")
+  end
+
+  it "captures deferred beforeinstallprompt and handles install outcomes on custom click" do
+    script = Crumble::PwaInstallComponent::Script.to_js
+
+    script.should contain("window.addEventListener(\"beforeinstallprompt\", event => {")
+    script.should contain("event.preventDefault();")
+    script.should contain("deferredPrompt = event;")
+    script.should contain("button.addEventListener(\"click\", async () => {")
+    script.should contain("deferredPrompt.prompt();")
+    script.should contain("const choiceResult = await deferredPrompt.userChoice;")
+    script.should contain("choiceResult.outcome === \"accepted\"")
+    script.should contain("choiceResult.outcome === \"dismissed\"")
+    script.should contain("deferredPrompt = null;")
+  end
+
+  it "keeps the control mobile-only, hides when standalone, and shows iOS Safari fallback panel" do
+    script = Crumble::PwaInstallComponent::Script.to_js
+
+    script.should contain("const isMobile = mobileMedia.matches || isMobileAgent;")
+    script.should contain("window.matchMedia(\"(display-mode: standalone)\").matches || window.navigator.standalone === true")
+    script.should contain("if (!isMobile || isStandalone()) {")
+    script.should contain("if (isIosSafari) {")
+    script.should contain("closePanel();")
+    script.should contain("openPanel();")
+    script.should contain("panel.addEventListener(\"click\", event => {")
+    script.should contain("if (event.target === panel) closePanel();")
+    script.should contain("window.addEventListener(\"appinstalled\", () => {")
+  end
+end
diff --git a/src/crumble.cr b/src/crumble.cr
index 233b4f6..68375b5 100644
--- a/src/crumble.cr
+++ b/src/crumble.cr
@@ -12,3 +12,4 @@ require "./server/file_session_store"
 require "./server"
 require "./form"
 require "./pwa_utils"
+require "./pwa_install_component"
diff --git a/src/pwa_install_component.cr b/src/pwa_install_component.cr
new file mode 100644
index 0000000..9275546
--- /dev/null
+++ b/src/pwa_install_component.cr
@@ -0,0 +1,198 @@
+require "js"
+require "to_html"
+
+module Crumble
+  class PwaInstallComponent
+    include Crumble::ContextView
+
+    class Script < JS::Code
+      def_to_js do
+        _literal_js <<-JS
+        (() => {
+          const root = document.getElementById("crumble-pwa-install");
+          const button = document.getElementById("crumble-pwa-install-trigger");
+          const panel = document.getElementById("crumble-pwa-install-panel");
+          const closeButton = document.getElementById("crumble-pwa-install-panel-close");
+          if (!root || !button || !panel || !closeButton) return;
+
+          let deferredPrompt = null;
+          const mobileMedia = window.matchMedia("(max-width: 900px)");
+          const isMobileAgent = /Android|iPhone|iPad|iPod|IEMobile|Opera Mini/i.test(navigator.userAgent);
+          const isMobile = mobileMedia.matches || isMobileAgent;
+          // iPadOS can report MacIntel, so we include the touch-point fallback.
+          const isIos = /iPhone|iPad|iPod/i.test(navigator.userAgent) || (navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1);
+          const isSafari = /Safari/i.test(navigator.userAgent) && !/CriOS|FxiOS|EdgiOS|OPiOS|Chrome|Android/i.test(navigator.userAgent);
+          const isIosSafari = isIos && isSafari;
+          const isStandalone = () => window.matchMedia("(display-mode: standalone)").matches || window.navigator.standalone === true;
+
+          const closePanel = () => {
+            panel.hidden = true;
+          };
+
+          const openPanel = () => {
+            panel.hidden = false;
+          };
+
+          const hideInstallUi = () => {
+            root.hidden = true;
+            closePanel();
+          };
+
+          const showInstallUi = () => {
+            root.hidden = false;
+          };
+
+          if (!isMobile || isStandalone()) {
+            hideInstallUi();
+            return;
+          }
+
+          if (isIosSafari) showInstallUi();
+
+          // Capture the browser's install event and defer it until button click.
+          window.addEventListener("beforeinstallprompt", event => {
+            event.preventDefault();
+            deferredPrompt = event;
+            if (!isStandalone()) showInstallUi();
+          });
+
+          window.addEventListener("appinstalled", () => {
+            deferredPrompt = null;
+            hideInstallUi();
+          });
+
+          closeButton.addEventListener("click", () => {
+            closePanel();
+          });
+
+          // Clicking the backdrop (outside the panel card) closes the fallback.
+          panel.addEventListener("click", event => {
+            if (event.target === panel) closePanel();
+          });
+
+          button.addEventListener("click", async () => {
+            if (isStandalone()) {
+              hideInstallUi();
+              return;
+            }
+
+            if (isIosSafari) {
+              closePanel();
+              openPanel();
+              return;
+            }
+
+            if (!deferredPrompt) return;
+
+            deferredPrompt.prompt();
+            const choiceResult = await deferredPrompt.userChoice;
+            deferredPrompt = null;
+            if (choiceResult && (choiceResult.outcome === "accepted" || choiceResult.outcome === "dismissed")) hideInstallUi();
+          });
+        })();
+        JS
+      end
+    end
+
+    template do
+      div id: "crumble-pwa-install", hidden: true do
+        button id: "crumble-pwa-install-trigger", type: "button", aria: {haspopup: "dialog", controls: "crumble-pwa-install-panel"} do
+          "Install app"
+        end
+      end
+
+      div id: "crumble-pwa-install-panel", hidden: true do
+        div id: "crumble-pwa-install-panel-dialog", role: "dialog", aria: {modal: true} do
+          p { "To install this app, tap Share, then Add to Home Screen." }
+          button id: "crumble-pwa-install-panel-close", type: "button", aria: {label: "Close install instructions"} do
+            "Close"
+          end
+        end
+      end
+
+      script { Script.to_js }
+
+      style do
+        <<-CSS
+        #crumble-pwa-install {
+          position: fixed;
+          left: 0;
+          right: 0;
+          bottom: 0;
+          width: 100vw;
+          box-sizing: border-box;
+          padding: 0.5rem 0.75rem;
+          background: #f6edac;
+          display: flex;
+          justify-content: center;
+          align-items: center;
+          z-index: 2147483640;
+        }
+
+        #crumble-pwa-install[hidden] {
+          display: none;
+        }
+
+        #crumble-pwa-install-trigger {
+          appearance: none;
+          border: 0;
+          border-radius: 999px;
+          padding: 0.45rem 1rem;
+          background: #757575;
+          color: #ffffff;
+          font-size: 0.9rem;
+          line-height: 1;
+        }
+
+        #crumble-pwa-install-panel {
+          position: fixed;
+          inset: 0;
+          display: flex;
+          justify-content: center;
+          align-items: flex-end;
+          padding: 0 0.75rem 4rem;
+          box-sizing: border-box;
+          background: rgba(0, 0, 0, 0.3);
+          z-index: 2147483641;
+        }
+
+        #crumble-pwa-install-panel[hidden] {
+          display: none;
+        }
+
+        #crumble-pwa-install-panel-dialog {
+          width: min(30rem, 100%);
+          box-sizing: border-box;
+          border-radius: 0.75rem;
+          padding: 0.8rem;
+          background: #ffffff;
+          color: #1f2937;
+          box-shadow: 0 0.5rem 1.5rem rgba(0, 0, 0, 0.2);
+        }
+
+        #crumble-pwa-install-panel-dialog p {
+          margin: 0 0 0.6rem;
+          font-size: 0.9rem;
+        }
+
+        #crumble-pwa-install-panel-close {
+          appearance: none;
+          border: 0;
+          border-radius: 0.5rem;
+          padding: 0.4rem 0.75rem;
+          background: #757575;
+          color: #ffffff;
+          font-size: 0.85rem;
+        }
+
+        @media (min-width: 901px) {
+          #crumble-pwa-install,
+          #crumble-pwa-install-panel {
+            display: none !important;
+          }
+        }
+        CSS
+      end
+    end
+  end
+end

From f08d53633fc22cd2cf3f5d3017bf533657ae5922 Mon Sep 17 00:00:00 2001
From: SB Software Agent <agent@sbsoftware.de>
Date: Sat, 28 Feb 2026 15:45:30 +0100
Subject: [PATCH 2/6] CR-126 Refactor PWA install component to js.cr and css.cr
 DSL usage

---
 spec/pwa_install_component_spec.cr |  50 ++---
 src/pwa_install_component.cr       | 336 ++++++++++++++---------------
 2 files changed, 189 insertions(+), 197 deletions(-)

diff --git a/spec/pwa_install_component_spec.cr b/spec/pwa_install_component_spec.cr
index 77d2652..cf20390 100644
--- a/spec/pwa_install_component_spec.cr
+++ b/spec/pwa_install_component_spec.cr
@@ -17,43 +17,45 @@ end
 describe Crumble::PwaInstallComponent do
   it "renders as a drop-in layout component via #to_html" do
     html = Crumble::PwaInstallComponentSpec::LayoutWithInstall.new(ctx: test_handler_context).to_html
+    style_asset = AssetFileRegistry.query(Crumble::PwaInstallComponent::Style.uri_path).not_nil!
 
-    html.should contain(%(<div id="crumble-pwa-install" hidden>))
-    html.should contain(%(<button id="crumble-pwa-install-trigger" type="button" aria-haspopup="dialog" aria-controls="crumble-pwa-install-panel">Install app</button>))
-    html.should contain(%(<div id="crumble-pwa-install-panel" hidden>))
-    html.should contain(%(<button id="crumble-pwa-install-panel-close" type="button" aria-label="Close install instructions">Close</button>))
+    html.should contain(%(<link rel="stylesheet" href="#{Crumble::PwaInstallComponent::Style.uri_path}">))
+    html.should contain(%(<div class="#{Crumble::PwaInstallComponent::InstallContainer}" hidden>))
+    html.should contain(%(<button class="#{Crumble::PwaInstallComponent::InstallTrigger}" type="button" aria-haspopup="dialog">Install app</button>))
+    html.should contain(%(<div class="#{Crumble::PwaInstallComponent::InstallPanel}" hidden>))
+    html.should contain(%(<button class="#{Crumble::PwaInstallComponent::InstallPanelClose}" type="button" aria-label="Close install instructions">Close</button>))
     html.should contain("To install this app, tap Share, then Add to Home Screen.")
-    html.should contain("#crumble-pwa-install {")
-    html.should contain("background: #f6edac;")
-    html.should contain("#crumble-pwa-install-trigger {")
-    html.should contain("background: #757575;")
+    style_asset.contents.should contain(".#{Crumble::PwaInstallComponent::InstallContainer} {")
+    style_asset.contents.should contain("background: #f6edac;")
+    style_asset.contents.should contain(".#{Crumble::PwaInstallComponent::InstallTrigger} {")
+    style_asset.contents.should contain("background: #757575;")
   end
 
   it "captures deferred beforeinstallprompt and handles install outcomes on custom click" do
     script = Crumble::PwaInstallComponent::Script.to_js
 
-    script.should contain("window.addEventListener(\"beforeinstallprompt\", event => {")
+    script.should contain("window.addEventListener(\"beforeinstallprompt\", (event) => {")
     script.should contain("event.preventDefault();")
-    script.should contain("deferredPrompt = event;")
-    script.should contain("button.addEventListener(\"click\", async () => {")
-    script.should contain("deferredPrompt.prompt();")
-    script.should contain("const choiceResult = await deferredPrompt.userChoice;")
-    script.should contain("choiceResult.outcome === \"accepted\"")
-    script.should contain("choiceResult.outcome === \"dismissed\"")
-    script.should contain("deferredPrompt = null;")
+    script.should contain("deferred_prompt = event;")
+    script.should contain("button.addEventListener(\"click\", async function() {")
+    script.should contain("deferred_prompt.prompt();")
+    script.should contain("choice_result = await deferred_prompt.userChoice;")
+    script.should contain("choice_result.outcome == \"accepted\"")
+    script.should contain("choice_result.outcome == \"dismissed\"")
+    script.should contain("deferred_prompt = undefined;")
   end
 
   it "keeps the control mobile-only, hides when standalone, and shows iOS Safari fallback panel" do
     script = Crumble::PwaInstallComponent::Script.to_js
 
-    script.should contain("const isMobile = mobileMedia.matches || isMobileAgent;")
-    script.should contain("window.matchMedia(\"(display-mode: standalone)\").matches || window.navigator.standalone === true")
-    script.should contain("if (!isMobile || isStandalone()) {")
-    script.should contain("if (isIosSafari) {")
-    script.should contain("closePanel();")
-    script.should contain("openPanel();")
-    script.should contain("panel.addEventListener(\"click\", event => {")
-    script.should contain("if (event.target === panel) closePanel();")
+    script.should contain("is_mobile = mobile_media.matches || is_mobile_agent;")
+    script.should contain("(window.matchMedia(\"(display-mode: standalone)\")).matches || (navigator.standalone == true)")
+    script.should contain("if ((is_mobile == false) || is_standalone) {")
+    script.should contain("if (is_ios_safari) {")
+    script.should contain("close_panel();")
+    script.should contain("open_panel();")
+    script.should contain("panel.addEventListener(\"click\", (event) => {")
+    script.should contain("if (event.target == panel) {")
     script.should contain("window.addEventListener(\"appinstalled\", () => {")
   end
 end
diff --git a/src/pwa_install_component.cr b/src/pwa_install_component.cr
index 9275546..662b071 100644
--- a/src/pwa_install_component.cr
+++ b/src/pwa_install_component.cr
@@ -4,195 +4,185 @@ require "to_html"
 module Crumble
   class PwaInstallComponent
     include Crumble::ContextView
+    css_class InstallContainer
+    css_class InstallTrigger
+    css_class InstallPanel
+    css_class InstallPanelDialog
+    css_class InstallPanelText
+    css_class InstallPanelClose
+
+    class Style < CSS::Stylesheet
+      rule InstallContainer do
+        position :fixed
+        left 0
+        right 0
+        bottom 0
+        width 100.vw
+        box_sizing :border_box
+        padding 0.5.rem, 0.75.rem
+        background "#f6edac"
+        display :flex
+        justify_content :center
+        align_items :center
+        z_index 2147483640
+      end
+
+      rule InstallTrigger do
+        appearance "none"
+        border 0
+        border_radius 999.px
+        padding 0.45.rem, 1.rem
+        background "#757575"
+        color "#ffffff"
+        font_size 0.9.rem
+        line_height 1
+      end
+
+      rule InstallPanel do
+        position :fixed
+        inset 0
+        display :flex
+        justify_content :center
+        align_items :flex_end
+        padding 0, 0.75.rem, 4.rem
+        box_sizing :border_box
+        background "rgba(0, 0, 0, 0.3)"
+        z_index 2147483641
+      end
+
+      rule InstallPanelDialog do
+        width 100.percent
+        max_width 30.rem
+        box_sizing :border_box
+        border_radius 0.75.rem
+        padding 0.8.rem
+        background "#ffffff"
+        color "#1f2937"
+        box_shadow 0.px, 0.5.rem, 1.5.rem, rgb(0, 0, 0, alpha: 20.percent)
+      end
+
+      rule InstallPanelText do
+        margin 0, 0, 0.6.rem
+        font_size 0.9.rem
+      end
+
+      rule InstallPanelClose do
+        appearance "none"
+        border 0
+        border_radius 0.5.rem
+        padding 0.4.rem, 0.75.rem
+        background "#757575"
+        color "#ffffff"
+        font_size 0.85.rem
+      end
+
+      media(min_width 901.px) do
+        rule InstallContainer, InstallPanel do
+          display :none
+        end
+      end
+    end
 
     class Script < JS::Code
       def_to_js do
-        _literal_js <<-JS
-        (() => {
-          const root = document.getElementById("crumble-pwa-install");
-          const button = document.getElementById("crumble-pwa-install-trigger");
-          const panel = document.getElementById("crumble-pwa-install-panel");
-          const closeButton = document.getElementById("crumble-pwa-install-panel-close");
-          if (!root || !button || !panel || !closeButton) return;
-
-          let deferredPrompt = null;
-          const mobileMedia = window.matchMedia("(max-width: 900px)");
-          const isMobileAgent = /Android|iPhone|iPad|iPod|IEMobile|Opera Mini/i.test(navigator.userAgent);
-          const isMobile = mobileMedia.matches || isMobileAgent;
-          // iPadOS can report MacIntel, so we include the touch-point fallback.
-          const isIos = /iPhone|iPad|iPod/i.test(navigator.userAgent) || (navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1);
-          const isSafari = /Safari/i.test(navigator.userAgent) && !/CriOS|FxiOS|EdgiOS|OPiOS|Chrome|Android/i.test(navigator.userAgent);
-          const isIosSafari = isIos && isSafari;
-          const isStandalone = () => window.matchMedia("(display-mode: standalone)").matches || window.navigator.standalone === true;
-
-          const closePanel = () => {
-            panel.hidden = true;
-          };
-
-          const openPanel = () => {
-            panel.hidden = false;
-          };
-
-          const hideInstallUi = () => {
-            root.hidden = true;
-            closePanel();
-          };
-
-          const showInstallUi = () => {
-            root.hidden = false;
-          };
-
-          if (!isMobile || isStandalone()) {
-            hideInstallUi();
-            return;
-          }
-
-          if (isIosSafari) showInstallUi();
-
-          // Capture the browser's install event and defer it until button click.
-          window.addEventListener("beforeinstallprompt", event => {
-            event.preventDefault();
-            deferredPrompt = event;
-            if (!isStandalone()) showInstallUi();
-          });
-
-          window.addEventListener("appinstalled", () => {
-            deferredPrompt = null;
-            hideInstallUi();
-          });
-
-          closeButton.addEventListener("click", () => {
-            closePanel();
-          });
-
-          // Clicking the backdrop (outside the panel card) closes the fallback.
-          panel.addEventListener("click", event => {
-            if (event.target === panel) closePanel();
-          });
-
-          button.addEventListener("click", async () => {
-            if (isStandalone()) {
-              hideInstallUi();
-              return;
-            }
-
-            if (isIosSafari) {
-              closePanel();
-              openPanel();
-              return;
-            }
-
-            if (!deferredPrompt) return;
-
-            deferredPrompt.prompt();
-            const choiceResult = await deferredPrompt.userChoice;
-            deferredPrompt = null;
-            if (choiceResult && (choiceResult.outcome === "accepted" || choiceResult.outcome === "dismissed")) hideInstallUi();
-          });
-        })();
-        JS
+        root = document.querySelector(".crumble--pwa-install-component--install-container")
+        button = document.querySelector(".crumble--pwa-install-component--install-trigger")
+        panel = document.querySelector(".crumble--pwa-install-component--install-panel")
+        close_button = document.querySelector(".crumble--pwa-install-component--install-panel-close")
+
+        if root && button && panel && close_button
+          deferred_prompt = nil
+          user_agent = navigator.userAgent
+          mobile_media = window.matchMedia("(max-width: 900px)")
+          is_mobile_agent = user_agent.includes("Android") || user_agent.includes("iPhone") || user_agent.includes("iPad") || user_agent.includes("iPod") || user_agent.includes("IEMobile") || user_agent.includes("Opera Mini")
+          is_mobile = mobile_media.matches || is_mobile_agent
+
+          # iPadOS can report MacIntel, so we include a touch-point check.
+          is_ios = user_agent.includes("iPhone") || user_agent.includes("iPad") || user_agent.includes("iPod") || (navigator.platform == "MacIntel" && navigator.maxTouchPoints > 1)
+          is_safari = user_agent.includes("Safari") && user_agent.includes("CriOS") == false && user_agent.includes("FxiOS") == false && user_agent.includes("EdgiOS") == false && user_agent.includes("OPiOS") == false && user_agent.includes("Chrome") == false && user_agent.includes("Android") == false
+          is_ios_safari = is_ios && is_safari
+          is_standalone = window.matchMedia("(display-mode: standalone)").matches || navigator.standalone == true
+
+          close_panel = -> { panel.hidden = true }
+          open_panel = -> { panel.hidden = false }
+          hide_install_ui = -> { root.hidden = true; close_panel._call }
+
+          if is_mobile == false || is_standalone
+            hide_install_ui._call
+          else
+            if is_ios_safari
+              root.hidden = false
+            end
+
+            # Capture browser install intent and defer native prompt to custom CTA click.
+            window.addEventListener("beforeinstallprompt", ->(event) do
+              event.preventDefault._call
+              deferred_prompt = event
+              if window.matchMedia("(display-mode: standalone)").matches == false && navigator.standalone != true
+                root.hidden = false
+              end
+            end)
+
+            window.addEventListener("appinstalled", -> do
+              deferred_prompt = nil
+              hide_install_ui._call
+            end)
+
+            close_button.addEventListener("click", -> do
+              close_panel._call
+            end)
+
+            # Treat clicks on the backdrop (outside the panel card) as dismiss.
+            panel.addEventListener("click", ->(event) do
+              if event.target == panel
+                close_panel._call
+              end
+            end)
+
+            button.addEventListener("click", async do
+              is_standalone_now = window.matchMedia("(display-mode: standalone)").matches || navigator.standalone == true
+
+              if is_standalone_now
+                hide_install_ui._call
+              elsif is_ios_safari
+                close_panel._call
+                open_panel._call
+              elsif deferred_prompt
+                deferred_prompt.prompt._call
+                choice_result = await(deferred_prompt.userChoice)
+                deferred_prompt = nil
+
+                if choice_result && (choice_result.outcome == "accepted" || choice_result.outcome == "dismissed")
+                  hide_install_ui._call
+                end
+              end
+            end)
+          end
+        end
       end
     end
 
     template do
-      div id: "crumble-pwa-install", hidden: true do
-        button id: "crumble-pwa-install-trigger", type: "button", aria: {haspopup: "dialog", controls: "crumble-pwa-install-panel"} do
+      Style
+
+      div InstallContainer, hidden: true do
+        button InstallTrigger, type: "button", aria: {haspopup: "dialog"} do
           "Install app"
         end
       end
 
-      div id: "crumble-pwa-install-panel", hidden: true do
-        div id: "crumble-pwa-install-panel-dialog", role: "dialog", aria: {modal: true} do
-          p { "To install this app, tap Share, then Add to Home Screen." }
-          button id: "crumble-pwa-install-panel-close", type: "button", aria: {label: "Close install instructions"} do
+      div InstallPanel, hidden: true do
+        div InstallPanelDialog, role: "dialog", aria: {modal: true} do
+          p InstallPanelText do
+            "To install this app, tap Share, then Add to Home Screen."
+          end
+          button InstallPanelClose, type: "button", aria: {label: "Close install instructions"} do
             "Close"
           end
         end
       end
 
-      script { Script.to_js }
-
-      style do
-        <<-CSS
-        #crumble-pwa-install {
-          position: fixed;
-          left: 0;
-          right: 0;
-          bottom: 0;
-          width: 100vw;
-          box-sizing: border-box;
-          padding: 0.5rem 0.75rem;
-          background: #f6edac;
-          display: flex;
-          justify-content: center;
-          align-items: center;
-          z-index: 2147483640;
-        }
-
-        #crumble-pwa-install[hidden] {
-          display: none;
-        }
-
-        #crumble-pwa-install-trigger {
-          appearance: none;
-          border: 0;
-          border-radius: 999px;
-          padding: 0.45rem 1rem;
-          background: #757575;
-          color: #ffffff;
-          font-size: 0.9rem;
-          line-height: 1;
-        }
-
-        #crumble-pwa-install-panel {
-          position: fixed;
-          inset: 0;
-          display: flex;
-          justify-content: center;
-          align-items: flex-end;
-          padding: 0 0.75rem 4rem;
-          box-sizing: border-box;
-          background: rgba(0, 0, 0, 0.3);
-          z-index: 2147483641;
-        }
-
-        #crumble-pwa-install-panel[hidden] {
-          display: none;
-        }
-
-        #crumble-pwa-install-panel-dialog {
-          width: min(30rem, 100%);
-          box-sizing: border-box;
-          border-radius: 0.75rem;
-          padding: 0.8rem;
-          background: #ffffff;
-          color: #1f2937;
-          box-shadow: 0 0.5rem 1.5rem rgba(0, 0, 0, 0.2);
-        }
-
-        #crumble-pwa-install-panel-dialog p {
-          margin: 0 0 0.6rem;
-          font-size: 0.9rem;
-        }
-
-        #crumble-pwa-install-panel-close {
-          appearance: none;
-          border: 0;
-          border-radius: 0.5rem;
-          padding: 0.4rem 0.75rem;
-          background: #757575;
-          color: #ffffff;
-          font-size: 0.85rem;
-        }
-
-        @media (min-width: 901px) {
-          #crumble-pwa-install,
-          #crumble-pwa-install-panel {
-            display: none !important;
-          }
-        }
-        CSS
-      end
+      Script
     end
   end
 end

From 5985adc1dc268f9f2312d4c770f962f440f5a2b2 Mon Sep 17 00:00:00 2001
From: SB Software Agent <agent@sbsoftware.de>
Date: Sat, 28 Feb 2026 17:11:38 +0100
Subject: [PATCH 3/6] CR-126 Use style macro head injection and hidden class
 toggling for PWA install

---
 spec/pwa_install_component_spec.cr | 12 ++++++++++--
 src/pwa_install_component.cr       | 25 +++++++++++++++----------
 2 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/spec/pwa_install_component_spec.cr b/spec/pwa_install_component_spec.cr
index cf20390..058ec0a 100644
--- a/spec/pwa_install_component_spec.cr
+++ b/spec/pwa_install_component_spec.cr
@@ -20,15 +20,17 @@ describe Crumble::PwaInstallComponent do
     style_asset = AssetFileRegistry.query(Crumble::PwaInstallComponent::Style.uri_path).not_nil!
 
     html.should contain(%(<link rel="stylesheet" href="#{Crumble::PwaInstallComponent::Style.uri_path}">))
-    html.should contain(%(<div class="#{Crumble::PwaInstallComponent::InstallContainer}" hidden>))
+    html.should contain(%(<div class="#{Crumble::PwaInstallComponent::InstallContainer} #{Crumble::PwaInstallComponent::Hidden}">))
     html.should contain(%(<button class="#{Crumble::PwaInstallComponent::InstallTrigger}" type="button" aria-haspopup="dialog">Install app</button>))
-    html.should contain(%(<div class="#{Crumble::PwaInstallComponent::InstallPanel}" hidden>))
+    html.should contain(%(<div class="#{Crumble::PwaInstallComponent::InstallPanel} #{Crumble::PwaInstallComponent::Hidden}">))
     html.should contain(%(<button class="#{Crumble::PwaInstallComponent::InstallPanelClose}" type="button" aria-label="Close install instructions">Close</button>))
     html.should contain("To install this app, tap Share, then Add to Home Screen.")
     style_asset.contents.should contain(".#{Crumble::PwaInstallComponent::InstallContainer} {")
     style_asset.contents.should contain("background: #f6edac;")
     style_asset.contents.should contain(".#{Crumble::PwaInstallComponent::InstallTrigger} {")
     style_asset.contents.should contain("background: #757575;")
+    style_asset.contents.should contain(".#{Crumble::PwaInstallComponent::Hidden} {")
+    style_asset.contents.should contain("display: none;")
   end
 
   it "captures deferred beforeinstallprompt and handles install outcomes on custom click" do
@@ -43,6 +45,9 @@ describe Crumble::PwaInstallComponent do
     script.should contain("choice_result.outcome == \"accepted\"")
     script.should contain("choice_result.outcome == \"dismissed\"")
     script.should contain("deferred_prompt = undefined;")
+    script.should contain("hidden_class = \"crumble--pwa-install-component--hidden\";")
+    script.should contain("show_install_ui = () => {")
+    script.should contain("root.classList.remove(hidden_class);")
   end
 
   it "keeps the control mobile-only, hides when standalone, and shows iOS Safari fallback panel" do
@@ -54,6 +59,9 @@ describe Crumble::PwaInstallComponent do
     script.should contain("if (is_ios_safari) {")
     script.should contain("close_panel();")
     script.should contain("open_panel();")
+    script.should contain("panel.classList.add(hidden_class);")
+    script.should contain("panel.classList.remove(hidden_class);")
+    script.should contain("root.classList.add(hidden_class);")
     script.should contain("panel.addEventListener(\"click\", (event) => {")
     script.should contain("if (event.target == panel) {")
     script.should contain("window.addEventListener(\"appinstalled\", () => {")
diff --git a/src/pwa_install_component.cr b/src/pwa_install_component.cr
index 662b071..0453fd1 100644
--- a/src/pwa_install_component.cr
+++ b/src/pwa_install_component.cr
@@ -10,8 +10,9 @@ module Crumble
     css_class InstallPanelDialog
     css_class InstallPanelText
     css_class InstallPanelClose
+    css_class Hidden
 
-    class Style < CSS::Stylesheet
+    style Style do
       rule InstallContainer do
         position :fixed
         left 0
@@ -76,6 +77,10 @@ module Crumble
         font_size 0.85.rem
       end
 
+      rule Hidden do
+        display :none
+      end
+
       media(min_width 901.px) do
         rule InstallContainer, InstallPanel do
           display :none
@@ -102,16 +107,18 @@ module Crumble
           is_safari = user_agent.includes("Safari") && user_agent.includes("CriOS") == false && user_agent.includes("FxiOS") == false && user_agent.includes("EdgiOS") == false && user_agent.includes("OPiOS") == false && user_agent.includes("Chrome") == false && user_agent.includes("Android") == false
           is_ios_safari = is_ios && is_safari
           is_standalone = window.matchMedia("(display-mode: standalone)").matches || navigator.standalone == true
+          hidden_class = "crumble--pwa-install-component--hidden"
 
-          close_panel = -> { panel.hidden = true }
-          open_panel = -> { panel.hidden = false }
-          hide_install_ui = -> { root.hidden = true; close_panel._call }
+          close_panel = -> { panel.classList.add(hidden_class) }
+          open_panel = -> { panel.classList.remove(hidden_class) }
+          hide_install_ui = -> { root.classList.add(hidden_class); close_panel._call }
+          show_install_ui = -> { root.classList.remove(hidden_class) }
 
           if is_mobile == false || is_standalone
             hide_install_ui._call
           else
             if is_ios_safari
-              root.hidden = false
+              show_install_ui._call
             end
 
             # Capture browser install intent and defer native prompt to custom CTA click.
@@ -119,7 +126,7 @@ module Crumble
               event.preventDefault._call
               deferred_prompt = event
               if window.matchMedia("(display-mode: standalone)").matches == false && navigator.standalone != true
-                root.hidden = false
+                show_install_ui._call
               end
             end)
 
@@ -163,15 +170,13 @@ module Crumble
     end
 
     template do
-      Style
-
-      div InstallContainer, hidden: true do
+      div [InstallContainer, Hidden] do
         button InstallTrigger, type: "button", aria: {haspopup: "dialog"} do
           "Install app"
         end
       end
 
-      div InstallPanel, hidden: true do
+      div [InstallPanel, Hidden] do
         div InstallPanelDialog, role: "dialog", aria: {modal: true} do
           p InstallPanelText do
             "To install this app, tap Share, then Add to Home Screen."

From 388b9655673eefc25683c1d127e5ac9ce6eb725a Mon Sep 17 00:00:00 2001
From: SB Software Agent <agent@sbsoftware.de>
Date: Sat, 28 Feb 2026 17:25:03 +0100
Subject: [PATCH 4/6] CR-126 Use Stylesheet.rgb and class-derived selector refs
 in PWA install component

---
 src/pwa_install_component.cr | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/pwa_install_component.cr b/src/pwa_install_component.cr
index 0453fd1..81c50ea 100644
--- a/src/pwa_install_component.cr
+++ b/src/pwa_install_component.cr
@@ -47,7 +47,7 @@ module Crumble
         align_items :flex_end
         padding 0, 0.75.rem, 4.rem
         box_sizing :border_box
-        background "rgba(0, 0, 0, 0.3)"
+        background CSS::Stylesheet.rgb(0, 0, 0, alpha: 30.percent)
         z_index 2147483641
       end
 
@@ -59,7 +59,7 @@ module Crumble
         padding 0.8.rem
         background "#ffffff"
         color "#1f2937"
-        box_shadow 0.px, 0.5.rem, 1.5.rem, rgb(0, 0, 0, alpha: 20.percent)
+        box_shadow 0.px, 0.5.rem, 1.5.rem, CSS::Stylesheet.rgb(0, 0, 0, alpha: 20.percent)
       end
 
       rule InstallPanelText do
@@ -90,10 +90,10 @@ module Crumble
 
     class Script < JS::Code
       def_to_js do
-        root = document.querySelector(".crumble--pwa-install-component--install-container")
-        button = document.querySelector(".crumble--pwa-install-component--install-trigger")
-        panel = document.querySelector(".crumble--pwa-install-component--install-panel")
-        close_button = document.querySelector(".crumble--pwa-install-component--install-panel-close")
+        root = document.querySelector(InstallContainer.to_css_selector.to_s.to_js_ref)
+        button = document.querySelector(InstallTrigger.to_css_selector.to_s.to_js_ref)
+        panel = document.querySelector(InstallPanel.to_css_selector.to_s.to_js_ref)
+        close_button = document.querySelector(InstallPanelClose.to_css_selector.to_s.to_js_ref)
 
         if root && button && panel && close_button
           deferred_prompt = nil
@@ -107,7 +107,7 @@ module Crumble
           is_safari = user_agent.includes("Safari") && user_agent.includes("CriOS") == false && user_agent.includes("FxiOS") == false && user_agent.includes("EdgiOS") == false && user_agent.includes("OPiOS") == false && user_agent.includes("Chrome") == false && user_agent.includes("Android") == false
           is_ios_safari = is_ios && is_safari
           is_standalone = window.matchMedia("(display-mode: standalone)").matches || navigator.standalone == true
-          hidden_class = "crumble--pwa-install-component--hidden"
+          hidden_class = Hidden.to_s.to_js_ref
 
           close_panel = -> { panel.classList.add(hidden_class) }
           open_panel = -> { panel.classList.remove(hidden_class) }
@@ -170,13 +170,13 @@ module Crumble
     end
 
     template do
-      div [InstallContainer, Hidden] do
+      div InstallContainer, Hidden do
         button InstallTrigger, type: "button", aria: {haspopup: "dialog"} do
           "Install app"
         end
       end
 
-      div [InstallPanel, Hidden] do
+      div InstallPanel, Hidden do
         div InstallPanelDialog, role: "dialog", aria: {modal: true} do
           p InstallPanelText do
             "To install this app, tap Share, then Add to Home Screen."

From 17106b23b2a2aba2357d8c2a16ecd924e234ca11 Mon Sep 17 00:00:00 2001
From: SB Software Agent <agent@sbsoftware.de>
Date: Sat, 28 Feb 2026 17:35:23 +0100
Subject: [PATCH 5/6] CR-126 Use unprefixed rgb helper in PWA install
 stylesheet

---
 src/pwa_install_component.cr | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/pwa_install_component.cr b/src/pwa_install_component.cr
index 81c50ea..d169b25 100644
--- a/src/pwa_install_component.cr
+++ b/src/pwa_install_component.cr
@@ -47,7 +47,7 @@ module Crumble
         align_items :flex_end
         padding 0, 0.75.rem, 4.rem
         box_sizing :border_box
-        background CSS::Stylesheet.rgb(0, 0, 0, alpha: 30.percent)
+        background rgb(0, 0, 0, alpha: 30.percent)
         z_index 2147483641
       end
 
@@ -59,7 +59,7 @@ module Crumble
         padding 0.8.rem
         background "#ffffff"
         color "#1f2937"
-        box_shadow 0.px, 0.5.rem, 1.5.rem, CSS::Stylesheet.rgb(0, 0, 0, alpha: 20.percent)
+        box_shadow 0.px, 0.5.rem, 1.5.rem, rgb(0, 0, 0, alpha: 20.percent)
       end
 
       rule InstallPanelText do

From a432a8f04e025c42ca825e8b516d328f4738cd81 Mon Sep 17 00:00:00 2001
From: SB Software Agent <agent@sbsoftware.de>
Date: Sat, 28 Feb 2026 21:32:57 +0100
Subject: [PATCH 6/6] CR-126 Remove script-only assertions from PWA install
 component spec

---
 spec/pwa_install_component_spec.cr | 34 ------------------------------
 1 file changed, 34 deletions(-)

diff --git a/spec/pwa_install_component_spec.cr b/spec/pwa_install_component_spec.cr
index 058ec0a..486037c 100644
--- a/spec/pwa_install_component_spec.cr
+++ b/spec/pwa_install_component_spec.cr
@@ -32,38 +32,4 @@ describe Crumble::PwaInstallComponent do
     style_asset.contents.should contain(".#{Crumble::PwaInstallComponent::Hidden} {")
     style_asset.contents.should contain("display: none;")
   end
-
-  it "captures deferred beforeinstallprompt and handles install outcomes on custom click" do
-    script = Crumble::PwaInstallComponent::Script.to_js
-
-    script.should contain("window.addEventListener(\"beforeinstallprompt\", (event) => {")
-    script.should contain("event.preventDefault();")
-    script.should contain("deferred_prompt = event;")
-    script.should contain("button.addEventListener(\"click\", async function() {")
-    script.should contain("deferred_prompt.prompt();")
-    script.should contain("choice_result = await deferred_prompt.userChoice;")
-    script.should contain("choice_result.outcome == \"accepted\"")
-    script.should contain("choice_result.outcome == \"dismissed\"")
-    script.should contain("deferred_prompt = undefined;")
-    script.should contain("hidden_class = \"crumble--pwa-install-component--hidden\";")
-    script.should contain("show_install_ui = () => {")
-    script.should contain("root.classList.remove(hidden_class);")
-  end
-
-  it "keeps the control mobile-only, hides when standalone, and shows iOS Safari fallback panel" do
-    script = Crumble::PwaInstallComponent::Script.to_js
-
-    script.should contain("is_mobile = mobile_media.matches || is_mobile_agent;")
-    script.should contain("(window.matchMedia(\"(display-mode: standalone)\")).matches || (navigator.standalone == true)")
-    script.should contain("if ((is_mobile == false) || is_standalone) {")
-    script.should contain("if (is_ios_safari) {")
-    script.should contain("close_panel();")
-    script.should contain("open_panel();")
-    script.should contain("panel.classList.add(hidden_class);")
-    script.should contain("panel.classList.remove(hidden_class);")
-    script.should contain("root.classList.add(hidden_class);")
-    script.should contain("panel.addEventListener(\"click\", (event) => {")
-    script.should contain("if (event.target == panel) {")
-    script.should contain("window.addEventListener(\"appinstalled\", () => {")
-  end
 end