@lessonkit/themes 1.2.0 → 1.3.1

package/dist/index.cjs

@@ -36,6 +36,7 @@ __export(index_exports, {
   lightTheme: () => lightTheme,
   mergeThemes: () => mergeThemes,
   radiusVarName: () => radiusVarName,
+  sanitizeCssCustomPropertyValue: () => sanitizeCssCustomPropertyValue,
   shadowVarName: () => shadowVarName,
   spacingVarName: () => spacingVarName,
   themeToCssDeclarationBlock: () => themeToCssDeclarationBlock,
@@ -68,9 +69,20 @@ var TYPOGRAPHY_KEYS = [
 ];
 var RADIUS_KEYS = ["sm", "md", "lg"];
 var SHADOW_KEYS = ["sm", "md", "lg"];
+var EXTRA_COLOR_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
 function isNonEmptyString(v) {
   return typeof v === "string" && v.trim().length > 0;
 }
+function isSafeCssCustomPropertyValue(value) {
+  return !/[;}\r\n\\<>]/.test(value) && !value.includes("/*");
+}
+function validateCssTokenValue(path, value, issues) {
+  if (!isSafeCssCustomPropertyValue(value)) {
+    issues.push({ path, message: "must not contain CSS-breaking characters (;, }, newlines, or comments)" });
+    return false;
+  }
+  return true;
+}
 function validateRequiredGroup(group, value, keys, issues) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     issues.push({ path: group, message: "must be an object" });
@@ -82,7 +94,7 @@ function validateRequiredGroup(group, value, keys, issues) {
     const v = obj[key];
     if (!isNonEmptyString(v)) {
       issues.push({ path: `${group}.${key}`, message: "required non-empty string" });
-    } else {
+    } else if (validateCssTokenValue(`${group}.${key}`, v, issues)) {
       out[key] = v;
     }
   }
@@ -96,9 +108,16 @@ function validateColorsExtra(value, issues) {
   }
   const extra = {};
   for (const [k, v] of Object.entries(value)) {
+    if (!EXTRA_COLOR_KEY_PATTERN.test(k)) {
+      issues.push({
+        path: `colors.extra.${k}`,
+        message: "key must match [a-zA-Z][a-zA-Z0-9_-]*"
+      });
+      continue;
+    }
     if (!isNonEmptyString(v)) {
       issues.push({ path: `colors.extra.${k}`, message: "must be a non-empty string" });
-    } else {
+    } else if (validateCssTokenValue(`colors.extra.${k}`, v, issues)) {
       extra[k] = v;
     }
   }
@@ -204,6 +223,21 @@ function mergeThemes(base, ...overrides) {
 }
 
 // src/cssVariables.ts
+function sanitizeCssCustomPropertyValue(value) {
+  if (/[;}\r\n\\<>]/.test(value) || value.includes("/*")) return null;
+  return value;
+}
+function isSafeCssSelector(selector) {
+  if (selector === ":root") return true;
+  if (/^\.[a-zA-Z_][\w-]*$/.test(selector)) return true;
+  if (/^#[a-zA-Z_][\w-]*$/.test(selector)) return true;
+  if (/^\[data-lk-theme=(["'])[^"']+\1\]$/.test(selector)) return true;
+  return false;
+}
+function assignCssVar(vars, key, value) {
+  const safe = sanitizeCssCustomPropertyValue(value);
+  if (safe !== null) vars[key] = safe;
+}
 function tokenKeyToKebab(key) {
   return key.replace(/([A-Z])/g, "-$1").toLowerCase();
 }
@@ -230,23 +264,23 @@ function themeToCssVariables(theme) {
   for (const [key, value] of Object.entries(theme.colors)) {
     if (key === "extra" && value && typeof value === "object") {
       for (const [ek, ev] of Object.entries(value)) {
-        vars[colorExtraVarName(ek)] = ev;
+        assignCssVar(vars, colorExtraVarName(ek), ev);
       }
     } else if (key !== "extra") {
-      vars[colorVarName(key)] = value;
+      assignCssVar(vars, colorVarName(key), value);
     }
   }
   for (const [key, value] of Object.entries(theme.spacing)) {
-    vars[spacingVarName(key)] = value;
+    assignCssVar(vars, spacingVarName(key), value);
   }
   for (const [key, value] of Object.entries(theme.typography)) {
-    vars[typographyVarName(key)] = value;
+    assignCssVar(vars, typographyVarName(key), value);
   }
   for (const [key, value] of Object.entries(theme.radius)) {
-    vars[radiusVarName(key)] = value;
+    assignCssVar(vars, radiusVarName(key), value);
   }
   for (const [key, value] of Object.entries(theme.shadows)) {
-    vars[shadowVarName(key)] = value;
+    assignCssVar(vars, shadowVarName(key), value);
   }
   const sorted = {};
   for (const key of Object.keys(vars).sort()) {
@@ -256,6 +290,9 @@ function themeToCssVariables(theme) {
 }
 function themeToCssDeclarationBlock(theme, opts) {
   const selector = opts?.selector ?? ":root";
+  if (!isSafeCssSelector(selector)) {
+    throw new Error(`[lessonkit] unsafe CSS selector for theme block: ${selector}`);
+  }
   const vars = themeToCssVariables(theme);
   const body = Object.entries(vars).map(([k, v]) => `  ${k}: ${v};`).join("\n");
   return `${selector} {
@@ -373,8 +410,11 @@ var PRESETS = {
   dark: darkTheme,
   brand: brandTheme
 };
+function cloneTheme(theme) {
+  return JSON.parse(JSON.stringify(theme));
+}
 function getPresetTheme(preset) {
-  return PRESETS[preset];
+  return cloneTheme(PRESETS[preset]);
 }
 
 // src/catalog.ts
@@ -492,6 +532,7 @@ function buildThemeCatalog() {
   lightTheme,
   mergeThemes,
   radiusVarName,
+  sanitizeCssCustomPropertyValue,
   shadowVarName,
   spacingVarName,
   themeToCssDeclarationBlock,

package/dist/index.d.cts

@@ -53,6 +53,8 @@ declare const REQUIRED_SHADOW_KEYS: ThemeShadowKey[];
  */
 declare function mergeThemes(base: LessonkitThemeV1, ...overrides: (PartialLessonkitThemeV1 | undefined)[]): LessonkitThemeV1;
 
+/** Reject values that could break out of a CSS declaration block. */
+declare function sanitizeCssCustomPropertyValue(value: string): string | null;
 /** Map a token path segment to kebab-case for CSS custom property names. */
 declare function tokenKeyToKebab(key: string): string;
 /** CSS custom property name for a color token (required keys). */
@@ -93,4 +95,4 @@ type ThemeCatalogEntry = {
 /** Enumerable catalog of themeable tokens (v1). */
 declare function buildThemeCatalog(): ThemeCatalogEntry[];
 
-export { type LessonkitTheme, type LessonkitThemeColors, type LessonkitThemeRadius, type LessonkitThemeShadows, type LessonkitThemeSpacing, type LessonkitThemeTypography, type LessonkitThemeV1, type PartialLessonkitThemeV1, REQUIRED_COLOR_KEYS, REQUIRED_RADIUS_KEYS, REQUIRED_SHADOW_KEYS, REQUIRED_SPACING_KEYS, REQUIRED_TYPOGRAPHY_KEYS, type ThemeCatalogEntry, type ThemeColorKey, type ThemePresetName, type ThemeRadiusKey, type ThemeShadowKey, type ThemeSpacingKey, type ThemeTypographyKey, type ThemeValidationIssue, type ThemeValidationResult, brandTheme, brandThemeOverrides, buildThemeCatalog, colorExtraVarName, colorVarName, darkTheme, defaultTheme, getPresetTheme, lightTheme, mergeThemes, radiusVarName, shadowVarName, spacingVarName, themeToCssDeclarationBlock, themeToCssVariables, tokenKeyToKebab, typographyVarName, validateTheme };
+export { type LessonkitTheme, type LessonkitThemeColors, type LessonkitThemeRadius, type LessonkitThemeShadows, type LessonkitThemeSpacing, type LessonkitThemeTypography, type LessonkitThemeV1, type PartialLessonkitThemeV1, REQUIRED_COLOR_KEYS, REQUIRED_RADIUS_KEYS, REQUIRED_SHADOW_KEYS, REQUIRED_SPACING_KEYS, REQUIRED_TYPOGRAPHY_KEYS, type ThemeCatalogEntry, type ThemeColorKey, type ThemePresetName, type ThemeRadiusKey, type ThemeShadowKey, type ThemeSpacingKey, type ThemeTypographyKey, type ThemeValidationIssue, type ThemeValidationResult, brandTheme, brandThemeOverrides, buildThemeCatalog, colorExtraVarName, colorVarName, darkTheme, defaultTheme, getPresetTheme, lightTheme, mergeThemes, radiusVarName, sanitizeCssCustomPropertyValue, shadowVarName, spacingVarName, themeToCssDeclarationBlock, themeToCssVariables, tokenKeyToKebab, typographyVarName, validateTheme };

package/dist/index.d.ts

@@ -53,6 +53,8 @@ declare const REQUIRED_SHADOW_KEYS: ThemeShadowKey[];
  */
 declare function mergeThemes(base: LessonkitThemeV1, ...overrides: (PartialLessonkitThemeV1 | undefined)[]): LessonkitThemeV1;
 
+/** Reject values that could break out of a CSS declaration block. */
+declare function sanitizeCssCustomPropertyValue(value: string): string | null;
 /** Map a token path segment to kebab-case for CSS custom property names. */
 declare function tokenKeyToKebab(key: string): string;
 /** CSS custom property name for a color token (required keys). */
@@ -93,4 +95,4 @@ type ThemeCatalogEntry = {
 /** Enumerable catalog of themeable tokens (v1). */
 declare function buildThemeCatalog(): ThemeCatalogEntry[];
 
-export { type LessonkitTheme, type LessonkitThemeColors, type LessonkitThemeRadius, type LessonkitThemeShadows, type LessonkitThemeSpacing, type LessonkitThemeTypography, type LessonkitThemeV1, type PartialLessonkitThemeV1, REQUIRED_COLOR_KEYS, REQUIRED_RADIUS_KEYS, REQUIRED_SHADOW_KEYS, REQUIRED_SPACING_KEYS, REQUIRED_TYPOGRAPHY_KEYS, type ThemeCatalogEntry, type ThemeColorKey, type ThemePresetName, type ThemeRadiusKey, type ThemeShadowKey, type ThemeSpacingKey, type ThemeTypographyKey, type ThemeValidationIssue, type ThemeValidationResult, brandTheme, brandThemeOverrides, buildThemeCatalog, colorExtraVarName, colorVarName, darkTheme, defaultTheme, getPresetTheme, lightTheme, mergeThemes, radiusVarName, shadowVarName, spacingVarName, themeToCssDeclarationBlock, themeToCssVariables, tokenKeyToKebab, typographyVarName, validateTheme };
+export { type LessonkitTheme, type LessonkitThemeColors, type LessonkitThemeRadius, type LessonkitThemeShadows, type LessonkitThemeSpacing, type LessonkitThemeTypography, type LessonkitThemeV1, type PartialLessonkitThemeV1, REQUIRED_COLOR_KEYS, REQUIRED_RADIUS_KEYS, REQUIRED_SHADOW_KEYS, REQUIRED_SPACING_KEYS, REQUIRED_TYPOGRAPHY_KEYS, type ThemeCatalogEntry, type ThemeColorKey, type ThemePresetName, type ThemeRadiusKey, type ThemeShadowKey, type ThemeSpacingKey, type ThemeTypographyKey, type ThemeValidationIssue, type ThemeValidationResult, brandTheme, brandThemeOverrides, buildThemeCatalog, colorExtraVarName, colorVarName, darkTheme, defaultTheme, getPresetTheme, lightTheme, mergeThemes, radiusVarName, sanitizeCssCustomPropertyValue, shadowVarName, spacingVarName, themeToCssDeclarationBlock, themeToCssVariables, tokenKeyToKebab, typographyVarName, validateTheme };

package/dist/index.js

@@ -20,9 +20,20 @@ var TYPOGRAPHY_KEYS = [
 ];
 var RADIUS_KEYS = ["sm", "md", "lg"];
 var SHADOW_KEYS = ["sm", "md", "lg"];
+var EXTRA_COLOR_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
 function isNonEmptyString(v) {
   return typeof v === "string" && v.trim().length > 0;
 }
+function isSafeCssCustomPropertyValue(value) {
+  return !/[;}\r\n\\<>]/.test(value) && !value.includes("/*");
+}
+function validateCssTokenValue(path, value, issues) {
+  if (!isSafeCssCustomPropertyValue(value)) {
+    issues.push({ path, message: "must not contain CSS-breaking characters (;, }, newlines, or comments)" });
+    return false;
+  }
+  return true;
+}
 function validateRequiredGroup(group, value, keys, issues) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     issues.push({ path: group, message: "must be an object" });
@@ -34,7 +45,7 @@ function validateRequiredGroup(group, value, keys, issues) {
     const v = obj[key];
     if (!isNonEmptyString(v)) {
       issues.push({ path: `${group}.${key}`, message: "required non-empty string" });
-    } else {
+    } else if (validateCssTokenValue(`${group}.${key}`, v, issues)) {
       out[key] = v;
     }
   }
@@ -48,9 +59,16 @@ function validateColorsExtra(value, issues) {
   }
   const extra = {};
   for (const [k, v] of Object.entries(value)) {
+    if (!EXTRA_COLOR_KEY_PATTERN.test(k)) {
+      issues.push({
+        path: `colors.extra.${k}`,
+        message: "key must match [a-zA-Z][a-zA-Z0-9_-]*"
+      });
+      continue;
+    }
     if (!isNonEmptyString(v)) {
       issues.push({ path: `colors.extra.${k}`, message: "must be a non-empty string" });
-    } else {
+    } else if (validateCssTokenValue(`colors.extra.${k}`, v, issues)) {
       extra[k] = v;
     }
   }
@@ -156,6 +174,21 @@ function mergeThemes(base, ...overrides) {
 }
 
 // src/cssVariables.ts
+function sanitizeCssCustomPropertyValue(value) {
+  if (/[;}\r\n\\<>]/.test(value) || value.includes("/*")) return null;
+  return value;
+}
+function isSafeCssSelector(selector) {
+  if (selector === ":root") return true;
+  if (/^\.[a-zA-Z_][\w-]*$/.test(selector)) return true;
+  if (/^#[a-zA-Z_][\w-]*$/.test(selector)) return true;
+  if (/^\[data-lk-theme=(["'])[^"']+\1\]$/.test(selector)) return true;
+  return false;
+}
+function assignCssVar(vars, key, value) {
+  const safe = sanitizeCssCustomPropertyValue(value);
+  if (safe !== null) vars[key] = safe;
+}
 function tokenKeyToKebab(key) {
   return key.replace(/([A-Z])/g, "-$1").toLowerCase();
 }
@@ -182,23 +215,23 @@ function themeToCssVariables(theme) {
   for (const [key, value] of Object.entries(theme.colors)) {
     if (key === "extra" && value && typeof value === "object") {
       for (const [ek, ev] of Object.entries(value)) {
-        vars[colorExtraVarName(ek)] = ev;
+        assignCssVar(vars, colorExtraVarName(ek), ev);
       }
     } else if (key !== "extra") {
-      vars[colorVarName(key)] = value;
+      assignCssVar(vars, colorVarName(key), value);
     }
   }
   for (const [key, value] of Object.entries(theme.spacing)) {
-    vars[spacingVarName(key)] = value;
+    assignCssVar(vars, spacingVarName(key), value);
   }
   for (const [key, value] of Object.entries(theme.typography)) {
-    vars[typographyVarName(key)] = value;
+    assignCssVar(vars, typographyVarName(key), value);
   }
   for (const [key, value] of Object.entries(theme.radius)) {
-    vars[radiusVarName(key)] = value;
+    assignCssVar(vars, radiusVarName(key), value);
   }
   for (const [key, value] of Object.entries(theme.shadows)) {
-    vars[shadowVarName(key)] = value;
+    assignCssVar(vars, shadowVarName(key), value);
   }
   const sorted = {};
   for (const key of Object.keys(vars).sort()) {
@@ -208,6 +241,9 @@ function themeToCssVariables(theme) {
 }
 function themeToCssDeclarationBlock(theme, opts) {
   const selector = opts?.selector ?? ":root";
+  if (!isSafeCssSelector(selector)) {
+    throw new Error(`[lessonkit] unsafe CSS selector for theme block: ${selector}`);
+  }
   const vars = themeToCssVariables(theme);
   const body = Object.entries(vars).map(([k, v]) => `  ${k}: ${v};`).join("\n");
   return `${selector} {
@@ -325,8 +361,11 @@ var PRESETS = {
   dark: darkTheme,
   brand: brandTheme
 };
+function cloneTheme(theme) {
+  return JSON.parse(JSON.stringify(theme));
+}
 function getPresetTheme(preset) {
-  return PRESETS[preset];
+  return cloneTheme(PRESETS[preset]);
 }
 
 // src/catalog.ts
@@ -443,6 +482,7 @@ export {
   lightTheme,
   mergeThemes,
   radiusVarName,
+  sanitizeCssCustomPropertyValue,
   shadowVarName,
   spacingVarName,
   themeToCssDeclarationBlock,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/themes",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "private": false,
   "description": "Theme primitives and tokens for LessonKit.",
   "license": "Apache-2.0",