@conduction/docusaurus-preset 3.39.0 → 3.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/docusaurus-preset",
-  "version": "3.39.0",
+  "version": "3.40.0",
   "scripts": {
     "prepack": "node scripts/prepack-bundle-css.js",
     "test": "node --test"

package/src/components/LockPick/LockPick.jsx

@@ -0,0 +1,210 @@
+/**
+ * <LockPick />
+ *
+ * Keepiq's mini-game, and the one everybody has played before: set the
+ * pick, turn the cylinder, feel how far it gives. Close to the sweet
+ * spot it turns; far from it the pick strains and eventually snaps.
+ * Three picks, and each lock you open is narrower than the last.
+ *
+ * The rules live in ./engine.js with no DOM and no clock. There is no
+ * clock here either: a lock is a puzzle you reason your way into, and
+ * hurrying someone who is counting clicks would only make it a worse
+ * version of the timed games.
+ *
+ * Usage on a product page:
+ *
+ *   <LockPick />
+ *
+ * Fires the shared `connext:gameend` event when the last pick snaps,
+ * and listens for `connext:gamereplay`.
+ *
+ * Accessibility: the dial is a real slider, so arrow keys, Home and End
+ * work without any code of ours, and the feedback after every turn is
+ * a sentence rather than a bar. A player who cannot see the dial can
+ * pick every lock in the game from the feedback alone, which is the
+ * property the engine tests pin.
+ */
+
+import React, {useCallback, useEffect, useRef, useState} from 'react';
+import {translate} from '@docusaurus/Translate';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {createGame, setPosition, turn, summarise, POSITIONS} from './engine';
+import styles from './LockPick.module.css';
+
+const GAME_ID = 'lock-pick';
+
+/* What the last turn felt like, in words. The thresholds match the
+   engine's `give`, so the sentence and the strain always agree. */
+function feelCopy(value) {
+  if (value >= 0.97) {
+    return translate({id: 'preset.lockPick.feel.almost', message: 'It almost turns. You are within a hair of it.', description: 'Lock-pick feedback when the pick is very close to the sweet spot'});
+  }
+  if (value >= 0.85) {
+    return translate({id: 'preset.lockPick.feel.close', message: 'The cylinder turns a good way, then stops.', description: 'Lock-pick feedback when the pick is close'});
+  }
+  if (value >= 0.6) {
+    return translate({id: 'preset.lockPick.feel.some', message: 'It gives a little.', description: 'Lock-pick feedback when the pick is somewhere near'});
+  }
+  if (value >= 0.3) {
+    return translate({id: 'preset.lockPick.feel.barely', message: 'Barely anything. You are a long way off.', description: 'Lock-pick feedback when the pick is far from the sweet spot'});
+  }
+  return translate({id: 'preset.lockPick.feel.nothing', message: 'Nothing. The cylinder does not move at all.', description: 'Lock-pick feedback when the pick is nowhere near the sweet spot'});
+}
+
+export default function LockPick({className}) {
+  const {i18n} = useDocusaurusContext();
+  const locale = (i18n && i18n.currentLocale) || 'en';
+
+  const [game, setGame] = useState(null);
+  const gameRef = useRef(null);
+  const endedRef = useRef(false);
+
+  const running = Boolean(game) && !game.over;
+
+  const begin = useCallback(() => {
+    endedRef.current = false;
+    const fresh = createGame({seed: Math.floor(Math.random() * 2 ** 31)});
+    gameRef.current = fresh;
+    setGame(fresh);
+  }, []);
+
+  useEffect(() => {
+    if (!game || !game.over || endedRef.current) return;
+    endedRef.current = true;
+    if (typeof window === 'undefined') return;
+    window.dispatchEvent(new CustomEvent('connext:gameend', {
+      detail: {
+        id: GAME_ID,
+        won: false,
+        score: game.score,
+        summary: summarise(game, locale),
+        title: translate({id: 'preset.lockPick.over.title', message: 'That was the last pick.', description: 'Headline on the game-over dialog after a lock-pick run'}),
+        subtitle: translate({id: 'preset.lockPick.over.subtitle', message: 'The lock is still shut, which is rather the point of a good one.', description: 'Subtitle on the game-over dialog after a lock-pick run'}),
+      },
+    }));
+  }, [game, locale]);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return undefined;
+    const onReplay = (e) => { if (e.detail && e.detail.id === GAME_ID) begin(); };
+    window.addEventListener('connext:gamereplay', onReplay);
+    return () => window.removeEventListener('connext:gamereplay', onReplay);
+  }, [begin]);
+
+  const moveTo = useCallback((value) => {
+    if (!gameRef.current || gameRef.current.over) return;
+    const next = setPosition(gameRef.current, value);
+    gameRef.current = next;
+    setGame(next);
+  }, []);
+
+  const tryTurn = useCallback(() => {
+    if (!gameRef.current || gameRef.current.over) return;
+    const next = turn(gameRef.current);
+    gameRef.current = next;
+    setGame(next);
+  }, []);
+
+  const position = game ? game.position : Math.floor(POSITIONS / 2);
+  const last = game ? game.last : null;
+  /* The cylinder shows what the last turn achieved, not what the
+     current position would achieve: showing the latter would hand the
+     player the answer by dragging the dial. */
+  const turned = last && (last.result === 'held' || last.result === 'snapped') ? last.give : 0;
+
+  return (
+    <section className={[styles.lp, className].filter(Boolean).join(' ')} aria-labelledby="lock-pick-title">
+      <header className={styles.head}>
+        <div>
+          <p className={styles.eyebrow}>
+            {translate({id: 'preset.lockPick.eyebrow', message: 'Mini-game', description: 'Eyebrow above the lock-pick game on a product page'})}
+          </p>
+          <h3 className={styles.title} id="lock-pick-title">
+            {translate({id: 'preset.lockPick.title', message: 'Lock pick', description: 'Name of the Keepiq mini-game'})}
+          </h3>
+          <p className={styles.lede}>
+            {translate({id: 'preset.lockPick.lede', message: 'Set the pick, turn the cylinder, feel how far it gives. Every turn tells you how close you were. Three picks, and each lock is tighter than the last.', description: 'One-line explanation of the lock-pick rules'})}
+          </p>
+        </div>
+        <div className={styles.hud} role="status" aria-live="polite">
+          <span className={styles.hudPill}>
+            {translate({id: 'preset.lockPick.hud.score', message: 'Score {score}', description: 'Score readout on the lock-pick HUD'}, {score: Number(game ? game.score : 0).toLocaleString(locale)})}
+          </span>
+          <span className={styles.hudPill}>
+            {translate({id: 'preset.lockPick.hud.picks', message: 'Picks {picks}', description: 'Remaining-picks readout on the lock-pick HUD'}, {picks: game ? game.picks : 3})}
+          </span>
+          <span className={styles.hudPill}>
+            {translate({id: 'preset.lockPick.hud.opened', message: 'Opened {opened}', description: 'Opened-locks readout on the lock-pick HUD'}, {opened: game ? game.opened : 0})}
+          </span>
+        </div>
+      </header>
+
+      <div className={styles.lock}>
+        {/* The cylinder, turned as far as the last attempt managed. */}
+        <div
+          className={styles.cylinder}
+          role="img"
+          aria-label={translate(
+            {id: 'preset.lockPick.cylinder', message: 'The cylinder turned {percent} per cent on the last try', description: 'Accessible description of the lock cylinder. {percent} is how far it turned.'},
+            {percent: Math.round(turned * 100)},
+          )}>
+          <div className={styles.cylinderFill} style={{transform: `rotate(${-90 + turned * 80}deg)`}} />
+          <span className={styles.keyhole} aria-hidden="true" />
+        </div>
+
+        <div className={styles.dial}>
+          <label className={styles.dialLabel} htmlFor="lock-pick-dial">
+            {translate({id: 'preset.lockPick.dialLabel', message: 'Where the pick sits', description: 'Label for the lock-pick dial slider'})}
+          </label>
+          <input
+            id="lock-pick-dial"
+            className={styles.slider}
+            type="range"
+            min={0}
+            max={POSITIONS - 1}
+            step={1}
+            value={position}
+            disabled={!running}
+            onChange={(e) => moveTo(Number(e.target.value))}
+          />
+          <div className={styles.pickRow}>
+            <span className={styles.pickLabel}>
+              {translate({id: 'preset.lockPick.wear', message: 'This pick', description: 'Label for the lock-pick durability bar'})}
+            </span>
+            <span
+              className={styles.wear}
+              role="progressbar"
+              aria-valuemin={0}
+              aria-valuemax={100}
+              aria-valuenow={game ? game.durability : 100}>
+              <span
+                className={[styles.wearFill, game && game.durability <= 35 && styles.wearLow].filter(Boolean).join(' ')}
+                style={{width: `${game ? game.durability : 100}%`}}
+              />
+            </span>
+          </div>
+        </div>
+      </div>
+
+      <footer className={styles.foot}>
+        <button type="button" className={styles.turn} onClick={tryTurn} disabled={!running}>
+          {translate({id: 'preset.lockPick.turn', message: 'Turn the cylinder', description: 'Button that attempts to turn the lock'})}
+        </button>
+        <button type="button" className={styles.start} onClick={begin}>
+          {game
+            ? translate({id: 'preset.lockPick.restart', message: 'New lock', description: 'Button that restarts the lock-pick game'})
+            : translate({id: 'preset.lockPick.start', message: 'Take a pick', description: 'Button that starts the lock-pick game'})}
+        </button>
+        <p className={styles.feedback} role="status" aria-live="polite">
+          {last && last.result === 'opened' && translate(
+            {id: 'preset.lockPick.feedback.opened', message: 'Open, in {attempts}. Worth {points}. The next one is tighter.', description: 'Feedback after opening a lock. {attempts} is how many turns it took, {points} what it scored.'},
+            {attempts: last.attempts, points: last.points},
+          )}
+          {last && last.result === 'snapped' && translate({id: 'preset.lockPick.feedback.snapped', message: 'The pick snapped. The lock is where you left it, so keep going from there.', description: 'Feedback after a pick breaks'})}
+          {last && last.result === 'held' && feelCopy(last.give)}
+          {!last && translate({id: 'preset.lockPick.hint', message: 'Move the pick with the slider or the arrow keys, then turn. Wild guesses cost the pick; near misses cost very little.', description: 'Hint under the lock-pick board before the first turn'})}
+        </p>
+      </footer>
+    </section>
+  );
+}

package/src/components/LockPick/LockPick.module.css

@@ -0,0 +1,205 @@
+/**
+ * <LockPick /> styles.
+ *
+ * Tokens only. One accent: a pick that is nearly spent. Everything the
+ * player needs to reason with is a sentence under the lock, so the
+ * cylinder and the bars are illustration rather than information.
+ */
+
+.lp {
+  border: 1px solid var(--c-cobalt-100);
+  border-radius: var(--radius-lg);
+  background: white;
+  padding: clamp(16px, 3vw, 28px);
+  font-family: var(--conduction-typography-font-family-body);
+}
+
+.head {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+  align-items: flex-start;
+  justify-content: space-between;
+  margin-bottom: 18px;
+}
+
+.eyebrow {
+  margin: 0 0 4px;
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 11px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--c-orange-knvb);
+}
+
+.title {
+  margin: 0 0 6px;
+  font-size: 20px;
+  font-weight: 700;
+  color: var(--c-cobalt-900);
+}
+
+.lede {
+  margin: 0;
+  max-width: 58ch;
+  font-size: 14px;
+  line-height: 1.5;
+  color: var(--c-cobalt-700);
+}
+
+.hud {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+}
+.hudPill {
+  padding: 6px 10px;
+  border-radius: var(--radius-pill);
+  background: var(--c-cobalt-50);
+  color: var(--c-cobalt-900);
+  white-space: nowrap;
+}
+
+.lock {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 24px;
+  padding: 18px;
+  border-radius: var(--radius-md);
+  background: var(--c-cobalt-50);
+  max-width: 620px;
+}
+
+.cylinder {
+  position: relative;
+  width: 104px;
+  height: 104px;
+  flex-shrink: 0;
+  border-radius: 50%;
+  background: white;
+  border: 2px solid var(--c-cobalt-200);
+  overflow: hidden;
+}
+
+/* The bar across the cylinder, rotated as far as the last turn got. */
+.cylinderFill {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 66px;
+  height: 8px;
+  margin: -4px 0 0 -33px;
+  border-radius: var(--radius-pill);
+  background: var(--c-blue-cobalt);
+  transform-origin: center;
+  transition: transform 180ms ease-out;
+}
+
+.keyhole {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 14px;
+  height: 14px;
+  margin: -7px 0 0 -7px;
+  border-radius: 50%;
+  background: var(--c-cobalt-900);
+}
+
+.dial {
+  flex: 1;
+  min-width: 220px;
+}
+
+.dialLabel {
+  display: block;
+  font-size: 12px;
+  color: var(--c-cobalt-700);
+  margin-bottom: 6px;
+}
+
+.slider {
+  width: 100%;
+  accent-color: var(--c-blue-cobalt);
+}
+.slider:focus-visible { outline: 2px solid var(--c-blue-cobalt); outline-offset: 4px; }
+
+.pickRow {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-top: 14px;
+}
+
+.pickLabel {
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 11px;
+  color: var(--c-cobalt-400);
+  white-space: nowrap;
+}
+
+.wear {
+  flex: 1;
+  height: 6px;
+  border-radius: var(--radius-pill);
+  background: var(--c-cobalt-200);
+  overflow: hidden;
+}
+.wearFill {
+  display: block;
+  height: 100%;
+  background: var(--c-mint-500);
+  transition: width 160ms ease-out;
+}
+.wearLow { background: var(--c-orange-knvb); }
+
+.foot {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 10px;
+  margin-top: 16px;
+}
+
+.turn {
+  background: var(--c-blue-cobalt);
+  color: white;
+  border: 1px solid var(--c-blue-cobalt);
+  padding: 10px 18px;
+  border-radius: var(--radius-md);
+  font-family: inherit;
+  font-weight: 500;
+  font-size: 14px;
+  cursor: pointer;
+  transition: background 120ms ease;
+}
+.turn:hover:not(:disabled) { background: var(--c-cobalt-700); border-color: var(--c-cobalt-700); }
+.turn:disabled { opacity: 0.5; cursor: default; }
+.turn:focus-visible { outline: 2px solid var(--c-cobalt-900); outline-offset: 2px; }
+
+.start {
+  background: white;
+  color: var(--c-cobalt-700);
+  border: 1px solid var(--c-cobalt-200);
+  padding: 10px 18px;
+  border-radius: var(--radius-md);
+  font-family: inherit;
+  font-weight: 500;
+  font-size: 14px;
+  cursor: pointer;
+  transition: border-color 120ms ease;
+}
+.start:hover { border-color: var(--c-blue-cobalt); color: var(--c-blue-cobalt); }
+.start:focus-visible { outline: 2px solid var(--c-blue-cobalt); outline-offset: 2px; }
+
+.feedback {
+  margin: 0;
+  flex-basis: 100%;
+  font-size: 13px;
+  color: var(--c-cobalt-700);
+  min-height: 1.5em;
+}

package/src/components/LockPick/__tests__/engine.test.js

@@ -0,0 +1,193 @@
+/**
+ * engine.test.js — the lock-pick rules.
+ *
+ * Two properties carry the game. Every lock must be openable by
+ * feeling for it, which is what makes this deduction rather than a
+ * lottery: the feedback has to get stronger as the pick gets closer,
+ * on every lock, at every difficulty. And a snapped pick must not cost
+ * the player the lock they had almost worked out.
+ */
+
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  createGame, setPosition, nudge, give, turn, summarise, POSITIONS, DEFAULTS,
+} = require('../engine.js');
+
+/** Play a lock the way a person would: halve the range by feel. */
+function pickByFeel(state, maxTurns = 40) {
+  let s = state;
+  let low = 0;
+  let high = POSITIONS - 1;
+  const opened = s.opened;
+  for (let i = 0; i < maxTurns && !s.over && s.opened === opened; i++) {
+    const mid = Math.round((low + high) / 2);
+    s = setPosition(s, mid);
+    const before = give(s);
+    s = turn(s);
+    if (s.opened > opened || s.over) break;
+    /* Feel left and right of the guess, and walk towards the stronger
+       side. This is what a player does with graded feedback. */
+    const left = give(setPosition(s, Math.max(low, mid - 5)));
+    const right = give(setPosition(s, Math.min(high, mid + 5)));
+    if (left > before && left >= right) high = mid;
+    else if (right > before) low = mid;
+    else { low = Math.max(low, mid - 10); high = Math.min(high, mid + 10); }
+  }
+  return s;
+}
+
+test('a game starts with three picks, a whole pick, and a lock', () => {
+  const s = createGame({seed: 1});
+  assert.equal(s.picks, DEFAULTS.picks);
+  assert.equal(s.durability, DEFAULTS.durability);
+  assert.equal(s.lock.tolerance, DEFAULTS.toleranceStart);
+  assert.equal(s.over, false);
+});
+
+test('the sweet spot is never against either end of the dial', () => {
+  for (let seed = 1; seed <= 50; seed++) {
+    let s = createGame({seed});
+    for (let lock = 0; lock < 8; lock++) {
+      const {sweet, tolerance} = s.lock;
+      assert.ok(sweet - tolerance > 0, `seed ${seed}: a lock opens at the very start of the dial`);
+      assert.ok(sweet + tolerance < POSITIONS - 1, `seed ${seed}: a lock opens at the very end`);
+      s = turn(setPosition(s, sweet));
+    }
+  }
+});
+
+test('the pick moves, and the dial does not wrap', () => {
+  const s = createGame({seed: 2});
+  assert.equal(setPosition(s, -5).position, 0);
+  assert.equal(setPosition(s, 999).position, POSITIONS - 1);
+  assert.equal(nudge(setPosition(s, 10), -1).position, 9);
+  assert.equal(nudge(setPosition(s, 0), -1).position, 0);
+});
+
+test('the cylinder gives more the closer the pick gets, on every lock', () => {
+  for (let seed = 1; seed <= 25; seed++) {
+    const s = createGame({seed});
+    const {sweet} = s.lock;
+    let previous = -1;
+    /* Walk in from a long way out on whichever side has room: the dial
+       does not wrap, so on a lock near one end the far distances all
+       clamp to the same position and would compare equal. */
+    const towardsEnd = sweet > POSITIONS / 2 ? -1 : 1;
+    for (const distance of [40, 30, 20, 14, 10]) {
+      const at = sweet + towardsEnd * distance;
+      assert.ok(at >= 0 && at < POSITIONS, `seed ${seed}: walked off the dial at ${distance}`);
+      const value = give(setPosition(s, at));
+      assert.ok(value > previous, `seed ${seed}: the feel did not improve at ${distance} away`);
+      previous = value;
+    }
+    assert.equal(give(setPosition(s, sweet)), 1);
+  }
+});
+
+test('turning on the sweet spot opens the lock and pays for the pick that is left', () => {
+  const s = createGame({seed: 3});
+  const opened = turn(setPosition(s, s.lock.sweet));
+  assert.equal(opened.opened, 1);
+  assert.ok(opened.score >= DEFAULTS.pointsPerLock);
+  assert.equal(opened.last.result, 'opened');
+  assert.equal(opened.picks, DEFAULTS.picks, 'opening a lock cost a pick');
+  assert.equal(opened.durability, DEFAULTS.durability, 'the next lock started on a worn pick');
+});
+
+test('each lock opened narrows the next one, down to a floor', () => {
+  let s = createGame({seed: 4});
+  const seen = [];
+  for (let i = 0; i < 12; i++) {
+    seen.push(s.lock.tolerance);
+    s = turn(setPosition(s, s.lock.sweet));
+  }
+  assert.equal(seen[0], DEFAULTS.toleranceStart);
+  assert.ok(seen[3] < seen[0], 'the locks never got harder');
+  assert.equal(Math.min(...seen), DEFAULTS.toleranceFloor, 'the difficulty never reached its floor');
+  assert.ok(seen.every((t) => t >= DEFAULTS.toleranceFloor), 'a lock got harder than the floor');
+});
+
+test('a turn well off the spot strains the pick, and a wild one costs far more', () => {
+  const s = createGame({seed: 5});
+  const near = turn(setPosition(s, s.lock.sweet + s.lock.tolerance + 4));
+  const far = turn(setPosition(s, s.lock.sweet > 50 ? 0 : POSITIONS - 1));
+
+  assert.equal(near.last.result, 'held');
+  assert.ok(near.durability < DEFAULTS.durability);
+
+  /* The wild turn must hurt more but must not be fatal on its own:
+     the pick has to survive long enough for the player to read the
+     feedback it just gave them. */
+  assert.equal(far.last.result, 'held', 'one wild turn snapped a fresh pick');
+  assert.ok(
+    DEFAULTS.durability - far.durability > DEFAULTS.durability - near.durability,
+    'a wild guess cost no more than a near miss',
+  );
+});
+
+test('two wild turns in a row do end a pick', () => {
+  let s = createGame({seed: 5});
+  const wild = s.lock.sweet > 50 ? 0 : POSITIONS - 1;
+  s = turn(setPosition(s, wild));
+  assert.equal(s.picks, DEFAULTS.picks);
+  s = turn(setPosition(s, wild));
+  assert.equal(s.last.result, 'snapped');
+  assert.equal(s.picks, DEFAULTS.picks - 1);
+});
+
+test('a snapped pick costs a pick but never the lock', () => {
+  let s = createGame({seed: 6});
+  const {sweet, tolerance} = s.lock;
+  const wild = sweet > 50 ? 0 : POSITIONS - 1;
+  while (s.picks === DEFAULTS.picks && !s.over) s = turn(setPosition(s, wild));
+  assert.equal(s.picks, DEFAULTS.picks - 1);
+  assert.equal(s.last.result, 'snapped');
+  assert.equal(s.durability, DEFAULTS.durability, 'the new pick started already worn');
+  assert.equal(s.lock.sweet, sweet, 'the lock was re-dealt under the player');
+  assert.equal(s.lock.tolerance, tolerance);
+});
+
+test('three snapped picks end the run, and nothing moves afterwards', () => {
+  let s = createGame({seed: 7});
+  const wild = s.lock.sweet > 50 ? 0 : POSITIONS - 1;
+  for (let i = 0; i < 200 && !s.over; i++) s = turn(setPosition(s, wild));
+  assert.equal(s.over, true);
+  assert.equal(s.picks, 0);
+  assert.equal(s.snapped, 3);
+  assert.equal(turn(s).turns, s.turns, 'the lock still turned after the last pick snapped');
+  assert.equal(setPosition(s, 5).position, s.position, 'the pick still moved after game over');
+});
+
+test('a player who feels for it opens locks rather than running out of picks', () => {
+  /* Twenty seeds, played the way the feedback asks to be played. If
+     this fails the game is a lottery, whatever it looks like. */
+  let openedTotal = 0;
+  for (let seed = 1; seed <= 20; seed++) {
+    let s = createGame({seed});
+    for (let lock = 0; lock < 3 && !s.over; lock++) s = pickByFeel(s);
+    assert.ok(s.opened >= 1, `seed ${seed}: feeling for the spot never opened a single lock`);
+    openedTotal += s.opened;
+  }
+  assert.ok(openedTotal >= 40, `expected most locks to fall to deduction, got ${openedTotal}`);
+});
+
+test('the same seed sets the same locks, a different one does not', () => {
+  const spots = (seed) => {
+    let s = createGame({seed});
+    const out = [];
+    for (let i = 0; i < 6; i++) { out.push(s.lock.sweet); s = turn(setPosition(s, s.lock.sweet)); }
+    return out.join(',');
+  };
+  assert.equal(spots(11), spots(11));
+  assert.notEqual(spots(11), spots(12));
+});
+
+test('the summary reads as a sentence in both locales', () => {
+  const s = {opened: 5, turns: 23};
+  assert.match(summarise(s, 'en'), /5 locks opened · 23 turns/);
+  assert.match(summarise(s, 'nl'), /5 sloten open · 23 pogingen/);
+});

package/src/components/LockPick/engine.js

@@ -0,0 +1,172 @@
+/**
+ * Lock pick — the rules, with no DOM and no clock of its own.
+ *
+ * Keepiq's game, and the one everybody already knows how to play: set
+ * the pick, turn the cylinder, feel how far it gives. Close to the
+ * sweet spot it turns; far from it the pick strains and eventually
+ * snaps. Three picks and the lock wins.
+ *
+ * The feedback is graded rather than binary, which is what makes it a
+ * game of deduction instead of a lottery: every turn tells you how
+ * close you were, so the next one is a better guess. It also means the
+ * lock is pickable without seeing anything, which matters more here
+ * than the animation does.
+ *
+ * Nothing in here runs on a clock. A lock is a state machine, not a
+ * race, and that is the difference between this game and the other
+ * four.
+ */
+
+export const POSITIONS = 100;
+
+export const DEFAULTS = {
+  picks: 3,
+  /* How far off the sweet spot the pick may be and still open the
+     lock, as positions on the dial. Narrows each time a lock opens,
+     down to a floor that is still findable by halving the range. */
+  toleranceStart: 9,
+  toleranceFloor: 3,
+  toleranceStep: 1,
+  /* A pick survives a few bad turns near the spot and one wild one.
+     Strain is the square of how far off you were, so the punishment
+     for a guess a long way out is what ends a pick, not patience. */
+  durability: 100,
+  strainScale: 2.4,
+  /* No single turn may snap a fresh pick. Without this cap a guess at
+     the far end of the dial costs a whole pick, so a player who has
+     not found the spot yet loses all three before learning anything,
+     and the graded feedback the game is built on never gets read. Two
+     wild turns in a row still end a pick. */
+  maxStrain: 55,
+  pointsPerLock: 20,
+  /* What is left of the pick when the lock opens is worth points: it
+     rewards deduction over brute force, which is the whole game. */
+  durabilityBonusDivisor: 5,
+};
+
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function random() {
+    a |= 0; a = (a + 0x6D2B79F5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function newLock(state) {
+  const tolerance = Math.max(
+    state.cfg.toleranceFloor,
+    state.cfg.toleranceStart - state.opened * state.cfg.toleranceStep,
+  );
+  /* Keep the sweet spot off the very edges: a lock whose answer is 0
+     or 99 is opened by the two guesses everybody tries first. */
+  const margin = tolerance + 2;
+  const span = POSITIONS - 1 - margin * 2;
+  return {
+    sweet: margin + Math.floor(state.random() * (span + 1)),
+    tolerance,
+    attempts: 0,
+  };
+}
+
+export function createGame({seed = Date.now(), config = {}} = {}) {
+  const cfg = {...DEFAULTS, ...config};
+  const base = {
+    cfg,
+    random: mulberry32(seed),
+    position: Math.floor(POSITIONS / 2),
+    picks: cfg.picks,
+    durability: cfg.durability,
+    score: 0,
+    opened: 0,
+    snapped: 0,
+    turns: 0,
+    last: null,
+    over: false,
+  };
+  return {...base, lock: newLock(base)};
+}
+
+/** Move the pick. The dial does not wrap: both ends are ends. */
+export function setPosition(state, position) {
+  if (state.over) return state;
+  const clamped = Math.min(POSITIONS - 1, Math.max(0, Math.round(position)));
+  return clamped === state.position ? state : {...state, position: clamped};
+}
+
+export function nudge(state, delta) {
+  return setPosition(state, state.position + delta);
+}
+
+/**
+ * How far the cylinder turns at the current position, 0 to 1.
+ *
+ * Inside the tolerance it is 1: the lock opens. Outside, it falls away
+ * with distance, and that number is both the feedback the player reads
+ * and the inverse of the strain the pick takes.
+ */
+export function give(state) {
+  const distance = Math.abs(state.position - state.lock.sweet);
+  if (distance <= state.lock.tolerance) return 1;
+  const reach = POSITIONS / 2;
+  return Math.max(0, 1 - (distance - state.lock.tolerance) / reach);
+}
+
+/**
+ * Turn the cylinder.
+ *
+ * Opens the lock, or costs the pick some life. A pick that runs out
+ * snaps, and the next one starts fresh on the same lock: the lock is
+ * not re-dealt, because a player who has narrowed it down to two
+ * positions should not lose that work to a broken pick.
+ */
+export function turn(state) {
+  if (state.over) return state;
+
+  const turned = give(state);
+  const attempts = state.lock.attempts + 1;
+  const base = {...state, turns: state.turns + 1, lock: {...state.lock, attempts}};
+
+  if (turned >= 1) {
+    const bonus = Math.round(base.durability / base.cfg.durabilityBonusDivisor);
+    const opened = {
+      ...base,
+      score: base.score + base.cfg.pointsPerLock + bonus,
+      opened: base.opened + 1,
+      durability: base.cfg.durability,
+      last: {result: 'opened', points: base.cfg.pointsPerLock + bonus, attempts},
+    };
+    /* A fresh lock, and a fresh pick with it: the run ends on the
+       locks that beat you, not on wear from the ones you solved. */
+    return {...opened, lock: newLock(opened), position: Math.floor(POSITIONS / 2)};
+  }
+
+  const strain = Math.min(
+    base.cfg.maxStrain,
+    Math.round((1 - turned) ** 2 * 100 * base.cfg.strainScale / 2) + 4,
+  );
+  const durability = base.durability - strain;
+
+  if (durability > 0) {
+    return {...base, durability, last: {result: 'held', give: turned, attempts}};
+  }
+
+  const picks = base.picks - 1;
+  return {
+    ...base,
+    picks,
+    snapped: base.snapped + 1,
+    durability: base.cfg.durability,
+    last: {result: 'snapped', give: turned, attempts},
+    over: picks <= 0,
+  };
+}
+
+/** The line that goes on the game-over card and into the post. */
+export function summarise(state, locale = 'en') {
+  const n = (v) => Number(v || 0).toLocaleString(locale);
+  return locale === 'nl'
+    ? `${n(state.opened)} sloten open · ${n(state.turns)} pogingen`
+    : `${n(state.opened)} locks opened · ${n(state.turns)} turns`;
+}

package/src/components/index.js

@@ -64,6 +64,7 @@ export {default as StampRush} from './StampRush/StampRush.jsx';
 export {default as DeadlineDefender} from './DeadlineDefender/DeadlineDefender.jsx';
 export {default as BlueprintRush} from './BlueprintRush/BlueprintRush.jsx';
 export {default as RecordRun} from './RecordRun/RecordRun.jsx';
+export {default as LockPick} from './LockPick/LockPick.jsx';
 
 /* Diagram-set web-component React wrappers (cn-hex, cn-platform,
    cn-domain-tree, cn-pipeline, cn-side-box, cn-honeycomb-bg, cn-pair,