From a01b4e8b4f8c1c4570b1286d317f5296dd586230 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 14 Jul 2026 17:32:42 +0000
Subject: [PATCH 01/10] Derive release package contents from manifest.json and
 test the archive

The hand-maintained INCLUDE list in scripts/build.mjs had fallen out of
sync with manifest.json: checks.js was loaded as a content script but
never packaged, so published .zip/.xpi builds shipped with the
status-checks helpers missing. Derive the file list from the manifest
(content scripts, background scripts, icons, popup, and the popup's
<script src> tags), fail the build if any referenced file is missing,
and add a packaging test that inspects the real archive in CI.

Co-authored-by: Julius Walton <ShiosOS@users.noreply.github.com>
---
 scripts/build.mjs   | 71 +++++++++++++++++++++++++++++++--------------
 test/build.test.mjs | 70 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 119 insertions(+), 22 deletions(-)
 create mode 100644 test/build.test.mjs

diff --git a/scripts/build.mjs b/scripts/build.mjs
index a750ac6..81a93e9 100644
--- a/scripts/build.mjs
+++ b/scripts/build.mjs
@@ -3,9 +3,16 @@
 // The version is read from manifest.json — the single source of truth — so
 // bumping the extension version never means editing this script or a
 // filename by hand.
+//
+// The file list is derived from manifest.json (content scripts, background
+// scripts, icons, popup) plus the <script src> tags of any packaged HTML
+// page, rather than hand-maintained. A hand-maintained list once shipped a
+// broken build by omitting checks.js; deriving the list makes that class of
+// mistake impossible, and the existence check below turns a missing file
+// into a build failure instead of a silently broken archive.
 
 import { createWriteStream } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -16,23 +23,32 @@ const archiver = require("archiver");
 
 const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 
-// Files the browser actually loads. Everything else (tests, configs,
-// node_modules, docs) is dev-only and must not ship.
-const INCLUDE = [
-  "manifest.json",
-  "constants.js",
-  "reorder.js",
-  "content.js",
-  "background.js",
-  "popup.html",
-  "popup.js",
-  "icon-16.png",
-  "icon-16-disabled.png",
-  "icon-48.png",
-  "icon-48-disabled.png",
-  "icon-128.png",
-  "icon-128-disabled.png",
-];
+/** Collect every file the browser loads, straight from the manifest. */
+async function collectFiles(manifest) {
+  const files = new Set(["manifest.json"]);
+
+  for (const cs of manifest.content_scripts ?? []) {
+    for (const f of cs.js ?? []) files.add(f);
+    for (const f of cs.css ?? []) files.add(f);
+  }
+
+  if (manifest.background?.service_worker) files.add(manifest.background.service_worker);
+  for (const f of manifest.background?.scripts ?? []) files.add(f);
+
+  for (const f of Object.values(manifest.icons ?? {})) files.add(f);
+  for (const f of Object.values(manifest.action?.default_icon ?? {})) files.add(f);
+  if (manifest.action?.default_popup) files.add(manifest.action.default_popup);
+
+  // HTML pages pull in their own scripts via <script src>.
+  for (const f of [...files].filter((f) => f.endsWith(".html"))) {
+    const html = await readFile(path.join(root, f), "utf8");
+    for (const [, src] of html.matchAll(/<script\s+[^>]*src="([^"]+)"/g)) {
+      files.add(src);
+    }
+  }
+
+  return [...files].sort();
+}
 
 function zipTo(outPath, files) {
   return new Promise((resolve, reject) => {
@@ -48,15 +64,26 @@ function zipTo(outPath, files) {
 
 const manifest = JSON.parse(await readFile(path.join(root, "manifest.json"), "utf8"));
 const { version, name } = manifest;
-const base = "github-pr-reverse-comments";
+const files = await collectFiles(manifest);
+
+// Fail loudly if the manifest references a file that doesn't exist.
+const missing = [];
+for (const f of files) {
+  await stat(path.join(root, f)).catch(() => missing.push(f));
+}
+if (missing.length) {
+  console.error(`Referenced files not found: ${missing.join(", ")}`);
+  process.exit(1);
+}
 
+const base = "github-pr-reverse-comments";
 const zipName = `${base}.zip`;
 const xpiName = `${base}-${version}.xpi`;
 
 // Identical contents; the .xpi extension is just what Firefox expects.
-const zipBytes = await zipTo(path.join(root, zipName), INCLUDE);
-await zipTo(path.join(root, xpiName), INCLUDE);
+const zipBytes = await zipTo(path.join(root, zipName), files);
+await zipTo(path.join(root, xpiName), files);
 
-console.log(`Built ${name} v${version}`);
+console.log(`Built ${name} v${version} (${files.length} files)`);
 console.log(`  ${zipName} (${zipBytes} bytes)`);
 console.log(`  ${xpiName}`);
diff --git a/test/build.test.mjs b/test/build.test.mjs
new file mode 100644
index 0000000..893b6b8
--- /dev/null
+++ b/test/build.test.mjs
@@ -0,0 +1,70 @@
+// Integration test for scripts/build.mjs: run the real packaging script
+// and verify the archive contains every file the browser will ask for.
+// This guards against the class of bug where a script is added to
+// manifest.json but the release archive doesn't ship it (which once
+// happened with checks.js, producing broken store builds).
+
+import { describe, it, expect, beforeAll } from "vitest";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const run = promisify(execFile);
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const zipPath = path.join(root, "github-pr-reverse-comments.zip");
+
+/** @type {string[]} */
+let entries = [];
+let manifest;
+
+beforeAll(async () => {
+  manifest = JSON.parse(await readFile(path.join(root, "manifest.json"), "utf8"));
+  await run("node", [path.join(root, "scripts", "build.mjs")]);
+  const { stdout } = await run("unzip", ["-Z1", zipPath]);
+  entries = stdout.split(/\r?\n/).filter(Boolean);
+}, 30_000);
+
+describe("packaged archive", () => {
+  it("contains the manifest itself", () => {
+    expect(entries).toContain("manifest.json");
+  });
+
+  it("contains every content script listed in manifest.json", () => {
+    for (const cs of manifest.content_scripts) {
+      for (const f of cs.js) expect(entries).toContain(f);
+    }
+  });
+
+  it("contains the background scripts", () => {
+    expect(entries).toContain(manifest.background.service_worker);
+    for (const f of manifest.background.scripts) expect(entries).toContain(f);
+  });
+
+  it("contains the popup page and the scripts it loads", async () => {
+    const popup = manifest.action.default_popup;
+    expect(entries).toContain(popup);
+    const html = await readFile(path.join(root, popup), "utf8");
+    for (const [, src] of html.matchAll(/<script\s+[^>]*src="([^"]+)"/g)) {
+      expect(entries).toContain(src);
+    }
+  });
+
+  it("contains every icon referenced by the manifest", () => {
+    for (const f of Object.values(manifest.icons)) expect(entries).toContain(f);
+    for (const f of Object.values(manifest.action.default_icon)) expect(entries).toContain(f);
+  });
+
+  it("ships no dev-only files", () => {
+    const forbidden = entries.filter(
+      (e) =>
+        e.startsWith("node_modules/") ||
+        e.startsWith("test/") ||
+        e.startsWith(".github/") ||
+        /\.(mjs|md|lock)$/.test(e) ||
+        e.startsWith("."),
+    );
+    expect(forbidden).toEqual([]);
+  });
+});

From 27c6b3ddb8f2400afa58ce413628871d25d85c52 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 14 Jul 2026 17:32:42 +0000
Subject: [PATCH 02/10] Wire the 128px icon variants into the action icon set

icon-128-disabled.png existed in the repo but was referenced nowhere;
add both 128px variants to the action icons so high-DPI toolbars get a
crisp icon and the asset ships for a reason.

Co-authored-by: Julius Walton <ShiosOS@users.noreply.github.com>
---
 background.js | 8 ++++++--
 manifest.json | 3 ++-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/background.js b/background.js
index 96226fa..c4e327c 100644
--- a/background.js
+++ b/background.js
@@ -9,8 +9,12 @@
 // so the icon updates correctly even when the user navigates to a
 // non-PR URL (where the content script doesn't run).
 
-const ACTIVE_PATH = { 16: "icon-16.png", 48: "icon-48.png" };
-const DISABLED_PATH = { 16: "icon-16-disabled.png", 48: "icon-48-disabled.png" };
+const ACTIVE_PATH = { 16: "icon-16.png", 48: "icon-48.png", 128: "icon-128.png" };
+const DISABLED_PATH = {
+  16: "icon-16-disabled.png",
+  48: "icon-48-disabled.png",
+  128: "icon-128-disabled.png",
+};
 
 // Matches any PR page the extension is active on:
 //   /owner/repo/pull/N            (Conversation)
diff --git a/manifest.json b/manifest.json
index ee5808b..6e06488 100644
--- a/manifest.json
+++ b/manifest.json
@@ -14,7 +14,8 @@
     "default_title": "GitHub PR Reverse Comments",
     "default_icon": {
       "16": "icon-16-disabled.png",
-      "48": "icon-48-disabled.png"
+      "48": "icon-48-disabled.png",
+      "128": "icon-128-disabled.png"
     },
     "default_popup": "popup.html"
   },

From bf5a92c59446d7aaffe0f4c6f2531890575a4d65 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 14 Jul 2026 17:32:54 +0000
Subject: [PATCH 03/10] Harden preference handling, live checks refresh, popup
 sync, and a11y

- normalizeOrder() in constants.js coerces whatever comes out of
  chrome.storage into a valid order value, so a stale or corrupted
  entry can no longer desync the toggle label from the sort behavior.
- The popup mirrors chrome.storage.onChanged, so toggling via the
  in-page button updates an open popup immediately.
- The body observer also watches aria-label mutations: GitHub updates
  check-row labels in place (running -> successful) without structural
  changes, which previously left the checks indicator stale.
- The injected toggle and checks indicator get plain-text aria-labels;
  the visible text leans on glyphs and color alone.

Co-authored-by: Julius Walton <ShiosOS@users.noreply.github.com>
---
 constants.js            | 20 ++++++++++++++------
 content.js              | 23 +++++++++++++++++++----
 eslint.config.mjs       |  1 +
 popup.js                | 12 ++++++++++--
 test/constants.test.mjs | 19 +++++++++++++++++++
 types/globals.d.ts      |  1 +
 6 files changed, 64 insertions(+), 12 deletions(-)
 create mode 100644 test/constants.test.mjs

diff --git a/constants.js b/constants.js
index f54d504..c1437e1 100644
--- a/constants.js
+++ b/constants.js
@@ -15,10 +15,18 @@
     Object.assign(root, factory());
   }
 })(typeof globalThis !== "undefined" ? globalThis : this, function () {
-  return {
-    // chrome.storage.local key holding the user's order preference.
-    STORAGE_KEY: "prCommentOrder",
-    // Allowed values for that preference.
-    ORDER: { NEWEST: "newest", OLDEST: "oldest" },
-  };
+  // chrome.storage.local key holding the user's order preference.
+  const STORAGE_KEY = "prCommentOrder";
+  // Allowed values for that preference.
+  const ORDER = { NEWEST: "newest", OLDEST: "oldest" };
+
+  // Coerce whatever came out of storage into a valid order value. Storage
+  // is a system boundary: a stale or corrupted value must not leave the
+  // button label saying one thing while the sort does another.
+  /** @param {unknown} value */
+  function normalizeOrder(value) {
+    return value === ORDER.OLDEST ? ORDER.OLDEST : ORDER.NEWEST;
+  }
+
+  return { STORAGE_KEY, ORDER, normalizeOrder };
 });
diff --git a/content.js b/content.js
index 3e328e1..552f32e 100644
--- a/content.js
+++ b/content.js
@@ -302,6 +302,9 @@
       indicator.textContent = state.label;
       indicator.style.border = `1px solid ${state.color}`;
       indicator.style.color = state.color;
+      // The visible label leans on color and a glyph (✓/✗/•); spell the
+      // status out for assistive tech.
+      indicator.setAttribute("aria-label", `PR status checks: ${state.key}. Jump to checks`);
     }
 
     if (indicator !== anchor.previousElementSibling) {
@@ -311,13 +314,16 @@
 
   /** @param {HTMLElement} btn */
   function updateButtonLabel(btn) {
+    const next = currentOrder === ORDER.NEWEST ? ORDER.OLDEST : ORDER.NEWEST;
     btn.textContent = currentOrder === ORDER.NEWEST ? "↓ Newest first" : "↑ Oldest first";
-    btn.title = `Click to switch to ${currentOrder === ORDER.NEWEST ? ORDER.OLDEST : ORDER.NEWEST} first`;
+    btn.title = `Click to switch to ${next} first`;
+    // The arrow glyph is decorative; give assistive tech a plain-text label.
+    btn.setAttribute("aria-label", `Comment order: ${currentOrder} first. Switch to ${next} first`);
   }
 
   chrome.storage.onChanged.addListener((changes, area) => {
     if (area !== "local" || !changes[STORAGE_KEY]) return;
-    currentOrder = /** @type {string} */ (changes[STORAGE_KEY].newValue || ORDER.NEWEST);
+    currentOrder = normalizeOrder(changes[STORAGE_KEY].newValue);
     const btn = document.getElementById(BUTTON_ID);
     if (btn) updateButtonLabel(btn);
     applyOrder(currentOrder);
@@ -371,7 +377,16 @@
 
   function startBodyWatcher() {
     const bodyObs = new MutationObserver(scheduleRebindIfNeeded);
-    bodyObs.observe(document.body, { childList: true, subtree: true });
+    // aria-label is watched because GitHub updates a check row's label in
+    // place (e.g. "in progress" -> "successful") without any structural
+    // mutation; without it the checks indicator would go stale until some
+    // unrelated DOM churn happened to fire the observer.
+    bodyObs.observe(document.body, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["aria-label"],
+    });
   }
 
   async function init() {
@@ -381,7 +396,7 @@
       await chrome.storage.local.set({ [RESET_VERSION_KEY]: CURRENT_RESET_VERSION });
       currentOrder = ORDER.NEWEST;
     } else {
-      currentOrder = /** @type {string} */ (stored[STORAGE_KEY] || ORDER.NEWEST);
+      currentOrder = normalizeOrder(stored[STORAGE_KEY]);
     }
 
     startBodyWatcher();
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 37fc335..29ac235 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -7,6 +7,7 @@ import prettier from "eslint-config-prettier";
 const sharedGlobals = {
   STORAGE_KEY: "readonly",
   ORDER: "readonly",
+  normalizeOrder: "readonly",
   firstMatchingTarget: "readonly",
   pushedCommitTargets: "readonly",
   applyOrderToTarget: "readonly",
diff --git a/popup.js b/popup.js
index d3f7c95..52166a8 100644
--- a/popup.js
+++ b/popup.js
@@ -1,5 +1,6 @@
 // @ts-check
-// STORAGE_KEY and ORDER come from constants.js (loaded first in popup.html).
+// STORAGE_KEY, ORDER, and normalizeOrder come from constants.js (loaded
+// first in popup.html).
 
 const buttons = {
   [ORDER.NEWEST]: document.getElementById("newest"),
@@ -14,7 +15,7 @@ function render(order) {
 
 async function init() {
   const stored = await chrome.storage.local.get(STORAGE_KEY);
-  render(/** @type {string} */ (stored[STORAGE_KEY] || ORDER.NEWEST));
+  render(normalizeOrder(stored[STORAGE_KEY]));
 }
 
 for (const [order, btn] of Object.entries(buttons)) {
@@ -24,4 +25,11 @@ for (const [order, btn] of Object.entries(buttons)) {
   });
 }
 
+// Keep the popup in step with the in-page toggle button: both write the
+// same storage key, so a change from either side re-renders here.
+chrome.storage.onChanged.addListener((changes, area) => {
+  if (area !== "local" || !changes[STORAGE_KEY]) return;
+  render(normalizeOrder(changes[STORAGE_KEY].newValue));
+});
+
 init();
diff --git a/test/constants.test.mjs b/test/constants.test.mjs
new file mode 100644
index 0000000..4ae16be
--- /dev/null
+++ b/test/constants.test.mjs
@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest";
+import constants from "../constants.js";
+
+const { ORDER, normalizeOrder } = constants;
+
+describe("normalizeOrder", () => {
+  it("passes through the two valid values", () => {
+    expect(normalizeOrder(ORDER.NEWEST)).toBe(ORDER.NEWEST);
+    expect(normalizeOrder(ORDER.OLDEST)).toBe(ORDER.OLDEST);
+  });
+
+  it("falls back to newest for anything else from storage", () => {
+    expect(normalizeOrder(undefined)).toBe(ORDER.NEWEST);
+    expect(normalizeOrder(null)).toBe(ORDER.NEWEST);
+    expect(normalizeOrder("")).toBe(ORDER.NEWEST);
+    expect(normalizeOrder("descending")).toBe(ORDER.NEWEST);
+    expect(normalizeOrder(42)).toBe(ORDER.NEWEST);
+  });
+});
diff --git a/types/globals.d.ts b/types/globals.d.ts
index 4e4a675..b0c8d42 100644
--- a/types/globals.d.ts
+++ b/types/globals.d.ts
@@ -21,6 +21,7 @@ interface PrrcChecksState {
 // (the UMD modules read `globalThis.ORDER`).
 declare var STORAGE_KEY: string;
 declare var ORDER: { NEWEST: string; OLDEST: string };
+declare function normalizeOrder(value: unknown): string;
 
 // reorder.js
 declare function firstMatchingTarget(

From f89dd6f0b60f45bbe1ac0331b311420c085279f4 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 14 Jul 2026 17:32:54 +0000
Subject: [PATCH 04/10] Update docs, package metadata, and dev-dependency audit

- README: document checks.js in the file table, list the typecheck
  script, and correct the test command description.
- package.json: add repository, homepage, and bugs fields.
- CHANGELOG: record the packaging fix and behavior changes under
  Unreleased.
- npm audit fix: bump transitive undici (jsdom) past known advisories.

Co-authored-by: Julius Walton <ShiosOS@users.noreply.github.com>
---
 CHANGELOG.md      | 21 +++++++++++++++++++++
 README.md         |  4 +++-
 package-lock.json |  6 +++---
 package.json      |  8 ++++++++
 4 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa786e2..329e736 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Release packaging omitted `checks.js`, so published `.zip`/`.xpi` builds
+  shipped without the status-checks helpers the content script depends on.
+  The packaged file list is now derived from `manifest.json` (plus popup
+  `<script>` tags) instead of being hand-maintained, missing files fail the
+  build, and a packaging test verifies the archive contents in CI.
+- The status-checks indicator now refreshes when GitHub updates a check's
+  label in place (e.g. running → successful) instead of waiting for
+  unrelated DOM changes.
+- The popup now reflects a preference change made via the in-page toggle
+  while it is open.
+- A corrupted stored preference value no longer desyncs the toggle label
+  from the actual sort order; anything unrecognized falls back to newest.
+
+### Added
+
+- Accessible labels (`aria-label`) on the injected toggle button and
+  status-checks indicator.
+- 128px toolbar icon variants wired into the action icon set.
+
 ## [1.1.0] - 2026-06-04
 
 ### Added
diff --git a/README.md b/README.md
index a65701c..4ab0740 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,7 @@ in Firefox), and refresh a PR page.
 | `manifest.json` | Extension definition (Manifest V3, Chrome + Firefox)  |
 | `constants.js`  | Shared constants (storage key, order values)          |
 | `reorder.js`    | Pure DOM-reordering helpers (unit-tested)             |
+| `checks.js`     | PR status-checks detection helpers (unit-tested)      |
 | `content.js`    | Runs on PR pages; reorders comments, draws the toggle |
 | `background.js` | Keeps the toolbar icon in sync with the current tab   |
 | `popup.html`    | Toolbar popup UI                                      |
@@ -134,7 +135,8 @@ extension — they only help when contributing.
 npm install      # install dev dependencies
 npm run lint     # ESLint
 npm run format   # Prettier (writes)
-npm test         # Vitest unit tests for reorder.js
+npm run typecheck # tsc --checkJs over the extension sources
+npm test         # Vitest unit tests (reorder, checks, constants, packaging)
 npm run build    # produce the .zip / .xpi (version read from manifest.json)
 ```
 
diff --git a/package-lock.json b/package-lock.json
index 5c68e1b..ffb6331 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -4058,9 +4058,9 @@
       }
     },
     "node_modules/undici": {
-      "version": "7.27.0",
-      "resolved": "https://registry.npmjs.org/undici/-/undici-7.27.0.tgz",
-      "integrity": "sha512-+t2Z/GwkZQDtu00813aP66ygViGtPHKhhoFZpQKpKrE+9jIgES+Zw+mFNaDWOVRKiuJjuqKHzD3B1sfGg8+ZOQ==",
+      "version": "7.28.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-7.28.0.tgz",
+      "integrity": "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==",
       "dev": true,
       "license": "MIT",
       "engines": {
diff --git a/package.json b/package.json
index d1106b5..2e8087f 100644
--- a/package.json
+++ b/package.json
@@ -3,6 +3,14 @@
   "version": "1.1.0",
   "description": "Dev tooling for the GitHub PR Reverse Comments browser extension. The extension itself has no build step; these scripts only lint, format, test, and package it.",
   "private": true,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShiosOS/github-pr-reverse-comments.git"
+  },
+  "homepage": "https://github.com/ShiosOS/github-pr-reverse-comments#readme",
+  "bugs": {
+    "url": "https://github.com/ShiosOS/github-pr-reverse-comments/issues"
+  },
   "engines": {
     "node": ">=22"
   },

From 74139cea0afa2c718d41b95033d1aa09423ba08a Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 14 Jul 2026 17:43:17 +0000
Subject: [PATCH 05/10] Extract GitHub DOM selectors to pages.js and make
 background.js testable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The selectors that break when GitHub ships UI changes — the extension's
main maintenance burden — lived untested inside content.js. They now
live in pages.js (same UMD pattern as the other modules) with jsdom
tests whose fixtures mirror the real Conversation, modern React
Commits, and legacy Rails Commits structures, plus path-routing tests.
content.js shrinks to observer/storage/UI glue.

background.js gets the same treatment: logic in a factory that Node
tests exercise against a stubbed chrome API, with listener registration
kept synchronous at load (an MV3 service-worker requirement). Tests
cover URL matching (incl. rejecting /files, /checks, commit permalinks,
non-GitHub hosts), icon selection, tab-event handling, and the
runtime.lastError path.

Both modules join the coverage gate; content.js also stops silently
swallowing storage failures at init (logs instead of an unhandled
rejection), and the stored-order/checks-state types tighten from string
to unions.

Co-authored-by: Julius Walton <ShiosOS@users.noreply.github.com>
---
 background.js            | 121 ++++++++++++++++----------
 content.js               | 130 +++-------------------------
 eslint.config.mjs        |   7 +-
 manifest.json            |   2 +-
 pages.js                 | 156 +++++++++++++++++++++++++++++++++
 test/background.test.mjs | 148 +++++++++++++++++++++++++++++++
 test/pages.test.mjs      | 182 +++++++++++++++++++++++++++++++++++++++
 tsconfig.json            |   1 +
 types/globals.d.ts       |  26 ++++--
 vitest.config.mjs        |   9 +-
 10 files changed, 599 insertions(+), 183 deletions(-)
 create mode 100644 pages.js
 create mode 100644 test/background.test.mjs
 create mode 100644 test/pages.test.mjs

diff --git a/background.js b/background.js
index c4e327c..c89f07a 100644
--- a/background.js
+++ b/background.js
@@ -8,60 +8,87 @@
 // We use chrome.tabs events instead of messages from the content script
 // so the icon updates correctly even when the user navigates to a
 // non-PR URL (where the content script doesn't run).
+//
+// Structured like the other modules: the logic lives in a factory so
+// Node tests can import and exercise it against a stubbed chrome API,
+// while listener registration stays synchronous at load time (an MV3
+// service-worker requirement — events fired while the worker was asleep
+// are only redelivered to listeners registered during startup).
 
-const ACTIVE_PATH = { 16: "icon-16.png", 48: "icon-48.png", 128: "icon-128.png" };
-const DISABLED_PATH = {
-  16: "icon-16-disabled.png",
-  48: "icon-48-disabled.png",
-  128: "icon-128-disabled.png",
-};
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== "undefined" && module.exports) {
+    module.exports = api;
+  } else {
+    Object.assign(root, api);
+  }
 
-// Matches any PR page the extension is active on:
-//   /owner/repo/pull/N            (Conversation)
-//   /owner/repo/pull/N/commits    (Commits)
-// All other sub-paths (/files, /checks, deep diff anchors) leave the
-// toolbar icon in the disabled state.
-const ACTIVE_URL_RE =
-  /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+(?:\/commits)?\/?(?:[?#].*)?$/;
+  if (typeof chrome !== "undefined" && chrome.runtime) {
+    chrome.runtime.onInstalled.addListener(api.syncAllTabs);
+    chrome.runtime.onStartup.addListener(api.syncAllTabs);
+    chrome.tabs.onUpdated.addListener(api.handleTabUpdated);
+    chrome.tabs.onActivated.addListener(api.handleTabActivated);
+  }
+})(typeof globalThis !== "undefined" ? globalThis : this, function () {
+  const ACTIVE_PATH = { 16: "icon-16.png", 48: "icon-48.png", 128: "icon-128.png" };
+  const DISABLED_PATH = {
+    16: "icon-16-disabled.png",
+    48: "icon-48-disabled.png",
+    128: "icon-128-disabled.png",
+  };
 
-/** @param {unknown} url */
-function isActiveUrl(url) {
-  return typeof url === "string" && ACTIVE_URL_RE.test(url);
-}
+  // Matches any PR page the extension is active on:
+  //   /owner/repo/pull/N            (Conversation)
+  //   /owner/repo/pull/N/commits    (Commits)
+  // All other sub-paths (/files, /checks, deep diff anchors) leave the
+  // toolbar icon in the disabled state.
+  const ACTIVE_URL_RE =
+    /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+(?:\/commits)?\/?(?:[?#].*)?$/;
 
-/**
- * @param {number | undefined} tabId
- * @param {string | undefined} url
- */
-function setIconForTab(tabId, url) {
-  const path = isActiveUrl(url) ? ACTIVE_PATH : DISABLED_PATH;
-  chrome.action.setIcon({ tabId, path }).catch(() => {
-    // Tab may have been closed between the event and our call; ignore.
-  });
-}
+  /** @param {unknown} url */
+  function isActiveUrl(url) {
+    return typeof url === "string" && ACTIVE_URL_RE.test(url);
+  }
 
-// Initial state on install / browser start: walk existing tabs.
-function syncAllTabs() {
-  chrome.tabs.query({}, (tabs) => {
-    for (const tab of tabs) setIconForTab(tab.id, tab.url);
-  });
-}
+  /**
+   * @param {number | undefined} tabId
+   * @param {string | undefined} url
+   */
+  function setIconForTab(tabId, url) {
+    const path = isActiveUrl(url) ? ACTIVE_PATH : DISABLED_PATH;
+    chrome.action.setIcon({ tabId, path }).catch(() => {
+      // Tab may have been closed between the event and our call; ignore.
+    });
+  }
 
-chrome.runtime.onInstalled.addListener(syncAllTabs);
-chrome.runtime.onStartup.addListener(syncAllTabs);
+  // Initial state on install / browser start: walk existing tabs.
+  function syncAllTabs() {
+    chrome.tabs.query({}, (tabs) => {
+      for (const tab of tabs) setIconForTab(tab.id, tab.url);
+    });
+  }
 
-// URL changes — covers both full page loads and pushState/replaceState soft nav.
-chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
-  if (changeInfo.url || changeInfo.status === "complete") {
-    setIconForTab(tabId, changeInfo.url || tab.url);
+  // URL changes — covers both full page loads and pushState/replaceState soft nav.
+  /**
+   * @param {number} tabId
+   * @param {chrome.tabs.OnUpdatedInfo} changeInfo
+   * @param {chrome.tabs.Tab} tab
+   */
+  function handleTabUpdated(tabId, changeInfo, tab) {
+    if (changeInfo.url || changeInfo.status === "complete") {
+      setIconForTab(tabId, changeInfo.url || tab.url);
+    }
+  }
+
+  // Tab activation — make sure the toolbar reflects the now-focused tab
+  // even if it was opened/loaded in the background.
+  /** @param {{ tabId: number }} activeInfo */
+  function handleTabActivated({ tabId }) {
+    chrome.tabs.get(tabId, (tab) => {
+      if (chrome.runtime.lastError) return;
+      setIconForTab(tabId, tab.url);
+    });
   }
-});
 
-// Tab activation — make sure the toolbar reflects the now-focused tab
-// even if it was opened/loaded in the background.
-chrome.tabs.onActivated.addListener(({ tabId }) => {
-  chrome.tabs.get(tabId, (tab) => {
-    if (chrome.runtime.lastError) return;
-    setIconForTab(tabId, tab.url);
-  });
+  return { isActiveUrl, setIconForTab, syncAllTabs, handleTabUpdated, handleTabActivated };
 });
diff --git a/content.js b/content.js
index 552f32e..7ad1fb1 100644
--- a/content.js
+++ b/content.js
@@ -13,128 +13,15 @@
 // page. Non-supported PR sub-tabs (Files Changed, Checks) are ignored.
 
 (() => {
-  // STORAGE_KEY and ORDER come from constants.js (loaded first);
-  // firstMatchingTarget and applyOrderToTarget come from reorder.js.
+  // STORAGE_KEY, ORDER, and normalizeOrder come from constants.js (loaded
+  // first); applyOrderToTarget from reorder.js; getPageConfig (and every
+  // GitHub DOM selector) from pages.js; the checks helpers from checks.js.
   const RESET_VERSION_KEY = "prrcDefaultResetVersion";
   const CURRENT_RESET_VERSION = 1;
   const BUTTON_ID = "pr-reverse-comments-toggle";
   const CHECKS_STATUS_ID = "pr-reverse-comments-checks-status";
 
-  // Per-page configuration. `getTargets()` returns an array of
-  //   { el, item, descendant }
-  // — one entry per DOM region that should be reversed. Conversation has
-  // exactly one (the timeline); Commits has many (the list of date
-  // groups, plus the inner <ol> of every individual date group).
-  const PAGE_CONFIGS = [
-    {
-      name: "conversation",
-      pathRe: /^\/[^/]+\/[^/]+\/pull\/\d+\/?$/,
-      getTargets: () => {
-        const candidates = [
-          { container: ".js-discussion", item: ".js-timeline-item" },
-          {
-            container: '[data-testid="issue-viewer-issue-container"]',
-            item: '[data-testid^="issue-viewer-comment"]',
-          },
-          { container: '[data-testid="pr-timeline"]', item: '[data-testid^="pr-timeline-item"]' },
-          { container: ".pull-discussion-timeline", item: ".js-timeline-item" },
-        ];
-        const t = firstMatchingTarget(candidates);
-        const targets = t ? [t] : [];
-
-        // The batch as a whole is one .js-timeline-item (reversed by the
-        // target above); also reverse the individual commits inside each
-        // "added N commits" batch so they read newest-first too.
-        targets.push(...pushedCommitTargets());
-
-        return targets;
-      },
-    },
-    {
-      name: "commits",
-      pathRe: /^\/[^/]+\/[^/]+\/pull\/\d+\/commits\/?$/,
-      getTargets: () => {
-        const targets = [];
-
-        // Modern React-rendered Commits page. Structure (May 2026):
-        //   <div data-testid="commits-list">
-        //     <div class="prc-Timeline-Timeline-...">              ← Timeline wrapper
-        //       <div class="… Timeline-Item …">                    ← day group N
-        //         <h3 data-testid="commit-group-title">Commits on …</h3>
-        //         <ul data-listview-component="items-list">
-        //           <li data-testid="commit-row-item">…</li>       ← commit within day
-        //           …
-        //         </ul>
-        //       </div>
-        //       <div class="… Timeline-Item …">…</div>             ← day group N+1
-        //       …
-        //     </div>
-        //   </div>
-        //
-        // To make "newest first" feel right we have to reverse two
-        // levels at once: the .Timeline-Item day groups (so the most
-        // recent day moves to the top), AND the <li> commits inside
-        // each day's <ul> (so within a day the latest commit is on
-        // top). Doing only one of them gives a confusing half-flipped
-        // result.
-        const commitsList = document.querySelector('[data-testid="commits-list"]');
-        if (commitsList) {
-          const dayGroups = commitsList.querySelectorAll(".Timeline-Item");
-
-          // 1) Reverse the day groups themselves (only meaningful if 2+).
-          if (dayGroups.length >= 2) {
-            const dayParent = dayGroups[0].parentElement;
-            if (dayParent) {
-              targets.push({
-                el: dayParent,
-                item: ".Timeline-Item",
-                descendant: false,
-              });
-            }
-          }
-
-          // 2) Reverse commits within each day's <ul>.
-          for (const group of dayGroups) {
-            const ul = group.querySelector('ul[data-listview-component="items-list"]');
-            if (
-              ul &&
-              ul.querySelectorAll(':scope > li[data-testid="commit-row-item"]').length >= 2
-            ) {
-              targets.push({
-                el: ul,
-                item: 'li[data-testid="commit-row-item"]',
-                descendant: false,
-              });
-            }
-          }
-
-          if (targets.length) return targets;
-        }
-
-        // Legacy Rails-rendered Commits page: .js-commit-group date
-        // groups wrapping per-day ordered lists.
-        const groupTarget = firstMatchingTarget([
-          { container: ".js-commits-list", item: ".js-commit-group" },
-          { container: "#commits_bucket", item: ".js-commit-group" },
-        ]);
-        if (groupTarget) targets.push(groupTarget);
-
-        for (const group of document.querySelectorAll(".js-commit-group")) {
-          const ol = group.querySelector("ol");
-          if (ol && ol.querySelectorAll(":scope > li").length >= 2) {
-            targets.push({
-              el: ol,
-              item: ":scope > li",
-              descendant: false,
-            });
-          }
-        }
-
-        return targets;
-      },
-    },
-  ];
-
+  /** @type {PrrcOrder} */
   let currentOrder = ORDER.NEWEST;
   let isSorting = false;
   /** @type {MutationObserver[]} */
@@ -143,8 +30,7 @@
   let activeTargets = []; // [{ el, item, ... }]
 
   function getCurrentPageConfig() {
-    const path = location.pathname;
-    return PAGE_CONFIGS.find((c) => c.pathRe.test(path)) || null;
+    return getPageConfig(location.pathname);
   }
 
   function onSupportedPage() {
@@ -407,7 +293,11 @@
     scheduleRebindIfNeeded();
   }
 
-  init();
+  init().catch((err) => {
+    // A storage failure here leaves the extension inert on this page; make
+    // the cause visible instead of an unhandled rejection.
+    console.error("[pr-reverse-comments] initialization failed:", err);
+  });
 
   // Fast paths for the soft-nav events GitHub does fire — avoid waiting
   // for the next DOM mutation tick. The body watcher above is the real
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 29ac235..291673d 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -11,6 +11,7 @@ const sharedGlobals = {
   firstMatchingTarget: "readonly",
   pushedCommitTargets: "readonly",
   applyOrderToTarget: "readonly",
+  getPageConfig: "readonly",
   findChecksBox: "readonly",
   getCheckLabels: "readonly",
   deriveChecksState: "readonly",
@@ -24,7 +25,7 @@ export default [
   // UMD modules: run in the browser (extension) AND under Node (tests),
   // so they legitimately reference both `globalThis`/window and module.
   {
-    files: ["constants.js", "reorder.js", "checks.js"],
+    files: ["constants.js", "reorder.js", "checks.js", "pages.js"],
     languageOptions: {
       globals: { ...globals.browser, ...globals.node, ...sharedGlobals },
     },
@@ -38,11 +39,11 @@ export default [
     },
   },
 
-  // Background service worker.
+  // Background service worker (UMD so its logic is testable under Node).
   {
     files: ["background.js"],
     languageOptions: {
-      globals: { ...globals.serviceworker, chrome: "readonly" },
+      globals: { ...globals.serviceworker, ...globals.node, chrome: "readonly" },
     },
   },
 
diff --git a/manifest.json b/manifest.json
index 6e06488..b444597 100644
--- a/manifest.json
+++ b/manifest.json
@@ -26,7 +26,7 @@
   "content_scripts": [
     {
       "matches": ["https://github.com/*/*/pull/*"],
-      "js": ["constants.js", "reorder.js", "checks.js", "content.js"],
+      "js": ["constants.js", "reorder.js", "checks.js", "pages.js", "content.js"],
       "run_at": "document_idle"
     }
   ],
diff --git a/pages.js b/pages.js
new file mode 100644
index 0000000..d85a0fe
--- /dev/null
+++ b/pages.js
@@ -0,0 +1,156 @@
+// @ts-check
+// Per-page target configuration: which URL paths the extension acts on and
+// which DOM regions get reversed there. This is where all the GitHub DOM
+// selectors live — the part most likely to break when GitHub ships a UI
+// change — so it is factored out of content.js and unit-tested under jsdom
+// with fixtures mirroring the real page structures.
+//
+// `getTargets()` returns an array of { el, item, descendant } — one entry
+// per DOM region that should be reversed. Conversation has one (the
+// timeline) plus one per "added N commits" batch; Commits has many (the
+// list of date groups, plus the inner list of every individual date group).
+//
+// Browser: attaches getPageConfig to the global scope (loaded after
+// reorder.js, before content.js). Node: exports it for tests.
+
+(function (root, factory) {
+  if (typeof module !== "undefined" && module.exports) {
+    const { firstMatchingTarget, pushedCommitTargets } = require("./reorder.js");
+    module.exports = factory(firstMatchingTarget, pushedCommitTargets);
+  } else {
+    const r = /** @type {*} */ (root);
+    Object.assign(root, factory(r.firstMatchingTarget, r.pushedCommitTargets));
+  }
+})(
+  typeof globalThis !== "undefined" ? globalThis : this,
+  function (
+    /** @type {(candidates: { container: string; item: string }[]) => PrrcTarget | null} */
+    firstMatchingTarget,
+    /** @type {(root?: ParentNode) => PrrcTarget[]} */
+    pushedCommitTargets,
+  ) {
+    /** @type {PrrcPageConfig[]} */
+    const PAGE_CONFIGS = [
+      {
+        name: "conversation",
+        pathRe: /^\/[^/]+\/[^/]+\/pull\/\d+\/?$/,
+        getTargets: () => {
+          const candidates = [
+            { container: ".js-discussion", item: ".js-timeline-item" },
+            {
+              container: '[data-testid="issue-viewer-issue-container"]',
+              item: '[data-testid^="issue-viewer-comment"]',
+            },
+            {
+              container: '[data-testid="pr-timeline"]',
+              item: '[data-testid^="pr-timeline-item"]',
+            },
+            { container: ".pull-discussion-timeline", item: ".js-timeline-item" },
+          ];
+          const t = firstMatchingTarget(candidates);
+          const targets = t ? [t] : [];
+
+          // The batch as a whole is one .js-timeline-item (reversed by the
+          // target above); also reverse the individual commits inside each
+          // "added N commits" batch so they read newest-first too.
+          targets.push(...pushedCommitTargets());
+
+          return targets;
+        },
+      },
+      {
+        name: "commits",
+        pathRe: /^\/[^/]+\/[^/]+\/pull\/\d+\/commits\/?$/,
+        getTargets: () => {
+          /** @type {PrrcTarget[]} */
+          const targets = [];
+
+          // Modern React-rendered Commits page. Structure (May 2026):
+          //   <div data-testid="commits-list">
+          //     <div class="prc-Timeline-Timeline-...">              ← Timeline wrapper
+          //       <div class="… Timeline-Item …">                    ← day group N
+          //         <h3 data-testid="commit-group-title">Commits on …</h3>
+          //         <ul data-listview-component="items-list">
+          //           <li data-testid="commit-row-item">…</li>       ← commit within day
+          //           …
+          //         </ul>
+          //       </div>
+          //       <div class="… Timeline-Item …">…</div>             ← day group N+1
+          //       …
+          //     </div>
+          //   </div>
+          //
+          // To make "newest first" feel right we have to reverse two
+          // levels at once: the .Timeline-Item day groups (so the most
+          // recent day moves to the top), AND the <li> commits inside
+          // each day's <ul> (so within a day the latest commit is on
+          // top). Doing only one of them gives a confusing half-flipped
+          // result.
+          const commitsList = document.querySelector('[data-testid="commits-list"]');
+          if (commitsList) {
+            const dayGroups = commitsList.querySelectorAll(".Timeline-Item");
+
+            // 1) Reverse the day groups themselves (only meaningful if 2+).
+            if (dayGroups.length >= 2) {
+              const dayParent = dayGroups[0].parentElement;
+              if (dayParent) {
+                targets.push({
+                  el: dayParent,
+                  item: ".Timeline-Item",
+                  descendant: false,
+                });
+              }
+            }
+
+            // 2) Reverse commits within each day's <ul>.
+            for (const group of dayGroups) {
+              const ul = group.querySelector('ul[data-listview-component="items-list"]');
+              if (
+                ul &&
+                ul.querySelectorAll(':scope > li[data-testid="commit-row-item"]').length >= 2
+              ) {
+                targets.push({
+                  el: ul,
+                  item: 'li[data-testid="commit-row-item"]',
+                  descendant: false,
+                });
+              }
+            }
+
+            if (targets.length) return targets;
+          }
+
+          // Legacy Rails-rendered Commits page: .js-commit-group date
+          // groups wrapping per-day ordered lists.
+          const groupTarget = firstMatchingTarget([
+            { container: ".js-commits-list", item: ".js-commit-group" },
+            { container: "#commits_bucket", item: ".js-commit-group" },
+          ]);
+          if (groupTarget) targets.push(groupTarget);
+
+          for (const group of document.querySelectorAll(".js-commit-group")) {
+            const ol = group.querySelector("ol");
+            if (ol && ol.querySelectorAll(":scope > li").length >= 2) {
+              targets.push({
+                el: ol,
+                item: ":scope > li",
+                descendant: false,
+              });
+            }
+          }
+
+          return targets;
+        },
+      },
+    ];
+
+    // The config whose pathRe matches the given location.pathname, or null
+    // on unsupported pages (Files Changed, Checks, issues, everything else).
+    /** @param {string} pathname */
+    function getPageConfig(pathname) {
+      return PAGE_CONFIGS.find((c) => c.pathRe.test(pathname)) || null;
+    }
+
+    return { getPageConfig };
+  },
+);
diff --git a/test/background.test.mjs b/test/background.test.mjs
new file mode 100644
index 0000000..c21a9ef
--- /dev/null
+++ b/test/background.test.mjs
@@ -0,0 +1,148 @@
+// background.js is exercised against a stubbed chrome API: the stub is
+// installed before the (dynamic) import so the module's synchronous
+// listener registration runs against it, exactly as it does in the browser.
+
+import { describe, it, expect, beforeAll, beforeEach, vi } from "vitest";
+
+const setIcon = vi.fn(() => Promise.resolve());
+const tabsQuery = vi.fn();
+const tabsGet = vi.fn();
+const fakeEvent = () => ({ addListener: vi.fn() });
+
+const chromeStub = {
+  runtime: { onInstalled: fakeEvent(), onStartup: fakeEvent(), lastError: undefined },
+  tabs: { onUpdated: fakeEvent(), onActivated: fakeEvent(), query: tabsQuery, get: tabsGet },
+  action: { setIcon },
+};
+
+let background;
+
+beforeAll(async () => {
+  globalThis.chrome = chromeStub;
+  background = (await import("../background.js")).default;
+});
+
+beforeEach(() => {
+  setIcon.mockClear();
+  tabsQuery.mockClear();
+  tabsGet.mockClear();
+  chromeStub.runtime.lastError = undefined;
+});
+
+describe("module load", () => {
+  it("registers all four event listeners synchronously", () => {
+    // MV3 requirement: listeners must attach during worker startup.
+    expect(chromeStub.runtime.onInstalled.addListener).toHaveBeenCalledWith(background.syncAllTabs);
+    expect(chromeStub.runtime.onStartup.addListener).toHaveBeenCalledWith(background.syncAllTabs);
+    expect(chromeStub.tabs.onUpdated.addListener).toHaveBeenCalledWith(background.handleTabUpdated);
+    expect(chromeStub.tabs.onActivated.addListener).toHaveBeenCalledWith(
+      background.handleTabActivated,
+    );
+  });
+});
+
+describe("isActiveUrl", () => {
+  it.each([
+    "https://github.com/owner/repo/pull/1",
+    "https://github.com/owner/repo/pull/123/",
+    "https://github.com/owner/repo/pull/123?diff=split",
+    "https://github.com/owner/repo/pull/123#issuecomment-1",
+    "https://github.com/owner/repo/pull/123/commits",
+    "https://github.com/owner/repo/pull/123/commits/?page=2",
+  ])("accepts %s", (url) => {
+    expect(background.isActiveUrl(url)).toBe(true);
+  });
+
+  it.each([
+    "https://github.com/owner/repo/pull/123/files",
+    "https://github.com/owner/repo/pull/123/checks",
+    "https://github.com/owner/repo/pull/123/commits/abc123",
+    "https://github.com/owner/repo/issues/123",
+    "https://github.com/owner/repo",
+    "https://github.com/owner/repo/pulls",
+    "http://github.com/owner/repo/pull/1", // not https
+    "https://example.com/owner/repo/pull/1", // not github.com
+    "https://github.evil.example/owner/repo/pull/1",
+    undefined,
+    42,
+  ])("rejects %s", (url) => {
+    expect(background.isActiveUrl(url)).toBe(false);
+  });
+});
+
+describe("setIconForTab", () => {
+  it("sets the active icon set on PR pages", () => {
+    background.setIconForTab(7, "https://github.com/o/r/pull/1");
+    expect(setIcon).toHaveBeenCalledWith({
+      tabId: 7,
+      path: { 16: "icon-16.png", 48: "icon-48.png", 128: "icon-128.png" },
+    });
+  });
+
+  it("sets the disabled icon set elsewhere (including unknown URLs)", () => {
+    background.setIconForTab(7, undefined);
+    expect(setIcon).toHaveBeenCalledWith({
+      tabId: 7,
+      path: {
+        16: "icon-16-disabled.png",
+        48: "icon-48-disabled.png",
+        128: "icon-128-disabled.png",
+      },
+    });
+  });
+
+  it("swallows setIcon rejections (tab closed mid-flight)", async () => {
+    setIcon.mockImplementationOnce(() => Promise.reject(new Error("No tab with id")));
+    background.setIconForTab(9, "https://github.com/o/r/pull/1");
+    // Must not surface as an unhandled rejection.
+    await new Promise((r) => setTimeout(r, 0));
+  });
+});
+
+describe("handleTabUpdated", () => {
+  it("updates on URL change", () => {
+    background.handleTabUpdated(1, { url: "https://github.com/o/r/pull/2" }, { id: 1 });
+    expect(setIcon).toHaveBeenCalledTimes(1);
+  });
+
+  it("updates on load completion using the tab's URL", () => {
+    background.handleTabUpdated(1, { status: "complete" }, { url: "https://github.com/o/r" });
+    expect(setIcon).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignores unrelated updates (e.g. title changes)", () => {
+    background.handleTabUpdated(1, { title: "New title" }, { id: 1 });
+    expect(setIcon).not.toHaveBeenCalled();
+  });
+});
+
+describe("handleTabActivated", () => {
+  it("looks the tab up and sets its icon", () => {
+    tabsGet.mockImplementation((tabId, cb) => cb({ id: tabId, url: "https://github.com/o/r" }));
+    background.handleTabActivated({ tabId: 3 });
+    expect(tabsGet).toHaveBeenCalledWith(3, expect.any(Function));
+    expect(setIcon).toHaveBeenCalledTimes(1);
+  });
+
+  it("bails out when the tab is already gone (runtime.lastError)", () => {
+    tabsGet.mockImplementation((tabId, cb) => {
+      chromeStub.runtime.lastError = { message: "No tab with id" };
+      cb(undefined);
+    });
+    background.handleTabActivated({ tabId: 3 });
+    expect(setIcon).not.toHaveBeenCalled();
+  });
+});
+
+describe("syncAllTabs", () => {
+  it("sets the icon for every open tab", () => {
+    tabsQuery.mockImplementation((_filter, cb) =>
+      cb([
+        { id: 1, url: "https://github.com/o/r/pull/1" },
+        { id: 2, url: "https://example.com" },
+      ]),
+    );
+    background.syncAllTabs();
+    expect(setIcon).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/test/pages.test.mjs b/test/pages.test.mjs
new file mode 100644
index 0000000..c2281fa
--- /dev/null
+++ b/test/pages.test.mjs
@@ -0,0 +1,182 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import pages from "../pages.js";
+
+const { getPageConfig } = pages;
+
+beforeEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("getPageConfig — path routing", () => {
+  it("matches the Conversation page, with and without a trailing slash", () => {
+    expect(getPageConfig("/owner/repo/pull/123")?.name).toBe("conversation");
+    expect(getPageConfig("/owner/repo/pull/123/")?.name).toBe("conversation");
+  });
+
+  it("matches the Commits page, with and without a trailing slash", () => {
+    expect(getPageConfig("/owner/repo/pull/123/commits")?.name).toBe("commits");
+    expect(getPageConfig("/owner/repo/pull/123/commits/")?.name).toBe("commits");
+  });
+
+  it("rejects unsupported PR sub-tabs and other pages", () => {
+    expect(getPageConfig("/owner/repo/pull/123/files")).toBeNull();
+    expect(getPageConfig("/owner/repo/pull/123/checks")).toBeNull();
+    expect(getPageConfig("/owner/repo/pull/123/commits/abc123")).toBeNull();
+    expect(getPageConfig("/owner/repo/issues/123")).toBeNull();
+    expect(getPageConfig("/owner/repo/pull/not-a-number")).toBeNull();
+    expect(getPageConfig("/owner/repo")).toBeNull();
+    expect(getPageConfig("/")).toBeNull();
+  });
+});
+
+describe("conversation targets", () => {
+  function buildTimeline(itemCount) {
+    const timeline = document.createElement("div");
+    timeline.className = "js-discussion";
+    for (let i = 0; i < itemCount; i++) {
+      const item = document.createElement("div");
+      item.className = "js-timeline-item";
+      timeline.appendChild(item);
+    }
+    document.body.appendChild(timeline);
+    return timeline;
+  }
+
+  it("targets the classic .js-discussion timeline", () => {
+    const timeline = buildTimeline(3);
+    const targets = getPageConfig("/o/r/pull/1").getTargets();
+    expect(targets).toHaveLength(1);
+    expect(targets[0]).toMatchObject({ el: timeline, item: ".js-timeline-item" });
+  });
+
+  it("falls back to the React issue-viewer container", () => {
+    const container = document.createElement("div");
+    container.setAttribute("data-testid", "issue-viewer-issue-container");
+    for (const id of ["issue-viewer-comment-1", "issue-viewer-comment-2"]) {
+      const item = document.createElement("div");
+      item.setAttribute("data-testid", id);
+      container.appendChild(item);
+    }
+    document.body.appendChild(container);
+
+    const targets = getPageConfig("/o/r/pull/1").getTargets();
+    expect(targets).toHaveLength(1);
+    expect(targets[0].el).toBe(container);
+  });
+
+  it("adds a target per pushed-commit batch alongside the timeline", () => {
+    buildTimeline(2);
+    // "added N commits" batch: header + sibling wrapper of .TimelineItem.
+    const header = document.createElement("div");
+    header.id = "commits-pushed-abc123";
+    const wrapper = document.createElement("div");
+    for (let i = 0; i < 2; i++) {
+      const commit = document.createElement("div");
+      commit.className = "TimelineItem";
+      wrapper.appendChild(commit);
+    }
+    document.body.append(header, wrapper);
+
+    const targets = getPageConfig("/o/r/pull/1").getTargets();
+    expect(targets).toHaveLength(2);
+    expect(targets[1]).toMatchObject({ el: wrapper, item: ".TimelineItem" });
+  });
+
+  it("returns no targets on an unrecognized DOM", () => {
+    document.body.innerHTML = "<main><p>not a PR timeline</p></main>";
+    expect(getPageConfig("/o/r/pull/1").getTargets()).toEqual([]);
+  });
+});
+
+describe("commits targets — modern React page", () => {
+  // Mirrors the May 2026 structure documented in pages.js.
+  function buildModernCommitsPage(commitsPerDay) {
+    const list = document.createElement("div");
+    list.setAttribute("data-testid", "commits-list");
+    const timeline = document.createElement("div");
+    timeline.className = "prc-Timeline-Timeline-x";
+    for (const count of commitsPerDay) {
+      const day = document.createElement("div");
+      day.className = "Timeline-Item";
+      const ul = document.createElement("ul");
+      ul.setAttribute("data-listview-component", "items-list");
+      for (let i = 0; i < count; i++) {
+        const li = document.createElement("li");
+        li.setAttribute("data-testid", "commit-row-item");
+        ul.appendChild(li);
+      }
+      day.appendChild(ul);
+      timeline.appendChild(day);
+    }
+    list.appendChild(timeline);
+    document.body.appendChild(list);
+    return { timeline };
+  }
+
+  it("targets the day groups AND each day's multi-commit list", () => {
+    const { timeline } = buildModernCommitsPage([2, 3]);
+    const targets = getPageConfig("/o/r/pull/1/commits").getTargets();
+    // 1 day-group target + 2 per-day list targets.
+    expect(targets).toHaveLength(3);
+    expect(targets[0]).toMatchObject({ el: timeline, item: ".Timeline-Item" });
+  });
+
+  it("skips the day-group target when there is a single day", () => {
+    buildModernCommitsPage([2]);
+    const targets = getPageConfig("/o/r/pull/1/commits").getTargets();
+    expect(targets).toHaveLength(1);
+    expect(targets[0].item).toBe('li[data-testid="commit-row-item"]');
+  });
+
+  it("skips per-day lists holding fewer than 2 commits", () => {
+    buildModernCommitsPage([2, 1]);
+    const targets = getPageConfig("/o/r/pull/1/commits").getTargets();
+    // Day-group target + only the 2-commit day's list.
+    expect(targets).toHaveLength(2);
+  });
+});
+
+describe("commits targets — legacy Rails page", () => {
+  function buildLegacyCommitsPage(commitsPerGroup) {
+    const list = document.createElement("div");
+    list.className = "js-commits-list";
+    for (const count of commitsPerGroup) {
+      const group = document.createElement("div");
+      group.className = "js-commit-group";
+      const ol = document.createElement("ol");
+      for (let i = 0; i < count; i++) ol.appendChild(document.createElement("li"));
+      group.appendChild(ol);
+      list.appendChild(group);
+    }
+    document.body.appendChild(list);
+    return list;
+  }
+
+  it("targets the group list and each multi-commit group", () => {
+    const list = buildLegacyCommitsPage([2, 3]);
+    const targets = getPageConfig("/o/r/pull/1/commits").getTargets();
+    expect(targets).toHaveLength(3);
+    expect(targets[0]).toMatchObject({ el: list, item: ".js-commit-group" });
+  });
+
+  it("skips single-commit groups", () => {
+    buildLegacyCommitsPage([2, 1]);
+    const targets = getPageConfig("/o/r/pull/1/commits").getTargets();
+    expect(targets).toHaveLength(2);
+  });
+
+  it("falls through to legacy when a modern commits-list is present but empty", () => {
+    const empty = document.createElement("div");
+    empty.setAttribute("data-testid", "commits-list");
+    document.body.appendChild(empty);
+    buildLegacyCommitsPage([2, 2]);
+
+    const targets = getPageConfig("/o/r/pull/1/commits").getTargets();
+    expect(targets).toHaveLength(3);
+  });
+
+  it("returns no targets on an unrecognized DOM", () => {
+    document.body.innerHTML = "<main><p>nothing commit-shaped</p></main>";
+    expect(getPageConfig("/o/r/pull/1/commits").getTargets()).toEqual([]);
+  });
+});
diff --git a/tsconfig.json b/tsconfig.json
index 3ffc1da..90fc0af 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -16,6 +16,7 @@
     "constants.js",
     "reorder.js",
     "checks.js",
+    "pages.js",
     "content.js",
     "background.js",
     "popup.js",
diff --git a/types/globals.d.ts b/types/globals.d.ts
index b0c8d42..9122576 100644
--- a/types/globals.d.ts
+++ b/types/globals.d.ts
@@ -1,9 +1,12 @@
 // Ambient declarations for the symbols shared across content scripts.
 //
-// constants.js / reorder.js / checks.js attach these to the global scope
-// (the extension injects them into one shared world), and content.js reads
-// them as bare globals. Declaring them here lets `tsc --checkJs` verify
-// content.js without each file having to import the others.
+// constants.js / reorder.js / checks.js / pages.js attach these to the
+// global scope (the extension injects them into one shared world), and
+// content.js reads them as bare globals. Declaring them here lets
+// `tsc --checkJs` verify content.js without each file having to import
+// the others.
+
+type PrrcOrder = "newest" | "oldest";
 
 interface PrrcTarget {
   el: Element;
@@ -11,8 +14,14 @@ interface PrrcTarget {
   descendant: boolean;
 }
 
+interface PrrcPageConfig {
+  name: string;
+  pathRe: RegExp;
+  getTargets(): PrrcTarget[];
+}
+
 interface PrrcChecksState {
-  key: string;
+  key: "failing" | "running" | "passing" | "unknown";
   label: string;
   color: string;
 }
@@ -20,8 +29,8 @@ interface PrrcChecksState {
 // constants.js — declared with `var` so they also appear on `globalThis`
 // (the UMD modules read `globalThis.ORDER`).
 declare var STORAGE_KEY: string;
-declare var ORDER: { NEWEST: string; OLDEST: string };
-declare function normalizeOrder(value: unknown): string;
+declare var ORDER: { NEWEST: "newest"; OLDEST: "oldest" };
+declare function normalizeOrder(value: unknown): PrrcOrder;
 
 // reorder.js
 declare function firstMatchingTarget(
@@ -30,6 +39,9 @@ declare function firstMatchingTarget(
 declare function pushedCommitTargets(root?: ParentNode): PrrcTarget[];
 declare function applyOrderToTarget(target: PrrcTarget, order: string): boolean;
 
+// pages.js
+declare function getPageConfig(pathname: string): PrrcPageConfig | null;
+
 // checks.js
 declare function findChecksBox(root?: ParentNode): Element | null;
 declare function getCheckLabels(root?: ParentNode): string[];
diff --git a/vitest.config.mjs b/vitest.config.mjs
index 0c66d72..83af241 100644
--- a/vitest.config.mjs
+++ b/vitest.config.mjs
@@ -13,11 +13,10 @@ export default defineConfig({
       // provider under-reports with the threads pool in some sandboxed/CI
       // environments.
       provider: "istanbul",
-      // Measure only the pure, unit-tested logic modules. content.js,
-      // background.js, and popup.js are DOM/chrome glue exercised in a real
-      // browser, not under jsdom, so including them would report misleading
-      // zeros.
-      include: ["constants.js", "reorder.js", "checks.js"],
+      // Measure the unit-tested logic modules. content.js and popup.js are
+      // thin DOM/chrome glue exercised in a real browser, not under jsdom,
+      // so including them would report misleading zeros.
+      include: ["constants.js", "reorder.js", "checks.js", "pages.js", "background.js"],
       reporter: ["text", "lcov"],
       // Branches sits a little lower than the rest: each module's UMD
       // wrapper has a browser-global branch that can't run under Node tests.

From c5b6b23fc7fb24fba8d649b578392b04b925f917 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 14 Jul 2026 17:43:17 +0000
Subject: [PATCH 06/10] Match check status words on word boundaries, not
 substrings

A passing check named e.g. failover-suite or cancellation-service was
reported as failing because the failure regex matched bare substrings.
Match explicit inflected status phrases behind word boundaries instead,
with regression tests for embedded-status-word names and for every
inflected form GitHub actually emits.

Co-authored-by: Julius Walton <ShiosOS@users.noreply.github.com>
---
 checks.js            | 17 ++++++++++++++---
 test/checks.test.mjs | 18 ++++++++++++++++++
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/checks.js b/checks.js
index 5fffe6b..bc41e1b 100644
--- a/checks.js
+++ b/checks.js
@@ -45,6 +45,17 @@
       .filter(Boolean);
   }
 
+  // Status-phrase patterns. Word boundaries plus explicit word forms keep
+  // a check *named* e.g. "failover-suite" or "cancellation-service" from
+  // tripping the failure branch when its label reads "... successful in 2m"
+  // (bare substring matching used to misreport those as failing). A check
+  // name that itself contains a standalone status word (e.g. "error-pages")
+  // is still ambiguous — labels are all GitHub's accessible rows give us.
+  const FAILING_RE =
+    /\b(fail(?:ed|ing|ure|s)?|error(?:ed|s)?|timed out|cancel(?:l?ed)?|denied|action required)\b/i;
+  const RUNNING_RE = /\b(in[ _]progress|pending|queued|running|waiting|expected)\b/i;
+  const PASSING_RE = /\b(success(?:ful)?|passed|passing)\b/i;
+
   // Aggregate the check-row labels into a coarse { key, label, color }.
   // Precedence: any failure -> failing; else any in-flight -> running;
   // else any success -> passing; else unknown. Checked in that order so a
@@ -55,13 +66,13 @@
     /** @param {RegExp} re */
     const any = (re) => list.some((l) => re.test(l));
 
-    if (any(/(fail|error|timed out|cancel|denied|action required)/i)) {
+    if (any(FAILING_RE)) {
       return { key: "failing", label: "✗ Checks failing", color: "#d1242f" };
     }
-    if (any(/(in progress|in_progress|pending|queued|running|waiting|expected)/i)) {
+    if (any(RUNNING_RE)) {
       return { key: "running", label: "• Checks running", color: "#9a6700" };
     }
-    if (any(/(success|passed|passing)/i)) {
+    if (any(PASSING_RE)) {
       return { key: "passing", label: "✓ Checks passing", color: "#1a7f37" };
     }
     return { key: "unknown", label: "• Checks status", color: "#1f6feb" };
diff --git a/test/checks.test.mjs b/test/checks.test.mjs
index 23585aa..8a16d51 100644
--- a/test/checks.test.mjs
+++ b/test/checks.test.mjs
@@ -73,6 +73,24 @@ describe("deriveChecksState", () => {
     expect(deriveChecksState("everything successful").key).toBe("passing");
   });
 
+  it("is not fooled by status words embedded in check names", () => {
+    // Substring matching used to classify these as failing.
+    expect(deriveChecksState(["failover-suite successful in 2m"]).key).toBe("passing");
+    expect(deriveChecksState(["cancellation-service successful in 1m"]).key).toBe("passing");
+    expect(deriveChecksState(["unfailing-tests successful"]).key).toBe("passing");
+  });
+
+  it("still matches the real inflected status phrases", () => {
+    expect(deriveChecksState(["ci failed after 2m"]).key).toBe("failing");
+    expect(deriveChecksState(["ci failure"]).key).toBe("failing");
+    expect(deriveChecksState(["deploy cancelled after 10s"]).key).toBe("failing");
+    expect(deriveChecksState(["deploy canceled after 10s"]).key).toBe("failing");
+    expect(deriveChecksState(["lint timed out"]).key).toBe("failing");
+    expect(deriveChecksState(["review action required"]).key).toBe("failing");
+    expect(deriveChecksState(["build queued"]).key).toBe("running");
+    expect(deriveChecksState(["build in_progress"]).key).toBe("running");
+  });
+
   it("matches the real captured check set (running: one is waiting)", () => {
     expect(deriveChecksState(REAL_LABELS).key).toBe("running");
   });

From 06ff9be444e2d4c16cf859de050f507c4b20775e Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 14 Jul 2026 17:43:26 +0000
Subject: [PATCH 07/10] CI: test the minimum supported Node and drop persisted
 credentials

Run the matrix on Node 22 (package.json engines floor) and 24 so an
engines violation can't slip through, and pass persist-credentials:
false to checkout since no CI step needs the token after clone.

Co-authored-by: Julius Walton <ShiosOS@users.noreply.github.com>
---
 .github/workflows/ci.yml | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ace7f57..1489fe5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -17,15 +17,25 @@ concurrency:
 jobs:
   check:
     runs-on: ubuntu-latest
+    strategy:
+      # Test the oldest Node we claim to support (package.json engines)
+      # alongside current, so "works on my machine" can't hide an engines
+      # violation.
+      matrix:
+        node-version: [22, 24]
     steps:
       # Actions are pinned to commit SHAs (supply-chain hardening); the
       # trailing comment records the human-readable version. v6 runs on the
       # Node 24 action runtime, clearing the Node 20 deprecation warning.
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          # No step here pushes or calls the API; don't leave the token in
+          # .git/config for the rest of the job.
+          persist-credentials: false
 
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: 24
+          node-version: ${{ matrix.node-version }}
           cache: npm
 
       - run: npm ci

From 442f1c8f61f5bc282aafdd7b32d4e8cba4fe1adb Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 14 Jul 2026 17:43:26 +0000
Subject: [PATCH 08/10] Popup: follow the browser's light/dark preference

The popup hardcoded GitHub dark-mode colors, which looked out of place
for light-mode users. Move the palette to custom properties with a
prefers-color-scheme override and declare color-scheme so form controls
match.

Co-authored-by: Julius Walton <ShiosOS@users.noreply.github.com>
---
 popup.html | 40 +++++++++++++++++++++++++++++++---------
 1 file changed, 31 insertions(+), 9 deletions(-)

diff --git a/popup.html b/popup.html
index 29d72d2..8e15919 100644
--- a/popup.html
+++ b/popup.html
@@ -4,6 +4,28 @@
     <meta charset="utf-8" />
     <title>PR Reverse Comments</title>
     <style>
+      /* GitHub-ish palette; follows the browser's light/dark preference
+         instead of forcing dark on light-mode users. */
+      :root {
+        color-scheme: light dark;
+        --bg: #ffffff;
+        --fg: #1f2328;
+        --fg-muted: #59636e;
+        --btn-bg: #f6f8fa;
+        --btn-border: #d1d9e0;
+        --btn-hover: #eef1f4;
+        --accent: #1f6feb;
+      }
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --bg: #0d1117;
+          --fg: #c9d1d9;
+          --fg-muted: #8b949e;
+          --btn-bg: #21262d;
+          --btn-border: #30363d;
+          --btn-hover: #30363d;
+        }
+      }
       body {
         font:
           13px -apple-system,
@@ -13,8 +35,8 @@
         width: 220px;
         margin: 0;
         padding: 12px;
-        background: #0d1117;
-        color: #c9d1d9;
+        background: var(--bg);
+        color: var(--fg);
       }
       h1 {
         font-size: 13px;
@@ -22,7 +44,7 @@
       }
       p {
         margin: 0 0 10px 0;
-        color: #8b949e;
+        color: var(--fg-muted);
         font-size: 11px;
       }
       .row {
@@ -32,20 +54,20 @@
       button {
         flex: 1;
         padding: 6px 8px;
-        background: #21262d;
-        color: #c9d1d9;
-        border: 1px solid #30363d;
+        background: var(--btn-bg);
+        color: var(--fg);
+        border: 1px solid var(--btn-border);
         border-radius: 6px;
         cursor: pointer;
         font-size: 12px;
       }
       button.active {
-        background: #1f6feb;
-        border-color: #1f6feb;
+        background: var(--accent);
+        border-color: var(--accent);
         color: #fff;
       }
       button:hover:not(.active) {
-        background: #30363d;
+        background: var(--btn-hover);
       }
     </style>
   </head>

From eecbdf578bb4db2482b3813d755dd04b892470ee Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 14 Jul 2026 17:43:26 +0000
Subject: [PATCH 09/10] Document pages.js, selector-maintenance workflow, and
 changelog entries

Co-authored-by: Julius Walton <ShiosOS@users.noreply.github.com>
---
 CHANGELOG.md | 15 +++++++++++++++
 README.md    | 26 ++++++++++++++++----------
 2 files changed, 31 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 329e736..42210ed 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,11 +22,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - A corrupted stored preference value no longer desyncs the toggle label
   from the actual sort order; anything unrecognized falls back to newest.
 
+- Status-word matching in the checks indicator uses word boundaries, so a
+  check _named_ e.g. `failover-suite` or `cancellation-service` that passed
+  is no longer misreported as failing.
+
 ### Added
 
 - Accessible labels (`aria-label`) on the injected toggle button and
   status-checks indicator.
 - 128px toolbar icon variants wired into the action icon set.
+- The popup follows the browser's light/dark preference instead of always
+  rendering dark.
+
+### Changed
+
+- The per-page GitHub DOM selectors moved from `content.js` into a new
+  `pages.js` module, and `background.js` became importable under Node —
+  both are now covered by unit tests (79 tests total), including the page
+  structures for the Conversation, modern Commits, and legacy Commits
+  views.
+- CI runs on both the minimum supported Node (22) and current (24).
 
 ## [1.1.0] - 2026-06-04
 
diff --git a/README.md b/README.md
index 4ab0740..0c3f0b6 100644
--- a/README.md
+++ b/README.md
@@ -115,16 +115,22 @@ source files in this repo as-is. To make a change, edit the source, reload
 the extension at `chrome://extensions` (or re-install the temporary add-on
 in Firefox), and refresh a PR page.
 
-| File            | Purpose                                               |
-| --------------- | ----------------------------------------------------- |
-| `manifest.json` | Extension definition (Manifest V3, Chrome + Firefox)  |
-| `constants.js`  | Shared constants (storage key, order values)          |
-| `reorder.js`    | Pure DOM-reordering helpers (unit-tested)             |
-| `checks.js`     | PR status-checks detection helpers (unit-tested)      |
-| `content.js`    | Runs on PR pages; reorders comments, draws the toggle |
-| `background.js` | Keeps the toolbar icon in sync with the current tab   |
-| `popup.html`    | Toolbar popup UI                                      |
-| `popup.js`      | Popup behavior; reads/writes saved preference         |
+| File            | Purpose                                                   |
+| --------------- | --------------------------------------------------------- |
+| `manifest.json` | Extension definition (Manifest V3, Chrome + Firefox)      |
+| `constants.js`  | Shared constants (storage key, order values)              |
+| `reorder.js`    | Pure DOM-reordering helpers (unit-tested)                 |
+| `checks.js`     | PR status-checks detection helpers (unit-tested)          |
+| `pages.js`      | Per-page GitHub DOM selectors and targets (unit-tested)   |
+| `content.js`    | Runs on PR pages; wires storage, observers, and the UI    |
+| `background.js` | Keeps the toolbar icon in sync with the tab (unit-tested) |
+| `popup.html`    | Toolbar popup UI                                          |
+| `popup.js`      | Popup behavior; reads/writes saved preference             |
+
+When GitHub ships a UI change that breaks reordering, the selectors to
+update live in `pages.js` (timeline/commits targets) and `checks.js`
+(status-checks box); each has jsdom tests with fixtures mirroring the real
+page structure, so start by updating the fixture to match the new DOM.
 
 ### Dev tooling (optional)
 

From 6fec1a37879873193530f554c4b346e3df6b8853 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 14 Jul 2026 18:17:51 +0000
Subject: [PATCH 10/10] CI: report an aggregate 'check' status for branch
 protection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Splitting the check job into a Node 22/24 matrix renamed its check runs
to 'check (22)' / 'check (24)', so the branch-protection rule requiring
a status named 'check' waited forever ('Expected — Waiting for status
to be reported'). Add a merge-gate job that reports the stable 'check'
name and fails unless every matrix leg succeeded.

Co-authored-by: Julius Walton <ShiosOS@users.noreply.github.com>
---
 .github/workflows/ci.yml | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1489fe5..8d1b7fb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -52,3 +52,16 @@ jobs:
       - run: npm run coverage
 
       - run: npm run build
+
+  # Merge gate: branch protection requires a single status named "check".
+  # Reporting that name from an aggregate job (instead of the matrix legs,
+  # whose names carry the Node version) keeps the required-check name
+  # stable no matter how the matrix changes.
+  ci-ok:
+    name: check
+    needs: check
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail unless every matrix leg succeeded
+        run: test "${{ needs.check.result }}" = "success"