@omega.js/web 0.1.0

package/dist/target-shortlinks.js

@@ -0,0 +1,123 @@
+/**
+ * Download and extension shortlink pages (#561) — the download/extension half
+ * of the shortlink lane #429 opened for socials.
+ *
+ * Legacy UJM shipped these as hand-maintained default pages
+ * (`src/defaults/dist/redirects/download/**`, `.../extension/*.html`):
+ * `/download/mac`, `/download/mac/universal`, `/download/linux/snap`,
+ * `/extension/chrome`, … Each is linked from a store page, a third-party
+ * listing or an old post, and every migrating brand 404s the lot of them.
+ *
+ * A brand never hand-authors these (FILE-AND-SKIP ruling), and since
+ * [#610](https://github.com/Omega-JS-Stack/omega/issues/610) there is exactly
+ * ONE declaration to read: the curated `site.targets` view — the same facts
+ * `/download` and `/extension` render from.
+ *
+ *   site.targets.desktop.downloads[platform][artifact] → every desktop shortlink
+ *   site.targets.extension.listings[store]             → /extension/<store>
+ *
+ * A download shortlink hands over the FILE, never the releases page
+ * ([#620](https://github.com/Omega-JS-Stack/omega/issues/620)): the curated
+ * view's per-artifact URLs are versionless, so a desktop release never touches
+ * the website and these links never change.
+ *
+ * Legacy parity that matters: `/download/<platform>` with no artifact points at
+ * the platform's FIRST artifact — UJM's own pages sent /download/mac to
+ * mac.universal and /download/linux to linux.debian.
+ */
+const { redirectPage } = require('./redirect-page.js');
+
+// A store key is a URL segment (a brand authors these under
+// targets.extension.listings).
+const KEY_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/** How a bad key prints in an error — readable when it is legal, quoted when not. */
+const at = (key) => (KEY_PATTERN.test(key) ? key : JSON.stringify(key));
+
+/**
+ * The desktop shortlinks: one per platform (its first artifact) and one per
+ * artifact, each pointing straight at that artifact's file. The platform and
+ * artifact keys — and their order — are the curated view's own, which is
+ * @omega.js/config's artifact catalog. A desktop target that did not opt into
+ * releases (#124) carries no `downloads` and declares nothing.
+ * @param {object} [desktop] - the curated site.targets.desktop view
+ * @returns {Array<{ label: string, url: string, redirect: string }>}
+ */
+function readDownloads(desktop) {
+  const downloads = desktop && desktop.downloads;
+  if (!downloads) return [];
+
+  const entries = [];
+
+  for (const [platform, artifacts] of Object.entries(downloads)) {
+    const urls = Object.entries(artifacts || {});
+    if (!urls.length) continue;
+
+    // The bare platform URL leads with the first artifact (legacy parity).
+    entries.push({ label: `download.${platform}`, url: `/download/${platform}`, redirect: urls[0][1] });
+    for (const [artifact, url] of urls) {
+      entries.push({ label: `download.${platform}.${artifact}`, url: `/download/${platform}/${artifact}`, redirect: url });
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * The extension shortlinks: one per store listing that has a URL. A listing
+ * with only a `state` (announced, not shipped) declares no page, exactly the
+ * way the /extension page already leaves it on Coming soon. A malformed key is
+ * an ERROR — a shortlink that silently fails to generate is a dead link on a
+ * third-party listing nobody controls.
+ * @param {object} [extension] - the curated site.targets.extension view
+ * @returns {Array<{ label: string, url: string, redirect: string }>}
+ * @throws {Error} on an unusable store key
+ */
+function readListings(extension) {
+  const listings = extension && extension.listings;
+  if (!listings) return [];
+
+  const entries = [];
+
+  for (const [store, entry] of Object.entries(listings)) {
+    const url = entry && entry.url;
+    if (!url) continue; // a store the brand has not shipped to
+
+    if (!KEY_PATTERN.test(store)) {
+      throw new Error(
+        `targets.extension.listings.${at(store)} is not a usable store key — a key is lowercase, starts with a letter, and names the shortlink URL (/extension/${store})`,
+      );
+    }
+
+    entries.push({ label: `extension.${store}`, url: `/extension/${store}`, redirect: url });
+  }
+
+  return entries;
+}
+
+/**
+ * Every shortlink the curated targets view declares.
+ * @param {object} [site] - the site global (reads site.targets)
+ * @returns {Array<{ label: string, url: string, redirect: string }>}
+ */
+function readTargetShortlinks(site) {
+  const targets = site && site.targets;
+  return [...readDownloads(targets && targets.desktop), ...readListings(targets && targets.extension)];
+}
+
+/**
+ * The generated page of each shortlink.
+ * @param {Array<object>} entries - readTargetShortlinks output
+ * @returns {Array<{ virtual: string, label: string, url: string, raw: string }>}
+ */
+function targetShortlinkPages(entries) {
+  return entries.map((entry) => redirectPage({
+    virtual: `omega-target-shortlinks${entry.url}.html`,
+    label: entry.label,
+    url: entry.url,
+    redirect: entry.redirect,
+    note: `Shortlink generated by @omega.js/web from ${entry.label} (#561).`,
+  }));
+}
+
+module.exports = { readTargetShortlinks, targetShortlinkPages };

package/dist/theme-vocabulary.js

@@ -0,0 +1,76 @@
+/**
+ * The CSS fall-through guard (#98) — a build-time WARNING when a non-classy
+ * theme skips the two blessed lanes of docs/shared/theming.md § "CSS
+ * fall-through".
+ *
+ * Framework pages a theme doesn't cover (auth, account, legal) render the
+ * shared `omega-*` vocabulary. A theme reaches it either through the
+ * inheritance hatch (`@forward 'omega:theme';` — partial themes) or by
+ * importing classy's token-pure floor partials (full sibling themes with
+ * their own Bootstrap). A theme that does neither still builds — and those
+ * pages render unstyled with zero signal. This check reads the COMPILED main
+ * bundle, so it sees what is true rather than guessing from source.
+ */
+
+// Libraries
+const path = require('node:path');
+const Logger = require('./vendor/devkit/logger.js');
+
+// Variables
+const logger = new Logger('theme-vocabulary');
+
+// The sentinels: one selector per fall-through surface, each guaranteed by
+// BOTH lanes (the hatch emits classy's whole chain; the ratified floor set
+// names these exact partials). A theme that deliberately RE-styles the
+// vocabulary defines the same selectors itself and passes — the check asks
+// only "is the shared vocabulary painted at all".
+const SENTINELS = [
+  { selector: '.omega-auth', partial: 'pages/auth', surface: 'auth pages (sign-in, sign-up, reset)' },
+  { selector: '.omega-statgrid', partial: 'app/panels', surface: 'account/app panels' },
+  { selector: '.omega-footer', partial: 'layout/footer', surface: 'the shared site footer' },
+];
+
+// A theme that DEFINES Bootstrap's body-bg custom property ships its own
+// Bootstrap (bootstrap/scss/_root.scss, or classy's bridge when the chain
+// emitted) — so its lane is the floor, never the whole-chain hatch (two
+// Bootstraps). Core css only ever READS --bs-* properties, never defines
+// this one.
+const OWN_BOOTSTRAP = '--bs-body-bg:';
+
+/**
+ * Warn once when the active theme paints none of the fall-through vocabulary.
+ * @param {object} options
+ * @param {string} options.css - the compiled MAIN css bundle
+ * @param {string[]} options.themeRoots - resolveThemeLayers output (active theme first,
+ *   base last); a single root means base itself is active and the check is moot
+ * @param {function} [options.warn] - warning sink (default the devkit logger)
+ * @returns {{ theme: string, lane: 'hatch'|'floor', missing: string[] }|null} null when silent
+ */
+function checkThemeVocabulary(options) {
+  const { css, themeRoots } = options;
+  if (!css || !themeRoots || themeRoots.length < 2) return null;
+
+  const missing = SENTINELS.filter((sentinel) => !css.includes(sentinel.selector));
+  if (missing.length === 0) return null;
+
+  const theme = path.basename(themeRoots[0]);
+  const lane = css.includes(OWN_BOOTSTRAP) ? 'floor' : 'hatch';
+  const fix = lane === 'hatch'
+    ? `add \`@forward 'omega:theme';\` as the FIRST line of themes/${theme}/_theme.scss`
+    : `import classy's token-pure floor EARLY in themes/${theme}/_theme.scss: ${missing.map((sentinel) => `@import '../classy/css/${sentinel.partial}';`).join(' ')}`;
+
+  const warn = options.warn || logger.warn.bind(logger);
+  warn(
+    `theme "${theme}" skips the CSS fall-through contract — framework pages (auth, account, legal) `
+    + `will render UNSTYLED omega-* markup.\n`
+    + `  missing from the compiled bundle: `
+    + `${missing.map((sentinel) => `${sentinel.selector} (${sentinel.partial} → ${sentinel.surface})`).join(', ')}\n`
+    + `  the missing piece: the ${lane === 'hatch' ? 'inheritance hatch (this theme ships no Bootstrap of its own)' : 'vocabulary floor (this theme ships its own Bootstrap)'}\n`
+    + `  the fix: ${fix}\n`
+    + `  contract: docs/shared/theming.md § "CSS fall-through — the two lanes"`,
+  );
+
+  return { theme, lane, missing: missing.map((sentinel) => sentinel.selector) };
+}
+
+module.exports = { checkThemeVocabulary };

package/dist/translate/collect-text-nodes.js

@@ -0,0 +1,93 @@
+/**
+ * Collect every translatable text unit from a built HTML page (cheerio DOM):
+ * element text nodes, <title>, translatable meta contents, and translatable
+ * attributes. The walk order is deterministic, so collecting again on a fresh
+ * DOM yields positionally-aligned nodes for applying translations.
+ *
+ * Ported from UJM's collectTextNodes with two fixes: aria-describedby /
+ * aria-labelledby are no longer collected (they are ID references —
+ * translating them breaks the link), and `value` is only collected on
+ * button-like inputs (translating hidden/token input values corrupted forms).
+ * Opt-out: any element inside [data-omega-no-translate] is skipped.
+ */
+
+// Meta tags whose content is human-visible copy
+const META_KEYS = ['description', 'og:title', 'og:description', 'twitter:title', 'twitter:description'];
+
+// Attributes carrying human-visible copy on any element
+const TEXT_ATTRIBUTES = ['title', 'placeholder', 'alt', 'aria-label', 'aria-placeholder', 'label'];
+
+// input types whose `value` is a visible label
+const BUTTON_INPUT_TYPES = ['button', 'submit', 'reset'];
+
+/**
+ * Walk the DOM and collect translatable units.
+ * @param {object} $ - cheerio root
+ * @returns {Array<{ node: object, type: 'text'|'attr'|'data', attr: string|null, reference?: object, text: string }>}
+ */
+function collectTextNodes($) {
+  const textNodes = [];
+
+  $('*').each((_, el) => {
+    const node = $(el);
+
+    if (node.is('script') || node.is('style') || node.is('noscript')) {
+      return;
+    }
+
+    if (node.closest('[data-omega-no-translate]').length) {
+      return;
+    }
+
+    // <title>
+    if (node.is('title')) {
+      const text = node.text().trim();
+      if (text) {
+        textNodes.push({ node, type: 'text', attr: null, text });
+      }
+      return;
+    }
+
+    // Translatable meta content
+    if (node.is('meta')) {
+      const key = node.attr('name') || node.attr('property');
+      if (META_KEYS.includes(key)) {
+        const text = node.attr('content')?.trim();
+        if (text) {
+          textNodes.push({ node, type: 'attr', attr: 'content', text });
+        }
+      }
+      return;
+    }
+
+    // Translatable attributes
+    const attributes = [...TEXT_ATTRIBUTES];
+    if (node.is('input') && BUTTON_INPUT_TYPES.includes(node.attr('type'))) {
+      attributes.push('value');
+    }
+
+    attributes.forEach((attr) => {
+      const text = node.attr(attr)?.trim();
+      if (text) {
+        textNodes.push({ node, type: 'attr', attr, text });
+      }
+    });
+
+    // Regular DOM text nodes (direct children only — descendants get their own visit)
+    node.contents().each((_, child) => {
+      if (child.type === 'text' && child.data?.trim()) {
+        const text = child.data
+          // Preserve a single leading/trailing whitespace, normalize the rest
+          .replace(/^\s*(\s)\s*/, '$1')
+          .replace(/\s*(\s)\s*$/, '$1')
+          .replace(/\s+/g, ' ');
+
+        textNodes.push({ node, type: 'data', attr: null, reference: child, text });
+      }
+    });
+  });
+
+  return textNodes;
+}
+
+module.exports = { collectTextNodes };

package/dist/translate/default-routes.js

@@ -0,0 +1,152 @@
+/**
+ * The routes the framework never translates (#605) — DERIVED from the packaged
+ * defaults tree rather than typed out. Every default page declares the layout
+ * that renders it, and a layout says which side of the line the page is on:
+ * the auth flows, the user app, the account/payment/portal screens, the legal
+ * boilerplate, and the redirect stubs are plumbing, and no brand should have to
+ * name any of them in `translation.exclude` — that key is for the brand's OWN
+ * pages. Deriving means a default page that moves, arrives, or is renamed can
+ * never drift out of the list.
+ */
+const path = require('node:path');
+const jetpack = require('fs-jetpack');
+const yaml = require('js-yaml');
+const { PATHS } = require('../paths.js');
+
+// The legal boilerplate's family, named because TWO derivations read it: the
+// never-translated set below, and legalRoutes() — the generator harvests those
+// routes from nowhere, so the framework packages no copy for them.
+const LEGAL_LAYOUT = 'blueprint/legal';
+
+// Layouts whose pages carry no marketing copy — matched exactly or as a family
+// prefix (`blueprint/auth` covers `blueprint/auth/signin`).
+const NEVER_TRANSLATED_LAYOUTS = [
+  'modules/utilities/redirect', // a redirect stub renders no prose at all
+  'blueprint/404',
+  'blueprint/app', // the user app shell
+  'blueprint/account',
+  'blueprint/auth',
+  'blueprint/connections', // the provider redirect lands here — a spinner, not copy
+  LEGAL_LAYOUT, // terms/privacy/cookies — legally binding in ONE language
+  'blueprint/payment',
+  'blueprint/portal',
+];
+
+// Derivation is per defaults tree and the tree ships with the package, so the
+// scan happens once per process.
+const derived = new Map();
+
+/**
+ * Read a default page's frontmatter (the two keys this derivation needs).
+ * @param {string} file - absolute path to a default page
+ * @returns {object} the parsed frontmatter ({} when there is none)
+ */
+function readFrontmatter(file) {
+  const match = (jetpack.read(file) || '').match(/^?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) {
+    return {};
+  }
+
+  try {
+    return yaml.load(match[1]) || {};
+  } catch {
+    // Unparseable frontmatter is the engine's error to raise, not ours.
+    return {};
+  }
+}
+
+/**
+ * The route a permalink lands on, in the shape routeOf() produces from a built
+ * file ('/signin' → 'signin', '/404.html' → '404').
+ * @param {*} permalink - the frontmatter value
+ * @returns {string|null} null when the permalink is templated, non-HTML, or absent
+ */
+function routeFromPermalink(permalink) {
+  if (typeof permalink !== 'string' || /[{}]/.test(permalink)) {
+    return null;
+  }
+
+  const withoutExt = permalink.trim().replace(/\.html$/i, '');
+
+  // A meta file (robots.txt, feeds/posts.xml) is not a page.
+  if (/\.[a-z0-9]+$/i.test(withoutExt)) {
+    return null;
+  }
+
+  return withoutExt.replace(/^\/+|\/+$/g, '');
+}
+
+/**
+ * Whether a layout belongs to a family — exactly, or as its prefix.
+ * @param {*} layout - the frontmatter value
+ * @param {string} family - a layout family
+ * @returns {boolean}
+ */
+function inFamily(layout, family) {
+  return typeof layout === 'string' && (layout === family || layout.startsWith(`${family}/`));
+}
+
+/**
+ * Whether a layout renders framework plumbing rather than brand copy.
+ * @param {*} layout - the frontmatter value
+ * @returns {boolean}
+ */
+function isPlumbing(layout) {
+  return NEVER_TRANSLATED_LAYOUTS.some((family) => inFamily(layout, family));
+}
+
+/**
+ * Scan a defaults tree once — every never-translated route, and the legal
+ * subset of them.
+ * @param {string} [defaultsDir] - the packaged defaults dir (tests override it)
+ * @returns {{ excluded: Set<string>, legal: Set<string> }} routes, in routeOf()
+ *   shape (no leading slash)
+ */
+function scanDefaults(defaultsDir) {
+  const dir = path.resolve(defaultsDir || PATHS.defaults);
+
+  if (!derived.has(dir)) {
+    const excluded = new Set();
+    const legal = new Set();
+
+    for (const file of jetpack.find(path.join(dir, 'pages'), { matching: ['*.md', '*.html'] })) {
+      const { layout, permalink } = readFrontmatter(file);
+      const route = isPlumbing(layout) ? routeFromPermalink(permalink) : null;
+
+      // The home route ('') would swallow the whole site as a folder prefix —
+      // it is also never a plumbing page, so reaching it means a broken tree.
+      if (route) {
+        excluded.add(route);
+
+        if (inFamily(layout, LEGAL_LAYOUT)) {
+          legal.add(route);
+        }
+      }
+    }
+
+    derived.set(dir, { excluded, legal });
+  }
+
+  return derived.get(dir);
+}
+
+/**
+ * The framework's never-translated routes, read off the defaults tree.
+ * @param {string} [defaultsDir] - the packaged defaults dir (tests override it)
+ * @returns {Set<string>} routes, in routeOf() shape (no leading slash)
+ */
+function defaultExcludedRoutes(defaultsDir) {
+  return scanDefaults(defaultsDir).excluded;
+}
+
+/**
+ * The framework's legal routes — the never-translated pages the generator also
+ * harvests nothing for, so no packaged copy of them exists (#621).
+ * @param {string} [defaultsDir] - the packaged defaults dir (tests override it)
+ * @returns {Set<string>} routes, in routeOf() shape (no leading slash)
+ */
+function legalRoutes(defaultsDir) {
+  return scanDefaults(defaultsDir).legal;
+}
+
+module.exports = { defaultExcludedRoutes, legalRoutes };