@apleasantview/eleventy-plugin-baseline 0.1.0-next.32 → 0.1.0-next.39

package/modules/assets/index.js

@@ -0,0 +1,162 @@
+import path from 'node:path';
+import { TemplatePath } from '@11ty/eleventy-utils';
+
+import { optionsSchema } from './schema.js';
+import assetsESbuild from './processors/esbuild-process.js';
+import assetsPostCSS from './processors/postcss-process.js';
+
+/**
+ * Assets (module)
+ *
+ * Asset pipeline integration. Wires Eleventy’s template formats to esbuild
+ * and PostCSS through compile guards that allow only declared entrypoints,
+ * and exposes inline filters for critical-path assets.
+ *
+ * Architecture layer:
+ *   module
+ *
+ * System role:
+ *   Bridge between Eleventy’s template system and the external asset
+ *   processors. Reads `directories.assets` from the virtual-dir substrate.
+ *
+ * Lifecycle:
+ *   build-time → register js/css formats, compile guards, watch target, and
+ *                inline filters; guards run per-entrypoint during compile
+ *
+ * Why this exists:
+ *   Eleventy treats every .js and .css file as a template. Without compile
+ *   guards, 11tydata.js files and non-entry assets would either pollute the
+ *   template graph or trigger the wrong processor.
+ *
+ * Scope:
+ *   Owns template format registration, compile guards, watch wiring, and the
+ *   inline filters (inlinePostCSS, inlineESbuild).
+ *   Does not own the processors themselves (assets/processors/) or
+ *   `directories.assets` resolution (core/virtual-dir.js).
+ *
+ * Data flow:
+ *   assets/{js,css}/index.{js,css} entrypoints → compile guard →
+ *   esbuild/PostCSS processor → output
+ *
+ * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
+ * @param {Object} moduleContext
+ */
+export function assetsCore(eleventyConfig, moduleContext) {
+	const { state, directories, log } = moduleContext;
+	const { settings, options } = state;
+
+	// Structural-only options check: log on mismatch, do not throw.
+	const parsed = optionsSchema.safeParse(options.assets);
+	if (!parsed.success) {
+		for (const issue of parsed.error.issues) {
+			log.info('options:', `${issue.path.join('.')} — ${issue.message}`);
+		}
+	}
+
+	const inputDirectory = directories.input;
+	const assetsDirectory = directories.assets;
+	const jsDirectory = `${assetsDirectory}js/`;
+	const cssDirectory = `${assetsDirectory}css/`;
+
+	const esbuildOptions = options.assets.esbuild || {};
+	const dataFiles = `${inputDirectory}**/*.11tydata.js`;
+	const watchGlob = TemplatePath.join(assetsDirectory, '**/*.{css,js,svg,png,jpeg,jpg,webp,gif,avif}');
+
+	if (!assetsDirectory) {
+		log.warn('eleventyConfig.directories.assets is unset; registerVirtualDir must run before this plugin.');
+		return;
+	}
+
+	// Watch common asset formats so edits trigger reloads during --serve.
+	eleventyConfig.addWatchTarget(watchGlob);
+
+	// --- JS (esbuild) ---
+	// Register js as a template format. Only index.js files under assets/js/
+	// are compiled; everything else (11tydata.js, non-entry scripts) is skipped
+	// by the compile guard. The inline filter wraps the same process function.
+	// Defaults (minify, target) live in assets-esbuild/process.js.
+
+	eleventyConfig.addTemplateFormats('js');
+
+	// Prevent Eleventy from processing 11tydata.js files as templates.
+	// The compile guard below also filters these, but without this ignore
+	// Eleventy still enters them into the template graph (data cascade,
+	// permalink computation) before compile gets a chance to reject them.
+	eleventyConfig.ignores.add(dataFiles);
+
+	eleventyConfig.addExtension('js', {
+		outputFileExtension: 'js',
+		useLayouts: false,
+		read: false,
+		compileOptions: {
+			permalink: true,
+			cache: true
+		},
+		// Compile guard: only process index.js files under the assets js directory.
+		// Returning undefined skips the file without error.
+		compile: async function (_inputContent, inputPath) {
+			if (
+				inputPath.includes('11tydata.js') ||
+				!inputPath.startsWith(jsDirectory) ||
+				path.basename(inputPath) !== 'index.js'
+			) {
+				return;
+			}
+
+			return async () => assetsESbuild(inputPath, esbuildOptions);
+		}
+	});
+
+	// Inline filter: bundle a JS file and wrap in <script> tags.
+	// Accepts per-call esbuild options (merged with defaults in process.js).
+	// Eleventy's addAsyncFilter handles the Nunjucks callback bridge,
+	// so this is a plain async function.
+	eleventyConfig.addAsyncFilter('inlineESbuild', async function (inputPath, opts = {}) {
+		try {
+			const js = await assetsESbuild(inputPath, opts);
+			return `<script>${js}</script>`;
+		} catch {
+			// Non-fatal: return an error comment so the build doesn't break.
+			return `<script>/* Error processing JS */</script>`;
+		}
+	});
+
+	// --- CSS (PostCSS) ---
+	// Register css as a template format. Only index.css files under assets/css/
+	// are compiled; non-entry CSS is skipped. Reads from disk (read: false) —
+	// the process function owns its own I/O. Config loading and caching live
+	// in assets-postcss/process.js.
+
+	eleventyConfig.addTemplateFormats('css');
+
+	eleventyConfig.addExtension('css', {
+		outputFileExtension: 'css',
+		useLayouts: false,
+		read: false,
+		compileOptions: {
+			permalink: true,
+			cache: true
+		},
+		// Compile guard: only process index.css files under the assets css directory.
+		compile: async function (_inputContent, inputPath) {
+			if (!inputPath.startsWith(cssDirectory) || path.basename(inputPath) !== 'index.css') {
+				return;
+			}
+
+			return async () => assetsPostCSS(inputPath);
+		}
+	});
+
+	// Inline filter: process a CSS file through PostCSS and wrap in <style> tags.
+	// Eleventy's addAsyncFilter handles the Nunjucks callback bridge,
+	// so this is a plain async function.
+	eleventyConfig.addAsyncFilter('inlinePostCSS', async function (inputPath) {
+		try {
+			const css = await assetsPostCSS(inputPath);
+			return `<style>${css}</style>`;
+		} catch {
+			// Non-fatal: return an error comment so the build doesn't break.
+			return `<style>/* Error processing CSS */</style>`;
+		}
+	});
+}

package/modules/assets/processors/esbuild-process.js

@@ -0,0 +1,35 @@
+import * as esbuild from 'esbuild';
+import { createLogger } from '../../../core/logging.js';
+
+const log = createLogger('assets-esbuild');
+const defaultOptions = { minify: true, target: 'es2020' };
+
+/**
+ * Bundle a JS file with esbuild.
+ *
+ * @param {string} jsFilePath - Absolute path to the entry file.
+ * @param {Object} [options] - esbuild options (merged with defaults).
+ * @param {boolean} [options.minify=true] - Minify output.
+ * @param {string} [options.target='es2020'] - esbuild target.
+ * @returns {Promise<string>} Bundled JS text, or an error comment on failure.
+ */
+export default async function assetsESbuild(jsFilePath, options = {}) {
+	const userOptions = { ...defaultOptions, ...options };
+
+	try {
+		let result = await esbuild.build({
+			entryPoints: [jsFilePath],
+			bundle: true,
+			minify: userOptions.minify,
+			target: userOptions.target,
+			write: false
+		});
+
+		// Return raw JS; markup wrapping is handled by the plugin registration.
+		return result.outputFiles[0].text;
+	} catch (error) {
+		log.error('esbuild failed:', error);
+		// Surface a safe JS comment so the caller can decide how to wrap it.
+		return '/* Error processing JS */';
+	}
+}

package/modules/assets/processors/postcss-process.js

@@ -0,0 +1,52 @@
+import fs from 'fs/promises';
+import postcss from 'postcss';
+import loadPostCSSConfig from 'postcss-load-config';
+import fallbackPostCSSConfig from '../configs/postcss.config.js';
+import { createLogger } from '../../../core/logging.js';
+
+const log = createLogger('assets-postcss');
+
+// Resolve user PostCSS config from the project root (cwd), not the Eleventy input dir.
+const configRoot = process.cwd();
+let cachedConfig = null;
+
+async function getPostCSSConfig() {
+	if (cachedConfig) return cachedConfig;
+
+	try {
+		// Prefer the consuming project's PostCSS config (postcss.config.* or package.json#postcss).
+		cachedConfig = await loadPostCSSConfig({}, configRoot);
+	} catch {
+		// If none is found, fall back to the bundled Baseline config to keep builds working.
+		const { plugins, ...options } = fallbackPostCSSConfig;
+		cachedConfig = { plugins, options };
+	}
+	return cachedConfig;
+}
+
+/**
+ * Process a CSS file through PostCSS.
+ * Reads from disk, uses project postcss.config.js or bundled fallback.
+ * Config is cached for the lifetime of the process.
+ *
+ * @param {string} cssFilePath - Absolute path to the entry file.
+ * @returns {Promise<string>} Processed CSS text, or an error comment on failure.
+ */
+export default async function assetsPostCSS(cssFilePath) {
+	try {
+		const cssContent = await fs.readFile(cssFilePath, 'utf8');
+		const { plugins, options } = await getPostCSSConfig();
+
+		const result = await postcss(plugins).process(cssContent, {
+			...options,
+			from: cssFilePath
+		});
+
+		// Return raw CSS; markup wrapping is handled in the plugin registration.
+		return result.css;
+	} catch (error) {
+		log.error('PostCSS failed:', error);
+		// Surface a safe CSS string so the caller can decide how to wrap it.
+		return '/* Error processing CSS */';
+	}
+}

package/modules/assets/schema.js

@@ -0,0 +1,14 @@
+import * as z from 'zod';
+
+// Structural schema for the `options.assets` slice. Permissive on unknown
+// keys (esbuild accepts many options we don't touch); strict on the keys the
+// plugin itself reads.
+
+export const esbuildOptionsSchema = z.looseObject({
+	minify: z.boolean().optional(),
+	target: z.string().optional()
+});
+
+export const optionsSchema = z.looseObject({
+	esbuild: esbuildOptionsSchema.optional()
+});

package/modules/head/drivers/capo-adapter.js

@@ -0,0 +1,72 @@
+/**
+ * capo.js adapter for PostHTML AST nodes.
+ *
+ * Implements the HTMLAdapter interface capo.js v2 uses to compute element
+ * weights (src/adapters/adapter.js in @rviscomi/capo.js). Only getWeight is
+ * consumed downstream; the rest are shimmed to satisfy the shape.
+ *
+ * A PostHTML element node looks like `{ tag, attrs, content }` where attrs
+ * is either undefined or a plain object. Boolean attributes appear with an
+ * empty-string value (`{ async: '' }`) or as `true`.
+ */
+
+const hasAttr = (node, name) => {
+	if (!node || !node.attrs) return false;
+	const key = name.toLowerCase();
+	for (const k of Object.keys(node.attrs)) {
+		if (k.toLowerCase() === key) return true;
+	}
+	return false;
+};
+
+const getAttr = (node, name) => {
+	if (!node || !node.attrs) return null;
+	const key = name.toLowerCase();
+	for (const k of Object.keys(node.attrs)) {
+		if (k.toLowerCase() === key) {
+			const v = node.attrs[k];
+			return v === true ? '' : v == null ? null : String(v);
+		}
+	}
+	return null;
+};
+
+const getText = (node) => {
+	if (!node || node.content == null) return '';
+	if (typeof node.content === 'string') return node.content;
+	if (Array.isArray(node.content)) return node.content.filter((c) => typeof c === 'string').join('');
+	return '';
+};
+
+export const capoPosthtmlAdapter = {
+	isElement(node) {
+		return !!(node && typeof node === 'object' && typeof node.tag === 'string');
+	},
+	getTagName(node) {
+		return node && typeof node.tag === 'string' ? node.tag.toLowerCase() : '';
+	},
+	getAttribute(node, name) {
+		return getAttr(node, name);
+	},
+	hasAttribute(node, name) {
+		return hasAttr(node, name);
+	},
+	getAttributeNames(node) {
+		return node && node.attrs ? Object.keys(node.attrs) : [];
+	},
+	getTextContent(node) {
+		return getText(node);
+	},
+	getChildren() {
+		return [];
+	},
+	getParent() {
+		return null;
+	},
+	getSiblings() {
+		return [];
+	},
+	stringify(node) {
+		return node && node.tag ? `<${node.tag}>` : '';
+	}
+};

package/modules/head/drivers/posthtml-head-elements.js

@@ -0,0 +1,140 @@
+import { getWeight, ElementWeights } from '@rviscomi/capo.js';
+import { capoPosthtmlAdapter as adapter } from './capo-adapter.js';
+import { dedupeMeta, dedupeLink } from '../utils/dedupe.js';
+
+/**
+ * PostHTML head driver (driver)
+ *
+ * Default head renderer. Emits standard meta tags, layers user extras and
+ * hreflang alternates on top, dedupes, capo-sorts, and replaces the
+ * <baseline-head> placeholder with the result.
+ *
+ * Architecture layer:
+ *   module (driver inside head)
+ *
+ * System role:
+ *   The seam between head's pipeline and the renderer choice. Alternate
+ *   drivers can be substituted at the import site without changing the
+ *   cascade-time seed builder.
+ *
+ * Lifecycle:
+ *   transform-time → emit, dedupe, sort, mutate the PostHTML tree
+ *
+ * Why this exists:
+ *   Splitting the renderer from the seed builder lets head swap rendering
+ *   strategies (e.g. a future direct-DOM driver) without touching cascade
+ *   wiring or the page-context shape.
+ *
+ * Scope:
+ *   Owns node emission, dedupe orchestration, capo sort, and placeholder
+ *   replacement.
+ *   Does not own seed shape (page context), hreflang building
+ *   (head/utils/alternates.js), or capo's element weights (capo.js).
+ *
+ * Data flow:
+ *   seeds + alternates + options → emit → dedupe → capo-sort → PostHTML
+ *   tree mutation
+ *
+ * @param {Object} args
+ * @param {Object} args.seeds - Page context for the current page.
+ * @param {Array<Object>} args.alternates - hreflang link descriptors.
+ * @param {Object} args.options - Head options (titleSeparator, showGenerator).
+ * @param {string} args.placeholderTag - Placeholder element to replace.
+ * @param {string} args.eol - End-of-line separator interleaved between nodes.
+ * @param {Object} args.log - Scoped logger.
+ * @returns {(tree: Object) => Object} PostHTML plugin function.
+ */
+export function renderHead({ seeds, alternates, options, placeholderTag, eol, log }) {
+	const defaults = emitMeta(seeds.meta, seeds.render, options);
+	const extras = emitExtras(seeds.head, alternates);
+
+	const deduped = dedupeAll([...defaults, ...extras]);
+	const sorted = capoSort(deduped);
+
+	return function rendererPlugin(tree) {
+		// log.info('injecting head for', seeds.page.inputPath || seeds.page.url);
+		tree.match({ tag: placeholderTag }, () => ({
+			tag: 'head',
+			content: interleaveEOL(sorted, eol)
+		}));
+		return tree;
+	};
+}
+
+function emitMeta(meta, render, options) {
+	const nodes = [];
+	nodes.push(mkMeta({ charset: 'UTF-8' }));
+	nodes.push(mkMeta({ name: 'viewport', content: 'width=device-width, initial-scale=1.0' }));
+	if (meta.title) nodes.push({ tag: 'title', content: [meta.title] });
+	if (meta.description) nodes.push(mkMeta({ name: 'description', content: meta.description }));
+	nodes.push(mkMeta({ name: 'robots', content: meta.robots }));
+	if (meta.canonical) nodes.push(mkLink({ rel: 'canonical', href: meta.canonical }));
+	if (options.showGenerator && render.generator) {
+		nodes.push(mkMeta({ name: 'generator', content: render.generator }));
+	}
+
+	return nodes;
+}
+
+function emitExtras(head, alternates = []) {
+	const nodes = [];
+	for (const m of asArray(head?.meta)) nodes.push(mkMeta(m));
+	for (const l of asArray(head?.link)) {
+		if (l?.rel === 'canonical') continue; // 🚨 remove duplication source
+		nodes.push(mkLink(l));
+	}
+	for (const s of asArray(head?.script)) nodes.push(mkScript(s));
+	for (const s of asArray(head?.style)) nodes.push(mkStyle(s));
+	for (const a of alternates) nodes.push(mkLink(a));
+
+	return nodes;
+}
+
+function dedupeAll(nodes) {
+	const metas = [];
+	const links = [];
+	const others = [];
+	for (const n of nodes) {
+		if (n.tag === 'meta') metas.push(n.attrs || {});
+		else if (n.tag === 'link') links.push(n.attrs || {});
+		else others.push(n);
+	}
+	const dedupedMetas = dedupeMeta(metas).map(mkMeta);
+	const dedupedLinks = dedupeLink(links).map(mkLink);
+
+	return [...dedupedMetas, ...dedupedLinks, ...others];
+}
+
+function capoSort(nodes) {
+	const weighted = nodes.map((node, i) => ({
+		node,
+		i,
+		weight: adapter.isElement(node) ? getWeight(node, adapter) : ElementWeights.OTHER
+	}));
+	weighted.sort((a, b) => b.weight - a.weight || a.i - b.i);
+
+	return weighted.map((w) => w.node);
+}
+
+function mkMeta(attrs) {
+	return { tag: 'meta', attrs };
+}
+function mkLink(attrs) {
+	return { tag: 'link', attrs };
+}
+function mkScript(entry) {
+	const { content, ...attrs } = entry || {};
+	return content !== undefined ? { tag: 'script', attrs, content: [content] } : { tag: 'script', attrs };
+}
+function mkStyle(entry) {
+	const { content, ...attrs } = entry || {};
+	return content !== undefined ? { tag: 'style', attrs, content: [content] } : { tag: 'style', attrs };
+}
+function asArray(v) {
+	return Array.isArray(v) ? v : [];
+}
+function interleaveEOL(nodes, eol) {
+	const out = [];
+	for (const n of nodes) out.push(n, eol);
+	return out;
+}

package/modules/head/index.js

@@ -0,0 +1,106 @@
+import { renderHead } from './drivers/posthtml-head-elements.js';
+import { buildAlternates } from './utils/alternates.js';
+import { optionsSchema } from './schema.js';
+
+// Internal constants — not user-facing.
+const PLACEHOLDER_TAG = 'baseline-head';
+const EOL = '\n';
+
+/**
+ * Head (module)
+ *
+ * Render-time <head> composer. Turns the normalised page context into a
+ * sorted, deduped element list and replaces <baseline-head> in the output.
+ *
+ * Architecture layer:
+ *   module
+ *
+ * System role:
+ *   Consumes the page context (built at cascade-time) and the translation
+ *   map (written at cascade-time) to produce the final <head> at
+ *   transform-time.
+ *
+ * Lifecycle:
+ *   cascade-time   → upstream page-context registry builds the per-page seeds
+ *   transform-time → PostHTML plugin reads seeds, emits nodes, capo-sorts,
+ *                    replaces <baseline-head>
+ *
+ * Why this exists:
+ *   Eleventy's htmlTransformer context exposes only page metadata, not the
+ *   full data cascade. Pre-built seeds in the page-context registry carry
+ *   every field the composer needs from cascade-time into transform-time.
+ *
+ * Scope:
+ *   Owns transform-time composition and placeholder replacement.
+ *   Pass 1 covers bucket 1 only: charset, viewport, title, description,
+ *   robots, canonical, optional generator, plus user extras from
+ *   settings.head and hreflang alternates. SEO and JSON-LD are later passes.
+ *   Does not own seed shape (page context) or driver internals.
+ *
+ * Data flow:
+ *   page context + translation-map store + settings.head → driver →
+ *   PostHTML tree mutation (replaces <baseline-head>)
+ *
+ * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
+ * @param {Object} moduleContext
+ */
+export function headCore(eleventyConfig, moduleContext) {
+	const { state, runtime, log } = moduleContext;
+	const { settings, options } = state;
+
+	// Structural-only options check: log on mismatch, do not throw.
+	const parsed = optionsSchema.safeParse(options.head);
+	if (!parsed.success) {
+		for (const issue of parsed.error.issues) {
+			log.info('options:', `${issue.path.join('.')} — ${issue.message}`);
+		}
+	}
+
+	const pageContextRegistry = moduleContext.resolvePageContext;
+
+	// Resolved plugin options with defaults.
+	const headOptions = {
+		titleSeparator: options.head?.titleSeparator ?? ' – ',
+		showGenerator: options.head?.showGenerator ?? false
+	};
+
+	// Per-build stats (cleared on eleventy.after for watch-mode reruns).
+	const headStats = { pages: new Set() };
+
+	eleventyConfig.on('eleventy.after', () => {
+		log.info({
+			message: 'Head injection summary',
+			totalPages: headStats.pages.size,
+			sample: Array.from(headStats.pages).slice(0, 10)
+		});
+		headStats.pages.clear();
+	});
+
+	// --- Transform-time: compose and inject. ---
+	log.info('Injecting heads to pages');
+	eleventyConfig.htmlTransformer.addPosthtmlPlugin('html', function (context) {
+		headStats.pages.add(context?.page?.inputPath || context?.outputPath);
+
+		const key = context?.page?.url ?? context?.page?.inputPath;
+		const seeds = pageContextRegistry?.getByKey(key);
+		if (!seeds) {
+			log.warn('no head seeds for', context?.page?.inputPath || context?.outputPath);
+			return (tree) => tree;
+		}
+
+		const translationKey = seeds.page?.locale?.translationKey;
+
+		const alternates = translationKey
+			? buildAlternates(seeds.page?.locale?.translationKey, runtime.translationMap.get(), seeds.site?.url)
+			: [];
+
+		return renderHead({
+			seeds,
+			alternates,
+			options: headOptions,
+			placeholderTag: PLACEHOLDER_TAG,
+			eol: EOL,
+			log
+		});
+	});
+}

package/modules/head/schema.js

@@ -0,0 +1,42 @@
+import * as z from 'zod';
+
+// Structural schemas for head-core. Permissive on unknown keys, typed on
+// keys the driver reads. Non-throwing at the call site — safeParse only.
+
+// `options.head` slice: render-behaviour knobs.
+export const optionsSchema = z.looseObject({
+	titleSeparator: z.string().optional(),
+	showGenerator: z.boolean().optional()
+});
+
+// `settings.head` extras slot: additive link/script/meta/style arrays.
+export const settingsHeadSchema = z.looseObject({
+	link: z.array(z.looseObject({})).optional(),
+	script: z.array(z.looseObject({})).optional(),
+	meta: z.array(z.looseObject({})).optional(),
+	style: z.array(z.looseObject({})).optional()
+});
+
+// `settings.seo` site-default SEO scalars, page-overridable.
+export const settingsSeoSchema = z.looseObject({
+	ogImage: z.string().optional(),
+	twitterSite: z.string().optional()
+});
+
+// Page-level `seo:` block. Same scalar set as bare front matter, namespaced.
+// `seo.foo` wins over bare `foo`.
+export const pageSeoSchema = z.looseObject({
+	title: z.string().optional(),
+	description: z.string().optional(),
+	noindex: z.boolean().optional(),
+	canonical: z.string().optional(),
+	ogTitle: z.string().optional(),
+	ogDescription: z.string().optional(),
+	ogType: z.string().optional(),
+	ogImage: z.string().optional(),
+	twitterCard: z.string().optional(),
+	twitterSite: z.string().optional(),
+	twitterTitle: z.string().optional(),
+	twitterDescription: z.string().optional(),
+	twitterImage: z.string().optional()
+});

package/modules/head/utils/alternates.js

@@ -0,0 +1,11 @@
+export function buildAlternates(translationKey, translationsMap, siteUrl) {
+	if (!translationKey || !translationsMap) return [];
+	const variants = translationsMap[translationKey];
+	if (!variants) return [];
+	return Object.values(variants).flatMap((entry) => {
+		if (!entry?.url) return [];
+		const href = siteUrl ? new URL(entry.url, siteUrl).href : entry.url;
+		const link = { rel: 'alternate', hreflang: entry.lang, href };
+		return entry.isDefaultLang ? [link, { ...link, hreflang: 'x-default' }] : [link];
+	});
+}

package/modules/head/utils/dedupe.js

@@ -0,0 +1,47 @@
+/**
+ * Deduplicate meta tags. Last-wins by key (charset, name, property, http-equiv).
+ * Preserves insertion order after dedup.
+ * @param {Array<Object>} [arr=[]] - Array of meta tag objects.
+ * @returns {Array<Object>}
+ */
+function metaKey(meta) {
+	if (meta.charset) return 'charset';
+	if (meta.name) return `name:${meta.name}`;
+	if (meta.property) return `prop:${meta.property}`;
+	if (meta['http-equiv']) return `http:${meta['http-equiv']}`;
+	return null;
+}
+
+export const dedupeMeta = (arr = []) => {
+	const seen = new Set();
+	const out = [];
+
+	for (let i = arr.length - 1; i >= 0; i--) {
+		const key = metaKey(arr[i]);
+		if (!key || seen.has(key)) continue;
+		seen.add(key);
+		out.push(arr[i]);
+	}
+
+	return out.reverse();
+};
+
+/**
+ * Deduplicate link tags by rel+hreflang+href. Last-wins, preserves insertion order.
+ * @param {Array<Object>} [links=[]] - Array of link tag objects.
+ * @returns {Array<Object>}
+ */
+export const dedupeLink = (links = []) => {
+	const seen = new Set();
+	const out = [];
+
+	for (let i = links.length - 1; i >= 0; i--) {
+		const link = links[i];
+		const key = link.rel && link.href ? `rel:${link.rel}|hreflang:${link.hreflang ?? ''}|${link.href}` : null;
+		if (!key || seen.has(key)) continue;
+		seen.add(key);
+		out.push(link);
+	}
+
+	return out.reverse();
+};