Add daily challenges and local engagement metrics

Author: gmval-g3

PRIVACY.md

@@ -0,0 +1,17 @@
+# Privacy
+
+Little Android does not send gameplay analytics to a server.
+
+The game stores the following data locally in the visitor's browser:
+
+- discovered and collected signal IDs;
+- scanned resident names;
+- quest completion state;
+- sound preference;
+- aggregate counters such as sessions, first scan, completions, replays, and share intent.
+
+These values contain no account identifier, free-form input, location, or device fingerprint. They are used only by the local experience and can be removed by clearing site data or resetting the journey where applicable. The game continues to work when browser storage is unavailable.
+
+The share action uses the browser's native share sheet or clipboard only after the visitor activates it. Shared text contains the daily challenge code and the public project URL.
+
+The page currently requests display fonts from Google Fonts. That external request is separate from gameplay measurement and is tracked for reliability/privacy review in issue #17.

README.md

@@ -54,6 +54,10 @@ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Keep chan
 
 Codex review follows the repository rules in [AGENTS.md](AGENTS.md).
 
+## Privacy
+
+Gameplay progress, preferences, and aggregate engagement counters remain in the visitor's browser. See [PRIVACY.md](PRIVACY.md) for the exact local data and sharing behavior.
+
 ## License
 
 Source code and original project assets are available under the [MIT License](LICENSE).

index.html

@@ -33,6 +33,9 @@
 #quest-reset{position:absolute;top:max(88px,calc(66px + 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:20px monospace;cursor:pointer}
 #quest-reset.show{display:block}
 #quest-reset:focus-visible{outline:3px solid #E8E0D0;outline-offset:2px}
+#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}
 #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}
@@ -55,6 +58,7 @@
   #quest{top:calc(54px + env(safe-area-inset-top));right:12px;font-size:9px}
   #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}
   #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)))}
@@ -82,6 +86,7 @@
   <div id="quest" aria-live="polite">SIGNALS 0/3</div>
   <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>
@@ -95,6 +100,7 @@ <h2 id="journal-title">SIGNAL LOG</h2>
 <script src="src/game-content.js"></script>
 <script src="src/progress.js"></script>
 <script src="src/feedback.js"></script>
+<script src="src/engagement.js"></script>
 <script>
 // ══════════════════════════════════════════════════════
 // SETUP
@@ -113,6 +119,7 @@ <h2 id="journal-title">SIGNAL LOG</h2>
 const journalList = document.getElementById('journal-list');
 const journalClose = document.getElementById('journal-close');
 const soundButton = document.getElementById('sound-button');
+const shareButton = document.getElementById('share-button');
 
 const PX = 3;
 const TILE = 16;
@@ -166,15 +173,22 @@ <h2 id="journal-title">SIGNAL LOG</h2>
 } = LittleAndroidLogic;
 const world = createWorldMap(77);
 const MW = world.width, MH = world.height, map = world.map;
-const signalFragments = LittleAndroidContent.SIGNAL_FRAGMENTS.map(fragment => ({
-  ...fragment,
+const dailyChallenge = LittleAndroidEngagement.createDailyChallenge(
+  new Date(),
+  LittleAndroidContent.SIGNAL_FRAGMENTS.map(fragment => fragment.id),
+);
+const fragmentContent = new Map(LittleAndroidContent.SIGNAL_FRAGMENTS.map(fragment => [fragment.id, fragment]));
+const signalFragments = dailyChallenge.order.map(id => ({
+  ...fragmentContent.get(id),
   discovered: false,
   collected: false,
 }));
 let progressStorage = null;
 try { progressStorage = window.localStorage; } catch {}
 const savedProgress = LittleAndroidProgress.loadProgress(progressStorage);
 const feedback = LittleAndroidFeedback.createFeedbackController(window, progressStorage);
+const metrics = LittleAndroidEngagement.createLocalMetrics(progressStorage);
+metrics.increment('sessions');
 for (const fragment of signalFragments) {
   fragment.discovered = savedProgress.discoveredFragments.includes(fragment.id);
   fragment.collected = savedProgress.collectedFragments.includes(fragment.id);
@@ -262,6 +276,7 @@ <h2 id="journal-title">SIGNAL LOG</h2>
   player.moveToX = tx; player.moveToY = ty;
   player.moveProgress = 0;
   player.idleTimer = 0;
+  metrics.markOnce('first_move');
 }
 
 function drawUnit01(sx, sy, facing, walkFrame, moving, idleCoreOn, interacting) {
@@ -647,6 +662,7 @@ <h2 id="journal-title">SIGNAL LOG</h2>
   triggerNPCInteraction(npc);
   rememberNPC(npc);
   feedback.play('interact');
+  metrics.markOnce('first_interaction');
   const dialogue = LittleAndroidContent.NPC_DIALOGUE[npc.type];
   showStatus(dialogue ? (quest.complete ? dialogue.complete : dialogue.active) : `LINK: ${npc.scanLabel || npc.type.toUpperCase()}`, 3.5);
 }
@@ -934,8 +950,9 @@ <h2 id="journal-title">SIGNAL LOG</h2>
 
 function updateQuestUI() {
   const collected = signalFragments.filter(fragment => fragment.collected).length;
-  questEl.textContent = quest.complete ? 'FACTORY ONLINE' : `SIGNALS ${collected}/${signalFragments.length}`;
+  questEl.textContent = quest.complete ? `FACTORY ONLINE · ${dailyChallenge.code}` : `SIGNALS ${collected}/${signalFragments.length} · ${dailyChallenge.code}`;
   questResetButton.classList.toggle('show', quest.complete);
+  shareButton.classList.toggle('show', quest.complete);
 }
 
 function currentProgress() {
@@ -981,6 +998,7 @@ <h2 id="journal-title">SIGNAL LOG</h2>
     showStatus('FACTORY LINK RESTORED', 4);
     feedback.play('complete');
     feedback.haptic([25, 35, 50]);
+    metrics.increment('completions');
   } else {
     showStatus(`${fragment.name} RECOVERED · ${collected}/${signalFragments.length}`, 2.5);
     feedback.play('collect');
@@ -1004,6 +1022,7 @@ <h2 id="journal-title">SIGNAL LOG</h2>
   updateQuestUI();
   updateJournal();
   showStatus('SIGNAL SEARCH RESTARTED', 2);
+  metrics.increment('replays');
 }
 
 function performAction() {
@@ -1040,6 +1059,28 @@ <h2 id="journal-title">SIGNAL LOG</h2>
   if (!muted) feedback.play('interact');
 });
 
+async function shareCompletion() {
+  const text = LittleAndroidEngagement.completionText(dailyChallenge.code);
+  metrics.increment('share_intent');
+  try {
+    if (window.navigator && typeof window.navigator.share === 'function') {
+      await window.navigator.share({ title: 'Little Android', text, url: 'https://littleandroid.com' });
+      showStatus('COMPLETION SHARED', 2);
+      return;
+    }
+    if (window.navigator && window.navigator.clipboard) {
+      await window.navigator.clipboard.writeText(text);
+      showStatus('RESULT COPIED', 2);
+      return;
+    }
+  } catch {
+    showStatus('SHARE CANCELLED', 2);
+    return;
+  }
+  showStatus(text, 4);
+}
+shareButton.addEventListener('click', shareCompletion);
+
 let statusTimer = 0;
 function showStatus(message, duration = 1.5) {
   statusEl.textContent = message;
@@ -1085,6 +1126,7 @@ <h2 id="journal-title">SIGNAL LOG</h2>
   player.idleTimer = 0;
   showStatus('SCANNING...');
   feedback.play('scan');
+  metrics.markOnce('first_scan');
   return true;
 }
 

scripts/check.cjs

@@ -20,6 +20,9 @@ if (!html.includes('src/progress.js')) {
 if (!html.includes('src/feedback.js')) {
   throw new Error('index.html must load the feedback module');
 }
+if (!html.includes('src/engagement.js')) {
+  throw new Error('index.html must load the engagement module');
+}
 if (inlineScripts.length !== 1) {
   throw new Error(`Expected one inline runtime script, found ${inlineScripts.length}`);
 }
@@ -29,5 +32,6 @@ require('../src/game-logic.js');
 require('../src/game-content.js');
 require('../src/progress.js');
 require('../src/feedback.js');
+require('../src/engagement.js');
 
 console.log('Static checks passed.');

src/engagement.js

@@ -0,0 +1,101 @@
+(function exposeEngagement(root, factory) {
+  const api = factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  if (root) root.LittleAndroidEngagement = api;
+})(typeof globalThis !== 'undefined' ? globalThis : this, function createEngagementApi() {
+  'use strict';
+
+  const METRICS_KEY = 'littleandroid.metrics';
+
+  function hashString(value) {
+    let hash = 2166136261;
+    for (let index = 0; index < value.length; index++) {
+      hash ^= value.charCodeAt(index);
+      hash = Math.imul(hash, 16777619);
+    }
+    return hash >>> 0;
+  }
+
+  function seededRandom(seed) {
+    return function random() {
+      seed |= 0;
+      seed = seed + 0x6D2B79F5 | 0;
+      let value = Math.imul(seed ^ seed >>> 15, 1 | seed);
+      value = value + Math.imul(value ^ value >>> 7, 61 | value) ^ value;
+      return ((value ^ value >>> 14) >>> 0) / 4294967296;
+    };
+  }
+
+  function createDailyChallenge(date, fragmentIds) {
+    const dateKey = typeof date === 'string' ? date : date.toISOString().slice(0, 10);
+    const seed = hashString(dateKey);
+    const random = seededRandom(seed);
+    const order = [...fragmentIds];
+    for (let index = order.length - 1; index > 0; index--) {
+      const swapIndex = Math.floor(random() * (index + 1));
+      [order[index], order[swapIndex]] = [order[swapIndex], order[index]];
+    }
+    return {
+      dateKey,
+      code: `D${String(seed % 10000).padStart(4, '0')}`,
+      order,
+    };
+  }
+
+  function parseMetrics(raw) {
+    try {
+      const parsed = JSON.parse(raw || '{}');
+      const counters = {};
+      for (const [name, value] of Object.entries(parsed.counters || {})) {
+        if (Number.isFinite(value) && value >= 0) counters[name] = value;
+      }
+      return { counters };
+    } catch {
+      return { counters: {} };
+    }
+  }
+
+  function createLocalMetrics(storage) {
+    let state;
+    try { state = parseMetrics(storage && storage.getItem(METRICS_KEY)); }
+    catch { state = { counters: {} }; }
+
+    function persist() {
+      try {
+        if (storage) storage.setItem(METRICS_KEY, JSON.stringify(state));
+      } catch {}
+    }
+
+    function increment(name) {
+      state.counters[name] = (state.counters[name] || 0) + 1;
+      persist();
+      return state.counters[name];
+    }
+
+    function markOnce(name) {
+      if (state.counters[name]) return false;
+      state.counters[name] = 1;
+      persist();
+      return true;
+    }
+
+    return Object.freeze({
+      increment,
+      markOnce,
+      snapshot: () => JSON.parse(JSON.stringify(state)),
+    });
+  }
+
+  function completionText(challengeCode) {
+    return `I restored the Little Android factory (${challengeCode}). Explore it at https://littleandroid.com`;
+  }
+
+  return Object.freeze({
+    METRICS_KEY,
+    hashString,
+    createDailyChallenge,
+    parseMetrics,
+    createLocalMetrics,
+    completionText,
+  });
+});

tests/engagement.test.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  createDailyChallenge,
+  parseMetrics,
+  createLocalMetrics,
+  completionText,
+} = require('../src/engagement.js');
+
+function memoryStorage() {
+  const values = new Map();
+  return {
+    getItem: key => values.get(key) || null,
+    setItem: (key, value) => values.set(key, value),
+  };
+}
+
+test('daily challenges are deterministic and retain every fragment', () => {
+  const ids = ['a', 'b', 'c'];
+  const first = createDailyChallenge('2026-07-16', ids);
+  const second = createDailyChallenge('2026-07-16', ids);
+  assert.deepEqual(first, second);
+  assert.deepEqual([...first.order].sort(), ids);
+  assert.match(first.code, /^D\d{4}$/);
+});
+
+test('local metrics count without storing event payloads', () => {
+  const metrics = createLocalMetrics(memoryStorage());
+  assert.equal(metrics.increment('sessions'), 1);
+  assert.equal(metrics.increment('sessions'), 2);
+  assert.equal(metrics.markOnce('first_scan'), true);
+  assert.equal(metrics.markOnce('first_scan'), false);
+  assert.deepEqual(metrics.snapshot(), { counters: { sessions: 2, first_scan: 1 } });
+  assert.deepEqual(parseMetrics('{bad'), { counters: {} });
+});
+
+test('completion copy contains only challenge and public URL', () => {
+  assert.equal(
+    completionText('D0042'),
+    'I restored the Little Android factory (D0042). Explore it at https://littleandroid.com',
+  );
+});

tests/runtime-smoke.test.cjs

@@ -8,6 +8,7 @@ const LittleAndroidLogic = require('../src/game-logic.js');
 const LittleAndroidContent = require('../src/game-content.js');
 const LittleAndroidProgress = require('../src/progress.js');
 const LittleAndroidFeedback = require('../src/feedback.js');
+const LittleAndroidEngagement = require('../src/engagement.js');
 
 function memoryStorage() {
   const values = new Map();
@@ -53,12 +54,14 @@ test('runtime initializes and renders a frame', () => {
     'journal-list': element(),
     'journal-close': element(),
     'sound-button': element(),
+    'share-button': element(),
   };
   const sandbox = {
     LittleAndroidLogic,
     LittleAndroidContent,
     LittleAndroidProgress,
     LittleAndroidFeedback,
+    LittleAndroidEngagement,
     console,
     Date,
     Math,
@@ -97,7 +100,7 @@ test('runtime initializes and renders a frame', () => {
     ({ complete: quest.complete, collected: signalFragments.filter(fragment => fragment.collected).length });
   `, sandbox);
   assert.deepEqual({ ...completion }, { complete: true, collected: 3 });
-  assert.equal(elements.quest.textContent, 'FACTORY ONLINE');
+  assert.match(elements.quest.textContent, /^FACTORY ONLINE · D\d{4}$/);
 });
 
 test('NPC movement rejects a destination reserved earlier in the frame', () => {
@@ -112,9 +115,9 @@ 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() };
+  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 sandbox = {
-    LittleAndroidLogic, LittleAndroidContent, LittleAndroidProgress, LittleAndroidFeedback, console, Date, Math, setTimeout, clearTimeout,
+    LittleAndroidLogic, LittleAndroidContent, LittleAndroidProgress, LittleAndroidFeedback, LittleAndroidEngagement, console, Date, Math, setTimeout, clearTimeout,
     document: { hidden: false, body: element(), getElementById: id => elements[id] },
     window: { innerWidth: 800, innerHeight: 600, devicePixelRatio: 1, localStorage: memoryStorage(), addEventListener() {} },
     requestAnimationFrame() {},
@@ -143,9 +146,9 @@ 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() };
+  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 sandbox = {
-    LittleAndroidLogic, LittleAndroidContent, LittleAndroidProgress, LittleAndroidFeedback, console, Date, Math, setTimeout, clearTimeout,
+    LittleAndroidLogic, LittleAndroidContent, LittleAndroidProgress, LittleAndroidFeedback, LittleAndroidEngagement, console, Date, Math, setTimeout, clearTimeout,
     document: { hidden: false, body: element(), getElementById: id => elements[id] },
     window: { innerWidth: 800, innerHeight: 600, devicePixelRatio: 1, localStorage: memoryStorage(), addEventListener() {} },
     requestAnimationFrame() {},