@conduction/docusaurus-preset 3.38.0 → 3.40.0

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`;
+}