@loworbitstudio/visor-theme-engine 0.6.0 → 0.8.1

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-CtozYHw0.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

@@ -13,7 +13,7 @@ import {
   parseColor,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-4U5L3AWY.js";
+} from "../chunk-OJVNL7KN.js";
 
 // src/adapters/layers.ts
 var LAYER_ORDER = "@layer visor-primitives, visor-semantic, visor-adaptive, visor-bridge;";
@@ -32,6 +32,7 @@ function toKebabCase(name) {
 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();
@@ -89,12 +90,15 @@ function nextjsAdapter(input, options) {
   lines.push(LAYER_ORDER);
   lines.push("");
   const primitivesBody = stripHeader(
-    generatePrimitivesCss(input.primitives, input.config, { aliasedFamilies })
+    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)
   );

package/dist/{chunk-4U5L3AWY.js → chunk-OJVNL7KN.js}

@@ -122,9 +122,18 @@ var FONT_WEIGHT_ALIASES = {
     400: "Book",
     800: "Super"
   },
+  "PP Model Sans": {
+    400: "Book",
+    800: "Super"
+  },
   "PP Model Plastic": {
     400: "Book",
     800: "Super"
+  },
+  // Hoefler's Gotham uses "Book" instead of "Regular" at weight 400.
+  // Light (300) and Medium (500) match WEIGHT_NAMES defaults.
+  Gotham: {
+    400: "Book"
   }
 };
 function lookupFontWeightAlias(family, weight) {
@@ -623,13 +632,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) {
@@ -1299,22 +1324,23 @@ function generateMiscPrimitives() {
 }
 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, options?.aliasedFamilies)));
+  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) {
@@ -1356,25 +1382,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"));

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-CtozYHw0.js';
-export { k as ColorFormat, l as FontSource, m as RGBA, n as SemanticTokenValue } from './types-CtozYHw0.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.
@@ -128,6 +128,16 @@ interface FontCoverageError {
 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;
 
 /**
@@ -901,10 +911,15 @@ type AliasedFamilies = ReadonlyMap<string, 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;
 
 /**
@@ -982,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, 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, 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 };
+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,7 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-4U5L3AWY.js";
+} from "./chunk-OJVNL7KN.js";
 
 // src/fonts/validate-coverage.ts
 var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
@@ -166,6 +166,13 @@ function extractFontVarDeclarations(css) {
   }
   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);
@@ -910,6 +917,7 @@ function resolveConfig(config) {
   }
   return {
     name: config.name,
+    ...config.label !== void 0 && { label: config.label },
     version: 1,
     colors: {
       primary: colors.primary,
@@ -1616,6 +1624,41 @@ var KNOWN_SEMANTIC_TOKENS = /* @__PURE__ */ new Set([
   ...Object.keys(SEMANTIC_BORDER_MAP).map((k) => `border-${k}`),
   ...Object.keys(SEMANTIC_INTERACTIVE_MAP).map((k) => `interactive-${k}`)
 ]);
+var REQUIRED_OVERRIDE_TOKENS = {
+  text: ["primary", "secondary", "tertiary", "disabled"],
+  surface: [
+    "page",
+    "card",
+    "popover",
+    "subtle",
+    "muted",
+    "interactive-default",
+    "interactive-hover",
+    "interactive-active",
+    "interactive-disabled",
+    "selected",
+    "accent-subtle",
+    "success-subtle",
+    "warning-subtle",
+    "error-subtle",
+    "info-subtle",
+    "elev-0",
+    "elev-1",
+    "elev-2",
+    "elev-3",
+    "elev-4"
+  ],
+  border: ["default", "muted", "strong", "disabled"],
+  interactive: [
+    "secondary-bg",
+    "secondary-bg-hover",
+    "secondary-bg-active",
+    "secondary-text",
+    "secondary-border",
+    "ghost-bg",
+    "ghost-bg-hover"
+  ]
+};
 function issue(severity, code, message, path) {
   const result = { severity, code, message };
   if (path !== void 0) {
@@ -1958,6 +2001,30 @@ function checkOverrides(config, issues) {
     }
   }
 }
+function checkOverrideCompleteness(config, issues) {
+  const lightOverrides = config.overrides?.light;
+  if (!lightOverrides) return;
+  const presentKeys = Object.keys(lightOverrides);
+  if (presentKeys.length === 0) return;
+  const hasTriggerKey = "surface-page" in lightOverrides || "surface-card" in lightOverrides;
+  if (!hasTriggerKey) return;
+  const present = new Set(presentKeys);
+  for (const [family, tokens] of Object.entries(REQUIRED_OVERRIDE_TOKENS)) {
+    for (const token of tokens) {
+      const fullKey = `${family}-${token}`;
+      if (!present.has(fullKey)) {
+        issues.push(
+          issue(
+            "warning",
+            "INCOMPLETE_OVERRIDE",
+            `'overrides.light' inverts the light-mode surface (overrides 'surface-page' or 'surface-card') but is missing '${fullKey}'. The engine's light-mode default for this token may leak (bright/light-natural values on inverted always-dark themes like Blackout).`,
+            `overrides.light.${fullKey}`
+          )
+        );
+      }
+    }
+  }
+}
 function checkResolvedCompleteness(resolved, issues) {
   const requiredColors = [
     "primary",
@@ -2274,6 +2341,7 @@ function validate(config) {
   for (const iss of overrideIssues) {
     (iss.severity === "error" ? errors : warnings).push(iss);
   }
+  checkOverrideCompleteness(typedConfig, warnings);
   if (errors.length === 0) {
     const resolved = resolveConfig(typedConfig);
     checkResolvedCompleteness(resolved, errors);
@@ -2791,6 +2859,7 @@ export {
   compositeOverBackground,
   exportTheme,
   extractFromCSS,
+  formatFontCoverageError,
   generateDarkCss,
   generateFullBundleCss,
   generateLightCss,

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

@@ -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;
     };
@@ -267,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;

package/package.json

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