@lovrozagar/flare 0.1.0

package/src/plugins/sx.d.ts

@@ -0,0 +1,14 @@
+import type { ClassValue, Sx } from "../styles/sx-types";
+
+declare module "solid-js" {
+	namespace JSX {
+		interface HTMLAttributes<T> {
+			sx?: Sx;
+			class?: string | ClassValue[];
+		}
+		interface CoreSVGAttributes<T> {
+			sx?: Sx;
+			class?: string | ClassValue[];
+		}
+	}
+}

package/src/plugins/tw-compile.ts

@@ -0,0 +1,240 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+
+export interface TailwindCompiler {
+	build: (classes: string[]) => string;
+	themeVars: Map<string, string>;
+}
+
+/**
+ * Tokens Tailwind expresses as literal class selectors for descendants to target.
+ * Must land on the DOM as a real `class=` attribute.
+ */
+const MARKER_TOKEN_RE = /^(?:group|peer)(?:\/[\w-]+)?$/;
+
+export function splitTokens(classes: string): { markers: string[]; utilities: string } {
+	const markers: string[] = [];
+	const utilities: string[] = [];
+	for (const tok of classes.split(/\s+/).filter(Boolean)) {
+		if (MARKER_TOKEN_RE.test(tok)) markers.push(tok);
+		else utilities.push(tok);
+	}
+	return { markers, utilities: utilities.join(" ") };
+}
+
+function extractPseudo(selector: string): string | null {
+	for (let i = selector.length - 1; i >= 0; i--) {
+		if (selector[i] === ":" && (i === 0 || selector[i - 1] !== "\\")) {
+			return selector.slice(i);
+		}
+	}
+	return null;
+}
+
+function cssEscapeClass(cls: string): string {
+	return cls.replace(/([^a-zA-Z0-9_-])/g, "\\$1");
+}
+
+function selectorMatchesAny(selector: string, prefixes: Set<string>): boolean {
+	for (const prefix of prefixes) {
+		if (
+			selector === prefix ||
+			selector.startsWith(`${prefix}:`) ||
+			selector.startsWith(`${prefix} `) ||
+			selector.startsWith(`${prefix},`)
+		) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function extractLayerContent(css: string, atStart: number): string {
+	const braceStart = css.indexOf("{", atStart);
+	if (braceStart === -1) return "";
+	let depth = 1;
+	let i = braceStart + 1;
+	for (; i < css.length; i++) {
+		if (css[i] === "{") depth++;
+		else if (css[i] === "}") {
+			depth--;
+			if (depth === 0) break;
+		}
+	}
+	return css.slice(braceStart + 1, i).trim();
+}
+
+function extractDeclsInner(css: string, selectorSet?: Set<string>): string {
+	const result: string[] = [];
+	let remaining = css.trim();
+	while (remaining.length > 0) {
+		remaining = remaining.trim();
+		if (remaining.length === 0) break;
+
+		if (remaining.startsWith("@")) {
+			const braceStart = remaining.indexOf("{");
+			if (braceStart === -1) break;
+			const atRule = remaining.slice(0, braceStart).trim();
+			let depth = 1;
+			let i = braceStart + 1;
+			for (; i < remaining.length; i++) {
+				if (remaining[i] === "{") depth++;
+				else if (remaining[i] === "}") {
+					depth--;
+					if (depth === 0) break;
+				}
+			}
+			const inner = remaining.slice(braceStart + 1, i).trim();
+			const innerDecls = extractDeclsInner(inner, selectorSet);
+			if (innerDecls.length > 0) {
+				result.push(`${atRule} { ${innerDecls} }`);
+			}
+			remaining = remaining.slice(i + 1).trim();
+			continue;
+		}
+
+		const braceStart = remaining.indexOf("{");
+		if (braceStart === -1) break;
+		const selector = remaining.slice(0, braceStart).trim();
+		let depth = 1;
+		let i = braceStart + 1;
+		for (; i < remaining.length; i++) {
+			if (remaining[i] === "{") depth++;
+			else if (remaining[i] === "}") {
+				depth--;
+				if (depth === 0) break;
+			}
+		}
+		const body = remaining.slice(braceStart + 1, i).trim();
+		const matchesFilter = !selectorSet || selectorMatchesAny(selector, selectorSet);
+		if (matchesFilter && body.length > 0) {
+			const pseudo = extractPseudo(selector);
+			if (pseudo) {
+				result.push(`&${pseudo} { ${body} }`);
+			} else {
+				result.push(body);
+			}
+		}
+		remaining = remaining.slice(i + 1).trim();
+	}
+	return result.join(";");
+}
+
+function resolveThemeVars(css: string, themeVars: Map<string, string>): string {
+	let result = css;
+	for (let i = 0; i < 5; i++) {
+		const next = result.replace(/var\((--[\w-]+)\)/g, (full, name: string) => {
+			return themeVars.get(name) ?? full;
+		});
+		if (next === result) break;
+		result = next;
+	}
+	return result;
+}
+
+/**
+ * Returns the full Tailwind preamble from a zero-class build output — everything
+ * except the `@layer utilities` block. Captures theme vars and preflight so
+ * browser defaults are normalized even when no utility classes are present.
+ */
+export function extractPrefaceCss(cssOutput: string): string {
+	const stripped = cssOutput.replace(/\/\*[\s\S]*?\*\//g, "").trim();
+	/* Strip the utilities layer entirely; keep theme + base + components. */
+	const utilMatch = stripped.match(/@layer\s+utilities\s*\{/);
+	if (!utilMatch || utilMatch.index === undefined) return stripped;
+	const beforeUtil = stripped.slice(0, utilMatch.index).trim();
+	const afterUtil = (() => {
+		const braceStart = stripped.indexOf("{", utilMatch.index);
+		if (braceStart === -1) return "";
+		let depth = 1;
+		let i = braceStart + 1;
+		for (; i < stripped.length; i++) {
+			if (stripped[i] === "{") depth++;
+			else if (stripped[i] === "}") {
+				depth--;
+				if (depth === 0) break;
+			}
+		}
+		return stripped.slice(i + 1).trim();
+	})();
+	return [beforeUtil, afterUtil].filter(Boolean).join("\n").trim();
+}
+
+export function extractDeclarations(
+	cssOutput: string,
+	requestedClasses: string[],
+	themeVars?: Map<string, string>,
+): string {
+	const stripped = cssOutput.replace(/\/\*[\s\S]*?\*\//g, "").trim();
+	const utilMatch = stripped.match(/@layer\s+utilities\s*\{/);
+	const toParse = utilMatch ? extractLayerContent(stripped, utilMatch.index ?? 0) : stripped;
+	const selectorSet = new Set(requestedClasses.map((c) => `.${cssEscapeClass(c)}`));
+	let raw = extractDeclsInner(toParse, selectorSet);
+	if (themeVars) {
+		raw = resolveThemeVars(raw, themeVars);
+	}
+	return raw.replace(/\s+/g, " ").trim();
+}
+
+/** Initialize a Tailwind v4 compiler from an optional CSS entry file. */
+export async function initTailwindCompiler(cssPath?: string): Promise<TailwindCompiler> {
+	try {
+		const tw = await import("tailwindcss");
+		const compileFn = tw.compile ?? (tw.default as { compile?: unknown })?.compile;
+		if (typeof compileFn !== "function") {
+			throw new Error(
+				"tailwindcss compile function not found. Ensure tailwindcss ^4.0 is installed: bun add tailwindcss@latest",
+			);
+		}
+
+		let cssContent: string;
+		if (cssPath) {
+			cssContent = readFileSync(resolve(cssPath), "utf-8");
+		} else {
+			cssContent = '@import "tailwindcss";';
+		}
+
+		const compiler = await (
+			compileFn as (
+				css: string,
+				opts?: unknown,
+			) => Promise<{
+				build: (classes: string[]) => string;
+			}>
+		)(cssContent, {
+			loadStylesheet: (id: string, base: string) => {
+				if (id === "tailwindcss") {
+					const esmRequire = createRequire(import.meta.url);
+					const pkgPath = esmRequire.resolve("tailwindcss/package.json");
+					const pkgDir = dirname(pkgPath);
+					const cssPath2 = join(pkgDir, "index.css");
+					const content = readFileSync(cssPath2, "utf-8");
+					return { base: pkgDir, content, path: cssPath2 };
+				}
+				const resolved = resolve(base, id);
+				const content = readFileSync(resolved, "utf-8");
+				return { base: dirname(resolved), content, path: resolved };
+			},
+		});
+
+		const themeVars = new Map<string, string>();
+		const originalBuild = compiler.build.bind(compiler);
+		const trackingBuild = (classes: string[]): string => {
+			const output = originalBuild(classes);
+			for (const m of output.matchAll(/(--[\w-]+)\s*:\s*([^;]+)/g)) {
+				if (!themeVars.has(m[1])) {
+					themeVars.set(m[1], m[2].trim());
+				}
+			}
+			return output;
+		};
+
+		return { build: trackingBuild, themeVars };
+	} catch (e: unknown) {
+		throw new Error(
+			`tailwindcss init failed: ${e instanceof Error ? e.message : String(e)}. Check tailwind.config.ts for syntax errors.`,
+			{ cause: e },
+		);
+	}
+}

package/src/plugins/types.ts

@@ -0,0 +1,41 @@
+export interface VitePlugin {
+	buildStart?: () => Promise<void> | void;
+	closeBundle?: () => Promise<void> | void;
+	config?: (
+		userConfig: unknown,
+		env: { command?: string; mode?: string },
+	) => Record<string, unknown> | undefined | void;
+	configResolved?: (config: { command?: string; mode?: string }) => Promise<void> | void;
+	configurePreviewServer?: (server: unknown) => (() => void) | undefined;
+	configureServer?: (server: unknown) => (() => void) | undefined;
+	enforce?: "post" | "pre";
+	load?: (
+		id: string,
+	) =>
+		| Promise<string | { code: string; moduleType?: string } | null>
+		| string
+		| { code: string; moduleType?: string }
+		| null;
+	name: string;
+	resolveId?: (id: string, importer?: unknown, options?: unknown) => string | null;
+	transform?: (
+		code: string,
+		id: string,
+	) => Promise<{ code: string; map?: null } | null> | { code: string; map?: null } | null;
+	transformIndexHtml?: (
+		html: string,
+		ctx: unknown,
+	) =>
+		| {
+				attrs?: Record<string, string | boolean | undefined>;
+				children?: string;
+				injectTo?: "body" | "body-prepend" | "head" | "head-prepend";
+				tag: string;
+		  }[]
+		| undefined;
+}
+
+export interface ResolvedEntries {
+	client: string;
+	server: string;
+}

package/src/plugins/virtual.d.ts

@@ -0,0 +1,110 @@
+// oxlint-disable-next-line typescript-eslint/triple-slash-reference
+/// <reference path="solid-jsx.d.ts" />
+// oxlint-disable-next-line typescript-eslint/triple-slash-reference
+/// <reference path="sx.d.ts" />
+
+interface ImportMeta {
+	readonly env: {
+		readonly DEV: boolean;
+		readonly PROD: boolean;
+		readonly MODE: string;
+		readonly BASE_URL: string;
+		readonly SSR: boolean;
+		[key: string]: unknown;
+	};
+}
+
+declare module "virtual:flare-server-fn-map" {
+	import type { ServerFnRegistration } from "@lovrozagar/flare/server";
+	const map: Map<string, ServerFnRegistration>;
+	export default map;
+}
+
+declare module "virtual:flare-is-dev" {
+	const isDev: boolean;
+	export default isDev;
+}
+
+declare module "virtual:flare-log-level" {
+	const level: "error" | "silent" | "verbose" | "warn";
+	export default level;
+}
+
+declare module "virtual:flare-config" {
+	const config: Record<string, unknown>;
+	export default config;
+}
+
+declare module "virtual:flare-client-entry" {
+	const entry: string;
+	export default entry;
+}
+
+declare module "virtual:flare-generated" {
+	export const layoutModuleIds: Record<string, string>;
+	export const routeTree: unknown;
+	export const layouts: unknown;
+}
+
+declare module "virtual:flare-module-preloads" {
+	export const clientManifest: Record<string, unknown> | null;
+	export const entryPreloads: { css: string[]; js: string[] };
+}
+
+declare module "virtual:flare-sx-manifest" {
+	import type { SxCssManifest } from "../ssr/critical-css";
+	export const sxManifest: SxCssManifest | null;
+}
+
+declare module "virtual:flare-sx-dev-css" {
+	/** Returns the current accumulated sx CSS string. Re-imported each SSR request to pick up HMR additions. */
+	export function getDevSxCss(): string;
+	/** Returns the current accumulated class-name list. Seeded into window state so client module injects dedupe against SSR-emitted classes. */
+	export function getDevSxClasses(): string[];
+}
+
+declare module "virtual:flare-server-fn-secret" {
+	const secret: string;
+	export default secret;
+}
+
+declare module "virtual:flare-sw-config" {
+	const config: { enabled: false } | { enabled: true; path: string; scope: string };
+	export default config;
+}
+
+declare module "*.avif" {
+	import type { StaticImageData } from "../image.ts";
+	const data: StaticImageData;
+	export default data;
+}
+
+declare module "*.jpg" {
+	import type { StaticImageData } from "../image.ts";
+	const data: StaticImageData;
+	export default data;
+}
+
+declare module "*.jpeg" {
+	import type { StaticImageData } from "../image.ts";
+	const data: StaticImageData;
+	export default data;
+}
+
+declare module "*.png" {
+	import type { StaticImageData } from "../image.ts";
+	const data: StaticImageData;
+	export default data;
+}
+
+declare module "*.tiff" {
+	import type { StaticImageData } from "../image.ts";
+	const data: StaticImageData;
+	export default data;
+}
+
+declare module "*.webp" {
+	import type { StaticImageData } from "../image.ts";
+	const data: StaticImageData;
+	export default data;
+}

package/src/plugins/virtual.ts

@@ -0,0 +1,184 @@
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { findEntryKey, resolveModulePreloads, type ViteManifest } from "../module-graph/index.ts";
+import type { SxCssManifest } from "../ssr/critical-css.ts";
+import type { ResolvedEntries, VitePlugin } from "./types.ts";
+
+/**
+ * Read the client entry path from Vite's build manifest.
+ * buildApp() builds client before SSR, so manifest.json exists
+ * when the SSR build loads this virtual module.
+ */
+function readClientManifest(root: string): ViteManifest | undefined {
+	const manifestPath = join(root, "dist/client/.vite/manifest.json");
+	try {
+		const raw = readFileSync(manifestPath, "utf-8");
+		return JSON.parse(raw) as ViteManifest;
+	} catch {
+		/* manifest doesn't exist yet (dev mode) — caller uses dev fallback */
+	}
+	return undefined;
+}
+
+/** Read the sx CSS manifest emitted by the sx-ast plugin during the client build. */
+function readSxManifest(root: string): SxCssManifest | undefined {
+	const manifestPath = join(root, "dist/client/flare-sx-manifest.json");
+	try {
+		const raw = readFileSync(manifestPath, "utf-8");
+		/* Trust bundleHref written by sx-ast — it knows assetsBase. */
+		return JSON.parse(raw) as SxCssManifest;
+	} catch {
+		/* sx plugin not enabled or client not built yet */
+	}
+	return undefined;
+}
+
+function resolveClientEntryFromManifest(root: string, clientEntry: string): string | undefined {
+	const manifest = readClientManifest(root);
+	if (!manifest) return undefined;
+
+	const entry = manifest[clientEntry];
+	if (entry?.file) return `/${entry.file}`;
+
+	/* Fallback: find any entry chunk */
+	for (const value of Object.values(manifest)) {
+		if (value.isEntry && value.file) return `/${value.file}`;
+	}
+	return undefined;
+}
+
+export function createVirtualPlugin(
+	config: { ignorePrefix?: string; logLevel?: string },
+	entries: ResolvedEntries,
+	codegen?: { routesFilePath?: string },
+): VitePlugin {
+	const routesFilePath = codegen?.routesFilePath ?? "src/_gen/routes.gen.ts";
+	const serializedConfig = JSON.stringify({
+		clientEntryFilePath: entries.client,
+		ignorePrefix: config.ignorePrefix ?? "_",
+	});
+
+	/* Captured from the parent ResolvedConfig — use this instead of `environment.config.mode`,
+	   because under cf-vite-plugin (Vite 8) the SSR worker environment reports `mode: "production"`
+	   even during `vite serve`, which silently flips Flare into prod-CSP mode (no unsafe-inline,
+	   nonces added) and breaks dev HMR + third-party widgets. */
+	let isDevMode = false;
+
+	return {
+		config(_userConfig: unknown, env: { command?: string; mode?: string }) {
+			if (env.command === "serve" || env.mode === "development") isDevMode = true;
+			/* Inject `__FLARE_IS_DEV__` as a Vite define — survives cf-vite-plugin's SSR worker
+			   bundle where `import.meta.env.DEV` is forced to `false` (SSR env mode defaults to
+			   `production` even during `vite serve`). Define replacement is per-environment but
+			   always honored, so this single source-of-truth flag works in every env. */
+			return {
+				define: {
+					__FLARE_IS_DEV__: JSON.stringify(isDevMode),
+				},
+			};
+		},
+		configResolved(resolvedConfig: { command?: string; mode?: string }) {
+			if (resolvedConfig.command === "serve" || resolvedConfig.mode === "development") {
+				isDevMode = true;
+			}
+		},
+		load(
+			this: {
+				environment?: {
+					config?: { build?: { outDir?: string }; mode?: string; root?: string };
+					name?: string;
+				};
+			},
+			id: string,
+		): { code: string; moduleType: string } | null {
+			if (id === "\0virtual:flare-config") {
+				return { code: `export default ${serializedConfig}`, moduleType: "js" };
+			}
+			if (id === "\0virtual:flare-client-entry") {
+				const mode = this.environment?.config?.mode ?? "production";
+				if (mode === "development") {
+					return { code: `export default "/${entries.client}"`, moduleType: "js" };
+				}
+				/* Prod: read hashed filename from client build manifest */
+				const root = this.environment?.config?.root ?? process.cwd();
+				const resolved = resolveClientEntryFromManifest(root, entries.client);
+				return {
+					code: `export default "${resolved ?? `/${entries.client}`}"`,
+					moduleType: "js",
+				};
+			}
+			if (id === "\0virtual:flare-generated") {
+				const root = this.environment?.config?.root ?? process.cwd();
+				/* file:// URL gives rolldown an unambiguous filesystem anchor so relative imports
+				   inside routes.gen.ts resolve from the real file location, not from the virtual
+				   module's synthetic base (which otherwise produced 13-deep ../ traversals under
+				   vite 8 + rolldown) */
+				const genFileUrl = pathToFileURL(resolve(root, routesFilePath)).href;
+				return {
+					code: `export { routeTree, layouts, layoutModuleIds } from "${genFileUrl}"`,
+					moduleType: "js",
+				};
+			}
+			if (id === "\0virtual:flare-is-dev") {
+				const dev = isDevMode || this.environment?.config?.mode === "development";
+				return { code: `export default ${dev}`, moduleType: "js" };
+			}
+			if (id === "\0virtual:flare-log-level") {
+				const dev = isDevMode || this.environment?.config?.mode === "development";
+				const level = config.logLevel ?? (dev ? "warn" : "error");
+				return { code: `export default "${level}"`, moduleType: "js" };
+			}
+			if (id === "\0virtual:flare-module-preloads") {
+				const mode = this.environment?.config?.mode ?? "production";
+				if (mode === "development") {
+					return {
+						code: ["export const entryPreloads = { js: [], css: [] }", "export const clientManifest = null"].join("\n"),
+						moduleType: "js",
+					};
+				}
+				const root = this.environment?.config?.root ?? process.cwd();
+				const manifest = readClientManifest(root);
+				if (!manifest) {
+					return {
+						code: ["export const entryPreloads = { js: [], css: [] }", "export const clientManifest = null"].join("\n"),
+						moduleType: "js",
+					};
+				}
+				const entryKey = findEntryKey(manifest);
+				const preloads = entryKey ? resolveModulePreloads(manifest, entryKey) : { css: [], js: [] };
+				return {
+					code: [
+						`export const entryPreloads = ${JSON.stringify(preloads)}`,
+						`export const clientManifest = ${JSON.stringify(manifest)}`,
+					].join("\n"),
+					moduleType: "js",
+				};
+			}
+			if (id === "\0virtual:flare-sx-manifest") {
+				const mode = this.environment?.config?.mode ?? "production";
+				if (mode === "development") {
+					return { code: "export const sxManifest = null", moduleType: "js" };
+				}
+				const root = this.environment?.config?.root ?? process.cwd();
+				const manifest = readSxManifest(root);
+				return {
+					code: `export const sxManifest = ${manifest ? JSON.stringify(manifest) : "null"}`,
+					moduleType: "js",
+				};
+			}
+			return null;
+		},
+		name: "flare:virtual",
+		resolveId(id: string): string | null {
+			if (id === "virtual:flare-config") return "\0virtual:flare-config";
+			if (id === "virtual:flare-client-entry") return "\0virtual:flare-client-entry";
+			if (id === "virtual:flare-generated") return "\0virtual:flare-generated";
+			if (id === "virtual:flare-is-dev") return "\0virtual:flare-is-dev";
+			if (id === "virtual:flare-log-level") return "\0virtual:flare-log-level";
+			if (id === "virtual:flare-module-preloads") return "\0virtual:flare-module-preloads";
+			if (id === "virtual:flare-sx-manifest") return "\0virtual:flare-sx-manifest";
+			return null;
+		},
+	};
+}

package/src/preload/index.ts

@@ -0,0 +1,77 @@
+const RETRY_DELAY_MS = 1000;
+const MAX_ATTEMPTS = 2;
+
+interface PreloadOptions<T, R extends boolean = false> {
+	loader: () => Promise<{ default: T }>;
+	throws?: R;
+}
+
+interface PreloadResult<T, R extends boolean> {
+	load: () => Promise<R extends true ? T : T | undefined>;
+	preload: () => void;
+	reset: () => void;
+}
+
+export function preload<T, R extends boolean = false>(options: PreloadOptions<T, R>): PreloadResult<T, R> {
+	let cached: Promise<T | undefined> | null = null;
+	let attempts = 0;
+	let generation = 0;
+
+	function doLoad(gen: number): Promise<T | undefined> {
+		attempts++;
+		return options.loader().then(
+			(mod) => mod.default,
+			(error: unknown) => {
+				/* Discard stale retry from previous generation */
+				if (gen !== generation) return undefined;
+				if (attempts < MAX_ATTEMPTS) {
+					return new Promise<T | undefined>((resolve) => {
+						setTimeout(() => {
+							/* Check generation again after delay */
+							if (gen !== generation) {
+								resolve(undefined);
+								return;
+							}
+							resolve(doLoad(gen));
+						}, RETRY_DELAY_MS);
+					});
+				}
+				/* exhausted — clear cache for fresh attempt next time */
+				cached = null;
+				attempts = 0;
+				if (options.throws) {
+					throw error;
+				}
+				return undefined;
+			},
+		);
+	}
+
+	function load(): Promise<T | undefined> {
+		if (!cached) {
+			cached = doLoad(generation);
+			cached.catch(() => {});
+		}
+		return cached;
+	}
+
+	function preloadFn(): void {
+		if (!cached) {
+			cached = doLoad(generation);
+			/* swallow unhandled rejection */
+			cached.catch(() => {});
+		}
+	}
+
+	function reset(): void {
+		cached = null;
+		attempts = 0;
+		generation++;
+	}
+
+	return {
+		load: load as PreloadResult<T, R>["load"],
+		preload: preloadFn,
+		reset,
+	};
+}