@open-yama/astro 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "@open-yama/astro",
+	"version": "0.1.0",
+	"description": "Yama Astro help build personalized themes for Yama CMS",
+	"license": "MIT",
+	"author": "Yama CMS",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./components/Favicons.astro": "./src/components/Favicons.astro",
+		"./components/GoogleFonts.astro": "./src/components/GoogleFonts.astro",
+		"./integrations/colors": "./src/integrations/colors.ts",
+		"./integrations/favicons": "./src/integrations/favicons.ts",
+		"./modules/colors": "./src/modules/colors.ts",
+		"./modules/favicons": "./src/modules/favicons.ts",
+		"./modules/fonts": "./src/modules/fonts.ts",
+		"./modules/ogImage": "./src/modules/ogImage.ts"
+	},
+	"dependencies": {
+		"astro": "^6.4.8",
+		"chalk": "^5.6.2",
+		"favicons": "^7.3.0",
+		"file-type": "^22.0.1",
+		"fs-extra": "^11.3.5",
+		"pretty-hrtime": "^1.0.3"
+	},
+	"devDependencies": {
+		"@types/fs-extra": "^11.0.4",
+		"@types/node": "^25.9.3",
+		"@types/pretty-hrtime": "^1.0.3"
+	}
+}

package/src/components/Favicons.astro

@@ -0,0 +1,20 @@
+---
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import { publicDir } from "astro:config/server";
+
+
+
+const faviconsHTMLPath = path.join(publicDir instanceof URL ? publicDir.pathname : publicDir, "favicons", "favicons.html");
+let faviconsHTML = null;
+
+try {
+	faviconsHTML = await fs.readFile(faviconsHTMLPath, "utf-8");
+} catch (error) {
+	console.error(`[yama-favicon] Warning: Failed to read favicons HTML file at ${faviconsHTMLPath}`);
+	return;
+}
+---
+
+<!-- Favicons links to inject in the head -->
+<Fragment set:html={faviconsHTML} />

package/src/components/GoogleFonts.astro

@@ -0,0 +1,66 @@
+---
+/**
+ * Code source slightly modified from : https://github.com/sebholstein/astro-google-fonts-optimizer/blob/main/packages/astro-google-fonts-optimizer/
+ * License : MIT
+ */
+import { getContent } from "../modules/fonts";
+import type { SiteFontsConfig } from "../modules/fonts";
+
+
+
+export interface Props {
+	fontsData: SiteFontsConfig;
+	preload?: boolean;
+}
+
+
+
+const { fontsData, preload = true } = Astro.props as Props;
+
+if (!fontsData?.embeddedCode) {
+	console.error("No Google Fonts embeddedCode provided");
+	return;
+}
+
+const content = await getContent(fontsData);
+
+const isRaw = "rawEmbed" in content;
+const preconnects = !isRaw ? content.preconnects : [];
+const inlineCss = "css" in content ? content.css : "";
+const hasCss = Boolean(inlineCss);
+const sheetUrl = "url" in content ? content.url : "";
+---
+
+{isRaw ? (
+	<Fragment set:html={content.rawEmbed} is:raw />
+) : (
+	<>
+		{preconnects.map(({ href, crossOrigin }) => (
+			<link
+				rel="preconnect"
+				href={href}
+				{...(crossOrigin ? { crossorigin: "anonymous" } : {})}
+			/>
+		))}
+		{hasCss ? (
+			<style set:html={inlineCss} is:inline />
+		) : sheetUrl ? (
+			preload ? (
+				<>
+					<link
+						rel="preload"
+						as="style"
+						href={sheetUrl}
+						onload="this.onload=null;this.rel='stylesheet'"
+					/>
+					<Fragment
+						set:html={`<noscript><link rel="stylesheet" href="${sheetUrl}"></noscript>`}
+						is:raw
+					/>
+				</>
+			) : (
+				<link rel="stylesheet" href={sheetUrl} />
+			)
+		) : null}
+	</>
+)}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { default as GoogleFonts } from "./components/GoogleFonts.astro"
+export { default as Favicons } from "./components/Favicons.astro"
+

package/src/integrations/colors.ts

@@ -0,0 +1,27 @@
+import type { AstroIntegration, AstroIntegrationLogger } from "astro";
+import { buildColorsCSS, type ColorsOptions } from "../modules/colors";
+import path from "path";
+
+
+
+export default function yamaColors(options: Partial<ColorsOptions> = {}): AstroIntegration {
+	const opts: ColorsOptions = {
+		input: options.input ?? "yama.config.json",
+		output: options.output ?? "src/styles/generated-colors.css",
+		fallbackColors: options.fallbackColors,
+	};
+
+	const buildColors = async (logger: AstroIntegrationLogger) => {
+		logger.info("Building color themes...");
+		buildColorsCSS(opts, logger);
+	};
+
+	return {
+		name: "yama-colors",
+		hooks: {
+			"astro:config:setup": async ({ addWatchFile, config }) => addWatchFile(path.resolve(config.root.pathname, opts.input)),
+			"astro:server:start": async ({ logger }) => buildColors(logger),
+			"astro:build:start": async ({ logger }) => buildColors(logger),
+		},
+	};
+}

package/src/integrations/favicons.ts

@@ -0,0 +1,42 @@
+import type { FaviconOptions } from "favicons";
+import type { AstroIntegration, AstroIntegrationLogger, ViteUserConfig } from "astro";
+
+import chalk from "chalk";
+import { generateFavicons } from "../modules/favicons";
+import { executionTime } from "../modules/favicons";
+
+
+
+export default function (logoPath: string, options: FaviconOptions = {}): AstroIntegration {
+	return {
+		name: "yama-favicon",
+		hooks: {
+			"astro:build:setup": async ({ logger, vite }: { logger: AstroIntegrationLogger; vite: ViteUserConfig }) => {
+				const execTime = executionTime({
+					logger,
+					callback: ({ words }) => logger.info(chalk.green(`✓ Completed in ${words}.`)),
+				});
+				execTime.start("yama-favicon");
+
+				if (!logoPath) {
+					throw new Error("No logo path provided");
+				}
+
+				logger.info("Generating favicons…");
+				await generateFavicons(logoPath, {
+					...options,
+					path: "/favicons",
+					icons: {
+						...options.icons,
+						appleStartup: false,
+						yandex: false,
+					},
+					publicDir: vite.publicDir as string,
+					logger,
+				});
+
+				execTime.stop("yama-favicon");
+			},
+		},
+	};
+}

package/src/modules/colors.ts

@@ -0,0 +1,75 @@
+import type { AstroIntegrationLogger } from "astro";
+
+import fs from "fs";
+import path from "path";
+import chalk from "chalk";
+
+
+
+export type ColorsOptions = {
+	input: string;
+	output: string;
+	fallbackColors?: ColorsData;
+};
+
+export type ColorsData = {
+	code: string;
+};
+
+type ThemesRecord = Record<string, Record<string, string>>;
+
+
+
+/**
+ * Fetch colors data from yama.config.json and parse the stringified themes
+ * record (e.g. `{"default":{...},"dark":{...}}`) used to build CSS variables.
+ */
+export function getColorsData(input: string, fallbackColors?: ColorsData): ThemesRecord {
+	const raw = fs.readFileSync(input, "utf-8");
+	const config = JSON.parse(raw);
+	const colorsData: ColorsData | undefined = config?.site?.data?.colors ?? fallbackColors;
+
+	if (!colorsData?.code) {
+		throw new Error("Missing 'site.data.colors.code' in yama.config.json and no fallback colors provided");
+	}
+
+	return JSON.parse(colorsData.code) as ThemesRecord;
+}
+
+export function buildColorsCSS(options: ColorsOptions, logger: AstroIntegrationLogger) {
+	const { input, output } = options;
+
+	try {
+		const themes = getColorsData(input, options.fallbackColors);
+
+		/* DEFAULT THEME */
+		let css = `
+/**
+ * This file is automatically generated by a script. Do not edit manually.
+ */
+
+:root {
+`;
+		for (const [key, value] of Object.entries(themes.default)) {
+			css += `    --color-${key}: ${value};\n`;
+		}
+		css += `}\n\n`;
+
+		/* OTHER THEMES */
+		for (const [themeName, vars] of Object.entries(themes)) {
+			if (themeName === "default") continue;
+			css += `[data-theme="${themeName}"] {\n`;
+			for (const [key, value] of Object.entries(vars as Record<string, string>)) {
+				css += `    --color-${key}: ${value};\n`;
+			}
+			css += `}\n\n`;
+		}
+
+		fs.mkdirSync(path.dirname(output), { recursive: true });
+		fs.writeFileSync(output, css, "utf-8");
+
+		logger.info(chalk.green(`✓ Colors CSS generated → ${output}`));
+	} catch (err: any) {
+		logger.error(chalk.red(`✗ Colors build failed: ${err.message}`));
+	}
+}

package/src/modules/favicons.ts

@@ -0,0 +1,261 @@
+import { favicons, type FaviconOptions } from "favicons";
+import type { AstroIntegrationLogger } from "astro";
+
+import { fileTypeFromBuffer } from "file-type";
+import * as fs from "node:fs/promises";
+import * as fsExtra from "fs-extra";
+import * as path from "node:path";
+import chalk from "chalk";
+import sharp from "sharp";
+import prettyHrtime from "pretty-hrtime";
+
+
+
+type DownloadLogoOptions = {
+	cacheDir?: string;
+	logger?: AstroIntegrationLogger;
+};
+
+
+
+const DEFAULT_CACHE_DIR = "node_modules/.cache/yama/favicons";
+const DEFAULT_CACHE_DIR_CONTENT = `${DEFAULT_CACHE_DIR}/content/`;
+const LOGO_BASENAME = "logo";
+
+export async function getCachedLogoPath({
+	cacheDir = DEFAULT_CACHE_DIR,
+	fileName = LOGO_BASENAME,
+	excludeSvg = false,
+}: {
+	cacheDir?: string;
+	fileName?: string;
+	excludeSvg?: boolean;
+} = {}) {
+	try {
+		const files = await fs.readdir(cacheDir);
+		const logoFile = files
+			.filter((file) => file.startsWith(`${fileName}.`))
+			.find((file) => (excludeSvg ? !file.endsWith(`.svg`) : true));
+
+		if (!logoFile) return null;
+
+		return path.join(cacheDir, logoFile);
+	} catch {
+		return null;
+	}
+}
+
+// If logo is a SVG, we also generate a PNG to cover all cases (OG Image, ect.)
+async function ensurePngLogoGenerated(logoPath: string): Promise<string> {
+	if (!logoPath.endsWith(".svg")) {
+		return logoPath;
+	}
+
+	const pngPath = logoPath.replace(/\.svg$/i, ".png");
+
+	const exists = await fs
+		.stat(pngPath)
+		.then(() => true)
+		.catch(() => false);
+	if (exists) return pngPath;
+
+	await sharp(logoPath).png().toFile(pngPath);
+
+	return pngPath;
+}
+
+async function removeCachedLogos(cacheDir: string) {
+	try {
+		const files = await fs.readdir(cacheDir);
+
+		await Promise.all(files.filter((file) => file.startsWith(LOGO_BASENAME)).map((file) => fs.unlink(path.join(cacheDir, file))));
+	} catch {}
+}
+
+export async function downloadLogo(url: string, { cacheDir = DEFAULT_CACHE_DIR, logger }: DownloadLogoOptions) {
+	const res = await fetch(url);
+	if (!res.ok) throw new Error(`Failed to download logo: ${url}`);
+
+	const buffer = Buffer.from(await res.arrayBuffer());
+	let ext: string | undefined;
+
+	const fileType = await fileTypeFromBuffer(buffer);
+
+	if (fileType) {
+		ext = fileType.ext;
+	} else {
+		const contentType = res.headers.get("content-type");
+
+		if (contentType?.includes("image/svg+xml")) {
+			ext = "svg";
+		}
+	}
+
+	if (!ext) {
+		throw new Error("Unable to detect logo file type");
+	}
+
+	const logoPath = path.join(cacheDir, `logo.${ext}`);
+	const cacheExists = await fs
+		.stat(logoPath)
+		.then(() => true)
+		.catch(() => false);
+	const cached = cacheExists ? await fs.readFile(logoPath) : null;
+	const unchanged = cached && Buffer.compare(cached, buffer) === 0;
+
+	if (unchanged) {
+		logger?.info(chalk.gray("Logo found in cache (unchanged)"));
+		return {
+			relativeLogoPath: logoPath,
+			unchanged,
+		};
+	}
+
+	await removeCachedLogos(cacheDir);
+	await fs.mkdir(cacheDir, { recursive: true });
+	await fs.writeFile(logoPath, buffer);
+	await ensurePngLogoGenerated(logoPath);
+
+	logger?.info(chalk.gray(cached ? "Logo updated in cache" : "Logo generated and cached"));
+	return {
+		relativeLogoPath: logoPath,
+		unchanged: false,
+	};
+}
+
+export async function generateFavicons(
+	logoPath: string,
+	options: FaviconOptions & {
+		publicDir: string | false;
+		logger?: AstroIntegrationLogger;
+		cacheDir?: string;
+	},
+) {
+	if (!options.publicDir) {
+		throw new Error("Public directory is required to generate favicons");
+	}
+	// Prevent removing the project root files by accident
+	if (options.path === "/") {
+		throw new Error(
+			"Favicons directory path cannot be root (`/`), you should use a subpath instead to avoid overriding the project root files and unwanted behavior, use `/favicons` for example",
+		);
+	}
+
+	const { relativeLogoPath, unchanged } = await downloadLogo(logoPath, {
+		logger: options.logger,
+	});
+	const cacheDir = options.cacheDir ?? DEFAULT_CACHE_DIR_CONTENT;
+	const cacheDirExists = await fs
+		.stat(cacheDir)
+		.then(() => true)
+		.catch(() => false);
+
+	const outputDir = path.join(options.publicDir, options.path!);
+
+	// Skip generation if the logo is unchanged in the cache
+	if (unchanged && cacheDirExists) {
+		await fsExtra.copy(cacheDir, outputDir);
+		options.logger?.info(chalk.gray("Favicons found in cache (unchanged)"));
+		return;
+	}
+
+	const response = await favicons(relativeLogoPath, options);
+
+	// Remove the existing favicons directory if it exists
+	await fs.rm(outputDir, { recursive: true, force: true });
+
+	// Create the favicons directory
+	await fs.mkdir(outputDir, { recursive: true });
+
+	// Generate the favicons images
+	Promise.all(
+		response.images.map(async (image) => {
+			await fs.writeFile(path.join(outputDir, image.name), image.contents);
+		}),
+	);
+
+	// Generate the favicons files (manifest, browserconfig, etc.)
+	Promise.all(
+		response.files.map(async (file) => {
+			await fs.writeFile(path.join(outputDir, file.name), file.contents);
+		}),
+	);
+
+	// Generate the favicons links HTML to be used in the head of the project HTML files
+	await fs.writeFile(path.join(outputDir, "favicons.html"), response.html.join("\n"));
+
+	// Cache the favicons content
+	try {
+		await fsExtra.copy(outputDir, cacheDir);
+		options.logger?.info(chalk.gray("Favicons generated and cached"));
+	} catch (error) {
+		options.logger?.error(chalk.red("Failed to cache favicons", error));
+	}
+}
+
+/*
+ *
+ *
+ * FAVICONS UTILITIES
+ * Code source who relies on execution time is based on [execution-time](https://github.com/svenkatreddy/execution-time) package.
+*/
+type HrTime = [number, number];
+
+type PerformanceEntry = {
+	startAt: HrTime;
+};
+
+type PerformanceResult = {
+	name: string;
+	time: number; // milliseconds
+	words: string;
+	preciseWords: string;
+	verboseWords: string;
+};
+
+type LoggerOptions = {
+	logger: AstroIntegrationLogger;
+	callback: ({ time, words }: { time: number; words: string }) => void;
+	silent?: boolean;
+};
+
+
+
+const namedPerformances: Record<string, PerformanceEntry> = {};
+const defaultName = "default";
+
+export function executionTime({ logger, callback, silent = false }: LoggerOptions) {
+	return {
+		start(name: string = defaultName): void {
+			namedPerformances[name] = {
+				startAt: process.hrtime(),
+			};
+		},
+
+		stop(name: string = defaultName): PerformanceResult {
+			const entry = namedPerformances[name];
+			if (!entry?.startAt) {
+				throw new Error(`Namespace: ${name} doesnt exist`);
+			}
+
+			const diff = process.hrtime(entry.startAt);
+			const time = diff[0] * 1e3 + diff[1] * 1e-6;
+
+			const words = prettyHrtime(diff).replace(" ", "");
+			const preciseWords = prettyHrtime(diff, { precise: true }).replace(" ", "");
+			const verboseWords = prettyHrtime(diff, { verbose: true }).replace(" ", "");
+
+			if (logger && callback && !silent) {
+				callback({ time, words });
+			}
+
+			return {
+				name,
+				time,
+				words,
+				preciseWords,
+				verboseWords,
+			};
+		},
+	};
+}

package/src/modules/fonts.ts

@@ -0,0 +1,118 @@
+/**
+ * Inspired by https://github.com/sebholstein/astro-google-fonts-optimizer (MIT).
+ * Parses Google Fonts pasted HTML and inlines fetched @font-face CSS at build time.
+ */
+
+export type SiteFontsConfig = {
+	embeddedCode: string;
+	body: string;
+	headings: string;
+};
+
+type Preconnect = { href: string; crossOrigin: boolean };
+
+
+
+const DEFAULT_PRECONNECTS: Preconnect[] = [
+	{ href: "https://fonts.googleapis.com", crossOrigin: false },
+	{ href: "https://fonts.gstatic.com", crossOrigin: true },
+];
+
+function getAttr(attrs: string, name: string): string | undefined {
+	const re = new RegExp(`\\b${name}\\s*=\\s*["']([^"']*)["']`, "i");
+	return re.exec(attrs)?.[1]?.trim();
+};
+
+function relOf(attrs: string): string | undefined {
+	return getAttr(attrs, "rel")?.toLowerCase();
+}
+
+/** Parse Google Fonts snippet: preconnects + primary css2 stylesheet URL. */
+export function parseGoogleFontsEmbedded(html: string): { stylesheetUrl?: string; preconnects: Preconnect[] } {
+	const preconnects: Preconnect[] = [];
+	let stylesheetUrl: string | undefined;
+	const linkTagRegex = /<link\s+([^>]+)>/gi;
+
+	for (const m of html.matchAll(linkTagRegex)) {
+		const attrs = m[1];
+		const href = getAttr(attrs, "href");
+		if (!href) continue;
+
+		const rel = relOf(attrs);
+		if (rel === "preconnect") {
+			preconnects.push({ href, crossOrigin: /\bcrossorigin\b/i.test(attrs) });
+		} else if (rel === "stylesheet" && href.includes("fonts.googleapis.com")) {
+			if (!stylesheetUrl) stylesheetUrl = href;
+		}
+	}
+
+	return { stylesheetUrl, preconnects };
+};
+
+const userAgents: { name: string; ua: string }[] = [
+	// this must always be the first element here!
+	{
+		name: "woff",
+		ua: "Mozilla/5.0 (Windows NT 10.0; Trident/7.0; rv:11.0) like Gecko",
+	},
+	// from: https://github.com/fontsource/google-font-metadata/blob/main/data/user-agents.json
+	{
+		name: "woff2",
+		ua: 'Mozilla/5.0 (Windows NT 6.3; rv:39.0) Gecko/20100101 Firefox/44.0"',
+	},
+];
+
+export async function downloadFontCSS(url: string): Promise<string | undefined> {
+	if (!url) {
+		throw new Error("No Google Fonts URL provided");
+	}
+
+	const chunks = await Promise.all(
+		userAgents.map(async (entry) => {
+			const res = await fetch(url, {
+				headers: { "User-Agent": entry.ua },
+			});
+			if (!res.ok) throw new Error(res.statusText);
+			const text = await res.text();
+			return text.replace(/ {2,}/g, "").replace(/\t+/g, "").replace(/\n+/g, "");
+		}),
+	);
+
+	return chunks.join(" ");
+};
+
+
+/*
+ *
+ *
+ * FONTS UTILITIES
+ * 
+ */
+
+export type FontsHeadContent =
+	| { rawEmbed: string }
+	| { css: string; preconnects: Preconnect[] }
+	| { url: string; preconnects: Preconnect[] };
+
+
+
+export async function getContent(fontsData: SiteFontsConfig): Promise<FontsHeadContent> {
+	const { stylesheetUrl, preconnects: parsed } = parseGoogleFontsEmbedded(fontsData.embeddedCode);
+	const preconnects = parsed.length > 0 ? parsed : DEFAULT_PRECONNECTS;
+
+	if (!stylesheetUrl) {
+		console.warn("[fonts] No fonts.googleapis.com stylesheet in embeddedCode; injecting raw snippet.");
+		return { rawEmbed: fontsData.embeddedCode };
+	}
+
+	try {
+		const css = await downloadFontCSS(stylesheetUrl);
+		if (css) {
+			return { css, preconnects };
+		}
+		return { url: stylesheetUrl, preconnects };
+	} catch (err) {
+		console.error("[fonts] Downloading CSS from Google Fonts:", err);
+		return { url: stylesheetUrl, preconnects };
+	}
+};

package/src/modules/ogImage.ts

@@ -0,0 +1,125 @@
+import * as path from "node:path";
+import { downloadLogo } from "./favicons.ts";
+
+
+
+const REMOTE_URL = /^https?:\/\//i;
+const cache = new Map<string, Promise<string>>();
+
+/**
+ * Resolve a logo source (remote URL or local path) to a local file path
+ * suitable for `astro-og-canvas`. Remote logos are downloaded once and
+ * cached; SVG sources fall back to the auto-generated PNG companion since
+ * `canvaskit-wasm` does not render SVG natively.
+ */
+export function getLocalLogoPath(source: string): Promise<string> {
+	const cached = cache.get(source);
+	if (cached) return cached;
+
+	const promise = resolveLogoPath(source);
+	cache.set(source, promise);
+	return promise;
+}
+
+async function resolveLogoPath(source: string): Promise<string> {
+	if (!REMOTE_URL.test(source)) {
+		return path.resolve(source);
+	}
+
+	const { relativeLogoPath } = await downloadLogo(source, {});
+
+	// `downloadLogo` already emits a PNG companion next to SVG sources.
+	return relativeLogoPath.toLowerCase().endsWith(".svg") ? relativeLogoPath.replace(/\.svg$/i, ".png") : relativeLogoPath;
+}
+
+/*
+ *
+ *
+ * COLORS UTILITIES
+ * All these functions and formats are compatible and made for the package "astro-og-canvas"
+ */
+
+export type RGB = [number, number, number];
+
+
+
+/**
+ * Convert a CSS color string (`#hex`, `hsl(...)`, `rgb(...)`) or an already
+ * parsed `[R, G, B]` tuple into a `[R, G, B]` tuple consumable by
+ * `astro-og-canvas`.
+ */
+export function toRGB(color: string | RGB): RGB {
+	if (Array.isArray(color)) return color;
+
+	const value = color.trim().toLowerCase();
+	if (value.startsWith("#")) return hexToRGB(value);
+	if (value.startsWith("hsl")) return hslToRGB(value);
+	if (value.startsWith("rgb")) return rgbStringToRGB(value);
+
+	throw new Error(`Unsupported color format: ${color}`);
+}
+
+function hexToRGB(hex: string): RGB {
+	let h = hex.replace("#", "");
+	// Expand shorthand (#RGB / #RGBA) to full form.
+	if (h.length === 3 || h.length === 4) {
+		h = h
+			.split("")
+			.map((c) => c + c)
+			.join("");
+	}
+	if (h.length !== 6 && h.length !== 8) {
+		throw new Error(`Invalid hex color: ${hex}`);
+	}
+	return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+}
+
+function hslToRGB(hsl: string): RGB {
+	const match = hsl.match(/hsla?\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)%\s*,\s*(\d+(?:\.\d+)?)%/);
+	if (!match) throw new Error(`Invalid HSL color: ${hsl}`);
+
+	const h = (((Number(match[1]) % 360) + 360) % 360) / 360;
+	const s = Number(match[2]) / 100;
+	const l = Number(match[3]) / 100;
+
+	if (s === 0) {
+		const v = Math.round(l * 255);
+		return [v, v, v];
+	}
+
+	const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+	const p = 2 * l - q;
+
+	return [
+		Math.round(hueToChannel(p, q, h + 1 / 3) * 255),
+		Math.round(hueToChannel(p, q, h) * 255),
+		Math.round(hueToChannel(p, q, h - 1 / 3) * 255),
+	];
+}
+
+function hueToChannel(p: number, q: number, t: number): number {
+	let v = t;
+	if (v < 0) v += 1;
+	if (v > 1) v -= 1;
+	if (v < 1 / 6) return p + (q - p) * 6 * v;
+	if (v < 1 / 2) return q;
+	if (v < 2 / 3) return p + (q - p) * (2 / 3 - v) * 6;
+	return p;
+}
+
+function rgbStringToRGB(rgb: string): RGB {
+	const match = rgb.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+	if (!match) throw new Error(`Invalid RGB color: ${rgb}`);
+	return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/*
+ *
+ *
+ * OG IMAGE UTILITIES
+ * 
+ */
+
+export function getOgImageURL(origin: string, permalink: string) {
+	return new URL(`/open-graph${permalink}.png`, origin).toString();
+};