@omega.js/web 0.1.0

package/dist/brand-tokens.js

@@ -0,0 +1,195 @@
+/**
+ * Brand accent ramp — derives the accent token family from ONE brand color
+ * (C3/D6: `brand.color` drives the accent everywhere via CSS custom
+ * properties; the static token sheet's neutral placeholder stands when the
+ * brand has no usable color).
+ *
+ * Pure math, dependency-free: hex → RGB → HSL round-trips plus WCAG
+ * relative luminance for the on-accent ink pick. Every output value is
+ * regenerated from parsed numbers, so nothing from config reaches the
+ * emitted <style> block verbatim.
+ */
+
+const INK_DARK = '#111213';
+const INK_LIGHT = '#ffffff';
+
+// WCAG contrast-vs-white beats contrast-vs-black below this luminance
+const INK_LUMINANCE_THRESHOLD = 0.1791;
+
+// Accents darker than this lightness brighten on hover instead of darkening
+const HOVER_LIGHTEN_THRESHOLD = 0.25;
+
+// Dark-mode variant: accents at/above this lightness are already legible on
+// charcoal and pass through; darker ones lift into the floor..ceil band.
+const DARK_KEEP_THRESHOLD = 0.66;
+const DARK_LIGHTNESS_FLOOR = 0.55;
+const DARK_LIGHTNESS_CEIL = 0.78;
+
+/**
+ * Parse a 3- or 6-digit hex color.
+ * @param {*} value - candidate color
+ * @returns {{ r: number, g: number, b: number }|null} channels 0-255, or null
+ */
+function parseHex(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const match = value.trim().match(/^#?([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (!match) {
+    return null;
+  }
+
+  let hex = match[1].toLowerCase();
+  if (hex.length === 3) {
+    hex = hex.split('').map((c) => c + c).join('');
+  }
+
+  return {
+    r: parseInt(hex.slice(0, 2), 16),
+    g: parseInt(hex.slice(2, 4), 16),
+    b: parseInt(hex.slice(4, 6), 16),
+  };
+}
+
+/**
+ * WCAG 2.x relative luminance.
+ * @param {{ r: number, g: number, b: number }} rgb - channels 0-255
+ * @returns {number} 0 (black) to 1 (white)
+ */
+function relativeLuminance({ r, g, b }) {
+  const linearize = (channel) => {
+    const c = channel / 255;
+    return c <= 0.03928 ? c / 12.92 : (((c + 0.055) / 1.055) ** 2.4);
+  };
+  return (0.2126 * linearize(r)) + (0.7152 * linearize(g)) + (0.0722 * linearize(b));
+}
+
+/**
+ * RGB (0-255) → HSL (h 0-360, s/l 0-1).
+ */
+function rgbToHsl({ r, g, b }) {
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+
+  if (max === min) {
+    return { h: 0, s: 0, l };
+  }
+
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === rn) {
+    h = ((gn - bn) / d) + (gn < bn ? 6 : 0);
+  } else if (max === gn) {
+    h = ((bn - rn) / d) + 2;
+  } else {
+    h = ((rn - gn) / d) + 4;
+  }
+
+  return { h: h * 60, s, l };
+}
+
+/**
+ * HSL (h 0-360, s/l 0-1) → RGB (0-255).
+ */
+function hslToRgb({ h, s, l }) {
+  if (s === 0) {
+    const v = Math.round(l * 255);
+    return { r: v, g: v, b: v };
+  }
+
+  const hueToChannel = (p, q, t) => {
+    let tn = t;
+    if (tn < 0) tn += 1;
+    if (tn > 1) tn -= 1;
+    if (tn < 1 / 6) return p + ((q - p) * 6 * tn);
+    if (tn < 1 / 2) return q;
+    if (tn < 2 / 3) return p + ((q - p) * ((2 / 3) - tn) * 6);
+    return p;
+  };
+
+  const q = l < 0.5 ? l * (1 + s) : l + s - (l * s);
+  const p = (2 * l) - q;
+  const hn = h / 360;
+
+  return {
+    r: Math.round(hueToChannel(p, q, hn + (1 / 3)) * 255),
+    g: Math.round(hueToChannel(p, q, hn) * 255),
+    b: Math.round(hueToChannel(p, q, hn - (1 / 3)) * 255),
+  };
+}
+
+/**
+ * RGB → #rrggbb.
+ */
+function toHex({ r, g, b }) {
+  const pair = (v) => v.toString(16).padStart(2, '0');
+  return `#${pair(r)}${pair(g)}${pair(b)}`;
+}
+
+/**
+ * Shift an accent's lightness for hover/active states — darker accents
+ * brighten, everything else deepens, clamped to [0, 1].
+ * @param {{ h: number, s: number, l: number }} hsl - base accent
+ * @param {number} amount - lightness delta (positive magnitude)
+ * @returns {string} #rrggbb
+ */
+function shiftLightness(hsl, amount) {
+  const direction = hsl.l < HOVER_LIGHTEN_THRESHOLD ? 1 : -1;
+  const l = Math.min(1, Math.max(0, hsl.l + (direction * amount)));
+  return toHex(hslToRgb({ ...hsl, l }));
+}
+
+/**
+ * Compose one accent ramp from resolved channels.
+ * @param {{ r: number, g: number, b: number }} rgb - accent channels
+ * @param {{ h: number, s: number, l: number }} hsl - same accent in HSL
+ * @param {number} subtleAlpha - alpha for the subtle wash (mode-specific)
+ * @returns {object} { accent, accentHover, accentActive, accentSubtle, accentInk, accentRing }
+ */
+function composeRamp(rgb, hsl, subtleAlpha) {
+  const luminance = relativeLuminance(rgb);
+
+  return {
+    accent: toHex(rgb),
+    accentHover: shiftLightness(hsl, 0.07),
+    accentActive: shiftLightness(hsl, 0.11),
+    accentSubtle: `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${subtleAlpha})`,
+    accentInk: luminance > INK_LUMINANCE_THRESHOLD ? INK_DARK : INK_LIGHT,
+    accentRing: `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, 0.35)`,
+  };
+}
+
+/**
+ * Compose the accent token families from a brand color: the light ramp plus
+ * a dark-mode variant (darker brand colors lift so they stay legible on the
+ * charcoal ground — the classy v2 per-mode accent).
+ * @param {string} color - brand color (#rgb or #rrggbb)
+ * @returns {object|null} ramps for the head emitter, or null when unusable:
+ *   { accent, accentHover, accentActive, accentSubtle, accentInk, accentRing,
+ *     dark: { …same shape… } }
+ */
+function composeBrandTokens(color) {
+  const rgb = parseHex(color);
+  if (!rgb) {
+    return null;
+  }
+
+  const hsl = rgbToHsl(rgb);
+  const darkHsl = hsl.l >= DARK_KEEP_THRESHOLD
+    ? hsl
+    : { ...hsl, l: Math.min(Math.max(hsl.l + 0.1, DARK_LIGHTNESS_FLOOR), DARK_LIGHTNESS_CEIL) };
+  const darkRgb = hslToRgb(darkHsl);
+
+  return {
+    ...composeRamp(rgb, hsl, 0.12),
+    dark: composeRamp(darkRgb, darkHsl, 0.16),
+  };
+}
+
+module.exports = { composeBrandTokens, parseHex, relativeLuminance };

package/dist/build.js

@@ -0,0 +1,192 @@
+/**
+ * Full production build orchestration — the seed of `omega build` (B3):
+ * assets (esbuild page modules + layered sass) → Eleventy → PurgeCSS, with
+ * per-phase timings returned for benches and CLIs. Consumer-agnostic: the
+ * caller supplies the consumer dir + site data; framework content (themes,
+ * core, default pages) defaults to what ships with the package.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { buildAssets, purgeCss } = require('./assets.js');
+const { resolvePathPrefix } = require('./path-prefix.js');
+const { buildServiceWorker, writeBuildMeta } = require('./service-worker.js');
+const { copyStaticAssets, hasFaviconSet, brandmarkSvgUrl } = require('./static-assets.js');
+const { processImages } = require('./imagemin.js');
+const { configureOmega } = require('./engine.js');
+const { emitIcons } = require('./vendor/devkit/icons.js');
+const { emitLanguageFlags } = require('./language-flags.js');
+const { resolveThemeLayers } = require('./layers.js');
+const { getEnvironment } = require('./mode-helpers.js');
+const { PATHS } = require('./paths.js');
+
+/**
+ * Build a consumer site end to end.
+ * @param {object} options
+ * @param {string} options.consumerDir - the consumer site (Eleventy input dir)
+ * @param {object} options.siteData - raw site data (resolved omega config shape)
+ * @param {string} options.outDir - output dir (cleared first)
+ * @param {string} options.clientEntry - @omega.js/client entry for the `@omega.js/client` esbuild alias
+ * @param {string} [options.version] - the consumer package version (build meta / service worker, and the Configuration block the client reads)
+ * @param {string} [options.siteAssetsDir] - the consumer's own asset layer (js/pages page modules)
+ * @param {string} [options.themesDir] - default: packaged themes
+ * @param {string} [options.coreDir] - default: packaged core
+ * @param {string} [options.defaultsDir] - default: packaged default pages
+ * @param {string} [options.activeTheme] - default: siteData.theme.id
+ * @param {Array<{src: string, dest: string}>} [options.staticDirs] - verbatim static copies (resolveStaticDirs), later entries win
+ * @param {{ cacheDir: string, log?: function }} [options.imagemin] - responsive image matrix over the copied images (omit to skip — dev and `web.imagemin.enabled: false`)
+ * @param {string} [options.layoutMode] - 'virtual' (default) or 'farm'
+ * @param {string} [options.farmDir] - symlink-farm target (farm mode)
+ * @param {boolean} [options.skipPurge] - skip the PurgeCSS pass
+ * @param {string} [options.manifestPath] - also write the asset manifest here (the dev config reads it)
+ * @param {string} [options.pathPrefix] - the base path the site is served under (#355) — default `process.env.OMEGA_PATH_PREFIX`, then the domain root
+ * @param {object} [options.license] - the deploy-time license stamp (#320) the verb resolved → site.license (default: keyless)
+ * @param {function} [options.onPhase] - (name, seconds) callback after each phase
+ * @returns {Promise<{ timings: object, htmlCount: number, manifest: object, pathPrefix: string }>}
+ */
+async function buildSite(options) {
+  // The environment (#717): resolved ONCE here, from the one surface, and
+  // handed to both emit lanes below — the build meta and the engine read the
+  // same answer instead of each re-testing a loose `options.environment`.
+  const environment = getEnvironment.call(options);
+  const themesDir = options.themesDir || PATHS.themes;
+  const coreDir = options.coreDir || PATHS.core;
+  const defaultsDir = options.defaultsDir || PATHS.defaults;
+  const activeTheme = options.activeTheme || (options.siteData.theme && options.siteData.theme.id) || 'classy';
+  const themeLayerDirs = resolveThemeLayers({ activeTheme, consumerDir: options.consumerDir, themesDir });
+  // Base path (#355), read ONCE here and handed to both emit lanes. The env var
+  // is the publisher's channel (workkit's publish derives it from the Pages
+  // API); `omega dev` never comes through here, so the dev server keeps serving
+  // at the root no matter what the environment says.
+  const pathPrefix = resolvePathPrefix(
+    options.pathPrefix === undefined ? process.env.OMEGA_PATH_PREFIX : options.pathPrefix,
+  );
+
+  const timings = {};
+  const started = process.hrtime.bigint();
+  const phase = async (name, fn) => {
+    const t0 = process.hrtime.bigint();
+    const result = await fn();
+    timings[name] = Number(process.hrtime.bigint() - t0) / 1e9;
+    if (options.onPhase) options.onPhase(name, timings[name]);
+    return result;
+  };
+
+  fs.rmSync(options.outDir, { recursive: true, force: true });
+
+  // ---- assets first: the manifest feeds the head/foot includes
+  const manifest = await phase('assets', () =>
+    buildAssets({
+      layers: [
+        ...(options.siteAssetsDir ? [options.siteAssetsDir] : []),
+        ...themeLayerDirs,
+        coreDir,
+      ],
+      themeRoots: themeLayerDirs,
+      sectionRoots: [options.consumerDir, ...themeLayerDirs],
+      themesDir,
+      coreDir,
+      outDir: options.outDir,
+      clientEntry: options.clientEntry,
+      pathPrefix,
+    })
+  );
+  manifest.favicons = hasFaviconSet(options.staticDirs);
+  manifest.brandmarkSvg = brandmarkSvgUrl(options.staticDirs);
+  if (options.manifestPath) {
+    fs.mkdirSync(path.dirname(options.manifestPath), { recursive: true });
+    fs.writeFileSync(options.manifestPath, JSON.stringify(manifest, null, 2));
+  }
+
+  // ---- service worker + build meta: /service-worker.js, /build.js, /build.json
+  await phase('service-worker', async () => {
+    writeBuildMeta({
+      siteData: options.siteData,
+      outDir: options.outDir,
+      environment,
+      version: options.version,
+      consumerDir: options.consumerDir,
+      clientEntry: options.clientEntry,
+      manifest,
+    });
+    return buildServiceWorker({
+      consumerDir: options.consumerDir,
+      outDir: options.outDir,
+      clientEntry: options.clientEntry,
+    });
+  });
+
+  // ---- runtime icon set (assets/icons/) — feeds the browser-side auto-render,
+  //      plus the language-named flag aliases the client switcher fetches
+  await phase('icons', () => {
+    const icons = emitIcons({
+      outDir: options.outDir,
+      coreIconsDir: path.join(coreDir, 'icons'),
+    });
+    emitLanguageFlags({ outDir: options.outDir });
+    return icons;
+  });
+
+  // ---- static assets: minted brand identity bridge + consumer src/assets
+  if (options.staticDirs && options.staticDirs.length) {
+    await phase('static', () => copyStaticAssets({ staticDirs: options.staticDirs, outDir: options.outDir }));
+  }
+
+  // ---- responsive image matrix over the shipped images (build-time only)
+  let imagemin = null;
+  if (options.imagemin) {
+    imagemin = await phase('imagemin', () => processImages({
+      imagesDir: path.join(options.outDir, 'assets', 'images'),
+      cacheDir: options.imagemin.cacheDir,
+      log: options.imagemin.log,
+    }));
+  }
+
+  // ---- Eleventy
+  await phase('eleventy', async () => {
+    const Eleventy = require('@11ty/eleventy').default;
+    const elev = new Eleventy(options.consumerDir, options.outDir, {
+      quietMode: true,
+      configPath: false,
+      config: (eleventyConfig) =>
+        configureOmega(eleventyConfig, {
+          consumerDir: options.consumerDir,
+          siteData: options.siteData,
+          themesDir,
+          coreDir,
+          defaultsDir,
+          activeTheme,
+          layoutMode: options.layoutMode,
+          farmDir: options.farmDir,
+          assetManifest: manifest,
+          environment,
+          version: options.version,
+          pathPrefix,
+          license: options.license,
+        }),
+    });
+    await elev.write();
+  });
+
+  // ---- PurgeCSS over the rendered HTML
+  if (!options.skipPurge) {
+    await phase('purge', () => purgeCss({ outDir: options.outDir, manifest, purgecss: options.siteData.purgecss }));
+  }
+
+  timings.total = Number(process.hrtime.bigint() - started) / 1e9;
+  return { timings, htmlCount: countHtml(options.outDir), manifest, imagemin, pathPrefix };
+}
+
+/**
+ * Count .html files under a directory.
+ * @param {string} dir
+ * @returns {number}
+ */
+function countHtml(dir) {
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { recursive: true, withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith('.html')) count++;
+  }
+  return count;
+}
+
+module.exports = { buildSite };

package/dist/cachebreak-html.js

@@ -0,0 +1,71 @@
+/**
+ * Build-time image cache-breaker — every LOCAL <img>/<source> URL in
+ * rendered HTML gets ?cb=<build stamp> so image edits show up on rebuilds
+ * without busting on every request. One stamp per build process, shared
+ * with the omega_cachebreak filter and (via site.omega.cache_breaker) the runtime
+ * lazy-loader.
+ *
+ * Local = site-relative or bare-relative URLs. External (http/https,
+ * protocol-relative), data:/blob:, and empty srcs pass through; URLs that
+ * already carry a cb param keep the value they have (an explicit
+ * omega_cachebreak or author value wins).
+ */
+
+const { mapSrcset } = require('./srcset.js');
+
+const IMG_TAG_PATTERN = /<(?:img|source)\b[^>]*>/gi;
+// Lookbehind keeps data-src/data-srcset (and any *-src) out of scope
+const SRC_ATTR_PATTERN = /(?<![-\w])(src|srcset)=(?:"([^"]*)"|'([^']*)')/gi;
+
+/**
+ * Whether a URL is a first-party asset this build owns.
+ *
+ * ⚠️ Mirrored by `isLocalUrl()` in `core/js/core/lazy-loading.js` (#368) — the
+ * runtime half busts the caches of the `data-lazy` URLs this pass defers.
+ *
+ * @param {string} url
+ * @returns {boolean}
+ */
+function isLocal(url) {
+  const value = String(url).trim();
+  if (!value) return false;
+  if (/^(https?:)?\/\//i.test(value)) return false;
+  if (/^(data|blob|mailto|tel|javascript):/i.test(value)) return false;
+  return true;
+}
+
+/**
+ * Append the stamp to one URL (no-op for external/data/already-stamped).
+ * @param {string} url
+ * @param {string} stamp
+ * @returns {string}
+ */
+function breakUrl(url, stamp) {
+  if (!isLocal(url) || /[?&]cb=/.test(url)) return url;
+
+  const [base, hash] = url.split('#');
+  const sep = base.includes('?') ? '&' : '?';
+  return `${base}${sep}cb=${stamp}${hash ? `#${hash}` : ''}`;
+}
+
+/**
+ * Rewrite an HTML document's <img>/<source> src + srcset attributes.
+ * @param {string} html - rendered page
+ * @param {string} stamp - build cache stamp (CACHE_TIMESTAMP)
+ * @returns {string}
+ */
+function cachebreakHtml(html, stamp) {
+  return String(html).replace(IMG_TAG_PATTERN, (tag) => tag.replace(
+    SRC_ATTR_PATTERN,
+    (attr, name, doubleQuoted, singleQuoted) => {
+      const value = doubleQuoted !== undefined ? doubleQuoted : singleQuoted;
+      const broken = name.toLowerCase() === 'srcset'
+        ? mapSrcset(value, (url) => breakUrl(url, stamp))
+        : breakUrl(value, stamp);
+      const quote = doubleQuoted !== undefined ? '"' : "'";
+      return `${name}=${quote}${broken}${quote}`;
+    },
+  ));
+}
+
+module.exports = { cachebreakHtml };

package/dist/cli-run.js

@@ -0,0 +1,25 @@
+/**
+ * run() — the omega bin body for @omega.js/web, shared by bin/omega (via
+ * src/omega-bin.js) and cross-framework dispatch ('@omega.js/web/cli').
+ */
+async function run() {
+  // Local-dist freshness guard: a stale locally-linked dist rebuilds and the
+  // invocation re-execs once, so no command ever runs stale framework code
+  require('./vendor/devkit/local.js').freshnessBoot({ packageName: '@omega.js/web' });
+
+  // Value-less flags must be declared boolean — otherwise yargs treats the next
+  // positional as the flag's VALUE (`omega test --extended some/target` would
+  // become extended='some/target' with NO target). Mirrors the UJM/@omega.js/backend
+  // CLI fix. yargs' built-in --version/--help are disabled so `-v`/`--version`
+  // route to our version command through the alias table.
+  const argv = require('yargs')(process.argv.slice(2))
+    .boolean(['extended', 'check', 'dry-run', 'local', 'direct', 'list', 'a'])
+    .version(false)
+    .help(false)
+    .parseSync();
+  const cli = new (require('./cli.js'))(argv);
+
+  await cli.process(argv);
+}
+
+module.exports = { run };

package/dist/cli.js

@@ -0,0 +1,47 @@
+/**
+ * The @omega.js/web CLI dispatcher — devkit's shared router over
+ * src/commands/. `omega` with no command prints help: setup is retired and
+ * every verb runs the local scaffold itself ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)).
+ */
+const path = require('node:path');
+
+// Resolve the .env cascade from the consumer project before any command runs
+// (shell > local .env > brand .env > company .env). The target name delivers
+// the schema's `deliverAs` renames into process.env (#678) — the brand's
+// GOOGLE_ANALYTICS_SECRET_WEB arrives as GOOGLE_ANALYTICS_SECRET.
+require('./vendor/config/index.js').loadEnv(process.cwd(), { target: 'web' });
+
+const { createCliRouter } = require('./vendor/devkit/cli-router.js');
+
+// Command name → positional/flag aliases (UJM alias table, adapted)
+const ALIASES = {
+  install: ['-i', 'i', '--install'],
+  dev: ['serve', 'start', '--dev'],
+  build: ['-b', '--build'],
+  deploy: ['-d', '--deploy'],
+  update: ['-u', '--update', 'outdated', 'out'],
+  migrate: ['-m', '--migrate', 'migration'],
+  customize: ['-cz', '--customize'],
+  translate: ['--translate', 'translation'],
+  audit: ['-a', '--audit'],
+  purge: ['-cf', '--purge', 'cloudflare-purge'],
+  // -t = test on EVERY framework (mirrored-implementation rule) — translate
+  // deliberately has no single-letter alias so the muscle-memory flag is safe
+  test: ['-t', '--test'],
+  clean: ['-c', '--clean'],
+  version: ['-v', '--version'],
+};
+
+const Main = createCliRouter({
+  commandsDir: path.join(__dirname, 'commands'),
+  aliases: ALIASES,
+  defaultCommand: 'help',
+});
+
+// The environment surface (#717) — web's Manager equivalent is this CLI class,
+// the object every bin instantiates, so `Main.getEnvironment()` /
+// `isDevelopment()` / `isProduction()` / `isTesting()` are reachable the same
+// way @omega.js/desktop's and @omega.js/extension's Managers reach theirs.
+require('./mode-helpers.js').attachTo(Main);
+
+module.exports = Main;