@loworbitstudio/visor-theme-engine 0.12.0 → 0.14.0

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { g as GeneratedPrimitives, m as SemanticTokens, R as ResolvedThemeConfig } from '../types-BKEkyelS.js';
+import { g as GeneratedPrimitives, m as SemanticTokens, R as ResolvedThemeConfig } from '../types-BDRXkldG.js';
 
 /**
  * Adapter types for the Visor theme engine.

package/dist/adapters/index.js

@@ -4,6 +4,7 @@ import {
   SELECTIVE_SHADE_STEPS,
   aliasFamily,
   buildVisorFontUrl,
+  collectBrandPassthrough,
   fontStack,
   generateDarkCss,
   generateHairlineDecls,
@@ -18,7 +19,53 @@ import {
   resolveThemeBrand,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-B56A5DE6.js";
+} from "../chunk-YDRQQIOB.js";
+
+// src/adapters/brand-passthrough.ts
+var SENTINEL_COLOR = "#ff00ff";
+function isDevBuild() {
+  return process.env.NODE_ENV !== "production";
+}
+function isUnresolved(value) {
+  return typeof value !== "string" || value.trim().length === 0;
+}
+function declFor(key, value) {
+  if (isUnresolved(value)) {
+    if (isDevBuild()) {
+      return `--${key}: ${SENTINEL_COLOR}; /* [visor-brand] UNRESOLVED pass-through value */`;
+    }
+    return `--${key}: ${value};`;
+  }
+  return `--${key}: ${value};`;
+}
+function indentBlock(selector, decls) {
+  if (decls.length === 0) return "";
+  return [selector + " {", ...decls.map((d) => `  ${d}`), "}"].join("\n");
+}
+function generateBrandPassthroughCss(passthrough, selectors) {
+  const lightKeys = Object.keys(passthrough.light);
+  const darkKeys = Object.keys(passthrough.dark);
+  if (lightKeys.length === 0 && darkKeys.length === 0) return "";
+  const blocks = [];
+  if (isDevBuild()) {
+    const names = [.../* @__PURE__ */ new Set([...lightKeys, ...darkKeys])].map((k) => `--${k}`).join(", ");
+    const count = lightKeys.length + darkKeys.length;
+    blocks.push(`/* [visor-brand] ${count} passthrough: ${names} */`);
+  }
+  if (lightKeys.length > 0) {
+    const decls = lightKeys.map((k) => declFor(k, passthrough.light[k]));
+    blocks.push(indentBlock(selectors.light, decls));
+  }
+  if (darkKeys.length > 0) {
+    const decls = darkKeys.map((k) => declFor(k, passthrough.dark[k]));
+    blocks.push(indentBlock(selectors.dark, decls));
+    const prefersInner = indentBlock(selectors.prefers, decls).split("\n").map((l) => `  ${l}`).join("\n");
+    blocks.push(`@media (prefers-color-scheme: dark) {
+${prefersInner}
+}`);
+  }
+  return blocks.filter(Boolean).join("\n\n");
+}
 
 // src/adapters/layers.ts
 var LAYER_ORDER = "@layer visor-primitives, visor-semantic, visor-brand, visor-adaptive, visor-bridge;";
@@ -102,6 +149,17 @@ function nextjsAdapter(input, options) {
   );
   lines.push(wrapInLayer("visor-primitives", primitivesBody));
   lines.push("");
+  const passthrough = collectBrandPassthrough(input.tokens, input.config.overrides);
+  const darkSelectors = scopePrefix ? [`${scopePrefix}.dark`, `${scopePrefix}.theme-dark`, `${scopePrefix}[data-theme="dark"]`] : [".dark", ".theme-dark", '[data-theme="dark"]'];
+  const passthroughCss = generateBrandPassthroughCss(passthrough, {
+    light: scopePrefix ?? ":root",
+    dark: darkSelectors.join(",\n"),
+    prefers: scopePrefix ? `${scopePrefix}:not(.light):not(.theme-light):not([data-theme="light"])` : ':root:not(.light):not(.theme-light):not([data-theme="light"])'
+  });
+  if (passthroughCss) {
+    lines.push(wrapInLayer("visor-brand", passthroughCss));
+    lines.push("");
+  }
   const lightBody = stripHeader(generateLightCss(input.tokens, { scopePrefix }));
   const darkBody = stripHeader(generateDarkCss(input.tokens, { scopePrefix }));
   lines.push(
@@ -562,7 +620,7 @@ function docsAdapter(input, options) {
   ];
   for (const cat of pcsCategories) {
     lines.push(sectionComment2(`Adaptive: ${cat.label} (dark) \u2014 prefers-color-scheme`));
-    const inner = block(`${scopeClass}:not(.light)`, cat.entries);
+    const inner = block(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, cat.entries);
     lines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
@@ -570,7 +628,7 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   }
   if (darkPrimitiveOverrides.length > 0) {
     lines.push(sectionComment2("Primitive overrides (dark) \u2014 prefers-color-scheme"));
-    const inner = block(`${scopeClass}:not(.light)`, darkPrimitiveOverrides);
+    const inner = block(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, darkPrimitiveOverrides);
     lines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
@@ -616,7 +674,7 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   semanticLines.push("");
   semanticLines.push(sectionComment2("Intent aliases (dark) \u2014 prefers-color-scheme"));
   {
-    const inner = block(`${scopeClass}:not(.light)`, generateIntentDecls(input.tokens, "dark"));
+    const inner = block(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, generateIntentDecls(input.tokens, "dark"));
     semanticLines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
@@ -624,16 +682,25 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   semanticLines.push("");
   semanticLines.push(sectionComment2("Hairline aliases (dark) \u2014 prefers-color-scheme"));
   {
-    const inner = block(`${scopeClass}:not(.light)`, generateHairlineDecls(input.tokens, "dark"));
+    const inner = block(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, generateHairlineDecls(input.tokens, "dark"));
     semanticLines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
   }
   semanticLines.push("");
   const brandResult = resolveThemeBrand(input.config.brand, { scope: scopeClass });
+  const passthroughCss = generateBrandPassthroughCss(
+    collectBrandPassthrough(input.tokens, input.config.overrides),
+    {
+      light: `html:not(.dark) ${scopeClass}`,
+      dark: `.dark ${scopeClass}`,
+      prefers: `${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`
+    }
+  );
   const adaptiveLayer = wrapInLayer("visor-adaptive", lines.join("\n").trim());
   const semanticLayer = wrapInLayer("visor-semantic", semanticLines.join("\n").trim());
-  const brandLayer = wrapInLayer("visor-brand", brandResult.css);
+  const brandLayerBody = [brandResult.css, passthroughCss].filter(Boolean).join("\n\n");
+  const brandLayer = wrapInLayer("visor-brand", brandLayerBody);
   const head = fontLines.length > 0 ? fontLines.join("\n") + "\n" : "";
   const layerBlocks = [semanticLayer, brandLayer, adaptiveLayer].filter(Boolean);
   return head + LAYER_ORDER + "\n\n" + layerBlocks.join("\n\n") + "\n";

package/dist/{chunk-B56A5DE6.js → chunk-YDRQQIOB.js}

@@ -802,7 +802,8 @@ var BRAND_VARIANTS = [
   "brandmark",
   "wordmark",
   "monochrome",
-  "favicon"
+  "favicon",
+  "animated"
 ];
 
 // src/brand/pipeline.ts
@@ -1346,6 +1347,91 @@ function generateShadeScale(color, role) {
   return scale;
 }
 
+// src/overrides.ts
+var TOKEN_CATEGORIES = [
+  { prefix: "text-", key: "text" },
+  { prefix: "surface-", key: "surface" },
+  { prefix: "border-", key: "border" },
+  { prefix: "interactive-", key: "interactive" },
+  { prefix: "hairline-", key: "hairline" }
+];
+function findToken(key, tokens) {
+  if (key === "hairline" && "default" in tokens.hairline) {
+    return { group: tokens.hairline, name: "default" };
+  }
+  for (const { prefix, key: groupKey } of TOKEN_CATEGORIES) {
+    if (key.startsWith(prefix)) {
+      const name = key.slice(prefix.length);
+      if (name in tokens[groupKey]) {
+        return { group: tokens[groupKey], name };
+      }
+    }
+  }
+  if (key in tokens.intent) {
+    return { group: tokens.intent, name: key };
+  }
+  return null;
+}
+function isRecognizedOverrideKey(key, tokens) {
+  return findToken(key, tokens) !== null;
+}
+function collectBrandPassthrough(tokens, overrides) {
+  const passthrough = { light: {}, dark: {} };
+  if (!overrides) return passthrough;
+  for (const mode of ["light", "dark"]) {
+    const modeOverrides = overrides[mode];
+    if (!modeOverrides) continue;
+    for (const [key, value] of Object.entries(modeOverrides)) {
+      if (!isRecognizedOverrideKey(key, tokens)) {
+        passthrough[mode][key] = value;
+      }
+    }
+  }
+  return passthrough;
+}
+function hasBrandPassthrough(passthrough) {
+  return Object.keys(passthrough.light).length > 0 || Object.keys(passthrough.dark).length > 0;
+}
+function applyOverrides(tokens, overrides) {
+  if (!overrides) return tokens;
+  const result = {
+    text: { ...tokens.text },
+    surface: { ...tokens.surface },
+    border: { ...tokens.border },
+    interactive: { ...tokens.interactive },
+    intent: { ...tokens.intent },
+    hairline: { ...tokens.hairline }
+  };
+  for (const group of ["text", "surface", "border", "interactive", "intent", "hairline"]) {
+    for (const [name, value] of Object.entries(result[group])) {
+      result[group][name] = { ...value };
+    }
+  }
+  if (overrides.light) {
+    for (const [key, value] of Object.entries(overrides.light)) {
+      const match = findToken(key, result);
+      if (match) {
+        match.group[match.name] = {
+          ...match.group[match.name],
+          light: value
+        };
+      }
+    }
+  }
+  if (overrides.dark) {
+    for (const [key, value] of Object.entries(overrides.dark)) {
+      const match = findToken(key, result);
+      if (match) {
+        match.group[match.name] = {
+          ...match.group[match.name],
+          dark: value
+        };
+      }
+    }
+  }
+  return result;
+}
+
 // src/fonts/theme-alias.ts
 var EMPTY_ALIASES = /* @__PURE__ */ new Map();
 function aliasFamily(family, themeSlug) {
@@ -1821,6 +1907,9 @@ export {
   SELECTIVE_SHADE_STEPS,
   TAILWIND_GRAY,
   generateShadeScale,
+  collectBrandPassthrough,
+  hasBrandPassthrough,
+  applyOverrides,
   aliasFamily,
   fontStack,
   header,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, c as VisorBrand, B as BrandSlot, d as BrandSource, e as BrandResolution, f as ThemeBrandResult, R as ResolvedThemeConfig, g as GeneratedPrimitives, h as ThemeOutput, i as ThemeData, j as VisorThemeConfig, k as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, l as RGB, P as ParsedColor, O as OKLCH, m as SemanticTokens, n as ShadeStep } from './types-BKEkyelS.js';
-export { o as BRAND_VARIANTS, p as BrandVariant, q as ColorFormat, r as FontSource, s as RGBA, t as SemanticTokenValue } from './types-BKEkyelS.js';
+import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, c as VisorBrand, B as BrandSlot, d as BrandSource, e as BrandResolution, f as ThemeBrandResult, R as ResolvedThemeConfig, g as GeneratedPrimitives, h as ThemeOutput, i as ThemeData, j as VisorThemeConfig, k as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, l as RGB, P as ParsedColor, O as OKLCH, m as SemanticTokens, n as ShadeStep } from './types-BDRXkldG.js';
+export { o as BRAND_VARIANTS, p as BrandVariant, q as ColorFormat, r as FontSource, s as RGBA, t as SemanticTokenValue } from './types-BDRXkldG.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -315,6 +315,18 @@ var properties = {
 		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."
 	},
+	label: {
+		type: "string",
+		description: "Human-readable display name for the theme (e.g. 'Blacklight Pro'). Overrides the name-derived label in the docs theme switcher. Optional."
+	},
+	"default-mode": {
+		type: "string",
+		"enum": [
+			"light",
+			"dark"
+		],
+		description: "Default color mode when activating this theme. When set, the docs site forces this mode on theme switch (unless the user has a stored mode preference). Optional."
+	},
 	colors: {
 		type: "object",
 		description: "Color definitions for light mode. Only primary is required — all others have sensible defaults.",
@@ -631,6 +643,9 @@ var properties = {
 			favicon: {
 				$ref: "#/$defs/brandSlot"
 			},
+			animated: {
+				$ref: "#/$defs/brandSlot"
+			},
 			custom: {
 				type: "object",
 				description: "Operator-defined slots, addressed by key.",
@@ -943,6 +958,21 @@ interface ThemeValidationResult {
     errors: ValidationIssue[];
     warnings: ValidationIssue[];
 }
+/**
+ * Options for the validate() function.
+ */
+interface ValidateOptions {
+    /**
+     * When true, promote DARK_LIGHT_PARITY warnings and the
+     * "colors.neutral present without colors-dark.neutral" check
+     * from warning to error. Use this in CI to enforce the
+     * "always both modes" authoring convention.
+     *
+     * Opt-in today; flip to the default after all convergent
+     * themes add their dark neutral (see VI-495 docs).
+     */
+    strictDark?: boolean;
+}
 /**
  * Validate a theme config comprehensively.
  *
@@ -950,9 +980,10 @@ interface ThemeValidationResult {
  * Results are JSON-serializable for CLI `--json` output.
  *
  * @param config - A parsed theme config object (from YAML or programmatic)
+ * @param options - Optional validator flags (e.g. strictDark)
  * @returns ThemeValidationResult with errors[], warnings[], and valid boolean
  */
-declare function validate(config: unknown): ThemeValidationResult;
+declare function validate(config: unknown, options?: ValidateOptions): ThemeValidationResult;
 
 /**
  * Shade Scale Generation
@@ -1059,6 +1090,30 @@ declare function assignSemanticTokens(lightPrimitives: GeneratedPrimitives, dark
  * replacing derived token values with user-specified values.
  */
 
+/** Pass-through brand tokens collected per mode (VI-493). */
+interface BrandPassthrough {
+    light: Record<string, string>;
+    dark: Record<string, string>;
+}
+/**
+ * Collect unrecognized override keys into a brand-passthrough map (VI-493).
+ *
+ * Any `overrides.{light,dark}` key that does NOT map to a recognized semantic,
+ * intent, or hairline token is captured here verbatim (key + value). These were
+ * previously DROPPED silently by `applyOverrides`; the adapters now emit them as
+ * bare `--<key>` custom properties inside `@layer visor-brand`, ending the
+ * dual-source-of-truth between `.visor.yaml` and hand-maintained `:root` blocks.
+ *
+ * Recognized tokens are excluded — they continue to flow through the normal
+ * semantic pipeline. Pass-through tokens are legitimately mode-asymmetric (a key
+ * may appear in `light` only, `dark` only, or both); no both-modes rule applies.
+ */
+declare function collectBrandPassthrough(tokens: SemanticTokens, overrides?: {
+    light?: Record<string, string>;
+    dark?: Record<string, string>;
+}): BrandPassthrough;
+/** True when the passthrough map carries at least one token in either mode. */
+declare function hasBrandPassthrough(passthrough: BrandPassthrough): boolean;
 /**
  * Apply override values to semantic tokens.
  * Returns a new SemanticTokens with overrides applied (does not mutate input).
@@ -1218,4 +1273,4 @@ declare function cleanFontValue(val: string): string;
  */
 declare function extractFromCSS(files: CSSFile[], name?: string): ExtractionResult;
 
-export { BrandResolution, BrandSlot, BrandSource, type CSSFile, ColorRole, type Confidence, DEFAULT_VISOR_BRAND, type ExtractedToken, type ExtractionResult, FONT_WEIGHT_ALIASES, type FontCoverageError, type FontCoverageResult, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, ShadeStep, TAILWIND_GRAY, ThemeBrandResult, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_BRANDS_CDN, VISOR_DEFAULT_BRAND_PATH, VISOR_FONTS_CDN, type ValidationIssue, type ValidationSeverity, VisorBrand, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorBrandUrl, buildVisorFontUrl, clampToSrgb, cleanFontValue, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, googleFontsCatalog, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, lookupFontWeightAlias, lookupGoogleFont, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveBrandSlot, resolveBrandSource, resolveConfig, resolveFont, resolveThemeBrand, resolveThemeFonts, rgbToHex, serializeColor, validate, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };
+export { type BrandPassthrough, BrandResolution, BrandSlot, BrandSource, type CSSFile, ColorRole, type Confidence, DEFAULT_VISOR_BRAND, type ExtractedToken, type ExtractionResult, FONT_WEIGHT_ALIASES, type FontCoverageError, type FontCoverageResult, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, ShadeStep, TAILWIND_GRAY, ThemeBrandResult, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_BRANDS_CDN, VISOR_DEFAULT_BRAND_PATH, VISOR_FONTS_CDN, type ValidateOptions, type ValidationIssue, type ValidationSeverity, VisorBrand, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorBrandUrl, buildVisorFontUrl, clampToSrgb, cleanFontValue, collectBrandPassthrough, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, googleFontsCatalog, hasBrandPassthrough, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, lookupFontWeightAlias, lookupGoogleFont, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveBrandSlot, resolveBrandSource, resolveConfig, resolveFont, resolveThemeBrand, resolveThemeFonts, rgbToHex, serializeColor, validate, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };

package/dist/index.js

@@ -7,9 +7,11 @@ import {
   VISOR_BRANDS_CDN,
   VISOR_DEFAULT_BRAND_PATH,
   VISOR_FONTS_CDN,
+  applyOverrides,
   buildVisorBrandUrl,
   buildVisorFontUrl,
   clampToSrgb,
+  collectBrandPassthrough,
   compositeOverBackground,
   generateDarkCss,
   generateFullBundleCss,
@@ -21,6 +23,7 @@ import {
   generateStylesheetLinks,
   getContrastRatio,
   googleFontsCatalog,
+  hasBrandPassthrough,
   hexToOklch,
   hexToRgb,
   isValidColor,
@@ -42,7 +45,7 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-B56A5DE6.js";
+} from "./chunk-YDRQQIOB.js";
 
 // src/fonts/validate-coverage.ts
 var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
@@ -224,6 +227,15 @@ var visor_theme_schema_default = {
       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."
     },
+    label: {
+      type: "string",
+      description: "Human-readable display name for the theme (e.g. 'Blacklight Pro'). Overrides the name-derived label in the docs theme switcher. Optional."
+    },
+    "default-mode": {
+      type: "string",
+      enum: ["light", "dark"],
+      description: "Default color mode when activating this theme. When set, the docs site forces this mode on theme switch (unless the user has a stored mode preference). Optional."
+    },
     colors: {
       type: "object",
       description: "Color definitions for light mode. Only primary is required \u2014 all others have sensible defaults.",
@@ -457,6 +469,7 @@ var visor_theme_schema_default = {
         wordmark: { $ref: "#/$defs/brandSlot" },
         monochrome: { $ref: "#/$defs/brandSlot" },
         favicon: { $ref: "#/$defs/brandSlot" },
+        animated: { $ref: "#/$defs/brandSlot" },
         custom: {
           type: "object",
           description: "Operator-defined slots, addressed by key.",
@@ -705,9 +718,10 @@ var KNOWN_BRAND_KEYS = /* @__PURE__ */ new Set([
   "wordmark",
   "monochrome",
   "favicon",
+  "animated",
   "custom"
 ]);
-var KNOWN_BRAND_STANDARD_SLOTS = ["logo", "brandmark", "wordmark", "monochrome", "favicon"];
+var KNOWN_BRAND_STANDARD_SLOTS = ["logo", "brandmark", "wordmark", "monochrome", "favicon", "animated"];
 var KNOWN_BRAND_SLOT_KEYS = /* @__PURE__ */ new Set(["slug", "formats", "light", "dark", "clearSpace", "aspectRatio"]);
 var KNOWN_BRAND_SOURCES = /* @__PURE__ */ new Set(["visor-brands", "local"]);
 var KNOWN_BRAND_CDN_OVERRIDE_KEYS = /* @__PURE__ */ new Set(["visor-brands"]);
@@ -1039,6 +1053,20 @@ function validateConfig(config) {
           }
         }
       }
+      if (typeof brand.animated === "object" && brand.animated !== null) {
+        const animated = brand.animated;
+        if (Array.isArray(animated.formats) && !animated.formats.every(
+          (f) => typeof f === "string" && f.toLowerCase() === "svg"
+        )) {
+          errors.push("'brand.animated.formats' must be SVG-only (the animated slot accepts self-contained animated SVGs only)");
+        }
+        for (const mode of ["light", "dark"]) {
+          const p = animated[mode];
+          if (typeof p === "string" && !p.toLowerCase().endsWith(".svg")) {
+            errors.push(`'brand.animated.${mode}' must be an .svg path (the animated slot is SVG-only)`);
+          }
+        }
+      }
     }
   }
   if (obj.overrides !== void 0) {
@@ -1112,6 +1140,9 @@ function resolveBrand(brand) {
     wordmark: brand.wordmark ?? DEFAULT_VISOR_BRAND.wordmark,
     monochrome: brand.monochrome ?? DEFAULT_VISOR_BRAND.monochrome,
     favicon: brand.favicon ?? DEFAULT_VISOR_BRAND.favicon,
+    // animated is optional with no Visor default (D2): pass through only when a
+    // theme declares it, so undeclared themes emit no --brand-animated.
+    ...brand.animated && { animated: brand.animated },
     ...brand.custom && { custom: brand.custom }
   };
 }
@@ -1146,6 +1177,7 @@ function resolveConfig(config) {
   return {
     name: config.name,
     ...config.label !== void 0 && { label: config.label },
+    ...config["default-mode"] !== void 0 && { "default-mode": config["default-mode"] },
     version: 1,
     colors: {
       primary: colors.primary,
@@ -1407,7 +1439,7 @@ var SEMANTIC_SURFACE_MAP = {
   // VI-478: status soft tints (BL-193) — alpha overlays, semantically distinct
   // from the OPAQUE `surface-{status}-subtle` above (do NOT alias them together).
   // Default to a color-mix of the status color so they track the theme; themes
-  // pin exact values via overrides (blacklight-underground: success @10%,
+  // pin exact values via overrides (blacklight-pro: success @10%,
   // warning/error @12%).
   "success-soft": {
     light: { constant: "color-mix(in srgb, var(--color-success-500) 10%, transparent)" },
@@ -1504,7 +1536,7 @@ var SEMANTIC_INTERACTIVE_MAP = {
   // VI-478: brand-derived alpha-overlay helpers (BL-193). `soft`/`glow` are
   // alpha overlays that track the theme's primary via color-mix (distinct from
   // any opaque surface); `strong` is a solid lightened-brand emphasis color.
-  // Themes pin exact values via overrides — e.g. blacklight-underground sets
+  // Themes pin exact values via overrides — e.g. blacklight-pro sets
   // soft @12% / glow @32% / strong #FFD050.
   "primary-soft": {
     light: { constant: "color-mix(in srgb, var(--color-primary-500) 12%, transparent)" },
@@ -1567,11 +1599,14 @@ var SEMANTIC_INTENT_MAP = {
     light: { role: "primary", shade: 500 },
     dark: { role: "primary", shade: 500 }
   },
-  // Text color paired with --primary backgrounds. Default white; themes whose
-  // primary fails AA on white pin to a graphite via overrides (entr does this).
+  // Single-source alias of --interactive-primary-text. Default white (same value
+  // as the interactive group); themes that need a different value (e.g. entr)
+  // override via overrides.{light,dark}["primary-text"] which replaces this alias
+  // with the explicit override value. Hand-authored static CSS (blackout-theme.css,
+  // neutral-theme.css) should consume --primary-text via this alias path.
   "primary-text": {
-    light: { constant: "#ffffff" },
-    dark: { constant: "#ffffff" }
+    light: { constant: "var(--interactive-primary-text)" },
+    dark: { constant: "var(--interactive-primary-text)" }
   },
   accent: {
     light: { role: "accent", shade: 500 },
@@ -1676,71 +1711,6 @@ function assignSemanticTokens(lightPrimitives, darkPrimitives, config) {
   return { text, surface, border, interactive, intent, hairline };
 }
 
-// src/overrides.ts
-var TOKEN_CATEGORIES = [
-  { prefix: "text-", key: "text" },
-  { prefix: "surface-", key: "surface" },
-  { prefix: "border-", key: "border" },
-  { prefix: "interactive-", key: "interactive" },
-  { prefix: "hairline-", key: "hairline" }
-];
-function findToken(key, tokens) {
-  if (key === "hairline" && "default" in tokens.hairline) {
-    return { group: tokens.hairline, name: "default" };
-  }
-  for (const { prefix, key: groupKey } of TOKEN_CATEGORIES) {
-    if (key.startsWith(prefix)) {
-      const name = key.slice(prefix.length);
-      if (name in tokens[groupKey]) {
-        return { group: tokens[groupKey], name };
-      }
-    }
-  }
-  if (key in tokens.intent) {
-    return { group: tokens.intent, name: key };
-  }
-  return null;
-}
-function applyOverrides(tokens, overrides) {
-  if (!overrides) return tokens;
-  const result = {
-    text: { ...tokens.text },
-    surface: { ...tokens.surface },
-    border: { ...tokens.border },
-    interactive: { ...tokens.interactive },
-    intent: { ...tokens.intent },
-    hairline: { ...tokens.hairline }
-  };
-  for (const group of ["text", "surface", "border", "interactive", "intent", "hairline"]) {
-    for (const [name, value] of Object.entries(result[group])) {
-      result[group][name] = { ...value };
-    }
-  }
-  if (overrides.light) {
-    for (const [key, value] of Object.entries(overrides.light)) {
-      const match = findToken(key, result);
-      if (match) {
-        match.group[match.name] = {
-          ...match.group[match.name],
-          light: value
-        };
-      }
-    }
-  }
-  if (overrides.dark) {
-    for (const [key, value] of Object.entries(overrides.dark)) {
-      const match = findToken(key, result);
-      if (match) {
-        match.group[match.name] = {
-          ...match.group[match.name],
-          dark: value
-        };
-      }
-    }
-  }
-  return result;
-}
-
 // src/pipeline.ts
 function generatePrimitives(config) {
   return {
@@ -2342,7 +2312,7 @@ function checkOverrides(config, issues) {
           issue(
             "warning",
             "UNKNOWN_OVERRIDE_KEY",
-            `'overrides.${mode}.${key}' does not match any known semantic token. Valid tokens include: text-primary, surface-page, border-default, interactive-primary-bg, etc.`,
+            `'overrides.${mode}.${key}' does not match any known semantic token; it will be emitted as a bare '--${key}' custom property in @layer visor-brand (brand pass-through). If you meant to override a semantic token, valid tokens include: text-primary, surface-page, border-default, interactive-primary-bg, etc.`,
             `overrides.${mode}.${key}`
           )
         );
@@ -2623,14 +2593,15 @@ function checkRadiusScale(config, issues) {
     );
   }
 }
-function checkDarkLightParity(config, issues) {
+function checkDarkLightParity(config, issues, opts) {
   if (!config.colors) return;
   const colorKeys = Object.keys(config.colors).filter((k) => k !== "primary");
   const hasDarkSection = config["colors-dark"] !== void 0;
   if (colorKeys.length > 0 && !hasDarkSection) {
+    const severity = opts.strictDark ? "error" : "warning";
     issues.push(
       issue(
-        "warning",
+        severity,
         "DARK_LIGHT_PARITY",
         "Custom colors are set but no colors-dark section exists. Dark mode will use generated defaults which may not match your brand.",
         "colors-dark"
@@ -2644,9 +2615,10 @@ function checkDarkLightParity(config, issues) {
     for (const key of lightKeys) {
       if (key === "primary") continue;
       if (!darkKeys.has(key)) {
+        const severity = opts.strictDark ? "error" : "warning";
         issues.push(
           issue(
-            "warning",
+            severity,
             "DARK_LIGHT_PARITY",
             `Color "${key}" is set in colors but missing from colors-dark. Dark mode will use a generated default.`,
             "colors-dark"
@@ -2668,7 +2640,8 @@ function checkDarkLightParity(config, issues) {
     }
   }
 }
-function validate(config) {
+function validate(config, options) {
+  const opts = options || {};
   const errors = [];
   const warnings = [];
   const structurallyValid = checkStructuralIntegrity(config, errors);
@@ -2700,7 +2673,11 @@ function validate(config) {
     checkColorSimilarity(typedConfig, warnings);
     checkMissingGlowShadow(typedConfig, warnings);
     checkRadiusScale(typedConfig, warnings);
-    checkDarkLightParity(typedConfig, warnings);
+    const parityIssues = [];
+    checkDarkLightParity(typedConfig, parityIssues, opts);
+    for (const iss of parityIssues) {
+      (iss.severity === "error" ? errors : warnings).push(iss);
+    }
   }
   return {
     valid: errors.length === 0,
@@ -3210,6 +3187,7 @@ export {
   buildVisorFontUrl,
   clampToSrgb,
   cleanFontValue,
+  collectBrandPassthrough,
   compositeOverBackground,
   exportTheme,
   extractFromCSS,
@@ -3229,6 +3207,7 @@ export {
   generateThemeFromConfig,
   getContrastRatio,
   googleFontsCatalog,
+  hasBrandPassthrough,
   hexToOklch,
   hexToRgb,
   isValidColor,

package/dist/{types-BKEkyelS.d.ts → types-BDRXkldG.d.ts}

@@ -138,7 +138,7 @@ type BrandSource = "visor-brands" | "local";
  * Standard brand variant slots. A fixed set covers the common lockups; custom
  * operator-defined slots are addressed by key through the `custom` map.
  */
-type BrandVariant = "logo" | "brandmark" | "wordmark" | "monochrome" | "favicon";
+type BrandVariant = "logo" | "brandmark" | "wordmark" | "monochrome" | "favicon" | "animated";
 /** Ordered list of the standard brand variant slots. */
 declare const BRAND_VARIANTS: readonly BrandVariant[];
 /**
@@ -185,6 +185,13 @@ interface VisorBrand {
     monochrome?: BrandSlot;
     /** Favicon source. */
     favicon?: BrandSlot;
+    /**
+     * Animated lockup. Optional and SVG-only (D2/D3): the asset must be a
+     * self-contained animated SVG (inlined `<style>`/@keyframes or SMIL) so it
+     * animates inside `<img>`. Stock themes omit this — absent → no
+     * `--brand-animated` emitted. Reduced-motion consumers fall back to `logo`.
+     */
+    animated?: BrandSlot;
     /** Operator-defined slots, addressed by key. */
     custom?: Record<string, BrandSlot>;
 }
@@ -405,6 +412,8 @@ interface ResolvedThemeConfig {
     name: string;
     /** Optional display label override forwarded from VisorThemeConfig.label. */
     label?: string;
+    /** Default color mode forwarded from VisorThemeConfig["default-mode"]. */
+    "default-mode"?: "dark" | "light";
     version: 1;
     colors: {
         primary: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor-theme-engine",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Theme engine for the Visor design system — shade generation, token mapping, font resolution, and import/export for .visor.yaml themes.",
   "type": "module",
   "main": "./dist/index.js",

package/src/visor-theme.schema.json

@@ -20,6 +20,15 @@
       "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."
     },
+    "label": {
+      "type": "string",
+      "description": "Human-readable display name for the theme (e.g. 'Blacklight Pro'). Overrides the name-derived label in the docs theme switcher. Optional."
+    },
+    "default-mode": {
+      "type": "string",
+      "enum": ["light", "dark"],
+      "description": "Default color mode when activating this theme. When set, the docs site forces this mode on theme switch (unless the user has a stored mode preference). Optional."
+    },
     "colors": {
       "type": "object",
       "description": "Color definitions for light mode. Only primary is required — all others have sensible defaults.",
@@ -253,6 +262,7 @@
         "wordmark": { "$ref": "#/$defs/brandSlot" },
         "monochrome": { "$ref": "#/$defs/brandSlot" },
         "favicon": { "$ref": "#/$defs/brandSlot" },
+        "animated": { "$ref": "#/$defs/brandSlot" },
         "custom": {
           "type": "object",
           "description": "Operator-defined slots, addressed by key.",