ultimate-jekyll-manager 1.4.3 → 1.5.0

package/dist/gulp/tasks/translation.js

@@ -995,6 +995,11 @@ function getIgnoredPages() {
   const socials = config?.socials || {};
   // const downloads = config?.downloads || {};
 
+  // User-configured excludes (translation.exclude). Each entry can be a folder
+  // (e.g. "blog" → /blog/**) or a single page path (e.g. "some-page"). We add
+  // each to BOTH files and folders so it matches either way.
+  const userExcludes = config?.translation?.exclude || [];
+
   const redirectsDir = path.join('dist', 'redirects');
   const redirectFiles = glob(`${redirectsDir}/**/*.html`);
   const redirectPermalinks = [];
@@ -1045,6 +1050,9 @@ function getIgnoredPages() {
 
       // Redirects
       ...redirectPermalinks,
+
+      // User-configured excludes (treated as a page path)
+      ...userExcludes,
     ],
     folders: [
       // Languages
@@ -1055,6 +1063,9 @@ function getIgnoredPages() {
 
       // Firestore auth pages
       '__/auth',
+
+      // User-configured excludes (treated as a folder)
+      ...userExcludes,
     ],
   };
 }

package/dist/gulp/tasks/utils/manage-test-layers.js

@@ -0,0 +1,97 @@
+// Test-layer manager (dev only)
+// Powers the CONSUMER layer of the /test/libraries/layers asset-cascade panel.
+//
+// The Consumer dots only go green if the consuming project has its own page files
+// at src/assets/{css,js}/pages/test/libraries/layers/index.*. To prove that layer
+// live WITHOUT permanently adding files to the consumer, this is OPT-IN via the
+// UJ_TEST_LAYERS=true env flag:
+//
+//   - ALWAYS (every run): remove any previously-generated consumer test-layer files,
+//     so they never persist or get committed even if the flag is later unset.
+//   - WHEN UJ_TEST_LAYERS=true: (re)generate them into the consumer's src/ at build
+//     START — before sass + jekyll run — so the real __project_assets__ / consumer
+//     page-CSS path picks them up exactly like any other consumer page file. This is
+//     the honest mechanism (no aliases/shims); the files are just real, briefly.
+//
+// Generated files carry a GENERATED marker so the cleaner only ever deletes its own.
+const path = require('path');
+const jetpack = require('fs-jetpack');
+
+// Page path the panel lives at → where its consumer-layer assets must sit.
+const REL_CSS = 'src/assets/css/pages/test/libraries/layers/index.scss';
+const REL_JS = 'src/assets/js/pages/test/libraries/layers/index.js';
+
+const MARKER = 'GENERATED — UJ_TEST_LAYERS';
+
+// NOTE: a consumer page-CSS file shares the SAME output bundle as the framework's
+// base page CSS, so it must @use the base (like every real consumer page file) to
+// COMPOSE with it rather than replace it. The base lives at the same page path under
+// UJM's css/, importable via the SASS loadPaths (which include UJM's dist/assets/css).
+const CSS_CONTENT = `// ${MARKER} (auto-removed on the next build; do not commit)
+// Consumer layer of the /test/libraries/layers panel → turns the "css-consumer" dot green.
+@use 'pages/test/libraries/layers/index' as *;
+
+.layer-dot[data-layer="css-consumer"] {
+  background: #30a46c; // green
+}
+`;
+
+const JS_CONTENT = `// ${MARKER} (auto-removed on the next build; do not commit)
+// Consumer layer of the /test/libraries/layers panel → turns the "js-consumer" dot green.
+export default ({ manager, options }) => {
+  const dot = document.querySelector('.layer-dot[data-layer="js-consumer"]');
+  if (dot) {
+    dot.style.background = '#30a46c';
+  }
+  console.log('[test-layer] consumer JS ran → js-consumer dot green');
+};
+`;
+
+// Delete a generated file only if it still carries our marker (never clobber a real
+// consumer file someone legitimately created at this path).
+function removeIfGenerated(absPath) {
+  if (!jetpack.exists(absPath)) {
+    return false;
+  }
+  const contents = jetpack.read(absPath) || '';
+  if (contents.includes(MARKER)) {
+    jetpack.remove(absPath);
+    // Clean up now-empty generated dirs (best effort)
+    jetpack.remove(path.dirname(absPath) + '/.keep'); // no-op if absent
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Manage the consumer-layer test fixtures (dev only).
+ * Always cleans prior generated files; generates fresh ones when UJ_TEST_LAYERS=true.
+ * @param {object} Manager - UJM build Manager
+ * @param {object} logger - task logger (optional)
+ */
+function manageTestLayers(Manager, logger) {
+  // Never touch anything in a production build
+  if (Manager.isBuildMode()) {
+    return;
+  }
+
+  const cssPath = path.resolve(process.cwd(), REL_CSS);
+  const jsPath = path.resolve(process.cwd(), REL_JS);
+
+  // 1) Always clean previously-generated files
+  const removed = [removeIfGenerated(cssPath), removeIfGenerated(jsPath)].filter(Boolean).length;
+
+  // 2) Generate when explicitly requested
+  const enabled = process.env.UJ_TEST_LAYERS === 'true';
+  if (enabled) {
+    jetpack.write(cssPath, CSS_CONTENT);
+    jetpack.write(jsPath, JS_CONTENT);
+    if (logger) {
+      logger.log('UJ_TEST_LAYERS: generated consumer test-layer files (auto-removed next run)');
+    }
+  } else if (removed > 0 && logger) {
+    logger.log(`UJ_TEST_LAYERS: cleaned ${removed} stale generated test-layer file(s)`);
+  }
+}
+
+module.exports = manageTestLayers;

package/dist/index.js

@@ -66,10 +66,17 @@ class Manager {
           .catch(e => console.error('Failed to load ultimate-jekyll-manager.js:', e))
       );
 
+      // Theme page module path (resolved via the __theme__ webpack alias)
+      const themeModulePathFull = `__theme__/pages/${pageModulePath}`;
+
       console.log(`Page-specific module loading: #main/${pageModulePathFull}`);
+      console.log(`Page-specific module loading: #theme/${themeModulePathFull}`);
       console.log(`Page-specific module loading: #project/${pageModulePathFull}`);
 
-      // Load page-specific scripts
+      // Load page-specific scripts.
+      // Three layers, executed in order: #main (framework default) → #theme
+      // (active theme) → #project (consumer). Mirrors the page-CSS cascade.
+      // A missing module at any layer is a no-op — no fallback needed.
       modulePromises.push(
         // Import the main page-specific script
         import(`__main_assets__/js/pages/${pageModulePath}`)
@@ -85,11 +92,29 @@ class Manager {
           })
       );
 
+      modulePromises.push(
+        // Import the active theme's page-specific script.
+        // webpackInclude restricts the dynamic-import context to .js files — the
+        // theme's pages/ dir also contains page CSS (.scss), which must NOT be
+        // pulled into the JS context (webpack would try to parse it as JS).
+        import(/* webpackInclude: /\.js$/ */ `__theme__/pages/${pageModulePath}`)
+          .then(mod => {
+            modules[1] = { tag: 'theme', default: mod?.default };
+          })
+          .catch(e => {
+            if (this.isNotFound(e, pageModulePath)) {
+              console.warn(`Page-specific module missing: #theme/${themeModulePathFull}`);
+            } else {
+              console.error(`Page-specific module error: #theme/${themeModulePathFull}`, e);
+            }
+          })
+      );
+
       modulePromises.push(
         // Import the project page-specific script
         import(`__project_assets__/js/pages/${pageModulePath}`)
           .then(mod => {
-            modules[1] = { tag: 'project', default: mod?.default };
+            modules[2] = { tag: 'project', default: mod?.default };
           })
           .catch(e => {
             if (this.isNotFound(e, pageModulePath)) {
@@ -111,12 +136,13 @@ class Manager {
         }
 
         // Execute the module function
+        const modPathLabel = mod.tag === 'theme' ? themeModulePathFull : pageModulePathFull;
         try {
-          console.log(`Page-specific module loaded: #${mod.tag}/${pageModulePathFull}`);
+          console.log(`Page-specific module loaded: #${mod.tag}/${modPathLabel}`);
 
           await mod.default({ manager: this, options });
         } catch (e) {
-          console.error(`Page-specific module error: #${mod.tag}/${pageModulePathFull}`, e);
+          console.error(`Page-specific module error: #${mod.tag}/${modPathLabel}`, e);
           break; // Stop execution if any module fails
         }
       }

package/dist/test/runner.js

@@ -50,6 +50,10 @@ async function run(options = {}) {
   console.log('');
   console.log(chalk.bold('  Ultimate Jekyll Manager Tests'));
 
+  // Run the optional test/_init.js setup() hooks (framework + consumer) ONCE,
+  // before any suite. There is no cleanup hook — tests clean up after themselves.
+  await runInitSetups();
+
   const results = { passed: 0, failed: 0, skipped: 0, tests: [] };
 
   if (sources.framework.length > 0) {
@@ -399,4 +403,62 @@ function relativizePath(file, source) {
   return path.relative(path.join(process.cwd(), 'test'), file);
 }
 
+// ---------------------------------------------------------------------------
+// test/_init.js — pre-test lifecycle hook (setup only)
+//
+// Mirrors the backend framework's hook so all four frameworks share one shape.
+// A project may add `<cwd>/test/_init.js` exporting a FUNCTION —
+// `module.exports = (ctx) => ({ setup })` — called with `{ projectRoot }` and
+// returning an object with an async `setup({ projectRoot })` that runs ONCE
+// before any suite (e.g. to scaffold a fixture file the boot layer needs).
+// There is no `cleanup` hook: tests clean up after themselves. Unlike the
+// backend framework, there is no `accounts` field here — these frameworks have
+// no auth/user system.
+// ---------------------------------------------------------------------------
+
+function loadInit(testDir, label) {
+  const initPath = path.join(testDir, '_init.js');
+
+  if (!jetpack.exists(initPath)) {
+    return {};
+  }
+
+  try {
+    const fn = require(initPath);
+
+    if (typeof fn !== 'function') {
+      console.log(chalk.red(`  ✗ ${label} test/_init.js must export a function: module.exports = (ctx) => ({ ... })`));
+      return {};
+    }
+
+    const mod = fn({ projectRoot: process.cwd() });
+    return mod && typeof mod === 'object' ? mod : {};
+  } catch (e) {
+    console.log(chalk.red(`  ✗ Failed to load ${label} test/_init.js: ${e.message}`));
+    return {};
+  }
+}
+
+async function runInitSetups() {
+  const frameworkTestsDir = path.resolve(__dirname, '../../test');
+  const projectTestsDir = path.join(process.cwd(), 'test');
+
+  const hooks = [
+    loadInit(frameworkTestsDir, 'framework'),
+    loadInit(projectTestsDir, 'project'),
+  ];
+
+  const setups = hooks.filter((h) => typeof h.setup === 'function').map((h) => h.setup);
+
+  for (const setup of setups) {
+    process.stdout.write(chalk.gray('  Running test/_init.js setup... '));
+    try {
+      await setup({ projectRoot: process.cwd() });
+      console.log(chalk.green('✓'));
+    } catch (e) {
+      console.log(chalk.red(`✗ (${e.message})`));
+    }
+  }
+}
+
 module.exports = { run, SkipError };

package/dist/test/suites/build/manager.test.js

@@ -86,18 +86,25 @@ module.exports = {
       },
     },
     {
-      name: 'getEnvironment maps server flag to environment string',
+      name: 'getEnvironment maps to development/testing/production',
       run: async (ctx) => {
         const Manager = require('../../../build.js');
-        const original = process.env.UJ_IS_SERVER;
+        const origServer = process.env.UJ_IS_SERVER;
+        const origTest = process.env.UJ_TEST_MODE;
         try {
+          // Testing wins over everything.
+          process.env.UJ_TEST_MODE = 'true';
+          process.env.UJ_IS_SERVER = 'true';
+          ctx.expect(Manager.getEnvironment()).toBe('testing');
+          // With testing cleared, server flag → production; absent → development.
+          delete process.env.UJ_TEST_MODE;
           process.env.UJ_IS_SERVER = 'true';
           ctx.expect(Manager.getEnvironment()).toBe('production');
           delete process.env.UJ_IS_SERVER;
           ctx.expect(Manager.getEnvironment()).toBe('development');
         } finally {
-          if (original === undefined) delete process.env.UJ_IS_SERVER;
-          else process.env.UJ_IS_SERVER = original;
+          if (origServer === undefined) delete process.env.UJ_IS_SERVER; else process.env.UJ_IS_SERVER = origServer;
+          if (origTest === undefined) delete process.env.UJ_TEST_MODE; else process.env.UJ_TEST_MODE = origTest;
         }
       },
     },

package/dist/test/suites/build/mode-helpers.test.js

@@ -11,7 +11,7 @@ module.exports = {
       name: 'helpers attach to Manager statically AND on prototype',
       run: async (ctx) => {
         const Manager = require('../../../build.js');
-        for (const name of ['isTesting', 'isDevelopment', 'isProduction', 'getVersion']) {
+        for (const name of ['getEnvironment', 'isTesting', 'isDevelopment', 'isProduction', 'getVersion']) {
           ctx.expect(typeof Manager[name]).toBe('function');
           ctx.expect(typeof Manager.prototype[name]).toBe('function');
         }
@@ -35,17 +35,69 @@ module.exports = {
       },
     },
     {
-      name: 'isDevelopment false when UJ_BUILD_MODE=true',
+      name: 'isDevelopment false / isProduction true when UJ_BUILD_MODE=true (and not testing)',
       run: async (ctx) => {
         const Manager = require('../../../build.js');
         const original = process.env.UJ_BUILD_MODE;
+        const origTest = process.env.UJ_TEST_MODE;
         try {
+          delete process.env.UJ_TEST_MODE; // isolate the build-mode branch from testing precedence
           process.env.UJ_BUILD_MODE = 'true';
           ctx.expect(Manager.isDevelopment()).toBe(false);
           ctx.expect(Manager.isProduction()).toBe(true);
         } finally {
           if (original === undefined) delete process.env.UJ_BUILD_MODE;
           else process.env.UJ_BUILD_MODE = original;
+          if (origTest !== undefined) process.env.UJ_TEST_MODE = origTest;
+        }
+      },
+    },
+    {
+      name: 'environments are mutually exclusive — testing wins under UJ_TEST_MODE',
+      run: async (ctx) => {
+        const Manager = require('../../../build.js');
+        // These tests run under UJ_TEST_MODE=true → testing wins; dev and prod are false.
+        ctx.expect(Manager.isTesting()).toBe(true);
+        ctx.expect(Manager.isDevelopment()).toBe(false);
+        ctx.expect(Manager.isProduction()).toBe(false);
+      },
+    },
+    {
+      // The core invariant of the SSOT refactor: is*() DERIVE from getEnvironment(), so they
+      // can NEVER disagree with it, and exactly one is always true. (In build-time Node `window`
+      // is undefined, so getEnvironment() resolves via the env-var fallback.)
+      name: 'invariant: is*() exactly matches getEnvironment() + mutually exclusive (every scenario)',
+      run: async (ctx) => {
+        const Manager = require('../../../build.js');
+        const prevTest = process.env.UJ_TEST_MODE;
+        const prevBuild = process.env.UJ_BUILD_MODE;
+        const prevServer = process.env.UJ_IS_SERVER;
+        const prevNode = process.env.NODE_ENV;
+        const scenarios = [
+          { env: { UJ_TEST_MODE: 'true', UJ_BUILD_MODE: 'true' }, expect: 'testing' },
+          { env: { UJ_BUILD_MODE: 'true' },                       expect: 'production' },
+          { env: { UJ_IS_SERVER: 'true' },                        expect: 'production' },
+          { env: { NODE_ENV: 'development' },                     expect: 'development' },
+          { env: {},                                              expect: 'development' }, // UJM defaults dev (signal always baked in)
+        ];
+        try {
+          for (const s of scenarios) {
+            delete process.env.UJ_TEST_MODE; delete process.env.UJ_BUILD_MODE;
+            delete process.env.UJ_IS_SERVER; delete process.env.NODE_ENV;
+            for (const k of Object.keys(s.env)) process.env[k] = s.env[k];
+            const e = Manager.getEnvironment();
+            ctx.expect(e).toBe(s.expect);
+            ctx.expect(Manager.isDevelopment()).toBe(e === 'development');
+            ctx.expect(Manager.isTesting()).toBe(e === 'testing');
+            ctx.expect(Manager.isProduction()).toBe(e === 'production');
+            const trueCount = [Manager.isDevelopment(), Manager.isTesting(), Manager.isProduction()].filter(Boolean).length;
+            ctx.expect(trueCount).toBe(1);
+          }
+        } finally {
+          if (prevTest === undefined) delete process.env.UJ_TEST_MODE; else process.env.UJ_TEST_MODE = prevTest;
+          if (prevBuild === undefined) delete process.env.UJ_BUILD_MODE; else process.env.UJ_BUILD_MODE = prevBuild;
+          if (prevServer === undefined) delete process.env.UJ_IS_SERVER; else process.env.UJ_IS_SERVER = prevServer;
+          if (prevNode === undefined) delete process.env.NODE_ENV; else process.env.NODE_ENV = prevNode;
         }
       },
     },

package/dist/utils/mode-helpers.js

@@ -2,51 +2,72 @@
 // (build-time `src/build.js`, frontend ES module `src/index.js`, service worker
 // `src/service-worker.js`).
 //
-// Three orthogonal concepts:
-//   isDevelopment() — true when running in dev mode (jekyll dev server, not a
-//                     production build). Detected via NODE_ENV / UJ_BUILD_MODE /
-//                     site config.
-//   isProduction()  — inverse. Running a production-built `_site/`.
-//   isTesting()     — true when UJM's test framework is running this process. Set
-//                     by UJM's test runners (UJ_TEST_MODE=true) and consumer test
-//                     setups that want the same signal.
+// `getEnvironment()` is the SINGLE SOURCE OF TRUTH: it is the ONLY function that reads the
+// raw signals (UJ_TEST_MODE / window.Configuration.uj.environment / UJ_BUILD_MODE /
+// UJ_IS_SERVER / NODE_ENV) and resolves them to exactly ONE of three mutually-exclusive
+// values. The three is*() checks DERIVE from it — they never read raw signals themselves,
+// so they can never disagree with getEnvironment().
 //
-// Use these whenever behavior should differ by *what kind of process* you're in —
-// shorter timeouts in tests, prompts suppressed in tests, dev-only banners.
-// Don't use them for "should we hit dev or prod backends" — that's a config
-// concern; use `getEnvironment()` for that (in build.js).
+//   isDevelopment() — `getEnvironment() === 'development'`: running in dev mode (jekyll dev
+//                     server, not a production build), and NOT testing.
+//   isTesting()     — `getEnvironment() === 'testing'`: UJM's test framework is running this
+//                     process (UJ_TEST_MODE=true). TAKES PRECEDENCE — a test run is not dev.
+//   isProduction()  — `getEnvironment() === 'production'`: running a production-built `_site/`,
+//                     and NOT testing. A real positive check — NOT `!isDevelopment()`.
 //
-// Context caveat: in build-time Node (gulp / CLI), `window` is undefined. We
-// detect via `typeof window` so the same code works in every context. In test
-// mode the browser-side check is short-circuited via UJ_TEST_MODE / global so
-// `isTesting()` returns a stable value regardless of which test layer is running.
+// To gate "anything non-production" use `!isProduction()` or `isDevelopment() ||
+// isTesting()` intentionally — never assume two values.
+//
+// Context caveat: in build-time Node (gulp / CLI), `window` is undefined. getEnvironment()
+// detects via `typeof window` so the same code works in every context. Browser detection
+// reads `window.Configuration.uj.environment` (baked into the page at build time).
 
-function isDevelopment() {
-  // Build-time Node fallback.
+// getEnvironment() — the SINGLE SOURCE OF TRUTH. Reads every raw signal and resolves to
+// exactly ONE of 'development' | 'testing' | 'production' (mutually exclusive; testing wins).
+// Precedence: testing → production → development.
+function getEnvironment() {
+  // 1. Testing wins — set by UJM's test runners / harness, or a testing-baked build.
+  //    Works in Node (process.env), browser (globalThis set before consumer JS), and
+  //    config-baked builds (window.Configuration.uj.environment === 'testing').
+  if (typeof process !== 'undefined' && process.env && process.env.UJ_TEST_MODE === 'true') return 'testing';
+  if (typeof globalThis !== 'undefined' && globalThis.UJ_TEST_MODE === true) return 'testing';
+  if (typeof window !== 'undefined' && window.Configuration && window.Configuration.uj
+    && window.Configuration.uj.environment === 'testing') return 'testing';
+
+  // 2. Build-time Node signals (a production build or the running dev server).
   if (typeof process !== 'undefined' && process.env) {
-    if (process.env.UJ_BUILD_MODE === 'true') return false;
-    if (process.env.NODE_ENV === 'development') return true;
-    if (process.env.UJ_IS_SERVER === 'true') return false;
+    if (process.env.UJ_BUILD_MODE === 'true') return 'production';
+    if (process.env.UJ_IS_SERVER === 'true') return 'production';
+    if (process.env.NODE_ENV === 'development') return 'development';
   }
-  // Browser-side: look at window.Configuration if present.
+
+  // 3. Browser-side: the environment baked into the page at build time.
   if (typeof window !== 'undefined' && window.Configuration && window.Configuration.uj) {
-    if (window.Configuration.uj.environment === 'development') return true;
-    if (window.Configuration.uj.environment === 'production') return false;
+    if (window.Configuration.uj.environment === 'development') return 'development';
+    if (window.Configuration.uj.environment === 'production') return 'production';
   }
-  return false;
+
+  // 4. Default: development. UJM's deployed artifacts ALWAYS carry their signal — the
+  //    browser has `window.Configuration.uj.environment` baked in, and build-time Node
+  //    always sets UJ_BUILD_MODE / UJ_IS_SERVER. So reaching here means a bare tooling /
+  //    local-script context, where development is the sensible answer. (Contrast BEM/EM,
+  //    whose deployed RUNTIME can legitimately lack a signal, so they default to production.)
+  return 'development';
+}
+
+// The three checks DERIVE from getEnvironment() — they never read raw signals, so they can
+// never disagree with it. isDevelopment() is NOT true in testing; isProduction() is a real
+// positive check (never `!isDevelopment()`).
+function isDevelopment() {
+  return getEnvironment() === 'development';
 }
 
 function isProduction() {
-  return !this.isDevelopment();
+  return getEnvironment() === 'production';
 }
 
 function isTesting() {
-  // Canonical signal — set by UJM's test runners and consumer test setups alike.
-  // Works in Node (process.env) AND in browser contexts (the harness preload sets
-  // globalThis.UJ_TEST_MODE before any consumer code runs).
-  if (typeof process !== 'undefined' && process.env && process.env.UJ_TEST_MODE === 'true') return true;
-  if (typeof globalThis !== 'undefined' && globalThis.UJ_TEST_MODE === true) return true;
-  return false;
+  return getEnvironment() === 'testing';
 }
 
 // `getVersion()` — returns UJM's own version string.
@@ -64,19 +85,23 @@ function getVersion() {
 
 // Mix the helpers into a Manager constructor's prototype + the constructor itself
 // (so `Manager.isTesting()` works statically too, matching BEM/EM/BXM pattern).
+// getEnvironment() is the SSOT and is attached here too — build.js no longer defines it.
 function attachTo(Manager) {
-  Manager.prototype.isDevelopment = isDevelopment;
-  Manager.prototype.isProduction  = isProduction;
-  Manager.prototype.isTesting     = isTesting;
-  Manager.prototype.getVersion    = getVersion;
-  Manager.isDevelopment = isDevelopment;
-  Manager.isProduction  = isProduction;
-  Manager.isTesting     = isTesting;
-  Manager.getVersion    = getVersion;
+  Manager.prototype.getEnvironment = getEnvironment;
+  Manager.prototype.isDevelopment  = isDevelopment;
+  Manager.prototype.isProduction   = isProduction;
+  Manager.prototype.isTesting      = isTesting;
+  Manager.prototype.getVersion     = getVersion;
+  Manager.getEnvironment = getEnvironment;
+  Manager.isDevelopment  = isDevelopment;
+  Manager.isProduction   = isProduction;
+  Manager.isTesting      = isTesting;
+  Manager.getVersion     = getVersion;
 }
 
 module.exports = {
   attachTo,
+  getEnvironment,
   isDevelopment,
   isProduction,
   isTesting,

package/docs/assets.md

@@ -2,6 +2,11 @@
 
 This document covers UJM's asset layout, consuming-project overrides, the JSON-driven section configuration system (nav, footer, account dropdown), frontmatter-driven page customization, webpack aliases, and the page module pattern.
 
+> **Authoring or selecting a theme?** The `themes/[theme-id]/` layout/include
+> paths and the `__theme__` SCSS/JS resolution referenced throughout this doc are
+> explained in full — including the classy layout fallback and how to build a new
+> theme — in [docs/themes.md](themes.md).
+
 ## Ultimate Jekyll Manager Files (THIS project)
 
 **CSS:**
@@ -269,7 +274,7 @@ import { getPrerenderedIcon } from '__main_assets__/js/libs/prerendered-icons.js
 import(`__project_assets__/js/pages/${pageModulePath}`)
 ```
 
-**How they work together:** `src/index.js` loads page modules from both aliases — first from `__main_assets__` (UJM defaults), then from `__project_assets__` (project overrides/extensions). If a project module doesn't exist, it gracefully skips. This enables a layered system where UJM provides defaults and consuming projects can extend or override page behavior.
+**How they work together:** `src/index.js` loads page modules from **three** layers, executed in order: `__main_assets__` (UJM default) → `__theme__/pages/...` (active theme) → `__project_assets__` (consumer override/extension). A missing module at any layer gracefully skips. This layered system mirrors the page-CSS cascade — UJM provides defaults, the theme customizes, and the consuming project always gets the final say. See [docs/themes.md → Page-specific JS](themes.md#5-page-specific-js-theme-aware-additive--mirrors-page-css).
 
 **When to use which:**
 - **`__main_assets__`** — When importing UJM-provided libraries, core modules, or referencing UJM's built-in page scripts

package/docs/environment-detection.md

@@ -0,0 +1,85 @@
+# Environment Detection
+
+`getEnvironment()` returns exactly ONE of three mutually-exclusive, exhaustive values:
+
+```javascript
+Manager.getEnvironment()    // 'development' | 'testing' | 'production'
+
+Manager.isDevelopment()     // true ONLY in development
+Manager.isTesting()         // true ONLY in testing
+Manager.isProduction()      // true ONLY in production
+```
+
+**The Manager is the single source of truth.** `getEnvironment()` is the ONLY function that reads the raw signals (`UJ_TEST_MODE` / `window.Configuration.uj.environment` / `UJ_BUILD_MODE` / `UJ_IS_SERVER` / `NODE_ENV`). The three `is*()` checks **derive** from it live on every call — they never read raw signals themselves, so they can never disagree with `getEnvironment()`.
+
+**One implementation, mixed into every Manager.** UJM mixes the helpers into the build-time Manager and the frontend Manager via `attachTo(Manager)` from [src/utils/mode-helpers.js](../src/utils/mode-helpers.js), available as both prototype methods (`manager.isTesting()`) and statics (`Manager.isTesting()`).
+
+```javascript
+manager.getEnvironment()    // same answer build-time and in the browser
+Manager.isTesting()         // static form, for build-time scripts
+```
+
+**Resolution order:** testing wins first, then production, else development. The three checks are mutually exclusive — exactly one is true. `isDevelopment()` is **false** during testing, and `isProduction()` is a real positive check (it is NOT `!isDevelopment()`).
+
+## Available helpers
+
+| Helper | Returns |
+|---|---|
+| `getEnvironment()` | `'development' \| 'testing' \| 'production'` — the SSOT resolver; the only reader of raw signals. |
+| `isDevelopment()` | `true` ONLY in development (jekyll dev server, not a production build), and NOT testing. Derives from `getEnvironment()`. |
+| `isTesting()` | `true` ONLY in testing (`UJ_TEST_MODE === 'true'`). **Takes precedence** — a test run is not development. |
+| `isProduction()` | `true` ONLY in production (a production-built `_site/`). A **real positive check** — NOT `!isDevelopment()`. |
+
+## Gating side effects — use the INTENTIONAL check
+
+Because there are three environments, never gate a side effect on a two-value assumption. State what you mean:
+
+```javascript
+// Production-only (skip real telemetry / production behavior in dev AND testing):
+if (isProduction())  { /* do the real thing */ }
+if (!isProduction()) { /* skip / use the safe local behavior */ }
+
+// Local-or-test (anything that should run in BOTH dev and testing):
+if (isDevelopment() || isTesting()) { /* localhost URL, observable redirect delay, dev banners */ }
+```
+
+**Avoid** `if (!isDevelopment())` or `if (env !== 'development')` to gate production behavior — those wrongly include `testing` as production and leak real side effects during test runs. This is the bug class that motivated the 3-value model.
+
+## URL helpers
+
+UJM does **not** own backend URL helpers. Frontend page code resolves backend URLs through the `web-manager` runtime singleton:
+
+```javascript
+webManager.getApiUrl()  // the brand's API URL — from web-manager, not UJM
+```
+
+`web-manager`'s `getApiUrl()` follows the same convention as the sister frameworks — local in development/testing, production otherwise — so the rule "call the getter, never hardcode" still applies; the implementation just lives in `web-manager`. UJM's own URL helper is build-time only: `Manager.getWorkingUrl()` returns the BrowserSync dev-server URL (or the configured project URL) for the running dev server.
+
+## Where they live
+
+Source: [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) for `getEnvironment()` + `is*()` + `getVersion()`. The module exposes the functions plus an `attachTo(Manager)` mixin. Attached at the bottom of the build-time Manager [src/build.js](../src/build.js) and the frontend Manager [src/index.js](../src/index.js) — so build-time scripts and browser code resolve the environment identically.
+
+## How detection works
+
+`getEnvironment()` resolves in this precedence order:
+
+1. **Testing** — `process.env.UJ_TEST_MODE === 'true'`, `globalThis.UJ_TEST_MODE === true`, or a build baked with `window.Configuration.uj.environment === 'testing'` (set by the harness before any consumer JS runs). A test run is a test run regardless of any other signal.
+2. **Build-time signals** — `UJ_BUILD_MODE === 'true'` → production; `UJ_IS_SERVER === 'true'` → production; `NODE_ENV === 'development'` → development.
+3. **Browser signal** — `window.Configuration.uj.environment` (`'development'` / `'production'`), baked into the page at build time.
+4. **Default** — development. UJM's deployed artifacts always carry their signal (the browser has `window.Configuration.uj.environment` baked in; build-time Node always sets `UJ_BUILD_MODE`/`UJ_IS_SERVER`), so reaching here means a bare tooling / local-script context where development is correct. (Contrast BEM/EM, whose deployed *runtime* can legitimately lack a signal, so they default to **production**.)
+
+## Adding a new helper
+
+Write the function in [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) (or a new `src/utils/<topic>-helpers.js` module), expose it from `attachTo(Manager)`, and ensure both the build-time and frontend Managers call `attachTo`. For anything environment-derived, derive from `getEnvironment()` rather than reading `process.env` / `window.Configuration` directly, so there is one source of truth and no chance of drift.
+
+## Why this matters
+
+**One signal, used everywhere.** The test runner sets `UJ_TEST_MODE=true`; every piece of code that calls `isTesting()` (framework or consumer) then sees `true` — no need to invent a per-module env var.
+
+**Sub-modules check the same signal.** When framework code (a network probe, a prompt) needs to skip side effects in tests, it checks `isTesting()` — the same answer the consumer's own code gets. No drift.
+
+**`is*()` can never disagree with `getEnvironment()`.** Because the checks derive from the single resolver instead of reading raw signals (`window.Configuration` vs `UJ_BUILD_MODE`), there is exactly one definition of "what environment is this," and a wrong-but-confident gate is structurally impossible.
+
+## See also
+
+- [test-framework.md](test-framework.md) — `UJ_TEST_MODE` is set automatically by the test runners; `--integration` gates real external APIs.