gatsby-matrix-theme 53.20.0 → 54.0.0-beta.1

package/.ci.yml

@@ -44,6 +44,9 @@ Theme Publish:
     - yarn
     - cd matrix-theme/
     - yarn
+    # husky install (run by yarn prepare) sets a local core.hooksPath; override it
+    # locally AFTER install so semantic-release's release commit skips commitlint
+    - git config core.hooksPath /dev/null
     - rm -rf /root/.npmrc /root/.npm
     - npm cache clean --force
     - npx semantic-release@22.0.0 -b $CI_COMMIT_REF_NAME
@@ -63,11 +66,21 @@ Theme Beta Publish:
     - git config --global http.sslverify false
     - git config --global user.email "floyd@gig.com"
     - git config --global user.name "floyd"
+    - echo "@gigmedia:registry=https://npm.gigmedia.tech/" >> ~/.npmrc
+    - echo "//npm.gigmedia.tech/:_authToken=${NPM_PRIVATE_TOKEN}" >> ~/.npmrc
+    - echo "//registry.npmjs.org/:_authToken=${NPM_AUTH_TOKEN}" >> ~/.npmrc
+
   script:
     - export HUSKY=0
     - yarn config set cache-folder .yarn
     - yarn
     - cd matrix-theme/
+    - yarn
+    # husky install (run by yarn prepare) sets a local core.hooksPath; override it
+    # locally AFTER install so semantic-release's release commit skips commitlint
+    - git config core.hooksPath /dev/null
+    - rm -rf /root/.npmrc /root/.npm
+    - npm cache clean --force
     - npx semantic-release@22.0.0
   when: manual
   only:

package/CHANGELOG.md

@@ -1,3 +1,51 @@
+# [54.0.0-beta.1](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/compare/v53.20.0...v54.0.0-beta.1) (2026-06-17)
+
+
+### Bug Fixes
+
+* **ci:** clean stale npmrc before beta semantic-release to fix EINVALIDNPMTOKEN ([e360eea](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/e360eea13e02f76b641f55acf2fb618e967c4bcb))
+* **ci:** disable git hooks in publish jobs so semantic-release commit passes ([05ea13e](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/05ea13e11c16048731fee84af01fed5f777ba1b2))
+* **ci:** set local core.hooksPath after yarn install to bypass husky in release ([9437ab7](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/9437ab740479532d417d99417c23448eaa3f5c69))
+* **critical-css:** per-page render-blocking chunk linking to eliminate CLS ([bb3578f](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/bb3578f4f781f82decfdaa30535a802ff798695d))
+* testing gtm removal ([c717e12](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/c717e12b6d935645a8cdce9da76292ce32ef0165))
+* tm-5551 - remove conflicting env var from ci ([f113ae2](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/f113ae26095f4e9907d40eb5040f47a82547adca))
+* tm-5551 - revert yarn.lock ([98f717e](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/98f717ef9602ecd4b7f8f2af6b7908c32346186f))
+* update env ([d2e6558](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/d2e65585707890da96b2ea9bd1db0146ee5a7238))
+* update theme ([5f6d82f](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/5f6d82fed691c71c2bb64805c1b4c9f841ae634f))
+
+
+### chore
+
+* **release:** 53.10.0-beta.1 [skip ci] ([b5c909b](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/b5c909bff492c9de6594653f2cea2ec57895bea8))
+
+
+### Config
+
+* cicd token ([e44e3c5](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/e44e3c5c376d48bca55843fb498ca342d730879c))
+* update theme ([c87e63f](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/c87e63ff3a5c0c2ab877b8b6f9598188165bedf1))
+
+
+* Merge branch 'en-391-unused-css' into 'beta' ([a37b54f](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/a37b54f7eb9cf75078fbed90c48f058a69cedc66))
+* Merge branch 'master' into beta ([18b071d](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/18b071da6c64fb5bb4ce75b5a6112ab40afe665e))
+
+
+### Features
+
+* **critical-css:** flag-gated critical-CSS deferral (CSS split + manifest + above-fold re-inline) ([ae6bc2b](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/ae6bc2bd3bf73f2386961d12992b679ff9665297))
+* remove unused scripts ([5ba0309](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/5ba0309d196acf6023a267dbb0f730deaab77cbe))
+* tm-5551 - add enigma-middleware configurations to env file ([53a0453](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/53a04532d968addfdec96bca38e08a107ec01086))
+* tm-5551 - add enigma-middleware to matrix theme ([f1a4b9b](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/f1a4b9b9716052d83e31412d5663a7a48257724b))
+
+
+### norelease
+
+* reconcile yarn.lock after merging master into beta ([7b4021a](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/7b4021a4c47b8851377e83568063e0b0e54f6680))
+
+
+### Tests
+
+* **critical-css:** integration tests for injectCriticalCss to restore coverage ([87a6d19](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/commit/87a6d19fe6872e8dcaa972377bf41255883c60c7))
+
 # [53.20.0](https://gitlab.com/g2m-gentoo/team-floyd/themes/matrix-theme/compare/v53.19.1...v53.20.0) (2026-06-16)
 
 

package/critical-css/README.md

@@ -0,0 +1,106 @@
+# Critical-CSS split (per-page render-blocking)
+
+Splits the single merged stylesheet (~400–520 KB) that the core theme inlines render-blocking on
+**every** page into separate cacheable chunks, then, for each page, references **only the chunks that
+page actually renders** as render-blocking `<link rel="stylesheet">` in `<head>`. Each page paints
+fully styled on first paint (**no FOUC, no CLS**) while carrying only its own CSS — well under the
+stock merged stylesheet — and the chunks are external cacheable files instead of bytes re-inlined into
+every HTML document.
+
+**Why this shape (history):**
+
+- The merged baseline inlines all CSS render-blocking into every page → no CLS, but ~520 KB re-shipped
+  per page, uncacheable.
+- A first attempt *deferred* below-the-fold lazy-module CSS to **async** chunks and re-inlined only an
+  above-the-fold subset. That caused **CLS** — async CSS paints unstyled then reflows. With browser
+  **scroll restoration** (reload returns the user to wherever they scrolled) the shifting content lands
+  in the viewport, so no fixed above-the-fold safelist can prevent it.
+- Making **all** chunks render-blocking on every page killed the CLS but doubled render-blocking CSS
+  (~1 MB), because the split duplicates shared rules across chunks → worse cold FCP than baseline.
+- **This version** render-blocks only each page's *own* chunks → no CLS and below-baseline CSS per page.
+
+**Trade-off:** the win is on every axis vs the merged baseline *except* request count — each chunk is a
+separate `<link>` (HTTP/2 multiplexed). Per-page CSS is smaller than baseline, and chunks are cached
+across navigation/reload. **LCP is unaffected** (hydration/JS-bound here — a separate track).
+
+## How it works
+
+Two Gatsby hooks in `gatsby-node.js`, both guarded (a failure degrades gracefully, never breaks the build):
+
+1. **`onCreateWebpackConfig`** — sets the `styles` cacheGroup to `chunks: 'initial'`, so CSS splits
+   into per-route + lazy-module chunks instead of one merged file.
+2. **`onPostBuild`** (`injectCriticalCss.js`) — builds a `className → chunk` index from the emitted
+   `.css` files, then for each page adds a render-blocking
+   `<link rel="stylesheet" href="/…" data-crit="…">` for every chunk whose CSS-module class names
+   appear in that page's server-rendered HTML (see `selectChunks.js`). A used module's wrapper class is
+   always in the SSR HTML, so its chunk is linked; chunks for modules the page doesn't render are
+   skipped. This needs **no module→component registry** and auto-covers header variants. Idempotent and
+   deduped against CSS already inlined by the core theme (the base chunk) or already linked.
+
+## Enabling it (per site)
+
+Off by default. Enable via theme plugin options in the consumer's `gatsby-config.js`:
+
+```js
+plugins: [
+  {
+    resolve: 'gatsby-matrix-theme',
+    options: {
+      criticalCss: {
+        enabled: true,
+        // optional:
+        skipRoutes: ['preview'],  // route first-segments left with default (full) inlining
+        minClassLen: 5,           // advanced: min classname length used for chunk matching
+      },
+    },
+  },
+],
+```
+
+The feature only runs in production `gatsby build` (the split is `build-javascript`-stage;
+`onPostBuild` is build-only).
+
+### Options
+
+| option | default | meaning |
+|---|---|---|
+| `enabled` | `false` | hard gate |
+| `skipRoutes` | `['preview']` | route first-segments left untouched; preview/tracker pages are also skipped via `isPreview`/`isTracker` |
+| `minClassLen` | `5` | minimum classname length considered when matching chunks to a page's HTML. Lower → looser matching (more chunks); higher → tighter (risk of missing a chunk). |
+
+## Caveats / QA
+
+- **No CLS by design** — a page render-blocks exactly the chunks whose classes it renders, so all its CSS
+  is present on first paint at any scroll position. Still spot-check CLS after enabling.
+- **Residual miss risk** — a chunk that styles rendered content using *only* global/element selectors
+  (no CSS-module class) would not be matched and would stay async. Module SCSS almost always has a hashed
+  wrapper class, so this is rare; watch for it in QA, and lower `minClassLen` if a chunk is missed.
+- **Request count** — each chunk is a separate render-blocking `<link>` (HTTP/2 multiplexes). Per-page
+  CSS is smaller than baseline; the payoff over baseline is caching on navigation/reload.
+- **LCP** is unaffected (hydration-bound here).
+
+## Per-site rollout checklist
+
+Adopting a site is QA, not code:
+
+1. **Bump** `gatsby-matrix-theme` to a version that includes this feature.
+2. **Enable** `options.criticalCss.enabled: true`.
+3. **Build** (`gatsby build`). Confirm the log shows `CSS split enabled` and
+   `render-blocking-linked page chunks on X/Y pages`.
+4. **Measure** with the harness on the homepage + the top template(s):
+   ```bash
+   CHROME_PATH=/path/to/chrome \
+   node scripts/lh-critical-compare.mjs public / /<operator-route>/ --runs 3
+   ```
+   Run it once before enabling and once after for a before/after.
+5. **Verify**: **no FOUC**, **CLS = 0 / not regressed** at top *and* after a mid-page reload (scroll
+   restoration), per-page CSS smaller than baseline, and reload serves chunks from cache.
+6. **Ship behind the flag**, then ramp.
+
+> Chrome for the harness: snap chromium does not work. Download a standalone build, e.g.
+> `npx @puppeteer/browsers install chrome@stable`, and point `CHROME_PATH` at it.
+
+## Disabling
+
+Set `criticalCss.enabled: false` (or remove the option). The build reverts to the stock single
+merged inlined stylesheet.

package/critical-css/config.js

@@ -0,0 +1,32 @@
+/**
+ * Critical-CSS feature config — resolved from theme plugin options.
+ *
+ * A consumer site enables/configures the feature via its gatsby-config:
+ *   {
+ *     resolve: 'gatsby-matrix-theme',
+ *     options: {
+ *       criticalCss: {
+ *         enabled: true,            // hard gate, default OFF
+ *         skipRoutes: ['preview'],  // route prefixes to leave with default (full) inlining
+ *         minClassLen: 5,           // advanced: min classname length for chunk matching
+ *       },
+ *     },
+ *   }
+ *
+ * Everything here is build-time Node code (read in gatsby-node), NOT bundled app code —
+ * which is why config goes through plugin options rather than component shadowing.
+ */
+
+function resolveConfig(pluginOptions = {}) {
+  const cc = (pluginOptions && pluginOptions.criticalCss) || {};
+  return {
+    enabled: cc.enabled === true,
+    skipRoutes:
+      Array.isArray(cc.skipRoutes) && cc.skipRoutes.length
+        ? cc.skipRoutes.filter((s) => typeof s === 'string')
+        : ['preview'],
+    minClassLen: Number.isInteger(cc.minClassLen) && cc.minClassLen >= 1 ? cc.minClassLen : 5,
+  };
+}
+
+module.exports = { resolveConfig };

package/critical-css/injectCriticalCss.js

@@ -0,0 +1,171 @@
+/**
+ * injectCriticalCss — post-build: make each page's own split CSS chunks render-blocking.
+ *
+ * The webpack split (styles cacheGroup -> chunks:'initial') moves lazy-module CSS into async
+ * chunks that the runtime injects at hydration. Async CSS paints unstyled then reflows => FOUC +
+ * CLS, and with browser scroll restoration (reload returns the user to wherever they scrolled) the
+ * shifting content is often in the viewport, so a fixed above-the-fold safelist can't prevent it.
+ *
+ * Fix: for each page, add a render-blocking <link rel="stylesheet"> for exactly the chunks that
+ * page renders — detected by classname presence (a chunk is needed iff one of its CSS-module class
+ * names appears in the page's server-rendered HTML; see ./selectChunks). All CSS the page uses is
+ * then present on first paint => no FOUC/CLS at any scroll position, while pages only carry their
+ * own chunks (well under the stock single merged inlined stylesheet) and the chunks stay separate
+ * cacheable files (cross-page / reload caching, smaller HTML).
+ *
+ * Idempotent (skips chunks already inlined by the core theme or already linked) and fully guarded —
+ * never throws out of the function.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { buildClassIndex, selectChunksForHtml } = require('./selectChunks');
+
+// Lazy-module chunk .css files live at the public root (Gatsby / mini-css-extract). Exclude the
+// initial/route stylesheets: the base (`styles.*`) and route-component shells (`component---*`) are
+// already inlined render-blocking by the core theme (or are duplicate SSR/preview entry CSS that a
+// normal page never loads). Only the lazy *module* chunks otherwise load async and need re-linking.
+function isModuleChunk(name) {
+  return name.endsWith('.css') && !/^styles\./.test(name) && !/^component---/.test(name);
+}
+
+function listCssChunks(publicDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(publicDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter((e) => e.isFile() && isModuleChunk(e.name)).map((e) => e.name);
+}
+
+function injectCriticalCss({ publicDir, config, reporter }) {
+  const log = reporter || { info() {}, warn() {} };
+  const minLen = config && Number.isInteger(config.minClassLen) ? config.minClassLen : 5;
+
+  const chunkFiles = listCssChunks(publicDir);
+  if (!chunkFiles.length) {
+    log.warn('[critical-css] no css chunks found in public/; nothing to link');
+    return;
+  }
+
+  // Build the classname -> chunk index once for the whole build.
+  const chunks = [];
+  for (const f of chunkFiles) {
+    try {
+      chunks.push({ file: f, css: fs.readFileSync(path.join(publicDir, f), 'utf8') });
+    } catch {
+      /* skip unreadable chunk */
+    }
+  }
+  const classIndex = buildClassIndex(chunks, minLen);
+
+  const skipRoutes = Array.isArray(config && config.skipRoutes) ? config.skipRoutes : ['preview'];
+  const pageDataRoot = path.join(publicDir, 'page-data');
+  let scanned = 0;
+  let patched = 0;
+  let skipped = 0;
+  let missedHead = 0;
+  let totalLinked = 0;
+
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        walk(full);
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+      // eslint-disable-next-line no-continue
+      if (ent.name !== 'page-data.json') continue;
+      scanned += 1;
+
+      // page-data/<route>/page-data.json -> public/<route>/index.html ("index" => public/index.html)
+      const route = path.relative(pageDataRoot, dir);
+
+      // never touch preview/tracker routes — they keep default (full) inlining
+      const firstSeg = route.split(path.sep)[0];
+      if (skipRoutes.indexOf(firstSeg) !== -1) {
+        skipped += 1;
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
+      let pageCtx;
+      try {
+        const pd = JSON.parse(fs.readFileSync(full, 'utf8'));
+        pageCtx = pd && pd.result && pd.result.pageContext ? pd.result.pageContext : undefined;
+      } catch {
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
+      // skip preview/tracker pages regardless of route
+      if (pageCtx && (pageCtx.isPreview === true || pageCtx.isTracker === true)) {
+        skipped += 1;
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
+      const htmlPath =
+        route === 'index'
+          ? path.join(publicDir, 'index.html')
+          : path.join(publicDir, route, 'index.html');
+      // eslint-disable-next-line no-continue
+      if (!fs.existsSync(htmlPath)) continue;
+
+      let html;
+      try {
+        html = fs.readFileSync(htmlPath, 'utf8');
+      } catch {
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
+      const needed = selectChunksForHtml(html, classIndex);
+      let add = '';
+      for (const f of needed) {
+        // skip chunks already inlined by the core theme (data-href, e.g. the base chunk) or
+        // already linked (href) — idempotent, avoids double-loading.
+        // eslint-disable-next-line no-continue
+        if (html.includes(`data-href="/${f}"`) || html.includes(`href="/${f}"`)) continue;
+        add += `<link rel="stylesheet" href="/${f}" data-crit="${f}">`;
+        totalLinked += 1;
+      }
+      // eslint-disable-next-line no-continue
+      if (!add) continue;
+
+      // if there's no </head> (error/custom pages), leave it split-only but record the miss
+      if (html.indexOf('</head>') === -1) {
+        missedHead += 1;
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
+      try {
+        fs.writeFileSync(htmlPath, html.replace('</head>', `${add}</head>`));
+        patched += 1;
+      } catch {
+        /* leave the page as split-only on write failure */
+      }
+    }
+  };
+
+  walk(pageDataRoot);
+
+  const avg = patched ? (totalLinked / patched).toFixed(1) : '0';
+  const parts = [
+    `[critical-css] render-blocking-linked page chunks on ${patched}/${scanned} pages (avg ${avg}/page)`,
+  ];
+  if (skipped) parts.push(`(${skipped} preview/tracker skipped)`);
+  if (missedHead) parts.push(`(${missedHead} pages had no </head>, left split-only)`);
+  log.info(parts.join(' '));
+}
+
+module.exports = { injectCriticalCss, listCssChunks, isModuleChunk };

package/critical-css/injectCriticalCss.test.js

@@ -0,0 +1,119 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { injectCriticalCss, isModuleChunk } from './injectCriticalCss';
+
+describe('isModuleChunk', () => {
+  test('accepts lazy module chunks (numeric / hashed)', () => {
+    expect(isModuleChunk('7058.85be7b8d3f97fe1255e9.css')).toBe(true);
+    expect(isModuleChunk('922.3161d0beba28e0a349fc.css')).toBe(true);
+  });
+
+  test('rejects the inlined base and route-component shells', () => {
+    expect(isModuleChunk('styles.5f846a3bcbc9df9c2721.css')).toBe(false);
+    expect(isModuleChunk('component---node-modules-gatsby-core-theme-src-components-app-ssr-js.832a.css')).toBe(false);
+    expect(isModuleChunk('component---node-modules-gatsby-core-theme-src-pages-preview-index-js.832a.css')).toBe(false);
+  });
+
+  test('rejects non-css', () => {
+    expect(isModuleChunk('7058.85be7b8d3f97fe1255e9.js')).toBe(false);
+  });
+});
+
+describe('injectCriticalCss (integration over a temp public/)', () => {
+  let dir;
+  const silent = { info() {}, warn() {} };
+  const html = (body) => `<html><head><title>t</title></head><body>${body}</body></html>`;
+  const pageData = (extra = {}) =>
+    JSON.stringify({ result: { pageContext: { page: { relation_type: 'page' }, ...extra } } });
+
+  const write = (rel, content) => {
+    const full = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+  };
+  const read = (rel) => fs.readFileSync(path.join(dir, rel), 'utf8');
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'crit-'));
+    // module chunks
+    write('100.aaa.css', '.Bonus_wrap__x1{color:red}');
+    write('200.bbb.css', '.Toplist_row__y2{margin:0}');
+    write('300.ccc.css', '.Unused_z__z3{display:none}'); // no page renders this
+    // base + route shell — must be ignored as candidates
+    write('styles.deadbeef.css', '.Base_thing__b1{}');
+    write('component---node-modules-gatsby-core-theme-src-components-app-js.832a.css', '.App_shell__s1{}');
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  const run = () =>
+    injectCriticalCss({
+      publicDir: dir,
+      config: { enabled: true, skipRoutes: ['preview'], minClassLen: 5 },
+      reporter: silent,
+    });
+
+  test('links only the module chunks whose classes the page renders', () => {
+    write('page-data/index/page-data.json', pageData());
+    write('index.html', html('<div class="Bonus_wrap__x1 bonus">x</div>'));
+
+    run();
+    const out = read('index.html');
+    expect(out).toContain('<link rel="stylesheet" href="/100.aaa.css" data-crit="100.aaa.css">');
+    expect(out).not.toContain('200.bbb.css'); // toplist not rendered
+    expect(out).not.toContain('300.ccc.css'); // unused
+    expect(out).not.toContain('styles.deadbeef.css'); // base, excluded candidate
+    expect(out).not.toContain('app-js.832a.css'); // route shell, excluded candidate
+  });
+
+  test('does not double-link a chunk already inlined by the core theme (data-href)', () => {
+    write('page-data/index/page-data.json', pageData());
+    write(
+      'index.html',
+      html('<div class="Bonus_wrap__x1">x</div>').replace(
+        '<title>t</title>',
+        '<title>t</title><style data-href="/100.aaa.css">.Bonus_wrap__x1{}</style>',
+      ),
+    );
+    run();
+    const out = read('index.html');
+    expect(out).not.toContain('data-crit="100.aaa.css"'); // already inlined -> skipped
+  });
+
+  test('is idempotent — running twice does not add duplicate links', () => {
+    write('page-data/index/page-data.json', pageData());
+    write('index.html', html('<div class="Bonus_wrap__x1 Toplist_row__y2">x</div>'));
+    run();
+    run();
+    const out = read('index.html');
+    expect(out.match(/data-crit="100\.aaa\.css"/g)).toHaveLength(1);
+    expect(out.match(/data-crit="200\.bbb\.css"/g)).toHaveLength(1);
+  });
+
+  test('skips preview/tracker pages (route prefix and pageContext flags)', () => {
+    write('page-data/preview/page-data.json', pageData());
+    write('preview/index.html', html('<div class="Bonus_wrap__x1">x</div>'));
+    write('page-data/tracked/page-data.json', pageData({ isTracker: true }));
+    write('tracked/index.html', html('<div class="Bonus_wrap__x1">x</div>'));
+    run();
+    expect(read('preview/index.html')).not.toContain('data-crit');
+    expect(read('tracked/index.html')).not.toContain('data-crit');
+  });
+
+  test('leaves a page untouched when it renders no module chunks', () => {
+    write('page-data/index/page-data.json', pageData());
+    const original = html('<div class="onlyGlobalClass">x</div>');
+    write('index.html', original);
+    run();
+    expect(read('index.html')).toBe(original);
+  });
+
+  test('guards: missing public dir does not throw', () => {
+    expect(() =>
+      injectCriticalCss({ publicDir: path.join(dir, 'nope'), config: { enabled: true }, reporter: silent }),
+    ).not.toThrow();
+  });
+});

package/critical-css/selectChunks.js

@@ -0,0 +1,75 @@
+/**
+ * selectChunks — pure helpers for per-page CSS-chunk selection by classname presence.
+ *
+ * The split emits one .css file per (lazy) module chunk. To know which chunks a page actually
+ * needs — without a brittle module→component registry — we look at what's really in the page's
+ * server-rendered HTML: a chunk is needed iff at least one of its (CSS-module, hashed) class
+ * names appears in the page's `class="…"` attributes. SSR renders every module the page uses, so
+ * each used module's wrapper class is present; chunks for modules the page doesn't render are
+ * skipped. This auto-covers header variants and needs no per-site config.
+ *
+ * All functions are pure & total (no I/O, never throw on string input).
+ */
+
+// class selector in CSS: a dot followed by an identifier (letters/_/-, then word chars). Excludes
+// fractional values (.5em) and file extensions short enough to fall under minLen (.png/.svg/…).
+const CSS_CLASS_RE = /\.(-?[_a-zA-Z][\w-]*)/g;
+const CLASS_ATTR_RE = /class="([^"]*)"/g;
+
+function extractCssClasses(css, minLen = 5) {
+  const out = new Set();
+  if (typeof css !== 'string') return out;
+  let m;
+  // eslint-disable-next-line no-cond-assign
+  while ((m = CSS_CLASS_RE.exec(css))) {
+    if (m[1].length >= minLen) out.add(m[1]);
+  }
+  return out;
+}
+
+function extractHtmlClasses(html) {
+  const out = new Set();
+  if (typeof html !== 'string') return out;
+  let m;
+  // eslint-disable-next-line no-cond-assign
+  while ((m = CLASS_ATTR_RE.exec(html))) {
+    for (const tok of m[1].split(/\s+/)) if (tok) out.add(tok);
+  }
+  return out;
+}
+
+/**
+ * chunks: [{ file, css }]  ->  Map<className, Set<file>>
+ */
+function buildClassIndex(chunks, minLen = 5) {
+  const index = new Map();
+  if (!Array.isArray(chunks)) return index;
+  for (const c of chunks) {
+    if (c && typeof c.file === 'string') {
+      for (const cls of extractCssClasses(c.css, minLen)) {
+        let set = index.get(cls);
+        if (!set) {
+          set = new Set();
+          index.set(cls, set);
+        }
+        set.add(c.file);
+      }
+    }
+  }
+  return index;
+}
+
+/**
+ * Given a page's HTML and the class index, return the Set of chunk files the page needs.
+ */
+function selectChunksForHtml(html, classIndex) {
+  const files = new Set();
+  if (!(classIndex instanceof Map)) return files;
+  for (const tok of extractHtmlClasses(html)) {
+    const set = classIndex.get(tok);
+    if (set) for (const f of set) files.add(f);
+  }
+  return files;
+}
+
+module.exports = { extractCssClasses, extractHtmlClasses, buildClassIndex, selectChunksForHtml };

package/critical-css/selectChunks.test.js

@@ -0,0 +1,73 @@
+import {
+  extractCssClasses,
+  extractHtmlClasses,
+  buildClassIndex,
+  selectChunksForHtml,
+} from './selectChunks';
+
+describe('extractCssClasses', () => {
+  test('captures class selectors, skips fractional values and short tokens', () => {
+    const css = '.Bonus_wrap__a1b2c{margin:.5em;width:50px}.x{}.short{}a.Toplist_row__9zz{}';
+    const out = extractCssClasses(css, 5);
+    expect(out.has('Bonus_wrap__a1b2c')).toBe(true);
+    expect(out.has('Toplist_row__9zz')).toBe(true);
+    expect(out.has('short')).toBe(true); // exactly 5 chars
+    expect(out.has('x')).toBe(false); // below minLen
+    expect([...out]).not.toContain('5em'); // fractional value, not a class
+  });
+
+  test('respects minLen and tolerates non-string', () => {
+    expect([...extractCssClasses('.abcdefg{}', 8)]).toEqual([]);
+    expect([...extractCssClasses(null)]).toEqual([]);
+  });
+});
+
+describe('extractHtmlClasses', () => {
+  test('collects whitespace-separated tokens from every class attribute', () => {
+    const html = '<div class="Bonus_wrap__a1b2c bonus module"></div><span class="Toplist_row__9zz"></span>';
+    const out = extractHtmlClasses(html);
+    expect(out.has('Bonus_wrap__a1b2c')).toBe(true);
+    expect(out.has('bonus')).toBe(true);
+    expect(out.has('Toplist_row__9zz')).toBe(true);
+  });
+
+  test('tolerates non-string', () => {
+    expect([...extractHtmlClasses(undefined)]).toEqual([]);
+  });
+});
+
+describe('buildClassIndex + selectChunksForHtml', () => {
+  const chunks = [
+    { file: '922.aaa.css', css: '.Bonus_wrap__a1b2c{}.Bonus_logo__c3d{}' },
+    { file: '700.bbb.css', css: '.Toplist_row__9zz{}' },
+    { file: '404.ccc.css', css: '.NotFound_box__qq1{}' },
+  ];
+  const index = buildClassIndex(chunks, 5);
+
+  test('selects only chunks whose classes appear in the page HTML', () => {
+    const html = '<div class="Bonus_wrap__a1b2c bonus"></div><div class="Toplist_row__9zz"></div>';
+    const sel = selectChunksForHtml(html, index);
+    expect(sel).toEqual(new Set(['922.aaa.css', '700.bbb.css']));
+    expect(sel.has('404.ccc.css')).toBe(false); // not rendered on this page
+  });
+
+  test('a chunk with no matching class is not selected (empty page)', () => {
+    expect(selectChunksForHtml('<div class="someGlobal"></div>', index)).toEqual(new Set());
+  });
+
+  test('a class shared by two chunks selects both', () => {
+    const idx = buildClassIndex(
+      [
+        { file: 'a.css', css: '.Shared_x__h1{}' },
+        { file: 'b.css', css: '.Shared_x__h1{}' },
+      ],
+      5,
+    );
+    expect(selectChunksForHtml('<i class="Shared_x__h1"></i>', idx)).toEqual(new Set(['a.css', 'b.css']));
+  });
+
+  test('guards: bad inputs never throw', () => {
+    expect(buildClassIndex(null)).toEqual(new Map());
+    expect(selectChunksForHtml('<div class="x"></div>', null)).toEqual(new Set());
+  });
+});

package/gatsby-node.js

@@ -0,0 +1,57 @@
+/**
+ * gatsby-matrix-theme — build-time hooks.
+ *
+ * Critical-CSS split (default OFF; enable per-site via options.criticalCss.enabled):
+ *   1. onCreateWebpackConfig — split CSS so only initial-chunk CSS stays inlined; lazy-module CSS
+ *      goes to separate cacheable chunks.
+ *   2. onPostBuild — make each page's own chunks render-blocking (no async => no FOUC/CLS).
+ *
+ * All hooks are guarded so a failure degrades gracefully and never breaks a consumer build.
+ */
+
+const path = require('path');
+const { resolveConfig } = require('./critical-css/config');
+const { injectCriticalCss } = require('./critical-css/injectCriticalCss');
+
+exports.onCreateWebpackConfig = ({ stage, getConfig, actions, reporter }, pluginOptions) => {
+  // The split only matters for the production JS/CSS build.
+  if (stage !== 'build-javascript') return;
+
+  const cfg = resolveConfig(pluginOptions);
+  if (!cfg.enabled) return;
+
+  try {
+    const config = getConfig();
+    const cacheGroups =
+      config.optimization &&
+      config.optimization.splitChunks &&
+      config.optimization.splitChunks.cacheGroups;
+
+    if (cacheGroups && cacheGroups.styles) {
+      // Only CSS reachable from initial (sync) chunks gets merged into the per-route
+      // stylesheet that Gatsby inlines; lazy-module CSS goes to separate chunks (which
+      // onPostBuild then re-links render-blocking, per page).
+      cacheGroups.styles.chunks = 'initial';
+      reporter.info('[critical-css] CSS split enabled (styles cacheGroup -> chunks:"initial")');
+    } else {
+      reporter.warn('[critical-css] no styles cacheGroup found; CSS split NOT applied');
+    }
+
+    actions.replaceWebpackConfig(config);
+  } catch (e) {
+    reporter.warn(`[critical-css] onCreateWebpackConfig skipped: ${e && e.message}`);
+  }
+};
+
+exports.onPostBuild = async ({ reporter, store }, pluginOptions) => {
+  const cfg = resolveConfig(pluginOptions);
+  if (!cfg.enabled) return;
+  try {
+    const dir =
+      (store && store.getState && store.getState().program && store.getState().program.directory) ||
+      process.cwd();
+    injectCriticalCss({ publicDir: path.join(dir, 'public'), config: cfg, reporter });
+  } catch (e) {
+    reporter.warn(`[critical-css] onPostBuild skipped: ${e && e.message}`);
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gatsby-matrix-theme",
-  "version": "53.20.0",
+  "version": "54.0.0-beta.1",
   "main": "index.js",
   "description": "Matrix Theme NPM Package",
   "author": "",

package/storybook/public/project.json

@@ -1 +1,2 @@
-{"generatedAt":1781601464197,"builder":{"name":"webpack5"},"hasCustomBabel":false,"hasCustomWebpack":true,"hasStaticDirs":false,"hasStorybookEslint":false,"refCount":0,"metaFramework":{"name":"Gatsby","packageName":"gatsby","version":"5.13.6"},"monorepo":"Workspaces","packageManager":{"type":"yarn","version":"1.22.19"},"storybookVersion":"6.5.16","language":"javascript","storybookPackages":{"@storybook/addon-actions":{"version":"6.5.16"},"@storybook/builder-webpack5":{"version":"6.5.16"},"@storybook/manager-webpack5":{"version":"6.5.16"},"@storybook/react":{"version":"6.5.16"}},"framework":{"name":"react"},"addons":{"@storybook/addon-links":{"version":"6.5.16"},"@storybook/addon-essentials":{"version":"6.5.16"}}}
+{"generatedAt":1781707357621,"builder":{"name":"webpack5"},"hasCustomBabel":false,"hasCustomWebpack":true,"hasStaticDirs":false,"hasStorybookEslint":false,"refCount":0,"metaFramework":{"name":"Gatsby","packageName":"gatsby","version":"5.13.6"},"monorepo":"Workspaces","packageManager":{"type":"yarn","version":"1.22.19"},"storybookVersion":"6.5.16","language":"javascript","storybookPackages":{"@storybook/addon-actions":{"version":"6.5.16"},"@storybook/builder-webpack5":{"version":"6.5.16"},"@storybook/manager-webpack5":{"version":"6.5.16"},"@storybook/react":{"version":"6.5.16"}},"framework":{"name":"react"},"addons":{"@storybook/addon-links":{"version":"6.5.16"},"@storybook/addon-essentials":{"version":"6.5.16"}}}
+don-measure":{"version":"6.5.16-alpha.0"},"@storybook/addon-outline":{"version":"6.5.16-alpha.0"},"@storybook/addon-storyshots":{"version":"6.5.16-alpha.0"},"@storybook/addon-storyshots-puppeteer":{"version":"6.5.16-alpha.0"},"@storybook/addon-storysource":{"version":"6.5.16-alpha.0"},"@storybook/addon-toolbars":{"version":"6.5.16-alpha.0"},"@storybook/addon-viewport":{"version":"6.5.16-alpha.0"},"@storybook/addons":{"version":"6.5.16-alpha.0"},"@storybook/angular":{"version":"6.5.16-alpha.0"},"@storybook/api":{"version":"6.5.16-alpha.0"},"@storybook/babel-plugin-require-context-hook":{"version":"1.0.1"},"@storybook/channel-postmessage":{"version":"6.5.16-alpha.0"},"@storybook/channel-websocket":{"version":"6.5.16-alpha.0"},"@storybook/channels":{"version":"6.5.16-alpha.0"},"@storybook/cli":{"version":"6.5.16-alpha.0"},"@storybook/client-api":{"version":"6.5.16-alpha.0"},"@storybook/client-logger":{"version":"6.5.16-alpha.0"},"@storybook/codemod":{"version":"6.5.16-alpha.0"},"@storybook/components":{"version":"6.5.16-alpha.0"},"@storybook/core":{"version":"6.5.16-alpha.0"},"@storybook/core-events":{"version":"6.5.16-alpha.0"},"@storybook/csf-tools":{"version":"6.5.16-alpha.0"},"@storybook/docs-tools":{"version":"6.5.16-alpha.0"},"@storybook/ember":{"version":"6.5.16-alpha.0"},"@storybook/eslint-config-storybook":{"version":"2.4.0"},"@storybook/html":{"version":"6.5.16-alpha.0"},"@storybook/instrumenter":{"version":"6.5.16-alpha.0"},"@storybook/jest":{"version":"0.0.5"},"@storybook/linter-config":{"version":"2.5.0"},"@storybook/node-logger":{"version":"6.5.16-alpha.0"},"@storybook/postinstall":{"version":"6.5.16-alpha.0"},"@storybook/preact":{"version":"6.5.16-alpha.0"},"@storybook/preview-web":{"version":"6.5.16-alpha.0"},"@storybook/react":{"version":"6.5.16-alpha.0"},"@storybook/router":{"version":"6.5.16-alpha.0"},"@storybook/semver":{"version":"7.3.2"},"@storybook/server":{"version":"6.5.16-alpha.0"},"@storybook/source-loader":{"version":"6.5.16-alpha.0"},"@storybook/store":{"version":"6.5.16-alpha.0"},"@storybook/svelte":{"version":"6.5.16-alpha.0"},"@storybook/telemetry":{"version":"6.5.16-alpha.0"},"@storybook/testing-library":{"version":"0.0.7"},"@storybook/theming":{"version":"6.5.16-alpha.0"},"@storybook/ui":{"version":"6.5.16-alpha.0"},"@storybook/vue":{"version":"6.5.16-alpha.0"},"@storybook/web-components":{"version":"6.5.16-alpha.0"},"eslint-plugin-storybook":{"version":"0.3.5"}},"framework":{"name":"angular"},"addons":{"@storybook/addon-links":{"version":"6.5.16-alpha.0"},"@storybook/addon-essentials":{"version":"6.5.16-alpha.0"}}}

package/package.old.json

@@ -1,87 +0,0 @@
-{
-    "name": "gatsby-matrix-theme",
-    "version": "5.0.11",
-    "main": "index.js",
-    "description": "Matrix Theme NPM Package",
-    "author": "",
-    "license": "MIT",
-    "GATSBY_RECAPTCHA_SITEKEY": "6LfoyvMUAAAAAO4nl_MQnqHb4XdHxEiu5cXgIqeB",
-    "peerDependencies": {
-      "gatsby": "^3.3.1"
-    },
-    "directories": {
-      "test": "tests"
-    },
-    "repository": {
-      "type": "git",
-      "url": "https://git.ilcd.rocks/team-floyd/themes/matrix-theme"
-    },
-    "scripts": {
-      "test": "jest --coverage",
-      "update-packages": "npm version patch && npm publish",
-      "storybook": "cross-env STORYBOOK_IMAGE_CDN_URL=https://cdn.irishluck.ie STORYBOOK_GATSBY_SITE_NAME=irishluck.ie STORYBOOK_GATSBY_TRACKER_LINK_PREFIX=visit start-storybook -s ./storybook-images -p 7007",
-      "build-storybook": "cross-env STORYBOOK_IMAGE_CDN_URL=https://cdn.irishluck.ie STORYBOOK_GATSBY_SITE_NAME=irishluck.ie STORYBOOK_GATSBY_TRACKER_LINK_PREFIX=visit build-storybook"
-    },
-    "storybook": {
-      "url": "https://storybook-matrix.gigmedia.com/"
-    },
-    "dependencies": {
-      "babel-preset-gatsby": "^1.3.0",
-      "chalk": "^4.1.0",
-      "cross-env": "^7.0.2",
-      "dotenv": "8.2.0",
-      "gatsby": "^3.3.1",
-      "gatsby-core-theme": "^5.1.4",
-      "gatsby-image": "^3.3.0",
-      "gatsby-plugin-image": "^1.3.1",
-      "gatsby-plugin-postcss": "^4.3.0",
-      "postcss": "^8.2.10",
-      "prop-types": "15.7.2",
-      "react": "^17.0.2",
-      "react-dom": "^17.0.2",
-      "react-icons": "^4.2.0",
-      "react-masonry-css": "^1.0.16"
-    },
-    "devDependencies": {
-      "@babel/core": "^7.13.1",
-      "@babel/plugin-syntax-class-properties": "^7.12.1",
-      "@babel/plugin-syntax-jsx": "^7.12.1",
-      "@babel/preset-env": "^7.13.5",
-      "@babel/preset-react": "^7.12.1",
-      "@semantic-release/changelog": "^5.0.1",
-      "@semantic-release/commit-analyzer": "^8.0.1",
-      "@semantic-release/git": "^9.0.0",
-      "@semantic-release/gitlab": "^6.2.1",
-      "@semantic-release/gitlab-config": "^8.0.0",
-      "@semantic-release/npm": "^7.1.3",
-      "@semantic-release/release-notes-generator": "^9.0.3",
-      "@storybook/addon-actions": "^6.0.21",
-      "@storybook/addon-essentials": "^6.0.21",
-      "@storybook/addon-links": "^6.0.21",
-      "@storybook/react": "^6.0.21",
-      "@testing-library/jest-dom": "^5.14.1",
-      "@testing-library/react": "^11.2.6",
-      "babel-jest": "^26.6.3",
-      "babel-loader": "^8.2.2",
-      "babel-preset-gatsby": "^1.3.0",
-      "gatsby-plugin-compile-es6-packages": "^2.1.0",
-      "identity-obj-proxy": "^3.0.0",
-      "jest": "^26.6.3",
-      "sass-resources-loader": "^2.1.0"
-    },
-    "jest": {
-      "verbose": true,
-      "moduleFileExtensions": [
-        "js",
-        "jsx"
-      ],
-      "moduleDirectories": [
-        "node_modules"
-      ],
-      "transform": {
-        "\\.js$": "<rootDir>/node_modules/babel-jest"
-      }
-    },
-    "browserslist": "> 0.25%, not dead"
-  }
-