tokens-to-css 1.0.0

package/dist/index.js

@@ -0,0 +1,1366 @@
+import { mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { request } from "node:http";
+import { request as request$1 } from "node:https";
+import { lookup } from "node:dns";
+import { BlockList, isIP, isIPv4 } from "node:net";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+//#region src/model/index.ts
+/** Builds a literal value. */
+function literal(value) {
+	return {
+		kind: "literal",
+		value
+	};
+}
+/** Builds a reference to another token. */
+function ref(path) {
+	return {
+		kind: "ref",
+		path
+	};
+}
+/** Builds a token node. */
+function token(path, value) {
+	return {
+		path,
+		value
+	};
+}
+/** Narrows a value to a reference. */
+function isRef(value) {
+	return value.kind === "ref";
+}
+/**
+* Renders a path the way the token document wrote it, for humans.
+*
+* This is how a token is named in an error message — it is *not* the custom
+* property name, which follows the naming rule and lives in the emitter.
+*/
+function formatPath(path) {
+	return path.join(".");
+}
+//#endregion
+//#region src/errors.ts
+/**
+* The failure contract — public surface, frozen by semver (AD-4).
+*
+* Every failure in this library is a `TokenCssError` carrying one of the codes
+* below. Callers branch on `code`; they never match on message text, so message
+* wording stays free to improve. Renaming or merging a code is a major version.
+*/
+/**
+* The complete set of ways a conversion can fail.
+*
+* One code per failure class in the PRD. Adding a code is a minor version;
+* renaming, merging, or removing one is a major version.
+*/
+const FailureCode = Object.freeze({
+	/** The path or URL could not be read: missing, denied, unreachable, timed out, oversized, or refused by network policy. */
+	SOURCE_UNREADABLE: "SOURCE_UNREADABLE",
+	/** The source was read but its content is not valid JSON. */
+	SOURCE_INVALID_JSON: "SOURCE_INVALID_JSON",
+	/** The document is not a shape this version accepts. */
+	FORMAT_NOT_ALLOWED: "FORMAT_NOT_ALLOWED",
+	/** Aliases reference each other in a loop. */
+	ALIAS_CYCLE: "ALIAS_CYCLE",
+	/** An alias points at a token that does not exist. */
+	ALIAS_DANGLING: "ALIAS_DANGLING",
+	/** A value is an object, array, boolean, or null rather than a scalar. */
+	COMPOSITE_VALUE: "COMPOSITE_VALUE",
+	/** Two or more tokens would emit the same custom-property name. */
+	NAME_COLLISION: "NAME_COLLISION",
+	/** The stylesheet could not be written. */
+	OUTPUT_WRITE_FAILED: "OUTPUT_WRITE_FAILED"
+});
+/**
+* The only error this library throws.
+*
+* There are no subclasses: the `code` is what callers branch on, and one type
+* means a caller never has to ask which error shape it caught.
+*/
+var TokenCssError = class extends Error {
+	name = "TokenCssError";
+	/** The failure class. Stable across minor versions. */
+	code;
+	/** The Token Source being converted when this failed. */
+	source;
+	/** Offending token paths — empty for failures that are not token-scoped. */
+	tokenPaths;
+	constructor(message, init) {
+		super(message, init.cause === void 0 ? void 0 : { cause: init.cause });
+		this.code = init.code;
+		this.source = init.source;
+		this.tokenPaths = init.tokenPaths ?? [];
+	}
+};
+//#endregion
+//#region src/emit/literal.ts
+/**
+* Turning a token value into stylesheet text (AD-19).
+*
+* One rule, no options: write what the token said. A string goes out verbatim,
+* a number goes out as its plain decimal form. Nothing is inferred from a
+* `$type`, which is why the internal model does not carry one — the moment this
+* function could see that a token is a "dimension", someone would reasonably
+* append `px`, and two implementations would disagree about what `16` means.
+*/
+/** Whether a raw JSON value can be written into a stylesheet at all. */
+function isScalar(value) {
+	return typeof value === "string" || typeof value === "number" && Number.isFinite(value);
+}
+/** How a rejected value is described in the failure message. */
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	if (typeof value === "object") return "an object";
+	return `a ${typeof value}`;
+}
+/**
+* Accepts a raw value only if it is a scalar (FR-20).
+*
+* @throws {TokenCssError} `COMPOSITE_VALUE` for objects, arrays, booleans and
+* null. A composite has no single stylesheet value, and stringifying one
+* produces `[object Object]` under a successful-looking run.
+*/
+function assertScalar(value, path, source) {
+	if (isScalar(value)) return value;
+	throw new TokenCssError(`token "${formatPath(path)}" has ${describe(value)} as its value, but this version writes one custom property per scalar token`, {
+		code: FailureCode.COMPOSITE_VALUE,
+		source,
+		tokenPaths: [formatPath(path)]
+	});
+}
+/**
+* Renders a scalar as stylesheet text.
+*
+* Verbatim for strings — no quoting, no trimming, no escaping: a token that
+* says `1px solid red` means exactly that, and a token with a trailing space
+* keeps it, because the golden files are byte-exact and silently tidying the
+* input would make the output depend on this function's taste.
+*/
+function stringifyLiteral(value) {
+	return typeof value === "string" ? value : String(value);
+}
+//#endregion
+//#region src/emit/name.ts
+/**
+* The custom-property naming rule (FR-9, AD-11).
+*
+* **This is public contract.** The names produced here appear in the stylesheet
+* and in the stylesheets of everyone using it, so changing this function's
+* output is a major version — no exceptions, no options, no configurable prefix.
+*
+* The rule is deliberately lossy: anything outside `[a-z0-9]` collapses. Two
+* paths can therefore normalize to the same name, which is not this module's
+* problem to solve — the collision pass runs on the names this returns and
+* fails clearly rather than dropping a token (FR-21).
+*/
+/**
+* Normalizes one path segment.
+*
+* Unicode is normalized to NFC first, and that is not decoration. The same
+* word can arrive composed or decomposed depending on which tool wrote the
+* file — `é` as one code point, or `e` followed by a combining accent. Without
+* NFC those two produce different custom-property names from identical-looking
+* source, which would make the output depend on the editor rather than the
+* tokens.
+*/
+function normalizeSegment(segment) {
+	return segment.normalize("NFC").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+/**
+* Builds the custom-property name for a token path.
+*
+* `['color', 'brand', 'primary']` becomes `--color-brand-primary`.
+*
+* @param path Path segments from the document root.
+* @param source The Token Source, carried only so a failure can name it.
+* @throws {TokenCssError} `FORMAT_NOT_ALLOWED` when a segment has nothing left
+* after normalization. Dropping it would silently rename the token.
+*/
+function customPropertyName(path, source) {
+	const segments = path.map((segment) => {
+		const normalized = normalizeSegment(segment);
+		if (normalized === "") throw new TokenCssError(`token "${formatPath(path)}" has a path segment ("${segment}") with no letters or digits, so it cannot become part of a custom-property name`, {
+			code: FailureCode.FORMAT_NOT_ALLOWED,
+			source,
+			tokenPaths: [formatPath(path)]
+		});
+		return normalized;
+	});
+	if (segments.length === 0) throw new TokenCssError("a token has an empty path, so it cannot be named", {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source,
+		tokenPaths: [""]
+	});
+	return `--${segments.join("-")}`;
+}
+//#endregion
+//#region src/emit/css.ts
+/**
+* Writing the stylesheet (FR-9, FR-10, AD-10).
+*
+* The whole document becomes one string before anything reaches disk (AD-6), so
+* a failure late in emission cannot leave half a stylesheet behind.
+*
+* The exact bytes produced here are the contract the golden files hold. Two
+* runs over the same document must produce identical text, which is why nothing
+* in this module reads the clock, the filesystem, the environment, or the
+* order a runtime happens to iterate keys — declaration order is the order of
+* the array it was handed, and that is document order.
+*/
+/** Two spaces. Fixed: a configurable indent would make goldens negotiable. */
+const INDENT = "  ";
+/**
+* Renders a normalized document as a stylesheet.
+*
+* A token whose value points at another token is written as `var(--target)`,
+* never as the target's value. That is the whole point of the product: the
+* relationship the token file expressed survives into the CSS, so changing a
+* primitive still moves everything that referred to it.
+*
+* @param doc The normalized document, in document order.
+* @param source The Token Source, carried only so a naming failure can name it.
+* @returns The complete stylesheet text, ending in exactly one newline.
+*/
+function emitStylesheet(doc, source) {
+	return [
+		":root {",
+		...doc.tokens.map((node) => {
+			const property = customPropertyName(node.path, source);
+			const value = isRef(node.value) ? `var(${customPropertyName(node.value.path, source)})` : stringifyLiteral(node.value.value);
+			return `${INDENT}${property}: ${value};`;
+		}),
+		"}",
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/options.ts
+/** The defaults a conversion uses when the caller says nothing. */
+const DEFAULTS = Object.freeze({
+	outDir: "assets/css",
+	fileName: "tokens.css",
+	http: Object.freeze({
+		allowInsecure: false,
+		timeoutMs: 1e4,
+		maxBytes: 1e7,
+		maxRedirects: 3
+	})
+});
+//#endregion
+//#region src/dialects/values.ts
+/**
+* Object-form scalar values (FR-23).
+*
+* The current DTCG spec writes a colour and a dimension as objects rather than
+* strings:
+*
+*   { "colorSpace": "srgb", "components": [0, 0, 0], "alpha": 1, "hex": "#000" }
+*   { "value": 0.25, "unit": "rem" }
+*
+* Both still describe **one** CSS value. They are scalars written with more
+* ceremony, not composites, and refusing them meant refusing every design
+* system published against the current spec.
+*
+* Two properties of this module matter more than the conversion itself:
+*
+* **It reads the shape, never the `$type`.** `{colorSpace, components}` can only
+* be a colour; `{value, unit}` can only be a dimension. So nothing here infers
+* anything from a declared type, and the rule that a `16` never becomes `16px`
+* survives untouched.
+*
+* **It runs at normalization.** What reaches the internal representation is
+* still a plain string, so no stage downstream learns that object values exist.
+*/
+/** Units CSS understands. `dp` and friends belong to other platforms. */
+const CSS_UNITS = /* @__PURE__ */ new Set([
+	"px",
+	"rem",
+	"em",
+	"ex",
+	"ch",
+	"cap",
+	"ic",
+	"lh",
+	"rlh",
+	"%",
+	"vw",
+	"vh",
+	"vmin",
+	"vmax",
+	"svw",
+	"svh",
+	"lvw",
+	"lvh",
+	"dvw",
+	"dvh",
+	"cqw",
+	"cqh",
+	"cqi",
+	"cqb",
+	"cqmin",
+	"cqmax",
+	"cm",
+	"mm",
+	"q",
+	"in",
+	"pt",
+	"pc",
+	"deg",
+	"grad",
+	"rad",
+	"turn",
+	"s",
+	"ms",
+	"fr"
+]);
+const refuse$1 = (message, path, source) => {
+	throw new TokenCssError(message, {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source,
+		tokenPaths: [formatPath(path)]
+	});
+};
+/** `{ value, unit }` — a dimension or a duration. */
+function isDimension(raw) {
+	const keys = Object.keys(raw);
+	return keys.includes("value") && keys.every((key) => key === "value" || key === "unit");
+}
+function dimensionToCss(raw, path, source) {
+	const { value, unit } = raw;
+	if (typeof value !== "number" || !Number.isFinite(value)) refuse$1(`token "${formatPath(path)}" has a dimension whose value is not a number`, path, source);
+	if (typeof unit !== "string") refuse$1(`token "${formatPath(path)}" has a dimension whose unit is not text`, path, source);
+	if (unit === "") return String(value);
+	if (!CSS_UNITS.has(unit)) refuse$1(`token "${formatPath(path)}" is measured in "${unit}", which is not a CSS unit`, path, source);
+	return `${value}${unit}`;
+}
+/** `{ colorSpace, components, alpha?, hex? }`. */
+function isColor(raw) {
+	return "colorSpace" in raw && "components" in raw;
+}
+/**
+* Renders a colour.
+*
+* sRGB becomes `rgb()`, which every browser has understood for decades. The
+* components are 0–1 in the token and 0–255 in CSS, and across every published
+* design system checked while deciding this, that multiplication reproduces the
+* `hex` the file itself declares — exactly, in all 689 cases. So the familiar
+* notation costs nothing.
+*
+* Any other colour space becomes `color(space …)` with the numbers untouched,
+* because there is no lossless shorter form.
+*
+* `hex` is read and ignored, the way `$description` is. It is optional in the
+* spec, and a value that changed shape depending on whether an optional field
+* happened to be present would be worse than one that never uses it.
+*/
+function colorToCss(raw, path, source) {
+	const space = raw["colorSpace"];
+	const components = raw["components"];
+	const alpha = raw["alpha"];
+	if (typeof space !== "string" || space === "") refuse$1(`token "${formatPath(path)}" has a colour with no colour space`, path, source);
+	if (!Array.isArray(components) || components.length !== 3) refuse$1(`token "${formatPath(path)}" has a colour with ${Array.isArray(components) ? `${components.length} components` : "no components"}; three are expected`, path, source);
+	const rendered = components.map((component, index) => {
+		if (component === "none") return "none";
+		if (typeof component !== "number" || !Number.isFinite(component)) refuse$1(`token "${formatPath(path)}" has a colour whose component ${index + 1} is not a number`, path, source);
+		return component;
+	});
+	const suffix = typeof alpha === "number" && alpha !== 1 ? ` / ${alpha}` : alpha === "none" ? " / none" : "";
+	if (space === "srgb") return `rgb(${rendered.map((c) => c === "none" ? "none" : Math.round(c * 255)).join(" ")}${suffix})`;
+	return `color(${space} ${rendered.join(" ")}${suffix})`;
+}
+/**
+* Converts an object-form scalar into stylesheet text.
+*
+* @returns The CSS value, or `null` when the object is not a scalar in object
+* form — a typography or shadow block, which stays a composite and is refused
+* by the caller.
+* @throws {TokenCssError} `FORMAT_NOT_ALLOWED` when the object *is* one of these
+* shapes but is malformed or unusable in CSS.
+*/
+function objectValueToCss(raw, path, source) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+	const record = raw;
+	if (isColor(record)) return colorToCss(record, path, source);
+	if (isDimension(record)) return dimensionToCss(record, path, source);
+	return null;
+}
+//#endregion
+//#region src/dialects/walk.ts
+/**
+* The shared tree walk every dialect uses (AD-2, AD-9, AD-20).
+*
+* Dialects differ in one thing: which key marks a node as a token, and how to
+* read its value out. Everything else — recursion, prototype safety, reference
+* syntax, refusing to drop things silently — is identical, and lives here so
+* three dialects cannot disagree about it.
+*/
+/**
+* Keys that must never be walked into or copied.
+*
+* `JSON.parse` puts `__proto__` on the object as an ordinary own property
+* rather than invoking the setter, so it arrives here intact — which is exactly
+* why it has to be refused explicitly rather than assumed impossible.
+*/
+const UNSAFE_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/** A whole-string reference, and nothing else: `{color.brand.primary}`. */
+const WHOLE_REFERENCE = /^\{([^{}]+)\}$/;
+/** Any brace at all, used to catch references embedded in a larger string. */
+const ANY_BRACE = /[{}]/;
+const fail = (message, source, path) => {
+	throw new TokenCssError(message, {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source,
+		tokenPaths: [formatPath(path)]
+	});
+};
+/** True for a plain object — not null, not an array. */
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Turns a raw token value into a reference or a literal.
+*
+* A value is a reference only when the entire string is one. A string that
+* merely contains `{…}` — `1px solid {color.border}` — is refused: emitting it
+* verbatim would produce syntactically valid CSS that silently does nothing,
+* which is the failure mode this library exists to prevent.
+*/
+function toTokenValue(raw, path, source) {
+	if (typeof raw === "string") {
+		const whole = WHOLE_REFERENCE.exec(raw.trim());
+		if (whole) {
+			const target = whole[1].split(".");
+			if (target.some((segment) => segment.trim() === "")) fail(`token "${formatPath(path)}" references "${raw.trim()}", which is not a token path`, source, path);
+			return ref(target);
+		}
+		if (ANY_BRACE.test(raw)) fail(`token "${formatPath(path)}" has a reference inside a larger value ("${raw}"). This version emits a reference only when the whole value is one`, source, path);
+	}
+	const asObjectScalar = objectValueToCss(raw, path, source);
+	if (asObjectScalar !== null) return literal(asObjectScalar);
+	return literal(assertScalar(raw, path, source));
+}
+/**
+* Walks a token document into a flat, ordered list of tokens.
+*
+* Nothing is dropped quietly. A scalar sitting where a group should be is a
+* failure, not a skipped entry, because a token that vanishes between the file
+* and the stylesheet is the silent breakage the Reliability requirement forbids.
+*
+* @throws {TokenCssError} `FORMAT_NOT_ALLOWED` for unsafe keys, stray scalars,
+* and malformed references. Multi-file constructs are caught earlier, by the
+* registry, because they can appear in a document no dialect claims.
+*/
+function walkTokenTree(root, source, reader) {
+	const tokens = [];
+	const visit = (node, path) => {
+		const value = reader.read(node);
+		if (value.found) {
+			tokens.push(token(path, toTokenValue(value.raw, path, source)));
+			return;
+		}
+		for (const key of Object.keys(node)) {
+			const childPath = [...path, key];
+			if (UNSAFE_KEYS.has(key)) fail(`token document contains the key "${key}" at "${formatPath(childPath)}", which is refused`, source, childPath);
+			if (reader.isMetadataKey(key)) continue;
+			const child = node[key];
+			if (isPlainObject(child)) visit(child, childPath);
+			else fail(`"${formatPath(childPath)}" is a ${Array.isArray(child) ? "list" : typeof child}, but a group or a token was expected here`, source, childPath);
+		}
+	};
+	visit(root, []);
+	return tokens;
+}
+//#endregion
+//#region src/dialects/dtcg.ts
+/** Keys DTCG reserves. Inside a token node they are metadata; at group level, document metadata. */
+const isDollarKey = (key) => key.startsWith("$");
+const reader$2 = {
+	read: (node) => "$value" in node ? {
+		found: true,
+		raw: node["$value"]
+	} : {
+		found: false,
+		raw: void 0
+	},
+	isMetadataKey: isDollarKey
+};
+/**
+* Finds a multi-file construct, wherever it sits.
+*
+* This runs before dialect detection, and it has to. A resolver document
+* carries no `$value` anywhere, so no dialect claims it and the tree walk that
+* holds the specific message never runs — the developer would be told "no
+* tokens were recognized", which is true and useless when the real answer is
+* "this file points at other files, and this version reads one".
+*
+* @returns The path where the construct was found, or `null`.
+*/
+function findMultiFileConstruct(root) {
+	const seen = /* @__PURE__ */ new Set();
+	const scan = (node, path) => {
+		if (seen.has(node)) return null;
+		seen.add(node);
+		for (const key of Object.keys(node)) {
+			if (key === "$ref") return [...path, key];
+			const child = node[key];
+			if (isPlainObject(child)) {
+				const found = scan(child, [...path, key]);
+				if (found) return found;
+			}
+		}
+		return null;
+	};
+	return scan(root, []);
+}
+/** True when any node in the document carries a `$value`. */
+function looksLikeDtcg(root) {
+	const seen = /* @__PURE__ */ new Set();
+	const scan = (node) => {
+		if (seen.has(node)) return false;
+		seen.add(node);
+		if ("$value" in node) return true;
+		return Object.keys(node).some((key) => {
+			const child = node[key];
+			return isPlainObject(child) && scan(child);
+		});
+	};
+	return scan(root);
+}
+/** Normalizes a DTCG document into the internal representation. */
+function normalizeDtcg(root, source) {
+	return { tokens: walkTokenTree(root, source, reader$2) };
+}
+//#endregion
+//#region src/dialects/sd-legacy.ts
+/**
+* A node holding `value` is a token.
+*
+* There is a trade-off buried here. A group literally named `value` would be
+* misread as a token — but a composite `value` (a shadow, a typography block)
+* is far more common than a group by that name, and it must reach the composite
+* check rather than be walked into as a group. The pathological case fails
+* clearly, naming the token, rather than converting into something wrong.
+*/
+const reader$1 = {
+	read: (node) => "value" in node ? {
+		found: true,
+		raw: node["value"]
+	} : {
+		found: false,
+		raw: void 0
+	},
+	isMetadataKey: (key) => key.startsWith("$")
+};
+/** True when any node in the document carries a `value`. */
+function looksLikeSdLegacy(root) {
+	const seen = /* @__PURE__ */ new Set();
+	const scan = (node) => {
+		if (seen.has(node)) return false;
+		seen.add(node);
+		if ("value" in node) return true;
+		return Object.keys(node).some((key) => {
+			const child = node[key];
+			return isPlainObject(child) && scan(child);
+		});
+	};
+	return scan(root);
+}
+/** Normalizes a Style Dictionary legacy document into the internal representation. */
+function normalizeSdLegacy(root, source) {
+	return { tokens: walkTokenTree(root, source, reader$1) };
+}
+/**
+* Finds a token node that speaks both dialects at once.
+*
+* Detection is first-match-wins, so a node carrying `$value` and `value`
+* together would be read as DTCG and its `value` quietly ignored. A key that
+* disappears between the file and the stylesheet is the silent breakage this
+* library refuses to produce, so the ambiguity is refused instead of resolved.
+*
+* @returns The path of the offending node, or `null`.
+*/
+function findMixedDialectNode(root) {
+	const seen = /* @__PURE__ */ new Set();
+	const scan = (node, path) => {
+		if (seen.has(node)) return null;
+		seen.add(node);
+		if ("$value" in node && "value" in node) return path;
+		for (const key of Object.keys(node)) {
+			const child = node[key];
+			if (isPlainObject(child)) {
+				const found = scan(child, [...path, key]);
+				if (found) return found;
+			}
+		}
+		return null;
+	};
+	return scan(root, []);
+}
+//#endregion
+//#region src/dialects/tokens-studio.ts
+/**
+* Tokens Studio exports — shape A3 of the Format Allowlist.
+*
+* What arrives from Tokens Studio is a DTCG or legacy tree wrapped in a token
+* set, alongside the plugin's own bookkeeping. The bookkeeping is read and
+* dropped; the wrapper is dropped from the emitted names.
+*
+* That last part is the whole reason this needs its own entry rather than
+* falling through to another dialect. Left in place, the set name folds into
+* every custom property — `global.color.brand` becoming `--global-color-brand`
+* instead of `--color-brand` — which converts perfectly happily and is wrong
+* everywhere at once.
+*/
+/** The plugin's own keys, read and ignored. */
+const BOOKKEEPING = /* @__PURE__ */ new Set(["$themes", "$metadata"]);
+/** A token node in either dialect the wrapper may contain. */
+const reader = {
+	read: (node) => {
+		if ("$value" in node) return {
+			found: true,
+			raw: node["$value"]
+		};
+		if ("value" in node) return {
+			found: true,
+			raw: node["value"]
+		};
+		return {
+			found: false,
+			raw: void 0
+		};
+	},
+	isMetadataKey: (key) => key.startsWith("$")
+};
+/** True when the document carries the plugin's bookkeeping. */
+function looksLikeTokensStudio(root) {
+	return [...BOOKKEEPING].some((key) => key in root);
+}
+/** Arithmetic written as a string: `2 * 4`, `16 / 2`, `(8 + 8)`. */
+const ARITHMETIC = /^\(?\s*-?\d+(\.\d+)?\s*([+\-*/]\s*\(?\s*-?\d+(\.\d+)?\s*\)?\s*)+$/;
+/** A helper Tokens Studio provides and this version does not evaluate. */
+const STUDIO_FUNCTION = /^\s*roundTo\s*\(/;
+/**
+* Refuses a value that is an expression rather than a value.
+*
+* No expression is evaluated here or anywhere else — there is no evaluator in
+* this package, deliberately. Tokens Studio can resolve its own math on export;
+* a converter that quietly implemented a second, slightly different arithmetic
+* would produce numbers nobody could account for.
+*
+* Deliberately narrow. `calc(100% - 16px)` and `clamp(1rem, 2vw, 3rem)` are
+* valid CSS and pass through untouched; only arithmetic that CSS would not
+* accept, and the plugin's own helpers, are refused.
+*/
+function refuseExpressions(node, source) {
+	if (node.value.kind !== "literal" || typeof node.value.value !== "string") return;
+	const text = node.value.value;
+	if (!ARITHMETIC.test(text) && !STUDIO_FUNCTION.test(text)) return;
+	throw new TokenCssError(`token "${formatPath(node.path)}" is an expression ("${text}"). This version writes token values as they are and evaluates nothing — resolve it in Tokens Studio before exporting`, {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source,
+		tokenPaths: [formatPath(node.path)]
+	});
+}
+/**
+* Normalizes a Tokens Studio export.
+*
+* @throws {TokenCssError} `FORMAT_NOT_ALLOWED` when the export holds more than
+* one token set, or when a value is an expression.
+*/
+function normalizeTokensStudio(root, source) {
+	const setNames = Object.keys(root).filter((key) => !BOOKKEEPING.has(key));
+	if (setNames.length === 0) throw new TokenCssError(`this Tokens Studio export contains no token set — only the plugin's own metadata`, {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source
+	});
+	if (setNames.length > 1) throw new TokenCssError(`this Tokens Studio export contains ${setNames.length} token sets (${setNames.join(", ")}). This version converts one set at a time — merging sets would need to decide which one wins, and that is a choice the export does not record`, {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source
+	});
+	const set = root[setNames[0]];
+	if (!isPlainObject(set)) throw new TokenCssError(`the token set "${setNames[0]}" is not a group of tokens`, {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source
+	});
+	const tokens = walkTokenTree(set, source, reader);
+	for (const node of tokens) refuseExpressions(node, source);
+	return { tokens };
+}
+//#endregion
+//#region src/dialects/registry.ts
+/**
+* The Format Allowlist, as a closed ordered registry (AD-3).
+*
+* Every accepted shape is one entry. Detection walks the list in a fixed order
+* and the first match wins, so a document that could be read two ways is always
+* read the same way. Adding a shape means adding an entry and its fixtures —
+* there is nowhere else to change, which is what keeps the allowlist a decision
+* rather than an accumulation.
+*/
+/**
+* Detection order: Tokens Studio, then DTCG, then Style Dictionary legacy.
+*
+* Tokens Studio comes first because its documents *contain* DTCG or legacy
+* nodes — checking it later would match the inner shape and lose the wrappers.
+* The Epic 2 dialects slot in around this entry without reordering it.
+*/
+const DIALECTS = [
+	{
+		id: "tokens-studio",
+		describedAs: "Tokens Studio exports, one token set per file",
+		matches: looksLikeTokensStudio,
+		normalize: normalizeTokensStudio
+	},
+	{
+		id: "dtcg",
+		describedAs: "DTCG single-file documents using $value",
+		matches: looksLikeDtcg,
+		normalize: normalizeDtcg
+	},
+	{
+		id: "sd-legacy",
+		describedAs: "Style Dictionary legacy documents using value/type without the dollar",
+		matches: looksLikeSdLegacy,
+		normalize: normalizeSdLegacy
+	}
+];
+/**
+* Reads a parsed JSON document into the internal representation.
+*
+* @throws {TokenCssError} `FORMAT_NOT_ALLOWED` when the root is not an object,
+* or when no allowlisted shape matches. The message lists what is accepted, so
+* a developer can act on it without reading this source.
+*/
+function normalizeDocument(root, source) {
+	if (!isPlainObject(root)) throw new TokenCssError(`the token source is ${Array.isArray(root) ? "a list" : `a ${root === null ? "null" : typeof root}`}, but a token document must be a JSON object`, {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source
+	});
+	const multiFile = findMultiFileConstruct(root);
+	if (multiFile) throw new TokenCssError(`token document uses "$ref" at "${multiFile.join(".")}". Multi-file documents and resolver manifests are not supported — pass a single self-contained file`, {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source,
+		tokenPaths: [multiFile.join(".")]
+	});
+	const mixed = findMixedDialectNode(root);
+	if (mixed) throw new TokenCssError(`${mixed.length === 0 ? "the document root" : `"${mixed.join(".")}"`} carries both "$value" and "value". A token speaks one dialect or the other — remove whichever one is not meant to be there`, {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source,
+		tokenPaths: [mixed.join(".")]
+	});
+	for (const dialect of DIALECTS) if (dialect.matches(root)) {
+		const doc = dialect.normalize(root, source);
+		if (doc.tokens.length === 0) break;
+		return doc;
+	}
+	throw new TokenCssError(`no tokens were recognized in this document. This version reads: ${DIALECTS.map((d) => d.describedAs).join("; ")}`, {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source
+	});
+}
+//#endregion
+//#region src/source/file.ts
+/**
+* Reading a local token file (FR-12, FR-13).
+*
+* The failure classes here are deliberately distinguishable: a missing file, a
+* file you may not read, and a directory are three different mistakes with
+* three different fixes, and telling them apart is most of what makes an error
+* message worth reading.
+*/
+/**
+* Reads a token file from disk.
+*
+* @throws {TokenCssError} `SOURCE_UNREADABLE` when the file is missing or
+* cannot be read; `FORMAT_NOT_ALLOWED` when the path is a directory, which is
+* a different mistake with a different fix.
+*/
+async function readTokenFile(path, source) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (err) {
+		const code = err.code;
+		if (code === "EISDIR") throw new TokenCssError(`"${source}" is a directory. This version converts one token file at a time — pass the file itself`, {
+			code: FailureCode.FORMAT_NOT_ALLOWED,
+			source,
+			cause: err
+		});
+		throw new TokenCssError(`could not read "${source}": ${code === "ENOENT" ? "there is no file there" : code === "EACCES" || code === "EPERM" ? "permission was denied" : `reading it failed (${code ?? "unknown error"})`}`, {
+			code: FailureCode.SOURCE_UNREADABLE,
+			source,
+			cause: err
+		});
+	}
+}
+/**
+* Parses token JSON.
+*
+* @throws {TokenCssError} `SOURCE_INVALID_JSON`, carrying the parser's own
+* message, which names the position when the runtime provides it.
+*/
+function parseTokenJson(text, source) {
+	try {
+		return JSON.parse(text);
+	} catch (err) {
+		throw new TokenCssError(`"${source}" is not valid JSON: ${err.message}`, {
+			code: FailureCode.SOURCE_INVALID_JSON,
+			source,
+			cause: err
+		});
+	}
+}
+//#endregion
+//#region src/source/http.ts
+/**
+* The guarded remote adapter (FR-1, FR-12, AD-8, AD-13).
+*
+* This is the only module in the package that opens a socket, and the only one
+* that needs to be read as security code.
+*
+* It is built on `node:https` rather than global `fetch` for one reason:
+* `fetch` never tells you which address it resolved, and pinning a connection
+* to an address you have checked requires a dispatcher that is not a Node
+* builtin. Taking that dependency would break the package's zero-dependency
+* promise, so the choice is between a real guard and a convenient client.
+*
+* The shape of the guard:
+*
+*   - `https:` only, unless the caller explicitly allows `http:`.
+*   - Every hop is re-validated. A redirect is a new request to a new host, and
+*     treating it as a continuation of an approved one is how a benign URL
+*     reaches a metadata endpoint.
+*   - The address is checked in a custom `lookup`, and the address the check
+*     approved is the address handed to the socket. Resolving once to validate
+*     and again to connect leaves a window between the two.
+*   - One deadline covers the whole exchange, redirects included.
+*   - The body is counted while it arrives and the connection is dropped the
+*     moment it is too big, rather than after it has all been buffered.
+*/
+/**
+* Address ranges a token URL has no business reaching.
+*
+* The one that matters most is `169.254.0.0/16`: cloud metadata services live
+* at `169.254.169.254` and hand out credentials to whoever asks from inside the
+* host. A library that fetches a URL somebody else supplied is exactly the
+* thing an attacker would like to point at it.
+*/
+function buildBlockList() {
+	const list = new BlockList();
+	for (const [network, prefix] of [
+		["0.0.0.0", 8],
+		["10.0.0.0", 8],
+		["100.64.0.0", 10],
+		["127.0.0.0", 8],
+		["169.254.0.0", 16],
+		["172.16.0.0", 12],
+		["192.0.0.0", 24],
+		["192.168.0.0", 16],
+		["198.18.0.0", 15],
+		["224.0.0.0", 4],
+		["240.0.0.0", 4]
+	]) list.addSubnet(network, prefix, "ipv4");
+	for (const [network, prefix] of [
+		["::", 128],
+		["::1", 128],
+		["fc00::", 7],
+		["fe80::", 10],
+		["ff00::", 8]
+	]) list.addSubnet(network, prefix, "ipv6");
+	return list;
+}
+const BLOCKED = buildBlockList();
+/** `::ffff:169.254.169.254` is the same address as `169.254.169.254`. */
+function unwrapMapped(address) {
+	const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+	if (mapped) return {
+		address: mapped[1],
+		family: 4
+	};
+	return {
+		address,
+		family: isIPv4(address) ? 4 : 6
+	};
+}
+const STRICT = { allowInternalAddresses: false };
+/** Whether an address is inside a range this adapter refuses to reach. */
+function isBlockedAddress(address) {
+	const { address: plain, family } = unwrapMapped(address);
+	return BLOCKED.check(plain, family === 4 ? "ipv4" : "ipv6");
+}
+/**
+* Refuses a host that is already a literal address.
+*
+* Node skips DNS entirely when the host is an IP, so the custom `lookup` never
+* runs and the address check with it. `http://169.254.169.254/` — the most
+* obvious payload there is — would otherwise walk straight past the guard and
+* sit there until something timed out.
+*/
+function checkLiteralHost(url, source, policy) {
+	if (policy.allowInternalAddresses) return;
+	const host = url.hostname.replace(/^\[|\]$/g, "");
+	if (isIP(host) === 0) return;
+	if (isBlockedAddress(host)) throw unreadable(`refusing to fetch "${url.href}": ${host} is a loopback, private, link-local or otherwise internal address`, source);
+}
+const unreadable = (message, source, cause) => new TokenCssError(message, {
+	code: FailureCode.SOURCE_UNREADABLE,
+	source,
+	...cause === void 0 ? {} : { cause }
+});
+/** Rejects a URL whose scheme this adapter will not fetch. */
+function checkScheme(url, allowInsecure, source) {
+	if (url.protocol === "https:") return;
+	if (url.protocol === "http:" && allowInsecure) return;
+	if (url.protocol === "http:") throw unreadable(`"${url.href}" uses http:. Tokens are fetched over https by default — pass http: { allowInsecure: true } if you really mean to read this over plain http`, source);
+	throw unreadable(`"${url.href}" uses the "${url.protocol}" scheme, which is not fetched`, source);
+}
+/** One hop: connect, check the address, read the body or the `Location`. */
+function fetchOnce(attempt, policy) {
+	const { url, deadline, maxBytes, source } = attempt;
+	return new Promise((resolve, reject) => {
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) {
+			reject(unreadable(`fetching "${source}" took too long`, source));
+			return;
+		}
+		const request$2 = (url.protocol === "https:" ? request$1 : request)(url, { lookup: (hostname, options, callback) => {
+			lookup(hostname, {
+				...options,
+				all: true
+			}, (err, addresses) => {
+				if (err) {
+					callback(err, "", 4);
+					return;
+				}
+				const internal = addresses.find((entry) => isBlockedAddress(entry.address));
+				if (internal !== void 0 && !policy.allowInternalAddresses) {
+					callback(/* @__PURE__ */ new Error(`"${hostname}" resolves to ${internal.address}, which is a loopback, private, link-local or otherwise internal address`), "", 4);
+					return;
+				}
+				if (options.all === true) {
+					callback(null, addresses, 0);
+					return;
+				}
+				const first = addresses[0];
+				if (first === void 0) {
+					callback(/* @__PURE__ */ new Error(`"${hostname}" resolved to no addresses`), "", 4);
+					return;
+				}
+				callback(null, first.address, first.family);
+			});
+		} }, (response) => {
+			const status = response.statusCode ?? 0;
+			if (status >= 300 && status < 400) {
+				const location = response.headers.location;
+				response.resume();
+				if (location === void 0) {
+					reject(unreadable(`"${url.href}" redirected without saying where`, source));
+					return;
+				}
+				resolve({
+					body: null,
+					redirectTo: new URL(location, url).href
+				});
+				return;
+			}
+			if (status < 200 || status >= 300) {
+				response.resume();
+				reject(unreadable(`"${url.href}" answered ${status}`, source));
+				return;
+			}
+			const chunks = [];
+			let size = 0;
+			response.on("data", (chunk) => {
+				size += chunk.length;
+				if (size > maxBytes) {
+					request$2.destroy();
+					reject(unreadable(`"${url.href}" is larger than the ${maxBytes} byte limit for a token document`, source));
+					return;
+				}
+				chunks.push(chunk);
+			});
+			response.on("end", () => resolve({
+				body: Buffer.concat(chunks),
+				redirectTo: null
+			}));
+			response.on("error", (err) => reject(unreadable(`reading "${url.href}" failed`, source, err)));
+		});
+		request$2.setTimeout(remaining, () => {
+			request$2.destroy();
+			reject(unreadable(`fetching "${source}" took longer than the time allowed`, source));
+		});
+		request$2.on("error", (err) => {
+			if (/resolves to .* which is a/.test(err.message)) {
+				reject(unreadable(`refusing to fetch "${url.href}": ${err.message}`, source, err));
+				return;
+			}
+			reject(unreadable(`could not reach "${url.href}" (${err.code ?? err.message})`, source, err));
+		});
+		request$2.end();
+	});
+}
+/**
+* Fetches a token document, following redirects under the guard.
+*
+* @returns The document text. The core never sees the URL — only bytes that
+* passed every check.
+* @throws {TokenCssError} `SOURCE_UNREADABLE` for every network failure, so a
+* caller can tell "I could not read it" from "I read it and it was wrong".
+*/
+async function fetchTokenDocument(url, source, options = {}) {
+	return fetchWithPolicy(url, source, options, STRICT);
+}
+/** The same fetch, with the address rule supplied. Internal; see {@link AddressPolicy}. */
+async function fetchWithPolicy(url, source, options, policy) {
+	const allowInsecure = options.allowInsecure ?? DEFAULTS.http.allowInsecure;
+	const maxRedirects = options.maxRedirects ?? DEFAULTS.http.maxRedirects;
+	const deadline = Date.now() + (options.timeoutMs ?? DEFAULTS.http.timeoutMs);
+	const maxBytes = options.maxBytes ?? DEFAULTS.http.maxBytes;
+	let current = url;
+	for (let hop = 0; hop <= maxRedirects; hop++) {
+		checkScheme(current, allowInsecure, source);
+		checkLiteralHost(current, source, policy);
+		const { body, redirectTo } = await fetchOnce({
+			url: current,
+			deadline,
+			maxBytes,
+			source
+		}, policy);
+		if (body !== null) return body.toString("utf8");
+		current = new URL(redirectTo);
+	}
+	throw unreadable(`"${source}" redirected more than ${maxRedirects} times without arriving anywhere`, source);
+}
+//#endregion
+//#region src/source/resolve.ts
+/**
+* Working out what the caller pointed at (FR-1, FR-3).
+*
+* Path resolution happens here, once, at the edge. Everything inside the
+* pipeline sees absolute paths, so no pure stage has to know what the current
+* working directory is.
+*/
+/** Characters that make a path a pattern rather than a file. */
+const GLOB = /[*?[\]{}]/;
+/**
+* A scheme, but not a Windows drive letter.
+*
+* `C:\tokens.json` parses as a URL with protocol `c:`, so requiring at least
+* two characters keeps a Windows path a path.
+*/
+const SCHEME = /^([a-z][a-z0-9+.-]+):/i;
+const refuse = (message, source) => {
+	throw new TokenCssError(message, {
+		code: FailureCode.FORMAT_NOT_ALLOWED,
+		source
+	});
+};
+/**
+* Turns whatever the caller passed into an absolute path or a URL.
+*
+* @param source A path or a URL, as the caller wrote it.
+* @param baseDir What relative paths resolve against.
+* @throws {TokenCssError} `FORMAT_NOT_ALLOWED` for globs, unsupported schemes,
+* and anything that is not a single file.
+*/
+function resolveSource(source, baseDir) {
+	const display = String(source);
+	if (source instanceof URL) return fromUrl(source, display);
+	if (SCHEME.exec(source)) {
+		let url;
+		try {
+			url = new URL(source);
+		} catch {
+			return refuse(`"${display}" looks like a URL but cannot be parsed as one`, display);
+		}
+		return fromUrl(url, display);
+	}
+	if (GLOB.test(source)) refuse(`"${display}" looks like a pattern. This version converts one token file at a time — pass a single path, not a glob`, display);
+	return {
+		kind: "file",
+		path: isAbsolute(source) ? source : resolve(baseDir, source)
+	};
+}
+function fromUrl(url, display) {
+	if (url.protocol === "file:") return {
+		kind: "file",
+		path: fileURLToPath(url)
+	};
+	if (url.protocol === "http:" || url.protocol === "https:") return {
+		kind: "url",
+		url
+	};
+	return refuse(`"${display}" uses the "${url.protocol}" scheme. This version reads a local path, an https: URL, or an http: URL when explicitly allowed`, display);
+}
+/** Where the stylesheet goes, resolved the same way as the input. */
+function resolveOutputPath(outDir, fileName, baseDir) {
+	return resolve(isAbsolute(outDir) ? outDir : resolve(baseDir, outDir), fileName);
+}
+//#endregion
+//#region src/validate/alias-graph.ts
+/**
+* Alias Graph Validation (FR-15, FR-22, AD-5).
+*
+* This checks that the reference graph is sound. It never resolves anything:
+* "validate" here means *the edges make sense*, not *replace the edge with the
+* value it points at*. Emission keeps every reference as `var(--target)`.
+*
+* Two passes, in a fixed order, each exhaustive within its class. Dangling runs
+* first — running cycle detection over a graph with missing nodes reports
+* confusing half-cycles, and a developer with a typo should be told about the
+* typo rather than about a loop that only exists because of it.
+*
+* Every token has at most one outgoing edge — a value is either a literal or a
+* single reference — so the graph is a chain per token, and one linear sweep
+* finds every cycle.
+*/
+/** Where a token's reference points, or `undefined` when it holds a literal. */
+function targetOf(node) {
+	return isRef(node.value) ? formatPath(node.value.path) : void 0;
+}
+/**
+* Reports every reference whose target is not a token in this document.
+*
+* A reference to a *group* is reported differently from a reference to nothing
+* at all: seeing "color.brand does not exist" when `color.brand` is visibly
+* there in the file is the kind of message that sends people to read library
+* source.
+*/
+function checkDangling(doc, byPath, source) {
+	const problems = [];
+	const offenders = [];
+	for (const node of doc.tokens) {
+		const target = targetOf(node);
+		if (target === void 0 || byPath.has(target)) continue;
+		const from = formatPath(node.path);
+		offenders.push(from);
+		const isGroup = [...byPath.keys()].some((known) => known.startsWith(`${target}.`));
+		problems.push(isGroup ? `"${from}" references "${target}", which is a group of tokens rather than a token` : `"${from}" references "${target}", which does not exist`);
+	}
+	if (problems.length > 0) throw new TokenCssError(`${problems.length} ${problems.length === 1 ? "reference points" : "references point"} nowhere:\n  ${problems.join("\n  ")}`, {
+		code: FailureCode.ALIAS_DANGLING,
+		source,
+		tokenPaths: offenders
+	});
+}
+const UNVISITED = 0;
+const ON_PATH = 1;
+const SETTLED = 2;
+/**
+* Reports every cycle in the reference graph.
+*
+* Iterative rather than recursive: a document is allowed to be a chain of ten
+* thousand tokens, and that is a stack overflow rather than a clear failure if
+* this walks itself.
+*/
+function checkCycles(doc, byPath, source) {
+	const state = /* @__PURE__ */ new Map();
+	const cycles = [];
+	for (const start of doc.tokens) {
+		const startKey = formatPath(start.path);
+		if (state.get(startKey) !== void 0) continue;
+		const chain = [];
+		let cursor = startKey;
+		while (cursor !== void 0 && (state.get(cursor) ?? UNVISITED) === UNVISITED) {
+			state.set(cursor, ON_PATH);
+			chain.push(cursor);
+			const node = byPath.get(cursor);
+			cursor = node === void 0 ? void 0 : targetOf(node);
+		}
+		if (cursor !== void 0 && state.get(cursor) === ON_PATH) cycles.push(chain.slice(chain.indexOf(cursor)));
+		for (const key of chain) state.set(key, SETTLED);
+	}
+	if (cycles.length > 0) {
+		const described = cycles.map((cycle) => `  ${[...cycle, cycle[0]].join(" → ")}`);
+		throw new TokenCssError(`${cycles.length} alias cycle${cycles.length === 1 ? "" : "s"} found:\n` + described.join("\n"), {
+			code: FailureCode.ALIAS_CYCLE,
+			source,
+			tokenPaths: cycles.flat()
+		});
+	}
+}
+/**
+* Validates the whole reference graph.
+*
+* @throws {TokenCssError} `ALIAS_DANGLING` or `ALIAS_CYCLE`, each listing every
+* offender of its class so one run tells the developer everything of that kind
+* that is wrong.
+*/
+function validateAliasGraph(doc, source) {
+	const byPath = /* @__PURE__ */ new Map();
+	for (const node of doc.tokens) byPath.set(formatPath(node.path), node);
+	checkDangling(doc, byPath, source);
+	checkCycles(doc, byPath, source);
+}
+//#endregion
+//#region src/validate/collisions.ts
+/**
+* Name collision detection (FR-21, AD-12).
+*
+* The naming rule is deliberately lossy — everything outside `[a-z0-9]`
+* collapses — so two different token paths can arrive at the same custom
+* property. `color.brand.primary` and `color.brand-primary` both become
+* `--color-brand-primary`, and so do `cafe` and `café`.
+*
+* That is fine, as long as it is never silent. Emitting both would let the
+* second declaration quietly win and ship a theme that reports success while a
+* token has vanished — the exact failure the Reliability requirement forbids.
+*
+* This runs on the **final emitted names**, not on the paths. Comparing paths
+* would find the identical ones and miss every collision the naming rule
+* itself creates, which are the ones nobody expects.
+*/
+/**
+* Checks that every token emits a distinct custom property.
+*
+* @throws {TokenCssError} `NAME_COLLISION` listing every colliding group, so
+* one run tells the developer about all of them.
+*/
+function validateNoCollisions(doc, source) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const node of doc.tokens) {
+		const name = customPropertyName(node.path, source);
+		const paths = byName.get(name);
+		if (paths === void 0) byName.set(name, [formatPath(node.path)]);
+		else paths.push(formatPath(node.path));
+	}
+	const collisions = [...byName].filter(([, paths]) => paths.length > 1);
+	if (collisions.length === 0) return;
+	const described = collisions.map(([name, paths]) => `  ${name} ← ${paths.map((p) => `"${p}"`).join(", ")}`);
+	throw new TokenCssError(`${collisions.length} custom ${collisions.length === 1 ? "property is" : "properties are"} claimed by more than one token:\n${described.join("\n")}\nRename one of each pair — this version will not pick a winner for you.`, {
+		code: FailureCode.NAME_COLLISION,
+		source,
+		tokenPaths: collisions.flatMap(([, paths]) => paths)
+	});
+}
+//#endregion
+//#region src/write/atomic.ts
+/**
+* Writing the stylesheet without ever leaving a half-written one (FR-2, FR-19, AD-7).
+*
+* The stylesheet is written to a temporary file beside the target and renamed
+* into place. `rename` within a directory is atomic, so a reader sees either
+* the old file or the new one — never a truncated one, whatever happens
+* mid-write.
+*
+* The temporary file goes in the **target directory**, not the system temp
+* directory: `rename` across filesystems is not atomic and often is not even
+* possible, and the two are frequently on different filesystems.
+*/
+function explain(code, targetPath) {
+	switch (code) {
+		case "EACCES":
+		case "EPERM": return `permission was denied writing to "${targetPath}"`;
+		case "ENOSPC": return `the disk is full`;
+		case "EROFS": return `"${targetPath}" is on a read-only filesystem`;
+		case "ENOTDIR": return `part of the path to "${targetPath}" is a file, not a directory`;
+		default: return `writing "${targetPath}" failed (${code ?? "unknown error"})`;
+	}
+}
+/**
+* Writes the stylesheet, replacing whatever was there.
+*
+* Creates the output directory if it does not exist. On any failure the
+* temporary file is removed and the previous stylesheet is left exactly as it
+* was — a failed run never costs you the last good output.
+*
+* @throws {TokenCssError} `OUTPUT_WRITE_FAILED`, naming the reason.
+*/
+async function writeStylesheet(targetPath, contents, source) {
+	const directory = dirname(targetPath);
+	const temporary = join(directory, `.${randomUUID()}.tmp`);
+	try {
+		await mkdir(directory, { recursive: true });
+		const handle = await open(temporary, "wx");
+		try {
+			await handle.writeFile(contents, "utf8");
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		await rename(temporary, targetPath);
+	} catch (err) {
+		await unlink(temporary).catch(() => {});
+		throw new TokenCssError(explain(err.code, targetPath), {
+			code: FailureCode.OUTPUT_WRITE_FAILED,
+			source,
+			cause: err
+		});
+	}
+}
+//#endregion
+//#region src/pipeline.ts
+/**
+* The conversion pipeline (AD-1, AD-5, AD-6).
+*
+* Six stages, in one fixed order, sequenced only here. Reading and writing
+* happen at the two ends; everything between them is a pure function of what
+* the stage before it returned.
+*
+* Nothing touches the output path until the whole stylesheet exists in memory
+* and every check has passed. That is what makes "it failed" and "your previous
+* stylesheet is intact" the same sentence.
+*/
+/**
+* Everything between reading and writing: detect, normalize, validate, emit.
+*
+* Exported so the fixture corpus exercises the real stage order rather than
+* re-implementing it. A corpus that sequenced the passes itself could stay green
+* while the pipeline ran them in a different order, which is precisely the
+* divergence the fixed order exists to prevent.
+*/
+function convertDocument(raw, source) {
+	const doc = normalizeDocument(raw, source);
+	validateAliasGraph(doc, source);
+	validateNoCollisions(doc, source);
+	return {
+		css: emitStylesheet(doc, source),
+		tokenCount: doc.tokens.length
+	};
+}
+async function runConversion(source, options = {}) {
+	const display = String(source);
+	const baseDir = options.baseDir ?? process.cwd();
+	const resolved = resolveSource(source, baseDir);
+	const { css, tokenCount } = convertDocument(parseTokenJson(resolved.kind === "url" ? await fetchTokenDocument(resolved.url, display, options.http ?? {}) : await readTokenFile(resolved.path, display), display), display);
+	const outputPath = resolveOutputPath(options.outDir ?? DEFAULTS.outDir, options.fileName ?? DEFAULTS.fileName, baseDir);
+	await writeStylesheet(outputPath, css, display);
+	return {
+		outputPath,
+		tokenCount
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* tokens-to-css — the public surface (AD-14).
+*
+* Everything a caller can reach is declared here. Nothing else in `src/` is
+* exported, and `package.json` publishes no subpaths, so internals stay free to
+* move without a major version.
+*/
+/**
+* Convert a design-token document into a CSS custom-properties stylesheet.
+*
+* Reads the Token Source, validates it completely, and writes the stylesheet —
+* or throws a `TokenCssError` and writes nothing at all. There is no partial
+* success: a previous stylesheet at the target path is left untouched whenever
+* the conversion fails.
+*
+* @param source Path to a single local file, or a URL.
+* @param options Output location and network policy.
+* @returns Where the stylesheet was written, and how many properties it holds.
+* @throws {TokenCssError} With a `code` naming the failure class.
+*/
+function generateCss(source, options) {
+	return runConversion(source, options);
+}
+//#endregion
+export { DEFAULTS, FailureCode, TokenCssError, generateCss };