@teacss/engine 0.8.5-alpha.3 → 0.9.0-alpha.3

package/dist/facade/generator.js

@@ -0,0 +1,777 @@
+// `FacadeGenerator`: the object `createGenerator` returns, shaped like the 0.8.2 `TeacssGenerator`
+// (v02.9 §3.2) and backed by the Rust engine or, after a fallback, a TypeScript generator.
+// The tooling members (`makeContext`, `parseUtil`, ...) forward to a TypeScript generator and
+// return its objects: a `RuleContext.generator` there is that generator, not the facade.
+import { Engine } from "../../binding.js";
+import { createConfigView } from "./config-view.js";
+import { ENGINE_INSTANCE, ENGINE_MATERIALIZE, ENGINE_PACKAGE_VERSION, ENGINE_STATS } from "./constants.js";
+import { BoundedSet, BoundedTokenCache, CountableSet, copyCountableSet, expandInputGroups, isCountableSet } from "./countable-set.js";
+import { tsNotReadyError } from "./errors.js";
+import { buildMatched, createFacadeResult, describeUnmatched, fallbackIsTokenShaped, formatUnmatchedError, toTuple } from "./result.js";
+import { translateConfig } from "./select.js";
+import { createCompileClassTransformer } from "./transformer.js";
+import { createTsFallback } from "./ts-fallback.js";
+/** Port of core/utils/events.ts:84-112. */
+export function createNanoEvents() {
+    return {
+        events: Object.create(null),
+        emit(event, ...args) {
+            const listeners = Object.hasOwn(this.events, event) && Array.isArray(this.events[event]) ? [...this.events[event]] : [];
+            for (const listener of listeners)
+                listener(...args);
+        },
+        on(event, cb) {
+            const existing = Object.hasOwn(this.events, event) ? this.events[event] : undefined;
+            const listeners = Array.isArray(existing) ? existing : [];
+            if (listeners !== existing)
+                this.events[event] = listeners;
+            listeners.push(cb);
+            let subscribed = true;
+            return () => {
+                if (!subscribed)
+                    return;
+                const current = Object.hasOwn(this.events, event) && Array.isArray(this.events[event]) ? this.events[event] : [];
+                this.events[event] = current.filter((listener) => listener !== cb);
+                subscribed = false;
+            };
+        },
+    };
+}
+/** Port of core/utils/escape.ts:10-72 (CSSOM "serialize an identifier"). */
+export function escapeSelector(str) {
+    const length = str.length;
+    const firstCodeUnit = str.charCodeAt(0);
+    let result = "";
+    for (let index = 0; index < length; index++) {
+        const codeUnit = str.charCodeAt(index);
+        if (codeUnit === 0x0000) {
+            result += "\uFFFD";
+            continue;
+        }
+        if ((codeUnit >= 0x0001 && codeUnit <= 0x001f) || codeUnit === 0x007f || (index === 0 && codeUnit >= 0x0030 && codeUnit <= 0x0039) || (index === 1 && codeUnit >= 0x0030 && codeUnit <= 0x0039 && firstCodeUnit === 0x002d)) {
+            result += `\\${codeUnit.toString(16)} `;
+            continue;
+        }
+        if (index === 0 && length === 1 && codeUnit === 0x002d) {
+            result += `\\${str.charAt(index)}`;
+            continue;
+        }
+        if (codeUnit >= 0x0080 || codeUnit === 0x002d || codeUnit === 0x005f || (codeUnit >= 0x0030 && codeUnit <= 0x0039) || (codeUnit >= 0x0041 && codeUnit <= 0x005a) || (codeUnit >= 0x0061 && codeUnit <= 0x007a)) {
+            result += str.charAt(index);
+            continue;
+        }
+        result += `\\${str.charAt(index)}`;
+    }
+    return result;
+}
+const attributifyRe = /^\[(.+?)(~?=)"(.*)"\]$/;
+/** generator.ts:3722. */
+export function toEscapedSelector(raw) {
+    if (attributifyRe.test(raw))
+        return raw.replace(attributifyRe, (_, name, sign, value) => `[${escapeSelector(name)}${sign}"${escapeSelector(value)}"]`);
+    return `.${escapeSelector(raw)}`;
+}
+/**
+ * generator.ts:393-440: the selector with each whole occurrence of the token's own selector
+ * replaced by `&`, skipping strings, comments, escapes and attribute brackets.
+ */
+function normalizedSelector(selector, raw, escape) {
+    if (selector === undefined)
+        return undefined;
+    const subject = escape(raw);
+    const attributeSubject = subject.startsWith("[");
+    let brackets = 0;
+    let quote;
+    let cursor = 0;
+    let normalized = "";
+    for (let index = 0; index < selector.length; index++) {
+        const char = selector[index];
+        if (quote) {
+            if (char === "\\")
+                index++;
+            else if (char === quote)
+                quote = undefined;
+            continue;
+        }
+        if (char === "/" && selector[index + 1] === "*") {
+            const end = selector.indexOf("*/", index + 2);
+            if (end === -1)
+                break;
+            index = end + 1;
+            continue;
+        }
+        if (char === "\\") {
+            index++;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (brackets === 0 && char === subject[0] && selector.startsWith(subject, index)) {
+            const next = selector[index + subject.length];
+            const continued = next !== undefined && (/[\w-]/.test(next) || next === "\\" || next.charCodeAt(0) >= 0x80);
+            if (attributeSubject || !continued) {
+                normalized += `${selector.slice(cursor, index)}&`;
+                cursor = index + subject.length;
+                index = cursor - 1;
+                continue;
+            }
+        }
+        if (char === "[")
+            brackets++;
+        else if (char === "]" && brackets > 0)
+            brackets--;
+    }
+    return normalized + selector.slice(cursor);
+}
+/** generator.ts:462. */
+const isStringifiedUtilTuple = (value) => Array.isArray(value) && [0, 1, 2, 3, 4, 5, 6].every((index) => Object.hasOwn(value, index));
+const metaValue = (meta, key) => (meta && typeof meta === "object" ? meta[key] : undefined);
+/**
+ * generator.ts:441-460: same bodies, selectors (relative to each token), parents and layer,
+ * sort, noScope and noMerge.
+ */
+function sameStringifiedUtils(left, leftRaw, right, rightRaw, escape) {
+    const leftItems = left.filter(isStringifiedUtilTuple);
+    const rightItems = right.filter(isStringifiedUtilTuple);
+    if (leftItems.length !== rightItems.length)
+        return false;
+    for (let index = 0; index < leftItems.length; index++) {
+        const item = leftItems[index];
+        const other = rightItems[index];
+        if (item[2] !== other[2] ||
+            normalizedSelector(item[1], leftRaw, escape) !== normalizedSelector(other[1], rightRaw, escape) ||
+            item[3] !== other[3] ||
+            metaValue(item[4], "layer") !== metaValue(other[4], "layer") ||
+            metaValue(item[4], "sort") !== metaValue(other[4], "sort") ||
+            !!metaValue(item[4], "noScope") !== !!metaValue(other[4], "noScope") ||
+            !!(item[6] ?? metaValue(item[4], "noMerge")) !== !!(other[6] ?? metaValue(other[4], "noMerge")))
+            return false;
+    }
+    return true;
+}
+/** A fresh copy of each tuple, as the oracle's `copyValidatedStringifiedUtils` returns. */
+const copyTuples = (tuples) => tuples.map((tuple) => [...tuple]);
+/**
+ * core/config.ts:26-36: the first entry of each name wins.
+ */
+function uniqueNamed(entries) {
+    const names = new Set();
+    const unique = [];
+    for (const entry of entries) {
+        if (names.has(entry.name))
+            continue;
+        names.add(entry.name);
+        unique.push(entry);
+    }
+    return unique;
+}
+/**
+ * v02.9 §8.1: the process-wide counters, the same object the teacss-ts hook updates.
+ */
+export function engineStats() {
+    const scope = globalThis;
+    return (scope[ENGINE_STATS] ??= { rust: 0, ts: 0, fallbacks: Object.create(null) });
+}
+const reported = new Set();
+/**
+ * v02.9 §9: each reason and path prints once per process; the counter grows on every call. A
+ * host `report(reason, path, level)` (the hook's consola) replaces the stderr line.
+ */
+export function reportFallback(reason, path, host = {}, level = "info") {
+    const stats = engineStats();
+    stats.fallbacks[reason] = (stats.fallbacks[reason] ?? 0) + 1;
+    const key = `${reason}\0${path}`;
+    if (reported.has(key))
+        return;
+    reported.add(key);
+    if (typeof host.report === "function")
+        host.report(reason, path, level);
+    else
+        process.stderr.write(`[teacss] engine: falling back to the TypeScript engine (${reason} at ${path})\n`);
+}
+/** array-internal.ts:7-13: ownership is rechecked before each read. */
+function* ownArrayValues(array) {
+    if (!Array.isArray(array))
+        return;
+    for (let index = 0, length = array.length; index < length; index++) {
+        if (Object.hasOwn(array, index))
+            yield array[index];
+    }
+}
+/** generator.ts:363-372: `then` is read once and called on the original value. */
+function snapshotThenable(value) {
+    if (value === null || (typeof value !== "object" && typeof value !== "function"))
+        return undefined;
+    const then = Reflect.get(value, "then");
+    if (typeof then !== "function")
+        return undefined;
+    return { then: (onFulfilled, onRejected) => Reflect.apply(then, value, [onFulfilled, onRejected]) };
+}
+const FORWARDED_OPTIONS = ["id", "scope", "preflights", "safelist", "minify", "extendedInfo", "tokenConcurrency"];
+/**
+ * Generate options whose own `isInputCurrent` was read once; the other own options are still
+ * read on every access, as the oracle reads them on every retry (generator.ts:2366-2372).
+ */
+function captureInputCheck(options) {
+    if (options === null || typeof options !== "object")
+        return options;
+    const captured = {};
+    if (Object.hasOwn(options, "isInputCurrent"))
+        captured.isInputCurrent = options.isInputCurrent;
+    for (const key of FORWARDED_OPTIONS) {
+        if (Object.hasOwn(options, key))
+            Object.defineProperty(captured, key, { enumerable: true, get: () => options[key] });
+    }
+    return captured;
+}
+function disposeEngine(engine) {
+    try {
+        engine.dispose();
+    }
+    catch { }
+}
+/** The `extract` each host `extractorSplit` had when the facade first saw it. */
+const originalExtract = new WeakMap();
+function replacedExtract(split) {
+    if (!originalExtract.has(split))
+        originalExtract.set(split, split.extract);
+    return originalExtract.get(split) !== split.extract;
+}
+export class FacadeGenerator {
+    /** An uncommitted candidate's Engine is disposed once the candidate is collected. */
+    static #registry = new FinalizationRegistry((held) => {
+        if (held.kind === "rust" && !held.committed)
+            disposeEngine(held.engine);
+    });
+    #backend;
+    #held = null;
+    #host;
+    #tsFallback;
+    /** The compile-class transformer: created once and handed to every candidate (v02.9 §5.2). */
+    #transformer;
+    #cache = new BoundedTokenCache();
+    #blocked = new BoundedSet();
+    #parentOrders = new Map();
+    #activatedRules = new Set();
+    // Declared for the method cards (F7.15-F7.19).
+    #warnedUnmatched = new BoundedSet();
+    #allTokens = null;
+    #configVersion = 0;
+    /** Weak, so a prepared config nobody commits does not keep its candidate (and Engine) alive. */
+    #prepared = new WeakSet();
+    /** The facade's own emitter; a TS backend's `events` are not forwarded. */
+    events = createNanoEvents();
+    /**
+     * An `engine` gives a Rust backend and `ts` a TypeScript one.
+     */
+    constructor({ engine, request = {}, presets = [], transformers = [], ts, userConfig = {}, defaults = {}, host = {}, transformer = null, }) {
+        this.#host = host;
+        if (host.core?.extractorSplit)
+            replacedExtract(host.core.extractorSplit);
+        this.userConfig = userConfig;
+        this.defaults = defaults;
+        this.#transformer = transformer;
+        this.#tsFallback = createTsFallback(host, { userConfig, defaults });
+        if (ts) {
+            this.#backend = { kind: "ts", generator: ts };
+            return;
+        }
+        if (!engine)
+            throw new TypeError("[@teacss/engine] FacadeGenerator needs engine or ts");
+        this.#transformer = transformer ?? createCompileClassTransformer();
+        const view = engine.configView();
+        const own = view.standard?.compileClass === true ? [this.#transformer] : [];
+        const list = uniqueNamed([...own, ...transformers]);
+        const config = createConfigView({ view, request, presets, userConfig, transformers: list, host, fallback: this.#tsFallback, engine: own.length ? engine : undefined });
+        this.#backend = { kind: "rust", engine, request, presets, config, transformer: this.#transformer };
+    }
+    get version() {
+        return this.#host.core?.version ?? ENGINE_PACKAGE_VERSION;
+    }
+    get config() {
+        return this.#backend.kind === "rust" ? this.#backend.config : this.#backend.generator.config;
+    }
+    get cache() {
+        return this.#backend.kind === "rust" ? this.#cache : this.#backend.generator.cache;
+    }
+    get blocked() {
+        return this.#backend.kind === "rust" ? this.#blocked : this.#backend.generator.blocked;
+    }
+    get parentOrders() {
+        return this.#backend.kind === "rust" ? this.#parentOrders : this.#backend.generator.parentOrders;
+    }
+    get activatedRules() {
+        return this.#backend.kind === "rust" ? this.#activatedRules : this.#backend.generator.activatedRules;
+    }
+    // The runtime gives a detached reload candidate its own copies (transformer-context.ts:421-424),
+    // as it may on the oracle's public fields; a Rust backend keeps its bounded containers.
+    set cache(value) {
+        if (this.#backend.kind === "ts") {
+            this.#backend.generator.cache = value;
+            return;
+        }
+        if (value instanceof BoundedTokenCache) {
+            this.#cache = value;
+            return;
+        }
+        const cache = new BoundedTokenCache();
+        for (const [token, utils] of value)
+            cache.set(token, utils);
+        this.#cache = cache;
+    }
+    set blocked(value) {
+        if (this.#backend.kind === "ts")
+            this.#backend.generator.blocked = value;
+        else
+            this.#blocked = value instanceof BoundedSet ? value : new BoundedSet(undefined, value);
+    }
+    set parentOrders(value) {
+        if (this.#backend.kind === "ts")
+            this.#backend.generator.parentOrders = value;
+        else
+            this.#parentOrders = value;
+    }
+    set activatedRules(value) {
+        if (this.#backend.kind === "ts")
+            this.#backend.generator.activatedRules = value;
+        else
+            this.#activatedRules = value;
+    }
+    get [ENGINE_INSTANCE]() {
+        return this.#backend.kind === "rust" ? this.#backend.engine : null;
+    }
+    /**
+     * The two overloads of generator.ts:2037-2040. With an `id` the Engine records the module's
+     * tokens; a counted set adds each token's occurrences.
+     */
+    async applyExtractors(code, id, extracted = new Set()) {
+        await Promise.resolve();
+        const backend = this.#backend;
+        if (backend.kind === "ts")
+            return backend.generator.applyExtractors(code, id, extracted);
+        const split = this.#host.core?.extractorSplit;
+        if (split && replacedExtract(split)) {
+            // The host's default extractor was swapped at runtime (runtime context.ts `usesDefaultExtractor`
+            // checks the same): run it as generator.ts:2037 does instead of the native splitter.
+            const result = await split.extract({ code, id, extracted, envMode: this.config.envMode });
+            for (const token of result ?? []) {
+                if (isCountableSet(extracted))
+                    extracted.setCount(token, extracted.getCount(token) + 1);
+                else
+                    extracted.add(token);
+            }
+            return extracted;
+        }
+        const engine = backend.engine;
+        if (isCountableSet(extracted)) {
+            const counted = id === undefined ? engine.extractCounted(code) : engine.extractCounted(code, id);
+            if (id !== undefined)
+                this.#updateModule(id, code);
+            for (const { token, count } of counted)
+                extracted.setCount(token, extracted.getCount(token) + count);
+            return extracted;
+        }
+        const tokens = id === undefined ? engine.extract(code) : this.#updateModule(id, code);
+        for (const token of tokens)
+            extracted.add(token);
+        return extracted;
+    }
+    /**
+     * The overloads of generator.ts:2316-2318. String input is extracted here, as Rust's
+     * `{ kind: "code" }` would, so its tokens reach the cache and the unmatched check (the oracle
+     * runs `applyExtractors` on it, generator.ts:2378).
+     */
+    async generate(input, options = {}) {
+        const backend = this.#backend;
+        if (backend.kind === "ts") {
+            // A rule may commit a new configuration through this facade while the TS backend runs; the
+            // oracle then retries on the new configuration (generator.ts:2356), reading the input
+            // check once (generator.ts:2324).
+            const delegated = captureInputCheck(options);
+            const result = await backend.generator.generate(input, delegated);
+            return this.#backend === backend ? result : this.generate(input, delegated);
+        }
+        const own = (key) => (Object.hasOwn(options, key) ? options[key] : undefined);
+        const isInputCurrent = own("isInputCurrent");
+        if (isInputCurrent !== undefined && typeof isInputCurrent !== "function")
+            throw new TypeError("[@teacss/core] isInputCurrent must be a function.");
+        const checkInput = () => {
+            if (!isInputCurrent)
+                return;
+            const current = isInputCurrent();
+            if (typeof current !== "boolean") {
+                void Promise.resolve(current).catch(() => { });
+                throw new TypeError("[@teacss/core] isInputCurrent must return a boolean synchronously.");
+            }
+            if (!current)
+                throw new Error("[@teacss/core] Generation input is no longer current.");
+        };
+        await Promise.resolve();
+        checkInput();
+        const tokenConcurrency = own("tokenConcurrency");
+        if (tokenConcurrency !== undefined && (!Number.isSafeInteger(tokenConcurrency) || tokenConcurrency < 1))
+            throw new RangeError("tokenConcurrency must be a positive integer");
+        const preflights = own("preflights") ?? true;
+        const safelist = own("safelist") ?? true;
+        const minify = own("minify") ?? false;
+        const extendedInfo = own("extendedInfo") ?? false;
+        const { rustInput, countOf, collection, tokens } = this.#normalizeInput(input, own("id"), extendedInfo);
+        // Payloads are always requested: the cache stores them even when the caller did not ask.
+        const rust = backend.engine.generate(rustInput, { id: own("id"), preflights, safelist, minify, extendedInfo: true, scope: own("scope") });
+        const config = backend.config;
+        const matched = buildMatched({ rust: extendedInfo ? rust : { ...rust, matchedInfo: null }, extendedInfo, countOf });
+        const candidates = this.#candidates(tokens, safelist ? config.safelist : []);
+        this.#recordGeneration(rust, candidates, collection);
+        const unmatchedTokens = this.#collectUnmatched(rust, candidates, config);
+        let resolved;
+        const resolveUnmatched = () => (resolved ??= unmatchedTokens.length ? backend.engine.diagnoseUnmatched(unmatchedTokens) : []);
+        if (unmatchedTokens.length && config.unmatched === "error") {
+            const diagnosed = resolveUnmatched();
+            if (diagnosed.length)
+                throw new Error(formatUnmatchedError(diagnosed));
+        }
+        const result = createFacadeResult({ rust, matched, minify, outputToCssLayers: config.outputToCssLayers, configuredLayers: config.layers, resolveUnmatched });
+        if (unmatchedTokens.length && config.unmatched === "warn" && config.warn) {
+            for (const entry of resolveUnmatched()) {
+                if (this.#warnedUnmatched.has(entry.token))
+                    continue;
+                console.warn("[Teacss]", `unmatched token ${describeUnmatched(entry)}`);
+                this.#warnedUnmatched.add(entry.token);
+            }
+        }
+        checkInput();
+        return result;
+    }
+    #normalizeInput(input, id, extendedInfo) {
+        const engine = this.#backend.engine;
+        if (typeof input === "string") {
+            const counted = engine.extractCounted(input, id);
+            const tokens = new CountableSet();
+            for (const { token, count } of counted)
+                tokens.setCount(token, count);
+            return { rustInput: { kind: "tokens", tokens: [...tokens] }, countOf: extendedInfo ? (token) => tokens.getCount(token) : undefined, collection: false, tokens };
+        }
+        const counted = input instanceof CountableSet || this.#host.core?.isCountableSet?.(input);
+        if (counted) {
+            const source = input;
+            const copy = new CountableSet();
+            for (const token of source)
+                copy.setCount(token, source.getCount(token));
+            const expanded = expandInputGroups(copyCountableSet(copy));
+            return { rustInput: { kind: "tokens", tokens: [...expanded] }, countOf: (token) => expanded.getCount(token), collection: true, tokens: expanded };
+        }
+        if (Array.isArray(input) || input instanceof Set) {
+            const tokens = expandInputGroups(new Set(input));
+            return { rustInput: this.#isAllTokens(tokens) ? { kind: "all" } : { kind: "tokens", tokens: [...tokens] }, countOf: () => -1, collection: true, tokens };
+        }
+        throw new TypeError("[@teacss/engine] generate input must be a string, array, Set or CountableSet");
+    }
+    /** v02.9 §7.3: a set equal to every module token is sent as `{ kind: "all" }`. */
+    #isAllTokens(tokens) {
+        const engine = this.#backend.engine;
+        this.#allTokens ??= new Set(engine.allTokens());
+        const all = this.#allTokens;
+        return tokens.size === all.size && [...tokens].every((token) => all.has(token));
+    }
+    /**
+     * The tokens generation visits, in order: the input, then the safelist members it lacks
+     * (generator.ts:2390-2410, which adds them without counting).
+     */
+    #candidates(tokens, configuredSafelist) {
+        const candidates = [...tokens];
+        const seen = new Set(candidates);
+        for (const entry of Array.isArray(configuredSafelist) ? configuredSafelist : []) {
+            if (typeof entry !== "string")
+                continue;
+            const trimmed = entry.trim();
+            if (!trimmed)
+                continue;
+            for (const member of trimmed.includes("{") ? expandInputGroups(new Set([trimmed])) : [trimmed]) {
+                if (seen.has(member))
+                    continue;
+                seen.add(member);
+                candidates.push(member);
+            }
+        }
+        return candidates;
+    }
+    /**
+     * v02.9 §3.7: every visited token is cached in order (a miss as `null`, a blocked one also in
+     * `blocked`); a collection's matches then become the retained entries (generator.ts:2626-2630).
+     * `parentOrders` is not written: the Rust utils carry no parent order, and the oracle's
+     * Standard rules record none.
+     */
+    #recordGeneration(rust, candidates, collection) {
+        const engine = this.#backend.engine;
+        const payloads = new Map((rust.matchedInfo ?? []).map((info) => [info.token, info.data.map(toTuple)]));
+        for (const token of candidates) {
+            const payload = payloads.get(token);
+            if (payload) {
+                if (!collection)
+                    this.#cache.set(token, payload);
+                continue;
+            }
+            if (engine.isBlocked(token))
+                this.#blocked.add(token);
+            this.#cache.set(token, null);
+        }
+        if (collection)
+            this.#cache.replaceRetained(rust.matched.map((token) => [token, payloads.get(token) ?? []]));
+    }
+    /** Token-shaped misses that no blocklist explains, in visiting order. */
+    #collectUnmatched(rust, candidates, config) {
+        if (config.unmatched !== "warn" && config.unmatched !== "error")
+            return [];
+        const engine = this.#backend.engine;
+        const matched = new Set(rust.matched);
+        const isTokenShaped = this.#host.core?.isTokenShaped ?? fallbackIsTokenShaped;
+        return candidates.filter((token) => !matched.has(token) && isTokenShaped(token) && !this.#blocked.has(token) && !engine.isBlocked(token));
+    }
+    /**
+     * generator.ts:2113-2286. A tuple array, or `undefined` for a miss or a blocked token; a miss
+     * already cached reads back as `null`. With an `alias` nothing is cached.
+     */
+    async parseToken(raw, alias) {
+        await Promise.resolve();
+        const backend = this.#backend;
+        if (backend.kind === "ts")
+            return backend.generator.parseToken(raw, alias);
+        if (this.#blocked.has(raw))
+            return undefined;
+        const shared = !alias;
+        if (shared && this.#cache.has(raw)) {
+            const cached = this.#cache.get(raw);
+            if (!cached)
+                return cached;
+            return cached.length === 0 ? undefined : copyTuples(cached);
+        }
+        const utils = backend.engine.parseToken(raw, alias);
+        if (utils === null) {
+            if (backend.engine.isBlocked(raw)) {
+                if (shared) {
+                    this.#blocked.add(raw);
+                    this.#cache.set(raw, null);
+                }
+                return undefined;
+            }
+            if (shared)
+                this.#cache.set(raw, null);
+            return undefined;
+        }
+        const tuples = utils.map(toTuple);
+        if (shared)
+            this.#cache.set(raw, tuples);
+        // An empty static match is cached but reads as no match (generator.ts:2116).
+        return tuples.length === 0 ? undefined : copyTuples(tuples);
+    }
+    /** generator.ts:3611. */
+    isBlocked(raw) {
+        return this.#backend.kind === "ts" ? this.#backend.generator.isBlocked(raw) : this.#backend.engine.isBlocked(raw);
+    }
+    /** generator.ts:3623; the blocklist holds strings only (anything else falls back). */
+    getBlocked(raw) {
+        if (this.#backend.kind === "ts")
+            return this.#backend.generator.getBlocked(raw);
+        for (const value of this.#backend.config.blocklist)
+            if (value === raw)
+                return [value, undefined];
+        return undefined;
+    }
+    /** generator.ts:2304-2314: cached tokens that emit the same output as `raw`. */
+    getCachedEquivalentTokens(raw) {
+        if (this.#backend.kind === "ts")
+            return this.#backend.generator.getCachedEquivalentTokens(raw);
+        const target = this.#cache.get(raw);
+        if (!target?.length)
+            return [raw];
+        const escape = this.#host.core?.toEscapedSelector ?? toEscapedSelector;
+        const names = new Set([raw]);
+        for (const [name, utils] of this.#cache) {
+            if (utils && !name.endsWith(" -") && sameStringifiedUtils(utils, name, target, raw, escape))
+                names.add(name);
+        }
+        return [...names];
+    }
+    /** The TypeScript generator behind the tooling members, created on first call; a TS backend returns itself. */
+    async [ENGINE_MATERIALIZE]() {
+        if (this.#backend.kind === "ts")
+            return this.#backend.generator;
+        return this.#tsFallback.generator("materialize");
+    }
+    #tsSync(member) {
+        if (this.#backend.kind === "ts")
+            return this.#backend.generator;
+        const ts = this.#tsFallback.peek();
+        if (!ts)
+            throw tsNotReadyError(member);
+        return ts;
+    }
+    async #tsAsync(member) {
+        if (this.#backend.kind === "ts")
+            return this.#backend.generator;
+        return this.#tsFallback.generator(member);
+    }
+    /** generator.ts:2105. */
+    makeContext(raw, applied) {
+        return this.#tsSync("makeContext").makeContext(raw, applied);
+    }
+    /** generator.ts:2809. */
+    constructCustomCSS(context, body, overrideSelector) {
+        return this.#tsSync("constructCustomCSS").constructCustomCSS(context, body, overrideSelector);
+    }
+    /** generator.ts:3160. */
+    stringifyUtil(parsed, context) {
+        return this.#tsSync("stringifyUtil").stringifyUtil(parsed, context);
+    }
+    /** generator.ts:2635. */
+    async matchVariants(raw, current) {
+        return (await this.#tsAsync("matchVariants")).matchVariants(raw, current);
+    }
+    /** generator.ts:2866. */
+    async parseUtil(input, context, internal = false, shortcutPrefix) {
+        return (await this.#tsAsync("parseUtil")).parseUtil(input, context, internal, shortcutPrefix);
+    }
+    /** generator.ts:3208. */
+    async expandShortcut(input, context, depth = 5) {
+        return (await this.#tsAsync("expandShortcut")).expandShortcut(input, context, depth);
+    }
+    /** generator.ts:3409. */
+    async stringifyShortcuts(parent, context, expanded, meta, matchedPrefixes) {
+        return (await this.#tsAsync("stringifyShortcuts")).stringifyShortcuts(parent, context, expanded, meta, matchedPrefixes);
+    }
+    /** generator.ts:1976-1980: a falsy config keeps the current one. */
+    async setConfig(userConfig, defaults) {
+        if (userConfig)
+            this.commitConfig(await this.prepareConfig(userConfig, defaults));
+    }
+    /**
+     * generator.ts:1983-2008: a candidate generator for the configuration, without touching this
+     * one. A configuration Rust cannot serve gets a TypeScript candidate.
+     */
+    async prepareConfig(userConfig, defaults) {
+        await Promise.resolve();
+        const version = ++this.#configVersion;
+        const nextDefaults = defaults ?? this.defaults;
+        const translated = await translateConfig(userConfig, nextDefaults);
+        let candidate;
+        if (translated.ok) {
+            const engine = new Engine();
+            engine.loadProject(translated.request);
+            candidate = new FacadeGenerator({ engine, request: translated.request, presets: translated.presets, transformers: translated.transformers, userConfig, defaults: nextDefaults, host: this.#host, transformer: this.#transformer });
+            engineStats().rust++;
+        }
+        else {
+            this.#reportFallback(translated);
+            const ts = await this.#tsFallback.create(userConfig, nextDefaults);
+            candidate = new FacadeGenerator({ ts, userConfig, defaults: nextDefaults, host: this.#host });
+        }
+        const prepared = Object.freeze({ config: candidate.config, defaults: nextDefaults, generator: candidate, userConfig, version });
+        this.#prepared.add(prepared);
+        const held = candidate.#backend.kind === "rust" ? { kind: "rust", engine: candidate.#backend.engine, committed: false } : { kind: "ts", committed: false };
+        candidate.#held = held;
+        FacadeGenerator.#registry.register(candidate, held);
+        return prepared;
+    }
+    /**
+     * generator.ts:2010-2035: switch to the prepared backend if no newer request superseded it. A
+     * superseded Rust candidate is disposed; so is the previous Engine once it is replaced.
+     */
+    commitConfig(prepared) {
+        if (!this.#prepared.delete(prepared))
+            return false;
+        const candidate = prepared.generator;
+        if (prepared.version !== this.#configVersion) {
+            candidate.#disposeIfRust();
+            return false;
+        }
+        if (candidate.config !== prepared.config)
+            return false;
+        const previous = this.#backend;
+        this.defaults = prepared.defaults;
+        this.userConfig = prepared.userConfig;
+        this.#clearRuntimeCaches();
+        this.#backend = candidate.#backend;
+        if (candidate.#held)
+            candidate.#held.committed = true;
+        this.#allTokens = null;
+        this.#tsFallback.invalidate(prepared.userConfig, prepared.defaults);
+        if (previous.kind === "rust" && (this.#backend.kind !== "rust" || previous.engine !== this.#backend.engine))
+            disposeEngine(previous.engine);
+        this.#dispatchConfig(this.config);
+        return true;
+    }
+    /** An explicit `engine: "rust"` asked for Rust, so its fallback is a warning. */
+    #reportFallback(failure) {
+        const explicit = this.defaults?.engine === "rust" || this.userConfig?.engine === "rust";
+        reportFallback(failure.reason, failure.path, this.#host, explicit ? "warn" : "info");
+        engineStats().ts++;
+    }
+    #disposeIfRust() {
+        if (this.#backend.kind === "rust")
+            disposeEngine(this.#backend.engine);
+        if (this.#held)
+            this.#held.committed = true;
+    }
+    /** generator.ts:1671-1680. */
+    #clearRuntimeCaches() {
+        this.#cache.clear();
+        this.#blocked.clear();
+        this.#parentOrders.clear();
+        this.#activatedRules.clear();
+        this.#warnedUnmatched.clear();
+    }
+    /**
+     * generator.ts:1649-1671: only own listener slots are called, a result's `then` is read once,
+     * and a throwing store or observer is reported, never rethrown.
+     */
+    #dispatchConfig(config) {
+        const errors = [];
+        const append = (error) => Object.defineProperty(errors, errors.length, { configurable: true, enumerable: true, value: error, writable: true });
+        try {
+            const store = this.events.events;
+            const listeners = Array.from(ownArrayValues(Object.hasOwn(store, "config") ? store.config : undefined));
+            for (const listener of listeners) {
+                try {
+                    const pending = snapshotThenable(listener(config));
+                    if (pending)
+                        void Promise.resolve(pending).catch((error) => this.#reportObserverErrors([error]));
+                }
+                catch (error) {
+                    append(error);
+                }
+            }
+        }
+        catch (error) {
+            append(error);
+        }
+        if (errors.length)
+            this.#reportObserverErrors(errors);
+    }
+    /** generator.ts:1638-1643. */
+    #reportObserverErrors(errors) {
+        try {
+            console.error("[@teacss/core] Configuration observer failed:", new AggregateError(errors, "Configuration observers failed"));
+        }
+        catch { }
+    }
+    /** A changed module invalidates the `allTokens` snapshot. */
+    #updateModule(id, code) {
+        if (this.#backend.kind !== "rust")
+            return [];
+        const result = this.#backend.engine.updateModule(id, code);
+        if (result.changed)
+            this.#allTokens = null;
+        return result.tokens;
+    }
+}
+export async function createGenerator(config = {}, defaults = {}, host = {}) {
+    const translated = await translateConfig(config, defaults);
+    if (!translated.ok)
+        return { ok: false, reason: translated.reason, path: translated.path };
+    const engine = new Engine();
+    engine.loadProject(translated.request);
+    return { ok: true, generator: new FacadeGenerator({ engine, request: translated.request, presets: translated.presets, transformers: translated.transformers, userConfig: config, defaults, host }) };
+}
+//# sourceMappingURL=generator.js.map