ultimate-jekyll-manager 1.1.10 → 1.2.0

package/README.md

@@ -28,6 +28,7 @@
 * **SEO Optimized**: Ultimate Jekyll is fully SEO optimized.
 * **Blazingly Fast**: Ultimate Jekyll is blazingly fast.
 * **NPM & Gulp**: Ultimate Jekyll is fueled by an intuitive incorporation of npm and gulp.
+* **Built-in test framework**: three layers (`build` / `page` / `boot`) — plain Node, headless Chromium tab, headless Chromium against real `_site/` with SW registration verification.
 
 ## 🚀 Getting started
 1. [Create a repo](https://github.com/itw-creative-works/ultimate-jekyll/generate) from the **Ultimate Jekyll** template.
@@ -37,6 +38,49 @@
 npm start
 ```
 
+## 🧪 Testing
+
+UJM ships a built-in three-layer test harness. Write tests under `test/<layer>/*.test.js` and run with:
+
+```bash
+npx mgr test                   # all layers
+npx mgr test --layer build     # plain Node, fast
+npx mgr test --layer page      # headless Chromium tab against harness HTML
+npx mgr test --layer boot      # headless Chromium against built _site/
+```
+
+Test files use Jest-compatible matchers:
+
+```js
+// test/build/config.test.js
+const Manager = require('ultimate-jekyll-manager/build');
+
+module.exports = {
+  layer: 'build',
+  description: 'config has brand.id',
+  run: async (ctx) => {
+    const cfg = Manager.getConfig('project');
+    ctx.expect(cfg.brand.id).toBeTruthy();
+  },
+};
+```
+
+Boot tests run against your actually-built `_site/` after `npm run build`:
+
+```js
+// test/boot/site.test.js
+module.exports = {
+  layer: 'boot',
+  description: 'home renders + SW registers',
+  inspect: async ({ site, page, expect }) => {
+    await page.goto(site.baseUrl + '/');
+    expect((await page.title()).length).toBeGreaterThan(0);
+  },
+};
+```
+
+Full guide: [docs/test-framework.md](docs/test-framework.md). Boot layer deep-dive: [docs/test-boot-layer.md](docs/test-boot-layer.md).
+
 ## 📦 How to sync with the template
 1. Simply run `npm start` in Terminal to get all the latest updates from the **Ultimate Jekyll template** and launch your website in the browser.
 
@@ -761,23 +805,8 @@ Add this to any js file to ONLY run in development mode (it will be excluded in
   /* @dev-only:end */
 ```
 
-> This project is "ultimate-jekyll", an NPM module that helps   │
-│   streamline development of Jekyll websites. A "consuming       │
-│   project" will require this NPM module to take advantage of    │
-│   its features like automatic folder structure setup, themes,   │
-│   and default pages to get a website up and running in          │
-│   seconds, while allowing further customization down the line.  │
-│   Right now i am struggling on the theme portion of this        │
-│   project. I want the user to be able to define the theme in    │
-│   their _config.yml (which currently they do by setting         │
-│   theme.id). I have some themes from the official bootstrap     │
-│   team. usually a theme comes with a frontend, a backend/admin  │
-│   dashboard, and docs. these 3 subparts of the theme have       │
-│   different html structure and css and js requirements. so i    │
-│   need a super easy system that allows me to make a file in     │
-│   the consuming project, say its the index.html for example,    │
-│   and i should easily be able to put which subseciton (or       │
-│   target as i call it) of the theme to use. so for an agency    │
-│   website i will probably use the frontend target, while for a  │
-│   chat app i will probably use the backend target. however, i   │
-│   need to be able to use
+## 🧰 Sister projects
+
+- [Electron Manager (EM)](https://github.com/itw-creative-works/electron-manager) — same patterns, but for Electron desktop apps
+- [Browser Extension Manager (BXM)](https://github.com/itw-creative-works/browser-extension-manager) — same patterns, but for cross-browser MV3 extensions
+- [Backend Manager (BEM)](https://github.com/itw-creative-works/backend-manager) — Firebase Functions backend framework

package/dist/build.js

@@ -351,5 +351,8 @@ Manager.prototype.processBatches = Manager.processBatches;
 //   };
 // };
 
+// Mix in cross-context mode helpers (isDevelopment/isProduction/isTesting/getVersion).
+require('./utils/mode-helpers.js').attachTo(Manager);
+
 // Export
 module.exports = Manager;

package/dist/cli.js

@@ -17,6 +17,7 @@ const ALIASES = {
   // Tasks
   audit: ['-a', '--audit'],
   translation: ['-t', '--translation'],
+  test: ['--test'],
 };
 
 // Function to resolve command name from aliases

package/dist/commands/test.js

@@ -0,0 +1,56 @@
+// Libraries
+const path    = require('path');
+const fs      = require('fs');
+const Manager = require('../build.js');
+const mgr     = new Manager();
+const logger  = mgr.logger('test');
+const { run } = require('../test/runner.js');
+
+module.exports = async function (options) {
+  const layer       = options.layer    || 'all';
+  const filter      = options.filter   || null;
+  const reporter    = options.reporter || 'pretty';
+  const integration = options.integration === true || options.integration === 'true';
+
+  if (integration) {
+    process.env.UJ_TEST_INTEGRATION = '1';
+  }
+
+  // Canonical signal — every Manager picks this up via isTesting().
+  process.env.UJ_TEST_MODE = 'true';
+
+  // When UJM itself runs its own boot-layer tests (the cwd's package.json is
+  // UJM's package.json), there's no real consumer site to target. Point the
+  // boot runner at the fixture under dist/test/fixtures/consumer-site unless
+  // the caller has already set UJ_TEST_BOOT_PROJECT explicitly.
+  if (!process.env.UJ_TEST_BOOT_PROJECT) {
+    try {
+      const cwdPkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+      if (cwdPkg.name === 'ultimate-jekyll-manager') {
+        process.env.UJ_TEST_BOOT_PROJECT = path.join(__dirname, '..', 'test', 'fixtures', 'consumer-site');
+      }
+    } catch (_) { /* no package.json — leave unset */ }
+  }
+
+  if (reporter !== 'json') {
+    logger.log(`Running tests (layer=${layer}${filter ? ` filter="${filter}"` : ''}${integration ? ' +integration' : ''})`);
+  }
+
+  const result = await run({ layer, filter, reporter });
+
+  if (reporter === 'json') {
+    // Final machine-readable summary.
+    process.stdout.write(JSON.stringify({
+      event:   'summary',
+      passed:  result.passed,
+      failed:  result.failed,
+      skipped: result.skipped,
+      total:   result.passed + result.failed + result.skipped,
+    }) + '\n');
+  }
+
+  if (result.failed > 0) {
+    process.exitCode = 1;
+    throw new Error(`${result.failed} test(s) failed`);
+  }
+};

package/dist/defaults/CLAUDE.md

@@ -1,8 +1,74 @@
-# Identity
-This is a jekyll site that is "consuming" a jekyll template project called Ultimate Jekyll--a collection of components that can be used to build a Jekyll site quickly and efficiently.
+# ========== Default Values ==========
+# Ultimate Jekyll Manager (UJM) — consumer project
 
-## UJ Documentation
-You should have a full understanding of Ultimate Jekyll before editing this project, which can be found at: node_modules/ultimate-jekyll-manager/CLAUDE.md
+> **Auto-managed file.** Everything between `# ========== Default Values ==========` and `# ========== Custom Values ==========` is owned by `ultimate-jekyll-manager` and rewritten on every `npx mgr setup`. Put your own project-specific notes BELOW the `Custom Values` marker — that section is preserved verbatim across setups.
 
-## Project-specific Notes
-Add any notes specific to this project here.
+## Framework
+
+This project consumes **Ultimate Jekyll Manager** (UJM) — a comprehensive framework for building modern Jekyll-powered static sites. UJM provides one-line bootstrap per context (build / frontend / service-worker), a multi-stage gulp pipeline (defaults / distribute / webpack / sass / imagemin / jekyll / audit / translation / minifyHtml / serve), default Jekyll layouts + themes, a frontend ES-module Manager with dynamic per-page module loading, a service worker with Firebase Messaging + cache management, and a built-in three-layer test framework.
+
+**Framework's own docs** (read these for deep-dives; both paths point to the same files, the absolute path works regardless of working directory):
+- Top-level overview: `/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-manager/CLAUDE.md` (or `node_modules/ultimate-jekyll-manager/CLAUDE.md`)
+- Subsystem references: `/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-manager/docs/` (or `node_modules/ultimate-jekyll-manager/docs/`)
+
+## Quick start
+
+```bash
+npm start           # dev: clean → setup → bundle exec gulp serve (Jekyll + BrowserSync + livereload)
+npm run build       # production build (UJ_BUILD_MODE=true): clean → setup → full gulp pipeline → _site/
+npm run deploy      # build → `npu sync --message='Deploy'` (publishes _site/)
+npx mgr test        # run framework + project test suites (build / page / boot layers)
+npx mgr audit       # HTML validation + spellcheck + optional Lighthouse
+```
+
+## Where things live
+
+- `src/_config.yml` — Jekyll config: brand, theme, meta, web_manager (Firebase). `Manager.getConfig('project')` reads this. **`brand.id` + `theme.id` are required.**
+- `config/ultimate-jekyll-manager.json` — UJM-specific config (JSON5): purgecss safelist, webpack target, imagemin options, distribute glob patterns. `Manager.getUJMConfig()` reads this.
+- `src/pages/<name>.html` — your custom pages. May contain frontmatter only (and use a UJM `blueprint/*` layout) to customize a default page without writing HTML.
+- `src/_layouts/`, `src/_includes/` — custom layouts / includes that override UJM's defaults.
+- `src/assets/css/main.scss` — shared SCSS. Theme load paths resolve via `__theme__` webpack alias.
+- `src/assets/css/pages/<page>/index.scss` — page-specific styles (compile to `dist/assets/css/pages/<page>/...bundle.css`).
+- `src/assets/js/main.js` — main JS entry.
+- `src/assets/js/pages/<page>/index.js` — page-specific JS. UJM's frontend Manager loads these dynamically based on `data-page-path`.
+- `src/_includes/frontend/sections/{nav,footer}.json` — JSON-driven nav/footer config. UJM renders these into HTML at build time.
+- `hooks/build/{pre,post}.js`, `hooks/middleware/request.js` — optional lifecycle hooks.
+- `_site/` — Jekyll output (the deployable site). Not committed.
+- `dist/` — intermediate compile output (webpack bundles, sass, processed images) before Jekyll merges them into `_site/`.
+- `test/**/*.js` — your project test suites (framework auto-runs them alongside its own).
+
+## Per-context imports
+
+```js
+// Frontend (browser ES module) — every consumer page gets one
+import Manager from 'ultimate-jekyll-manager';
+new Manager().initialize();
+
+// Service worker — at the top of src/service-worker.js
+importScripts('/build.js');   // exposes UJ_BUILD_JSON
+// ...then construct your service-worker Manager
+
+// Build-time / gulp / commands
+const Manager = require('ultimate-jekyll-manager/build');
+```
+
+## Available APIs at runtime
+
+After `new Manager().initialize()`, the frontend Manager exposes:
+- `manager.webManager` — Web Manager singleton (Firebase, auth, analytics, reactive `data-wm-bind` directives)
+- `manager.isDevelopment()` / `isProduction()` / `isTesting()` / `getVersion()` — cross-context helpers
+
+At build time, `require('ultimate-jekyll-manager/build')` exposes:
+- `Manager.getConfig(type)` — read `_config.yml` (`'project'` or `'main'`)
+- `Manager.getPackage(type)` — read `package.json` (`'project'` or `'main'`)
+- `Manager.getUJMConfig()` — read `config/ultimate-jekyll-manager.json`
+- `Manager.getEnvironment()` — `'development'` or `'production'`
+- `Manager.isBuildMode()` / `isQuickMode()` / `isServer()` / `actLikeProduction()` — env-gated flags
+- `Manager.logger(name)` — timestamped logger instance
+- `Manager.require(path)` — escape hatch for UJM transitive deps (use sparingly)
+
+# ========== Custom Values ==========
+
+## Project-specific notes
+
+Add anything specific to THIS project here. Edits below this line are preserved across `npx mgr setup` runs.

package/dist/gulp/tasks/defaults.js

@@ -98,6 +98,15 @@ const FILE_MAP = {
     mergeLines: true, // Merge line-by-line instead of overwriting
   },
 
+  // Consumer CLAUDE.md uses the same marker-based merge as .env/.gitignore.
+  // Framework owns the Default section; consumer owns everything below the Custom marker.
+  // Must come AFTER `**/*.md` (which sets overwrite: false) — `getFileOptions` does
+  // last-match-wins, so this rule's `mergeLines: true` activates the merge path even though
+  // the catch-all would otherwise skip.
+  'CLAUDE.md': {
+    mergeLines: true,
+  },
+
   // Config file with smart merging
   'config/ultimate-jekyll-manager.json': {
     overwrite: true,
@@ -319,8 +328,12 @@ function mergeLineBasedFiles(existingContent, newContent, fileName) {
   result.push(DEFAULT_SECTION_MARKER);
   result.push(...mergedDefaultSection);
 
-  // Add custom section
-  result.push('');
+  // Add custom section. Insert a single blank line before the marker, but only if the
+  // merged default doesn't already end with one — otherwise we'd accumulate an extra blank
+  // line on every merge, breaking idempotency after the first re-run.
+  if (mergedDefaultSection.length === 0 || mergedDefaultSection[mergedDefaultSection.length - 1].trim() !== '') {
+    result.push('');
+  }
   result.push(CUSTOM_SECTION_MARKER);
 
   // First add any user lines that were in default section (moved to custom)

package/dist/index.js

@@ -1,5 +1,6 @@
 // Libraries
 import webManager from 'web-manager';
+import { attachTo as attachModeHelpers } from './utils/mode-helpers.js';
 
 // Manager Class
 class Manager {
@@ -133,5 +134,8 @@ class Manager {
   }
 }
 
+// Mix in cross-context mode helpers (isDevelopment/isProduction/isTesting/getVersion).
+attachModeHelpers(Manager);
+
 // Export
 export default Manager;

package/dist/test/assert.js

@@ -0,0 +1,120 @@
+// Tiny expect() — Jest/Vitest-compatible subset.
+// Each matcher throws on failure; the runner catches.
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return a === b;
+  if (typeof a !== 'object') return false;
+
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((x, i) => deepEqual(x, b[i]));
+  }
+
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => deepEqual(a[k], b[k]));
+}
+
+function fmt(v) {
+  if (typeof v === 'string') return JSON.stringify(v);
+  if (v === undefined) return 'undefined';
+  try {
+    return JSON.stringify(v);
+  } catch (e) {
+    return String(v);
+  }
+}
+
+function fail(message) {
+  const err = new Error(message);
+  err.name = 'AssertionError';
+  throw err;
+}
+
+function buildMatchers(actual, negated) {
+  const not = negated ? 'not ' : '';
+
+  function check(cond, message) {
+    if (negated) cond = !cond;
+    if (!cond) fail(message);
+  }
+
+  return {
+    toBe(expected) {
+      check(actual === expected, `expected ${fmt(actual)} ${not}to be ${fmt(expected)}`);
+    },
+    toEqual(expected) {
+      check(deepEqual(actual, expected), `expected ${fmt(actual)} ${not}to deeply equal ${fmt(expected)}`);
+    },
+    toBeTruthy() {
+      check(!!actual, `expected ${fmt(actual)} ${not}to be truthy`);
+    },
+    toBeFalsy() {
+      check(!actual, `expected ${fmt(actual)} ${not}to be falsy`);
+    },
+    toBeDefined() {
+      check(actual !== undefined, `expected ${fmt(actual)} ${not}to be defined`);
+    },
+    toBeUndefined() {
+      check(actual === undefined, `expected ${fmt(actual)} ${not}to be undefined`);
+    },
+    toBeNull() {
+      check(actual === null, `expected ${fmt(actual)} ${not}to be null`);
+    },
+    toContain(item) {
+      const has = Array.isArray(actual)
+        ? actual.includes(item)
+        : (typeof actual === 'string' && actual.includes(item));
+      check(has, `expected ${fmt(actual)} ${not}to contain ${fmt(item)}`);
+    },
+    toHaveProperty(key) {
+      const has = actual != null && Object.prototype.hasOwnProperty.call(actual, key);
+      check(has, `expected ${fmt(actual)} ${not}to have property "${key}"`);
+    },
+    toMatch(regex) {
+      check(regex.test(actual), `expected ${fmt(actual)} ${not}to match ${regex}`);
+    },
+    toBeInstanceOf(cls) {
+      check(actual instanceof cls, `expected value ${not}to be instance of ${cls.name}`);
+    },
+    toBeGreaterThan(n) {
+      check(actual > n, `expected ${fmt(actual)} ${not}to be > ${n}`);
+    },
+    toBeLessThan(n) {
+      check(actual < n, `expected ${fmt(actual)} ${not}to be < ${n}`);
+    },
+    async toThrow(matcher) {
+      let threw = false;
+      let thrown;
+      try {
+        if (typeof actual === 'function') {
+          await actual();
+        }
+      } catch (e) {
+        threw = true;
+        thrown = e;
+      }
+      if (!threw) {
+        return check(false, `expected function ${not}to throw`);
+      }
+      if (matcher instanceof RegExp) {
+        check(matcher.test(thrown.message), `expected thrown message ${not}to match ${matcher} (got: ${thrown.message})`);
+      } else if (typeof matcher === 'string') {
+        check(thrown.message.includes(matcher), `expected thrown message ${not}to contain "${matcher}" (got: ${thrown.message})`);
+      } else {
+        check(true, '');
+      }
+    },
+  };
+}
+
+function expect(actual) {
+  const m = buildMatchers(actual, false);
+  m.not = buildMatchers(actual, true);
+  return m;
+}
+
+module.exports = expect;

package/dist/test/fixtures/consumer-site/_site/about.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" data-page-path="/about">
+<head>
+<meta charset="utf-8">
+<title>About — UJM Fixture Consumer</title>
+</head>
+<body>
+  <main id="main-content">
+    <h1>About</h1>
+    <p>Fixture about page.</p>
+  </main>
+</body>
+</html>

package/dist/test/fixtures/consumer-site/_site/assets/css/main.bundle.css

@@ -0,0 +1,2 @@
+/* Fixture stylesheet — loaded by index.html to verify CSS MIME routing. */
+body { font-family: system-ui, sans-serif; margin: 2rem; }

package/dist/test/fixtures/consumer-site/_site/assets/js/main.bundle.js

@@ -0,0 +1,6 @@
+// Minimal fixture bundle. Real UJM bundles initialize a Manager + webManager;
+// for boot tests we only need a script that loads without throwing so the
+// fixture site can assert "no console errors".
+(function () {
+  window.__ujmFixtureLoaded = true;
+})();

package/dist/test/fixtures/consumer-site/_site/build.json

@@ -0,0 +1,11 @@
+{
+  "timestamp": "2024-01-01T00:00:00.000Z",
+  "repo":      { "user": "itw-creative-works", "name": "ujm-fixture" },
+  "environment": "production",
+  "packages":  { "ultimate-jekyll-manager": "fixture", "web-manager": "fixture" },
+  "config": {
+    "brand": { "id": "ujm-fixture", "name": "UJM Fixture Consumer" },
+    "theme": { "id": "classy", "target": "frontend" },
+    "uj":    { "environment": "production", "cache_breaker": "fixture-1" }
+  }
+}

package/dist/test/fixtures/consumer-site/_site/index.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en" data-page-path="/">
+<head>
+<meta charset="utf-8">
+<title>UJM Fixture Consumer</title>
+<meta name="description" content="Fixture site for UJM boot tests.">
+<link rel="stylesheet" href="/assets/css/main.bundle.css">
+</head>
+<body>
+  <main id="main-content">
+    <h1>UJM Fixture Consumer</h1>
+    <p>This is a minimal _site/ snapshot used by UJM's framework boot tests.</p>
+  </main>
+  <script>
+    window.Configuration = {
+      brand: { id: 'ujm-fixture', name: 'UJM Fixture Consumer' },
+      theme: { id: 'classy', target: 'frontend' },
+      uj:    { environment: 'production', cache_breaker: 'fixture-1' },
+    };
+  </script>
+  <script src="/assets/js/main.bundle.js"></script>
+  <script>
+    if ('serviceWorker' in navigator) {
+      navigator.serviceWorker.register('/service-worker.js', { scope: '/' });
+    }
+  </script>
+</body>
+</html>

package/dist/test/fixtures/consumer-site/_site/service-worker.js

@@ -0,0 +1,29 @@
+// Minimal fixture service worker. UJM's real SW imports Firebase + does cache
+// management; for boot tests we only need to verify registration + activation
+// + cache naming, so this is a trimmed-down stand-in.
+
+const UJ_BUILD_JSON = {
+  config: {
+    brand: { id: 'ujm-fixture' },
+    uj:    { environment: 'production', cache_breaker: 'fixture-1' },
+  },
+};
+
+const brand        = UJ_BUILD_JSON.config.brand.id;
+const cacheBreaker = UJ_BUILD_JSON.config.uj.cache_breaker;
+const CACHE_NAME   = `${brand}-${cacheBreaker}`;
+
+self.addEventListener('install', (event) => {
+  self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(self.clients.claim());
+});
+
+self.addEventListener('message', (event) => {
+  const data = event.data || {};
+  if (data.command === 'get-cache-name') {
+    event.ports[0] && event.ports[0].postMessage({ name: CACHE_NAME });
+  }
+});

package/dist/test/fixtures/consumer-site/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "ujm-fixture-consumer",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Fixture consumer site used by UJM's framework boot tests. Not published."
+}

package/dist/test/harness/page/index.html

@@ -0,0 +1,51 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>UJM Test Harness</title>
+<!--
+  Page-layer test harness. Loaded by Puppeteer from a tiny embedded HTTP server.
+  Stubs `window.Configuration` (what consumer sites get from Jekyll-rendered
+  HTML) and the data-attributes Manager.initialize() reads. Page-layer suites
+  run their `run(ctx)` body inside this page via `page.evaluate(payload)` —
+  the payload bakes assert.js + each test's body as inline async functions.
+
+  Test results are emitted as console messages prefixed `__UJM_TEST__` and
+  parsed by the parent runner via `page.on('console')`.
+-->
+</head>
+<body data-uj-test-harness>
+  <!--
+    Stub the same DOM signals the frontend Manager reads. The frontend
+    `src/index.js` reads `document.documentElement.dataset.pagePath` and
+    `dataset.assetPath` — set defaults here.
+  -->
+  <script>
+    document.documentElement.dataset.pagePath  = '/';
+    document.documentElement.dataset.assetPath = '';
+
+    // Minimal stub of what Jekyll renders as `window.Configuration` —
+    // enough that webManager.initialize() doesn't throw, and enough for
+    // tests to assert against. Tests that need richer config can mutate
+    // this in their own setup.
+    window.Configuration = {
+      brand:       { id: 'ujm-test', name: 'UJM Test' },
+      theme:       { id: 'classy', target: 'frontend' },
+      meta:        { title: 'UJM Test Harness' },
+      uj:          { environment: 'development', cache_breaker: '0' },
+      web_manager: { firebase: { app: { config: { apiKey: 'test', projectId: 'ujm-test' } } } },
+    };
+
+    // Prerendered icons template — the harness exposes a single icon so
+    // `getPrerenderedIcon('test')` works without any consumer page setup.
+    const tmpl = document.createElement('template');
+    tmpl.id = 'prerendered-icons';
+    tmpl.innerHTML = '<svg data-icon="test" viewBox="0 0 1 1"><rect width="1" height="1"/></svg>';
+    document.body.appendChild(tmpl);
+
+    // Signal the canonical test-mode flag so cross-context helpers can pick
+    // it up even though `process.env` is unreachable from a tab.
+    globalThis.UJ_TEST_MODE = true;
+  </script>
+</body>
+</html>

package/dist/test/index.js

@@ -0,0 +1,63 @@
+// Public test API — what consumers see.
+//
+// Test files export a test definition. Three forms:
+//
+// Standalone:
+//   module.exports = {
+//     layer: 'build',                  // 'build' | 'page' | 'boot'
+//     description: 'config has brand.id',
+//     timeout: 5000,
+//     run: async (ctx) => {
+//       const cfg = Manager.getConfig('project');
+//       ctx.expect(cfg.brand.id).toBeTruthy();
+//     },
+//     cleanup: async (ctx) => { ... },
+//   };
+//
+// Boot layer — spawns Chromium with the consumer's actually-built `_site/` and
+// serves it from an embedded local HTTP server, then runs `inspect` against the
+// live site. Replaces shell-level smoke tests with deterministic, signal-driven
+// pass/fail. Use this to verify the WHOLE integration: site builds, SW registers,
+// pages render, no console errors.
+//
+//   module.exports = {
+//     layer: 'boot',
+//     description: 'home renders + SW registers',
+//     timeout: 20000,
+//     inspect: async ({ site, page, expect, projectRoot }) => {
+//       await page.goto(site.baseUrl + '/');
+//       expect(await page.title()).toBeTruthy();
+//     },
+//   };
+//
+// Suite (sequential, shared state, stop on first failure):
+//   module.exports = {
+//     type: 'suite',
+//     layer: 'page',
+//     description: 'manager init',
+//     tests: [
+//       { name: 'step 1', run: async (ctx) => { ctx.state.mgr = new Manager(); } },
+//       { name: 'step 2', run: async (ctx) => { ctx.expect(ctx.state.mgr).toBeTruthy(); } },
+//     ],
+//   };
+//
+// Group (sequential, shared state, runs ALL tests even if some fail):
+//   module.exports = {
+//     type: 'group',
+//     layer: 'build',
+//     tests: [ ... ],
+//   };
+//
+// Array form (treated as group):
+//   module.exports = [ { name, run }, ... ];
+//
+// The ctx (context) provided to every run/cleanup includes:
+//   - ctx.expect       — Jest-compatible assertion library
+//   - ctx.state        — shared object across tests in a suite/group
+//   - ctx.skip(reason) — throw to skip the current test at runtime
+//   - ctx.layer        — current layer name
+//   - ctx.page         — Puppeteer Page (page layer only)
+
+module.exports = {
+  expect: require('./assert.js'),
+};