Merge PR #24: Add first-visit mission briefing

Add an accessible starter briefing with persistent first-visit state

Author: mcvalosborne

README.md

@@ -6,6 +6,8 @@ An explorable pixel-art micro-world rendered entirely in the browser. Walk throu
 
 ## Controls
 
+First-time players receive a short mission briefing. Reopen it at any time with the `?` control.
+
 | Action | Input |
 | --- | --- |
 | Move | `W` `A` `S` `D` or click/tap a destination |
@@ -20,6 +22,9 @@ The current mobile experience supports tap-to-move. A dedicated touch action con
 - Eight residents with distinct movement and interaction state machines
 - Grid-based movement and click-to-move pathfinding
 - A radial scan that reveals character identities
+- A three-part signal recovery quest with resident hints and daily challenge codes
+- Persistent progress, a discovery journal, replay, and completion sharing
+- Optional sound, haptic feedback, touch controls, and reduced-motion support
 - No runtime framework, backend, or asset bundle
 
 ## Run locally

index.html

@@ -38,6 +38,8 @@
 #share-button{position:absolute;top:max(128px,calc(106px + env(safe-area-inset-top)));right:max(22px,env(safe-area-inset-right));z-index:20;display:none;width:34px;height:34px;border:1px solid #D4A030;border-radius:4px;background:rgba(10,10,10,.82);color:#E8C040;font:18px monospace;cursor:pointer}
 #share-button.show{display:block}
 #share-button:focus-visible{outline:3px solid #E8E0D0;outline-offset:2px}
+#briefing-button{position:absolute;top:max(22px,env(safe-area-inset-top));left:max(22px,env(safe-area-inset-left));z-index:20;width:34px;height:34px;border:1px solid #5A8848;border-radius:4px;background:rgba(10,10,10,.82);color:#A8C088;font:700 16px 'Silkscreen',monospace;cursor:pointer}
+#briefing-button:focus-visible,#briefing-start:focus-visible{outline:3px solid #E8E0D0;outline-offset:2px}
 #journal-button{position:absolute;top:max(48px,calc(26px + env(safe-area-inset-top)));right:max(22px,env(safe-area-inset-right));z-index:20;width:42px;height:30px;border:1px solid #5A8848;border-radius:4px;background:rgba(10,10,10,.82);color:#A8C088;font:10px 'Silkscreen',monospace;cursor:pointer}
 #journal-button:focus-visible,#journal-close:focus-visible{outline:3px solid #E8E0D0;outline-offset:2px}
 #sound-button{position:absolute;right:max(20px,env(safe-area-inset-right));bottom:max(20px,env(safe-area-inset-bottom));z-index:20;width:38px;height:34px;border:1px solid #5A8848;border-radius:4px;background:rgba(10,10,10,.82);color:#A8C088;font:18px monospace;cursor:pointer}
@@ -50,6 +52,18 @@
 .journal-entry{padding-bottom:7px;border-bottom:1px solid #383030;color:#B0A890}
 .journal-entry.found{color:#E8E0D0}
 #journal-close{margin-top:16px;padding:8px 12px;border:1px solid #D4A030;border-radius:4px;background:#181820;color:#E8C040;font:11px 'Silkscreen',monospace;cursor:pointer}
+#briefing-dialog{width:min(480px,calc(100vw - 32px));padding:0;border:2px solid #5A8848;border-radius:4px;background:#181820;color:#E8E0D0;font-family:'Silkscreen',monospace}
+#briefing-dialog::backdrop{background:rgba(10,10,10,.84)}
+#briefing-header{padding:16px 18px 12px;border-bottom:1px solid #383030}
+#briefing-header span{display:block;margin-bottom:7px;color:#6B9848;font-size:9px}
+#briefing-header h2{color:#E8C040;font-size:18px}
+#briefing-body{padding:18px}
+#briefing-objective{margin-bottom:18px;color:#E8E0D0;font-size:12px;line-height:1.8}
+#briefing-controls{display:grid;grid-template-columns:88px 1fr;gap:10px 14px;padding:14px 0;border-top:1px solid #383030;border-bottom:1px solid #383030;font-size:10px;line-height:1.5}
+.briefing-input{color:#E8C040}
+.briefing-action{color:#B0A890}
+#briefing-note{margin-top:14px;color:#8A9870;font-size:9px;line-height:1.7}
+#briefing-start{width:100%;margin-top:18px;padding:11px 14px;border:2px solid #D4A030;border-radius:4px;background:#242018;color:#E8C040;font:700 12px 'Silkscreen',monospace;cursor:pointer}
 .sr-only{position:absolute!important;width:1px!important;height:1px!important;padding:0!important;margin:-1px!important;overflow:hidden!important;clip:rect(0,0,0,0)!important;white-space:nowrap!important;border:0!important}
 @media(max-width:600px){
   #ui-overlay{justify-content:flex-start;padding:calc(10px + env(safe-area-inset-top)) 10px 10px}
@@ -61,6 +75,7 @@
   #journal-button{top:calc(74px + env(safe-area-inset-top));right:12px}
   #quest-reset{top:calc(112px + env(safe-area-inset-top));right:12px}
   #share-button{top:calc(152px + env(safe-area-inset-top));right:12px}
+  #briefing-button{top:calc(50px + env(safe-area-inset-top));left:12px}
   #hint{bottom:max(88px,calc(68px + env(safe-area-inset-bottom)));width:70vw;font-size:10px;text-align:center}
   #action-button{display:block}
   #sound-button{right:max(104px,calc(104px + env(safe-area-inset-right)));bottom:max(28px,calc(28px + env(safe-area-inset-bottom)))}
@@ -91,12 +106,29 @@
   <div id="emote"></div>
   <div id="status" role="status" aria-live="polite"></div>
   <div id="quest" aria-live="polite">SIGNALS 0/3</div>
+  <button id="briefing-button" type="button" aria-label="Open mission briefing" title="Mission briefing">?</button>
   <button id="journal-button" type="button" aria-label="Open signal log">LOG</button>
   <button id="quest-reset" type="button" aria-label="Restart signal quest" title="Restart signal quest">↻</button>
   <button id="share-button" type="button" aria-label="Share completion" title="Share completion">↗</button>
   <button id="action-button" type="button" aria-label="Scan or interact">SCAN</button>
   <button id="sound-button" type="button" aria-label="Mute sound" title="Toggle sound">♪</button>
   <p class="sr-only" id="game-instructions">Move with WASD, arrow keys, or by selecting a destination. Press Space or Enter, or use the Scan button, to scan nearby residents or interact with the character you face.</p>
+  <dialog id="briefing-dialog" aria-labelledby="briefing-title">
+    <div id="briefing-header">
+      <span>UNIT-01 // DAILY ASSIGNMENT</span>
+      <h2 id="briefing-title">RESTORE THE LINK</h2>
+    </div>
+    <div id="briefing-body">
+      <p id="briefing-objective">Three signal carriers are dark. Explore the river factory, scan for their locations, and recover all three before the cycle resets.</p>
+      <div id="briefing-controls" aria-label="Game controls">
+        <span class="briefing-input">WASD</span><span class="briefing-action">MOVE</span>
+        <span class="briefing-input">CLICK / TAP</span><span class="briefing-action">WALK TO A LOCATION</span>
+        <span class="briefing-input">SPACE / SCAN</span><span class="briefing-action">SEARCH OR INTERACT</span>
+      </div>
+      <p id="briefing-note">Residents remember what you discover. Progress is saved on this device.</p>
+      <button id="briefing-start" type="button">BEGIN</button>
+    </div>
+  </dialog>
   <dialog id="journal-dialog" aria-labelledby="journal-title">
     <h2 id="journal-title">SIGNAL LOG</h2>
     <div id="journal-list"></div>
@@ -121,6 +153,9 @@ <h2 id="journal-title">SIGNAL LOG</h2>
 const actionButton = document.getElementById('action-button');
 const questEl = document.getElementById('quest');
 const questResetButton = document.getElementById('quest-reset');
+const briefingButton = document.getElementById('briefing-button');
+const briefingDialog = document.getElementById('briefing-dialog');
+const briefingStart = document.getElementById('briefing-start');
 const journalButton = document.getElementById('journal-button');
 const journalDialog = document.getElementById('journal-dialog');
 const journalList = document.getElementById('journal-list');
@@ -1139,6 +1174,19 @@ <h2 id="journal-title">SIGNAL LOG</h2>
   performAction();
 });
 questResetButton.addEventListener('click', () => requestQuestReset());
+const BRIEFING_SEEN_KEY = 'littleandroid.briefingSeen';
+function rememberBriefing() {
+  try { window.localStorage.setItem(BRIEFING_SEEN_KEY, '1'); } catch {}
+}
+function openBriefing() {
+  if (!briefingDialog.open) briefingDialog.showModal();
+}
+briefingButton.addEventListener('click', openBriefing);
+briefingStart.addEventListener('click', () => briefingDialog.close());
+briefingDialog.addEventListener('close', () => {
+  rememberBriefing();
+  canvas.focus({ preventScroll: true });
+});
 journalButton.addEventListener('click', () => {
   updateJournal();
   journalDialog.showModal();
@@ -1601,6 +1649,9 @@ <h2 id="journal-title">SIGNAL LOG</h2>
 } else {
   showStatus('OBJECTIVE: LOCATE 3 SIGNALS', 4);
 }
+let hasSeenBriefing = false;
+try { hasSeenBriefing = window.localStorage.getItem(BRIEFING_SEEN_KEY) === '1'; } catch {}
+if (!hasSeenBriefing) openBriefing();
 requestAnimationFrame((t) => { lastTime = t; gameLoop(t); });
 </script>
 </body>

tests/runtime-smoke.test.cjs

@@ -49,6 +49,9 @@ test('runtime initializes and renders a frame', async () => {
     'action-button': element(),
     quest: element(),
     'quest-reset': element(),
+    'briefing-button': element(),
+    'briefing-dialog': element(),
+    'briefing-start': element(),
     'journal-button': element(),
     'journal-dialog': element(),
     'journal-list': element(),
@@ -204,7 +207,7 @@ test('NPC movement rejects a destination reserved earlier in the frame', () => {
     getBoundingClientRect: () => ({ left: 0, top: 0 }),
     addEventListener() {}, getContext: () => context2d,
   });
-  const elements = { game: element(), coords: element(), hint: element(), emote: element(), status: element(), 'action-button': element(), quest: element(), 'quest-reset': element(), 'journal-button': element(), 'journal-dialog': element(), 'journal-list': element(), 'journal-close': element(), 'sound-button': element(), 'share-button': element() };
+  const elements = { game: element(), coords: element(), hint: element(), emote: element(), status: element(), 'action-button': element(), quest: element(), 'quest-reset': element(), 'briefing-button': element(), 'briefing-dialog': element(), 'briefing-start': element(), 'journal-button': element(), 'journal-dialog': element(), 'journal-list': element(), 'journal-close': element(), 'sound-button': element(), 'share-button': element() };
   const sandbox = {
     LittleAndroidLogic, LittleAndroidContent, LittleAndroidProgress, LittleAndroidFeedback, LittleAndroidEngagement, console, Date, Math, setTimeout, clearTimeout,
     document: { hidden: false, body: element(), getElementById: id => elements[id] },
@@ -241,7 +244,7 @@ test('interaction waits for a moving NPC to finish its tile step', () => {
     getBoundingClientRect: () => ({ left: 0, top: 0 }), addEventListener() {},
     getContext: () => context2d,
   });
-  const elements = { game: element(), coords: element(), hint: element(), emote: element(), status: element(), 'action-button': element(), quest: element(), 'quest-reset': element(), 'journal-button': element(), 'journal-dialog': element(), 'journal-list': element(), 'journal-close': element(), 'sound-button': element(), 'share-button': element() };
+  const elements = { game: element(), coords: element(), hint: element(), emote: element(), status: element(), 'action-button': element(), quest: element(), 'quest-reset': element(), 'briefing-button': element(), 'briefing-dialog': element(), 'briefing-start': element(), 'journal-button': element(), 'journal-dialog': element(), 'journal-list': element(), 'journal-close': element(), 'sound-button': element(), 'share-button': element() };
   const sandbox = {
     LittleAndroidLogic, LittleAndroidContent, LittleAndroidProgress, LittleAndroidFeedback, LittleAndroidEngagement, console, Date, Math, setTimeout, clearTimeout,
     document: { hidden: false, body: element(), getElementById: id => elements[id] },