@refrakt-md/next 0.14.2 → 0.14.4

package/dist/index.d.ts

@@ -6,5 +6,9 @@ export type { RefraktMetadataInput } from './metadata.js';
 export { buildUrlFromParams } from './loader.js';
 export type { PageParams } from './loader.js';
 export { hasInteractiveRunes } from './behaviors.js';
+export { getSiteTokensCss } from './tokens.js';
+export { getUsedCssImports } from './tokens.js';
+export { printPipelineSummary } from './tokens.js';
+export { createNextLoader } from './tokens.js';
 export type { NextTheme } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGrD,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAIrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAK/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIhD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAInD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -7,4 +7,17 @@ export { buildMetadata, buildJsonLd } from './metadata.js';
 export { buildUrlFromParams } from './loader.js';
 // Behaviors (server-side detection only)
 export { hasInteractiveRunes } from './behaviors.js';
+// Site-level token-overrides CSS (SPEC-048 + SPEC-056). Async helper consumers
+// call at module-scope in `app/layout.tsx` and inline via `<style />`.
+export { getSiteTokensCss } from './tokens.js';
+// Tree-shaken per-rune CSS imports. Async helper returns the ordered list of
+// module specifiers the consumer should import in `app/layout.tsx` (via
+// generated code or a pre-build script).
+export { getUsedCssImports } from './tokens.js';
+// Pipeline-stats summary writer — matches the SvelteKit reference's build
+// output across the refrakt stack.
+export { printPipelineSummary } from './tokens.js';
+// Pre-configured loader factory — typed shorthand around createRefraktLoader
+// for the common Next.js case (configPath + site + variables + security).
+export { createNextLoader } from './tokens.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY;AACZ,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM;AACN,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG3D,0BAA0B;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,yCAAyC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY;AACZ,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM;AACN,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG3D,0BAA0B;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,yCAAyC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD,+EAA+E;AAC/E,uEAAuE;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,6EAA6E;AAC7E,wEAAwE;AACxE,yCAAyC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,0EAA0E;AAC1E,mCAAmC;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,6EAA6E;AAC7E,0EAA0E;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/metadata.d.ts

@@ -1,5 +1,10 @@
-import type { SeoInput } from '@refrakt-md/transform';
-export type RefraktMetadataInput = SeoInput;
+import type { SeoInput, SeoToHtmlOptions } from '@refrakt-md/transform';
+/**
+ * Combined input shape: per-page SEO (title, frontmatter, seo block) plus
+ * site-level options (siteName, baseUrl, defaultImage, logo). Matches the
+ * surface every other adapter's SEO helper accepts.
+ */
+export type RefraktMetadataInput = SeoInput & SeoToHtmlOptions;
 /**
  * Transform refrakt page SEO data into a Next.js Metadata object.
  *
@@ -7,12 +12,29 @@ export type RefraktMetadataInput = SeoInput;
  *
  *   export async function generateMetadata({ params }) {
  *     const page = await loadPage(params.slug);
- *     return buildMetadata({ title: page.title, seo: page.seo });
+ *     return buildMetadata({
+ *       title: page.title,
+ *       seo: page.seo,
+ *       siteName: site.siteName,
+ *       baseUrl: site.baseUrl,
+ *       defaultImage: site.defaultImage,
+ *     });
  *   }
+ *
+ * When site-level options are supplied:
+ * - `metadata.metadataBase` is set to `new URL(baseUrl)` so Next.js
+ *   absolutizes relative URLs natively in og:url, canonical, etc.
+ * - `metadata.openGraph.siteName` carries the site name
+ * - `metadata.openGraph.images` falls back to `[defaultImage]` for pages
+ *   without their own image
  */
 export declare function buildMetadata(input: RefraktMetadataInput): Record<string, unknown>;
 /**
  * Build JSON-LD structured data objects for inclusion in the page head.
+ *
+ * Page-level JSON-LD entries (from `seo.jsonLd`) come first. When `baseUrl`
+ * + `siteName` are supplied, synthetic WebSite and Organization entries are
+ * appended — matching the SvelteKit reference's `seoToHtml` output.
  */
-export declare function buildJsonLd(input?: SeoInput): object[];
+export declare function buildJsonLd(input?: RefraktMetadataInput): object[];
 //# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAE5C;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2BlF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,EAAE,CAGtD"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,gBAAgB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwClF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,oBAAoB,GAAG,MAAM,EAAE,CA2BlE"}

package/dist/metadata.js

@@ -6,12 +6,34 @@ import { extractSeoData } from '@refrakt-md/transform';
  *
  *   export async function generateMetadata({ params }) {
  *     const page = await loadPage(params.slug);
- *     return buildMetadata({ title: page.title, seo: page.seo });
+ *     return buildMetadata({
+ *       title: page.title,
+ *       seo: page.seo,
+ *       siteName: site.siteName,
+ *       baseUrl: site.baseUrl,
+ *       defaultImage: site.defaultImage,
+ *     });
  *   }
+ *
+ * When site-level options are supplied:
+ * - `metadata.metadataBase` is set to `new URL(baseUrl)` so Next.js
+ *   absolutizes relative URLs natively in og:url, canonical, etc.
+ * - `metadata.openGraph.siteName` carries the site name
+ * - `metadata.openGraph.images` falls back to `[defaultImage]` for pages
+ *   without their own image
  */
 export function buildMetadata(input) {
+    const { siteName, baseUrl, defaultImage } = input;
     const data = extractSeoData(input);
     const metadata = {};
+    if (baseUrl) {
+        try {
+            metadata.metadataBase = new URL(baseUrl);
+        }
+        catch {
+            // Invalid baseUrl — skip metadataBase rather than throwing.
+        }
+    }
     if (data.title)
         metadata.title = data.title;
     if (data.description)
@@ -21,12 +43,15 @@ export function buildMetadata(input) {
         openGraph.title = data.title;
     if (data.description)
         openGraph.description = data.description;
-    if (data.ogImage)
-        openGraph.images = [data.ogImage];
+    if (siteName)
+        openGraph.siteName = siteName;
     if (data.ogUrl)
         openGraph.url = data.ogUrl;
     if (data.ogType)
         openGraph.type = data.ogType;
+    const ogImage = data.ogImage ?? defaultImage;
+    if (ogImage)
+        openGraph.images = [ogImage];
     if (Object.keys(openGraph).length > 0)
         metadata.openGraph = openGraph;
     const twitter = {};
@@ -34,9 +59,9 @@ export function buildMetadata(input) {
         twitter.title = data.title;
     if (data.description)
         twitter.description = data.description;
-    if (data.ogImage) {
+    if (ogImage) {
         twitter.card = 'summary_large_image';
-        twitter.images = [data.ogImage];
+        twitter.images = [ogImage];
     }
     else {
         twitter.card = 'summary';
@@ -47,10 +72,36 @@ export function buildMetadata(input) {
 }
 /**
  * Build JSON-LD structured data objects for inclusion in the page head.
+ *
+ * Page-level JSON-LD entries (from `seo.jsonLd`) come first. When `baseUrl`
+ * + `siteName` are supplied, synthetic WebSite and Organization entries are
+ * appended — matching the SvelteKit reference's `seoToHtml` output.
  */
 export function buildJsonLd(input) {
     if (!input)
         return [];
-    return extractSeoData(input).jsonLd;
+    const { siteName, baseUrl, logo } = input;
+    const data = extractSeoData(input);
+    const entries = [...data.jsonLd];
+    if (baseUrl) {
+        const name = siteName ?? '';
+        entries.push({
+            '@context': 'https://schema.org',
+            '@type': 'WebSite',
+            name,
+            url: baseUrl,
+        });
+        const org = {
+            '@context': 'https://schema.org',
+            '@type': 'Organization',
+            name,
+            url: baseUrl,
+        };
+        if (logo) {
+            org.logo = baseUrl + logo;
+        }
+        entries.push(org);
+    }
+    return entries;
 }
 //# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAKvD;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,KAA2B;IACxD,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAE7C,IAAI,IAAI,CAAC,KAAK;QAAE,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC5C,IAAI,IAAI,CAAC,WAAW;QAAE,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;IAE9D,MAAM,SAAS,GAA4B,EAAE,CAAC;IAC9C,IAAI,IAAI,CAAC,KAAK;QAAE,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC7C,IAAI,IAAI,CAAC,WAAW;QAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;IAC/D,IAAI,IAAI,CAAC,OAAO;QAAE,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,KAAK;QAAE,SAAS,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC;IAC3C,IAAI,IAAI,CAAC,MAAM;QAAE,SAAS,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;IAC9C,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,QAAQ,CAAC,SAAS,GAAG,SAAS,CAAC;IAEtE,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,IAAI,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC3C,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;IAC7D,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,CAAC,IAAI,GAAG,qBAAqB,CAAC;QACrC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;SAAM,CAAC;QACP,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC;IAC1B,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAC;IAEhE,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,KAAgB;IAC3C,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AACrC,CAAC"}
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"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"}

package/dist/tokens.d.ts

@@ -0,0 +1,96 @@
+import { type SecurityPolicy } from '@refrakt-md/types';
+import type { Site } from '@refrakt-md/content';
+/**
+ * Resolve the per-site config from `refrakt.config.json` and compose the
+ * site-level token overrides CSS (SPEC-048 presets + tokens + modes, SPEC-056
+ * scoped tint projections).
+ *
+ * Designed to be called at module-scope in a Next.js `app/layout.tsx` Server
+ * Component, with the result inlined as a `<style dangerouslySetInnerHTML />`
+ * block in `<head>`:
+ *
+ * ```tsx
+ * const siteTokensCss = await getSiteTokensCss();
+ * // ...
+ * <head>
+ *   <style dangerouslySetInnerHTML={{ __html: siteTokensCss }} />
+ * </head>
+ * ```
+ *
+ * Returns an empty string when the site uses the legacy string-theme form or
+ * declares no overrides — safe to inline either way.
+ *
+ * For consumers who prefer a linked stylesheet over an inline `<style>`,
+ * write the result to `public/site-tokens.css` via a build-time script and
+ * reference it with `<link rel="stylesheet" href="/site-tokens.css">`.
+ *
+ * @param configPath Path to `refrakt.config.json`. Default: `./refrakt.config.json`.
+ * @param siteName   Which site to use from a multi-site config. Required when
+ *                   the config declares multiple `sites.*`.
+ */
+export declare function getSiteTokensCss(configPath?: string, siteName?: string): Promise<string>;
+/**
+ * Compute the tree-shaken list of CSS module specifiers the site should
+ * import — `base.css` first, then one entry per used rune block. Designed
+ * for use in a Next.js pre-build script that generates `import` statements
+ * for `app/layout.tsx`, or in `next.config.mjs`'s webpack hook.
+ *
+ * Falls back to the theme package's barrel specifier (`@refrakt-md/lumina`)
+ * when rune-usage analysis fails — same graceful-degradation behaviour as
+ * the SvelteKit + Astro plugins.
+ *
+ * ```ts
+ * // scripts/generate-css-imports.mjs
+ * import { getUsedCssImports } from '@refrakt-md/next';
+ * import { writeFileSync } from 'node:fs';
+ *
+ * const imports = await getUsedCssImports();
+ * const code = imports.map(spec => `import '${spec}';`).join('\n');
+ * writeFileSync('./app/generated-css-imports.ts', code);
+ * ```
+ *
+ * @param configPath Path to `refrakt.config.json`.
+ * @param siteName   Which site to use from a multi-site config.
+ */
+/**
+ * Print the cross-page pipeline's Phase 1/2/3/4 + warnings summary to stderr.
+ *
+ * Call once from `app/[...slug]/page.tsx` or a setup module so Next.js builds
+ * get the same visibility into the content pipeline that the SvelteKit
+ * reference adapter prints.
+ *
+ * Memoise the call site (e.g. via a module-scope flag) — Next will re-evaluate
+ * the page module per static-param entry, and you only want one summary.
+ */
+export declare function printPipelineSummary(site: Site): void;
+export declare function getUsedCssImports(configPath?: string, siteName?: string): Promise<string[]>;
+/**
+ * Convenience factory: build a `createRefraktLoader` instance pre-configured
+ * with the four optional Next.js-side fields (configPath, site, variables,
+ * security). Re-exports the loader for direct use in Server Components.
+ *
+ * ```ts
+ * // app/layout.tsx or a setup module
+ * import { createNextLoader } from '@refrakt-md/next';
+ *
+ * const loader = createNextLoader({
+ *   variables: { version: '1.0.0' },
+ *   security: 'strict',
+ * });
+ *
+ * export async function generateStaticParams() {
+ *   const site = await loader.getSite();
+ *   // ...
+ * }
+ * ```
+ *
+ * For consumers who already wire `createRefraktLoader` directly: use that
+ * import — this helper is purely a typed shorthand for the common case.
+ */
+export declare function createNextLoader(options?: {
+    configPath?: string;
+    site?: string;
+    variables?: Record<string, unknown>;
+    security?: SecurityPolicy;
+}): Promise<import("@refrakt-md/content").RefraktLoader>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAQA,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,gBAAgB,CACrC,UAAU,SAA0B,EACpC,QAAQ,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAKrD;AAED,wBAAsB,iBAAiB,CACtC,UAAU,SAA0B,EACpC,QAAQ,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,EAAE,CAAC,CAyBnB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,GAAE;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,cAAc,CAAC;CACrB,wDAGL"}

package/dist/tokens.js

@@ -0,0 +1,125 @@
+import { dirname, resolve } from 'node:path';
+import { composeSiteTokensCss, loadRefraktConfig, resolveSite, computeUsedCssBlocks, buildUsedCssImports, } from '@refrakt-md/transform/node';
+import { getThemePackage } from '@refrakt-md/types';
+/**
+ * Resolve the per-site config from `refrakt.config.json` and compose the
+ * site-level token overrides CSS (SPEC-048 presets + tokens + modes, SPEC-056
+ * scoped tint projections).
+ *
+ * Designed to be called at module-scope in a Next.js `app/layout.tsx` Server
+ * Component, with the result inlined as a `<style dangerouslySetInnerHTML />`
+ * block in `<head>`:
+ *
+ * ```tsx
+ * const siteTokensCss = await getSiteTokensCss();
+ * // ...
+ * <head>
+ *   <style dangerouslySetInnerHTML={{ __html: siteTokensCss }} />
+ * </head>
+ * ```
+ *
+ * Returns an empty string when the site uses the legacy string-theme form or
+ * declares no overrides — safe to inline either way.
+ *
+ * For consumers who prefer a linked stylesheet over an inline `<style>`,
+ * write the result to `public/site-tokens.css` via a build-time script and
+ * reference it with `<link rel="stylesheet" href="/site-tokens.css">`.
+ *
+ * @param configPath Path to `refrakt.config.json`. Default: `./refrakt.config.json`.
+ * @param siteName   Which site to use from a multi-site config. Required when
+ *                   the config declares multiple `sites.*`.
+ */
+export async function getSiteTokensCss(configPath = './refrakt.config.json', siteName) {
+    const absConfigPath = resolve(configPath);
+    const config = loadRefraktConfig(absConfigPath);
+    const { site } = resolveSite(config, siteName);
+    return composeSiteTokensCss(site, dirname(absConfigPath));
+}
+/**
+ * Compute the tree-shaken list of CSS module specifiers the site should
+ * import — `base.css` first, then one entry per used rune block. Designed
+ * for use in a Next.js pre-build script that generates `import` statements
+ * for `app/layout.tsx`, or in `next.config.mjs`'s webpack hook.
+ *
+ * Falls back to the theme package's barrel specifier (`@refrakt-md/lumina`)
+ * when rune-usage analysis fails — same graceful-degradation behaviour as
+ * the SvelteKit + Astro plugins.
+ *
+ * ```ts
+ * // scripts/generate-css-imports.mjs
+ * import { getUsedCssImports } from '@refrakt-md/next';
+ * import { writeFileSync } from 'node:fs';
+ *
+ * const imports = await getUsedCssImports();
+ * const code = imports.map(spec => `import '${spec}';`).join('\n');
+ * writeFileSync('./app/generated-css-imports.ts', code);
+ * ```
+ *
+ * @param configPath Path to `refrakt.config.json`.
+ * @param siteName   Which site to use from a multi-site config.
+ */
+/**
+ * Print the cross-page pipeline's Phase 1/2/3/4 + warnings summary to stderr.
+ *
+ * Call once from `app/[...slug]/page.tsx` or a setup module so Next.js builds
+ * get the same visibility into the content pipeline that the SvelteKit
+ * reference adapter prints.
+ *
+ * Memoise the call site (e.g. via a module-scope flag) — Next will re-evaluate
+ * the page module per static-param entry, and you only want one summary.
+ */
+export function printPipelineSummary(site) {
+    // Resolved lazily so the import surface stays Server-Component-safe.
+    void import('@refrakt-md/content').then(({ formatPipelineSummary }) => {
+        process.stderr.write(formatPipelineSummary(site.pipelineStats, site.pipelineWarnings));
+    });
+}
+export async function getUsedCssImports(configPath = './refrakt.config.json', siteName) {
+    const absConfigPath = resolve(configPath);
+    const config = loadRefraktConfig(absConfigPath);
+    const { site } = resolveSite(config, siteName);
+    const themePackage = getThemePackage(site.theme);
+    try {
+        const { createRefraktLoader, analyzeRuneUsage } = await import('@refrakt-md/content');
+        const themeModule = await import(themePackage + '/transform');
+        const themeConfig = themeModule.themeConfig ?? themeModule.luminaConfig ?? themeModule.default;
+        const loader = createRefraktLoader({ configPath: absConfigPath, site: siteName });
+        const loadedSite = await loader.getSite();
+        const report = analyzeRuneUsage(loadedSite.pages);
+        const { usedBlocks } = await computeUsedCssBlocks(report.allTypes, themeConfig, themePackage);
+        return buildUsedCssImports(themePackage, usedBlocks);
+    }
+    catch {
+        // Fall back to the theme package barrel — pulls in every rune's CSS,
+        // matching the pre-tree-shake behaviour.
+        return [themePackage];
+    }
+}
+/**
+ * Convenience factory: build a `createRefraktLoader` instance pre-configured
+ * with the four optional Next.js-side fields (configPath, site, variables,
+ * security). Re-exports the loader for direct use in Server Components.
+ *
+ * ```ts
+ * // app/layout.tsx or a setup module
+ * import { createNextLoader } from '@refrakt-md/next';
+ *
+ * const loader = createNextLoader({
+ *   variables: { version: '1.0.0' },
+ *   security: 'strict',
+ * });
+ *
+ * export async function generateStaticParams() {
+ *   const site = await loader.getSite();
+ *   // ...
+ * }
+ * ```
+ *
+ * For consumers who already wire `createRefraktLoader` directly: use that
+ * import — this helper is purely a typed shorthand for the common case.
+ */
+export async function createNextLoader(options = {}) {
+    const { createRefraktLoader } = await import('@refrakt-md/content');
+    return createRefraktLoader(options);
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EACN,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,oBAAoB,EACpB,mBAAmB,GACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,eAAe,EAAuB,MAAM,mBAAmB,CAAC;AAGzE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,UAAU,GAAG,uBAAuB,EACpC,QAAiB;IAEjB,MAAM,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAChD,MAAM,EAAE,IAAI,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,OAAO,oBAAoB,CAAC,IAAI,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAU;IAC9C,qEAAqE;IACrE,KAAK,MAAM,CAAC,qBAAqB,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,qBAAqB,EAAE,EAAE,EAAE;QACrE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACxF,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,UAAU,GAAG,uBAAuB,EACpC,QAAiB;IAEjB,MAAM,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAChD,MAAM,EAAE,IAAI,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEjD,IAAI,CAAC;QACJ,MAAM,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;QACtF,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,YAAY,GAAG,YAAY,CAAC,CAAC;QAC9D,MAAM,WAAW,GAChB,WAAW,CAAC,WAAW,IAAI,WAAW,CAAC,YAAY,IAAI,WAAW,CAAC,OAAO,CAAC;QAC5E,MAAM,MAAM,GAAG,mBAAmB,CAAC,EAAE,UAAU,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAClF,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,gBAAgB,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAClD,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,oBAAoB,CAChD,MAAM,CAAC,QAAQ,EACf,WAAW,EACX,YAAY,CACZ,CAAC;QACF,OAAO,mBAAmB,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACR,qEAAqE;QACrE,yCAAyC;QACzC,OAAO,CAAC,YAAY,CAAC,CAAC;IACvB,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,UAKnC,EAAE;IACL,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;IACpE,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@refrakt-md/next",
   "description": "Next.js adapter for refrakt.md — render Markdoc runes with React Server Components",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -33,10 +33,10 @@
     "build": "tsc"
   },
   "dependencies": {
-    "@refrakt-md/behaviors": "0.14.2",
-    "@refrakt-md/content": "0.14.2",
-    "@refrakt-md/transform": "0.14.2",
-    "@refrakt-md/types": "0.14.2"
+    "@refrakt-md/behaviors": "0.14.4",
+    "@refrakt-md/content": "0.14.4",
+    "@refrakt-md/transform": "0.14.4",
+    "@refrakt-md/types": "0.14.4"
   },
   "devDependencies": {
     "next": "^15.0.0",