Require a nickname before joining and add a quick-start help modal

New visitors (no nickname in localStorage) get a blocking welcome
modal instead of a silently-generated guest-N name, so everyone in a
room has a name they actually chose. It doubles as quick-start help
(join a channel, mic/deafen/share shortcuts, drag-to-reposition on the
spatial map) reachable any time via the new ? button. The sidebar nick
field no longer falls back to a random name when cleared — it now
just rejects the blank edit.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

public/app.js

@@ -40,6 +40,7 @@ const els = {
   meAvatar: $('#me-avatar'), mic: $('#btn-mic'), deafen: $('#btn-deafen'),
   reconnectBanner: $('#reconnect-banner'), reconnectText: $('#reconnect-text'),
   mxPanel: $('#mx-panel'), mxMessages: $('#mx-messages'), mxInput: $('#mx-input'),
+  welcomeBackdrop: $('#welcome-backdrop'), welcomeNick: $('#welcome-nick'), welcomeNickError: $('#welcome-nick-error'),
 };
 
 // ---------------------------------------------------------------------------
@@ -1280,16 +1281,13 @@ $('#btn-settings').onclick = openSettings;
 
 els.nick.value = S.name;
 els.nick.addEventListener('change', () => {
-  S.name = els.nick.value.trim() || `guest-${Math.random().toString(36).slice(2, 6)}`;
+  const trimmed = els.nick.value.trim();
+  if (!trimmed) { els.nick.value = S.name; return; } // nickname can't be blanked out
+  S.name = trimmed;
   els.nick.value = S.name;
   localStorage.setItem(LS_NAME, S.name);
   setAvatar(els.meAvatar, S.name, S.myId || 'me');
 });
-if (!S.name) {
-  S.name = `guest-${Math.random().toString(36).slice(2, 6)}`;
-  els.nick.value = S.name;
-  localStorage.setItem(LS_NAME, S.name);
-}
 setAvatar(els.meAvatar, S.name, 'me');
 
 document.querySelectorAll('.channel.voice').forEach((el) => {
@@ -1375,3 +1373,39 @@ $('#ice-save').onclick = () => {
   $('#modal-backdrop').classList.add('hidden');
   toast(enabled ? 'Custom ICE saved — rejoin to apply' : 'Reverted to server ICE — rejoin to apply', 'ok');
 };
+
+// ---------------------------------------------------------------------------
+// welcome modal — required nickname + quick-start info
+// ---------------------------------------------------------------------------
+let welcomeRequired = false;
+function openWelcome(required) {
+  welcomeRequired = required;
+  els.welcomeNick.value = S.name;
+  els.welcomeNick.classList.remove('invalid');
+  els.welcomeNickError.classList.add('hidden');
+  els.welcomeBackdrop.classList.remove('hidden');
+  els.welcomeNick.focus();
+}
+function closeWelcome() { els.welcomeBackdrop.classList.add('hidden'); }
+function submitWelcome() {
+  const trimmed = els.welcomeNick.value.trim();
+  if (!trimmed) {
+    els.welcomeNick.classList.add('invalid');
+    els.welcomeNickError.classList.remove('hidden');
+    els.welcomeNick.focus();
+    return;
+  }
+  S.name = trimmed;
+  els.nick.value = S.name;
+  localStorage.setItem(LS_NAME, S.name);
+  setAvatar(els.meAvatar, S.name, S.myId || 'me');
+  closeWelcome();
+}
+$('#welcome-continue').onclick = submitWelcome;
+els.welcomeNick.addEventListener('keydown', (ev) => { if (ev.key === 'Enter') submitWelcome(); });
+els.welcomeBackdrop.onclick = (ev) => {
+  if (ev.target === els.welcomeBackdrop && !welcomeRequired) closeWelcome();
+};
+$('#btn-help').onclick = () => openWelcome(false);
+
+if (!S.name) openWelcome(true);

public/index.html

@@ -52,6 +52,7 @@
         <button id="btn-deafen" class="ctl" title="Toggle deafen (D)">&#128064;</button>
         <button id="btn-share" class="ctl" title="Share your screen (S)">&#128421;&#65039;</button>
         <button id="btn-settings" class="ctl" title="Voice &amp; ICE settings">&#9881;&#65039;</button>
+        <button id="btn-help" class="ctl" title="How to use gibbz voice">&#10067;</button>
       </div>
     </footer>
   </aside>
@@ -98,6 +99,30 @@
   </div>
 </div>
 
+<!-- welcome / nickname / how-to-use modal -->
+<div id="welcome-backdrop" class="hidden">
+  <div id="welcome-modal" role="dialog" aria-modal="true">
+    <h2>Welcome to gibbz voice</h2>
+    <p class="hint">Pick a name so others can recognize you.</p>
+    <label class="field-label" for="welcome-nick">Nickname</label>
+    <input id="welcome-nick" maxlength="24" spellcheck="false" autocomplete="off" placeholder="e.g. alex" />
+    <div id="welcome-nick-error" class="field-error hidden">Enter a nickname to continue.</div>
+
+    <h3>Quick start</h3>
+    <ul class="howto-list">
+      <li>Click a <b>voice channel</b> in the sidebar to join it — click another to switch.</li>
+      <li><b>Mic</b>, <b>Deafen</b> and <b>Share screen</b> are the buttons bottom-left, or press <b>M</b> / <b>D</b> / <b>S</b>.</li>
+      <li>On the <b>spatial audio</b> map, drag your dot around — you hear people relative to where they stand.</li>
+      <li>Screen shares show up at the top of the main area; pop one into its own window with <b>&#10726;</b>.</li>
+    </ul>
+
+    <div class="modal-actions">
+      <span class="spacer"></span>
+      <button id="welcome-continue">Continue</button>
+    </div>
+  </div>
+</div>
+
 <div id="mx-panel" class="hidden">
   <div class="mx-header">
     <span>#general <span class="poc-tag">matrix · experimental</span></span>

public/style.css

@@ -288,6 +288,31 @@ body {
 .modal-actions button.ghost { background: transparent; color: var(--text-1); }
 .modal-actions button.ghost:hover { text-decoration: underline; }
 
+/* welcome modal */
+#welcome-backdrop {
+  position: fixed; inset: 0; background: rgba(0,0,0,.7); display: grid;
+  place-items: center; z-index: 60;
+}
+#welcome-backdrop.hidden { display: none; }
+#welcome-modal {
+  width: min(480px, 92vw); max-height: 90vh; overflow: auto;
+  background: var(--bg-1); border-radius: 8px; padding: 20px;
+  box-shadow: 0 12px 40px rgba(0,0,0,.6);
+}
+#welcome-modal h2 { font-size: 18px; margin-bottom: 6px; }
+#welcome-modal h3 { font-size: 13px; margin: 18px 0 8px; color: var(--text-1); }
+.field-label { display: block; font-size: 12px; color: var(--text-1); margin-bottom: 4px; }
+#welcome-nick {
+  width: 100%; background: var(--bg-0); color: var(--text-0); border: 1px solid var(--bg-4);
+  border-radius: 6px; padding: 8px 10px; font-size: 14px;
+}
+#welcome-nick:focus { outline: none; border-color: var(--brand); }
+#welcome-nick.invalid { border-color: var(--red); }
+.field-error { color: var(--red); font-size: 12px; margin-top: 4px; }
+.field-error.hidden { display: none; }
+.howto-list { display: flex; flex-direction: column; gap: 8px; padding-left: 18px; font-size: 13px; color: var(--text-1); }
+.howto-list li { line-height: 1.4; }
+
 /* matrix text chat panel */
 #mx-panel {
   position: fixed; top: 0; right: 0; bottom: 0; width: 340px; max-width: 90vw;