@tenphi/docs 0.16.0 → 0.17.1

package/README.md

@@ -27,4 +27,4 @@ extraction root.
 
 Most applications should install `@tenphi/cookbook`, which combines this engine
 with the supported Astro/Starlight renderer. This package is useful for custom
-tooling, validation, and alternate renderers. Node.js 22.14 or newer is required.
+tooling, validation, and alternate renderers. Node.js 22.19 or newer is required.

package/dist/config/index.d.ts

@@ -1,4 +1,4 @@
-import { A as MarkdownConfig, B as SiteConfig, D as HeadConfig, E as EditLinkConfig, F as NormalizedDocsConfig, G as ThemeTokens, H as ThemeConfig, K as TypographyPreset, M as NavigationItem, N as NavigationPlacement, O as HeaderLink, P as NavigationTab, T as DocsSource, U as ThemePaletteConfig, V as SiteIconConfig, W as ThemeTokenValue, _ as DocsConfig, a as ComponentStyleConfig, c as ComponentsConfig, i as COOKBOOK_COMPONENT_SUB_ELEMENTS, j as NavigationConfig, k as LocaleConfig, l as ContentConfig, n as BuildConfig, o as ComponentStyles, q as TypographyPresets, r as COOKBOOK_COMPONENT_NAMES, s as ComponentStylesConfig, t as BrandConfig, u as CookbookComponentName, v as DocsDiagnostic, z as SearchConfig } from "../types-CH6E2v-J.js";
+import { $ as TypographyPresets, A as LocaleConfig, B as SearchConfig, D as EditLinkConfig, E as DocsSource, F as NavigationTab, G as ThemeFont, H as SiteIconConfig, I as NormalizedDocsConfig, J as ThemePaletteColor, K as ThemeFontFile, M as NavigationConfig, N as NavigationItem, O as HeadConfig, P as NavigationPlacement, Q as TypographyPreset, V as SiteConfig, W as ThemeConfig, X as ThemeTokenValue, Y as ThemePaletteConfig, Z as ThemeTokens, a as COOKBOOK_COMPONENT_SUB_ELEMENTS, c as ComponentStylesConfig, d as CookbookComponentName, i as COOKBOOK_COMPONENT_NAMES, j as MarkdownConfig, k as HeaderLink, l as ComponentsConfig, n as BrandDeclaration, o as ComponentStyleConfig, q as ThemeFonts, r as BuildConfig, s as ComponentStyles, t as BrandConfig, u as ContentConfig, v as DocsConfig, y as DocsDiagnostic } from "../types-CY8WfBmM.js";
 //#region src/config/index.d.ts
 declare class DocsConfigError extends Error {
   readonly diagnostics: DocsDiagnostic[];
@@ -7,8 +7,8 @@ declare class DocsConfigError extends Error {
 declare function validateConfig(config: DocsConfig): DocsDiagnostic[];
 declare function normalizeDocsConfig(config?: DocsConfig): NormalizedDocsConfig;
 declare function defineDocsConfig(config: DocsConfig): DocsConfig;
-/** Compose presets. Objects merge, arrays replace, and styles use Tasty semantics. */
+/** Compose presets. Color roles and fonts replace, other objects merge, and styles use Tasty semantics. */
 declare function mergeDocsConfig(...configs: DocsConfig[]): DocsConfig;
 //#endregion
-export { type BrandConfig, type BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, type ComponentStyleConfig, type ComponentStyles, type ComponentStylesConfig, type ComponentsConfig, type ContentConfig, type CookbookComponentName, type DocsConfig, DocsConfigError, type DocsSource, type EditLinkConfig, type HeadConfig, type HeaderLink, type LocaleConfig, type MarkdownConfig, type NavigationConfig, type NavigationItem, type NavigationPlacement, type NavigationTab, type NormalizedDocsConfig, type SearchConfig, type SiteConfig, type SiteIconConfig, type ThemeConfig, type ThemePaletteConfig, type ThemeTokenValue, type ThemeTokens, type TypographyPreset, type TypographyPresets, defineDocsConfig, mergeDocsConfig, normalizeDocsConfig, validateConfig };
+export { type BrandConfig, type BrandDeclaration, type BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, type ComponentStyleConfig, type ComponentStyles, type ComponentStylesConfig, type ComponentsConfig, type ContentConfig, type CookbookComponentName, type DocsConfig, DocsConfigError, type DocsSource, type EditLinkConfig, type HeadConfig, type HeaderLink, type LocaleConfig, type MarkdownConfig, type NavigationConfig, type NavigationItem, type NavigationPlacement, type NavigationTab, type NormalizedDocsConfig, type SearchConfig, type SiteConfig, type SiteIconConfig, type ThemeConfig, type ThemeFont, type ThemeFontFile, type ThemeFonts, type ThemePaletteColor, type ThemePaletteConfig, type ThemeTokenValue, type ThemeTokens, type TypographyPreset, type TypographyPresets, defineDocsConfig, mergeDocsConfig, normalizeDocsConfig, validateConfig };
 //# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/config/index.ts"],"mappings":";;cA0Ea,wBAAwB;WAC1B,aAAa;EAEtB,YAAY,aAAa;;iBAOX,eAAe,QAAQ,aAAa;iBAmqBpC,oBACd,SAAQ,aACP;iBA4Ca,iBAAiB,QAAQ,aAAa;;iBAOtC,mBAAmB,SAAS,eAAe"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/config/index.ts"],"mappings":";;cA8Fa,wBAAwB;WAC1B,aAAa;EAEtB,YAAY,aAAa;;iBAOX,eAAe,QAAQ,aAAa;iBA63BpC,oBACd,SAAQ,aACP;iBA4Ca,iBAAiB,QAAQ,aAAa;;iBAOtC,mBAAmB,SAAS,eAAe"}

package/dist/config/index.js

@@ -1,2 +1,2 @@
-import { a as validateConfig, i as normalizeDocsConfig, n as defineDocsConfig, o as COOKBOOK_COMPONENT_NAMES, r as mergeDocsConfig, s as COOKBOOK_COMPONENT_SUB_ELEMENTS, t as DocsConfigError } from "../config-CmoSqvii.js";
+import { a as validateConfig, i as normalizeDocsConfig, n as defineDocsConfig, o as COOKBOOK_COMPONENT_NAMES, r as mergeDocsConfig, s as COOKBOOK_COMPONENT_SUB_ELEMENTS, t as DocsConfigError } from "../config-CW0iIYp8.js";
 export { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, DocsConfigError, defineDocsConfig, mergeDocsConfig, normalizeDocsConfig, validateConfig };

package/dist/config/schema.json

@@ -15,6 +15,19 @@
         "version": {
           "type": "string"
         },
+        "versions": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["label", "routeBase"],
+            "properties": {
+              "label": { "type": "string", "minLength": 1 },
+              "routeBase": { "type": "string", "pattern": "^/(?!/)" }
+            }
+          }
+        },
         "description": {
           "type": "string"
         },
@@ -179,20 +192,30 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "brand": {},
+        "brand": { "$ref": "#/$defs/brandColor" },
         "palette": {
           "type": "object",
           "additionalProperties": false,
           "properties": {
-            "surface": {},
-            "text": {},
-            "textSoft": {},
-            "info": {},
-            "success": {},
-            "warning": {},
-            "danger": {},
-            "header": {},
-            "overlay": {}
+            "surface": { "$ref": "#/$defs/paletteColor" },
+            "text": { "$ref": "#/$defs/paletteColor" },
+            "heading": { "$ref": "#/$defs/paletteColor" },
+            "textSoft": { "$ref": "#/$defs/paletteColor" },
+            "info": { "$ref": "#/$defs/paletteColor" },
+            "success": { "$ref": "#/$defs/paletteColor" },
+            "warning": { "$ref": "#/$defs/paletteColor" },
+            "danger": { "$ref": "#/$defs/paletteColor" },
+            "header": { "$ref": "#/$defs/paletteColor" },
+            "overlay": { "$ref": "#/$defs/paletteColor" }
+          }
+        },
+        "fonts": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "body": { "$ref": "#/$defs/themeFont" },
+            "heading": { "$ref": "#/$defs/themeFont" },
+            "code": { "$ref": "#/$defs/themeFont" }
           }
         },
         "states": {
@@ -268,6 +291,14 @@
                 }
               }
             },
+            "Heading": {
+              "type": "object",
+              "propertyNames": {
+                "not": {
+                  "const": "mode"
+                }
+              }
+            },
             "LanguageSelect": {
               "type": "object",
               "propertyNames": {
@@ -356,6 +387,14 @@
                 }
               }
             },
+            "VersionSwitcher": {
+              "type": "object",
+              "propertyNames": {
+                "not": {
+                  "const": "mode"
+                }
+              }
+            },
             "Preview": {
               "type": "object",
               "propertyNames": {
@@ -609,6 +648,207 @@
     }
   },
   "$defs": {
+    "brandColor": {
+      "description": "A Glaze from declaration for the brand seed, optionally with APCA targets. Literal shorthand and structured hue, saturation, and tone are also supported.",
+      "oneOf": [
+        { "$ref": "#/$defs/glazeColorValue" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["from"],
+          "properties": {
+            "from": { "$ref": "#/$defs/glazeColorValue" },
+            "contrast": { "$ref": "#/$defs/brandContrast" },
+            "unsafeContrast": { "type": "boolean" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["hue", "saturation", "tone"],
+          "properties": {
+            "hue": { "type": "number", "minimum": 0, "maximum": 360 },
+            "saturation": { "type": "number", "minimum": 0, "maximum": 100 },
+            "tone": { "type": "number", "minimum": 0, "maximum": 100 },
+            "contrast": { "$ref": "#/$defs/brandContrast" },
+            "unsafeContrast": { "type": "boolean" }
+          }
+        }
+      ]
+    },
+    "brandContrast": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["apca"],
+      "properties": {
+        "apca": {
+          "oneOf": [
+            { "type": "number" },
+            {
+              "type": "array",
+              "prefixItems": [{ "type": "number" }, { "type": "number" }],
+              "minItems": 2,
+              "maxItems": 2
+            }
+          ]
+        }
+      }
+    },
+    "paletteColor": {
+      "description": "A Glaze color declaration; literal colors are convenient seed shorthands.",
+      "oneOf": [
+        { "$ref": "#/$defs/glazeColorValue" },
+        { "$ref": "#/$defs/glazeDeclaration" }
+      ]
+    },
+    "glazeColorValue": {
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["h", "s", "l"],
+          "properties": {
+            "h": { "type": "number" },
+            "s": { "type": "number" },
+            "l": { "type": "number" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["h", "s", "t"],
+          "properties": {
+            "h": { "type": "number" },
+            "s": { "type": "number" },
+            "t": { "type": "number" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["r", "g", "b"],
+          "properties": {
+            "r": { "type": "number" },
+            "g": { "type": "number" },
+            "b": { "type": "number" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["l", "c", "h"],
+          "properties": {
+            "l": { "type": "number" },
+            "c": { "type": "number" },
+            "h": { "type": "number" }
+          }
+        }
+      ]
+    },
+    "glazeDeclaration": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "from": { "$ref": "#/$defs/glazeColorValue" },
+        "tone": {
+          "oneOf": [
+            { "type": "number", "minimum": 0, "maximum": 100 },
+            { "type": "string" },
+            {
+              "type": "array",
+              "prefixItems": [
+                { "oneOf": [{ "type": "number" }, { "type": "string" }] },
+                { "oneOf": [{ "type": "number" }, { "type": "string" }] }
+              ],
+              "minItems": 2,
+              "maxItems": 2
+            }
+          ]
+        },
+        "saturation": { "type": "number", "minimum": 0, "maximum": 1 },
+        "hue": { "oneOf": [{ "type": "number" }, { "type": "string" }] },
+        "darkHue": { "oneOf": [{ "type": "number" }, { "type": "string" }] },
+        "darkSaturation": { "type": "number", "minimum": 0, "maximum": 1 },
+        "base": { "type": "string" },
+        "contrast": {
+          "oneOf": [
+            { "type": "number" },
+            { "type": "string" },
+            {
+              "type": "array",
+              "minItems": 2,
+              "maxItems": 2
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "apca": {},
+                "wcag": {}
+              }
+            }
+          ]
+        },
+        "mode": { "enum": ["auto", "fixed", "static"] },
+        "autoFlip": { "type": "boolean" },
+        "opacity": { "type": "number", "minimum": 0, "maximum": 1 },
+        "pastel": { "type": "boolean" },
+        "role": { "type": "string" },
+        "inherit": { "type": "boolean" }
+      }
+    },
+    "themeFont": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["google"],
+          "properties": {
+            "google": { "type": "string", "minLength": 1 },
+            "weights": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "integer", "minimum": 1, "maximum": 1000 }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["family", "files"],
+          "properties": {
+            "family": { "type": "string", "minLength": 1 },
+            "files": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["src"],
+                "properties": {
+                  "src": {
+                    "type": "string",
+                    "pattern": "^/(?!/).+\\.(woff2?|ttf|otf)$"
+                  },
+                  "weight": {
+                    "oneOf": [
+                      { "type": "integer", "minimum": 1, "maximum": 1000 },
+                      {
+                        "type": "string",
+                        "pattern": "^(?:[1-9][0-9]{0,2}|1000) (?:[1-9][0-9]{0,2}|1000)$"
+                      }
+                    ]
+                  },
+                  "style": { "enum": ["normal", "italic"] }
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
     "locale": {
       "type": "object",
       "additionalProperties": false,
@@ -872,6 +1112,17 @@
               "format": "uri"
             }
           }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["openapi"],
+          "properties": {
+            "openapi": { "type": "string", "minLength": 1 },
+            "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" },
+            "root": { "type": "string" },
+            "routeBase": { "type": "string" }
+          }
         }
       ]
     },

package/dist/{config-CmoSqvii.js → config-CW0iIYp8.js}

@@ -12,6 +12,7 @@ const COOKBOOK_COMPONENT_NAMES = [
 	"PageFrame",
 	"HeaderFrame",
 	"HeaderLinks",
+	"Heading",
 	"Layout",
 	"SearchButton",
 	"TableOfContentsLayout",
@@ -27,6 +28,7 @@ const COOKBOOK_COMPONENT_NAMES = [
 	"MobileNavigationTabs",
 	"MobileTableOfContents",
 	"PackageVersion",
+	"VersionSwitcher",
 	"Preview",
 	"Sidebar",
 	"SocialIcons",
@@ -45,6 +47,15 @@ const COOKBOOK_COMPONENT_SUB_ELEMENTS = {
 		"Columns"
 	],
 	HeaderFrame: [],
+	Heading: [
+		"Level1",
+		"Level2",
+		"Level3",
+		"Level4",
+		"Level5",
+		"Level6",
+		"PageTitle"
+	],
 	HeaderLinks: [
 		"Desktop",
 		"Link",
@@ -190,6 +201,13 @@ const COOKBOOK_COMPONENT_SUB_ELEMENTS = {
 		"CurrentIndicator"
 	],
 	PackageVersion: [],
+	VersionSwitcher: [
+		"Trigger",
+		"Panel",
+		"OpenPanel",
+		"Link",
+		"CurrentLink"
+	],
 	Preview: [
 		"Caption",
 		"Stage",
@@ -306,6 +324,22 @@ const HEAD_KEYS = /* @__PURE__ */ new Set([
 	"content"
 ]);
 const SITE_ICON_KEYS = /* @__PURE__ */ new Set(["source", "background"]);
+const COLOR_DECLARATION_KEYS = /* @__PURE__ */ new Set([
+	"from",
+	"tone",
+	"saturation",
+	"hue",
+	"darkHue",
+	"darkSaturation",
+	"base",
+	"contrast",
+	"mode",
+	"autoFlip",
+	"opacity",
+	"pastel",
+	"role",
+	"inherit"
+]);
 const ROOT_KEYS = /* @__PURE__ */ new Set([
 	"root",
 	"redirects",
@@ -327,6 +361,7 @@ const OBJECT_KEYS = {
 	site: /* @__PURE__ */ new Set([
 		"title",
 		"version",
+		"versions",
 		"description",
 		"url",
 		"repository",
@@ -345,6 +380,7 @@ const OBJECT_KEYS = {
 	theme: /* @__PURE__ */ new Set([
 		"brand",
 		"palette",
+		"fonts",
 		"states",
 		"tokens",
 		"presets",
@@ -388,6 +424,25 @@ function validateConfig(config) {
 		}
 		for (const key of Object.keys(value)) if (!keys.has(key)) unknown(diagnostics, `${section}.${key}`);
 	}
+	if (isRecord(config.site) && config.site.versions !== void 0) {
+		if (!Array.isArray(config.site.versions) || config.site.versions.length < 2) invalid(diagnostics, "site.versions must contain at least two versions.");
+		else {
+			const bases = /* @__PURE__ */ new Set();
+			for (const [index, version] of config.site.versions.entries()) {
+				const path = `site.versions[${index}]`;
+				if (!isRecord(version)) {
+					invalid(diagnostics, `${path} must be an object.`);
+					continue;
+				}
+				for (const key of Object.keys(version)) if (key !== "label" && key !== "routeBase") unknown(diagnostics, `${path}.${key}`);
+				if (typeof version.label !== "string" || !version.label.trim()) invalid(diagnostics, `${path}.label must be a non-empty string.`);
+				const base = version.routeBase;
+				if (typeof base !== "string" || !base.startsWith("/") || base !== "/" && base.endsWith("/") || base.includes("//") || /[?#\\\s]/.test(base) || base.split("/").some((segment) => segment === "." || segment === "..")) invalid(diagnostics, `${path}.routeBase must be a root-relative route without a trailing slash.`);
+				else if (bases.has(base)) invalid(diagnostics, `${path}.routeBase duplicates ${base}.`);
+				else bases.add(base);
+			}
+		}
+	}
 	if (isRecord(config.site) && config.site.headerLinks !== void 0) {
 		if (!Array.isArray(config.site.headerLinks)) invalid(diagnostics, "site.headerLinks must be an array.");
 		else config.site.headerLinks.forEach((item, index) => {
@@ -495,13 +550,14 @@ function validateConfig(config) {
 		const variants = [
 			"file",
 			"glob",
-			"package"
+			"package",
+			"openapi"
 		].filter((key) => key in source);
 		if (variants.length !== 1) {
 			diagnostics.push({
 				code: "DOCS_CONFIG_INVALID",
 				severity: "error",
-				message: `content.sources[${index}] must select exactly one of file, glob, or package.`
+				message: `content.sources[${index}] must select exactly one of file, glob, package, or openapi.`
 			});
 			continue;
 		}
@@ -535,6 +591,12 @@ function validateConfig(config) {
 				"index",
 				"routeBase",
 				"trust"
+			]),
+			openapi: /* @__PURE__ */ new Set([
+				"id",
+				"root",
+				"routeBase",
+				"openapi"
 			])
 		}[variant];
 		for (const key of Object.keys(source)) if (!allowed.has(key)) unknown(diagnostics, `content.sources[${index}].${key}`);
@@ -597,10 +659,58 @@ function validateConfig(config) {
 		"styles",
 		"customStyles",
 		"palette",
+		"fonts",
 		"tokens",
 		"states",
 		"presets"
 	]) if (config.theme?.[field] !== void 0 && !isRecord(config.theme[field])) invalid(diagnostics, `theme.${field} must be an object.`);
+	if (isRecord(config.theme?.fonts)) for (const [role, font] of Object.entries(config.theme.fonts)) {
+		const path = `theme.fonts.${role}`;
+		if (![
+			"body",
+			"heading",
+			"code"
+		].includes(role)) {
+			unknown(diagnostics, path);
+			continue;
+		}
+		if (font === void 0) continue;
+		if (typeof font === "string") {
+			if (!validFontFamily(font)) invalid(diagnostics, `${path} must name a Google Fonts family.`);
+			continue;
+		}
+		if (!isRecord(font)) {
+			invalid(diagnostics, `${path} must be a Google Fonts name or font definition.`);
+			continue;
+		}
+		if ("google" in font) {
+			for (const key of Object.keys(font)) if (!["google", "weights"].includes(key)) unknown(diagnostics, `${path}.${key}`);
+			if (!validFontFamily(font.google)) invalid(diagnostics, `${path}.google must name a Google Fonts family.`);
+			if (font.weights !== void 0 && (!Array.isArray(font.weights) || font.weights.length === 0 || font.weights.some((weight) => !Number.isInteger(weight) || weight < 1 || weight > 1e3))) invalid(diagnostics, `${path}.weights must be a non-empty array of font weights from 1 to 1000.`);
+		} else {
+			for (const key of Object.keys(font)) if (!["family", "files"].includes(key)) unknown(diagnostics, `${path}.${key}`);
+			if (!validFontFamily(font.family)) invalid(diagnostics, `${path}.family must be a font family name.`);
+			if (!Array.isArray(font.files) || font.files.length === 0) {
+				invalid(diagnostics, `${path}.files must contain at least one font file.`);
+				continue;
+			}
+			font.files.forEach((file, index) => {
+				const filePath = `${path}.files[${index}]`;
+				if (!isRecord(file)) {
+					invalid(diagnostics, `${filePath} must be an object.`);
+					return;
+				}
+				for (const key of Object.keys(file)) if (![
+					"src",
+					"weight",
+					"style"
+				].includes(key)) unknown(diagnostics, `${filePath}.${key}`);
+				if (typeof file.src !== "string" || !/^\/(?!\/)[^\s"'()\\?#]+\.(?:woff2?|ttf|otf)$/.test(file.src) || file.src.split("/").some((segment) => segment === "." || segment === "..")) invalid(diagnostics, `${filePath}.src must be a root-relative .woff2, .woff, .ttf, or .otf public path.`);
+				if (file.weight !== void 0 && !(typeof file.weight === "number" && Number.isInteger(file.weight) && file.weight >= 1 && file.weight <= 1e3) && !(typeof file.weight === "string" && /^(?:[1-9]\d{0,2}|1000) (?:[1-9]\d{0,2}|1000)$/.test(file.weight) && Number(file.weight.split(" ")[0]) < Number(file.weight.split(" ")[1]))) invalid(diagnostics, `${filePath}.weight must be a weight from 1 to 1000 or an ascending range.`);
+				if (file.style !== void 0 && !["normal", "italic"].includes(file.style)) invalid(diagnostics, `${filePath}.style must be normal or italic.`);
+			});
+		}
+	}
 	for (const [name, entry] of Object.entries(config.theme?.styles ?? {})) {
 		if (!COOKBOOK_COMPONENT_NAMES.includes(name)) {
 			unknown(diagnostics, `theme.styles.${name}; register custom components under theme.customStyles`);
@@ -623,20 +733,22 @@ function validateConfig(config) {
 			"header",
 			"overlay",
 			"text",
+			"heading",
 			"textSoft",
 			"info",
 			"success",
 			"warning",
 			"danger"
 		].includes(name)) unknown(diagnostics, `theme.palette.${name}`);
-		try {
-			glaze.color({ from: value }).resolve();
-		} catch (error) {
-			invalid(diagnostics, `theme.palette.${name}: ${error instanceof Error ? error.message : String(error)}`);
-		}
+		validatePaletteColor(name, value, diagnostics);
 	}
 	if (brand !== void 0) try {
-		glaze.color({ from: typeof brand === "object" && brand !== null && "from" in brand ? brand.from : brand }).resolve();
+		if (isBrandDeclaration(brand)) glaze.color({
+			hue: brand.hue,
+			saturation: brand.saturation,
+			tone: brand.tone
+		}).resolve();
+		else glaze.color({ from: typeof brand === "object" && brand !== null && "from" in brand ? brand.from : brand }).resolve();
 	} catch (error) {
 		invalid(diagnostics, `theme.brand: ${error instanceof Error ? error.message : String(error)}`);
 	}
@@ -651,6 +763,50 @@ function validateConfig(config) {
 	}
 	return diagnostics;
 }
+function validatePaletteColor(name, value, diagnostics) {
+	try {
+		if (!isPaletteDeclaration(value)) {
+			glaze.color({ from: value }).resolve();
+			return;
+		}
+		for (const key of Object.keys(value)) if (!COLOR_DECLARATION_KEYS.has(key)) unknown(diagnostics, `theme.palette.${name}.${key}`);
+		const colorName = name === "textSoft" ? "text-soft" : name;
+		const theme = glaze(266, 68);
+		theme.colors({
+			surface: { tone: 98 },
+			"surface-2": {
+				base: "surface",
+				tone: "-2"
+			},
+			"accent-surface": { tone: 48 },
+			text: {
+				base: "surface",
+				contrast: { apca: 75 }
+			},
+			heading: {
+				base: "surface",
+				tone: 4
+			},
+			"text-soft": {
+				base: "surface",
+				contrast: { apca: 60 }
+			},
+			[colorName]: {
+				tone: colorName === "surface" ? 98 : 50,
+				...value
+			}
+		});
+		theme.resolve();
+	} catch (error) {
+		invalid(diagnostics, `theme.palette.${name}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function isPaletteDeclaration(value) {
+	return typeof value === "object" && value !== null && !("h" in value || "r" in value || "c" in value);
+}
+function isBrandDeclaration(value) {
+	return isRecord(value) && "hue" in value && "saturation" in value && "tone" in value;
+}
 function unknown(diagnostics, path) {
 	diagnostics.push({
 		code: "DOCS_CONFIG_UNKNOWN_KEY",
@@ -668,6 +824,9 @@ function invalid(diagnostics, message) {
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function validFontFamily(value) {
+	return typeof value === "string" && value.length <= 100 && /^[\p{L}\p{N} ._-]+$/u.test(value) && value.trim() === value && value.length > 0;
+}
 function isHttpUrl(value) {
 	try {
 		return ["http:", "https:"].includes(new URL(value).protocol);
@@ -745,7 +904,7 @@ function defineDocsConfig(config) {
 	if (diagnostics.length > 0) throw new DocsConfigError(diagnostics);
 	return config;
 }
-/** Compose presets. Objects merge, arrays replace, and styles use Tasty semantics. */
+/** Compose presets. Color roles and fonts replace, other objects merge, and styles use Tasty semantics. */
 function mergeDocsConfig(...configs) {
 	const merge = (base, next) => {
 		const result = { ...base };
@@ -759,6 +918,15 @@ function mergeDocsConfig(...configs) {
 		const diagnostics = validateConfig(next);
 		if (diagnostics.length) throw new DocsConfigError(diagnostics);
 		const result = merge(base, next);
+		if (next.theme?.brand !== void 0) result.theme.brand = next.theme.brand;
+		if (next.theme?.palette) result.theme.palette = {
+			...base.theme?.palette,
+			...Object.fromEntries(Object.entries(next.theme.palette).filter(([, color]) => color !== void 0))
+		};
+		if (next.theme?.fonts) result.theme.fonts = {
+			...base.theme?.fonts,
+			...Object.fromEntries(Object.entries(next.theme.fonts).filter(([, font]) => font !== void 0))
+		};
 		for (const field of ["styles", "customStyles"]) {
 			if (!next.theme?.[field]) continue;
 			const styles = { ...base.theme?.[field] };
@@ -771,4 +939,4 @@ function mergeDocsConfig(...configs) {
 //#endregion
 export { validateConfig as a, normalizeDocsConfig as i, defineDocsConfig as n, COOKBOOK_COMPONENT_NAMES as o, mergeDocsConfig as r, COOKBOOK_COMPONENT_SUB_ELEMENTS as s, DocsConfigError as t };
 
-//# sourceMappingURL=config-CmoSqvii.js.map
+//# sourceMappingURL=config-CW0iIYp8.js.map