@loworbitstudio/visor-theme-engine 0.17.0 → 0.17.1

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { k as GeneratedPrimitives, r as SemanticTokens, R as ResolvedThemeConfig } from '../types-DqsWwFVZ.js';
+import { k as GeneratedPrimitives, s as SemanticTokens, R as ResolvedThemeConfig } from '../types-Cvm7vFwe.js';
 
 /**
  * Adapter types for the Visor theme engine.

package/dist/adapters/index.js

@@ -20,7 +20,7 @@ import {
   resolveThemeBrand,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-DQ256PSE.js";
+} from "../chunk-BUWBBUFG.js";
 
 // src/adapters/brand-passthrough.ts
 var SENTINEL_COLOR = "#ff00ff";
@@ -43,7 +43,7 @@ function indentBlock(selector, decls) {
   if (decls.length === 0) return "";
   return [selector + " {", ...decls.map((d) => `  ${d}`), "}"].join("\n");
 }
-function generateBrandPassthroughCss(passthrough, selectors) {
+function generateBrandPassthroughCss(passthrough, selectors, colorScheme = "adaptive") {
   const lightKeys = Object.keys(passthrough.light);
   const darkKeys = Object.keys(passthrough.dark);
   if (lightKeys.length === 0 && darkKeys.length === 0) return "";
@@ -53,6 +53,20 @@ function generateBrandPassthroughCss(passthrough, selectors) {
     const count = lightKeys.length + darkKeys.length;
     blocks.push(`/* [visor-brand] ${count} passthrough: ${names} */`);
   }
+  if (colorScheme === "dark-only") {
+    if (darkKeys.length > 0) {
+      const decls = darkKeys.map((k) => declFor(k, passthrough.dark[k]));
+      blocks.push(indentBlock(selectors.light, decls));
+    }
+    return blocks.filter(Boolean).join("\n\n");
+  }
+  if (colorScheme === "light-only") {
+    if (lightKeys.length > 0) {
+      const decls = lightKeys.map((k) => declFor(k, passthrough.light[k]));
+      blocks.push(indentBlock(selectors.light, decls));
+    }
+    return blocks.filter(Boolean).join("\n\n");
+  }
   if (lightKeys.length > 0) {
     const decls = lightKeys.map((k) => declFor(k, passthrough.light[k]));
     blocks.push(indentBlock(selectors.light, decls));
@@ -86,6 +100,7 @@ function nextjsAdapter(input, options) {
   const includeFontImports = options?.includeFontImports ?? true;
   const includeFowt = options?.includeFowt ?? true;
   const scopePrefix = options?.scopePrefix;
+  const colorScheme = input.config["color-scheme"] ?? "adaptive";
   const lines = [];
   const slug = toKebabCase(input.config.name);
   const aliasedFamilies = /* @__PURE__ */ new Map();
@@ -156,7 +171,7 @@ function nextjsAdapter(input, options) {
     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"])'
-  });
+  }, colorScheme);
   if (passthroughCss) {
     lines.push(wrapInLayer("visor-brand", passthroughCss));
     lines.push("");
@@ -173,43 +188,60 @@ function nextjsAdapter(input, options) {
   semanticLines.push(sectionComment("Discrete: Space aliases (--space-N)"));
   semanticLines.push(block(hostSelector, generateSpaceAliasDecls(input.config)));
   semanticLines.push("");
-  semanticLines.push(sectionComment("Intent aliases (light)"));
-  semanticLines.push(block(lightModeSelector, generateIntentDecls(input.tokens, "light")));
-  semanticLines.push("");
-  semanticLines.push(sectionComment("Hairline aliases (light)"));
-  semanticLines.push(block(lightModeSelector, generateHairlineDecls(input.tokens, "light")));
-  semanticLines.push("");
-  semanticLines.push(sectionComment("Intent aliases (dark) \u2014 manual toggle"));
-  semanticLines.push(block(darkModeSelector, generateIntentDecls(input.tokens, "dark")));
-  semanticLines.push("");
-  semanticLines.push(sectionComment("Hairline aliases (dark) \u2014 manual toggle"));
-  semanticLines.push(block(darkModeSelector, generateHairlineDecls(input.tokens, "dark")));
-  semanticLines.push("");
-  semanticLines.push(sectionComment("Intent aliases (dark) \u2014 prefers-color-scheme"));
-  {
-    const inner = block(prefersSelector, generateIntentDecls(input.tokens, "dark"));
-    semanticLines.push(`@media (prefers-color-scheme: dark) {
+  if (colorScheme === "dark-only") {
+    semanticLines.push(sectionComment("Intent aliases (dark) \u2014 host"));
+    semanticLines.push(block(hostSelector, generateIntentDecls(input.tokens, "dark")));
+    semanticLines.push("");
+    semanticLines.push(sectionComment("Hairline aliases (dark) \u2014 host"));
+    semanticLines.push(block(hostSelector, generateHairlineDecls(input.tokens, "dark")));
+    semanticLines.push("");
+  } else if (colorScheme === "light-only") {
+    semanticLines.push(sectionComment("Intent aliases (light) \u2014 host"));
+    semanticLines.push(block(hostSelector, generateIntentDecls(input.tokens, "light")));
+    semanticLines.push("");
+    semanticLines.push(sectionComment("Hairline aliases (light) \u2014 host"));
+    semanticLines.push(block(hostSelector, generateHairlineDecls(input.tokens, "light")));
+    semanticLines.push("");
+  } else {
+    semanticLines.push(sectionComment("Intent aliases (light)"));
+    semanticLines.push(block(lightModeSelector, generateIntentDecls(input.tokens, "light")));
+    semanticLines.push("");
+    semanticLines.push(sectionComment("Hairline aliases (light)"));
+    semanticLines.push(block(lightModeSelector, generateHairlineDecls(input.tokens, "light")));
+    semanticLines.push("");
+    semanticLines.push(sectionComment("Intent aliases (dark) \u2014 manual toggle"));
+    semanticLines.push(block(darkModeSelector, generateIntentDecls(input.tokens, "dark")));
+    semanticLines.push("");
+    semanticLines.push(sectionComment("Hairline aliases (dark) \u2014 manual toggle"));
+    semanticLines.push(block(darkModeSelector, generateHairlineDecls(input.tokens, "dark")));
+    semanticLines.push("");
+    semanticLines.push(sectionComment("Intent aliases (dark) \u2014 prefers-color-scheme"));
+    {
+      const inner = block(prefersSelector, generateIntentDecls(input.tokens, "dark"));
+      semanticLines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
-  }
-  semanticLines.push("");
-  semanticLines.push(sectionComment("Hairline aliases (dark) \u2014 prefers-color-scheme"));
-  {
-    const inner = block(prefersSelector, generateHairlineDecls(input.tokens, "dark"));
-    semanticLines.push(`@media (prefers-color-scheme: dark) {
+    }
+    semanticLines.push("");
+    semanticLines.push(sectionComment("Hairline aliases (dark) \u2014 prefers-color-scheme"));
+    {
+      const inner = block(prefersSelector, generateHairlineDecls(input.tokens, "dark"));
+      semanticLines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
+    }
+    semanticLines.push("");
   }
-  semanticLines.push("");
   const semanticLayer = wrapInLayer("visor-semantic", semanticLines.join("\n").trim());
   if (semanticLayer) {
     lines.push(semanticLayer);
     lines.push("");
   }
-  const lightBody = stripHeader(generateLightCss(input.tokens, { scopePrefix }));
-  const darkBody = stripHeader(generateDarkCss(input.tokens, { scopePrefix }));
+  const lightBody = stripHeader(generateLightCss(input.tokens, { scopePrefix, colorScheme }));
+  const darkBody = stripHeader(generateDarkCss(input.tokens, { scopePrefix, colorScheme }));
+  const adaptiveBody = [lightBody, darkBody].filter(Boolean).join("\n\n");
   lines.push(
-    wrapInLayer("visor-adaptive", lightBody + "\n\n" + darkBody)
+    wrapInLayer("visor-adaptive", adaptiveBody)
   );
   if (includeFowt) {
     lines.push("");
@@ -554,6 +586,14 @@ function sectionComment2(label) {
 function docsAdapter(input, options) {
   const slug = toKebabCase3(input.config.name);
   const scopeClass = `.${slug}-theme`;
+  const colorScheme = input.config["color-scheme"] ?? "adaptive";
+  const singleMode = colorScheme === "dark-only" ? "dark" : colorScheme === "light-only" ? "light" : null;
+  const emitDark = colorScheme !== "light-only";
+  const emitLight = colorScheme !== "dark-only";
+  const emitPrefers = colorScheme === "adaptive";
+  const darkSel = singleMode ? scopeClass : `.dark ${scopeClass}`;
+  const lightSel = singleMode ? scopeClass : `html:not(.dark) ${scopeClass}`;
+  const darkSuffix = singleMode ? " \u2014 host" : " \u2014 manual toggle";
   const includeFontImports = options?.includeFontImports ?? true;
   const fontLines = [];
   const lines = [];
@@ -601,6 +641,8 @@ function docsAdapter(input, options) {
   const sharedDecls = [
     "min-height: 100vh;",
     "font-size: 1rem;",
+    // BO-56: pin UA chrome to the brand's single mode (adaptive emits nothing).
+    ...singleMode ? [`color-scheme: ${singleMode};`] : [],
     `background: var(--surface-page, var(--surface-background));`,
     "color: var(--text-primary);",
     "font-family: var(--font-sans);"
@@ -650,9 +692,9 @@ function docsAdapter(input, options) {
       }
     }
   }
-  if (darkPrimitiveOverrides.length > 0) {
+  if (darkPrimitiveOverrides.length > 0 && emitDark) {
     lines.push(sectionComment2("Primitive overrides (dark) \u2014 dark brand color anchors at shade 500"));
-    lines.push(block2(`.dark ${scopeClass}`, darkPrimitiveOverrides));
+    lines.push(block2(darkSel, darkPrimitiveOverrides));
     lines.push("");
   }
   const categories = ["Text", "Surface", "Border", "Interactive"];
@@ -662,10 +704,12 @@ function docsAdapter(input, options) {
     Object.entries(input.tokens.border).map(([n, v]) => `--border-${n}: ${v.dark};`),
     Object.entries(input.tokens.interactive).map(([n, v]) => `--interactive-${n}: ${v.dark};`)
   ];
-  for (let i = 0; i < categories.length; i++) {
-    lines.push(sectionComment2(`Adaptive: ${categories[i]} (dark) \u2014 manual toggle`));
-    lines.push(block2(`.dark ${scopeClass}`, categoryDecls[i]));
-    lines.push("");
+  if (emitDark) {
+    for (let i = 0; i < categories.length; i++) {
+      lines.push(sectionComment2(`Adaptive: ${categories[i]} (dark)${darkSuffix}`));
+      lines.push(block2(darkSel, categoryDecls[i]));
+      lines.push("");
+    }
   }
   const pcsCategories = [
     { label: "Text", entries: Object.entries(input.tokens.text).map(([n, v]) => `--text-${n}: ${v.dark};`) },
@@ -673,15 +717,17 @@ function docsAdapter(input, options) {
     { label: "Border", entries: Object.entries(input.tokens.border).map(([n, v]) => `--border-${n}: ${v.dark};`) },
     { label: "Interactive", entries: Object.entries(input.tokens.interactive).map(([n, v]) => `--interactive-${n}: ${v.dark};`) }
   ];
-  for (const cat of pcsCategories) {
-    lines.push(sectionComment2(`Adaptive: ${cat.label} (dark) \u2014 prefers-color-scheme`));
-    const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, cat.entries);
-    lines.push(`@media (prefers-color-scheme: dark) {
+  if (emitPrefers) {
+    for (const cat of pcsCategories) {
+      lines.push(sectionComment2(`Adaptive: ${cat.label} (dark) \u2014 prefers-color-scheme`));
+      const inner = block2(`${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")}
 }`);
-    lines.push("");
+      lines.push("");
+    }
   }
-  if (darkPrimitiveOverrides.length > 0) {
+  if (darkPrimitiveOverrides.length > 0 && emitPrefers) {
     lines.push(sectionComment2("Primitive overrides (dark) \u2014 prefers-color-scheme"));
     const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, darkPrimitiveOverrides);
     lines.push(`@media (prefers-color-scheme: dark) {
@@ -696,17 +742,23 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
     { label: "Border", entries: Object.entries(input.tokens.border).map(([n, v]) => `--border-${n}: ${v.light};`) },
     { label: "Interactive", entries: Object.entries(input.tokens.interactive).map(([n, v]) => `--interactive-${n}: ${v.light};`) }
   ];
-  for (const cat of lightCategoryDecls) {
-    lines.push(sectionComment2(`Adaptive: ${cat.label} (light)`));
-    lines.push(block2(`html:not(.dark) ${scopeClass}`, cat.entries));
+  if (emitLight) {
+    for (const cat of lightCategoryDecls) {
+      lines.push(sectionComment2(`Adaptive: ${cat.label} (light)`));
+      lines.push(block2(lightSel, cat.entries));
+      lines.push("");
+    }
+  }
+  if (emitDark) {
+    lines.push(sectionComment2("Fumadocs bridge: dark"));
+    lines.push(block2(darkSel, generateFumadocsBridgeDecls(input.tokens, "dark")));
+    lines.push("");
+  }
+  if (emitLight) {
+    lines.push(sectionComment2("Fumadocs bridge: light"));
+    lines.push(block2(lightSel, generateFumadocsBridgeDecls(input.tokens, "light")));
     lines.push("");
   }
-  lines.push(sectionComment2("Fumadocs bridge: dark"));
-  lines.push(block2(`.dark ${scopeClass}`, generateFumadocsBridgeDecls(input.tokens, "dark")));
-  lines.push("");
-  lines.push(sectionComment2("Fumadocs bridge: light"));
-  lines.push(block2(`html:not(.dark) ${scopeClass}`, generateFumadocsBridgeDecls(input.tokens, "light")));
-  lines.push("");
   const semanticLines = [];
   semanticLines.push("\n/* \u2500\u2500 Layer: Semantic aliases (VI-451) \u2500\u2500 */");
   semanticLines.push(sectionComment2("Discrete: Text size aliases (--text-N)"));
@@ -715,42 +767,49 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   semanticLines.push(sectionComment2("Discrete: Space aliases (--space-N)"));
   semanticLines.push(block2(scopeClass, generateSpaceAliasDecls(input.config)));
   semanticLines.push("");
-  semanticLines.push(sectionComment2("Intent aliases (light)"));
-  semanticLines.push(block2(`html:not(.dark) ${scopeClass}`, generateIntentDecls(input.tokens, "light")));
-  semanticLines.push("");
-  semanticLines.push(sectionComment2("Hairline aliases (light)"));
-  semanticLines.push(block2(`html:not(.dark) ${scopeClass}`, generateHairlineDecls(input.tokens, "light")));
-  semanticLines.push("");
-  semanticLines.push(sectionComment2("Intent aliases (dark) \u2014 manual toggle"));
-  semanticLines.push(block2(`.dark ${scopeClass}`, generateIntentDecls(input.tokens, "dark")));
-  semanticLines.push("");
-  semanticLines.push(sectionComment2("Hairline aliases (dark) \u2014 manual toggle"));
-  semanticLines.push(block2(`.dark ${scopeClass}`, generateHairlineDecls(input.tokens, "dark")));
-  semanticLines.push("");
-  semanticLines.push(sectionComment2("Intent aliases (dark) \u2014 prefers-color-scheme"));
-  {
-    const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, generateIntentDecls(input.tokens, "dark"));
-    semanticLines.push(`@media (prefers-color-scheme: dark) {
+  if (emitLight) {
+    semanticLines.push(sectionComment2("Intent aliases (light)"));
+    semanticLines.push(block2(lightSel, generateIntentDecls(input.tokens, "light")));
+    semanticLines.push("");
+    semanticLines.push(sectionComment2("Hairline aliases (light)"));
+    semanticLines.push(block2(lightSel, generateHairlineDecls(input.tokens, "light")));
+    semanticLines.push("");
+  }
+  if (emitDark) {
+    semanticLines.push(sectionComment2(`Intent aliases (dark)${darkSuffix}`));
+    semanticLines.push(block2(darkSel, generateIntentDecls(input.tokens, "dark")));
+    semanticLines.push("");
+    semanticLines.push(sectionComment2(`Hairline aliases (dark)${darkSuffix}`));
+    semanticLines.push(block2(darkSel, generateHairlineDecls(input.tokens, "dark")));
+    semanticLines.push("");
+  }
+  if (emitPrefers) {
+    semanticLines.push(sectionComment2("Intent aliases (dark) \u2014 prefers-color-scheme"));
+    {
+      const inner = block2(`${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")}
 }`);
-  }
-  semanticLines.push("");
-  semanticLines.push(sectionComment2("Hairline aliases (dark) \u2014 prefers-color-scheme"));
-  {
-    const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, generateHairlineDecls(input.tokens, "dark"));
-    semanticLines.push(`@media (prefers-color-scheme: dark) {
+    }
+    semanticLines.push("");
+    semanticLines.push(sectionComment2("Hairline aliases (dark) \u2014 prefers-color-scheme"));
+    {
+      const inner = block2(`${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("");
   }
-  semanticLines.push("");
-  const brandResult = resolveThemeBrand(input.config.brand, { scope: scopeClass });
+  const brandResult = resolveThemeBrand(input.config.brand, { scope: scopeClass, colorScheme });
   const passthroughCss = generateBrandPassthroughCss(
     collectBrandPassthrough(input.tokens, input.config.overrides),
     {
-      light: `html:not(.dark) ${scopeClass}`,
-      dark: `.dark ${scopeClass}`,
+      light: lightSel,
+      dark: darkSel,
       prefers: `${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`
-    }
+    },
+    colorScheme
   );
   const adaptiveLayer = wrapInLayer("visor-adaptive", lines.join("\n").trim());
   const semanticLayer = wrapInLayer("visor-semantic", semanticLines.join("\n").trim());

package/dist/{chunk-DQ256PSE.js → chunk-BUWBBUFG.js}

@@ -829,7 +829,7 @@ function block(selector, decls) {
   if (decls.length === 0) return "";
   return [`${selector} {`, ...decls.map((d) => `  ${d}`), "}"].join("\n");
 }
-function generateBrandCSS(resolutions, scope) {
+function generateBrandCSS(resolutions, scope, colorScheme = "adaptive") {
   if (resolutions.length === 0) return "";
   const baseSelector = scope ? scope : ":root";
   const lightSelector = scope ? `html:not(.dark) ${scope}` : ":root";
@@ -840,6 +840,18 @@ function generateBrandCSS(resolutions, scope) {
   lines.push("/* --- Brand: forced-mode aliases + tokens --- */");
   lines.push(block(baseSelector, staticDecls));
   lines.push("");
+  if (colorScheme === "dark-only") {
+    const darkDecls2 = resolutions.map((r) => modeDecl(r, "dark"));
+    lines.push("/* --- Brand: variants (dark) \u2014 host --- */");
+    lines.push(block(baseSelector, darkDecls2));
+    return lines.join("\n").trim();
+  }
+  if (colorScheme === "light-only") {
+    const lightDecls2 = resolutions.map((r) => modeDecl(r, "light"));
+    lines.push("/* --- Brand: variants (light) \u2014 host --- */");
+    lines.push(block(baseSelector, lightDecls2));
+    return lines.join("\n").trim();
+  }
   const lightDecls = resolutions.map((r) => modeDecl(r, "light"));
   lines.push("/* --- Brand: variants (light) --- */");
   lines.push(block(lightSelector, lightDecls));
@@ -860,6 +872,7 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 function resolveThemeBrand(brand, options) {
   const effective = brand ?? DEFAULT_VISOR_BRAND;
   const scope = options?.scope ?? "";
+  const colorScheme = options?.colorScheme ?? "adaptive";
   const source = resolveBrandSource(effective);
   const org = effective.org ?? null;
   const cdnBase = effective["cdn-overrides"]?.["visor-brands"] ?? null;
@@ -881,7 +894,7 @@ function resolveThemeBrand(brand, options) {
       if (resolution.guidance) warnings.push(resolution.guidance);
     }
   }
-  const css = generateBrandCSS([...variants, ...custom], scope);
+  const css = generateBrandCSS([...variants, ...custom], scope, colorScheme);
   return { variants, custom, css, warnings };
 }
 
@@ -1730,9 +1743,15 @@ function buildAdaptiveDecls(tokens, theme) {
   return { textDecls, surfaceDecls, borderDecls, interactiveDecls, intentDecls, hairlineDecls };
 }
 function generateLightCss(tokens, options) {
+  const colorScheme = options?.colorScheme ?? "adaptive";
+  if (colorScheme === "dark-only") return "";
   const lines = [];
   const { textDecls, surfaceDecls, borderDecls, interactiveDecls, intentDecls, hairlineDecls } = buildAdaptiveDecls(tokens, "light");
   const host = options?.scopePrefix ?? ":root";
+  if (colorScheme === "light-only") {
+    lines.push(sectionComment("Adaptive: color-scheme (light)"));
+    lines.push(block2(host, ["color-scheme: light;"]));
+  }
   lines.push(sectionComment("Adaptive: Text (light)"));
   lines.push(block2(host, textDecls));
   lines.push(sectionComment("Adaptive: Surface (light)"));
@@ -1748,8 +1767,28 @@ function generateLightCss(tokens, options) {
   return header("Visor Theme \u2014 Light") + lines.join("\n");
 }
 function generateDarkCss(tokens, options) {
+  const colorScheme = options?.colorScheme ?? "adaptive";
+  if (colorScheme === "light-only") return "";
   const lines = [];
   const { textDecls, surfaceDecls, borderDecls, interactiveDecls, intentDecls, hairlineDecls } = buildAdaptiveDecls(tokens, "dark");
+  if (colorScheme === "dark-only") {
+    const host = options?.scopePrefix ?? ":root";
+    lines.push(sectionComment("Adaptive: color-scheme (dark)"));
+    lines.push(block2(host, ["color-scheme: dark;"]));
+    lines.push(sectionComment("Adaptive: Text (dark) \u2014 host"));
+    lines.push(block2(host, textDecls));
+    lines.push(sectionComment("Adaptive: Surface (dark) \u2014 host"));
+    lines.push(block2(host, surfaceDecls));
+    lines.push(sectionComment("Adaptive: Border (dark) \u2014 host"));
+    lines.push(block2(host, borderDecls));
+    lines.push(sectionComment("Adaptive: Interactive (dark) \u2014 host"));
+    lines.push(block2(host, interactiveDecls));
+    lines.push(sectionComment("Adaptive: Intent aliases (dark) \u2014 host"));
+    lines.push(block2(host, intentDecls));
+    lines.push(sectionComment("Adaptive: Hairline aliases (dark) \u2014 host"));
+    lines.push(block2(host, hairlineDecls));
+    return header("Visor Theme \u2014 Dark") + lines.join("\n");
+  }
   const prefix = options?.scopePrefix;
   const darkSelectors = prefix ? [`${prefix}.dark`, `${prefix}.theme-dark`, `${prefix}[data-theme="dark"]`] : [".dark", ".theme-dark", '[data-theme="dark"]'];
   const darkSelector = darkSelectors.join(",\n");
@@ -1829,6 +1868,29 @@ function generateFullBundleCss(primitives, tokens, config) {
   );
   const primitivesBody = generatePrimitivesCss(primitives, config).split("\n").slice(6).join("\n");
   lines.push(primitivesBody);
+  const colorScheme = config["color-scheme"] ?? "adaptive";
+  if (colorScheme === "dark-only") {
+    lines.push(
+      "/* ============================================",
+      "   Tier 3: Adaptive \u2014 Dark Theme (:root host) + color-scheme: dark",
+      "   ============================================ */"
+    );
+    lines.push(
+      generateDarkCss(tokens, { colorScheme }).split("\n").slice(6).join("\n")
+    );
+    return lines.join("\n");
+  }
+  if (colorScheme === "light-only") {
+    lines.push(
+      "/* ============================================",
+      "   Tier 3: Adaptive \u2014 Light Theme (:root host) + color-scheme: light",
+      "   ============================================ */"
+    );
+    lines.push(
+      generateLightCss(tokens, { colorScheme }).split("\n").slice(6).join("\n")
+    );
+    return lines.join("\n");
+  }
   lines.push(
     "/* ============================================",
     "   Tier 3: Adaptive \u2014 Light Theme (:root)",

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, g as BrandStrategy, h as BrandStrategyContext, i as BrandStrategyIssue, j as BrandStrategyValidationResult, S as SerializedBrandStrategy, R as ResolvedThemeConfig, k as GeneratedPrimitives, l as ThemeOutput, m as ThemeData, n as VisorThemeConfig, o as FullShadeScale, C as ColorRole, p as SelectiveShadeScale, q as RGB, P as ParsedColor, O as OKLCH, r as SemanticTokens, s as ShadeStep } from './types-DqsWwFVZ.js';
-export { t as BRAND_VARIANTS, u as BRAND_VISIBILITIES, v as BrandAccessibility, w as BrandArchetype, x as BrandBoilerplate, y as BrandColorPairing, z as BrandColorUsage, A as BrandContrastTarget, D as BrandGoverns, E as BrandLexiconEntry, H as BrandMessaging, I as BrandPersonalityTrait, J as BrandPillar, K as BrandPositioning, L as BrandStrategyIssueSeverity, M as BrandToneEntry, N as BrandVariant, Q as BrandVisibility, U as BrandVoice, W as BrandVoiceTrait, X as ColorFormat, Y as DEFAULT_BRAND_STRATEGY_SURFACES, Z as DEFAULT_BRAND_STRATEGY_TONE_STATES, _ as FontSource, $ as GOVERNS_WILDCARD, a0 as RGBA, a1 as SemanticTokenValue } from './types-DqsWwFVZ.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, C as ColorScheme, f as ThemeBrandResult, g as BrandStrategy, h as BrandStrategyContext, i as BrandStrategyIssue, j as BrandStrategyValidationResult, S as SerializedBrandStrategy, R as ResolvedThemeConfig, k as GeneratedPrimitives, l as ThemeOutput, m as ThemeData, n as VisorThemeConfig, o as FullShadeScale, p as ColorRole, q as SelectiveShadeScale, r as RGB, P as ParsedColor, O as OKLCH, s as SemanticTokens, t as ShadeStep } from './types-Cvm7vFwe.js';
+export { u as BRAND_VARIANTS, v as BRAND_VISIBILITIES, w as BrandAccessibility, x as BrandArchetype, y as BrandBoilerplate, z as BrandColorPairing, A as BrandColorUsage, D as BrandContrastTarget, E as BrandGoverns, H as BrandLexiconEntry, I as BrandMessaging, J as BrandPersonalityTrait, K as BrandPillar, L as BrandPositioning, M as BrandStrategyIssueSeverity, N as BrandToneEntry, Q as BrandVariant, U as BrandVisibility, W as BrandVoice, X as BrandVoiceTrait, Y as ColorFormat, Z as DEFAULT_BRAND_STRATEGY_SURFACES, _ as DEFAULT_BRAND_STRATEGY_TONE_STATES, $ as FontSource, a0 as GOVERNS_WILDCARD, a1 as RGBA, a2 as SemanticTokenValue } from './types-Cvm7vFwe.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -234,6 +234,7 @@ declare function resolveBrandSource(brand: VisorBrand): BrandSource;
  */
 declare function resolveThemeBrand(brand: VisorBrand | undefined, options?: {
     scope?: string;
+    colorScheme?: ColorScheme;
 }): ThemeBrandResult;
 
 /**
@@ -390,6 +391,15 @@ var properties = {
 		],
 		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."
 	},
+	"color-scheme": {
+		type: "string",
+		"enum": [
+			"dark-only",
+			"light-only",
+			"adaptive"
+		],
+		description: "Brand constraint declaring which color modes the theme supports. 'dark-only'/'light-only' lock the brand to a single mode; 'adaptive' supports both. Complements 'default-mode' (the runtime default) — 'color-scheme' is authoritative for the brand-lock. Defaults to 'adaptive' when omitted. Optional."
+	},
 	colors: {
 		type: "object",
 		description: "Color definitions for light mode. Only primary is required — all others have sensible defaults.",
@@ -1588,6 +1598,7 @@ 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 getLuminance(r: number, g: number, b: number): number;
 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;
@@ -1764,9 +1775,11 @@ declare function generatePrimitivesCss(primitives: GeneratedPrimitives, config:
 declare function generateSemanticCss(tokens: SemanticTokens): string;
 declare function generateLightCss(tokens: SemanticTokens, options?: {
     scopePrefix?: string;
+    colorScheme?: ColorScheme;
 }): string;
 declare function generateDarkCss(tokens: SemanticTokens, options?: {
     scopePrefix?: string;
+    colorScheme?: ColorScheme;
 }): string;
 declare function generateFullBundleCss(primitives: GeneratedPrimitives, tokens: SemanticTokens, config: ResolvedThemeConfig): string;
 
@@ -1845,4 +1858,4 @@ declare function cleanFontValue(val: string): string;
  */
 declare function extractFromCSS(files: CSSFile[], name?: string): ExtractionResult;
 
-export { type BrandPassthrough, BrandResolution, BrandSlot, BrandSource, BrandStrategy, BrandStrategyContext, BrandStrategyIssue, BrandStrategyValidationResult, 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, SerializedBrandStrategy, 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, checkBrandStrategyCoherence, checkBrandStrategyStructure, clampToSrgb, cleanFontValue, collectBrandPassthrough, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, getKnownTokenRefs, 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, serializeBrandStrategy, serializeColor, validate, validateBrandStrategy, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };
+export { type BrandPassthrough, BrandResolution, BrandSlot, BrandSource, BrandStrategy, BrandStrategyContext, BrandStrategyIssue, BrandStrategyValidationResult, 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, SerializedBrandStrategy, 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, checkBrandStrategyCoherence, checkBrandStrategyStructure, clampToSrgb, cleanFontValue, collectBrandPassthrough, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, getKnownTokenRefs, getLuminance, 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, serializeBrandStrategy, serializeColor, validate, validateBrandStrategy, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };

package/dist/index.js

@@ -46,7 +46,7 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-DQ256PSE.js";
+} from "./chunk-BUWBBUFG.js";
 
 // src/fonts/validate-coverage.ts
 var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
@@ -628,6 +628,11 @@ var visor_theme_schema_default = {
       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."
     },
+    "color-scheme": {
+      type: "string",
+      enum: ["dark-only", "light-only", "adaptive"],
+      description: "Brand constraint declaring which color modes the theme supports. 'dark-only'/'light-only' lock the brand to a single mode; 'adaptive' supports both. Complements 'default-mode' (the runtime default) \u2014 'color-scheme' is authoritative for the brand-lock. Defaults to 'adaptive' when omitted. Optional."
+    },
     colors: {
       type: "object",
       description: "Color definitions for light mode. Only primary is required \u2014 all others have sensible defaults.",
@@ -1294,6 +1299,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "group",
   "label",
   "default-mode",
+  "color-scheme",
   "colors",
   "colors-dark",
   "typography",
@@ -1574,6 +1580,12 @@ function validateConfig(config) {
       errors.push("'default-mode' must be either 'dark' or 'light'");
     }
   }
+  if (obj["color-scheme"] !== void 0) {
+    const scheme = obj["color-scheme"];
+    if (scheme !== "dark-only" && scheme !== "light-only" && scheme !== "adaptive") {
+      errors.push("'color-scheme' must be one of: dark-only, light-only, adaptive");
+    }
+  }
   if (typeof obj.colors !== "object" || obj.colors === null) {
     errors.push("'colors' is required and must be an object");
     return { valid: false, errors };
@@ -1863,6 +1875,9 @@ function resolveConfig(config) {
     name: config.name,
     ...config.label !== void 0 && { label: config.label },
     ...config["default-mode"] !== void 0 && { "default-mode": config["default-mode"] },
+    // BO-55: always-resolved brand constraint — existing themes (no field) resolve
+    // to 'adaptive', preserving back-compat.
+    "color-scheme": config["color-scheme"] ?? "adaptive",
     version: 1,
     colors: {
       primary: colors.primary,
@@ -2555,8 +2570,8 @@ ${validation.errors.map((e) => `  - ${e}`).join("\n")}`
   const output = {
     primitivesCss: generatePrimitivesCss(primitives, resolved),
     semanticCss: generateSemanticCss(tokens),
-    lightCss: generateLightCss(tokens),
-    darkCss: generateDarkCss(tokens),
+    lightCss: generateLightCss(tokens, { colorScheme: resolved["color-scheme"] }),
+    darkCss: generateDarkCss(tokens, { colorScheme: resolved["color-scheme"] }),
     fullBundleCss: generateFullBundleCss(primitives, tokens, resolved)
   };
   return { config: resolved, primitives, tokens, output };
@@ -3903,6 +3918,36 @@ function extractBackgroundSurface(declarations) {
   }
   return result;
 }
+function detectExplicitColorScheme(files) {
+  for (const file of files) {
+    const content = file.content.replace(/\/\*[\s\S]*?\*\//g, "");
+    const re = /(?<![\w-])color-scheme\s*:\s*([^;}]+)/gi;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      const keywords = m[1].trim().toLowerCase().split(/\s+/).filter((k) => k.length > 0 && k !== "only");
+      const hasDark = keywords.includes("dark");
+      const hasLight = keywords.includes("light");
+      if (hasDark && hasLight) return "adaptive";
+      if (hasDark) return "dark-only";
+      if (hasLight) return "light-only";
+      if (keywords.includes("normal")) return "adaptive";
+    }
+  }
+  return null;
+}
+function detectColorScheme(files, bgSurface, warnings) {
+  const explicit = detectExplicitColorScheme(files);
+  const heuristic = bgSurface.dark.background && !bgSurface.light.background ? "dark-only" : "adaptive";
+  if (explicit) {
+    if (heuristic !== "adaptive" && heuristic !== explicit) {
+      warnings.push(
+        `color-scheme ambiguity: source CSS explicitly declares 'color-scheme: ${explicit}' but the background heuristic suggests '${heuristic}'. Using the explicit declaration \u2014 review the source if this is unexpected.`
+      );
+    }
+    return explicit;
+  }
+  return heuristic;
+}
 function extractFromCSS(files, name = "extracted-theme") {
   const warnings = [];
   const allDeclarations = [];
@@ -3976,6 +4021,7 @@ function extractFromCSS(files, name = "extracted-theme") {
   if (Object.keys(darkColors).length > 0) {
     config["colors-dark"] = darkColors;
   }
+  config["color-scheme"] = detectColorScheme(files, bgSurface, warnings);
   if (typography.heading || typography.display || typography.body || typography.mono) {
     config.typography = {};
     if (typography.heading) config.typography.heading = typography.heading;
@@ -4046,6 +4092,7 @@ export {
   generateThemeFromConfig,
   getContrastRatio,
   getKnownTokenRefs,
+  getLuminance,
   googleFontsCatalog,
   hasBrandPassthrough,
   hexToOklch,

package/dist/{types-DqsWwFVZ.d.ts → types-Cvm7vFwe.d.ts}

@@ -483,6 +483,11 @@ interface TextSlotOverride {
     /** Letter spacing in logical pixels (Flutter `TextStyle.letterSpacing`). */
     "letter-spacing"?: number;
 }
+/**
+ * BO-55/BO-56: brand color-mode constraint. `dark-only`/`light-only` lock the
+ * brand to a single mode; `adaptive` supports both (the historical default).
+ */
+type ColorScheme = "dark-only" | "light-only" | "adaptive";
 interface VisorThemeConfig {
     name: string;
     version: 1;
@@ -492,6 +497,13 @@ interface VisorThemeConfig {
     label?: string;
     /** Default color mode to force when the theme is activated ('dark' or 'light'). If unset, user/system preference applies. */
     "default-mode"?: "dark" | "light";
+    /**
+     * BO-55: Brand constraint declaring which color modes the theme supports.
+     * 'dark-only'/'light-only' lock the brand to a single mode; 'adaptive' supports both.
+     * Complements `default-mode` (the runtime default) — `color-scheme` is authoritative
+     * for the brand-lock. Defaults to 'adaptive' when omitted.
+     */
+    "color-scheme"?: ColorScheme;
     colors: {
         primary: string;
         accent?: string;
@@ -674,6 +686,12 @@ interface ResolvedThemeConfig {
     label?: string;
     /** Default color mode forwarded from VisorThemeConfig["default-mode"]. */
     "default-mode"?: "dark" | "light";
+    /**
+     * BO-55: Brand constraint for supported color modes. Always resolved (defaults
+     * to 'adaptive' when the theme omits it) so downstream readers (engine/extractor/gate)
+     * get a guaranteed value.
+     */
+    "color-scheme": ColorScheme;
     version: 1;
     colors: {
         primary: string;
@@ -836,4 +854,4 @@ interface ThemeData {
     output: ThemeOutput;
 }
 
-export { GOVERNS_WILDCARD as $, type BrandContrastTarget as A, type BrandSlot as B, type ColorRole as C, type BrandGoverns as D, type BrandLexiconEntry as E, type FontResolveOptions as F, type GoogleFontEntry as G, type BrandMessaging as H, type BrandPersonalityTrait as I, type BrandPillar as J, type BrandPositioning as K, type BrandStrategyIssueSeverity as L, type BrandToneEntry as M, type BrandVariant as N, type OKLCH as O, type ParsedColor as P, type BrandVisibility as Q, type ResolvedThemeConfig as R, type SerializedBrandStrategy as S, type ThemeFontResult as T, type BrandVoice as U, type VisorTypography as V, type BrandVoiceTrait as W, type ColorFormat as X, DEFAULT_BRAND_STRATEGY_SURFACES as Y, DEFAULT_BRAND_STRATEGY_TONE_STATES as Z, type FontSource as _, type FontResolution as a, type RGBA as a0, type SemanticTokenValue as a1, type FontDisplayStrategy as b, type VisorBrand as c, type BrandSource as d, type BrandResolution as e, type ThemeBrandResult as f, type BrandStrategy as g, type BrandStrategyContext as h, type BrandStrategyIssue as i, type BrandStrategyValidationResult as j, type GeneratedPrimitives as k, type ThemeOutput as l, type ThemeData as m, type VisorThemeConfig as n, type FullShadeScale as o, type SelectiveShadeScale as p, type RGB as q, type SemanticTokens as r, type ShadeStep as s, BRAND_VARIANTS as t, BRAND_VISIBILITIES as u, type BrandAccessibility as v, type BrandArchetype as w, type BrandBoilerplate as x, type BrandColorPairing as y, type BrandColorUsage as z };
+export { type FontSource as $, type BrandColorUsage as A, type BrandSlot as B, type ColorScheme as C, type BrandContrastTarget as D, type BrandGoverns as E, type FontResolveOptions as F, type GoogleFontEntry as G, type BrandLexiconEntry as H, type BrandMessaging as I, type BrandPersonalityTrait as J, type BrandPillar as K, type BrandPositioning as L, type BrandStrategyIssueSeverity as M, type BrandToneEntry as N, type OKLCH as O, type ParsedColor as P, type BrandVariant as Q, type ResolvedThemeConfig as R, type SerializedBrandStrategy as S, type ThemeFontResult as T, type BrandVisibility as U, type VisorTypography as V, type BrandVoice as W, type BrandVoiceTrait as X, type ColorFormat as Y, DEFAULT_BRAND_STRATEGY_SURFACES as Z, DEFAULT_BRAND_STRATEGY_TONE_STATES as _, type FontResolution as a, GOVERNS_WILDCARD as a0, type RGBA as a1, type SemanticTokenValue as a2, type FontDisplayStrategy as b, type VisorBrand as c, type BrandSource as d, type BrandResolution as e, type ThemeBrandResult as f, type BrandStrategy as g, type BrandStrategyContext as h, type BrandStrategyIssue as i, type BrandStrategyValidationResult as j, type GeneratedPrimitives as k, type ThemeOutput as l, type ThemeData as m, type VisorThemeConfig as n, type FullShadeScale as o, type ColorRole as p, type SelectiveShadeScale as q, type RGB as r, type SemanticTokens as s, type ShadeStep as t, BRAND_VARIANTS as u, BRAND_VISIBILITIES as v, type BrandAccessibility as w, type BrandArchetype as x, type BrandBoilerplate as y, type BrandColorPairing as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor-theme-engine",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "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

@@ -29,6 +29,11 @@
       "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."
     },
+    "color-scheme": {
+      "type": "string",
+      "enum": ["dark-only", "light-only", "adaptive"],
+      "description": "Brand constraint declaring which color modes the theme supports. 'dark-only'/'light-only' lock the brand to a single mode; 'adaptive' supports both. Complements 'default-mode' (the runtime default) — 'color-scheme' is authoritative for the brand-lock. Defaults to 'adaptive' when omitted. Optional."
+    },
     "colors": {
       "type": "object",
       "description": "Color definitions for light mode. Only primary is required — all others have sensible defaults.",