ultimate-jekyll-manager 1.4.3 → 1.5.0

package/docs/test-framework.md

@@ -2,6 +2,28 @@
 
 UJM ships a built-in three-layer test harness. `npx mgr test` discovers framework suites from `<ujm>/dist/test/suites/**/*.js` and consumer suites from `<cwd>/test/**/*.js`, partitions by `layer`, and runs each layer in the right environment. Same shape as the sister harnesses in EM (electron-manager) and BXM (browser-extension-manager).
 
+## 🚫 NEVER mock — test against the real harness (HARD RULE)
+
+**Do NOT hand-roll fake/stub/mock objects.** Every test runs against a real environment, and the harness hands the test the real thing — use it:
+
+- **`build` layer** gets the **real** `Manager` from `require('ultimate-jekyll-manager/build')` — call its real API (`getConfig`, `getUJMConfig`, `getPackage`, `isTesting`, the gulp pure helpers). Never fake a `Manager` whose `getConfig()` returns canned data.
+- **`page` layer** runs in a **real** headless Chromium tab with real `window`/`document` and the harness-provided `window.Configuration`. Drive the real frontend Manager surface; don't stub DOM globals in your test.
+- **`boot` layer** runs against the **real** built `_site/` served over a **real** HTTP origin — exercise the actually-shipped site through Puppeteer.
+- **Pure functions (zero I/O) are the ONLY thing you call directly** — e.g. `mergeJekyllConfigs`, `validateYAMLFrontMatter`, `createTemplateTransform`, `collectTextNodes`. `require()` them and pass plain inputs. That is NOT mocking — there is nothing to mock. The moment a function touches real I/O (config files, the DOM, the HTTP server, an external API), it MUST run against the real harness/build, not a stub.
+
+If you find yourself writing `const mockX = {...}` to satisfy code under test, STOP — use the real context the layer already provides, or (if it's genuinely pure) call it with plain data.
+
+### The ONLY two exceptions where a narrow stub is allowed
+
+Mock **nothing** by default. There are exactly two cases where the real dependency genuinely cannot run in the test environment — and even then, stub the *smallest possible seam* (one method / one object), restore it immediately, and comment *why*:
+
+1. **A side effect that would destroy the test run itself.** If the real call would kill or corrupt the harness — a process-exit, a destructive `_site/` wipe, a recursive re-invocation of the build/test command — stub *that one call* to a no-op, assert the surrounding logic, then restore. You are preventing the harness from terminating mid-assertion, not faking behavior.
+2. **A real dependency the test environment can't provide.** When the real thing only exists from infra you can't stand up in the current layer (an external service with no local equivalent, a second running instance), a unit test may hand minimal inputs to exercise the logic in isolation — but a real-harness test (`page`/`boot`) MUST still cover the wired path where one exists.
+
+If you can run it for real, you must. These exceptions are not a license to unit-test in isolation when a real-harness layer would work.
+
+**External APIs are skipped in-source, NOT mocked.** UJM build/gulp code that would hit the network (e.g. fetching Firebase auth files) short-circuits in its own source when `Manager.isTesting()` is true — it returns early, it does not return canned/mocked data. See [environment-detection.md](environment-detection.md). If a suite has slower live-integration tests, gate them behind the `--integration` flag (`UJ_TEST_INTEGRATION=1`) and run the real path; anything such a test creates externally MUST be cleaned up by the test (`cleanup`/`inspect` teardown) — the runner does not clean external systems.
+
 ## Quick start
 
 ```bash
@@ -135,7 +157,7 @@ The public surface exposed by `require('ultimate-jekyll-manager/build')` include
 - `Manager.logger(name)` — returns a `Logger` instance
 - `Manager.require(path)` — escape hatch when you really need a UJM transitive dep
 
-See [docs/cross-context-helpers.md](cross-context-helpers.md) for `isTesting`/`isDevelopment` semantics.
+See [docs/environment-detection.md](environment-detection.md) for `isTesting`/`isDevelopment` semantics.
 
 ## Reporter contract — `__UJM_TEST__` JSON-line events
 
@@ -162,12 +184,35 @@ Same protocol as EM (`__EM_TEST__`) and BXM (`__BXM_TEST__`). One marker per fra
 - **Excluded**: any directory starting with `_` (handy for shared helpers).
 - **Framework boot suites** are excluded when the cwd's `package.json#name` is not `ultimate-jekyll-manager` — they target UJM's fixture site, not the consumer's. Consumers write their own boot tests in `<cwd>/test/boot/`.
 
+## `test/_init.js` — pre-test lifecycle hook
+
+The runner loads an optional `test/_init.js` from **both** test roots — the framework (`<UJM>/test/_init.js`) and the consumer project (`<cwd>/test/_init.js`) — and runs it **once, before any suite** (it is NOT itself run as a test; the `_`-prefix keeps it out of discovery). Mirrors the same hook in BEM/EM/BXM so all four frameworks share one shape.
+
+The module **must export a function** — `module.exports = (ctx) => ({ ... })` — called with `{ projectRoot }` and returning the hook object. It may declare:
+
+- `async setup({ projectRoot })` — runs once before the suites, e.g. to scaffold a fixture file the boot layer needs.
+
+There is **no `cleanup` hook** and **no `accounts` field** (unlike BEM — these frameworks have no auth/user system): tests clean up after themselves, so there is nothing project-level to tear down.
+
+```javascript
+// <cwd>/test/_init.js
+const fs = require('fs');
+const path = require('path');
+
+module.exports = ({ projectRoot }) => ({
+  async setup() {
+    // Seed any fixture a suite needs before it runs.
+    fs.mkdirSync(path.join(projectRoot, '.temp'), { recursive: true });
+  },
+});
+```
+
 ## Env vars
 
 | Env | Set by | Purpose |
 |---|---|---|
 | `UJ_TEST_MODE=true`         | `npx mgr test` always | Canonical test signal. `Manager.isTesting()` reads this. Use it to short-circuit network calls / prompts / long timers in code that runs during tests. |
-| `UJ_TEST_INTEGRATION=1`     | `--integration` flag | Opt-in flag for slower integration tests if your suite has them |
+| `UJ_TEST_INTEGRATION=1`     | `--integration` flag | Opt-in flag for slower live-integration tests if your suite has them. These run the **real** external path (NOT mocked); anything they create externally MUST be cleaned up by the test. |
 | `UJ_TEST_BOOT_PROJECT`      | Auto-set when UJM tests itself; else manual | Project root the boot runner uses (its `_site/` is the boot target) |
 | `UJ_TEST_BOOT_DIR`          | Manual | Absolute override for the `_site/` directory. Wins over `UJ_TEST_BOOT_PROJECT/_site` and `<cwd>/_site` |
 | `UJ_TEST_DEBUG=1`           | Manual | Verbose Puppeteer console output piped to the parent stdout |
@@ -179,5 +224,5 @@ Puppeteer is a `devDependency` of UJM itself. Consumers don't get it unless they
 ## See also
 
 - [test-boot-layer.md](test-boot-layer.md) — deep dive on boot layer (`_site/` discovery, HTTP server, fixture vs consumer)
-- [cross-context-helpers.md](cross-context-helpers.md) — `Manager.isTesting()` / `isDevelopment()` semantics
+- [environment-detection.md](environment-detection.md) — `Manager.isTesting()` / `isDevelopment()` semantics
 - [cli.md](cli.md) — CLI surface, env-var conventions

package/docs/themes.md

@@ -0,0 +1,451 @@
+# Themes
+
+How UJM's theme system works, and how to author a theme — either **inside UJM**
+(shipped to every consumer) or **in a consumer project** (that project only).
+
+A theme controls the **visual language** (colors, type, borders, shadows,
+component styling) and optionally the **markup** of specific pages. It does NOT
+need to re-implement the framework's shared behavior — that is injected for every
+theme automatically (see [Shared vs per-theme](#shared-vs-per-theme)).
+
+Shipped themes live in [src/assets/themes/](../src/assets/themes/):
+
+- **`bootstrap/`** — the base layer: Bootstrap 5 SCSS/JS + universal `overrides/`
+  every theme inherits. Not selected directly.
+- **`classy/`** — the default, full-featured frontend theme. Also the **layout
+  fallback source** (see below).
+- **`neobrutalism/`** — bold high-contrast theme (hard borders, offset shadows,
+  zero radius). A worked example of a second theme.
+- **`_template/`** — a copy-paste starter for new themes (the `_` prefix excludes
+  it from selection).
+
+---
+
+## How a theme is selected and loaded
+
+A consumer picks a theme with one field in `src/_config.yml`:
+
+```yaml
+theme:
+  id: "neobrutalism"     # folder name under assets/themes/
+  appearance: "light"    # light | dark | system  → sets <html data-bs-theme>
+```
+
+Three resolution mechanisms turn that id into a built site:
+
+### 1. SCSS (`__theme__` via loadPaths)
+
+The consumer's `src/assets/css/main.scss` does `@use 'ultimate-jekyll-manager' as *;`.
+That entry point ([src/assets/css/ultimate-jekyll-manager.scss](../src/assets/css/ultimate-jekyll-manager.scss))
+does `@forward 'theme'`. The SASS task resolves the bare `theme` import via
+`loadPaths`, in priority order
+([src/gulp/tasks/sass.js](../src/gulp/tasks/sass.js)):
+
+1. `<project>/src/assets/themes/<id>/` ← **project shadows package**
+2. `<package>/dist/assets/themes/<id>/` ← UJM's built-in theme
+3. `<package>/dist/assets/themes/` ← lets a theme `@import '../bootstrap/...'`
+
+So `_theme.scss` is found in the project's theme dir first, else UJM's. You never
+import a theme by hard path — let loadPaths resolve it.
+
+### 2. JS (`__theme__` webpack alias)
+
+`ultimate-jekyll-manager.js` does `import('__theme__/_theme.js')`. The webpack
+alias ([src/gulp/tasks/webpack.js](../src/gulp/tasks/webpack.js)) resolves
+`__theme__` to the project theme dir if it exists, else UJM's package theme dir —
+same project-shadows-package rule as SCSS.
+
+### 3. Layouts & includes (the classy fallback)
+
+This is the key to **not duplicating ~40 page layouts**. Theme HTML lives under:
+
+- `src/defaults/dist/_layouts/themes/<id>/...`
+- `src/defaults/dist/_includes/themes/<id>/...`
+
+During build, `copyFallbackThemeFiles()`
+([src/gulp/tasks/distribute.js](../src/gulp/tasks/distribute.js)) copies every
+layout/include from the **`classy`** theme that the selected theme hasn't defined,
+rewriting `themes/classy/` → `themes/<id>/` in the content. Layouts also use the
+`themes/[ site.theme.id ]/...` template variable, which distribute resolves to the
+active theme.
+
+**Result:** a new theme inherits all of classy's pages for free and overrides
+**only** the files whose *markup* must differ. You saw this in the build log:
+
+```
+Copied 48 fallback files from 'classy' to 'neobrutalism' theme
+```
+
+> Because classy is the fallback source, **keep classy's layouts theme-agnostic**
+> (semantic Bootstrap classes, data-driven includes). Every other theme inherits
+> them.
+
+#### When to override a layout vs just restyle with CSS
+
+Most of the time you do NOT override layouts — you restyle Bootstrap's classes
+(see [Shared vs per-theme](#shared-vs-per-theme)) and the inherited classy markup
+adopts your look. Override a layout only when the **structure itself** must differ.
+
+The `neobrutalism` theme demonstrates both. It restyles classy's markup everywhere
+EXCEPT the homepage and pricing page, where it ships genuinely different structure
+(asymmetric split hero, offset showcase rows, oversized color-block stats) at
+`_layouts/themes/neobrutalism/frontend/pages/{index,pricing}.html`. **Critically,
+those overrides reuse the SAME `page.resolved.*` frontmatter data contract as
+classy's versions** — same `hero`, `pricing`, `stats`, `cta` keys, same
+price-resolution Liquid — so a consumer's existing page frontmatter keeps working;
+only the HTML that renders the data changes. When you override a page layout, copy
+classy's frontmatter block and preserve any data-resolution Liquid; restructure
+only the markup below the front matter.
+
+#### No theme-prefixed classes — use universal class names
+
+**Markup must never use theme-prefixed classes** (no `nb-*`, `classy-*`, etc.). A
+theme-prefixed class hardcodes the markup to one theme and breaks swappability. When a
+theme writes its own layout, it uses:
+
+1. **Standard Bootstrap classes** wherever one fits — every theme already styles these:
+   - `.card` (+ `.card-body`) — the canonical box for stat/step/plan/feature blocks
+   - `.btn` / `.btn-primary` / `.btn-warning` / `.btn-outline-*` — buttons (theme picks the semantic color; `.btn-warning` = the yellow accent in neobrutalism)
+   - `.text-bg-{primary,secondary,success,info,warning,danger}` — full color-block fills
+   - `.border`, `.shadow`, `.accordion`, `.badge`, grid/flex utilities
+2. **Universal semantic layout classes** for structures with no Bootstrap equivalent —
+   shared *names*, each theme supplies its own *styling*:
+
+   | Class | Represents |
+   |---|---|
+   | `.section-hero` / `.hero-title` / `.hero-actions` | a page hero block |
+   | `.action-block` (`--ink` / `--surface`) | large stacked call-to-action blocks |
+   | `.logo-strip` (`-box`, `-label`) | a "trusted by" logo marquee strip |
+   | `.showcase` / `.showcase-row` (`--flip`) / `.showcase-num` / `.showcase-body` | alternating feature showcase rows |
+   | `.steps` / `.step-card` (`-num`, `-icon`, `-title`, `-desc`) | numbered "how it works" steps |
+   | `.stats` / `.stats-grid` / `.stat-block` (`-num`, `-label`, `-sub`) | stat / social-proof cells |
+   | `.cta` / `.cta-panel` / `.cta-title` / `.cta-desc` / `.cta-actions` | closing CTA panel |
+   | `.pricing-hero` / `.pricing-title` / `.pricing-plans` / `.pricing-plan` (`--popular`) / `.pricing-plan-*` | pricing page structures |
+   | `.billing-toggle` / `.billing-option` / `.billing-save` | monthly/annual billing switch |
+   | `.enterprise-panel` (`-title`) / `.faq` | enterprise strip, FAQ section |
+   | `.section-head` / `.section-title` / `.kicker` (`--invert`) / `.highlight` / `.font-mono` | shared section heading + label/highlight helpers |
+
+   A new theme that overrides these pages styles **the same class names** its own way.
+   This is the contract that keeps custom layouts swappable.
+
+> The `nb-`-style prefix survives ONLY on a theme's SCSS internals — its `$theme-*`
+> config tokens, `--theme-*` CSS variables, and `@mixin` helpers. Those never appear in
+> HTML, so they don't affect swappability. Keep prefixes out of markup, not out of SCSS.
+
+### 4. Page-specific CSS (theme-aware, additive)
+
+Every page links a per-path CSS bundle (`/assets/css/pages/<path>/index.bundle.css`,
+resolved in [_includes/core/head.html](../src/defaults/dist/_includes/core/head.html)).
+That bundle composes UJM's base page CSS (`assets/css/pages/<path>/index.scss`) and
+the consumer's same-path file. Themes add a **third, additive layer**:
+
+- Put theme page CSS at **`themes/<id>/pages/<path>/index.scss`**.
+- The SASS task ([src/gulp/tasks/sass.js](../src/gulp/tasks/sass.js)) compiles it to a
+  separate bundle **`pages/<path>/index.<id>.bundle.css`**.
+- `head.html` links that bundle **in addition to** the base bundle, loaded *after* it
+  (so theme page CSS can override base), gated by `{% iffile %}`.
+
+**The fallback is the absence of a file** — and that's the whole elegance:
+
+- If the theme has **no** page CSS for a path (e.g. signin, which almost no theme
+  customizes), the `<id>` bundle simply doesn't exist, `{% iffile %}` skips the link,
+  and the page is styled entirely by the theme's component/general CSS in the main
+  bundle. **No fallback mechanism needed** — missing = nothing extra loads.
+- If the theme **does** ship page CSS (e.g. neobrutalism's `pages/index.scss` for its
+  custom homepage structure), it loads and layers on top.
+
+This asymmetry vs. HTML layouts is deliberate: a page must always have *some* layout
+(hence the classy copy-fallback), but page CSS is purely additive, so a missing file
+is the correct no-op. Theme page CSS compiles standalone, so it pulls in the theme's
+tokens + mixins via loadPaths (`@use 'config' as *;` + `@import 'css/base/mixins';`).
+
+**Path shape must match the base bundle.** The theme file's path mirrors the base
+page-CSS path for that page — which is NOT always `pages/<path>/index.scss`:
+
+| Page | Base page CSS | Theme page CSS |
+|---|---|---|
+| Homepage (`/`) | `pages/index.scss` (flat) | `pages/index.scss` (flat) |
+| Other (`/pricing`) | `pages/pricing/index.scss` (nested) | `pages/pricing/index.scss` (nested) |
+
+The homepage is the one special case — its bundle is the flat `pages/index.bundle.css`,
+so the theme file is the flat `themes/<id>/pages/index.scss`, NOT `pages/index/index.scss`.
+If the shapes don't match, `{% iffile %}` looks for a bundle that was compiled under a
+different name and silently skips the link. (The same flat-vs-nested rule applies to
+theme page JS below.)
+
+### 5. Page-specific JS (theme-aware, additive — mirrors page CSS)
+
+Page JS works exactly like page CSS — three additive layers, same no-op-on-missing
+rule. The frontend Manager ([src/index.js](../src/index.js)) dynamically imports a
+page module from each layer and runs them **in order**:
+
+1. `#main` — `__main_assets__/js/pages/<path>/index.js` (framework default)
+2. `#theme` — `__theme__/pages/<path>/index.js` (active theme) ← the theme layer
+3. `#project` — `__project_assets__/js/pages/<path>/index.js` (consumer)
+
+- Put theme page JS at **`themes/<id>/pages/<path>/index.js`** (same path shape as the
+  CSS — flat `pages/index.js` for the homepage, nested otherwise).
+- A module exports `default ({ manager, options }) => { ... }`. Missing at any layer is
+  a graceful no-op (logged as `module missing: #<layer>/…`, execution continues).
+- Execution order is **main → theme → project**, matching the CSS cascade: framework
+  default first, theme second, consumer last (consumer always wins).
+- The theme import uses a `/* webpackInclude: /\.js$/ */` magic comment so webpack's
+  dynamic-import context only scans `.js` — the theme's `pages/` dir also holds page
+  CSS (`.scss`), which must NOT be pulled into the JS context.
+
+So a theme can ship a page's structure (layout override), its styling (theme page CSS),
+AND its behavior (theme page JS) — all three keyed off the same `pages/<path>` path,
+all three no-ops when absent.
+
+The three layers, named by **source** (the `#main`/`#theme`/`#project` tags in the
+console logs map to these), always load in this order:
+
+1. **Global** — the framework's own page file (`#main`)
+2. **Theme** — the active theme's page file (`#theme`)
+3. **Consumer** — the consuming project's page file (`#project`)
+
+Later layers win (Consumer overrides Theme overrides Global) — the same cascade for
+both CSS and JS.
+
+### Asset-layer test panel
+
+The built-in **`/test/libraries/layers`** page renders a live status panel for exactly
+this cascade: six dots (CSS ×3, JS ×3), one per layer. Each dot starts **red** and a
+layer turns **its own** dot green when it loads (CSS via a selector, JS by setting the
+dot color). A **red** dot means that layer has no file for this page — the normal state
+for a layer nobody customized. The panel reflects what *actually* loads.
+
+- **Global** and **Theme** dots are populated by files shipped in the framework:
+  `assets/{css,js}/pages/test/libraries/layers/index.*` (global) and the active theme's
+  `pages/test/libraries/layers/index.*` (theme). These are green out of the box.
+- **Consumer** dots require a real consumer file at
+  `src/assets/{css,js}/pages/test/libraries/layers/index.*`. By default a project has
+  none, so they're **red** — the honest "this layer is available but unused" signal.
+
+**Proving the Consumer layer without committing files (`UJ_TEST_LAYERS`).** To light the
+Consumer dots green on demand, run the dev server with the flag — there's a ready-made
+script:
+
+```bash
+npm run start:test-layers      # ≡ UJ_TEST_LAYERS=true npm start
+```
+
+When set, the `defaults` task ([utils/manage-test-layers.js](../src/gulp/tasks/utils/manage-test-layers.js))
+generates a real consumer page file into the project's `src/` **at build start** (before
+sass + jekyll), so it loads through the genuine `__project_assets__` / consumer-page-CSS
+path — no shims. The generated CSS `@use`s the framework base so it *composes* (the same
+contract every real consumer page file follows). The files carry a `GENERATED — UJ_TEST_LAYERS`
+marker and are **auto-removed at the start of the next run** (and never on a normal run),
+so they never persist or get committed. (`.temp`/`dist` are also cleaned by `npx mgr clean`.)
+
+> **Build-order note (dev only).** Theme page bundles are produced by the SASS task,
+> then Jekyll's `{% iffile %}` checks for them in its source tree (`dist/`). On the
+> *very first* dev render, Jekyll may render a page before its theme bundle has been
+> written, so the link is missing until that page is re-rendered (touch the page source
+> or save it again). A production `npm run build` runs sass before jekyll, so there's no
+> race. If a theme page's CSS/JS isn't applying in dev, re-trigger that page's render.
+
+> Editing `sass.js` / `index.js` (or any gulp/build task)? The consumer's running
+> `gulp serve` loaded the task at startup — **fully restart the consumer's `npm start`**
+> for task-code changes to take effect (webpack picks up `src/index.js` on its own watch,
+> but gulp task definitions like the sass globs only reload on a fresh process).
+> Layout/SCSS/`head.html` *content* changes are picked up live.
+
+---
+
+## Shared vs per-theme
+
+Get this distinction right or you'll either duplicate plumbing or fight overrides.
+
+### Shared — do NOT re-implement in a theme
+
+| Layer | Where | What |
+|---|---|---|
+| Core behavior CSS | [src/assets/css/core/](../src/assets/css/core/) | animations, alerts, lazy-loading shimmer, cookie consent, bindings skeletons, social sharing. Injected for **every** theme by `ultimate-jekyll-manager.scss`. |
+| Bootstrap extensions | [src/assets/themes/bootstrap/overrides/](../src/assets/themes/bootstrap/overrides/) | avatars, color-shades, soft-colors, adaptive buttons, spacing, link/typography utilities. Each theme pulls these in via `@import '../bootstrap/overrides'` at the end of its `_theme.scss`. |
+| Page layouts/includes | classy theme + fallback copy | the ~40 frontend/backend/admin layouts and nav/footer/account includes. |
+| Bootstrap class contract | `bootstrap/scss` | the markup + class names (`.btn`, `.card`, `.navbar`, `.form-control`). Themes **restyle** these classes; they don't invent new markup. |
+
+### Per-theme — this IS the theme's job (and SHOULD differ between themes)
+
+- `_config.scss` — design tokens (`!default`), Bootstrap forward.
+- `_root.scss` — SCSS → CSS-variable bridge for light/dark.
+- Component SCSS — how `.btn`/`.card`/`.form-control`/`.navbar` actually look.
+- `_theme.js` — expose Bootstrap + run theme behaviors on DOM ready.
+- *(optional)* Page-layout overrides under `_layouts/themes/<id>/...` — for pages
+  whose structure must differ (reuse classy's frontmatter data contract).
+- *(optional)* Theme page CSS at `pages/<path>/index.scss` — additive per-page
+  styles for those overridden layouts.
+- *(optional)* Theme page JS at `pages/<path>/index.js` — additive per-page behavior
+  (the `#theme` layer between `#main` and `#project`).
+
+A neobrutalist button and a classy button share only the `.btn` class — restyling
+it is the theme's whole purpose. **Do not try to "share" component styling between
+themes**; that produces an override-fighting mess. Share *plumbing*, not *looks*.
+
+> Themes share the **class-name contract** (standard Bootstrap classes + the universal
+> semantic layout classes — see [No theme-prefixed classes](#no-theme-prefixed-classes--use-universal-class-names)),
+> not the styling. Same names, different looks → markup stays swappable.
+
+### Structural vs visual components (gotcha)
+
+A few "components" in classy are **structural behavior**, not just styling — e.g.
+`_infinite-scroll.scss` (the trusted-by logo marquee + testimonial scroll). The
+shared layouts emit `.infinite-scroll-track` markup, so any theme using those
+layouts needs the matching CSS or the content renders broken (giant unstyled
+logos). Until these are promoted to the shared layer, **port structural components
+you actually use** into your theme (neobrutalism ships its own
+`css/components/_infinite-scroll.scss` — mostly the same flex/marquee rules with
+theme-tuned cosmetics). If a page using shared markup looks broken, check whether
+a structural component is missing.
+
+### Adaptive buttons need an explicit theme override (gotcha)
+
+The shared `bootstrap/overrides/_buttons-adaptive.scss` defines `.btn-adaptive` /
+`.btn-adaptive-inverse` (mode-flipping solids used by the nav CTA, auth buttons,
+redirect, etc.) **only at single-class specificity** (`.btn-adaptive`, `0,1,0`) and
+via the `--bs-btn-*` custom properties. A theme that restyles `.btn` will hit two
+problems with these classes if it ignores them:
+
+1. **Transparent resting fill.** Bootstrap's base `.btn { --bs-btn-bg: transparent }`
+   can tie/beat the `.btn-adaptive` rule on source order, so the button renders
+   *transparent* instead of solid. Fix: restate the resting fill at **doubled
+   specificity** (`.btn.btn-adaptive`, `0,2,0`) in the theme's `_buttons.scss`, with a
+   `[data-bs-theme="dark"]` pair for the mode flip.
+2. **Hover color flash.** The adaptive defaults darken on hover (`--bs-btn-hover-bg:
+   var(--bs-dark-hover)`), so an adaptive button animates differently from the theme's
+   other solids. Fix: add `.btn-adaptive` / `.btn-adaptive-inverse` to the same
+   hover/active **freeze** list the theme uses for `.btn-primary` etc.
+   (`--bs-btn-hover-bg: var(--bs-btn-bg)`), so the press is pure transform+shadow.
+
+See `themes/neobrutalism/css/components/_buttons.scss` for the reference treatment.
+The `[class*="btn-outline-"]` selector already catches the *outline* adaptive
+variants, so only the two **solid** adaptive classes need this.
+
+### One token for interactive hovers — and `$primary` ≠ `--bs-primary` (gotcha)
+
+Give every interactive hover/active fill (nav links, footer links, dropdown items,
+in-content links, mobile toggler) a **single** token so they retune from one line and
+never drift. Neobrutalism defines `--nb-accent-interactive` (blue) in `_root.scss`,
+distinct from the yellow signature accent (`--nb-accent-yellow`) reserved for static
+blocks (kicker tags, highlight marker, hero, badges). Every interactive `:hover`/
+`.active` reads `var(--nb-accent-interactive)`; nothing hardcodes the color.
+
+**The trap:** point that token at the runtime **`var(--bs-primary)`**, NOT the SCSS
+`$primary` token. A consumer can set them to *different* values (UJM consumers
+frequently do — the SCSS `$primary` and the rendered `--bs-primary` diverged, so a
+rule written as `background: $primary` compiled a purple that didn't match the blue
+`.btn-primary` buttons on the page). Any rule that should match a rendered Bootstrap
+color must use the **CSS variable** (`var(--bs-primary)`), because SCSS values are
+frozen at compile time while the `--bs-*` vars reflect the live theme.
+
+One more: a generic `a:hover { color: … }` also paints **button** labels (buttons are
+`<a>`). Guard it with `a.btn:hover { color: var(--bs-btn-color); }` so buttons keep
+their own (frozen) text color. Nav/dropdown/footer links already win on specificity.
+
+---
+
+## Authoring conventions (both paths)
+
+1. **Every token is `!default`** so consumers can override without forking.
+2. **Bridge to CSS variables** in `_root.scss`; components read `var(--*)`, not raw
+   SCSS. Dark mode then becomes one `[data-bs-theme="dark"]` override block.
+3. **Restyle Bootstrap's own classes** so inherited markup adopts your look with no
+   HTML edits. Add your own classes only for net-new patterns.
+4. **Namespace your own classes** (`.nb-*`, `.recipe-*`) to avoid collisions.
+5. **Match classy's `$avatar-sizes` map** in `_config.scss` — the shared includes
+   (nav/account) reference it.
+6. **Fonts** load via the base layout's `theme.head.content`, NOT a CSS `@import`
+   (avoids render-blocking duplicate loads). To use custom fonts, override
+   `frontend/core/base.html` (see below).
+7. **Validate live, then document.** UJM can't run a dev server — build in a
+   consumer and screenshot (see [Validating](#validating-a-theme)).
+
+---
+
+## Path A — author a theme INSIDE UJM (shipped to all consumers)
+
+Use this for first-party themes like `neobrutalism`.
+
+1. **Copy the template** to your theme id:
+   ```
+   src/assets/themes/_template/  →  src/assets/themes/my-theme/
+   ```
+2. **Edit the SCSS:**
+   - `_config.scss` — your tokens + the `@forward '../bootstrap/scss/bootstrap.scss' with (...)` block.
+   - `_root.scss` — CSS-variable bridge (light + dark).
+   - add `css/base/`, `css/layout/`, `css/components/` partials and `@import` them
+     in `_theme.scss`. End `_theme.scss` with `@import '../bootstrap/overrides';`.
+   - If you use shared mixins across partials, `@import` a `_mixins.scss` first so
+     they're in the global scope the other `@import`s share (neobrutalism does this).
+3. **Edit `_theme.js`** — `import bootstrap from '__main_assets__/themes/bootstrap/js/index.umd.js'`,
+   `window.bootstrap = bootstrap`, run behaviors inside `domReady()`. Keep multiple
+   behaviors in small `js/` files.
+4. **Override only the HTML that must differ** under
+   `src/defaults/dist/_layouts/themes/my-theme/...` (and `_includes/...`). The
+   classy fallback supplies the rest. The most common override is
+   `frontend/core/base.html` to load your fonts (neobrutalism overrides just this
+   one file).
+5. **Add a `README.md`** in the theme folder (customization quickstart).
+6. `npm run prepare` (copies `src/`→`dist/`) so consumers see it. Then test in a
+   consumer (Path: [Validating](#validating-a-theme)).
+
+## Path B — author a theme IN A CONSUMER PROJECT (that project only)
+
+Use this when one site needs a bespoke look that shouldn't ship in UJM (e.g. Sweet
+Saucy's `recipe` theme).
+
+1. **Copy the template** from UJM into your project:
+   ```
+   node_modules/ultimate-jekyll-manager/dist/assets/themes/_template/
+     →  <project>/src/assets/themes/my-theme/
+   ```
+2. **Select it** in `src/_config.yml`: `theme: { id: "my-theme" }`.
+3. **Edit the SCSS/JS** exactly as Path A. The `../bootstrap/...` imports still
+   resolve — UJM's loadPaths include the package themes root.
+4. **Override HTML** (only if needed) under
+   `<project>/src/_layouts/themes/my-theme/...` and `src/_includes/themes/my-theme/...`.
+   The fallback still copies classy's defaults into your theme id at build time.
+5. **PurgeCSS safelist:** if you add custom classes used only in JS-injected DOM,
+   add them to `config/ultimate-jekyll-manager.json` → `sass.purgecss.safelist` so
+   production builds don't strip them.
+6. **`npm start`** and verify.
+
+> To merely *recolor* an existing theme (not build a new one), don't create a
+> theme — override its `!default` tokens in `main.scss` before
+> `@use 'ultimate-jekyll-manager'`. See classy's README. To change a theme's
+> component styles or a layout, **shadow it**: create
+> `src/assets/themes/<id>/` (SCSS) or `src/_layouts/themes/<id>/<file>` (HTML) in
+> your project — loadPaths/fallback resolve your copy first.
+
+---
+
+## Validating a theme
+
+UJM cannot run a dev server itself (it runs inside a consumer). To verify a theme:
+
+1. In UJM: `npm run prepare` (or `npm start` for watch) to publish `src/`→`dist/`.
+2. In a consumer wired to local UJM (`"ultimate-jekyll-manager": "file:../ultimate-jekyll-manager"`),
+   set `theme.id` and run `npm start`. Capture the BrowserSync URL (e.g.
+   `https://localhost:4000`).
+3. Screenshot the key pages (home, pricing, signin, signup) in **both** light and
+   dark (`document.documentElement.setAttribute('data-bs-theme','dark')`) — e.g.
+   via the chrome-devtools MCP. Check the console for errors and that your theme's
+   "loaded" log appears.
+4. Iterate on SCSS — the consumer's gulp watcher recompiles when UJM's `dist/`
+   changes (if UJM is running `npm start`), or re-run `npm run prepare`.
+
+**Do not declare a theme done without looking at rendered screenshots.** Verified
+example: `neobrutalism` built into `ultimate-jekyll-website`, screenshotted across
+all four pages in light + dark.
+
+---
+
+## Reference
+
+- Theme tokens example: [src/assets/themes/neobrutalism/_config.scss](../src/assets/themes/neobrutalism/_config.scss)
+- CSS-variable bridge example: [src/assets/themes/neobrutalism/css/base/_root.scss](../src/assets/themes/neobrutalism/css/base/_root.scss)
+- Starter: [src/assets/themes/_template/](../src/assets/themes/_template/)
+- Fallback mechanism: [src/gulp/tasks/distribute.js](../src/gulp/tasks/distribute.js) (`copyFallbackThemeFiles`)
+- Resolution: [src/gulp/tasks/sass.js](../src/gulp/tasks/sass.js), [src/gulp/tasks/webpack.js](../src/gulp/tasks/webpack.js)
+- Related: [docs/assets.md](assets.md) (file layout), [docs/css.md](css.md) (section/theme-adaptive classes), [docs/appearance.md](appearance.md) (dark/light switching)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultimate-jekyll-manager",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "description": "Ultimate Jekyll dependency manager",
   "main": "dist/index.js",
   "exports": {
@@ -31,6 +31,7 @@
   },
   "projectScripts": {
     "start": "npx mgr clean && npx mgr setup && bundle exec npm run gulp --",
+    "start:test-layers": "UJ_TEST_LAYERS=true npm start",
     "gulp": "gulp --cwd ./ --gulpfile ./node_modules/ultimate-jekyll-manager/dist/gulp/main.js",
     "build": "npx mgr clean && npx mgr setup && UJ_BUILD_MODE=true bundle exec npm run gulp -- build",
     "deploy": "npx mgr deploy",

package/docs/cross-context-helpers.md

@@ -1,75 +0,0 @@
-# Cross-context Helpers
-
-`src/utils/mode-helpers.js` exposes four shared helpers mixed into every UJM Manager via `attachTo(Manager)`. Mirrors the same pattern in EM and BXM. Used when behavior should differ by *what kind of process* you're in — short-circuit network probes in tests, suppress dev-only banners in production, etc.
-
-## API
-
-| Method | Returns | Purpose |
-|---|---|---|
-| `Manager.isTesting()` | `boolean` | True when UJM's test framework is running this process. Set by `npx mgr test` (`UJ_TEST_MODE=true`) and consumer test setups that want the same signal. |
-| `Manager.isDevelopment()` | `boolean` | True when running in dev mode (not a production build). Reads `UJ_BUILD_MODE` / `NODE_ENV` / `UJ_IS_SERVER` / `window.Configuration.uj.environment` depending on context. |
-| `Manager.isProduction()` | `boolean` | Inverse of `isDevelopment()`. |
-| `Manager.getVersion()` | `string \| null` | UJM's version from `<cwd>/package.json#version`. Null if no `package.json` (e.g. shipped browser bundle). |
-
-All four are available both **statically** on the Manager constructor and on **`Manager.prototype`**, so these all work:
-
-```js
-const Manager = require('ultimate-jekyll-manager/build');
-Manager.isTesting();                  // static
-new Manager().isTesting();            // instance
-```
-
-## When to use
-
-```js
-// In a build helper that fetches Firebase auth files:
-async function fetchFirebaseAuthFiles() {
-  if (Manager.isTesting()) {
-    return;  // short-circuit — tests provide their own stubs
-  }
-  // ...real fetch
-}
-
-// In a gulp task that opens the dev browser:
-function maybeOpenBrowser() {
-  if (Manager.isBuildMode() || Manager.isTesting()) return;
-  // ...exec `open` etc.
-}
-
-// In a frontend module that logs verbose debug info:
-if (manager.isDevelopment()) {
-  console.log('[dev] webManager loaded with', cfg);
-}
-```
-
-**Don't use these for "should I hit dev or prod backends"** — that's a config concern. Use `Manager.getEnvironment()` (returns `'development'` or `'production'` strings) for that distinction.
-
-## How `isDevelopment` is detected
-
-Order of checks:
-
-1. **Build-time Node**: `process.env.UJ_BUILD_MODE === 'true'` → production. `process.env.NODE_ENV === 'development'` → development. `process.env.UJ_IS_SERVER === 'true'` → production.
-2. **Browser**: `window.Configuration.uj.environment` if present (`'development'` or `'production'`).
-3. Default → `false`.
-
-## How `isTesting` is detected
-
-Two checks (either is sufficient):
-
-1. **Node**: `process.env.UJ_TEST_MODE === 'true'`. Set automatically by `npx mgr test`.
-2. **Browser**: `globalThis.UJ_TEST_MODE === true`. Set automatically by UJM's `page`-layer harness HTML before any consumer code runs.
-
-This means consumer code that calls `Manager.isTesting()` from a tab context gets the right answer — Node-only check would always return false in a browser.
-
-## Adding new helpers
-
-If you find yourself writing the same `if (process.env.UJ_FOO === 'true') ...` check more than twice, factor it into `mode-helpers.js`. Things to consider:
-
-- Does the helper need to work in **all** contexts (Node build-time + browser page + service worker)? If yes, gate every check with `typeof process !== 'undefined'` / `typeof window !== 'undefined'` so the same code runs everywhere.
-- Should it be mixed into static AND prototype? Almost always yes — the static form is for build-time CLI usage, the instance form for runtime use.
-- Add a test in `src/test/suites/build/mode-helpers.test.js` that toggles the underlying env var and asserts both states.
-
-## See also
-
-- [test-framework.md](test-framework.md) — the test harness that sets `UJ_TEST_MODE`
-- [cli.md](cli.md) — full env-var matrix