@omega.js/web 0.1.0

package/dist/frontmatter-liquid.js

@@ -0,0 +1,253 @@
+/**
+ * Frontmatter-value Liquid rendering (cached) — the Eleventy home for
+ * jekyll-uj-powertools' variable_resolver behavior: corpus frontmatter carries
+ * `{{ site.* }}` refs in values ("… - {{ site.brand.name }}").
+ *
+ * Site-only values render against the CONSTANT site global and cache by raw
+ * source — across 1030 posts most frontmatter templates repeat. Every other
+ * value bypasses the cache: per-page values (`page.*`, `resolved.*`, and the
+ * page's own pagination alias — #544) render against the caller's per-page
+ * scope, and a value reaching for the consumer's `_data` globals (#542)
+ * renders against the SAME cascade a template render gets. Which lane a value
+ * takes is decided by its variable ROOTS, read with LiquidJS's own analyzer.
+ *
+ * The context-free omega_* filters are registered here too: LiquidJS drops an
+ * unknown filter SILENTLY (the value passes through un-filtered), so a
+ * frontmatter value reaching for one used to lose it with no signal — the
+ * taxonomy pages' `meta.title` needs omega_title_case (#294). Only the pure
+ * filter pack: the omega_* TAGS need the collection/icon wiring the render
+ * engine owns, and nothing may render a section at frontmatter time.
+ */
+const { Liquid } = require('liquidjs');
+const { FILTER_NAMES } = require('./vendor/template-kit/filters.js');
+
+// Engine-machinery keys the frontmatter walker must never enter: dynamic
+// permalinks belong to Eleventy, and the rest hold globals or other
+// templates' raw content (which may contain unregistered tags).
+// sectionLibrary is the showcase's data source — its demo args liquify at
+// the section tag's CALL SITE, never at frontmatter time (walking here would
+// bake the first page's rendering into the shared global).
+const DEFAULT_SKIP = new Set([
+  'permalink', 'pagination', 'collections', 'eleventy', 'pkg', 'page',
+  'content', 'site', 'assetManifest', 'eleventyComputed', 'resolved',
+  'sectionLibrary',
+]);
+
+// Per-page refs: `page.*` (the real sweet-saucy recipe meta) and `resolved.*`
+// (layout defaults templating on the merged cascade — cover's align knob,
+// the base alternative competitor values). These render UNCACHED against
+// the caller's per-page scope; the raw-string cache would serve the first
+// page's rendering to every page.
+const PER_PAGE_ROOTS = new Set(['page', 'resolved']);
+
+// The same test on the raw source, for the values LiquidJS cannot parse (a
+// frontmatter string reaching for an omega_* TAG this engine never registers):
+// no roots to classify, so the resolver falls back to what it always did.
+const PER_PAGE_RE = /\b(?:page|resolved)\./;
+
+/**
+ * Create a resolver bound to a site global.
+ * @param {object} options
+ * @param {object} options.site - the `site.*` global (constant per build)
+ * @returns {{ render(value: string): string, resolveData(data: object): void, renderData(data: object): object, cacheSize(): number }}
+ */
+function createFrontmatterResolver(options) {
+  const engine = new Liquid();
+  for (const [name, fn] of Object.entries(FILTER_NAMES)) engine.registerFilter(name, fn);
+  const scope = { site: options.site };
+  const cache = new Map();
+  const rootsCache = new Map();
+
+  /**
+   * Every top-level variable a value reads, via LiquidJS's own analyzer — a
+   * regex would have to model filters, string literals and for-loop locals.
+   * Memoized by raw source beside the render cache: most frontmatter repeats.
+   * @param {string} value
+   * @returns {string[]|null} the roots, or null when LiquidJS cannot parse it
+   */
+  function rootsOf(value) {
+    if (rootsCache.has(value)) return rootsCache.get(value);
+    let roots = null;
+    try {
+      roots = engine.globalVariablesSync(value);
+    } catch { /* unparseable here — the render below raises the real error */ }
+    rootsCache.set(value, roots);
+    return roots;
+  }
+
+  /**
+   * The cascade bindings a value's roots need, by NAME (`{{ brands.size }}`
+   * reads a bare `brands`, not `site.brands`) — #542. Only the roots the value
+   * actually reads are touched: the cascade holds foreign objects whose
+   * getters throw before render.
+   * @param {object} [globals] - the template's data cascade
+   * @param {string[]|null} roots
+   * @returns {object}
+   */
+  function bindRoots(globals, roots) {
+    const bound = {};
+    if (!globals || !roots) return bound;
+    for (const root of roots) {
+      if (root !== 'site' && root in globals) bound[root] = globals[root];
+    }
+    return bound;
+  }
+
+  /**
+   * Render a single frontmatter string value (Liquid), cached.
+   * Per-page values (`page.*` recipe meta, `resolved.*` layout defaults, and
+   * the page's own pagination alias) render UNCACHED against `extraScope`;
+   * site-only values are build-constant and cache by raw source; everything
+   * else renders uncached against the template's own cascade.
+   * @param {string} value
+   * @param {object} [extraScope] - per-page scope ({ resolved, page, <alias> })
+   * @param {object} [context] - { globals, defer, strict, file } — see resolveData
+   * @returns {string}
+   */
+  function render(value, extraScope, context = {}) {
+    const roots = rootsOf(value);
+    const perPage = roots === null
+      ? PER_PAGE_RE.test(value)
+      : roots.some((root) => PER_PAGE_ROOTS.has(root) || (context.defer && context.defer.has(root)));
+    if (perPage) {
+      // Per-page: WITHOUT a page scope, defer (leave raw) — the engine's
+      // `resolved` computed re-renders with { resolved, page } once the
+      // cascade is merged; rendering here would empty the refs (no scope)
+      // and mutate layout objects SHARED across pages.
+      if (!extraScope) return value;
+      return engine.parseAndRenderSync(value, { ...scope, ...bindRoots(context.globals, roots), ...extraScope });
+    }
+
+    // Build-constant — `site.*` alone, or no refs at all — is the cacheable
+    // lane. A value reading anything else renders against the cascade, per
+    // template: what a global holds is not the resolver's to assume.
+    const siteOnly = roots !== null && roots.every((root) => root === 'site');
+    if (siteOnly && cache.has(value)) return cache.get(value);
+
+    if (context.strict) assertRootsDefined(value, roots, context);
+
+    let rendered = value;
+    if (rendered.includes('{{') || rendered.includes('{%')) {
+      rendered = engine.parseAndRenderSync(rendered, siteOnly ? scope : { ...scope, ...bindRoots(context.globals, roots) });
+    }
+
+    if (siteOnly) cache.set(value, rendered);
+    return rendered;
+  }
+
+  /**
+   * The loud half of #544: a meta value whose root nothing in the cascade
+   * defines is a spelling mistake, and a meta value renders ONCE and CACHES —
+   * so rendering it would ship an empty string on every page sharing the
+   * value (280 trusteroo brand pages under one nameless title). Only the ROOT
+   * is checked: `{{ site.meta.keywords }}` on a brand that sets no keywords is
+   * a legit empty optional and passes.
+   * @param {string} value
+   * @param {string[]|null} roots
+   * @param {object} context - { globals, file }
+   */
+  function assertRootsDefined(value, roots, context) {
+    if (!roots || !context.globals) return;
+    const missing = roots.filter((root) => root !== 'site' && !(root in context.globals));
+    if (!missing.length) return;
+    throw new Error(
+      `[@omega.js/web:frontmatter-liquid] ${context.file || 'unknown template'}: meta value "${value}" reads `
+      + `${missing.map((root) => `\`${root}\``).join(', ')} — nothing in this page's data defines that. `
+      + 'A meta value renders once and caches, so this would ship as an empty string on every page that shares it. '
+      + 'Name the page\'s pagination alias (it defers to render time), spell a layout/page value `resolved.<key>`, or fix the typo.',
+    );
+  }
+
+  /**
+   * Deep-walk a frontmatter data object, rendering every string value that
+   * contains Liquid refs, in place. The engine-machinery keys (DEFAULT_SKIP:
+   * collections, pagination, permalink, globals…) are left alone — Eleventy
+   * renders dynamic permalinks itself, and machinery subtrees contain other
+   * templates' raw content.
+   *
+   * This is the CACHE-TIME pass, which is why `meta` walks strict (#544): it
+   * is the subtree whose values render once, cache, and ship into every page's
+   * head. Everything else keeps rendering whatever the cascade gives it.
+   * @param {object} data
+   * @param {object} [context] - { globals: the data cascade (#542), defer: Set of per-page roots (a pagination alias), file: inputPath }
+   */
+  function resolveData(data, context) {
+    const seen = new WeakSet();
+    for (const key of Object.keys(data)) {
+      if (DEFAULT_SKIP.has(key)) continue;
+      const keyContext = key === 'meta' ? { ...context, strict: true } : context;
+      if (typeof data[key] === 'string') data[key] = maybeRender(data[key], undefined, keyContext);
+      else walk(data[key], seen, keyContext);
+    }
+  }
+
+  function walk(node, seen, context, extraScope) {
+    if (node === null || typeof node !== 'object' || seen.has(node)) return;
+    seen.add(node);
+
+    if (Array.isArray(node)) {
+      for (let i = 0; i < node.length; i++) {
+        if (typeof node[i] === 'string') node[i] = maybeRender(node[i], extraScope, context);
+        else walk(node[i], seen, context, extraScope);
+      }
+      return;
+    }
+
+    for (const key of Object.keys(node)) {
+      if (typeof node[key] === 'string') node[key] = maybeRender(node[key], extraScope, context);
+      else walk(node[key], seen, context, extraScope);
+    }
+  }
+
+  function maybeRender(value, extraScope, context) {
+    return value.includes('{{') ? render(value, extraScope, context) : value;
+  }
+
+  /**
+   * Copy-on-write render pass over a data tree: returns the SAME references
+   * wherever nothing needed rendering, and shallow copies only along paths
+   * where a string rendered. Safe for per-page `resolved` computation —
+   * cascade sub-objects shared across pages are never mutated, and foreign
+   * objects with throwing getters (Eleventy collection items expose a
+   * templateContent getter that throws before render) stay opaque.
+   * @param {object} data
+   * @param {object} [extraScope] - per-page scope ({ page }) for page refs
+   * @param {object} [context] - { globals, file } — the cascade a `_data` ref resolves against (#542)
+   * @returns {object} rendered tree (original object when nothing changed)
+   */
+  function renderData(data, extraScope, context) {
+    const seen = new WeakSet();
+
+    const transform = (node) => {
+      if (typeof node === 'string') return maybeRender(node, extraScope, context);
+      if (node === null || typeof node !== 'object' || seen.has(node)) return node;
+      // Eleventy collection items (pagination aliases carry them, e.g. a
+      // taxonomy group's `posts`) stay opaque — checked WITHOUT touching the
+      // getter: templateContent THROWS before render, and constructing those
+      // errors per item per page was a measured corpus hotspot (~19% CPU).
+      if ('templateContent' in node) return node;
+      seen.add(node);
+
+      let entries;
+      try {
+        entries = Object.entries(node);
+      } catch {
+        return node; // foreign object (throwing getter) — leave opaque
+      }
+
+      let copy = null;
+      for (const [key, value] of entries) {
+        const next = transform(value);
+        if (next !== value && copy === null) copy = Array.isArray(node) ? [...node] : { ...node };
+        if (copy !== null && next !== value) copy[key] = next;
+      }
+      return copy === null ? node : copy;
+    };
+
+    return transform(data);
+  }
+
+  return { render, resolveData, renderData, cacheSize: () => cache.size };
+}
+
+module.exports = { createFrontmatterResolver };

package/dist/github-secrets.js

@@ -0,0 +1,80 @@
+/**
+ * The `.env` → GitHub Actions secrets pair (#189), UJM's setup capability
+ * rebuilt on the OMEGA cascade — and, since the #627 review, web's BIND of the
+ * shared publisher rather than its own copy of it.
+ *
+ * The orchestration (derive the schema's key set → collect from the composed
+ * target env → guard on the brand's DECLARED repo → publish over devkit's `gh`
+ * boundary, with its five loud skips) lives once, in
+ * `@omega.js/devkit/target-secrets`. Web and the extension ran two
+ * near-byte-identical copies of it for one wave; this file now passes a target
+ * string and nothing else.
+ *
+ * What stays web's own is the fourth step — INJECT: the SAME schema set renders
+ * the scaffolded workflow's env block, one `KEY: ${{ secrets.KEY }}` line each
+ * (`renderSecretsBlock('web')`, @omega.js/config). It is GENERATED, never
+ * hand-maintained: `scaffold/.github/workflows/build.yml` carries a
+ * `{{ githubSecrets }}` token and the workflow scaffolds with
+ * `overwrite: true`, so every verb's ensureTarget re-renders the block — the
+ * same heal path as .nvmrc's node version.
+ *
+ * A key with no value in the cascade is not published (an empty value never
+ * claims a key there), but it is still RENDERED into the workflow: what CI
+ * needs is what the schema declares, not what this machine's files hold.
+ */
+const { renderSecretsBlock } = require('./vendor/config/env-delivery.js');
+const { collectTargetSecrets, declaredBrandRepo: declaredRepoFor, publishTargetSecrets } = require('./vendor/devkit/target-secrets.js');
+
+const TARGET = 'web';
+
+/**
+ * Collect the publishable secrets for a target: the schema's web delivery set,
+ * valued from the COMPOSED env.
+ *
+ * Positional `targetDir`, the shape its desktop and extension siblings already
+ * take ([#723](https://github.com/Omega-JS-Stack/omega/issues/723)).
+ *
+ * @param {string} targetDir - The target root (its .env is the local layer)
+ * @returns {Object<string, string>} key → value, ready to publish
+ */
+function collectEnvSecrets(targetDir) {
+  return collectTargetSecrets({ targetDir, target: TARGET });
+}
+
+/**
+ * The brand's OWN repo as `owner/name`, from the composed config — the same
+ * derivation `omega deploy --direct` uses (`repo.providers.github`, name
+ * falling back to brand.id). Null when the config declares nothing usable or
+ * doesn't load.
+ *
+ * @param {string} targetDir - The target root
+ * @returns {string|null}
+ */
+function declaredBrandRepo(targetDir) {
+  return declaredRepoFor({ targetDir, target: TARGET });
+}
+
+/**
+ * The `omega deploy` precheck (#675): publish the target's collected `.env`
+ * values as repo Actions secrets.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root
+ * @param {object} options.logger - `{ log, warn, error }`
+ * @param {object} [options.env] - Env map (default: process.env)
+ * @param {function} [options.execFn] - Injectable `gh` exec (tests)
+ * @param {function} [options.gitExecFn] - Injectable `git` exec for remote discovery (tests)
+ * @returns {{ skipped: string }|{ published: string[], failed: Array<object> }}
+ */
+function publishEnvSecrets(options) {
+  return publishTargetSecrets({ ...(options || {}), target: TARGET });
+}
+
+// renderSecretsBlock is @omega.js/config's, re-exported so web's scaffold and
+// this module read the block from ONE import site (#627).
+module.exports = {
+  collectEnvSecrets,
+  renderSecretsBlock,
+  publishEnvSecrets,
+  declaredBrandRepo,
+};

package/dist/hero-animations.js

@@ -0,0 +1,170 @@
+/**
+ * hero-animations.js — the hero's custom-animation slot
+ * ([#441](https://github.com/Omega-JS-Stack/omega/issues/441), Ian's ruling
+ * 2026-08-25).
+ *
+ * A brand that wants a moving hero visual makes ONE folder and names it:
+ *
+ *   src/_hero/orbit/
+ *     index.html   the markup
+ *     style.scss   its styles   → the main sheet, like a section's scss
+ *     script.js    its behavior → the main bundle, like a section's js
+ *
+ *   {% section "marketing/hero" %}
+ *   demo:
+ *     enabled: true
+ *     type: custom
+ *     name: orbit
+ *   {% endsection %}
+ *
+ * Resolution is the layer chain, exactly like `_sections`/`_components`:
+ * consumer first, then the theme layers — so a brand overrides a shipped
+ * animation by owning the name, and the FIRST folder with an `index.html` wins
+ * the whole entry (markup and assets travel together).
+ *
+ * Why this is not a third `KINDS` entry: a hero animation is not a composable
+ * band. It has no args schema, no gallery, no demo variants, and Ian named its
+ * files after what they ARE (`style`, `script`) rather than after the folder.
+ * What it DOES share is the asset lane — the collector returns the same
+ * `{ kind, id, scss, js }` shape `collectSectionAssets` does, so the sass
+ * `omega:sections` importer and the main bundle's `bootSections` registry take
+ * it with no special case: the markup carries `data-omega-hero="<name>"` and
+ * `script.js` inits per element like any section module.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const reads = require('./vendor/devkit/reads.js');
+
+// The folder family, and what a folder must hold. `index.html` is the entry —
+// a folder without one is not an animation, whatever else is in it.
+const HERO_DIR = '_hero';
+const HERO_FILES = { html: 'index.html', scss: 'style.scss', js: 'script.js' };
+
+// Names are single kebab-case segments: an animation is referenced by name in
+// frontmatter, and a path there would be a traversal waiting to happen.
+const HERO_NAME = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * Collect every resolved hero animation across the layer chain, in the asset
+ * lane's own shape.
+ * @param {string[]} baseDirs - resolution bases in precedence order (consumer
+ *   dir first, then theme layers — registerSectionTags' order)
+ * @returns {Array<{kind: string, id: string, html: string, scss: string|null, js: string|null}>}
+ *   sorted by id, so the emitted sheet and bundle order are deterministic
+ */
+function collectHeroAnimations(baseDirs) {
+  const entries = new Map(); // name → entry
+
+  for (const base of baseDirs) {
+    const dir = path.join(base, HERO_DIR);
+    if (!fs.existsSync(dir)) continue;
+
+    for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!item.isDirectory() || !HERO_NAME.test(item.name)) continue;
+      if (entries.has(item.name)) continue; // a higher layer already won
+
+      const entryDir = path.join(dir, item.name);
+      const html = path.join(entryDir, HERO_FILES.html);
+      if (!fs.existsSync(html)) continue;
+
+      const scss = path.join(entryDir, HERO_FILES.scss);
+      const js = path.join(entryDir, HERO_FILES.js);
+      entries.set(item.name, {
+        kind: 'hero',
+        id: item.name,
+        html,
+        scss: fs.existsSync(scss) ? scss : null,
+        js: fs.existsSync(js) ? js : null,
+      });
+    }
+  }
+
+  return [...entries.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Register `{% hero_animation <name expression> %}` on a LiquidJS engine — the
+ * ONE reader of the folder, used by the `marketing/hero` section's custom demo
+ * branch. It is a TAG rather than a global because section markup is
+ * context-free by contract: page globals never reach it, and registered tags do.
+ *
+ * The markup renders in an empty scope for the same reason a section does — the
+ * `omega_*` tags and filters work, the calling page's data does not leak in.
+ * The wrapper carries `data-omega-hero="<name>"`, which is what boots the
+ * folder's `script.js` (runtime/boot.js `bootSections`).
+ *
+ * @param {object} engine - LiquidJS engine (Eleventy's, via amendLibrary)
+ * @param {object} options
+ * @param {string[]} options.baseDirs - resolution bases in precedence order
+ */
+function registerHeroAnimationTag(engine, options) {
+  const roots = options.baseDirs
+    .map((dir) => path.join(dir, HERO_DIR))
+    .filter((dir) => fs.existsSync(dir));
+
+  // Per-registration caches — roots are fixed for a build, so a resolved path
+  // and its parsed template never go stale within one.
+  const pathCache = new Map(); // name → abs index.html | null
+  const templateCache = new Map(); // abs path → parsed templates
+
+  const resolveAnimation = (name) => {
+    if (pathCache.has(name)) return pathCache.get(name);
+    let found = null;
+    for (const root of roots) {
+      const html = path.join(root, name, HERO_FILES.html);
+      if (fs.existsSync(html)) { found = html; break; }
+    }
+    pathCache.set(name, found);
+    return found;
+  };
+
+  engine.registerTag('hero_animation', {
+    parse(tagToken) {
+      this.markup = String(tagToken.args || '').trim();
+    },
+
+    * render(context, emitter) {
+      const quoted = this.markup.match(/^"([^"]+)"$|^'([^']+)'$/);
+      const name = quoted
+        ? (quoted[1] ?? quoted[2])
+        : yield this.liquid.evalValue(this.markup, context);
+
+      if (typeof name !== 'string' || !name) {
+        throw new Error(`{% hero_animation ${this.markup} %}: the name must resolve to a folder name string — got ${JSON.stringify(name)}`);
+      }
+      if (!HERO_NAME.test(name)) {
+        throw new Error(`{% hero_animation "${name}" %}: hero animation names are one kebab-case segment (src/${HERO_DIR}/${name}/)`);
+      }
+
+      const html = resolveAnimation(name);
+      if (!html) {
+        throw new Error(
+          `{% hero_animation "${name}" %}: no ${HERO_DIR}/${name}/${HERO_FILES.html} in any layer `
+          + `(${roots.join(', ') || 'no roots'})`,
+        );
+      }
+
+      let templates = templateCache.get(html);
+      if (!templates) {
+        templates = this.liquid.parse(fs.readFileSync(html, 'utf8'), html);
+        templateCache.set(html, templates);
+      }
+
+      emitter.write(`<div class="omega-hero-animation" data-omega-hero="${name}">`);
+      emitter.write(yield this.liquid.render(templates, {}));
+      emitter.write('</div>');
+    },
+  });
+}
+
+/**
+ * Register every hero-animation folder as a dev WATCH target — the same probe
+ * the section walk does, so a new folder (or an edit inside one) resets the
+ * config instead of serving a captured resolution.
+ * @param {string[]} baseDirs
+ */
+function watchHeroAnimations(baseDirs) {
+  for (const base of baseDirs) reads.dirExists(path.join(base, HERO_DIR));
+}
+
+module.exports = { collectHeroAnimations, registerHeroAnimationTag, watchHeroAnimations, HERO_DIR, HERO_FILES };