@lovrozagar/flare 0.1.0

package/src/ssr/critical-css.ts

@@ -0,0 +1,150 @@
+/** Manifest emitted by the sx-ast Vite plugin at build time. */
+export interface SxCssManifest {
+	version: 1;
+	hashVersion: string;
+	/** className → full CSS rule text (e.g. `.a1-abc12345 { color: red }`) */
+	rules: Record<string, string>;
+	/** Which layer each class belongs to. */
+	layerByRule: Record<string, "sx" | "app">;
+	/** moduleId → class names that module emits. Covers Show/Switch/handler branches. */
+	moduleManifest: Record<string, string[]>;
+	/** Final asset URL with Vite content hash. */
+	bundleHref: string;
+}
+
+export interface CriticalCssResult {
+	css: string;
+	bundleHref?: string;
+}
+
+export const CRITICAL_SHEET_ID = "flare-critical";
+
+/* Prod: a1-<8 base-36 chars>. Dev: sx-<prop>-<val>-<4 base-36 chars>. */
+const ATOMIC_CLASS_RE = /\bclass="([^"]*)"/g;
+const PROD_CLASS_RE = /^a1-[a-z0-9]{8}$/;
+const DEV_CLASS_RE = /^sx-/;
+
+function isAtomicClass(cls: string, manifestKeys?: Set<string>): boolean {
+	/* Manifest keys are the ground truth — raw Tailwind tokens (e.g. bg-accent) are valid
+	 * when the sx plugin emitted a rule for them (pass-through / non-hashed mode). */
+	if (manifestKeys?.has(cls)) return true;
+	return PROD_CLASS_RE.test(cls) || DEV_CLASS_RE.test(cls);
+}
+
+/** Scan rendered HTML and return the set of atomic/manifest class names present. */
+export function collectAtomicClasses(html: string, manifest?: SxCssManifest): Set<string> {
+	const manifestKeys = manifest ? new Set(Object.keys(manifest.rules)) : undefined;
+	const found = new Set<string>();
+	ATOMIC_CLASS_RE.lastIndex = 0;
+	let m: RegExpExecArray | null;
+	while ((m = ATOMIC_CLASS_RE.exec(html)) !== null) {
+		for (const cls of m[1].split(/\s+/)) {
+			if (cls && isAtomicClass(cls, manifestKeys)) found.add(cls);
+		}
+	}
+	return found;
+}
+
+/**
+ * Compute critical CSS from rendered HTML + module manifest.
+ *
+ * Returns empty string when manifest absent — caller skips injection.
+ */
+export function buildCriticalCss(
+	html: string,
+	renderedModules: string[],
+	manifest: SxCssManifest | undefined,
+): CriticalCssResult {
+	if (!manifest) return { css: "" };
+
+	/* Union: classes from HTML + classes from module-manifest for loaded modules */
+	const classes = collectAtomicClasses(html, manifest);
+	for (const modId of renderedModules) {
+		const modClasses = manifest.moduleManifest[modId];
+		if (modClasses) {
+			for (const cls of modClasses) classes.add(cls);
+		}
+	}
+
+	const sxRules: string[] = [];
+	const appRules: string[] = [];
+
+	for (const cls of classes) {
+		const rule = manifest.rules[cls];
+		if (!rule) continue;
+
+		const layer = manifest.layerByRule[cls] ?? "app";
+		if (layer === "sx") sxRules.push(rule);
+		else appRules.push(rule);
+	}
+
+	if (sxRules.length === 0 && appRules.length === 0) {
+		return { bundleHref: manifest.bundleHref, css: "" };
+	}
+
+	const parts: string[] = [];
+	/* Declare Tailwind's implicit layer order AND flare's sx/app layers before rules so
+	 * browser positions `app` AFTER `base` (bundle registers same names later — same
+	 * positions reused). Without these preludes the first `@layer app { }` encountered
+	 * creates `app` at position 1 (lowest), causing base's `h1{font-size:inherit}` to
+	 * beat `.text-4xl` and collapse typography. */
+	parts.push("@layer theme, base, components, utilities;");
+	parts.push("@layer reset, sx, app, user.lib, user.app, inline;");
+	if (sxRules.length > 0) parts.push(`@layer sx { ${sxRules.join(" ")} }`);
+	if (appRules.length > 0) parts.push(`@layer app { ${appRules.join(" ")} }`);
+
+	return { bundleHref: manifest.bundleHref, css: parts.join("\n") };
+}
+
+/**
+ * Inject empty critical-CSS placeholder + optional preload link before `</head>`.
+ * Called during head-injection phase (before body is known).
+ */
+export function injectCriticalPlaceholder(html: string, nonce: string, bundleHref?: string): string {
+	if (!html.includes("</head>")) return html;
+
+	const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+	let inject = `<style id="${CRITICAL_SHEET_ID}"${nonceAttr}></style>`;
+
+	if (bundleHref) {
+		const escapedHref = bundleHref.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+		inject += `<link rel="preload" as="style" href="${escapedHref}" onload="this.rel='stylesheet'"${nonceAttr}/>`;
+	}
+
+	return html.replace("</head>", `${inject}</head>`);
+}
+
+/**
+ * Scan body HTML, compute critical CSS, fill the `<style id="flare-critical">`
+ * placeholder in `<head>` (emitted upstream by injectHeadContent). Populating the
+ * head placeholder keeps the critical sheet outside Solid's render tree; emitting
+ * a fresh `<style>` near `</body>` left the tag as an unowned sibling that Solid's
+ * post-hydrate cleanup disposed during SPA nav, stripping utilities off the page.
+ */
+export function injectCriticalAppend(
+	html: string,
+	renderedModules: string[],
+	manifest: SxCssManifest | undefined,
+	nonce: string,
+): string {
+	if (!manifest) return html;
+
+	const { css } = buildCriticalCss(html, renderedModules, manifest);
+	if (!css) return html;
+
+	/* Escape </style> inside CSS to prevent tag injection */
+	const safeCSS = css.replace(/<\/style\b/gi, "<\\/style");
+
+	/* Fill the existing empty `<style id="flare-critical">…</style>` placeholder. */
+	const filled = html.replace(
+		/(<style id="flare-critical"[^>]*>)<\/style>/,
+		(_match, open) => `${open}${safeCSS}</style>`,
+	);
+	if (filled !== html) return filled;
+
+	/* Fallback: placeholder missing (non-standard head injection path) — keep the
+	 * old behaviour of appending before `</body>` so we don't silently drop styles. */
+	const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+	const tag = `<style data-flare-critical-append${nonceAttr}>${safeCSS}</style>`;
+	return html.replace("</body>", `${tag}</body>`);
+}

package/src/ssr/head-prefix.ts

@@ -0,0 +1,65 @@
+import { getDirectionScript, type DirectionConfig } from "../direction/index.tsx";
+import { getLocaleScript, type LocaleConfig } from "../locale/index.tsx";
+import type { ModulePreloads } from "../module-graph/index.ts";
+import type { HeadConfig } from "../route-builder/types.ts";
+import { getThemeScript, type ThemeConfig } from "../theme/index.tsx";
+
+function escapeAttr(str: string): string {
+	return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function colorSchemeCss(attribute: string): string {
+	const attr = attribute.replace(/[^\w-]/g, "") || "data-theme";
+	return `html{color-scheme:light}html[${attr}=dark]{color-scheme:dark}`;
+}
+
+export interface HeadPrefixOptions {
+	direction?: DirectionConfig;
+	locale?: LocaleConfig;
+	modulePreloads?: ModulePreloads;
+	nonce: string;
+	resolvedHead: HeadConfig;
+	theme?: ThemeConfig;
+}
+
+/**
+ * Blocking head prefix. Order is first-paint critical:
+ *   1. CSP nonce meta
+ *   2. viewport (if the app did not set one)
+ *   3. theme / direction / locale inline scripts — before any CSS or modulepreload
+ *   4. modulepreload + stylesheets
+ *
+ * Theme must run before stylesheets or first paint is unthemed until refresh
+ * (CSS cache + later ThemeProvider). Modulepreloads stay after the scripts so
+ * Chrome can still mark them isLinkPreload when CSP has no 'strict-dynamic'.
+ */
+export function buildHeadPrefix(options: HeadPrefixOptions): string {
+	const escapedNonce = escapeAttr(options.nonce);
+	let prefix = `<meta name="csp-nonce" nonce="${escapedNonce}">`;
+	if (options.resolvedHead.meta?.viewport === undefined) {
+		prefix += `<meta name="viewport" content="width=device-width, initial-scale=1">`;
+	}
+
+	const nonceAttr = ` nonce="${escapedNonce}"`;
+	const themeAttr = options.theme?.attribute ?? "data-theme";
+	prefix += `<script${nonceAttr}>${getThemeScript(options.theme)}</script>`;
+	prefix += `<style${nonceAttr}>${colorSchemeCss(themeAttr)}</style>`;
+
+	if (options.direction) {
+		prefix += `<script${nonceAttr}>${getDirectionScript(options.direction)}</script>`;
+	}
+	if (options.locale) {
+		prefix += `<script${nonceAttr}>${getLocaleScript(options.locale)}</script>`;
+	}
+
+	if (options.modulePreloads) {
+		for (const href of options.modulePreloads.js) {
+			prefix += `<link rel="modulepreload" href="${escapeAttr(href)}"/>`;
+		}
+		for (const href of options.modulePreloads.css) {
+			prefix += `<link rel="stylesheet" href="${escapeAttr(href)}"/>`;
+		}
+	}
+
+	return prefix;
+}

package/src/ssr/head.ts

@@ -0,0 +1,259 @@
+import type { HeadConfig, SeoImage } from "../route-builder/types.ts";
+
+function escapeHtml(str: string): string {
+	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function escapeAttr(str: string): string {
+	return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+const VALID_ATTR_RE = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+
+function isSafeAttrName(name: string): boolean {
+	if (!VALID_ATTR_RE.test(name)) return false;
+	if (name.length > 2 && name[0] === "o" && name[1] === "n") return false;
+	if (name.length > 2 && name[0] === "O" && name[1] === "N") return false;
+	return !name.toLowerCase().startsWith("on");
+}
+
+function renderOgImage(parts: string[], img: SeoImage): void {
+	parts.push(`<meta property="og:image" content="${escapeAttr(img.url)}">`);
+	if (img.width) parts.push(`<meta property="og:image:width" content="${img.width}">`);
+	if (img.height) parts.push(`<meta property="og:image:height" content="${img.height}">`);
+	if (img.type) parts.push(`<meta property="og:image:type" content="${escapeAttr(img.type)}">`);
+	if (img.alt) parts.push(`<meta property="og:image:alt" content="${escapeAttr(img.alt)}">`);
+}
+
+export function renderHeadToHtml(head: HeadConfig, nonce: string): string {
+	const parts: string[] = [];
+
+	if (head.title !== undefined) {
+		parts.push(`<title>${escapeHtml(head.title)}</title>`);
+	}
+
+	if (head.description !== undefined) {
+		parts.push(`<meta name="description" content="${escapeAttr(head.description)}">`);
+	}
+
+	if (head.canonical !== undefined) {
+		parts.push(`<link rel="canonical" href="${escapeAttr(head.canonical)}">`);
+	}
+
+	if (head.keywords !== undefined) {
+		parts.push(`<meta name="keywords" content="${escapeAttr(head.keywords)}">`);
+	}
+
+	if (head.robots) {
+		const directives: string[] = [];
+		const r = head.robots;
+		if (r.index === true) directives.push("index");
+		if (r.index === false) directives.push("noindex");
+		if (r.follow === true) directives.push("follow");
+		if (r.follow === false) directives.push("nofollow");
+		if (r.noarchive === true) directives.push("noarchive");
+		if (r.noimageindex === true) directives.push("noimageindex");
+		if (r["max-snippet"] !== undefined) directives.push(`max-snippet:${r["max-snippet"]}`);
+		if (r["max-image-preview"] !== undefined) directives.push(`max-image-preview:${r["max-image-preview"]}`);
+		if (r["max-video-preview"] !== undefined) directives.push(`max-video-preview:${r["max-video-preview"]}`);
+		if (directives.length > 0) {
+			parts.push(`<meta name="robots" content="${directives.join(",")}">`);
+		}
+	}
+
+	if (head.meta) {
+		const m = head.meta;
+		if (m.charset !== undefined) {
+			parts.push(`<meta charset="${escapeAttr(m.charset)}">`);
+		}
+		if (m.viewport !== undefined && m.viewport !== false) {
+			parts.push(`<meta name="viewport" content="${escapeAttr(m.viewport)}">`);
+		}
+		if (m.manifest !== undefined) {
+			parts.push(`<link rel="manifest" href="${escapeAttr(m.manifest)}">`);
+		}
+		if (m.appleMobileWebAppCapable !== undefined) {
+			parts.push(`<meta name="apple-mobile-web-app-capable" content="${escapeAttr(m.appleMobileWebAppCapable)}">`);
+		}
+		if (m.appleMobileWebAppStatusBarStyle !== undefined) {
+			parts.push(
+				`<meta name="apple-mobile-web-app-status-bar-style" content="${escapeAttr(m.appleMobileWebAppStatusBarStyle)}">`,
+			);
+		}
+		if (m.appleMobileWebAppTitle !== undefined) {
+			parts.push(`<meta name="apple-mobile-web-app-title" content="${escapeAttr(m.appleMobileWebAppTitle)}">`);
+		}
+
+		const META_NAME_MAP: Record<string, string> = {
+			applicationName: "application-name",
+			mobileWebAppCapable: "mobile-web-app-capable",
+		};
+		const genericMetaKeys = [
+			"applicationName",
+			"author",
+			"creator",
+			"generator",
+			"mobileWebAppCapable",
+			"publisher",
+		] as const;
+		for (const key of genericMetaKeys) {
+			const val = m[key];
+			if (val !== undefined) {
+				const name = META_NAME_MAP[key] ?? key;
+				parts.push(`<meta name="${name}" content="${escapeAttr(val)}">`);
+			}
+		}
+	}
+
+	if (head.favicons) {
+		const f = head.favicons;
+		if (f.ico !== undefined) {
+			parts.push(`<link rel="icon" href="${escapeAttr(f.ico)}" sizes="any">`);
+		}
+		if (f.svg !== undefined) {
+			parts.push(`<link rel="icon" type="image/svg+xml" href="${escapeAttr(f.svg)}">`);
+		}
+		if (f.appleTouchIcon !== undefined) {
+			parts.push(`<link rel="apple-touch-icon" href="${escapeAttr(f.appleTouchIcon)}">`);
+		}
+		const sizedKeys = ["96x96", "192x192", "512x512"] as const;
+		for (const size of sizedKeys) {
+			const href = f[size];
+			if (href !== undefined) {
+				parts.push(`<link rel="icon" type="image/png" sizes="${size}" href="${escapeAttr(href)}">`);
+			}
+		}
+	}
+
+	if (head.images) {
+		for (const img of head.images) {
+			renderOgImage(parts, img);
+		}
+	}
+
+	if (head.openGraph) {
+		const og = head.openGraph;
+		if (og.title !== undefined) parts.push(`<meta property="og:title" content="${escapeAttr(og.title)}">`);
+		if (og.description !== undefined)
+			parts.push(`<meta property="og:description" content="${escapeAttr(og.description)}">`);
+		if (og.type !== undefined) parts.push(`<meta property="og:type" content="${escapeAttr(og.type)}">`);
+		if (og.url !== undefined) parts.push(`<meta property="og:url" content="${escapeAttr(og.url)}">`);
+		if (og.siteName !== undefined) parts.push(`<meta property="og:site_name" content="${escapeAttr(og.siteName)}">`);
+		if (og.locale !== undefined) parts.push(`<meta property="og:locale" content="${escapeAttr(og.locale)}">`);
+		if (og.alternateLocale) {
+			for (const locale of og.alternateLocale) {
+				parts.push(`<meta property="og:locale:alternate" content="${escapeAttr(locale)}">`);
+			}
+		}
+		if (og.images) {
+			for (const img of og.images) {
+				renderOgImage(parts, img);
+			}
+		}
+		if (og.videos) {
+			for (const video of og.videos) {
+				parts.push(`<meta property="og:video" content="${escapeAttr(video.url)}">`);
+				if (video.secureUrl)
+					parts.push(`<meta property="og:video:secure_url" content="${escapeAttr(video.secureUrl)}">`);
+				if (video.type) parts.push(`<meta property="og:video:type" content="${escapeAttr(video.type)}">`);
+				if (video.width) parts.push(`<meta property="og:video:width" content="${video.width}">`);
+				if (video.height) parts.push(`<meta property="og:video:height" content="${video.height}">`);
+			}
+		}
+		if (og.audio) {
+			for (const audio of og.audio) {
+				parts.push(`<meta property="og:audio" content="${escapeAttr(audio.url)}">`);
+				if (audio.secureUrl)
+					parts.push(`<meta property="og:audio:secure_url" content="${escapeAttr(audio.secureUrl)}">`);
+				if (audio.type) parts.push(`<meta property="og:audio:type" content="${escapeAttr(audio.type)}">`);
+			}
+		}
+	}
+
+	if (head.twitter) {
+		const tw = head.twitter;
+		if (tw.card !== undefined) parts.push(`<meta name="twitter:card" content="${escapeAttr(tw.card)}">`);
+		if (tw.site !== undefined) parts.push(`<meta name="twitter:site" content="${escapeAttr(tw.site)}">`);
+		if (tw.creator !== undefined) parts.push(`<meta name="twitter:creator" content="${escapeAttr(tw.creator)}">`);
+		if (tw.title !== undefined) parts.push(`<meta name="twitter:title" content="${escapeAttr(tw.title)}">`);
+		if (tw.description !== undefined)
+			parts.push(`<meta name="twitter:description" content="${escapeAttr(tw.description)}">`);
+		if (tw.images) {
+			for (const img of tw.images) {
+				parts.push(`<meta name="twitter:image" content="${escapeAttr(img.url)}">`);
+				if (img.alt) parts.push(`<meta name="twitter:image:alt" content="${escapeAttr(img.alt)}">`);
+			}
+		}
+	}
+
+	if (head.languages) {
+		for (const [lang, href] of Object.entries(head.languages)) {
+			parts.push(`<link rel="alternate" hreflang="${escapeAttr(lang)}" href="${escapeAttr(href)}">`);
+		}
+	}
+
+	if (head.jsonLd) {
+		const items = Array.isArray(head.jsonLd) ? head.jsonLd : [head.jsonLd];
+		for (const item of items) {
+			const json = JSON.stringify(item).replace(/<\/script\b/gi, "<\\/script");
+			parts.push(`<script type="application/ld+json" nonce="${escapeAttr(nonce)}">${json}</script>`);
+		}
+	}
+
+	if (head.css !== undefined) {
+		const cssItems = Array.isArray(head.css) ? head.css : [head.css];
+		for (const href of cssItems) {
+			parts.push(`<link rel="stylesheet" href="${escapeAttr(href)}">`);
+		}
+	}
+
+	if (head.custom) {
+		if (head.custom.links) {
+			for (const link of head.custom.links) {
+				let attrs = "";
+				for (const [k, v] of Object.entries(link)) {
+					if (isSafeAttrName(k)) {
+						if (attrs) attrs += " ";
+						attrs += `${k}="${escapeAttr(v)}"`;
+					}
+				}
+				parts.push(`<link ${attrs}>`);
+			}
+		}
+		if (head.custom.meta) {
+			for (const meta of head.custom.meta) {
+				let attrs = "";
+				for (const [k, v] of Object.entries(meta)) {
+					if (isSafeAttrName(k)) {
+						if (attrs) attrs += " ";
+						attrs += `${k}="${escapeAttr(v)}"`;
+					}
+				}
+				parts.push(`<meta ${attrs}>`);
+			}
+		}
+		if (head.custom.scripts) {
+			for (const script of head.custom.scripts) {
+				const attrs: string[] = [`nonce="${escapeAttr(nonce)}"`];
+				if (script.async) attrs.push("async");
+				if (script.type) attrs.push(`type="${escapeAttr(script.type)}"`);
+				if (script.src) attrs.push(`src="${escapeAttr(script.src)}"`);
+				if (script.extra) {
+					for (const [k, v] of Object.entries(script.extra)) {
+						if (isSafeAttrName(k)) attrs.push(`${k}="${escapeAttr(v)}"`);
+					}
+				}
+				const children = (script.children ?? "").replace(/<\/script\b/gi, "<\\/script");
+				parts.push(`<script ${attrs.join(" ")}>${children}</script>`);
+			}
+		}
+		if (head.custom.styles) {
+			for (const style of head.custom.styles) {
+				const safeChildren = (style.children ?? "").replace(/<\/style\b/gi, "<\\/style");
+				parts.push(`<style nonce="${escapeAttr(nonce)}">${safeChildren}</style>`);
+			}
+		}
+	}
+
+	return parts.join("");
+}