fix(pwa): Install button shows steps instead of silently dismissing

The PWA install affordance had two failure modes that looked
identical to the user (click → drawer closes → nothing installs):

  1. `kind: "generic"` state hits when Chromium's
     beforeinstallprompt hasn't fired yet. The onClick handler called
     dismiss() with no fallback path, so a tap just hid the row for
     30 days.
  2. `kind: "chromium"` with a saved event but the saved event has
     already been consumed (Chrome only lets prompt() fire once per
     engagement window). prompt() throws, the catch ran dismiss(),
     same broken UX.

Fix:

  - generic + ios states now expand to show browser-specific
    instructions inline ("Tap Share, then Add to Home Screen" /
    "Open the three-dot menu → Install app", etc.). The X button
    is still the only way to dismiss for 30 days.
  - chromium state's failure path also expands instructions so the
    user has a working route even when prompt() refuses.
  - UA-sniffed step lists for iOS Safari, Android Chrome, Edge,
    desktop Chrome, with a generic fallback for everything else.

The native install dialog still triggers on Android Chrome / desktop
Chrome / Edge when beforeinstallprompt has actually been captured
and not yet consumed; the user just gets a useful fallback instead
of an opaque close.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Signed-off-by: Tim Thomas <0800tim@gmail.com>

Author: 0800tim

apps/web/components/shell/InstallPrompt.tsx

@@ -86,8 +86,52 @@ function isIosSafari(): boolean {
   return isIos && !isChromeOrFx;
 }
 
+/** Browser-specific instruction copy shown when we can't trigger the
+ * native install dialog. Falls back to a generic step list when we
+ * can't sniff the UA. Tim 2026-05-23: clicking Install used to call
+ * dismiss() and close the drawer with no install path; this state
+ * now expands the row to show what to do. */
+function instructionSteps(state: InstallState): readonly string[] {
+  if (state.kind === "ios") {
+    return [
+      "Tap the Share icon at the bottom of Safari.",
+      "Scroll the share sheet and tap “Add to Home Screen”.",
+      "Tap Add. Tournamental opens like a normal app from your home screen.",
+    ];
+  }
+  if (typeof window !== "undefined") {
+    const ua = window.navigator.userAgent ?? "";
+    if (/Android.*Chrome/i.test(ua)) {
+      return [
+        "Tap the three-dot menu at the top right of Chrome.",
+        "Tap “Install app” (or “Add to Home screen”).",
+        "Confirm to install. Tournamental launches from your home screen with no browser chrome.",
+      ];
+    }
+    if (/Edg\//i.test(ua)) {
+      return [
+        "Click the three-dot menu at the top right of Edge.",
+        "Choose Apps → Install Tournamental.",
+        "Confirm. Tournamental opens in its own window.",
+      ];
+    }
+    if (/Chrome/i.test(ua) && !/Mobile/i.test(ua)) {
+      return [
+        "Click the install icon in the address bar (small box with a downward arrow), or open the three-dot menu and choose Cast, save, and share → Install Tournamental.",
+        "Confirm. Tournamental opens in its own window.",
+      ];
+    }
+  }
+  return [
+    "Open your browser’s main menu (usually three dots or a hamburger icon).",
+    "Look for “Install app”, “Add to Home Screen”, or “Install Tournamental”.",
+    "Confirm. Tournamental launches as a standalone app.",
+  ];
+}
+
 export function InstallPrompt() {
   const [state, setState] = useState<InstallState>({ kind: "hidden" });
+  const [showSteps, setShowSteps] = useState(false);
 
   useEffect(() => {
     if (typeof window === "undefined") return undefined;
@@ -139,17 +183,28 @@ export function InstallPrompt() {
       try {
         await state.event.prompt();
         const choice = await state.event.userChoice;
-        if (choice.outcome === "accepted" || choice.outcome === "dismissed") {
+        if (choice.outcome === "accepted") {
           dismiss();
+          return;
         }
+        // outcome === "dismissed": Chrome will refuse to fire the
+        // same prompt event again, so fall through to the instructions
+        // hint instead of silently re-dismissing. The user clicked
+        // Install for a reason; give them a path that still works.
+        setShowSteps(true);
       } catch {
-        dismiss();
+        // event.prompt() can throw if the saved event has been
+        // consumed already (the browser only lets prompt() fire once
+        // per engagement). Show instructions in that case too.
+        setShowSteps(true);
       }
       return;
     }
-    // iOS + generic paths: no programmatic install API. Tapping the
-    // line counts as "saw the hint" and dismisses for 30 days.
-    dismiss();
+    // iOS + generic paths: no programmatic install API; expand to
+    // show browser-specific instructions instead of dismissing the
+    // affordance (Tim 2026-05-23 — clicking Install used to close
+    // the drawer without anything happening).
+    setShowSteps((v) => !v);
   };
 
   // Single-word visible label per Tim 2026-05-21 ("just say Install").
@@ -162,13 +217,19 @@ export function InstallPrompt() {
         ? "Install Tournamental: open your browser menu, then Install app"
         : "Install Tournamental as an app";
 
+  const steps = showSteps ? instructionSteps(state) : null;
+
   return (
-    <div className="vt-drawer-install">
+    <div
+      className="vt-drawer-install"
+      data-expanded={showSteps ? "1" : undefined}
+    >
       <button
         type="button"
         className="vt-drawer-install-cta"
         onClick={onClick}
         aria-label={ariaLabel}
+        aria-expanded={showSteps}
       >
         {/* Standard install glyph (downward arrow into tray) per
          * 2026-05-21 — the gold ball was misread as a generic logo
@@ -206,6 +267,13 @@ export function InstallPrompt() {
       >
         ✕
       </button>
+      {steps && (
+        <ol className="vt-drawer-install-steps" aria-live="polite">
+          {steps.map((s, i) => (
+            <li key={i}>{s}</li>
+          ))}
+        </ol>
+      )}
     </div>
   );
 }

apps/web/components/shell/shell.css

@@ -786,12 +786,34 @@
    * + bottom safe-area margin from the old foot position are dropped;
    * a leading hairline rule under the drawer header is enough
    * separation. The element stays a flex row so the dismiss X can
-   * sit alongside the CTA. */
+   * sit alongside the CTA; the optional instruction list (Tim
+   * 2026-05-23) wraps onto a new row below when shown. */
   display: flex;
   align-items: stretch;
   gap: 4px;
   margin: 8px 16px 16px;
   padding: 0;
+  flex-wrap: wrap;
+}
+
+.vt-drawer-install-steps {
+  flex-basis: 100%;
+  margin: 8px 0 0;
+  padding: 12px 14px 12px 32px;
+  list-style: decimal;
+  background: rgba(192, 138, 38, 0.08);
+  border: 1px solid rgba(192, 138, 38, 0.32);
+  border-radius: var(--vt-radius-md, 10px);
+  color: var(--vt-fg, #f4f4f5);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.vt-drawer-install-steps li {
+  margin: 0 0 6px;
+}
+.vt-drawer-install-steps li:last-child {
+  margin-bottom: 0;
 }
 
 .vt-drawer-install-cta {