@teacss/core 0.4.7 → 0.5.0

package/dist/index.d.ts

@@ -20,7 +20,7 @@
  * presets own the vocabulary.
  */
 /** How an `@cond` segment is classified by its first character (after a NOT `!`). */
-type ConditionKind =
+export type ConditionKind =
 /** `@.cls` / `@#id` — a class/id on the subject itself. */
 "self" |
 /** `@::after` — a pseudo-element on the subject. */
@@ -32,7 +32,7 @@ type ConditionKind =
 /** Letter-first: a named condition (pseudo-class / media / relation / breakpoint / at-rule). Resolved by hooks. */
 "named";
 /** A single `@cond` segment parsed into structured form (no CSS resolved yet). */
-interface ParsedCondition {
+export interface ParsedCondition {
   /** The segment without its leading `@`, exactly as written (e.g. `hover`, `.is-dragging`, `>li:hover`, `!disabled`). */
   raw: string;
   kind: ConditionKind;
@@ -47,16 +47,17 @@ interface ParsedCondition {
  * Pure and total. A leading `!` sets `negate` and is stripped before dispatch.
  * First-character dispatch follows the current condition grammar:
  *   `::` → pseudo-element · `.`/`#` → self · `> _ + ~` → target · `[` → arbitrary · else → named.
+ * CSS comments may separate the two pseudo-element colons.
  */
-declare function parseCondition(raw: string): ParsedCondition;
+export declare function parseCondition(raw: string): ParsedCondition;
 /** Classify a list of condition segments (e.g. `ParsedClassToken.conditions`). */
-declare function parseConditions(conditions: string[]): ParsedCondition[];
+export declare function parseConditions(conditions: string[]): ParsedCondition[];
 /**
  * The contribution of one resolved condition to the final rule, split by role so
  * assembly can place each part canonically (selector-first), independent of the
  * order conditions were written in.
  */
-interface ResolvedCondition {
+export interface ResolvedCondition {
   /** Ancestor prepended before the subject, e.g. `.group:hover `. */
   prefix?: string;
   /** Combinator + target appended after the subject, shifting the styled element, e.g. ` > li`. */
@@ -69,7 +70,7 @@ interface ResolvedCondition {
   parent?: string;
 }
 /** Context handed to resolver hooks. */
-interface ConditionResolveContext {
+export interface ConditionResolveContext {
   /** The full parsed condition list, for hooks that need siblings (e.g. named container). */
   conditions: ParsedCondition[];
   /** The resolved theme, for hooks whose vocabulary is theme-driven (e.g. breakpoints). */
@@ -80,8 +81,8 @@ interface ConditionResolveContext {
  * or `undefined` to defer to the next hook. Presets register hooks for named
  * and arbitrary conditions.
  */
-type ConditionResolver = (cond: ParsedCondition, ctx: ConditionResolveContext) => ResolvedCondition | undefined;
-interface ResolveConditionsResult {
+export type ConditionResolver = (cond: ParsedCondition, ctx: ConditionResolveContext) => ResolvedCondition | undefined;
+export interface ResolveConditionsResult {
   /** Conditions resolved to structured contributions (by core or a hook). */
   resolved: ResolvedCondition[];
   /** Conditions no hook handled — surfaced so callers/tests can detect missing vocabulary. */
@@ -95,8 +96,8 @@ interface ResolveConditionsResult {
  *
  * Enforces at most one pseudo-element per token.
  */
-declare function resolveConditions(conditions: ParsedCondition[], resolvers?: ConditionResolver[], theme?: object): ResolveConditionsResult;
-interface BuiltConditionSelector {
+export declare function resolveConditions(conditions: ParsedCondition[], resolvers?: ConditionResolver[], theme?: object): ResolveConditionsResult;
+export interface BuiltConditionSelector {
   /** The assembled selector, e.g. `.group:hover .bg\:red:hover > li`. */
   selector: string;
   /** At-rule parents wrapping the rule, outermost-last (e.g. `["@media (min-width: 48rem)"]`). */
@@ -111,19 +112,19 @@ interface BuiltConditionSelector {
  * `a@_svg@group-hover@md` and `a@md@group-hover@_svg` produce the same selector
  * + parents. Conditions within the same role retain their authored order.
  */
-declare function buildConditionSelector(subject: string, resolved: ResolvedCondition[]): BuiltConditionSelector;
+export declare function buildConditionSelector(subject: string, resolved: ResolvedCondition[]): BuiltConditionSelector;
 //#endregion
 //#region src/utils/basic.d.ts
-type ToArrayResult<T> = T extends any[] ? T[number][] : T extends readonly (infer U)[] ? readonly U[] : T[];
-declare function toArray<T = never>(): T[];
-declare function toArray(value: undefined): [];
-declare function toArray<T>(value: T): ToArrayResult<T>;
-declare function uniq<T>(value: T[]): T[];
-declare function uniqueBy<T>(array: readonly T[], equalFn: (a: T, b: T) => boolean): T[];
-declare function isString(s: any): s is string;
+type ToArrayResult<T, Value = Exclude<T, undefined>> = [Value] extends [never] ? [] : Value extends any[] ? Value[number][] : Value extends readonly (infer U)[] ? readonly U[] : Value[];
+export declare function toArray<T = never>(): T[];
+export declare function toArray(value: undefined): [];
+export declare function toArray<T>(value: T): ToArrayResult<T>;
+export declare function uniq<T>(value: T[]): T[];
+export declare function uniqueBy<T>(array: readonly T[], equalFn: (a: T, b: T) => boolean): T[];
+export declare function isString(s: any): s is string;
 //#endregion
 //#region src/utils/countable-set.d.ts
-declare class CountableSet<K> extends Set<K> {
+export declare class CountableSet<K> extends Set<K> {
   _map: Map<K, number>;
   constructor(values?: Iterable<K>);
   add(key: K): this;
@@ -132,23 +133,24 @@ declare class CountableSet<K> extends Set<K> {
   getCount(key: K): number;
   setCount(key: K, count: number): this;
 }
-declare function isCountableSet<T = string>(value: any): value is CountableSet<T>;
+export declare function isCountableSet<T = string>(value: any): value is CountableSet<T>;
 //#endregion
 //#region src/utils/escape.d.ts
-declare function escapeRegExp(string: string): string;
+export declare function escapeRegExp(string: string): string;
 /**
  * CSS Selector Escape
  */
-declare function escapeSelector(str: string): string;
-declare const e: typeof escapeSelector;
+export declare function escapeSelector(str: string): string;
+export declare const e: typeof escapeSelector;
 //#endregion
 //#region src/utils/events.d.ts
 type EventsMap = Record<string, any>;
 interface DefaultEvents extends EventsMap {
   [event: string]: (...args: any) => void;
 }
-type Unsubscribe = () => void;
-interface Emitter<Events extends EventsMap = DefaultEvents> {
+/** Unbind listeners; calls after a successful unsubscribe are no-ops. */
+export type Unsubscribe = () => void;
+export interface Emitter<Events extends EventsMap = DefaultEvents> {
   /**
    * Event names in keys and arrays with listeners in values.
    *
@@ -207,30 +209,29 @@ interface Emitter<Events extends EventsMap = DefaultEvents> {
  * }
  * ```
  */
-declare function createNanoEvents<Events extends EventsMap = DefaultEvents>(): Emitter<Events>;
+export declare function createNanoEvents<Events extends EventsMap = DefaultEvents>(): Emitter<Events>;
 //#endregion
 //#region src/utils/helpers.d.ts
-declare const attributifyRE: RegExp;
-declare const cssIdRE: RegExp;
-declare const validateFilterRE: RegExp;
-declare function isAttributifySelector(selector: string): RegExpMatchArray | null;
-declare function isValidSelector(selector?: string): selector is string;
-declare function normalizeVariant(variant: Variant<any>): VariantObject<any>;
-declare function isRawUtil(util: ParsedUtil | RawUtil | StringifiedUtil): util is RawUtil;
-declare function notNull<T>(value: T | null | undefined): value is T;
+export declare const attributifyRE: RegExp;
+export declare const cssIdRE: RegExp;
+export declare const validateFilterRE: RegExp;
+export declare function isAttributifySelector(selector: string): RegExpMatchArray | null;
+export declare function isValidSelector(selector?: string): selector is string;
+export declare function normalizeVariant<Theme extends object = object>(variant: Variant<Theme>): VariantObject<Theme>;
+export declare function isRawUtil(util: ParsedUtil | RawUtil | StringifiedUtil): util is RawUtil;
+export declare function notNull<T>(value: T | null | undefined): value is T;
 /**
- * A value is a thenable (promise-like) — used to take a synchronous fast path on
- * the per-token hot path: only genuinely-async handler/variant results are
- * `await`ed, so the common all-synchronous case never allocates a microtask.
+ * Checks for a callable `then` on an object or function, without invoking it.
+ * Primitive values are never thenables. Object getter errors propagate.
  */
-declare function isThenable<T>(value: T | PromiseLike<T>): value is PromiseLike<T>;
-declare function noop(): void;
+export declare function isThenable<T>(value: T | PromiseLike<T>): value is PromiseLike<T>;
+export declare function noop(): void;
 //#endregion
 //#region src/utils/layer.d.ts
-declare function withLayer<T extends object>(layer: string, rules: Rule<T>[]): Rule<T>[];
+export declare function withLayer<T extends object>(layer: string, rules: Rule<T>[]): Rule<T>[];
 //#endregion
 //#region src/utils/map.d.ts
-declare class TwoKeyMap<K1, K2, V> {
+export declare class TwoKeyMap<K1, K2, V> {
   _map: Map<K1, Map<K2, V>>;
   get(key1: K1, key2: K2): V | undefined;
   getFallback(key1: K1, key2: K2, fallback: V): V;
@@ -240,26 +241,26 @@ declare class TwoKeyMap<K1, K2, V> {
   deleteTop(key1: K1): boolean;
   map<T>(fn: (v: V, k1: K1, k2: K2) => T): T[];
 }
-declare class BetterMap<K, V> extends Map<K, V> {
+export declare class BetterMap<K, V> extends Map<K, V> {
   getFallback(key: K, fallback: V): V;
   map<R>(mapFn: (value: V, key: K) => R): R[];
   flatMap<R extends readonly unknown[]>(mapFn: (value: V, key: K) => R): R[number][];
 }
 //#endregion
 //#region src/utils/object.d.ts
-declare function normalizeCSSEntries(obj: string | CSSEntriesInput | CSSObjectInput): string | CSSEntriesInput;
-declare function normalizeCSSValues(obj: CSSValueInput | string | (CSSValueInput | string)[]): (string | CSSEntriesInput)[];
-declare function clearIdenticalEntries(entry: CSSEntriesInput): CSSEntries;
-declare const VirtualKey = "__virtual_key__";
-declare function entriesToCss(arr?: CSSEntriesInput): string;
-declare function isObject(item: any): item is Record<string, any>;
+export declare function normalizeCSSEntries(obj: string | CSSEntriesInput | CSSObjectInput): string | CSSEntriesInput;
+export declare function normalizeCSSValues(obj: CSSValueInput | string | (CSSValueInput | string)[]): (string | CSSEntriesInput)[];
+export declare function clearIdenticalEntries(entry: CSSEntriesInput): CSSEntries;
+export declare const VirtualKey = "__virtual_key__";
+export declare function entriesToCss(arr?: CSSEntriesInput): string;
+export declare function isObject(item: any): item is Record<string, any>;
 /**
  * Marker key on a patch object that forces a full replacement of the
  * corresponding original value instead of a deep merge. An explicit
  * `{ $reset: true, … }` replaces an entire category.
  * The marker is stripped from output.
  */
-declare const RESET_KEY = "$reset";
+export declare const RESET_KEY = "$reset";
 /**
  * Deep merge two objects.
  *
@@ -268,37 +269,22 @@ declare const RESET_KEY = "$reset";
  * marker) is used as-is. This applies recursively, so a single theme category can
  * opt out of deep-merging (`theme.colors = { $reset: true, ... }`).
  */
-declare function mergeDeep<T>(original: T, patch: DeepPartial<T>, mergeArray?: boolean): T;
-declare function clone<T>(val: T): T;
-declare function isStaticRule(rule: Rule<any>): rule is StaticRule;
-declare function isStaticShortcut(sc: Shortcut<any>): sc is StaticShortcut;
+export declare function mergeDeep<T>(original: T, patch: DeepPartial<T>, mergeArray?: boolean): T;
+export declare function clone<T>(val: T): T;
+export declare function isStaticRule(rule: Rule<any>): rule is StaticRule;
+export declare function isStaticShortcut(sc: Shortcut<any>): sc is StaticShortcut;
 //#endregion
 //#region src/utils/selector-target.d.ts
-/**
- * Structural validation for the target selector of a `@>li` / `@_p` / `@+span`
- * condition.
- *
- * Core keeps the target verbatim so state written on the target survives
- * (`@>li:hover`), which means whatever the class carries is what reaches the
- * stylesheet. Text that cannot begin a compound selector — `@_5` produced the
- * selector `.…\@_5 5` — makes the browser drop the whole rule, so the token
- * must not match in the first place.
- *
- * This is CSS *syntax*, not preset vocabulary: it accepts one complex selector
- * built from compounds and the three combinators a class token can spell. It
- * deliberately does not know which type names, pseudo-classes, or attributes
- * exist — that is the preset's business.
- */
 /** True when `target` is one complex selector that can begin a compound. */
-declare function isValidTargetSelector(target: string): boolean;
+export declare function isValidTargetSelector(target: string): boolean;
 //#endregion
 //#region src/utils/source.d.ts
-declare function getPath(id: string): string;
-declare function isCssId(id: string): boolean;
-declare function hash(str: string): string;
-declare function transformSkipCode(code: string, map: Map<string, string>, SKIP_RULES_RE: RegExp, keyFlag: string): string;
-declare function restoreSkipCode(code: string, map: Map<string, string>): string;
-declare function replaceAsync(string: string, searchValue: RegExp, replacer: (substring: string, ...args: any[]) => Promise<string>): Promise<string>;
+export declare function getPath(id: string): string;
+export declare function isCssId(id: string): boolean;
+export declare function hash(str: string): string;
+export declare function transformSkipCode(code: string, map: Map<string, string>, SKIP_RULES_RE: RegExp, keyFlag: string): string;
+export declare function restoreSkipCode(code: string, map: Map<string, string>): string;
+export declare function replaceAsync(string: string, searchValue: RegExp, replacer: (substring: string, ...args: any[]) => Promise<string>): Promise<string>;
 //#endregion
 //#region src/utils/unmatched-diagnostics.d.ts
 /** The structural slice of a resolved config the suggestion index reads. */
@@ -307,16 +293,15 @@ interface SuggestionSource {
   rulesDynamic: readonly (readonly [RegExp, ...unknown[]])[];
 }
 /**
- * Strip trailing `@…` condition chains: the base ends at the first `@` that
- * sits outside brackets, parentheses, and quotes.
+ * Strip trailing conditions using the shared token grammar, retaining `!`.
  */
-declare function tokenConditionBase(token: string): string;
+export declare function tokenConditionBase(token: string): string;
 /**
  * Extracted source text is mostly not TeaCSS. Only candidates that read as a
  * `prefix:value` token (optionally behind a condition chain) are diagnosed —
  * plain words, framework class names, import specifiers, and URLs never are.
  */
-declare function isTokenShaped(token: string): boolean;
+export declare function isTokenShaped(token: string): boolean;
 /**
  * Decide whether an unmatched, token-shaped candidate deserves a diagnostic
  * and compute its suggestions in one pass. Returns `undefined` for candidates
@@ -324,35 +309,35 @@ declare function isTokenShaped(token: string): boolean;
  * full of `word:word` shapes, and silence beats noise when no known or
  * near-known prefix is involved.
  */
-declare function diagnoseUnmatchedToken(token: string, config: SuggestionSource, options?: {
+export declare function diagnoseUnmatchedToken(token: string, config: SuggestionSource, options?: {
   confirmedIntent?: boolean;
 }): string[] | undefined;
 //#endregion
 //#region src/utils/variant-group.d.ts
-declare function makeRegexClassGroup(separators?: string[]): RegExp;
+export declare function makeRegexClassGroup(separators?: string[]): RegExp;
 interface VariantGroup {
   length: number;
   items: HighlightAnnotation[];
 }
-declare function parseVariantGroup(str: string | MagicStringLike, separators?: string[], depth?: number): {
+export declare function parseVariantGroup(str: string | MagicStringLike, separators?: string[], depth?: number): {
   prefixes: string[];
   hasChanged: boolean;
   groupsByOffset: Map<number, VariantGroup>;
   readonly expanded: string;
 };
-declare function collapseVariantGroup(str: string, prefixes: string[]): string;
-declare function expandVariantGroup(str: string, separators?: string[], depth?: number): string;
-declare function expandVariantGroup(str: MagicStringLike, separators?: string[], depth?: number): MagicStringLike;
+export declare function collapseVariantGroup(str: string, prefixes: string[]): string;
+export declare function expandVariantGroup(str: string, separators?: string[], depth?: number): string;
+export declare function expandVariantGroup(str: MagicStringLike, separators?: string[], depth?: number): MagicStringLike;
 //#endregion
 //#region src/utils/warn.d.ts
-declare function warnOnce(msg: string): void;
+export declare function warnOnce(msg: string): void;
 //#endregion
 //#region src/generator.d.ts
-declare const symbols: ControlSymbols;
+export declare const symbols: ControlSymbols;
 type ExpansionEntry<Theme extends object = object> = Shortcut<Theme>;
 type ExpansionResult = [(string | ExpansionInlineValue)[], RuleMeta | undefined];
 type ExpansionPrefixes = readonly (string | undefined)[];
-interface PreparedGeneratorConfig<Theme extends object = object> {
+export interface PreparedGeneratorConfig<Theme extends object = object> {
   readonly config: ResolvedConfig<Theme>;
   readonly defaults: UserConfigDefaults<Theme>;
   /** Isolated generator for validating work against `config` before commit. */
@@ -361,22 +346,16 @@ interface PreparedGeneratorConfig<Theme extends object = object> {
   readonly version: number;
 }
 /** A width reduced to the scale it can be compared on. @see {@link comparableWidth} */
-interface ComparableWidth {
-  /** `"px"` for every unit with a fixed pixel ratio, else the unit as authored. */
-  unit: string;
-  /** The width on that scale. Negative reverses the direction within it. */
-  value: number;
-}
-/** A width reduced to the scale it can be compared on. @see {@link comparableWidth} */
-interface ComparableWidth {
+export interface ComparableWidth {
   /** `"px"` for every unit with a fixed pixel ratio, else the unit as authored. */
   unit: string;
   /** The width on that scale. Negative reverses the direction within it. */
   value: number;
 }
 /**
- * A CSS width reduced to a comparable scale, or `null` when the text is not a length —
- * `calc()`, `var()`, an unknown unit, and malformed values such as `..` among them. A
+ * A CSS width reduced to a comparable scale, or `null` when it cannot be represented
+ * as a finite number — including conversion overflow, `calc()`, `var()`, unknown
+ * units, and malformed values such as `..`. A
  * non-length must never yield a number: `NaN` compares equal to everything, which marks
  * two unequal parents equal and skips the tiebreak {@link compareParentAtRules} relies
  * on.
@@ -387,7 +366,7 @@ interface ComparableWidth {
  * has to order the same widths — the `@screen` range resolver reads them straight from
  * `theme.breakpoint` — asks generation rather than keeping a copy that drifts.
  */
-declare function comparableWidth(size: string): ComparableWidth | null;
+export declare function comparableWidth(size: string): ComparableWidth | null;
 /**
  * Order two parent (at-rule) selectors for the emitted sheet: an explicit
  * `parentOrders` delta wins; otherwise width media queries cascade numerically
@@ -399,7 +378,7 @@ declare function comparableWidth(size: string): ComparableWidth | null;
  * the language service derives completion colors that way — orders parent blocks
  * exactly as generation does, instead of keeping a copy that drifts.
  */
-declare function compareParentAtRules(parentOrders: ReadonlyMap<string, number>, a: string, b: string): number;
+export declare function compareParentAtRules(parentOrders: ReadonlyMap<string, number>, a: string, b: string): number;
 declare class TeacssGeneratorInternal<Theme extends object = object> {
   userConfig: UserConfig<Theme>;
   defaults: UserConfigDefaults<Theme>;
@@ -420,6 +399,9 @@ declare class TeacssGeneratorInternal<Theme extends object = object> {
   private _contextConfigs;
   private _expansionPrefixes;
   private _generationContexts;
+  private _matchedStaticContexts;
+  /** Tagged empty cache payloads retain match evidence without retaining contexts or raw token keys. */
+  private _emptyStaticPayloads;
   private _configVersion;
   private _collectionGeneration;
   private _preparedConfigs;
@@ -429,6 +411,8 @@ declare class TeacssGeneratorInternal<Theme extends object = object> {
   private _preparedConfigMutable;
   private _preparedCacheReliable;
   private _startingGenerationParse;
+  private _startingInputCheck;
+  private _contextInputChecks;
   private _runtimeRevision;
   private _variantCacheOwner;
   private _initialization?;
@@ -455,11 +439,11 @@ declare class TeacssGeneratorInternal<Theme extends object = object> {
    * Index one expansion-entry list so a lookup replaces the per-token scan:
    * static names — with each configured prefix folded into the key — resolve
    * through one map read, and only regex entries still walk in order. Bodies
-   * and metas are read from the live tuples at match time; the shape captured
-   * here goes stale only with the same config mutations that already stale the
-   * token cache, and every cache reset drops the index with it. The list is
-   * also revalidated slot by slot on every lookup, because registration flows
-   * such as compile-class splice entries into the live array between parses.
+   * and metas are read from the live tuples at match time. Only config-owned
+   * lists participate in cache invalidation; external lists must be reindexed
+   * on every lookup and must not replace the cached config index. Cached lists
+   * are also revalidated slot by slot, because registration flows such as
+   * compile-class splice entries into the live array between parses.
    */
   private getExpansionIndex;
   private getDynamicIndex;
@@ -472,8 +456,8 @@ declare class TeacssGeneratorInternal<Theme extends object = object> {
   prepareConfig(userConfig: UserConfig<Theme>, defaults?: UserConfigDefaults<Theme>): Promise<PreparedGeneratorConfig<Theme>>;
   /** Commit a prepared configuration if no newer configuration request superseded it. */
   commitConfig(prepared: PreparedGeneratorConfig<Theme>): boolean;
+  applyExtractors(code: string, id: string | undefined, extracted: CountableSet<string>): Promise<CountableSet<string>>;
   applyExtractors(code: string, id?: string, extracted?: Set<string>): Promise<Set<string>>;
-  applyExtractors(code: string, id?: string, extracted?: CountableSet<string>): Promise<CountableSet<string>>;
   private applyExtractorsCurrent;
   private applyExtractorsForConfig;
   private requireInitialized;
@@ -490,7 +474,10 @@ declare class TeacssGeneratorInternal<Theme extends object = object> {
    */
   getCachedEquivalentTokens(raw: string): string[];
   generate(input: string | Set<string> | CountableSet<string> | string[], options?: GenerateOptions<false>): Promise<GenerateResult<Set<string>>>;
-  generate(input: string | Set<string> | CountableSet<string> | string[], options?: GenerateOptions<true>): Promise<GenerateResult<Map<string, ExtendedTokenInfo<Theme>>>>;
+  generate(input: string | Set<string> | CountableSet<string> | string[], options: GenerateOptions<true> & {
+    extendedInfo: true;
+  }): Promise<GenerateResult<Map<string, ExtendedTokenInfo<Theme>>>>;
+  generate(input: string | Set<string> | CountableSet<string> | string[], options?: GenerateOptions<boolean>): Promise<GenerateResult<Set<string> | Map<string, ExtendedTokenInfo<Theme>>>>;
   private generateInternal;
   matchVariants(raw: string, current?: string): Promise<readonly VariantMatchedResult<Theme>[]>;
   private matchVariantsCurrent;
@@ -510,16 +497,16 @@ declare class TeacssGeneratorInternal<Theme extends object = object> {
   getBlocked(raw: string): [BlocklistValue, BlocklistMeta | undefined] | undefined;
   private matchesBlocklist;
 }
-declare class TeacssGenerator<Theme extends object = object> extends TeacssGeneratorInternal<Theme> {
+export declare class TeacssGenerator<Theme extends object = object> extends TeacssGeneratorInternal<Theme> {
   /**
    * @deprecated `new TeacssGenerator` is deprecated, please use `createGenerator()` instead
    */
   constructor(userConfig?: UserConfig<Theme>, defaults?: UserConfigDefaults<Theme>);
 }
-declare function createGenerator<Theme extends object = object>(config?: UserConfig<Theme>, defaults?: UserConfigDefaults<Theme>): Promise<TeacssGenerator<Theme>>;
-declare const regexScopePlaceholder: RegExp;
-declare function hasScopePlaceholder(css: string): boolean;
-declare function toEscapedSelector(raw: string): string;
+export declare function createGenerator<Theme extends object = object>(config?: UserConfig<Theme>, defaults?: UserConfigDefaults<Theme>): Promise<TeacssGenerator<Theme>>;
+export declare const regexScopePlaceholder: RegExp;
+export declare function hasScopePlaceholder(css: string): boolean;
+export declare function toEscapedSelector(raw: string): string;
 //#endregion
 //#region src/types.d.ts
 /**
@@ -529,7 +516,7 @@ declare function toEscapedSelector(raw: string): string;
  * so the integration layer (which constructs one) still passes it directly, but
  * consumers of `@teacss/core` don't inherit a dependency on `magic-string`.
  */
-interface MagicStringLike {
+export interface MagicStringLike {
   readonly original: string;
   slice(start?: number, end?: number): string;
   toString(): string;
@@ -540,35 +527,36 @@ interface MagicStringLike {
   appendRight(index: number, content: string): MagicStringLike;
 }
 /** The result of resolving config from the CSS entry: the config + its source file(s). */
-interface LoadConfigResult<Config = any> {
+export interface LoadConfigResult<Config = any> {
   config: Config;
   sources: string[];
 }
-type Awaitable<T> = T | Promise<T>;
-type Arrayable<T> = T | T[];
-type ToArray<T> = T extends any[] ? T[number][] : T extends readonly (infer U)[] ? readonly U[] : T[];
-type ArgumentType<T> = T extends ((...args: infer A) => any) ? A : never;
-type Shift<T> = T extends [_: any, ...args: infer A] ? A : never;
-type RestArgs<T> = Shift<ArgumentType<T>>;
-type DeepPartial<T> = { [P in keyof T]?: DeepPartial<T[P]>; };
-type FlatObjectTuple<T> = { [K in keyof T]: T[K]; };
-type PartialByKeys<T, K extends keyof T = keyof T> = FlatObjectTuple<Partial<Pick<T, Extract<keyof T, K>>> & Omit<T, K>>;
-type RequiredByKey<T, K extends keyof T = keyof T> = FlatObjectTuple<Required<Pick<T, Extract<keyof T, K>>> & Omit<T, K>>;
-type CSSObject = Record<string, string | number | undefined>;
+export type Awaitable<T> = T | Promise<T>;
+export type Arrayable<T> = T | T[];
+export type ToArray<T> = T extends any[] ? T[number][] : T extends readonly (infer U)[] ? readonly U[] : T[];
+export type ArgumentType<T> = T extends ((...args: infer A) => any) ? A : never;
+export type Shift<T> = T extends [_: any, ...args: infer A] ? A : never;
+export type RestArgs<T> = Shift<ArgumentType<T>>;
+export type DeepPartial<T> = { [P in keyof T]?: DeepPartial<T[P]>; };
+export type FlatObjectTuple<T> = { [K in keyof T]: T[K]; };
+export type PartialByKeys<T, K extends keyof T = keyof T> = FlatObjectTuple<Partial<Pick<T, Extract<keyof T, K>>> & Omit<T, K>>;
+export type RequiredByKey<T, K extends keyof T = keyof T> = FlatObjectTuple<Required<Pick<T, Extract<keyof T, K>>> & Omit<T, K>>;
+export type CSSObject = Record<string, string | number | undefined>;
 /**
  * [property, value, operators?]
  *
- * - operators: Used to perform specific operations on value or property.
+ * The optional third slot is retained as entry data for custom processors.
+ * Core does not execute operators; CSS serialization uses only property and value.
  */
-type CSSEntry = [string, string | number | undefined, Arrayable<string>?];
-type CSSEntries = CSSEntry[];
-type CSSObjectInput = CSSObject | Partial<ControlSymbolsValue>;
-type CSSEntriesInput = (CSSEntry | ControlSymbolsEntry)[];
-type CSSValueInput = CSSObjectInput | CSSEntriesInput | CSSValue;
-interface PresetOptions {
+export type CSSEntry = [string, string | number | undefined, Arrayable<string>?];
+export type CSSEntries = CSSEntry[];
+export type CSSObjectInput = CSSObject | Partial<ControlSymbolsValue>;
+export type CSSEntriesInput = (CSSEntry | ControlSymbolsEntry)[];
+export type CSSValueInput = CSSObjectInput | CSSEntriesInput | CSSValue;
+export interface PresetOptions {
   [key: string]: any;
 }
-interface RuleContext<Theme extends object = object> {
+export interface RuleContext<Theme extends object = object> {
   /**
    * Unprocessed selector from user input.
    * Useful for generating CSS rule.
@@ -576,6 +564,8 @@ interface RuleContext<Theme extends object = object> {
   rawSelector: string;
   /**
    * Current selector for rule matching
+   * In shortcut leaf rule callbacks, this is the leaf after variant matching;
+   * rawSelector remains the outer token being styled.
    */
   currentSelector: string;
   /**
@@ -595,7 +585,7 @@ interface RuleContext<Theme extends object = object> {
    */
   variantHandlers: VariantHandler[];
   /**
-   * The result of variant matching.
+   * The result of variant matching for the current parse branch.
    */
   variantMatch: VariantMatchedResult<Theme>;
   /**
@@ -625,7 +615,7 @@ declare const SymbolSelector: unique symbol;
 declare const SymbolLayer: unique symbol;
 declare const SymbolSort: unique symbol;
 declare const SymbolBody: unique symbol;
-interface ControlSymbols {
+export interface ControlSymbols {
   /**
    * Prevent merging in shortcuts
    */
@@ -639,7 +629,8 @@ interface ControlSymbols {
    */
   readonly noScope: typeof SymbolNoScope;
   /**
-   * Additional variants applied to this rule
+   * Additional variants applied to this rule output. Functional values receive
+   * a private handler list; inserting or removing handlers leaves siblings intact.
    */
   readonly variants: typeof SymbolVariants;
   /**
@@ -663,7 +654,7 @@ interface ControlSymbols {
    */
   readonly body: typeof SymbolBody;
 }
-interface ControlSymbolsValue {
+export interface ControlSymbolsValue {
   [SymbolShortcutsNoMerge]: boolean;
   [SymbolNoMerge]: boolean;
   [SymbolNoScope]: boolean;
@@ -674,9 +665,9 @@ interface ControlSymbolsValue {
   [SymbolSort]: number;
   [SymbolBody]: string;
 }
-type ObjectToEntry<T> = { [K in keyof T]: [K, T[K]]; }[keyof T];
-type ControlSymbolsEntry = ObjectToEntry<ControlSymbolsValue>;
-interface VariantContext<Theme extends object = object> {
+export type ObjectToEntry<T> = { [K in keyof T]: [K, T[K]]; }[keyof T];
+export type ControlSymbolsEntry = ObjectToEntry<ControlSymbolsValue>;
+export interface VariantContext<Theme extends object = object> {
   /**
    * Unprocessed selector from user input.
    */
@@ -690,14 +681,14 @@ interface VariantContext<Theme extends object = object> {
    */
   theme: Theme;
 }
-interface ExtractorContext {
+export interface ExtractorContext {
   readonly original: string;
   code: string;
   id?: string;
   extracted: Set<string> | CountableSet<string>;
   envMode?: "dev" | "build";
 }
-interface BaseContext<Theme extends object = object> {
+export interface BaseContext<Theme extends object = object> {
   /**
    * Generator instance
    */
@@ -707,12 +698,12 @@ interface BaseContext<Theme extends object = object> {
    */
   theme: Theme;
 }
-interface PreflightContext<Theme extends object = object> extends BaseContext<Theme> {
+export interface PreflightContext<Theme extends object = object> extends BaseContext<Theme> {
   /** Utilities produced for this generate() call after postprocessing, including cache hits and excluding preflights. */
   generated?: readonly StringifiedUtil<Theme>[];
 }
-interface SafeListContext<Theme extends object = object> extends BaseContext<Theme> {}
-interface Extractor {
+export interface SafeListContext<Theme extends object = object> extends BaseContext<Theme> {}
+export interface Extractor {
   name: string;
   order?: number;
   /**
@@ -722,7 +713,7 @@ interface Extractor {
    */
   extract?: (ctx: ExtractorContext) => Awaitable<Set<string> | CountableSet<string> | string[] | undefined | void>;
 }
-interface RuleMeta {
+export interface RuleMeta {
   /**
    * The layer name of this rule.
    * @default 'default'
@@ -773,40 +764,40 @@ interface RuleMeta {
    */
   custom?: Record<string, any>;
 }
-type CSSValue = CSSObject | CSSEntries;
-type CSSValues = CSSValue | CSSValue[];
-type DynamicMatcher<Theme extends object = object> = (match: RegExpMatchArray, context: Readonly<RuleContext<Theme>>) => Awaitable<CSSValueInput | string | (CSSValueInput | string)[] | undefined> | Generator<CSSValueInput | string | undefined> | AsyncGenerator<CSSValueInput | string | undefined>;
-type DynamicRule<Theme extends object = object> = [RegExp, DynamicMatcher<Theme>, RuleMeta?];
-type StaticRule = [string, CSSObjectInput | CSSEntriesInput | (CSSValueInput | string)[], RuleMeta?];
-type Rule<Theme extends object = object> = DynamicRule<Theme> | StaticRule;
-type ExpansionValue = string | CSSValue;
-interface ExpansionInlineValue {
+export type CSSValue = CSSObject | CSSEntries;
+export type CSSValues = CSSValue | CSSValue[];
+export type DynamicMatcher<Theme extends object = object> = (match: RegExpMatchArray, context: Readonly<RuleContext<Theme>>) => Awaitable<CSSValueInput | string | (CSSValueInput | string)[] | undefined> | Generator<CSSValueInput | string | undefined> | AsyncGenerator<CSSValueInput | string | undefined>;
+export type DynamicRule<Theme extends object = object> = [RegExp, DynamicMatcher<Theme>, RuleMeta?];
+export type StaticRule = [string, CSSObjectInput | CSSEntriesInput | (CSSValueInput | string)[], RuleMeta?];
+export type Rule<Theme extends object = object> = DynamicRule<Theme> | StaticRule;
+export type ExpansionValue = string | CSSValue;
+export interface ExpansionInlineValue {
   handles: VariantHandler[];
   value: ExpansionValue;
 }
-type DynamicExpansionMatcher<Theme extends object = object> = (match: RegExpMatchArray, context: Readonly<RuleContext<Theme>>) => string | ExpansionValue[] | undefined;
-type DynamicShortcutMatcher<Theme extends object = object> = DynamicExpansionMatcher<Theme>;
-type StaticShortcut = [string, string | ExpansionValue[], RuleMeta?];
-type StaticShortcutMap = Record<string, string | ExpansionValue[]>;
-type DynamicShortcut<Theme extends object = object> = [RegExp, DynamicShortcutMatcher<Theme>, RuleMeta?];
-type UserShortcuts<Theme extends object = object> = StaticShortcutMap | (StaticShortcut | DynamicShortcut<Theme> | StaticShortcutMap)[];
-type Shortcut<Theme extends object = object> = StaticShortcut | DynamicShortcut<Theme>;
-type ShortcutInlineValue = ExpansionInlineValue;
-type ShortcutValue = ExpansionValue;
-type FilterPattern = ReadonlyArray<string | RegExp> | string | RegExp | null;
-interface Preflight<Theme extends object = object> {
+export type DynamicExpansionMatcher<Theme extends object = object> = (match: RegExpMatchArray, context: Readonly<RuleContext<Theme>>) => string | ExpansionValue[] | undefined;
+export type DynamicShortcutMatcher<Theme extends object = object> = DynamicExpansionMatcher<Theme>;
+export type StaticShortcut = [string, string | ExpansionValue[], RuleMeta?];
+export type StaticShortcutMap = Record<string, string | ExpansionValue[]>;
+export type DynamicShortcut<Theme extends object = object> = [RegExp, DynamicShortcutMatcher<Theme>, RuleMeta?];
+export type UserShortcuts<Theme extends object = object> = StaticShortcutMap | (StaticShortcut | DynamicShortcut<Theme> | StaticShortcutMap)[];
+export type Shortcut<Theme extends object = object> = StaticShortcut | DynamicShortcut<Theme>;
+export type ShortcutInlineValue = ExpansionInlineValue;
+export type ShortcutValue = ExpansionValue;
+export type FilterPattern = ReadonlyArray<string | RegExp> | string | RegExp | null;
+export interface Preflight<Theme extends object = object> {
   getCSS: (context: PreflightContext<Theme>) => Promise<string | undefined> | string | undefined;
   layer?: string;
 }
-interface BlocklistMeta {
+export interface BlocklistMeta {
   /**
    * Custom message to show why this selector is blocked.
    */
   message?: string | ((selector: string) => string);
 }
-type BlocklistValue = string | RegExp | ((selector: string) => boolean | null | undefined);
-type BlocklistRule = BlocklistValue | [BlocklistValue, BlocklistMeta];
-interface VariantHandlerContext {
+export type BlocklistValue = string | RegExp | ((selector: string) => boolean | null | undefined);
+export type BlocklistRule = BlocklistValue | [BlocklistValue, BlocklistMeta];
+export interface VariantHandlerContext {
   /**
    * Rewrite the output selector. Often be used to append parents.
    */
@@ -845,7 +836,7 @@ interface VariantHandlerContext {
    */
   noMerge?: boolean;
 }
-interface VariantHandler {
+export interface VariantHandler {
   /**
    * Callback to process the handler.
    */
@@ -879,8 +870,8 @@ interface VariantHandler {
    */
   layer?: string | undefined;
 }
-type VariantFunction<Theme extends object = object> = (matcher: string, context: Readonly<VariantContext<Theme>>) => Awaitable<string | VariantHandler | VariantHandler[] | undefined>;
-interface VariantObject<Theme extends object = object> {
+export type VariantFunction<Theme extends object = object> = (matcher: string, context: Readonly<VariantContext<Theme>>) => Awaitable<string | VariantHandler | VariantHandler[] | undefined>;
+export interface VariantObject<Theme extends object = object> {
   /**
    * The name of the variant.
    */
@@ -904,11 +895,11 @@ interface VariantObject<Theme extends object = object> {
    */
   autocomplete?: Arrayable<AutoCompleteFunction | AutoCompleteTemplate>;
 }
-type Variant<Theme extends object = object> = VariantFunction<Theme> | VariantObject<Theme>;
-type Preprocessor = (matcher: string) => string | undefined;
-type Postprocessor = (util: UtilObject) => void | UtilObject | (UtilObject | null | undefined)[];
-type ThemeExtender<Theme extends object = object> = (theme: Theme, config: Readonly<ResolvedConfig<Theme>>) => Theme | void;
-interface ConfigBase<Theme extends object = object> {
+export type Variant<Theme extends object = object> = VariantFunction<Theme> | VariantObject<Theme>;
+export type Preprocessor = (matcher: string) => string | undefined;
+export type Postprocessor = (util: UtilObject) => void | UtilObject | (UtilObject | null | undefined)[];
+export type ThemeExtender<Theme extends object = object> = (theme: Theme, config: Readonly<ResolvedConfig<Theme>>) => Theme | void;
+export interface ConfigBase<Theme extends object = object> {
   /**
    * Rules to generate CSS utilities.
    *
@@ -939,7 +930,8 @@ interface ConfigBase<Theme extends object = object> {
    */
   blocklist?: BlocklistRule[];
   /**
-   * Utilities that always been included
+   * Utilities always included in generation, unless `safelist: false` is passed.
+   * Static entries and callback results support `{a;b}@condition` groups.
    */
   safelist?: (string | ((context: SafeListContext<Theme>) => Arrayable<string>))[];
   /**
@@ -1019,7 +1011,11 @@ interface ConfigBase<Theme extends object = object> {
   /**
    * Hook to modify the resolved config.
    *
-   * First presets runs first and the user config
+   * Hooks run sequentially in resolved preset order, then the user hook.
+   * Returned promises are awaited; a throw or rejection aborts resolution.
+   * Rule indexes are rebuilt after all hooks finish. Return values are ignored.
+   * The void callback type accepts async functions while preserving existing
+   * synchronous callbacks that return an ignored value.
    */
   configResolved?: (config: ResolvedConfig<Theme>) => void;
   /**
@@ -1042,7 +1038,7 @@ interface ConfigBase<Theme extends object = object> {
    */
   transformers?: SourceCodeTransformer[];
 }
-interface OutputCssLayersOptions {
+export interface OutputCssLayersOptions {
   /**
    * Specify the css layer that the internal layer should be output to.
    *
@@ -1056,13 +1052,13 @@ interface OutputCssLayersOptions {
    */
   allLayers?: boolean;
 }
-type AutoCompleteTemplate = string;
-type AutoCompleteFunction = (input: string) => Awaitable<string[]>;
-interface AutoCompleteExtractorContext {
+export type AutoCompleteTemplate = string;
+export type AutoCompleteFunction = (input: string) => Awaitable<string[]>;
+export interface AutoCompleteExtractorContext {
   content: string;
   cursor: number;
 }
-interface Replacement {
+export interface Replacement {
   /**
    * The range of the original text
    */
@@ -1073,7 +1069,7 @@ interface Replacement {
    */
   replacement: string;
 }
-interface SuggestResult {
+export interface SuggestResult {
   /**
    * The generated suggestions
    *
@@ -1086,7 +1082,7 @@ interface SuggestResult {
    */
   resolveReplacement: (suggestion: string) => Replacement;
 }
-interface AutoCompleteExtractorResult {
+export interface AutoCompleteExtractorResult {
   /**
    * The extracted string
    */
@@ -1100,12 +1096,12 @@ interface AutoCompleteExtractorResult {
    */
   transformSuggestions?: (suggestions: string[]) => string[];
 }
-interface AutoCompleteExtractor {
+export interface AutoCompleteExtractor {
   name: string;
   extract: (context: AutoCompleteExtractorContext) => Awaitable<AutoCompleteExtractorResult | null>;
   order?: number;
 }
-interface Preset<Theme extends object = object> extends ConfigBase<Theme> {
+export interface Preset<Theme extends object = object> extends ConfigBase<Theme> {
   name: string;
   /**
    * Enforce the preset to be applied before or after other presets
@@ -1132,11 +1128,11 @@ interface Preset<Theme extends object = object> extends ConfigBase<Theme> {
    */
   meta?: Record<string, any>;
 }
-type PresetFactory<Theme extends object = object, PresetOptions extends object | undefined = undefined> = (options?: PresetOptions) => Preset<Theme>;
-type PresetFactoryAwaitable<Theme extends object = object, PresetOptions extends object | undefined = undefined> = (options?: PresetOptions) => Awaitable<Preset<Theme>>;
-type PresetOrFactory<Theme extends object = object> = Preset<Theme> | PresetFactory<Theme, any>;
-type PresetOrFactoryAwaitable<Theme extends object = object> = PresetOrFactory<Theme> | Promise<Preset<Theme>> | PresetFactoryAwaitable<Theme>;
-interface GeneratorOptions {
+export type PresetFactory<Theme extends object = object, PresetOptions extends object | undefined = undefined> = (options?: PresetOptions) => Preset<Theme>;
+export type PresetFactoryAwaitable<Theme extends object = object, PresetOptions extends object | undefined = undefined> = (options?: PresetOptions) => Awaitable<Preset<Theme>>;
+export type PresetOrFactory<Theme extends object = object> = Preset<Theme> | PresetFactory<Theme, any>;
+export type PresetOrFactoryAwaitable<Theme extends object = object> = PresetOrFactory<Theme> | Promise<Preset<Theme>> | PresetFactoryAwaitable<Theme>;
+export interface GeneratorOptions {
   /**
    * Merge utilities with the exact same body to save the file size
    *
@@ -1150,7 +1146,7 @@ interface GeneratorOptions {
    */
   warn?: boolean;
 }
-interface UserOnlyOptions<Theme extends object = object> {
+export interface UserOnlyOptions<Theme extends object = object> {
   /**
    * Opt-in reporting for token-shaped candidates that match no rule. With the
    * default `"off"`, unmatched tokens stay silent, nothing is collected, and
@@ -1190,12 +1186,12 @@ interface UserOnlyOptions<Theme extends object = object> {
 /**
  * For cli config
  */
-interface CliOptions {
+export interface CliOptions {
   cli?: {
     entry?: Arrayable<CliEntryItem>;
   };
 }
-interface TeacssPluginContext<Config extends UserConfig = UserConfig> {
+export interface TeacssPluginContext<Config extends UserConfig = UserConfig> {
   /**
    * Singleton promise for config loading
    */
@@ -1228,16 +1224,18 @@ interface TeacssPluginContext<Config extends UserConfig = UserConfig> {
   extract: (code: string, id?: string) => Promise<void>;
   reloadConfig: () => Promise<LoadConfigResult<Config>>;
   getConfig: () => Promise<Config>;
-  /** Subscribe to config reloads. Returns a function that removes the listener. */
+  /** Subscribe to config reloads. Async failures are reported without delaying publication. Returns a disposer. */
   onReload: (fn: () => void) => () => void;
   invalidate: () => void;
-  /** Subscribe to generated-output invalidations. Returns a function that removes the listener. */
+  /** Subscribe to generated-output invalidations. Async failures are reported without delaying notification. Returns a disposer. */
   onInvalidate: (fn: () => void) => () => void;
   root: string;
   updateRoot: (root: string) => Promise<LoadConfigResult<Config>>;
   getConfigFileList: () => string[];
   /**
    * Get regexes to match virtual module ids
+   * Full matches include directory prefixes; layer/query captures are preserved.
+   * Virtual names in query or fragment suffixes are not matched as filenames.
    */
   getVMPRegexes: () => Promise<{
     prefix: string;
@@ -1245,7 +1243,7 @@ interface TeacssPluginContext<Config extends UserConfig = UserConfig> {
     RESOLVED_ID_RE: RegExp;
   }>;
 }
-interface SourceMap {
+export interface SourceMap {
   file?: string;
   mappings?: string;
   names?: string[];
@@ -1253,13 +1251,13 @@ interface SourceMap {
   sourcesContent?: string[];
   version?: number;
 }
-interface HighlightAnnotation {
+export interface HighlightAnnotation {
   offset: number;
   length: number;
   className: string;
 }
-type SourceCodeTransformerEnforce = "pre" | "post" | "default";
-interface SourceCodeTransformer {
+export type SourceCodeTransformerEnforce = "pre" | "post" | "default";
+export interface SourceCodeTransformer {
   name: string;
   /**
    * The order of transformer
@@ -1280,7 +1278,7 @@ interface SourceCodeTransformer {
    */
   onModuleRemoved?: (id: string, ctx: TeacssPluginContext) => Awaitable<void>;
 }
-interface ContentOptions {
+export interface ContentOptions {
   /**
    * Glob patterns to extract from the file system, in addition to other content sources.
    *
@@ -1314,7 +1312,7 @@ interface ContentOptions {
      * By default, `.ts` and `.js` files are NOT extracted.
      *
      * @see https://www.npmjs.com/package/picomatch
-     * @default [/\.(vue|svelte|[jt]sx|vine.ts|mdx?|astro|elm|php|phtml|marko|html)($|\?)/]
+     * @default [/\.(vue|svelte|[jt]sx|vine\.ts|mdx?|astro|elm|php|phtml|marko|html)($|\?)/]
      */
     include?: FilterPattern;
     /**
@@ -1332,7 +1330,7 @@ interface ContentOptions {
 /**
  * For other modules to aggregate the options
  */
-interface PluginOptions {
+export interface PluginOptions {
   /**
    * Custom transformers to the source code
    */
@@ -1349,9 +1347,9 @@ interface PluginOptions {
    */
   content?: ContentOptions;
 }
-interface UserConfig<Theme extends object = object> extends ConfigBase<Theme>, UserOnlyOptions<Theme>, GeneratorOptions, PluginOptions, CliOptions {}
-interface UserConfigDefaults<Theme extends object = object> extends ConfigBase<Theme>, UserOnlyOptions<Theme> {}
-interface ResolvedConfig<Theme extends object = object> extends Omit<RequiredByKey<UserConfig<Theme>, "mergeSelectors" | "theme" | "rules" | "variants" | "layers" | "extractors" | "blocklist" | "safelist" | "preflights" | "sortLayers">, "rules" | "shortcuts" | "autocomplete" | "presets"> {
+export interface UserConfig<Theme extends object = object> extends ConfigBase<Theme>, UserOnlyOptions<Theme>, GeneratorOptions, PluginOptions, CliOptions {}
+export interface UserConfigDefaults<Theme extends object = object> extends ConfigBase<Theme>, UserOnlyOptions<Theme> {}
+export interface ResolvedConfig<Theme extends object = object> extends Omit<RequiredByKey<UserConfig<Theme>, "mergeSelectors" | "theme" | "rules" | "variants" | "layers" | "extractors" | "blocklist" | "safelist" | "preflights" | "sortLayers">, "rules" | "shortcuts" | "autocomplete" | "presets"> {
   presets: Preset<Theme>[];
   shortcuts: Shortcut<Theme>[];
   variants: VariantObject<Theme>[];
@@ -1368,14 +1366,14 @@ interface ResolvedConfig<Theme extends object = object> extends Omit<RequiredByK
   };
   separators: string[];
 }
-interface UnmatchedTokenDiagnostic {
+export interface UnmatchedTokenDiagnostic {
   token: string;
   suggestions: string[];
 }
-interface GenerateDiagnostics {
+export interface GenerateDiagnostics {
   unmatched: UnmatchedTokenDiagnostic[];
 }
-interface GenerateResult<T = Set<string>> {
+export interface GenerateResult<T = Set<string>> {
   css: string;
   layers: string[];
   getLayer: (name?: string) => string | undefined;
@@ -1385,12 +1383,12 @@ interface GenerateResult<T = Set<string>> {
   /** Token-shaped candidates that matched no rule; populated only when the opt-in `unmatched` option is enabled, suggestions compute lazily on first read. */
   diagnostics: GenerateDiagnostics;
 }
-type VariantMatchedResult<Theme extends object = object> = [raw: string, current: string, variantHandlers: VariantHandler[], variants: Set<Variant<Theme>>];
-type ParsedUtil = readonly [index: number, raw: string, entries: CSSEntriesInput, meta: RuleMeta | undefined, variantHandlers: VariantHandler[]];
-type RawUtil = readonly [index: number, rawCSS: string, meta: RuleMeta | undefined];
-type StringifiedUtil<Theme extends object = object> = readonly [index: number, selector: string | undefined, body: string, parent: string | undefined, meta: RuleMeta | undefined, context: RuleContext<Theme> | undefined, noMerge: boolean | undefined];
-type PreparedRule = readonly [selector: [string, number][], body: string, noMerge: boolean];
-interface CliEntryItem {
+export type VariantMatchedResult<Theme extends object = object> = [raw: string, current: string, variantHandlers: VariantHandler[], variants: Set<Variant<Theme>>];
+export type ParsedUtil = readonly [index: number, raw: string, entries: CSSEntriesInput, meta: RuleMeta | undefined, variantHandlers: VariantHandler[]];
+export type RawUtil = readonly [index: number, rawCSS: string, meta: RuleMeta | undefined];
+export type StringifiedUtil<Theme extends object = object> = readonly [index: number, selector: string | undefined, body: string, parent: string | undefined, meta: RuleMeta | undefined, context: RuleContext<Theme> | undefined, noMerge: boolean | undefined];
+export type PreparedRule = readonly [selector: [string, number][], body: string, noMerge: boolean];
+export interface CliEntryItem {
   patterns: string[];
   outFile: string;
   /**
@@ -1414,7 +1412,7 @@ interface CliEntryItem {
    */
   splitCss?: boolean | "multi" | "single";
 }
-interface UtilObject {
+export interface UtilObject {
   selector: string;
   entries: CSSEntriesInput;
   parent: string | undefined;
@@ -1425,7 +1423,7 @@ interface UtilObject {
 /**
  * Returned from `tea.generate()` when `extendedInfo` option is enabled.
  */
-interface ExtendedTokenInfo<Theme extends object = object> {
+export interface ExtendedTokenInfo<Theme extends object = object> {
   /**
    * Stringified util data
    */
@@ -1435,7 +1433,7 @@ interface ExtendedTokenInfo<Theme extends object = object> {
    */
   count: number;
 }
-interface GenerateOptions<T extends boolean> {
+export interface GenerateOptions<T extends boolean> {
   /**
    * Filepath of the file being processed.
    */
@@ -1461,6 +1459,18 @@ interface GenerateOptions<T extends boolean> {
    */
   tokenConcurrency?: number;
   /**
+   * Synchronous, side-effect-free check for externally extracted input.
+   * Called repeatedly across generation boundaries and before diagnostics.
+   * Returning false rejects generation; thrown errors propagate. Omit to
+   * preserve normal config retries. This does not cancel running hooks or
+   * undo previously published diagnostics.
+   */
+  isInputCurrent?: () => boolean;
+  /**
+   * Scope generated selectors to a CSS selector or selector list. Each scope
+   * arm is applied independently, preserving its own specificity.
+   * An empty string disables scoping; empty or comment-only list arms reject
+   * generation rather than emitting unscoped selectors.
    * @experimental
    */
   scope?: string;
@@ -1471,7 +1481,7 @@ interface GenerateOptions<T extends boolean> {
 }
 //#endregion
 //#region src/condition-variant.d.ts
-interface ConditionVariantOptions {
+export interface ConditionVariantOptions {
   /**
    * Variant name (for debugging / `details`).
    * @default "at-condition"
@@ -1490,32 +1500,32 @@ interface ConditionVariantOptions {
  * If any condition is unrecognized by the resolvers, the token is left unclaimed
  * (`undefined`), preserving the generator's behavior for unknown tokens.
  */
-declare function createConditionVariant<Theme extends object = object>(resolvers: ConditionResolver[], options?: ConditionVariantOptions): VariantObject<Theme>;
+export declare function createConditionVariant<Theme extends object = object>(resolvers: ConditionResolver[], options?: ConditionVariantOptions): VariantObject<Theme>;
 //#endregion
 //#region src/config.d.ts
-declare function resolveShortcuts<Theme extends object = object>(shortcuts: UserShortcuts<Theme>): Shortcut<Theme>[];
+export declare function resolveShortcuts<Theme extends object = object>(shortcuts: UserShortcuts<Theme>): Shortcut<Theme>[];
 /**
  * Resolve a single preset, nested presets are ignored
  */
-declare function resolvePreset<Theme extends object = object>(presetInput: PresetOrFactoryAwaitable<Theme>): Promise<Preset<Theme>>;
+export declare function resolvePreset<Theme extends object = object>(presetInput: PresetOrFactoryAwaitable<Theme>): Promise<Preset<Theme>>;
 /**
  * Resolve presets with nested presets
  */
-declare function resolvePresets<Theme extends object = object>(preset: PresetOrFactoryAwaitable<Theme>): Promise<Preset<Theme>[]>;
-declare function resolveConfig<Theme extends object = object>(userConfig?: UserConfig<Theme>, defaults?: UserConfigDefaults<Theme>): Promise<ResolvedConfig<Theme>>;
-declare function mergeConfigs<Theme extends object = object>(configs: UserConfig<Theme>[]): UserConfig<Theme>;
-declare function definePreset<Options extends object | undefined = undefined, Theme extends object = object>(preset: PresetFactory<Theme, Options>): PresetFactory<Theme, Options>;
-declare function definePreset<Options extends object | undefined = undefined, Theme extends object = object>(preset: PresetFactoryAwaitable<Theme, Options>): PresetFactoryAwaitable<Theme, Options>;
-declare function definePreset<Theme extends object = object>(preset: Preset<Theme>): Preset<Theme>;
+export declare function resolvePresets<Theme extends object = object>(preset: PresetOrFactoryAwaitable<Theme>): Promise<Preset<Theme>[]>;
+export declare function resolveConfig<Theme extends object = object>(userConfig?: UserConfig<Theme>, defaults?: UserConfigDefaults<Theme>): Promise<ResolvedConfig<Theme>>;
+export declare function mergeConfigs<Theme extends object = object>(configs: UserConfig<Theme>[]): UserConfig<Theme>;
+export declare function definePreset<Options extends object | undefined = undefined, Theme extends object = object>(preset: PresetFactory<Theme, Options>): PresetFactory<Theme, Options>;
+export declare function definePreset<Options extends object | undefined = undefined, Theme extends object = object>(preset: PresetFactoryAwaitable<Theme, Options>): PresetFactoryAwaitable<Theme, Options>;
+export declare function definePreset<Theme extends object = object>(preset: Preset<Theme>): Preset<Theme>;
 //#endregion
 //#region src/constants.d.ts
-declare const LAYER_IMPORTS = "imports";
-declare const LAYER_PRIMITIVES = "primitives";
-declare const LAYER_PROPERTIES = "properties";
-declare const LAYER_PREFLIGHTS = "preflights";
-declare const LAYER_SHORTCUTS = "shortcuts";
-declare const LAYER_UTILITIES = "utilities";
-declare const DEFAULT_LAYERS: Readonly<{
+export declare const LAYER_IMPORTS = "imports";
+export declare const LAYER_PRIMITIVES = "primitives";
+export declare const LAYER_PROPERTIES = "properties";
+export declare const LAYER_PREFLIGHTS = "preflights";
+export declare const LAYER_SHORTCUTS = "shortcuts";
+export declare const LAYER_UTILITIES = "utilities";
+export declare const DEFAULT_LAYERS: Readonly<{
   imports: -200;
   properties: -150;
   preflights: -100;
@@ -1525,25 +1535,25 @@ declare const DEFAULT_LAYERS: Readonly<{
 }>;
 //#endregion
 //#region src/env.d.ts
-declare function getEnvFlags(): {
+export declare function getEnvFlags(): {
   isNode: boolean;
   isVSCode: boolean;
   isESLint: boolean;
 };
 //#endregion
 //#region src/extractors/split.d.ts
-declare const defaultSplitRE: RegExp;
-declare const splitWithVariantGroupRE: RegExp;
-declare const extractorSplit: Extractor;
+export declare const defaultSplitRE: RegExp;
+export declare const splitWithVariantGroupRE: RegExp;
+export declare const extractorSplit: Extractor;
 //#endregion
 //#region src/group.d.ts
 /** Expand groups in host source, including groups nested in strings/arrays. */
-declare function expandGroups(code: string): string;
+export declare function expandGroups(code: string): string;
 /** Expand groups in a class list while preserving braces inside attached literals. */
-declare function expandClassGroups(code: string): string;
+export declare function expandClassGroups(code: string): string;
 //#endregion
 //#region src/hash.d.ts
-declare function getHash(input: string, length?: number): string;
+export declare function getHash(input: string, length?: number): string;
 //#endregion
 //#region src/literal.d.ts
 /**
@@ -1570,7 +1580,7 @@ declare function getHash(input: string, length?: number): string;
  * or backticks as delimiters. It is for already-isolated class-list surfaces
  * such as shortcuts, `cn()`, and `@apply`.
  */
-declare function splitClassTokens(input: string): string[];
+export declare function splitClassTokens(input: string): string[];
 /**
  * Expand `_` to a space inside an arbitrary `[]` region.
  *
@@ -1578,16 +1588,16 @@ declare function splitClassTokens(input: string): string[];
  * - `_` at paren depth 0 → a space.
  * - `_` inside `(…)` → kept literal (so `var(--my_var)` survives).
  */
-declare function expandUnderscores(content: string): string;
+export declare function expandUnderscores(content: string): string;
 /**
  * Add surrounding spaces to `+ - * /` operators inside balanced `calc()` /
  * `clamp()` / `min()` / `max()` functions without rewriting adjacent values,
  * quoted text, URLs, custom-property names, or numeric exponent signs.
  */
-declare function spaceCalcOperators(str: string): string;
+export declare function spaceCalcOperators(str: string): string;
 /** True when `value` is a single `[…]` arbitrary region. */
-declare function isArbitrary(value: string): boolean;
-interface NormalizeArbitraryOptions {
+export declare function isArbitrary(value: string): boolean;
+export interface NormalizeArbitraryOptions {
   /**
    * Apply `calc` / `clamp` / `min` / `max` operator spacing.
    * @default true
@@ -1610,18 +1620,18 @@ interface NormalizeArbitraryOptions {
  * @example normalizeArbitraryValue("calc(100%-1rem)") // "calc(100% - 1rem)"
  * @example normalizeArbitraryValue("var(--my_var)")   // "var(--my_var)"
  */
-declare function normalizeArbitraryValue(value: string, options?: NormalizeArbitraryOptions): string;
+export declare function normalizeArbitraryValue(value: string, options?: NormalizeArbitraryOptions): string;
 //#endregion
 //#region src/markers.d.ts
-declare const INCLUDE_COMMENT = "@teacss-include";
-declare const IGNORE_COMMENT = "@teacss-ignore";
-declare const INCLUDE_COMMENT_IDE = "@teacss-ide-include";
-declare const CSS_PLACEHOLDER = "@teacss-placeholder";
-declare const SKIP_START_COMMENT = "@teacss-skip-start";
-declare const SKIP_END_COMMENT = "@teacss-skip-end";
-declare const SKIP_COMMENT_RE: RegExp;
-declare const VIRTUAL_ENTRY_ALIAS: RegExp[];
-declare const LAYER_MARK_ALL = "__ALL__";
+export declare const INCLUDE_COMMENT = "@teacss-include";
+export declare const IGNORE_COMMENT = "@teacss-ignore";
+export declare const INCLUDE_COMMENT_IDE = "@teacss-ide-include";
+export declare const CSS_PLACEHOLDER = "@teacss-placeholder";
+export declare const SKIP_START_COMMENT = "@teacss-skip-start";
+export declare const SKIP_END_COMMENT = "@teacss-skip-end";
+export declare const SKIP_COMMENT_RE: RegExp;
+export declare const VIRTUAL_ENTRY_ALIAS: RegExp[];
+export declare const LAYER_MARK_ALL = "__ALL__";
 //#endregion
 //#region src/token.d.ts
 /**
@@ -1644,12 +1654,13 @@ declare const LAYER_MARK_ALL = "__ALL__";
  * - `()` and `[]` are literal regions; operators inside them (`:` `!` `@` …) do
  *   not participate in parsing.
  * - `!` immediately after the value (before any `@`) is `!important`.
- * - The value extends up to the first depth-0 `!` or `@`.
+ * - The declaration ends at the first depth-0 `@` or the token's end. Only a
+ *   trailing depth-0 `!` is stripped; other bangs remain for later validation.
  * - Zero or more `@cond` segments follow; each is captured verbatim (without its
  *   leading `@`). Interpreting a condition (pseudo / target / media / NOT `!…` …)
  *   belongs to the condition pipeline.
  */
-interface ParsedClassToken {
+export interface ParsedClassToken {
   /** The full original token, unchanged. */
   raw: string;
   /** Declaration body without the trailing `!` or any `@cond` (e.g. `bg:red`, `d:flex`, `content:[""]`). */
@@ -1672,6 +1683,6 @@ interface ParsedClassToken {
  * unbalanced brackets) are parsed leniently rather than throwing — validation is
  * left to the rule layer.
  */
-declare function parseClassToken(raw: string): ParsedClassToken;
+export declare function parseClassToken(raw: string): ParsedClassToken;
 //#endregion
-export { ArgumentType, Arrayable, AutoCompleteExtractor, AutoCompleteExtractorContext, AutoCompleteExtractorResult, AutoCompleteFunction, AutoCompleteTemplate, Awaitable, BaseContext, BetterMap, BlocklistMeta, BlocklistRule, BlocklistValue, BuiltConditionSelector, CSSEntries, CSSEntriesInput, CSSEntry, CSSObject, CSSObjectInput, CSSValue, CSSValueInput, CSSValues, CSS_PLACEHOLDER, CliEntryItem, CliOptions, ComparableWidth, ConditionKind, ConditionResolveContext, ConditionResolver, ConditionVariantOptions, ConfigBase, ContentOptions, ControlSymbols, ControlSymbolsEntry, ControlSymbolsValue, CountableSet, DEFAULT_LAYERS, DeepPartial, DynamicExpansionMatcher, DynamicMatcher, DynamicRule, DynamicShortcut, DynamicShortcutMatcher, Emitter, ExpansionInlineValue, ExpansionValue, ExtendedTokenInfo, Extractor, ExtractorContext, FilterPattern, FlatObjectTuple, GenerateDiagnostics, GenerateOptions, GenerateResult, GeneratorOptions, HighlightAnnotation, IGNORE_COMMENT, INCLUDE_COMMENT, INCLUDE_COMMENT_IDE, LAYER_IMPORTS, LAYER_MARK_ALL, LAYER_PREFLIGHTS, LAYER_PRIMITIVES, LAYER_PROPERTIES, LAYER_SHORTCUTS, LAYER_UTILITIES, LoadConfigResult, MagicStringLike, NormalizeArbitraryOptions, ObjectToEntry, OutputCssLayersOptions, ParsedClassToken, ParsedCondition, ParsedUtil, PartialByKeys, PluginOptions, Postprocessor, Preflight, PreflightContext, PreparedGeneratorConfig, PreparedRule, Preprocessor, Preset, PresetFactory, PresetFactoryAwaitable, PresetOptions, PresetOrFactory, PresetOrFactoryAwaitable, RESET_KEY, RawUtil, Replacement, RequiredByKey, ResolveConditionsResult, ResolvedCondition, ResolvedConfig, RestArgs, Rule, RuleContext, RuleMeta, SKIP_COMMENT_RE, SKIP_END_COMMENT, SKIP_START_COMMENT, SafeListContext, Shift, Shortcut, ShortcutInlineValue, ShortcutValue, SourceCodeTransformer, SourceCodeTransformerEnforce, SourceMap, StaticRule, StaticShortcut, StaticShortcutMap, StringifiedUtil, SuggestResult, TeacssGenerator, TeacssPluginContext, ThemeExtender, ToArray, TwoKeyMap, UnmatchedTokenDiagnostic, Unsubscribe, UserConfig, UserConfigDefaults, UserOnlyOptions, UserShortcuts, UtilObject, VIRTUAL_ENTRY_ALIAS, Variant, VariantContext, VariantFunction, VariantHandler, VariantHandlerContext, VariantMatchedResult, VariantObject, VirtualKey, attributifyRE, buildConditionSelector, clearIdenticalEntries, clone, collapseVariantGroup, comparableWidth, compareParentAtRules, createConditionVariant, createGenerator, createNanoEvents, cssIdRE, defaultSplitRE, definePreset, diagnoseUnmatchedToken, e, entriesToCss, escapeRegExp, escapeSelector, expandClassGroups, expandGroups, expandUnderscores, expandVariantGroup, extractorSplit as extractorDefault, extractorSplit, getEnvFlags, getHash, getPath, hasScopePlaceholder, hash, isArbitrary, isAttributifySelector, isCountableSet, isCssId, isObject, isRawUtil, isStaticRule, isStaticShortcut, isString, isThenable, isTokenShaped, isValidSelector, isValidTargetSelector, makeRegexClassGroup, mergeConfigs, mergeDeep, noop, normalizeArbitraryValue, normalizeCSSEntries, normalizeCSSValues, normalizeVariant, notNull, parseClassToken, parseCondition, parseConditions, parseVariantGroup, regexScopePlaceholder, replaceAsync, resolveConditions, resolveConfig, resolvePreset, resolvePresets, resolveShortcuts, restoreSkipCode, spaceCalcOperators, splitClassTokens, splitWithVariantGroupRE, symbols, toArray, toEscapedSelector, tokenConditionBase, transformSkipCode, uniq, uniqueBy, validateFilterRE, warnOnce, withLayer };
+export { extractorSplit as extractorDefault };