@conduction/docusaurus-preset 3.28.0 → 3.31.0

package/src/components/CookieCli/spaceInvaders.js

@@ -0,0 +1,359 @@
+/**
+ * Conduction Space Invaders — the game behind `game.exe` in the cookie CLI.
+ *
+ * Ported from the kit specimen at preview/cookie-cli.html, where this had
+ * lived since the component was designed. The React <CookieCli /> shipped
+ * without it for a while, which meant GameModal advertised a game
+ * ("Hex-vaders · cookie CLI") that no site actually had.
+ *
+ * Kept as a plain class rather than React state on purpose. It ticks every
+ * 90ms and repaints a 48x14 character grid, which is 672 cells per frame,
+ * eleven times a second. Reconciling that through React would do a great
+ * deal of work to arrive at the same string. The class builds the frame as
+ * HTML and hands it to the caller, which writes it to a ref.
+ *
+ * Cobalt UFOs, KNVB-orange lasers, per the kit.
+ *
+ * The engine owns no DOM and reads no globals. It reports frames through
+ * `onFrame` and asks to be dismissed through `onExit`, so the React
+ * component stays the only thing that touches the document.
+ */
+
+const COLS = 48;
+const ROWS = 14;
+
+/* The event the shared GameModal listens for. Named `connext:` because the
+   modal has used that prefix since the ConNext era; it is a brand-internal
+   identifier kept for compatibility, not a live brand reference. */
+const GAME_END_EVENT = 'connext:gameend';
+const GAME_REPLAY_EVENT = 'connext:gamereplay';
+const GAME_ID = 'invaders';
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  }[c]));
+}
+
+export default class SpaceInvaders {
+  /**
+   * @param {object}   opts
+   * @param {function} opts.onFrame - called with {screen, hud, footer} HTML each repaint
+   * @param {function} opts.onExit  - called when the player quits (ESC / Q)
+   */
+  constructor({onFrame, onExit} = {}) {
+    this.onFrame = typeof onFrame === 'function' ? onFrame : () => {};
+    this.onExit = typeof onExit === 'function' ? onExit : () => {};
+
+    this.score = 0;
+    this.wave = 1;
+    this.hits = 0;      // bombs that landed on you; costs nothing but pride
+    this.cleared = 0;   // waves shot down
+    this.landed = 0;    // waves that reached the floor
+    this.hitFlash = 0;  // ticks left of the impact glyph
+    this.paused = false;
+    this.player = {x: Math.floor(COLS / 2) - 1};
+    this.lasers = [];
+    this.bombs = [];
+    this.ufos = [];
+    this.ufoDir = 1;
+    this.ufoSpeed = 9;
+    this.tickCount = 0;
+    this.graceTicks = 18; // ~1.6s before bombs start dropping
+
+    this.onReplay = (e) => {
+      if (e.detail && e.detail.id === GAME_ID) this.restart();
+    };
+    if (typeof window !== 'undefined') {
+      window.addEventListener(GAME_REPLAY_EVENT, this.onReplay);
+    }
+
+    this.spawnUfos();
+    this.interval = setInterval(() => this.tick(), 90);
+    this.render();
+  }
+
+  spawnUfos() {
+    this.ufos = [];
+    const rows = 3, cols = 6;
+    const spacing = 7;
+    const xStart = Math.floor((COLS - (cols - 1) * spacing - 3) / 2);
+    for (let r = 0; r < rows; r++) {
+      for (let c = 0; c < cols; c++) {
+        this.ufos.push({x: xStart + c * spacing, y: 1 + r * 2, alive: true, exploding: 0, row: r});
+      }
+    }
+  }
+
+  onKey(e) {
+    /* The old game-over branch is gone with game over itself. [R] used to
+       live only in that branch, which would have left it dead: reachable
+       by a key hint that never appeared, on a screen that never showed.
+       It now restarts at any time. */
+    switch (e.key) {
+      case 'r': case 'R':
+        this.restart(); e.preventDefault(); return;
+      default: break;
+    }
+    switch (e.key) {
+      case 'ArrowLeft': case 'a': case 'A':
+        this.player.x = Math.max(0, this.player.x - 2);
+        e.preventDefault(); break;
+      case 'ArrowRight': case 'd': case 'D':
+        this.player.x = Math.min(COLS - 3, this.player.x + 2);
+        e.preventDefault(); break;
+      case ' ': case 'ArrowUp': case 'w': case 'W':
+        this.fire(); e.preventDefault(); break;
+      case 'Escape': case 'q': case 'Q':
+        this.quit(); e.preventDefault(); break;
+      case 'p': case 'P':
+        this.paused = !this.paused; e.preventDefault(); this.render(); break;
+      default: break;
+    }
+  }
+
+  fire() {
+    if (this.lasers.length >= 3) return;
+    this.lasers.push({x: this.player.x + 1, y: ROWS - 2});
+  }
+
+  quit() {
+    this.stop();
+    this.onExit();
+  }
+
+  stop() {
+    clearInterval(this.interval);
+    this.interval = null;
+    if (typeof window !== 'undefined') {
+      window.removeEventListener(GAME_REPLAY_EVENT, this.onReplay);
+    }
+  }
+
+  restart() {
+    this.score = 0;
+    this.wave = 1;
+    this.hits = 0;
+    this.cleared = 0;
+    this.landed = 0;
+    this.hitFlash = 0;
+    this._endEmitted = false;
+    this.player = {x: Math.floor(COLS / 2) - 1};
+    this.lasers = [];
+    this.bombs = [];
+    this.ufoSpeed = 9;
+    this.tickCount = 0;
+    this.graceTicks = 18;
+    this.spawnUfos();
+    this.render();
+  }
+
+  /* Advance to a fresh wave, whether the last one was shot down or landed.
+     Clears bombs so the new wave does not open under incoming fire, and
+     restores the grace period so there is a beat before it resumes. */
+  nextWave() {
+    this.wave += 1;
+    this.spawnUfos();
+    this.ufoSpeed = Math.max(3, 9 - this.wave);
+    this.bombs = [];
+    this.graceTicks = 12;
+    this.render();
+  }
+
+  tick() {
+    if (this.paused) return;
+    this.tickCount++;
+
+    // lasers up every tick
+    this.lasers.forEach((l) => { l.y -= 1; });
+    this.lasers = this.lasers.filter((l) => l.y >= 0);
+
+    // bombs down every 2 ticks
+    if (this.tickCount % 2 === 0) {
+      this.bombs.forEach((b) => { b.y += 1; });
+      this.bombs = this.bombs.filter((b) => b.y < ROWS);
+    }
+
+    // UFOs march
+    if (this.tickCount % this.ufoSpeed === 0) {
+      const alive = this.ufos.filter((u) => u.alive);
+      if (alive.length) {
+        const minX = Math.min(...alive.map((u) => u.x));
+        const maxX = Math.max(...alive.map((u) => u.x));
+        if (this.ufoDir === 1 && maxX + 3 >= COLS) {
+          this.ufoDir = -1;
+          alive.forEach((u) => { u.y += 1; });
+        } else if (this.ufoDir === -1 && minX <= 0) {
+          this.ufoDir = 1;
+          alive.forEach((u) => { u.y += 1; });
+        } else {
+          alive.forEach((u) => { u.x += this.ufoDir; });
+        }
+      }
+    }
+
+    // random bombs, after a short grace period so the player can settle in
+    if (this.graceTicks > 0) {
+      this.graceTicks--;
+    } else {
+      const aliveUfos = this.ufos.filter((u) => u.alive);
+      const bombChance = 0.035 + (this.wave - 1) * 0.01;
+      if (aliveUfos.length && this.bombs.length < 4 && Math.random() < bombChance) {
+        const u = aliveUfos[Math.floor(Math.random() * aliveUfos.length)];
+        this.bombs.push({x: u.x + 1, y: u.y + 1});
+      }
+    }
+
+    // laser vs ufo
+    this.lasers.forEach((l) => {
+      this.ufos.forEach((u) => {
+        if (!u.alive) return;
+        if (l.y === u.y && l.x >= u.x && l.x <= u.x + 2) {
+          u.alive = false;
+          u.exploding = 2;
+          l.dead = true;
+          this.score += 10 * (3 - u.row);
+          const remaining = this.ufos.filter((uu) => uu.alive).length;
+          this.ufoSpeed = Math.max(2, 8 - Math.floor((18 - remaining) / 3));
+        }
+      });
+    });
+    this.lasers = this.lasers.filter((l) => !l.dead);
+
+    this.ufos.forEach((u) => { if (u.exploding > 0) u.exploding -= 1; });
+
+    /* Bombs vs player. You cannot die here.
+       This is an easter egg in a cookie banner, not an arcade cabinet:
+       ending someone's game with GAME OVER while they were only trying to
+       set a cookie preference is a bad trade. A hit still lands and still
+       reads as a hit, it just costs a moment of shield flash rather than a
+       life. Bombs stay dangerous-looking and become harmless. */
+    this.bombs.forEach((b) => {
+      if (b.y === ROWS - 1 && b.x >= this.player.x && b.x <= this.player.x + 2) {
+        b.dead = true;
+        this.hitFlash = 4;   // ticks the player renders as an impact
+        this.hits += 1;
+      }
+    });
+    this.bombs = this.bombs.filter((b) => !b.dead);
+    if (this.hitFlash > 0) this.hitFlash -= 1;
+
+    /* UFOs reaching the bottom used to end the game outright, regardless of
+       lives. Now the wave simply lands and a fresh one spawns, so the run
+       continues. Without this the one unavoidable death would still be
+       reachable by standing still. */
+    if (this.ufos.some((u) => u.alive && u.y >= ROWS - 1)) {
+      this.landed += 1;
+      this.nextWave();
+      return;
+    }
+
+    // wave clear
+    if (this.ufos.every((u) => !u.alive && u.exploding === 0)) {
+      this.cleared += 1;
+      this.nextWave();
+
+      /* Tell the shared GameModal the game was found, so it records
+         discovery and score in its cross-site progress cookie.
+         This used to fire on game over. Since there is no game over any
+         more, clearing the first wave is the moment: without moving it the
+         event would never fire at all and the game would stay permanently
+         undiscovered in the modal, which is a silent regression rather than
+         a visible one. Once per run. */
+      if (!this._endEmitted && typeof window !== 'undefined') {
+        this._endEmitted = true;
+        window.dispatchEvent(new CustomEvent(GAME_END_EVENT, {
+          detail: {
+            id: GAME_ID,
+            won: true,
+            score: this.score,
+            summary: `${this.score} pts · wave ${this.wave}`,
+          },
+        }));
+      }
+    }
+
+    this.render();
+  }
+
+  render() {
+    const grid = [];
+    const meta = [];
+    for (let y = 0; y < ROWS; y++) {
+      grid.push(Array(COLS).fill(' '));
+      meta.push(Array(COLS).fill(''));
+    }
+    const set = (y, x, c, t) => {
+      if (y >= 0 && y < ROWS && x >= 0 && x < COLS) { grid[y][x] = c; meta[y][x] = t; }
+    };
+
+    this.ufos.forEach((u) => {
+      if (u.alive) {
+        set(u.y, u.x, '<', 'ufo'); set(u.y, u.x + 1, 'O', 'ufo'); set(u.y, u.x + 2, '>', 'ufo');
+      } else if (u.exploding > 0) {
+        set(u.y, u.x, '*', 'boom'); set(u.y, u.x + 1, '#', 'boom'); set(u.y, u.x + 2, '*', 'boom');
+      }
+    });
+
+    this.lasers.forEach((l) => set(l.y, l.x, '|', 'laser'));
+    this.bombs.forEach((b) => set(b.y, b.x, '*', 'bomb'));
+
+    /* The ship, or a brief impact burst when something just hit it. The
+       flash is the whole feedback for taking a hit now that it costs
+       nothing, so without it bombs would land with no effect at all and
+       the game would feel broken rather than forgiving. */
+    if (this.hitFlash > 0) {
+      set(ROWS - 1, this.player.x, '*', 'boom');
+      set(ROWS - 1, this.player.x + 1, '#', 'boom');
+      set(ROWS - 1, this.player.x + 2, '*', 'boom');
+    } else {
+      set(ROWS - 1, this.player.x, '<', 'player');
+      set(ROWS - 1, this.player.x + 1, 'A', 'player');
+      set(ROWS - 1, this.player.x + 2, '>', 'player');
+    }
+
+    /* Coalesce equal-styled runs into one span per run instead of one per
+       character. A row is 48 cells but usually only a handful of runs. */
+    let screen = '';
+    for (let y = 0; y < ROWS; y++) {
+      let line = '';
+      let runT = '', runS = '';
+      const flush = () => {
+        if (!runS) return;
+        line += runT ? `<span class="g-${runT}">${escapeHtml(runS)}</span>` : escapeHtml(runS);
+        runS = '';
+      };
+      for (let x = 0; x < COLS; x++) {
+        if (meta[y][x] === runT) runS += grid[y][x];
+        else { flush(); runT = meta[y][x]; runS = grid[y][x]; }
+      }
+      flush();
+      screen += `${line}\n`;
+    }
+
+    /* LIVES is gone, because there is nothing to count down. SHIELD says
+       the same thing the three little ships used to say (you are fine)
+       without implying a budget that can run out. HITS is there so the
+       bombs still mean something. */
+    const hud = `
+      <span class="hud-label">SCORE</span> <span class="hud-val g-laser">${String(this.score).padStart(4, '0')}</span>
+      <span class="hud-label">SHIELD</span> <span class="hud-val g-player">${escapeHtml('∞')}</span>
+      <span class="hud-label">WAVE</span>  <span class="hud-val">${this.wave}</span>
+      <span class="hud-label">HITS</span>  <span class="hud-val">${this.hits}</span>
+      <span style="margin-left:auto" class="hud-label">conduction · space-invaders.exe</span>
+    `;
+
+    let footer;
+    if (this.paused) {
+      footer = '<span class="warn">-- paused -- press [P] to resume</span>';
+    } else if (this.graceTicks > 0) {
+      footer = '<span class="ok">-- READY --</span> <span class="cmt">defend the cookies. fire orange lasers at the cobalt UFOs.</span>';
+    } else {
+      footer = '<span class="cmt"># [← →] move &nbsp; [space] fire orange laser &nbsp; [P] pause &nbsp; [ESC] exit</span>';
+    }
+
+    this.onFrame({screen, hud, footer});
+  }
+}
+
+export {COLS, ROWS, GAME_ID, GAME_END_EVENT};

package/src/components/CookieCli/spaceInvaders.test.js

@@ -0,0 +1,112 @@
+/**
+ * The one rule this game has: you cannot lose it.
+ *
+ * It is an easter egg inside a cookie banner. Someone opened that banner to
+ * set a preference, so ending their game with GAME OVER is a worse outcome
+ * than letting them play forever. Both original death paths are covered
+ * here, because they were separate: bombs draining lives, and the swarm
+ * reaching the floor, which ended the run outright no matter how many lives
+ * were left.
+ *
+ * These assertions were checked against the previous engine before being
+ * committed: nine of the ten fail on it. A test for the absence of
+ * behaviour is worth very little until you have watched it fail.
+ *
+ * Runs under `npm test` (node --test) with no DOM: the engine guards its
+ * window access, and stop() lets the tick be driven by hand instead of a
+ * timer.
+ */
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import SpaceInvaders, {ROWS} from './spaceInvaders.js';
+
+function newGame() {
+  const frames = [];
+  const game = new SpaceInvaders({
+    onFrame: (f) => frames.push(f),
+    onExit: () => assert.fail('the game exited on its own'),
+  });
+  game.stop(); // drive tick() manually
+  return {game, frames};
+}
+
+test('bombs landing on the player never end the run', () => {
+  const {game} = newGame();
+  game.graceTicks = 0;
+  /* Drop each bomb one row above the player and tick twice, which is how a
+     bomb actually arrives: it descends every other tick, and the collision
+     check runs in the same tick as the move. Injecting one directly onto
+     the player's row instead tests nothing, because on a move tick it
+     advances to ROWS and is filtered as off-screen before the check. */
+  for (let i = 0; i < 6; i++) {
+    game.bombs.push({x: game.player.x + 1, y: ROWS - 2});
+    game.tick();
+    game.tick();
+  }
+  assert.ok(game.hits >= 6, `all six bombs should register a hit, got ${game.hits}`);
+  assert.equal(game.lives, undefined, 'there should be no lives counter to run out');
+  assert.equal(game.gameOver, undefined, 'there should be no game-over flag');
+});
+
+test('the swarm reaching the floor rolls into a new wave', () => {
+  const {game} = newGame();
+  const before = game.wave;
+  game.ufos.forEach((u) => { u.alive = true; u.y = ROWS - 1; });
+  game.tick();
+  assert.equal(game.wave, before + 1, 'the wave should advance');
+  assert.equal(game.ufos.filter((u) => u.alive).length, 18, 'a fresh swarm should spawn');
+  assert.equal(game.landed, 1, 'the landing should be counted');
+});
+
+test('clearing a wave advances it', () => {
+  const {game} = newGame();
+  const before = game.wave;
+  game.ufos.forEach((u) => { u.alive = false; u.exploding = 0; });
+  game.tick();
+  assert.equal(game.wave, before + 1);
+  assert.equal(game.cleared, 1);
+});
+
+test('no frame ever renders a GAME OVER', () => {
+  const {game, frames} = newGame();
+  game.graceTicks = 0;
+  for (let i = 0; i < 40; i++) {
+    game.bombs.push({x: game.player.x + 1, y: ROWS - 1});
+    game.tick();
+  }
+  const bad = frames.filter((f) => /GAME OVER|YOU WIN/i.test(f.footer));
+  assert.equal(bad.length, 0, 'the footer should never announce an ending');
+  assert.ok(frames.at(-1).hud.includes('∞'), 'the HUD should show an infinite shield');
+});
+
+/* GameModal records discovery from `connext:gameend`. That used to fire on
+   game over, so removing game over would have silently stopped the game
+   from ever being marked as found. It now fires on the first wave cleared,
+   and this is the test that keeps it honest. */
+test('clearing the first wave still reports the game as found', () => {
+  const events = [];
+  const priorWindow = globalThis.window;
+  globalThis.window = {
+    addEventListener() {}, removeEventListener() {},
+    dispatchEvent: (e) => { events.push(e); return true; },
+  };
+  globalThis.CustomEvent = globalThis.CustomEvent || class { constructor(type, init) { this.type = type; this.detail = init?.detail; } };
+  try {
+    const game = new SpaceInvaders({onFrame() {}, onExit() {}});
+    game.stop();
+    game.ufos.forEach((u) => { u.alive = false; u.exploding = 0; });
+    game.tick();
+    const end = events.filter((e) => e.type === 'connext:gameend');
+    assert.equal(end.length, 1, 'exactly one gameend should fire');
+    assert.equal(end[0].detail.id, 'invaders');
+    assert.equal(end[0].detail.won, true);
+
+    // and only once per run
+    game.ufos.forEach((u) => { u.alive = false; u.exploding = 0; });
+    game.tick();
+    assert.equal(events.filter((e) => e.type === 'connext:gameend').length, 1);
+  } finally {
+    globalThis.window = priorWindow;
+  }
+});

package/src/data/app-glyphs.json

@@ -19,6 +19,10 @@
     "inner": "<rect x=\"5\" y=\"11\" width=\"14\" height=\"10\" rx=\"2\" fill=\"currentColor\"/><path d=\"M8,11V7a4,4,0,0,1,8,0v4\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\"/>",
     "viewBox": "0 0 24 24"
   },
+  "hermiq": {
+    "inner": "<path fill=\"currentColor\" d=\"M19,1L17.74,3.75L15,5L17.74,6.26L19,9L20.25,6.26L23,5L20.25,3.75M9,4L6.5,9.5L1,12L6.5,14.5L9,20L11.5,14.5L17,12L11.5,9.5M19,15L17.74,17.74L15,19L17.74,20.25L19,23L20.25,20.25L23,19L20.25,17.74\"/>",
+    "viewBox": "0 0 24 24"
+  },
   "financeq": {
     "inner": "<path fill=\"currentColor\" d=\"M6,16.5L3,19.44V11H6M11,14.66L9.43,13.32L8,14.64V7H11M16,13L13,16V3H16M18.81,12.81L17,11H22V16L20.21,14.21L13,21.36L9.53,18.34L5.75,22H3L9.47,15.66L13,18.64\"/>",
     "viewBox": "0 0 24 24"