ultimate-jekyll-manager 1.7.2 → 1.8.0

package/dist/test/suites/build/theme-contract.test.js

@@ -0,0 +1,173 @@
+// Theme contract — structural invariants every shipped theme must satisfy
+// (docs/themes.md conventions turned into executable assertions). Globs the
+// theme directories, so a new theme is covered the moment it lands:
+//   1. Entry files exist ($avatar-sizes map, shared bootstrap overrides import)
+//   2. Layouts are swappable (parent refs use [ site.theme.id ] brackets,
+//      no theme-prefixed classes in markup, no inline <script> bodies)
+//   3. Cross-theme JS contracts hold (pricing data attributes, blog-post-content)
+//   4. Page asset files use a shape the layouts' asset_path frontmatter declares
+//      (wrong shape = silent bundle skip)
+
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const glob = require('glob').globSync;
+
+const ROOT = path.join(__dirname, '../../../..');
+const ASSETS = path.join(ROOT, 'src/assets/themes');
+const LAYOUTS = path.join(ROOT, 'src/defaults/dist/_layouts/themes');
+const INCLUDES = path.join(ROOT, 'src/defaults/dist/_includes/themes');
+
+// _template is held to the asset contract too — it's what theme authors copy.
+// bootstrap is the shared Bootstrap source, not a theme.
+const themes = jetpack.list(ASSETS).filter((t) => t !== 'bootstrap');
+
+// Class tokens that would couple markup to one theme (markup must stay
+// swappable; theme prefixes live only in SCSS internals)
+const THEME_PREFIXES = ['nf-', 'nb-', 'classy-', 'newsflash-', 'neobrutalism-', 'broadsheet-', 'template-'];
+
+// Markers the framework pricing JS reads — identical across themes by contract
+// (see docs/themes.md "Pricing page JS contract")
+const PRICING_MARKERS = ['data-plan-id', 'billing-info', 'price-per-unit', 'pricing-promo-banner', 'card-title', 'data-monthly'];
+
+// All markup files (layouts + includes) for a theme
+function markupFiles(theme) {
+  return [
+    ...glob(`${LAYOUTS}/${theme}/**/*.html`),
+    ...glob(`${INCLUDES}/${theme}/**/*.html`),
+  ];
+}
+
+// Inline <script> bodies are banned in theme markup (ld+json and src loaders OK)
+function findInlineScript(html) {
+  const scripts = html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/g);
+
+  for (const [, attrs, body] of scripts) {
+    if (attrs.includes('src=')) {
+      continue;
+    }
+    if (attrs.includes('application/ld+json')) {
+      continue;
+    }
+    if (body.trim() === '') {
+      continue;
+    }
+
+    return body.trim().slice(0, 80);
+  }
+
+  return null;
+}
+
+// Flat page-asset names declared by ANY theme layout's asset_path frontmatter
+// (the fallback means classy's declarations apply to every theme)
+function declaredAssetPaths() {
+  const paths = new Set();
+
+  for (const file of glob(`${LAYOUTS}/*/**/*.html`)) {
+    const match = jetpack.read(file).match(/^asset_path:\s*(\S+)/m);
+    if (match) {
+      paths.add(match[1].replace(/['"]/g, ''));
+    }
+  }
+
+  return paths;
+}
+
+module.exports = {
+  layer: 'build',
+  description: 'theme contract (structure, swappability, cross-theme JS contracts)',
+  type: 'group',
+  tests: [
+    ...themes.map((theme) => ({
+      name: `${theme}: entry files + config contract`,
+      run: (ctx) => {
+        const config = jetpack.read(`${ASSETS}/${theme}/_config.scss`);
+        const entry = jetpack.read(`${ASSETS}/${theme}/_theme.scss`);
+
+        ctx.expect(config).toBeTruthy();
+        ctx.expect(entry).toBeTruthy();
+        ctx.expect(jetpack.exists(`${ASSETS}/${theme}/_theme.js`)).toBeTruthy();
+
+        // Shared nav/account includes depend on the avatar size map
+        ctx.expect(config).toContain('$avatar-sizes');
+
+        // Universal Bootstrap overrides must close the cascade
+        ctx.expect(entry).toContain("@import '../bootstrap/overrides'");
+      },
+    })),
+
+    ...themes.map((theme) => ({
+      name: `${theme}: layouts swappable, markup clean`,
+      run: (ctx) => {
+        for (const file of markupFiles(theme)) {
+          const html = jetpack.read(file);
+          const rel = path.relative(ROOT, file);
+
+          // Parent layout refs resolve via bracket templating, never a
+          // hardcoded theme id (swappability: change theme.id, done)
+          const parent = html.match(/^layout:\s*themes\/(.+)$/m);
+          if (parent) {
+            ctx.expect(`${rel}: ${parent[1]}`).toMatch(/\[\s*site\.theme\.id\s*\]/);
+          }
+
+          // No theme-prefixed classes in markup
+          for (const [, classes] of html.matchAll(/class="([^"]*)"/g)) {
+            for (const token of classes.split(/\s+/)) {
+              const prefixed = THEME_PREFIXES.some((p) => token.startsWith(p));
+              ctx.expect(prefixed ? `${rel}: class "${token}"` : '').toBeFalsy();
+            }
+          }
+
+          // No inline script bodies
+          const inline = findInlineScript(html);
+          ctx.expect(inline ? `${rel}: inline <script> "${inline}"` : null).toBeFalsy();
+        }
+      },
+    })),
+
+    ...themes.map((theme) => ({
+      name: `${theme}: cross-theme JS contracts`,
+      run: (ctx) => {
+        // A theme that ships its own pricing/post layouts must keep the
+        // markers the framework JS targets; absent layouts inherit classy's,
+        // so the contract holds by definition.
+        const pricing = jetpack.read(`${LAYOUTS}/${theme}/frontend/pages/pricing.html`);
+        if (pricing) {
+          for (const marker of PRICING_MARKERS) {
+            ctx.expect(pricing).toContain(marker);
+          }
+        }
+
+        const post = jetpack.read(`${LAYOUTS}/${theme}/frontend/pages/blog/post.html`);
+        if (post) {
+          // Load-bearing for ad injection
+          ctx.expect(post).toContain('blog-post-content');
+        }
+      },
+    })),
+
+    {
+      name: 'page asset files match a declared asset_path shape',
+      run: (ctx) => {
+        const declared = declaredAssetPaths();
+
+        // Sanity: the derivation itself found the known flat shapes
+        ctx.expect(declared.has('blog/post')).toBeTruthy();
+
+        for (const theme of themes) {
+          for (const file of glob(`${ASSETS}/${theme}/pages/**/*.{scss,js}`)) {
+            const rel = path.relative(`${ASSETS}/${theme}/pages`, file);
+            const base = rel.replace(/\.(scss|js)$/, '');
+
+            // index.* shapes resolve by page path; flat shapes must be
+            // declared by some layout's asset_path or the bundle never loads
+            if (path.basename(base) === 'index') {
+              continue;
+            }
+            ctx.expect(declared.has(base) ? '' : `${theme}/pages/${rel}: no layout declares asset_path "${base}"`).toBeFalsy();
+          }
+        }
+      },
+    },
+  ],
+};

package/dist/test/utils/extended-mode-warning.js

@@ -0,0 +1,13 @@
+// TEST_EXTENDED_MODE warning — SSOT for consistent messaging.
+//
+// Mirrors BEM/BXM/EM: `TEST_EXTENDED_MODE` is the shared, unprefixed env var that opts a
+// test run into hitting REAL external services instead of skipping/stubbing them. Off by
+// default so `npx mgr test` stays fast and offline-safe. Used by the test command (printed to
+// console + teed to logs/test.log).
+const EXTENDED_MODE_WARNING = [
+  '⚠️⚠️⚠️  WARNING: TEST_EXTENDED_MODE IS TRUE  ⚠️⚠️⚠️',
+  'Tests that hit real external services (network fetches, Firebase via web-manager, live APIs) are ENABLED!',
+  'This will make real network calls against live backends.',
+];
+
+module.exports = { EXTENDED_MODE_WARNING };

package/dist/utils/attach-log-file.js

@@ -12,75 +12,102 @@
 // Truncates fresh on each call (O_TRUNC), so a new `npm start` doesn't accumulate stale
 // lines from the previous run.
 //
-// Idempotent: calling twice with the same path just returns the existing fd.
+// Idempotent: calling twice with the same name on one tee just returns the existing fd.
 //
 // Uses synchronous fs.writeSync(fd, ...) rather than createWriteStream(). Reason: gulp tasks
 // crash via thrown errors that propagate to process.exit, and createWriteStream's internal
 // buffer was being dropped before the kernel could flush it — so the very lines describing
 // the crash (the most important ones) never made it to disk. Synchronous writes incur a
-// per-line syscall but guarantee the tail of the log survives an immediate exit.
+// per-line syscall but guarantee the tail of the log survives an immediate exit. (This is the
+// key behavioral difference from EM, whose tee is async/stream-based with an awaited detach.)
+//
+// The default export is a process-wide SINGLETON (the common case: a CLI command tees its
+// whole run to one file). `attachLogFile.createTee()` returns an INDEPENDENT tee with its own
+// state. Tees STACK: a later attach() captures the CURRENT `process.stdout.write` (which may
+// already be an outer tee) as its "original", so writes fan out through every layer and
+// detach() restores the exact prior writer in LIFO order. That stacking is what lets the
+// attach-log-file unit test exercise attach/detach on a throwaway instance WITHOUT killing
+// the live singleton tee that's capturing the actual test run — the bug that previously
+// truncated `logs/test.log` to ~9 lines (the test detached the live tee mid-run).
 
 const fs = require('fs');
 const path = require('path');
 
 const ANSI_PATTERN = /\x1B\[[0-9;]*[a-zA-Z]/g;
 
-let activeFd       = null;
-let activePath     = null;
-let originalStdoutWrite = null;
-let originalStderrWrite = null;
+function stripAnsi(s) {
+  return String(s).replace(ANSI_PATTERN, '');
+}
 
-function attachLogFile(name) {
-  // Skip on CI/cloud — controlled by UJ_IS_SERVER env var (set by workflows).
-  const Manager = require('../build.js');
-  if (Manager.isServer()) return null;
+// Factory — each call returns an independent tee with its own closure state.
+function createTee() {
+  let activeFd            = null;
+  let activePath          = null;
+  let originalStdoutWrite = null;
+  let originalStderrWrite = null;
 
-  if (!name) return null;
+  function attach(name) {
+    // Skip on CI/cloud — controlled by UJ_IS_SERVER env var (set by workflows).
+    const Manager = require('../build.js');
+    if (Manager.isServer()) return null;
 
-  const abs = path.resolve(process.cwd(), 'logs', `${name}.log`);
+    if (!name) return null;
 
-  if (activeFd !== null && activePath === abs) return activeFd;
-  if (activeFd !== null) detach();
+    const abs = path.resolve(process.cwd(), 'logs', `${name}.log`);
 
-  fs.mkdirSync(path.dirname(abs), { recursive: true });
-  const fd = fs.openSync(abs, 'w');
+    if (activeFd !== null && activePath === abs) return activeFd;
+    if (activeFd !== null) detach();
 
-  fs.writeSync(fd, `# ujm log — ${new Date().toISOString()} — pid=${process.pid}\n`);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const fd = fs.openSync(abs, 'w');
 
-  originalStdoutWrite = process.stdout.write.bind(process.stdout);
-  originalStderrWrite = process.stderr.write.bind(process.stderr);
+    fs.writeSync(fd, `# ujm log — ${new Date().toISOString()} — pid=${process.pid}\n`);
 
-  process.stdout.write = function (chunk, ...rest) {
-    try { fs.writeSync(fd, stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
-    return originalStdoutWrite(chunk, ...rest);
-  };
-  process.stderr.write = function (chunk, ...rest) {
-    try { fs.writeSync(fd, stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
-    return originalStderrWrite(chunk, ...rest);
-  };
+    // Capture whatever the CURRENT writer is — could be the raw stream OR an outer tee.
+    // Restoring this exact reference on detach() is what makes stacked tees safe.
+    originalStdoutWrite = process.stdout.write.bind(process.stdout);
+    originalStderrWrite = process.stderr.write.bind(process.stderr);
 
-  activeFd   = fd;
-  activePath = abs;
+    process.stdout.write = function (chunk, ...rest) {
+      try { fs.writeSync(fd, stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
+      return originalStdoutWrite(chunk, ...rest);
+    };
+    process.stderr.write = function (chunk, ...rest) {
+      try { fs.writeSync(fd, stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
+      return originalStderrWrite(chunk, ...rest);
+    };
 
-  return fd;
-}
+    activeFd   = fd;
+    activePath = abs;
 
-function detach() {
-  if (originalStdoutWrite) process.stdout.write = originalStdoutWrite;
-  if (originalStderrWrite) process.stderr.write = originalStderrWrite;
-  if (activeFd !== null) {
-    try { fs.closeSync(activeFd); } catch (e) { /* ignore */ }
+    return fd;
   }
-  activeFd   = null;
-  activePath = null;
-  originalStdoutWrite = null;
-  originalStderrWrite = null;
+
+  // Restores stdout/stderr and closes the fd. Synchronous — UJM writes synchronously, so the
+  // tail is already on disk by the time detach() runs; this just cleans up the handle.
+  function detach() {
+    if (originalStdoutWrite) process.stdout.write = originalStdoutWrite;
+    if (originalStderrWrite) process.stderr.write = originalStderrWrite;
+    if (activeFd !== null) {
+      try { fs.closeSync(activeFd); } catch (e) { /* ignore */ }
+    }
+    activeFd   = null;
+    activePath = null;
+    originalStdoutWrite = null;
+    originalStderrWrite = null;
+  }
+
+  return { attach, detach };
 }
 
-function stripAnsi(s) {
-  return String(s).replace(ANSI_PATTERN, '');
+// Process-wide singleton — the production entry point.
+const singleton = createTee();
+
+function attachLogFile(name) {
+  return singleton.attach(name);
 }
 
 module.exports = attachLogFile;
-module.exports.detach    = detach;
+module.exports.detach    = singleton.detach;
 module.exports.stripAnsi = stripAnsi;
+module.exports.createTee = createTee;

package/docs/appearance.md

@@ -63,3 +63,4 @@ webManager.uj().appearance.clear();      // Clear saved preference
 - **Module:** `src/assets/js/core/appearance.js` — API and UI handling
 - **Storage:** Saved under `_manager.appearance.preference` in localStorage
 - **Test page:** `/test/libraries/appearance`
+- **Footer picker:** every theme footer ships the appearance dropdown next to the language dropdown (classy's footer provides it to fallback themes automatically; themes with custom footers include it themselves — see [docs/themes.md](themes.md#the-appearance-picker-is-required-in-every-footer)). The footer toggle button is **icon-only** — `data-appearance-icon` spans, no `data-appearance-current` text label (the mode words live in the menu items)

package/docs/assets.md

@@ -151,6 +151,15 @@ This is the single source of truth for account dropdown menu items. Consuming pr
 
 This renders the full account dropdown: avatar button with profile photo, user info header (displayName + email), and the menu items from `account.json`.
 
+Each dropdown item supports:
+
+- `label` — Display text
+- `href` — Link URL (omit for button behavior, e.g. Sign Out)
+- `icon` — Font Awesome icon name
+- `class` — Additional CSS classes
+- `divider: true` — Renders a divider line
+- `attributes` — Array of `[name, value]` pairs (e.g. `data-wm-bind` for visibility)
+
 **Parameters:**
 
 | Parameter | Default | Description |

package/docs/audit.md

@@ -1,11 +1,31 @@
 # Audit Workflow
 
-When fixing issues identified by the audit task (`src/gulp/tasks/audit.js`):
+Auditing a UJM site runs in two stages: an AI-powered content pass over the source files, then the automated `npx mgr audit` tool with a systematic fix loop.
 
-1. Review the audit file location provided
-2. Create a TODO list for each audit category
-3. Read the ENTIRE audit file and plan fixes for each category
-4. Tackle issues incrementally — DO NOT attempt to fix everything at once
-5. Work through one category at a time
+## Stage 1: Content Audit (source files)
 
-**Remember:** Audit files are large. Systematic, incremental fixes prevent errors and ensure thoroughness.
+1. **Locate all page source files** — `src/pages/**` and `src/_posts/**` (`.html` + `.md`).
+2. **Enforce content conventions** — headings start with action verbs, sentence case, headline/accent structure (see [seo.md](seo.md#content-writing-rules-applies-to-all-pages)). Skip front matter (`meta.title` etc. are controlled by blueprints/layouts), test pages, and blog posts.
+3. **Fix spelling and grammar** in body text — skip code blocks, attributes, URLs.
+4. **XSS / HTML escaping audit** — flag unsafe `innerHTML` assignments; fix with `webManager.utilities().escapeHTML()` (+ `sanitizeURL` for URL sinks). See [xss-prevention.md](xss-prevention.md).
+5. **Inline `<script>` audit (HARD RULE)** — scan all HTML under `src/` for inline script bodies and move them per the playbook in [no-inline-scripts.md](no-inline-scripts.md).
+6. **Summarize** — list files scanned and fixes applied before moving to stage 2.
+
+## Stage 2: Automated Audit (`npx mgr audit`)
+
+1. **Ask the user** whether to run the audit or whether they've already run it; run `npx mgr audit` if needed.
+2. **Locate results** in `.temp/audit/` and read every file COMPLETELY — audit files are large; don't plan from a skim.
+3. **Create a TODO list** — break fixes into atomic tasks, organized by category and priority.
+4. **Fix systematically** — one issue at a time: mark in-progress → navigate → understand root cause → fix → verify → mark complete. Work one category at a time; do NOT attempt to fix everything at once.
+5. **Re-run `npx mgr audit`** after each batch — confirm fixed issues are resolved and no new issues appeared.
+
+## Source
+
+- Audit task implementation: [`src/gulp/tasks/audit.js`](../src/gulp/tasks/audit.js)
+- Results land in `<projectRoot>/.temp/audit/`
+
+## See also
+
+- [seo.md](seo.md) — the content conventions stage 1 enforces
+- [xss-prevention.md](xss-prevention.md) — escaping rules
+- [no-inline-scripts.md](no-inline-scripts.md) — the inline-script migration playbook

package/docs/build-system.md

@@ -0,0 +1,57 @@
+# Build System
+
+UJM's build is a multi-stage gulp pipeline orchestrated by `src/gulp/main.js`, run from the consumer project (`npm start` for dev, `npm run build` for production).
+
+## Pipeline overview
+
+Build sequence:
+
+```
+defaults → distribute → parallel(webpack, sass, imagemin) → jsonToHtml → jekyll → audit → translation → minifyHtml
+```
+
+Dev sequence:
+
+```
+serve → build → developmentRebuild
+```
+
+## Gulp tasks
+
+15 tasks live in `src/gulp/tasks/`: `defaults` / `distribute` / `webpack` / `sass` / `imagemin` / `jekyll` / `jsonToHtml` / `preprocess` / `audit` / `translation` / `minifyHtml` / `serve` / `setup` / `developmentRebuild`.
+
+Pure helpers are exposed under [src/gulp/tasks/utils/](../src/gulp/tasks/utils/) (`merge-jekyll-configs`, `_validate-yaml`, `template-transform`, `collectTextNodes`, `dictionary`, `github-cache`, `formatDocument`) — these are the highest-value test targets (zero I/O, callable directly in `build`-layer tests).
+
+## Config flow
+
+Three config files in the consumer project feed the build:
+
+1. **`src/_config.yml`** — Jekyll config (brand, theme, meta, web_manager). Read by `Manager.getConfig('project')`.
+2. **`config/ultimate-jekyll-manager.json`** — UJM-specific config (purgecss safelist, webpack target, imagemin opts, distribute glob patterns). JSON5.
+3. **`package.json`** — read by `Manager.getPackage('project')`.
+
+UJM ships defaults via `_config_default.yml` + `_config_development.yml` at `src/config/` — merged at Jekyll build time via the `--config` chain by [merge-jekyll-configs.js](../src/gulp/tasks/utils/merge-jekyll-configs.js).
+
+## Build modes
+
+| Mode | Trigger | Effect |
+|---|---|---|
+| Development | `npm start` (default) | Serve + watch + incremental rebuild via `developmentRebuild` |
+| Production | `npm run build` (`UJ_BUILD_MODE=true`) | Full pipeline incl. minifyHtml; PurgeCSS runs automatically |
+
+PurgeCSS can be enabled locally with `UJ_PURGECSS=true`; consumer safelist patterns live in `config/ultimate-jekyll-manager.json` under `sass.purgecss.safelist`. See [local-development.md](local-development.md).
+
+## Serve / live reload
+
+The dev server URL is stored in `.temp/_config_browsersync.yml` in the consuming project root — read it to determine the correct URL for browsing/testing. See [local-development.md](local-development.md) for emulator connection (`FIREBASE_EMULATOR_CONNECT=true`).
+
+## Log files
+
+The gulp pipeline tees all output to `logs/dev.log` (`npm start`) / `logs/build.log` (`npm run build`). Full reference: [logging.md](logging.md).
+
+## See also
+
+- [templating.md](templating.md) — node-powertools bracket conventions in the pipeline
+- [css.md](css.md) — SCSS structure + PurgeCSS
+- [local-development.md](local-development.md) — dev server, emulators, PurgeCSS toggles
+- [test-framework.md](test-framework.md) — testing the pipeline's pure helpers

package/docs/common-mistakes.md

@@ -0,0 +1,15 @@
+# Common Mistakes to Avoid
+
+1. **🚫 Inline `<script>` tags in HTML files** — the #1 worst mistake. Move ALL JS to page modules (`src/assets/js/pages/<path>/index.js`) or `main.js`. Component/layout scripts go in `main.js` with element-existence guards. Liquid-templated scripts bridge via `data-*` attributes or `<template>` elements. **Only exceptions:** `type="application/ld+json"`, external `<script src="...">` loaders, and ≤10-line first-paint display helpers with an explaining comment.
+2. **🚫 Reinventing Bootstrap — the #1 CSS mistake** — NEVER create custom classes for things Bootstrap already provides. No `.lm-btn` when `.btn .btn-primary` exists; no `.lm-wrap` when `.container` exists; no custom flex/gap/padding/margin/text-align classes when Bootstrap utilities do the same thing. Theme SCSS overrides how `.btn`/`.card`/`.navbar` LOOK — it doesn't create parallel replacements. Custom CSS is ONLY for genuinely novel components with no Bootstrap equivalent. Before writing ANY custom class, ask: "Does Bootstrap have this?" If yes, USE IT. See [themes.md](themes.md) and [css.md](css.md).
+3. **Creating duplicate CSS** — check Bootstrap and the active theme first.
+4. **Wrong imports** — FormManager needs curly braces: `import { FormManager } from ...`.
+5. **Assuming `Manager`, `firebase`, `webManager` are on `window`** — they are NOT. Use `import webManager from 'web-manager'` in a module. `firebase.firestore()` → `webManager.firestore()`. **Consumer code NEVER imports Firebase directly** — Firebase is web-manager's internal dependency. Same rule in EM and BXM.
+6. **Installing UJM's dependencies as direct consumer deps** — Consumer projects must NOT `npm install firebase`, `web-manager`, or any other UJM/web-manager transitive dep. UJM's webpack config includes `resolve.modules` pointing at the framework's own `node_modules/`. If a dependency isn't resolving, the fix is in UJM's webpack config — not the consumer's `package.json`. Mirrors EM and BXM.
+7. **Not using FormManager** — use it for ALL forms.
+8. **Calling `$form.requestSubmit()` directly** — use `formManager.submit()`.
+9. **Wrong dark mode classes** — use `bg-body` variants, not `bg-light`/`bg-dark`.
+10. **Not waiting for DOM** — always `await webManager.dom().ready()`.
+11. **Using native fetch** — always use `wonderful-fetch` or `authorized-fetch`.
+12. **XSS — unescaped dynamic data in innerHTML** — Use `webManager.utilities().escapeHTML()`. Dynamic URLs in `href`/`src`/`action`/`window.location`/`window.open` ALSO need `webManager.utilities().sanitizeURL()` — `escapeHTML` alone lets `javascript:` execute. See [xss-prevention.md](xss-prevention.md).
+13. **Leaving Liquid `{{ }}` or `{% %}` inside moved JS modules** — Jekyll does NOT process `src/assets/js/**/*.js`. Use `data-*` attribute bridges or `<template>` cloning.

package/docs/{project-structure.md → directory-structure.md}

@@ -1,4 +1,4 @@
-# Project Structure
+# Directory Structure
 
 UJM is a template framework that consuming projects install as an NPM module to build Jekyll sites quickly and efficiently. It provides best-practice configurations, default components, themes, and build tools.
 

package/docs/environment-detection.md

@@ -82,4 +82,4 @@ Write the function in [src/utils/mode-helpers.js](../src/utils/mode-helpers.js)
 
 ## See also
 
-- [test-framework.md](test-framework.md) — `UJ_TEST_MODE` is set automatically by the test runners; `--integration` gates real external APIs.
+- [test-framework.md](test-framework.md) — `UJ_TEST_MODE` is set automatically by the test runners; `--extended` / `TEST_EXTENDED_MODE=true` gates real external APIs.

package/docs/javascript-libraries.md

@@ -46,6 +46,43 @@ Raw subscription data (product.id, status, trial, cancellation) is on `account.s
 
 The same function exists in BEM as `User.resolveSubscription(account)` with identical return shape.
 
+### Reads vs Writes: When to Use What
+
+| Operation | Method | Why |
+|-----------|--------|-----|
+| **Read** (list, fetch single) | `webManager.firestore()` | Faster, cheaper, no Cloud Function cold starts, no HTTP overhead |
+| **Write** (create, update, delete) | `authorizedFetch` (Cloud Function) | Server-side validation, usage tracking, analytics |
+| **Config/limits lookup** | `webManager.config.payment.products` | Already available client-side from `_config.yml`, no fetch needed |
+
+**Dashboard and frontend reads MUST use the Firestore SDK directly** — never call a Cloud Function GET endpoint from the dashboard. Firestore reads are faster, cheaper, and don't incur cold starts. The backend GET routes (`routes/{resource}/get.js`) exist for **external API consumers only**, not for our own frontend. (Requires Firestore security rules that allow the read, e.g. `allow read: if isAuthenticated() && resource.data.owner == authUid()`.)
+
+```javascript
+// Collection query (list user's items) — wait for auth first
+webManager.auth().listen({ once: true }, async ({ user }) => {
+  if (!user) return;
+
+  const result = await webManager.firestore()
+    .collection('codes')
+    .where('owner', '==', user.uid)
+    .orderBy('meta.created.timestampUNIX', 'desc')
+    .get();
+
+  if (result.empty) return; // show empty state
+
+  result.docs.forEach((doc) => {
+    const data = doc.data();
+    // Render item...
+  });
+});
+
+// Single document read
+const doc = await webManager.firestore().doc(`codes/${id}`).get();
+if (!doc.exists()) return; // not found
+const data = doc.data();
+```
+
+Full Firestore query API (chainable `.where()`/`.orderBy()`/`.limit()`/`.startAt()`, response shapes): see `web-manager`'s [docs/modules.md](../../web-manager/docs/modules.md) — in consumer projects, `node_modules/web-manager/docs/modules.md`.
+
 ## Ultimate Jekyll Libraries
 
 Ultimate Jekyll provides helper libraries in `src/assets/js/libs/` that can be imported as needed.
@@ -314,7 +351,7 @@ initializing → ready ⇄ submitting → ready (or submitted)
   allowResubmit: true,       // Allow resubmission after success (false = 'submitted' state)
   resetOnSuccess: false,     // Clear form fields after successful submission
   warnOnUnsavedChanges: true, // Warn user before leaving page with unsaved changes
-  submittingText: 'Processing...', // Text shown on submit button during submission
+  submittingText: 'Processing...', // Text shown on submit button during submission (use '' for icon-only buttons)
   submittedText: 'Processed!', // Text shown on submit button after success (when allowResubmit: false)
   inputGroup: null           // Filter getData() by data-input-group attribute (null = all fields)
 }