@navecss/tokens 0.1.0 → 0.2.0

package/dist/lib/theming/comment-open-tracker.js

@@ -1,15 +1,37 @@
 export function linesThatBeginInsideAnUnclosedComment(lines) {
     const beginningsInsideAnUnclosedComment = new Set();
-    let isInsideAnOpenComment = false;
-    for (const [index, line] of lines.entries()) {
-        if (isInsideAnOpenComment)
-            beginningsInsideAnUnclosedComment.add(index);
-        isInsideAnOpenComment = isLineStillInsideAnOpenCommentAfterScanning(line, isInsideAnOpenComment);
+    const readings = [
+        AS_THE_TOKENIZER_READS_IT,
+        RESUMING_PAST_AN_UNCLOSED_QUOTE,
+        RESUMING_WITH_NO_FURTHER_STRINGS,
+    ];
+    for (const reading of readings) {
+        let isInsideAnOpenComment = false;
+        for (const [index, line] of lines.entries()) {
+            if (isInsideAnOpenComment)
+                beginningsInsideAnUnclosedComment.add(index);
+            isInsideAnOpenComment = isLineStillInsideAnOpenComment(line, isInsideAnOpenComment, reading);
+        }
     }
+    markLinesFlaggedByTheUrlOpaqueReading(lines, beginningsInsideAnUnclosedComment);
+    markLinesFlaggedByTheEscapedLineBreakReading(lines, beginningsInsideAnUnclosedComment);
     return beginningsInsideAnUnclosedComment;
 }
-function isLineStillInsideAnOpenCommentAfterScanning(line, wasInsideAnOpenComment) {
+const AS_THE_TOKENIZER_READS_IT = {
+    resumesAtEndOfLineAfterAnUnclosedQuote: true,
+    aLaterQuoteCanStillOpenAString: false,
+};
+const RESUMING_PAST_AN_UNCLOSED_QUOTE = {
+    resumesAtEndOfLineAfterAnUnclosedQuote: false,
+    aLaterQuoteCanStillOpenAString: true,
+};
+const RESUMING_WITH_NO_FURTHER_STRINGS = {
+    resumesAtEndOfLineAfterAnUnclosedQuote: false,
+    aLaterQuoteCanStillOpenAString: false,
+};
+function isLineStillInsideAnOpenComment(line, wasInsideAnOpenComment, reading) {
     let isInsideAnOpenComment = wasInsideAnOpenComment;
+    let hasPassedAnUnclosedQuoteOnThisLine = false;
     let cursor = 0;
     while (cursor < line.length) {
         if (isInsideAnOpenComment) {
@@ -21,8 +43,17 @@ function isLineStillInsideAnOpenCommentAfterScanning(line, wasInsideAnOpenCommen
             continue;
         }
         const character = line[cursor];
-        if (character === '"' || character === "'") {
-            cursor = indexAfterAStringLiteral(line, cursor, character);
+        const canThisQuoteOpenAString = isAQuoteCharacter(character) &&
+            (reading.aLaterQuoteCanStillOpenAString || !hasPassedAnUnclosedQuoteOnThisLine);
+        if (canThisQuoteOpenAString) {
+            const afterTheString = indexAfterAStringLiteral(line, cursor, character);
+            if (afterTheString === -1) {
+                hasPassedAnUnclosedQuoteOnThisLine = true;
+                cursor = reading.resumesAtEndOfLineAfterAnUnclosedQuote ? line.length : cursor + 1;
+            }
+            else {
+                cursor = afterTheString;
+            }
             continue;
         }
         if (line.startsWith('/*', cursor)) {
@@ -34,6 +65,9 @@ function isLineStillInsideAnOpenCommentAfterScanning(line, wasInsideAnOpenCommen
     }
     return isInsideAnOpenComment;
 }
+function isAQuoteCharacter(character) {
+    return character === '"' || character === "'";
+}
 function indexAfterAStringLiteral(line, quoteIndex, quote) {
     let cursor = quoteIndex + 1;
     while (cursor < line.length) {
@@ -45,5 +79,192 @@ function indexAfterAStringLiteral(line, quoteIndex, quote) {
             return cursor + 1;
         cursor += 1;
     }
-    return line.length;
+    return -1;
+}
+function markLinesFlaggedByTheUrlOpaqueReading(lines, into) {
+    let state = { isInsideAnOpenComment: false, urlCarry: 'none' };
+    for (const [index, line] of lines.entries()) {
+        if (state.isInsideAnOpenComment)
+            into.add(index);
+        state = scanLineWithOpaqueUrlContent(line, state);
+    }
+}
+function resumeUrlCarry(line, urlCarry) {
+    if (urlCarry === 'none')
+        return 0;
+    return urlCarry === 'pending' ? resolveUrlContent(line, 0) : indexAfterUnquotedUrlContent(line, 0);
+}
+function scanLineWithOpaqueUrlContent(line, state) {
+    const cursor = resumeUrlCarry(line, state.urlCarry);
+    if (typeof cursor === 'string')
+        return { isInsideAnOpenComment: false, urlCarry: cursor };
+    return scanLineForOpaqueUrlContentAndComments(line, state.isInsideAnOpenComment, cursor);
+}
+function scanLineForOpaqueUrlContentAndComments(line, wasInsideAnOpenComment, cursor) {
+    let isInsideAnOpenComment = wasInsideAnOpenComment;
+    let index = cursor;
+    while (index < line.length) {
+        if (isInsideAnOpenComment) {
+            const closerIndex = line.indexOf('*/', index);
+            if (closerIndex === -1)
+                return { isInsideAnOpenComment: true, urlCarry: 'none' };
+            isInsideAnOpenComment = false;
+            index = closerIndex + 2;
+            continue;
+        }
+        const urlLookup = tryToSkipAnUnquotedUrlToken(line, index);
+        if (typeof urlLookup === 'string')
+            return { isInsideAnOpenComment: false, urlCarry: urlLookup };
+        if (urlLookup !== undefined) {
+            index = urlLookup;
+            continue;
+        }
+        const character = line[index];
+        if (isAQuoteCharacter(character)) {
+            const afterTheString = indexAfterAStringLiteral(line, index, character);
+            index = afterTheString === -1 ? line.length : afterTheString;
+            continue;
+        }
+        if (line.startsWith('/*', index)) {
+            isInsideAnOpenComment = true;
+            index += 2;
+            continue;
+        }
+        index += 1;
+    }
+    return { isInsideAnOpenComment, urlCarry: 'none' };
+}
+function isAnIdentifierCharacter(character) {
+    return (character !== undefined && (/[A-Za-z0-9_-]/.test(character) || character.codePointAt(0) > 0x7f));
+}
+function tryToSkipAnUnquotedUrlToken(line, cursor) {
+    if (isAnIdentifierCharacter(line[cursor - 1]) || /[#@]/.test(line[cursor - 1]))
+        return undefined;
+    if (!/^url\(/i.test(line.slice(cursor, cursor + 4)))
+        return undefined;
+    return resolveUrlContent(line, cursor + 4);
+}
+function resolveUrlContent(line, cursor) {
+    let index = cursor;
+    while (index < line.length && /\s/.test(line[index]))
+        index += 1;
+    if (index === line.length)
+        return 'pending';
+    if (isAQuoteCharacter(line[index]))
+        return index;
+    return indexAfterUnquotedUrlContent(line, index);
+}
+function indexAfterUnquotedUrlContent(line, contentStart) {
+    let index = contentStart;
+    while (index < line.length) {
+        if (line[index] === '\\' && index + 1 < line.length) {
+            index += 2;
+            continue;
+        }
+        if (line[index] === ')')
+            return index + 1;
+        index += 1;
+    }
+    return 'contentOpen';
+}
+function markLinesFlaggedByTheEscapedLineBreakReading(lines, into) {
+    let state = NOTHING_IS_OPEN;
+    for (const [index, line] of lines.entries()) {
+        if (state.isInsideAnOpenComment)
+            into.add(index);
+        state = scanLineAcrossEscapedLineBreaksAndUrls(line, state);
+    }
+}
+const NOTHING_IS_OPEN = {
+    isInsideAnOpenComment: false,
+    urlCarry: 'none',
+    openStringQuote: undefined,
+};
+const STILL_INSIDE_AN_OPEN_COMMENT = {
+    ...NOTHING_IS_OPEN,
+    isInsideAnOpenComment: true,
+};
+function scanLineAcrossEscapedLineBreaksAndUrls(line, state) {
+    if (state.openStringQuote !== undefined) {
+        return resumeAnOpenStringCarriedIntoThisLine(line, state.isInsideAnOpenComment, state.openStringQuote);
+    }
+    const cursor = resumeUrlCarry(line, state.urlCarry);
+    if (typeof cursor === 'string')
+        return { ...NOTHING_IS_OPEN, urlCarry: cursor };
+    return scanFromStartOfLine(line, state.isInsideAnOpenComment, cursor);
+}
+function resumeAnOpenStringCarriedIntoThisLine(line, isInsideAnOpenComment, openStringQuote) {
+    const outcome = scanAPossiblyContinuedStringLiteral(line, -1, openStringQuote);
+    if (outcome.kind === 'continuesAcrossAnEscapedLineBreak') {
+        return { ...NOTHING_IS_OPEN, isInsideAnOpenComment, openStringQuote };
+    }
+    if (outcome.kind === 'doesNotClose') {
+        return { ...NOTHING_IS_OPEN, isInsideAnOpenComment };
+    }
+    return scanFromStartOfLine(line, isInsideAnOpenComment, outcome.indexAfter);
+}
+function stringStep(outcome, endOfLine) {
+    if (outcome.kind === 'closes')
+        return outcome.indexAfter;
+    if (outcome.kind === 'continuesAcrossAnEscapedLineBreak')
+        return undefined;
+    return endOfLine;
+}
+function scanFromStartOfLine(line, wasInsideAnOpenComment, cursor) {
+    let isInsideAnOpenComment = wasInsideAnOpenComment;
+    let index = cursor;
+    while (index < line.length) {
+        if (isInsideAnOpenComment) {
+            const closerIndex = line.indexOf('*/', index);
+            if (closerIndex === -1)
+                return STILL_INSIDE_AN_OPEN_COMMENT;
+            isInsideAnOpenComment = false;
+            index = closerIndex + 2;
+            continue;
+        }
+        const urlLookup = tryToSkipAnUnquotedUrlToken(line, index);
+        if (urlLookup !== undefined) {
+            if (typeof urlLookup === 'string')
+                return { ...NOTHING_IS_OPEN, urlCarry: urlLookup };
+            index = urlLookup;
+            continue;
+        }
+        const character = line[index];
+        if (isAQuoteCharacter(character)) {
+            const outcome = scanAPossiblyContinuedStringLiteral(line, index, character);
+            const target = stringStep(outcome, line.length);
+            if (target === undefined)
+                return { ...NOTHING_IS_OPEN, openStringQuote: character };
+            index = target;
+            continue;
+        }
+        if (line.startsWith('/*', index)) {
+            isInsideAnOpenComment = true;
+            index += 2;
+            continue;
+        }
+        index += 1;
+    }
+    return { ...NOTHING_IS_OPEN, isInsideAnOpenComment };
+}
+function scanAPossiblyContinuedStringLiteral(line, quoteIndex, quote) {
+    let cursor = quoteIndex + 1;
+    while (cursor < line.length) {
+        if (line[cursor] === '\\') {
+            if (isAnEscapedLineBreakAtEndOfLine(line, cursor)) {
+                return { kind: 'continuesAcrossAnEscapedLineBreak' };
+            }
+            cursor += 2;
+            continue;
+        }
+        if (line[cursor] === quote)
+            return { kind: 'closes', indexAfter: cursor + 1 };
+        cursor += 1;
+    }
+    return { kind: 'doesNotClose' };
+}
+function isAnEscapedLineBreakAtEndOfLine(line, cursor) {
+    if (cursor === line.length - 1)
+        return true;
+    return cursor === line.length - 2 && line[cursor + 1] === '\r';
 }

package/dist/lib/theming/core-contract.js

@@ -1,13 +1,136 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 const NAVE_VAR_PATTERN = /var\((--nave-[a-z0-9-]+)/g;
-const BLOCK_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
+function isIdentifierChar(ch) {
+    return ch !== undefined && /[A-Za-z0-9_$-]/.test(ch);
+}
+function findSpanEnd(content, found, offset) {
+    return found === -1 ? content.length : found + offset;
+}
+function findUrlTokenEnd(content, start) {
+    let end = start;
+    while (end < content.length) {
+        const ch = content[end];
+        if (ch === '\\' && end + 1 < content.length && content[end + 1] !== '\n') {
+            end += 2;
+        }
+        else if (ch === ')') {
+            return end + 1;
+        }
+        else if (['\n', '"', "'"].includes(ch)) {
+            return end;
+        }
+        else {
+            end++;
+        }
+    }
+    return end;
+}
+function matchUrlToken(content, index) {
+    if (!/^url\(/i.test(content.slice(index, index + 4)))
+        return undefined;
+    if (isIdentifierChar(content[index - 1]))
+        return undefined;
+    let i = index + 4;
+    while (i < content.length && /\s/.test(content[i]))
+        i++;
+    if (content[i] === "'" || content[i] === '"')
+        return undefined;
+    return findUrlTokenEnd(content, index + 4);
+}
+function stepInString(content, index, stack) {
+    const frame = stack.at(-1);
+    const ch = content[index];
+    if (ch === '\\' && index + 1 < content.length) {
+        return { index: index + 2, out: ch + content[index + 1] };
+    }
+    if (ch === '\n' || ch === frame.quote)
+        stack.pop();
+    return { index: index + 1, out: ch };
+}
+function stepInTemplateText(content, index, stack) {
+    const ch = content[index];
+    if (ch === '\\' && index + 1 < content.length) {
+        return { index: index + 2, out: ch + content[index + 1] };
+    }
+    if (ch === '`') {
+        stack.pop();
+        return { index: index + 1, out: ch };
+    }
+    if (ch === '$' && content[index + 1] === '{') {
+        stack.push({ kind: 'interp', depth: 0 });
+        return { index: index + 2, out: '${' };
+    }
+    return { index: index + 1, out: ch };
+}
+function stepBraceInCode(ch, frame, stack) {
+    if (frame.kind !== 'interp')
+        return;
+    if (ch === '{')
+        frame.depth++;
+    else if (ch === '}' && frame.depth === 0)
+        stack.pop();
+    else if (ch === '}')
+        frame.depth--;
+}
+function didOpenQuoteOrTemplate(ch, stack) {
+    if (ch === '`') {
+        stack.push({ kind: 'template' });
+        return true;
+    }
+    if (ch === "'" || ch === '"') {
+        stack.push({ kind: 'string', quote: ch });
+        return true;
+    }
+    return false;
+}
+function trySkipCommentOrUrl(content, index) {
+    const ch = content[index];
+    if (ch === '/' && content[index + 1] === '*') {
+        return { index: findSpanEnd(content, content.indexOf('*/', index + 2), 2), out: '' };
+    }
+    if (ch === '/' && content[index + 1] === '/') {
+        return { index: findSpanEnd(content, content.indexOf('\n', index), 0), out: '' };
+    }
+    const urlEnd = matchUrlToken(content, index);
+    if (urlEnd !== undefined)
+        return { index: urlEnd, out: content.slice(index, urlEnd) };
+    return undefined;
+}
+function stepInCode(content, index, stack) {
+    const ch = content[index];
+    if (didOpenQuoteOrTemplate(ch, stack))
+        return { index: index + 1, out: ch };
+    const skipped = trySkipCommentOrUrl(content, index);
+    if (skipped)
+        return skipped;
+    stepBraceInCode(ch, stack.at(-1), stack);
+    return { index: index + 1, out: ch };
+}
+function step(content, index, stack) {
+    const frame = stack.at(-1);
+    if (frame.kind === 'string')
+        return stepInString(content, index, stack);
+    if (frame.kind === 'template')
+        return stepInTemplateText(content, index, stack);
+    return stepInCode(content, index, stack);
+}
+function stripComments(content) {
+    const stack = [{ kind: 'code' }];
+    let out = '';
+    let i = 0;
+    while (i < content.length) {
+        const result = step(content, i, stack);
+        out += result.out;
+        i = result.index;
+    }
+    return out;
+}
 const CONTRACT_AUDIT_PATTERN = /var\((--nave-[a-z0-9-]+)/g;
-const CONTRACT_AUDIT_BLOCK_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
 export function scanCoreContract(fileContents) {
     const found = new Set();
     for (const content of fileContents) {
-        const stripped = content.replaceAll(BLOCK_COMMENT_RE, '');
+        const stripped = stripComments(content);
         for (const match of stripped.matchAll(NAVE_VAR_PATTERN)) {
             found.add(match[1]);
         }
@@ -50,7 +173,7 @@ export function assertContractPreconditions(names, rawSourceText) {
     if (unprefixed.length > 0) {
         throw new StaleContractPreconditionError(`these scanned names are not yet prefixed --nave-: ${unprefixed.join(', ')}`);
     }
-    const stripped = rawSourceText.replaceAll(CONTRACT_AUDIT_BLOCK_COMMENT_RE, '');
+    const stripped = stripComments(rawSourceText);
     const referenced = new Set(stripped.matchAll(CONTRACT_AUDIT_PATTERN).map((match) => match[1]));
     const scanned = new Set(names);
     const unscanned = referenced.difference(scanned);

package/dist/lib/theming/guard-message-probes.js

@@ -1,4 +1,4 @@
-import { ADJACENCY, assertNoOrphanedSemanticSlot } from "./adjacency.js";
+import { ADJACENCY, assertCoverageFloor, assertNoFocusableAdjacentToActionFill, assertNoForbiddenAdjacency, assertNoOrphanedSemanticSlot, } from "./adjacency.js";
 import { assertContrastFloors, assertFloorProvenance, assertNoSameStepViolations, checkSameStepLint, runContrastHarness, } from "./contrast.js";
 import { assertNoticeIsEmitted, RETHEMING_NOTICE } from "./copy-lint.js";
 import { TINT_SEED_COMMENT_STEM } from "./emit.js";
@@ -59,6 +59,23 @@ export const ACCESSIBILITY_GUARD_MESSAGE_PROBES = [
         label: 'the orphaned-semantic-slot output',
         capture: () => capturedFailureMessage(() => assertNoOrphanedSemanticSlot(['content.brandNew'])),
     },
+    {
+        label: 'the adjacency coverage-floor output',
+        capture: () => capturedFailureMessage(() => assertCoverageFloor(ADJACENCY.filter((a) => a.subject !== 'border.control'))),
+    },
+    {
+        label: 'the forbidden-adjacency output',
+        capture: () => capturedFailureMessage(() => assertNoForbiddenAdjacency([
+            { subject: 'content.secondary', against: 'surface.inverse', class: 'text' },
+        ])),
+    },
+    {
+        label: 'the focusable-adjacent-to-action-fill output',
+        capture: () => capturedFailureMessage(() => assertNoFocusableAdjacentToActionFill([
+            ...ADJACENCY,
+            { subject: 'border.focus', against: 'action.primary', class: 'non-text' },
+        ])),
+    },
     {
         label: "the same-step lint's real violation output (build-step.ts's runResultGuards)",
         capture: () => {

package/dist/lib/theming/neutral.js

@@ -68,7 +68,7 @@ export function neutralRcsFormula(step, literals) {
     const found = literals.find((s) => s.step === step);
     if (!found)
         throw new Error(`Neutral step ${step} is not in the shared step table.`);
-    return `oklch(from var(--nave-color-tint) ${roundTo(found.l, 4)} ${roundTo(found.c, 4)} h)`;
+    return `oklch(from var(--nave-color-tint) ${roundTo(found.l, 4)} ${roundTo(found.c, 4)} h / 1)`;
 }
 function roundTo(n, d) {
     const f = 10 ** d;

package/dist/lib/theming/seed-channel-split.js

@@ -1,7 +1,13 @@
 import { clamp01 } from "./seed-refusal.js";
-const CSS_WHITESPACE_EDGES = /^[ \t\n\r\f]+|[ \t\n\r\f]+$/g;
+const CSS_WHITESPACE_CHARS = ' \t\n\r\f';
 function cssTrim(text) {
-    return text.replaceAll(CSS_WHITESPACE_EDGES, '');
+    let start = 0;
+    let end = text.length;
+    while (start < end && CSS_WHITESPACE_CHARS.includes(text[start]))
+        start += 1;
+    while (end > start && CSS_WHITESPACE_CHARS.includes(text[end - 1]))
+        end -= 1;
+    return text.slice(start, end);
 }
 const CSS_NUMBER = /^[+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?$/;
 export function readNumericToken(text) {
@@ -22,7 +28,6 @@ function parseAlphaToken(token) {
         return clamp01(readNumericToken(t.slice(0, -1)) / 100);
     return clamp01(readNumericToken(t));
 }
-const CSS_WHITESPACE_CHARS = ' \t\n\r\f';
 function splitTopLevel(text, isSeparator) {
     const tokens = [];
     let current = '';

package/dist/lib/validate-report.d.ts

@@ -14,6 +14,7 @@ export type CoreVersionReportStatus = {
     message: string;
     status: 'unreadable';
 };
+export declare function formatVersionSkewFact(producerName: string, versionSkew: ManifestVersionSkew): string;
 export declare function formatValidateReport(manifest: CoreContractManifest, missing: readonly string[], versionSkew: ManifestVersionSkew | undefined, coreVersionStatus?: CoreVersionReportStatus & {
     supplied?: readonly string[];
 }): string[];

package/dist/lib/validate-report.js

@@ -7,6 +7,11 @@ export function checkManifestFormatSupport(manifest) {
 const NAMESPACE_PREAMBLE = 'Contract names below are the emitted CSS custom-property spelling (for example ' +
     '--nave-color-surface-base). Your DTCG 2025.10 source names the same node with the "--nave-" ' +
     'prefix dropped and hyphens read as a dotted path (color.surface.base).';
+export function formatVersionSkewFact(producerName, versionSkew) {
+    return (`the core contract this @navecss/tokens ships was recorded against ` +
+        `${producerName}@${versionSkew.recorded}, but the installed ${producerName} is ` +
+        `@${versionSkew.installed}`);
+}
 const SCOPE_STATEMENT = 'This check is one-directional: it reports every core contract name missing from your ' +
     'source. A token in your source beyond the contract is never an error.';
 const NO_INSTALLED_CORE_DISCLAIMER = 'No installed @navecss/core was found, so no version-skew check ran.';
@@ -79,9 +84,8 @@ export function formatValidateReport(manifest, missing, versionSkew, coreVersion
     }
     if (versionSkew) {
         return [
-            `Version skew: this manifest was recorded against ${manifest.producer.name}@` +
-                `${versionSkew.recorded}, but the installed ${manifest.producer.name} is @` +
-                `${versionSkew.installed}. Reinstall matching versions before trusting this result.`,
+            `Version skew: ${formatVersionSkewFact(manifest.producer.name, versionSkew)}. Reinstall ` +
+                `matching versions before trusting this result.`,
         ];
     }
     return [

package/dist/lib/validate.js

@@ -10,11 +10,25 @@ export function detectSourceKind(filePath) {
         return 'json';
     return undefined;
 }
-const DECLARED_CUSTOM_PROPERTY_RE = /(--[a-zA-Z0-9-]+)\s*:/g;
-const CSS_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
+const DECLARED_CUSTOM_PROPERTY_RE = /(?<![\w\u{80}-\u{10FFFF}-])(--[a-zA-Z0-9-]+)\s*:/gu;
+function stripCssComments(css) {
+    let kept = '';
+    let from = 0;
+    for (;;) {
+        const open = css.indexOf('/*', from);
+        if (open === -1)
+            break;
+        const close = css.indexOf('*/', open + 2);
+        if (close === -1)
+            break;
+        kept += css.slice(from, open);
+        from = close + 2;
+    }
+    return kept + css.slice(from);
+}
 export function scanDeclaredCustomProperties(css) {
     const found = new Set();
-    const declarations = css.replaceAll(CSS_COMMENT_RE, '');
+    const declarations = stripCssComments(css);
     for (const match of declarations.matchAll(DECLARED_CUSTOM_PROPERTY_RE))
         found.add(match[1]);
     return found;