@loworbitstudio/visor-theme-engine 0.15.1 → 0.16.0

package/dist/adapters/index.d.ts

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

package/dist/fowt.d.ts

@@ -33,5 +33,50 @@ declare function generateFowtScript(options?: FowtOptions): string;
  *   <script>...paste FOWT_SCRIPT value...</script>
  */
 declare const FOWT_SCRIPT: string;
+/**
+ * Options for the theme-identity (palette) FOWT script.
+ *
+ * This axis is orthogonal to the dark/light MODE axis covered by
+ * {@link generateFowtScript}: it selects one of N registered themes (palettes)
+ * persisted in localStorage, rather than toggling a light/dark class. Consumers
+ * that switch BOTH axes at runtime can place both scripts in the same <head>.
+ */
+interface ThemeFowtOptions {
+    /**
+     * Allowlist of registered theme names. The stored value is validated against
+     * this list; anything not present (including a missing or corrupt value)
+     * falls back to {@link ThemeFowtOptions.defaultTheme}.
+     */
+    themes: string[];
+    /** Theme name to use when no valid preference is stored. */
+    defaultTheme: string;
+    /** localStorage key to read (default: "visor-theme-name"). */
+    storageKey?: string;
+    /**
+     * Attribute stamped on <html> with the resolved theme name, for the runtime
+     * switcher and tests to read (default: "data-theme-name").
+     */
+    attribute?: string;
+}
+/**
+ * Generate a pre-paint script for the theme-identity (palette) axis.
+ *
+ * The emitted script, run before first paint as a blocking <script> in <head>:
+ *   1. Reads the stored theme name from localStorage.
+ *   2. Validates it against the registered-theme allowlist; falls back to the
+ *      default when the stored value is unknown, absent, or unreadable.
+ *   3. Stamps the resolved name on <html> via the configured attribute.
+ *   4. Toggles `disabled` across every inlined `style[data-theme-css]` element,
+ *      enabling exactly the one matching the resolved theme.
+ *
+ * Place the inlined `style[data-theme-css="<name>"]` elements in <head> BEFORE
+ * this script so they exist when it runs.
+ *
+ * The output is ES5-safe (no arrow functions, no template literals) since it
+ * runs before any polyfills load. It mirrors the existing FOWT conventions:
+ * self-invoking, parser-blocking, try/catch-wrapped, allowlist-validated with a
+ * default fallback.
+ */
+declare function generateThemeFowtScript(options: ThemeFowtOptions): string;
 
-export { FOWT_SCRIPT, type FowtOptions, generateFowtScript };
+export { FOWT_SCRIPT, type FowtOptions, type ThemeFowtOptions, generateFowtScript, generateThemeFowtScript };

package/dist/fowt.js

@@ -17,7 +17,28 @@ function generateFowtScript(options) {
   ].join("\n");
 }
 var FOWT_SCRIPT = generateFowtScript();
+function generateThemeFowtScript(options) {
+  const key = options.storageKey ?? "visor-theme-name";
+  const attr = options.attribute ?? "data-theme-name";
+  const names = JSON.stringify(options.themes);
+  const fallback = JSON.stringify(options.defaultTheme);
+  return [
+    "(function() {",
+    "  try {",
+    "    var themes = " + names + ";",
+    '    var stored = localStorage.getItem("' + key + '");',
+    "    var active = themes.indexOf(stored) !== -1 ? stored : " + fallback + ";",
+    '    document.documentElement.setAttribute("' + attr + '", active);',
+    '    var styles = document.querySelectorAll("style[data-theme-css]");',
+    "    for (var i = 0; i < styles.length; i++) {",
+    '      styles[i].disabled = styles[i].getAttribute("data-theme-css") !== active;',
+    "    }",
+    "  } catch(e) {}",
+    "})();"
+  ].join("\n");
+}
 export {
   FOWT_SCRIPT,
-  generateFowtScript
+  generateFowtScript,
+  generateThemeFowtScript
 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, c as VisorBrand, B as BrandSlot, d as BrandSource, e as BrandResolution, f as ThemeBrandResult, R as ResolvedThemeConfig, g as GeneratedPrimitives, h as ThemeOutput, i as ThemeData, j as VisorThemeConfig, k as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, l as RGB, P as ParsedColor, O as OKLCH, m as SemanticTokens, n as ShadeStep } from './types-zug1_eLX.js';
-export { o as BRAND_VARIANTS, p as BrandVariant, q as ColorFormat, r as FontSource, s as RGBA, t as SemanticTokenValue } from './types-zug1_eLX.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, f as ThemeBrandResult, g as BrandStrategy, h as BrandStrategyContext, i as BrandStrategyIssue, j as BrandStrategyValidationResult, S as SerializedBrandStrategy, R as ResolvedThemeConfig, k as GeneratedPrimitives, l as ThemeOutput, m as ThemeData, n as VisorThemeConfig, o as FullShadeScale, C as ColorRole, p as SelectiveShadeScale, q as RGB, P as ParsedColor, O as OKLCH, r as SemanticTokens, s as ShadeStep } from './types-BstIS9rL.js';
+export { t as BRAND_VARIANTS, u as BRAND_VISIBILITIES, v as BrandArchetype, w as BrandGoverns, x as BrandLexiconEntry, y as BrandPersonalityTrait, z as BrandPillar, A as BrandPositioning, D as BrandStrategyIssueSeverity, E as BrandToneEntry, H as BrandVariant, I as BrandVisibility, J as BrandVoice, K as BrandVoiceTrait, L as ColorFormat, M as DEFAULT_BRAND_STRATEGY_SURFACES, N as DEFAULT_BRAND_STRATEGY_TONE_STATES, Q as FontSource, U as GOVERNS_WILDCARD, W as RGBA, X as SemanticTokenValue } from './types-BstIS9rL.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -236,6 +236,66 @@ declare function resolveThemeBrand(brand: VisorBrand | undefined, options?: {
     scope?: string;
 }): ThemeBrandResult;
 
+/**
+ * Brand-strategy validation (VI-505) — pure, engine-decoupled (D4).
+ *
+ * Two layers:
+ *  - {@link checkBrandStrategyStructure}: shape, types, required fields, enums.
+ *    No external context — catches malformed records.
+ *  - {@link checkBrandStrategyCoherence}: the D2 links — every `governs` target
+ *    resolves to a real token/component/surface, and every `tone` key maps to a
+ *    real UI state. The real-world sets are INJECTED via {@link BrandStrategyContext}
+ *    so this file never imports the engine's token map (keeps it liftable).
+ *
+ * {@link validateBrandStrategy} composes both into a structured result.
+ */
+
+/**
+ * Validate the shape of a `brand-strategy` block. Returns an error per problem
+ * (empty array = structurally valid). All ten top-level fields are required.
+ */
+declare function checkBrandStrategyStructure(block: unknown): BrandStrategyIssue[];
+/**
+ * Check the D2 links of a structurally-valid strategy: every `governs` target
+ * resolves to a real token/component/surface, and every `tone` key maps to a
+ * real UI state. Unknown links are errors — coherence drift fails the build the
+ * way token drift does.
+ *
+ * Each namespace is checked only when the caller supplies the matching set:
+ *  - `ctx.tokens` absent → token refs are not checked (the engine always
+ *    supplies it; a bare structural caller may not).
+ *  - `ctx.components` absent → only `"*"` is accepted for components (the engine
+ *    has no registry access; tests inject a set to exercise the named path).
+ *  - `ctx.surfaces` / `ctx.states` default to the recognized sets.
+ */
+declare function checkBrandStrategyCoherence(strategy: BrandStrategy, ctx?: BrandStrategyContext): BrandStrategyIssue[];
+/**
+ * Validate a `brand-strategy` block end to end: structure first, then (only if
+ * structurally valid) coherence against the injected context. Coherence
+ * findings inherit their severity (errors block; warnings don't).
+ */
+declare function validateBrandStrategy(block: unknown, ctx?: BrandStrategyContext): BrandStrategyValidationResult;
+
+/**
+ * Brand-strategy serialization (VI-505, D3).
+ *
+ * Projects a validated strategy into its agent-manifest form
+ * (`visor-manifest.json` → `brand_strategy`). The projection mirrors the
+ * authored shape so an agent reads `voice.traits` / `tone.error` the way it
+ * reads a component's `when_to_use`.
+ *
+ * PRIVACY: a `private` strategy (client brands) returns `null` and is never
+ * written to the public manifest. The caller omits the field when null.
+ */
+
+/**
+ * Serialize a validated brand strategy for the manifest. Returns `null` when
+ * `visibility: private`. Optional fields (`archetype.secondary`,
+ * `voice.traits[].example`, absent `governs` lists) are emitted only when
+ * present, so the agent reads a clean, predictable object.
+ */
+declare function serializeBrandStrategy(strategy: BrandStrategy): SerializedBrandStrategy | null;
+
 /**
  * Import Pipeline
  *
@@ -317,7 +377,7 @@ var properties = {
 	},
 	label: {
 		type: "string",
-		description: "Human-readable display name for the theme (e.g. 'Blacklight Pro'). Overrides the name-derived label in the docs theme switcher. Optional."
+		description: "Human-readable display name for the theme (e.g. 'My Brand Pro'). Overrides the name-derived label in the docs theme switcher. Optional."
 	},
 	"default-mode": {
 		type: "string",
@@ -704,6 +764,101 @@ var properties = {
 			]
 		}
 	},
+	"brand-strategy": {
+		type: "object",
+		description: "Brand-strategy block (VI-505) — positioning, personality, pillars, voice, and tone as validated, serializable data. Sibling to `brand` (assets): different lifecycle and consumer. NOT expanded into derived CSS values; coherence-checked (pillars govern real tokens/components/surfaces; tone keys map to real UI states) and serialized to the agent manifest under `brand_strategy`.",
+		additionalProperties: false,
+		required: [
+			"positioning",
+			"essence",
+			"personality",
+			"archetype",
+			"pillars",
+			"voice",
+			"tone",
+			"lexicon",
+			"core",
+			"visibility"
+		],
+		properties: {
+			positioning: {
+				$ref: "#/$defs/brandPositioning"
+			},
+			essence: {
+				type: "array",
+				items: {
+					type: "string"
+				},
+				minItems: 1,
+				description: "2–3 internal-facing core words (Aaker essence)."
+			},
+			personality: {
+				type: "array",
+				items: {
+					$ref: "#/$defs/brandPersonalityTrait"
+				},
+				minItems: 1,
+				description: "Brand-as-person traits, each sharpened by its antonym."
+			},
+			archetype: {
+				$ref: "#/$defs/brandArchetype"
+			},
+			pillars: {
+				type: "array",
+				items: {
+					$ref: "#/$defs/brandPillar"
+				},
+				minItems: 1,
+				description: "Strategic pillars — essence words made operational, each governing real tokens/components/surfaces."
+			},
+			voice: {
+				$ref: "#/$defs/brandVoice"
+			},
+			tone: {
+				type: "object",
+				description: "Voice flexed per UI state. Keys must be recognized UI states.",
+				minProperties: 1,
+				propertyNames: {
+					"enum": [
+						"error",
+						"success",
+						"warning",
+						"info",
+						"empty",
+						"loading",
+						"validation-warning"
+					]
+				},
+				additionalProperties: {
+					$ref: "#/$defs/brandToneEntry"
+				}
+			},
+			lexicon: {
+				type: "array",
+				items: {
+					$ref: "#/$defs/brandLexiconEntry"
+				},
+				minItems: 1,
+				description: "Words to use and the ones to avoid."
+			},
+			core: {
+				type: "array",
+				items: {
+					type: "string"
+				},
+				minItems: 1,
+				description: "Aaker core/extended — the immutable subset, as section names."
+			},
+			visibility: {
+				type: "string",
+				"enum": [
+					"public",
+					"private"
+				],
+				description: "Client brands are private and are omitted from the public agent manifest."
+			}
+		}
+	},
 	spacing: {
 		type: "object",
 		description: "Spacing configuration.",
@@ -925,6 +1080,224 @@ var $defs = {
 				description: "Letter spacing in logical pixels (Flutter TextStyle.letterSpacing). Material defaults include negative values, e.g. -0.25 for displayLarge."
 			}
 		}
+	},
+	brandPositioning: {
+		type: "object",
+		description: "Positioning — the onliness, category, and differentiation wedge.",
+		additionalProperties: false,
+		required: [
+			"onliness",
+			"category",
+			"differentiation"
+		],
+		properties: {
+			onliness: {
+				type: "string",
+				minLength: 1,
+				description: "The single sentence that passes Neumeier's \"only\" test."
+			},
+			category: {
+				type: "string",
+				minLength: 1,
+				description: "The category the brand competes in (e.g. \"design system\")."
+			},
+			differentiation: {
+				type: "string",
+				minLength: 1,
+				description: "What sets the brand apart within that category."
+			}
+		}
+	},
+	brandPersonalityTrait: {
+		type: "object",
+		description: "A personality trait sharpened by its antonym (brand-as-person).",
+		additionalProperties: false,
+		required: [
+			"trait",
+			"not"
+		],
+		properties: {
+			trait: {
+				type: "string",
+				minLength: 1
+			},
+			not: {
+				type: "string",
+				minLength: 1,
+				description: "The antonym — what the trait is not."
+			}
+		}
+	},
+	brandArchetype: {
+		type: "object",
+		description: "Brand archetype assignment (Pearson & Mark). Primary required; secondary/tertiary optional.",
+		additionalProperties: false,
+		required: [
+			"primary"
+		],
+		properties: {
+			primary: {
+				type: "string",
+				minLength: 1
+			},
+			secondary: {
+				type: "string",
+				minLength: 1
+			},
+			tertiary: {
+				type: "string",
+				minLength: 1
+			}
+		}
+	},
+	brandGoverns: {
+		type: "object",
+		description: "What a pillar governs — design tokens, registry components, and/or meta-surfaces. At least one list is expected; use \"*\" for all of a namespace.",
+		additionalProperties: false,
+		minProperties: 1,
+		properties: {
+			tokens: {
+				type: "array",
+				items: {
+					type: "string"
+				},
+				minItems: 1,
+				description: "Semantic token refs (with or without the leading --), or \"*\"."
+			},
+			components: {
+				type: "array",
+				items: {
+					type: "string"
+				},
+				minItems: 1,
+				description: "Registry component names, or \"*\" for all."
+			},
+			surfaces: {
+				type: "array",
+				items: {
+					type: "string",
+					"enum": [
+						"manifest",
+						"cli",
+						"component-metadata"
+					]
+				},
+				minItems: 1,
+				description: "Meta-surfaces a pillar may govern."
+			}
+		}
+	},
+	brandPillar: {
+		type: "object",
+		description: "A strategic pillar — an essence word made operational.",
+		additionalProperties: false,
+		required: [
+			"id",
+			"statement",
+			"governs"
+		],
+		properties: {
+			id: {
+				type: "string",
+				minLength: 1
+			},
+			statement: {
+				type: "string",
+				minLength: 1,
+				description: "The pillar's claim in one line."
+			},
+			governs: {
+				$ref: "#/$defs/brandGoverns"
+			}
+		}
+	},
+	brandVoice: {
+		type: "object",
+		description: "Voice — fixed across the brand; never flexes.",
+		additionalProperties: false,
+		required: [
+			"traits"
+		],
+		properties: {
+			traits: {
+				type: "array",
+				items: {
+					$ref: "#/$defs/brandVoiceTrait"
+				},
+				minItems: 1
+			}
+		}
+	},
+	brandVoiceTrait: {
+		type: "object",
+		description: "A fixed voice trait with a worked example.",
+		additionalProperties: false,
+		required: [
+			"name",
+			"do",
+			"dont"
+		],
+		properties: {
+			name: {
+				type: "string",
+				minLength: 1
+			},
+			"do": {
+				type: "string",
+				minLength: 1,
+				description: "What to do."
+			},
+			dont: {
+				type: "string",
+				minLength: 1,
+				description: "What not to do."
+			},
+			example: {
+				type: "string",
+				minLength: 1,
+				description: "A worked example sentence."
+			}
+		}
+	},
+	brandToneEntry: {
+		type: "object",
+		description: "A single tone entry, keyed (in `tone`) to a recognized UI state.",
+		additionalProperties: false,
+		required: [
+			"feeling",
+			"example"
+		],
+		properties: {
+			feeling: {
+				type: "string",
+				minLength: 1,
+				description: "The feeling the copy should evoke in this state."
+			},
+			example: {
+				type: "string",
+				minLength: 1,
+				description: "A worked example message for this state."
+			}
+		}
+	},
+	brandLexiconEntry: {
+		type: "object",
+		description: "A lexicon pairing — the word to use and the one to avoid.",
+		additionalProperties: false,
+		required: [
+			"use",
+			"avoid"
+		],
+		properties: {
+			use: {
+				type: "string",
+				minLength: 1
+			},
+			avoid: {
+				type: "string",
+				minLength: 1
+			}
+		}
 	}
 };
 var visorTheme_schema = {
@@ -1178,6 +1551,19 @@ declare const SEMANTIC_MAP: {
     intent: Record<string, SemanticMapping>;
     hairline: Record<string, SemanticMapping>;
 };
+/**
+ * The full set of emitted semantic token names, WITHOUT the leading `--`,
+ * spanning all six groups. The prefixed groups emit as `--{group}-{key}`; the
+ * bare intent aliases emit as `--{key}` (e.g. `--primary`); hairlines emit as
+ * `--hairline` / `--hairline-strong`.
+ *
+ * Used by brand-strategy coherence (VI-505) to verify a pillar governs a real
+ * token. Distinct from validate.ts's `KNOWN_SEMANTIC_TOKENS` (the four prefixed
+ * groups only, used for override-key validation) — this set additionally
+ * includes the bare intent aliases and hairlines, which a `brand-strategy`
+ * pillar may legitimately govern (Visor's own record governs `--primary`).
+ */
+declare function getKnownTokenRefs(): Set<string>;
 
 /**
  * Per-theme font-family aliasing — substrate fix for VI-354.
@@ -1298,4 +1684,4 @@ declare function cleanFontValue(val: string): string;
  */
 declare function extractFromCSS(files: CSSFile[], name?: string): ExtractionResult;
 
-export { type BrandPassthrough, BrandResolution, BrandSlot, BrandSource, 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, 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, clampToSrgb, cleanFontValue, collectBrandPassthrough, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, 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, serializeColor, validate, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };
+export { type BrandPassthrough, BrandResolution, BrandSlot, BrandSource, BrandStrategy, BrandStrategyContext, BrandStrategyIssue, BrandStrategyValidationResult, type CSSFile, ColorRole, type Confidence, DEFAULT_VISOR_BRAND, type ExtractedToken, type ExtractionResult, FONT_WEIGHT_ALIASES, type FontCoverageError, type FontCoverageResult, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, SerializedBrandStrategy, ShadeStep, TAILWIND_GRAY, ThemeBrandResult, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_BRANDS_CDN, VISOR_DEFAULT_BRAND_PATH, VISOR_FONTS_CDN, type ValidateOptions, type ValidationIssue, type ValidationSeverity, VisorBrand, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorBrandUrl, buildVisorFontUrl, checkBrandStrategyCoherence, checkBrandStrategyStructure, clampToSrgb, cleanFontValue, collectBrandPassthrough, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, getKnownTokenRefs, 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 };