@getvitops/astro 0.9.0 → 2.0.0

package/dist/index.mjs

@@ -1,11 +1,229 @@
-import { cpSync, existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { cpSync, existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { faviconLinks, generateFavicons, writeFaviconManifest } from "@getvitops/utils";
+import { isSiteConfig, resolveSiteConfig } from "@getvitops/generator";
+import { collectIconRefs, faviconLinks, generateFavicons, generateIconInclude, resolveIcon, scanFiles, writeFaviconManifest } from "@getvitops/utils";
 import vitops from "@getvitops/vite";
+import { fontProviders } from "astro/config";
 
 export * from "@getvitops/utils"
 
+//#region src/analytics.ts
+/**
+* IDs land inside an inline `<script>`, so they are checked rather than trusted.
+* A `<\/script>` in a measurement ID is not a plausible accident, but the cost of
+* the guard is one regex and the cost of not having it is arbitrary script
+* injection from a config file.
+*/
+const SAFE_ID = /^[\w.-]+$/;
+function bad(value) {
+	return !SAFE_ID.test(value);
+}
+/** JSON is a subset of JS object-literal syntax; `<` can't appear unescaped. */
+function literal(value) {
+	return JSON.stringify(value).replaceAll("<", "\\u003c");
+}
+function googleAnalytics(input) {
+	const opts = typeof input === "string" ? { id: input } : input;
+	if (bad(opts.id)) return `googleAnalytics: "${opts.id}" is not a valid measurement ID. Skipped.`;
+	const config = opts.config ? `,${literal(opts.config)}` : "";
+	return {
+		key: "googleAnalytics",
+		provider: "Google Analytics",
+		category: opts.category ?? "analytics",
+		setsCookies: true,
+		cookies: [
+			"_ga",
+			"_ga_*",
+			"_gid",
+			"_gat",
+			"_gat_*"
+		],
+		strategy: "idle",
+		gated: true,
+		inline: `window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments)}gtag('js',new Date());gtag('config','${opts.id}'${config});`,
+		src: `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(opts.id)}`,
+		attrs: {}
+	};
+}
+function clarity(input) {
+	const opts = typeof input === "string" ? { id: input } : input;
+	if (bad(opts.id)) return `clarity: "${opts.id}" is not a valid project ID. Skipped.`;
+	const category = opts.category ?? "analytics";
+	return {
+		key: "clarity",
+		provider: "Microsoft Clarity",
+		category,
+		setsCookies: true,
+		cookies: [
+			"_clck",
+			"_clsk",
+			"MUID",
+			"CLID",
+			"ANONCHK",
+			"SM"
+		],
+		strategy: "idle",
+		gated: true,
+		inline: `(function(c,l,a,r,i,t,y){c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y)})(window,document,"clarity","script","${opts.id}");window.clarity('consentv2',{ad_Storage:'${category === "marketing" ? "granted" : "denied"}',analytics_Storage:'granted'});`,
+		src: null,
+		attrs: {}
+	};
+}
+function matomo(opts) {
+	const siteId = String(opts.siteId);
+	if (bad(siteId)) return `matomo: "${siteId}" is not a valid site ID. Skipped.`;
+	let base;
+	try {
+		base = new URL(opts.url);
+	} catch {
+		return `matomo: "${opts.url}" is not a valid URL. Skipped.`;
+	}
+	const url = `${base.origin}${base.pathname.replace(/\/*$/, "")}/`;
+	const cookies = opts.cookies === true;
+	return {
+		key: "matomo",
+		provider: "Matomo",
+		category: cookies ? "analytics" : "necessary",
+		setsCookies: cookies,
+		cookies: cookies ? [
+			"_pk_id*",
+			"_pk_ses*",
+			"_pk_ref*",
+			"_pk_cvar*",
+			"_pk_hsr*"
+		] : [],
+		strategy: "idle",
+		gated: true,
+		inline: `var _paq=window._paq=window._paq||[];` + (cookies ? "" : `_paq.push(['disableCookies']);`) + `_paq.push(['trackPageView']);_paq.push(['enableLinkTracking']);(function(){var u="${url}";_paq.push(['setTrackerUrl',u+'matomo.php']);_paq.push(['setSiteId','${siteId}']);var d=document,g=d.createElement('script'),s=d.getElementsByTagName('script')[0];g.async=true;g.src=u+'matomo.js';s.parentNode.insertBefore(g,s)})();`,
+		src: null,
+		attrs: {}
+	};
+}
+function plausible(input) {
+	const opts = typeof input === "string" ? { domain: input } : input;
+	if (bad(opts.domain)) return `plausible: "${opts.domain}" is not a valid domain. Skipped.`;
+	return {
+		key: "plausible",
+		provider: "Plausible Analytics",
+		category: "necessary",
+		setsCookies: false,
+		cookies: [],
+		strategy: "idle",
+		gated: true,
+		inline: "",
+		src: opts.src ?? "https://plausible.io/js/script.js",
+		attrs: { "data-domain": opts.domain }
+	};
+}
+/**
+* Resolve the configured providers into the tags to emit.
+*
+* An invalid provider is dropped with a warning rather than throwing: one
+* malformed ID should not take down a build, and a missing tag is visible in the
+* output while a failed build is just a red wall.
+*/
+function resolveAnalytics(opts, ctx = {}) {
+	const warnings = [];
+	const tags = [];
+	if (!opts) return {
+		tags,
+		needsRuntime: false,
+		warnings
+	};
+	const strategy = opts.strategy ?? "idle";
+	const results = [
+		opts.googleAnalytics === void 0 ? null : googleAnalytics(opts.googleAnalytics),
+		opts.clarity === void 0 ? null : clarity(opts.clarity),
+		opts.matomo === void 0 ? null : matomo(opts.matomo),
+		opts.plausible === void 0 ? null : plausible(opts.plausible)
+	];
+	for (const result of results) {
+		if (result === null) continue;
+		if (typeof result === "string") {
+			warnings.push(result);
+			continue;
+		}
+		const gated = result.category !== "necessary" || strategy !== "async";
+		tags.push({
+			...result,
+			strategy,
+			gated
+		});
+	}
+	const setting = tags.filter((t) => t.setsCookies);
+	if (setting.length && !ctx.consent) warnings.push(`${setting.map((t) => t.provider).join(" and ")} ${setting.length === 1 ? "sets" : "set"} cookies (${setting.flatMap((t) => t.cookies).join(", ")}) and \`consent\` is off, so ${setting.length === 1 ? "it loads" : "they load"} for every visitor with no way to decline. Set \`consent: true\`, or switch to a cookieless provider (Plausible, or Matomo with its default \`cookies: false\`).`);
+	return {
+		tags,
+		needsRuntime: tags.some((t) => t.gated),
+		warnings
+	};
+}
+/** Which optional categories a set of tags actually needs a visitor to decide. */
+function consentCategories(tags) {
+	const used = /* @__PURE__ */ new Set();
+	for (const tag of tags) if (tag.category !== "necessary") used.add(tag.category);
+	return [
+		"analytics",
+		"marketing",
+		"preferences"
+	].filter((c) => used.has(c));
+}
+
+//#endregion
+//#region src/fonts.ts
+/**
+* Provider names, matching `fontProviders`' keys 1:1 (verified against astro@7.1.2).
+* The generator's `SiteFontSchema` enumerates the same set, so a mismatch is a
+* compile-time-invisible drift — `resolveFonts` throws on an unknown name rather than
+* quietly dropping the family and leaving the token resolving to a fallback stack.
+*/
+const PROVIDERS = new Set(Object.keys(fontProviders));
+/**
+* Providers a declaration can construct with no arguments.
+*
+* `adobe` is the one that can't: `fontProviders.adobe({ id })` takes a project API id,
+* and the point of that id being an argument is that it comes from the environment. A
+* JSON declaration has nowhere to put `process.env.ADOBE_ID` without either inlining the
+* key into a committed file or inventing an interpolation syntax, so Adobe families are
+* declared in `astro.config` directly — see the error thrown below.
+*/
+const NEEDS_OPTIONS = new Set(["adobe"]);
+/**
+* Map declarations onto Astro's `fonts:` entries.
+*
+* `preload` is dropped from the Astro entry on purpose — it is not part of the config
+* schema there, it is a prop on the `<Font />` component. It rides along in `head`
+* instead, which is what makes preload a property of the declaration rather than
+* something the consumer hand-picks in their layout.
+*/
+function resolveFonts(decls) {
+	const fonts = [];
+	const head = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const decl of decls) {
+		if (!PROVIDERS.has(decl.provider)) throw new Error(`[getvitops] fonts: unknown provider "${decl.provider}" for "${decl.name}". Astro provides: ${[...PROVIDERS].sort().join(", ")}.`);
+		if (NEEDS_OPTIONS.has(decl.provider)) throw new Error(`[getvitops] fonts: provider "${decl.provider}" needs an API id from your environment ("${decl.name}"), and a JSON declaration has nowhere to hold one. Declare this family in astro.config instead — fonts: [{ provider: fontProviders.${decl.provider}({ id: process.env.ADOBE_ID }), name: '${decl.name}', cssVariable: '${decl.cssVariable}' }] — and render its <Font /> yourself; the design-system token can still point at it.`);
+		if (!decl.cssVariable.startsWith("--")) throw new Error(`[getvitops] fonts: cssVariable "${decl.cssVariable}" (${decl.name}) must start with "--".`);
+		if (seen.has(decl.cssVariable)) throw new Error(`[getvitops] fonts: two families both declare ${decl.cssVariable} (the second is "${decl.name}"). Astro resolves one family per variable — give them separate variables, or drop one.`);
+		seen.add(decl.cssVariable);
+		const { provider, preload, ...rest } = decl;
+		fonts.push({
+			...rest,
+			provider: fontProviders[provider]()
+		});
+		head.push({
+			cssVariable: decl.cssVariable,
+			preload: preload ?? false
+		});
+	}
+	return {
+		fonts,
+		head
+	};
+}
+
+//#endregion
 //#region src/integration.ts
 /**
 * @getvitops/astro — the Astro integration. One entry wires the design system's
@@ -16,6 +234,35 @@ export * from "@getvitops/utils"
 * The `<Head />` component (shipped alongside) renders the tags, reading resolved
 * config from the `virtual:getvitops/head` module this integration provides.
 */
+/**
+* Which providers `getvitops({ analytics })` configures that the site config's
+* own `analytics` block does not.
+*
+* The two are separate surfaces on purpose — the integration must not import
+* `SiteConfig` — but they describe the same site, and a disagreement between them
+* is a compliance defect rather than a style issue: `vitops legal` derives the
+* cookie notice from the site config, so a provider missing there is a tag the
+* site runs and its own notice never mentions. That is precisely what the
+* generator's processor table exists to prevent.
+*
+* Read is best-effort — the `legal` step already reports an unreadable config,
+* and a second copy of that error helps nobody.
+*/
+const SITE_CONFIG_KEYS = {
+	googleAnalytics: "googleAnalyticsId",
+	clarity: "clarityId",
+	matomo: "matomo",
+	plausible: "plausibleDomain"
+};
+function undisclosedProviders(configPath, analytics) {
+	let declared;
+	try {
+		declared = JSON.parse(readFileSync(configPath, "utf8")).analytics ?? {};
+	} catch {
+		return [];
+	}
+	return Object.keys(SITE_CONFIG_KEYS).filter((key) => analytics[key] !== void 0 && !declared[SITE_CONFIG_KEYS[key]]);
+}
 const VIRTUAL_ID = "virtual:getvitops/head";
 const RESOLVED_ID = `\0${VIRTUAL_ID}`;
 function virtualHeadPlugin(data) {
@@ -29,6 +276,63 @@ function virtualHeadPlugin(data) {
 		}
 	};
 }
+const ICONS_ID = "virtual:getvitops/icons";
+const RESOLVED_ICONS_ID = `\0${ICONS_ID}`;
+function virtualIconsPlugin(data) {
+	return {
+		name: "@getvitops/astro:virtual-icons",
+		resolveId(id) {
+			return id === ICONS_ID ? RESOLVED_ICONS_ID : null;
+		},
+		load(id) {
+			return id === RESOLVED_ICONS_ID ? `export default ${JSON.stringify(data)};` : null;
+		}
+	};
+}
+/** Defaults live here so the component and the integration can't drift. */
+const ICON_DEFAULTS = {
+	ui: "fa7-solid",
+	brand: "simple-icons",
+	sprite: "/vitops/icons.svg",
+	scan: ["src"]
+};
+/**
+* Probe an optional icon integration so it can be registered for the consumer's
+* OWN `<Icon>` usage. Nothing here decides how our `<Icon />` renders — that is
+* `engine`, and it never needs a peer.
+*/
+/**
+* Indirection so the bundler can't resolve the specifier statically. See the
+* import site in the `tailwind` branch for why that matters.
+*/
+const TAILWIND_VITE = "@tailwindcss/vite";
+async function probeIconPackage(name) {
+	try {
+		await import(
+			/* @vite-ignore */
+			name
+);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Does the file at `path` hold a site config rather than a bare design system?
+*
+* Swallows a missing or unparseable file and answers `false`: this only decides
+* whether the other options may default their paths to this one, and the real
+* read happens in the Vite plugin, which reports a parse error properly. Failing
+* the build here would turn "your JSON has a trailing comma" into an error about
+* an option the consumer never set.
+*/
+function readsAsSiteConfig(path) {
+	try {
+		return isSiteConfig(JSON.parse(readFileSync(path, "utf8")));
+	} catch {
+		return false;
+	}
+}
 function getvitops(opts = {}) {
 	return {
 		name: "@getvitops/astro",
@@ -38,6 +342,26 @@ function getvitops(opts = {}) {
 			const webComponents = opts.webComponents !== false;
 			const editor = opts.editor === true;
 			if (editor && !opts.css) logger.warn("editor: true needs a `css` config — it reads design-manifest.json.");
+			if (opts.legal && !opts.css) logger.warn("legal: needs a `css` config — the generation runs in the Vite plugin that `css` registers. Run `npx vitops legal` instead if you do not use `css`.");
+			const cssInput = opts.css ? opts.css.input ?? "design-system.json" : void 0;
+			const siteInput = opts.site?.input ?? (cssInput != null && readsAsSiteConfig(resolve(root, cssInput)) ? cssInput : void 0);
+			if (opts.site && !opts.css) logger.warn("site: needs a `css` config — it is read during generation, which runs in the Vite plugin that `css` registers. Without it the site config changes nothing here.");
+			const legalInput = opts.legal?.input ?? siteInput;
+			if (opts.legal && !legalInput) throw new Error("[getvitops] legal: needs `legal.input` (a site config path), the top-level `site` option, or a `css.input` that is itself a site config.");
+			if (opts.seo) {
+				if (!config.site) logger.warn("seo: needs the `site` astro.config option (your deployed URL) — without it <Seo /> omits canonical, og:url and any relative og:image rather than guessing an origin.");
+				if (config.integrations.some((i) => i.name === "emdash")) logger.warn("seo: emdash() is registered, and its <EmDashHead> emits the same title/description/canonical/og tags from the CMS. Use one or the other — rendering both duplicates every tag.");
+			}
+			const consentEnabled = !!opts.consent;
+			const consentOpts = typeof opts.consent === "object" ? opts.consent : {};
+			const analytics = resolveAnalytics(opts.analytics, { consent: consentEnabled });
+			const detectedCategories = consentCategories(analytics.tags);
+			const offeredCategories = consentOpts.categories ?? (detectedCategories.length ? detectedCategories : ["analytics"]);
+			for (const warning of analytics.warnings) logger.warn(warning);
+			if (opts.analytics && legalInput) {
+				const undisclosed = undisclosedProviders(resolve(root, legalInput), opts.analytics);
+				if (undisclosed.length) logger.warn(`analytics: ${undisclosed.join(", ")} ${undisclosed.length === 1 ? "is" : "are"} configured here but absent from your site config's \`analytics\` block, so the cookie notice \`legal\` generates will not disclose ${undisclosed.length === 1 ? "it" : "them"}. Add ${undisclosed.map((k) => SITE_CONFIG_KEYS[k]).join(", ")} to ${legalInput}.`);
+			}
 			const hasManifest = !!(opts.favicon?.name && opts.favicon?.themeColor);
 			let hasSvg = false;
 			if (opts.favicon) {
@@ -46,7 +370,8 @@ function getvitops(opts = {}) {
 				await generateFavicons({
 					source,
 					outputDir: publicDir,
-					...opts.favicon.lowResSource ? { lowResSource: resolve(root, opts.favicon.lowResSource) } : {}
+					...opts.favicon.lowResSource ? { lowResSource: resolve(root, opts.favicon.lowResSource) } : {},
+					...opts.favicon.backgroundColor ? { backgroundColor: opts.favicon.backgroundColor } : {}
 				});
 				if (opts.favicon.name && opts.favicon.themeColor) await writeFaviconManifest(publicDir, {
 					name: opts.favicon.name,
@@ -55,16 +380,45 @@ function getvitops(opts = {}) {
 				});
 				logger.info("generated favicons + manifest → public/");
 			}
-			if (webComponents) {
+			let headFonts = [];
+			if (opts.fonts) {
+				const given = Array.isArray(opts.fonts) ? { families: opts.fonts } : typeof opts.fonts === "string" ? { input: opts.fonts } : opts.fonts === true ? {} : opts.fonts;
+				const o = {
+					...given,
+					...given.input == null && given.families == null && siteInput ? {
+						input: siteInput,
+						...opts.site?.siteEnv ? { siteEnv: opts.site.siteEnv } : {}
+					} : {}
+				};
+				const declared = [];
+				if (o.input) {
+					const site = resolveSiteConfig(JSON.parse(readFileSync(resolve(root, o.input), "utf8")), o.siteEnv ?? "production");
+					declared.push(...site.fonts ?? []);
+				}
+				declared.push(...o.families ?? []);
+				if (declared.length === 0) logger.warn("fonts: nothing declared — no webfonts will load. Add families, or drop the option.");
+				else {
+					const existing = new Set((config.fonts ?? []).map((f) => f.cssVariable));
+					const { fonts, head } = resolveFonts(declared);
+					for (const f of head) if (existing.has(f.cssVariable)) logger.warn(`fonts: ${f.cssVariable} is already declared in your astro.config \`fonts\` array. Astro resolves one family per variable, so one of the two will be dropped — remove it from one place.`);
+					updateConfig({ fonts });
+					headFonts = head;
+					const preloaded = head.filter((f) => f.preload !== false).length;
+					logger.info(`fonts: ${fonts.length} famil${fonts.length === 1 ? "y" : "ies"} registered via Astro's Fonts API (${preloaded} preloaded) — <Head /> emits <Font /> for each`);
+				}
+			}
+			const consentRuntime = consentEnabled || analytics.needsRuntime;
+			if (webComponents || consentRuntime) {
 				const coreDist = join(dirname(fileURLToPath(import.meta.resolve("@getvitops/core/package.json"))), "dist");
 				const dest = join(publicDir, "vitops");
 				if (existsSync(coreDist)) {
-					const bundles = [
+					const bundles = webComponents ? [
 						"polyfills.js",
 						"deferred.js",
 						"elements.js",
 						"polyfills"
-					];
+					] : [];
+					if (consentRuntime) bundles.push("consent.js");
 					if (editor) bundles.push("editor.js");
 					for (const f of bundles) {
 						const src = join(coreDist, f);
@@ -73,7 +427,107 @@ function getvitops(opts = {}) {
 					logger.info("copied web-component bundles → public/vitops/");
 				} else logger.warn(`@getvitops/core dist not found (${coreDist}); run build:core. Skipping WC copy.`);
 			}
-			updateConfig({ vite: { plugins: [virtualHeadPlugin({
+			let sitemapHref = null;
+			if (opts.sitemap) {
+				const registered = config.integrations.map((i) => i.name);
+				if (registered.includes("@astrojs/sitemap")) logger.info("sitemap: @astrojs/sitemap is already in your integrations — leaving yours in charge.");
+				else if (registered.includes("emdash")) logger.warn("sitemap: emdash() already serves /sitemap.xml from the database, which also covers on-demand pages a static sitemap cannot. Skipping — drop the `sitemap` option, or add @astrojs/sitemap to `integrations` yourself to run both.");
+				else if (!config.site) logger.warn("sitemap: needs the `site` astro.config option (your deployed URL) — a sitemap lists absolute URLs. Skipping.");
+				else {
+					let sitemap;
+					try {
+						({default: sitemap} = await import("@astrojs/sitemap"));
+					} catch {
+						throw new Error("[getvitops] sitemap requires `@astrojs/sitemap` in your devDependencies — install it, or drop the `sitemap` option.");
+					}
+					if (config.output === "server") logger.warn("sitemap: output: 'server' — @astrojs/sitemap lists prerendered routes only, so on-demand pages are left out. Add `export const prerender = true` to the pages you want indexed, or list them in `sitemap.customPages`.");
+					const sitemapOpts = opts.sitemap === true ? void 0 : opts.sitemap;
+					updateConfig({ integrations: [sitemap(sitemapOpts)] });
+					sitemapHref = `/${sitemapOpts?.filenameBase ?? "sitemap"}-index.xml`;
+					logger.info(`sitemap registered → ${sitemapHref.slice(1)}`);
+				}
+			}
+			let iconsData = null;
+			if (opts.icons) {
+				const o = opts.icons === true ? {} : opts.icons;
+				const ui = o.ui ?? ICON_DEFAULTS.ui;
+				const brand = o.brand ?? ICON_DEFAULTS.brand;
+				const spriteHref = o.sprite ?? ICON_DEFAULTS.sprite;
+				const weightOpt = o.weight ? { weight: o.weight } : {};
+				const include = o.include ? generateIconInclude({
+					ui,
+					brand,
+					...weightOpt,
+					...o.include
+				}) : {};
+				const add = (prefix, name) => {
+					const list = include[prefix] ??= [];
+					if (!list.includes(name)) list.push(name);
+				};
+				const scanDirs = o.scan === false ? [] : o.scan ?? [...ICON_DEFAULTS.scan];
+				const unresolved = [];
+				const dynamic = [];
+				for (const dir of scanDirs) {
+					const abs = resolve(root, dir);
+					if (!existsSync(abs)) continue;
+					const found = collectIconRefs(scanFiles(abs));
+					dynamic.push(...found.dynamic.map((d) => ({
+						file: relative(root, d.file),
+						line: d.line,
+						expr: d.expr
+					})));
+					for (const name of found.names) {
+						const colon = name.indexOf(":");
+						if (colon > 0) {
+							add(name.slice(0, colon), name.slice(colon + 1));
+							continue;
+						}
+						try {
+							const q = resolveIcon(name, ui, weightOpt);
+							add(q.slice(0, q.indexOf(":")), q.slice(q.indexOf(":") + 1));
+						} catch {
+							unresolved.push(name);
+						}
+					}
+				}
+				const wantsInclude = config.output !== "static";
+				if (dynamic.length && wantsInclude) logger.warn(`icons: ${dynamic.length} icon name(s) are computed at runtime and cannot be bundled automatically:\n` + dynamic.map((d) => `  ${d.file}:${d.line}  ${d.expr}`).join("\n") + `\n  Declare them in \`icons.include\` (or set \`icons.scan: false\` to silence this).`);
+				if (unresolved.length) logger.warn(`icons: ${unresolved.length} name(s) are not in the semantic map for '${ui}': ${unresolved.join(", ")}. Left as-is — fine for a local src/icons/*.svg or a sprite id, a typo otherwise.`);
+				const engine = o.engine ?? "inline";
+				if (o.sprite && !opts.css) logger.warn("icons: the sprite is written by the same pass that generates the CSS, so `sprite` without `css` produces no file. Add `css`, or run `vitops icons --sprite`.");
+				const already = config.integrations.map((i) => i.name).find((n) => n === "astro-icon" || n === "astro-iconset");
+				if (o.register === false) logger.info("icons: register: false — resolving names only, not registering anything.");
+				else if (already) logger.info(`icons: ${already} is already in your integrations — leaving yours in charge.`);
+				else {
+					const pkg = await probeIconPackage("astro-icon") ? "astro-icon" : await probeIconPackage("astro-iconset") ? "astro-iconset" : null;
+					if (pkg) {
+						const { default: icon } = await import(
+							/* @vite-ignore */
+							pkg
+);
+						updateConfig({ integrations: [icon(wantsInclude ? { include } : {})] });
+						logger.info(wantsInclude ? `icons: ${pkg} registered — bundling ${Object.values(include).flat().length} icon(s)` : `icons: ${pkg} registered (output: 'static' — no include needed)`);
+					}
+				}
+				iconsData = {
+					engine,
+					root,
+					ui,
+					brand,
+					weight: o.weight ?? null,
+					overrides: o.overrides ?? {},
+					sprite: engine === "sprite" || o.sprite ? spriteHref : null
+				};
+			}
+			updateConfig({ vite: { plugins: [virtualIconsPlugin(iconsData ?? {
+				engine: "none",
+				root,
+				ui: ICON_DEFAULTS.ui,
+				brand: ICON_DEFAULTS.brand,
+				weight: null,
+				overrides: {},
+				sprite: null
+			}), virtualHeadPlugin({
 				favicons: !!opts.favicon,
 				faviconLinks: opts.favicon ? faviconLinks({
 					hasSvg,
@@ -82,21 +536,42 @@ function getvitops(opts = {}) {
 				themeColor: opts.favicon?.themeColor ?? null,
 				webComponents,
 				wcBase: "/vitops",
-				editor
+				editor,
+				sitemap: sitemapHref,
+				fonts: headFonts,
+				site: config.site ?? null,
+				seo: opts.seo ?? {},
+				analytics: opts.analytics ?? {},
+				consent: consentEnabled,
+				consentCategories: offeredCategories,
+				consentPolicyUrl: consentOpts.policyUrl ?? null,
+				consentRuntime
 			})] } });
 			if (opts.css) {
 				const format = opts.css.format ?? "tailwind";
+				if (format === "design") throw new Error("[getvitops] css.format: 'design' emits only DESIGN.md, not a stylesheet. Run `npx vitops generate --format design --out .` for that file, and set css.format to 'tailwind' | 'css' | 'bricks' here.");
 				const out = opts.css.out ?? "src/styles";
 				const plugins = [vitops({
 					input: opts.css.input ?? "design-system.json",
+					...opts.css.theme != null ? { theme: opts.css.theme } : {},
 					format,
 					out,
-					...editor ? { editorManifestDir: publicDir } : {}
+					...editor ? { editorManifestDir: publicDir } : {},
+					...iconsData?.sprite ? { spriteDir: publicDir } : {},
+					...opts.legal ? { legal: {
+						...opts.legal,
+						input: legalInput
+					} } : {},
+					...opts.site ? { site: opts.site } : {},
+					...opts.css.systemColorScheme != null ? { systemColorScheme: opts.css.systemColorScheme } : {}
 				})];
 				if (format === "tailwind") {
 					let tailwindcss;
 					try {
-						({default: tailwindcss} = await import("@tailwindcss/vite"));
+						({default: tailwindcss} = await import(
+							/* @vite-ignore */
+							TAILWIND_VITE
+));
 					} catch {
 						throw new Error("[getvitops] css.format: 'tailwind' requires `tailwindcss` and `@tailwindcss/vite` in your devDependencies — install them, or switch to css.format: 'css' for the standalone bundle.");
 					}
@@ -115,5 +590,127 @@ function getvitops(opts = {}) {
 }
 
 //#endregion
-export { getvitops as default };
+//#region src/seo.ts
+/** `en-CA` → `en_CA`; Open Graph wants the underscore form. */
+const ogLocale = (locale) => locale.replace("-", "_");
+/**
+* Absolute URLs pass through; relative ones resolve against `site`, or are
+* dropped when there is no `site` to resolve them against. A relative `og:image`
+* or canonical is worse than none — crawlers resolve it against whatever origin
+* served the page.
+*/
+function absolute(url, site) {
+	if (!url) return null;
+	try {
+		return new URL(url).href;
+	} catch {
+		return site ? new URL(url, site).href : null;
+	}
+}
+/** Composes the robots directive, or null when nothing meaningful was asked for. */
+function resolveRobots(props, defaults) {
+	if (props.robots) return props.robots;
+	const { noindex, nofollow, noarchive, nocache, robotsExtras } = props;
+	if (noindex || nofollow || noarchive || nocache || robotsExtras) return [
+		noindex ? "noindex" : "index",
+		nofollow ? "nofollow" : "follow",
+		...noarchive ? ["noarchive"] : [],
+		...nocache ? ["nocache"] : [],
+		...robotsExtras ? [robotsExtras] : []
+	].join(", ");
+	return defaults.robots ?? null;
+}
+/**
+* Merges site defaults with page props into the final tag set.
+*
+* Pure — no `Astro`, no filesystem, no config lookup. Everything it needs comes
+* through its three arguments, which is what makes it testable and what keeps the
+* package free of the consumer-global coupling that sank the previous site model.
+*/
+function resolveSeo(defaults, props, ctx) {
+	const { site } = ctx;
+	const siteName = props.siteName ?? defaults.siteName ?? null;
+	const templated = props.title && defaults.titleTemplate && props.title !== siteName;
+	const fallbackTitle = defaults.defaultTitle ?? siteName;
+	const title = props.title ? templated ? String(defaults.titleTemplate).replaceAll("%s", props.title) : props.title : fallbackTitle;
+	const socialTitle = props.ogTitle ?? props.title ?? fallbackTitle;
+	const description = props.description ?? defaults.defaultDescription ?? null;
+	const canonical = props.canonical ? absolute(props.canonical, site) : site ? new URL(ctx.pathname + (ctx.search ?? ""), site).href : null;
+	const image = absolute(props.image, site) ?? absolute(defaults.openGraph?.image?.url, site);
+	const usingDefaultImage = !props.image;
+	const defaultImage = defaults.openGraph?.image;
+	const imageAlt = props.imageAlt ?? (usingDefaultImage ? defaultImage?.alt : void 0);
+	const imageWidth = props.imageWidth ?? (usingDefaultImage ? defaultImage?.width : void 0);
+	const imageHeight = props.imageHeight ?? (usingDefaultImage ? defaultImage?.height : void 0);
+	const imageType = props.imageType ?? (usingDefaultImage ? defaultImage?.type : void 0);
+	const type = props.type ?? defaults.openGraph?.type ?? "website";
+	const locale = props.locale ?? defaults.openGraph?.locale;
+	const openGraph = [];
+	const og = (property, content) => {
+		if (content !== null && content !== void 0 && content !== "") openGraph.push({
+			property,
+			content: String(content)
+		});
+	};
+	og("og:type", type);
+	og("og:title", socialTitle);
+	og("og:description", description);
+	og("og:url", canonical);
+	og("og:site_name", siteName);
+	og("og:locale", locale ? ogLocale(locale) : null);
+	for (const alt of defaults.openGraph?.localeAlternates ?? []) og("og:locale:alternate", ogLocale(alt));
+	og("og:image", image);
+	if (image) {
+		og("og:image:alt", imageAlt);
+		og("og:image:width", imageWidth);
+		og("og:image:height", imageHeight);
+		og("og:image:type", imageType);
+	}
+	if (type === "article" && props.article) {
+		const a = props.article;
+		og("article:published_time", a.publishedTime);
+		og("article:modified_time", a.modifiedTime);
+		og("article:expiration_time", a.expirationTime);
+		for (const author of a.authors ?? []) og("article:author", author);
+		og("article:section", a.section);
+		for (const tag of a.tags ?? []) og("article:tag", tag);
+	}
+	const twitter = [];
+	const tw = (name, content) => {
+		if (content) twitter.push({
+			name,
+			content
+		});
+	};
+	tw("twitter:card", image ? "summary_large_image" : defaults.twitter?.card ?? "summary");
+	tw("twitter:site", defaults.twitter?.site);
+	tw("twitter:creator", props.twitterCreator ?? defaults.twitter?.creator);
+	tw("twitter:title", socialTitle);
+	tw("twitter:description", description);
+	tw("twitter:image", image);
+	tw("twitter:image:alt", image ? imageAlt : null);
+	const verification = [];
+	if (defaults.googleSiteVerification) verification.push({
+		name: "google-site-verification",
+		content: defaults.googleSiteVerification
+	});
+	if (defaults.bingSiteVerification) verification.push({
+		name: "msvalidate.01",
+		content: defaults.bingSiteVerification
+	});
+	return {
+		title,
+		socialTitle,
+		description,
+		canonical,
+		robots: resolveRobots(props, defaults),
+		openGraph,
+		twitter,
+		verification,
+		alternates: props.alternates ?? []
+	};
+}
+
+//#endregion
+export { consentCategories, getvitops as default, resolveAnalytics, resolveSeo };
 //# sourceMappingURL=index.mjs.map