@loworbitstudio/visor-theme-engine 0.19.0 → 0.20.0

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { k as GeneratedPrimitives, s as SemanticTokens, R as ResolvedThemeConfig } from '../types-DF5StphJ.js';
+import { k as GeneratedPrimitives, s as SemanticTokens, R as ResolvedThemeConfig } from '../types-BG-YT4JW.js';
 
 /**
  * Adapter types for the Visor theme engine.
@@ -37,6 +37,10 @@ interface NextJSAdapterOptions extends AdapterOptions {
      * `@layer visor-base` origination block that binds theme tokens to the page
      * root (default: true). Set false for consumers that ship Tailwind preflight
      * or their own reset. See VI-616.
+     *
+     * VI-638: the base block also carries `font-size: var(--font-size-base)`,
+     * which is how `typography.scale` reaches the page. A consumer that declines
+     * it must bind the base size itself — on `body`, not `:root`.
      */
     includeBaseLayer?: boolean;
 }

package/dist/adapters/index.js

@@ -8,6 +8,8 @@ import {
   collectBrandPassthrough,
   fontStack,
   generateDarkCss,
+  generateFontSizeDecls,
+  generateFontWeightDecls,
   generateHairlineDecls,
   generateIntentDecls,
   generateLightCss,
@@ -21,7 +23,7 @@ import {
   resolveThemeBrand,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-32DC5DAR.js";
+} from "../chunk-JDYLDGUN.js";
 
 // src/adapters/brand-passthrough.ts
 var SENTINEL_COLOR = "#ff00ff";
@@ -212,7 +214,11 @@ function nextjsAdapter(input, options) {
     baseLines.push(
       block(scopePrefix ?? "body", [
         "font-family: var(--font-body);",
-        "font-size: 1rem;",
+        // VI-638: the scaled ramp is the single mechanism that sets type size,
+        // and the base step is what the page inherits. This binding lives on
+        // `body` (or the body-class scope), never `:root` — the ramp is
+        // expressed in `rem`, so a scaled root would multiply it a second time.
+        "font-size: var(--font-size-base, 1rem);",
         "color: var(--text-primary);",
         "background: var(--surface-page, var(--surface-background));"
       ])
@@ -537,23 +543,8 @@ function generateTypographyDecls(config, 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,
-    base: 16,
-    lg: 18,
-    xl: 20,
-    "2xl": 24,
-    "3xl": 30,
-    "4xl": 36
-  };
-  for (const [name, px] of Object.entries(fontSizes)) {
-    decls.push(`--font-size-${name}: ${px / 16}rem; /* ${px}px */`);
-  }
-  decls.push(`--font-weight-normal: ${config.typography.body.weight};`);
-  decls.push("--font-weight-medium: 500;");
-  decls.push(`--font-weight-semibold: ${config.typography.heading.weight};`);
-  decls.push("--font-weight-bold: 700;");
+  decls.push(...generateFontSizeDecls(config.typography.scale));
+  decls.push(...generateFontWeightDecls(config.typography));
   const lineHeights = {
     none: 1,
     tight: 1.25,
@@ -686,7 +677,6 @@ function docsAdapter(input, options) {
         fontLines.push("");
       }
     }
-    const scale = input.config.typography?.scale ?? 1;
     const emittedFamilies = /* @__PURE__ */ new Set();
     for (const font of fontSlots) {
       if (font && font.source === "visor-fonts" && !emittedFamilies.has(font.family)) {
@@ -700,9 +690,6 @@ function docsAdapter(input, options) {
           fontLines.push(`  font-weight: ${weight};`);
           fontLines.push(`  font-style: ${font.italic ? "italic" : "normal"};`);
           fontLines.push(`  font-display: ${font.display};`);
-          if (scale !== 1) {
-            fontLines.push(`  size-adjust: ${Math.round(scale * 100)}%;`);
-          }
           fontLines.push("}");
           fontLines.push("");
         }
@@ -712,7 +699,11 @@ function docsAdapter(input, options) {
   lines.push("\n/* \u2500\u2500 Section 1: Shared tokens (mode-independent) \u2500\u2500 */");
   const sharedDecls = [
     "min-height: 100vh;",
-    "font-size: 1rem;",
+    // VI-638: the scaled ramp is the single mechanism that sets type size, and
+    // the base step is what the page inherits. Safe here because the scope is a
+    // class on a wrapper, never `:root` — a scaled root would multiply the
+    // rem-expressed ramp a second time.
+    "font-size: var(--font-size-base, 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));`,

package/dist/{chunk-32DC5DAR.js → chunk-JDYLDGUN.js}

@@ -1928,6 +1928,99 @@ function applyOverrides(tokens, overrides) {
   return result;
 }
 
+// src/font-weights.ts
+var WEIGHT_RAMP_TARGETS = {
+  medium: 500,
+  semibold: 600,
+  bold: 700
+};
+var SLOTS = ["heading", "display", "body", "mono"];
+function loadedWeights(typography) {
+  const set = /* @__PURE__ */ new Set();
+  for (const slot of SLOTS) {
+    const cfg = typography[slot];
+    if (!cfg) continue;
+    if (cfg.weights?.length) {
+      for (const w of cfg.weights) set.add(w);
+    } else if (typeof cfg.weight === "number") {
+      set.add(cfg.weight);
+    }
+  }
+  return [...set].sort((a, b) => a - b);
+}
+function declaresWeights(typography) {
+  return SLOTS.some((slot) => Boolean(typography[slot]?.weights?.length));
+}
+function matchLoadedWeight(desired, loaded) {
+  if (loaded.length === 0) return desired;
+  if (loaded.includes(desired)) return desired;
+  const ascending = [...loaded].sort((a, b) => a - b);
+  const lighter = ascending.filter((w) => w < desired).reverse();
+  const heavier = ascending.filter((w) => w > desired);
+  if (desired >= 400 && desired <= 500) {
+    const upToFive = heavier.filter((w) => w <= 500);
+    const aboveFive = heavier.filter((w) => w > 500);
+    return upToFive[0] ?? lighter[0] ?? aboveFive[0];
+  }
+  if (desired < 400) {
+    return lighter[0] ?? heavier[0];
+  }
+  return heavier[0] ?? lighter[0];
+}
+function resolveWeightRamp(typography) {
+  const bodyWeight = typography.body?.weight ?? 400;
+  if (!declaresWeights(typography)) {
+    return {
+      normal: bodyWeight,
+      medium: WEIGHT_RAMP_TARGETS.medium,
+      semibold: WEIGHT_RAMP_TARGETS.semibold,
+      bold: WEIGHT_RAMP_TARGETS.bold
+    };
+  }
+  const loaded = loadedWeights(typography);
+  return {
+    normal: matchLoadedWeight(bodyWeight, loaded),
+    medium: matchLoadedWeight(WEIGHT_RAMP_TARGETS.medium, loaded),
+    semibold: matchLoadedWeight(WEIGHT_RAMP_TARGETS.semibold, loaded),
+    bold: matchLoadedWeight(WEIGHT_RAMP_TARGETS.bold, loaded)
+  };
+}
+function resolveRoleWeight(declared, typography) {
+  if (!declaresWeights(typography)) return declared;
+  return matchLoadedWeight(declared, loadedWeights(typography));
+}
+function generateFontWeightDecls(typography) {
+  const ramp = resolveWeightRamp(typography);
+  const decls = [
+    `--font-weight-normal: ${ramp.normal};`,
+    `--font-weight-medium: ${ramp.medium};`,
+    `--font-weight-semibold: ${ramp.semibold};`,
+    `--font-weight-bold: ${ramp.bold};`,
+    // Role primitives. These are why `semibold` was pinned in the first place:
+    // packages/tokens defined `--weight-heading: var(--font-weight-semibold)`
+    // and the engine emitted no per-theme value, so hijacking `semibold` was
+    // the only channel a theme's heading weight had. Each role has its own
+    // primitive now, and the semantic `--weight-*` roles resolve through them.
+    //
+    // Emitted as `--font-weight-*` primitives rather than the bare `--weight-*`
+    // names on purpose: the semantic names are defined in @layer visor-semantic,
+    // which wins over visor-primitives, so a theme writing them directly would
+    // be overridden by the tokens package on a `:root`-scoped consumer.
+    `--font-weight-heading: ${resolveRoleWeight(typography.heading.weight, typography)};`,
+    `--font-weight-body: ${resolveRoleWeight(typography.body.weight, typography)};`,
+    `--font-weight-display: ${resolveRoleWeight(typography.display.weight, typography)};`,
+    // Retained: `--weight-display` has no competing definition in the tokens
+    // package and predates this change, so consumers already reference it.
+    `--weight-display: ${resolveRoleWeight(typography.display.weight, typography)};`
+  ];
+  if (declaresWeights(typography)) {
+    for (const weight of loadedWeights(typography)) {
+      decls.push(`--font-weight-${weight}: ${weight};`);
+    }
+  }
+  return decls;
+}
+
 // src/fonts/theme-alias.ts
 var EMPTY_ALIASES = /* @__PURE__ */ new Map();
 function aliasFamily(family, themeSlug) {
@@ -2024,33 +2117,32 @@ function generateShadowPrimitives(config) {
     `--shadow-xl: ${config.shadows.xl};`
   ];
 }
+var FONT_SIZE_RAMP_PX = {
+  xs: 12,
+  sm: 14,
+  base: 16,
+  lg: 18,
+  xl: 20,
+  "2xl": 24,
+  "3xl": 30,
+  "4xl": 36
+};
+function generateFontSizeDecls(scale) {
+  return Object.entries(FONT_SIZE_RAMP_PX).map(([name, px]) => {
+    const scaled = px * scale;
+    const rem = Number((scaled / 16).toFixed(5));
+    return `--font-size-${name}: ${rem}rem; /* ${Number(scaled.toFixed(2))}px */`;
+  });
+}
 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: ${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,
-    base: 16,
-    lg: 18,
-    xl: 20,
-    "2xl": 24,
-    "3xl": 30,
-    "4xl": 36
-  };
-  for (const [name, px] of Object.entries(fontSizes)) {
-    decls.push(`--font-size-${name}: ${px / 16}rem; /* ${px}px */`);
-  }
-  decls.push(`--font-weight-normal: ${config.typography.body.weight};`);
-  decls.push("--font-weight-medium: 500;");
-  decls.push(`--font-weight-semibold: ${config.typography.heading.weight};`);
-  decls.push("--font-weight-bold: 700;");
-  decls.push(`--weight-display: ${config.typography.display.weight};`);
+  decls.push(...generateFontSizeDecls(config.typography.scale));
+  decls.push(...generateFontWeightDecls(config.typography));
   const lineHeights = {
     none: 1,
     tight: 1.25,
@@ -2464,11 +2556,19 @@ export {
   collectBrandPassthrough,
   hasBrandPassthrough,
   applyOverrides,
+  WEIGHT_RAMP_TARGETS,
+  loadedWeights,
+  declaresWeights,
+  matchLoadedWeight,
+  resolveWeightRamp,
+  resolveRoleWeight,
+  generateFontWeightDecls,
   aliasFamily,
   fontStack,
   header,
   sectionComment,
   block2 as block,
+  generateFontSizeDecls,
   generatePrimitivesCss,
   generateSemanticCss,
   generateTextScaleAliasDecls,

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, 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-DF5StphJ.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 COMPONENT_TOKEN_FAMILIES, Z as COMPONENT_TOKEN_FAMILY_BY_NAME, _ as ColorFormat, $ as ComponentTokenBinding, a0 as ComponentTokenBindings, a1 as ComponentTokenConsumer, a2 as ComponentTokenFamily, a3 as ComponentTokenSpec, a4 as DEFAULT_BRAND_STRATEGY_SURFACES, a5 as DEFAULT_BRAND_STRATEGY_TONE_STATES, a6 as FontSource, a7 as GOVERNS_WILDCARD, a8 as RGBA, a9 as ResolvedComponentTokens, aa as SemanticTokenValue, ab as allComponentTokenNames, ac as componentTokenName, ad as hasComponentBindings, ae as resolveComponentBindings, af as validateComponentBindings } from './types-DF5StphJ.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-BG-YT4JW.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 COMPONENT_TOKEN_FAMILIES, Z as COMPONENT_TOKEN_FAMILY_BY_NAME, _ as ColorFormat, $ as ComponentTokenBinding, a0 as ComponentTokenBindings, a1 as ComponentTokenConsumer, a2 as ComponentTokenFamily, a3 as ComponentTokenSpec, a4 as DEFAULT_BRAND_STRATEGY_SURFACES, a5 as DEFAULT_BRAND_STRATEGY_TONE_STATES, a6 as FontSource, a7 as GOVERNS_WILDCARD, a8 as RGBA, a9 as ResolvedComponentTokens, aa as SemanticTokenValue, ab as allComponentTokenNames, ac as componentTokenName, ad as hasComponentBindings, ae as resolveComponentBindings, af as validateComponentBindings } from './types-BG-YT4JW.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -585,7 +585,7 @@ var properties = {
 			},
 			scale: {
 				type: "number",
-				description: "Type scale multiplier applied to the font-size ramp. Default: 1."
+				description: "Type scale multiplier applied to the font-size ramp: every --font-size-* step is multiplied by it, and the page inherits the scaled --font-size-base. Default: 1. CSS adapters only — the Flutter adapter emits Material 3 slot sizes verbatim and ignores this field."
 			},
 			"text-on-light": {
 				type: "string",
@@ -1922,6 +1922,135 @@ declare function generateDarkCss(tokens: SemanticTokens, options?: {
 }): string;
 declare function generateFullBundleCss(primitives: GeneratedPrimitives, tokens: SemanticTokens, config: ResolvedThemeConfig): string;
 
+/**
+ * Font-weight resolution (VI-639).
+ *
+ * The named weight ramp used to be three literals and one role leak:
+ *
+ * ```
+ * --font-weight-normal:   <body.weight>
+ * --font-weight-medium:   500                 // literal
+ * --font-weight-semibold: <heading.weight>    // a different concept entirely
+ * --font-weight-bold:     700                 // literal
+ * ```
+ *
+ * `semibold` is not a heading. Pinning it there collapsed it onto `medium` on
+ * every theme whose heading weight is 500 (the Blacklight family), onto
+ * `normal` where it is 400 (knowmentum), and inverted the ramp where it is
+ * above `bold` (strata emitted `semibold: 800` over `bold: 700`). Meanwhile the
+ * literals ignored the `weights` array a theme actually loaded, so a theme
+ * declaring `[200, 400, 600, 900]` got tokens pointing at faces it never
+ * fetched — which the browser then silently substituted.
+ *
+ * Resolution here follows the CSS font-matching algorithm's weight-selection
+ * order (CSS Fonts 4 §5.2) rather than naive nearest-numeric. The browser is
+ * already performing exactly this substitution at render time, so an emitted
+ * token becomes the weight that was *already rendering* — which is what makes
+ * this change visually neutral everywhere except where the token was wrong.
+ */
+/** Canonical targets for the named ramp above `normal`. */
+declare const WEIGHT_RAMP_TARGETS: {
+    readonly medium: 500;
+    readonly semibold: 600;
+    readonly bold: 700;
+};
+/** The typography slots that can declare a family, weight and weights array. */
+declare const SLOTS: readonly ["heading", "display", "body", "mono"];
+type WeightedSlot = {
+    weight?: number;
+    weights?: number[];
+} | undefined;
+type SlottedTypography = Partial<Record<(typeof SLOTS)[number], WeightedSlot>>;
+/**
+ * The weights a theme actually loads: each slot's explicit `weights` array, or
+ * its single `weight` when it declares none — mirroring how the font pipeline
+ * resolves the set it fetches.
+ */
+declare function loadedWeights(typography: SlottedTypography): number[];
+/**
+ * Whether any slot declares an explicit `weights` array.
+ *
+ * Resolution is gated on this. A theme that declares one has told us what it
+ * loads, so we can hold every emitted token to that set. A theme that hasn't
+ * keeps the historical emission untouched — snapping against a set inferred
+ * from three `weight` fields would move tokens on a claim the theme never made
+ * (and says nothing at all about a system font stack, which has whatever the OS
+ * has). `validateFontWeights` warns about those instead.
+ */
+declare function declaresWeights(typography: SlottedTypography): boolean;
+/**
+ * Pick the weight a browser would actually use for `desired`, given the faces
+ * the theme loaded — CSS Fonts 4 §5.2 weight-matching order:
+ *
+ * - exact match wins;
+ * - desired 400–500: heavier faces up to 500 ascending, then lighter descending,
+ *   then heavier than 500 ascending;
+ * - desired below 400: lighter descending, then heavier ascending;
+ * - desired above 500: heavier ascending, then lighter descending.
+ *
+ * Returns `desired` unchanged when the theme loads nothing (nothing to match
+ * against, and the system font has its own ideas).
+ */
+declare function matchLoadedWeight(desired: number, loaded: readonly number[]): number;
+/** The four named ramp steps a theme emits, resolved against what it loaded. */
+interface ResolvedWeightRamp {
+    normal: number;
+    medium: number;
+    semibold: number;
+    bold: number;
+}
+/**
+ * Resolve the named ramp.
+ *
+ * `normal` tracks the theme's body weight rather than a hard 400 — it is the
+ * ramp's zero point, and Blacklight's `body.weight: 300` is a deliberate
+ * choice, not a rounding error. It is still coerced to a loaded face (strata
+ * declares `body.weight: 450` and loads `[400, 700, 900]`).
+ *
+ * `medium / semibold / bold` resolve the canonical 500 / 600 / 700 targets.
+ * Names can still share a value on a family that cannot separate them — two
+ * loaded faces cannot back four distinct names — but the result is now the
+ * truth about what renders rather than a number nothing will honour.
+ */
+declare function resolveWeightRamp(typography: SlottedTypography & {
+    body?: WeightedSlot;
+}): ResolvedWeightRamp;
+/**
+ * Resolve a role weight (`--weight-heading`, `--weight-body`,
+ * `--weight-display`) to a loaded face. Roles carry theme intent — what this
+ * theme's headings weigh — and are the channel components should read when they
+ * mean "the heading weight" rather than "a step above medium".
+ */
+declare function resolveRoleWeight(declared: number, typography: SlottedTypography): number;
+/**
+ * Emit the shared weight declarations: the named ramp, the role tokens, and the
+ * discrete ladder.
+ *
+ * The ladder (`--font-weight-300` … `--font-weight-800`, one per loaded face)
+ * is what makes the `weights` array authoritative instead of decorative. Before
+ * it, a theme could load five faces and reach four of them by name at best —
+ * Blacklight's 800 was unreachable from CSS, so BL-987 had to write a literal.
+ * It follows the `--text-N` / `--space-N` discrete-alias precedent from VI-451.
+ */
+declare function generateFontWeightDecls(typography: {
+    heading: {
+        weight: number;
+        weights?: number[];
+    };
+    display: {
+        weight: number;
+        weights?: number[];
+    };
+    body: {
+        weight: number;
+        weights?: number[];
+    };
+    mono: {
+        weight?: number;
+        weights?: number[];
+    };
+}): string[];
+
 /**
  * Theme Extraction Engine
  *
@@ -1997,4 +2126,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, 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 };
+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, type ResolvedWeightRamp, 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, WEIGHT_RAMP_TARGETS, applyOverrides, assignSemanticTokens, buildVisorBrandUrl, buildVisorFontUrl, checkBrandStrategyCoherence, checkBrandStrategyStructure, clampToSrgb, cleanFontValue, collectBrandPassthrough, compositeOverBackground, declaresWeights, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFontWeightDecls, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, getKnownTokenRefs, getLuminance, googleFontsCatalog, hasBrandPassthrough, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, loadedWeights, lookupFontWeightAlias, lookupGoogleFont, matchLoadedWeight, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveBrandSlot, resolveBrandSource, resolveConfig, resolveFont, resolveRoleWeight, resolveThemeBrand, resolveThemeFonts, resolveWeightRamp, rgbToHex, serializeBrandStrategy, serializeColor, validate, validateBrandStrategy, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };

package/dist/index.js

@@ -9,6 +9,7 @@ import {
   VISOR_BRANDS_CDN,
   VISOR_DEFAULT_BRAND_PATH,
   VISOR_FONTS_CDN,
+  WEIGHT_RAMP_TARGETS,
   allComponentTokenNames,
   applyOverrides,
   buildVisorBrandUrl,
@@ -17,7 +18,9 @@ import {
   collectBrandPassthrough,
   componentTokenName,
   compositeOverBackground,
+  declaresWeights,
   generateDarkCss,
+  generateFontWeightDecls,
   generateFullBundleCss,
   generateLightCss,
   generatePreloadLinks,
@@ -34,8 +37,10 @@ import {
   hexToRgb,
   isValidColor,
   isValidHex,
+  loadedWeights,
   lookupFontWeightAlias,
   lookupGoogleFont,
+  matchLoadedWeight,
   normalizeHex,
   oklchToHex,
   parseColor,
@@ -47,13 +52,15 @@ import {
   resolveBrandSource,
   resolveComponentBindings,
   resolveFont,
+  resolveRoleWeight,
   resolveThemeBrand,
   resolveThemeFonts,
+  resolveWeightRamp,
   rgbToHex,
   rgbToOklch,
   serializeColor,
   validateComponentBindings
-} from "./chunk-32DC5DAR.js";
+} from "./chunk-JDYLDGUN.js";
 
 // src/fonts/validate-coverage.ts
 var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
@@ -793,7 +800,7 @@ var visor_theme_schema_default = {
         },
         scale: {
           type: "number",
-          description: "Type scale multiplier applied to the font-size ramp. Default: 1."
+          description: "Type scale multiplier applied to the font-size ramp: every --font-size-* step is multiplied by it, and the page inherits the scaled --font-size-base. Default: 1. CSS adapters only \u2014 the Flutter adapter emits Material 3 slot sizes verbatim and ignores this field."
         },
         "text-on-light": {
           type: "string",
@@ -3137,6 +3144,46 @@ function checkTypeScaleCoherence(config, issues) {
     }
   }
 }
+function checkFontWeightCoverage(config, issues) {
+  const typography = config.typography;
+  if (!typography) return;
+  const HOSTED = /* @__PURE__ */ new Set(["visor-fonts", "google-fonts", "fontshare"]);
+  const slots = ["heading", "display", "body", "mono"];
+  if (!declaresWeights(typography)) {
+    const hosted = slots.filter((slot) => {
+      const source = typography[slot]?.source;
+      return typeof source === "string" && HOSTED.has(source);
+    });
+    if (hosted.length > 0) {
+      issues.push(
+        issue(
+          "warning",
+          "FONT_WEIGHTS_UNDECLARED",
+          `typography.${hosted[0]} loads from '${typography[hosted[0]].source}' but no slot declares a 'weights' array. Named weight tokens fall back to the canonical 500/600/700 literals, which may not be faces this theme fetched. Declare 'weights' to make them resolve against what you actually load.`,
+          `typography.${hosted[0]}.weights`
+        )
+      );
+    }
+    return;
+  }
+  const loaded = loadedWeights(typography);
+  const ramp = resolveWeightRamp(typography);
+  const collapsed = [
+    ["medium", "normal"],
+    ["semibold", "medium"],
+    ["bold", "semibold"]
+  ].filter(([heavier, lighter]) => ramp[heavier] === ramp[lighter]).map(([heavier, lighter]) => `${heavier} = ${lighter} (${ramp[heavier]})`);
+  if (collapsed.length > 0) {
+    issues.push(
+      issue(
+        "warning",
+        "FONT_WEIGHT_RAMP_COLLAPSED",
+        `Named weight steps share a value because this theme loads only [${loaded.join(", ")}]: ${collapsed.join(", ")}. Asking for the heavier name renders no differently from the lighter one. This is what the browser already does \u2014 load an intermediate face, or use the discrete ladder (--font-weight-${loaded.join(" / --font-weight-")}) where a real step is needed.`,
+        "typography"
+      )
+    );
+  }
+}
 function checkLetterSpacing(config, issues) {
   const ls = config.typography?.["letter-spacing"];
   if (!ls) return;
@@ -3643,6 +3690,7 @@ function validate(config, options) {
   const typedConfig = config;
   checkCompleteness(typedConfig, errors);
   checkTypeScaleCoherence(typedConfig, errors);
+  checkFontWeightCoverage(typedConfig, warnings);
   checkLetterSpacing(typedConfig, errors);
   checkMotionEasing(typedConfig, errors);
   const durationIssues = [];
@@ -4216,6 +4264,7 @@ export {
   VISOR_BRANDS_CDN,
   VISOR_DEFAULT_BRAND_PATH,
   VISOR_FONTS_CDN,
+  WEIGHT_RAMP_TARGETS,
   allComponentTokenNames,
   applyOverrides,
   assignSemanticTokens,
@@ -4228,10 +4277,12 @@ export {
   collectBrandPassthrough,
   componentTokenName,
   compositeOverBackground,
+  declaresWeights,
   exportTheme,
   extractFromCSS,
   formatFontCoverageError,
   generateDarkCss,
+  generateFontWeightDecls,
   generateFullBundleCss,
   generateLightCss,
   generatePreloadLinks,
@@ -4255,8 +4306,10 @@ export {
   isValidColor,
   isValidHex,
   isVisorThemeConfig,
+  loadedWeights,
   lookupFontWeightAlias,
   lookupGoogleFont,
+  matchLoadedWeight,
   normalizeHex,
   oklchToHex,
   parseCSSDeclarations,
@@ -4272,8 +4325,10 @@ export {
   resolveComponentBindings,
   resolveConfig,
   resolveFont,
+  resolveRoleWeight,
   resolveThemeBrand,
   resolveThemeFonts,
+  resolveWeightRamp,
   rgbToHex,
   serializeBrandStrategy,
   serializeColor,

package/dist/{types-DF5StphJ.d.ts → types-BG-YT4JW.d.ts}

@@ -678,6 +678,12 @@ interface VisorThemeConfig {
         info?: string;
     };
     typography?: {
+        /**
+         * Type-scale multiplier applied to the `--font-size-*` ramp (VI-638).
+         * Every step is multiplied by it, and the page inherits the scaled
+         * `--font-size-base`. CSS adapters only — the Flutter adapter emits
+         * Material 3 slot sizes verbatim. Default: 1.
+         */
         scale?: number;
         /**
          * VI-375: text color placed on a LIGHT interactive background. Auto-picked
@@ -867,6 +873,12 @@ interface ResolvedThemeConfig {
     };
     "colors-dark"?: VisorThemeConfig["colors-dark"];
     typography: {
+        /**
+         * Type-scale multiplier applied to the `--font-size-*` ramp (VI-638).
+         * Every step is multiplied by it, and the page inherits the scaled
+         * `--font-size-base`. CSS adapters only — the Flutter adapter emits
+         * Material 3 slot sizes verbatim. Default: 1.
+         */
         scale: number;
         /**
          * VI-375: resolved default text color for LIGHT interactive backgrounds.

package/package.json

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

package/src/visor-theme.schema.json

@@ -187,7 +187,7 @@
         },
         "scale": {
           "type": "number",
-          "description": "Type scale multiplier applied to the font-size ramp. Default: 1."
+          "description": "Type scale multiplier applied to the font-size ramp: every --font-size-* step is multiplied by it, and the page inherits the scaled --font-size-base. Default: 1. CSS adapters only — the Flutter adapter emits Material 3 slot sizes verbatim and ignores this field."
         },
         "text-on-light": {
           "type": "string",