@canonical/terrazzo-plugin-css 0.1.0 → 0.3.0

package/dist/esm/plugin.js

@@ -1,930 +1,8 @@
 /**
- * @canonical/terrazzo-plugin-css — Custom Terrazzo plugin for Canonical design tokens.
+ * Plugin composition-root shim.
  *
- * Generates CSS files from a single resolver:
- *   sets.primitive.css     — :root with primitive tokens
- *   sets.semantic.css      — :root with mode-invariant semantics (may be empty)
- *   modifiers.theme.css    — light-dark() colour tokens + delta vars
- *   modifiers.typography.css — base + per-product typography
- *   modifiers.{family}.css — modifier channel classes (one file per family)
- *   modifiers.surfaces.css — surface channel classes
- *   states.css             — derived hover/active/disabled via * {}
- *   tokens.json            — LSP artifact
+ * Keeps the historical `plugin.ts` entry point while the implementation,
+ * its sidecar tests, and its option types live together under `plugin/`.
  */
-import { readFileSync } from "node:fs";
-import { transformCSSValue } from "@terrazzo/token-tools/css";
-import { makeArtifactToken, makeDerivedArtifactToken, serializeArtifact, } from "./artifact/index.js";
-import { decl, printRules, rule } from "./css-ast/index.js";
-import { resolveLayerConfig, wrapInLayer } from "./layers/index.js";
-import { buildLightDarkDeclarations } from "./light-dark/index.js";
-import { buildModifierContextCSS, computeModifierContext, } from "./modifiers/index.js";
-import { prefixVar, tokenIdToCssVar } from "./naming.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const FORMAT = "canonical-css";
-const HEADER = "/* Generated by @canonical/terrazzo-plugin-css. DO NOT EDIT. */";
-// ---------------------------------------------------------------------------
-// Token classification helpers
-// ---------------------------------------------------------------------------
-/** Token IDs that belong to the primitive set. */
-function isPrimitive(id) {
-    return (id.startsWith("color.palette.") ||
-        id.startsWith("dimension.") ||
-        id.startsWith("number.") ||
-        id.startsWith("typography.fontFamily.") ||
-        id.startsWith("typography.fontWeight.") ||
-        id.startsWith("typography.fontStyle.") ||
-        id.startsWith("typography.figureStyle.") ||
-        id.startsWith("typography.textDecoration.") ||
-        id.startsWith("typography.letterCase."));
-}
-/** Token IDs that are semantic colour tokens (from theme modifier). */
-function isSemanticColor(id) {
-    return id.startsWith("color.") && !id.startsWith("color.palette.");
-}
-/** Token IDs that are semantic typography (from typography modifier). */
-function isSemanticTypography(id) {
-    return id.startsWith("typography.") && !isPrimitive(id);
-}
-// ---------------------------------------------------------------------------
-// Transform value helper
-// ---------------------------------------------------------------------------
-/**
- * Coerce transformCSSValue output to a simple string (sRGB fallback for
- * wide-gamut, or the plain string).  Returns null for multi-value
- * (typography composites) — those are handled separately.
- */
-function cssValueToString(val) {
-    if (typeof val === "string")
-        return val;
-    if ("." in val)
-        return val["."]; // WideGamutColorValue sRGB fallback
-    return null; // multi-value (typography)
-}
-/**
- * Walk a DTCG token JSON tree and collect alias targets (from `$value` alias
- * strings) and `$description` values, keyed by the dot-separated token ID path.
- *
- * @note Performs synchronous file I/O (readFileSync).
- */
-function extractModifierFileData(filePath) {
-    const aliases = {};
-    const descriptions = {};
-    try {
-        const raw = readFileSync(filePath, "utf8");
-        const json = JSON.parse(raw);
-        walkTokenTree(json, [], aliases, descriptions);
-    }
-    catch (err) {
-        console.warn(`[canonical-css] Could not read modifier data from ${filePath}:`, err instanceof Error ? err.message : err);
-    }
-    return { aliases, descriptions };
-}
-/**
- * Recursively walk a DTCG token tree, collecting alias targets and
- * `$description` values.
- *
- * Alias targets are extracted from DTCG `$value` strings matching the
- * `"{token.path}"` pattern. When `$root` is encountered, the token ID
- * is the parent path (the `$root` marker is stripped per DTCG spec).
- */
-function walkTokenTree(node, path, aliases, descriptions) {
-    if (typeof node !== "object" || node === null)
-        return;
-    const obj = node;
-    // Check for DTCG alias: $value is a string matching "{token.path}"
-    const rawValue = obj.$value;
-    if (typeof rawValue === "string") {
-        const aliasMatch = /^\{(.+)\}$/.exec(rawValue);
-        if (aliasMatch) {
-            const tokenId = path.join(".");
-            aliases[tokenId] = aliasMatch[1];
-        }
-    }
-    // Collect $description at this level (only for token nodes with $value)
-    if ("$value" in obj &&
-        "$description" in obj &&
-        typeof obj.$description === "string") {
-        const tokenId = path.join(".");
-        descriptions[tokenId] = obj.$description;
-    }
-    // Recurse into children (skip $-prefixed keys except $root)
-    for (const [key, value] of Object.entries(obj)) {
-        if (key === "$root") {
-            // $root collapses to the parent path
-            walkTokenTree(value, path, aliases, descriptions);
-        }
-        else if (key.startsWith("$")) {
-        }
-        else {
-            walkTokenTree(value, [...path, key], aliases, descriptions);
-        }
-    }
-}
-/**
- * Load modifier file data for a specific family context by reading the raw
- * token source files referenced in the resolver JSON.
- *
- * Returns both the alias map (token ID → aliasOf target) and the
- * description map (token ID → `$description` text).
- *
- * @note Performs synchronous file I/O (readFileSync + JSON.parse on the resolver).
- * @param tokensDir  - Base directory for token sources (e.g. "./tokens/canonical")
- * @param family     - Modifier family name (e.g. "anticipation")
- * @param context    - Context name (e.g. "constructive")
- */
-function loadModifierData(tokensDir, family, context) {
-    // Read the resolver JSON to find the $ref paths for this context
-    const resolverPath = `${tokensDir}/canonical.resolver.json`;
-    try {
-        const resolverJson = JSON.parse(readFileSync(resolverPath, "utf8"));
-        const refs = resolverJson.modifiers?.[family]?.contexts?.[context] ?? [];
-        const aliases = {};
-        const descriptions = {};
-        for (const ref of refs) {
-            if (ref.$ref) {
-                const filePath = `${tokensDir}/${ref.$ref}`;
-                const data = extractModifierFileData(filePath);
-                Object.assign(aliases, data.aliases);
-                Object.assign(descriptions, data.descriptions);
-            }
-        }
-        return { aliases, descriptions };
-    }
-    catch (err) {
-        console.warn(`[canonical-css] Could not load modifier data for ${family}/${context}:`, err instanceof Error ? err.message : err);
-        return { aliases: {}, descriptions: {} };
-    }
-}
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Create the Canonical CSS plugin for Terrazzo.
- *
- * @example
- * ```ts
- * import { defineConfig } from "@terrazzo/cli";
- * import { canonicalPlugin } from "./src/plugin/plugin.js";
- *
- * export default defineConfig({
- *   tokens: ["./tokens/canonical/canonical.resolver.json"],
- *   plugins: [canonicalPlugin()],
- * });
- * ```
- */
-export function canonicalPlugin(options = {}) {
-    const layers = resolveLayerConfig(options.layers);
-    const tokensDir = options.tokensDir ?? "./tokens/canonical";
-    const families = options.families ?? [
-        "anticipation",
-        "criticality",
-        "emphasis",
-        "importance",
-    ];
-    return {
-        name: "@canonical/terrazzo-plugin-css",
-        // ── transform() ────────────────────────────────────────────────────
-        async transform({ tokens, setTransform, resolver, }) {
-            // Base resolution (all defaults: light theme, global typography, small breakpoint)
-            const baseSet = resolver.apply({});
-            // Transform every token in the base resolution
-            for (const [id, token] of Object.entries(baseSet)) {
-                const cssVar = tokenIdToCssVar(id);
-                const val = transformCSSValue(token, {
-                    tokensSet: baseSet,
-                    permutation: {},
-                });
-                const str = cssValueToString(val);
-                if (str !== null) {
-                    setTransform(id, { format: FORMAT, localID: cssVar, value: str });
-                }
-                else {
-                    // Multi-value (typography composite) — emit each sub-property
-                    setTransform(id, {
-                        format: FORMAT,
-                        localID: cssVar,
-                        value: val,
-                    });
-                }
-            }
-            // Dark theme — register additional transforms for colour tokens
-            const darkSet = resolver.apply({ theme: "dark" });
-            for (const [id, token] of Object.entries(darkSet)) {
-                if (token.$type !== "color")
-                    continue;
-                const cssVar = tokenIdToCssVar(id);
-                const val = transformCSSValue(token, {
-                    tokensSet: darkSet,
-                    permutation: { theme: "dark" },
-                });
-                const str = cssValueToString(val);
-                if (str !== null) {
-                    setTransform(id, {
-                        format: FORMAT,
-                        localID: cssVar,
-                        value: str,
-                        input: { theme: "dark" },
-                    });
-                }
-            }
-            // Typography product contexts
-            for (const ctx of ["apps", "docs", "sites"]) {
-                const typoSet = resolver.apply({ typography: ctx });
-                for (const [id, token] of Object.entries(typoSet)) {
-                    if (!isSemanticTypography(id))
-                        continue;
-                    // setTransform requires the token ID to exist in the base `tokens`
-                    // map. Context-only tokens (e.g. typography.heading.display in sites)
-                    // must be skipped.
-                    if (!(id in tokens))
-                        continue;
-                    const cssVar = tokenIdToCssVar(id);
-                    const val = transformCSSValue(token, {
-                        tokensSet: typoSet,
-                        permutation: { typography: ctx },
-                    });
-                    const str = cssValueToString(val);
-                    if (str !== null) {
-                        setTransform(id, {
-                            format: FORMAT,
-                            localID: cssVar,
-                            value: str,
-                            input: { typography: ctx },
-                        });
-                    }
-                    else {
-                        setTransform(id, {
-                            format: FORMAT,
-                            localID: cssVar,
-                            value: val,
-                            input: { typography: ctx },
-                        });
-                    }
-                }
-            }
-        },
-        // ── build() ────────────────────────────────────────────────────────
-        async build({ tokens, getTransforms, resolver, outputFile, }) {
-            const artifact = {};
-            // Capture CSS outputs so we can scan them for declaration positions
-            const cssOutputs = new Map();
-            const capturingOutputFile = (filename, contents) => {
-                if (typeof contents === "string" && filename.endsWith(".css")) {
-                    cssOutputs.set(filename, contents);
-                }
-                outputFile(filename, contents);
-            };
-            // ── sets.primitive.css ───────────────────────────────────────────
-            buildSetsPrimitive(getTransforms, layers, artifact, capturingOutputFile);
-            // ── sets.semantic.css ───────────────────────────────────────────
-            buildSetsSemantic(layers, capturingOutputFile);
-            // ── modifiers.theme.css ─────────────────────────────────────────
-            buildTheme(tokens, getTransforms, resolver, layers, artifact, capturingOutputFile);
-            // ── modifiers.typography.css ────────────────────────────────────
-            buildTypography(getTransforms, layers, artifact, capturingOutputFile);
-            // ── modifiers.{family}.css ──────────────────────────────────────
-            for (const family of families) {
-                buildFamily(family, resolver, layers, artifact, capturingOutputFile, tokensDir);
-            }
-            // ── modifiers.surfaces.css ──────────────────────────────────────
-            buildSurfaces(resolver, layers, artifact, capturingOutputFile, tokensDir);
-            // ── states.css ──────────────────────────────────────────────────
-            buildStates(tokens, resolver, layers, artifact, capturingOutputFile);
-            // ── Annotate artifact with declaration positions ───────────────
-            annotateDeclarations(artifact, cssOutputs);
-            // ── tokens.json ─────────────────────────────────────────────────
-            outputFile("tokens.json", serializeArtifact(artifact));
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// Build helpers
-//
-// @note All build* functions are impure: they mutate the `artifact` map and
-//       call `outputFile()` to emit CSS files.  They are called once per
-//       build run from the plugin's `build()` hook.
-// ---------------------------------------------------------------------------
-/** @note Mutates `artifact`, calls `outputFile`. */
-function buildSetsPrimitive(getTransforms, layers, artifact, outputFile) {
-    const transforms = getTransforms({ format: FORMAT });
-    const nodes = [];
-    for (const t of transforms) {
-        if (!isPrimitive(t.id))
-            continue;
-        if (t.id.startsWith("number."))
-            continue;
-        // Skip dark / per-product permutations — only use the base
-        if (t.input &&
-            Object.keys(t.input).some((k) => k === "theme" && t.input[k] !== "light"))
-            continue;
-        if (t.input && "typography" in t.input && t.input.typography !== "global")
-            continue;
-        const cssVar = t.localID ?? tokenIdToCssVar(t.id);
-        if (t.type === "SINGLE_VALUE") {
-            nodes.push(decl(cssVar, t.value));
-            artifact[cssVar] = makeArtifactToken({
-                cssVar,
-                id: t.id,
-                type: t.token.$type ?? "unknown",
-                tier: "primitive",
-                cssOutputFile: "sets.primitive.css",
-                description: t.token.$description,
-                valueLight: t.value,
-                valueDark: t.value,
-            });
-        }
-        else {
-            // Multi-value — emit each sub-property
-            for (const [suffix, val] of Object.entries(t.value)) {
-                const subVar = `${cssVar}-${suffix}`;
-                nodes.push(decl(subVar, val));
-                artifact[subVar] = makeArtifactToken({
-                    cssVar: subVar,
-                    id: `${t.id}.${suffix}`,
-                    type: t.token.$type ?? "unknown",
-                    tier: "primitive",
-                    cssOutputFile: "sets.primitive.css",
-                    description: t.token.$description,
-                    valueLight: val,
-                    valueDark: val,
-                });
-            }
-        }
-    }
-    const wrapped = wrapInLayer(layers.tokens, [rule([":root"], nodes)]);
-    outputFile("sets.primitive.css", `${HEADER}\n${printRules(wrapped)}\n`);
-}
-/** @note Calls `outputFile`. */
-function buildSetsSemantic(_layers, outputFile) {
-    // In V2, most semantic tokens come via modifier contexts (theme, typography).
-    // This file may be empty.  Emit a comment-only placeholder.
-    const comment = "/* sets.semantic.css — no mode-invariant semantic tokens in V2. */";
-    outputFile("sets.semantic.css", `${HEADER}\n${comment}\n`);
-}
-/** @note Mutates `artifact`, calls `outputFile`. */
-function buildTheme(tokens, getTransforms, resolver, layers, artifact, outputFile) {
-    // Collect base (light) and dark transforms for colour tokens
-    const baseTransforms = getTransforms({ format: FORMAT });
-    const darkTransforms = getTransforms({
-        format: FORMAT,
-        input: { theme: "dark" },
-    });
-    // Index dark transforms by token ID
-    const darkById = new Map();
-    for (const t of darkTransforms) {
-        if (t.type !== "SINGLE_VALUE")
-            continue;
-        darkById.set(t.id, t.value);
-    }
-    // Build a reverse index: resolved literal value → primitive var name.
-    // When a semantic token resolves to the same literal as a primitive,
-    // we emit var(--primitive) instead of the raw oklch value. This keeps
-    // the CSS and artifact connected to the primitive tokens rather than
-    // resolving away the relationship.
-    const primitiveByValue = new Map();
-    for (const [cssVar, entry] of Object.entries(artifact)) {
-        if (entry.tier === "primitive" &&
-            entry.type === "color" &&
-            entry.valueLight) {
-            if (!primitiveByValue.has(entry.valueLight)) {
-                primitiveByValue.set(entry.valueLight, cssVar);
-            }
-        }
-    }
-    // Build light-dark pairs for semantic colour tokens
-    const pairs = [];
-    const seenIds = new Set();
-    for (const t of baseTransforms) {
-        if (!isSemanticColor(t.id))
-            continue;
-        if (t.type !== "SINGLE_VALUE")
-            continue;
-        if (seenIds.has(t.id))
-            continue;
-        seenIds.add(t.id);
-        const cssVar = t.localID ?? tokenIdToCssVar(t.id);
-        const rawLight = t.value;
-        const rawDark = darkById.get(t.id) ?? rawLight;
-        // Recover var() references to primitives when the resolved literal
-        // matches a known primitive value. Skip when the value already is a
-        // var() reference (whole-token aliases preserved by Terrazzo).
-        const lightVal = recoverPrimitiveRef(rawLight, cssVar, primitiveByValue);
-        const darkVal = recoverPrimitiveRef(rawDark, cssVar, primitiveByValue);
-        pairs.push({ property: cssVar, light: lightVal, dark: darkVal });
-        artifact[cssVar] = makeArtifactToken({
-            cssVar,
-            id: t.id,
-            type: "color",
-            tier: "semantic",
-            cssOutputFile: "modifiers.theme.css",
-            description: t.token.$description,
-            valueLight: lightVal,
-            valueDark: darkVal,
-        });
-    }
-    // Build CSS
-    const themeDecls = buildLightDarkDeclarations(pairs);
-    // Compute NativeState deltas (task 2.9)
-    const { lightDeltaDecls, darkDeltaDecls } = computeDeltas(tokens, resolver, artifact);
-    // Assemble :root block
-    const rootNodes = [
-        decl("color-scheme", "light dark"),
-        ...themeDecls,
-        ...lightDeltaDecls,
-    ];
-    const rootRule = rule([":root"], rootNodes);
-    // Override selectors
-    const lightOverride = rule([".light"], [decl("color-scheme", "light")]);
-    const darkOverride = rule([".dark"], [decl("color-scheme", "dark"), ...darkDeltaDecls]);
-    const mediaQuery = rule(["@media (prefers-color-scheme: dark)"], [rule([":root"], [decl("color-scheme", "dark"), ...darkDeltaDecls])]);
-    const wrapped = wrapInLayer(layers.modifiers, [
-        rootRule,
-        lightOverride,
-        darkOverride,
-        mediaQuery,
-    ]);
-    outputFile("modifiers.theme.css", `${HEADER}\n${printRules(wrapped)}\n`);
-}
-/** @note Mutates `artifact`, calls `outputFile`. */
-function buildTypography(getTransforms, layers, artifact, outputFile) {
-    const allNodes = [];
-    // Base (global) typography → :root
-    const baseTransforms = getTransforms({ format: FORMAT });
-    const rootDecls = [];
-    const seenIds = new Set();
-    for (const t of baseTransforms) {
-        if (!isSemanticTypography(t.id))
-            continue;
-        if (seenIds.has(t.id))
-            continue;
-        seenIds.add(t.id);
-        emitTypographyDecls(t, rootDecls, artifact, "modifiers.typography.css");
-    }
-    allNodes.push(rule([":root"], rootDecls));
-    // Per-product contexts → class selectors
-    for (const ctx of ["apps", "docs", "sites"]) {
-        const contextTransforms = getTransforms({
-            format: FORMAT,
-            input: { typography: ctx },
-        });
-        const contextDecls = [];
-        for (const t of contextTransforms) {
-            if (!isSemanticTypography(t.id))
-                continue;
-            emitTypographyDecls(t, contextDecls, artifact, "modifiers.typography.css");
-        }
-        if (contextDecls.length > 0) {
-            allNodes.push(rule([`.${ctx}`], contextDecls));
-        }
-    }
-    const wrapped = wrapInLayer(layers.modifiers, allNodes);
-    outputFile("modifiers.typography.css", `${HEADER}\n${printRules(wrapped)}\n`);
-}
-function emitTypographyDecls(t, decls, artifact, outputFile) {
-    const cssVar = t.localID ?? tokenIdToCssVar(t.id);
-    if (t.type === "SINGLE_VALUE") {
-        decls.push(decl(cssVar, t.value));
-        artifact[cssVar] = makeArtifactToken({
-            cssVar,
-            id: t.id,
-            type: t.token.$type ?? "unknown",
-            tier: "semantic",
-            cssOutputFile: outputFile,
-            description: t.token.$description,
-            valueLight: t.value,
-            valueDark: t.value,
-        });
-    }
-    else {
-        // Multi-value: typography composite → individual sub-properties
-        for (const [suffix, val] of Object.entries(t.value)) {
-            const subVar = `${cssVar}-${suffix}`;
-            decls.push(decl(subVar, val));
-            artifact[subVar] = makeArtifactToken({
-                cssVar: subVar,
-                id: `${t.id}.${suffix}`,
-                type: t.token.$type ?? "unknown",
-                tier: "semantic",
-                cssOutputFile: outputFile,
-                description: t.token.$description,
-                valueLight: val,
-                valueDark: val,
-            });
-        }
-    }
-}
-/** @note Mutates `artifact`, calls `outputFile` and `loadModifierData` (file I/O). */
-function buildFamily(family, resolver, layers, artifact, outputFile, tokensDir) {
-    const baseTokens = resolver.apply({});
-    const modifiers = resolver.source?.modifiers;
-    const familyMod = modifiers?.[family];
-    if (!familyMod?.contexts)
-        return;
-    const allNodes = [];
-    for (const context of Object.keys(familyMod.contexts)) {
-        if (context === "none")
-            continue; // skip the empty default context
-        const { aliases: aliasMap, descriptions } = loadModifierData(tokensDir, family, context);
-        const overlayTokens = resolver.apply({ [family]: context });
-        // Build channel-var → description lookup
-        const descByChannelVar = buildDescriptionLookup(descriptions, "modifier");
-        const ctx = computeModifierContext(family, context, baseTokens, overlayTokens, "modifier", aliasMap);
-        const nodes = buildModifierContextCSS(ctx);
-        allNodes.push(...nodes);
-        // Register channel declarations in artifact
-        for (const d of ctx.declarations) {
-            artifact[d.property] = makeDerivedArtifactToken({
-                cssVar: d.property,
-                type: "color",
-                tier: "semantic",
-                cssOutputFile: `modifiers.${family}.css`,
-                derivedFrom: d.value.replace(/^var\(/, "").replace(/\)$/, ""),
-                derivation: "channel-modifier",
-                description: descByChannelVar[d.property],
-            });
-        }
-    }
-    const wrapped = wrapInLayer(layers.modifiers, allNodes);
-    outputFile(`modifiers.${family}.css`, `${HEADER}\n${printRules(wrapped)}\n`);
-}
-/**
- * Surface selector compounding: map resolver context names to compound
- * `.surface` descendant selectors based on depth.
- *
- * - layer1 → `.surface`                      (depth 1)
- * - layer2 → `.surface .surface`             (depth 2)
- * - layer3 → `.surface .surface .surface`    (depth 3, capped)
- */
-const SURFACE_SELECTOR_MAP = {
-    layer1: ".surface",
-    layer2: ".surface .surface",
-    layer3: ".surface .surface .surface",
-};
-/** @note Mutates `artifact`, calls `outputFile` and `loadModifierData` (file I/O). */
-function buildSurfaces(resolver, layers, artifact, outputFile, tokensDir) {
-    const baseTokens = resolver.apply({});
-    const modifiers = resolver.source?.modifiers;
-    const surfaceMod = modifiers?.surface;
-    if (!surfaceMod?.contexts)
-        return;
-    const allNodes = [];
-    for (const context of Object.keys(surfaceMod.contexts)) {
-        if (context === "none")
-            continue; // skip the empty default context
-        const { aliases: aliasMap, descriptions } = loadModifierData(tokensDir, "surface", context);
-        const overlayTokens = resolver.apply({ surface: context });
-        // Build channel-var → description lookup
-        const descByChannelVar = buildDescriptionLookup(descriptions, "surface");
-        const ctx = computeModifierContext("surface", context, baseTokens, overlayTokens, "surface", aliasMap, SURFACE_SELECTOR_MAP[context]);
-        const nodes = buildModifierContextCSS(ctx);
-        allNodes.push(...nodes);
-        for (const d of ctx.declarations) {
-            artifact[d.property] = makeDerivedArtifactToken({
-                cssVar: d.property,
-                type: "color",
-                tier: "semantic",
-                cssOutputFile: "modifiers.surfaces.css",
-                derivedFrom: d.value.replace(/^var\(/, "").replace(/\)$/, ""),
-                derivation: "channel-surface",
-                description: descByChannelVar[d.property],
-            });
-        }
-    }
-    const wrapped = wrapInLayer(layers.surfaces, allNodes);
-    outputFile("modifiers.surfaces.css", `${HEADER}\n${printRules(wrapped)}\n`);
-}
-// ---------------------------------------------------------------------------
-// NativeState delta computation (task 2.9)
-// ---------------------------------------------------------------------------
-/** Interactive roles and their state variants. */
-const INTERACTIVE_ROLES = [
-    {
-        role: "color.foreground.primary",
-        states: ["hover", "active", "disabled"],
-        hasSurface: false,
-        hasModifier: true,
-    },
-    {
-        role: "color.foreground.secondary",
-        states: ["hover", "active", "disabled"],
-        hasSurface: false,
-        hasModifier: true,
-    },
-    {
-        role: "color.foreground.ghost",
-        states: ["hover", "active", "disabled"],
-        hasSurface: true,
-        hasModifier: true,
-    },
-    {
-        role: "color.foreground.input",
-        states: ["hover", "active", "disabled"],
-        hasSurface: true,
-        hasModifier: true,
-    },
-    {
-        role: "color.foreground.navigation.primary",
-        states: ["hover", "active", "disabled"],
-        hasSurface: true,
-        hasModifier: false,
-    },
-    {
-        role: "color.foreground.navigation.secondary",
-        states: ["hover", "active", "disabled"],
-        hasSurface: false,
-        hasModifier: false,
-    },
-    {
-        role: "color.foreground.checkbox.unselected",
-        states: ["hover", "active", "disabled"],
-        hasSurface: true,
-        hasModifier: false,
-    },
-    {
-        role: "color.foreground.radio.unselected",
-        states: ["hover", "active", "disabled"],
-        hasSurface: true,
-        hasModifier: false,
-    },
-    {
-        role: "color.foreground.checkbox.checkmark",
-        states: ["disabled"],
-        hasSurface: true,
-        hasModifier: false,
-    },
-    {
-        role: "color.foreground.radio.checkmark",
-        states: ["disabled"],
-        hasSurface: true,
-        hasModifier: false,
-    },
-    {
-        role: "color.foreground.switch.knob",
-        states: ["disabled"],
-        hasSurface: true,
-        hasModifier: false,
-    },
-    {
-        role: "color.border",
-        states: ["disabled"],
-        hasSurface: false,
-        hasModifier: true,
-    },
-    {
-        role: "color.text",
-        states: ["disabled"],
-        hasSurface: false,
-        hasModifier: true,
-    },
-    {
-        role: "color.icon",
-        states: ["disabled"],
-        hasSurface: false,
-        hasModifier: true,
-    },
-];
-/**
- * Compute per-role lightness deltas for hover/active states.
- *
- * Deltas must be emitted as plain numbers — NOT wrapped in `light-dark()` —
- * because `var(--delta-*)` is consumed inside `calc()` inside `oklch(from ...)`,
- * and `light-dark()` inside `calc()` inside `oklch(from ...)` is broken in
- * Chromium (resolves to transparent). The chosen approach (per the design spec)
- * is: `:root` sets the light-mode delta as default, `.dark` and
- * `@media (prefers-color-scheme: dark)` override with dark-mode deltas.
- */
-function computeDeltas(_tokens, resolver, artifact) {
-    const lightSet = resolver.apply({ theme: "light" });
-    const darkSet = resolver.apply({ theme: "dark" });
-    const lightDeltaDecls = [];
-    const darkDeltaDecls = [];
-    for (const { role, states } of INTERACTIVE_ROLES) {
-        for (const state of states) {
-            if (state === "disabled")
-                continue; // disabled uses color-mix, no delta
-            const stateId = `${role}.${state}`;
-            const lightRest = lightSet[role];
-            const lightState = lightSet[stateId];
-            const darkRest = darkSet[role];
-            const darkState = darkSet[stateId];
-            if (!lightRest?.$value || !lightState?.$value)
-                continue;
-            if (!darkRest?.$value || !darkState?.$value)
-                continue;
-            const lightRestL = extractOklchL(lightRest.$value);
-            const lightStateL = extractOklchL(lightState.$value);
-            const darkRestL = extractOklchL(darkRest.$value);
-            const darkStateL = extractOklchL(darkState.$value);
-            if (lightRestL === null ||
-                lightStateL === null ||
-                darkRestL === null ||
-                darkStateL === null)
-                continue;
-            const lightDelta = lightStateL - lightRestL;
-            const darkDelta = darkStateL - darkRestL;
-            const rolePath = tokenIdToCssVar(role).slice(2); // strip --
-            const deltaVar = `--delta-${state}-${rolePath}`;
-            // :root gets the light-mode delta (light is the default color-scheme)
-            lightDeltaDecls.push(decl(deltaVar, formatDelta(lightDelta)));
-            // .dark and @media override get the dark-mode delta
-            darkDeltaDecls.push(decl(deltaVar, formatDelta(darkDelta)));
-            artifact[deltaVar] = makeDerivedArtifactToken({
-                cssVar: deltaVar,
-                type: "number",
-                tier: "derived",
-                cssOutputFile: "modifiers.theme.css",
-                derivedFrom: tokenIdToCssVar(role),
-                derivation: "delta",
-                valueLight: formatDelta(lightDelta),
-                valueDark: formatDelta(darkDelta),
-            });
-        }
-    }
-    return { lightDeltaDecls, darkDeltaDecls };
-}
-function extractOklchL(value) {
-    if (typeof value === "object" &&
-        value !== null &&
-        "colorSpace" in value &&
-        value.colorSpace === "oklch" &&
-        "components" in value &&
-        Array.isArray(value.components)) {
-        const l = value.components[0];
-        return typeof l === "number" ? l : null;
-    }
-    return null;
-}
-function formatDelta(d) {
-    // Round to 6 decimal places to avoid floating-point noise
-    const rounded = Math.round(d * 1_000_000) / 1_000_000;
-    return String(rounded);
-}
-// ---------------------------------------------------------------------------
-// states.css (task 2.10) — generated derivation layer
-// ---------------------------------------------------------------------------
-/** @note Mutates `artifact`, calls `outputFile`. */
-function buildStates(_tokens, _resolver, layers, artifact, outputFile) {
-    const derivedDecls = [];
-    for (const { role, states, hasSurface, hasModifier } of INTERACTIVE_ROLES) {
-        const cssRole = tokenIdToCssVar(role); // e.g. --color-foreground-primary
-        const rolePath = cssRole.slice(2); // color-foreground-primary
-        // Build fallback chain: modifier → surface → base
-        const restFallback = buildFallbackChain(cssRole, hasModifier, hasSurface);
-        const bgFallback = buildFallbackChain("--color-background", false, true);
-        for (const state of states) {
-            const derivedVar = `--${state}--${rolePath}`;
-            let formula;
-            if (state === "disabled") {
-                // color-mix(in oklch, <rest> 34%, <background>)
-                formula = `color-mix(in oklch, ${restFallback} 34%, ${bgFallback})`;
-            }
-            else {
-                // oklch(from <rest> calc(l + var(--delta-{state}-{role})) c h)
-                const deltaVar = `--delta-${state}-${rolePath}`;
-                formula = `oklch(from ${restFallback} calc(l + var(${deltaVar})) c h)`;
-            }
-            derivedDecls.push(decl(derivedVar, formula));
-            artifact[derivedVar] = makeDerivedArtifactToken({
-                cssVar: derivedVar,
-                type: "color",
-                tier: "derived",
-                cssOutputFile: "states.css",
-                derivedFrom: cssRole,
-                derivation: state,
-            });
-        }
-    }
-    const starRule = rule(["*"], derivedDecls);
-    const wrapped = wrapInLayer(layers.states, [starRule]);
-    outputFile("states.css", `${HEADER}\n${printRules(wrapped)}\n`);
-}
-function buildFallbackChain(cssVar, hasModifier, hasSurface) {
-    const modVar = prefixVar(cssVar, "modifier");
-    const surfVar = prefixVar(cssVar, "surface");
-    if (hasModifier && hasSurface) {
-        return `var(${modVar}, var(${surfVar}, var(${cssVar})))`;
-    }
-    if (hasModifier) {
-        return `var(${modVar}, var(${cssVar}))`;
-    }
-    if (hasSurface) {
-        return `var(${surfVar}, var(${cssVar}))`;
-    }
-    return `var(${cssVar})`;
-}
-// ---------------------------------------------------------------------------
-// Declaration annotation
-// ---------------------------------------------------------------------------
-/**
- * Scan CSS output strings and annotate artifact tokens with their
- * declaration sites (selector, file, line).
- *
- * Parses each CSS file to find custom property declarations (`--var: ...`)
- * and records the enclosing selector and line number. Tokens appearing in
- * multiple selectors (e.g. modifier channels in `.warning`, `.error`, etc.)
- * accumulate all their declaration sites.
- */
-function annotateDeclarations(artifact, cssOutputs) {
-    for (const [file, css] of cssOutputs) {
-        const lines = css.split("\n");
-        const selectorStack = [];
-        const atRuleStack = [];
-        for (let i = 0; i < lines.length; i++) {
-            const line = lines[i];
-            const trimmed = line.trim();
-            // Track selector entries: line ending with `{`
-            if (trimmed.endsWith("{")) {
-                const selector = trimmed.slice(0, -1).trim();
-                if (selector.startsWith("@")) {
-                    // at-rule — parse name and prelude, keep current selector
-                    const atMatch = selector.match(/^@(\w+)\s*(.*)/);
-                    const atRule = atMatch
-                        ? { name: atMatch[1], prelude: atMatch[2] }
-                        : { name: selector.slice(1), prelude: "" };
-                    const parentAtRules = atRuleStack[atRuleStack.length - 1] ?? [];
-                    atRuleStack.push([...parentAtRules, atRule]);
-                    selectorStack.push(selectorStack[selectorStack.length - 1] ?? ":root");
-                }
-                else {
-                    atRuleStack.push(atRuleStack[atRuleStack.length - 1] ?? []);
-                    selectorStack.push(selector);
-                }
-                continue;
-            }
-            // Track block exits
-            if (trimmed === "}") {
-                selectorStack.pop();
-                atRuleStack.pop();
-                continue;
-            }
-            // Match custom property declarations
-            const m = trimmed.match(/^(--[\w-]+)\s*:/);
-            if (!m)
-                continue;
-            const cssVar = m[1];
-            const entry = artifact[cssVar];
-            if (!entry)
-                continue;
-            const selector = selectorStack[selectorStack.length - 1] ?? ":root";
-            const currentAtRules = atRuleStack[atRuleStack.length - 1] ?? [];
-            const decl = {
-                selector,
-                file,
-                line: i,
-                ...(currentAtRules.length > 0 ? { atRules: currentAtRules } : {}),
-            };
-            if (entry.declarations) {
-                entry.declarations.push(decl);
-            }
-            else {
-                entry.declarations = [decl];
-            }
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// Description lookup helper
-// ---------------------------------------------------------------------------
-/**
- * Build a map from channel CSS variable to description.
- *
- * Converts token IDs (e.g. `color.foreground.primary`) into their
- * channel CSS var form (e.g. `--modifier-color-foreground-primary`)
- * and maps each to its description.
- */
-function buildDescriptionLookup(descriptions, prefix) {
-    const lookup = {};
-    for (const [tokenId, desc] of Object.entries(descriptions)) {
-        const channelVar = prefixVar(tokenIdToCssVar(tokenId), prefix);
-        lookup[channelVar] = desc;
-    }
-    return lookup;
-}
-// ---------------------------------------------------------------------------
-// Primitive reference recovery
-// ---------------------------------------------------------------------------
-/**
- * Replace a resolved literal value with a `var()` reference to the matching
- * primitive token when one exists.
- *
- * Terrazzo resolves component-level `$ref` aliases to literal values during
- * `transformCSSValue`. This restores the semantic → primitive relationship
- * so the CSS output and artifact both reference the primitive custom property
- * instead of duplicating the raw value.
- *
- * Values that are already `var()` references (whole-token aliases preserved
- * by Terrazzo) are returned unchanged. Self-references are also skipped.
- */
-function recoverPrimitiveRef(value, selfCssVar, primitiveByValue) {
-    // Already a var() reference — nothing to recover
-    if (value.startsWith("var("))
-        return value;
-    const primitiveVar = primitiveByValue.get(value);
-    if (primitiveVar && primitiveVar !== selfCssVar) {
-        return `var(${primitiveVar})`;
-    }
-    return value;
-}
+export { default } from "./plugin/index.js";
 //# sourceMappingURL=plugin.js.map