create-refrakt 0.14.2 → 0.14.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-refrakt",
   "description": "Scaffold a new refrakt.md project",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -30,8 +30,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.2.0",
-    "@refrakt-md/plan": "0.14.2",
-    "@refrakt-md/runes": "0.14.2",
-    "@refrakt-md/transform": "0.14.2"
+    "@refrakt-md/plan": "0.14.4",
+    "@refrakt-md/runes": "0.14.4",
+    "@refrakt-md/transform": "0.14.4"
   }
 }

package/template-astro/src/pages/[...slug].astro

@@ -1,5 +1,5 @@
 ---
-import { getTransform, getSite, getTheme, getHighlightTransform } from '../setup';
+import { getTransform, getSite, getTheme, getHighlightTransform, seoSiteFields } from '../setup';
 import { renderPage, buildSeoHead } from '@refrakt-md/astro';
 import type { RendererNode } from '@refrakt-md/types';
 
@@ -51,7 +51,7 @@ export async function getStaticPaths() {
 const { page, seo, highlightCss } = Astro.props;
 const theme = await getTheme();
 const html = renderPage({ theme, page });
-const head = buildSeoHead({ title: page.title, frontmatter: page.frontmatter, seo });
+const head = buildSeoHead({ title: page.title, frontmatter: page.frontmatter, seo, ...seoSiteFields });
 const needsBehaviors = html.includes('data-layout-behaviors') || html.includes('data-rune=');
 const contextData = JSON.stringify({ pages: page.pages, currentUrl: page.url });
 ---

package/template-astro/src/setup.ts

@@ -1,91 +1,57 @@
-import { loadContent, buildHighlightOptions } from '@refrakt-md/content';
-import { assembleThemeConfig, createTransform } from '@refrakt-md/transform';
+import { createRefraktLoader } from '@refrakt-md/content';
 import { loadRefraktConfig, resolveSite } from '@refrakt-md/transform/node';
-import { loadPlugin, mergePlugins, runes as coreRunes } from '@refrakt-md/runes';
 import { getThemePackage } from '@refrakt-md/types';
-import type { Schema } from '@markdoc/markdoc';
 import { readFileSync } from 'node:fs';
-import * as path from 'node:path';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
 
-const config = loadRefraktConfig(path.resolve('refrakt.config.json'));
+const configPath = resolve('refrakt.config.json');
+const config = loadRefraktConfig(configPath);
 const { site } = resolveSite(config);
-const themePackage = getThemePackage(site.theme);
-const contentDir = path.resolve(site.contentDir);
 
-const routeRules = site.routeRules ?? [{ pattern: '**', layout: 'default' }];
-
-let _transform: ((tree: any) => any) | null = null;
-let _hl: { (tree: any): any; css: string } | null = null;
+const loader = createRefraktLoader({ configPath });
+
+export const getTransform = () => loader.getTransform();
+export const getHighlightTransform = () => loader.getHighlightTransform();
+export const getSite = () => loader.getSite();
+
+/** Site-level SEO fields surfaced for `buildSeoHead`. Read once from refrakt.config.json. */
+export const seoSiteFields = {
+	siteName: site.siteName,
+	baseUrl: site.baseUrl,
+	defaultImage: site.defaultImage,
+	logo: site.logo,
+};
+
+/**
+ * Build the AstroTheme `{ manifest, layouts }` shape for `renderPage`.
+ *
+ * Loads the theme package's manifest + layouts and bakes site-level fields
+ * (`routeRules`, `siteName`, `baseUrl`, `defaultImage`, `logo`) into the
+ * manifest so the SEO and route-resolution paths have what they need.
+ *
+ * Memoised — the theme is resolved once per process.
+ */
 let _theme: { manifest: any; layouts: any } | null = null;
-let _communityTags: Record<string, Schema> | undefined;
-let _packages: any[] | undefined;
-
-async function init() {
-	if (_transform) return;
+export async function getTheme() {
+	if (_theme) return _theme;
 
-	const [themeModule, layoutsModule] = await Promise.all([
-		import(themePackage + '/transform'),
-		import(themePackage + '/layouts'),
-	]);
+	const themePackage = getThemePackage(site.theme);
+	const layouts = (await import(themePackage + '/layouts')).layouts;
 
-	// Manifest is a JSON file — resolve its path and read directly
-	const { createRequire: cr } = await import('node:module');
-	const manifestPath = cr(import.meta.url).resolve(themePackage + '/manifest');
+	const manifestPath = createRequire(import.meta.url).resolve(themePackage + '/manifest');
 	const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
 
 	_theme = {
-		manifest: { ...manifest, routeRules },
-		layouts: layoutsModule.layouts,
+		manifest: {
+			...manifest,
+			routeRules: site.routeRules ?? [{ pattern: '**', layout: 'default' }],
+			...(site.siteName && { siteName: site.siteName }),
+			...(site.baseUrl && { baseUrl: site.baseUrl }),
+			...(site.defaultImage && { defaultImage: site.defaultImage }),
+			...(site.logo && { logo: site.logo }),
+		},
+		layouts,
 	};
-
-	const themeConfig = themeModule.themeConfig ?? themeModule.luminaConfig ?? themeModule.default;
-
-	let transformConfig = themeConfig;
-
-	const pluginNames = site.plugins ?? config.plugins ?? [];
-	if (pluginNames.length > 0) {
-		const loaded = await Promise.all(
-			pluginNames.map((name: string) => loadPlugin(name))
-		);
-		const coreRuneNames = new Set(Object.keys(coreRunes));
-		const merged = mergePlugins(loaded, coreRuneNames, site.runes?.prefer);
-
-		_communityTags = Object.keys(merged.tags).length > 0 ? merged.tags : undefined;
-		_packages = loaded.map((l: any) => l.pkg);
-
-		const { config: assembledConfig } = assembleThemeConfig({
-			coreConfig: themeConfig,
-			pluginRunes: merged.themeRunes,
-			pluginIcons: merged.themeIcons,
-			pluginBackgrounds: merged.themeBackgrounds,
-			extensions: merged.extensions as any,
-			provenance: merged.provenance,
-		});
-
-		transformConfig = assembledConfig;
-	}
-
-	_transform = createTransform(transformConfig);
-}
-
-export async function getTransform() {
-	await init();
-	return _transform!;
-}
-
-export async function getTheme() {
-	await init();
-	return _theme!;
-}
-
-export async function getHighlightTransform() {
-	if (_hl) return _hl;
-	const { createHighlightTransform } = await import('@refrakt-md/highlight');
-	_hl = await createHighlightTransform(buildHighlightOptions(site));
-	return _hl;
-}
-
-export async function getSite() {
-	await init();
-	return loadContent(contentDir, '/', {}, _communityTags, _packages);
+	return _theme;
 }

package/template-eleventy/eleventy.config.js

@@ -1,4 +1,14 @@
-import { refraktPlugin } from '@refrakt-md/eleventy';
+import { refraktPlugin, writeSiteTokensCss } from '@refrakt-md/eleventy';
+import { resolve } from 'node:path';
+
+// Compose site-level token overrides (SPEC-048 presets + tokens + modes,
+// SPEC-056 scoped tint projections) once at config-load time and write the
+// CSS to a build-input directory. Eleventy's passthrough copy picks it up
+// and ships it as `/css/site-tokens.css`.
+await writeSiteTokensCss(
+	resolve('refrakt.config.json'),
+	resolve('src/_generated/site-tokens.css'),
+);
 
 export default function (eleventyConfig) {
 	eleventyConfig.addPlugin(refraktPlugin, {
@@ -6,11 +16,15 @@ export default function (eleventyConfig) {
 		cssPrefix: '/css',
 		behaviorFile: 'node_modules/@refrakt-md/behaviors/dist/index.js',
 		jsPrefix: '/js',
+		// Watch content (and any sandbox examples) for --serve mode so edits
+		// trigger a rebuild + browser reload.
+		contentDir: resolve('content'),
 	});
 
 	eleventyConfig.addPassthroughCopy({
 		'node_modules/@refrakt-md/lumina/tokens': '/css/tokens',
 		'node_modules/@refrakt-md/lumina/styles': '/css/styles',
+		'src/_generated/site-tokens.css': '/css/site-tokens.css',
 	});
 
 	return {

package/template-eleventy/src/_data/refrakt.js

@@ -1,5 +1,19 @@
 import { createDataFile } from '@refrakt-md/eleventy';
+import { loadRefraktConfig, resolveSite } from '@refrakt-md/transform/node';
 import manifest from '@refrakt-md/lumina/manifest';
 import { layouts } from '@refrakt-md/lumina/layouts';
+import { resolve } from 'node:path';
 
-export default createDataFile({ theme: { manifest, layouts } });
+const config = loadRefraktConfig(resolve('refrakt.config.json'));
+const { site } = resolveSite(config);
+
+export default createDataFile({
+	theme: { manifest, layouts },
+	contentDir: site.contentDir,
+	seo: {
+		siteName: site.siteName,
+		baseUrl: site.baseUrl,
+		defaultImage: site.defaultImage,
+		logo: site.logo,
+	},
+});

package/template-eleventy/src/_includes/base.njk

@@ -7,6 +7,7 @@
   {{ seo.metaTags | safe }}
   {{ seo.jsonLd | safe }}
   <link rel="stylesheet" href="/css/index.css">
+  <link rel="stylesheet" href="/css/site-tokens.css">
 </head>
 <body>
   {{ html | safe }}

package/template-html/build.ts

@@ -1,5 +1,15 @@
-import { loadContent, buildHighlightOptions } from '@refrakt-md/content';
-import { renderFullPage } from '@refrakt-md/html';
+import {
+	loadContent,
+	buildHighlightOptions,
+	analyzeRuneUsage,
+	formatPipelineSummary,
+} from '@refrakt-md/content';
+import {
+	renderFullPage,
+	composeSiteTokensCss,
+	computeUsedCssBlocks,
+	buildUsedCssImports,
+} from '@refrakt-md/html';
 import type { HtmlTheme } from '@refrakt-md/html';
 import { assembleThemeConfig, createTransform, defaultLayout } from '@refrakt-md/transform';
 import { loadRefraktConfig, resolveSite } from '@refrakt-md/transform/node';
@@ -9,13 +19,16 @@ import { getThemePackage } from '@refrakt-md/types';
 import type { RendererNode } from '@refrakt-md/types';
 import type { Schema } from '@markdoc/markdoc';
 import { mkdirSync, writeFileSync, cpSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 
 // --- Configuration -------------------------------------------------------
 
-const config = loadRefraktConfig(path.resolve('refrakt.config.json'));
+const configPath = path.resolve('refrakt.config.json');
+const config = loadRefraktConfig(configPath);
 const { site } = resolveSite(config);
 const contentDir = path.resolve(site.contentDir);
+const configDir = path.dirname(configPath);
 const outDir = 'build';
 
 // --- Helpers --------------------------------------------------------------
@@ -88,6 +101,10 @@ async function build() {
 	// Create highlight transform
 	const hl = await createHighlightTransform(buildHighlightOptions(site));
 
+	// Compose site-level token overrides CSS (SPEC-048 + SPEC-056).
+	// Empty string when the site has no overrides; safe to inline either way.
+	const siteTokensCss = await composeSiteTokensCss(site, configDir);
+
 	// Build theme object for HTML adapter
 	const themeManifestModule = await import(themePackage + '/manifest', { with: { type: 'json' } });
 	const manifest = themeManifestModule.default;
@@ -102,13 +119,55 @@ async function build() {
 		},
 	};
 
-	// Load content
-	const site = await loadContent(contentDir, '/', icons, communityTags);
+	// Load content. The HTML adapter's build script doesn't surface
+	// `security` / `variables` via a CLI flag — for hosted-product use, edit
+	// this file to pass them through to `loadContent` (matches the option
+	// shape `createRefraktLoader` accepts for the Vite-based adapters).
+	const loadedSite = await loadContent(contentDir, '/', icons, communityTags);
+
+	// Print the standard Phase 1/2/3/4 + warnings summary so the HTML build
+	// gets the same visibility into the cross-page pipeline that the SvelteKit
+	// reference adapter prints.
+	process.stderr.write(
+		formatPipelineSummary(loadedSite.pipelineStats, loadedSite.pipelineWarnings),
+	);
 
 	mkdirSync(outDir, { recursive: true });
 
+	// Tree-shake per-rune CSS: only ship blocks that actually appear in the
+	// page corpus. Falls back to the theme barrel if analysis fails.
+	const usageReport = analyzeRuneUsage(loadedSite.pages);
+	let stylesheets: string[];
+	let blocksToCopy: { src: string; dest: string }[] = [];
+	try {
+		const { usedBlocks, stylesDir } = await computeUsedCssBlocks(
+			usageReport.allTypes,
+			finalConfig,
+			themePackage,
+		);
+		const themeEntryUrl = import.meta.resolve(themePackage);
+		const themeDir = path.dirname(fileURLToPath(themeEntryUrl));
+		stylesheets = ['/base.css'];
+		blocksToCopy.push({
+			src: path.join(themeDir, 'base.css'),
+			dest: path.join(outDir, 'base.css'),
+		});
+		for (const block of [...usedBlocks].sort()) {
+			stylesheets.push(`/styles/runes/${block}.css`);
+			blocksToCopy.push({
+				src: path.join(stylesDir, `${block}.css`),
+				dest: path.join(outDir, 'styles', 'runes', `${block}.css`),
+			});
+		}
+	} catch (err) {
+		console.warn(
+			`Tree-shaking skipped (${(err as Error).message}); shipping full theme barrel.`,
+		);
+		stylesheets = ['/styles.css'];
+	}
+
 	// Collect page metadata for navigation
-	const pages = site.pages
+	const pages = loadedSite.pages
 		.filter(p => !p.route.draft)
 		.map(p => ({
 			url: p.route.url,
@@ -118,7 +177,7 @@ async function build() {
 
 	let count = 0;
 
-	for (const page of site.pages) {
+	for (const page of loadedSite.pages) {
 		if (page.route.draft) continue;
 
 		// Serialize → identity transform → highlight
@@ -147,9 +206,17 @@ async function build() {
 				},
 			},
 			{
-				stylesheets: ['/styles.css'],
-				headExtra: hl.css ? `<style>${hl.css}</style>` : '',
+				stylesheets,
+				// Order matters: highlight CSS first, site-tokens CSS second so
+				// site-level `--rf-*` overrides resolve last in the cascade.
+				headExtra:
+					(hl.css ? `<style>${hl.css}</style>` : '') +
+					(siteTokensCss ? `<style>${siteTokensCss}</style>` : ''),
 				seo: page.seo,
+				baseUrl: site.baseUrl,
+				siteName: site.siteName,
+				defaultImage: site.defaultImage,
+				logo: site.logo,
 			},
 		);
 
@@ -163,16 +230,27 @@ async function build() {
 		count++;
 	}
 
-	// Copy theme CSS to build directory
-	try {
-		const themePkg = themePackage;
-		const themeDir = path.dirname(require.resolve(themePkg + '/package.json'));
-		const cssPath = path.join(themeDir, 'index.css');
-		if (existsSync(cssPath)) {
-			cpSync(cssPath, path.join(outDir, 'styles.css'));
+	// Copy the per-rune CSS files (or the theme barrel as fallback)
+	if (blocksToCopy.length > 0) {
+		for (const { src, dest } of blocksToCopy) {
+			if (existsSync(src)) {
+				mkdirSync(path.dirname(dest), { recursive: true });
+				cpSync(src, dest);
+			}
+		}
+	} else {
+		try {
+			const themePkg = themePackage;
+			const themeDir = path.dirname(require.resolve(themePkg + '/package.json'));
+			const cssPath = path.join(themeDir, 'index.css');
+			if (existsSync(cssPath)) {
+				cpSync(cssPath, path.join(outDir, 'styles.css'));
+			}
+		} catch {
+			console.warn(
+				'Warning: Could not copy theme CSS. Add a styles.css to the build directory manually.',
+			);
 		}
-	} catch {
-		console.warn('Warning: Could not copy theme CSS. Add a styles.css to the build directory manually.');
 	}
 
 	console.log(`Built ${count} pages to ${outDir}/`);

package/template-next/app/[...slug]/page.tsx

@@ -1,25 +1,35 @@
 import { loadContent } from '@refrakt-md/content';
 import { assembleThemeConfig, createTransform } from '@refrakt-md/transform';
+import { loadRefraktConfig, resolveSite } from '@refrakt-md/transform/node';
 import { loadPlugin, mergePlugins, runes as coreRunes } from '@refrakt-md/runes';
+import { getThemePackage } from '@refrakt-md/types';
 import manifest from '@refrakt-md/lumina/manifest';
 import { layouts } from '@refrakt-md/lumina/layouts';
 const theme = { manifest, layouts };
-import { RefraktContent, buildMetadata, buildUrlFromParams, hasInteractiveRunes } from '@refrakt-md/next';
+import { RefraktContent, buildMetadata, buildJsonLd, buildUrlFromParams, hasInteractiveRunes } from '@refrakt-md/next';
 import { BehaviorInit } from '@refrakt-md/next/client';
 import type { RendererNode } from '@refrakt-md/types';
-import type { RefraktConfig } from '@refrakt-md/types';
 import type { Schema } from '@markdoc/markdoc';
-import { readFileSync } from 'node:fs';
 import * as path from 'node:path';
 
-const config: RefraktConfig = JSON.parse(readFileSync(path.resolve('refrakt.config.json'), 'utf-8'));
-const contentDir = path.resolve(config.contentDir);
+const config = loadRefraktConfig(path.resolve('refrakt.config.json'));
+const { site } = resolveSite(config);
+const contentDir = path.resolve(site.contentDir);
+
+// Site-level SEO fields surfaced into buildMetadata + buildJsonLd.
+const seoSite = {
+	siteName: site.siteName,
+	baseUrl: site.baseUrl,
+	defaultImage: site.defaultImage,
+	logo: site.logo,
+};
 
 async function getTransformAndTags() {
-	const themeModule = await import(config.theme + '/transform');
+	const themePackage = getThemePackage(site.theme);
+	const themeModule = await import(themePackage + '/transform');
 	const themeConfig = themeModule.themeConfig ?? themeModule.luminaConfig ?? themeModule.default;
 
-	const pluginNames = config.plugins ?? [];
+	const pluginNames = site.plugins ?? [];
 	if (pluginNames.length === 0) {
 		return { transform: createTransform(themeConfig), communityTags: undefined };
 	}
@@ -28,7 +38,7 @@ async function getTransformAndTags() {
 		pluginNames.map((name: string) => loadPlugin(name))
 	);
 	const coreRuneNames = new Set(Object.keys(coreRunes));
-	const merged = mergePlugins(loaded, coreRuneNames, config.runes?.prefer);
+	const merged = mergePlugins(loaded, coreRuneNames, site.runes?.prefer);
 
 	const communityTags: Record<string, Schema> | undefined =
 		Object.keys(merged.tags).length > 0 ? merged.tags : undefined;
@@ -73,6 +83,7 @@ export async function generateMetadata({ params }: { params: Promise<{ slug?: st
 		title: (page.frontmatter.title as string) ?? '',
 		frontmatter: page.frontmatter,
 		seo: page.seo,
+		...seoSite,
 	});
 }
 

package/template-next/app/layout.tsx

@@ -1,9 +1,21 @@
 import '@refrakt-md/lumina';
+import { getSiteTokensCss } from '@refrakt-md/next';
 import type { ReactNode } from 'react';
 
-export default function RootLayout({ children }: { children: ReactNode }) {
+// Site-level token overrides (SPEC-048 + SPEC-056). Computed once per request
+// in the Server Component scope; the resulting CSS layers on top of the
+// theme package's barrel so `--rf-*` overrides resolve last.
+const siteTokensCssPromise = getSiteTokensCss();
+
+export default async function RootLayout({ children }: { children: ReactNode }) {
+	const siteTokensCss = await siteTokensCssPromise;
 	return (
 		<html lang="en">
+			<head>
+				{siteTokensCss && (
+					<style dangerouslySetInnerHTML={{ __html: siteTokensCss }} />
+				)}
+			</head>
 			<body>{children}</body>
 		</html>
 	);