@loworbitstudio/visor-theme-engine 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,799 @@
+import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, R as ResolvedThemeConfig, c as GeneratedPrimitives, d as ThemeOutput, e as ThemeData, f as VisorThemeConfig, g as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, h as RGB, P as ParsedColor, O as OKLCH, i as SemanticTokens, j as ShadeStep } from './types-r7ae3WP2.js';
+export { k as ColorFormat, l as FontSource, m as RGBA, n as SemanticTokenValue } from './types-r7ae3WP2.js';
+
+/**
+ * Font resolver — maps font family names to loadable font resources.
+ *
+ * For Google Fonts: constructs the CSS URL deterministically.
+ * For custom/commercial fonts: flags them with setup guidance.
+ */
+
+/**
+ * Build a Visor Fonts CDN URL for a specific font file.
+ *
+ * URL pattern: https://fonts.visor.design/{org}/{family-slug}/{filename}.woff2
+ * Family slug: lowercase family name, spaces to hyphens.
+ * Filename: original uploaded name (e.g., PPModelPlastic-Regular).
+ */
+declare const VISOR_FONTS_CDN = "https://fonts.visor.design";
+declare function buildVisorFontUrl(org: string, family: string, weight: number): string;
+/**
+ * Resolve a font family name to a FontResolution.
+ *
+ * Resolution order:
+ *   1. If source is explicitly "visor-fonts", build CDN URLs (requires org)
+ *   2. If source is explicitly "local", return local guidance
+ *   3. Otherwise, look up in Google Fonts catalog
+ *   4. If not found in catalog, fall back to local
+ */
+declare function resolveFont(family: string, options?: FontResolveOptions): FontResolution;
+
+/**
+ * Preload hint generation for font loading performance.
+ *
+ * Generates <link> tags for preconnecting to Google Fonts
+ * and preloading critical font files.
+ */
+
+/**
+ * Generate preconnect and preload link tags for resolved fonts.
+ *
+ * For Google Fonts:
+ *   - <link rel="preconnect"> to fonts.googleapis.com
+ *   - <link rel="preconnect" crossorigin> to fonts.gstatic.com
+ *   - <link rel="preload" as="style"> for the CSS URL
+ *
+ * For custom fonts with provided file paths:
+ *   - <link rel="preload" as="font" type="font/woff2" crossorigin> per file
+ */
+declare function generatePreloadLinks(resolutions: FontResolution[], customFontPaths?: Map<string, string[]>): string[];
+/**
+ * Generate the stylesheet link tags for Google Fonts (non-preload).
+ * These are the actual <link rel="stylesheet"> tags that load the fonts.
+ */
+declare function generateStylesheetLinks(resolutions: FontResolution[]): string[];
+
+/**
+ * Theme font pipeline — connects font resolution to the .visor.yaml import flow.
+ *
+ * Takes the typography section from a .visor.yaml file and produces:
+ *   - Resolved font resources (Google Fonts URLs or custom flags)
+ *   - Preload/preconnect link tags
+ *   - CSS output (@font-face stubs, custom property overrides)
+ *   - Warnings for fonts needing manual setup
+ */
+
+/**
+ * Resolve all fonts for a theme's typography configuration.
+ *
+ * This is the main entry point for the font pipeline — called during
+ * .visor.yaml import to process the typography section.
+ */
+declare function resolveThemeFonts(typography: VisorTypography, options?: {
+    display?: FontDisplayStrategy;
+}): ThemeFontResult;
+
+/**
+ * Google Fonts Catalog
+ *
+ * Curated set of popular Google Fonts families.
+ * Run `npm run update-catalog` to regenerate from the full API.
+ *
+ * Source: Google Fonts API (sorted by popularity)
+ */
+
+declare const googleFontsCatalog: GoogleFontEntry[];
+/** Look up a font family in the Google Fonts catalog (case-insensitive) */
+declare function lookupGoogleFont(family: string): GoogleFontEntry | undefined;
+
+/**
+ * Import Pipeline
+ *
+ * Main public API that orchestrates all 4 stages:
+ *   1. Shade Generation (Primitives)
+ *   2. Semantic Assignment
+ *   3. Adaptive Assembly (CSS)
+ *   4. Override Application
+ */
+
+/**
+ * Generate all shade scales from a resolved config.
+ * If neutral is null, uses Tailwind Gray verbatim.
+ */
+declare function generatePrimitives(config: ResolvedThemeConfig): GeneratedPrimitives;
+/**
+ * Parse a YAML string into a VisorThemeConfig.
+ * Validates the structure before returning.
+ */
+declare function parseConfig(yamlString: string): VisorThemeConfig;
+/**
+ * Generate a complete theme from a .visor.yaml string.
+ * Parses YAML, validates, and runs all 4 pipeline stages.
+ */
+declare function generateTheme(yamlString: string): ThemeOutput;
+/**
+ * Generate a complete theme from a pre-parsed config object.
+ * Skips YAML parsing — for browser consumers or programmatic use.
+ */
+declare function generateThemeFromConfig(config: VisorThemeConfig): ThemeOutput;
+/**
+ * Generate theme data including intermediate artifacts from a .visor.yaml string.
+ * Returns config, primitives, tokens, and CSS output — used by adapters.
+ */
+declare function generateThemeData(yamlString: string): ThemeData;
+/**
+ * Generate theme data including intermediate artifacts from a pre-parsed config.
+ * Returns config, primitives, tokens, and CSS output — used by adapters.
+ */
+declare function generateThemeDataFromConfig(config: VisorThemeConfig): ThemeData;
+
+/**
+ * Export Pipeline
+ *
+ * Reverses the import pipeline: given theme data, produces a minimal .visor.yaml string.
+ * Only includes values that differ from defaults.
+ */
+
+/**
+ * Export a theme to a minimal .visor.yaml string.
+ * Omits values that match defaults to keep output minimal.
+ */
+declare function exportTheme(primitives: GeneratedPrimitives, config: ResolvedThemeConfig): string;
+
+var $schema = "https://json-schema.org/draft/2020-12/schema";
+var $id = "https://visor.loworbit.studio/schemas/visor-theme.schema.json";
+var title = "Visor Theme";
+var description = "Schema for .visor.yaml theme files — portable visual identity definitions for the Visor design system.";
+var type = "object";
+var required = [
+	"name",
+	"version",
+	"colors"
+];
+var additionalProperties = false;
+var properties = {
+	name: {
+		type: "string",
+		minLength: 1,
+		description: "Human-readable theme name."
+	},
+	version: {
+		"const": 1,
+		description: "Schema version. Currently always 1."
+	},
+	group: {
+		type: "string",
+		description: "Theme group for the docs site theme switcher (e.g. 'Visor', 'Client', 'Low Orbit'). Used by `visor theme sync`. Defaults to folder-based grouping when omitted."
+	},
+	colors: {
+		type: "object",
+		description: "Color definitions for light mode. Only primary is required — all others have sensible defaults.",
+		required: [
+			"primary"
+		],
+		additionalProperties: false,
+		properties: {
+			primary: {
+				$ref: "#/$defs/cssColor",
+				description: "Brand color. Drives interactive-*, accent-*, text-link, border-focus tokens. Anchored at shade 600."
+			},
+			accent: {
+				$ref: "#/$defs/cssColor",
+				description: "Secondary brand color. Defaults to primary if omitted."
+			},
+			neutral: {
+				$ref: "#/$defs/cssColor",
+				description: "Base neutral color for generating the gray scale (50-950). Defaults to Tailwind Gray if omitted."
+			},
+			background: {
+				$ref: "#/$defs/cssColor",
+				description: "Page background for light mode. Default: #FFFFFF."
+			},
+			surface: {
+				$ref: "#/$defs/cssColor",
+				description: "Card/panel background for light mode. Default: #FFFFFF."
+			},
+			success: {
+				$ref: "#/$defs/cssColor",
+				description: "Success status color. Default: #22C55E (Tailwind green-500)."
+			},
+			warning: {
+				$ref: "#/$defs/cssColor",
+				description: "Warning status color. Default: #F59E0B (Tailwind amber-500)."
+			},
+			error: {
+				$ref: "#/$defs/cssColor",
+				description: "Error status color. Default: #EF4444 (Tailwind red-500)."
+			},
+			info: {
+				$ref: "#/$defs/cssColor",
+				description: "Info status color. Default: #0EA5E9 (Tailwind sky-500)."
+			}
+		}
+	},
+	"colors-dark": {
+		type: "object",
+		description: "Dark mode color overrides. Any key from colors can be overridden. Omitted keys inherit from the derived dark mode values (not from light mode).",
+		additionalProperties: false,
+		properties: {
+			primary: {
+				$ref: "#/$defs/cssColor"
+			},
+			accent: {
+				$ref: "#/$defs/cssColor"
+			},
+			neutral: {
+				$ref: "#/$defs/cssColor"
+			},
+			background: {
+				$ref: "#/$defs/cssColor"
+			},
+			surface: {
+				$ref: "#/$defs/cssColor"
+			},
+			success: {
+				$ref: "#/$defs/cssColor"
+			},
+			warning: {
+				$ref: "#/$defs/cssColor"
+			},
+			error: {
+				$ref: "#/$defs/cssColor"
+			},
+			info: {
+				$ref: "#/$defs/cssColor"
+			}
+		}
+	},
+	typography: {
+		type: "object",
+		description: "Typography configuration. Defaults to system font stacks if omitted.",
+		additionalProperties: false,
+		properties: {
+			heading: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					family: {
+						type: "string",
+						description: "Google Fonts family name or CSS font stack."
+					},
+					weight: {
+						type: "integer",
+						minimum: 100,
+						maximum: 900,
+						description: "Font weight for headings. Default: 600."
+					},
+					source: {
+						type: "string",
+						"enum": [
+							"google-fonts",
+							"visor-fonts",
+							"local"
+						],
+						description: "Font source. Defaults to Google Fonts lookup, then local."
+					},
+					org: {
+						type: "string",
+						description: "Organization namespace for visor-fonts CDN (required when source is visor-fonts)."
+					}
+				}
+			},
+			display: {
+				type: "object",
+				description: "Display/decorative font for hero text and splash screens. Falls back to heading font if omitted.",
+				additionalProperties: false,
+				properties: {
+					family: {
+						type: "string",
+						description: "Google Fonts family name or CSS font stack."
+					},
+					weight: {
+						type: "integer",
+						minimum: 100,
+						maximum: 900,
+						description: "Font weight for display text. Default: 400."
+					},
+					source: {
+						type: "string",
+						"enum": [
+							"google-fonts",
+							"visor-fonts",
+							"local"
+						],
+						description: "Font source. Defaults to Google Fonts lookup, then local."
+					},
+					org: {
+						type: "string",
+						description: "Organization namespace for visor-fonts CDN (required when source is visor-fonts)."
+					}
+				}
+			},
+			body: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					family: {
+						type: "string",
+						description: "Google Fonts family name or CSS font stack."
+					},
+					weight: {
+						type: "integer",
+						minimum: 100,
+						maximum: 900,
+						description: "Font weight for body text. Default: 400."
+					},
+					source: {
+						type: "string",
+						"enum": [
+							"google-fonts",
+							"visor-fonts",
+							"local"
+						],
+						description: "Font source. Defaults to Google Fonts lookup, then local."
+					},
+					org: {
+						type: "string",
+						description: "Organization namespace for visor-fonts CDN (required when source is visor-fonts)."
+					}
+				}
+			},
+			mono: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					family: {
+						type: "string",
+						description: "Google Fonts family name or CSS font stack for monospace."
+					}
+				}
+			},
+			scale: {
+				type: "number",
+				description: "Type scale multiplier applied to the font-size ramp. Default: 1."
+			},
+			"letter-spacing": {
+				type: "object",
+				description: "Letter spacing scale.",
+				additionalProperties: false,
+				properties: {
+					tight: {
+						type: "string"
+					},
+					normal: {
+						type: "string"
+					},
+					wide: {
+						type: "string"
+					}
+				}
+			}
+		}
+	},
+	spacing: {
+		type: "object",
+		description: "Spacing configuration.",
+		additionalProperties: false,
+		properties: {
+			base: {
+				type: "number",
+				minimum: 1,
+				description: "Base spacing unit in pixels. Default: 4. Generates the full spacing scale."
+			}
+		}
+	},
+	radius: {
+		type: "object",
+		description: "Border radius scale in pixels.",
+		additionalProperties: false,
+		properties: {
+			sm: {
+				type: "number",
+				minimum: 0
+			},
+			md: {
+				type: "number",
+				minimum: 0
+			},
+			lg: {
+				type: "number",
+				minimum: 0
+			},
+			xl: {
+				type: "number",
+				minimum: 0
+			},
+			pill: {
+				type: "number",
+				minimum: 0,
+				description: "Default: 9999."
+			}
+		}
+	},
+	shadows: {
+		type: "object",
+		description: "Named shadow definitions as CSS box-shadow values.",
+		additionalProperties: false,
+		properties: {
+			xs: {
+				type: "string"
+			},
+			sm: {
+				type: "string"
+			},
+			md: {
+				type: "string"
+			},
+			lg: {
+				type: "string"
+			},
+			xl: {
+				type: "string"
+			}
+		}
+	},
+	motion: {
+		type: "object",
+		description: "Motion/animation configuration.",
+		additionalProperties: false,
+		properties: {
+			"duration-fast": {
+				type: "string",
+				pattern: "^\\d+ms$",
+				description: "Fast duration for micro-interactions. Default: 100ms."
+			},
+			"duration-normal": {
+				type: "string",
+				pattern: "^\\d+ms$",
+				description: "Normal duration for standard transitions. Default: 200ms."
+			},
+			"duration-slow": {
+				type: "string",
+				pattern: "^\\d+ms$",
+				description: "Slow duration for larger animations. Default: 500ms."
+			},
+			easing: {
+				type: "string",
+				description: "Default easing curve as a CSS timing function."
+			}
+		}
+	},
+	overrides: {
+		type: "object",
+		description: "Per-token escape hatch. Values replace derived tokens. Use CSS custom property names without the -- prefix as keys.",
+		additionalProperties: false,
+		properties: {
+			light: {
+				type: "object",
+				description: "Token overrides applied in light mode.",
+				additionalProperties: {
+					type: "string"
+				}
+			},
+			dark: {
+				type: "object",
+				description: "Token overrides applied in dark mode.",
+				additionalProperties: {
+					type: "string"
+				}
+			}
+		}
+	}
+};
+var $defs = {
+	cssColor: {
+		type: "string",
+		description: "CSS color value. Accepts hex (#RGB, #RRGGBB, #RRGGBBAA), rgb()/rgba(), hsl()/hsla(), or oklch() formats.",
+		anyOf: [
+			{
+				pattern: "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$"
+			},
+			{
+				pattern: "^rgba?\\("
+			},
+			{
+				pattern: "^hsla?\\("
+			},
+			{
+				pattern: "^oklch\\("
+			}
+		]
+	}
+};
+var visorTheme_schema = {
+	$schema: $schema,
+	$id: $id,
+	title: title,
+	description: description,
+	type: type,
+	required: required,
+	additionalProperties: additionalProperties,
+	properties: properties,
+	$defs: $defs
+};
+
+/**
+ * JSON Schema & Validation
+ *
+ * Exports the .visor.yaml JSON Schema and a lightweight validation function.
+ * No external validation library — keeps the bundle small for browser use.
+ */
+
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Lightweight structural validation for a .visor.yaml config object.
+ * Checks required fields, types, and hex color format.
+ * For full JSON Schema validation, use the exported schema with ajv or similar.
+ */
+declare function validateConfig(config: unknown): ValidationResult;
+/**
+ * Type guard that validates and narrows an unknown config to VisorThemeConfig.
+ */
+declare function isVisorThemeConfig(config: unknown): config is VisorThemeConfig;
+
+/**
+ * Theme Validator
+ *
+ * Comprehensive validation for .visor.yaml theme configs.
+ * Returns structured, JSON-serializable results with errors (blocking)
+ * and warnings (non-blocking).
+ *
+ * Consumed by CLI (`npx visor theme validate`) and the docs site
+ * (live validation in the future theme creator).
+ */
+type ValidationSeverity = "error" | "warning";
+interface ValidationIssue {
+    severity: ValidationSeverity;
+    code: string;
+    message: string;
+    path?: string;
+}
+interface ThemeValidationResult {
+    valid: boolean;
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+}
+/**
+ * Validate a theme config comprehensively.
+ *
+ * Returns structured results with errors (blocking) and warnings (non-blocking).
+ * Results are JSON-serializable for CLI `--json` output.
+ *
+ * @param config - A parsed theme config object (from YAML or programmatic)
+ * @returns ThemeValidationResult with errors[], warnings[], and valid boolean
+ */
+declare function validate(config: unknown): ThemeValidationResult;
+
+/**
+ * Shade Scale Generation
+ *
+ * Generates perceptually uniform shade scales (50-950) from a base hex color
+ * using the OKLCH color space. Implements the algorithm from the interchange format spec.
+ */
+
+/** Tailwind Gray — used verbatim when neutral is omitted from .visor.yaml. */
+declare const TAILWIND_GRAY: FullShadeScale;
+/**
+ * Generate a shade scale from a base color and a color role.
+ * Accepts any supported CSS color format (hex, rgba, hsla, oklch).
+ *
+ * Primary/accent/neutral produce a full 11-step scale (50-950).
+ * Status colors (success/warning/error/info) produce a selective 6-step scale.
+ */
+declare function generateShadeScale(color: string, role: ColorRole): FullShadeScale | SelectiveShadeScale;
+
+/**
+ * OKLCH Color Math
+ *
+ * Pure color conversion and gamut mapping utilities with zero external dependencies.
+ * Ported from Blacklight's colorMath.ts with improved gamut clamping via binary search.
+ */
+
+/**
+ * Normalize a hex color to lowercase 6-digit format.
+ * Accepts #RGB, #RRGGBB, or #RRGGBBAA (alpha is stripped).
+ * Returns null if invalid.
+ */
+declare function normalizeHex(hex: string): string | null;
+declare function isValidHex(hex: string): boolean;
+declare function hexToRgb(hex: string): RGB;
+declare function rgbToHex(rgb: RGB): string;
+declare function hexToOklch(hex: string): OKLCH;
+/**
+ * Gamut-map an OKLCH color into sRGB by reducing chroma via binary search.
+ * Preserves lightness and hue — only chroma is adjusted.
+ */
+declare function clampToSrgb(L: number, C: number, H: number): RGB;
+/**
+ * Convert OKLCH to hex, with gamut clamping.
+ */
+declare function oklchToHex(L: number, C: number, H: number): string;
+declare function getContrastRatio(color1: string | ParsedColor, color2: string | ParsedColor, compositeBackground?: RGB): number;
+/** Parse a hex color string into a ParsedColor. */
+declare function parseHex(str: string): ParsedColor | null;
+/** Parse an rgb() or rgba() color string into a ParsedColor. */
+declare function parseRgba(str: string): ParsedColor | null;
+/** Parse an hsl() or hsla() color string into a ParsedColor. */
+declare function parseHsla(str: string): ParsedColor | null;
+/** Parse an oklch() color string into a ParsedColor. */
+declare function parseOklch(str: string): ParsedColor | null;
+/**
+ * Parse any supported CSS color string into a ParsedColor.
+ * Supports hex, rgba(), hsla(), and oklch().
+ * Returns null if the string is not a recognized format.
+ */
+declare function parseColor(str: string): ParsedColor | null;
+/** Returns true if the string is a valid CSS color in any supported format. */
+declare function isValidColor(str: string): boolean;
+/**
+ * Alpha-composite a color with alpha onto an opaque background.
+ * Returns the composited RGB value.
+ */
+declare function compositeOverBackground(color: ParsedColor, background: RGB): RGB;
+/**
+ * Serialize a ParsedColor back to a CSS string in its original format.
+ * For non-hex formats, returns the original string to avoid lossy round-trips
+ * (especially oklch, where gamut clamping makes RGB→OKLCH irreversible).
+ * Falls back to re-deriving from RGB only for hex format.
+ */
+declare function serializeColor(parsed: ParsedColor): string;
+
+/**
+ * Config Resolution
+ *
+ * Takes a raw VisorThemeConfig and fills in all defaults,
+ * producing a fully resolved config ready for the pipeline.
+ */
+
+declare function resolveConfig(config: VisorThemeConfig): ResolvedThemeConfig;
+
+/**
+ * Semantic Token Assignment (Stage 2)
+ *
+ * Takes generated primitives and resolved config, applies the semantic mapping table,
+ * and produces concrete hex values for every semantic token in light and dark modes.
+ */
+
+/**
+ * Assign semantic tokens from generated shade scales and resolved config.
+ * Returns concrete hex values for all ~55 tokens in both light and dark modes.
+ */
+declare function assignSemanticTokens(primitives: GeneratedPrimitives, config: ResolvedThemeConfig): SemanticTokens;
+
+/**
+ * Override Application (Stage 4)
+ *
+ * Applies the optional `overrides` section from .visor.yaml,
+ * replacing derived token values with user-specified values.
+ */
+
+/**
+ * Apply override values to semantic tokens.
+ * Returns a new SemanticTokens with overrides applied (does not mutate input).
+ */
+declare function applyOverrides(tokens: SemanticTokens, overrides?: {
+    light?: Record<string, string>;
+    dark?: Record<string, string>;
+}): SemanticTokens;
+
+/**
+ * Semantic Token Mapping Table
+ *
+ * Static data encoding the complete Stage 2 mapping from the interchange format spec.
+ * Each token maps to a {role, shade} reference for both light and dark modes.
+ *
+ * Matches the existing adaptive.ts structure in packages/tokens/ exactly.
+ */
+
+interface ShadeRef {
+    role: ColorRole;
+    shade: ShadeStep;
+}
+interface ConstantRef {
+    constant: string;
+}
+type TokenRef = ShadeRef | ConstantRef;
+interface SemanticMapping {
+    light: TokenRef;
+    dark: TokenRef;
+}
+/** All semantic maps grouped together. */
+declare const SEMANTIC_MAP: {
+    text: Record<string, SemanticMapping>;
+    surface: Record<string, SemanticMapping>;
+    border: Record<string, SemanticMapping>;
+    interactive: Record<string, SemanticMapping>;
+};
+
+/**
+ * CSS Generation (Stage 3 + Output)
+ *
+ * Generates CSS custom property strings matching the existing
+ * packages/tokens/src/generate/generate-css.ts output format.
+ */
+
+declare function generatePrimitivesCss(primitives: GeneratedPrimitives, config: ResolvedThemeConfig): string;
+declare function generateSemanticCss(tokens: SemanticTokens): string;
+declare function generateLightCss(tokens: SemanticTokens): string;
+declare function generateDarkCss(tokens: SemanticTokens): string;
+declare function generateFullBundleCss(primitives: GeneratedPrimitives, tokens: SemanticTokens, config: ResolvedThemeConfig): string;
+
+/**
+ * Theme Extraction Engine
+ *
+ * Scans CSS files from an existing project and produces a best-effort
+ * VisorThemeConfig with confidence annotations per token.
+ *
+ * Handles three CSS architectures:
+ * 1. Reference app: full 3-tier separation, :root/.dark, RGB channels
+ * 2. Blacklight: flat primitives only, no semantic layer, opacity variants
+ * 3. Kaiah: OKLCH format, @custom-variant dark, @theme inline syntax
+ */
+
+type Confidence = "high" | "medium" | "low";
+interface ExtractedToken {
+    name: string;
+    value: string;
+    context: "light" | "dark";
+    confidence: Confidence;
+    reason: string;
+}
+interface ExtractionResult {
+    config: VisorThemeConfig;
+    tokens: ExtractedToken[];
+    unmapped: Array<{
+        name: string;
+        value: string;
+        context: "light" | "dark";
+    }>;
+    warnings: string[];
+}
+interface CSSFile {
+    path: string;
+    content: string;
+}
+interface CSSDeclaration {
+    property: string;
+    value: string;
+    context: "light" | "dark";
+}
+/**
+ * Parse CSS content and extract all custom property declarations.
+ * Groups them by light/dark context based on selector.
+ */
+declare function parseCSSDeclarations(css: string): CSSDeclaration[];
+interface FontFaceDeclaration {
+    family: string;
+    src?: string;
+    weight?: string;
+    style?: string;
+}
+/**
+ * Parse @font-face blocks from CSS content and extract font metadata.
+ * Runs before CSS custom property extraction so @font-face fonts are
+ * available as fallback font hints.
+ */
+declare function parseFontFaceDeclarations(css: string): FontFaceDeclaration[];
+/**
+ * Clean a font-family CSS value to extract just the primary font name.
+ *
+ * Handles:
+ * - var() references (returned as-is by default, or resolved via resolveVarFont)
+ * - Quoted font names with trailing quote artifacts (Fix 3: VI-82)
+ * - Font stacks with fallback families (Fix 3: VI-82)
+ * - Bare font names
+ */
+declare function cleanFontValue(val: string): string;
+/**
+ * Extract a VisorThemeConfig from CSS files.
+ *
+ * @param files - Array of CSS files with path and content
+ * @param name - Theme name for the output config
+ * @returns ExtractionResult with config, token details, unmapped tokens, and warnings
+ */
+declare function extractFromCSS(files: CSSFile[], name?: string): ExtractionResult;
+
+export { type CSSFile, ColorRole, type Confidence, type ExtractedToken, type ExtractionResult, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, ShadeStep, TAILWIND_GRAY, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_FONTS_CDN, type ValidationIssue, type ValidationSeverity, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorFontUrl, clampToSrgb, cleanFontValue, compositeOverBackground, exportTheme, extractFromCSS, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, googleFontsCatalog, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, lookupGoogleFont, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveConfig, resolveFont, resolveThemeFonts, rgbToHex, serializeColor, validate, validateConfig, visorTheme_schema as visorThemeSchema };