feat: surface mobile device readiness (Closes #559)

frontend/dashboard.css

@@ -28,6 +28,11 @@ button { background: linear-gradient(180deg,#1f3a5f,#15324d); border:1px solid #
 .device-setup-step { min-width:0; display:grid; grid-template-columns:minmax(0,1fr) auto; gap:12px; align-items:center; padding:12px; border:1px solid #2a496e; border-radius:12px; background:#10233a; overflow-wrap:anywhere; }
 .device-setup-step p { margin:5px 0 0; }
 .device-setup-ready { margin:0; padding:12px; border-radius:10px; background:#0f2237; color:#bfdbfe; font-weight:700; }
+.device-readiness-card { display:none; min-width:0; margin:10px 0; padding:12px; border:1px solid #3b82b8; border-radius:12px; background:#102b46; overflow-x:hidden; }
+.device-readiness-card p { margin:5px 0 0; overflow-wrap:anywhere; }
+.device-readiness-summary { color:#bfdbfe; font-weight:700; }
+.device-readiness-actions { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:8px; }
+.device-readiness-actions button { min-height:44px; min-width:0; }
 .active-device { display:grid; grid-template-columns:minmax(0,1fr) auto; gap:8px; align-items:center; padding:12px; border:1px solid #2a496e; border-radius:12px; background:#0f2237; }
 .active-device strong, .active-device span { display:block; overflow-wrap:anywhere; }
 .active-device-current { color:#55d6be; font-weight:700; }
@@ -476,6 +481,7 @@ textarea { resize: vertical; min-height: 120px; }
   .device-setup-panel { width:100%; padding:14px; padding-bottom:calc(14px + env(safe-area-inset-bottom)); }
   .device-setup-step { grid-template-columns:1fr; }
   .device-setup-action { width:100%; }
+  .device-readiness-card:not([hidden]) { display:grid; gap:12px; margin-left:max(0px,env(safe-area-inset-left)); margin-right:max(0px,env(safe-area-inset-right)); }
   .my-work { margin:0; }
   .my-work-header { align-items:flex-start; }
   .my-work-actions { width:100%; flex-wrap:nowrap; }

frontend/dashboard.js

@@ -5290,6 +5290,7 @@
       await controller.init();
       return controller;
     }).catch(error => {
+      qs('#push-updates').disabled = true;
       qs('#push-update-status').textContent = 'Update notification settings unavailable.';
       console.warn('Push notifications unavailable', error);
       return null;
@@ -5304,8 +5305,8 @@
     deferredInstallPrompt = event;
   });
   let deviceSetup = null;
-  qs('#open-device-setup').addEventListener('click', async event => {
-    if (deviceSetup) return;
+  async function ensureDeviceSetup() {
+    if (deviceSetup) return deviceSetup;
     await issueCaptureFeatures.load('device-setup');
     const isIosDevice = /iPad|iPhone|iPod/.test(navigator.userAgent) ||
       (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1);
@@ -5319,7 +5320,7 @@
     });
     installApp.start();
     deviceSetup = createMobileDeviceSetup.mount({
-      document, installApp,
+      document, installApp, promptStorage:localStorage,
       offlineAvailable:() => offlineStorageReady,
       offlineEnabled:() => offlineWorkStore.enabled(),
       enableOffline:() => setOfflineWorkEnabled(true),
@@ -5330,12 +5331,17 @@
         await controller.change();
       },
     });
-    deviceSetup.start();
-    await deviceSetup.open(event);
+    await deviceSetup.start();
+    return deviceSetup;
+  }
+  qs('#open-device-setup').addEventListener('click', async event => {
+    if (!deviceSetup) await (await ensureDeviceSetup()).open(event);
   });
+  pushControllerReady.then(ensureDeviceSetup).catch(console.warn);
   contextPoller.start();
   document.addEventListener('visibilitychange', () => {
     contextPoller.setVisible(!document.hidden);
+    if (!document.hidden) deviceSetup?.render();
   });
 
   /* Widgets */

frontend/index.html

@@ -146,6 +146,17 @@
         </div>
       </details>
     </div>
+    <section class="device-readiness-card" id="device-readiness-card" aria-labelledby="device-readiness-heading" hidden>
+      <div>
+        <strong id="device-readiness-heading">Make this phone work-ready</strong>
+        <p class="small muted">Install, save work offline, and enable update alerts.</p>
+        <p class="small device-readiness-summary" id="device-readiness-summary" role="status" aria-live="polite"></p>
+      </div>
+      <div class="device-readiness-actions">
+        <button id="finish-device-setup" type="button">Finish setup</button>
+        <button id="dismiss-device-readiness" type="button">Not now</button>
+      </div>
+    </section>
     <div class="update-selection-controls" id="update-selection-controls" hidden>
       <button id="select-updates" type="button">Select updates</button>
       <button id="cancel-update-selection" type="button" hidden>Cancel selection</button>

frontend/mobile-device-setup.js

@@ -2,6 +2,8 @@
   if (typeof module === 'object' && module.exports) module.exports = factory;
   else root.createMobileDeviceSetup = factory;
 })(typeof self !== 'undefined' ? self : this, function createMobileDeviceSetup(options) {
+  const promptDismissKey = 'stackchain.device-setup-prompt-dismissed-until';
+  const promptDismissMs = 7 * 24 * 60 * 60 * 1000;
   const steps = [
     ['install', options.installButton, options.installStatus, options.install],
     ['offline', options.offlineButton, options.offlineStatus, options.enableOffline],
@@ -9,6 +11,23 @@
   ];
   let trigger = options.launcher;
 
+  function readinessCounts(readiness) {
+    const available = steps.filter(([name]) => readiness[name].state !== 'unavailable').length;
+    const complete = steps.filter(([name]) => readiness[name].state === 'complete').length;
+    return {available, complete};
+  }
+
+  function renderPrompt(readiness) {
+    if (!options.promptCard) return;
+    const {available, complete} = readinessCounts(readiness);
+    let dismissed = false;
+    try {
+      dismissed = Number(options.promptStorage?.getItem(promptDismissKey) || 0) > (options.now?.() ?? Date.now());
+    } catch (_error) {}
+    options.promptSummary.textContent = `${complete} of ${available} steps complete`;
+    options.promptCard.hidden = dismissed || available === 0 || complete === available;
+  }
+
   async function render() {
     const readiness = await options.getReadiness();
     let available = 0;
@@ -24,6 +43,7 @@
     options.readyStatus.textContent = complete === available
       ? 'This device is ready.'
       : `${complete} of ${available} available steps ready.`;
+    renderPrompt(readiness);
     return readiness;
   }
 
@@ -39,8 +59,15 @@
     trigger?.focus?.();
   }
 
-  function start() {
+  async function start() {
     options.launcher.addEventListener('click', open);
+    options.promptLauncher?.addEventListener('click', open);
+    options.promptDismiss?.addEventListener('click', () => {
+      try {
+        options.promptStorage?.setItem(promptDismissKey, String((options.now?.() ?? Date.now()) + promptDismissMs));
+      } catch (_error) {}
+      options.promptCard.hidden = true;
+    });
     options.closeButton.addEventListener('click', close);
     options.sheet.addEventListener('click', event => {
       if (event.target === options.sheet) close();
@@ -55,6 +82,7 @@
         finally { await render(); }
       });
     });
+    renderPrompt(await options.getReadiness());
   }
 
   return {start, open, close, render};
@@ -74,6 +102,9 @@ function mountMobileDeviceSetup(options) {
     offlineButton:qs('#device-setup-offline'), pushButton:qs('#device-setup-push'),
     installStatus:qs('#device-setup-install-status'), offlineStatus:qs('#device-setup-offline-status'),
     pushStatus:qs('#device-setup-push-status'), readyStatus:qs('#device-setup-ready-status'),
+    promptCard:qs('#device-readiness-card'), promptSummary:qs('#device-readiness-summary'),
+    promptLauncher:qs('#finish-device-setup'), promptDismiss:qs('#dismiss-device-readiness'),
+    promptStorage:options.promptStorage,
     escapeTarget:options.document,
     getReadiness:() => ({
       install:options.installApp.state(),

frontend/service-worker.js

@@ -1,6 +1,6 @@
 const BASE = new URL('./', self.location.href).pathname;
 importScripts(BASE + 'static/background-issue-sync.js');
-const CACHE = 'stackchain-dashboard-shell-v87';
+const CACHE = 'stackchain-dashboard-shell-v88';
 const OFFLINE_LEASE_URL = new URL(BASE + '__offline-session-lease', self.location.origin).href;
 const OUTAGE_STATUSES = new Set([500, 502, 503, 504]);
 const NAVIGATION_TIMEOUT_MS = self.__STACKCHAIN_NAVIGATION_TIMEOUT_MS || 4000;