@ewanc26/og 0.1.1

package/dist/types-Bn2R50Vr.d.cts

@@ -0,0 +1,60 @@
+/**
+ * @ewanc26/og types
+ */
+interface OgColorConfig {
+    /** Background color (very dark). @default '#0f1a15' */
+    background: string;
+    /** Primary text color. @default '#e8f5e9' */
+    text: string;
+    /** Secondary/accent text (mint). @default '#86efac' */
+    accent: string;
+}
+declare const defaultColors: OgColorConfig;
+interface OgFontConfig {
+    heading?: string;
+    body?: string;
+}
+interface OgNoiseConfig {
+    enabled?: boolean;
+    seed?: string;
+    opacity?: number;
+    colorMode?: 'grayscale' | 'hsl';
+}
+interface OgTemplateProps {
+    title: string;
+    description?: string;
+    siteName: string;
+    image?: string;
+    colors: OgColorConfig;
+    noiseDataUrl?: string;
+    circleNoiseDataUrl?: string;
+    width: number;
+    height: number;
+}
+type OgTemplate = (props: OgTemplateProps) => unknown;
+interface OgGenerateOptions {
+    title: string;
+    description?: string;
+    siteName: string;
+    image?: string;
+    template?: 'blog' | 'profile' | 'default' | OgTemplate;
+    colors?: Partial<OgColorConfig>;
+    fonts?: OgFontConfig;
+    noise?: OgNoiseConfig;
+    noiseSeed?: string;
+    width?: number;
+    height?: number;
+    debugSvg?: boolean;
+}
+interface OgEndpointOptions {
+    siteName: string;
+    defaultTemplate?: 'blog' | 'profile' | 'default' | OgTemplate;
+    colors?: Partial<OgColorConfig>;
+    fonts?: OgFontConfig;
+    noise?: OgNoiseConfig;
+    cacheMaxAge?: number;
+    width?: number;
+    height?: number;
+}
+
+export { type OgGenerateOptions as O, type OgNoiseConfig as a, type OgFontConfig as b, type OgEndpointOptions as c, type OgColorConfig as d, type OgTemplate as e, type OgTemplateProps as f, defaultColors as g };

package/dist/types-Bn2R50Vr.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @ewanc26/og types
+ */
+interface OgColorConfig {
+    /** Background color (very dark). @default '#0f1a15' */
+    background: string;
+    /** Primary text color. @default '#e8f5e9' */
+    text: string;
+    /** Secondary/accent text (mint). @default '#86efac' */
+    accent: string;
+}
+declare const defaultColors: OgColorConfig;
+interface OgFontConfig {
+    heading?: string;
+    body?: string;
+}
+interface OgNoiseConfig {
+    enabled?: boolean;
+    seed?: string;
+    opacity?: number;
+    colorMode?: 'grayscale' | 'hsl';
+}
+interface OgTemplateProps {
+    title: string;
+    description?: string;
+    siteName: string;
+    image?: string;
+    colors: OgColorConfig;
+    noiseDataUrl?: string;
+    circleNoiseDataUrl?: string;
+    width: number;
+    height: number;
+}
+type OgTemplate = (props: OgTemplateProps) => unknown;
+interface OgGenerateOptions {
+    title: string;
+    description?: string;
+    siteName: string;
+    image?: string;
+    template?: 'blog' | 'profile' | 'default' | OgTemplate;
+    colors?: Partial<OgColorConfig>;
+    fonts?: OgFontConfig;
+    noise?: OgNoiseConfig;
+    noiseSeed?: string;
+    width?: number;
+    height?: number;
+    debugSvg?: boolean;
+}
+interface OgEndpointOptions {
+    siteName: string;
+    defaultTemplate?: 'blog' | 'profile' | 'default' | OgTemplate;
+    colors?: Partial<OgColorConfig>;
+    fonts?: OgFontConfig;
+    noise?: OgNoiseConfig;
+    cacheMaxAge?: number;
+    width?: number;
+    height?: number;
+}
+
+export { type OgGenerateOptions as O, type OgNoiseConfig as a, type OgFontConfig as b, type OgEndpointOptions as c, type OgColorConfig as d, type OgTemplate as e, type OgTemplateProps as f, defaultColors as g };

package/package.json

@@ -0,0 +1,63 @@
+{
+	"name": "@ewanc26/og",
+	"version": "0.1.1",
+	"description": "Dynamic OpenGraph image generator with noise backgrounds, bold typography, and Satori-based rendering. Works in SvelteKit endpoints, edge runtimes, and build scripts.",
+	"author": "Ewan Croft",
+	"license": "AGPL-3.0-only",
+	"type": "module",
+	"keywords": [
+		"og",
+		"opengraph",
+		"image",
+		"satori",
+		"sveltekit",
+		"seo",
+		"social"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ewanc26/pkgs.git",
+		"directory": "packages/og"
+	},
+	"homepage": "https://github.com/ewanc26/pkgs/tree/main/packages/og",
+	"bugs": {
+		"url": "https://github.com/ewanc26/pkgs/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"src",
+		"fonts"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		},
+		"./templates": {
+			"types": "./dist/templates/index.d.ts",
+			"import": "./dist/templates/index.js"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"check": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@ewanc26/noise": "workspace:*",
+		"@resvg/resvg-js": "^2.6.0",
+		"satori": "^0.15.2"
+	},
+	"devDependencies": {
+		"@types/node": "^25.5.0",
+		"tsup": "^8.5.1",
+		"typescript": "^5.9.3"
+	}
+}

package/src/endpoint.ts

@@ -0,0 +1,92 @@
+/**
+ * SvelteKit endpoint helpers.
+ */
+
+import { generateOgResponse } from './generate.js'
+import type { OgEndpointOptions, OgTemplate } from './types.js'
+
+/**
+ * Create a SvelteKit GET handler for OG image generation.
+ *
+ * @example
+ * ```ts
+ * // src/routes/og/[title]/+server.ts
+ * import { createOgEndpoint } from '@ewanc26/og';
+ *
+ * export const GET = createOgEndpoint({
+ *   siteName: 'ewancroft.uk',
+ *   defaultTemplate: 'blog',
+ * });
+ * ```
+ *
+ * The endpoint expects query parameters:
+ * - `title` (required): Page title
+ * - `description`: Optional description
+ * - `image`: Optional avatar/logo URL
+ * - `seed`: Optional noise seed
+ */
+export function createOgEndpoint(options: OgEndpointOptions) {
+	const {
+		siteName,
+		defaultTemplate: template = 'default',
+		colors,
+		fonts,
+		noise,
+		cacheMaxAge = 3600,
+		width,
+		height,
+	} = options
+
+	return async ({ url }: { url: URL }) => {
+		const title = url.searchParams.get('title')
+		const description = url.searchParams.get('description') ?? undefined
+		const image = url.searchParams.get('image') ?? undefined
+		const noiseSeed = url.searchParams.get('seed') ?? undefined
+
+		if (!title) {
+			return new Response('Missing title parameter', { status: 400 })
+		}
+
+		try {
+			return await generateOgResponse(
+				{
+					title,
+					description,
+					siteName,
+					image,
+					template: template as OgTemplate,
+					colors,
+					fonts,
+					noise,
+					noiseSeed,
+					width,
+					height,
+				},
+				cacheMaxAge
+			)
+		} catch (error) {
+			console.error('Failed to generate OG image:', error)
+			return new Response('Failed to generate image', { status: 500 })
+		}
+	}
+}
+
+/**
+ * Create a typed OG image URL for use in meta tags.
+ */
+export function createOgImageUrl(
+	baseUrl: string,
+	params: {
+		title: string
+		description?: string
+		image?: string
+		seed?: string
+	}
+): string {
+	const url = new URL(baseUrl)
+	url.searchParams.set('title', params.title)
+	if (params.description) url.searchParams.set('description', params.description)
+	if (params.image) url.searchParams.set('image', params.image)
+	if (params.seed) url.searchParams.set('seed', params.seed)
+	return url.toString()
+}

package/src/fonts.ts

@@ -0,0 +1,121 @@
+/**
+ * @ewanc26/og fonts
+ *
+ * Font loading utilities. Bundles Inter font by default.
+ */
+
+import { readFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { OgFontConfig } from './types.js'
+
+// Declare __dirname for CJS contexts (injected by bundlers)
+declare const __dirname: string | undefined
+
+// ─── Paths ────────────────────────────────────────────────────────────────────
+
+/**
+ * Get the directory of the current module.
+ * Works in both ESM and bundled contexts.
+ */
+function getModuleDir(): string {
+	// ESM context
+	if (typeof import.meta !== 'undefined' && import.meta.url) {
+		return dirname(fileURLToPath(import.meta.url))
+	}
+	// Bundled CJS context - __dirname is injected by bundlers
+	if (typeof __dirname !== 'undefined') {
+		return __dirname
+	}
+	// Fallback
+	return resolve(process.cwd(), 'node_modules/@ewanc26/og/dist')
+}
+
+/**
+ * Resolve the fonts directory relative to the installed package.
+ */
+function getFontsDir(): string {
+	return resolve(getModuleDir(), '../fonts')
+}
+
+/**
+ * Resolve bundled font paths. Uses getters to defer resolution until runtime.
+ */
+export const BUNDLED_FONTS = {
+	get heading() {
+		return resolve(getFontsDir(), 'Inter-Bold.ttf')
+	},
+	get body() {
+		return resolve(getFontsDir(), 'Inter-Regular.ttf')
+	},
+} as const
+
+// ─── Font Loading ──────────────────────────────────────────────────────────────
+
+export interface LoadedFonts {
+	heading: ArrayBuffer
+	body: ArrayBuffer
+}
+
+/**
+ * Load fonts from config, falling back to bundled DM Sans.
+ */
+export async function loadFonts(config?: OgFontConfig): Promise<LoadedFonts> {
+	const headingPath = config?.heading ?? BUNDLED_FONTS.heading
+	const bodyPath = config?.body ?? BUNDLED_FONTS.body
+
+	const [heading, body] = await Promise.all([
+		loadFontFile(headingPath),
+		loadFontFile(bodyPath),
+	])
+
+	return { heading, body }
+}
+
+/**
+ * Load a font from file path or URL.
+ */
+async function loadFontFile(source: string): Promise<ArrayBuffer> {
+	// Handle URLs
+	if (source.startsWith('http://') || source.startsWith('https://')) {
+		const response = await fetch(source)
+		if (!response.ok) {
+			throw new Error(`Failed to load font from URL: ${source}`)
+		}
+		return response.arrayBuffer()
+	}
+
+	// Handle file paths
+	const buffer = await readFile(source)
+	return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength)
+}
+
+// ─── Font Registration for Satori ─────────────────────────────────────────────
+
+export type SatoriFontConfig = {
+	name: string
+	data: ArrayBuffer
+	weight: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+	style: 'normal' | 'italic'
+}
+
+/**
+ * Create Satori-compatible font config from loaded fonts.
+ * Uses Inter font family with weight 700 for headings and 400 for body.
+ */
+export function createSatoriFonts(fonts: LoadedFonts): SatoriFontConfig[] {
+	return [
+		{
+			name: 'Inter',
+			data: fonts.heading,
+			weight: 700,
+			style: 'normal',
+		},
+		{
+			name: 'Inter',
+			data: fonts.body,
+			weight: 400,
+			style: 'normal',
+		},
+	]
+}

package/src/generate.ts

@@ -0,0 +1,137 @@
+/**
+ * Core OG image generation.
+ * Uses satori for JSX-to-SVG and resvg-js for SVG-to-PNG.
+ */
+
+import satori from 'satori'
+import { Resvg } from '@resvg/resvg-js'
+import { loadFonts, createSatoriFonts } from './fonts.js'
+import { generateNoiseDataUrl, generateCircleNoiseDataUrl } from './noise.js'
+import { getTemplate } from './templates/index.js'
+import { defaultColors } from './types.js'
+import type {
+	OgGenerateOptions,
+	OgColorConfig,
+	OgTemplateProps,
+} from './types.js'
+
+// Standard OG image dimensions
+export const OG_WIDTH = 1200
+export const OG_HEIGHT = 630
+
+/**
+ * Generate an OG image as PNG Buffer.
+ */
+export async function generateOgImage(options: OgGenerateOptions): Promise<Buffer> {
+	const {
+		title,
+		description,
+		siteName,
+		image,
+		template = 'blog',
+		colors: colorOverrides,
+		fonts: fontConfig,
+		noise: noiseConfig,
+		noiseSeed,
+		width = OG_WIDTH,
+		height = OG_HEIGHT,
+		debugSvg = false,
+	} = options
+
+	// Merge colours
+	const colors: OgColorConfig = {
+		...defaultColors,
+		...colorOverrides,
+	}
+
+	// Load fonts
+	const fonts = await loadFonts(fontConfig)
+	const satoriFonts = createSatoriFonts(fonts)
+
+	// Generate noise background
+	const noiseEnabled = noiseConfig?.enabled !== false
+	const noiseSeedValue = noiseSeed || noiseConfig?.seed || title
+	const noiseDataUrl = noiseEnabled
+		? generateNoiseDataUrl({
+				seed: noiseSeedValue,
+				width,
+				height,
+				opacity: noiseConfig?.opacity ?? 0.4,
+				colorMode: noiseConfig?.colorMode ?? 'grayscale',
+			})
+		: undefined
+
+	// Generate circular noise decoration
+	const circleNoiseDataUrl = noiseEnabled
+		? generateCircleNoiseDataUrl({
+				seed: `${noiseSeedValue}-circle`,
+				size: 200,
+				opacity: noiseConfig?.opacity ?? 0.15,
+				colorMode: noiseConfig?.colorMode ?? 'grayscale',
+			})
+		: undefined
+
+	// Get template function
+	const templateFn = getTemplate(template as Parameters<typeof getTemplate>[0])
+
+	// Build template props
+	const props: OgTemplateProps = {
+		title,
+		description,
+		siteName,
+		image,
+		colors,
+		noiseDataUrl,
+		circleNoiseDataUrl,
+		width,
+		height,
+	}
+
+	// Render template to Satori-compatible structure
+	const element = templateFn(props)
+
+	// Generate SVG with satori
+	const svg = await satori(element as Parameters<typeof satori>[0], {
+		width,
+		height,
+		fonts: satoriFonts,
+	})
+
+	// Debug: return SVG string
+	if (debugSvg) {
+		return Buffer.from(svg)
+	}
+
+	// Convert SVG to PNG with resvg-js
+	const resvg = new Resvg(svg, {
+		fitTo: {
+			mode: 'width',
+			value: width,
+		},
+	})
+	const pngData = resvg.render()
+
+	return Buffer.from(pngData.asPng())
+}
+
+/**
+ * Generate OG image and return as base64 data URL.
+ */
+export async function generateOgImageDataUrl(options: OgGenerateOptions): Promise<string> {
+	const png = await generateOgImage(options)
+	return `data:image/png;base64,${png.toString('base64')}`
+}
+
+/**
+ * Generate OG image and return as Response (for SvelteKit endpoints).
+ */
+export async function generateOgResponse(options: OgGenerateOptions, cacheMaxAge = 3600): Promise<Response> {
+	const png = await generateOgImage(options)
+
+	return new Response(png, {
+		headers: {
+			'Content-Type': 'image/png',
+			'Cache-Control': `public, max-age=${cacheMaxAge}`,
+		},
+	})
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @ewanc26/og
+ *
+ * Dynamic OpenGraph image generator with noise backgrounds, bold typography,
+ * and Satori-based rendering. Works in SvelteKit endpoints, edge runtimes,
+ * and build scripts.
+ *
+ * @example
+ * ```ts
+ * import { generateOgImage, createOgEndpoint } from '@ewanc26/og';
+ * import { blogTemplate } from '@ewanc26/og/templates';
+ *
+ * // Generate PNG
+ * const png = await generateOgImage({
+ *   title: 'My Blog Post',
+ *   description: 'A description',
+ *   siteName: 'ewancroft.uk',
+ * });
+ *
+ * // SvelteKit endpoint
+ * export const GET = createOgEndpoint({ siteName: 'ewancroft.uk' });
+ * ```
+ */
+
+// Core generation
+export { generateOgImage, generateOgImageDataUrl, generateOgResponse, OG_WIDTH, OG_HEIGHT } from './generate.js'
+
+// Types
+export type {
+	OgColorConfig,
+	OgFontConfig,
+	OgNoiseConfig,
+	OgTemplateProps,
+	OgTemplate,
+	OgGenerateOptions,
+	OgEndpointOptions,
+} from './types.js'
+export { defaultColors } from './types.js'
+
+// Noise (for advanced customization)
+export { generateNoiseDataUrl, generateCircleNoiseDataUrl } from './noise.js'
+
+// Fonts (for advanced customization)
+export { loadFonts, createSatoriFonts, BUNDLED_FONTS } from './fonts.js'
+
+// Endpoint helpers
+export { createOgEndpoint } from './endpoint.js'
+
+// SVG to PNG conversion
+export { svgToPng, svgToPngDataUrl, svgToPngResponse } from './svg.js'
+export type { SvgToPngOptions } from './svg.js'

package/src/noise.ts

@@ -0,0 +1,90 @@
+/**
+ * @ewanc26/og noise
+ */
+
+import { generateNoisePixels } from '@ewanc26/noise'
+import { PNGEncoder } from './png-encoder.js'
+import type { OgNoiseConfig } from './types.js'
+
+export interface NoiseOptions {
+	seed: string
+	width: number
+	height: number
+	opacity?: number
+	colorMode?: OgNoiseConfig['colorMode']
+}
+
+export interface CircleNoiseOptions {
+	seed: string
+	size: number
+	opacity?: number
+	colorMode?: OgNoiseConfig['colorMode']
+}
+
+/**
+ * Generate a noise PNG as a data URL.
+ */
+export function generateNoiseDataUrl(options: NoiseOptions): string {
+	const { seed, width, height, opacity = 0.4, colorMode = 'grayscale' } = options
+
+	const pixels = generateNoisePixels(width, height, seed, {
+		gridSize: 4,
+		octaves: 3,
+		colorMode: colorMode === 'grayscale'
+			? { type: 'grayscale', range: [20, 60] }
+			: { type: 'hsl', hueRange: 40, saturationRange: [30, 50], lightnessRange: [30, 50] }
+	})
+
+	if (opacity < 1) {
+		for (let i = 3; i < pixels.length; i += 4) {
+			pixels[i] = Math.round(pixels[i] * opacity)
+		}
+	}
+
+	const pngBuffer = PNGEncoder.encode(pixels, width, height)
+	return `data:image/png;base64,${pngBuffer.toString('base64')}`
+}
+
+/**
+ * Generate a circular noise PNG as a data URL.
+ * Creates a square image with circular transparency mask.
+ */
+export function generateCircleNoiseDataUrl(options: CircleNoiseOptions): string {
+	const { seed, size, opacity = 0.15, colorMode = 'grayscale' } = options
+
+	const pixels = generateNoisePixels(size, size, seed, {
+		gridSize: 4,
+		octaves: 3,
+		colorMode: colorMode === 'grayscale'
+			? { type: 'grayscale', range: [30, 70] }
+			: { type: 'hsl', hueRange: 40, saturationRange: [30, 50], lightnessRange: [30, 50] }
+	})
+
+	const center = size / 2
+	const radius = size / 2
+
+	// Apply circular mask
+	for (let y = 0; y < size; y++) {
+		for (let x = 0; x < size; x++) {
+			const idx = (y * size + x) * 4
+			const dx = x - center + 0.5
+			const dy = y - center + 0.5
+			const dist = Math.sqrt(dx * dx + dy * dy)
+
+			if (dist > radius) {
+				// Outside circle - fully transparent
+				pixels[idx + 3] = 0
+			} else if (dist > radius - 2) {
+				// Anti-alias edge
+				const edgeOpacity = (radius - dist) / 2
+				pixels[idx + 3] = Math.round(255 * edgeOpacity * opacity)
+			} else {
+				// Inside circle - apply opacity
+				pixels[idx + 3] = Math.round(255 * opacity)
+			}
+		}
+	}
+
+	const pngBuffer = PNGEncoder.encode(pixels, size, size)
+	return `data:image/png;base64,${pngBuffer.toString('base64')}`
+}