@conduction/docusaurus-preset 3.37.0 → 3.39.0

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

@@ -0,0 +1,163 @@
+/**
+ * engine.test.js — the deadline-defender rules.
+ *
+ * Two things are worth protecting. A case that runs out of time costs
+ * the same as one sent to the wrong step, because in a real queue both
+ * end the same way. And every situation the game deals has exactly one
+ * correct lane, or the player is being asked to guess.
+ */
+
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  createGame, step, route, clockMs, remaining, summarise,
+  SITUATIONS, LANES, INTAKE, REVIEW, DECISION, DEFAULTS,
+} = require('../engine.js');
+
+/** Play correctly for a while, returning the state and what was dealt. */
+function playPerfect(seed, cases, startAt = 0) {
+  let s = createGame({seed, now: startAt});
+  let t = startAt;
+  const dealt = [];
+  for (let i = 0; i < cases; i++) {
+    s = step(s, t);
+    if (!s.current) { t += 60; i--; continue; }
+    dealt.push(s.current);
+    t += 200;
+    s = route(s, s.current.needs, t);
+    t += DEFAULTS.gapMs + 20;
+  }
+  return {state: s, dealt};
+}
+
+test('every situation the game can deal has exactly one correct lane', () => {
+  for (const sit of SITUATIONS) {
+    assert.ok(LANES.includes(sit.needs), `${sit.key} routes nowhere`);
+  }
+  /* All three lanes have to be reachable, or one button is decoration. */
+  for (const lane of LANES) {
+    assert.ok(SITUATIONS.some((s) => s.needs === lane), `nothing ever goes to ${lane}`);
+  }
+});
+
+test('a case is dealt, and it carries a number and a deadline', () => {
+  let s = step(createGame({seed: 2, now: 0}), 0);
+  assert.ok(s.current, 'no case arrived');
+  assert.match(s.current.id, /^\d{4}-\d{3}$/);
+  assert.equal(s.current.expiresAt - s.current.bornAt, DEFAULTS.clockStartMs);
+});
+
+test('routing correctly scores, and a streak pays more each time', () => {
+  const {state} = playPerfect(4, 2);
+  assert.equal(state.handled, 2);
+  assert.equal(state.score, DEFAULTS.pointsPerCase * 2 + DEFAULTS.comboBonus);
+  assert.equal(state.lives, DEFAULTS.lives);
+  assert.equal(state.bestCombo, 2);
+});
+
+test('the wrong step costs a life and breaks the streak', () => {
+  let s = step(createGame({seed: 6, now: 0}), 0);
+  const wrong = LANES.find((l) => l !== s.current.needs);
+  const before = s.score;
+  s = route(s, wrong, 100);
+  assert.equal(s.lives, DEFAULTS.lives - 1);
+  assert.equal(s.score, before, 'a misroute must not also pay');
+  assert.equal(s.misrouted, 1);
+  assert.equal(s.combo, 0);
+  assert.equal(s.current, null, 'the misrouted case stayed on the desk');
+});
+
+test('letting the deadline run out costs the same as misrouting it', () => {
+  let s = step(createGame({seed: 6, now: 0}), 0);
+  s = step(s, DEFAULTS.clockStartMs + 1);
+  assert.equal(s.lives, DEFAULTS.lives - 1);
+  assert.equal(s.missed, 1);
+  assert.equal(s.current, null);
+});
+
+test('the next case waits for the gap, then arrives', () => {
+  let s = step(createGame({seed: 8, now: 0}), 0);
+  s = route(s, s.current.needs, 100);
+  assert.equal(s.current, null);
+  s = step(s, 100 + DEFAULTS.gapMs - 50);
+  assert.equal(s.current, null, 'the queue skipped its own gap');
+  s = step(s, 100 + DEFAULTS.gapMs + 10);
+  assert.ok(s.current, 'the queue stalled');
+});
+
+test('three mistakes end the run, and nothing scores after it', () => {
+  let s = createGame({seed: 9, now: 0});
+  let t = 0;
+  for (let i = 0; i < 3; i++) {
+    s = step(s, t);
+    const wrong = LANES.find((l) => l !== s.current.needs);
+    t += 100;
+    s = route(s, wrong, t);
+    t += DEFAULTS.gapMs + 20;
+  }
+  assert.equal(s.over, true);
+  assert.equal(s.lives, 0);
+
+  const frozen = {...s};
+  assert.equal(step(frozen, t + 5000).score, s.score);
+  assert.equal(route(frozen, INTAKE, t + 10).score, s.score);
+});
+
+test('an unknown lane is ignored rather than counted as a mistake', () => {
+  let s = step(createGame({seed: 3, now: 0}), 0);
+  const after = route(s, 'archive', 50);
+  assert.equal(after.lives, s.lives);
+  assert.equal(after.current, s.current);
+});
+
+test('routing an empty desk does nothing', () => {
+  const s = createGame({seed: 3, now: 0});
+  assert.equal(route(s, INTAKE, 10).lives, s.lives);
+});
+
+test('the deadline tightens with the score, down to a readable floor', () => {
+  const fresh = createGame({seed: 1});
+  assert.equal(clockMs(fresh), DEFAULTS.clockStartMs);
+  assert.ok(clockMs({...fresh, score: 200}) < DEFAULTS.clockStartMs);
+  assert.equal(clockMs({...fresh, score: 5000}), DEFAULTS.clockFloorMs);
+});
+
+test('the countdown runs from full to empty, and never past either end', () => {
+  let s = step(createGame({seed: 5, now: 0}), 0);
+  assert.equal(remaining(s, 0), 1);
+  assert.ok(Math.abs(remaining(s, DEFAULTS.clockStartMs / 2) - 0.5) < 0.01);
+  assert.equal(remaining(s, DEFAULTS.clockStartMs), 0);
+  assert.equal(remaining(s, DEFAULTS.clockStartMs * 5), 0, 'the bar went negative');
+  assert.equal(remaining({...s, current: null}, 0), 0);
+});
+
+test('a perfect player is never punished by the clock', () => {
+  const {state} = playPerfect(40, 40);
+  assert.equal(state.lives, DEFAULTS.lives);
+  assert.equal(state.over, false);
+  assert.ok(state.score > 0);
+});
+
+test('the deal is varied, and all three lanes turn up in a real run', () => {
+  const {dealt} = playPerfect(13, 30);
+  const lanes = new Set(dealt.map((c) => c.needs));
+  assert.deepEqual([...lanes].sort(), [DECISION, INTAKE, REVIEW].sort());
+  assert.ok(new Set(dealt.map((c) => c.key)).size >= 4, 'the same few cases keep coming back');
+});
+
+test('the same seed deals the same cases, a different one does not', () => {
+  const a = playPerfect(21, 6).dealt.map((c) => c.key).join(',');
+  const b = playPerfect(21, 6).dealt.map((c) => c.key).join(',');
+  const c = playPerfect(22, 6).dealt.map((c) => c.key).join(',');
+  assert.equal(a, b);
+  assert.notEqual(a, c);
+});
+
+test('the summary reads as a sentence in both locales', () => {
+  const s = {handled: 9, bestCombo: 4};
+  assert.match(summarise(s, 'en'), /9 cases on time · streak 4/);
+  assert.match(summarise(s, 'nl'), /9 zaken op tijd · reeks 4/);
+});

package/src/components/DeadlineDefender/engine.js

@@ -0,0 +1,188 @@
+/**
+ * Deadline defender — the rules, with no DOM and no clock of its own.
+ *
+ * Dossiq's game. A case arrives with a legal deadline already running,
+ * and the only question is which step it goes to next. Send it to the
+ * right one before the clock runs out. Send it to the wrong one and
+ * you have moved a case backwards in front of a resident who can see
+ * their own file.
+ *
+ * One case at a time, on purpose: the stamp-rush board is six things
+ * at once, and two games with the same shape would be one game twice.
+ * Here the pressure is the clock on a single decision, which is the
+ * pressure the app is about.
+ *
+ * Time and randomness are injected. The component owns the clock.
+ */
+
+export const INTAKE = 'intake';
+export const REVIEW = 'review';
+export const DECISION = 'decision';
+export const LANES = [INTAKE, REVIEW, DECISION];
+
+/* Each case is one of these situations. `needs` is the only correct
+   lane; the text is what the player reads to work that out, which is
+   why every situation reads as a sentence from a real case file. */
+export const SITUATIONS = [
+  {key: 'permitReceived', needs: INTAKE},
+  {key: 'objectionReceived', needs: INTAKE},
+  {key: 'complaintReceived', needs: INTAKE},
+  {key: 'documentsComplete', needs: REVIEW},
+  {key: 'siteVisitDone', needs: REVIEW},
+  {key: 'adviceReturned', needs: REVIEW},
+  {key: 'assessmentDone', needs: DECISION},
+  {key: 'objectionAssessed', needs: DECISION},
+  {key: 'enforcementReady', needs: DECISION},
+];
+
+export const DEFAULTS = {
+  lives: 3,
+  /* A case has to be read before it can be routed, so the first ones
+     get three seconds. The floor is the point where a fast reader can
+     still finish the sentence. */
+  clockStartMs: 3200,
+  clockFloorMs: 1300,
+  rampPerPoint: 3,
+  /* The beat between finishing one case and the next arriving. Long
+     enough to see what happened, short enough to keep the queue
+     breathing down your neck. */
+  gapMs: 320,
+  pointsPerCase: 10,
+  comboBonus: 2,
+};
+
+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;
+  };
+}
+
+export function createGame({seed = Date.now(), now = 0, config = {}} = {}) {
+  const cfg = {...DEFAULTS, ...config};
+  const state = {
+    cfg,
+    random: mulberry32(seed),
+    current: null,
+    nextAt: now,
+    score: 0,
+    lives: cfg.lives,
+    combo: 0,
+    bestCombo: 0,
+    handled: 0,
+    missed: 0,
+    misrouted: 0,
+    last: null,
+    over: false,
+  };
+  return state;
+}
+
+/** How long the current difficulty gives you to read and route. */
+export function clockMs(state) {
+  const {cfg, score} = state;
+  return Math.max(cfg.clockFloorMs, cfg.clockStartMs - score * cfg.rampPerPoint);
+}
+
+function loseLife(state, reason) {
+  const lives = state.lives - 1;
+  return {
+    ...state,
+    lives,
+    combo: 0,
+    last: {result: reason, at: state.nextAt},
+    over: lives <= 0,
+  };
+}
+
+function deal(state, now) {
+  const pick = SITUATIONS[Math.floor(state.random() * SITUATIONS.length)];
+  /* The case number is cosmetic, but a case without one does not read
+     as a case. */
+  const year = 2026;
+  const seq = 100 + Math.floor(state.random() * 900);
+  return {
+    ...state,
+    current: {
+      ...pick,
+      id: `${year}-${seq}`,
+      bornAt: now,
+      expiresAt: now + clockMs(state),
+    },
+  };
+}
+
+/**
+ * Advance to `now`: let an unanswered case run out of time, then deal
+ * the next one once the gap has passed.
+ */
+export function step(state, now) {
+  if (state.over) return state;
+  let next = state;
+
+  if (next.current && now >= next.current.expiresAt) {
+    next = {...loseLife(next, 'missed'), current: null, missed: next.missed + 1, nextAt: now + next.cfg.gapMs};
+    if (next.over) return next;
+  }
+
+  if (!next.current && now >= next.nextAt) {
+    next = deal(next, now);
+  }
+
+  return next;
+}
+
+/**
+ * Route the case on the desk to `lane`.
+ *
+ * Routing to the wrong step costs a life. There is no partial credit:
+ * a case in the wrong queue is not half-handled, it is lost until
+ * somebody notices.
+ */
+export function route(state, lane, now) {
+  if (state.over || !state.current) return state;
+  if (!LANES.includes(lane)) return state;
+
+  const correct = state.current.needs === lane;
+  if (!correct) {
+    return {
+      ...loseLife(state, 'misrouted'),
+      current: null,
+      misrouted: state.misrouted + 1,
+      nextAt: now + state.cfg.gapMs,
+    };
+  }
+
+  const combo = state.combo + 1;
+  const gained = state.cfg.pointsPerCase + (combo - 1) * state.cfg.comboBonus;
+  return {
+    ...state,
+    current: null,
+    nextAt: now + state.cfg.gapMs,
+    score: state.score + gained,
+    combo,
+    bestCombo: Math.max(state.bestCombo, combo),
+    handled: state.handled + 1,
+    last: {result: 'handled', points: gained, at: now},
+  };
+}
+
+/** How much of the deadline is left, 1 to 0, for the countdown bar. */
+export function remaining(state, now) {
+  if (!state.current) return 0;
+  const total = state.current.expiresAt - state.current.bornAt;
+  if (total <= 0) return 0;
+  const left = (state.current.expiresAt - now) / total;
+  return Math.min(1, Math.max(0, left));
+}
+
+/** 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.handled)} zaken op tijd · reeks ${n(state.bestCombo)}`
+    : `${n(state.handled)} cases on time · streak ${n(state.bestCombo)}`;
+}

package/src/components/DetailHero/DetailHero.jsx

@@ -48,6 +48,10 @@
  * normally holds just the primary + secondary pair; a non-GitHub
  * tertiary still renders for compatibility.
  *
+ * The counter is hidden below MIN_DISPLAYED_DOWNLOADS (see
+ * ../../data/app-downloads), so a newly published app shows the
+ * GitHub chip on its own rather than a number that undersells it.
+ *
  * `background="cobalt"` paints the hero in a full-bleed cobalt panel
  * with white type — the product-page identity used on the
  * {slug}.conduction.nl landings. Default (undefined) keeps the
@@ -60,7 +64,7 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import HexBullet from '../primitives/HexBullet';
 import Button from '../primitives/Button';
 import {deriveStability} from '../../theme/brand.jsx';
-import {downloadsForApp, formatDownloads} from '../../data/app-downloads';
+import {downloadsForApp, formatDownloads, showDownloads} from '../../data/app-downloads';
 import {APPS_REGISTRY, applicationCategoryFor} from '../../data/apps-registry';
 import AppGlyph, {hasAppGlyph} from '../AppGlyph/AppGlyph.jsx';
 import styles from './DetailHero.module.css';
@@ -98,6 +102,9 @@ export default function DetailHero({
   repoHref,
 }) {
   const dlCount = downloads != null ? downloads : (appId ? downloadsForApp(appId) : 0);
+  /* A count under MIN_DISPLAYED_DOWNLOADS renders nowhere: not as the
+     chip, not in the JSON-LD. See showDownloads() for why. */
+  const showDlCount = showDownloads(dlCount);
   /* GitHub repo link for the badge row. Priority: explicit `repoHref`
      prop → a GitHub-pointing tertiaryCta (the old "View on GitHub"
      ghost button, which this hero now renders as a meta-row chip
@@ -187,7 +194,7 @@ export default function DetailHero({
     };
     if (taglineText) schema.description = taglineText;
     if (resolvedVersion) schema.softwareVersion = resolvedVersion.replace(/^v/, '');
-    if (dlCount > 0) {
+    if (showDlCount) {
       /* Surface install count as InteractionCounter rather than
          aggregateRating; downloads are not reviews. */
       schema.interactionStatistic = {
@@ -266,7 +273,7 @@ export default function DetailHero({
 
       <div className={styles.headInner}>
         <div className={styles.copy}>
-          {(resolvedStatus || resolvedVersion || locales || dlCount > 0 || resolvedRepoHref) && (
+          {(resolvedStatus || resolvedVersion || locales || showDlCount || resolvedRepoHref) && (
             <div className={styles.badgeRow}>
               {resolvedStatus && (
                 <span className={styles.badge}>
@@ -276,7 +283,7 @@ export default function DetailHero({
               )}
               {resolvedVersion && <span className={[styles.badge, styles.versionBadge].join(' ')}>{resolvedVersion}</span>}
               {locales && <span className={[styles.badge, styles.versionBadge].join(' ')}>{locales}</span>}
-              {dlCount > 0 && (() => {
+              {showDlCount && (() => {
                 /* The downloads counter links to the repo when one
                    resolves; a plain chip otherwise. */
                 const DlTag = resolvedRepoHref ? 'a' : 'span';

package/src/components/DetailHero/__tests__/DetailHero.downloads.test.js

@@ -0,0 +1,160 @@
+/**
+ * DetailHero.downloads.test.js — the per-app download counter only
+ * appears once an app has real traction.
+ *
+ * A freshly published app sits on a handful of downloads for weeks,
+ * and "5 downloads" beside the title argues against the app it is
+ * meant to recommend. The counter is therefore gated on
+ * MIN_DISPLAYED_DOWNLOADS, and the gate covers the schema.org
+ * InteractionCounter as well: a number the page hides must not reach
+ * search results through the structured data.
+ *
+ * Renders the real <DetailHero> JSX to static markup with the same
+ * esbuild-bundle-then-renderToStaticMarkup technique the other render
+ * tests use (AppMock, AiDisclosure). Docusaurus-only modules are
+ * stubbed, since this runs outside a Docusaurus build.
+ */
+
+'use strict';
+
+const test = require('node:test');
+const {before, after} = test;
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const {build} = require('esbuild');
+const React = require('react');
+const {renderToStaticMarkup} = require('react-dom/server');
+
+const {MIN_DISPLAYED_DOWNLOADS} = require('../../../data/app-downloads.js');
+
+const COMPONENT = path.resolve(__dirname, '..', 'DetailHero.jsx');
+const PRESET_ROOT = path.resolve(__dirname, '..', '..', '..', '..');
+const SCRATCH = path.join(PRESET_ROOT, '.tmp-detail-hero-test');
+
+const cssModuleStub = {
+  name: 'css-module-stub',
+  setup(b) {
+    b.onResolve({filter: /\.module\.css$/}, (args) => ({path: args.path, namespace: 'css-stub'}));
+    b.onLoad({filter: /.*/, namespace: 'css-stub'}, () => ({
+      contents: 'export default new Proxy({}, {get: (_, p) => p});',
+      loader: 'js',
+    }));
+  },
+};
+
+/* <Head> renders its children inline here, which is what lets the test
+   read the JSON-LD out of the same markup string. */
+const docusaurusStub = {
+  name: 'docusaurus-stub',
+  setup(b) {
+    b.onResolve({filter: /^@docusaurus\/Head$/}, () => ({path: 'docusaurus-head', namespace: 'docusaurus-stub'}));
+    b.onResolve({filter: /^@docusaurus\/useDocusaurusContext$/}, () => ({path: 'docusaurus-context', namespace: 'docusaurus-stub'}));
+    b.onResolve({filter: /^@docusaurus\/Link$/}, () => ({path: 'docusaurus-link', namespace: 'docusaurus-stub'}));
+    b.onResolve({filter: /^@docusaurus\/useBaseUrl$/}, () => ({path: 'docusaurus-base-url', namespace: 'docusaurus-stub'}));
+    b.onResolve({filter: /^@docusaurus\/Translate$/}, () => ({path: 'docusaurus-translate', namespace: 'docusaurus-stub'}));
+    b.onLoad({filter: /^docusaurus-head$/, namespace: 'docusaurus-stub'}, () => ({
+      contents: `import React from 'react';
+        export default function Head({children}) { return React.createElement(React.Fragment, null, children); }`,
+      loader: 'jsx',
+    }));
+    b.onLoad({filter: /^docusaurus-context$/, namespace: 'docusaurus-stub'}, () => ({
+      contents: `export default function useDocusaurusContext() {
+        return {i18n: {currentLocale: 'en'}, siteConfig: {url: 'https://conduction.nl', baseUrl: '/'}};
+      }`,
+      loader: 'js',
+    }));
+    b.onLoad({filter: /^docusaurus-link$/, namespace: 'docusaurus-stub'}, () => ({
+      contents: `import React from 'react';
+        export default function Link({to, href, children, ...rest}) {
+          return React.createElement('a', {href: to || href, ...rest}, children);
+        }`,
+      loader: 'jsx',
+    }));
+    b.onLoad({filter: /^docusaurus-base-url$/, namespace: 'docusaurus-stub'}, () => ({
+      contents: `export default function useBaseUrl(p) { return p; }`,
+      loader: 'js',
+    }));
+    b.onLoad({filter: /^docusaurus-translate$/, namespace: 'docusaurus-stub'}, () => ({
+      contents: `import React from 'react';
+        export function translate(o, v) { return o.message; }
+        export default function Translate({children}) { return React.createElement(React.Fragment, null, children); }`,
+      loader: 'jsx',
+    }));
+  },
+};
+
+let DetailHero;
+
+before(async () => {
+  await fs.mkdir(SCRATCH, {recursive: true});
+  const tmpDir = await fs.mkdtemp(path.join(SCRATCH, 'run-'));
+  const outFile = path.join(tmpDir, 'bundle.cjs');
+  await build({
+    entryPoints: [COMPONENT],
+    outfile: outFile,
+    bundle: true,
+    format: 'cjs',
+    jsx: 'automatic',
+    jsxImportSource: 'react',
+    tsconfigRaw: {compilerOptions: {jsx: 'react-jsx', jsxImportSource: 'react'}},
+    platform: 'node',
+    external: ['react'],
+    plugins: [cssModuleStub, docusaurusStub],
+    logLevel: 'warning',
+  });
+  delete require.cache[require.resolve(outFile)];
+  DetailHero = require(outFile).default;
+});
+
+after(async () => {
+  await fs.rm(SCRATCH, {recursive: true, force: true});
+});
+
+function render(props) {
+  return renderToStaticMarkup(
+    React.createElement(DetailHero, {title: 'Buildiq', appId: 'openbuild', ...props}),
+  );
+}
+
+/* The counter and the "View on GitHub" chip share the downloadsBadge
+   class, so the counter is identified by its own data attribute and by
+   the word it prints. Asserting on the shared class would fail on a
+   page that correctly shows only the GitHub chip. */
+test('a count under the threshold renders no counter at all', () => {
+  const html = render({downloads: MIN_DISPLAYED_DOWNLOADS - 1});
+  assert.doesNotMatch(html, /downloads</, 'the counter text is on the page');
+  assert.doesNotMatch(html, /data-app-downloads/, 'the counter element is on the page');
+  assert.match(html, /View on GitHub/, 'the GitHub chip went down with the counter');
+});
+
+test('zero downloads renders no counter', () => {
+  assert.doesNotMatch(render({downloads: 0}), /data-app-downloads/);
+});
+
+test('a count on the threshold renders the counter, formatted', () => {
+  const html = render({downloads: MIN_DISPLAYED_DOWNLOADS});
+  assert.match(html, /1,000 downloads/);
+  assert.match(html, /data-app-downloads/);
+});
+
+test('a large count keeps rendering', () => {
+  assert.match(render({downloads: 9079}), /9,079 downloads/);
+});
+
+test('the structured data follows the chip, so a hidden number is not published', () => {
+  const low = render({downloads: MIN_DISPLAYED_DOWNLOADS - 1});
+  assert.doesNotMatch(low, /InteractionCounter/, 'JSON-LD advertises a count the page hides');
+
+  const high = render({downloads: MIN_DISPLAYED_DOWNLOADS});
+  assert.match(high, /InteractionCounter/);
+  assert.match(high, /"userInteractionCount":1000/);
+});
+
+test('the rest of the badge row survives a suppressed counter', () => {
+  /* The row itself is conditional, so hiding the counter must not take
+     the version badge or the GitHub chip down with it. */
+  const html = render({downloads: 5, version: 'v0.10'});
+  assert.match(html, /v0\.10/);
+  assert.match(html, /View on GitHub/);
+});

package/src/components/FeaturedCard/FeaturedCard.jsx

@@ -24,6 +24,11 @@
  *     date="2026-05-05"
  *     thumbnail={{ icon: <svg>...</svg> }}
  *   />
+ *
+ * `visual={<AppMock app="openregister" />}` puts a node in the
+ * right-hand column instead of the hex thumbnail, for a card whose
+ * subject is better shown than symbolised. The satellite hexes stand
+ * down when it does.
  */
 
 import React from 'react';
@@ -52,6 +57,7 @@ export default function FeaturedCard({
   dateLabel,
   locale,
   thumbnail,
+  visual,
   accent = 'orange',
   contentType,
   durationMinutes,
@@ -98,6 +104,11 @@ export default function FeaturedCard({
   const metaBits = [readWatch, moduleLabel, moduleSlug ? (moduleTitle || moduleSlug) : null]
     .filter(Boolean);
   const Tag = href ? 'a' : 'div';
+  /* `visual` replaces the hex thumbnail with an arbitrary node (an
+     AppMock, a ThemeSeamMock, a diagram). The satellite hexes are
+     dropped with it: they frame a hex, and they read as clutter
+     around a rectangular frame. */
+  const hasVisual = Boolean(visual);
   const composed = [styles.card, className].filter(Boolean).join(' ');
   const thumbProps = thumbnail || {};
 
@@ -150,7 +161,8 @@ export default function FeaturedCard({
         )}
       </div>
 
-      <div className={styles.visual} aria-hidden="true">
+      <div className={[styles.visual, hasVisual && styles.visualNode].filter(Boolean).join(' ')} aria-hidden="true">
+        {hasVisual ? visual : (<>
         {thumbProps.src
           ? <HexThumbnail size="xl" tone="cobalt" src={thumbProps.src} alt={thumbProps.alt} />
           : <HexThumbnail size="xl" tone={thumbProps.tone || 'cobalt'}>{thumbProps.icon}</HexThumbnail>}
@@ -161,6 +173,7 @@ export default function FeaturedCard({
           styles.s3,
           accent === 'orange' ? styles.s3Orange : styles.s3Cobalt,
         ].join(' ')} />
+        </>)}
       </div>
     </Tag>
   );

package/src/components/FeaturedCard/FeaturedCard.module.css

@@ -53,6 +53,11 @@
   line-height: 1.55;
   margin: 0 0 var(--space-6);
   max-width: 50ch;
+  /* `pre-line` keeps the paragraph breaks a summary written as a YAML
+     block scalar carries, while still collapsing runs of spaces. A
+     one-line summary is unaffected: with no newlines in the source
+     there is nothing to preserve. */
+  white-space: pre-line;
 }
 
 .metaBits {
@@ -109,6 +114,11 @@
   min-height: 300px;
 }
 
+/* A passed-in visual gets the column to itself: no hex to frame, and
+   the node brings its own aspect ratio. */
+.visualNode { display: block; min-height: 0; }
+.visualNode > * { width: 100%; }
+
 .satellite {
   position: absolute;
   width: 64px;