app/blogs/
  understanding-psychometric-tests/page.tsx
  what-is-a-good-psychometric-test-score/page.tsx
  ...46 more

I needed all 48 as markdown. My first instinct was to parse the JSX, and that instinct was wrong in a way I think is worth writing down.

The content is not in the children

Plain prose parses fine. <p>Some text</p> has a text node in it. But a lot of our article content is passed to shared components as props:

<LookupRows
  rows={[
    { terms: 'Verify, Verify G+, OPQ32, TalentCentral', label: 'SHL', href: '/games/shl' },
    { terms: 'scales, smartPredict, gridChallenge, cut-e', label: 'Aon', href: '/games/aon' },
  ]}
/>

There is no text node anywhere in that subtree. There is an array of object literals whose meaning is entirely defined by a component in another file. To turn it into markdown from an AST, I would have to know that LookupRows renders terms as the visible lead and label as a small uppercase tag underneath, and that the whole card is a link to href.

Then do the same for CardGrid, Callout, SpecList, SectionIndex, NumberedSteps, SplitCompare, DoDont, PullQuote and TimeBudget. That is reimplementing the render, by hand, in a second renderer that will drift from the first one the day someone changes a component.

The browser has already done it

There is a renderer that knows exactly how every one of those components turns into content, and it is the one in production. So: open the published page, walk the DOM, emit markdown.

const page = await task.newPage();
await page.goto('https://cogniprep.app/blogs/' + slug);
await page.waitForSelector('.blog-content');
const { md } = await page.evaluate(converter);

Semantic tags are the easy half. H2 to ##, UL to a list, TABLE to a pipe table, A to [text](href) with relative hrefs made absolute.

The hard half is that styled components produce div soup: a grid of divs, each holding two or three more divs of bare text, with no roles and no headings. There is real structure there, but it is expressed in class names.

So the fallback branch reads the classes:

const walk = (n) => {
  // ...
  lines.push({
    t: inline(n).trim(),
    bold: /font-semibold|font-bold/.test(String(n.className)),
    upper: /uppercase/.test(String(n.className)),
  });
};

font-semibold means this line is the card's title. uppercase means it is the little eyebrow above it. Everything else is body. An <a> wrapping the whole card means the title should be a link. That reconstructs - **Percentile** (Most common in the UK): The percentage of the norm group you scored above. out of three anonymous divs.

This is a heuristic and it is coupled to our design system. I am fine with that, and I will come back to why at the end.

The part that actually matters

Every one of those branches is a chance to silently drop content. A div shape you did not anticipate falls through to a branch that returns '', and you get a clean-looking markdown file with a paragraph missing from the middle. You would never notice across 48 files.

So the converter returns a coverage diff along with the output:

const norm = (s) => s.toLowerCase().replace(/[^a-z0-9 ]+/g, ' ').split(/\s+/).filter(Boolean);
const mdWords = new Set(norm(markdown));
const missing = norm(container.innerText).filter((w) => !mdWords.has(w));
return { md: markdown, missing: [...new Set(missing)].slice(0, 25) };

Every word the browser renders should appear somewhere in the output. Print what did not. That is it, and it is the only reason I trust the result.

It earned its keep immediately. On the first run one file came back with a clean empty missing array and completely wrong output: I had the lookup rows inverted, emitting **SHL** -> [Verify, Verify G+, ...] when the source means the opposite. Word-level coverage cannot catch a transposition, because both words are present.

What it did catch was the second run:

what-is-a-good-psychometric-test-score | missing: ["01","02","03","04","05","06"]
does-practising-psychometric-tests-work | missing: ["1","2","3","4","5"]

Numbered eyebrows from a section index, dropped by a filter I wrote on purpose. Expected, and now visibly expected rather than invisibly gone.

Two things that cost me a run each

innerText applies text-transform, textContent does not. Our eyebrows are lowercase in the source and uppercased in CSS. Read them with innerText and your markdown SHOUTS. Read with textContent and you get the author's casing back. The coverage check has to use innerText on both sides, or every CSS-uppercased word shows up as missing.

innerText joins across inline boundaries without a space. A link at the end of a sentence produced libraryis in the diff, a word that exists in neither the page nor the output. Which is the argument against making the coverage check a hard assertion: it is a report you read, not a test you gate on. Two residual artifacts across 48 files is a fine result. A CI job failing on libraryis forever is not.

This is a script, not a pipeline

The tempting next step is to make this a proper export feature: a route, a cached artifact, maybe a CMS. It runs once. It lives in a scratch directory, it is about 120 lines, and when I need it again I would rather rewrite it against whatever the components look like then than maintain a DOM heuristic against a design system that is allowed to change.

The generalisable bit is not the script. It is the two rules:

• When content is defined by a renderer, read the renderer's output, not its input.
• Any lossy transform should tell you what it lost, in the same breath as it hands you the result.

The articles it was pointed at are at cogniprep.app/blogs, and the div soup in question is visible in any of them if you open the inspector on a card grid, for example on the one about test scores.

That is the failure mode of duplicated derived data. It does not error. It goes quiet.

Three copies of the same list

We had three places that needed to know every canonical URL on the site:

1. app/sitemap.ts, which Next.js turns into /sitemap.xml
2. app/api/indexnow/route.ts, a cron-triggered POST that tells Bing, Yandex, Seznam and Naver that things changed
3. scripts/submit-indexnow.ts, the manual version of the same thing

The first was maintained, because you look at your sitemap. The other two each kept their own hardcoded array, and both had drifted. Between them they were missing /tests, every /tests/<format> page, and /about.

Nobody introduced that bug. It accumulated, one "add the page, ship it" at a time, because adding a page to the site and adding it to a hand-written list in a script you run once a month are not the same motion.

Derive, do not copy

A Next.js sitemap.ts default export is just a function. There is nothing stopping you calling it:

import sitemap from '@/app/sitemap';

/**
 * Every canonical URL, read straight out of the sitemap so the two can never
 * disagree.
 */
export function getIndexNowUrls(): string[] {
  return sitemap().map((entry) => entry.url);
}

Both submitters now import that one function. Adding a page picks itself up with no extra wiring, and the class of bug is gone rather than fixed.

The sitemap derives too

Which only helps if the sitemap itself is not hand-maintained. Ours is a short list of genuinely singular pages, plus spreads over content registries:

...ALL_PROVIDERS.map((provider) => ({
  url: `${baseUrl}/games/${provider}`,
  lastModified: new Date('2026-08-09'),
  changeFrequency: 'weekly' as const,
  priority: 0.9,
})),
...TEST_TYPES.map((entry) => ({ url: `${baseUrl}/tests/${entry.slug}`, /* ... */ })),
...CHEATING_GUIDES.map((guide) => ({ url: `${baseUrl}/cheating/${guide.provider}`, /* ... */ })),
...INTERVIEW_GUIDES.map((guide) => ({ url: `${baseUrl}/interview/${guide.slug}`, /* ... */ })),

Same comment sits above each one, because it is the same reason every time: a page missing from the sitemap works fine and is simply never discovered.

Make the omission loud

The registry pattern has one hole, and it is the interesting part. If the registry is the source of truth, what stops someone adding a route folder and forgetting the registry entry?

You cannot solve this by discipline. You solve it by making the forgotten case break something visible. Our blog article pages do not carry their own title, date or category. They read them from the registry, by slug:

export default function Page() {
  return (
    <ArticleShell slug="understanding-psychometric-tests" width="wide">
      {/* body */}
    </ArticleShell>
  );
}

Forget the registry entry and the page does not quietly publish without a sitemap URL. It renders without a header, which you see the first time you open it. The loud failure and the silent one now have the same cause, so fixing the one you notice fixes the one you do not.

This is a general move and I reach for it constantly now: when a thing must be registered somewhere, make the registration also supply something the unregistered version visibly needs.

One more, for bundle reasons

There is a second module that looks redundant and is not:

// lib/blog/posts.ts
import { BLOG_POSTS } from './registry';

export const blogPostMeta = BLOG_POSTS.map(({ slug, date, lastModified }) => ({
  slug,
  date,
  lastModified,
}));

The sitemap and the IndexNow submitter need slugs and dates. They do not need every title, description, excerpt and tag array, and the registry is mostly prose. This narrow projection keeps the copy out of anything that only wants URLs. The RSS feed, which does want the copy, imports BLOG_POSTS directly.

What the fix is worth

Roughly nothing, on the day. The pages were already live and already in the sitemap, so Google had them; only the IndexNow engines were behind. The value is the next 50 pages, none of which anyone has to remember to add to three lists.

If you want to check your own, the test is cheap: get the URL list out of every place that has one and diff them. If you have more than one place, they have already drifted, and the diff will tell you by how much.

Ours are at cogniprep.app/sitemap.xml and cogniprep.app/feed.xml, both generated from the same registries as the blog index itself. Open the sitemap and the blog listing side by side; if they ever disagree, one of us has stopped deriving.

The fix is a two-column layout above lg. The interesting part was not the grid. It was the four things in our own stylesheet that quietly defeated it.

The shape of the thing

One component, used by 56 game files:

<GameSplitLayout
  stimulus={<MatrixGrid cells={item.cells} />}
  answers={<OptionList options={item.options} onPick={pick} />}
  action={<SubmitButton disabled={!picked} />}
  mobileWidthClassName="max-w-md sm:max-w-lg"
  desktopWidthClassName="lg:max-w-6xl"
  ratio="wide-stimulus"
/>

The constraint I set before writing a line of it: mobile must render byte-identical markup. Not "looks about the same". Identical. 56 screens is far too many to re-verify by eye on a phone, so every class the split adds is lg: prefixed, and below 1024px the component collapses to w-full <your widths> space-y-4 wrapping two plain divs. That is exactly what a flat sibling list produced before.

Which brings us to the first thing that fought back.

1. space-y-* puts margins on grid items

Tailwind v4 compiles space-y-4 to margin-block-end on every child but the last. Fine in a stack. In a grid, those children are grid items sitting in their own tracks, and the margin is still there, pushing the answers column a rem down inside its cell.

So the rhythm class has to be cancelled at the same breakpoint the grid appears:

className={cn(
  'w-full',
  mobileWidthClassName,
  spacingClassName,          // "space-y-4 lg:space-y-6", from the game
  'lg:grid lg:items-start lg:space-y-0',
  ...
)}

Note the order. lg:space-y-0 comes after spacingClassName because cn is tailwind-merge, and tailwind-merge resolves conflicts by last-wins, per variant. Put it first and the game's own lg:space-y-6 wins, and you get a mystery one-rem offset on exactly one column.

2. Grid items default to min-width: auto

This is the CSS spec behaviour that bites everyone once. A grid item will not shrink below its content's intrinsic minimum width. A wide data table or one long unbroken string will blow its track out past the container, and because our game shell is overflow-hidden, that overflow is clipped rather than scrollable. The content is just gone.

<div className={cn('min-w-0', spacingClassName, stimulusClassName)}>{stimulus}</div>

min-w-0 on both tracks, always, not only the one you think is wide.

3. position: sticky does nothing on a stretched grid item

Some games have a long stimulus and a short answer list, and pinning the answers while the stimulus scrolls past is the right call. The obvious implementation does not work:

stickyAnswers && 'lg:sticky lg:top-6'   // no effect

Grid items default to align-self: stretch, so the item is already as tall as its row. It has nowhere to stick. You need:

stickyAnswers && 'lg:sticky lg:top-6 lg:self-start'

The prop is also opt-in rather than default, for a reason worth stating: a sticky element taller than its scrollport pins at the top, and its own bottom becomes permanently unreachable. If the answers plus the submit button are not clearly shorter than the viewport, sticky turns a scrolling annoyance into an unanswerable question.

4. Tailwind's scanner reads source text, not runtime values

Three column ratios, chosen per game:

const RATIO_CLASSES: Record<GameSplitRatio, string> = {
  balanced: 'lg:grid-cols-2',
  'wide-stimulus': 'lg:grid-cols-[minmax(0,1.35fr)_minmax(320px,1fr)]',
  'wide-answers': 'lg:grid-cols-[minmax(0,1fr)_minmax(0,1.35fr)]',
};

Written out as complete literal strings. Tailwind generates CSS by scanning your source files for things that look like class names; it does not execute your code. lg:grid-cols-${cols} produces a class at runtime that has no CSS behind it, and you find out in production, on the one layout you did not open locally.

The stylesheet you forgot you wrote

The four above are general CSS. These two were ours, and they are the reason I now read globals.css before writing any layout in this codebase.

contain changes what fixed means. Our scroll container carries contain: layout style paint. Containment establishes a containing block for fixed-position descendants, so position: fixed inside a game resolves against that container rather than the viewport. A "fixed" bottom bar lands somewhere surprising. Use sticky.

A global !important that eats borders. There is an unlayered rule in our stylesheet:

[class*='bg-card'] {
  border: none !important;
}

Attribute-substring, deliberately, so that bg-card/90 is caught too. It also means anything with bg-card anywhere in its class attribute cannot have a border, including every <Card> component. If a column needs a visible edge, bg-muted/40 with border-border border, or an explicit bg-border h-px divider.

And one more: we hide every scrollbar in the app. So a nested overflow-auto region inside a game would scroll with no visible affordance at all. GameSplitLayout therefore adds no overflow-* and no fixed heights. The columns grow, and the one real scroll container in the shell scrolls, exactly as it did before.

Was it worth 85 files?

The diff was 85 files, +4521 / -3003. The honest answer is that about a third of that churn was mechanical and could have been a codemod if the games were more uniform, which they are not, because each one imitates a different real assessment with different item shapes.

What made it tractable was the byte-identical-mobile rule. It turned "re-check 56 screens on two form factors" into "re-check 56 screens on one", and it meant every regression I did find was a desktop regression, which is the one you can see on the machine you are working on.

You can resize any of the practice tests at cogniprep.app/games across 1024px and watch the split appear. The candidate-facing reason this matters, incidentally, is that most of these tests are timed per item, so a scroll between reading and answering is not a cosmetic cost.

const res = await fetch(`/game-questions/${bankId}.json`);

That is a relative fetch from the browser to a file in public/. Next.js copies public/ to the CDN and serves it to whoever asks. No session, no account, no rate limit. The directory held 102 JSON files, 3.9 MB of authored questions, and every answer key in the product.

The cache header made it worse, in the way that good cache headers usually do:

cache-control: public, max-age=31536000, immutable

public means shared caches may store it. immutable means do not even revalidate. The edge was told, correctly, to hand this to the entire internet for a year.

The ids were not a secret either

My first thought was that you would have to guess the filenames. You do not. The bank id is a string literal inside the game engine that loads it, so it ships in the JavaScript chunk for that game:

const questions = await loadQuestions('shl-numerical');

Download the chunk, grep for the strings, fetch 102 files. That is a loop, not an attack.

What moving it actually buys

The fix is a route. lib/games/questions/banks/ instead of public/game-questions/, and one handler in front of it:

// app/api/games/questions/[bankId]/route.ts
export const runtime = 'nodejs';
export const dynamic = 'force-dynamic';

export const GET = withApiHandler<{ bankId: string }>(
  async ({ params }) => {
    const { bankId } = await params;
    if (!isGameQuestionBankId(bankId)) {
      return apiError('Question bank not found', 404);
    }
    const json = await readQuestionBank(bankId);
    return new NextResponse(json, {
      headers: {
        'Content-Type': 'application/json',
        'Cache-Control': 'private, max-age=3600',
      },
    });
  },
  { rateLimit: 'default', errorMessage: 'Failed to load question bank' }
);

Here is the part I want to be honest about, because a lot of writing about this kind of change is not. This does not make the questions secret. A signed-in user is going to render those questions on their own screen. They can open their own network tab and read the response. Anything the browser can display, the browser can be made to dump.

What changed is who has to bother. Scraping the library used to cost an anonymous for loop. It now costs an account, it goes through the same rate limiter as everything else, and it is attributable in logs. That is a real difference in kind, and it is the whole return on the change.

Genuinely hiding the answer key from the person answering the question needs server-side grading: send the prompt, receive the choice, grade it on the server, never ship the key at all. We cannot do that yet, because the banks carry no stable per-question ids to grade against. That is a bigger piece of work, and pretending the route solved it would have been the easy lie.

A type union does not exist at runtime

The bank ids were a union type:

export type GameQuestionBankId = 'analysis' | 'balance' | 'order' | 'patterns' /* ...98 more */;

Which is worth exactly nothing to a route handler holding params.bankId. TypeScript erases it. So the union became an array, and the type is derived from the array:

export const GAME_QUESTION_BANK_IDS = ['analysis', 'balance', 'order', 'patterns' /* ... */] as const;

export type GameQuestionBankId = (typeof GAME_QUESTION_BANK_IDS)[number];

Adding a bank is still a one-line change, and the type and the runtime list cannot drift apart. The route checks membership against a Set built from that array.

I want to be specific about why it is an exact-match allowlist and not a sanitising regex. params.bankId is about to be concatenated into a filesystem path:

export async function readQuestionBank(bankId: GameQuestionBankId): Promise<string> {
  return readFile(path.join(BANK_DIR, `${bankId}.json`), 'utf8');
}

A regex that strips .. is a filter, and filters are a game of thinking of everything. A set membership check is structural: an id that is not one of the 102 known strings never reaches readFile at all, so path traversal is not filtered, it is unreachable. The allowlist runs before anything touches the disk.

Two smaller decisions in the same handler:

404, not 400, for an unknown id. A 400 would tell a prober that the id was malformed and a 404 that it was well formed but missing, which slowly leaks the shape of the id space. Same status for both, learn nothing.

Raw text, not NextResponse.json. The bank is already valid JSON on disk. Parsing it into objects so that NextResponse.json can serialise it straight back is CPU spent on every request to produce the bytes we started with, for a payload the server never inspects.

The two headers that undo the work

dynamic = 'force-dynamic' and Cache-Control: private are not decoration. Without the first, a route with no request-dependent inputs can be prerendered at build time and served from the static output, which puts the file right back on the CDN with a different URL. Without the second, a shared cache is entitled to store one user's authenticated response and hand it to the next caller, which is precisely what public, immutable was doing before.

So the test suite asserts on the header, not just the status:

✓ serves a bank to a signed-in user
✓ refuses an anonymous caller
✓ never lets a bank into a shared cache
✓ rejects ids outside the allowlist rather than touching the filesystem
✓ keeps the banks out of the public directory

That last one is a directory check. It fails the build if anyone ever drops a bank back into public/, which is exactly how this happened the first time: public/ is where you put static JSON, right up until the static JSON is the answer key.

Authenticate, but do not authorise

The obvious next step is to check entitlement too, so a free account cannot pull a paid provider's bank. I did not do it, and the reason is worth writing down.

There is no bank-to-game mapping in the codebase. Bank ids are hardcoded literals inside each engine, and several banks legitimately serve more than one game: asx-matrigma feeds both Matrigma games, and three TestGroup ability banks also back a combined test. Building that map properly is worth doing. Guessing at it inside a route handler would have broken real games for real users mid-session, which is a worse failure than the one it prevents.

Authentication is a complete, correct, shippable step. Authorisation is a different change with a different blast radius, and bundling them would have meant shipping neither cleanly.

Try it

Open any of the practice tests at cogniprep.app/games with your network tab open. You will see the bank arrive from /api/games/questions/<id> with cache-control: private, max-age=3600, and you will see nothing at all under /game-questions/. Sign out and request that path directly and you get a 401.

If you want the other half of the story, the reason these banks are hand-authored rather than generated is that the tests they imitate are measured instruments, and the scoring side of that is what makes a plausible-looking wrong question expensive.

The short version, for anyone auditing their own public/ directory this afternoon: public/ is a CDN, not a folder. The cache header you are proud of is the one that publishes it.