@navecss/tokens 0.1.0 → 0.2.0

package/README.md

@@ -46,7 +46,7 @@ Every custom property the stylesheet declares is listed in [TOKENS.md](./TOKENS.
 | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@navecss/tokens`               | JS entry point — the typed constants described under `@navecss/tokens/js` below. Not a CSS entry: `@import url('@navecss/tokens/css')` is the stylesheet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `@navecss/tokens/css`           | The generated stylesheet — `@import url('@navecss/tokens/css')`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `@navecss/tokens/js`            | Typed ESM token constants — the DTCG 2025.10 token set; every `--nave-color-*` custom property ships in the stylesheet above and not through this export, the `--nave-color-tint` seed included                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `@navecss/tokens/js`            | Typed ESM token constants — the DTCG 2025.10 token set; every `--nave-color-*` custom property (the `--nave-color-tint` seed included) ships as a value in the stylesheet above and not through this export, but its NAME is typed here as `ColorPropertyName`, exported alongside `TokenName`/`TokenValue` and disjoint from them                                                                                                                                                                                                                                                                                                                                                      |
 | `@navecss/tokens/breakpoints`   | Breakpoint values, em conversions, media strings                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `@navecss/tokens/core-contract` | The shipped core-contract manifest, as JSON, for a token layer you generate yourself and load through `@navecss/core/no-tokens`: the `--nave-*` custom-property names `@navecss/core` reads, generated from that package's own source rather than listed by hand, and not the colour namespace alone. Import it with `with { type: 'json' }`. A clean check against it means those names are present rather than that your token set is complete; for what else it does and does not establish, read the header comment in `@navecss/core/no-tokens`. A validator reading the manifest directly should refuse a `formatVersion` higher than it understands, rather than mis-reading it. |
 | `@navecss/tokens/build`         | The token build as a JavaScript API: `build` and `validate`, the two operations the `navecss-tokens` binary wraps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

package/dist/core-contract.json

@@ -2,7 +2,7 @@
   "formatVersion": 1,
   "producer": {
     "name": "@navecss/core",
-    "version": "0.1.0"
+    "version": "0.2.0"
   },
   "tokens": [
     "--nave-border-width-focus",

package/dist/lib/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
-import { build, DuplicateTokenNameRefusal, MissingContractTokensError, SeedIngestRefusal, TokenCollisionRefusal, UsageError, validate, } from "./facade.js";
+import { build, DuplicateTokenNameRefusal, formatVersionSkewFact, MissingContractTokensError, SeedIngestRefusal, TokenCollisionRefusal, UsageError, validate, } from "./facade.js";
 function normalizationQualifier(seedNormalization) {
     switch (seedNormalization) {
         case 'chroma-reduced': {
@@ -20,11 +20,21 @@ function normalizationQualifier(seedNormalization) {
 const USAGE = 'Usage:\n' +
     '  navecss-tokens build --seed=<colour> --out=<dir> [--source=<file>] [--overrides=<file>]\n' +
     '  navecss-tokens validate --source=<file>';
+function assertNoDuplicateFlags(tokens) {
+    const seen = new Set();
+    for (const token of tokens) {
+        if (token.kind !== 'option' || token.name === undefined)
+            continue;
+        if (seen.has(token.name)) {
+            throw new UsageError(`--${token.name} was given more than once; each flag accepts exactly one value.\n${USAGE}`);
+        }
+        seen.add(token.name);
+    }
+}
 function parseBuildArgs(args) {
     let values;
     try {
-        ;
-        ({ values } = parseArgs({
+        const parsed = parseArgs({
             args,
             options: {
                 out: { type: 'string' },
@@ -33,9 +43,14 @@ function parseBuildArgs(args) {
                 source: { type: 'string' },
             },
             strict: true,
-        }));
+            tokens: true,
+        });
+        assertNoDuplicateFlags(parsed.tokens);
+        values = parsed.values;
     }
     catch (error) {
+        if (error instanceof UsageError)
+            throw error;
         throw new UsageError(error.message);
     }
     if (!values.seed)
@@ -52,10 +67,18 @@ function parseBuildArgs(args) {
 function parseValidateArgs(args) {
     let values;
     try {
-        ;
-        ({ values } = parseArgs({ args, options: { source: { type: 'string' } }, strict: true }));
+        const parsed = parseArgs({
+            args,
+            options: { source: { type: 'string' } },
+            strict: true,
+            tokens: true,
+        });
+        assertNoDuplicateFlags(parsed.tokens);
+        values = parsed.values;
     }
     catch (error) {
+        if (error instanceof UsageError)
+            throw error;
         throw new UsageError(error.message);
     }
     if (!values.source)
@@ -78,6 +101,12 @@ async function main() {
         }
         const result = await build(parseBuildArgs(rest));
         console.log(`Built from seed ${result.resolvedSeed}${normalizationQualifier(result.seedNormalization)}: ${result.files.join(', ')}`);
+        if (result.versionSkew) {
+            const { producerName, ...skew } = result.versionSkew;
+            console.error(`Version skew: ${formatVersionSkewFact(producerName, skew)}. The generated file may ` +
+                `not carry every custom-property name the installed ${producerName} reads. Reinstall ` +
+                `matching versions, then build again.`);
+        }
         return 0;
     }
     if (subcommand === 'validate') {

package/dist/lib/core-version.d.ts

@@ -1,3 +1,4 @@
+import type { CoreContractManifest, ManifestVersionSkew } from './theming/core-contract.ts';
 export type CoreVersionProbe = {
     status: 'resolved';
     version: string;
@@ -9,4 +10,7 @@ export type CoreVersionProbe = {
     message: string;
     status: 'unreadable';
 };
-export declare function resolveInstalledCoreVersion(): Promise<CoreVersionProbe>;
+export declare function detectVersionSkew(manifest: CoreContractManifest): Promise<{
+    probe: CoreVersionProbe;
+    skew: ManifestVersionSkew | undefined;
+}>;

package/dist/lib/core-version.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
+import { checkManifestVersionSkew } from "./theming/core-contract.js";
 function canResolveCoreDefaultEntry() {
     try {
         import.meta.resolve('@navecss/core');
@@ -9,7 +10,7 @@ function canResolveCoreDefaultEntry() {
         return false;
     }
 }
-export async function resolveInstalledCoreVersion() {
+async function resolveInstalledCoreVersion() {
     let resolved;
     try {
         resolved = import.meta.resolve('@navecss/core/package.json');
@@ -38,3 +39,8 @@ export async function resolveInstalledCoreVersion() {
         return { message: error.message, status: 'unreadable' };
     }
 }
+export async function detectVersionSkew(manifest) {
+    const probe = await resolveInstalledCoreVersion();
+    const skew = probe.status === 'resolved' ? checkManifestVersionSkew(manifest, probe.version) : undefined;
+    return { probe, skew };
+}

package/dist/lib/facade.d.ts

@@ -1,8 +1,10 @@
 import type { SeedNormalization } from './theming/color-math.ts';
+import type { ManifestVersionSkew } from './theming/core-contract.ts';
 export { DuplicateTokenNameRefusal, MissingContractTokensError, TokenCollisionRefusal, UsageError, } from './errors.ts';
 export type { SeedNormalization } from './theming/color-math.ts';
 export type { PerStepOverrides } from './theming/pipeline.ts';
 export { SeedIngestRefusal } from './theming/seed-ingest.ts';
+export { formatVersionSkewFact } from './validate-report.ts';
 export interface TokensBuildOptions {
     seed: string;
     source?: string;
@@ -14,6 +16,9 @@ export interface TokensBuildResult {
     seedNormalization: SeedNormalization;
     files: string[];
     collidingNames: string[];
+    versionSkew?: (ManifestVersionSkew & {
+        producerName: string;
+    }) | undefined;
 }
 export declare function build(options: TokensBuildOptions): Promise<TokensBuildResult>;
 export interface TokensValidateOptions {

package/dist/lib/facade.js

@@ -3,14 +3,16 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { writeOutputs } from "./builder.js";
 import { detectCollidingNames, refuseOnCollision } from "./collision.js";
-import { resolveInstalledCoreVersion } from "./core-version.js";
+import { detectVersionSkew } from "./core-version.js";
 import { composeDtcgOutputs } from "./dtcg-outputs.js";
 import { MissingContractTokensError, UsageError } from "./errors.js";
+import { isOutPathConflict } from "./out-path-conflict.js";
 import { readOverrides } from "./overrides.js";
 import { findPackageRoot } from "./package-root.js";
+import { readManifest } from "./read-manifest.js";
 import { formatOklch } from "./theming/color-math.js";
 import { composeConsumerBuild } from "./theming/consumer-build.js";
-import { checkManifestVersionSkew, validateAgainstManifest } from "./theming/core-contract.js";
+import { validateAgainstManifest } from "./theming/core-contract.js";
 import { shippedThemingPropertyNames } from "./theming/emit.js";
 import { parseSeed } from "./theming/seed-ingest.js";
 import { SHIPPED_SEEDS } from "./theming/shipped-seeds.js";
@@ -18,11 +20,8 @@ import { checkManifestFormatSupport, formatValidateReport } from "./validate-rep
 import { computeMissing, detectSourceKind, namesFromSource, splitMissingBySupply, } from "./validate.js";
 export { DuplicateTokenNameRefusal, MissingContractTokensError, TokenCollisionRefusal, UsageError, } from "./errors.js";
 export { SeedIngestRefusal } from "./theming/seed-ingest.js";
+export { formatVersionSkewFact } from "./validate-report.js";
 const PACKAGE_ROOT = findPackageRoot(import.meta.url);
-async function readManifest() {
-    const raw = await readFile(path.join(PACKAGE_ROOT, 'dist', 'core-contract.json'), 'utf8');
-    return JSON.parse(raw);
-}
 export async function build(options) {
     const sourcePath = options.source ?? path.join(PACKAGE_ROOT, 'tokens.json');
     if (!existsSync(sourcePath)) {
@@ -37,6 +36,7 @@ export async function build(options) {
     const missing = validateAgainstManifest(manifest, emittedNames);
     if (missing.length > 0)
         throw new MissingContractTokensError(missing);
+    const { skew } = await detectVersionSkew(manifest);
     const theming = composeConsumerBuild({
         seedInputs: { primary },
         seeds: {
@@ -55,7 +55,15 @@ export async function build(options) {
         ? { ...file, content: `${file.content}\n${theming.css}` }
         : file);
     const allFiles = [...merged, ...theming.files];
-    await writeOutputs(allFiles);
+    try {
+        await writeOutputs(allFiles);
+    }
+    catch (error) {
+        if (isOutPathConflict(error)) {
+            throw new UsageError(`could not write to --out="${options.outDir}": ${error.message}`);
+        }
+        throw error;
+    }
     return {
         resolvedSeed: formatOklch(theming.primaryRecord.usedSeed),
         seedNormalization: theming.primaryRecord.normalization,
@@ -63,6 +71,7 @@ export async function build(options) {
             .map((file) => path.relative(options.outDir, file.destination))
             .toSorted((a, b) => a.localeCompare(b)),
         collidingNames,
+        versionSkew: skew === undefined ? undefined : { ...skew, producerName: manifest.producer.name },
     };
 }
 export async function validate(options) {
@@ -77,10 +86,7 @@ export async function validate(options) {
     const content = await readFile(options.source, 'utf8');
     const notDeclared = computeMissing(manifest, kind, content, { path: options.source });
     const { missing, supplied } = splitMissingBySupply(kind, notDeclared);
-    const coreProbe = await resolveInstalledCoreVersion();
-    const versionSkew = coreProbe.status === 'resolved'
-        ? checkManifestVersionSkew(manifest, coreProbe.version)
-        : undefined;
+    const { probe: coreProbe, skew: versionSkew } = await detectVersionSkew(manifest);
     const formatRefusal = checkManifestFormatSupport(manifest);
     const output = formatValidateReport(manifest, missing, versionSkew, { ...coreProbe, supplied });
     let exitCode;

package/dist/lib/formats.js

@@ -1,3 +1,4 @@
+import { shippedThemingPropertyNames } from "./theming/emit.js";
 const HEADER = '/* Nave Design System — generated, do not edit */';
 const LAYER_ORDER_STATEMENT = '@layer tokens.defaults, tokens.presets, reset, atomic, components.nave, components.consumer, overrides;';
 const PREFIX = '--nave-';
@@ -15,8 +16,10 @@ const isPublic = (token) => !token.path.includes('_primitive') && token.path[0]
 const isReducibleDuration = (token) => token.type === 'duration' &&
     token.path[0] === 'motion' &&
     token.name !== 'motion-duration-instant';
+const isZIndexShaped = (token) => token.type === 'number' && token.path[0] === 'layer';
+const atPropertySyntaxFor = (token) => isZIndexShaped(token) ? '<integer>' : AT_PROPERTY_SYNTAX[token.type];
 function isRegistrable(token) {
-    const syntax = AT_PROPERTY_SYNTAX[token.type];
+    const syntax = atPropertySyntaxFor(token);
     if (syntax === undefined)
         return false;
     if (syntax !== '<length>')
@@ -26,7 +29,7 @@ function isRegistrable(token) {
 function buildAtProperty(token) {
     return [
         `  @property ${PREFIX}${token.name} {`,
-        `    syntax: '${AT_PROPERTY_SYNTAX[token.type]}';`,
+        `    syntax: '${atPropertySyntaxFor(token)}';`,
         `    inherits: true;`,
         `    initial-value: ${token.value};`,
         `  }`,
@@ -93,8 +96,11 @@ export function formatJsTokens(tokens) {
         '',
         '/** The DTCG 2025.10 token set as a typed const object (e.g. `--nave-font-size-md`).',
         ' *  Keys are CSS custom property names. The semantic colour layer',
-        ' *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css`',
-        ' *  and is not part of this export.',
+        ' *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css` and is',
+        ' *  not part of this object; its property NAMES are typed separately as',
+        ' *  `ColorPropertyName`, and its VALUES are reachable only through CSS (e.g.',
+        ' *  `var(--nave-color-action-primary)`): the browser resolves each one for the',
+        ' *  active colour scheme, and the neutral-derived ones also follow the tint.',
         ' */',
         'export const tokens = {',
         entries,
@@ -107,13 +113,20 @@ export function formatTsDeclarations(tokens) {
         .filter((t) => isPublic(t))
         .map((t) => `  '${PREFIX}${t.name}': ${typeof t.value === 'number' ? 'number' : 'string'}`)
         .join('\n');
+    const colorPropertyNameMembers = [...shippedThemingPropertyNames()]
+        .toSorted((a, b) => a.localeCompare(b))
+        .map((name) => `  | '${name}'`)
+        .join('\n');
     return [
         HEADER,
         '',
         '/** The DTCG 2025.10 token set as a typed const object (e.g. `--nave-font-size-md`).',
         ' *  Keys are CSS custom property names. The semantic colour layer',
-        ' *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css`',
-        ' *  and is not part of this export.',
+        ' *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css` and is',
+        ' *  not part of this object; its property NAMES are typed separately as',
+        ' *  `ColorPropertyName`, and its VALUES are reachable only through CSS (e.g.',
+        ' *  `var(--nave-color-action-primary)`): the browser resolves each one for the',
+        ' *  active colour scheme, and the neutral-derived ones also follow the tint.',
         ' */',
         'export declare const tokens: {',
         keys,
@@ -122,6 +135,14 @@ export function formatTsDeclarations(tokens) {
         'export declare type TokenName = keyof typeof tokens',
         'export declare type TokenValue = typeof tokens[TokenName]',
         '',
+        '/** Every `--nave-color-*` custom property the semantic colour layer emits: names',
+        ' *  only, no value (see the doc comment above `tokens` for where the values live).',
+        ' *  Disjoint from `TokenName` — a consumer who wants both writes',
+        ' *  `TokenName | ColorPropertyName`.',
+        ' */',
+        'export declare type ColorPropertyName =',
+        colorPropertyNameMembers,
+        '',
     ].join('\n');
 }
 function buildBreakpointMap(tokens) {

package/dist/lib/out-path-conflict.d.ts

@@ -0,0 +1,3 @@
+export declare function isOutPathConflict(error: unknown): error is Error & {
+    code: string;
+};

package/dist/lib/out-path-conflict.js

@@ -0,0 +1,7 @@
+const OUT_PATH_CONFLICT_CODES = new Set(['EEXIST', 'EISDIR', 'ENOTDIR']);
+export function isOutPathConflict(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        OUT_PATH_CONFLICT_CODES.has(error.code));
+}

package/dist/lib/read-manifest.d.ts

@@ -0,0 +1,2 @@
+import type { CoreContractManifest } from './theming/core-contract.ts';
+export declare function readManifest(): Promise<CoreContractManifest>;

package/dist/lib/read-manifest.js

@@ -0,0 +1,17 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { UsageError } from "./errors.js";
+import { findPackageRoot } from "./package-root.js";
+const PACKAGE_ROOT = findPackageRoot(import.meta.url);
+export async function readManifest() {
+    let raw;
+    try {
+        raw = await readFile(path.join(PACKAGE_ROOT, 'dist', 'core-contract.json'), 'utf8');
+    }
+    catch (error) {
+        throw new UsageError(`could not read this package's own dist/core-contract.json: ${error.message}. ` +
+            'This is a broken install of @navecss/tokens, not something your build/validate ' +
+            'arguments can fix — reinstall the package.');
+    }
+    return JSON.parse(raw);
+}

package/dist/lib/reader.d.ts

@@ -5,4 +5,10 @@ export interface FlatToken {
     readonly type: string;
     readonly value: string | number;
 }
+export interface RawToken {
+    path: string[];
+    ref?: string;
+    type: string;
+    rawValue: unknown;
+}
 export declare function readTokens(source: unknown, sourceName?: string): FlatToken[];

package/dist/lib/reader.js

@@ -1,14 +1,35 @@
-import { renderTokenValue } from "./composite-value.js";
 import { classifyMalformed, formatUnreadableNodesRefusal } from "./dtcg-malformed.js";
 import { classifyDraftShape, refuseTypeReason } from "./dtcg-shape.js";
 import { DtcgShapeRefusal } from "./errors.js";
-import { refuseBothReferenceForms, resolveTokenPointer } from "./json-pointer.js";
+import { refuseBothReferenceForms } from "./json-pointer.js";
+import { refuseUnsupportedReservedKey } from "./reserved-keys.js";
+import { resolveValue } from "./resolve-value.js";
 import { nameFromPath } from "./token-name.js";
 export { kebabName } from "./token-name.js";
-const REF_RE = /^\{([^{}]+)\}$/;
+const RESERVED_METADATA_KEYS = new Set([
+    '$deprecated',
+    '$description',
+    '$extensions',
+    '$ref',
+    '$type',
+    '$value',
+]);
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function assertRecognisedDollarKey(key, at) {
+    if (RESERVED_METADATA_KEYS.has(key))
+        return;
+    refuseUnsupportedReservedKey(key, at);
+    throw new TypeError(`DTCG 2025.10 reader: "${at}" starts with "$", which DTCG 2025.10 ` +
+        'reserves for metadata — it is not a valid token or group name');
+}
+function assertTokenDollarKeys(node, path) {
+    for (const key of Object.keys(node)) {
+        if (key.startsWith('$'))
+            assertRecognisedDollarKey(key, [...path, key].join('.'));
+    }
+}
 function readTokenNode(node, path, inheritedType) {
     const hasValue = '$value' in node;
     const hasRef = typeof node.$ref === 'string';
@@ -17,6 +38,13 @@ function readTokenNode(node, path, inheritedType) {
     const at = path.join('.');
     if (hasValue && hasRef)
         refuseBothReferenceForms(at);
+    assertTokenDollarKeys(node, path);
+    const childKeys = Object.keys(node).filter((key) => !key.startsWith('$'));
+    if (childKeys.length > 0) {
+        throw new TypeError(`DTCG 2025.10 reader: "${at}" carries both a $value and child token(s) (${childKeys.join(', ')}) ` +
+            '— a node is either a token (a $value/$ref leaf) or a group (children only), never both; ' +
+            'give the children their own group, separate from this token');
+    }
     const type = typeof node.$type === 'string' ? node.$type : inheritedType;
     if (type === undefined) {
         throw new TypeError(`DTCG 2025.10 reader: no resolvable $type for token "${at}"`);
@@ -41,8 +69,16 @@ function collectRawTokens(node, path, inheritedType, out) {
     }
     const groupType = typeof node.$type === 'string' ? node.$type : inheritedType;
     for (const [key, child] of Object.entries(node)) {
-        if (key.startsWith('$'))
+        if (key.startsWith('$')) {
+            assertRecognisedDollarKey(key, [...path, key].join('.'));
             continue;
+        }
+        if (key.includes('.')) {
+            throw new TypeError(`DTCG 2025.10 reader: "${[...path, key].join('.')}" contains a literal "." in "${key}" ` +
+                "— dotted keys are ambiguous against this reader's own dotted alias paths " +
+                '(a group "a" -> "b" -> "c" and a group "a" with a key "b.c" both name the path ' +
+                '"a.b.c"), and the format has no other separator to disambiguate them');
+        }
         collectRawTokens(child, [...path, key], groupType, out);
     }
 }
@@ -81,43 +117,6 @@ function refuseUnreadableNodes(raw, sourceName) {
         throw new DtcgShapeRefusal(formatUnreadableNodesRefusal(drafts, malformed, sourceName), drafts);
     }
 }
-function resolveReference(key, targetPath, context) {
-    if (context.visiting.has(key)) {
-        throw new TypeError(`DTCG 2025.10 reader: reference cycle detected at "${key}" -> "${targetPath}"`);
-    }
-    const target = context.byPath.get(targetPath);
-    if (!target) {
-        throw new TypeError(`DTCG 2025.10 reader: "${key}" references unresolved target "${targetPath}"`);
-    }
-    context.visiting.add(key);
-    const value = resolveValue(target, context);
-    context.visiting.delete(key);
-    return value;
-}
-function resolveValue(token, context) {
-    const key = token.path.join('.');
-    const cached = context.resolved.get(key);
-    if (cached !== undefined)
-        return cached;
-    let value;
-    if (token.ref !== undefined) {
-        const targetPath = resolveTokenPointer(token.ref, key, (path) => context.byPath.has(path));
-        value = resolveReference(key, targetPath, context);
-    }
-    else if (typeof token.rawValue === 'string' && REF_RE.test(token.rawValue)) {
-        value = resolveReference(key, REF_RE.exec(token.rawValue)[1], context);
-    }
-    else if (typeof token.rawValue === 'string' &&
-        (token.rawValue.includes('{') || token.rawValue.includes('}'))) {
-        throw new TypeError(`DTCG 2025.10 reader: "${key}" embeds a reference inside a larger string ("${token.rawValue}") — ` +
-            'only a whole-value alias (curly braces around one dotted path, nothing else) is supported');
-    }
-    else {
-        value = renderTokenValue(token.type, token.rawValue, key);
-    }
-    context.resolved.set(key, value);
-    return value;
-}
 export function readTokens(source, sourceName) {
     const raw = [];
     collectRawTokens(source, [], undefined, raw);
@@ -126,6 +125,7 @@ export function readTokens(source, sourceName) {
         byPath: new Map(raw.map((t) => [t.path.join('.'), t])),
         resolved: new Map(),
         visiting: new Set(),
+        depth: 0,
     };
     return raw.map((token) => ({
         path: token.path,

package/dist/lib/reserved-keys.d.ts

@@ -0,0 +1 @@
+export declare function refuseUnsupportedReservedKey(key: string, at: string): void;

package/dist/lib/reserved-keys.js

@@ -0,0 +1,18 @@
+const UNSUPPORTED_RESERVED_KEYS = [
+    {
+        key: '$root',
+        reason: 'DTCG 2025.10 §6.2 "Root Tokens in Groups". Move its $value to a sibling token with an ' +
+            'ordinary name (for example "base") and alias that instead: {group.base}.',
+    },
+    {
+        key: '$extends',
+        reason: 'DTCG 2025.10 §6.4 "Extending Groups". Copy the extended group\'s tokens into this group, ' +
+            'or alias them individually with {group.token}.',
+    },
+];
+export function refuseUnsupportedReservedKey(key, at) {
+    const found = UNSUPPORTED_RESERVED_KEYS.find((entry) => entry.key === key);
+    if (found === undefined)
+        return;
+    throw new TypeError(`DTCG 2025.10 reader: "${at}" uses "${key}", which this reader does not support yet (${found.reason})`);
+}

package/dist/lib/resolve-value.d.ts

@@ -0,0 +1,8 @@
+import type { RawToken } from './reader.ts';
+export interface ResolveContext {
+    byPath: ReadonlyMap<string, RawToken>;
+    resolved: Map<string, string | number>;
+    visiting: Set<string>;
+    depth: number;
+}
+export declare function resolveValue(token: RawToken, context: ResolveContext): string | number;

package/dist/lib/resolve-value.js

@@ -0,0 +1,56 @@
+import { renderTokenValue } from "./composite-value.js";
+import { resolveTokenPointer } from "./json-pointer.js";
+const REF_RE = /^\{([^{}]+)\}$/;
+const MAX_ALIAS_CHAIN_DEPTH = 1000;
+function resolveReference(key, targetPath, context) {
+    if (context.visiting.has(key)) {
+        throw new TypeError(`DTCG 2025.10 reader: reference cycle detected at "${key}" -> "${targetPath}"`);
+    }
+    const target = context.byPath.get(targetPath);
+    if (!target) {
+        throw new TypeError(`DTCG 2025.10 reader: "${key}" references unresolved target "${targetPath}"`);
+    }
+    if (context.depth >= MAX_ALIAS_CHAIN_DEPTH) {
+        throw new TypeError(`DTCG 2025.10 reader: "${key}" -> "${targetPath}" exceeds the maximum alias chain depth ` +
+            `(${MAX_ALIAS_CHAIN_DEPTH}); this reads as a generated or malformed source rather than an ` +
+            'authored one');
+    }
+    context.visiting.add(key);
+    context.depth += 1;
+    const value = resolveValue(target, context);
+    context.depth -= 1;
+    context.visiting.delete(key);
+    return value;
+}
+function refuseUnsafeStringValue(key, rawValue) {
+    if (rawValue.includes(';') || rawValue.includes('/*')) {
+        throw new TypeError(`DTCG 2025.10 reader: "${key}" carries a ";" or a comment opener ("/*") in its value ` +
+            `("${rawValue}") — a raw string value is spliced directly into generated CSS, and ` +
+            'either would splice a second declaration in beside it');
+    }
+    if (rawValue.includes('{') || rawValue.includes('}')) {
+        throw new TypeError(`DTCG 2025.10 reader: "${key}" embeds a reference inside a larger string ("${rawValue}") — ` +
+            'only a whole-value alias (curly braces around one dotted path, nothing else) is supported');
+    }
+}
+export function resolveValue(token, context) {
+    const key = token.path.join('.');
+    const cached = context.resolved.get(key);
+    if (cached !== undefined)
+        return cached;
+    let value;
+    if (token.ref !== undefined) {
+        const targetPath = resolveTokenPointer(token.ref, key, (path) => context.byPath.has(path));
+        value = resolveReference(key, targetPath, context);
+    }
+    else if (typeof token.rawValue === 'string' && REF_RE.test(token.rawValue)) {
+        value = resolveReference(key, REF_RE.exec(token.rawValue)[1], context);
+    }
+    else {
+        if (typeof token.rawValue === 'string')
+            refuseUnsafeStringValue(key, token.rawValue);
+        value = renderTokenValue(token.type, token.rawValue, key);
+    }
+    context.resolved.set(key, value);
+    return value;
+}