@reforma/project-tokens 0.0.1

package/dist/compilation/validation.js

@@ -0,0 +1,179 @@
+import { isDtcgColorValue } from '../color-value.js';
+const FONT_WEIGHTS = new Set([
+    'black',
+    'bold',
+    'book',
+    'demi-bold',
+    'extra-black',
+    'extra-bold',
+    'extra-light',
+    'hairline',
+    'heavy',
+    'light',
+    'medium',
+    'normal',
+    'regular',
+    'semi-bold',
+    'thin',
+    'ultra-black',
+    'ultra-bold',
+    'ultra-light',
+]);
+const STROKE_STYLES = new Set([
+    'dashed',
+    'dotted',
+    'double',
+    'groove',
+    'inset',
+    'outset',
+    'ridge',
+    'solid',
+]);
+// Terrazzo accepts additional types and CSS units; this gate keeps the final DTCG boundary strict.
+export function validateTokenValue(type, value) {
+    switch (type) {
+        case 'color':
+            return isDtcgColorValue(value);
+        case 'dimension':
+            return isDimension(value);
+        case 'duration':
+            return isDuration(value);
+        case 'number':
+            return isFiniteNumber(value);
+        case 'fontFamily':
+            return isFontFamily(value);
+        case 'fontWeight':
+            return isFontWeight(value);
+        case 'cubicBezier':
+            return isCubicBezier(value);
+        case 'strokeStyle':
+            return isStrokeStyle(value);
+        case 'border':
+            return isBorder(value);
+        case 'transition':
+            return isTransition(value);
+        case 'shadow':
+            return isShadow(value);
+        case 'gradient':
+            return isGradient(value);
+        case 'typography':
+            return isTypography(value);
+        default:
+            return false;
+    }
+}
+export function validateAuthoredColorValues(type, value) {
+    if (isReference(value))
+        return true;
+    if (type === 'color') {
+        return containsReference(value) || isDtcgColorValue(value);
+    }
+    if (type === 'border' && isObject(value) && 'color' in value) {
+        return isAuthoredColor(value.color);
+    }
+    if (type === 'gradient' && Array.isArray(value)) {
+        return value.every(stop => !isObject(stop) || !('color' in stop) || isAuthoredColor(stop.color));
+    }
+    if (type === 'shadow') {
+        const layers = Array.isArray(value) ? value : [value];
+        return layers.every(layer => !isObject(layer) || !('color' in layer) || isAuthoredColor(layer.color));
+    }
+    return true;
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isAuthoredColor(value) {
+    return isReference(value) || containsReference(value) || isDtcgColorValue(value);
+}
+function isReference(value) {
+    return typeof value === 'string' && /^\{[^{}]+\}$/.test(value)
+        || isObject(value) && typeof value.$ref === 'string';
+}
+function containsReference(value) {
+    if (isReference(value))
+        return true;
+    if (Array.isArray(value))
+        return value.some(containsReference);
+    if (isObject(value))
+        return Object.values(value).some(containsReference);
+    return false;
+}
+function isDimension(value) {
+    return isObject(value)
+        && isFiniteNumber(value.value)
+        && ['px', 'rem'].includes(value.unit);
+}
+function isDuration(value) {
+    return isObject(value)
+        && isFiniteNumber(value.value)
+        && ['ms', 's'].includes(value.unit);
+}
+function isFontFamily(value) {
+    return typeof value === 'string'
+        || Array.isArray(value)
+            && value.length > 0
+            && value.every(name => typeof name === 'string');
+}
+function isFontWeight(value) {
+    return isFiniteNumber(value) && value >= 1 && value <= 1000
+        || typeof value === 'string' && FONT_WEIGHTS.has(value);
+}
+function isCubicBezier(value) {
+    return Array.isArray(value)
+        && value.length === 4
+        && value.every(isFiniteNumber)
+        && value[0] >= 0
+        && value[0] <= 1
+        && value[2] >= 0
+        && value[2] <= 1;
+}
+function isStrokeStyle(value) {
+    if (typeof value === 'string') {
+        return STROKE_STYLES.has(value);
+    }
+    return isObject(value)
+        && Array.isArray(value.dashArray)
+        && value.dashArray.every(isDimension)
+        && ['round', 'butt', 'square'].includes(value.lineCap);
+}
+function isBorder(value) {
+    return isObject(value)
+        && isDimension(value.width)
+        && isDtcgColorValue(value.color)
+        && isStrokeStyle(value.style);
+}
+function isTransition(value) {
+    return isObject(value)
+        && isDuration(value.duration)
+        && isDuration(value.delay)
+        && isCubicBezier(value.timingFunction);
+}
+function isShadow(value) {
+    if (Array.isArray(value)) {
+        return value.every(layer => !Array.isArray(layer) && isShadow(layer));
+    }
+    return isObject(value)
+        && isDtcgColorValue(value.color)
+        && ['offsetX', 'offsetY', 'blur', 'spread'].every(key => isDimension(value[key]))
+        && (value.inset === undefined || typeof value.inset === 'boolean');
+}
+function isGradient(value) {
+    return Array.isArray(value) && value.every(stop => (isObject(stop)
+        && isDtcgColorValue(stop.color)
+        && isFiniteNumber(stop.position)
+        && stop.position >= 0
+        && stop.position <= 1));
+}
+function isTypography(value) {
+    return isObject(value)
+        && isFontFamily(value.fontFamily)
+        && isDimension(value.fontSize)
+        && isFontWeight(value.fontWeight)
+        && isDimension(value.letterSpacing)
+        && isFiniteNumber(value.lineHeight)
+        && Object.keys(value).every(key => (['fontFamily', 'fontSize', 'fontWeight', 'letterSpacing', 'lineHeight'].includes(key)));
+}

package/dist/compilation/web-projection.d.ts

@@ -0,0 +1,31 @@
+import type { TokenNormalized } from '@terrazzo/parser';
+import type { TokenPermutation } from './compiler.js';
+interface ModifierProjection {
+    name: string;
+    contexts?: Record<string, unknown>;
+    default?: string;
+}
+export declare function serializeTokenCss(token: TokenNormalized, path: string, tokensSet: Record<string, TokenNormalized>, input: Record<string, string>): {
+    [k: string]: string;
+};
+export declare function createPermutationSelector(input: Record<string, string>): string;
+export declare function buildWebProjection(permutations: TokenPermutation[], cssNames: Iterable<string>, defaultInput: Record<string, string>, modifiers: ModifierProjection[]): {
+    tokensCss: string;
+    tailwindCss: string;
+    modes: {
+        version: number;
+        default: string;
+        defaultInput: Record<string, string>;
+        modifiers: {
+            name: string;
+            contexts: string[];
+            default: string | null;
+        }[];
+        permutations: {
+            input: Record<string, string>;
+            selector: string;
+        }[];
+    };
+};
+export {};
+//# sourceMappingURL=web-projection.d.ts.map

package/dist/compilation/web-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-projection.d.ts","sourceRoot":"","sources":["../../src/compilation/web-projection.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAgB,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAoBpE,UAAU,kBAAkB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;EA2DhC;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,UAStE;AAED,wBAAgB,kBAAkB,CAC9B,YAAY,EAAE,gBAAgB,EAAE,EAChC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC1B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,SAAS,EAAE,kBAAkB,EAAE;;;;;;;;;;;;;;;;;EAgClC"}

package/dist/compilation/web-projection.js

@@ -0,0 +1,136 @@
+import { tokenToColor } from '@terrazzo/token-tools';
+import { transformCSSValue, transformDimension, transformShadowLayer, transformStrokeStyle, } from '@terrazzo/token-tools/css';
+import { serialize } from 'colorjs.io/fn';
+const GENERIC_FONT_FAMILIES = new Set([
+    'cursive',
+    'emoji',
+    'fangsong',
+    'fantasy',
+    'math',
+    'monospace',
+    'sans-serif',
+    'serif',
+    'system-ui',
+    'ui-monospace',
+    'ui-rounded',
+    'ui-sans-serif',
+    'ui-serif',
+]);
+const TAILWIND_NAMESPACE = /^--(color|spacing|font|text|font-weight|tracking|leading|breakpoint|container|radius|shadow|inset-shadow|drop-shadow|blur|perspective|aspect|ease|animate)-/;
+export function serializeTokenCss(token, path, tokensSet, input) {
+    const name = `--${path.replace(/\.\$root$/, '').replaceAll('.', '-')}`;
+    const cssOptions = { tokensSet, permutation: input };
+    const color = (value) => (serialize(tokenToColor(value), { precision: 15 }));
+    // Preserve native color spaces; Terrazzo's gamut fallback uses incompatible Color.js IDs.
+    let value;
+    switch (token.$type) {
+        case 'color':
+            value = color(token.$value);
+            break;
+        case 'border':
+            value = [
+                transformDimension({ $value: token.$value.width }, cssOptions),
+                transformStrokeStyle({ $value: token.$value.style }, cssOptions),
+                color(token.$value.color),
+            ].join(' ');
+            break;
+        case 'shadow':
+            value = token.$value.map(layer => transformShadowLayer(layer, { ...cssOptions, colorValue: color(layer.color) })).join(', ');
+            break;
+        case 'gradient':
+            value = token.$value.map(stop => (`${color(stop.color)} ${stop.position * 100}%`)).join(', ');
+            break;
+        default:
+            value = transformCSSValue({ ...token, aliasChain: [], partialAliasOf: undefined }, cssOptions);
+    }
+    if (token.$type === 'fontFamily') {
+        value = serializeFontFamily(token.$value);
+    }
+    if (token.$type === 'typography' && typeof value === 'object') {
+        value['font-family'] = serializeFontFamily(token.$value.fontFamily);
+    }
+    const entries = typeof value === 'string' ? [['', value]] : Object.entries(value);
+    return Object.fromEntries(entries.map(([suffix, propertyValue]) => [
+        `${name}${suffix ? `-${suffix}` : ''}`,
+        propertyValue,
+    ]));
+}
+export function createPermutationSelector(input) {
+    const attributes = Object.entries(input).map(([axis, value]) => {
+        const name = axis === 'mode'
+            ? 'data-theme'
+            : `data-token-${cssIdentifier(axis)}`;
+        return `[${name}=${cssString(value)}]`;
+    });
+    return `html${attributes.join('')}`;
+}
+export function buildWebProjection(permutations, cssNames, defaultInput, modifiers) {
+    const defaults = Object.assign({}, ...permutations[0].tokens.map(token => token.css));
+    const overrides = permutations.map(permutation => (buildPermutationOverrides(permutation, defaults))).join('');
+    const tailwind = Object.fromEntries([...cssNames]
+        .filter(name => TAILWIND_NAMESPACE.test(name))
+        .map(name => [name, `var(${cssIdentifier(name)})`]));
+    return {
+        tokensCss: cssBlock(':root', defaults) + overrides,
+        tailwindCss: Object.keys(tailwind).length > 0
+            ? cssBlock('@theme inline', tailwind)
+            : '',
+        modes: {
+            version: 1,
+            default: defaultInput.mode ?? null,
+            defaultInput,
+            modifiers: modifiers.map(modifier => ({
+                name: modifier.name,
+                contexts: Object.keys(modifier.contexts),
+                default: modifier.default ?? null,
+            })),
+            permutations: permutations.map(({ input, selector }) => ({ input, selector })),
+        },
+    };
+}
+function cssIdentifier(value) {
+    return [...value].map(character => {
+        const codePoint = character.codePointAt(0);
+        return /[a-zA-Z0-9_-]/.test(character) || codePoint >= 128
+            ? character
+            : `\\${codePoint.toString(16)} `;
+    }).join('');
+}
+function cssString(value) {
+    const escaped = [...value].map(character => {
+        const codePoint = character.codePointAt(0);
+        return character === '"' || character === '\\' || codePoint < 32 || codePoint === 127
+            ? `\\${codePoint.toString(16)} `
+            : character;
+    }).join('');
+    return `"${escaped}"`;
+}
+function serializeFontFamily(value) {
+    const names = Array.isArray(value) ? value : [value];
+    return names.map(name => (GENERIC_FONT_FAMILIES.has(name) ? name : cssString(name))).join(', ');
+}
+function buildPermutationOverrides(permutation, defaults) {
+    const values = {};
+    for (const token of permutation.tokens) {
+        for (const [name, value] of Object.entries(token.css)) {
+            if (defaults[name] !== value) {
+                values[name] = value;
+            }
+        }
+    }
+    for (const name of Object.keys(defaults)) {
+        if (!permutation.tokens.some(token => name in token.css)) {
+            values[name] = 'initial';
+        }
+    }
+    return Object.keys(values).length > 0
+        ? `\n${cssBlock(permutation.selector, values)}`
+        : '';
+}
+function cssBlock(selector, values) {
+    const declarations = Object.entries(values)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, value]) => `  ${cssIdentifier(name)}: ${value};`)
+        .join('\n');
+    return `${selector} {\n${declarations}\n}\n`;
+}

package/dist/generation.d.ts

@@ -0,0 +1,6 @@
+import { type TokenCompilation, type TokenCompilationOptions } from './compilation/compiler.js';
+export declare function readTokenDependency(root: string, path: string): Promise<string | null>;
+export declare function withTokenCompilationLock<T>(options: TokenCompilationOptions, work: (generate: (expectedRevision?: string) => Promise<TokenCompilation>) => Promise<T>): Promise<T>;
+/** Compile and replace generated files under the same lock used by token transactions. */
+export declare function buildProjectTokens(options: TokenCompilationOptions): Promise<TokenCompilation>;
+//# sourceMappingURL=generation.d.ts.map

package/dist/generation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation.d.ts","sourceRoot":"","sources":["../src/generation.ts"],"names":[],"mappings":"AAKA,OAAO,EAAwB,KAAK,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAYtH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,0BAYnE;AAED,wBAAsB,wBAAwB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,gBAAgB,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAoIxL;AAED,0FAA0F;AAC1F,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAEpG"}

package/dist/generation.js

@@ -0,0 +1,186 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, readlink, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { compileProjectTokens } from './compilation/compiler.js';
+async function readOptional(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function readTokenDependency(root, path) {
+    try {
+        root = await realpath(root);
+        const actual = await realpath(resolve(root, path));
+        const rel = relative(root, actual);
+        if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`))
+            return null;
+        return await readOptional(actual);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function withTokenCompilationLock(options, work) {
+    const root = await realpath(options.workspaceRoot);
+    const directory = resolve(root, dirname(options.entry ?? '.reforma/tokens/tokens.resolver.json'), '.generated');
+    // Check every existing ancestor before creating output or following a symlink.
+    for (let path = directory; path !== root; path = dirname(path)) {
+        const rel = relative(root, path);
+        if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`))
+            throw new Error('Output escapes the workspace.');
+        try {
+            if ((await lstat(path)).isSymbolicLink())
+                throw new Error(`Output ancestor is a symlink: ${path}`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    await mkdir(directory, { recursive: true });
+    // Shared filesystem protocol for CLI and sandbox writers; all generated writes hold this lock.
+    const lock = join(directory, '.compile.lock');
+    const namespace = await readlink('/proc/self/ns/pid').catch(() => null);
+    const deadline = Date.now() + 10_000;
+    while (true) {
+        if (Date.now() > deadline)
+            throw new Error('Timed out waiting for the token compilation lock.');
+        try {
+            await mkdir(lock);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const identity = await lstat(lock).catch(() => undefined);
+            if (!identity)
+                continue;
+            if (!identity.isDirectory() || identity.isSymbolicLink())
+                throw new Error('The token compilation lock must be a directory.');
+            try {
+                const owner = JSON.parse(await readFile(join(lock, 'owner.json'), 'utf8'));
+                // Sandbox children have their own PID namespace; their PIDs are not controller PIDs.
+                if (owner.namespace && owner.namespace !== namespace) {
+                    await delay(40);
+                    continue;
+                }
+                process.kill(owner.pid, 0);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'ESRCH') {
+                    const claim = join(lock, '.reclaim');
+                    try {
+                        await mkdir(claim);
+                    }
+                    catch (error) {
+                        if (['EEXIST', 'ENOENT'].includes(error.code ?? ''))
+                            continue;
+                        throw error;
+                    }
+                    const current = await stat(lock);
+                    if (current.ino !== identity.ino || current.dev !== identity.dev) {
+                        await rm(claim, { recursive: true });
+                        continue;
+                    }
+                    const abandoned = `${lock}.${randomUUID()}`;
+                    await rename(lock, abandoned);
+                    await rm(abandoned, { recursive: true });
+                    continue;
+                }
+                if (code !== 'ENOENT' && code !== 'EPERM')
+                    throw error;
+            }
+            await delay(40);
+        }
+    }
+    try {
+        const ownerFile = join(lock, `owner-${randomUUID()}.json`);
+        await writeFile(ownerFile, JSON.stringify({ pid: process.pid, namespace }));
+        await rename(ownerFile, join(lock, 'owner.json'));
+        return await work(async (expectedRevision) => {
+            let stage;
+            try {
+                let result = await compileProjectTokens(options);
+                for (let attempt = 0; result.ok && attempt < 5; attempt++) {
+                    const unchanged = await Promise.all(result.dependencies.map(async (file) => {
+                        const text = await readTokenDependency(root, file.path);
+                        return (text === null ? null : createHash('sha256').update(text).digest('hex')) === file.hash;
+                    }));
+                    if (unchanged.every(Boolean))
+                        break;
+                    if (attempt === 4)
+                        throw new Error('Token sources keep changing; generation was not replaced.');
+                    result = await compileProjectTokens(options);
+                }
+                if (expectedRevision && result.revision !== expectedRevision) {
+                    throw Object.assign(new Error('Token sources changed before generation.'), { code: 'REVISION_CONFLICT' });
+                }
+                if (!result.ok || !result.output)
+                    return result;
+                const output = {
+                    'tokens.css': result.output.tokensCss,
+                    'tailwind.css': result.output.tailwindCss,
+                    'modes.json': result.output.modesJson,
+                };
+                const changes = [];
+                for (const [name, text] of Object.entries(output)) {
+                    const destination = join(directory, name);
+                    if ((await lstat(destination).catch((error) => {
+                        if (error.code === 'ENOENT')
+                            return null;
+                        throw error;
+                    }))?.isSymbolicLink())
+                        throw new Error(`Generated output is a symlink: ${name}`);
+                    const previous = await readOptional(destination);
+                    if (previous !== text)
+                        changes.push({ name, text, previous });
+                }
+                if (!changes.length)
+                    return result;
+                stage = join(directory, `.stage-${randomUUID()}`);
+                await mkdir(stage);
+                for (const { name, text } of changes)
+                    await writeFile(join(stage, name), text);
+                const replaced = [];
+                try {
+                    for (const change of changes) {
+                        await rename(join(stage, change.name), join(directory, change.name));
+                        replaced.push(change);
+                    }
+                }
+                catch (error) {
+                    for (const { name, previous } of replaced.reverse()) {
+                        if (previous === null)
+                            await rm(join(directory, name), { force: true });
+                        else {
+                            await writeFile(join(stage, name), previous);
+                            await rename(join(stage, name), join(directory, name));
+                        }
+                    }
+                    throw error;
+                }
+                return result;
+            }
+            finally {
+                if (stage)
+                    await rm(stage, { recursive: true, force: true });
+            }
+        });
+    }
+    finally {
+        await rm(lock, { recursive: true, force: true });
+    }
+}
+/** Compile and replace generated files under the same lock used by token transactions. */
+export async function buildProjectTokens(options) {
+    return withTokenCompilationLock(options, (generate) => generate());
+}

package/dist/json-pointer.d.ts

@@ -0,0 +1,5 @@
+export declare function encodeJsonPointer(parts: string[]): string;
+export declare function decodeJsonPointer(value: string): string[];
+export declare function readJsonPointer(root: unknown, parts: string[]): any;
+export declare function encodeJsonPointerPart(part: string): string;
+//# sourceMappingURL=json-pointer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json-pointer.d.ts","sourceRoot":"","sources":["../src/json-pointer.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAMhD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,YAY9C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAiB7D;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,UAEjD"}

package/dist/json-pointer.js

@@ -0,0 +1,36 @@
+export function encodeJsonPointer(parts) {
+    if (parts.length === 0) {
+        return '';
+    }
+    return '/' + parts.map(encodeJsonPointerPart).join('/');
+}
+export function decodeJsonPointer(value) {
+    const fragment = value.startsWith('#') ? decodeURIComponent(value.slice(1)) : value;
+    if (fragment === '') {
+        return [];
+    }
+    if (!fragment.startsWith('/') || /~(?![01])/.test(fragment)) {
+        throw new Error(`Invalid JSON Pointer: ${value}`);
+    }
+    return fragment.slice(1).split('/').map(decodeJsonPointerPart);
+}
+export function readJsonPointer(root, parts) {
+    let value = root;
+    for (const part of parts) {
+        const missing = !value
+            || typeof value !== 'object'
+            || !Object.hasOwn(value, part)
+            || Array.isArray(value) && !/^(0|[1-9]\d*)$/.test(part);
+        if (missing) {
+            throw new Error(`Missing JSON Pointer: ${encodeJsonPointer(parts)}`);
+        }
+        value = value[part];
+    }
+    return value;
+}
+export function encodeJsonPointerPart(part) {
+    return part.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+function decodeJsonPointerPart(part) {
+    return part.replaceAll('~1', '/').replaceAll('~0', '~');
+}

package/dist/mutation/documents.d.ts

@@ -0,0 +1,20 @@
+import { type TokenFileChange } from './types.js';
+import type { TokenCompilation, TokenCompilationOptions } from '../compilation/compiler.js';
+export declare class TokenMutationDocuments {
+    private readonly workspaceRoot;
+    readonly entryFile: string;
+    private readonly current;
+    private readonly original;
+    private constructor();
+    static load(options: Omit<TokenCompilationOptions, 'documents'>, compilation: TokenCompilation): Promise<TokenMutationDocuments>;
+    get values(): Readonly<Record<string, string>>;
+    get files(): string[];
+    has(file: string): boolean;
+    parse(file: string): any;
+    read(file: string, path: string[]): any;
+    create(file: string, text?: string): void;
+    edit(file: string, path: Array<string | number>, value: unknown): void;
+    assertAvailable(file: string): Promise<void>;
+    changes(): TokenFileChange[];
+}
+//# sourceMappingURL=documents.d.ts.map

package/dist/mutation/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/mutation/documents.ts"],"names":[],"mappings":"AAKA,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAEtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAE5F,qBAAa,sBAAsB;IAI3B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAElD,OAAO,eAMN;IAED,OAAa,IAAI,CACb,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,WAAW,CAAC,EACnD,WAAW,EAAE,gBAAgB,mCA0BhC;IAED,IAAI,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAE7C;IAED,IAAI,KAAK,aAER;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,WAEf;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAEvB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAIhC;IAED,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAS,QAEjC;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,QAY9D;IAEK,eAAe,CAAC,IAAI,EAAE,MAAM,iBAQjC;IAED,OAAO,IAAI,eAAe,EAAE,CAQ3B;CACJ"}