ultimate-jekyll-manager 1.4.2 → 1.5.0

package/dist/defaults/dist/pages/test/libraries/layers.html

@@ -0,0 +1,57 @@
+---
+### ALL PAGES ###
+layout: themes/[ site.theme.id ]/frontend/core/minimal
+permalink: /test/libraries/layers
+
+### REGULAR PAGES ###
+sitemap:
+  include: false
+meta:
+  title: "Asset layers"
+  description: "Live status of the Global → Theme → Consumer page-asset cascade (CSS + JS)."
+  breadcrumb: "Asset layers"
+  index: false
+---
+
+<!--
+  ASSET-LAYER TEST PANEL
+  Shows the three-layer page-asset cascade (CSS and JS), loaded in this order:
+    1. Global   — the framework's own page-specific file
+    2. Theme    — the active theme's page-specific file
+    3. Consumer — the consuming project's page-specific file
+  Each dot starts RED. A layer turns ITS OWN dot green when it loads (CSS via a
+  selector, JS by setting the dot's color). A RED dot = that layer has no file
+  for this page (the normal state for layers nobody customized).
+
+  The Consumer layer only loads if the consuming project has its own files at
+  src/assets/{css,js}/pages/test/libraries/layers/index.*. To prove it live
+  without committing anything, run with the UJ_TEST_LAYERS flag (see docs/themes.md
+  → "Asset-layer test panel"), which generates those files at build start and
+  auto-removes them on the next run.
+-->
+<section class="py-5">
+  <div class="container" style="max-width: 720px;">
+    <h1 class="mb-2">Asset layers</h1>
+    <p class="text-muted mb-4">
+      Each <strong>page-specific</strong> asset loads in three layers, in order:
+      <strong>Global → Theme → Consumer</strong> — all three are the same
+      <code>pages/&lt;path&gt;</code> file, just from different sources. Each layer turns its
+      own dot <strong>green</strong> when it loads; a <strong>red</strong> dot means that
+      layer has no file for this page (the normal state for layers nobody customized).
+    </p>
+
+    <h2 class="h5 mb-3">Page-specific CSS</h2>
+    <ul class="layer-list list-unstyled mb-4">
+      <li class="layer-row"><span class="layer-dot" data-layer="css-global"></span> Global <span class="text-muted">(framework default)</span></li>
+      <li class="layer-row"><span class="layer-dot" data-layer="css-theme"></span> Theme <span class="text-muted">(active theme)</span></li>
+      <li class="layer-row"><span class="layer-dot" data-layer="css-consumer"></span> Consumer <span class="text-muted">(your project)</span></li>
+    </ul>
+
+    <h2 class="h5 mb-3">Page-specific JS</h2>
+    <ul class="layer-list list-unstyled mb-0">
+      <li class="layer-row"><span class="layer-dot" data-layer="js-global"></span> Global <span class="text-muted">(framework default)</span></li>
+      <li class="layer-row"><span class="layer-dot" data-layer="js-theme"></span> Theme <span class="text-muted">(active theme)</span></li>
+      <li class="layer-row"><span class="layer-dot" data-layer="js-consumer"></span> Consumer <span class="text-muted">(your project)</span></li>
+    </ul>
+  </div>
+</section>

package/dist/defaults/dist/pages/test/libraries/lazy-loading.html

@@ -33,7 +33,7 @@ meta:
 
       <!-- First visible image (should load immediately) -->
       <section>
-        <h2 class="h3 mb-3">1. Above the Fold Image (Lazy Loading Starts Immediately)</h2>
+        <h2 class="h3 mb-3">1. Above the fold image (lazy loading starts immediately)</h2>
         <p>This image is visible on page load, so it should start loading immediately:</p>
         <img data-lazy="@src https://placehold.co/800x400?text=Immediate+Load"
              class="card-img-top lazy"
@@ -50,7 +50,7 @@ meta:
 
       <!-- Lazy loaded images with data-src -->
       <section>
-        <h2 class="h3 mb-3">2. Standard Lazy Loading (data-src)</h2>
+        <h2 class="h3 mb-3">2. Standard lazy loading (data-src)</h2>
         <p>These images use <code>data-src</code> attribute and will load when scrolled into view:</p>
 
         <div class="row g-4 mb-4">
@@ -153,7 +153,7 @@ meta:
 
       <!-- Lazy Classes -->
       <section>
-        <h2 class="h3 mb-3">6. Lazy Loaded Classes</h2>
+        <h2 class="h3 mb-3">6. Lazy loaded classes</h2>
         <p>These elements get classes added when they come into view:</p>
 
         <div class="row g-4">
@@ -194,7 +194,7 @@ meta:
 
       <!-- Iframes -->
       <section>
-        <h2 class="h3 mb-3">7. Lazy Loaded Iframes</h2>
+        <h2 class="h3 mb-3">7. Lazy loaded iframes</h2>
         <p>YouTube videos and other iframes that load on scroll:</p>
 
         <div class="ratio ratio-16x9 mb-4">
@@ -242,7 +242,7 @@ meta:
 
       <!-- Video -->
       <section>
-        <h2 class="h3 mb-3">9. Lazy Loaded Video</h2>
+        <h2 class="h3 mb-3">9. Lazy loaded video</h2>
         <p>HTML5 video that loads when scrolled into view:</p>
 
         <video data-lazy="@src https://www.w3schools.com/html/mov_bbb.mp4"
@@ -257,7 +257,7 @@ meta:
 
       <!-- Slow Loading Test with Picsum -->
       <section>
-        <h2 class="h3 mb-3">10. Slow Loading Test (Loading Animation Demo)</h2>
+        <h2 class="h3 mb-3">10. Slow loading test (loading animation demo)</h2>
         <p>These images from picsum.photos load slowly, so you can see the loading animation:</p>
 
         <div class="row g-4">
@@ -325,7 +325,7 @@ meta:
 
       <!-- Error handling test -->
       <section>
-        <h2 class="h3 mb-3">12. Error Handling Test</h2>
+        <h2 class="h3 mb-3">12. Error handling test</h2>
         <p>These images have invalid URLs to test error handling:</p>
 
         <div class="row g-4">
@@ -373,7 +373,7 @@ meta:
 
       <!-- Dynamic content test -->
       <section>
-        <h2 class="h3 mb-3">14. Dynamic Content Test</h2>
+        <h2 class="h3 mb-3">14. Dynamic content test</h2>
         <p>Click the button below to dynamically add new lazy-loaded images to test MutationObserver:</p>
 
         <button id="add-dynamic-images" class="btn btn-primary mb-4">Add dynamic images</button>

package/dist/defaults/dist/sitemap.html

@@ -54,7 +54,7 @@ web_manager:
   {%- endif -%}
 
   {% assign url_parts = page.url | split: '/' %}
-  {% assign section_name = "Root Pages" %}
+  {% assign section_name = "Root pages" %}
 
   {% if url_parts.size > 2 %}
     {% assign section_name = url_parts[1] | replace: '-', ' ' | replace: '_', ' ' | capitalize %}
@@ -104,7 +104,7 @@ web_manager:
               {%- endif -%}
 
               {% assign url_parts = page.url | split: '/' %}
-              {% assign page_section = "Root Pages" %}
+              {% assign page_section = "Root pages" %}
 
               {% if url_parts.size > 2 %}
                 {% assign page_section = url_parts[1] | replace: '-', ' ' | replace: '_', ' ' | capitalize %}

package/dist/defaults/src/_config.yml

@@ -277,6 +277,8 @@ manifest:
 translation:
   enabled: false
   default: "en"
+  exclude:
+    - "blog"
   languages:
     - "zh"
     - "es"

package/dist/defaults/test/_init.js

@@ -0,0 +1,10 @@
+/**
+ * Test lifecycle hook for this project. Runs once before any suite (not a test itself).
+ * See ultimate-jekyll-manager/docs/test-framework.md → "test/_init.js".
+ */
+
+module.exports = ({ projectRoot }) => ({
+  // Seed any fixture a suite needs before it runs.
+  async setup() {
+  },
+});

package/dist/gulp/tasks/defaults.js

@@ -8,6 +8,7 @@ const path = require('path');
 const { minimatch } = require('minimatch');
 const { template } = require('node-powertools');
 const createTemplateTransform = require('./utils/template-transform');
+const manageTestLayers = require('./utils/manage-test-layers');
 const argv = require('yargs')(process.argv.slice(2)).parseSync();
 const JSON5 = require('json5');
 
@@ -391,6 +392,13 @@ function defaults(complete, changedFile) {
   logger.log('Starting...');
   Manager.logMemory(logger, 'Start');
 
+  // Test-layer fixtures (dev only): clean any prior generated files, and generate
+  // fresh ones into the consumer src when UJ_TEST_LAYERS=true — at build START so
+  // sass + jekyll pick them up. Only on a full run, not per-changed-file in watch.
+  if (!changedFile) {
+    manageTestLayers(Manager, logger);
+  }
+
   // Use changedFile if provided, otherwise use all inputs
   const filesToProcess = changedFile ? [changedFile] : input;
   logger.log('input', filesToProcess)

package/dist/gulp/tasks/imagemin.js

@@ -6,6 +6,7 @@ const glob = require('glob').globSync;
 const responsive = require('gulp-responsive-modern');
 const sharp = require('sharp');
 const path = require('path');
+const { Transform } = require('stream');
 const jetpack = require('fs-jetpack');
 const GitHubCache = require('./utils/github-cache');
 
@@ -188,6 +189,7 @@ async function imagemin(complete) {
   // above (so `npm start` never blocks on this), letting BrowserSync reload as images land later.
   await new Promise((resolve, reject) => {
     src(filesToProcess, { base: 'src/assets/images' })
+      .pipe(lowercaseExtTransform())
       .pipe(responsive({
         [`**/${RESPONSIVE_GLOB}`]: responsiveConfigs
       }, {
@@ -358,6 +360,24 @@ async function rewriteOversizedSources(files) {
   }
 }
 
+// Lowercase the extension on each Vinyl file's path before piping into gulp-responsive-modern.
+// gulp-responsive-modern's lib/format.js uses a case-sensitive switch on path.extname() and returns
+// the string 'unsupported' for anything else, which then crashes sharp.toFormat(). Files saved
+// straight off a camera (IMG_3119.JPG) hit this. Rewriting the Vinyl path in-stream keeps the
+// on-disk file untouched while letting the plugin recognize the format.
+function lowercaseExtTransform() {
+  return new Transform({
+    objectMode: true,
+    transform(file, _enc, cb) {
+      const ext = path.extname(file.path);
+      if (ext && ext !== ext.toLowerCase()) {
+        file.path = file.path.slice(0, -ext.length) + ext.toLowerCase();
+      }
+      cb(null, file);
+    },
+  });
+}
+
 // Build responsive configurations from PICTURE_SIZES
 function getResponsiveConfigs() {
   const configs = [];
@@ -552,21 +572,26 @@ function logImageStatistics(stats, startTime, endTime) {
   // Size reduction stats
   if (stats.sizeBefore > 0 && stats.sizeAfter > 0) {
     const savedPercent = ((stats.savedBytes / stats.sizeBefore) * 100).toFixed(1);
+    const label = stats.savedBytes < 0 ? 'Total added' : 'Total saved';
     logger.log('\n💾 Size Reduction:');
     logger.log(`   Original size:       ${formatBytes(stats.sizeBefore)}`);
     logger.log(`   Optimized size:      ${formatBytes(stats.sizeAfter)}`);
-    logger.log(`   Total saved:         ${formatBytes(stats.savedBytes)} (${savedPercent}%)`);
+    logger.log(`   ${label}:         ${formatBytes(Math.abs(stats.savedBytes))} (${savedPercent}%)`);
   }
 
   logger.log('═══════════════════════════════════════\n');
 }
 
-// Helper to format bytes
+// Helper to format bytes. Handles negative inputs — when responsive variants (8 per source)
+// sum to more than the cached original, savedBytes goes negative; without the absolute-value
+// guard, Math.log(negative) is NaN and the suffix index becomes NaN -> "NaN undefined".
 function formatBytes(bytes, decimals = 2) {
   if (bytes === 0) return '0 Bytes';
+  const sign = bytes < 0 ? '-' : '';
+  const abs = Math.abs(bytes);
   const k = 1024;
   const dm = decimals < 0 ? 0 : decimals;
-  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
-  const i = Math.floor(Math.log(bytes) / Math.log(k));
-  return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.min(Math.floor(Math.log(abs) / Math.log(k)), sizes.length - 1);
+  return sign + parseFloat((abs / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
 }

package/dist/gulp/tasks/sass.js

@@ -44,6 +44,24 @@ const bundleFiles = [
   'src/assets/css/bundles/*.scss',
 ];
 
+// Build the active theme's page-CSS globs, but ONLY for `pages` dirs that exist —
+// gulp's src() throws ENOENT when it scandirs a missing directory. Project theme
+// takes priority over the package theme (matches the __theme__ resolution rule).
+function themePageGlobs() {
+  if (!config.theme.id) {
+    return [];
+  }
+
+  const candidates = [
+    path.resolve(rootPathProject, 'src/assets/themes', config.theme.id, 'pages'),
+    path.resolve(rootPathPackage, 'dist/assets/themes', config.theme.id, 'pages'),
+  ];
+
+  return candidates
+    .filter((dir) => jetpack.exists(dir))
+    .map((dir) => `${dir}/**/*.scss`);
+}
+
 // Glob
 const input = [
   // Bundle files (admin, and any future bundles)
@@ -56,10 +74,23 @@ const input = [
   `${rootPathPackage}/dist/assets/css/pages/**/*.scss`,
   'src/assets/css/pages/**/*.scss',
 
+  // Theme page-specific CSS (theme-aware page styles).
+  // Compiles to a SEPARATE bundle (pages/<path>/index.<themeId>.bundle.css)
+  // that head.html links IN ADDITION to the base + consumer page bundles.
+  // Missing = nothing loads (component styles handle it) — no fallback needed.
+  //
+  // Only include a glob whose base `pages` dir exists — gulp's src() throws ENOENT
+  // if it scandirs a non-existent directory. Most consumers don't shadow the theme,
+  // so the project-side path usually won't exist.
+  ...themePageGlobs(),
+
   // Files to exclude
   // '!dist/**',
 ];
 
+// Marker appended to theme page bundles so head.html can find them by theme id.
+const THEME_PAGE_SUFFIX = config.theme.id ? `.${config.theme.id}` : '';
+
 // Additional files to watch (but not compile as entry points)
 const watchInput = [
   // Watch the paths we're compiling
@@ -345,7 +376,17 @@ function sass(complete) {
     .pipe(cleanCSS({
       format: Manager.actLikeProduction() ? 'compressed' : 'beautify',
     }))
-    .pipe(rename((file) => {
+    .pipe(rename((file, vinyl) => {
+      // Theme page CSS originates from .../themes/<id>/pages/... — tag the bundle
+      // with the theme id (e.g. index.neobrutalism.bundle.css) so it compiles to
+      // its own file that head.html links alongside the base + consumer bundles.
+      const sourcePath = (vinyl && vinyl.history[0]) || '';
+      const isThemePage = THEME_PAGE_SUFFIX
+        && sourcePath.replace(/\\/g, '/').includes(`/themes/${config.theme.id}/pages/`);
+      if (isThemePage) {
+        file.basename += THEME_PAGE_SUFFIX;
+      }
+
       // Add bundle to the name
       file.basename += '.bundle';
 
@@ -355,7 +396,7 @@ function sass(complete) {
       bundleNames.push('main'); // main.scss is always a root bundle
 
       // Check if this is a root-level bundle
-      const baseName = file.basename.replace('.bundle', '');
+      const baseName = file.basename.replace('.bundle', '').replace(THEME_PAGE_SUFFIX, '');
       const isBundle = bundleNames.includes(baseName);
 
       // Check

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;
         }
       },
     },