@loworbitstudio/visor-theme-engine 0.5.0 → 0.8.0

package/README.md

@@ -24,6 +24,46 @@ Themes are typically managed via the Visor CLI (`visor theme sync`). Direct API
 import { generateTheme } from '@loworbitstudio/visor-theme-engine'
 ```
 
+## Migration
+
+### Themes pinned to `^0.4.x` with a custom mono font
+
+Engine 0.5 expanded `typography.mono` to accept `weight | weights | source | org` (previously only `family`). Engine 0.6 added `validate-coverage`, which errors when any `--font-*` declaration names a family with no matching `@font-face`. The combination created a trap: themes pinned to `^0.4.x` could only write `mono: { family: X }` (the only thing 0.4 allowed) and could not express the source/org fix the 0.6 error message points to.
+
+To migrate:
+
+1. **Bump both** `@loworbitstudio/visor` (the CLI) to `≥ 0.10` and `@loworbitstudio/visor-theme-engine` to `≥ 0.6` together. The CLI transitively pins its own engine copy (CLI 0.10 → engine `^0.6.0`), so `visor theme sync` runs against the CLI-bundled engine, not the hoisted one — bumping the engine alone is silently insufficient.
+
+2. **Decide between inheritance and explicit declaration:**
+
+   - **Inheritance (preferred when applicable).** If your mono slot's family matches another slot (heading, display, or body) with `source`/`org` set, leave `typography.mono.source` and `typography.mono.org` unset. The engine will inherit `source`/`org` from the matching slot. Match precedence: heading → display → body, case-insensitive.
+
+     ```yaml
+     typography:
+       body:
+         family: PP Model Mono
+         weight: 400
+         source: visor-fonts
+         org: low-orbit-studio
+       mono:
+         family: PP Model Mono
+         weight: 400
+         # source/org inherited from body
+     ```
+
+   - **Explicit declaration.** Otherwise, add `source` (and `org` for `visor-fonts`) directly:
+
+     ```yaml
+     typography:
+       mono:
+         family: PP Model Mono
+         weight: 400
+         source: visor-fonts        # or google-fonts, fontshare, local
+         org: low-orbit-studio      # required for visor-fonts only
+     ```
+
+System mono fonts (`SF Mono`, `JetBrains Mono`, `Source Code Pro`, `Menlo`, etc.) are already on the validator's `SYSTEM_FONTS` list and never need `source`/`org`.
+
 ## Documentation
 
 Full docs at [visor.loworbit.studio](https://visor.loworbit.studio).

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { c as GeneratedPrimitives, i as SemanticTokens, R as ResolvedThemeConfig } from '../types-ljcTtODU.js';
+import { c as GeneratedPrimitives, i as SemanticTokens, R as ResolvedThemeConfig } from '../types-CV0nmvMz.js';
 
 /**
  * Adapter types for the Visor theme engine.
@@ -22,6 +22,16 @@ interface AdapterOptions {
 interface NextJSAdapterOptions extends AdapterOptions {
     /** Include Google Fonts @import statements (default: true) */
     includeFontImports?: boolean;
+    /**
+     * Optional CSS selector that replaces `:root` in the generated output,
+     * enabling the body-class repaint pattern (e.g. `body.blacklight-theme`).
+     * When set, the dark-mode block scopes to `<scopePrefix>.dark`,
+     * `<scopePrefix>.theme-dark`, and `<scopePrefix>[data-theme="dark"]`;
+     * the `prefers-color-scheme: dark` media query composes the prefix with
+     * the existing `:not(.light)` guards. When omitted, output is unchanged
+     * (`:root`) for backward compatibility. See VI-368.
+     */
+    scopePrefix?: string;
 }
 /** Options specific to the Deck adapter. */
 interface DeckAdapterOptions extends AdapterOptions {

package/dist/adapters/index.js

@@ -2,7 +2,9 @@ import {
   FULL_SHADE_STEPS,
   MATERIAL_TEXT_SLOTS,
   SELECTIVE_SHADE_STEPS,
+  aliasFamily,
   buildVisorFontUrl,
+  fontStack,
   generateDarkCss,
   generateLightCss,
   generatePrimitivesCss,
@@ -11,7 +13,7 @@ import {
   parseColor,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-U5FXQ5EC.js";
+} from "../chunk-2O2DPCMJ.js";
 
 // src/adapters/layers.ts
 var LAYER_ORDER = "@layer visor-primitives, visor-semantic, visor-adaptive, visor-bridge;";
@@ -24,18 +26,30 @@ ${trimmed}
 }
 
 // src/adapters/nextjs.ts
+function toKebabCase(name) {
+  return name.toLowerCase().replace(/\s+/g, "-");
+}
 function nextjsAdapter(input, options) {
   const includeFontImports = options?.includeFontImports ?? true;
   const includeFowt = options?.includeFowt ?? true;
+  const scopePrefix = options?.scopePrefix;
   const lines = [];
+  const slug = toKebabCase(input.config.name);
+  const aliasedFamilies = /* @__PURE__ */ new Map();
   lines.push(header("Visor Theme \u2014 NextJS Adapter"));
   if (includeFontImports && input.config.typography) {
     const fontResult = resolveThemeFonts(input.config.typography);
-    const googleFonts = [fontResult.heading, fontResult.display, fontResult.body, fontResult.mono].filter(
-      (r) => r !== null && r.source === "google-fonts"
+    const fontSlots = [fontResult.heading, fontResult.display, fontResult.body, fontResult.mono];
+    for (const font of fontSlots) {
+      if (font && font.source === "visor-fonts" && !aliasedFamilies.has(font.family)) {
+        aliasedFamilies.set(font.family, aliasFamily(font.family, slug));
+      }
+    }
+    const hostedCssFonts = [fontResult.heading, fontResult.display, fontResult.body, fontResult.mono].filter(
+      (r) => r !== null && (r.source === "google-fonts" || r.source === "fontshare")
     );
     const seenUrls = /* @__PURE__ */ new Set();
-    for (const font of googleFonts) {
+    for (const font of hostedCssFonts) {
       if (font?.cssUrl && !seenUrls.has(font.cssUrl)) {
         seenUrls.add(font.cssUrl);
         lines.push(`@import url("${font.cssUrl}");`);
@@ -59,10 +73,11 @@ function nextjsAdapter(input, options) {
     for (const font of visorFonts) {
       if (seenVisorFamilies.has(font.family)) continue;
       seenVisorFamilies.add(font.family);
+      const aliased = aliasedFamilies.get(font.family);
       for (const weight of font.weights) {
         const url = buildVisorFontUrl(font.org ?? "", font.family, weight);
         lines.push(`@font-face {`);
-        lines.push(`  font-family: "${font.family}";`);
+        lines.push(`  font-family: "${aliased}";`);
         lines.push(`  src: url("${url}") format("woff2");`);
         lines.push(`  font-weight: ${weight};`);
         lines.push(`  font-style: ${font.italic ? "italic" : "normal"};`);
@@ -75,12 +90,15 @@ function nextjsAdapter(input, options) {
   lines.push(LAYER_ORDER);
   lines.push("");
   const primitivesBody = stripHeader(
-    generatePrimitivesCss(input.primitives, input.config)
+    generatePrimitivesCss(input.primitives, input.config, {
+      aliasedFamilies,
+      scopePrefix
+    })
   );
   lines.push(wrapInLayer("visor-primitives", primitivesBody));
   lines.push("");
-  const lightBody = stripHeader(generateLightCss(input.tokens));
-  const darkBody = stripHeader(generateDarkCss(input.tokens));
+  const lightBody = stripHeader(generateLightCss(input.tokens, { scopePrefix }));
+  const darkBody = stripHeader(generateDarkCss(input.tokens, { scopePrefix }));
   lines.push(
     wrapInLayer("visor-adaptive", lightBody + "\n\n" + darkBody)
   );
@@ -174,7 +192,7 @@ var SELECTIVE_SCALE_ROLES = [
   "error",
   "info"
 ];
-function toKebabCase(name) {
+function toKebabCase2(name) {
   return name.toLowerCase().replace(/\s+/g, "-");
 }
 function generateScopedPrimitives(primitives, config) {
@@ -226,7 +244,7 @@ function generateSemanticDecls(tokens, mode) {
   return decls;
 }
 function deckAdapter(input, options) {
-  const scopeClass = options?.scopeClass ?? `.deck--${toKebabCase(input.config.name)}`;
+  const scopeClass = options?.scopeClass ?? `.deck--${toKebabCase2(input.config.name)}`;
   const lines = [];
   lines.push(header(`Visor Theme \u2014 Deck Adapter (${scopeClass})`));
   const primDecls = generateScopedPrimitives(input.primitives, input.config);
@@ -260,7 +278,7 @@ function deckAdapter(input, options) {
 // src/adapters/docs.ts
 var FULL_SCALE_ROLES2 = ["primary", "accent", "neutral"];
 var SELECTIVE_SCALE_ROLES2 = ["success", "warning", "error", "info"];
-function toKebabCase2(name) {
+function toKebabCase3(name) {
   return name.toLowerCase().replace(/\s+/g, "-");
 }
 function generateColorDecls(primitives) {
@@ -298,13 +316,14 @@ function generateRadiusDecls(config) {
     `--radius-full: ${config.radius.pill}px;`
   ];
 }
-function generateTypographyDecls(config) {
+function generateTypographyDecls(config, aliases) {
   const decls = [];
-  decls.push(`--font-display: ${config.typography.display.family};`);
-  decls.push(`--font-sans: ${config.typography.body.family};`);
-  decls.push(`--font-heading: var(--font-sans);`);
-  decls.push(`--font-body: ${config.typography.body.family};`);
-  decls.push(`--font-mono: ${config.typography.mono.family};`);
+  const headingFamily = config.typography.heading?.family ?? config.typography.body.family;
+  decls.push(`--font-display: ${fontStack(config.typography.display.family, aliases)};`);
+  decls.push(`--font-sans: ${fontStack(config.typography.body.family, aliases)};`);
+  decls.push(`--font-heading: ${fontStack(headingFamily, aliases)};`);
+  decls.push(`--font-body: ${fontStack(config.typography.body.family, aliases)};`);
+  decls.push(`--font-mono: ${fontStack(config.typography.mono.family, aliases)};`);
   const fontSizes = {
     xs: 12,
     sm: 14,
@@ -415,31 +434,38 @@ function sectionComment2(label) {
 /* --- ${label} --- */`;
 }
 function docsAdapter(input, options) {
-  const slug = toKebabCase2(input.config.name);
+  const slug = toKebabCase3(input.config.name);
   const scopeClass = `.${slug}-theme`;
   const includeFontImports = options?.includeFontImports ?? true;
   const fontLines = [];
   const lines = [];
+  const aliasedFamilies = /* @__PURE__ */ new Map();
   if (includeFontImports && input.config.typography) {
     const fontResult = resolveThemeFonts(input.config.typography);
     const fontSlots = [fontResult.heading, fontResult.display, fontResult.body, fontResult.mono];
+    for (const font of fontSlots) {
+      if (font && font.source === "visor-fonts" && !aliasedFamilies.has(font.family)) {
+        aliasedFamilies.set(font.family, aliasFamily(font.family, slug));
+      }
+    }
     const seenUrls = /* @__PURE__ */ new Set();
     for (const font of fontSlots) {
-      if (font && font.source === "google-fonts" && font.cssUrl && !seenUrls.has(font.cssUrl)) {
+      if (font && (font.source === "google-fonts" || font.source === "fontshare") && font.cssUrl && !seenUrls.has(font.cssUrl)) {
         seenUrls.add(font.cssUrl);
         fontLines.push(`@import url("${font.cssUrl}");`);
         fontLines.push("");
       }
     }
     const scale = input.config.typography?.scale ?? 1;
-    const seenFamilies = /* @__PURE__ */ new Set();
+    const emittedFamilies = /* @__PURE__ */ new Set();
     for (const font of fontSlots) {
-      if (font && font.source === "visor-fonts" && !seenFamilies.has(font.family)) {
-        seenFamilies.add(font.family);
+      if (font && font.source === "visor-fonts" && !emittedFamilies.has(font.family)) {
+        emittedFamilies.add(font.family);
+        const aliased = aliasedFamilies.get(font.family);
         for (const weight of font.weights) {
           const url = buildVisorFontUrl(font.org ?? "", font.family, weight);
           fontLines.push("@font-face {");
-          fontLines.push(`  font-family: "${font.family}";`);
+          fontLines.push(`  font-family: "${aliased}";`);
           fontLines.push(`  src: url("${url}") format("woff2");`);
           fontLines.push(`  font-weight: ${weight};`);
           fontLines.push(`  font-style: ${font.italic ? "italic" : "normal"};`);
@@ -475,7 +501,7 @@ function docsAdapter(input, options) {
   lines.push(block(scopeClass, generateRadiusDecls(input.config)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Typography"));
-  lines.push(block(scopeClass, generateTypographyDecls(input.config)));
+  lines.push(block(scopeClass, generateTypographyDecls(input.config, aliasedFamilies)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Shadows"));
   lines.push(block(scopeClass, generateShadowDecls(input.config)));

package/dist/{chunk-U5FXQ5EC.js → chunk-2O2DPCMJ.js}

@@ -122,6 +122,10 @@ var FONT_WEIGHT_ALIASES = {
     400: "Book",
     800: "Super"
   },
+  "PP Model Sans": {
+    400: "Book",
+    800: "Super"
+  },
   "PP Model Plastic": {
     400: "Book",
     800: "Super"
@@ -151,6 +155,8 @@ function buildGoogleFontsCssUrl(family, weights, italic, display) {
   return `https://fonts.googleapis.com/css2?family=${encodedFamily}:wght@${wghtValues}&display=${display}`;
 }
 var VISOR_FONTS_CDN = "https://fonts.visor.design";
+var FONTSHARE_API_ORIGIN = "https://api.fontshare.com";
+var FONTSHARE_CDN_ORIGIN = "https://cdn.fontshare.com";
 function buildFamilySlug(family) {
   return family.toLowerCase().replace(/ /g, "-");
 }
@@ -174,6 +180,16 @@ function buildVisorFontUrl(org, family, weight) {
   const weightName = lookupFontWeightAlias(family, weight) ?? WEIGHT_NAMES[weight] ?? `W${weight}`;
   return `${VISOR_FONTS_CDN}/${org}/${slug}/${prefix}-${weightName}.woff2`;
 }
+function buildFontshareCssUrl(family, weights, italic, display) {
+  const slug = buildFamilySlug(family);
+  const sortedWeights = [...weights].sort((a, b) => a - b);
+  const tokens = [];
+  if (italic) {
+    for (const w of sortedWeights) tokens.push(`${w}i`);
+  }
+  for (const w of sortedWeights) tokens.push(`${w}`);
+  return `${FONTSHARE_API_ORIGIN}/v2/css?f[]=${slug}@${tokens.join(",")}&display=${display}`;
+}
 function resolveFont(family, options = {}) {
   const display = options.display ?? DEFAULT_DISPLAY;
   const requestedWeights = options.weights ?? DEFAULT_WEIGHTS;
@@ -192,6 +208,20 @@ function resolveFont(family, options = {}) {
       org: options.org ?? null
     };
   }
+  if (explicitSource === "fontshare") {
+    const cssUrl = buildFontshareCssUrl(family, requestedWeights, italic, display);
+    return {
+      family,
+      source: "fontshare",
+      cssUrl,
+      weights: requestedWeights,
+      italic,
+      display,
+      category: options.category ?? "sans-serif",
+      guidance: null,
+      org: null
+    };
+  }
   if (explicitSource === "local") {
     return {
       family,
@@ -288,6 +318,20 @@ function generatePreloadLinks(resolutions, customFontPaths) {
       }
     }
   }
+  const hasFontshare = resolutions.some((r) => r.source === "fontshare");
+  if (hasFontshare) {
+    links.push(`<link rel="preconnect" href="${FONTSHARE_API_ORIGIN}">`);
+    links.push(
+      `<link rel="preconnect" href="${FONTSHARE_CDN_ORIGIN}" crossorigin>`
+    );
+    for (const resolution of resolutions) {
+      if (resolution.source === "fontshare" && resolution.cssUrl) {
+        links.push(
+          `<link rel="preload" as="style" href="${resolution.cssUrl}">`
+        );
+      }
+    }
+  }
   if (customFontPaths) {
     for (const resolution of resolutions) {
       if (resolution.source === "local") {
@@ -307,7 +351,7 @@ function generatePreloadLinks(resolutions, customFontPaths) {
 function generateStylesheetLinks(resolutions) {
   const links = [];
   for (const resolution of resolutions) {
-    if (resolution.source === "google-fonts" && resolution.cssUrl) {
+    if ((resolution.source === "google-fonts" || resolution.source === "fontshare") && resolution.cssUrl) {
       links.push(
         `<link rel="stylesheet" href="${resolution.cssUrl}">`
       );
@@ -330,6 +374,19 @@ function generateFontCSS(heading, displayFont, body, mono, typography) {
     }
     lines.push("");
   }
+  const fontshareFonts = allSlots.filter(
+    (r) => r !== null && r.source === "fontshare"
+  );
+  const seenFontshareUrls = /* @__PURE__ */ new Set();
+  if (fontshareFonts.length > 0) {
+    lines.push("/* Fontshare \u2014 load these stylesheets in your HTML <head> */");
+    for (const font of fontshareFonts) {
+      if (!font.cssUrl || seenFontshareUrls.has(font.cssUrl)) continue;
+      seenFontshareUrls.add(font.cssUrl);
+      lines.push(`/* ${font.cssUrl} */`);
+    }
+    lines.push("");
+  }
   const visorFonts = allSlots.filter(
     (r) => r !== null && r.source === "visor-fonts"
   );
@@ -570,13 +627,29 @@ function resolveThemeFonts(typography, options) {
   }
   let monoResolution = null;
   if (typography.mono?.family) {
-    const monoWeights = [];
-    if (typography.mono.weight) monoWeights.push(typography.mono.weight);
+    const monoWeights = typography.mono.weights ? [...typography.mono.weights] : typography.mono.weight ? [typography.mono.weight] : [];
+    let monoSource = typography.mono.source;
+    let monoOrg = typography.mono.org;
+    if (!monoSource) {
+      const monoFamilyLower = typography.mono.family.toLowerCase();
+      const candidates = [
+        { resolution: headingResolution, configSource: typography.heading?.source, configOrg: typography.heading?.org },
+        { resolution: displayResolution, configSource: typography.display?.source, configOrg: typography.display?.org },
+        { resolution: bodyResolution, configSource: typography.body?.source, configOrg: typography.body?.org }
+      ];
+      for (const candidate of candidates) {
+        if (candidate.resolution && candidate.configSource && candidate.resolution.family.toLowerCase() === monoFamilyLower) {
+          monoSource = candidate.configSource;
+          monoOrg = candidate.configOrg;
+          break;
+        }
+      }
+    }
     monoResolution = resolveFont(typography.mono.family, {
       weights: monoWeights.length > 0 ? monoWeights : void 0,
       display,
-      source: typography.mono.source,
-      org: typography.mono.org,
+      source: monoSource,
+      org: monoOrg,
       category: "monospace"
     });
     if (monoResolution.guidance) {
@@ -1069,6 +1142,17 @@ function generateShadeScale(color, role) {
   return scale;
 }
 
+// src/fonts/theme-alias.ts
+var EMPTY_ALIASES = /* @__PURE__ */ new Map();
+function aliasFamily(family, themeSlug) {
+  return `${family} [${themeSlug}]`;
+}
+function fontStack(bare, aliases) {
+  const aliased = aliases.get(bare);
+  if (!aliased) return bare;
+  return `"${aliased}", "${bare}"`;
+}
+
 // src/generate-css.ts
 function header(label) {
   return [
@@ -1154,15 +1238,15 @@ function generateShadowPrimitives(config) {
     `--shadow-xl: ${config.shadows.xl};`
   ];
 }
-function generateTypographyPrimitives(config) {
+function generateTypographyPrimitives(config, aliases = EMPTY_ALIASES) {
   const decls = [];
   const scale = config.typography.scale;
   decls.push(`font-size: ${scale === 1 ? "1rem" : `${scale}rem`};`);
-  decls.push(`--font-heading: ${config.typography.heading.family};`);
-  decls.push(`--font-display: ${config.typography.display.family};`);
-  decls.push(`--font-sans: ${config.typography.body.family};`);
-  decls.push(`--font-body: ${config.typography.body.family};`);
-  decls.push(`--font-mono: ${config.typography.mono.family};`);
+  decls.push(`--font-heading: ${fontStack(config.typography.heading.family, aliases)};`);
+  decls.push(`--font-display: ${fontStack(config.typography.display.family, aliases)};`);
+  decls.push(`--font-sans: ${fontStack(config.typography.body.family, aliases)};`);
+  decls.push(`--font-body: ${fontStack(config.typography.body.family, aliases)};`);
+  decls.push(`--font-mono: ${fontStack(config.typography.mono.family, aliases)};`);
   const fontSizes = {
     xs: 12,
     sm: 14,
@@ -1233,24 +1317,25 @@ function generateMiscPrimitives() {
     "--focus-ring-offset: 2px;"
   ];
 }
-function generatePrimitivesCss(primitives, config) {
+function generatePrimitivesCss(primitives, config, options) {
   const lines = [];
+  const host = options?.scopePrefix ?? ":root";
   lines.push(sectionComment("Primitive: Colors"));
   lines.push(
-    block(":root", [generateColorPrimitives(primitives)])
+    block(host, [generateColorPrimitives(primitives)])
   );
   lines.push(sectionComment("Primitive: Spacing"));
-  lines.push(block(":root", generateSpacingPrimitives(config)));
+  lines.push(block(host, generateSpacingPrimitives(config)));
   lines.push(sectionComment("Primitive: Border Radius"));
-  lines.push(block(":root", generateRadiusPrimitives(config)));
+  lines.push(block(host, generateRadiusPrimitives(config)));
   lines.push(sectionComment("Primitive: Typography"));
-  lines.push(block(":root", generateTypographyPrimitives(config)));
+  lines.push(block(host, generateTypographyPrimitives(config, options?.aliasedFamilies)));
   lines.push(sectionComment("Primitive: Shadows"));
-  lines.push(block(":root", generateShadowPrimitives(config)));
+  lines.push(block(host, generateShadowPrimitives(config)));
   lines.push(sectionComment("Primitive: Motion"));
-  lines.push(block(":root", generateMotionPrimitives(config)));
+  lines.push(block(host, generateMotionPrimitives(config)));
   lines.push(sectionComment("Primitive: Miscellaneous"));
-  lines.push(block(":root", generateMiscPrimitives()));
+  lines.push(block(host, generateMiscPrimitives()));
   return header("Visor Theme \u2014 Primitives") + lines.join("\n");
 }
 function generateSemanticCss(tokens) {
@@ -1292,25 +1377,27 @@ function buildAdaptiveDecls(tokens, theme) {
   );
   return { textDecls, surfaceDecls, borderDecls, interactiveDecls };
 }
-function generateLightCss(tokens) {
+function generateLightCss(tokens, options) {
   const lines = [];
   const { textDecls, surfaceDecls, borderDecls, interactiveDecls } = buildAdaptiveDecls(tokens, "light");
+  const host = options?.scopePrefix ?? ":root";
   lines.push(sectionComment("Adaptive: Text (light)"));
-  lines.push(block(":root", textDecls));
+  lines.push(block(host, textDecls));
   lines.push(sectionComment("Adaptive: Surface (light)"));
-  lines.push(block(":root", surfaceDecls));
+  lines.push(block(host, surfaceDecls));
   lines.push(sectionComment("Adaptive: Border (light)"));
-  lines.push(block(":root", borderDecls));
+  lines.push(block(host, borderDecls));
   lines.push(sectionComment("Adaptive: Interactive (light)"));
-  lines.push(block(":root", interactiveDecls));
+  lines.push(block(host, interactiveDecls));
   return header("Visor Theme \u2014 Light") + lines.join("\n");
 }
-function generateDarkCss(tokens) {
+function generateDarkCss(tokens, options) {
   const lines = [];
   const { textDecls, surfaceDecls, borderDecls, interactiveDecls } = buildAdaptiveDecls(tokens, "dark");
-  const darkSelectors = [".dark", ".theme-dark", '[data-theme="dark"]'];
+  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");
-  const prefersSelector = ':root:not(.light):not(.theme-light):not([data-theme="light"])';
+  const prefersSelector = prefix ? `${prefix}:not(.light):not(.theme-light):not([data-theme="light"])` : ':root:not(.light):not(.theme-light):not([data-theme="light"])';
   lines.push(sectionComment("Adaptive: Text (dark) \u2014 manual toggle"));
   lines.push(block(darkSelector, textDecls));
   lines.push(sectionComment("Adaptive: Surface (dark) \u2014 manual toggle"));
@@ -1437,6 +1524,8 @@ export {
   SELECTIVE_SHADE_STEPS,
   TAILWIND_GRAY,
   generateShadeScale,
+  aliasFamily,
+  fontStack,
   header,
   sectionComment,
   generatePrimitivesCss,

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, R as ResolvedThemeConfig, c as GeneratedPrimitives, d as ThemeOutput, e as ThemeData, f as VisorThemeConfig, g as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, h as RGB, P as ParsedColor, O as OKLCH, i as SemanticTokens, j as ShadeStep } from './types-ljcTtODU.js';
-export { k as ColorFormat, l as FontSource, m as RGBA, n as SemanticTokenValue } from './types-ljcTtODU.js';
+import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, R as ResolvedThemeConfig, c as GeneratedPrimitives, d as ThemeOutput, e as ThemeData, f as VisorThemeConfig, g as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, h as RGB, P as ParsedColor, O as OKLCH, i as SemanticTokens, j as ShadeStep } from './types-CV0nmvMz.js';
+export { k as ColorFormat, l as FontSource, m as RGBA, n as SemanticTokenValue } from './types-CV0nmvMz.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -102,6 +102,44 @@ declare const googleFontsCatalog: GoogleFontEntry[];
 /** Look up a font family in the Google Fonts catalog (case-insensitive) */
 declare function lookupGoogleFont(family: string): GoogleFontEntry | undefined;
 
+/**
+ * Font coverage validator.
+ *
+ * Catches the failure mode behind VI-358: emitted theme CSS declares
+ * `--font-*: Family, ...` overrides but the same CSS contains no
+ * `@font-face` rule for that family, so the browser can never load the
+ * declared font and silently falls through to the next stack entry.
+ *
+ * The validator extracts the primary family from each `--font-*` declaration
+ * (the first comma-separated token, unquoted) and checks it against the set
+ * of @font-face families in the same emitted CSS. Generic CSS keywords
+ * (sans-serif, system-ui, etc.) and well-known platform-installed fonts
+ * (SF Mono, Helvetica, etc.) are skipped — those are intentionally part of
+ * the fallback stack and never carry their own @font-face.
+ *
+ * Size-adjusted system-fallback faces (family ends with " Fallback") are
+ * also excluded from the @font-face coverage set; they don't load a real
+ * font, they only adjust local metrics.
+ */
+interface FontCoverageError {
+    family: string;
+    declaredAt: string;
+}
+interface FontCoverageResult {
+    errors: FontCoverageError[];
+}
+/**
+ * Format a font coverage error for surfacing through the CLI / private-themes
+ * generator. The mono slot gets an additional sentence calling out the engine
+ * version requirement and the CLI/engine version coupling (VI-367 / BO-37):
+ * bumping the engine alone is silently insufficient because the visor CLI
+ * transitively pins its own engine copy.
+ *
+ * Filename is included so multi-theme runs surface which theme is failing.
+ */
+declare function formatFontCoverageError(filename: string, declaredAt: string, family: string): string;
+declare function validateFontCoverage(css: string): FontCoverageResult;
+
 /**
  * Import Pipeline
  *
@@ -840,6 +878,30 @@ declare const SEMANTIC_MAP: {
     interactive: Record<string, SemanticMapping>;
 };
 
+/**
+ * Per-theme font-family aliasing — substrate fix for VI-354.
+ *
+ * `@font-face` declarations are global to the document, so co-loaded themes
+ * that share a font family with differing per-theme properties (e.g.
+ * `size-adjust`) silently overwrite each other. Aliasing each theme's
+ * `@font-face` family as `{family} [{slug}]` scopes the declaration to
+ * that theme only; the theme's `--font-*` vars then list the alias first
+ * with the bare family as a fallback for graceful degradation.
+ *
+ * Lives in `fonts/` (not `adapters/`) because every adapter that emits
+ * visor-fonts `@font-face` blocks needs the same aliasing rules. Sharing
+ * the helpers prevents drift between adapters.
+ */
+/**
+ * Map of `bare family name → aliased family name` for every family the
+ * theme emits as a per-theme `@font-face`. The alias applies to every
+ * `--font-*` whose family matches an entry, regardless of which slot the
+ * var represents (the bug repro in VI-354 hinges on this for --font-mono,
+ * which can resolve to the same family as heading/body but doesn't carry
+ * the visor-fonts source through `resolveConfig`).
+ */
+type AliasedFamilies = ReadonlyMap<string, string>;
+
 /**
  * CSS Generation (Stage 3 + Output)
  *
@@ -847,10 +909,17 @@ declare const SEMANTIC_MAP: {
  * packages/tokens/src/generate/generate-css.ts output format.
  */
 
-declare function generatePrimitivesCss(primitives: GeneratedPrimitives, config: ResolvedThemeConfig): string;
+declare function generatePrimitivesCss(primitives: GeneratedPrimitives, config: ResolvedThemeConfig, options?: {
+    aliasedFamilies?: AliasedFamilies;
+    scopePrefix?: string;
+}): string;
 declare function generateSemanticCss(tokens: SemanticTokens): string;
-declare function generateLightCss(tokens: SemanticTokens): string;
-declare function generateDarkCss(tokens: SemanticTokens): string;
+declare function generateLightCss(tokens: SemanticTokens, options?: {
+    scopePrefix?: string;
+}): string;
+declare function generateDarkCss(tokens: SemanticTokens, options?: {
+    scopePrefix?: string;
+}): string;
 declare function generateFullBundleCss(primitives: GeneratedPrimitives, tokens: SemanticTokens, config: ResolvedThemeConfig): string;
 
 /**
@@ -928,4 +997,4 @@ declare function cleanFontValue(val: string): string;
  */
 declare function extractFromCSS(files: CSSFile[], name?: string): ExtractionResult;
 
-export { type CSSFile, ColorRole, type Confidence, type ExtractedToken, type ExtractionResult, FONT_WEIGHT_ALIASES, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, ShadeStep, TAILWIND_GRAY, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_FONTS_CDN, type ValidationIssue, type ValidationSeverity, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorFontUrl, clampToSrgb, cleanFontValue, compositeOverBackground, exportTheme, extractFromCSS, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, googleFontsCatalog, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, lookupFontWeightAlias, lookupGoogleFont, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveConfig, resolveFont, resolveThemeFonts, rgbToHex, serializeColor, validate, validateConfig, visorTheme_schema as visorThemeSchema };
+export { type CSSFile, ColorRole, type Confidence, 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, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_FONTS_CDN, type ValidationIssue, type ValidationSeverity, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, 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, resolveConfig, resolveFont, resolveThemeFonts, rgbToHex, serializeColor, validate, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };

package/dist/index.js

@@ -34,7 +34,161 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-U5FXQ5EC.js";
+} from "./chunk-2O2DPCMJ.js";
+
+// src/fonts/validate-coverage.ts
+var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
+var FONT_FACE_RE = /@font-face\s*\{[^}]*\}/g;
+var FONT_FAMILY_DECL_RE = /font-family\s*:\s*([^;]+);/;
+var GOOGLE_FONTS_IMPORT_RE = /@import\s+url\(["']?https:\/\/fonts\.googleapis\.com\/css2?\?family=([^:&"')]+)/g;
+var FONTSHARE_IMPORT_RE = /@import\s+url\(["']?https:\/\/api\.fontshare\.com\/v2\/css\?f(?:\[\]|%5B%5D)=([a-z0-9-]+)/gi;
+var GENERIC_FAMILIES = /* @__PURE__ */ new Set([
+  "serif",
+  "sans-serif",
+  "monospace",
+  "cursive",
+  "fantasy",
+  "system-ui",
+  "ui-monospace",
+  "ui-sans-serif",
+  "ui-serif",
+  "ui-rounded",
+  "emoji",
+  "math",
+  "fangsong",
+  "inherit",
+  "initial",
+  "unset",
+  "revert",
+  "none",
+  // Apple / Chromium-on-Mac system keywords. These behave like
+  // CSS-engine-level aliases, not real font families — `local()` can
+  // never resolve them, so they never need an @font-face.
+  "-apple-system",
+  "-webkit-system-font",
+  "BlinkMacSystemFont"
+]);
+var SYSTEM_FONTS = /* @__PURE__ */ new Set([
+  "Apple Color Emoji",
+  "Arial",
+  "Arial Black",
+  "BlinkMacSystemFont",
+  "Cambria",
+  "Comic Sans MS",
+  "Consolas",
+  "Courier",
+  "Courier New",
+  "DejaVu Sans",
+  "DejaVu Sans Mono",
+  "Fira Code",
+  "Fira Mono",
+  "Fira Sans",
+  "Georgia",
+  "Helvetica",
+  "Helvetica Neue",
+  "Impact",
+  "JetBrains Mono",
+  "Liberation Mono",
+  "Liberation Sans",
+  "Lucida Console",
+  "Lucida Grande",
+  "Menlo",
+  "Microsoft YaHei",
+  "Monaco",
+  "Noto Color Emoji",
+  "Open Sans",
+  "PingFang SC",
+  "PingFang TC",
+  "Roboto",
+  "Roboto Mono",
+  "Roboto Slab",
+  "SF Mono",
+  "SF Pro Display",
+  "SF Pro Text",
+  "Segoe UI",
+  "Segoe UI Emoji",
+  "Segoe UI Symbol",
+  "Segoe UI Variable",
+  "Source Code Pro",
+  "Source Sans Pro",
+  "Times",
+  "Times New Roman",
+  "Trebuchet MS",
+  "Verdana"
+]);
+function extractPrimaryFamily(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith("var(")) return null;
+  const firstToken = trimmed.split(",")[0].trim();
+  if (!firstToken) return null;
+  const unquoted = firstToken.replace(/^["']|["']$/g, "");
+  if (GENERIC_FAMILIES.has(unquoted)) return null;
+  if (SYSTEM_FONTS.has(unquoted)) return null;
+  return unquoted;
+}
+function extractFontFaceFamilies(css) {
+  const families = /* @__PURE__ */ new Set();
+  const blocks = css.match(FONT_FACE_RE) ?? [];
+  for (const block of blocks) {
+    const decl = FONT_FAMILY_DECL_RE.exec(block);
+    if (!decl) continue;
+    const family = decl[1].trim().replace(/^["']|["'];?$/g, "");
+    if (family.endsWith(" Fallback")) continue;
+    families.add(family);
+  }
+  return families;
+}
+function extractGoogleFontsImports(css) {
+  const families = /* @__PURE__ */ new Set();
+  for (const match of css.matchAll(GOOGLE_FONTS_IMPORT_RE)) {
+    const family = decodeURIComponent(match[1]).replace(/\+/g, " ");
+    families.add(family);
+  }
+  return families;
+}
+function fontshareSlugToFamily(slug) {
+  return slug.split("-").filter((p) => p.length > 0).map((p) => p[0].toUpperCase() + p.slice(1)).join(" ");
+}
+function extractFontshareImports(css) {
+  const families = /* @__PURE__ */ new Set();
+  for (const match of css.matchAll(FONTSHARE_IMPORT_RE)) {
+    families.add(fontshareSlugToFamily(match[1]));
+  }
+  return families;
+}
+function extractFontVarDeclarations(css) {
+  const decls = [];
+  for (const match of css.matchAll(FONT_VAR_RE)) {
+    const slot = `--font-${match[1]}`;
+    const family = extractPrimaryFamily(match[2]);
+    if (!family) continue;
+    decls.push({ slot, family });
+  }
+  return decls;
+}
+function formatFontCoverageError(filename, declaredAt, family) {
+  const base = `${filename}: ${declaredAt} declares "${family}" with no matching @font-face. `;
+  if (declaredAt === "--font-mono") {
+    return base + `Set typography.mono.source: visor-fonts (with org:), google-fonts, or fontshare; or pick a system mono font. The mono slot's source/org keys require @loworbitstudio/visor-theme-engine \u2265 0.5.0 and @loworbitstudio/visor \u2265 0.10.0 \u2014 bump both, since the CLI bundles its own engine copy.`;
+  }
+  return base + `Set typography.<slot>.source: visor-fonts (with org:), google-fonts, or fontshare; or pick a system font.`;
+}
+function validateFontCoverage(css) {
+  const declaredFamilies = extractFontFaceFamilies(css);
+  for (const f of extractGoogleFontsImports(css)) declaredFamilies.add(f);
+  for (const f of extractFontshareImports(css)) declaredFamilies.add(f);
+  const declarations = extractFontVarDeclarations(css);
+  const errors = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const decl of declarations) {
+    if (declaredFamilies.has(decl.family)) continue;
+    const key = `${decl.slot}::${decl.family}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    errors.push({ family: decl.family, declaredAt: decl.slot });
+  }
+  return { errors };
+}
 
 // src/pipeline.ts
 import { parse as parseYaml } from "yaml";
@@ -429,7 +583,7 @@ var KNOWN_TYPOGRAPHY_KEYS = /* @__PURE__ */ new Set([
   "slots"
 ]);
 var KNOWN_TYPOGRAPHY_FONT_KEYS = /* @__PURE__ */ new Set(["family", "weight", "weights", "source", "org"]);
-var KNOWN_TYPOGRAPHY_MONO_KEYS = /* @__PURE__ */ new Set(["family"]);
+var KNOWN_TYPOGRAPHY_MONO_KEYS = /* @__PURE__ */ new Set(["family", "weight", "weights", "source", "org"]);
 var KNOWN_LETTER_SPACING_KEYS = /* @__PURE__ */ new Set(["tight", "normal", "wide"]);
 var KNOWN_SLOT_NAMES = new Set(MATERIAL_TEXT_SLOTS);
 var KNOWN_SLOT_OVERRIDE_KEYS = /* @__PURE__ */ new Set(["size", "weight", "letter-spacing"]);
@@ -763,6 +917,7 @@ function resolveConfig(config) {
   }
   return {
     name: config.name,
+    ...config.label !== void 0 && { label: config.label },
     version: 1,
     colors: {
       primary: colors.primary,
@@ -801,7 +956,11 @@ function resolveConfig(config) {
         ...config.typography?.body?.weights && { weights: config.typography.body.weights }
       },
       mono: {
-        family: config.typography?.mono?.family ?? DEFAULTS.typography.mono.family
+        family: config.typography?.mono?.family ?? DEFAULTS.typography.mono.family,
+        ...config.typography?.mono?.weight && { weight: config.typography.mono.weight },
+        ...config.typography?.mono?.weights && { weights: config.typography.mono.weights },
+        ...config.typography?.mono?.source && { source: config.typography.mono.source },
+        ...config.typography?.mono?.org && { org: config.typography.mono.org }
       },
       slots: config.typography?.slots ?? {}
     },
@@ -2640,6 +2799,7 @@ export {
   compositeOverBackground,
   exportTheme,
   extractFromCSS,
+  formatFontCoverageError,
   generateDarkCss,
   generateFullBundleCss,
   generateLightCss,
@@ -2679,5 +2839,6 @@ export {
   serializeColor,
   validate,
   validateConfig,
+  validateFontCoverage,
   visor_theme_schema_default as visorThemeSchema
 };

package/dist/{types-ljcTtODU.d.ts → types-CV0nmvMz.d.ts}

@@ -2,7 +2,7 @@
  * Font resolution types for the Visor theme engine.
  */
 /** Where a font is loaded from */
-type FontSource = "google-fonts" | "visor-fonts" | "local";
+type FontSource = "google-fonts" | "visor-fonts" | "fontshare" | "local";
 /** CSS font-display strategy */
 type FontDisplayStrategy = "swap" | "block" | "fallback" | "optional" | "auto";
 /** A single resolved font */
@@ -11,7 +11,7 @@ interface FontResolution {
     family: string;
     /** Where this font comes from */
     source: FontSource;
-    /** Google Fonts CSS URL (only for google-fonts source) */
+    /** Hosted CSS URL (only for google-fonts or fontshare sources) */
     cssUrl: string | null;
     /** Weights available/requested for this font */
     weights: number[];
@@ -70,6 +70,8 @@ interface VisorTypography {
     mono?: {
         family: string;
         weight?: number;
+        /** Explicit list of font weights to load (overrides engine defaults) */
+        weights?: number[];
         source?: FontSource;
         org?: string;
     };
@@ -198,6 +200,7 @@ interface VisorThemeConfig {
         mono?: {
             family?: string;
             weight?: number;
+            weights?: number[];
             source?: FontSource;
             org?: string;
         };
@@ -266,6 +269,8 @@ interface VisorThemeConfig {
 /** Config with all defaults resolved */
 interface ResolvedThemeConfig {
     name: string;
+    /** Optional display label override forwarded from VisorThemeConfig.label. */
+    label?: string;
     version: 1;
     colors: {
         primary: string;
@@ -304,6 +309,10 @@ interface ResolvedThemeConfig {
         };
         mono: {
             family: string;
+            weight?: number;
+            weights?: number[];
+            source?: FontSource;
+            org?: string;
         };
         /**
          * Per-slot Material `TextTheme` overrides, passed through from the

package/package.json

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