@conduction/docusaurus-preset 3.37.0 → 3.39.0

package/src/components/GameModal/__tests__/scores.test.js

@@ -0,0 +1,123 @@
+/**
+ * scores.test.js — the mini-game score table.
+ *
+ * The migration case is the one that matters: every earlier build
+ * wrote a flat `{id: true}` map, and a returning player whose
+ * found-games progress silently reset to zero would read that as a
+ * bug in the games, not in the storage format.
+ */
+
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  migrate, recordResult, bestFor, foundCount, totalScore, readScores, writeScores,
+  STORAGE_KEY, STORAGE_VERSION,
+} = require('../scores.js');
+
+function fakeStorage(initial) {
+  let value = initial;
+  return {
+    getItem: () => value,
+    setItem: (_k, v) => { value = v; },
+    read: () => value,
+  };
+}
+
+test('migrates the version 1 flat map, keeping discovered games', () => {
+  const state = migrate({hexrain: true, boats: true, invaders: false});
+  assert.equal(state.version, STORAGE_VERSION);
+  assert.equal(foundCount(state), 2);
+  assert.deepEqual(state.games.hexrain, {found: true, best: null, plays: 0});
+  assert.equal(state.games.invaders, undefined, 'a false entry is not a found game');
+});
+
+test('reads the current shape back unchanged', () => {
+  const stored = {version: 2, games: {boats: {found: true, best: 18, plays: 3}}};
+  assert.deepEqual(migrate(stored).games.boats, {found: true, best: 18, plays: 3});
+});
+
+test('survives junk in user-writable storage', () => {
+  for (const junk of [null, undefined, 42, 'nope', [], {version: 2, games: null}, {version: 2, games: {a: 7}}]) {
+    const state = migrate(junk);
+    assert.equal(state.version, STORAGE_VERSION);
+    assert.equal(typeof state.games, 'object');
+  }
+  assert.equal(foundCount(migrate({version: 2, games: {a: {found: true, best: 'ten'}}})), 1);
+  assert.equal(bestFor(migrate({version: 2, games: {a: {found: true, best: 'ten'}}}), 'a'), null);
+});
+
+test('records a result, keeps the better score, and counts the play', () => {
+  let state = migrate(null);
+  state = recordResult(state, {id: 'boats', score: 12});
+  assert.equal(bestFor(state, 'boats'), 12);
+
+  state = recordResult(state, {id: 'boats', score: 18});
+  assert.equal(bestFor(state, 'boats'), 18);
+
+  state = recordResult(state, {id: 'boats', score: 3});
+  assert.equal(bestFor(state, 'boats'), 18, 'a worse run overwrote the best');
+  assert.equal(state.games.boats.plays, 3);
+});
+
+test('a game that reports no score still counts as found', () => {
+  const state = recordResult(migrate(null), {id: 'kade-cyclist'});
+  assert.equal(state.games['kade-cyclist'].found, true);
+  assert.equal(bestFor(state, 'kade-cyclist'), null);
+});
+
+test('recordResult does not mutate the state it was given', () => {
+  const before = migrate({version: 2, games: {boats: {found: true, best: 5, plays: 1}}});
+  const snapshot = JSON.stringify(before);
+  recordResult(before, {id: 'boats', score: 99});
+  assert.equal(JSON.stringify(before), snapshot);
+});
+
+test('the total is the sum of the bests, ignoring games without one', () => {
+  let state = migrate(null);
+  state = recordResult(state, {id: 'boats', score: 18});
+  state = recordResult(state, {id: 'invaders', score: 3400});
+  state = recordResult(state, {id: 'kade-cyclist'});
+  assert.equal(totalScore(state), 3418);
+});
+
+test('an empty table totals zero rather than NaN', () => {
+  assert.equal(totalScore(migrate(null)), 0);
+});
+
+test('round-trips through storage under the documented key', () => {
+  const store = fakeStorage(null);
+  const state = recordResult(migrate(null), {id: 'boats', score: 7});
+  writeScores(state, store);
+  assert.match(store.read(), /"version":2/);
+  assert.equal(bestFor(readScores(store), 'boats'), 7);
+  assert.equal(STORAGE_KEY, 'conduction:minigames');
+});
+
+test('a throwing storage never takes the game-over dialog down with it', () => {
+  const hostile = {
+    getItem: () => { throw new Error('blocked'); },
+    setItem: () => { throw new Error('blocked'); },
+  };
+  assert.equal(foundCount(readScores(hostile)), 0);
+  assert.doesNotThrow(() => writeScores(migrate(null), hostile));
+});
+
+test('the counts are scoped to the roster, so a stale game cannot exceed the total', () => {
+  /* The storage key is shared across Conduction sites, so a table can
+     hold games this site does not list. Counting them gave "6 / 5
+     found, 120%" the first time a sixth game shipped. */
+  let state = migrate(null);
+  state = recordResult(state, {id: 'boats', score: 18});
+  state = recordResult(state, {id: 'invaders', score: 3400});
+  state = recordResult(state, {id: 'retired-game', score: 999});
+
+  const roster = ['hexrain', 'boats', 'invaders'];
+  assert.equal(foundCount(state, roster), 2, 'a game off the roster was counted as found');
+  assert.equal(totalScore(state, roster), 3418, 'a game off the roster paid into the total');
+
+  assert.equal(foundCount(state), 3, 'without a roster, everything still counts');
+  assert.equal(totalScore(state), 4417);
+});

package/src/components/GameModal/__tests__/share.test.js

@@ -0,0 +1,83 @@
+/**
+ * share.test.js — the post a player publishes, and the links that open it.
+ *
+ * The instance parsing is the part with real input variety: people
+ * type their handle, their profile URL, or the bare host, and a wrong
+ * guess opens a broken tab on a domain that is not theirs.
+ */
+
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  buildShareText, scoreLines, normaliseInstance, mastodonShareUrl, linkedInShareUrl,
+} = require('../share.js');
+
+const GAMES = [
+  {id: 'hexrain', label: 'Twelve apps · hex rain'},
+  {id: 'boats', label: 'Sink the boats · footer canal'},
+  {id: 'invaders', label: 'Hex-vaders · cookie CLI'},
+];
+
+test('score lines name the game, not where it hides, and skip unplayed games', () => {
+  const bests = {hexrain: 12, invaders: 3400};
+  const lines = scoreLines(GAMES, (id) => (id in bests ? bests[id] : null));
+  assert.deepEqual(lines, ['Twelve apps 12', 'Hex-vaders 3,400']);
+});
+
+test('the post carries the total, the per-game lines, the site and the hashtag', () => {
+  const text = buildShareText({
+    total: 3412,
+    lines: ['Twelve apps 12', 'Hex-vaders 3,400'],
+    foundCount: 2,
+    totalGames: 5,
+    url: 'https://conduction.nl',
+    hashtag: '#IReadTheKit',
+  });
+  assert.match(text, /Total score 3,412 across 2 of 5 hidden Conduction mini-games\./);
+  assert.match(text, /Twelve apps 12 · Hex-vaders 3,400/);
+  assert.match(text, /https:\/\/conduction\.nl/);
+  assert.match(text, /#IReadTheKit$/);
+  assert.ok(text.length < 500, 'must fit a 500-character Mastodon instance with room for a screenshot');
+});
+
+test('a player with no scores yet still gets a postable line', () => {
+  const text = buildShareText({total: 0, lines: [], foundCount: 1, totalGames: 5});
+  assert.match(text, /Total score 0 across 1 of 5/);
+  assert.doesNotMatch(text, /undefined|null|NaN/);
+});
+
+test('Dutch is written, not interpolated into English', () => {
+  const text = buildShareText({total: 42, lines: [], foundCount: 1, totalGames: 5, locale: 'nl'});
+  assert.match(text, /Totaalscore 42 op 1 van de 5/);
+  assert.doesNotMatch(text, /Total score/);
+});
+
+test('an instance is recognised however the player writes it', () => {
+  for (const input of [
+    'chaos.social', 'https://chaos.social', 'https://chaos.social/', 'CHAOS.social',
+    '@me@chaos.social', 'https://chaos.social/@me', '  chaos.social  ',
+  ]) {
+    assert.equal(normaliseInstance(input), 'chaos.social', `failed on ${JSON.stringify(input)}`);
+  }
+});
+
+test('nonsense yields no instance, so nothing opens', () => {
+  for (const input of ['', '   ', null, undefined, 'not a host', '@me', 'localhost', 42]) {
+    assert.equal(normaliseInstance(input), null, `accepted ${JSON.stringify(input)}`);
+  }
+  assert.equal(mastodonShareUrl('@me', 'text'), null);
+});
+
+test('the Mastodon link targets the share endpoint on the player own instance', () => {
+  const url = mastodonShareUrl('@me@mastodon.nl', 'score 12 #IReadTheKit');
+  assert.equal(url, 'https://mastodon.nl/share?text=score%2012%20%23IReadTheKit');
+});
+
+test('the hashtag survives URL encoding on both networks', () => {
+  assert.match(mastodonShareUrl('mastodon.nl', '#IReadTheKit'), /%23IReadTheKit/);
+  assert.match(linkedInShareUrl('#IReadTheKit'), /%23IReadTheKit/);
+  assert.match(linkedInShareUrl('x'), /^https:\/\/www\.linkedin\.com\/feed\/\?shareActive=true/);
+});

package/src/components/GameModal/scores.js

@@ -0,0 +1,149 @@
+/**
+ * Mini-game scores.
+ *
+ * The score table lives in one localStorage key, on the player's own
+ * machine. There is no account and no server: a score is a thing you
+ * screenshot and post, not a row we hold. That is the whole storage
+ * design, and it is why nothing here needs consent.
+ *
+ * Shape (version 2):
+ *
+ *   {
+ *     version: 2,
+ *     games: {
+ *       hexrain: {found: true, best: 12, plays: 3},
+ *       boats:   {found: true, best: 18, plays: 1},
+ *     }
+ *   }
+ *
+ * Version 1 was a flat `{id: true}` map of discovered games, written
+ * by every earlier build. It is migrated on read rather than dropped,
+ * because a returning player's found-games progress bar would
+ * otherwise reset to zero and read as a bug.
+ *
+ * The total is the sum of the per-game bests. Games score in different
+ * units (boats sunk, apps collected, points), so the total is a tally
+ * rather than a rating, and a game with big numbers weighs more. That
+ * is a deliberate choice: the alternative, normalising every game onto
+ * the same range, makes a score impossible to explain in the one line
+ * someone posts with it.
+ */
+
+export const STORAGE_KEY = 'conduction:minigames';
+export const STORAGE_VERSION = 2;
+
+function emptyState() {
+  return {version: STORAGE_VERSION, games: {}};
+}
+
+/**
+ * Normalise whatever is in storage into the current shape.
+ * Exported for the tests; callers use readScores().
+ */
+export function migrate(raw) {
+  if (!raw || typeof raw !== 'object') return emptyState();
+
+  if (raw.version === STORAGE_VERSION && raw.games && typeof raw.games === 'object') {
+    /* Re-read every entry rather than trusting the stored shape: this
+       is user-writable storage, and one hand-edited value should not
+       be able to make the modal throw on open. */
+    const games = {};
+    for (const [id, entry] of Object.entries(raw.games)) {
+      if (!entry || typeof entry !== 'object') continue;
+      games[id] = {
+        found: Boolean(entry.found),
+        best: Number.isFinite(entry.best) ? entry.best : null,
+        plays: Number.isFinite(entry.plays) ? entry.plays : 0,
+      };
+    }
+    return {version: STORAGE_VERSION, games};
+  }
+
+  /* Version 1: a flat map of discovered games, no scores kept. */
+  const games = {};
+  for (const [id, value] of Object.entries(raw)) {
+    if (value === true) games[id] = {found: true, best: null, plays: 0};
+  }
+  return {version: STORAGE_VERSION, games};
+}
+
+export function readScores(storage) {
+  const store = storage || (typeof window !== 'undefined' ? window.localStorage : null);
+  if (!store) return emptyState();
+  try {
+    return migrate(JSON.parse(store.getItem(STORAGE_KEY)));
+  } catch (e) {
+    /* Unparseable or blocked storage: play on with an empty table
+       rather than breaking the game-over dialog. */
+    return emptyState();
+  }
+}
+
+export function writeScores(state, storage) {
+  const store = storage || (typeof window !== 'undefined' ? window.localStorage : null);
+  if (!store) return;
+  try {
+    store.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch (e) {/* fail open: a full or blocked store must not end the run */}
+}
+
+/**
+ * Fold one game-end result into the table.
+ *
+ * Returns a new state; never mutates. A run that scores worse than the
+ * player's best leaves the best alone, so the number they posted last
+ * week does not disappear because they played once more.
+ */
+export function recordResult(state, {id, score} = {}) {
+  if (!id) return state;
+  const prev = state.games[id] || {found: false, best: null, plays: 0};
+  const scored = Number.isFinite(score);
+  return {
+    version: STORAGE_VERSION,
+    games: {
+      ...state.games,
+      [id]: {
+        /* Any game-end counts as found: a few games (the cyclist, the
+           endless ones) never reach a clean win state. */
+        found: true,
+        best: scored ? Math.max(prev.best ?? -Infinity, score) : prev.best,
+        plays: (prev.plays || 0) + 1,
+      },
+    },
+  };
+}
+
+export function bestFor(state, id) {
+  const entry = state.games[id];
+  return entry && Number.isFinite(entry.best) ? entry.best : null;
+}
+
+/**
+ * Both counts take the roster of games currently on the site.
+ *
+ * Without it, a score table that remembers a game the site no longer
+ * ships (or one found on a sister site, since the key is the same)
+ * counts towards a total it is not listed in: the dialog then reads
+ * "6 / 5 mini-games found, 120%". Scoping to the roster keeps the
+ * numbers describing the list the player is looking at. Omitting ids
+ * counts everything, which is what a caller without a roster wants.
+ */
+function entries(state, ids) {
+  const all = Object.entries(state.games);
+  if (!ids || !ids.length) return all.map(([, g]) => g);
+  const wanted = new Set(ids);
+  return all.filter(([id]) => wanted.has(id)).map(([, g]) => g);
+}
+
+export function foundCount(state, ids) {
+  return entries(state, ids).filter((g) => g && g.found).length;
+}
+
+export function totalScore(state, ids) {
+  return entries(state, ids)
+    .reduce((sum, g) => sum + (g && Number.isFinite(g.best) ? g.best : 0), 0);
+}
+
+export function formatScore(n, locale = 'en') {
+  return Number(n || 0).toLocaleString(locale);
+}

package/src/components/GameModal/share.js

@@ -0,0 +1,97 @@
+/**
+ * Composing the post a player shares, and the links that open it.
+ *
+ * No API, no tokens, no account: we build a piece of text and hand it
+ * to the network the player already uses. Mastodon takes the text in
+ * the URL. LinkedIn does not reliably prefill any more, so there the
+ * text goes to the clipboard and the composer opens empty, which is
+ * why every path here also offers a plain copy.
+ */
+
+/**
+ * Build the post text.
+ *
+ * Deliberately short: it has to survive a 500-character Mastodon
+ * instance with a screenshot attached, and it reads as something a
+ * person wrote rather than a share widget's output.
+ */
+export function buildShareText({
+  total,
+  lines = [],
+  foundCount,
+  totalGames,
+  hashtag = '#IReadTheKit',
+  url,
+  locale = 'en',
+} = {}) {
+  const fmt = (n) => Number(n || 0).toLocaleString(locale);
+  const parts = [];
+
+  parts.push(
+    locale === 'nl'
+      ? `Totaalscore ${fmt(total)} op ${foundCount} van de ${totalGames} verstopte spelletjes van Conduction.`
+      : `Total score ${fmt(total)} across ${foundCount} of ${totalGames} hidden Conduction mini-games.`,
+  );
+
+  if (lines.length) parts.push(lines.join(' · '));
+
+  parts.push(
+    locale === 'nl'
+      ? 'Jouw beurt. De spelletjes staan verstopt op de site.'
+      : 'Your turn. The games are hidden on the site.',
+  );
+
+  if (url) parts.push(url);
+  if (hashtag) parts.push(hashtag);
+
+  return parts.join('\n\n');
+}
+
+/** One `Label 1,234` line per game with a best score. */
+export function scoreLines(games, bestOf, locale = 'en') {
+  return games
+    .map((g) => {
+      const best = bestOf(g.id);
+      if (best === null || best === undefined) return null;
+      /* The label carries "Game · where it hides"; the post only needs
+         the game. */
+      const name = String(g.label || g.id).split('·')[0].trim();
+      return `${name} ${Number(best).toLocaleString(locale)}`;
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Normalise whatever the player typed for their Mastodon instance.
+ * Accepts "chaos.social", "https://chaos.social/", "@me@chaos.social".
+ * Returns null when there is no host in it, so the caller can keep the
+ * field open instead of opening a broken tab.
+ */
+export function normaliseInstance(input) {
+  if (!input || typeof input !== 'string') return null;
+  let value = input.trim();
+  if (!value) return null;
+  /* Order matters. Strip the scheme and the path first, otherwise a
+     profile URL (https://chaos.social/@me) has its host thrown away
+     and the trailing "@me" is read as the instance. Only then treat a
+     remaining @ as a handle (@me@chaos.social). */
+  value = value.replace(/^https?:\/\//i, '').replace(/\/.*$/, '').trim();
+  if (value.includes('@')) value = value.slice(value.lastIndexOf('@') + 1);
+  if (!value || !value.includes('.') || /\s/.test(value)) return null;
+  return value.toLowerCase();
+}
+
+export function mastodonShareUrl(instance, text) {
+  const host = normaliseInstance(instance);
+  if (!host) return null;
+  return `https://${host}/share?text=${encodeURIComponent(text)}`;
+}
+
+/**
+ * LinkedIn's composer. The text parameter is honoured inconsistently,
+ * so the UI copies the post to the clipboard first and tells the
+ * player to paste. Passing it anyway costs nothing when it does work.
+ */
+export function linkedInShareUrl(text) {
+  return `https://www.linkedin.com/feed/?shareActive=true&text=${encodeURIComponent(text)}`;
+}