@omega.js/web 0.1.0

package/core/js/libs/recaptcha.js

@@ -0,0 +1,94 @@
+// Shared reCAPTCHA v3 management — lazy script load + token mint for any
+// public form that posts to a recaptcha-gated backend route (checkout
+// payment intent, newsletter capture). Site key: omega.config.captcha.providers.recaptcha.siteKey.
+import omega from '@omega.js/client';
+import { createLogger } from '__main_assets__/js/libs/logger.js';
+
+const logger = createLogger('recaptcha');
+
+let recaptchaReady = false;
+let recaptchaSiteKey = null;
+
+// Initialize reCAPTCHA
+export async function initializeRecaptcha(siteKey) {
+  if (!siteKey) {
+    console.warn('No reCAPTCHA site key provided');
+    return false;
+  }
+
+  recaptchaSiteKey = siteKey;
+
+  // Check if already loaded
+  if (window.grecaptcha) {
+    recaptchaReady = true;
+    return true;
+  }
+
+  try {
+    // Use omega.dom().loadScript()
+    const scriptUrl = `https://www.google.com/recaptcha/api.js?render=${siteKey}`;
+
+    await omega.dom().loadScript({
+      src: scriptUrl,
+      async: true,
+      defer: true,
+      timeout: 30000, // 30 second timeout
+      retries: 2 // Retry twice on failure
+    });
+
+    // Wait for grecaptcha to be ready
+    await new Promise((resolve) => {
+      if (window.grecaptcha && window.grecaptcha.ready) {
+        window.grecaptcha.ready(() => {
+          recaptchaReady = true;
+          console.log('🔐 reCAPTCHA initialized successfully');
+          resolve();
+        });
+      } else {
+        // Fallback timeout if grecaptcha.ready is not available
+        console.warn('grecaptcha.ready not available, using timeout fallback');
+        setTimeout(() => {
+          recaptchaReady = true;
+          resolve();
+        }, 1000);
+      }
+    });
+
+    return true;
+  } catch (error) {
+    console.error('Failed to load reCAPTCHA:', error);
+    return false;
+  }
+}
+
+// Get reCAPTCHA token
+export async function getRecaptchaToken(action = 'submit') {
+  /* @dev-only:start */
+  {
+    const devRecaptcha = new URLSearchParams(window.location.search).get('_dev_recaptcha');
+    if (devRecaptcha === 'invalid') {
+      logger.warn('Sending invalid reCAPTCHA token');
+      return 'invalid-dev-token';
+    }
+    if (devRecaptcha === 'empty') {
+      logger.warn('Sending empty reCAPTCHA token');
+      return '';
+    }
+  }
+  /* @dev-only:end */
+
+  if (!recaptchaReady || !recaptchaSiteKey) {
+    console.warn('reCAPTCHA not initialized');
+    return null;
+  }
+
+  try {
+    console.log('🔐 Getting reCAPTCHA token for action:', action);
+    const token = await grecaptcha.execute(recaptchaSiteKey, { action });
+    console.log('🔐 reCAPTCHA token obtained successfully');
+    return token;
+  } catch (error) {
+    console.error('Failed to get reCAPTCHA token:', error);
+    return null;
+  }
+}

package/core/js/libs/sale-name.js

@@ -0,0 +1,295 @@
+/**
+ * Sale Name Helper
+ * Determines the best sale/promotion name based on the current date
+ *
+ * Holiday precedence rules:
+ * - Each holiday has a "core" date (the actual holiday)
+ * - Promo window extends 1 week before and 3 days after the core date
+ * - A new holiday only takes precedence AFTER the previous holiday's core date has passed
+ * - Example: Black Friday promo runs until Black Friday ends, then Cyber Monday takes over
+ */
+
+// Configuration
+const DAYS_BEFORE = 7;
+const DAYS_AFTER = 3;
+
+/**
+ * Holiday definitions
+ * Each holiday defines how to calculate its core date for a given year
+ */
+const HOLIDAYS = [
+  {
+    name: 'Black Friday',
+    getCoreDate: (year) => {
+      // 4th Thursday of November + 1 day (Friday)
+      const thanksgiving = getNthWeekdayOfMonth(year, 10, 4, 4);
+      const blackFriday = new Date(thanksgiving);
+      blackFriday.setDate(blackFriday.getDate() + 1);
+      return blackFriday;
+    }
+  },
+  {
+    name: 'Cyber Monday',
+    getCoreDate: (year) => {
+      // Monday after Thanksgiving (4 days after Thursday)
+      const thanksgiving = getNthWeekdayOfMonth(year, 10, 4, 4);
+      const cyberMonday = new Date(thanksgiving);
+      cyberMonday.setDate(cyberMonday.getDate() + 4);
+      return cyberMonday;
+    }
+  },
+  {
+    name: 'Christmas',
+    getCoreDate: (year) => new Date(year, 11, 25)
+  },
+  {
+    name: 'Easter',
+    getCoreDate: (year) => calculateEaster(year)
+  }
+];
+
+// Season definitions
+const SEASONS = [
+  { name: 'Winter', months: [11, 0, 1], endMonth: 1, endDay: 28 },
+  { name: 'Spring', months: [2, 3, 4], endMonth: 4, endDay: 31 },
+  { name: 'Summer', months: [5, 6, 7], endMonth: 7, endDay: 31 },
+  { name: 'Fall', months: [8, 9, 10], endMonth: 10, endDay: 30 }
+];
+
+/**
+ * Get the nth occurrence of a weekday in a month
+ * @param {number} year - Year
+ * @param {number} month - Month (0-indexed)
+ * @param {number} n - Which occurrence (1-5)
+ * @param {number} weekday - Day of week (0=Sunday, 4=Thursday)
+ * @returns {Date}
+ */
+function getNthWeekdayOfMonth(year, month, n, weekday) {
+  const firstDay = new Date(year, month, 1);
+  const firstWeekday = firstDay.getDay();
+  let dayOffset = weekday - firstWeekday;
+
+  if (dayOffset < 0) {
+    dayOffset += 7;
+  }
+
+  const nthDay = 1 + dayOffset + (n - 1) * 7;
+  return new Date(year, month, nthDay);
+}
+
+/**
+ * Calculate Easter Sunday for a given year (Anonymous Gregorian algorithm)
+ * @param {number} year
+ * @returns {Date}
+ */
+function calculateEaster(year) {
+  const a = year % 19;
+  const b = Math.floor(year / 100);
+  const c = year % 100;
+  const d = Math.floor(b / 4);
+  const e = b % 4;
+  const f = Math.floor((b + 8) / 25);
+  const g = Math.floor((b - f + 1) / 3);
+  const h = (19 * a + b - d - g + 15) % 30;
+  const i = Math.floor(c / 4);
+  const k = c % 4;
+  const l = (32 + 2 * e + 2 * i - h - k) % 7;
+  const m = Math.floor((a + 11 * h + 22 * l) / 451);
+  const month = Math.floor((h + l - 7 * m + 114) / 31) - 1;
+  const day = ((h + l - 7 * m + 114) % 31) + 1;
+
+  return new Date(year, month, day);
+}
+
+/**
+ * Get the promo window for a holiday
+ * @param {Date} coreDate - The actual holiday date
+ * @returns {object} Object with promoStart, coreDate, and promoEnd
+ */
+function getHolidayWindow(coreDate) {
+  const promoStart = new Date(coreDate);
+  promoStart.setDate(promoStart.getDate() - DAYS_BEFORE);
+  promoStart.setHours(0, 0, 0, 0);
+
+  const promoEnd = new Date(coreDate);
+  promoEnd.setDate(promoEnd.getDate() + DAYS_AFTER);
+  promoEnd.setHours(23, 59, 59, 999);
+
+  // Core date end of day
+  const coreDateEnd = new Date(coreDate);
+  coreDateEnd.setHours(23, 59, 59, 999);
+
+  return {
+    promoStart,
+    coreDate: new Date(coreDate),
+    coreDateEnd,
+    promoEnd
+  };
+}
+
+/**
+ * Get all holidays with their windows for the relevant years
+ * @param {Date} date
+ * @returns {Array} Sorted array of holiday objects with windows
+ */
+function getHolidaysWithWindows(date) {
+  const year = date.getFullYear();
+  const yearsToCheck = [year - 1, year, year + 1];
+  const holidays = [];
+
+  for (const checkYear of yearsToCheck) {
+    for (const holiday of HOLIDAYS) {
+      const coreDate = holiday.getCoreDate(checkYear);
+      const window = getHolidayWindow(coreDate);
+
+      holidays.push({
+        name: holiday.name,
+        ...window
+      });
+    }
+  }
+
+  // Sort by core date
+  return holidays.sort((a, b) => a.coreDate - b.coreDate);
+}
+
+/**
+ * Get the current season based on date
+ * @param {Date} date
+ * @returns {object|null} Season object with name, progress, and isEndOfSeason
+ */
+function getCurrentSeason(date) {
+  const month = date.getMonth();
+  const season = SEASONS.find(s => s.months.includes(month));
+
+  if (!season) {
+    return null;
+  }
+
+  const year = date.getFullYear();
+
+  // Handle winter spanning year boundary
+  let startYear = year;
+  if (season.name === 'Winter' && month <= 1) {
+    startYear = year - 1;
+  }
+
+  const seasonStartDate = new Date(startYear, season.months[0], 1);
+
+  // For winter end date, use next year if starting month is December
+  let endYear = year;
+  if (season.name === 'Winter' && season.months[0] === 11) {
+    endYear = year + 1;
+  }
+
+  const seasonEndDate = new Date(endYear, season.endMonth, season.endDay, 23, 59, 59);
+  const seasonDuration = seasonEndDate - seasonStartDate;
+  const progress = (date - seasonStartDate) / seasonDuration;
+  const isEndOfSeason = progress >= 0.7;
+
+  return {
+    name: season.name,
+    progress,
+    isEndOfSeason,
+    startDate: seasonStartDate,
+    endDate: seasonEndDate
+  };
+}
+
+/**
+ * Get the best sale name for a given date
+ *
+ * Logic:
+ * 1. Find all holidays where we're in their promo window (1 week before to 3 days after)
+ * 2. If multiple holidays overlap, the one whose core date has NOT yet passed takes precedence
+ * 3. Once a holiday's core date passes, the next holiday can take over
+ *
+ * @param {Date} [date=new Date()] - Date to check (defaults to now)
+ * @returns {object} Object with saleName, endDate, and type
+ */
+export function getSaleName(date = new Date()) {
+  const holidays = getHolidaysWithWindows(date);
+
+  // Find all holidays where we're in their promo window
+  const activeHolidays = holidays.filter(h =>
+    date >= h.promoStart && date <= h.promoEnd
+  );
+
+  if (activeHolidays.length > 0) {
+    // Find the best holiday to show
+    // Priority: The holiday whose core date hasn't passed yet, or if all have passed, the most recent one
+    let bestHoliday = null;
+
+    // First, try to find a holiday whose core date hasn't passed
+    for (const holiday of activeHolidays) {
+      if (date <= holiday.coreDateEnd) {
+        bestHoliday = holiday;
+        break;
+      }
+    }
+
+    // If all core dates have passed, use the one with the latest core date
+    // (we're in the "3 days after" window of the most recent holiday)
+    if (!bestHoliday) {
+      bestHoliday = activeHolidays[activeHolidays.length - 1];
+    }
+
+    return {
+      saleName: `${bestHoliday.name} Sale`,
+      endDate: bestHoliday.promoEnd,
+      coreDate: bestHoliday.coreDate,
+      type: 'holiday'
+    };
+  }
+
+  // Fall back to season
+  const season = getCurrentSeason(date);
+
+  if (!season) {
+    return {
+      saleName: 'Sale',
+      endDate: null,
+      type: 'generic'
+    };
+  }
+
+  const saleName = season.isEndOfSeason
+    ? `End of ${season.name} Sale`
+    : `${season.name} Sale`;
+
+  return {
+    saleName,
+    endDate: season.endDate,
+    type: 'season'
+  };
+}
+
+/**
+ * Get all upcoming sales/holidays within a date range
+ * @param {Date} startDate
+ * @param {Date} endDate
+ * @returns {Array} Array of sale objects sorted by start date
+ */
+export function getUpcomingSales(startDate = new Date(), endDate = null) {
+  if (!endDate) {
+    endDate = new Date(startDate);
+    endDate.setFullYear(endDate.getFullYear() + 1);
+  }
+
+  const holidays = getHolidaysWithWindows(startDate);
+
+  return holidays
+    .filter(h => h.promoStart >= startDate && h.promoStart <= endDate)
+    .map(h => ({
+      saleName: `${h.name} Sale`,
+      startDate: h.promoStart,
+      coreDate: h.coreDate,
+      endDate: h.promoEnd,
+      type: 'holiday'
+    }));
+}
+
+export default {
+  getSaleName,
+  getUpcomingSales
+};

package/core/js/libs/showcase-frames.js

@@ -0,0 +1,37 @@
+/**
+ * Autosize the gallery's embedded variant frames (#463).
+ *
+ * The ONE home: the section gallery's entry pages and the component gallery
+ * (#549) embed the same frame documents, so they measure them the same way.
+ * The frames are same-origin, which is what makes this possible at all — each
+ * one's own document reports its height. Measure on load and on resize; a
+ * cross-origin src (never ours) throws on contentDocument, and the markup's
+ * inline min-height is the fallback, so an unmeasured frame scrolls instead of
+ * collapsing.
+ *
+ * @param {ParentNode} [$root] - the subtree to scan
+ * @returns {void}
+ */
+export default function autosizeShowcaseFrames($root = document) {
+  const $frames = [...$root.querySelectorAll('[data-omega-showcase-frame]')];
+
+  const fit = ($frame) => {
+    try {
+      const height = $frame.contentDocument.documentElement.scrollHeight;
+      if (height) $frame.style.height = `${height}px`;
+    } catch {
+      // opaque document — leave the fallback height alone
+    }
+  };
+
+  $frames.forEach(($frame) => {
+    $frame.addEventListener('load', () => fit($frame));
+    // Lazy frames that already loaded (bfcache, cached navigation) fire no
+    // load event — measure once now too.
+    fit($frame);
+  });
+
+  // Re-measure on resize: the frames are full-width, so a narrower viewport
+  // reflows their content taller.
+  window.addEventListener('resize', () => $frames.forEach(fit));
+}

package/core/js/libs/srcset.js

@@ -0,0 +1,69 @@
+/**
+ * The srcset candidate parser for the BROWSER (#367) — the ESM twin of the
+ * build-time `packages/web/src/srcset.js`. Same grammar, same output shape; two
+ * files because the two lanes cannot share one: the build passes are CJS node
+ * modules, and this one is bundled into the page's ESM bundle.
+ *
+ * ⚠️ FORMAT TWIN — keep in step with `packages/web/src/srcset.js`. A change to
+ * how a candidate is parsed belongs in BOTH files, or the runtime lazy-loader
+ * and the two build passes stop agreeing about what a candidate is.
+ *
+ * Why it exists: #362 fixed `value.split(',')` in the two HTML passes, and the
+ * runtime lazy-loader (`core/js/core/lazy-loading.js`) kept it — and it is the
+ * lane the build passes DEFER `data-srcset` to, so a candidate URL carrying a
+ * legal comma (a `data:` payload, a `?w=100,200` query) was still cut in half
+ * in the browser.
+ *
+ * Candidates are parsed the way the HTML srcset grammar actually works: the URL
+ * is a run of NON-WHITESPACE characters (commas inside it belong to the URL),
+ * the boundary is the comma that ends a candidate — either trailing the URL
+ * itself (descriptor-less form) or after the descriptor list.
+ */
+
+/**
+ * Rewrite every candidate URL in a srcset value, keeping the descriptors and
+ * the `, ` separator.
+ * @param {string} value - srcset attribute value
+ * @param {Function} mapUrl - (url: string) → string, the caller's URL rewrite
+ * @returns {string}
+ */
+export function mapSrcset(value, mapUrl) {
+  const input = String(value);
+  const candidates = [];
+  let i = 0;
+
+  while (i < input.length) {
+    // Leading whitespace and the empty candidates a stray comma leaves behind
+    while (i < input.length && /[\s,]/.test(input[i])) i++;
+    if (i >= input.length) break;
+
+    const urlStart = i;
+    while (i < input.length && !/\s/.test(input[i])) i++;
+    const url = input.slice(urlStart, i);
+
+    // A URL ending in commas IS the boundary (the descriptor-less form) —
+    // strip them and the candidate is done; otherwise the descriptors run to
+    // the next comma outside a parenthesized group.
+    if (url.endsWith(',')) {
+      candidates.push({ url: url.replace(/,+$/, ''), descriptor: '' });
+      continue;
+    }
+
+    const descriptorStart = i;
+    let depth = 0;
+    while (i < input.length) {
+      const char = input[i];
+      if (char === '(') depth++;
+      else if (char === ')') depth = Math.max(0, depth - 1);
+      else if (char === ',' && depth === 0) break;
+      i++;
+    }
+
+    candidates.push({ url, descriptor: input.slice(descriptorStart, i).trim() });
+    i++; // the boundary comma
+  }
+
+  return candidates
+    .map(({ url, descriptor }) => [mapUrl(url), ...(descriptor ? [descriptor] : [])].join(' '))
+    .join(', ');
+}

package/core/js/libs/tracking-consent.js

@@ -0,0 +1,161 @@
+/**
+ * The TRACKING consent record — one home for "what may this page load, and
+ * count?" ([#383](https://github.com/Omega-JS-Stack/omega/issues/383)).
+ *
+ * Shape, under `trackingConsent` in `omega.storage()`:
+ *
+ *   { analytics: bool, marketing: bool, region: 'opt-in'|'opt-out',
+ *     timestamp: ISO string, version: 1 }
+ *
+ * The key is `trackingConsent`, not `consent`, and every export says TRACKING
+ * out loud, because storage already has a `consent`: the signup form's LEGAL
+ * consent (`libs/auth/forms.js` captureSignupConsent → `{ legal, marketing }`,
+ * which the backend signup route interprets). Two different questions with two
+ * different shapes — sharing one key would have read a tracking answer as a
+ * revoked terms agreement.
+ *
+ * Two categories, because that is what a visitor can meaningfully answer:
+ * `analytics` (GA4) and `marketing` (Meta, TikTok). Necessary is not a category
+ * here — nothing about it is optional, so there is nothing to store.
+ *
+ * A stored record of the CURRENT version wins on every load. Anything else — no
+ * record, or a record written under an older version — is no decision at all,
+ * and the region default applies until the visitor makes one:
+ *   - opt-out region: both categories granted, banner shown anyway (informational)
+ *   - opt-in region: nothing granted; the gates stay closed until Accept/Save
+ *
+ * Bumping TRACKING_CONSENT_VERSION re-prompts everyone, which is what a change
+ * to what the categories COVER requires. Renaming a provider inside a category
+ * does not.
+ *
+ * The read API is deliberately tiny because it has callers beyond the banner:
+ * the loader gates on it, and the checkout/signup payloads read it.
+ */
+import omega from '@omega.js/client';
+
+import { createLogger } from '__main_assets__/js/libs/logger.js';
+import { detectRegion } from '__main_assets__/js/libs/consent-region.js';
+
+const logger = createLogger('tracking-consent');
+
+// Storage path inside the client's `_manager` blob. NOT `consent` — that key is
+// the signup form's legal consent (see the header).
+export const TRACKING_CONSENT_KEY = 'trackingConsent';
+
+// Bump to re-prompt every visitor (see the header).
+export const TRACKING_CONSENT_VERSION = 1;
+
+// The optional categories, in banner order.
+export const TRACKING_CONSENT_CATEGORIES = ['analytics', 'marketing'];
+
+const listeners = new Set();
+
+/**
+ * The stored record, or null when there is no decision this version can honor.
+ * @returns {object|null}
+ */
+function readStored() {
+  const stored = omega.storage().get(TRACKING_CONSENT_KEY);
+
+  if (!stored || typeof stored !== 'object' || stored.version !== TRACKING_CONSENT_VERSION) {
+    return null;
+  }
+
+  return {
+    analytics: stored.analytics === true,
+    marketing: stored.marketing === true,
+    region: stored.region === 'opt-in' ? 'opt-in' : 'opt-out',
+    timestamp: stored.timestamp || null,
+    version: TRACKING_CONSENT_VERSION,
+  };
+}
+
+/**
+ * Has the visitor actually answered (under the current version)?
+ * @returns {boolean}
+ */
+export function hasTrackingDecision() {
+  return readStored() !== null;
+}
+
+/**
+ * The consent in effect right now: the stored decision, or the region default.
+ * @returns {{ analytics: boolean, marketing: boolean, region: string, timestamp: (string|null), version: number }}
+ */
+export function getTrackingConsent() {
+  const stored = readStored();
+
+  if (stored) {
+    return stored;
+  }
+
+  const region = detectRegion();
+  const granted = region === 'opt-out';
+
+  return {
+    analytics: granted,
+    marketing: granted,
+    region: region,
+    timestamp: null,
+    version: TRACKING_CONSENT_VERSION,
+  };
+}
+
+/**
+ * Record the visitor's answer and tell everyone who is listening.
+ * @param {object} choices
+ * @param {boolean} choices.analytics
+ * @param {boolean} choices.marketing
+ * @returns {object} the stored record
+ */
+export function setTrackingConsent(choices) {
+  const record = {
+    analytics: choices.analytics === true,
+    marketing: choices.marketing === true,
+    region: detectRegion(),
+    timestamp: new Date().toISOString(),
+    version: TRACKING_CONSENT_VERSION,
+  };
+
+  omega.storage().set(TRACKING_CONSENT_KEY, record);
+  notify(record);
+
+  return record;
+}
+
+/**
+ * Forget the decision — the visitor reopened the banner to answer again. The
+ * region default applies until they do.
+ * @returns {object} the consent now in effect
+ */
+export function clearTrackingDecision() {
+  omega.storage().remove(TRACKING_CONSENT_KEY);
+
+  const record = getTrackingConsent();
+  notify(record);
+
+  return record;
+}
+
+/**
+ * Subscribe to consent changes. Called with the record now in effect.
+ * @param {Function} listener
+ * @returns {Function} unsubscribe
+ */
+export function onTrackingConsentChange(listener) {
+  listeners.add(listener);
+
+  return () => listeners.delete(listener);
+}
+
+function notify(record) {
+  listeners.forEach((listener) => {
+    // One broken listener never costs the others their update — and never
+    // costs the visitor the choice they just made.
+    try {
+      listener(record);
+    } catch (e) {
+      logger.error('A consent listener threw:', e);
+    }
+  });
+}