forgebook 0.3.2 → 0.4.0

package/dist/src/vite/cssImports.js

@@ -0,0 +1,48 @@
+/**
+ * A style sheet with the sheets it imports by relative path written into it, as Vite's own PostCSS step does before a
+ * project's plugins run: Lightning CSS reads an imported file from the disk, so a plugin would never see it, and Tailwind's
+ * directives in a sheet of their own would stay undone.
+ *
+ * @remarks
+ * Only a plain `@import "./x.css"` is written in. One with a media query, a layer or a package's name stays for those that
+ * read them (Tailwind 4's plugin reads its own imports). Relative addresses in a file from another folder are rewritten,
+ * since they now sit in the importing sheet. A sheet that imports itself, or that cannot be read, stays as it was written.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+/** A plain relative import of a style sheet, on a line of its own. */
+const RELATIVE_IMPORT = /^[ \t]*@import\s+(?:url\()?["'](\.{1,2}\/[^"'\n]+\.(?:css|pcss|postcss))["']\)?\s*;[ \t]*$/gm;
+/** A relative address in a sheet. */
+const RELATIVE_URL = /url\(\s*(["']?)(?!["']?(?:[a-z][a-z0-9+.-]*:|\/|#))([^"')\s]+)\1\s*\)/gi;
+/** A sheet's text with its addresses read from another folder. */
+const rebased = (css, from, to) => {
+    const prefix = relative(to, from).split("\\").join("/");
+    return prefix === ""
+        ? css
+        : css.replace(RELATIVE_URL, (_, quote, url) => `url(${quote}${prefix}/${url}${quote})`);
+};
+/**
+ * A sheet with its relative imports written in.
+ *
+ * @param css - its text.
+ * @param file - its file, absolute.
+ */
+export const inlineCssImports = (css, file) => {
+    const files = [];
+    const inlined = (text, current, seen) => text.replace(RELATIVE_IMPORT, (statement, path) => {
+        const imported = resolve(dirname(current), path);
+        if (seen.has(imported))
+            return statement;
+        try {
+            const body = readFileSync(imported, "utf8");
+            files.push(imported);
+            return inlined(rebased(body, dirname(imported), dirname(file)), imported, new Set([...seen, imported]));
+        }
+        catch {
+            return statement;
+        }
+    });
+    return { css: inlined(css, file, new Set([file])), files };
+};

package/dist/src/vite/cssReferences.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Custom properties a browser gives no value: those whose references lead back to themselves, and those that read a
+ * name with no fallback that nothing declares.
+ *
+ * @remarks
+ * Pure. Resolving a token keeps the text of a reference it cannot follow (`cssTokenValues.ts`), since a browser may fill
+ * it in later; that is right for a name code sets and wrong for a name nobody sets, which leaves the UI drawn with no
+ * colour at all. A cycle is certain: the browser treats every property in it as invalid. A name declared nowhere is only
+ * as certain as the caller's knowledge of what declares names, so the caller says which names are declared elsewhere.
+ * References are followed within a theme, as the browser does.
+ *
+ * @module
+ */
+import { type TokenDeclaration } from "./cssTokenValues.ts";
+/** A `var()` in a value. */
+export type CssReference = {
+    /** The name it reads. */
+    readonly name: string;
+    /** Whether it has a fallback, which stands when the name has no value. */
+    readonly hasFallback: boolean;
+    /** Whether it sits inside another reference's fallback, so it is read only when that one has no value. */
+    readonly isInFallback: boolean;
+};
+/** Why a declaration has no value. */
+export type BrokenReference = {
+    /** The declaration. */
+    readonly declaration: TokenDeclaration;
+    /** The theme where it breaks; none when it breaks in the base, and so wherever no theme fixes it. */
+    readonly mode: string | undefined;
+} & ({
+    /** Its references lead back to it. */
+    readonly kind: "cycle";
+    /** The other names in the cycle, in the order declared; none when it reads itself. */
+    readonly through: readonly string[];
+} | {
+    /** It reads, with no fallback, a name nothing declares. */
+    readonly kind: "undeclared";
+    /** That name. */
+    readonly target: string;
+});
+/**
+ * The references a value holds, in order, with where each stands.
+ *
+ * @param value - a custom property's value, as written.
+ */
+export declare const references: (value: string) => CssReference[];
+/**
+ * The declarations a browser gives no value, in the base and in each theme, each declaration and reason once.
+ *
+ * @param declarations - every declaration, the lowest priority first, as tokens are resolved from them.
+ * @param isDeclaredElsewhere - whether a name these do not declare gets a value from elsewhere: another rule of a sheet,
+ *   an installed package's sheet, code that sets it.
+ */
+export declare const brokenReferences: (declarations: readonly TokenDeclaration[], isDeclaredElsewhere: (name: string) => boolean) => BrokenReference[];

package/dist/src/vite/cssReferences.js

@@ -0,0 +1,157 @@
+/**
+ * Custom properties a browser gives no value: those whose references lead back to themselves, and those that read a
+ * name with no fallback that nothing declares.
+ *
+ * @remarks
+ * Pure. Resolving a token keeps the text of a reference it cannot follow (`cssTokenValues.ts`), since a browser may fill
+ * it in later; that is right for a name code sets and wrong for a name nobody sets, which leaves the UI drawn with no
+ * colour at all. A cycle is certain: the browser treats every property in it as invalid. A name declared nowhere is only
+ * as certain as the caller's knowledge of what declares names, so the caller says which names are declared elsewhere.
+ * References are followed within a theme, as the browser does.
+ *
+ * @module
+ */
+import { layerOf } from "./cssTokenValues.js";
+/** A reference's start, a parenthesis or a comma: what tells a fallback from the rest of a value. */
+const REFERENCE_PARTS = /var\(\s*(--[\w-]+)\s*(,?)|[(),]/g;
+/**
+ * The references a value holds, in order, with where each stands.
+ *
+ * @param value - a custom property's value, as written.
+ */
+export const references = (value) => {
+    const found = [];
+    // each open reference: the depth of its parentheses, and whether its fallback has begun
+    const open = [];
+    let depth = 0;
+    for (const [part, name, comma] of value.matchAll(REFERENCE_PARTS)) {
+        const innermost = open.at(-1);
+        if (name !== undefined) {
+            const hasFallback = comma === ",";
+            found.push({ name, hasFallback, isInFallback: open.some((each) => each.isInFallback) });
+            depth += 1;
+            open.push({ depth, isInFallback: hasFallback });
+        }
+        else if (part === "(")
+            depth += 1;
+        else if (part === "," && innermost?.depth === depth)
+            innermost.isInFallback = true;
+        else if (part === ")") {
+            if (innermost?.depth === depth)
+                open.pop();
+            depth -= 1;
+        }
+    }
+    return found;
+};
+/** A name reached for the first time. */
+const enter = (walk, name) => {
+    const index = walk.order.size;
+    walk.order.set(name, index);
+    walk.lowest.set(name, index);
+    walk.stack.push(name);
+    walk.onStack.add(name);
+};
+/** What a name reaches, lowered. */
+const lower = (walk, name, reached) => {
+    walk.lowest.set(name, Math.min(walk.lowest.get(name) ?? reached, reached));
+};
+/** A name whose references are all walked: when it is the first of its group, the group comes off the path. */
+const close = (walk, name, readsItself) => {
+    if (walk.lowest.get(name) !== walk.order.get(name))
+        return;
+    const group = [];
+    for (let each = walk.stack.pop(); each !== undefined; each = walk.stack.pop()) {
+        walk.onStack.delete(each);
+        group.push(each);
+        if (each === name)
+            break;
+    }
+    if (group.length > 1 || readsItself)
+        walk.groups.push(group);
+};
+/** Walks from one name, with a path of its own, since a long chain of references would run past the call stack. */
+const walkFrom = (walk, edges, start) => {
+    const path = [{ name: start, next: 0 }];
+    enter(walk, start);
+    for (let top = path.at(-1); top !== undefined; top = path.at(-1)) {
+        const targets = edges.get(top.name) ?? [];
+        const target = targets[top.next];
+        top.next += 1;
+        if (target === undefined) {
+            path.pop();
+            const parent = path.at(-1);
+            if (parent !== undefined)
+                lower(walk, parent.name, walk.lowest.get(top.name) ?? 0);
+            close(walk, top.name, targets.includes(top.name));
+        }
+        else if (edges.has(target) && !walk.order.has(target)) {
+            enter(walk, target);
+            path.push({ name: target, next: 0 });
+        }
+        else if (walk.onStack.has(target))
+            lower(walk, top.name, walk.order.get(target) ?? 0);
+    }
+};
+/** The groups of names whose references lead back to each other, a name that reads itself included. */
+const cycles = (edges) => {
+    const walk = { order: new Map(), lowest: new Map(), stack: [], onStack: new Set(), groups: [] };
+    for (const start of edges.keys())
+        if (!walk.order.has(start))
+            walkFrom(walk, edges, start);
+    return walk.groups;
+};
+/**
+ * Whether a reference names the variable of the same name set elsewhere rather than the declaration itself: Tailwind's
+ * `@theme inline { --font-sans: var(--font-sans); }` is how a theme takes a font a framework sets on the page, and
+ * utilities read the outer variable. Anywhere else a declaration that reads itself is a cycle.
+ */
+const namesElsewhere = (declaration, ref) => declaration.origin.kind === "tailwind-theme" && ref.name === declaration.name;
+/** What is broken in one theme's declarations. */
+const brokenIn = (layer, isDeclaredElsewhere) => {
+    const edges = new Map([...layer].map(([name, each]) => [
+        name,
+        references(each.value).flatMap((ref) => (namesElsewhere(each, ref) ? [] : [ref.name]))
+    ]));
+    const broken = [];
+    const position = new Map([...layer.keys()].map((name, index) => [name, index]));
+    const groupOf = new Map();
+    for (const group of cycles(edges)) {
+        const ordered = group.toSorted((first, second) => (position.get(first) ?? 0) - (position.get(second) ?? 0));
+        for (const name of group)
+            groupOf.set(name, ordered);
+    }
+    for (const [name, declaration] of layer) {
+        const group = groupOf.get(name);
+        if (group === undefined)
+            continue;
+        const through = [...group].filter((each) => each !== name);
+        broken.push({ declaration, kind: "cycle", through });
+    }
+    for (const declaration of layer.values()) {
+        const missing = references(declaration.value).find((ref) => !ref.hasFallback &&
+            !ref.isInFallback &&
+            (namesElsewhere(declaration, ref) || !layer.has(ref.name)) &&
+            !isDeclaredElsewhere(ref.name));
+        if (missing !== undefined)
+            broken.push({ declaration, kind: "undeclared", target: missing.name });
+    }
+    return broken;
+};
+/**
+ * The declarations a browser gives no value, in the base and in each theme, each declaration and reason once.
+ *
+ * @param declarations - every declaration, the lowest priority first, as tokens are resolved from them.
+ * @param isDeclaredElsewhere - whether a name these do not declare gets a value from elsewhere: another rule of a sheet,
+ *   an installed package's sheet, code that sets it.
+ */
+export const brokenReferences = (declarations, isDeclaredElsewhere) => {
+    const modes = [...new Set(declarations.flatMap((each) => (each.mode === undefined ? [] : [each.mode])))];
+    const seen = new Set();
+    return [undefined, ...modes].flatMap((mode) => brokenIn(layerOf(declarations, mode), isDeclaredElsewhere).flatMap((broken) => {
+        if (seen.has(broken.declaration))
+            return [];
+        seen.add(broken.declaration);
+        return [{ ...broken, mode }];
+    }));
+};

package/dist/src/vite/cssTokenValues.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What custom properties come to: the tokens a set of declarations makes, each with its value in every theme.
+ *
+ * @remarks
+ * Pure. A value in a real project is rarely a value: it is `var(--primary)`, `calc(var(--radius) - 2px)`, bare channels
+ * that a Tailwind configuration wraps in `hsl()`. These are followed here so that a token compares with what code writes
+ * by hand. References are followed within a theme, as the browser does, so a base alias changes with what a theme
+ * overrides. What cannot be worked out without a browser (a font a framework injects, `color-mix()`) keeps its text, and
+ * `nearestToken.ts` counts it as not compared rather than guessing.
+ *
+ * @module
+ */
+import type { DesignToken, TokenOrigin } from "./designTokens.ts";
+/** A declaration, from a sheet or a configuration, ready to resolve. */
+export type TokenDeclaration = {
+    /** Its name, with its dashes. */
+    readonly name: string;
+    /** Its value, as written. */
+    readonly value: string;
+    /** The theme it belongs to; none for the base. */
+    readonly mode: string | undefined;
+    /** Where it was read. */
+    readonly origin: TokenOrigin;
+    /** What it means, when the place that declares it says (a Tailwind configuration's `colors`). */
+    readonly type?: string;
+    /** It stands on a selector and not the document: what the document declares of that name stands over it. */
+    readonly isScoped?: boolean;
+};
+/**
+ * Which references are wrapped in a colour function, from any text that uses them: how bare channels are told from three
+ * plain numbers.
+ *
+ * @param texts - sheets and configurations.
+ */
+export declare const colorWrappers: (texts: readonly string[]) => ReadonlyMap<string, "hsl" | "rgb">;
+/**
+ * The declarations in force in a theme: its own over the base.
+ *
+ * @param declarations - every declaration, the lowest priority first.
+ * @param mode - the theme; none for the base.
+ */
+export declare const layerOf: (declarations: readonly TokenDeclaration[], mode: string | undefined) => ReadonlyMap<string, TokenDeclaration>;
+/**
+ * The tokens declarations make, in the order given. Where one name is declared twice in one theme the later stands, as
+ * in a browser's cascade.
+ *
+ * @param declarations - every declaration, the lowest priority first.
+ * @param wrappers - which references are wrapped in a colour function.
+ */
+export declare const resolvedTokens: (declarations: readonly TokenDeclaration[], wrappers: ReadonlyMap<string, "hsl" | "rgb">) => DesignToken[];

package/dist/src/vite/cssTokenValues.js

@@ -0,0 +1,233 @@
+/** The kinds of Tailwind's namespaces, which name a token's use whatever its value looks like. */
+const NAMESPACE_TYPES = [
+    [/^--breakpoint-/, "breakpoint"],
+    [/^--container-/, "container"],
+    [/--line-height$|^--leading-/, "number"],
+    [/--letter-spacing$|^--tracking-/, "tracking"],
+    [/--font-weight$|^--font-weight-/, "fontWeight"],
+    [/--font-feature-settings$|--font-variation-settings$/, "fontFeature"],
+    [/^--font-size/, "dimension"],
+    [/^--font-/, "fontFamily"],
+    [/^--color-/, "color"],
+    [/^--(?:inset-)?(?:drop-|text-)?shadow-/, "shadow"],
+    [/^--ease-/, "cubicBezier"],
+    [/^--animate-/, "animation"],
+    [/^--blur-|^--perspective-|^--aspect-/, "other"]
+];
+/** A value that is a colour by its form. */
+const COLOR_VALUE = /^(?:#[0-9a-f]{3,8}|(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color|color-mix|light-dark)\(.*\)|transparent|white|black)$/i;
+/** A value that is a size by its form, `calc()` included. */
+const SIZE_VALUE = /^(?:-?(?:\d+\.?\d*|\.\d+)(?:px|rem|em|vh|vw|ch)|calc\(.*\))$/i;
+/** A value that is a time by its form. */
+const TIME_VALUE = /^(?:\d+\.?\d*|\.\d+)m?s$/i;
+/** A value that is a plain number. */
+const NUMBER_VALUE = /^-?(?:\d+\.?\d*|\.\d+)$/;
+/** Hue, saturation and lightness with no function, which Tailwind's older configurations wrap in one. */
+const BARE_HSL = /^-?\d*\.?\d+(?:deg)?[\s,]+\d*\.?\d+%[\s,]+\d*\.?\d+%$/;
+/** Three numbers with no function, which a sheet or a configuration wraps in `rgb()`. */
+const BARE_RGB = /^\d+\.?\d*[\s,]+\d+\.?\d*[\s,]+\d+\.?\d*$/;
+/** A `var()`, with its fallback. */
+const VAR_CALL = /^var\(\s*(--[\w-]+)\s*(?:,\s*(.*))?\)$/s;
+/** The first `var()` in a longer value, its fallback holding one level of parentheses. */
+const VAR_INSIDE = /var\(\s*(--[\w-]+)\s*(?:,\s*([^()]*(?:\([^()]*\)[^()]*)*))?\)/;
+/** A colour function around a reference: what tells bare channels from any three numbers. */
+const COLOR_WRAPPER = /\b(hsla?|rgba?)\(\s*var\(\s*(--[\w-]+)/g;
+/** The placeholder Tailwind's older configurations write for an opacity. */
+const ALPHA_PLACEHOLDER = /\s*(?:\/|,)\s*<alpha-value>/;
+/** A function around a colour function, as `hsl(oklch(…))`, when a wrapper meets a whole colour. */
+const WRAPPED_COLOR = /^(?:hsla?|rgba?)\(\s*((?:rgba?|hsla?|oklab|oklch|lab|lch|hwb|color)\([^()]*\)|#[0-9a-f]{3,8})\s*(?:\/\s*([^()/]+))?\)$/i;
+/**
+ * Which references are wrapped in a colour function, from any text that uses them: how bare channels are told from three
+ * plain numbers.
+ *
+ * @param texts - sheets and configurations.
+ */
+export const colorWrappers = (texts) => {
+    const wrappers = new Map();
+    for (const text of texts) {
+        for (const match of text.matchAll(COLOR_WRAPPER)) {
+            const [, wrapper = "", name = ""] = match;
+            wrappers.set(name, wrapper.toLowerCase().startsWith("hsl") ? "hsl" : "rgb");
+        }
+    }
+    return wrappers;
+};
+/** How many names one value may lead through; past it the stack is at risk, and no system chains this far. */
+const MOST_REFERENCES = 512;
+/** Past this a value is references gone wrong and not a token, in characters. */
+const LONGEST_VALUE = 2000;
+/** Stands for `var` in a reference that cannot be followed, until the following is over. */
+const UNFOLLOWED = "\u0000";
+/** A number with no noise from the arithmetic. */
+const tidy = (value) => String(Math.round(value * 10000) / 10000);
+/** The value of a size in pixels, a rem being 16; none when it has no such unit. */
+const sizeInPixels = (text) => {
+    const match = /^(-?(?:\d+\.?\d*|\.\d+))(px|rem)$/.exec(text.trim());
+    if (match === null)
+        return undefined;
+    return Number(match[1]) * (match[2] === "rem" ? 16 : 1);
+};
+/** A plain number; none when it has a unit. */
+const plainNumber = (text) => NUMBER_VALUE.test(text.trim()) ? Number(text) : undefined;
+/**
+ * `calc()` of known sizes, as sheets write it over a base radius or spacing; none for anything more.
+ *
+ * @param inner - what is inside the parentheses, its references already followed.
+ */
+const calculated = (inner) => {
+    const product = /^(\S+)\s*\*\s*(\S+)$/.exec(inner.trim());
+    if (product !== null) {
+        const [first = "", second = ""] = [product[1], product[2]];
+        const size = sizeInPixels(first) ?? sizeInPixels(second);
+        const factor = plainNumber(first) ?? plainNumber(second);
+        return size === undefined || factor === undefined ? undefined : `${tidy(size * factor)}px`;
+    }
+    const sum = /^(\S+)\s*([+-])\s*(\S+)$/.exec(inner.trim());
+    if (sum === null)
+        return undefined;
+    const [first, second] = [sizeInPixels(sum[1] ?? ""), sizeInPixels(sum[3] ?? "")];
+    if (first === undefined || second === undefined)
+        return undefined;
+    return `${tidy(sum[2] === "+" ? first + second : first - second)}px`;
+};
+/** A value made plain: its own form, once its references are in. */
+const plainValue = (value, wrapper) => {
+    const text = value.replace(ALPHA_PLACEHOLDER, "").trim();
+    const [, wrapped, alpha] = WRAPPED_COLOR.exec(text) ?? [];
+    if (wrapped !== undefined) {
+        // a hex has no room for an opacity written apart, and the colour is what a token compares by
+        return alpha === undefined || !wrapped.endsWith(")")
+            ? wrapped
+            : `${wrapped.slice(0, -1)} / ${alpha.trim()})`;
+    }
+    if (BARE_HSL.test(text))
+        return `hsl(${text})`;
+    if (wrapper === "rgb" && BARE_RGB.test(text))
+        return `rgb(${text})`;
+    const inner = /^calc\((.*)\)$/s.exec(text)?.[1];
+    const sum = inner === undefined ? undefined : calculated(inner);
+    return sum ?? text;
+};
+/**
+ * The declarations in force in a theme: its own over the base.
+ *
+ * @param declarations - every declaration, the lowest priority first.
+ * @param mode - the theme; none for the base.
+ */
+export const layerOf = (declarations, mode) => {
+    const layer = new Map();
+    for (const each of declarations)
+        if (each.mode === undefined)
+            layer.set(each.name, each);
+    if (mode !== undefined)
+        for (const each of declarations)
+            if (each.mode === mode)
+                layer.set(each.name, each);
+    return layer;
+};
+/**
+ * A declaration's value with every reference it can follow followed; one it cannot keeps its mark all the way out, or the
+ * caller would meet it as a new reference. Each name is worked out once: references that lead back in a web of tokens
+ * would otherwise take exponentially long, and a browser treats those as invalid anyway.
+ */
+const followedText = (name, layer, wrappers, known) => {
+    if (known.has(name) || known.size > MOST_REFERENCES)
+        return known.get(name);
+    const declaration = layer.get(name);
+    // while it is being worked out, a reference to it leads back
+    known.set(name, undefined);
+    if (declaration === undefined)
+        return undefined;
+    let text = declaration.value;
+    for (let match = VAR_INSIDE.exec(text); match !== null; match = VAR_INSIDE.exec(text)) {
+        const [whole, target = "", fallback] = match;
+        const value = followedText(target, layer, wrappers, known) ?? fallback?.trim();
+        // left as written, marked so this loop passes over it: what a browser fills in later is not known here
+        text = text.replace(whole, () => value ?? `${UNFOLLOWED}(${target})`);
+        if (text.length > LONGEST_VALUE)
+            break;
+    }
+    // references that each hold two more double at every step: such a value is nothing anyone can compare
+    const followed = text.length > LONGEST_VALUE ? undefined : plainValue(text, wrappers.get(name));
+    known.set(name, followed);
+    return followed;
+};
+/** What a declaration comes to, what could not be followed written as the sheet wrote it. */
+const resolvedText = (name, layer, wrappers) => followedText(name, layer, wrappers, new Map())?.replaceAll(UNFOLLOWED, "var");
+/** What a token is, by its namespace, by what declared it, then by the form of its value. */
+const typeOf = (declaration, value) => {
+    if (declaration.type !== undefined)
+        return declaration.type;
+    const named = NAMESPACE_TYPES.find(([pattern]) => pattern.test(declaration.name))?.[1];
+    if (named !== undefined)
+        return named;
+    // Tailwind's `--text-*` are font sizes, and `--text-*` elsewhere may be a text's colour
+    if (COLOR_VALUE.test(value))
+        return "color";
+    if (SIZE_VALUE.test(value))
+        return "dimension";
+    if (TIME_VALUE.test(value))
+        return "duration";
+    if (NUMBER_VALUE.test(value))
+        return /weight/i.test(declaration.name) ? "fontWeight" : "number";
+    if (/font|family|typeface/i.test(declaration.name))
+        return "fontFamily";
+    if (/shadow/i.test(declaration.name))
+        return "shadow";
+    if (/^cubic-bezier\(/.test(value))
+        return "cubicBezier";
+    return "other";
+};
+/** The token a value aliases, when it is nothing else. */
+const aliasOf = (value) => VAR_CALL.exec(value.trim())?.[1];
+/** How code writes a token through Tailwind: the end of a class, for what makes utilities. */
+const utilityOf = (name, origin) => {
+    if (origin.kind === "css-variables")
+        return undefined;
+    const match = /^--(?:color|spacing|radius|text|shadow)-(.+)$/.exec(name);
+    return match === null || name.includes("--", 2) ? undefined : match[1];
+};
+/**
+ * The tokens declarations make, in the order given. Where one name is declared twice in one theme the later stands, as
+ * in a browser's cascade.
+ *
+ * @param declarations - every declaration, the lowest priority first.
+ * @param wrappers - which references are wrapped in a colour function.
+ */
+export const resolvedTokens = (declarations, wrappers) => {
+    const base = layerOf(declarations, undefined);
+    const modes = [...new Set(declarations.flatMap((each) => (each.mode === undefined ? [] : [each.mode])))];
+    const layers = new Map(modes.map((mode) => [mode, layerOf(declarations, mode)]));
+    const names = new Set(declarations.map((each) => each.name));
+    return [...names].flatMap((name) => {
+        const inBase = base.get(name);
+        const themed = modes.flatMap((mode) => {
+            const layer = layers.get(mode);
+            const text = layer === undefined ? undefined : resolvedText(name, layer, wrappers);
+            if (text === undefined)
+                return [];
+            return [{ mode, text, declared: declarations.some((d) => d.mode === mode && d.name === name) }];
+        });
+        const baseText = resolvedText(name, base, wrappers);
+        const value = baseText ?? themed[0]?.text;
+        const declaration = inBase ?? declarations.find((each) => each.name === name);
+        if (value === undefined || declaration === undefined)
+            return [];
+        const utility = utilityOf(name, declaration.origin);
+        const alias = aliasOf(declaration.value);
+        return [
+            {
+                name,
+                type: typeOf(declaration, value),
+                value,
+                ...(alias === undefined ? {} : { alias }),
+                modes: Object.fromEntries(themed
+                    .filter((each) => each.declared || each.text !== baseText)
+                    .map((each) => [each.mode, each.text])),
+                ...(inBase === undefined ? { isThemeOnly: true } : {}),
+                origin: declaration.origin,
+                ...(utility === undefined ? {} : { utility })
+            }
+        ];
+    });
+};

package/dist/src/vite/designTokens.d.ts

@@ -37,6 +37,30 @@ export type DesignToken = {
     readonly isThemeOnly?: true;
     /** The source that gives it, by its id or, when it writes none, by its module; none for the catalogue's own. */
     readonly source?: string;
+    /** Where the application itself declares it, for a token read from its style sheets or its Tailwind configuration. */
+    readonly origin?: TokenOrigin;
+    /** The end of a Tailwind class that writes it (`primary` for `bg-primary`), when it makes utilities. */
+    readonly utility?: string;
+};
+/** What one file gave a catalogue's tokens. */
+export type TokenSource = {
+    /** What kind of file: a tokens file the catalogue names, or what an application already has. */
+    readonly kind: "tokens-file" | "components-json" | TokenOriginKind;
+    /** The file, relative to the catalogue. */
+    readonly file: string;
+    /** How many tokens it gives; none for a tokens file, whose names later files may replace. */
+    readonly tokens?: number;
+};
+/** What a token read from an application was read from. */
+export type TokenOriginKind = "css-variables" | "tailwind-theme" | "tailwind-config" | "tailwind-default";
+/** Where an application declares a token. */
+export type TokenOrigin = {
+    /** What kind of source. */
+    readonly kind: TokenOriginKind;
+    /** Its file, relative to the catalogue. */
+    readonly file: string;
+    /** The line, from 1. */
+    readonly line?: number;
 };
 /** What the files gave. */
 export type ParsedTokens = {

package/dist/src/vite/designTokens.js

@@ -275,7 +275,11 @@ const resolvedValue = (raw, byName) => {
         return `${raw.name}: it says ${raw.ownType}, its alias is ${targetType}`;
     }
     try {
-        return { text: valueText(followed(raw.value, byName, new Set([raw.name])), type), type };
+        const text = valueText(followed(raw.value, byName, new Set([raw.name])), type);
+        // an empty value draws nothing, and a browser drops it in silence
+        if (text.trim() === "")
+            return `${raw.name}: its value comes to nothing, so a browser gives it none`;
+        return { text, type };
     }
     catch (error) {
         return `${raw.name}: ${error instanceof Error ? error.message : String(error)}`;

package/dist/src/vite/docsExtractor.d.ts

@@ -26,6 +26,11 @@ export type DocsRequest = {
 } | {
     /** A source file changed: the programs are renewed on their next read. */
     readonly kind: "changed";
+} | {
+    /** A build's story files: each program holds what they reach rather than its whole configuration. */
+    readonly kind: "stories";
+    /** The story files, absolute. */
+    readonly files: readonly string[];
 };
 /** The worker's answer to a request, of the request's kind. */
 export type DocsResponse = {
@@ -57,10 +62,11 @@ export type DocsExtractor = {
     /** What a group of story files' stories render, and the import graph they reach. */
     readonly usage: (files: readonly UsageRequestFile[]) => Promise<UsageResult>;
     /**
-     * Builds the program that holds a story file ahead of its first read, while the worker has nothing else to do, when
-     * the disk keeps no docs: a first start, or a build, starts the worker while Vite still loads the pages.
+     * Builds the program that holds a group's first story file ahead of its first read, while the worker has nothing else
+     * to do, when the disk keeps no docs: a first start, or a build, starts the worker while Vite still loads the pages.
+     * A build's worker is told every file of the group first, so its programs hold what the stories reach.
      */
-    readonly warm: (storyFile: string) => void;
+    readonly warm: (storyFiles: readonly string[]) => void;
     /** Tells the worker a source file changed, so the next read sees it. */
     readonly changed: () => void;
     /**

package/dist/src/vite/docsExtractor.js

@@ -199,7 +199,7 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
     };
     // a request's answer, or why the worker stopped before giving it
     const send = (request, resolve) => {
-        if (request.kind === "changed")
+        if (request.kind === "changed" || request.kind === "stories")
             return;
         pending.set(request.id, resolve);
         started().postMessage(request);
@@ -257,12 +257,20 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
             const request = { kind: "changed" };
             worker?.postMessage(request);
         },
-        warm: (storyFile) => {
+        warm: (storyFiles) => {
+            if (readsEverything && storyFiles.length > 0) {
+                // before any read of them, so no program is built whole first
+                const request = { kind: "stories", files: storyFiles };
+                started().postMessage(request);
+            }
             // only a first start, which the disk can answer nothing for: a later one reads each page's docs from the disk
             // and builds a program only for one it misses, so it stays without one until then
             if (isKeptRead && docsCache !== undefined && !docsCache.isEmpty())
                 return;
-            warmUps.push(storyFile);
+            const [first] = storyFiles;
+            if (first === undefined)
+                return;
+            warmUps.push(first);
             sendWarmUp();
         },
         listed: () => {