@navecss/tokens 0.1.0

package/dist/lib/facade.d.ts

@@ -0,0 +1,26 @@
+import type { SeedNormalization } from './theming/color-math.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 interface TokensBuildOptions {
+    seed: string;
+    source?: string;
+    overrides?: string;
+    outDir: string;
+}
+export interface TokensBuildResult {
+    resolvedSeed: string;
+    seedNormalization: SeedNormalization;
+    files: string[];
+    collidingNames: string[];
+}
+export declare function build(options: TokensBuildOptions): Promise<TokensBuildResult>;
+export interface TokensValidateOptions {
+    source: string;
+}
+export interface TokensValidateResult {
+    exitCode: 0 | 1 | 2;
+    output: string[];
+}
+export declare function validate(options: TokensValidateOptions): Promise<TokensValidateResult>;

package/dist/lib/facade.js

@@ -0,0 +1,97 @@
+import { existsSync } from 'node:fs';
+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 { composeDtcgOutputs } from "./dtcg-outputs.js";
+import { MissingContractTokensError, UsageError } from "./errors.js";
+import { readOverrides } from "./overrides.js";
+import { findPackageRoot } from "./package-root.js";
+import { formatOklch } from "./theming/color-math.js";
+import { composeConsumerBuild } from "./theming/consumer-build.js";
+import { checkManifestVersionSkew, 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";
+import { checkManifestFormatSupport, formatValidateReport } from "./validate-report.js";
+import { computeMissing, detectSourceKind, namesFromSource, splitMissingBySupply, } from "./validate.js";
+export { DuplicateTokenNameRefusal, MissingContractTokensError, TokenCollisionRefusal, UsageError, } from "./errors.js";
+export { SeedIngestRefusal } from "./theming/seed-ingest.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)) {
+        throw new UsageError(`no token source found at "${sourcePath}"`);
+    }
+    const overrides = await readOverrides(options.overrides);
+    const manifest = await readManifest();
+    const primary = parseSeed(options.seed);
+    const sourceContent = await readFile(sourcePath, 'utf8');
+    const sourceNames = namesFromSource('json', sourceContent, { path: sourcePath });
+    const emittedNames = new Set([...sourceNames, ...shippedThemingPropertyNames()]);
+    const missing = validateAgainstManifest(manifest, emittedNames);
+    if (missing.length > 0)
+        throw new MissingContractTokensError(missing);
+    const theming = composeConsumerBuild({
+        seedInputs: { primary },
+        seeds: {
+            danger: SHIPPED_SEEDS.danger,
+            declaredTintHue: SHIPPED_SEEDS.declaredTintHue,
+            primary: primary.value,
+        },
+        overrides,
+        outDir: options.outDir,
+    });
+    const dtcgOutputs = await composeDtcgOutputs(sourcePath, options.outDir);
+    const cssDestination = path.join(options.outDir, 'tokens.css');
+    const collidingNames = detectCollidingNames(dtcgOutputs, cssDestination, theming.css);
+    refuseOnCollision(collidingNames);
+    const merged = dtcgOutputs.map((file) => file.destination === cssDestination
+        ? { ...file, content: `${file.content}\n${theming.css}` }
+        : file);
+    const allFiles = [...merged, ...theming.files];
+    await writeOutputs(allFiles);
+    return {
+        resolvedSeed: formatOklch(theming.primaryRecord.usedSeed),
+        seedNormalization: theming.primaryRecord.normalization,
+        files: allFiles
+            .map((file) => path.relative(options.outDir, file.destination))
+            .toSorted((a, b) => a.localeCompare(b)),
+        collidingNames,
+    };
+}
+export async function validate(options) {
+    const kind = detectSourceKind(options.source);
+    if (!kind) {
+        throw new UsageError(`"${options.source}" is neither a .css nor a .json file: validate reads the extension and never guesses the format.`);
+    }
+    if (!existsSync(options.source)) {
+        throw new UsageError(`no file found at "${options.source}"`);
+    }
+    const manifest = await readManifest();
+    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 formatRefusal = checkManifestFormatSupport(manifest);
+    const output = formatValidateReport(manifest, missing, versionSkew, { ...coreProbe, supplied });
+    let exitCode;
+    if (formatRefusal !== undefined)
+        exitCode = 1;
+    else if (coreProbe.status === 'unreadable')
+        exitCode = 2;
+    else if (versionSkew !== undefined || missing.length > 0 || coreProbe.status === 'unresolvable') {
+        exitCode = 1;
+    }
+    else
+        exitCode = 0;
+    return { exitCode, output };
+}

package/dist/lib/formats.d.ts

@@ -0,0 +1,6 @@
+import type { FlatToken } from './reader.ts';
+export declare function formatCssTokens(tokens: FlatToken[], layer?: string): string;
+export declare function formatJsTokens(tokens: FlatToken[]): string;
+export declare function formatTsDeclarations(tokens: FlatToken[]): string;
+export declare function formatJsBreakpoints(tokens: FlatToken[]): string;
+export declare function formatTsBreakpoints(tokens: FlatToken[]): string;

package/dist/lib/formats.js

@@ -0,0 +1,236 @@
+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-';
+const camelCase = (str) => str.replaceAll(/-([a-z])/g, (_, c) => c.toUpperCase());
+const toEm = (px) => `${Number((px / 16).toFixed(4))}em`;
+const AT_PROPERTY_SYNTAX = {
+    color: '<color>',
+    dimension: '<length>',
+    number: '<number>',
+    duration: '<time>',
+    fontWeight: '<number>',
+};
+const ABSOLUTE_LENGTH = /^-?(?:\d+|\d*\.\d+)(?:px|cm|mm|in|pt|pc|q)?$/i;
+const isPublic = (token) => !token.path.includes('_primitive') && token.path[0] !== 'breakpoint';
+const isReducibleDuration = (token) => token.type === 'duration' &&
+    token.path[0] === 'motion' &&
+    token.name !== 'motion-duration-instant';
+function isRegistrable(token) {
+    const syntax = AT_PROPERTY_SYNTAX[token.type];
+    if (syntax === undefined)
+        return false;
+    if (syntax !== '<length>')
+        return true;
+    return ABSOLUTE_LENGTH.test(String(token.value).trim());
+}
+function buildAtProperty(token) {
+    return [
+        `  @property ${PREFIX}${token.name} {`,
+        `    syntax: '${AT_PROPERTY_SYNTAX[token.type]}';`,
+        `    inherits: true;`,
+        `    initial-value: ${token.value};`,
+        `  }`,
+    ].join('\n');
+}
+const buildCustomProp = (token) => `    ${PREFIX}${token.name}: ${token.value};`;
+export function formatCssTokens(tokens, layer = 'tokens.defaults') {
+    const allPublic = tokens.filter((t) => isPublic(t));
+    const atPropertyBlock = allPublic
+        .filter((t) => isRegistrable(t))
+        .map((t) => buildAtProperty(t))
+        .join('\n\n');
+    const customPropsBlock = allPublic.map((t) => buildCustomProp(t)).join('\n');
+    const reducedMotionBlock = allPublic
+        .filter((t) => isReducibleDuration(t))
+        .map((t) => `      ${PREFIX}${t.name}: 0.01ms;`)
+        .join('\n');
+    return [
+        HEADER,
+        LAYER_ORDER_STATEMENT,
+        '',
+        '/**',
+        ' * @property declarations provide:',
+        ' *   - Type safety (browsers reject invalid values)',
+        ' *   - CSS transitions on custom properties (e.g. color tokens)',
+        ' *   - IDE autocomplete in supported editors',
+        ' *',
+        ' * Only tokens whose initial-value is computationally independent are',
+        ' * registered. Font-relative values (rem/em) cannot be, so those tokens',
+        ' * ship as plain custom properties below.',
+        ' */',
+        atPropertyBlock,
+        '',
+        '/**',
+        ` * Token values scoped under @layer ${layer}.`,
+        ' * Override in @layer overrides — no specificity battles, ever.',
+        ' */',
+        `@layer ${layer} {`,
+        '  :root {',
+        customPropsBlock,
+        '  }',
+        '',
+        '  /**',
+        '   * Collapse all motion durations for users who prefer reduced motion.',
+        '   * Any component using --nave-motion-duration-* gets this for free.',
+        '   */',
+        '  @media (prefers-reduced-motion: reduce) {',
+        '    :root {',
+        reducedMotionBlock,
+        '    }',
+        '  }',
+        '}',
+        '',
+    ].join('\n');
+}
+export function formatJsTokens(tokens) {
+    const entries = tokens
+        .filter((t) => isPublic(t))
+        .map((t) => `  '${PREFIX}${t.name}': ${JSON.stringify(t.value)},`)
+        .join('\n');
+    return [
+        HEADER,
+        "// This file is the JavaScript entry of @navecss/tokens. For the stylesheet, use: @import '@navecss/tokens/css';",
+        '',
+        '/** 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.',
+        ' */',
+        'export const tokens = {',
+        entries,
+        '}',
+        '',
+    ].join('\n');
+}
+export function formatTsDeclarations(tokens) {
+    const keys = tokens
+        .filter((t) => isPublic(t))
+        .map((t) => `  '${PREFIX}${t.name}': ${typeof t.value === 'number' ? 'number' : 'string'}`)
+        .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.',
+        ' */',
+        'export declare const tokens: {',
+        keys,
+        '}',
+        '',
+        'export declare type TokenName = keyof typeof tokens',
+        'export declare type TokenValue = typeof tokens[TokenName]',
+        '',
+    ].join('\n');
+}
+function buildBreakpointMap(tokens) {
+    const bpMap = {};
+    const bpTokens = tokens.filter((t) => t.path[0] === 'breakpoint');
+    for (const t of bpTokens) {
+        const key = camelCase(t.path.slice(1).join('-'));
+        bpMap[key] = t.value;
+    }
+    return bpMap;
+}
+export function formatJsBreakpoints(tokens) {
+    const bpMap = buildBreakpointMap(tokens);
+    if (Object.keys(bpMap).length === 0)
+        return '// No breakpoints defined\n';
+    const valuesLines = Object.entries(bpMap)
+        .map(([k, v]) => `  ${k}: ${v}`)
+        .join(',\n');
+    const emLines = Object.entries(bpMap)
+        .map(([k, v]) => `  ${k}: '${toEm(v)}'`)
+        .join(',\n');
+    const mediaLines = [];
+    if (bpMap.tabletPortrait !== undefined) {
+        mediaLines.push(`  phoneOnly: '(width < ${toEm(bpMap.tabletPortrait)})'`, `  tabletPortraitUp: '(width >= ${toEm(bpMap.tabletPortrait)})'`);
+    }
+    if (bpMap.tabletLandscape !== undefined) {
+        mediaLines.push(`  tabletLandscapeUp: '(width >= ${toEm(bpMap.tabletLandscape)})'`);
+    }
+    if (bpMap.desktop !== undefined) {
+        mediaLines.push(`  desktopUp: '(width >= ${toEm(bpMap.desktop)})'`);
+    }
+    if (bpMap.wide !== undefined) {
+        mediaLines.push(`  wideUp: '(width >= ${toEm(bpMap.wide)})'`);
+    }
+    return `/**
+ * Nave breakpoints — generated from tokens.json
+ * Do not edit directly. Run \`pnpm build\` in packages/tokens to regenerate.
+ *
+ * breakpoints — raw px boundary values (number, no unit)
+ *   These are the design decisions. Edit tokens.json to change them.
+ *
+ * em — boundary values in em units (base: 16px)
+ *   For reference. The media strings below use these values.
+ *
+ * media — pre-built Level 4 media query condition strings
+ *   Use as @media keys in atoms.ts and consumer atoms.
+ *   Never write breakpoint values as magic numbers in your codebase.
+ *
+ * Syntax: Level 4 range queries — (width < Xem) / (width >= Xem)
+ *   phoneOnly and tabletPortraitUp share the same boundary value (37.5em).
+ *   < is exclusive upper bound, >= is inclusive lower bound.
+ *   No overlap, no gap, no rounding issues at any device pixel ratio.
+ *
+ * Why em: resolves against the browser's default font size, a user setting
+ *   (not page zoom, which scales px and em alike).
+ */
+
+export const breakpoints = {
+${valuesLines}
+}
+
+export const em = {
+${emLines}
+}
+
+export const media = {
+${mediaLines.join(',\n')}
+}
+`;
+}
+export function formatTsBreakpoints(tokens) {
+    const bpMap = buildBreakpointMap(tokens);
+    if (Object.keys(bpMap).length === 0)
+        return '// No breakpoints defined\n';
+    const bpDecls = Object.entries(bpMap)
+        .map(([k, v]) => `  readonly ${k}: ${v}`)
+        .join('\n');
+    const emDecls = Object.entries(bpMap)
+        .map(([k, v]) => `  readonly ${k}: '${toEm(v)}'`)
+        .join('\n');
+    const mediaDecls = [];
+    if (bpMap.tabletPortrait !== undefined) {
+        mediaDecls.push(`  readonly phoneOnly: '(width < ${toEm(bpMap.tabletPortrait)})'`, `  readonly tabletPortraitUp: '(width >= ${toEm(bpMap.tabletPortrait)})'`);
+    }
+    if (bpMap.tabletLandscape !== undefined) {
+        mediaDecls.push(`  readonly tabletLandscapeUp: '(width >= ${toEm(bpMap.tabletLandscape)})'`);
+    }
+    if (bpMap.desktop !== undefined) {
+        mediaDecls.push(`  readonly desktopUp: '(width >= ${toEm(bpMap.desktop)})'`);
+    }
+    if (bpMap.wide !== undefined) {
+        mediaDecls.push(`  readonly wideUp: '(width >= ${toEm(bpMap.wide)})'`);
+    }
+    return [
+        HEADER,
+        '',
+        'export declare const breakpoints: {',
+        bpDecls,
+        '}',
+        'export declare type BreakpointName = keyof typeof breakpoints',
+        '',
+        'export declare const em: {',
+        emDecls,
+        '}',
+        '',
+        'export declare const media: {',
+        mediaDecls.join('\n'),
+        '}',
+        'export declare type MediaName = keyof typeof media',
+        '',
+    ].join('\n');
+}

package/dist/lib/json-pointer.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveTokenPointer(pointer: string, at: string, isToken: (path: string) => boolean): string;
+export declare function refuseBothReferenceForms(at: string): never;

package/dist/lib/json-pointer.js

@@ -0,0 +1,28 @@
+import { READER, SPEC_POINTER } from "./dtcg-shape.js";
+const unescapeSegment = (segment) => segment.replaceAll('~1', '/').replaceAll('~0', '~');
+function pointerToPath(pointer, at) {
+    const body = pointer.startsWith('#') ? pointer.slice(1) : pointer;
+    if (body !== '' && !body.startsWith('/')) {
+        throw new TypeError(`${READER} "${at}" carries a $ref that is not a JSON Pointer ("${pointer}"); a pointer starts at the document root, as in "#/spacing/md". ${SPEC_POINTER}`);
+    }
+    return body
+        .split('/')
+        .slice(1)
+        .map((segment) => unescapeSegment(segment));
+}
+export function resolveTokenPointer(pointer, at, isToken) {
+    const segments = pointerToPath(pointer, at);
+    const target = segments.join('.');
+    if (isToken(target))
+        return target;
+    for (let end = segments.length - 1; end > 0; end--) {
+        const prefix = segments.slice(0, end).join('.');
+        if (isToken(prefix)) {
+            throw new TypeError(`${READER} "${at}" carries a $ref pointing into a sub-value of "${prefix}" ("${pointer}"), not at a whole token. Point at the token itself, or give the inner value a token of its own and point at that. ${SPEC_POINTER}`);
+        }
+    }
+    throw new TypeError(`${READER} "${at}" carries a $ref to "${pointer}", which names no token in this source. ${SPEC_POINTER}`);
+}
+export function refuseBothReferenceForms(at) {
+    throw new TypeError(`${READER} "${at}" carries both a $ref pointer and its own $value. A node states its value one way or the other: keep one and delete the other. ${SPEC_POINTER}`);
+}

package/dist/lib/overrides.d.ts

@@ -0,0 +1,2 @@
+import type { PerStepOverrides } from './theming/pipeline.ts';
+export declare function readOverrides(filePath: string | undefined): Promise<PerStepOverrides>;

package/dist/lib/overrides.js

@@ -0,0 +1,59 @@
+import { readFile } from 'node:fs/promises';
+import { UsageError } from "./errors.js";
+import { OVERRIDE_SCALE_NAMES } from "./theming/pipeline.js";
+const OVERRIDE_STEP_NAMES = new Set(OVERRIDE_SCALE_NAMES);
+function describeJsonValue(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    return typeof value;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function validatePerStepOverrides(value, filePath) {
+    if (!isPlainObject(value)) {
+        throw new UsageError(`the per-step override file at "${filePath}" must be a JSON object, got ${describeJsonValue(value)}.`);
+    }
+    for (const [step, stepOverrides] of Object.entries(value)) {
+        if (!OVERRIDE_STEP_NAMES.has(step)) {
+            throw new UsageError(`the per-step override file at "${filePath}" names an unrecognised step "${step}" ` +
+                `(expected one of: ${OVERRIDE_SCALE_NAMES.join(', ')}).`);
+        }
+        if (!isPlainObject(stepOverrides)) {
+            throw new UsageError(`the per-step override file at "${filePath}"'s "${step}" entry must be an object ` +
+                `mapping step numbers to override amounts, got ${describeJsonValue(stepOverrides)}.`);
+        }
+        for (const [rung, amount] of Object.entries(stepOverrides)) {
+            if (!Number.isFinite(Number(rung))) {
+                throw new UsageError(`the per-step override file at "${filePath}"'s "${step}" entry has a non-numeric ` +
+                    `step key "${rung}".`);
+            }
+            if (typeof amount !== 'number' || !Number.isFinite(amount)) {
+                throw new UsageError(`the per-step override file at "${filePath}"'s "${step}.${rung}" value must be a ` +
+                    `finite number, got ${describeJsonValue(amount)}.`);
+            }
+        }
+    }
+    return value;
+}
+export async function readOverrides(filePath) {
+    if (!filePath)
+        return {};
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        throw new UsageError(`could not read the per-step override file at "${filePath}": ${error.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new UsageError(`the per-step override file at "${filePath}" is not valid JSON: ${error.message}`);
+    }
+    return validatePerStepOverrides(parsed, filePath);
+}

package/dist/lib/package-root.d.ts

@@ -0,0 +1,2 @@
+export declare const OWN_PACKAGE_NAME = "@navecss/tokens";
+export declare function findPackageRoot(fromUrl: string, expectedName?: string): string;

package/dist/lib/package-root.js

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const OWN_PACKAGE_NAME = '@navecss/tokens';
+function isPackageNamed(manifestPath, expectedName) {
+    if (!existsSync(manifestPath))
+        return false;
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        return manifest.name === expectedName;
+    }
+    catch {
+        return false;
+    }
+}
+export function findPackageRoot(fromUrl, expectedName = OWN_PACKAGE_NAME) {
+    let dir = path.dirname(fileURLToPath(fromUrl));
+    for (;;) {
+        if (isPackageNamed(path.join(dir, 'package.json'), expectedName))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            throw new Error(`could not locate ${expectedName}'s own package.json above ${fromUrl}: this module is ` +
+                `running outside its own installed directory, which happens when ${expectedName} is ` +
+                `bundled into another package's output or copied out of node_modules. Its entry points ` +
+                `read files from inside their own installed directory and cannot be bundled; ` +
+                `import them as external instead.`);
+        }
+        dir = parent;
+    }
+}

package/dist/lib/reader.d.ts

@@ -0,0 +1,8 @@
+export { kebabName } from './token-name.ts';
+export interface FlatToken {
+    readonly path: readonly string[];
+    readonly name: string;
+    readonly type: string;
+    readonly value: string | number;
+}
+export declare function readTokens(source: unknown, sourceName?: string): FlatToken[];

package/dist/lib/reader.js

@@ -0,0 +1,136 @@
+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 { nameFromPath } from "./token-name.js";
+export { kebabName } from "./token-name.js";
+const REF_RE = /^\{([^{}]+)\}$/;
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readTokenNode(node, path, inheritedType) {
+    const hasValue = '$value' in node;
+    const hasRef = typeof node.$ref === 'string';
+    if (!hasValue && !hasRef)
+        return undefined;
+    const at = path.join('.');
+    if (hasValue && hasRef)
+        refuseBothReferenceForms(at);
+    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}"`);
+    }
+    const token = { path, rawValue: node.$value, type };
+    if (hasRef)
+        token.ref = node.$ref;
+    return token;
+}
+function collectRawTokens(node, path, inheritedType, out) {
+    if (!isPlainObject(node)) {
+        throw new TypeError(`DTCG 2025.10 reader: expected an object at "${path.join('.')}", got ${JSON.stringify(node)}`);
+    }
+    if ('value' in node && !('$value' in node)) {
+        throw new TypeError(`DTCG 2025.10 reader: legacy token shape at "${path.join('.')}" — carries "value"/"type" ` +
+            `instead of "$value"/"$type"`);
+    }
+    const token = readTokenNode(node, path, inheritedType);
+    if (token !== undefined) {
+        out.push(token);
+        return;
+    }
+    const groupType = typeof node.$type === 'string' ? node.$type : inheritedType;
+    for (const [key, child] of Object.entries(node)) {
+        if (key.startsWith('$'))
+            continue;
+        collectRawTokens(child, [...path, key], groupType, out);
+    }
+}
+function classifyUnreadableNode(token) {
+    const at = token.path.join('.');
+    const typeRefusal = refuseTypeReason(token.type, at);
+    if (typeRefusal !== undefined)
+        return { kind: 'typeRefusal', typeRefusal };
+    if (token.ref !== undefined)
+        return undefined;
+    const draft = classifyDraftShape(at, token.type, token.rawValue);
+    if (draft !== undefined)
+        return { draft, kind: 'draft' };
+    const malformed = classifyMalformed(at, token.type, token.rawValue);
+    return malformed === undefined ? undefined : { kind: 'malformed', malformed };
+}
+function refuseUnreadableNodes(raw, sourceName) {
+    const drafts = [];
+    const malformed = [];
+    const typeRefusals = [];
+    for (const token of raw) {
+        const found = classifyUnreadableNode(token);
+        if (found === undefined)
+            continue;
+        if (found.kind === 'typeRefusal')
+            typeRefusals.push(found.typeRefusal);
+        else if (found.kind === 'draft')
+            drafts.push(found.draft);
+        else
+            malformed.push(found.malformed);
+    }
+    if (typeRefusals.length > 0) {
+        throw new DtcgShapeRefusal(typeRefusals.join('\n'), []);
+    }
+    if (drafts.length > 0 || malformed.length > 0) {
+        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);
+    refuseUnreadableNodes(raw, sourceName);
+    const context = {
+        byPath: new Map(raw.map((t) => [t.path.join('.'), t])),
+        resolved: new Map(),
+        visiting: new Set(),
+    };
+    return raw.map((token) => ({
+        path: token.path,
+        name: nameFromPath(token.path),
+        type: token.type,
+        value: resolveValue(token, context),
+    }));
+}

package/dist/lib/theming/adjacency-source.d.ts

@@ -0,0 +1,20 @@
+type PairClass = 'text' | 'non-text';
+export interface Adjacency {
+    subject: string;
+    against: string;
+    class: PairClass;
+}
+export declare function materializeAdjacency(source: unknown): Adjacency[];
+export declare const ADJACENCY: readonly Adjacency[];
+export declare const ADJACENCY_EXCLUSIONS: Readonly<Record<string, string>>;
+export declare const ADJACENCY_OPEN: Readonly<Record<string, string>>;
+declare const measuredOpenSlotsBrand: unique symbol;
+export type MeasuredOpenSlots = readonly string[] & {
+    readonly [measuredOpenSlotsBrand]: true;
+};
+export interface OrphanCheckResult {
+    open: MeasuredOpenSlots;
+    excluded: readonly string[];
+}
+export declare function assertNoOrphanedSemanticSlot(slots: readonly string[], adjacency?: readonly Adjacency[], exclusions?: Readonly<Record<string, string>>, open?: Readonly<Record<string, string>>): OrphanCheckResult;
+export {};