@omega.js/web 0.1.0

package/dist/sections.js

@@ -0,0 +1,810 @@
+/**
+ * The section/component library machinery (docs/web/omega-sections-spec.md):
+ * `{% section "marketing/hero", key: value %}` and `{% component "frame/x" %}`
+ * Liquid tags. One tag, two authoring forms:
+ *
+ *   inline — {% section "marketing/hero", headline: "Ship it", data: resolved.hero %}
+ *   block  — {% section "marketing/testimonials" %}
+ *            headline: "What builders say"
+ *            items:
+ *              - quote: "…"
+ *            {% endsection %}
+ *
+ * The block body is YAML (same dialect as frontmatter); using inline named
+ * args AND a body on one call is an error. The reserved `data:` arg deep-
+ * spreads an object between defaults and named args — the bridge that keeps
+ * today's frontmatter-key overrides working (layouts pass `data: resolved.X`).
+ *
+ * Slots (Ian 2026-07-18): a body may carry named markup blocks —
+ * {% slot demo %}<any html>{% endslot %} — alongside the YAML (or alongside
+ * inline args: the XOR rule applies to the YAML remainder only). Slot content
+ * renders in the CALLER's scope (site.*, captures, omega_* tags all work) and
+ * reaches the section as a finished-HTML string arg (schema type 'html'),
+ * merged OUTERMOST after call-site liquification — so slot output never
+ * re-renders and literal braces (code samples via {% raw %}) survive. An
+ * empty slot passes '' — the absence spine: it kills a default the same way
+ * explicit-empty kills everywhere else. Same-tag nesting inside a slot
+ * ({% section %} in a section slot) is not supported — the dual-form scan
+ * would misread it (loud parse error); nest the OTHER tag instead
+ * (components inside section slots, sections inside component slots).
+ *
+ * Resolution walks the layer chain (consumer `_sections`/`_components` →
+ * active theme → base — first match wins), mirroring themes/layouts.
+ * Each entry is a folder owning `section.html` + optional `section.json5`
+ * ({ description, args, defaults, demo }) — defaults merge under passed args,
+ * top-level args validate against the schema (warn + did-you-mean, never
+ * throw).
+ *
+ * The name is usually a quoted literal; a bare expression that resolves to
+ * an id string is also legal ({% section entry.id, data: variant.args %}) —
+ * the auto-generated showcase's mechanism (spec §9), and how data-driven
+ * composition stays one tag. The expression runs up to the first comma.
+ *
+ * Context-free rule (load-bearing): the markup renders against `{ args }`
+ * ONLY — no page globals. Interpolation happens at the CALL site instead:
+ * string values (passed or default) containing Liquid render against the
+ * caller's scope before the section sees them, so defaults like
+ * "Introducing {{ site.brand.name }}" work while markup stays portable to
+ * any surface any framework builds.
+ *
+ * {% composition %}…{% endcomposition %} (spec §8) wraps a page layout's
+ * default section composition. Two page states, both byte-parity with the
+ * `{{ content | omega_content_format }}` layout line the wrap replaces:
+ *   - empty page → the wrapped one-liners render (absence is the spine)
+ *   - body content → the body REPLACES the composition (a page that writes
+ *     a body means it — Ian's 2026-07-19 ruling; what `omega customize
+ *     <url>` materializes supersedes the default while the sections inside
+ *     keep flowing from the theme)
+ *
+ * The legacy UJM add-below flag (`append: true`) is GONE (#607, Ian
+ * 2026-08-26): a page that wants the default bands AND its own prose writes
+ * the bands itself — `omega customize <url>` materializes exactly that — and
+ * body content always renders below the sections THE BODY ITSELF calls, never
+ * below the layout composition it replaced.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const JSON5 = require('json5');
+const yaml = require('js-yaml');
+const reads = require('./vendor/devkit/reads.js');
+const { deepMerge } = require('./merge.js');
+const { registerHeroAnimationTag } = require('./hero-animations.js');
+const Logger = require('./vendor/devkit/logger.js');
+
+// The warning sink's default: build-time output stamps the identity tag
+// itself, so no message hand-writes a module prefix of its own (#12).
+// Callers that inject a sink (tests, the engine) still own their formatting.
+const logger = new Logger('sections');
+
+// The two tiers share one implementation — only the folder family, the
+// filenames ({% section %} → _sections/<id>/section.*) and the gallery url
+// space differ.
+//
+// `gallery` is a kind's whole showcase URL SPACE
+// ([#602](https://github.com/Omega-JS-Stack/omega/issues/602)): `url` is its
+// index, `base` is what its entry pages hang off (`<base>/<id>`, frames at
+// `<base>/<id>/frames/<slug>`), `label` names it on both. The two galleries
+// MIRROR each other — an index, one page per entry, frames beside it — in
+// SEPARATE spaces: components used to live under the section space, which made
+// /test/components read like a second view of /test/sections instead of a
+// library of its own. ONE generator, kind-aware paths: the showcase templates
+// read these off the entry and never compose a url.
+//
+// The two spellings are HARMONIZED (Ian's #602 addendum, 2026-08-26): `base`
+// IS `url` on both, so an entry is `<index>/<id>` in either library and
+// neither carries a kind segment the other lacks. Sections used to hang off
+// `/test/sections/section/<id>`, which read as a leftover of the era when the
+// section space held both kinds; a gallery is dev-only (#554), so that
+// spelling just goes — no redirects. The index's own permalink gains the
+// `.html` Jekyll extension (engine.js jekyllPermalink), so `/test/sections`
+// the FILE and `/test/sections/` the DIRECTORY never collide.
+const KINDS = {
+  section: {
+    dirname: '_sections',
+    basename: 'section',
+    gallery: { kind: 'section', url: '/test/sections', base: '/test/sections', label: 'Section library' },
+  },
+  component: {
+    dirname: '_components',
+    basename: 'component',
+    gallery: { kind: 'component', url: '/test/components', base: '/test/components', label: 'Component library' },
+  },
+};
+
+// Section ids are kebab-case category paths (marketing/hero) — never
+// dotted/absolute/traversal paths.
+const NAME_SHAPE = /^[a-z0-9][a-z0-9-]*(\/[a-z0-9][a-z0-9-]*)*$/;
+
+/**
+ * Levenshtein distance — small inputs only (arg-name did-you-mean).
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshtein(a, b) {
+  const rows = Array.from({ length: a.length + 1 }, (unused, i) => [i]);
+  for (let j = 1; j <= b.length; j++) rows[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      rows[i][j] = Math.min(
+        rows[i - 1][j] + 1,
+        rows[i][j - 1] + 1,
+        rows[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+  }
+  return rows[a.length][b.length];
+}
+
+/**
+ * The nearest known arg name within edit distance 2, for warning text.
+ * @param {string} key
+ * @param {string[]} known
+ * @returns {string} ' — did you mean "x"?' or ''
+ */
+function suggest(key, known) {
+  let best = null;
+  let bestDistance = 3;
+  for (const candidate of known) {
+    const distance = levenshtein(key, candidate);
+    if (distance < bestDistance) {
+      best = candidate;
+      bestDistance = distance;
+    }
+  }
+  return best ? ` — did you mean "${best}"?` : '';
+}
+
+/**
+ * Parse the inline named-arg list after the section name:
+ * `headline: page.title, meta: "a, b"` → [{ key, expr }]. Quote-aware — a
+ * comma inside a quoted value never splits. Value expressions are handed to
+ * LiquidJS's evalValue verbatim (literals, dotted paths, filters all work).
+ * @param {string} rest - the markup after the quoted name (leading comma ok)
+ * @returns {Array<{key: string, expr: string}>}
+ */
+function parseInlineArgs(rest) {
+  const pairs = [];
+  let text = rest.trim().replace(/^,/, '');
+  while (text.trim()) {
+    const match = text.match(/^\s*([\w-]+)\s*:/);
+    if (!match) throw new Error(`bad inline args near "${text.trim().slice(0, 40)}" — expected key: value`);
+    let i = match[0].length;
+    let quote = null;
+    for (; i < text.length; i++) {
+      const ch = text[i];
+      if (quote) {
+        if (ch === quote) quote = null;
+      } else if (ch === '"' || ch === "'") {
+        quote = ch;
+      } else if (ch === ',') {
+        break;
+      }
+    }
+    const expr = text.slice(match[0].length, i).trim();
+    if (!expr) throw new Error(`inline arg "${match[1]}" has no value`);
+    pairs.push({ key: match[1], expr });
+    text = text.slice(i + 1);
+  }
+  return pairs;
+}
+
+// {% slot name %}…{% endslot %} regions inside a section/component block
+// body. Not a registered tag — pure body-text grammar, so a stray slot
+// outside a block call fails loudly as an unknown tag.
+const SLOT_RE = /\{%-?\s*slot\s+([A-Za-z_][\w-]*)\s*-?%\}([\s\S]*?)\{%-?\s*endslot\s*-?%\}/g;
+const SLOT_STRAY_RE = /\{%-?\s*(?:slot|endslot)\b/;
+
+/**
+ * Split a block body into its YAML remainder and its named slot blocks.
+ * @param {string} bodyText - raw captured block body
+ * @returns {{yamlText: string, slots: Array<{name: string, source: string}>}}
+ */
+function extractSlots(bodyText) {
+  const slots = [];
+  const seen = new Set();
+  const yamlText = bodyText.replace(SLOT_RE, (match, slotName, source) => {
+    if (seen.has(slotName)) throw new Error(`duplicate {% slot ${slotName} %} — one block per name`);
+    seen.add(slotName);
+    slots.push({ name: slotName, source });
+    return '';
+  });
+  if (SLOT_STRAY_RE.test(yamlText)) {
+    throw new Error('malformed slot block — every {% slot name %} needs a name and a matching {% endslot %}');
+  }
+  return { yamlText, slots };
+}
+
+/**
+ * Render every Liquid-carrying string in an args tree against the caller's
+ * scope — fresh containers, source never mutated.
+ * @param {object} liquid - the LiquidJS engine
+ * @param {object} scope - plain scope object (context.getAll())
+ * @param {*} value
+ * @returns {Promise<*>}
+ */
+async function liquifyDeep(liquid, scope, value) {
+  if (typeof value === 'string') {
+    return value.includes('{{') || value.includes('{%')
+      ? liquid.parseAndRender(value, scope)
+      : value;
+  }
+  if (Array.isArray(value)) {
+    return Promise.all(value.map((item) => liquifyDeep(liquid, scope, item)));
+  }
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) out[key] = await liquifyDeep(liquid, scope, item);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Validate a value against a schema type name. Warn-only machinery — callers
+ * turn `false` into a message.
+ * @param {*} value
+ * @param {string} type - 'string' | 'number' | 'boolean' | 'array' | 'object'
+ * @returns {boolean}
+ */
+function matchesType(value, type) {
+  if (value === null || value === undefined) return true; // explicit null = "remove" — always legal
+  switch (type) {
+    case 'array': return Array.isArray(value);
+    case 'object': return typeof value === 'object' && !Array.isArray(value);
+    case 'html': return typeof value === 'string'; // finished markup — slot blocks or capture-passed
+    case 'string': case 'number': case 'boolean': return typeof value === type;
+    default: return true; // unknown schema type — never punish the caller
+  }
+}
+
+// The §7 lanes an override folder may declare `inherit` for. html can't be
+// inherited (not overriding it IS inheritance) and json5 can't (the folder is
+// its own manifest — theme defaults are theme identity).
+const INHERITABLE_LANES = new Set(['js', 'scss']);
+
+/**
+ * Read an entry folder's declared inherit lanes from its json5. Absent file,
+ * unreadable file (resolveEntry warns that at render time), or no `inherit`
+ * key → []. A malformed declaration throws — a contradictory manifest is a
+ * structural error, like traversal ids.
+ * @param {string} entryDir
+ * @param {string} basename - 'section' | 'component'
+ * @returns {string[]} validated lane names
+ */
+function readInheritLanes(entryDir, basename) {
+  const metaPath = path.join(entryDir, `${basename}.json5`);
+  if (!fs.existsSync(metaPath)) return [];
+  let meta;
+  try {
+    meta = JSON5.parse(fs.readFileSync(metaPath, 'utf8'));
+  } catch {
+    return [];
+  }
+  if (meta.inherit === undefined) return [];
+  if (!Array.isArray(meta.inherit) || meta.inherit.some((lane) => !INHERITABLE_LANES.has(lane))) {
+    throw new Error(`[sections] ${metaPath}: inherit must be an array drawn from ${[...INHERITABLE_LANES].join('/')} — got ${JSON.stringify(meta.inherit)}`);
+  }
+  return meta.inherit;
+}
+
+/**
+ * Collect every section/component ASSET (section.scss / section.js and the
+ * component.* twins) across the layer chain — the spec §7 asset lanes. Same
+ * resolution semantics as the tags: first root owning the entry's .html wins
+ * the WHOLE entry (markup + assets travel together — a consumer overriding a
+ * section owns its styles/behavior too), with ONE declared exception: the
+ * winning folder's json5 may carry `inherit: ['js']` (and/or 'scss') — lanes
+ * it deliberately leaves to the chain, filled from the first LOWER full entry
+ * (a folder owning the .html) that has the file. That's how a theme override
+ * replaces markup while keeping the base section's behavior riding the
+ * bundle without a copy (the newsflash newsletter-cta pattern — the base
+ * js's DOM contract becomes part of the override's markup contract).
+ * Declaring a lane the folder also ships throws (contradictory manifest);
+ * a declaration no lower layer can fill warns and stays null. Sorted
+ * (kind, id) for deterministic sheet/bundle order.
+ * @param {string[]} baseDirs - resolution bases in precedence order
+ *   (consumer dir first, then theme layers — registerSectionTags' order)
+ * @param {object} [options]
+ * @param {function} [options.warn] - warning sink (default console.warn)
+ * @returns {Array<{kind: string, id: string, scss: string|null, js: string|null}>}
+ */
+function collectSectionAssets(baseDirs, options = {}) {
+  const warn = options.warn || logger.warn.bind(logger);
+  const entries = new Map(); // `${kind}:${id}` → {kind, id, scss, js}
+  const pending = new Map(); // `${kind}:${id}` → Set of inherit lanes still unfilled
+
+  const walk = (root, dir, kind, prefix) => {
+    const basename = KINDS[kind].basename;
+    for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!item.isDirectory()) continue;
+      const id = prefix ? `${prefix}/${item.name}` : item.name;
+      if (!NAME_SHAPE.test(id)) continue;
+      const entryDir = path.join(dir, item.name);
+      const html = path.join(entryDir, `${basename}.html`);
+      if (fs.existsSync(html)) {
+        const key = `${kind}:${id}`;
+        if (!entries.has(key)) {
+          const scss = path.join(entryDir, `${basename}.scss`);
+          const js = path.join(entryDir, `${basename}.js`);
+          const entry = {
+            kind,
+            id,
+            scss: fs.existsSync(scss) ? scss : null,
+            js: fs.existsSync(js) ? js : null,
+          };
+          const lanes = readInheritLanes(entryDir, basename);
+          for (const lane of lanes) {
+            if (entry[lane]) {
+              throw new Error(`[sections] ${entryDir}: declares inherit "${lane}" but ships its own ${basename}.${lane} — remove one`);
+            }
+          }
+          entries.set(key, entry);
+          if (lanes.length) pending.set(key, new Set(lanes));
+        } else if (pending.has(key)) {
+          // A LOWER layer's full entry at the same id — fill declared lanes
+          // from the first layer that has each file (the chain continues past
+          // layers lacking it).
+          const lanes = pending.get(key);
+          for (const lane of [...lanes]) {
+            const file = path.join(entryDir, `${basename}.${lane}`);
+            if (fs.existsSync(file)) {
+              entries.get(key)[lane] = file;
+              lanes.delete(lane);
+            }
+          }
+          if (!lanes.size) pending.delete(key);
+        }
+      } else {
+        walk(root, entryDir, kind, id);
+      }
+    }
+  };
+
+  for (const root of baseDirs) {
+    for (const kind of Object.keys(KINDS)) {
+      const dir = path.join(root, KINDS[kind].dirname);
+      if (fs.existsSync(dir)) walk(root, dir, kind, '');
+    }
+  }
+
+  for (const [key, lanes] of pending) {
+    warn(`${key}: declares inherit ${[...lanes].join(', ')} but no lower layer owns the file — nothing inherited`);
+  }
+
+  return [...entries.values()].sort((a, b) => (a.kind + a.id).localeCompare(b.kind + b.id));
+}
+
+/**
+ * The resolved library with meta, for the auto-generated showcase + schema
+ * docs (spec §9). Same first-match-wins resolution as the tags — the entry a
+ * page composing that id would actually render — with the winning folder's
+ * json5 normalized for template consumption:
+ *
+ *   argsTable    — [{ name, type, description }] rows (the reference docs;
+ *                  a shorthand `name: 'string'` schema yields type only)
+ *   defaultsJson — pretty-printed defaults ('' when none): display copy for
+ *                  the docs, showing the raw {{ site.brand.name }} tokens a
+ *                  consumer would see in the file
+ *
+ * Display strings (description, argsTable descriptions, defaultsJson) are
+ * HTML-ESCAPED here, including `{` → &#123; — templates print them verbatim
+ * (no | escape). That's load-bearing, not cosmetic: the library rides the
+ * page data cascade, whose frontmatter/resolved walkers liquify any string
+ * containing {{ — raw tokens would either render (wrong: docs must show the
+ * contract) or throw (JSON.stringify's escaped quotes inside a token are
+ * invalid Liquid). Demo args stay RAW — they liquify at the tag's call site
+ * like every real composition.
+ *   demo         — [{ label, slug, url, argsJson, args?, stage_class? }]
+ *                  variants, each rendered in its own EMBEDDED FRAME page
+ *                  (#463) that the entry page iframes in (args ride the data
+ *                  bridge, so json5 defaults still apply underneath — exactly
+ *                  the consumer experience); malformed variants warn + drop.
+ *                  `slug` is the kebab-cased label, de-duplicated within the
+ *                  entry (-2, -3 …) — it names the frame page's URL segment;
+ *                  `url` is that frame page's permalink; `argsJson` is the
+ *                  escaped authored-args display copy
+ *   url          — the entry page's own permalink, off its KIND's gallery base
+ *                  (#602) — the showcase templates never compose one
+ *   gallery      — that kind's whole url space ({ kind, url, base, label }),
+ *                  so an entry page can name its own library
+ *   source       — which layer owns the entry: 'consumer' or the layer dir's
+ *                  basename ('classy', 'newsflash')
+ *   inherit      — declared §7 inherit lanes, for the docs chip
+ *
+ * `groups` clusters entries by (kind, category folder) for the index page —
+ * sections first, then components, categories alphabetical (the spec §2
+ * "the showcase groups by folder automatically"). `variants` is the same demo
+ * variants FLATTENED across every entry ({ kind, id, source, label, slug, url,
+ * gallery, args, stage_class }) — the pagination data of the per-variant frame pages,
+ * one page per item.
+ *
+ * @param {object} options
+ * @param {string[]} options.baseDirs - resolution bases in precedence order
+ *   (registerSectionTags' order: consumer dir first, then theme layers)
+ * @param {string} [options.consumerDir] - labeled 'consumer' when it wins
+ * @param {function} [options.warn] - warning sink (default console.warn)
+ * @returns {{ entries: Array<object>, groups: Array<{kind: string, category: string, entries: Array<object>}>, variants: Array<object>, galleries: Array<object> }}
+ */
+function buildSectionLibrary(options) {
+  const warn = options.warn || logger.warn.bind(logger);
+  const entries = new Map(); // `${kind}:${id}` → entry
+
+  // Display-ready HTML text (see the JSDoc: the { escape makes the string
+  // liquid-inert, which the data-cascade walkers require).
+  const escapeHtml = (text) => String(text)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+    .replace(/{/g, '&#123;');
+
+  // A demo variant's URL segment on its frame page: kebab-case of the label,
+  // de-duplicated within the entry (two "Default"s become default, default-2).
+  const slugify = (text) => String(text).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'demo';
+
+  const normalizeMeta = (meta, label) => {
+    const argsTable = Object.entries(meta.args || {}).map(([name, spec]) => ({
+      name,
+      type: typeof spec === 'string' ? spec : (spec && spec.type) || '',
+      description: escapeHtml((spec && typeof spec === 'object' && spec.description) || ''),
+    }));
+    let demo = [];
+    if (meta.demo !== undefined) {
+      if (!Array.isArray(meta.demo)) {
+        warn(`showcase ${label}: demo must be an array of { label, args } variants — ignoring`);
+      } else {
+        const taken = new Map(); // base slug → how many variants claimed it
+        demo = meta.demo.filter((variant) => {
+          const ok = variant && typeof variant === 'object' && typeof variant.label === 'string' && variant.label;
+          if (!ok) warn(`showcase ${label}: demo variant without a label — dropped`);
+          return ok;
+        }).map((variant) => {
+          const base = slugify(variant.label);
+          const seen = (taken.get(base) || 0) + 1;
+          taken.set(base, seen);
+          return {
+            ...variant,
+            slug: seen === 1 ? base : `${base}-${seen}`,
+            argsJson: variant.args && Object.keys(variant.args).length
+              ? escapeHtml(JSON.stringify(variant.args, null, 2))
+              : '',
+          };
+        });
+      }
+    }
+    return {
+      description: escapeHtml(meta.description || ''),
+      argsTable,
+      defaultsJson: meta.defaults && Object.keys(meta.defaults).length
+        ? escapeHtml(JSON.stringify(meta.defaults, null, 2))
+        : '',
+      demo,
+      inherit: Array.isArray(meta.inherit) ? meta.inherit : [],
+    };
+  };
+
+  // The walk reads through the captured-read helper (#200): this runs at
+  // CONFIG time (the library is a global data value), so every dir it probes
+  // becomes a dev config-reset target — including the entry folders a brand
+  // has not authored yet.
+  const walk = (source, dir, kind, prefix) => {
+    const basename = KINDS[kind].basename;
+    for (const item of reads.readdir(dir, { withFileTypes: true })) {
+      if (!item.isDirectory()) continue;
+      const id = prefix ? `${prefix}/${item.name}` : item.name;
+      if (!NAME_SHAPE.test(id)) continue;
+      const entryDir = path.join(dir, item.name);
+      if (!reads.fileExists(path.join(entryDir, `${basename}.html`))) {
+        walk(source, entryDir, kind, id);
+        continue;
+      }
+      const key = `${kind}:${id}`;
+      if (entries.has(key)) continue; // a higher layer already won
+      let meta = {};
+      const metaPath = path.join(entryDir, `${basename}.json5`);
+      if (reads.fileExists(metaPath)) {
+        try {
+          meta = JSON5.parse(reads.read(metaPath));
+        } catch (error) {
+          warn(`showcase: unreadable ${metaPath} (${error.message}) — listing with empty meta`);
+        }
+      }
+      // The gallery urls are computed HERE, once (#602): the entry page's own
+      // permalink, and one per demo variant for its frame. Every showcase
+      // template reads them off the entry, so a kind's url space has ONE home.
+      const gallery = KINDS[kind].gallery;
+      const entry = { kind, id, source, gallery, url: `${gallery.base}/${id}`, ...normalizeMeta(meta, key) };
+      entry.demo = entry.demo.map((variant) => ({ ...variant, url: `${entry.url}/frames/${variant.slug}` }));
+      entries.set(key, entry);
+    }
+  };
+
+  for (const root of options.baseDirs) {
+    const source = root === options.consumerDir ? 'consumer' : path.basename(root);
+    for (const kind of Object.keys(KINDS)) {
+      const dir = path.join(root, KINDS[kind].dirname);
+      if (reads.dirExists(dir)) walk(source, dir, kind, '');
+    }
+  }
+
+  const sorted = [...entries.values()].sort((a, b) => (a.kind + a.id).localeCompare(b.kind + b.id));
+
+  const groupMap = new Map(); // `${kind}:${category}` → group
+  for (const entry of sorted) {
+    const category = entry.id.includes('/') ? entry.id.split('/').slice(0, -1).join('/') : '';
+    const key = `${entry.kind}:${category}`;
+    if (!groupMap.has(key)) groupMap.set(key, { kind: entry.kind, category, entries: [] });
+    groupMap.get(key).entries.push(entry);
+  }
+  const groups = [...groupMap.values()].sort((a, b) => (
+    a.kind === b.kind ? a.category.localeCompare(b.category) : (a.kind === 'section' ? -1 : 1)
+  ));
+
+  // The frame pages' pagination data (#463): every entry's demo variants,
+  // flattened, each carrying the entry coordinates its own page needs.
+  const variants = sorted.flatMap((entry) => entry.demo.map((variant) => ({
+    kind: entry.kind,
+    id: entry.id,
+    source: entry.source,
+    label: variant.label,
+    slug: variant.slug,
+    url: variant.url,          // the frame page's own permalink (#602)
+    gallery: entry.gallery,    // …and the library it belongs to, for its title
+    args: variant.args,
+    stage_class: variant.stage_class,
+  })));
+
+  // The gallery url spaces themselves (#602) — the index pages select their
+  // own out of this list, so a label or a url has ONE home for the whole
+  // showcase (KINDS above).
+  const galleries = Object.values(KINDS).map((kind) => kind.gallery);
+
+  return { entries: sorted, groups, variants, galleries };
+}
+
+/**
+ * Register the {% section %} and {% component %} tags on a LiquidJS engine —
+ * and, with them, `{% hero_animation %}` (#441): section MARKUP calls it
+ * (`marketing/hero`'s custom demo branch does), so registering the family
+ * without it leaves a tag no engine can parse. One call, one registration
+ * point, and no harness can forget half of it.
+ * @param {object} engine - LiquidJS engine (Eleventy's, via amendLibrary)
+ * @param {object} options
+ * @param {string[]} options.baseDirs - resolution bases in precedence order:
+ *   consumer dir first, then theme layers (each probed for
+ *   _sections/_components/_hero)
+ * @param {function} [options.warn] - warning sink (default console.warn)
+ */
+function registerSectionTags(engine, options) {
+  const warn = options.warn || logger.warn.bind(logger);
+
+  registerHeroAnimationTag(engine, { baseDirs: options.baseDirs });
+
+  for (const [tagName, kind] of Object.entries(KINDS)) {
+    const roots = options.baseDirs
+      .map((dir) => path.join(dir, kind.dirname))
+      .filter((dir) => fs.existsSync(dir));
+
+    // Per-registration caches — roots are fixed for a build, so entries and
+    // parsed templates never go stale within one; a new build re-registers.
+    const entryCache = new Map(); // name → { templatePath, meta } | null
+    const templateCache = new Map(); // abs path → parsed templates
+
+    const resolveEntry = (name) => {
+      if (entryCache.has(name)) return entryCache.get(name);
+      let entry = null;
+      for (const root of roots) {
+        const dir = path.join(root, name);
+        const templatePath = path.join(dir, `${kind.basename}.html`);
+        if (!fs.existsSync(templatePath)) continue;
+        let meta = {};
+        const metaPath = path.join(dir, `${kind.basename}.json5`);
+        if (fs.existsSync(metaPath)) {
+          try {
+            meta = JSON5.parse(fs.readFileSync(metaPath, 'utf8'));
+          } catch (error) {
+            warn(`${tagName} "${name}": unreadable ${kind.basename}.json5 (${error.message}) — treating as empty`);
+          }
+        }
+        entry = { templatePath, meta };
+        break;
+      }
+      entryCache.set(name, entry);
+      return entry;
+    };
+
+    engine.registerTag(tagName, {
+      parse(tagToken, remainTokens) {
+        this.markup = String(tagToken.args || '').trim();
+        this.bodyText = null;
+
+        // Dual-form discrimination: block iff the matching end tag appears
+        // before the next same-tag open in the remaining stream. Sound for
+        // all legal inputs — YAML bodies never contain {% section %} tags.
+        let isBlock = false;
+        for (const token of remainTokens) {
+          if (token.name === tagName) break;
+          if (token.name === `end${tagName}`) { isBlock = true; break; }
+        }
+        if (!isBlock) return;
+
+        const parts = [];
+        while (remainTokens.length) {
+          const token = remainTokens.shift();
+          if (token.name === `end${tagName}`) {
+            this.bodyText = parts.join('');
+            return;
+          }
+          // Raw source capture — output tokens ({{ site.brand.name }}) ride
+          // into the YAML verbatim and liquify at render, like every string arg.
+          parts.push(typeof token.getText === 'function'
+            ? token.getText()
+            : token.input.slice(token.begin, token.end));
+        }
+        throw new Error(`{% ${tagName} %} block not closed with {% end${tagName} %}`);
+      },
+
+      * render(context, emitter) {
+        const nameMatch = this.markup.match(/^"([^"]+)"|^'([^']+)'/);
+        let name;
+        let rest;
+        if (nameMatch) {
+          name = nameMatch[1] ?? nameMatch[2];
+          rest = this.markup.slice(nameMatch[0].length);
+        } else {
+          // Expression name (the showcase's lane): everything up to the
+          // first comma evaluates against the caller's scope and must yield
+          // an id string. Bare paths only — a filter taking comma-separated
+          // params needs a {% capture %} first.
+          const comma = this.markup.indexOf(',');
+          const expr = (comma === -1 ? this.markup : this.markup.slice(0, comma)).trim();
+          if (!expr) throw new Error(`{% ${tagName} %} needs a name: {% ${tagName} "marketing/hero" %} (or an expression resolving to an id)`);
+          name = yield this.liquid.evalValue(expr, context);
+          if (typeof name !== 'string' || !name) {
+            throw new Error(`{% ${tagName} ${expr} %}: the name expression must resolve to an entry id string — got ${JSON.stringify(name)}`);
+          }
+          rest = comma === -1 ? '' : this.markup.slice(comma);
+        }
+        if (!NAME_SHAPE.test(name)) throw new Error(`{% ${tagName} "${name}" %}: ids are kebab-case category paths (marketing/hero)`);
+
+        const entry = resolveEntry(name);
+        if (!entry) {
+          throw new Error(`{% ${tagName} "${name}" %}: no ${kind.dirname}/${name}/${kind.basename}.html in any layer (${roots.join(', ') || 'no roots'})`);
+        }
+
+        // ---- gather passed args (inline XOR YAML remainder; slots ride either)
+        const inlinePairs = parseInlineArgs(rest);
+        const { yamlText, slots } = this.bodyText !== null
+          ? (this.slotSplit ||= extractSlots(this.bodyText))
+          : { yamlText: null, slots: [] };
+        if (yamlText !== null && yamlText.trim() && inlinePairs.length) {
+          throw new Error(`{% ${tagName} "${name}" %}: use inline args OR a YAML body, not both (slot blocks compose with either)`);
+        }
+
+        let passed = {};
+        let dataArg;
+        for (const { key, expr } of inlinePairs) {
+          const value = yield this.liquid.evalValue(expr, context);
+          if (key === 'data') dataArg = value;
+          else passed[key] = value;
+        }
+        if (yamlText !== null && yamlText.trim()) {
+          const parsed = yaml.load(yamlText);
+          if (parsed === null || parsed === undefined) {
+            // whitespace-only body — nothing passed
+          } else if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error(`{% ${tagName} "${name}" %}: the YAML body must be a mapping of args`);
+          } else {
+            ({ data: dataArg, ...passed } = parsed);
+          }
+        }
+        if (dataArg !== undefined && dataArg !== null && (typeof dataArg !== 'object' || Array.isArray(dataArg))) {
+          warn(`${tagName} "${name}": data must be an object — ignoring ${typeof dataArg}`);
+          dataArg = undefined;
+        }
+
+        // ---- slots render NOW, in the caller's scope (site.*, captures,
+        // omega_* tags) — finished HTML that merges outermost below, after
+        // call-site liquification, so it never re-renders.
+        const scope = typeof context.getAll === 'function' ? context.getAll() : context.environments;
+        const slotValues = {};
+        for (const slot of slots) {
+          // Untrimmed — surrounding whitespace is cosmetic in HTML but load-
+          // bearing for byte-exact conversions; whitespace-ONLY collapses to
+          // '' so an empty slot reads as explicit-empty (kills a default).
+          const rendered = yield this.liquid.parseAndRender(slot.source, scope);
+          slotValues[slot.name] = rendered.trim() === '' ? '' : rendered;
+        }
+
+        // ---- schema validation (top level, warn-only)
+        const schema = entry.meta.args;
+        if (schema && typeof schema === 'object') {
+          const known = Object.keys(schema);
+          const incoming = { ...(dataArg || {}), ...passed, ...slotValues };
+          for (const [key, value] of Object.entries(incoming)) {
+            if (!known.includes(key)) {
+              warn(`${tagName} "${name}": unknown arg "${key}"${suggest(key, known)}`);
+            } else {
+              const type = typeof schema[key] === 'string' ? schema[key] : schema[key]?.type;
+              if (type && !matchesType(value, type)) {
+                warn(`${tagName} "${name}": arg "${key}" should be ${type}`);
+              }
+            }
+          }
+        }
+
+        // ---- defaults ← data ← named args, then call-site liquification,
+        // then slots (outermost — already rendered)
+        let args = deepMerge(entry.meta.defaults || {}, dataArg || {});
+        args = deepMerge(args, passed);
+        args = yield liquifyDeep(this.liquid, scope, args);
+        Object.assign(args, slotValues);
+
+        // ---- context-free render: { args } is the whole scope
+        let templates = templateCache.get(entry.templatePath);
+        if (!templates) {
+          templates = this.liquid.parse(fs.readFileSync(entry.templatePath, 'utf8'), entry.templatePath);
+          templateCache.set(entry.templatePath, templates);
+        }
+        emitter.write(yield this.liquid.render(templates, { args }));
+      },
+    });
+  }
+
+  // ---- {% composition %}…{% endcomposition %} (spec §8): the page-body
+  // replacement guard. Wraps a layout's default composition; page content
+  // (blank for every default page) picks the branch. Parity templates parse
+  // lazily per engine so the non-blank branch renders the exact line the
+  // wrap replaced.
+  let contentParity = null;
+  engine.registerTag('composition', {
+    parse(tagToken, remainTokens) {
+      this.tpls = [];
+      let closed = false;
+      while (remainTokens.length) {
+        const token = remainTokens.shift();
+        if (token.name === 'endcomposition') {
+          closed = true;
+          break;
+        }
+        this.tpls.push(this.liquid.parser.parseToken(token, remainTokens));
+      }
+      if (!closed) throw new Error('{% composition %} not closed with {% endcomposition %}');
+    },
+
+    * render(context, emitter) {
+      const read = (key) => {
+        try {
+          return context.getSync([key]);
+        } catch {
+          return undefined;
+        }
+      };
+      const content = read('content');
+      const blank = typeof content !== 'string' || content.trim() === '';
+
+      // Ian's ruling (2026-07-19): a page that writes a body MEANS it — the
+      // body REPLACES the layout's default composition, no flag needed (the
+      // old `composition: true` key is retired, and #607 retired the legacy
+      // add-below `append: true` escape hatch with it — a page that wants the
+      // default bands writes them, which is what `omega customize` hands it).
+      if (!blank) {
+        if (!contentParity) contentParity = this.liquid.parse('{{ content | omega_content_format }}');
+        emitter.write(yield this.liquid.renderer.renderTemplates(contentParity, context));
+        return;
+      }
+
+      emitter.write(yield this.liquid.renderer.renderTemplates(this.tpls, context));
+      // Blank content still flows through (it is only whitespace) — byte-
+      // parity with the replaced layout line, which emitted the chain's
+      // newlines.
+      if (typeof content === 'string') emitter.write(content);
+    },
+  });
+
+  return engine;
+}
+
+module.exports = { registerSectionTags, collectSectionAssets, buildSectionLibrary, parseInlineArgs, levenshtein, KINDS };