@uniweb/build 0.1.33 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.1.33",
+  "version": "0.2.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -51,7 +51,7 @@
   },
   "optionalDependencies": {
     "@uniweb/content-reader": "1.0.4",
-    "@uniweb/runtime": "0.2.19"
+    "@uniweb/runtime": "0.2.20"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -60,7 +60,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.1.16"
+    "@uniweb/core": "0.2.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/docs.js

@@ -165,8 +165,8 @@ export async function generateDocs(foundationDir, options = {}) {
 
   let schema
 
-  // Try to load schema.json from dist
-  const schemaPath = join(foundationDir, 'dist', 'schema.json')
+  // Try to load schema.json from dist/meta (where foundation build outputs it)
+  const schemaPath = join(foundationDir, 'dist', 'meta', 'schema.json')
 
   if (!fromSource && existsSync(schemaPath)) {
     // Load from existing schema.json

package/src/prerender.js

@@ -306,9 +306,11 @@ function renderBlock(block) {
   }
 
   // Wrapper props
+  // Use stableId for DOM ID if available (stable across reordering)
   const theme = block.themeName
+  const sectionId = block.stableId || block.id
   const wrapperProps = {
-    id: `Section${block.id}`,
+    id: `section-${sectionId}`,
     className: theme || ''
   }
 

package/src/site/content-collector.js

@@ -67,6 +67,90 @@ function extractRouteParam(folderName) {
   return match ? match[1] : null
 }
 
+// ─────────────────────────────────────────────────────────────────
+// Version Detection
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Check if a folder name represents a version (e.g., v1, v2, v1.0, v2.1)
+ * @param {string} folderName - The folder name to check
+ * @returns {boolean}
+ */
+function isVersionFolder(folderName) {
+  return /^v\d+(\.\d+)?$/.test(folderName)
+}
+
+/**
+ * Parse version info from folder name
+ * @param {string} folderName - The folder name (e.g., "v1", "v2.1")
+ * @returns {Object} Version info { id, major, minor, sortKey }
+ */
+function parseVersionInfo(folderName) {
+  const match = folderName.match(/^v(\d+)(?:\.(\d+))?$/)
+  if (!match) return null
+
+  const major = parseInt(match[1], 10)
+  const minor = match[2] ? parseInt(match[2], 10) : 0
+
+  return {
+    id: folderName,
+    major,
+    minor,
+    sortKey: major * 1000 + minor // For sorting: v2.1 > v2.0 > v1.9
+  }
+}
+
+/**
+ * Detect if a set of folders contains version folders
+ * @param {Array<string>} folderNames - List of folder names
+ * @returns {Array<Object>|null} Sorted version infos (highest first) or null if not versioned
+ */
+function detectVersions(folderNames) {
+  const versions = folderNames
+    .filter(isVersionFolder)
+    .map(parseVersionInfo)
+    .filter(Boolean)
+
+  if (versions.length === 0) return null
+
+  // Sort by version (highest first)
+  versions.sort((a, b) => b.sortKey - a.sortKey)
+
+  return versions
+}
+
+/**
+ * Build version metadata from detected versions and page.yml config
+ * @param {Array<Object>} detectedVersions - Detected version infos
+ * @param {Object} pageConfig - page.yml configuration
+ * @returns {Object} Version metadata { versions, latestId, scope }
+ */
+function buildVersionMetadata(detectedVersions, pageConfig = {}) {
+  const configVersions = pageConfig.versions || {}
+
+  // Build version list with metadata
+  const versions = detectedVersions.map((v, index) => {
+    const config = configVersions[v.id] || {}
+    const isLatest = config.latest === true || (index === 0 && !Object.values(configVersions).some(c => c.latest))
+
+    return {
+      id: v.id,
+      label: config.label || v.id,
+      latest: isLatest,
+      deprecated: config.deprecated || false,
+      sortKey: v.sortKey
+    }
+  })
+
+  // Find the latest version
+  const latestVersion = versions.find(v => v.latest) || versions[0]
+
+  return {
+    versions,
+    latestId: latestVersion?.id || null
+  }
+}
+
 /**
  * Parse YAML string using js-yaml
  */
@@ -144,11 +228,12 @@ function compareFilenames(a, b) {
  * Process a markdown file into a section
  *
  * @param {string} filePath - Path to markdown file
- * @param {string} id - Section ID
+ * @param {string} id - Section ID (numeric/positional)
  * @param {string} siteRoot - Site root directory for asset resolution
+ * @param {string} defaultStableId - Default stable ID from filename (can be overridden in frontmatter)
  * @returns {Object} Section data with assets manifest
  */
-async function processMarkdownFile(filePath, id, siteRoot) {
+async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = null) {
   const content = await readFile(filePath, 'utf8')
   let frontMatter = {}
   let markdown = content
@@ -162,7 +247,7 @@ async function processMarkdownFile(filePath, id, siteRoot) {
     }
   }
 
-  const { type, component, preset, input, props, fetch, data, ...params } = frontMatter
+  const { type, component, preset, input, props, fetch, data, id: frontmatterId, ...params } = frontMatter
 
   // Convert markdown to ProseMirror
   const proseMirrorContent = markdownToProseMirror(markdown)
@@ -176,8 +261,13 @@ async function processMarkdownFile(filePath, id, siteRoot) {
     resolvedFetch = { collection: collectionName }
   }
 
+  // Stable ID for scroll targeting: frontmatter id > filename-derived > null
+  // This ID is stable across reordering (unlike the positional id)
+  const stableId = frontmatterId || defaultStableId || null
+
   const section = {
     id,
+    stableId,
     component: type || component || 'Section',
     preset,
     input,
@@ -290,7 +380,8 @@ async function processExplicitSections(sectionsConfig, pagePath, siteRoot, paren
     }
 
     // Process the section
-    const { section, assetCollection: sectionAssets } = await processMarkdownFile(filePath, id, siteRoot)
+    // Use sectionName as stable ID for scroll targeting (e.g., "hero", "features")
+    const { section, assetCollection: sectionAssets } = await processMarkdownFile(filePath, id, siteRoot, sectionName)
     assetCollection = mergeAssetCollections(assetCollection, sectionAssets)
 
     // Track last modified
@@ -326,9 +417,10 @@ async function processExplicitSections(sectionsConfig, pagePath, siteRoot, paren
  * @param {boolean} options.isIndex - Whether this page is the index for its parent route
  * @param {string} options.parentRoute - The parent route (e.g., '/' or '/docs')
  * @param {Object} options.parentFetch - Parent page's fetch config (for dynamic routes)
+ * @param {Object} options.versionContext - Version context from parent { version, versionMeta, scope }
  * @returns {Object} Page data with assets manifest
  */
-async function processPage(pagePath, pageName, siteRoot, { isIndex = false, parentRoute = '/', parentFetch = null } = {}) {
+async function processPage(pagePath, pageName, siteRoot, { isIndex = false, parentRoute = '/', parentFetch = null, versionContext = null } = {}) {
   const pageConfig = await readYamlFile(join(pagePath, 'page.yml'))
 
   // Note: We no longer skip hidden pages here - they still exist as valid pages,
@@ -354,10 +446,13 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
     const sections = []
     for (const file of mdFiles) {
       const { name } = parse(file)
-      const { prefix } = parseNumericPrefix(name)
+      const { prefix, name: stableName } = parseNumericPrefix(name)
       const id = prefix || name
+      // Use the name part (after prefix) as stable ID for scroll targeting
+      // e.g., "1-intro.md" → stableId: "intro", "2-features.md" → stableId: "features"
+      const stableId = stableName || name
 
-      const { section, assetCollection } = await processMarkdownFile(join(pagePath, file), id, siteRoot)
+      const { section, assetCollection } = await processMarkdownFile(join(pagePath, file), id, siteRoot, stableId)
       sections.push(section)
       pageAssetCollection = mergeAssetCollections(pageAssetCollection, assetCollection)
 
@@ -415,6 +510,7 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
   return {
     page: {
       route,
+      id: pageConfig.id || null, // Stable page ID for page: links (survives reorganization)
       isIndex, // Marks this page as the index for its parent route (accessible at parentRoute)
       title: pageConfig.title || pageName,
       description: pageConfig.description || '',
@@ -427,6 +523,11 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
       paramName, // e.g., "slug" from [slug]
       parentSchema, // e.g., "articles" - the data array to iterate over
 
+      // Version metadata (if within a versioned section)
+      version: versionContext?.version || null,
+      versionMeta: versionContext?.versionMeta || null,
+      versionScope: versionContext?.scope || null,
+
       // Navigation options
       hidden: pageConfig.hidden || false, // Hide from all navigation
       hideInHeader: pageConfig.hideInHeader || false, // Hide from header nav
@@ -504,9 +605,10 @@ function determineIndexPage(orderConfig, availableFolders) {
  * @param {string} siteRoot - Site root directory for asset resolution
  * @param {Object} orderConfig - { pages: [...], index: 'name' } from parent's config
  * @param {Object} parentFetch - Parent page's fetch config (for dynamic child routes)
- * @returns {Promise<Object>} { pages, assetCollection, header, footer, left, right, notFound }
+ * @param {Object} versionContext - Version context from parent { version, versionMeta }
+ * @returns {Promise<Object>} { pages, assetCollection, header, footer, left, right, notFound, versionedScopes }
  */
-async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null) {
+async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, versionContext = null) {
   const entries = await readdir(dirPath)
   const pages = []
   let assetCollection = {
@@ -519,6 +621,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
   let left = null
   let right = null
   let notFound = null
+  const versionedScopes = new Map() // scope route → versionMeta
 
   // First pass: discover all page folders and read their order values
   const pageFolders = []
@@ -533,6 +636,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
       name: entry,
       path: entryPath,
       order: pageConfig.order,
+      pageConfig,
       childOrderConfig: {
         pages: pageConfig.pages,
         index: pageConfig.index
@@ -540,6 +644,72 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     })
   }
 
+  // Check if this directory contains version folders (versioned section)
+  const folderNames = pageFolders.map(f => f.name)
+  const detectedVersions = detectVersions(folderNames)
+
+  // If versioned section, handle version folders specially
+  if (detectedVersions && !versionContext) {
+    // Read parent page.yml for version metadata
+    const parentConfig = await readYamlFile(join(dirPath, 'page.yml'))
+    const versionMeta = buildVersionMetadata(detectedVersions, parentConfig)
+
+    // Record this versioned scope
+    versionedScopes.set(parentRoute, versionMeta)
+
+    // Process version folders
+    for (const folder of pageFolders) {
+      const { name: entry, path: entryPath, childOrderConfig, pageConfig } = folder
+
+      if (isVersionFolder(entry)) {
+        // This is a version folder
+        const versionInfo = versionMeta.versions.find(v => v.id === entry)
+        const isLatest = versionInfo?.latest || false
+
+        // For latest version, use parent route directly
+        // For other versions, add version prefix to route
+        const versionRoute = isLatest ? parentRoute : `${parentRoute}/${entry}`
+
+        // Recurse into version folder with version context
+        const subResult = await collectPagesRecursive(
+          entryPath,
+          versionRoute,
+          siteRoot,
+          childOrderConfig,
+          parentFetch,
+          {
+            version: versionInfo,
+            versionMeta,
+            scope: parentRoute // The route where versioning is scoped
+          }
+        )
+
+        pages.push(...subResult.pages)
+        assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
+        // Merge any nested versioned scopes (shouldn't happen often, but possible)
+        for (const [scope, meta] of subResult.versionedScopes) {
+          versionedScopes.set(scope, meta)
+        }
+      } else if (!entry.startsWith('@')) {
+        // Non-version, non-special folders in a versioned section
+        // These could be shared across versions - process normally
+        const result = await processPage(entryPath, entry, siteRoot, {
+          isIndex: false,
+          parentRoute,
+          parentFetch
+        })
+
+        if (result) {
+          pages.push(result.page)
+          assetCollection = mergeAssetCollections(assetCollection, result.assetCollection)
+        }
+      }
+    }
+
+    // Return early - we've handled all children
+    return { pages, assetCollection, header, footer, left, right, notFound, versionedScopes }
+  }
+
   // Determine which page is the index for this level
   const regularFolders = pageFolders.filter(f => !f.name.startsWith('@'))
   const indexPageName = determineIndexPage(orderConfig, regularFolders)
@@ -555,7 +725,8 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     const result = await processPage(entryPath, entry, siteRoot, {
       isIndex: isIndex && !isSpecial,
       parentRoute,
-      parentFetch
+      parentFetch,
+      versionContext
     })
 
     if (result) {
@@ -587,14 +758,19 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         const childParentRoute = isIndex ? parentRoute : page.route
         // Pass this page's fetch config to children (for dynamic routes that inherit parent data)
         const childFetch = page.fetch || parentFetch
-        const subResult = await collectPagesRecursive(entryPath, childParentRoute, siteRoot, childOrderConfig, childFetch)
+        // Pass version context to children (maintains version scope)
+        const subResult = await collectPagesRecursive(entryPath, childParentRoute, siteRoot, childOrderConfig, childFetch, versionContext)
         pages.push(...subResult.pages)
         assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
+        // Merge any versioned scopes from children
+        for (const [scope, meta] of subResult.versionedScopes) {
+          versionedScopes.set(scope, meta)
+        }
       }
     }
   }
 
-  return { pages, assetCollection, header, footer, left, right, notFound }
+  return { pages, assetCollection, header, footer, left, right, notFound, versionedScopes }
 }
 
 /**
@@ -606,11 +782,11 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
 async function loadFoundationVars(foundationPath) {
   if (!foundationPath) return {}
 
-  // Try dist/schema.json first (built foundation), then src/schema.json
-  const distSchemaPath = join(foundationPath, 'dist', 'schema.json')
-  const srcSchemaPath = join(foundationPath, 'schema.json')
+  // Try dist/meta/schema.json first (built foundation), then root schema.json
+  const distSchemaPath = join(foundationPath, 'dist', 'meta', 'schema.json')
+  const rootSchemaPath = join(foundationPath, 'schema.json')
 
-  const schemaPath = existsSync(distSchemaPath) ? distSchemaPath : srcSchemaPath
+  const schemaPath = existsSync(distSchemaPath) ? distSchemaPath : rootSchemaPath
 
   if (!existsSync(schemaPath)) {
     return {}
@@ -672,7 +848,7 @@ export async function collectSiteContent(sitePath, options = {}) {
   }
 
   // Recursively collect all pages
-  const { pages, assetCollection, header, footer, left, right, notFound } =
+  const { pages, assetCollection, header, footer, left, right, notFound, versionedScopes } =
     await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig)
 
   // Sort pages by order
@@ -685,6 +861,9 @@ export async function collectSiteContent(sitePath, options = {}) {
     console.log(`[content-collector] Found ${assetCount} asset references${explicitCount > 0 ? ` (${explicitCount} with explicit poster/preview)` : ''}`)
   }
 
+  // Convert versionedScopes Map to plain object for JSON serialization
+  const versionedScopesObj = Object.fromEntries(versionedScopes)
+
   return {
     config: {
       ...siteConfig,
@@ -700,6 +879,8 @@ export async function collectSiteContent(sitePath, options = {}) {
     left,
     right,
     notFound,
+    // Versioned scopes: route → { versions, latestId }
+    versionedScopes: versionedScopesObj,
     assets: assetCollection.assets,
     hasExplicitPoster: assetCollection.hasExplicitPoster,
     hasExplicitPreview: assetCollection.hasExplicitPreview

package/src/theme/shade-generator.js

@@ -4,6 +4,11 @@
  * Generates 11 color shades (50-950) from a single base color using
  * the OKLCH color space for perceptually uniform results.
  *
+ * Supports multiple generation modes:
+ * - 'fixed' (default): Predictable lightness values, constant hue
+ * - 'natural': Temperature-aware hue shifts, curved chroma
+ * - 'vivid': Higher saturation, more dramatic chroma curve
+ *
  * @module @uniweb/build/theme/shade-generator
  */
 
@@ -42,6 +47,31 @@ const CHROMA_SCALE = {
   950: 0.45,  // Reduced chroma at dark end
 }
 
+// Mode-specific configurations
+const MODE_CONFIG = {
+  // Fixed mode: predictable, consistent (current default behavior)
+  fixed: {
+    hueShift: { light: 0, dark: 0 },
+    chromaBoost: 1.0,
+    lightEndChroma: 0.15,
+    darkEndChroma: 0.45,
+  },
+  // Natural mode: temperature-aware hue shifts, organic feel
+  natural: {
+    hueShift: { light: 5, dark: -15 },  // For warm colors (inverted for cool)
+    chromaBoost: 1.1,
+    lightEndChroma: 0.20,
+    darkEndChroma: 0.40,
+  },
+  // Vivid mode: higher saturation, more dramatic
+  vivid: {
+    hueShift: { light: 3, dark: -10 },
+    chromaBoost: 1.4,
+    lightEndChroma: 0.35,
+    darkEndChroma: 0.55,
+  },
+}
+
 /**
  * Parse a color string into OKLCH components
  * Supports: hex (#fff, #ffffff), rgb(), hsl(), oklch()
@@ -281,6 +311,80 @@ function oklchToRgb(l, c, h) {
   return { r, g, b }
 }
 
+/**
+ * Check if RGB values are within sRGB gamut
+ */
+function inGamut(r, g, b) {
+  return r >= -0.5 && r <= 255.5 && g >= -0.5 && g <= 255.5 && b >= -0.5 && b <= 255.5
+}
+
+/**
+ * Find maximum chroma that fits within sRGB gamut using binary search
+ *
+ * @param {number} l - Lightness
+ * @param {number} h - Hue
+ * @param {number} idealC - Desired chroma (upper bound)
+ * @returns {number} Maximum valid chroma
+ */
+function findMaxChroma(l, h, idealC) {
+  let minC = 0
+  let maxC = idealC
+  let bestC = 0
+
+  // Binary search with 8 iterations for precision
+  for (let i = 0; i < 8; i++) {
+    const midC = (minC + maxC) / 2
+    const rgb = oklchToRgb(l, midC, h)
+    if (inGamut(rgb.r, rgb.g, rgb.b)) {
+      bestC = midC
+      minC = midC
+    } else {
+      maxC = midC
+    }
+  }
+
+  return bestC
+}
+
+/**
+ * Quadratic Bézier interpolation for smooth chroma curves
+ *
+ * @param {number} a - Start value
+ * @param {number} control - Control point
+ * @param {number} b - End value
+ * @param {number} t - Interpolation factor (0-1)
+ * @returns {number} Interpolated value
+ */
+function quadBezier(a, control, b, t) {
+  const mt = 1 - t
+  return mt * mt * a + 2 * mt * t * control + t * t * b
+}
+
+/**
+ * Linear interpolation
+ */
+function lerp(a, b, t) {
+  return a + (b - a) * t
+}
+
+/**
+ * Normalize hue to 0-360 range
+ */
+function normalizeHue(h) {
+  h = h % 360
+  return h < 0 ? h + 360 : h
+}
+
+/**
+ * Check if a color is warm (reds, oranges, yellows)
+ *
+ * @param {number} h - Hue angle (0-360)
+ * @returns {boolean} True if warm
+ */
+function isWarmColor(h) {
+  return (h >= 0 && h < 120) || h > 300
+}
+
 /**
  * Format OKLCH values as CSS string
  *
@@ -316,62 +420,217 @@ export function formatHex(r, g, b) {
  * @param {string} color - Base color in any supported format
  * @param {Object} options - Options
  * @param {string} [options.format='oklch'] - Output format: 'oklch' or 'hex'
+ * @param {string} [options.mode='fixed'] - Generation mode: 'fixed', 'natural', or 'vivid'
+ * @param {boolean} [options.exactMatch=false] - If true, shade 500 will be the exact input color
  * @returns {Object} Object with shade levels as keys (50-950) and color values
+ *
+ * @example
+ * // Default fixed mode (predictable, constant hue)
+ * generateShades('#3b82f6')
+ *
+ * @example
+ * // Natural mode (temperature-aware hue shifts)
+ * generateShades('#3b82f6', { mode: 'natural' })
+ *
+ * @example
+ * // Vivid mode (higher saturation)
+ * generateShades('#3b82f6', { mode: 'vivid', exactMatch: true })
  */
 export function generateShades(color, options = {}) {
-  const { format = 'oklch' } = options
-  const { l, c, h } = parseColor(color)
+  const { format = 'oklch', mode = 'fixed', exactMatch = false } = options
+  const base = parseColor(color)
+  const config = MODE_CONFIG[mode] || MODE_CONFIG.fixed
+
+  // For fixed mode, use the original simple algorithm
+  if (mode === 'fixed') {
+    return generateFixedShades(base, color, format, exactMatch)
+  }
 
+  // For natural/vivid modes, use enhanced algorithm
+  return generateEnhancedShades(base, color, format, config, exactMatch)
+}
+
+/**
+ * Original fixed-lightness algorithm (default)
+ */
+function generateFixedShades(base, originalColor, format, exactMatch) {
   const shades = {}
 
   for (const level of SHADE_LEVELS) {
+    // Handle exact match at 500
+    if (exactMatch && level === 500) {
+      if (format === 'hex') {
+        shades[level] = originalColor.startsWith('#') ? originalColor : formatHexFromOklch(base)
+      } else {
+        shades[level] = formatOklch(base.l, base.c, base.h)
+      }
+      continue
+    }
+
     const targetL = LIGHTNESS_MAP[level]
     const chromaScale = CHROMA_SCALE[level]
+    const targetC = base.c * chromaScale
+
+    // Use gamut mapping to find valid chroma
+    const safeC = findMaxChroma(targetL, base.h, targetC)
+
+    if (format === 'hex') {
+      const rgb = oklchToRgb(targetL, safeC, base.h)
+      shades[level] = formatHex(rgb.r, rgb.g, rgb.b)
+    } else {
+      shades[level] = formatOklch(targetL, safeC, base.h)
+    }
+  }
+
+  return shades
+}
+
+/**
+ * Enhanced algorithm with hue shifting and curved chroma (natural/vivid modes)
+ */
+function generateEnhancedShades(base, originalColor, format, config, exactMatch) {
+  const shades = {}
+  const isWarm = isWarmColor(base.h)
+
+  // Calculate hue shift direction based on color temperature
+  const hueShiftLight = isWarm ? config.hueShift.light : -config.hueShift.light
+  const hueShiftDark = isWarm ? config.hueShift.dark : -config.hueShift.dark
+
+  // Define endpoints
+  const lightEnd = {
+    l: LIGHTNESS_MAP[50],
+    c: base.c * config.lightEndChroma,
+    h: normalizeHue(base.h + hueShiftLight),
+  }
+
+  const darkEnd = {
+    l: LIGHTNESS_MAP[950],
+    c: base.c * config.darkEndChroma,
+    h: normalizeHue(base.h + hueShiftDark),
+  }
+
+  // Control point for chroma curve (peaks at middle)
+  const peakChroma = base.c * config.chromaBoost
+
+  for (let i = 0; i < SHADE_LEVELS.length; i++) {
+    const level = SHADE_LEVELS[i]
+
+    // Handle exact match at 500 (index 5)
+    if (exactMatch && level === 500) {
+      if (format === 'hex') {
+        shades[level] = originalColor.startsWith('#') ? originalColor : formatHexFromOklch(base)
+      } else {
+        shades[level] = formatOklch(base.l, base.c, base.h)
+      }
+      continue
+    }
+
+    let targetL, targetC, targetH
+
+    // Split the curve at the base color (index 5 = shade 500)
+    if (i <= 5) {
+      // Light half: interpolate from lightEnd to base
+      const t = i / 5
+      targetL = lerp(lightEnd.l, base.l, t)
+      targetH = lerp(lightEnd.h, base.h, t)
+
+      // Bézier curve for chroma with peak at middle
+      const controlC = (lightEnd.c + peakChroma) / 2
+      targetC = quadBezier(lightEnd.c, controlC, peakChroma, t)
+    } else {
+      // Dark half: interpolate from base to darkEnd
+      const t = (i - 5) / 5
+      targetL = lerp(base.l, darkEnd.l, t)
+      targetH = lerp(base.h, darkEnd.h, t)
+
+      // Bézier curve for chroma, descending from peak
+      const controlC = (peakChroma + darkEnd.c) / 2
+      targetC = quadBezier(peakChroma, controlC, darkEnd.c, t)
+    }
 
-    // Scale chroma based on lightness to prevent clipping
-    // Also consider the original chroma - low chroma colors stay low
-    const targetC = c * chromaScale
+    // Normalize hue
+    targetH = normalizeHue(targetH)
+
+    // Gamut map to find maximum valid chroma
+    const safeC = findMaxChroma(targetL, targetH, targetC)
 
     if (format === 'hex') {
-      const rgb = oklchToRgb(targetL, targetC, h)
+      const rgb = oklchToRgb(targetL, safeC, targetH)
       shades[level] = formatHex(rgb.r, rgb.g, rgb.b)
     } else {
-      shades[level] = formatOklch(targetL, targetC, h)
+      shades[level] = formatOklch(targetL, safeC, targetH)
     }
   }
 
   return shades
 }
 
+/**
+ * Helper to format OKLCH as hex
+ */
+function formatHexFromOklch(oklch) {
+  const rgb = oklchToRgb(oklch.l, oklch.c, oklch.h)
+  return formatHex(rgb.r, rgb.g, rgb.b)
+}
+
 /**
  * Generate shades for multiple colors
  *
- * @param {Object} colors - Object with color names as keys and color values
- * @param {Object} options - Options passed to generateShades
+ * @param {Object} colors - Object with color names as keys and color values or config objects
+ * @param {Object} options - Default options passed to generateShades
  * @returns {Object} Object with color names, each containing shade levels
  *
  * @example
+ * // Simple usage with defaults
  * generatePalettes({
  *   primary: '#3b82f6',
  *   secondary: '#64748b'
  * })
- * // Returns: { primary: { 50: '...', 100: '...', ... }, secondary: { ... } }
+ *
+ * @example
+ * // With per-color options
+ * generatePalettes({
+ *   primary: { base: '#3b82f6', mode: 'vivid', exactMatch: true },
+ *   secondary: '#64748b',  // Uses defaults
+ *   neutral: { base: '#737373', mode: 'fixed' }
+ * })
  */
 export function generatePalettes(colors, options = {}) {
   const palettes = {}
 
-  for (const [name, color] of Object.entries(colors)) {
-    // Skip if color is already an object (pre-defined shades)
-    if (typeof color === 'object' && color !== null) {
-      palettes[name] = color
-    } else {
-      palettes[name] = generateShades(color, options)
+  for (const [name, colorConfig] of Object.entries(colors)) {
+    // Pre-defined shades (object with numeric keys)
+    if (typeof colorConfig === 'object' && colorConfig !== null && !colorConfig.base) {
+      // Check if it's a shades object (has numeric keys like 50, 100, etc)
+      const keys = Object.keys(colorConfig)
+      if (keys.some(k => !isNaN(parseInt(k)))) {
+        palettes[name] = colorConfig
+        continue
+      }
+    }
+
+    // Color config object with base and options
+    if (typeof colorConfig === 'object' && colorConfig !== null && colorConfig.base) {
+      const { base, ...colorOptions } = colorConfig
+      palettes[name] = generateShades(base, { ...options, ...colorOptions })
+    }
+    // Simple color string
+    else if (typeof colorConfig === 'string') {
+      palettes[name] = generateShades(colorConfig, options)
     }
   }
 
   return palettes
 }
 
+/**
+ * Get available generation modes
+ * @returns {string[]} Array of mode names
+ */
+export function getAvailableModes() {
+  return Object.keys(MODE_CONFIG)
+}
+
 /**
  * Check if a color string is valid
  *
@@ -403,4 +662,5 @@ export default {
   generatePalettes,
   isValidColor,
   getShadeLevels,
+  getAvailableModes,
 }