@teacss/engine 0.0.0-stage → 0.8.5-alpha.2

package/src/facade/select.mjs

@@ -0,0 +1,600 @@
+// @ts-check
+// Selects the configurations the Rust engine can serve: the first item it cannot translate comes
+// back as `{ ok: false, reason, path }` (v02.9 §4.1); later cards (F7.07-F7.12) append the rest.
+
+import { TeacssEngineError } from "./errors.mjs";
+import { CONFIG_ENTRY_PROVENANCE, CONFIG_SOURCE_DECLARATIONS, ENGINE_COMPAT, ENGINE_PACKAGE_VERSION, PRESET_OPTIONS } from "./constants.mjs";
+
+/** @typedef {{ ok: false, reason: string, path: string }} Failure */
+/** @template T @typedef {{ ok: true, value: T }} Success */
+
+/** @param {string} reason @param {string} path @returns {Failure} */
+export function fail(reason, path) {
+  return { ok: false, reason, path };
+}
+
+/** @template T @param {T} value @returns {Success<T>} */
+export function ok(value) {
+  return { ok: true, value };
+}
+
+/**
+ * Port of core/config.ts:48-59: `defaults` underneath, then the user config's own enumerable keys
+ * whose value is not `undefined`. Only string keys are copied (v02.9 §4.4); values are defined
+ * rather than assigned so a `__proto__` key stays a plain property.
+ * @param {object} defaults @param {object} userConfig @returns {Record<string, unknown>}
+ */
+export function mergeDefinedConfig(defaults, userConfig) {
+  /** @type {Record<string, unknown>} */
+  const merged = { ...defaults };
+  for (const key of Object.keys(userConfig)) {
+    const value = /** @type {Record<string, unknown>} */ (userConfig)[key];
+    if (value === undefined) continue;
+    Object.defineProperty(merged, key, { value, configurable: true, enumerable: true, writable: true });
+  }
+  return merged;
+}
+
+export const KNOWN_KEYS = new Set([
+  "presets", "shortcuts", "safelist", "blocklist", "theme", "layers", "content", "envMode", "unmatched", "shortcutsLayer", "virtualModulePrefix", "outputToCssLayers",
+  "mergeSelectors", "warn", "details", "separators", "transformers", "extractors", "extractorDefault", "rules", "variants", "preflights", "preprocess", "postprocess",
+  "extendTheme", "configResolved", "autocomplete", "sortLayers", "cli", "engine",
+]);
+
+/** Keys whose presence with a non-empty value means fallback; `transformers` is checked by name (F7.09). */
+export const DYNAMIC_KEYS = Object.freeze([
+  "rules", "variants", "extractors", "extractorDefault", "preflights", "preprocess", "postprocess", "extendTheme", "configResolved", "autocomplete", "cli",
+]);
+
+/** A function, a non-empty array or object, or any other defined non-null value. @param {unknown} value */
+export function isNonEmpty(value) {
+  if (value === undefined || value === null) return false;
+  if (typeof value === "function") return true;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "object") return Object.keys(value).length > 0;
+  return true;
+}
+
+/** @param {unknown} separators */
+function isDefaultSeparators(separators) {
+  return Array.isArray(separators) && separators.length === 2 && separators[0] === ":" && separators[1] === "-";
+}
+
+/**
+ * v02.9 §4.2 step 2: unknown keys, then the dynamic keys in order, then the static options only
+ * the TypeScript engine honours. `engine` is a hook option and its value is not checked here.
+ * @param {Record<string, unknown>} merged @returns {Success<null> | Failure}
+ */
+export function checkTopLevelKeys(merged) {
+  for (const key of Object.keys(merged)) {
+    if (!KNOWN_KEYS.has(key)) return fail("unknown-key", key);
+  }
+  for (const key of DYNAMIC_KEYS) {
+    if (isNonEmpty(merged[key])) return fail(key, key);
+  }
+  if (merged.separators !== undefined && !isDefaultSeparators(merged.separators)) return fail("separators", "separators");
+  if (merged.mergeSelectors === false) return fail("mergeSelectors", "mergeSelectors");
+  if (merged.details !== undefined) return fail("details", "details");
+  if (merged.sortLayers !== undefined) return fail("sortLayers", "sortLayers");
+  return ok(null);
+}
+
+/** @param {unknown} value */
+const isThenable = (value) => value !== null && (typeof value === "object" || typeof value === "function") && typeof (/** @type {any} */ (value)).then === "function";
+
+/**
+ * v02.9 §4.2 step 3: nested presets flattened depth first, deduplicated by name keeping the first
+ * (core/config.ts:26-36 — a missing name is a name too), then ordered pre, normal, post
+ * (config.ts:216-220; any other `enforce` value drops the preset, as there).
+ * @param {unknown} presetsValue @returns {Success<object[]> | Failure}
+ */
+export function flattenPresets(presetsValue) {
+  const list = presetsValue === undefined ? [] : Array.isArray(presetsValue) ? presetsValue : [presetsValue];
+  /** @type {object[]} */
+  const flat = [];
+  /** @param {unknown} entry @param {string} path @param {Set<unknown>} ancestors @returns {Failure | undefined} */
+  const visit = (entry, path, ancestors) => {
+    if (Array.isArray(entry)) {
+      for (let index = 0; index < entry.length; index++) {
+        const failure = visit(entry[index], `${path}[${index}]`, ancestors);
+        if (failure) return failure;
+      }
+      return undefined;
+    }
+    if (typeof entry === "function" || isThenable(entry) || entry === null || typeof entry !== "object") return fail("preset-not-instantiated", path);
+    if (ancestors.has(entry)) return fail("preset-cycle", path);
+    flat.push(entry);
+    const children = Object.hasOwn(entry, "presets") ? /** @type {any} */ (entry).presets : undefined;
+    if (children === undefined) return undefined;
+    const nested = Array.isArray(children) ? children : [children];
+    const nextAncestors = new Set([...ancestors, entry]);
+    for (let index = 0; index < nested.length; index++) {
+      const failure = visit(nested[index], `${path}.presets[${index}]`, nextAncestors);
+      if (failure) return failure;
+    }
+    return undefined;
+  };
+  for (let index = 0; index < list.length; index++) {
+    const failure = visit(list[index], `presets[${index}]`, new Set());
+    if (failure) return failure;
+  }
+  const names = new Set();
+  const unique = flat.filter((preset) => {
+    const name = /** @type {any} */ (preset).name;
+    if (names.has(name)) return false;
+    names.add(name);
+    return true;
+  });
+  /** @param {object} preset */
+  const enforce = (preset) => /** @type {any} */ (preset).enforce;
+  return ok([...unique.filter((preset) => enforce(preset) === "pre"), ...unique.filter((preset) => enforce(preset) == null), ...unique.filter((preset) => enforce(preset) === "post")]);
+}
+
+/** The oracle's `PresetOptions` base (types.ts:53) has no named fields, so these five are Standard's whole option set. */
+export const STANDARD_OPTION_KEYS = new Set(["modeSelectors", "containers", "preflight", "variablePrefix", "compileClass"]);
+export const COMPILE_CLASS_KEYS = ["classPrefix", "alwaysHash", "keepUnknown", "layer"];
+export const ICONS_OPTION_KEYS = ["scale", "mode", "extraProperties", "warn", "layer", "unit"];
+export const BUNDLED_ICON_COLLECTIONS = new Set(["carbon", "crypto", "flagpack", "logo", "lucide"]);
+export const ROLE_PALETTES_PRESET = "@teacss/config/role-palettes";
+
+/** @param {Record<string, unknown>} obj @param {Iterable<string>} keys @returns {Record<string, unknown>} */
+export function pick(obj, keys) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const key of keys) if (obj[key] !== undefined) out[key] = obj[key];
+  return out;
+}
+
+/** @param {object} preset @param {symbol} marker */
+const markedOptions = (preset, marker) => /** @type {Record<string, any>} */ (Object.getOwnPropertyDescriptor(preset, marker)?.value ?? {});
+
+/**
+ * v02.9 §4.2 step 4, first four items: the marked built-in presets and the role-palettes marker.
+ * `ok(null)` means the preset yields no `PresetSpec`; `undefined` means it is not one of these
+ * (unmarked presets go to F7.08's static translation).
+ * @param {object} preset @param {string} path such as `presets[1]` @param {{ hasEntry: boolean }} ctx
+ * @returns {Success<object | null> | Failure | undefined}
+ */
+export function translateTaggedPreset(preset, path, ctx) {
+  if (Object.getOwnPropertyDescriptor(preset, PRESET_OPTIONS.standard) !== undefined) {
+    const options = markedOptions(preset, PRESET_OPTIONS.standard);
+    for (const key of Object.keys(options)) {
+      if (!STANDARD_OPTION_KEYS.has(key)) return fail("standard.unknown-option", `${path}.options.${key}`);
+    }
+    const compileClass = options.compileClass;
+    if (compileClass !== null && typeof compileClass === "object") {
+      if (Object.hasOwn(compileClass, "hashFn")) return fail("standard.compileClass.hashFn", `${path}.options.compileClass.hashFn`);
+      if (Object.hasOwn(compileClass, "trigger")) return fail("standard.compileClass.trigger", `${path}.options.compileClass.trigger`);
+    }
+    const spec = { kind: "standard", options: pick(options, STANDARD_OPTION_KEYS) };
+    if (compileClass !== null && typeof compileClass === "object") spec.options.compileClass = pick(compileClass, COMPILE_CLASS_KEYS);
+    return ok(spec);
+  }
+  if (Object.getOwnPropertyDescriptor(preset, PRESET_OPTIONS.icons) !== undefined) {
+    const options = markedOptions(preset, PRESET_OPTIONS.icons);
+    const collections = Object.keys(options.collections ?? {});
+    for (const key of collections) {
+      if (!BUNDLED_ICON_COLLECTIONS.has(key)) return fail("icons.collections", `${path}.options.collections.${key}`);
+    }
+    if (isNonEmpty(options.customizations)) return fail("icons.customizations", `${path}.options.customizations`);
+    if (options.processor !== undefined) return fail("icons.processor", `${path}.options.processor`);
+    const spec = { kind: "icons", options: pick(options, ICONS_OPTION_KEYS) };
+    if (options.collections !== undefined) spec.options.collections = collections;
+    return ok(spec);
+  }
+  if (Object.getOwnPropertyDescriptor(preset, PRESET_OPTIONS.official) !== undefined) return ok({ kind: "official" });
+  if (/** @type {any} */ (preset).name === ROLE_PALETTES_PRESET) return ctx.hasEntry ? ok(null) : fail("role-palettes-without-entry", path);
+  return undefined;
+}
+
+/** Keys of an unmarked preset whose non-empty value means fallback. */
+export const PRESET_DYNAMIC_KEYS = Object.freeze([
+  "rules", "variants", "extractors", "preflights", "preprocess", "postprocess", "extendTheme", "configResolved", "transformers", "autocomplete", "extractorDefault",
+]);
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Values `undefined` are left out. @param {Record<string, unknown>} entries */
+const defined = (entries) => Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined));
+
+/**
+ * v02.9 §4.5: the static shortcut forms as `[name, expansion]` pairs. A shortcut meta (`[n, e, meta]`)
+ * has no place in `StaticPreset.shortcuts`, so any meta key falls back.
+ * @param {unknown} value @param {string} path @param {string} reasonOnFail
+ * @returns {Success<Array<[string, string]> | undefined> | Failure}
+ */
+export function translateShortcuts(value, path, reasonOnFail) {
+  if (value === undefined) return ok(undefined);
+  /** @type {Array<[string, string]>} */
+  const pairs = [];
+  /** @param {Record<string, unknown>} object @param {string} objectPath @returns {Failure | undefined} */
+  const fromObject = (object, objectPath) => {
+    for (const [key, expansion] of Object.entries(object)) {
+      if (typeof expansion !== "string") return fail(reasonOnFail, `${objectPath}.${key}`);
+      pairs.push([key, expansion]);
+    }
+    return undefined;
+  };
+  if (isPlainObject(value)) {
+    const failure = fromObject(value, path);
+    if (failure) return failure;
+  } else if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      const item = value[index];
+      const itemPath = `${path}[${index}]`;
+      if (Array.isArray(item)) {
+        if (typeof item[0] !== "string" || typeof item[1] !== "string") return fail(reasonOnFail, itemPath);
+        if (item.length > 2 && item[2] !== undefined) {
+          const meta = item[2];
+          if (!isPlainObject(meta)) return fail(reasonOnFail, `${itemPath}[2]`);
+          const key = Object.keys(meta)[0];
+          if (key !== undefined) return fail(reasonOnFail, `${itemPath}[2].${key}`);
+        }
+        pairs.push([item[0], item[1]]);
+      } else if (isPlainObject(item)) {
+        const failure = fromObject(item, itemPath);
+        if (failure) return failure;
+      } else {
+        return fail(reasonOnFail, itemPath);
+      }
+    }
+  } else {
+    return fail(reasonOnFail, path);
+  }
+  return ok(pairs.length > 0 ? pairs : undefined);
+}
+
+/**
+ * v02.9 §4.5: a theme as dotted keys to string leaves (numbers stringified); empty objects vanish.
+ * @param {unknown} theme @param {string} path @param {string} reasonOnFail
+ * @returns {Success<Record<string, string> | undefined> | Failure}
+ */
+export function flattenTheme(theme, path, reasonOnFail) {
+  if (theme === undefined) return ok(undefined);
+  if (!isPlainObject(theme)) return fail(reasonOnFail, path);
+  /** @type {Record<string, string>} */
+  const flat = {};
+  /** @param {Record<string, unknown>} object @param {string} prefix @returns {Failure | undefined} */
+  const visit = (object, prefix) => {
+    for (const [key, value] of Object.entries(object)) {
+      const dotted = prefix ? `${prefix}.${key}` : key;
+      if (typeof value === "string") flat[dotted] = value;
+      else if (typeof value === "number") flat[dotted] = String(value);
+      else if (isPlainObject(value)) {
+        const failure = visit(value, dotted);
+        if (failure) return failure;
+      } else return fail(reasonOnFail, `${path}.${dotted}`);
+    }
+    return undefined;
+  };
+  const failure = visit(theme, "");
+  if (failure) return failure;
+  return ok(Object.keys(flat).length > 0 ? flat : undefined);
+}
+
+/** @param {unknown} list @param {string} path @param {string} reasonOnFail @returns {Success<string[] | undefined> | Failure} */
+export function translateStringList(list, path, reasonOnFail) {
+  if (list === undefined) return ok(undefined);
+  if (!Array.isArray(list)) return fail(reasonOnFail, path);
+  for (let index = 0; index < list.length; index++) {
+    if (typeof list[index] !== "string") return fail(reasonOnFail, `${path}[${index}]`);
+  }
+  return ok(list.length > 0 ? [...list] : undefined);
+}
+
+/** @param {unknown} layers @param {string} path @param {string} reasonOnFail @returns {Success<Record<string, number> | undefined> | Failure} */
+export function translateLayers(layers, path, reasonOnFail) {
+  if (layers === undefined) return ok(undefined);
+  if (!isPlainObject(layers)) return fail(reasonOnFail, path);
+  for (const [key, order] of Object.entries(layers)) {
+    if (typeof order !== "number") return fail(reasonOnFail, `${path}.${key}`);
+  }
+  return ok({ .../** @type {Record<string, number>} */ (layers) });
+}
+
+/**
+ * v02.9 §4.2 step 4, "other objects": an unmarked preset as a `StaticPreset`.
+ * @param {Record<string, any>} preset @param {string} path @returns {Success<{ kind: "static", preset: object }> | Failure}
+ */
+export function translateStaticPreset(preset, path) {
+  if (typeof preset.name !== "string") return fail("preset.name", `${path}.name`);
+  for (const key of PRESET_DYNAMIC_KEYS) {
+    if (isNonEmpty(preset[key])) return fail(`preset.${key}`, `${path}.${key}`);
+  }
+  const shortcuts = translateShortcuts(preset.shortcuts, `${path}.shortcuts`, "preset.shortcuts");
+  if (!shortcuts.ok) return shortcuts;
+  const safelist = translateStringList(preset.safelist, `${path}.safelist`, "preset.safelist");
+  if (!safelist.ok) return safelist;
+  const blocklist = translateStringList(preset.blocklist, `${path}.blocklist`, "preset.blocklist");
+  if (!blocklist.ok) return blocklist;
+  const theme = flattenTheme(preset.theme, `${path}.theme`, "preset.theme");
+  if (!theme.ok) return theme;
+  const layers = translateLayers(preset.layers, `${path}.layers`, "preset.layers");
+  if (!layers.ok) return layers;
+  if (preset.enforce !== undefined && preset.enforce !== "pre" && preset.enforce !== "post") return fail("preset.enforce", `${path}.enforce`);
+  if (preset.layer !== undefined && typeof preset.layer !== "string") return fail("preset.layer", `${path}.layer`);
+  return ok({
+    kind: "static",
+    preset: defined({ name: preset.name, enforce: preset.enforce, layer: preset.layer, layers: layers.value, shortcuts: shortcuts.value, safelist: safelist.value, blocklist: blocklist.value, theme: theme.value }),
+  });
+}
+
+/**
+ * v02.9 §4.2 step 5: the merged config's static fields as a `StaticConfig` (possibly empty).
+ * @param {Record<string, any>} merged @returns {Success<object> | Failure}
+ */
+export function translateInline(merged) {
+  const shortcuts = translateShortcuts(merged.shortcuts, "shortcuts", "shortcuts");
+  if (!shortcuts.ok) return shortcuts;
+  const safelist = translateStringList(merged.safelist, "safelist", "safelist");
+  if (!safelist.ok) return safelist;
+  const blocklist = translateStringList(merged.blocklist, "blocklist", "blocklist");
+  if (!blocklist.ok) return blocklist;
+  const theme = flattenTheme(merged.theme, "theme", "theme");
+  if (!theme.ok) return theme;
+  const layers = translateLayers(merged.layers, "layers", "layers");
+  if (!layers.ok) return layers;
+  let content;
+  if (merged.content !== undefined) {
+    if (!isPlainObject(merged.content)) return fail("content", "content");
+    if (Object.hasOwn(merged.content, "pipeline") && merged.content.pipeline !== undefined) return fail("content.pipeline", "content.pipeline");
+    if (isNonEmpty(merged.content.inline)) return fail("content.inline", "content.inline");
+    const filesystem = merged.content.filesystem;
+    if (filesystem !== undefined) {
+      if (!Array.isArray(filesystem) || filesystem.some((pattern) => typeof pattern !== "string")) return fail("content", "content.filesystem");
+      content = { filesystem: [...filesystem] };
+    }
+  }
+  return ok(defined({ shortcuts: shortcuts.value, safelist: safelist.value, blocklist: blocklist.value, theme: theme.value, layers: layers.value, content }));
+}
+
+export const ALLOWED_TRANSFORMER_NAMES = new Set(["@teacss/transformer-compile-class", "@teacss/directives"]);
+
+/**
+ * v02.2 §4: allow-listed transformers stay with the host (kept in the facade's `config.transformers`)
+ * and never reach Rust; any other name falls back. Repeated names are kept in order; the config view
+ * applies `uniqueNamed` later (F7.20). `@teacss/directives` options live in its closure and are
+ * checked per call (v02.9 §6.3), so none are read here.
+ * @param {unknown} list @returns {Success<object[]> | Failure}
+ */
+export function translateTransformers(list) {
+  if (list === undefined || list === null) return ok([]);
+  if (!Array.isArray(list)) return fail("transformers", "transformers");
+  const kept = [];
+  for (let index = 0; index < list.length; index++) {
+    const transformer = list[index];
+    if (!transformer || typeof transformer !== "object" || typeof transformer.name !== "string" || !ALLOWED_TRANSFORMER_NAMES.has(transformer.name)) {
+      return fail("transformers", `transformers[${index}]`);
+    }
+    kept.push(transformer);
+  }
+  return ok(kept);
+}
+
+/** @typedef {{ base: string, entryFile: string | undefined, entryCss: string | undefined, derivedKeys: string[] }} EntryProvenance */
+/** @typedef {{ root: string, entry: { path: string, css: string | null } | null, declarationFiles: string[], derivedKeys: string[] }} EntrySource */
+
+/** Test seam for the scanner; the default dynamically imports `@teacss/config/internal/source-scan`. */
+export const scanners = {
+  /** @type {(() => Promise<{ scanSourceFiles: (patterns: readonly string[], options: { cwd: string, ignore?: readonly string[], expandDirectories: boolean }) => Promise<string[]> }>) | null} */
+  load: null,
+};
+
+async function loadScanner() {
+  if (scanners.load) return scanners.load();
+  // @ts-ignore optional peer
+  return import("@teacss/config/internal/source-scan");
+}
+
+/**
+ * Entry source and declaration files (v02.9 §4.4). The symbols are read from `userConfig`, not
+ * `merged`: `mergeDefinedConfig` copies no symbols.
+ * @param {object} userConfig @param {Record<string, unknown>} merged @returns {Promise<Success<EntrySource> | Failure>}
+ */
+export async function resolveEntrySource(userConfig, merged) {
+  const provenance = /** @type {EntryProvenance | undefined} */ (/** @type {any} */ (userConfig)[CONFIG_ENTRY_PROVENANCE]);
+  const state = /** @type {any} */ (userConfig)[CONFIG_SOURCE_DECLARATIONS];
+  if (!provenance || typeof provenance.entryFile !== "string") return ok({ root: process.cwd(), entry: null, declarationFiles: [], derivedKeys: [] });
+
+  const root = provenance.base;
+  const entry = { path: provenance.entryFile, css: provenance.entryCss ?? null };
+  const derivedKeys = Array.isArray(provenance.derivedKeys) ? [...new Set(provenance.derivedKeys)] : [];
+  /** @type {string[]} */
+  let declarationFiles = [];
+  const content = /** @type {any} */ (merged.content);
+  if (state?.consumed?.status === "read") {
+    declarationFiles = state.consumed.members.map((/** @type {{ path: string }} */ member) => member.path);
+  } else if (content != null && typeof content === "object" && Array.isArray(content.filesystem)) {
+    const filesystem = /** @type {string[]} */ (content.filesystem);
+    const includes = filesystem.filter((glob) => !glob.startsWith("!"));
+    const excludes = filesystem.filter((glob) => glob.startsWith("!")).map((glob) => glob.slice(1));
+    let files;
+    try {
+      const { scanSourceFiles } = await loadScanner();
+      files = await scanSourceFiles(includes, { cwd: root, ignore: excludes, expandDirectories: false });
+    } catch {
+      return fail("declarations-unavailable", "content.filesystem");
+    }
+    declarationFiles = files.filter((file) => file.endsWith(".css") && file !== entry.path).sort();
+  }
+  return ok({ root, entry, declarationFiles, derivedKeys });
+}
+
+const ENV_MODES = new Set(["dev", "build"]);
+const UNMATCHED_MODES = new Set(["warn", "error", "off"]);
+
+/** @param {Record<string, any>} merged @returns {Success<object> | Failure} */
+function translateScalars(merged) {
+  const envMode = merged.envMode ?? "build";
+  if (!ENV_MODES.has(envMode)) return fail("envMode", "envMode");
+  const unmatched = merged.unmatched ?? "off";
+  if (!UNMATCHED_MODES.has(unmatched)) return fail("unmatched", "unmatched");
+  const layers = merged.outputToCssLayers;
+  let outputToCssLayers;
+  if (layers === undefined) outputToCssLayers = null;
+  else if (typeof layers === "boolean") outputToCssLayers = layers;
+  else if (isPlainObject(layers)) {
+    if (Object.hasOwn(layers, "cssLayerName") && layers.cssLayerName !== undefined) return fail("outputToCssLayers.cssLayerName", "outputToCssLayers.cssLayerName");
+    outputToCssLayers = { allLayers: Boolean(layers.allLayers) };
+  } else return fail("outputToCssLayers", "outputToCssLayers");
+  return ok({
+    envMode,
+    unmatched,
+    outputToCssLayers,
+    shortcutsLayer: typeof merged.shortcutsLayer === "string" ? merged.shortcutsLayer : null,
+    virtualModulePrefix: typeof merged.virtualModulePrefix === "string" ? merged.virtualModulePrefix : null,
+  });
+}
+
+/** @param {object} userConfig @param {object} defaults @returns {Promise<{ ok: true, request: Record<string, any>, presets: object[], transformers: object[] } | Failure>} */
+async function translate(userConfig, defaults) {
+  const merged = mergeDefinedConfig(defaults, userConfig);
+  delete merged.engine;
+  const keys = checkTopLevelKeys(merged);
+  if (!keys.ok) return keys;
+  const source = await resolveEntrySource(userConfig, merged);
+  if (!source.ok) return source;
+  const hasEntry = source.value.entry !== null;
+
+  const flat = flattenPresets(merged.presets);
+  if (!flat.ok) return flat;
+  const presetSpecs = [];
+  for (let index = 0; index < flat.value.length; index++) {
+    const preset = flat.value[index];
+    const path = `presets[${index}]`;
+    const spec = translateTaggedPreset(preset, path, { hasEntry }) ?? translateStaticPreset(preset, path);
+    if (!spec.ok) return spec;
+    if (spec.value !== null) presetSpecs.push(spec.value);
+  }
+  const presets = flat.value.filter((preset) => /** @type {any} */ (preset).name !== ROLE_PALETTES_PRESET);
+
+  const transformers = translateTransformers(merged.transformers);
+  if (!transformers.ok) return transformers;
+  const inline = translateInline(merged);
+  if (!inline.ok) return inline;
+  for (const key of source.value.derivedKeys) delete (/** @type {Record<string, unknown>} */ (inline.value))[key];
+  const scalars = translateScalars(merged);
+  if (!scalars.ok) return scalars;
+
+  const { root, entry, declarationFiles } = source.value;
+  const request = {
+    root,
+    entry,
+    presets: presetSpecs,
+    declarationFiles,
+    inline: Object.keys(inline.value).length === 0 ? null : inline.value,
+    ...scalars.value,
+  };
+  return { ok: true, request, presets, transformers: transformers.value };
+}
+
+/**
+ * v02.9 §4: `UserConfig` → `LoadProjectRequest`; the first item that cannot be translated is
+ * returned as a `Failure`.
+ * @param {object} userConfig @param {object} defaults
+ * @returns {Promise<{ ok: true, request: Record<string, any>, presets: object[], transformers: object[] } | Failure>}
+ */
+export async function translateConfig(userConfig = {}, defaults = {}) {
+  const outcome = await translate(userConfig, defaults);
+  debugTranslate(outcome, userConfig);
+  return outcome;
+}
+
+/**
+ * v02.9 §9: with `TEACSS_ENGINE_DEBUG=1`, the request or the failure goes to stderr.
+ * @param {{ ok: true, request: Record<string, any> } | Failure} outcome @param {object} userConfig
+ */
+export function debugTranslate(outcome, userConfig) {
+  if (process.env.TEACSS_ENGINE_DEBUG !== "1") return;
+  if (outcome.ok) {
+    process.stderr.write(`[teacss] engine: request for ${outcome.request.entry?.path ?? "<inline>"}\n`);
+    process.stderr.write(`${JSON.stringify(outcome.request, null, 2)}\n`);
+  } else {
+    process.stderr.write(`[teacss] engine: translate failed ${outcome.reason} at ${outcome.path} (keys: ${Object.keys(userConfig).join(", ")})\n`);
+  }
+}
+
+export const VALID_MODES = new Set(["auto", "rust", "ts"]);
+
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+
+/** @param {string} value */
+function parseSemver(value) {
+  const match = SEMVER_RE.exec(value);
+  if (!match) throw new TypeError(`[@teacss/engine] invalid semver: ${value}`);
+  return { core: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4] === undefined ? undefined : match[4].split(".") };
+}
+
+/**
+ * SemVer 2.0 precedence: the numeric triple, then a release above any of its prereleases, then
+ * the prerelease identifiers in order (numeric ones by value and below alphanumeric ones, a shorter
+ * list first when one is a prefix of the other).
+ * @param {string} a @param {string} b @returns {-1 | 0 | 1}
+ */
+export function compareSemver(a, b) {
+  const left = parseSemver(a);
+  const right = parseSemver(b);
+  for (let index = 0; index < 3; index++) {
+    if (left.core[index] !== right.core[index]) return left.core[index] < right.core[index] ? -1 : 1;
+  }
+  if (!left.prerelease || !right.prerelease) return left.prerelease === right.prerelease ? 0 : left.prerelease ? -1 : 1;
+  const length = Math.min(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < length; index++) {
+    const x = left.prerelease[index];
+    const y = right.prerelease[index];
+    if (x === y) continue;
+    const xNumeric = /^\d+$/.test(x);
+    const yNumeric = /^\d+$/.test(y);
+    if (xNumeric && yNumeric) return Number(x) < Number(y) ? -1 : 1;
+    if (xNumeric !== yNumeric) return xNumeric ? -1 : 1;
+    return x < y ? -1 : 1;
+  }
+  if (left.prerelease.length === right.prerelease.length) return 0;
+  return left.prerelease.length < right.prerelease.length ? -1 : 1;
+}
+
+/** Only the `>=A <B` form `engineCompat.core` uses (v02.11 §7.3). @param {string} version @param {string} range */
+export function satisfiesRange(version, range) {
+  const parts = range.trim().split(/\s+/);
+  if (parts.length !== 2 || !parts[0].startsWith(">=") || !parts[1].startsWith("<") || parts[1].startsWith("<=")) throw new TypeError(`[@teacss/engine] unsupported engineCompat range: ${range}`);
+  return compareSemver(version, parts[0].slice(2)) >= 0 && compareSemver(version, parts[1].slice(1)) < 0;
+}
+
+/**
+ * v02.9 §8.1: `TEACSS_ENGINE` over the hook option over `"ts"`; an `"auto"` option stays on TS while
+ * `defaultMode` is `"opt-in"`; a host core outside `engineCompat.core` keeps TS, or throws when
+ * Rust was asked for.
+ * @param {{ hostCoreVersion?: string | undefined, option?: unknown, env?: string | undefined, compat?: { core?: string, defaultMode?: "opt-in" | "auto" } }} args
+ * @returns {{ engine: "rust" | "ts", mode: "auto" | "rust" | "ts", source: "env" | "option" | "default", invalidEnv?: string, resolvedBy?: "opt-in", reason?: string, path?: string, detail?: Record<string, unknown> }}
+ */
+export function selectEngineRequest({ hostCoreVersion, option, env, compat = ENGINE_COMPAT }) {
+  /** @type {"auto" | "rust" | "ts"} */
+  let mode;
+  /** @type {"env" | "option" | "default"} */
+  let source;
+  /** @type {string | undefined} */
+  let invalidEnv;
+  if (env !== undefined && env !== "" && VALID_MODES.has(env)) {
+    mode = /** @type {"auto" | "rust" | "ts"} */ (env);
+    source = "env";
+  } else {
+    if (env !== undefined && env !== "") invalidEnv = env;
+    if (typeof option === "string" && VALID_MODES.has(option)) {
+      mode = /** @type {"auto" | "rust" | "ts"} */ (option);
+      source = "option";
+    } else {
+      mode = "ts";
+      source = "default";
+    }
+  }
+  const base = invalidEnv === undefined ? { mode, source } : { mode, source, invalidEnv };
+  if (mode === "ts") return { engine: "ts", ...base };
+  if (mode === "auto" && source === "option" && compat.defaultMode === "opt-in") return { engine: "ts", ...base, resolvedBy: "opt-in" };
+  if (compat.core && typeof hostCoreVersion === "string" && !satisfiesRange(hostCoreVersion, compat.core)) {
+    const detail = { hostCoreVersion, engineVersion: ENGINE_PACKAGE_VERSION, range: compat.core };
+    if (mode === "rust") throw new TeacssEngineError("E_ENGINE_COMPAT", `[@teacss/engine] @teacss/core ${hostCoreVersion} is outside engineCompat.core ${compat.core} (engine ${ENGINE_PACKAGE_VERSION})`, detail);
+    return { engine: "ts", ...base, reason: "engine-compat", path: "@teacss/core", detail };
+  }
+  return { engine: "rust", ...base };
+}

package/src/facade/transformer.mjs

@@ -0,0 +1,56 @@
+// @ts-check
+import { ENGINE_INSTANCE } from "./constants.mjs";
+
+/**
+ * Replays v02.2 `TransformResult.edits` on the host MagicString. A zero-length range is an insert:
+ * magic-string throws on a zero-length `update`.
+ * @param {{ update(start: number, end: number, text: string): unknown, appendLeft(index: number, text: string): unknown }} s
+ * @param {{ start: number, end: number, text: string }[]} edits
+ */
+export function replayEdits(s, edits) {
+  for (const { start, end, text } of edits) {
+    if (start === end) s.appendLeft(start, text);
+    else s.update(start, end, text);
+  }
+}
+
+/** @param {any} ctx */
+const engineOf = (ctx) => ctx?.generator?.[ENGINE_INSTANCE] ?? null;
+
+/**
+ * The object shape of preset-standard/transformers/compile-class.ts:178-274, backed by Rust
+ * `transformSource`. It has no `idFilter`: the runtime's pipeline filter picks the modules.
+ */
+export function createCompileClassTransformer() {
+  return {
+    name: "@teacss/transformer-compile-class",
+    enforce: "pre",
+    /** @param {any} s @param {string} id @param {any} ctx */
+    async transform(s, id, ctx) {
+      const engine = engineOf(ctx);
+      if (!engine) return;
+      const result = engine.transformSource(id, s.original);
+      if (!result) return;
+      replayEdits(s, result.edits);
+      if (ctx.tokens) for (const name of result.compiledClasses) ctx.tokens.add(name);
+      if (result.definitionsChanged) ctx.invalidate?.();
+      return { highlightAnnotations: result.highlightAnnotations };
+    },
+    /**
+     * Releases the module's definitions only: the runtime also calls this when a module stays
+     * (context switches, failed transforms), so its tokens are kept (v02.9 §6.1 step 8).
+     * @param {string} id @param {any} ctx
+     */
+    onModuleRemoved(id, ctx) {
+      const engine = engineOf(ctx);
+      if (!engine) return;
+      let changed = false;
+      try {
+        changed = engine.clearModuleDefinitions(id);
+      } catch (error) {
+        if (/** @type {any} */ (error)?.code !== "E_DISPOSED") throw error;
+      }
+      if (changed) ctx.invalidate?.();
+    },
+  };
+}