@pantoken/utils 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -60,33 +60,9 @@ declare function focusOutlineDeclarations(): [name: string, value: string][];
  */
 declare function focusOutlineRules(selector?: string): string;
 //#endregion
-//#region src/index.d.ts
+//#region src/resolver.d.ts
 /** The colour mode to collapse `light-dark()` to. */
 type Mode = "light" | "dark";
-/** One entry of the pantoken spacing scale: the short key, the long (word) key, and the shared CSS value. */
-interface SpacingStep {
-  /** The short scale key, e.g. `"sm"` (the zero step's short key is `"0"`). */
-  short: string;
-  /** The long, word-spelled key, e.g. `"small"` (the zero step's long key is `"none"`). */
-  long: string;
-  /** The CSS value — a token reference, or a plain `"0"`/`"auto"`. */
-  value: string;
-}
-/**
- * The pantoken spacing scale, `none`/`0` → `2xl` — the single shared source for
- * `@pantoken/components`' spacing/gap utilities and `@pantoken/interactions`' `resolveSpace`, so the
- * two never drift apart.
- */
-declare const SPACING_STEPS: readonly SpacingStep[];
-/** The `auto` step — margin only, spelled the same both ways. */
-declare const SPACING_AUTO_STEP: SpacingStep;
-/**
- * Strip `<script>` elements and event-handler attributes from SVG markup.
- *
- * Defense-in-depth for SVG decoded from vendored data URIs or contributed by plugins.
- * Not a full HTML parser — relies on the upstream source being trusted and pinned.
- */
-declare function sanitizeSvg(svg: string): string;
 /** A `var(--custom-prop)` reference (optional fallback); capture group 1 is the property name. */
 declare const VAR_RE: RegExp;
 /** A `light-dark(<light>, <dark>)` value; capture groups 1 and 2 are the two branches. */
@@ -172,38 +148,8 @@ declare function makeResolver(base: readonly Token[], options?: ResolveOptions):
  * ```
  */
 declare function resolveTokens(base: readonly Token[], options?: ResolveOptions): Map<string, string>;
-/**
- * Convert a kebab-case string to camelCase (`color-background-brand` → `colorBackgroundBrand`).
- *
- * @example
- * ```ts
- * import { camelCase } from "@pantoken/utils";
- *
- * camelCase("color-background-brand"); // → "colorBackgroundBrand"
- * ```
- */
-declare function camelCase(kebab: string): string;
-/** An RGBA colour: `r`/`g`/`b` are 0–255 integers, `a` is 0–1 (defaults to 1). */
-interface Rgba {
-  r: number;
-  g: number;
-  b: number;
-  a: number;
-}
-/**
- * Parse `#rgb`, `#rrggbb`, or `#rrggbbaa` to {@link Rgba}; returns `undefined` otherwise.
- *
- * @example
- * ```ts
- * import { parseHexColor } from "@pantoken/utils";
- *
- * parseHexColor("#fff");      // → { r: 255, g: 255, b: 255, a: 1 }
- * parseHexColor("#0374B5");   // → { r: 3, g: 116, b: 181, a: 1 }
- * parseHexColor("#00000080"); // → { r: 0, g: 0, b: 0, a: 0.5019… }
- * parseHexColor("nope");      // → undefined
- * ```
- */
-declare function parseHexColor(hex: string): Rgba | undefined;
+//#endregion
+//#region src/drift.d.ts
 /**
  * Every `--instui-*` custom-property name that appears anywhere in `text`.
  *
@@ -277,6 +223,101 @@ declare function unknownReferences(text: string, ir: readonly Token[]): string[]
  * ```
  */
 declare function danglingReferences(css: string): string[];
+//#endregion
+//#region src/case.d.ts
+/**
+ * Convert a kebab-case string to camelCase (`color-background-brand` → `colorBackgroundBrand`).
+ *
+ * @module
+ */
+/**
+ * Convert a kebab-case string to camelCase (`color-background-brand` → `colorBackgroundBrand`).
+ *
+ * @example
+ * ```ts
+ * import { camelCase } from "@pantoken/utils";
+ *
+ * camelCase("color-background-brand"); // → "colorBackgroundBrand"
+ * ```
+ */
+declare function camelCase(kebab: string): string;
+//#endregion
+//#region src/color.d.ts
+/**
+ * Hex-colour parsing (`#rgb`/`#rrggbb`/`#rrggbbaa` → {@link Rgba}).
+ *
+ * @module
+ */
+/** An RGBA colour: `r`/`g`/`b` are 0–255 integers, `a` is 0–1 (defaults to 1). */
+interface Rgba {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+/**
+ * Parse `#rgb`, `#rrggbb`, or `#rrggbbaa` to {@link Rgba}; returns `undefined` otherwise.
+ *
+ * @example
+ * ```ts
+ * import { parseHexColor } from "@pantoken/utils";
+ *
+ * parseHexColor("#fff");      // → { r: 255, g: 255, b: 255, a: 1 }
+ * parseHexColor("#0374B5");   // → { r: 3, g: 116, b: 181, a: 1 }
+ * parseHexColor("#00000080"); // → { r: 0, g: 0, b: 0, a: 0.5019… }
+ * parseHexColor("nope");      // → undefined
+ * ```
+ */
+declare function parseHexColor(hex: string): Rgba | undefined;
+//#endregion
+//#region src/svg.d.ts
+/**
+ * SVG sanitization for glyphs decoded from vendored data URIs or contributed by plugins.
+ *
+ * @module
+ */
+/**
+ * Strip `<script>` elements and event-handler attributes from SVG markup.
+ *
+ * Defense-in-depth for SVG decoded from vendored data URIs or contributed by plugins.
+ * Not a full HTML parser — relies on the upstream source being trusted and pinned.
+ */
+declare function sanitizeSvg(svg: string): string;
+//#endregion
+//#region src/spacing.d.ts
+/**
+ * The pantoken spacing scale — the single shared source for `@pantoken/components`' spacing/gap
+ * utilities and `@pantoken/interactions`' `resolveSpace`, so the two never drift apart.
+ *
+ * @module
+ */
+/** One entry of the pantoken spacing scale: the short key, the long (word) key, and the shared CSS value. */
+interface SpacingStep {
+  /** The short scale key, e.g. `"sm"` (the zero step's short key is `"0"`). */
+  short: string;
+  /** The long, word-spelled key, e.g. `"small"` (the zero step's long key is `"none"`). */
+  long: string;
+  /** The CSS value — a token reference, or a plain `"0"`/`"auto"`. */
+  value: string;
+}
+/**
+ * The pantoken spacing scale, `none`/`0` → `2xl` — the single shared source for
+ * `@pantoken/components`' spacing/gap utilities and `@pantoken/interactions`' `resolveSpace`, so the
+ * two never drift apart.
+ */
+declare const SPACING_STEPS: readonly SpacingStep[];
+/** The `auto` step — margin only, spelled the same both ways. */
+declare const SPACING_AUTO_STEP: SpacingStep;
+//#endregion
+//#region src/utility-css.d.ts
+/**
+ * Token → utility-class emitters. Pure string transforms (token name → `.class { prop: var(--token) }`),
+ * with no InstUI-look opinion — the caller supplies which token names to render. `@pantoken/components`
+ * feeds them a curated *semantic* allowlist; `@pantoken/plugin-primitives` feeds the raw palette. They
+ * live here (not in a format) so the primitive tier doesn't have to reach up into the component library.
+ *
+ * @module
+ */
 /** Options shared by the utility-class emitters. */
 interface UtilityOptions {
   /**
@@ -284,18 +325,30 @@ interface UtilityOptions {
    * falsy value (`null`/`undefined`/`""`) drops the prefix entirely (`.bg-…`).
    */
   prefix?: string | null;
+  /**
+   * Component base-class names (e.g. `"button"`, `"view"`) to also emit a chained alias for, per
+   * rule — `.<prefix>-bg-danger` (bare) plus `.<prefix>-button.-bg-danger` (chained), so the same
+   * modifier works standalone or attached to any component. Omit for bare-only output (unchanged
+   * behavior).
+   */
+  chainTargets?: readonly string[];
 }
-/** The semantic colour token names (without the `--instui-color-<family>-` prefix) per family. */
+/** One semantic colour family entry: a bare name (resolved against `--instui-color-<family>-<name>`)
+ *  or an explicit `[name, value]` pair — the second element is `var()`-wrapped if it's a `--custom-prop`
+ *  name, or used verbatim otherwise (a `light-dark(…)` expression, a raw keyword like `transparent`). */
+type ColorUtilityEntry = string | readonly [name: string, value: string];
+/** The semantic colour token names (or explicit `[name, token]` pairs) per family. */
 interface ColorUtilityNames {
-  background: readonly string[];
-  text: readonly string[];
-  stroke: readonly string[];
+  background: readonly ColorUtilityEntry[];
+  text: readonly ColorUtilityEntry[];
+  stroke: readonly ColorUtilityEntry[];
 }
 /**
  * Build the semantic-colour utility stylesheet: `.<prefix>-bg-<name>` (background),
- * `.<prefix>-fg-<name>` (text colour), `.<prefix>-border-<name>` (border colour), one per semantic
+ * `.<prefix>-text-<name>` (text colour), `.<prefix>-border-<name>` (border colour), one per semantic
  * colour token. Overrides are therefore only ever token-valid — no primitives, no arbitrary hex. Pass
- * the token names per family (e.g. from `@pantoken/tokens`).
+ * the token names per family (e.g. from `@pantoken/tokens`), or an explicit `[name, token]` pair to
+ * source a name from a different token than the family's own scale.
  *
  * @param names - {@link ColorUtilityNames}.
  * @param options - {@link UtilityOptions}.
@@ -328,4 +381,4 @@ interface TokenUtilityGroup {
  */
 declare function tokenUtilitiesCss(groups: readonly TokenUtilityGroup[], options?: UtilityOptions): string;
 //#endregion
-export { ColorUtilityNames, ELEVATION_NAMES, FOCUSABLE_SELECTOR, LIGHT_DARK_RE, Mode, ResolveOptions, Rgba, SPACING_AUTO_STEP, SPACING_STEPS, SpacingStep, TokenUtilityGroup, UtilityOptions, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, elevationDeclarations, extractInstuiRefs, focusOutlineDeclarations, focusOutlineRules, makeResolver, parseHexColor, resolveTokens, sanitizeSvg, tokenNames, tokenUtilitiesCss, unknownReferences };
+export { type ColorUtilityEntry, type ColorUtilityNames, ELEVATION_NAMES, FOCUSABLE_SELECTOR, LIGHT_DARK_RE, type Mode, type ResolveOptions, type Rgba, SPACING_AUTO_STEP, SPACING_STEPS, type SpacingStep, type TokenUtilityGroup, type UtilityOptions, VAR_RE, camelCase, colorUtilitiesCss, danglingReferences, elevationDeclarations, extractInstuiRefs, focusOutlineDeclarations, focusOutlineRules, makeResolver, parseHexColor, resolveTokens, sanitizeSvg, tokenNames, tokenUtilitiesCss, unknownReferences };

package/dist/index.mjs

@@ -117,91 +117,13 @@ function focusOutlineRules(selector = FOCUSABLE_SELECTOR) {
 	].join("\n");
 }
 //#endregion
-//#region src/index.ts
+//#region src/resolver.ts
 /**
-* `@pantoken/utils` — shared, upstream-free helpers used across the pantoken packages: the token
-* reference resolver (with `light-dark()` handling), the two token regexes (typed via `arkregex`),
-* kebab→camel case, hex-colour parsing, the shared spacing scale ({@link SPACING_STEPS}), and the
-* generic token→utility-class emitters ({@link colorUtilitiesCss}, {@link tokenUtilitiesCss}) that
-* both `@pantoken/components` (semantic tier) and `@pantoken/plugin-primitives` (raw-palette tier)
-* build on. Depends only on `@pantoken/model` (types) + `arkregex`, so any package can use it without
-* pulling the GitHub-only upstream.
+* The token reference resolver: expands `var(--x)` chains to concrete leaf values, with optional
+* `light-dark()` collapsing.
 *
 * @module
-* @beta
 */
-/**
-* The pantoken spacing scale, `none`/`0` → `2xl` — the single shared source for
-* `@pantoken/components`' spacing/gap utilities and `@pantoken/interactions`' `resolveSpace`, so the
-* two never drift apart.
-*/
-const SPACING_STEPS = [
-	{
-		short: "0",
-		long: "none",
-		value: "var(--instui-component-shared-tokens-spacing-general-space-none)"
-	},
-	{
-		short: "2xs",
-		long: "xx-small",
-		value: "var(--instui-spacing-space2xs)"
-	},
-	{
-		short: "xs",
-		long: "x-small",
-		value: "var(--instui-spacing-space-xs)"
-	},
-	{
-		short: "sm",
-		long: "small",
-		value: "var(--instui-spacing-space-sm)"
-	},
-	{
-		short: "md",
-		long: "medium",
-		value: "var(--instui-spacing-space-md)"
-	},
-	{
-		short: "lg",
-		long: "large",
-		value: "var(--instui-spacing-space-lg)"
-	},
-	{
-		short: "xl",
-		long: "x-large",
-		value: "var(--instui-spacing-space-xl)"
-	},
-	{
-		short: "2xl",
-		long: "xx-large",
-		value: "var(--instui-spacing-space2xl)"
-	}
-];
-/** The `auto` step — margin only, spelled the same both ways. */
-const SPACING_AUTO_STEP = {
-	short: "auto",
-	long: "auto",
-	value: "auto"
-};
-/**
-* Strip `<script>` elements and event-handler attributes from SVG markup.
-*
-* Defense-in-depth for SVG decoded from vendored data URIs or contributed by plugins.
-* Not a full HTML parser — relies on the upstream source being trusted and pinned.
-*/
-function sanitizeSvg(svg) {
-	let sanitized = svg;
-	let previous;
-	do {
-		previous = sanitized;
-		sanitized = sanitized.replace(/<script\b[^>]*>[\s\S]*?<\/script\b[^>]*>/gi, "");
-	} while (sanitized !== previous);
-	do {
-		previous = sanitized;
-		sanitized = sanitized.replace(/\son\w+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "");
-	} while (sanitized !== previous);
-	return sanitized;
-}
 const VAR_SOURCE = "var\\(\\s*(--[\\w-]+)[^)]*\\)";
 const LIGHT_DARK_SOURCE = "^light-dark\\(\\s*(.+?)\\s*,\\s*(.+?)\\s*\\)$";
 /** A `var(--custom-prop)` reference (optional fallback); capture group 1 is the property name. */
@@ -303,44 +225,8 @@ function resolveTokens(base, options = {}) {
 	const resolve = makeResolver(base, options);
 	return new Map(base.map((t) => [t.name, resolve(t.value)]));
 }
-/**
-* Convert a kebab-case string to camelCase (`color-background-brand` → `colorBackgroundBrand`).
-*
-* @example
-* ```ts
-* import { camelCase } from "@pantoken/utils";
-*
-* camelCase("color-background-brand"); // → "colorBackgroundBrand"
-* ```
-*/
-function camelCase(kebab) {
-	return kebab.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
-}
-/**
-* Parse `#rgb`, `#rrggbb`, or `#rrggbbaa` to {@link Rgba}; returns `undefined` otherwise.
-*
-* @example
-* ```ts
-* import { parseHexColor } from "@pantoken/utils";
-*
-* parseHexColor("#fff");      // → { r: 255, g: 255, b: 255, a: 1 }
-* parseHexColor("#0374B5");   // → { r: 3, g: 116, b: 181, a: 1 }
-* parseHexColor("#00000080"); // → { r: 0, g: 0, b: 0, a: 0.5019… }
-* parseHexColor("nope");      // → undefined
-* ```
-*/
-function parseHexColor(hex) {
-	const m = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(hex.trim());
-	if (!m) return void 0;
-	let h = m[1];
-	if (h.length === 3) h = h.replace(/(.)/g, "$1$1");
-	return {
-		r: Number.parseInt(h.slice(0, 2), 16),
-		g: Number.parseInt(h.slice(2, 4), 16),
-		b: Number.parseInt(h.slice(4, 6), 16),
-		a: h.length === 8 ? Number.parseInt(h.slice(6, 8), 16) / 255 : 1
-	};
-}
+//#endregion
+//#region src/drift.ts
 /**
 * Every `--instui-*` custom-property name that appears anywhere in `text`.
 *
@@ -427,11 +313,142 @@ function danglingReferences(css) {
 	for (const m of css.matchAll(/(--instui-[\w]+(?:-[\w]+)*)\s*:/g)) defined.add(m[1]);
 	return [...referenced].filter((name) => !defined.has(name)).sort();
 }
+//#endregion
+//#region src/case.ts
+/**
+* Convert a kebab-case string to camelCase (`color-background-brand` → `colorBackgroundBrand`).
+*
+* @module
+*/
+/**
+* Convert a kebab-case string to camelCase (`color-background-brand` → `colorBackgroundBrand`).
+*
+* @example
+* ```ts
+* import { camelCase } from "@pantoken/utils";
+*
+* camelCase("color-background-brand"); // → "colorBackgroundBrand"
+* ```
+*/
+function camelCase(kebab) {
+	return kebab.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+//#endregion
+//#region src/color.ts
+/**
+* Parse `#rgb`, `#rrggbb`, or `#rrggbbaa` to {@link Rgba}; returns `undefined` otherwise.
+*
+* @example
+* ```ts
+* import { parseHexColor } from "@pantoken/utils";
+*
+* parseHexColor("#fff");      // → { r: 255, g: 255, b: 255, a: 1 }
+* parseHexColor("#0374B5");   // → { r: 3, g: 116, b: 181, a: 1 }
+* parseHexColor("#00000080"); // → { r: 0, g: 0, b: 0, a: 0.5019… }
+* parseHexColor("nope");      // → undefined
+* ```
+*/
+function parseHexColor(hex) {
+	const m = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(hex.trim());
+	if (!m) return void 0;
+	let h = m[1];
+	if (h.length === 3) h = h.replace(/(.)/g, "$1$1");
+	return {
+		r: Number.parseInt(h.slice(0, 2), 16),
+		g: Number.parseInt(h.slice(2, 4), 16),
+		b: Number.parseInt(h.slice(4, 6), 16),
+		a: h.length === 8 ? Number.parseInt(h.slice(6, 8), 16) / 255 : 1
+	};
+}
+//#endregion
+//#region src/svg.ts
+/**
+* SVG sanitization for glyphs decoded from vendored data URIs or contributed by plugins.
+*
+* @module
+*/
+/**
+* Strip `<script>` elements and event-handler attributes from SVG markup.
+*
+* Defense-in-depth for SVG decoded from vendored data URIs or contributed by plugins.
+* Not a full HTML parser — relies on the upstream source being trusted and pinned.
+*/
+function sanitizeSvg(svg) {
+	let sanitized = svg;
+	let previous;
+	do {
+		previous = sanitized;
+		sanitized = sanitized.replace(/<script\b[^>]*>[\s\S]*?<\/script\b[^>]*>/gi, "");
+	} while (sanitized !== previous);
+	do {
+		previous = sanitized;
+		sanitized = sanitized.replace(/\son\w+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "");
+	} while (sanitized !== previous);
+	return sanitized;
+}
+//#endregion
+//#region src/spacing.ts
+/**
+* The pantoken spacing scale, `none`/`0` → `2xl` — the single shared source for
+* `@pantoken/components`' spacing/gap utilities and `@pantoken/interactions`' `resolveSpace`, so the
+* two never drift apart.
+*/
+const SPACING_STEPS = [
+	{
+		short: "0",
+		long: "none",
+		value: "var(--instui-component-shared-tokens-spacing-general-space-none)"
+	},
+	{
+		short: "2xs",
+		long: "xx-small",
+		value: "var(--instui-spacing-space2xs)"
+	},
+	{
+		short: "xs",
+		long: "x-small",
+		value: "var(--instui-spacing-space-xs)"
+	},
+	{
+		short: "sm",
+		long: "small",
+		value: "var(--instui-spacing-space-sm)"
+	},
+	{
+		short: "md",
+		long: "medium",
+		value: "var(--instui-spacing-space-md)"
+	},
+	{
+		short: "lg",
+		long: "large",
+		value: "var(--instui-spacing-space-lg)"
+	},
+	{
+		short: "xl",
+		long: "x-large",
+		value: "var(--instui-spacing-space-xl)"
+	},
+	{
+		short: "2xl",
+		long: "xx-large",
+		value: "var(--instui-spacing-space2xl)"
+	}
+];
+/** The `auto` step — margin only, spelled the same both ways. */
+const SPACING_AUTO_STEP = {
+	short: "auto",
+	long: "auto",
+	value: "auto"
+};
+//#endregion
+//#region src/utility-css.ts
 /**
 * Build the semantic-colour utility stylesheet: `.<prefix>-bg-<name>` (background),
-* `.<prefix>-fg-<name>` (text colour), `.<prefix>-border-<name>` (border colour), one per semantic
+* `.<prefix>-text-<name>` (text colour), `.<prefix>-border-<name>` (border colour), one per semantic
 * colour token. Overrides are therefore only ever token-valid — no primitives, no arbitrary hex. Pass
-* the token names per family (e.g. from `@pantoken/tokens`).
+* the token names per family (e.g. from `@pantoken/tokens`), or an explicit `[name, token]` pair to
+* source a name from a different token than the family's own scale.
 *
 * @param names - {@link ColorUtilityNames}.
 * @param options - {@link UtilityOptions}.
@@ -442,10 +459,17 @@ function danglingReferences(css) {
 function colorUtilitiesCss(names, options = {}) {
 	const prefix = options.prefix || "";
 	const p = prefix ? `${prefix}-` : "";
-	const emit = (family, util, prop, list) => list.map((n) => `.${p}${util}-${n} { ${prop}: var(--instui-color-${family}-${n}); }`).join("\n");
+	const chainTargets = options.chainTargets ?? [];
+	const emit = (family, util, prop, list) => list.map((entry) => {
+		const isPair = (e) => typeof e !== "string";
+		const [n, token] = isPair(entry) ? entry : [entry, `--instui-color-${family}-${entry}`];
+		const value = token.startsWith("--") ? `var(${token})` : token;
+		const modifier = `.-${util}-${n}`;
+		return `${[`.${p}${util}-${n}`, ...chainTargets.map((target) => `.${p}${target}${modifier}`)].join(", ")} { ${prop}: ${value}; }`;
+	}).join("\n");
 	return `/* InstUI semantic colour utilities (@pantoken/utils) — prefix: ${prefix} */\n${[
 		emit("background", "bg", "background", names.background),
-		emit("text", "fg", "color", names.text),
+		emit("text", "text", "color", names.text),
 		emit("stroke", "border", "border-color", names.stroke)
 	].join("\n")}\n`;
 }
@@ -467,9 +491,11 @@ function colorUtilitiesCss(names, options = {}) {
 function tokenUtilitiesCss(groups, options = {}) {
 	const prefix = options.prefix || "";
 	const p = prefix ? `${prefix}-` : "";
+	const chainTargets = options.chainTargets ?? [];
 	return `/* InstUI token utilities (@pantoken/utils) — prefix: ${prefix} */\n${groups.flatMap(({ property, tokens }) => tokens.map((token) => {
 		const name = token.replace(/^--instui-/, "");
-		return `.${p}${name} { ${property}: var(${token}); }`;
+		const modifier = `.-${name}`;
+		return `${[`.${p}${name}`, ...chainTargets.map((target) => `.${p}${target}${modifier}`)].join(", ")} { ${property}: var(${token}); }`;
 	})).join("\n")}\n`;
 }
 //#endregion

package/dist/token-syntax.d.mts

@@ -0,0 +1,119 @@
+import { Token } from "@pantoken/model";
+//#region src/token-syntax.d.ts
+/** A registered, real CSS property name (e.g. `"font-weight"`), matched via `matchProperty()`. */
+type PropertyName = string & {
+  readonly __brand: "PropertyName";
+};
+/**
+ * A CSS Value Definition Syntax grammar string (CSS Values 4 §2.1: `|` `||` `&&` `[]` `?` `{a,b}`
+ * `#`, e.g. `"<length>"` or `"none | <shadow>#"`), matched via `match()`.
+ */
+type Grammar = string & {
+  readonly __brand: "Grammar";
+};
+/** An ordered token-name-pattern → value table, checked first-match-wins via {@link firstMatch}. */
+type SyntaxRule<T> = readonly (readonly [RegExp, T])[];
+/**
+ * Non-standard property grammars `css-tree`/`mdn-data` don't know about —
+ * matched by token-name substring, most-specific first, as raw CSS Value Definition Syntax
+ * (CSS Values 4 §2.1: `|` `||` `&&` `[]` `?` `{a,b}` `#`) rather than a real property name. Only
+ * `<...>` references to types `mdn-data` registers as standalone generic types belong here (e.g.
+ * NOT `<font-family-name>`, which only exists inline inside the real `font-family` property's own
+ * definition — that's matched via `TOKEN_NAME_TO_PROPERTY` instead).
+ */
+declare const BESPOKE_SYNTAX: SyntaxRule<Grammar>;
+/**
+ * Real CSS properties, matched by token-name substring — the property name to validate against
+ * via `css-tree`'s built-in (`mdn-data`-sourced) lexer. Intentionally conservative: a name pattern
+ * not listed here is left unmodeled rather than guessed at, since a wrong mapping could fail the
+ * build on a legitimate value. Every entry here was verified with {@link candidatePropertyCoverage}
+ * against the real IR (all themes) before being added.
+ *
+ * Order matters: `color` is LAST and end-anchored (`color$`, not a bare `/color/` substring)
+ * because several UNRELATED components merely have "color" in their own name (`ColorPicker`,
+ * `ColorContrast`, `ColorIndicator`, `ColorPreset`) with an unrelated leaf property afterwards —
+ * e.g. `--instui-component-color-picker-hash-mark-container-left-padding` (a `padding`, caught
+ * earlier) or `--instui-component-color-indicator-background-size` (a `background-size`, not
+ * modeled at all — left `unmodeled` rather than misrouted to `color`). Anchoring to the literal
+ * end trades some coverage (a few genuine `color-<role>` tokens fall to `unmodeled`) for zero
+ * false failures, verified empirically: a bare `/color/` matched 937 tokens with 62 invalid, an
+ * end-anchored `/color$/` matched only 64 but 0 real invalids (its few reported "invalids" were
+ * icon glyphs already resolved by the bespoke `--instui-icon-` pattern above, which runs first).
+ * `opacity` excludes a digit suffix so a colour-with-baked-in-alpha primitive
+ * (`--instui-primitive-color-grey-opacity10`, a colour, not a CSS `opacity` value) isn't misrouted
+ * either way (`primitive-opacity\d+$` below is a separate, narrower pattern for the genuine
+ * standalone opacity primitives, e.g. `--instui-primitive-opacity50`). `gap` was tried and rejected
+ * naively (it also matches `--instui-icon-megaphone`), but that collision never actually reaches
+ * here in practice — the bespoke icon-glyph rule above already claims every `instui-icon-*` name
+ * first, so `gap` IS included, verified safe once that precedence is accounted for.
+ */
+declare const TOKEN_NAME_TO_PROPERTY: SyntaxRule<PropertyName>;
+/** A `namePattern`'s concrete, non-contextual matches against a candidate property, from the real IR. */
+interface PatternCoverage {
+  /** How many concrete (non-contextual) tokens matched `namePattern`. */
+  matched: number;
+  /** The matches that would FAIL the candidate property's real CSS grammar. */
+  invalid: readonly {
+    name: string;
+    value: string;
+  }[];
+}
+/**
+ * Empirically checks a candidate `TOKEN_NAME_TO_PROPERTY` entry against the real IR before it's
+ * added, rather than guessing: does every concrete value whose name matches `namePattern` actually
+ * validate against `candidateProperty`'s real CSS grammar? (e.g. "every
+ * `--instui-primitive-color-*-opacity\d` token is a valid `<color>`.") `matched === 0` means the
+ * pattern hit nothing in this IR — not evidence of safety either way. Contextual (`var()`/
+ * `light-dark()`) values are skipped, same as {@link isSyntaxValid}.
+ *
+ * @example
+ * ```ts
+ * import { candidatePropertyCoverage } from "@pantoken/utils";
+ * import { tokens } from "@pantoken/tokens";
+ *
+ * const coverage = candidatePropertyCoverage(tokens, /-opacity\d/u, "color");
+ * coverage.invalid; // → [] once every matching token is confirmed to be a valid <color>
+ * ```
+ */
+declare function candidatePropertyCoverage(tokens: readonly {
+  name: string;
+  value: string;
+}[], namePattern: RegExp, candidateProperty: string): PatternCoverage;
+/** One token whose value doesn't satisfy its property's CSS grammar, or whose name maps to none. */
+interface TokenSyntaxIssue {
+  /** The token's `--instui-*` name. */
+  name: string;
+  /** The token's resolved value. */
+  value: string;
+  /** `"mismatch"` fails a known property's real CSS grammar; `"unmodeled"` maps to no known property. */
+  kind: "mismatch" | "unmodeled";
+}
+/**
+ * Type-integrity check: every concrete token value validated against the REAL CSS grammar for the
+ * property its name implies (via `css-tree`'s `mdn-data`-backed lexer, plus the shared
+ * `BESPOKE_SYNTAX` table for pantoken-only properties) — catches upstream data corruption (e.g. a
+ * `font-weight` token whose value ends up as a non-numeric string) that a value-shape sniff alone
+ * would silently accept. Contextual values (`var()` / `light-dark()`) are skipped: their real type
+ * lives at the reference target. Sorted by name; empty means every modeled token is valid.
+ *
+ * @param tokens - The IR.
+ * @returns Tokens that fail their property's grammar (`"mismatch"`) or map to no known property
+ * (`"unmodeled"`).
+ *
+ * @example
+ * ```ts
+ * import { syntaxMismatches } from "@pantoken/utils";
+ * import type { Token } from "@pantoken/model";
+ *
+ * const ir: Token[] = [
+ *   { name: "--instui-font-weight-base", syntax: "<integer>", inherits: true, value: "400" },
+ *   { name: "--instui-content-quote-font-weight", syntax: "*", inherits: true, value: "Medium Italic" },
+ * ];
+ *
+ * syntaxMismatches(ir);
+ * // → [{ name: "--instui-content-quote-font-weight", value: "Medium Italic", kind: "mismatch" }]
+ * ```
+ */
+declare function syntaxMismatches(tokens: readonly Token[]): TokenSyntaxIssue[];
+//#endregion
+export { BESPOKE_SYNTAX, Grammar, PatternCoverage, PropertyName, SyntaxRule, TOKEN_NAME_TO_PROPERTY, TokenSyntaxIssue, candidatePropertyCoverage, syntaxMismatches };

package/dist/token-syntax.mjs

@@ -0,0 +1,256 @@
+import * as csstree from "css-tree";
+//#region src/token-syntax.ts
+/**
+* Validates a resolved token value against the REAL CSS grammar for the property its name
+* implies, using `css-tree`'s spec-driven lexer (backed by `mdn-data`, the same W3C-spec dataset
+* browsers/`stylelint` use) as the authoritative source — not a hand-rolled value-shape sniffer.
+* `BESPOKE_SYNTAX` is the one shared table of pantoken-invented, non-standard property grammars
+* (also consumed by `docs/scripts/build-css-api.ts` for human-readable type display), so the docs
+* and this validator can never drift apart.
+*
+* @module
+*/
+/** The registered `css-tree` property descriptor for `name`, or throws — never silently unmatched. */
+function requireProperty(name) {
+	const property = csstree.lexer.getProperty(name);
+	if (!property) throw new Error(`css-tree has no registered property named "${name}"`);
+	return property;
+}
+/**
+* The REAL CSS grammar string for a property, generated from `css-tree`'s own lexer (the same
+* instance {@link isSyntaxValid} matches against) rather than hand-typed — guaranteed byte-identical
+* to what the lexer actually validates, so it can never drift out of sync with itself.
+*/
+function propertyGrammar(name) {
+	const syntax = requireProperty(name).syntax;
+	if (!syntax) throw new Error(`css-tree property "${name}" has no generatable grammar`);
+	return csstree.definitionSyntax.generate(syntax);
+}
+/**
+* A real CSS property name for {@link TOKEN_NAME_TO_PROPERTY}, validated against `css-tree`'s
+* registry at module load — the same fail-fast safety net as {@link propertyGrammar}, so a typo'd
+* property name throws immediately with a clear message instead of silently flagging every
+* matching token as a mismatch at build time.
+*/
+function realProperty(name) {
+	requireProperty(name);
+	return name;
+}
+/**
+* A `<type>` reference for {@link BESPOKE_SYNTAX}, validated against `css-tree`'s registry at
+* module load — the same fail-fast safety net as {@link realProperty}, for the terminal/generic
+* types (`length`, `color`, `url`, `time`, …) that don't belong to any single real property.
+*/
+function typeReference(name) {
+	if (!csstree.lexer.getType(name)) throw new Error(`css-tree has no registered type named "${name}"`);
+	return `<${name}>`;
+}
+/**
+* Non-standard property grammars `css-tree`/`mdn-data` don't know about —
+* matched by token-name substring, most-specific first, as raw CSS Value Definition Syntax
+* (CSS Values 4 §2.1: `|` `||` `&&` `[]` `?` `{a,b}` `#`) rather than a real property name. Only
+* `<...>` references to types `mdn-data` registers as standalone generic types belong here (e.g.
+* NOT `<font-family-name>`, which only exists inline inside the real `font-family` property's own
+* definition — that's matched via `TOKEN_NAME_TO_PROPERTY` instead).
+*/
+const BESPOKE_SYNTAX = [
+	[/drop-shadow-(blur|spread|x|y)-/u, typeReference("length")],
+	[/elevation/u, propertyGrammar("box-shadow")],
+	[/text-decoration/u, propertyGrammar("text-decoration-line")],
+	[/focus-outline-color/u, propertyGrammar("outline-color")],
+	[/focus-outline-style/u, propertyGrammar("outline-style")],
+	[/focus-outline-width/u, propertyGrammar("outline-width")],
+	[/focus-outline-offset/u, propertyGrammar("outline-offset")],
+	[/focus-outline-radius/u, propertyGrammar("border-radius")],
+	[/--instui-icon-color-/u, typeReference("color")],
+	[/glyph|instui-icon/u, typeReference("url")],
+	[/-filter\b/u, propertyGrammar("filter")],
+	[/box-shadow-(blur|spread|x|y)$/u, typeReference("length")],
+	[/box-shadow-color$/u, typeReference("color")],
+	[/(?<!background)-size(?:-|\d|$)/u, typeReference("length")],
+	[/(?<!letter)-spacing/u, typeReference("length")],
+	[/offset$/u, typeReference("length")],
+	[/thickness$/u, typeReference("length")],
+	[/circumference$/u, typeReference("length")],
+	[/(?:transition-timing)|(?:toggle-transition$)/u, typeReference("time")],
+	[/(?:breakpoints-)|(?:byline-(?:large|medium|small)$)/u, typeReference("length")],
+	[/progress-circle-.*-transform$/u, typeReference("length")],
+	[/(?:icon-illu-)|(?:img-image-blur-amount$)/u, typeReference("length")],
+	[/tray-fix-top-position$/u, typeReference("length")]
+];
+/**
+* Real CSS properties, matched by token-name substring — the property name to validate against
+* via `css-tree`'s built-in (`mdn-data`-sourced) lexer. Intentionally conservative: a name pattern
+* not listed here is left unmodeled rather than guessed at, since a wrong mapping could fail the
+* build on a legitimate value. Every entry here was verified with {@link candidatePropertyCoverage}
+* against the real IR (all themes) before being added.
+*
+* Order matters: `color` is LAST and end-anchored (`color$`, not a bare `/color/` substring)
+* because several UNRELATED components merely have "color" in their own name (`ColorPicker`,
+* `ColorContrast`, `ColorIndicator`, `ColorPreset`) with an unrelated leaf property afterwards —
+* e.g. `--instui-component-color-picker-hash-mark-container-left-padding` (a `padding`, caught
+* earlier) or `--instui-component-color-indicator-background-size` (a `background-size`, not
+* modeled at all — left `unmodeled` rather than misrouted to `color`). Anchoring to the literal
+* end trades some coverage (a few genuine `color-<role>` tokens fall to `unmodeled`) for zero
+* false failures, verified empirically: a bare `/color/` matched 937 tokens with 62 invalid, an
+* end-anchored `/color$/` matched only 64 but 0 real invalids (its few reported "invalids" were
+* icon glyphs already resolved by the bespoke `--instui-icon-` pattern above, which runs first).
+* `opacity` excludes a digit suffix so a colour-with-baked-in-alpha primitive
+* (`--instui-primitive-color-grey-opacity10`, a colour, not a CSS `opacity` value) isn't misrouted
+* either way (`primitive-opacity\d+$` below is a separate, narrower pattern for the genuine
+* standalone opacity primitives, e.g. `--instui-primitive-opacity50`). `gap` was tried and rejected
+* naively (it also matches `--instui-icon-megaphone`), but that collision never actually reaches
+* here in practice — the bespoke icon-glyph rule above already claims every `instui-icon-*` name
+* first, so `gap` IS included, verified safe once that precedence is accounted for.
+*/
+const TOKEN_NAME_TO_PROPERTY = [
+	[/font-family/u, realProperty("font-family")],
+	[/font-weight/u, realProperty("font-weight")],
+	[/font-style/u, realProperty("font-style")],
+	[/font-size/u, realProperty("font-size")],
+	[/line-height/u, realProperty("line-height")],
+	[/letter-spacing/u, realProperty("letter-spacing")],
+	[/opacity(?!\d)/u, realProperty("opacity")],
+	[/primitive-opacity\d+$/u, realProperty("opacity")],
+	[/z-index|stacking/u, realProperty("z-index")],
+	[/transition-duration|-duration\b/u, realProperty("transition-duration")],
+	[/border-width/u, realProperty("border-width")],
+	[/-radius/u, realProperty("border-radius")],
+	[/border-style/u, realProperty("border-style")],
+	[/bottom-border/u, realProperty("border-bottom")],
+	[/box-shadow/u, realProperty("box-shadow")],
+	[/margin/u, realProperty("margin")],
+	[/padding/u, realProperty("padding")],
+	[/height/u, realProperty("height")],
+	[/width/u, realProperty("width")],
+	[/gap/u, realProperty("gap")],
+	[/inset/u, realProperty("inset")],
+	[/overflow-x$/u, realProperty("overflow-x")],
+	[/overflow-y$/u, realProperty("overflow-y")],
+	[/text-transform$/u, realProperty("text-transform")],
+	[/base-button-(hover-)?transform$/u, realProperty("transform")],
+	[/background-image$/u, realProperty("background-image")],
+	[/background-position$/u, realProperty("background-position")],
+	[/background-size$/u, realProperty("background-size")],
+	[/background$/u, realProperty("background")],
+	[/border-color/u, realProperty("border-color")],
+	[/primitive-color-/u, realProperty("color")],
+	[/color(?:\d*|-inverse)$/u, realProperty("color")],
+	[/position$/u, realProperty("position")]
+];
+function firstMatch(name, table) {
+	return table.find(([re]) => re.test(name))?.[1];
+}
+/** True when a value cannot be a typed CSS value at all (`var()` / `light-dark()`). */
+function isContextualValue(value) {
+	return /var\(|light-dark\(/.test(value);
+}
+/** Whether `name` maps to a modeled property/grammar at all (real or bespoke). */
+function hasModeledSyntax(name) {
+	return firstMatch(name, BESPOKE_SYNTAX) !== void 0 || TOKEN_NAME_TO_PROPERTY.some(([re]) => re.test(name));
+}
+/**
+* Whether a concrete value satisfies the real (or bespoke) CSS grammar for `name`'s property.
+* Returns `true` for any name with no modeled expectation — call {@link hasModeledSyntax} first
+* to distinguish "valid" from "not checked".
+*/
+function isSyntaxValid(name, value) {
+	const bespoke = firstMatch(name, BESPOKE_SYNTAX);
+	const property = bespoke ? void 0 : firstMatch(name, TOKEN_NAME_TO_PROPERTY);
+	if (!bespoke && !property) return true;
+	let ast;
+	try {
+		ast = csstree.parse(value, { context: "value" });
+	} catch {
+		return false;
+	}
+	return !(bespoke ? csstree.lexer.match(bespoke, ast) : csstree.lexer.matchProperty(property, ast)).error;
+}
+/**
+* Empirically checks a candidate `TOKEN_NAME_TO_PROPERTY` entry against the real IR before it's
+* added, rather than guessing: does every concrete value whose name matches `namePattern` actually
+* validate against `candidateProperty`'s real CSS grammar? (e.g. "every
+* `--instui-primitive-color-*-opacity\d` token is a valid `<color>`.") `matched === 0` means the
+* pattern hit nothing in this IR — not evidence of safety either way. Contextual (`var()`/
+* `light-dark()`) values are skipped, same as {@link isSyntaxValid}.
+*
+* @example
+* ```ts
+* import { candidatePropertyCoverage } from "@pantoken/utils";
+* import { tokens } from "@pantoken/tokens";
+*
+* const coverage = candidatePropertyCoverage(tokens, /-opacity\d/u, "color");
+* coverage.invalid; // → [] once every matching token is confirmed to be a valid <color>
+* ```
+*/
+function candidatePropertyCoverage(tokens, namePattern, candidateProperty) {
+	let matched = 0;
+	const invalid = [];
+	for (const { name, value } of tokens) {
+		if (!namePattern.test(name) || isContextualValue(value)) continue;
+		matched++;
+		let ast;
+		try {
+			ast = csstree.parse(value, { context: "value" });
+		} catch {
+			invalid.push({
+				name,
+				value
+			});
+			continue;
+		}
+		if (csstree.lexer.matchProperty(candidateProperty, ast).error) invalid.push({
+			name,
+			value
+		});
+	}
+	return {
+		matched,
+		invalid
+	};
+}
+/**
+* Type-integrity check: every concrete token value validated against the REAL CSS grammar for the
+* property its name implies (via `css-tree`'s `mdn-data`-backed lexer, plus the shared
+* `BESPOKE_SYNTAX` table for pantoken-only properties) — catches upstream data corruption (e.g. a
+* `font-weight` token whose value ends up as a non-numeric string) that a value-shape sniff alone
+* would silently accept. Contextual values (`var()` / `light-dark()`) are skipped: their real type
+* lives at the reference target. Sorted by name; empty means every modeled token is valid.
+*
+* @param tokens - The IR.
+* @returns Tokens that fail their property's grammar (`"mismatch"`) or map to no known property
+* (`"unmodeled"`).
+*
+* @example
+* ```ts
+* import { syntaxMismatches } from "@pantoken/utils";
+* import type { Token } from "@pantoken/model";
+*
+* const ir: Token[] = [
+*   { name: "--instui-font-weight-base", syntax: "<integer>", inherits: true, value: "400" },
+*   { name: "--instui-content-quote-font-weight", syntax: "*", inherits: true, value: "Medium Italic" },
+* ];
+*
+* syntaxMismatches(ir);
+* // → [{ name: "--instui-content-quote-font-weight", value: "Medium Italic", kind: "mismatch" }]
+* ```
+*/
+function syntaxMismatches(tokens) {
+	const issues = [];
+	for (const { name, value } of tokens) {
+		if (isContextualValue(value)) continue;
+		if (!hasModeledSyntax(name)) issues.push({
+			name,
+			value,
+			kind: "unmodeled"
+		});
+		else if (!isSyntaxValid(name, value)) issues.push({
+			name,
+			value,
+			kind: "mismatch"
+		});
+	}
+	return issues.sort((a, b) => a.name.localeCompare(b.name));
+}
+//#endregion
+export { BESPOKE_SYNTAX, TOKEN_NAME_TO_PROPERTY, candidatePropertyCoverage, syntaxMismatches };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantoken/utils",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Shared pantoken helpers: token reference resolver, typed regexes (arkregex), name-case, and hex-colour parsing.",
   "homepage": "https://pantoken.iywahl.com",
   "bugs": "https://github.com/thedannywahl/pantoken/issues",
@@ -17,6 +17,7 @@
   "sideEffects": false,
   "exports": {
     ".": "./dist/index.mjs",
+    "./token-syntax": "./dist/token-syntax.mjs",
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -25,9 +26,11 @@
   },
   "dependencies": {
     "arkregex": "^0.0.8",
+    "css-tree": "^3.2.1",
     "@pantoken/model": "0.3.0"
   },
   "devDependencies": {
+    "@types/css-tree": "^3.2.0",
     "@types/node": "^24.13.3",
     "typescript": "^7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.9",