@omega.js/web 0.1.0

package/dist/imagemin.js

@@ -0,0 +1,261 @@
+/**
+ * Responsive image matrix — the UJM imagemin successor. After the static
+ * phase ships images verbatim, this build-only pass rewrites every
+ * jpg/jpeg/png under dist/assets/images into the legacy matrix: widths
+ * 320/640/1024 + the original size, each in the source format AND webp,
+ * quality 80 (progressive mozjpeg for jpeg, palette quantization for png),
+ * metadata stripped, upscaling allowed — so every variant name ALWAYS
+ * exists and `@srcset` markup never 404s. Other formats (svg/gif/webp/ico)
+ * stay verbatim; the minted favicon dir is exempt (exact-name mint
+ * contract, fixed-purpose sizes). A file sharp can't decode warns and stays
+ * verbatim — one bad image never fails the build.
+ *
+ * Cache: content-addressed entries under <brand>/.omega/cache/imagemin —
+ * machine-owned and never committed (the outputs are reproducible
+ * binaries); the scaffolded build workflow restores it via actions/cache
+ * (the `cache-uj-imagemin` branch successor). A source-byte or settings
+ * change re-processes exactly that image; stale entries prune every run.
+ *
+ * Dev never processes: devImageFallback() middleware rewrites any missing
+ * -NNNpx/.webp variant URL to the original file, so variant references
+ * resolve in dev too (the legacy serve.js fallback contract).
+ */
+const path = require('node:path');
+const crypto = require('node:crypto');
+const jetpack = require('fs-jetpack');
+
+// The legacy UJM matrix: 3 fixed widths + the original size, source format
+// + webp each → 8 outputs per source image
+const WIDTHS = [320, 640, 1024];
+const QUALITY = 80;
+const RESPONSIVE_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png']);
+// Bump to invalidate every cache entry when encoder settings change
+const FORMAT_VERSION = 1;
+// Top-level dist/assets/images subtrees that stay verbatim: the minted
+// favicon set is an exact-name contract (head.html links each file) with
+// fixed-purpose sizes — variants would be pure dead weight, and the
+// framework's own core images are the same deal (fixed URLs, already
+// avatar-sized)
+const EXEMPT_DIRS = new Set(['favicon', 'core']);
+
+/**
+ * The output plan for one source image: 8 variants, each with its final
+ * on-disk name and its content-addressed name inside the cache entry.
+ * @param {string} base - source basename without extension
+ * @param {string} ext - lowercased source extension (with dot)
+ * @returns {Array<{ outName: string, cacheName: string, width: number|null, format: string }>}
+ */
+function variantPlan(base, ext) {
+  const plan = [];
+  for (const width of [...WIDTHS, null]) {
+    const suffix = width ? `-${width}px` : '';
+    const key = width ? `w${width}` : 'orig';
+    plan.push({ outName: `${base}${suffix}${ext}`, cacheName: `${key}${ext}`, width, format: ext });
+    plan.push({ outName: `${base}${suffix}.webp`, cacheName: `${key}.webp`, width, format: '.webp' });
+  }
+  return plan;
+}
+
+/**
+ * Apply the format encoder to a sharp pipeline.
+ * @param {import('sharp').Sharp} pipeline
+ * @param {string} format - lowercased extension (with dot)
+ * @returns {import('sharp').Sharp}
+ */
+function encode(pipeline, format) {
+  if (format === '.png') {
+    return pipeline.png({ quality: QUALITY });
+  }
+  if (format === '.webp') {
+    return pipeline.webp({ quality: QUALITY });
+  }
+  return pipeline.jpeg({ quality: QUALITY, progressive: true, mozjpeg: true });
+}
+
+/**
+ * Content-addressed cache key for one source image: the bytes plus the
+ * matrix settings, so a settings change re-processes everything.
+ * @param {Buffer} bytes
+ * @returns {string}
+ */
+function entryHash(bytes) {
+  return crypto.createHash('sha256')
+    .update(`v${FORMAT_VERSION}|${WIDTHS.join(',')}|q${QUALITY}|`)
+    .update(bytes)
+    .digest('hex')
+    .slice(0, 16);
+}
+
+/**
+ * Process every eligible image under imagesDir in place: originals are
+ * re-encoded at quality 80 under their own (lowercased-extension) name and
+ * the -320px/-640px/-1024px + webp variants land beside them. Cache-first;
+ * stale cache entries prune at the end.
+ * @param {object} options
+ * @param {string} options.imagesDir - the built site's assets/images dir
+ * @param {string} options.cacheDir - content-addressed cache root (never committed)
+ * @param {function} [options.log] - progress logger (message: string)
+ * @returns {Promise<{ images: number, processed: number, fromCache: number, failed: number, outputs: number, pruned: number, sizeBefore: number, sizeAfter: number, warnings: string[] }>}
+ */
+async function processImages(options) {
+  const { imagesDir, cacheDir, log = () => {} } = options;
+  const result = {
+    images: 0, processed: 0, fromCache: 0, failed: 0,
+    outputs: 0, pruned: 0, sizeBefore: 0, sizeAfter: 0, warnings: [],
+  };
+
+  if (!jetpack.exists(imagesDir)) {
+    return result;
+  }
+
+  const sharp = require('sharp');
+  const files = jetpack.find(imagesDir, { matching: '**/*' }).filter((file) => {
+    const rel = path.relative(imagesDir, file);
+    if (EXEMPT_DIRS.has(rel.split(path.sep)[0])) {
+      return false;
+    }
+    return RESPONSIVE_EXTENSIONS.has(path.extname(file).toLowerCase());
+  });
+  result.images = files.length;
+
+  const validEntries = new Set();
+  let index = 0;
+
+  for (const file of files) {
+    index++;
+    const rel = path.relative(imagesDir, file);
+    const bytes = jetpack.read(file, 'buffer');
+    const ext = path.extname(file);
+    const extLower = ext.toLowerCase();
+    const base = path.basename(file, ext);
+    const dir = path.dirname(file);
+    const plan = variantPlan(base, extLower);
+    const hash = entryHash(bytes);
+    const entryDir = path.join(cacheDir, hash);
+
+    // Uppercase-extension sources ship lowercased (IMG.JPG → IMG.jpg).
+    // Remove BEFORE writing outputs: on case-insensitive filesystems the
+    // lowercased write would hit the same inode and a later remove would
+    // delete the fresh output. The failure path restores the verbatim copy.
+    if (ext !== extLower) {
+      jetpack.remove(file);
+    }
+
+    const cacheHit = plan.every((variant) => jetpack.exists(path.join(entryDir, variant.cacheName)));
+
+    if (cacheHit) {
+      for (const variant of plan) {
+        jetpack.copy(path.join(entryDir, variant.cacheName), path.join(dir, variant.outName), { overwrite: true });
+        result.sizeAfter += jetpack.inspect(path.join(dir, variant.outName)).size;
+      }
+      result.fromCache++;
+    } else {
+      try {
+        const buffers = [];
+        for (const variant of plan) {
+          let pipeline = sharp(bytes);
+          if (variant.width) {
+            pipeline = pipeline.resize({ width: variant.width });
+          }
+          buffers.push({ variant, buffer: await encode(pipeline, variant.format).toBuffer() });
+        }
+        // All variants encoded — commit the cache entry and the outputs
+        for (const { variant, buffer } of buffers) {
+          jetpack.write(path.join(entryDir, variant.cacheName), buffer);
+          jetpack.write(path.join(dir, variant.outName), buffer);
+          result.sizeAfter += buffer.length;
+        }
+        result.processed++;
+        log(`imagemin: [${index}/${files.length}] ${rel} → ${plan.length} outputs`);
+      } catch (error) {
+        // Undecodable image: warn, drop the half-written entry, keep the
+        // verbatim copy the static phase already shipped
+        jetpack.remove(entryDir);
+        jetpack.write(file, bytes);
+        result.failed++;
+        result.warnings.push(`${rel}: ${error.message}`);
+        continue;
+      }
+    }
+
+    validEntries.add(hash);
+    result.sizeBefore += bytes.length;
+    result.outputs += plan.length;
+  }
+
+  // Prune cache entries whose source is gone (or re-encoded differently)
+  for (const entry of jetpack.list(cacheDir) || []) {
+    if (!validEntries.has(entry)) {
+      jetpack.remove(path.join(cacheDir, entry));
+      result.pruned++;
+    }
+  }
+
+  const failedNote = result.failed ? `, ${result.failed} failed` : '';
+  const prunedNote = result.pruned ? `, ${result.pruned} stale cache entries pruned` : '';
+  log(`imagemin: ${result.processed} processed, ${result.fromCache} from cache → ${result.outputs} outputs (${formatBytes(result.sizeBefore)} source → ${formatBytes(result.sizeAfter)} shipped)${failedNote}${prunedNote}`);
+
+  return result;
+}
+
+/**
+ * Dev-server middleware: variant URLs resolve without processing. A missing
+ * /assets/images/…-NNNpx or .webp request rewrites to the original file
+ * (which dev ships verbatim), so markup can reference the build-time matrix
+ * unconditionally.
+ * @param {string} outDir - the dev output dir static files serve from
+ * @returns {function} connect-style (req, res, next) middleware
+ */
+function devImageFallback(outDir) {
+  const root = path.resolve(outDir);
+  const inRoot = (pathname) => {
+    const resolved = path.resolve(root, `.${pathname}`);
+    return resolved.startsWith(root + path.sep) ? resolved : null;
+  };
+
+  return (req, res, next) => {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0]);
+    const requested = pathname.startsWith('/assets/images/') ? inRoot(pathname) : null;
+    if (!requested || jetpack.exists(requested)) {
+      return next();
+    }
+
+    // Strip the size suffix first: hero-640px.jpg → hero.jpg
+    const stripped = pathname.replace(/-\d+px(\.[^./]+)$/, '$1');
+    const strippedFile = stripped === pathname ? null : inRoot(stripped);
+    if (strippedFile && jetpack.exists(strippedFile)) {
+      req.url = stripped;
+      return next();
+    }
+
+    // A .webp variant of a non-webp source: try the source extensions
+    if (stripped.endsWith('.webp')) {
+      const base = stripped.slice(0, -'.webp'.length);
+      for (const ext of ['.jpg', '.jpeg', '.png', '.gif']) {
+        const candidate = inRoot(base + ext);
+        if (candidate && jetpack.exists(candidate)) {
+          req.url = base + ext;
+          return next();
+        }
+      }
+    }
+
+    return next();
+  };
+}
+
+/**
+ * Human-readable byte count for the summary line.
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) {
+    return '0 B';
+  }
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const order = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+  return `${parseFloat((bytes / 1024 ** order).toFixed(1))} ${units[order]}`;
+}
+
+module.exports = { processImages, devImageFallback, WIDTHS, QUALITY };

package/dist/index.js

@@ -0,0 +1,41 @@
+/**
+ * @omega.js/web — the OMEGA web framework: Eleventy 3 + LiquidJS +
+ * @omega.js/template-kit engine core (promoted from the winning bake-off
+ * spike — decision memo: _attic/spikes/bakeoff-shared/DECISION.md) plus the `omega`
+ * CLI (bin/omega → src/cli.js → src/commands/), which consumes these same
+ * entry points.
+ */
+const { configureOmega } = require('./engine.js');
+const { buildSite } = require('./build.js');
+const { buildAssets, purgeCss } = require('./assets.js');
+const { collectLayered } = require('./layers.js');
+const { createFrontmatterResolver } = require('./frontmatter-liquid.js');
+const { permalinkOf } = require('./consumer-scan.js');
+const { registerVirtualLayouts, composeSymlinkFarm } = require('./layouts.js');
+const { PATHS, resolveClientEntry } = require('./paths.js');
+const { consumerPaths, loadSiteData } = require('./consumer.js');
+const { scaffoldDefaults } = require('./scaffold.js');
+const { runMigration } = require('./migrate/index.js');
+const { getEnvironment, isDevelopment, isProduction, isTesting } = require('./mode-helpers.js');
+
+module.exports = {
+  configureOmega,
+  buildSite,
+  buildAssets,
+  purgeCss,
+  collectLayered,
+  createFrontmatterResolver,
+  permalinkOf,
+  registerVirtualLayouts,
+  composeSymlinkFarm,
+  PATHS,
+  resolveClientEntry,
+  consumerPaths,
+  loadSiteData,
+  scaffoldDefaults,
+  runMigration,
+  getEnvironment,
+  isDevelopment,
+  isProduction,
+  isTesting,
+};

package/dist/inline-icons.js

@@ -0,0 +1,65 @@
+/**
+ * Build-time icon inlining — the build half of the ONE icon system
+ * ([#619](https://github.com/Omega-JS-Stack/omega/issues/619)).
+ *
+ * Authoring is native Font Awesome markup, everywhere, with nothing to learn:
+ *
+ *   <i class="fa-solid fa-rocket"></i>
+ *   <i class="fa-brands fa-github fa-2xl"></i>
+ *   <i class="omega-flag omega-flag-us"></i>     — the flags namespace
+ *
+ * This pass runs over the RENDERED page (an Eleventy transform, like
+ * cachebreak-html.js) and fills every empty `<i>` whose classes name an icon
+ * with that icon's SVG. Static chrome therefore costs zero runtime fetches
+ * and never flashes; anything JS creates after the build is upgraded by the
+ * runtime watcher instead (runtime/icons.js), out of the same emitted set.
+ *
+ * The markup emitted here is BYTE-IDENTICAL to what @omega.js/client's
+ * icon-renderer produces in the browser — same `data-omega-fa` stamp, same
+ * icon-core root attributes — so the two halves can never render one icon two
+ * ways, and the stamp is also what tells the watcher this element is already
+ * done.
+ *
+ * A name the icon set has no file for is left EMPTY and marked
+ * `data-omega-icon-missing` (the dev audit turns those into console errors):
+ * a missing icon is a content problem, never a crash and never a wrong-glyph
+ * fallback.
+ */
+
+const { parseIconClasses, isValidIconName, isValidStyle, injectSvgAttributes } = require('@omega.js/client/modules/icon-core.js');
+
+// Only EMPTY <i> elements are icons. An `<i>` with content is emphasis (or an
+// icon a previous pass already filled), and neither is this pass's business.
+const EMPTY_I_PATTERN = /<i\b([^>]*)><\/i>/gi;
+const CLASS_ATTR_PATTERN = /(?:^|\s)class="([^"]*)"/i;
+
+/**
+ * Inline every icon a rendered page names.
+ *
+ * @param {string} html - the rendered page
+ * @param {function(string, string): (string|null)} load - (name, style) → raw SVG
+ * @param {function(string)} [onMissing] - called with `<style>/<name>` per unresolved icon
+ * @returns {string} the page with its icons inlined
+ */
+function inlineIcons(html, load, onMissing) {
+  return String(html).replace(EMPTY_I_PATTERN, (tag, attrs) => {
+    if (attrs.includes('data-omega-fa=')) return tag;
+
+    const classAttr = CLASS_ATTR_PATTERN.exec(attrs);
+    if (!classAttr) return tag;
+
+    const parsed = parseIconClasses(classAttr[1].split(/\s+/).filter(Boolean));
+    if (!parsed || !isValidIconName(parsed.name) || !isValidStyle(parsed.style)) return tag;
+
+    const key = `${parsed.style}/${parsed.name}`;
+    const svg = load(parsed.name, parsed.style);
+    if (!svg) {
+      if (onMissing) onMissing(key);
+      return `<i${attrs} data-omega-fa="${key}" data-omega-icon-missing="${key}"></i>`;
+    }
+
+    return `<i${attrs} data-omega-fa="${key}">${injectSvgAttributes(svg)}</i>`;
+  });
+}
+
+module.exports = { inlineIcons };

package/dist/language-flags.js

@@ -0,0 +1,55 @@
+/**
+ * Language flag aliases for the client-side switcher (#129).
+ *
+ * The retired footer dropdown drew its flags at BUILD time, through the core
+ * flag set and the language→country map. The switcher renders in the BROWSER
+ * from the page's own hreflang tags, so no build-time lookup can run for it —
+ * but the flag set already ships:
+ * emitIcons copies `core/icons/` wholesale, so `core/icons/flags/us.svg` lands
+ * at `assets/icons/flags/us.svg` in every build and dev boot.
+ *
+ * This pass writes LANGUAGE-named copies into their own namespace,
+ * `assets/icons/flags/lang/<code>.svg`, so a browser row needs only its hreflang
+ * code and carries no map of its own. The map stays template-kit's — the one
+ * home. The namespace is not cosmetic: language codes and country codes share
+ * a space (`ar` is Arabic AND Argentina, `ca` is Catalan AND Canada), so
+ * writing aliases beside the country set would overwrite real flags.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { ICONS_DIR } = require('./vendor/devkit/icons.js');
+const { LANGUAGE_TO_COUNTRY } = require('./vendor/template-kit/index.js');
+
+/**
+ * Write the language-named flag aliases into an emitted icon set. Runs AFTER
+ * emitIcons (it reads what that pass copied) and is idempotent — an alias that
+ * already exists is rewritten from the same source.
+ * @param {object} options
+ * @param {string} options.outDir - build output dir (the one emitIcons wrote into)
+ * @returns {{ files: number, dest: string }} aliases written + the alias dir
+ */
+function emitLanguageFlags(options) {
+  const flags = path.join(options.outDir, 'assets', ICONS_DIR, 'flags');
+  const dest = path.join(flags, 'lang');
+
+  // No flag set in this output (a build with no core icons dir) — nothing to alias
+  if (!fs.existsSync(flags)) return { files: 0, dest };
+
+  let files = 0;
+
+  for (const [language, country] of Object.entries(LANGUAGE_TO_COUNTRY)) {
+    const source = path.join(flags, `${country}.svg`);
+
+    // The set covers 47 countries, the map 46 languages — a language whose
+    // country has no flag simply gets none, and the row drops its <img>
+    if (!fs.existsSync(source)) continue;
+
+    fs.mkdirSync(dest, { recursive: true });
+    fs.copyFileSync(source, path.join(dest, `${language}.svg`));
+    files += 1;
+  }
+
+  return { files, dest };
+}
+
+module.exports = { emitLanguageFlags };

package/dist/layers.js

@@ -0,0 +1,80 @@
+/**
+ * Layered file resolution — SSG-agnostic core of the OMEGA theme system.
+ *
+ * A "layer chain" is an ordered list of directories (site → active theme →
+ * base theme → core); for any relative path the FIRST layer that contains it
+ * wins. Both bake-off candidates build their theme layering, page-module
+ * unions, and default-page scans on this.
+ *
+ * Every read goes through the captured-read helper (@omega.js/devkit/reads): inside a
+ * config build that is what registers each probed layer dir as a dev watch
+ * target, including the ones that do not exist yet (#200).
+ */
+const path = require('node:path');
+const reads = require('./vendor/devkit/reads.js');
+
+/**
+ * Collect EVERY layer that provides each relative path, in layer order. The
+ * first entry of each list is the winner; the rest are what it shadows —
+ * which is what the override map (`omega customize --list`) reports.
+ * @param {string[]} layerDirs - ordered layer dirs (first wins)
+ * @param {RegExp} [filter] - only include matching relative paths
+ * @returns {Map<string, Array<{ dir: string, file: string }>>} relative path → providers
+ */
+function collectProviders(layerDirs, filter) {
+  const providers = new Map();
+
+  for (const dir of layerDirs) {
+    if (!reads.dirExists(dir)) continue;
+
+    for (const entry of reads.readdir(dir, { recursive: true, withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+
+      const rel = path.relative(dir, path.join(entry.parentPath, entry.name));
+      if (filter && !filter.test(rel)) continue;
+      if (!providers.has(rel)) providers.set(rel, []);
+      providers.get(rel).push({ dir, file: path.join(dir, rel) });
+    }
+  }
+
+  return providers;
+}
+
+/**
+ * Collect the layered union of files under a list of layer directories.
+ * @param {string[]} layerDirs - ordered layer dirs (first wins)
+ * @param {RegExp} [filter] - only include matching relative paths
+ * @returns {Map<string, string>} relative path → winning absolute path
+ */
+function collectLayered(layerDirs, filter) {
+  const winners = new Map();
+
+  for (const [rel, providers] of collectProviders(layerDirs, filter)) {
+    winners.set(rel, providers[0].file);
+  }
+
+  return winners;
+}
+
+/**
+ * Resolve the ordered theme layer dirs for an active theme. Consumer-local
+ * themes win: `<consumerDir>/themes/<id>` beats the packaged `<themesDir>/<id>`,
+ * so a brand ships a FULL theme without forking the framework (C3 tier 2 —
+ * tier 1 is a consumer main.scss over the stock theme via `omega:main`).
+ * Every chain ends at `themes/base`, the structural markup layer with the
+ * neutral `omega-*` vocabulary (#177); themes are skins over it.
+ * @param {object} options
+ * @param {string} [options.activeTheme] - theme id (default 'classy')
+ * @param {string} [options.consumerDir] - consumer root to probe for local themes
+ * @param {string} options.themesDir - packaged themes root
+ * @returns {string[]} ordered theme layer dirs (active first, base last)
+ */
+function resolveThemeLayers({ activeTheme, consumerDir, themesDir }) {
+  const resolveId = (id) => {
+    const local = consumerDir ? path.join(consumerDir, 'themes', id) : null;
+    return local && reads.dirExists(local) ? local : path.join(themesDir, id);
+  };
+  return [...new Set([activeTheme || 'classy', 'base'])].map(resolveId);
+}
+
+module.exports = { collectLayered, collectProviders, resolveThemeLayers };

package/dist/layouts.js

@@ -0,0 +1,44 @@
+/**
+ * Layered layout DELIVERY — ZERO file copying. (The layered resolution
+ * itself is `collectLayered()` in ./layers.js.) Two delivery modes:
+ *
+ * - `virtual` (build): each winning layout file is registered as an Eleventy
+ *   v3 virtual template under `_includes/<rel>` — validated in the A1 probe
+ *   (layering, cross-layer layout chaining, no page emission).
+ * - `farm` (dev): a symlink farm is composed at a fixed dir and used as the
+ *   includes directory — symlinks are watchable, virtual templates are not
+ *   (their content is captured at config time).
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const reads = require('./vendor/devkit/reads.js');
+
+/**
+ * Register the winning layout files as Eleventy virtual templates so that
+ * Jekyll-style `layout: blueprint/index` names resolve verbatim.
+ * @param {object} eleventyConfig
+ * @param {Map<string, string>} layoutMap - from collectLayered() over _layouts dirs
+ */
+function registerVirtualLayouts(eleventyConfig, layoutMap) {
+  for (const [rel, abs] of layoutMap) {
+    eleventyConfig.addTemplate(`_includes/${rel}`, reads.read(abs));
+  }
+}
+
+/**
+ * Compose a symlink farm of the winning layout files (dev mode — watchable).
+ * Idempotent: the farm is rebuilt from scratch on every call.
+ * @param {Map<string, string>} layoutMap
+ * @param {string} farmDir - absolute target directory
+ */
+function composeSymlinkFarm(layoutMap, farmDir) {
+  fs.rmSync(farmDir, { recursive: true, force: true });
+
+  for (const [rel, abs] of layoutMap) {
+    const target = path.join(farmDir, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.symlinkSync(abs, target);
+  }
+}
+
+module.exports = { registerVirtualLayouts, composeSymlinkFarm };