@loworbitstudio/visor-theme-engine 0.19.0 → 0.21.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

@@ -6,12 +6,16 @@ import {
   block,
   buildVisorFontUrl,
   collectBrandPassthrough,
+  collectDeclaredProperties,
   fontStack,
   generateDarkCss,
+  generateFontSizeDecls,
+  generateFontWeightDecls,
   generateHairlineDecls,
   generateIntentDecls,
   generateLightCss,
   generatePrimitivesCss,
+  generateSemanticAliasDecls,
   generateShadeScale,
   generateSpaceAliasDecls,
   generateTextScaleAliasDecls,
@@ -21,7 +25,7 @@ import {
   resolveThemeBrand,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-32DC5DAR.js";
+} from "../chunk-LY5LXQYE.js";
 
 // src/adapters/brand-passthrough.ts
 var SENTINEL_COLOR = "#ff00ff";
@@ -212,7 +216,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));"
       ])
@@ -295,14 +303,27 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
     }
     semanticLines.push("");
   }
+  const lightBody = stripHeader(generateLightCss(input.tokens, { scopePrefix, colorScheme }));
+  const darkBody = stripHeader(generateDarkCss(input.tokens, { scopePrefix, colorScheme }));
+  const adaptiveBody = [lightBody, darkBody].filter(Boolean).join("\n\n");
+  if (scopePrefix) {
+    const declared = collectDeclaredProperties(
+      [primitivesBody, semanticLines.join("\n"), adaptiveBody].join("\n")
+    );
+    const aliasDecls = generateSemanticAliasDecls(declared);
+    if (aliasDecls.length > 0) {
+      semanticLines.push(
+        sectionComment("visor-core alias re-substitution at theme scope (VI-648)")
+      );
+      semanticLines.push(block(hostSelector, aliasDecls));
+      semanticLines.push("");
+    }
+  }
   const semanticLayer = wrapInLayer("visor-semantic", semanticLines.join("\n").trim());
   if (semanticLayer) {
     lines.push(semanticLayer);
     lines.push("");
   }
-  const lightBody = stripHeader(generateLightCss(input.tokens, { scopePrefix, colorScheme }));
-  const darkBody = stripHeader(generateDarkCss(input.tokens, { scopePrefix, colorScheme }));
-  const adaptiveBody = [lightBody, darkBody].filter(Boolean).join("\n\n");
   lines.push(
     wrapInLayer("visor-adaptive", adaptiveBody)
   );
@@ -537,23 +558,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 +692,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 +705,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 +714,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-LY5LXQYE.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,
@@ -2392,6 +2484,86 @@ function generateFullBundleCss(primitives, tokens, config) {
   return lines.join("\n");
 }
 
+// src/semantic-aliases.ts
+var VISOR_CORE_SEMANTIC_ALIASES = {
+  // Border — the one entry the engine's own `SemanticTokens.border` set lacks.
+  "border-input": "color-neutral-200",
+  // Component + layout spacing (4px grid multiples).
+  "component-xs": "spacing-1",
+  "component-sm": "spacing-2",
+  "component-md": "spacing-4",
+  "component-lg": "spacing-6",
+  "component-xl": "spacing-8",
+  "layout-sm": "spacing-4",
+  "layout-md": "spacing-8",
+  "layout-lg": "spacing-12",
+  "layout-xl": "spacing-16",
+  "layout-2xl": "spacing-24",
+  "layout-section-padding": "spacing-24",
+  "layout-section-padding-mobile": "spacing-16",
+  // Typography size roles — track the theme's `typography.scale` ramp.
+  "size-body": "font-size-base",
+  "size-body-sm": "font-size-sm",
+  "size-label": "font-size-sm",
+  "size-caption": "font-size-xs",
+  "size-heading-sm": "font-size-lg",
+  "size-heading-md": "font-size-xl",
+  "size-heading-lg": "font-size-2xl",
+  "size-heading-xl": "font-size-3xl",
+  // Typography weight roles — `--weight-heading` is the token VI-648 was filed on.
+  "weight-body": "font-weight-body",
+  "weight-label": "font-weight-medium",
+  "weight-heading": "font-weight-heading",
+  "weight-strong": "font-weight-bold",
+  // Motion. `--motion-easing-spring` is absent because the engine emits it
+  // under its own name, so it is already correct on the scope.
+  "motion-duration-fast": "motion-duration-100",
+  "motion-duration-normal": "motion-duration-200",
+  "motion-duration-slow": "motion-duration-500",
+  "motion-easing-default": "motion-easing-ease-in-out",
+  "motion-easing-enter": "motion-easing-ease-out",
+  "motion-easing-exit": "motion-easing-ease-in",
+  // Skeleton shimmer. Resolves through *semantic* surfaces, not primitives —
+  // the engine emits those in `visor-adaptive`, a later layer, which does not
+  // affect substitution: `var()` reads the computed value on the element.
+  "skeleton-from": "surface-muted",
+  "skeleton-to": "surface-subtle",
+  // Chart series.
+  "chart-1": "color-primary-500",
+  "chart-2": "color-success-500",
+  "chart-3": "color-warning-500",
+  "chart-4": "color-info-500",
+  "chart-5": "color-error-500",
+  // Sidebar chrome.
+  "sidebar-bg": "color-neutral-50",
+  "sidebar-text": "color-neutral-700",
+  "sidebar-primary-bg": "color-primary-600",
+  "sidebar-primary-text": "color-white",
+  "sidebar-accent-bg": "color-neutral-100",
+  "sidebar-accent-text": "color-neutral-900",
+  "sidebar-border": "color-neutral-200",
+  "sidebar-ring": "color-primary-500",
+  "sidebar-text-muted": "color-neutral-500",
+  // Field-attached floating panels (VI-497).
+  "field-menu-bg": "surface-popover"
+};
+function collectDeclaredProperties(css) {
+  const declared = /* @__PURE__ */ new Set();
+  for (const match of css.matchAll(/(^|[{;\s])--([a-zA-Z0-9-]+)\s*:/g)) {
+    declared.add(match[2]);
+  }
+  return declared;
+}
+function generateSemanticAliasDecls(declared) {
+  const decls = [];
+  for (const [alias, referent] of Object.entries(VISOR_CORE_SEMANTIC_ALIASES)) {
+    if (declared.has(alias)) continue;
+    if (!declared.has(referent)) continue;
+    decls.push(`--${alias}: var(--${referent});`);
+  }
+  return decls;
+}
+
 // src/types.ts
 var MATERIAL_TEXT_SLOTS = [
   "displayLarge",
@@ -2464,11 +2636,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,
@@ -2477,5 +2657,8 @@ export {
   generateHairlineDecls,
   generateLightCss,
   generateDarkCss,
-  generateFullBundleCss
+  generateFullBundleCss,
+  VISOR_CORE_SEMANTIC_ALIASES,
+  collectDeclaredProperties,
+  generateSemanticAliasDecls
 };

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",
@@ -1876,6 +1876,87 @@ declare const SEMANTIC_MAP: {
  */
 declare function getKnownTokenRefs(): Set<string>;
 
+/**
+ * visor-core semantic aliases that need re-substituting at a theme scope (VI-648).
+ *
+ * `packages/tokens` emits its semantic layer as indirections — `--chart-1:
+ * var(--color-primary-500)`, `--weight-heading: var(--font-weight-heading)` —
+ * declared on `:root`.
+ *
+ * Custom-property substitution resolves **where the property is declared**. On
+ * a `scopePrefix` theme (the VI-368 body-class repaint pattern that every
+ * Blacklight theme uses) the engine emits the theme's primitives on the scope
+ * selector, e.g. `body.blacklight-pro-theme`. From `:root`, a descendant's
+ * value is invisible, so `var(--color-primary-500)` sees only visor-core's
+ * untuned default. `body` then *inherits* the already-substituted default, and
+ * the alias silently ignores the theme:
+ *
+ * ```
+ * --font-weight-heading : 500   <- correct, emitted by the engine on the scope
+ * --weight-heading      : 600   <- visor-core's :root default
+ * --chart-1             : #3b82f6   <- stock blue on a monochrome theme
+ * --skeleton-from       : #f3f4f6   <- light gray on a dark theme
+ * ```
+ *
+ * The engine independently resolves 66 of visor-core's 114 aliases to concrete
+ * values (`--text-*`, `--surface-*`, `--border-*`, `--interactive-*`, `--font-*`)
+ * and emits those on the scope already, so they are correct. The 48 below are
+ * the ones only visor-core knows how to derive. Re-declaring them on the scope
+ * selector makes the substitution happen there, against the theme's own
+ * primitives.
+ *
+ * ## Why this table lives in the engine, not in `packages/tokens`
+ *
+ * `packages/tokens` is the natural owner — these are its aliases. But
+ * `packages/tokens` already depends on this package (its build calls
+ * `generateThemeData` + `docsAdapter` to emit `dist/themes/<slug>.css`), so an
+ * engine → tokens import would be a build cycle. The table therefore sits on
+ * the importable side of that edge.
+ *
+ * It is not a hand-maintained copy. `packages/tokens` owns the authoring
+ * tables in `src/tokens/semantic.ts` and this list is asserted against the
+ * *emitted* `tokens.css` by `semantic-alias-coverage` — a stronger check than
+ * comparing two constants, because it compares against what actually ships.
+ * Adding an alias in `packages/tokens` without adding it here fails that test
+ * with the missing names.
+ */
+/**
+ * Alias name → the token it resolves through. Both written without the leading
+ * `--`. Order mirrors visor-core's emission order in `tokens.css`, which keeps
+ * a diff against that file readable.
+ */
+declare const VISOR_CORE_SEMANTIC_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Every custom property declared anywhere in `css`, without the leading `--`.
+ *
+ * Read off the generated CSS rather than the token data so the filter in
+ * `generateSemanticAliasDecls` reflects what this theme *actually* emits —
+ * including conditional output such as the `--font-weight-<n>` ladder, which
+ * only appears when a theme declares an explicit `weights` array.
+ */
+declare function collectDeclaredProperties(css: string): Set<string>;
+/**
+ * The `--alias: var(--referent);` declarations to re-emit on a theme's scope
+ * selector, given everything the theme has emitted so far.
+ *
+ * Filtered on both sides, so the table can never make output worse:
+ *
+ * - **Skip an alias the theme already declares.** The theme's own value is
+ *   authoritative, and re-declaring it in `visor-semantic` would override a
+ *   `visor-primitives` declaration of the same name. `--font-body` is the live
+ *   case: the engine emits it as a concrete family, and re-aliasing it to
+ *   `var(--font-sans)` would win the layer contest and resolve to nothing.
+ * - **Skip an alias whose referent the theme does not declare.** There is then
+ *   nothing to re-resolve against, and inheriting visor-core's `:root` value is
+ *   the correct outcome — re-emitting would replace a working value with an
+ *   invalid one.
+ *
+ * Returns `[]` for a `:root`-scoped theme's caller, which does not need this at
+ * all: there, visor-core's aliases and the theme's primitives are declared on
+ * the same element, so substitution already sees the theme's values.
+ */
+declare function generateSemanticAliasDecls(declared: ReadonlySet<string>): string[];
+
 /**
  * Per-theme font-family aliasing — substrate fix for VI-354.
  *
@@ -1922,6 +2003,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 +2207,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_CORE_SEMANTIC_ALIASES, 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, collectDeclaredProperties, compositeOverBackground, declaresWeights, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFontWeightDecls, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticAliasDecls, 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

@@ -7,21 +7,27 @@ import {
   MATERIAL_TEXT_SLOTS,
   TAILWIND_GRAY,
   VISOR_BRANDS_CDN,
+  VISOR_CORE_SEMANTIC_ALIASES,
   VISOR_DEFAULT_BRAND_PATH,
   VISOR_FONTS_CDN,
+  WEIGHT_RAMP_TARGETS,
   allComponentTokenNames,
   applyOverrides,
   buildVisorBrandUrl,
   buildVisorFontUrl,
   clampToSrgb,
   collectBrandPassthrough,
+  collectDeclaredProperties,
   componentTokenName,
   compositeOverBackground,
+  declaresWeights,
   generateDarkCss,
+  generateFontWeightDecls,
   generateFullBundleCss,
   generateLightCss,
   generatePreloadLinks,
   generatePrimitivesCss,
+  generateSemanticAliasDecls,
   generateSemanticCss,
   generateShadeScale,
   generateStylesheetLinks,
@@ -34,8 +40,10 @@ import {
   hexToRgb,
   isValidColor,
   isValidHex,
+  loadedWeights,
   lookupFontWeightAlias,
   lookupGoogleFont,
+  matchLoadedWeight,
   normalizeHex,
   oklchToHex,
   parseColor,
@@ -47,13 +55,15 @@ import {
   resolveBrandSource,
   resolveComponentBindings,
   resolveFont,
+  resolveRoleWeight,
   resolveThemeBrand,
   resolveThemeFonts,
+  resolveWeightRamp,
   rgbToHex,
   rgbToOklch,
   serializeColor,
   validateComponentBindings
-} from "./chunk-32DC5DAR.js";
+} from "./chunk-LY5LXQYE.js";
 
 // src/fonts/validate-coverage.ts
 var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
@@ -793,7 +803,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 +3147,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 +3693,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 = [];
@@ -4214,8 +4265,10 @@ export {
   SEMANTIC_MAP,
   TAILWIND_GRAY,
   VISOR_BRANDS_CDN,
+  VISOR_CORE_SEMANTIC_ALIASES,
   VISOR_DEFAULT_BRAND_PATH,
   VISOR_FONTS_CDN,
+  WEIGHT_RAMP_TARGETS,
   allComponentTokenNames,
   applyOverrides,
   assignSemanticTokens,
@@ -4226,17 +4279,21 @@ export {
   clampToSrgb,
   cleanFontValue,
   collectBrandPassthrough,
+  collectDeclaredProperties,
   componentTokenName,
   compositeOverBackground,
+  declaresWeights,
   exportTheme,
   extractFromCSS,
   formatFontCoverageError,
   generateDarkCss,
+  generateFontWeightDecls,
   generateFullBundleCss,
   generateLightCss,
   generatePreloadLinks,
   generatePrimitives,
   generatePrimitivesCss,
+  generateSemanticAliasDecls,
   generateSemanticCss,
   generateShadeScale,
   generateStylesheetLinks,
@@ -4255,8 +4312,10 @@ export {
   isValidColor,
   isValidHex,
   isVisorThemeConfig,
+  loadedWeights,
   lookupFontWeightAlias,
   lookupGoogleFont,
+  matchLoadedWeight,
   normalizeHex,
   oklchToHex,
   parseCSSDeclarations,
@@ -4272,8 +4331,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.21.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",