Improve onboarding flow and user guidance

lifeart · claude · lifeart · commit b08b154733d9 · 2026-03-19T14:34:42.000Z
Onboarding:
- Add sound/microphone permission notice (orange callout)
- Add detection range and optimal conditions tips (blue box)
- Expand step descriptions (mic permission, stay still during calibration)
- Add Help (?) button in header to re-show onboarding anytime

Post-onboarding guidance:
- Add dynamic init hint that updates through the user journey
  (init -&gt; calibrate -&gt; scan, with error-specific messages)
- Disabled buttons now explain why in tooltips
- Descriptive status labels (idle -&gt; "click Init Audio to begin")

Error handling:
- Specific messages for mic permission denied and no audio device
- Error hint directs to Diagnostics log

Information gaps filled:
- Heatmap hint explains axes and color meaning
- Profile hint explains peaks and hover interaction
- Geometry hint explains layout and target trails
- Calibration section explains quality scores and conditions
- Direction axis hint explains detection range and surface types
- Keyboard shortcuts listed near viz pane with ? button reference
- Device preset shows (detected) on initial auto-detection

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/index.html b/index.html
@@ -22,7 +22,10 @@
 </head>
 <body>
 <header>
-  <h1>Echoscope — Browser Sonar</h1>
+  <div style="display:flex;justify-content:space-between;align-items:center;">
+    <h1>Echoscope — Browser Sonar</h1>
+    <button id="btnHelp" type="button" class="help-btn" title="Show quick-start guide and keyboard shortcuts.">?</button>
+  </div>
 </header>
 
 <!-- Device answer QR — top-level so it's immediately visible on phone -->
@@ -36,11 +39,11 @@ <h1>Echoscope — Browser Sonar</h1>
 
     <section class="card controls-pane">
       <div class="row actions-sticky" style="justify-content:space-between">
-        <button id="btnInit" title="Initialize Web Audio, request microphone access, and prepare the app for ping/scan operations.">Init Audio <kbd>I</kbd></button>
-        <button id="btnPing" disabled title="Run a single measurement at the current steering angle and update readouts.">Ping <kbd>P</kbd></button>
-        <button id="btnScan" disabled title="Run a full angular sweep using current scan settings and build the heatmap.">Scan <kbd>S</kbd></button>
-        <button id="btnStop" disabled title="Stop the active scan loop immediately.">Stop <kbd>Esc</kbd></button>
-        <button id="btnCalibrate" disabled title="Run direct-path calibration to improve timing lock and range accuracy.">Calibrate <kbd>C</kbd></button>
+        <button id="btnInit" title="Start here: initialize Web Audio and request microphone permission. Required before any other action.">Init Audio <kbd>I</kbd></button>
+        <button id="btnPing" disabled title="Requires Init Audio first. Runs a single measurement at the current steering angle.">Ping <kbd>P</kbd></button>
+        <button id="btnScan" disabled title="Requires Init Audio first. Runs a full angular sweep and builds the heatmap.">Scan <kbd>S</kbd></button>
+        <button id="btnStop" disabled title="No scan is running. Active only during a scan sweep.">Stop <kbd>Esc</kbd></button>
+        <button id="btnCalibrate" disabled title="Requires Init Audio first. Measures speaker-to-mic timing for accurate range.">Calibrate <kbd>C</kbd></button>
       </div>
 
       <div id="levelMeterWrap" style="display:none" class="level-meter-wrap">
@@ -50,8 +53,11 @@ <h1>Echoscope — Browser Sonar</h1>
         <span id="stereoIndicator" class="small indicator-ok" style="display:none;"></span>
       </div>
 
+      <p id="initHint" class="hint" style="color:#8dd0ff;font-weight:600;">
+        &#x2192; Start by clicking <b>Init Audio</b> above to enable microphone access and the audio engine.
+      </p>
       <p class="hint warn">
-        Run on <b>https</b> (or localhost). Keep volume low to avoid feedback. On iPhone, tap buttons to start/resume audio.
+        Run on <b>https</b> (or localhost). Keep volume moderate to avoid feedback. On iPhone, tap buttons to start/resume audio.
       </p>
 
       <details id="quickSetup" class="section-group" open>
@@ -625,12 +631,12 @@ <h1>Echoscope — Browser Sonar</h1>
         </label>
       </div>
 
-      <p class="hint">Use <b>Horizontal (L/R)</b> for left/right and <b>Vertical (T/B)</b> when your speaker axis is rotated 90 degrees.</p>
+      <p class="hint">Use <b>Horizontal (L/R)</b> for left/right and <b>Vertical (T/B)</b> when your speaker axis is rotated 90&deg;. Detection works best on hard, flat surfaces (walls, furniture) within 0.3&#x2013;5 m. Soft materials (curtains, pillows) absorb sound and produce weak echoes.</p>
 
       <hr/>
 
       <!-- Calibration -->
-      <p class="hint">Calibration measures speaker-to-mic distances to lock direct-path timing and improve range accuracy.</p>
+      <p class="hint">Calibration measures speaker-to-mic distances to lock direct-path timing and improve range accuracy. Keep the room quiet and don't move the device during calibration. A quality score above 0.5 is good; above 0.8 is excellent.</p>
       <div class="row" style="justify-content:space-between">
         <label class="checkbox-label">
           <input id="useCalib" type="checkbox" checked title="Use calibration data to constrain direct-path search and reduce ambiguity.">
@@ -769,7 +775,7 @@ <h1>Echoscope — Browser Sonar</h1>
       <details id="heatmapDetails" open style="margin-top:10px">
         <summary>Angle x Range heatmap</summary>
         <p class="hint" style="margin:4px 0 8px">
-          Main scan view: bright spots show stronger reflections by angle and range.
+          Main scan view. Horizontal axis = steering angle (degrees), vertical axis = distance (meters). Brighter colors = stronger echo reflections. Look for bright spots to locate objects.
         </p>
         <canvas id="heatmap" width="1000" height="520" role="img" aria-label="Angle versus range heatmap showing echo strength"></canvas>
         <div class="row" style="margin-top:6px;display:flex;gap:12px;align-items:center;flex-wrap:wrap">
@@ -792,7 +798,7 @@ <h1>Echoscope — Browser Sonar</h1>
       <details id="profileDetails" style="margin-top:10px">
         <summary>Range profile</summary>
         <p class="hint" style="margin:4px 0 8px">
-          Correlation vs range for the latest ping/scan row.
+          Correlation strength vs distance (meters) for the latest ping. Peaks indicate detected objects; taller peaks = stronger reflections. Hover to read exact range values.
         </p>
         <canvas id="profile" width="1000" height="260" role="img" aria-label="Correlation profile showing echo strength vs range"></canvas>
       </details>
@@ -811,7 +817,7 @@ <h1>Echoscope — Browser Sonar</h1>
       <details id="geometryDetails" style="margin-top:10px">
         <summary>Geometry view</summary>
         <p class="hint" style="margin:4px 0 8px">
-          Device layout and target position estimate in top view.
+          Top-down view showing speaker positions (L/R), microphone, and estimated target locations. Tracked targets show trails indicating movement history.
         </p>
         <canvas id="geometry" width="1000" height="280" role="img" aria-label="Geometry view showing speaker and microphone positions"></canvas>
         <div class="row" style="margin-top:8px">
@@ -826,6 +832,7 @@ <h1>Echoscope — Browser Sonar</h1>
       </details>
 
       <p class="hint">If audio goes silent after switching apps/locking screen: tap <b>Init Audio</b> to resume.</p>
+      <p class="hint">Keyboard shortcuts: <kbd>I</kbd> Init Audio, <kbd>P</kbd> / <kbd>Space</kbd> Ping, <kbd>S</kbd> Scan, <kbd>Esc</kbd> Stop, <kbd>C</kbd> Calibrate. Click <b>?</b> in the header for the full guide.</p>
     </section>
 
   </div>
@@ -836,12 +843,14 @@ <h1>Echoscope — Browser Sonar</h1>
   <div class="onboarding-dialog">
     <h2>Welcome to Echoscope</h2>
     <p class="onboarding-subtitle">Browser-based active sonar echolocation. Transmit acoustic signals through your speakers, capture echoes with your microphone, and visualize your surroundings in real time.</p>
+    <p class="onboarding-notice">&#x1f50a; This app emits audible sound through your speakers and requires <b>microphone permission</b> to capture echoes. Use headphones-free and keep volume moderate.</p>
     <ol class="onboarding-steps">
       <li><b>Select your device</b> &#x2014; pick your laptop or tablet from the <em>Device preset</em> dropdown so speaker/mic geometry is correct.</li>
-      <li><b>Init Audio</b> &#x2014; click the button (or press <kbd>I</kbd>) to grant microphone access and start the audio engine.</li>
-      <li><b>Calibrate</b> &#x2014; click <em>Calibrate</em> (or press <kbd>C</kbd>) to measure speaker-to-mic timing in your room.</li>
-      <li><b>Scan</b> &#x2014; click <em>Scan</em> (or press <kbd>S</kbd>) to start echolocation and build a heatmap.</li>
+      <li><b>Init Audio</b> &#x2014; click the button (or press <kbd>I</kbd>) to grant microphone access and start the audio engine. Your browser will ask for mic permission.</li>
+      <li><b>Calibrate</b> &#x2014; click <em>Calibrate</em> (or press <kbd>C</kbd>) to measure speaker-to-mic timing in your room. Stay still and keep the room quiet.</li>
+      <li><b>Scan</b> &#x2014; click <em>Scan</em> (or press <kbd>S</kbd>) to start echolocation and build a heatmap of nearby objects.</li>
     </ol>
+    <p class="onboarding-tip">Typical detection range is <b>0.3 &#x2013; 5 m</b> indoors. Hard, flat surfaces (walls, furniture, monitors) reflect best. A quiet room with minimal background noise gives the best results.</p>
     <div class="onboarding-actions">
       <button id="onboardingDismiss" type="button">Get Started</button>
       <a id="onboardingNeverShow" href="#" class="onboarding-skip">Don't show again</a>
diff --git a/src/styles/main.css b/src/styles/main.css
@@ -177,6 +177,52 @@ kbd { padding:1px 5px; font-size:10px; color:#9e9e9e; background:#1a1a1a; border
 	text-decoration: underline;
 }
 
+.onboarding-notice {
+	font-size: 12px;
+	color: #ffbf80;
+	line-height: 1.45;
+	margin: 0 0 12px;
+	padding: 8px 10px;
+	background: rgba(255, 191, 128, 0.08);
+	border: 1px solid rgba(255, 191, 128, 0.18);
+	border-radius: 8px;
+}
+
+.onboarding-tip {
+	font-size: 12px;
+	color: #8dd0ff;
+	line-height: 1.45;
+	margin: 0 0 16px;
+	padding: 8px 10px;
+	background: rgba(141, 208, 255, 0.06);
+	border: 1px solid rgba(141, 208, 255, 0.15);
+	border-radius: 8px;
+}
+
+.help-btn {
+	background: transparent;
+	border: 1px solid #444;
+	color: #bdbdbd;
+	border-radius: 50%;
+	width: 28px;
+	height: 28px;
+	padding: 0;
+	font-size: 14px;
+	font-weight: 700;
+	line-height: 1;
+	cursor: pointer;
+	flex-shrink: 0;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+}
+
+.help-btn:hover {
+	color: #eaeaea;
+	border-color: #888;
+	background: rgba(255, 255, 255, 0.05);
+}
+
 /* ---- Status error ---- */
 .status-error { color: #f44336; font-weight: bold; }
 
diff --git a/src/ui/app.ts b/src/ui/app.ts
@@ -124,6 +124,11 @@ export function initApp(): void {
       await refreshDeviceInfo();
       const audioState = store.get().audio;
       log(`[ok] audio initialized: sr=${audioState.actualSampleRate} Hz, capture=${audioState.captureMethod}, channels=${audioState.channelCount}`);
+      // Hide the init hint and show next-step guidance
+      const initHintEl = el('initHint');
+      if (initHintEl) {
+        initHintEl.textContent = '\u2192 Audio ready. Next: click Calibrate for best accuracy, or Scan to start immediately.';
+      }
       const stereoEl = el('stereoIndicator');
       if (stereoEl) {
         if (audioState.channelCount >= 2) {
@@ -141,7 +146,19 @@ export function initApp(): void {
     } catch (e: any) {
       if (btn) { btn.disabled = false; btn.textContent = 'Init Audio [I]'; }
       setStatus('error');
-      log('[err] init failed: ' + (e?.message || e));
+      const msg = e?.message || String(e);
+      if (/permission|denied|not allowed/i.test(msg)) {
+        log('[err] Microphone permission denied. Please allow mic access in your browser settings and try again.');
+      } else if (/not found|no device/i.test(msg)) {
+        log('[err] No audio input device found. Connect a microphone and try again.');
+      } else {
+        log('[err] init failed: ' + msg);
+      }
+      const initHintEl = el('initHint');
+      if (initHintEl) {
+        initHintEl.style.color = '#ffbf80';
+        initHintEl.textContent = '\u2192 Init failed. Check the Diagnostics log below for details, then retry Init Audio.';
+      }
     }
   });
 
@@ -198,6 +215,13 @@ export function initApp(): void {
         drawCalibSanityPlot(calib.sanity.curveL, calib.sanity.peakIndexL, calib.sanity.curveR, calib.sanity.peakIndexR, calib.sanity.earlyMs);
       }
       drawGeometry(store.get().config.minRange, store.get().config.maxRange);
+      // Update hint after successful calibration
+      const calibHintEl = el('initHint');
+      if (calibHintEl) {
+        const q = store.get().calibration?.quality ?? 0;
+        calibHintEl.style.color = q > 0.5 ? '#4caf50' : '#ffbf80';
+        calibHintEl.textContent = `\u2713 Calibrated (quality ${q.toFixed(2)}). Click Scan to start echolocation.`;
+      }
     } catch (e: any) {
       setStatus('error');
       log('[err] calibrate failed: ' + (e?.message || e));
diff --git a/src/ui/controls.ts b/src/ui/controls.ts
@@ -375,9 +375,35 @@ export function setButtonStates(audioReady: boolean, scanning: boolean): void {
   const btnCalibrate = el('btnCalibrate') as HTMLButtonElement | null;
   const btnRefreshDevices = el('btnRefreshDevices') as HTMLButtonElement | null;
 
-  if (btnPing) btnPing.disabled = !audioReady || scanning;
-  if (btnScan) btnScan.disabled = !audioReady || scanning;
-  if (btnStop) btnStop.disabled = !audioReady || !scanning;
-  if (btnCalibrate) btnCalibrate.disabled = !audioReady || scanning;
+  if (btnPing) {
+    btnPing.disabled = !audioReady || scanning;
+    btnPing.title = !audioReady
+      ? 'Requires Init Audio first. Runs a single measurement at the current steering angle.'
+      : scanning
+        ? 'Busy: a scan is in progress. Stop it first.'
+        : 'Run a single measurement at the current steering angle and update readouts.';
+  }
+  if (btnScan) {
+    btnScan.disabled = !audioReady || scanning;
+    btnScan.title = !audioReady
+      ? 'Requires Init Audio first. Runs a full angular sweep and builds the heatmap.'
+      : scanning
+        ? 'A scan is already running.'
+        : 'Run a full angular sweep using current scan settings and build the heatmap.';
+  }
+  if (btnStop) {
+    btnStop.disabled = !audioReady || !scanning;
+    btnStop.title = !scanning
+      ? 'No scan is running. Active only during a scan sweep.'
+      : 'Stop the active scan loop immediately.';
+  }
+  if (btnCalibrate) {
+    btnCalibrate.disabled = !audioReady || scanning;
+    btnCalibrate.title = !audioReady
+      ? 'Requires Init Audio first. Measures speaker-to-mic timing for accurate range.'
+      : scanning
+        ? 'Busy: a scan is in progress. Stop it first.'
+        : 'Run direct-path calibration to improve timing lock and range accuracy.';
+  }
   if (btnRefreshDevices) btnRefreshDevices.disabled = !audioReady;
 }
diff --git a/src/ui/device-presets.ts b/src/ui/device-presets.ts
@@ -78,16 +78,16 @@ export function applyDevicePreset(key: string, silent = false): void {
     }
   });
 
+  // Show "(detected)" hint on the selected preset option
+  const option = devicePresetEl?.querySelector(`option[value="${key}"]`);
+  if (option && !option.textContent?.includes('(detected)')) {
+    option.textContent += ' (detected)';
+  }
+
   if (!silent) {
     const dStr = preset.d !== null ? `d=${preset.d}m` : 'manual';
     const micStr = preset.mic.x !== null ? `mic\u2248(${preset.mic.x}, ${preset.mic.y})m` : 'manual';
     log(`[preset] ${preset.name}: ${dStr}, ${micStr}`);
-
-    // Show "(detected)" hint on auto-detected preset option
-    const option = devicePresetEl?.querySelector(`option[value="${key}"]`);
-    if (option && !option.textContent?.includes('(detected)')) {
-      option.textContent += ' (detected)';
-    }
   }
 
   // Apply laptop mode scan settings if checkbox is checked
diff --git a/src/ui/onboarding.ts b/src/ui/onboarding.ts
@@ -4,38 +4,7 @@ function el(id: string): HTMLElement | null {
   return document.getElementById(id);
 }
 
-/** Show onboarding overlay on first visit. No-op if already dismissed. */
-export function initOnboarding(): void {
-  if (localStorage.getItem(STORAGE_KEY)) return;
-
-  const overlay = el('onboardingOverlay');
-  if (!overlay) return;
-
-  overlay.classList.remove('hidden');
-
-  // Remember previously focused element to restore on dismiss
-  const previouslyFocused = document.activeElement as HTMLElement | null;
-
-  const dismiss = () => {
-    overlay.classList.add('hidden');
-    localStorage.setItem(STORAGE_KEY, '1');
-    // Return focus to previously focused element
-    if (previouslyFocused && typeof previouslyFocused.focus === 'function') {
-      previouslyFocused.focus();
-    }
-  };
-
-  // "Get Started" button
-  const dismissBtn = el('onboardingDismiss');
-  dismissBtn?.addEventListener('click', dismiss);
-
-  // "Don't show again" link — same effect
-  const neverShowLink = el('onboardingNeverShow');
-  neverShowLink?.addEventListener('click', (ev) => {
-    ev.preventDefault();
-    dismiss();
-  });
-
+function setupOverlayBehavior(overlay: HTMLElement, dismiss: () => void): void {
   // Click outside the dialog box to dismiss
   overlay.addEventListener('click', (ev) => {
     if (ev.target === overlay) dismiss();
@@ -70,6 +39,39 @@ export function initOnboarding(): void {
       }
     }
   });
+}
+
+/** Show the onboarding overlay and wire dismiss behavior. */
+function showOverlay(): void {
+  const overlay = el('onboardingOverlay');
+  if (!overlay) return;
+
+  // Remember previously focused element to restore on dismiss
+  const previouslyFocused = document.activeElement as HTMLElement | null;
+
+  overlay.classList.remove('hidden');
+
+  const dismiss = () => {
+    overlay.classList.add('hidden');
+    localStorage.setItem(STORAGE_KEY, '1');
+    // Return focus to previously focused element
+    if (previouslyFocused && typeof previouslyFocused.focus === 'function') {
+      previouslyFocused.focus();
+    }
+  };
+
+  // "Get Started" button
+  const dismissBtn = el('onboardingDismiss');
+  dismissBtn?.addEventListener('click', dismiss);
+
+  // "Don't show again" link — same effect
+  const neverShowLink = el('onboardingNeverShow');
+  neverShowLink?.addEventListener('click', (ev) => {
+    ev.preventDefault();
+    dismiss();
+  });
+
+  setupOverlayBehavior(overlay, dismiss);
 
   // Move focus to the "Get Started" button when dialog opens
   if (dismissBtn) {
@@ -78,3 +80,18 @@ export function initOnboarding(): void {
     });
   }
 }
+
+/** Show onboarding overlay on first visit. No-op if already dismissed. */
+export function initOnboarding(): void {
+  // Wire up the Help (?) button so it always re-shows the overlay
+  const helpBtn = el('btnHelp');
+  if (helpBtn) {
+    helpBtn.addEventListener('click', () => {
+      showOverlay();
+    });
+  }
+
+  if (localStorage.getItem(STORAGE_KEY)) return;
+
+  showOverlay();
+}
diff --git a/src/ui/readouts.ts b/src/ui/readouts.ts
@@ -5,10 +5,20 @@ function el(id: string): HTMLElement | null {
   return document.getElementById(id);
 }
 
+const STATUS_LABELS: Record<string, string> = {
+  idle: 'idle — click Init Audio to begin',
+  initializing: 'initializing audio...',
+  ready: 'ready — audio active',
+  pinging: 'pinging...',
+  scanning: 'scanning...',
+  calibrating: 'calibrating...',
+  error: 'error — see Diagnostics log',
+};
+
 export function setStatus(msg: string): void {
   const statusEl = el('status');
   if (statusEl) {
-    statusEl.textContent = 'Status: ' + msg;
+    statusEl.textContent = 'Status: ' + (STATUS_LABELS[msg] ?? msg);
     statusEl.classList.toggle('status-error', msg === 'error');
   }
 }
