@navecss/tokens 0.1.0

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

@@ -0,0 +1,49 @@
+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);
+    }
+    return beginningsInsideAnUnclosedComment;
+}
+function isLineStillInsideAnOpenCommentAfterScanning(line, wasInsideAnOpenComment) {
+    let isInsideAnOpenComment = wasInsideAnOpenComment;
+    let cursor = 0;
+    while (cursor < line.length) {
+        if (isInsideAnOpenComment) {
+            const closerIndex = line.indexOf('*/', cursor);
+            if (closerIndex === -1)
+                return true;
+            isInsideAnOpenComment = false;
+            cursor = closerIndex + 2;
+            continue;
+        }
+        const character = line[cursor];
+        if (character === '"' || character === "'") {
+            cursor = indexAfterAStringLiteral(line, cursor, character);
+            continue;
+        }
+        if (line.startsWith('/*', cursor)) {
+            isInsideAnOpenComment = true;
+            cursor += 2;
+            continue;
+        }
+        cursor += 1;
+    }
+    return isInsideAnOpenComment;
+}
+function indexAfterAStringLiteral(line, quoteIndex, quote) {
+    let cursor = quoteIndex + 1;
+    while (cursor < line.length) {
+        if (line[cursor] === '\\') {
+            cursor += 2;
+            continue;
+        }
+        if (line[cursor] === quote)
+            return cursor + 1;
+        cursor += 1;
+    }
+    return line.length;
+}

package/dist/lib/theming/consumer-build.d.ts

@@ -0,0 +1,18 @@
+import type { OutputFile } from '../builder.ts';
+import type { PerStepOverrides, Seeds } from './pipeline.ts';
+import type { SeedInputs } from './seed-input.ts';
+import { type SeedRecord } from './ramp.ts';
+export declare const CONSUMER_LAYER = "tokens.presets";
+export interface ConsumerBuildOptions {
+    seeds: Seeds;
+    seedInputs?: SeedInputs;
+    overrides?: PerStepOverrides;
+    env?: ReadonlyMap<number, number>;
+    outDir?: string;
+}
+export interface ConsumerBuildComposition {
+    css: string;
+    files: OutputFile[];
+    primaryRecord: SeedRecord;
+}
+export declare function composeConsumerBuild(options: ConsumerBuildOptions): ConsumerBuildComposition;

package/dist/lib/theming/consumer-build.js

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import { composeBuildRecord } from "./build-record.js";
+import { checkSameStepLint } from "./contrast.js";
+import { emitCss } from "./emit.js";
+import { composePaletteRecord } from "./palette-record.js";
+import { runPipeline } from "./pipeline.js";
+import { DEFAULT_ENV } from "./ramp.js";
+export const CONSUMER_LAYER = 'tokens.presets';
+const json = (value) => JSON.stringify(value, undefined, 2);
+export function composeConsumerBuild(options) {
+    const { seeds, seedInputs = {}, overrides = {}, env = DEFAULT_ENV, outDir = 'dist' } = options;
+    const result = runPipeline(seeds, overrides, env);
+    const emitted = emitCss(result, CONSUMER_LAYER);
+    checkSameStepLint(result, 'consumer');
+    return {
+        css: emitted.css,
+        files: [
+            {
+                destination: path.join(outDir, 'palette-record.json'),
+                content: json(composePaletteRecord(result)),
+            },
+            {
+                destination: path.join(outDir, 'build-record.json'),
+                content: json(composeBuildRecord(seeds, result, undefined, seedInputs)),
+            },
+        ],
+        primaryRecord: result.records.primary,
+    };
+}

package/dist/lib/theming/contact-sheet.d.ts

@@ -0,0 +1,22 @@
+import type { Oklch } from './color-math.ts';
+import type { PipelineResult } from './pipeline.ts';
+type SheetScale = 'danger' | 'neutral' | 'primary';
+export interface SheetColumn {
+    name: string;
+    seed: Oklch;
+    result: PipelineResult;
+}
+export interface ContactSheetCell {
+    seed: string;
+    scheme: 'dark' | 'light';
+    scale: SheetScale;
+    step: number;
+}
+export declare function expectedCells(columns: readonly SheetColumn[]): ContactSheetCell[];
+export declare function assertContactSheetComplete(html: string, expected: readonly ContactSheetCell[]): void;
+export interface ContactSheet {
+    html: string;
+    cells: readonly ContactSheetCell[];
+}
+export declare function composeContactSheet(columns: readonly SheetColumn[]): ContactSheet;
+export {};

package/dist/lib/theming/contact-sheet.js

@@ -0,0 +1,123 @@
+import { formatOklch } from "./color-math.js";
+import { resolveNeutralStep } from "./neutral.js";
+import { rampStep } from "./ramp.js";
+import { STEP_TABLE } from "./step-table.js";
+const SHEET_SCALES = ['primary', 'danger', 'neutral'];
+const SCHEMES = ['light', 'dark'];
+const SHEET_SURFACES = [
+    'surface.base',
+    'surface.raised',
+    'surface.overlay',
+    'surface.sunken',
+    'surface.inverse',
+];
+const cellId = (cell) => `${cell.seed}|${cell.scheme}|${cell.scale}|${cell.step}`;
+export function expectedCells(columns) {
+    const cells = [];
+    const forScale = (seed, scheme, scale) => {
+        for (const { step } of STEP_TABLE)
+            cells.push({ seed, scheme, scale, step });
+    };
+    for (const column of columns) {
+        for (const scheme of SCHEMES) {
+            for (const scale of SHEET_SCALES)
+                forScale(column.name, scheme, scale);
+        }
+    }
+    return cells;
+}
+function stepColour(result, scale, step) {
+    if (scale === 'neutral') {
+        return resolveNeutralStep(step, result.records.tintHue, result.neutralLiterals);
+    }
+    return rampStep(scale === 'primary' ? result.primaryRamp : result.dangerRamp, step);
+}
+function slotColour(result, slot, scheme) {
+    const found = result.slots.find((s) => s.slot === slot && s.branch === scheme);
+    if (!found)
+        throw new Error(`The contact sheet cannot resolve ${slot} (${scheme}). Open an issue.`);
+    return found.literal;
+}
+const escapeHtml = (text) => text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+function renderSwatch(cell, colour) {
+    const css = formatOklch(colour);
+    return (`<i class="sw" data-cell="${escapeHtml(cellId(cell))}" style="background:${css}" ` +
+        `title="${cell.scale} ${cell.step} — ${css}"></i>`);
+}
+function renderSurfaceBlock(column, scheme, surface) {
+    const background = formatOklch(slotColour(column.result, surface, scheme));
+    const label = formatOklch(slotColour(column.result, surface === 'surface.inverse' ? 'content.inverse' : 'content.primary', scheme));
+    const rows = SHEET_SCALES.map((scale) => {
+        const swatches = STEP_TABLE.map(({ step }) => renderSwatch({ seed: column.name, scheme, scale, step }, stepColour(column.result, scale, step))).join('');
+        return `<div class="row"><span class="lbl">${scale}</span><span class="ramp">${swatches}</span></div>`;
+    }).join('');
+    return (`<div class="surface" style="background:${background};color:${label}">` +
+        `<span class="lbl surf">${surface}</span>${rows}</div>`);
+}
+function renderColumn(column, scheme) {
+    const blocks = SHEET_SURFACES.map((surface) => renderSurfaceBlock(column, scheme, surface)).join('');
+    const seedCss = formatOklch(column.seed);
+    return (`<div class="col"><h3>${escapeHtml(column.name)}</h3>` +
+        `<code>${escapeHtml(seedCss)}</code>${blocks}</div>`);
+}
+const SHEET_STYLE = `
+:root { color-scheme: light dark; font-family: ui-sans-serif, system-ui, sans-serif; }
+body { margin: 0; padding: 1.5rem; background: #f6f6f6; color: #111; }
+h1 { font-size: 1.1rem; } h2 { font-size: 1rem; margin: 1.5rem 0 0.5rem; }
+h3 { font-size: 0.8rem; margin: 0 0 0.15rem; } code { font-size: 0.65rem; opacity: 0.7; }
+.note { max-width: 60rem; font-size: 0.75rem; line-height: 1.5; }
+.cols { display: flex; gap: 0.75rem; align-items: flex-start; flex-wrap: nowrap; overflow-x: auto; }
+.col { flex: 1 1 0; min-width: 16rem; }
+.surface { padding: 0.4rem 0.5rem; border-radius: 4px; margin-top: 0.35rem; }
+.row { display: flex; align-items: center; gap: 0.35rem; margin-top: 0.15rem; }
+.lbl { font-size: 0.6rem; width: 4.5rem; flex: none; }
+.lbl.surf { display: block; width: auto; opacity: 0.75; }
+.ramp { display: flex; flex: 1 1 auto; }
+.sw { display: block; flex: 1 1 0; height: 1.1rem; }
+`;
+function renderSheet(columns) {
+    const sections = SCHEMES.map((scheme) => {
+        const cols = columns.map((column) => renderColumn(column, scheme)).join('');
+        return `<h2>${scheme} scheme</h2><div class="cols">${cols}</div>`;
+    }).join('');
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<title>Nave contact sheet — generated, do not edit</title>
+<style>${SHEET_STYLE}</style></head>
+<body>
+<h1>Nave contact sheet</h1>
+<p class="note">Generated by the token build. Every step of every
+generated scale, in both schemes, drawn on the five shipped surfaces those steps sit on, with one
+column per seed in the build's adversarial seed set alongside the shipped default. This is the
+approval artifact for ramp quality; the numeric envelope is not. Chroma goes to zero at L&nbsp;1.000
+and L&nbsp;0.000 at every hue, so every chromatic column ends in a white and a black swatch — that
+is the arithmetic, not an oversight.</p>
+${sections}
+</body></html>
+`;
+}
+export function assertContactSheetComplete(html, expected) {
+    const rendered = new Set();
+    for (const match of html.matchAll(/data-cell="([^"]+)"/g))
+        rendered.add(match[1]);
+    const missing = expected.filter((cell) => !rendered.has(cellId(cell)));
+    if (missing.length > 0) {
+        const shown = missing
+            .slice(0, 10)
+            .map((cell) => cellId(cell))
+            .join(', ');
+        throw new Error(`The contact sheet is missing ${missing.length} of ${expected.length} cells ` +
+            `(seed|scheme|scale|step): ${shown}${missing.length > 10 ? ', ...' : ''}. A step or a ` +
+            'seed missing from the sheet fails the run: the sheet is the only ramp-quality ' +
+            'approval this design has. Open an issue rather than working around this check.');
+    }
+}
+export function composeContactSheet(columns) {
+    if (columns.length === 0) {
+        throw new Error('The contact sheet carries no seed column. Open an issue.');
+    }
+    const html = renderSheet(columns);
+    const cells = expectedCells(columns);
+    assertContactSheetComplete(html, cells);
+    return { html, cells };
+}

package/dist/lib/theming/contrast.d.ts

@@ -0,0 +1,31 @@
+import type { PipelineResult } from './pipeline.ts';
+import { type Adjacency } from './adjacency.ts';
+export declare const TEXT_FLOOR = 4.5;
+export declare const NON_TEXT_FLOOR = 3;
+export declare const MARGIN = 1.01;
+export interface FloorConstants {
+    textFloor: number;
+    nonTextFloor: number;
+    margin: number;
+}
+export declare function assertFloorProvenance(floors?: FloorConstants): void;
+export interface ContrastResult {
+    pair: Adjacency;
+    scheme: 'light' | 'dark';
+    ratio: number;
+    floor: number;
+    threshold: number;
+    pass: boolean;
+}
+export declare function runContrastHarness(result: PipelineResult, adjacency?: readonly Adjacency[]): ContrastResult[];
+export declare function assertContrastFloors(results: readonly ContrastResult[]): void;
+export type SameStepSource = 'nave' | 'consumer';
+type SameStepSeverity = 'fail' | 'report';
+export interface SameStepViolation {
+    slot: string;
+    description: string;
+    severity: SameStepSeverity;
+}
+export declare function checkSameStepLint(result: PipelineResult, source?: SameStepSource, adjacency?: readonly Adjacency[]): SameStepViolation[];
+export declare function assertNoSameStepViolations(sameStep: readonly SameStepViolation[]): void;
+export {};

package/dist/lib/theming/contrast.js

@@ -0,0 +1,133 @@
+import { ADJACENCY } from "./adjacency.js";
+import { contrastRatio } from "./color-math.js";
+export const TEXT_FLOOR = 4.5;
+export const NON_TEXT_FLOOR = 3;
+export const MARGIN = 1.01;
+const FLOOR_PROVENANCE = {
+    textFloor: 4.5,
+    nonTextFloor: 3,
+    margin: 1.01,
+};
+const LIVE_FLOORS = {
+    textFloor: TEXT_FLOOR,
+    nonTextFloor: NON_TEXT_FLOOR,
+    margin: MARGIN,
+};
+export function assertFloorProvenance(floors = LIVE_FLOORS) {
+    if (floors.textFloor !== FLOOR_PROVENANCE.textFloor ||
+        floors.nonTextFloor !== FLOOR_PROVENANCE.nonTextFloor ||
+        floors.margin !== FLOOR_PROVENANCE.margin) {
+        throw new Error(`Contrast floors: the floor constants in this file (text ${floors.textFloor}, ` +
+            `non-text ${floors.nonTextFloor}, margin ${floors.margin}) no longer match the ` +
+            `frozen record they are checked against. These three numbers are not this build's ` +
+            `to move: they are the project's contrast policy, and this check exists so a change ` +
+            `to them cannot land as a silent divergence. Revert the constant that moved. If you ` +
+            `believe the policy itself should change, open an issue and say so there; do not ` +
+            `update the frozen record to match the code.`);
+    }
+}
+function findSlot(slots, name, branch) {
+    const found = slots.find((s) => s.slot === name && s.branch === branch);
+    if (!found)
+        throw new Error(`Slot not found for contrast check: ${name} (${branch})`);
+    return found;
+}
+function harnessSlots(result) {
+    return [
+        ...result.slots,
+        result.actionSecondaryForeground.light,
+        result.actionSecondaryForeground.dark,
+        result.actionSecondaryBorder.light,
+        result.actionSecondaryBorder.dark,
+    ];
+}
+export function runContrastHarness(result, adjacency = ADJACENCY) {
+    if (adjacency.length === 0) {
+        throw new Error('Contrast check: the pair-declaration source is empty, so there are no colour pairs to ' +
+            'measure. This fails the build rather than reporting a clean run, because an untested ' +
+            'palette is not a passing one. Restore the declarations; if you believe an empty set ' +
+            'is correct here, open an issue rather than removing this check.');
+    }
+    const allSlots = harnessSlots(result);
+    const out = [];
+    for (const scheme of ['light', 'dark']) {
+        for (const pair of adjacency) {
+            const subject = findSlot(allSlots, pair.subject, scheme);
+            const against = findSlot(allSlots, pair.against, scheme);
+            const ratio = contrastRatio(subject.literal, against.literal);
+            const floor = pair.class === 'text' ? TEXT_FLOOR : NON_TEXT_FLOOR;
+            const threshold = floor * MARGIN;
+            out.push({ pair, scheme, ratio, floor, threshold, pass: ratio >= threshold });
+        }
+    }
+    return out;
+}
+export function assertContrastFloors(results) {
+    const failing = results.filter((r) => !r.pass);
+    if (failing.length === 0)
+        return;
+    const lines = failing.map((r) => `${r.pair.subject} vs ${r.pair.against} (${r.scheme}): computed ${r.ratio}, below the ` +
+        `applied threshold ${roundTo(r.threshold, 4)} (the recorded floor ${r.floor} plus a 1 ` +
+        'percent margin; a pair clearing only inside that margin counts as failing)');
+    throw new Error(`Contrast check: ${failing.length} colour pair(s) fall below the floor this build ` +
+        `applies:\n${lines.join('\n')}\nRe-point the failing slot. If you believe the floor ` +
+        'itself is wrong, open an issue rather than lowering it here.');
+}
+function roundTo(n, d) {
+    const f = 10 ** d;
+    return Math.round(n * f) / f;
+}
+function groupSlotsByName(slots) {
+    const bySlot = new Map();
+    for (const slot of slots) {
+        const entry = bySlot.get(slot.slot) ?? {};
+        entry[slot.branch] = slot;
+        bySlot.set(slot.slot, entry);
+    }
+    return bySlot;
+}
+function findPinnedSlots(slots) {
+    const pinned = new Set();
+    for (const [name, { light, dark }] of groupSlotsByName(slots)) {
+        if (!light || !dark)
+            continue;
+        const isSamePin = light.resolved.scale === dark.resolved.scale && light.resolved.step === dark.resolved.step;
+        if (isSamePin)
+            pinned.add(name);
+    }
+    return pinned;
+}
+export function checkSameStepLint(result, source = 'nave', adjacency = ADJACENCY) {
+    if (adjacency.length === 0) {
+        throw new Error('Same-step lint: the pair-declaration source is empty. Those declarations are what ' +
+            'mark a pair as text or non-text, which is the only thing this lint reads, so with ' +
+            'nothing declared there is nothing to check. That is not the same as nothing being ' +
+            'wrong, so this fails rather than reporting a clean run. Restore the declarations, ' +
+            'or open an issue.');
+    }
+    const pinned = findPinnedSlots(harnessSlots(result));
+    const severity = source === 'nave' ? 'fail' : 'report';
+    const hits = new Map();
+    const record = (slot, description) => void hits.set(`${slot}:${description}`, { slot, description, severity });
+    for (const pair of adjacency) {
+        if (pair.class !== 'text')
+            continue;
+        if (pinned.has(pair.subject)) {
+            record(pair.subject, `${pair.subject} (subject of ${pair.subject}/${pair.against})`);
+        }
+        if (pinned.has(pair.against)) {
+            record(pair.against, `${pair.against} (background of ${pair.subject}/${pair.against})`);
+        }
+    }
+    return hits.values().toArray();
+}
+export function assertNoSameStepViolations(sameStep) {
+    const failing = sameStep.filter((violation) => violation.severity === 'fail');
+    if (failing.length > 0) {
+        const lines = failing.map((violation) => violation.description);
+        throw new Error(`${failing.length} slot(s) resolve to the same palette step in both the light and the ` +
+            `dark scheme while sitting on one side of a pair marked as text:\n${lines.join('\n')}` +
+            '\nRe-point the listed slot(s) so each pair keeps a light/dark step difference, or ' +
+            'open an issue.');
+    }
+}

package/dist/lib/theming/copy-lint.d.ts

@@ -0,0 +1,13 @@
+export interface LintViolation {
+    text: string;
+    reason: string;
+}
+export declare function findConformanceFraming(text: string): string | undefined;
+export declare function lintDescriptions(descriptions: ReadonlyMap<string, string>): LintViolation[];
+export declare function assertDescriptionsAreClean(...descriptionMaps: readonly ReadonlyMap<string, string>[]): void;
+export declare const RETHEMING_NOTICE = "Changing this changes everything Nave derives from it. The contrast of the resulting palette follows from what you set, and checking it is yours.";
+export declare function assertNoticeIsClean(notice?: string, noticeLabel?: string): void;
+export declare const FEEDBACK_SHARED_IDENTITY_NOTICE = "warning, success and info, and their -foreground variants, resolve to one shared value here; only danger differs. Colour alone therefore cannot tell those three states apart, so wherever a feedback token carries meaning, give it a text label naming the state and a distinct icon or shape that differs per state.";
+export declare const NO_CONSUMER_CONTRAST_THRESHOLD_INPUT = "0.1.0 ships no consumer contrast-threshold input. No flag of this entry point sets one, and the build reads none. This is the absence of an input, not a limit on the consumer: a consumer may hold whatever contrast target they choose and check their palette against it with their own tooling. Where a check Nave ships runs in a consumer's build over the consumer's values, it reports and does not fail. A consumer-settable target is deliberately out of 0.1.0 rather than overlooked.";
+export declare function assertNoticeIsEmitted(css: string, notice: string, noticeLabel: string): void;
+export declare function assertHarnessFramingIsClean(): void;

package/dist/lib/theming/copy-lint.js

@@ -0,0 +1,98 @@
+import { linesThatBeginInsideAnUnclosedComment } from "./comment-open-tracker.js";
+import { assertContrastFloors, runContrastHarness } from "./contrast.js";
+import { ACCESSIBILITY_GUARD_MESSAGE_PROBES } from "./guard-message-probes.js";
+const FORBIDDEN_WORDS = /\b(WCAG|AA|AAA|accessible|compliant|meets|conformant)\b/i;
+const RATIO_PATTERN = /\d+(?:\.\d+)?\s*:\s*1/;
+const SUCCESS_CRITERION_PATTERN = /\bSC\s*\d+\.\d+\.\d+\b/i;
+export function findConformanceFraming(text) {
+    const wordMatch = FORBIDDEN_WORDS.exec(text);
+    if (wordMatch)
+        return `contains the word "${wordMatch[0]}"`;
+    const ratioMatch = RATIO_PATTERN.exec(text);
+    if (ratioMatch)
+        return `contains a contrast ratio ("${ratioMatch[0]}")`;
+    const scMatch = SUCCESS_CRITERION_PATTERN.exec(text);
+    if (scMatch)
+        return `contains a WCAG success-criterion identifier ("${scMatch[0]}")`;
+    return undefined;
+}
+export function lintDescriptions(descriptions) {
+    const violations = [];
+    for (const [token, text] of descriptions) {
+        const reason = findConformanceFraming(text);
+        if (reason)
+            violations.push({ text: token, reason });
+    }
+    return violations;
+}
+export function assertDescriptionsAreClean(...descriptionMaps) {
+    const violations = descriptionMaps.flatMap((descriptions) => lintDescriptions(descriptions));
+    if (violations.length === 0)
+        return;
+    const lines = violations.map((violation) => `${violation.text}: ${violation.reason}`);
+    throw new Error(`${violations.length} token description(s) state or imply an accessibility conformance ` +
+        `claim, which Nave's shipped copy does not make:\n${lines.join('\n')}\nDescribe what the ` +
+        'token is for and leave the claim out. If you think the description needs it, open an ' +
+        'issue rather than changing this check.');
+}
+export const RETHEMING_NOTICE = 'Changing this changes everything Nave derives from it. The contrast of the resulting palette follows from what you set, and checking it is yours.';
+export function assertNoticeIsClean(notice = RETHEMING_NOTICE, noticeLabel = 'Re-theming notice') {
+    const reason = findConformanceFraming(notice);
+    if (reason)
+        throw new Error(`${noticeLabel}: ${reason}.`);
+    if (/\bwarrant(y|ies)\b/i.test(notice)) {
+        throw new Error(`${noticeLabel}: it uses warranty wording. This notice states a fact and the act it ` +
+            'leaves to the reader; wording it as a disclaimer changes what it claims. Reword it, ' +
+            'or open an issue if the notice itself should change.');
+    }
+}
+export const FEEDBACK_SHARED_IDENTITY_NOTICE = 'warning, success and info, and their -foreground variants, resolve to one shared value here; only danger differs. Colour alone therefore cannot tell those three states apart, so wherever a feedback token carries meaning, give it a text label naming the state and a distinct icon or shape that differs per state.';
+export const NO_CONSUMER_CONTRAST_THRESHOLD_INPUT = "0.1.0 ships no consumer contrast-threshold input. No flag of this entry point sets one, and the build reads none. This is the absence of an input, not a limit on the consumer: a consumer may hold whatever contrast target they choose and check their palette against it with their own tooling. Where a check Nave ships runs in a consumer's build over the consumer's values, it reports and does not fail. A consumer-settable target is deliberately out of 0.1.0 rather than overlooked.";
+export function assertNoticeIsEmitted(css, notice, noticeLabel) {
+    if (!css.includes(notice)) {
+        throw new Error(`${noticeLabel} violation: the notice is not present, verbatim, in the emitted CSS. Restore it exactly as authored.`);
+    }
+    const allLines = css.split('\n');
+    const carryingLines = allLines
+        .map((line, index) => ({ index, line }))
+        .filter((candidate) => candidate.line.includes(notice));
+    if (carryingLines.length === 0) {
+        throw new Error(`${noticeLabel} violation: the notice text spans more than one line, so no single line of the emitted CSS carries it whole. This check reads that CSS one line at a time and refuses a notice it cannot read in full rather than skipping it. The notice text is defined in packages/tokens/src/theming/copy-lint.ts. Put it back on a single line, or open an issue if it genuinely needs more than one.`);
+    }
+    const linesThatBeginOpen = linesThatBeginInsideAnUnclosedComment(allLines);
+    for (const { index, line } of carryingLines) {
+        const trimmed = line.trim();
+        const rest = trimmed.replace(notice, '');
+        const isSelfContainedComment = trimmed.startsWith('/*') && trimmed.endsWith('*/');
+        const notSelfContainedMessage = `${noticeLabel} violation: a line of emitted CSS carrying the notice is not a self-contained comment, or sits inside a comment opened on an earlier line, so a reader sees more around the notice than this check can read, and it refuses rather than checking part of what they see. With the notice text itself elided, that line reads "${rest}", and it is built in packages/tokens/src/theming/emit.ts. Put the notice and the rest of its comment on one line, or open an issue if that comment genuinely needs to wrap.`;
+        if (!isSelfContainedComment) {
+            throw new Error(notSelfContainedMessage);
+        }
+        const reason = findConformanceFraming(line);
+        if (reason) {
+            throw new Error(`${noticeLabel} violation: a comment line carrying the notice ${reason}. The notice text itself is present byte for byte, so what needs changing is the rest of that line, which reads "${rest}" with the notice text itself elided and is built in packages/tokens/src/theming/emit.ts. Take the phrase out there, or open an issue if that line should genuinely carry it.`);
+        }
+        if (linesThatBeginOpen.has(index)) {
+            throw new Error(notSelfContainedMessage);
+        }
+    }
+}
+export function assertHarnessFramingIsClean() {
+    for (const name of [runContrastHarness.name, assertContrastFloors.name]) {
+        const reason = findConformanceFraming(name);
+        if (reason)
+            throw new Error(`Copy-check violation: the harness function name "${name}" ${reason}. Take those words out of the name.`);
+    }
+    for (const probe of ACCESSIBILITY_GUARD_MESSAGE_PROBES) {
+        let message;
+        try {
+            message = probe.capture();
+        }
+        catch (error) {
+            throw new Error(`Copy-check probe "${probe.label}" no longer reproduces its own failing direction: ${error.message}`, { cause: error });
+        }
+        const reason = findConformanceFraming(message);
+        if (reason)
+            throw new Error(`Copy-check violation: ${probe.label} ${reason}. Take those words out of the message that produced it.`);
+    }
+}

package/dist/lib/theming/core-contract.d.ts

@@ -0,0 +1,29 @@
+export declare function scanCoreContract(fileContents: readonly string[]): string[];
+export declare function scanCoreContractFromDisk(paths: readonly string[]): string[];
+export declare function discoverSourceFiles(dir: string, extensions?: readonly string[]): string[];
+export declare const MANIFEST_FORMAT_VERSION = 1;
+export interface ManifestProducer {
+    name: string;
+    version: string;
+}
+export interface CoreContractManifest {
+    formatVersion: number;
+    producer: ManifestProducer;
+    tokens: readonly string[];
+}
+export declare function buildManifest(tokens: readonly string[], producer: ManifestProducer): CoreContractManifest;
+export interface ManifestVersionSkew {
+    recorded: string;
+    installed: string;
+}
+export declare function checkManifestVersionSkew(manifest: CoreContractManifest, installedCoreVersion: string): ManifestVersionSkew | undefined;
+export declare function validateAgainstManifest(manifest: CoreContractManifest, emittedNames: ReadonlySet<string>): string[];
+export declare class StaleContractPreconditionError extends Error {
+    constructor(reason: string);
+}
+export declare function assertContractPreconditions(names: readonly string[], rawSourceText: string): void;
+export interface ContractDrift {
+    missing: string[];
+    added: string[];
+}
+export declare function diffContract(recorded: readonly string[], emitted: ReadonlySet<string>): ContractDrift;

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

@@ -0,0 +1,71 @@
+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;
+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, '');
+        for (const match of stripped.matchAll(NAVE_VAR_PATTERN)) {
+            found.add(match[1]);
+        }
+    }
+    return [...found].toSorted((a, b) => a.localeCompare(b));
+}
+export function scanCoreContractFromDisk(paths) {
+    return scanCoreContract(paths.map((p) => readFileSync(p, 'utf8')));
+}
+export function discoverSourceFiles(dir, extensions = ['.ts', '.css']) {
+    return readdirSync(dir, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile() && extensions.some((ext) => entry.name.endsWith(ext)))
+        .map((entry) => path.join(entry.parentPath, entry.name))
+        .toSorted((a, b) => a.localeCompare(b));
+}
+export const MANIFEST_FORMAT_VERSION = 1;
+export function buildManifest(tokens, producer) {
+    return {
+        formatVersion: MANIFEST_FORMAT_VERSION,
+        producer,
+        tokens: [...tokens].toSorted((a, b) => a.localeCompare(b)),
+    };
+}
+export function checkManifestVersionSkew(manifest, installedCoreVersion) {
+    if (manifest.producer.version === installedCoreVersion)
+        return undefined;
+    return { recorded: manifest.producer.version, installed: installedCoreVersion };
+}
+export function validateAgainstManifest(manifest, emittedNames) {
+    return manifest.tokens.filter((name) => !emittedNames.has(name));
+}
+export class StaleContractPreconditionError extends Error {
+    constructor(reason) {
+        super(`Manifest generation refused: ${reason}`);
+        this.name = 'StaleContractPreconditionError';
+    }
+}
+export function assertContractPreconditions(names, rawSourceText) {
+    const unprefixed = names.filter((name) => !name.startsWith('--nave-'));
+    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 referenced = new Set(stripped.matchAll(CONTRACT_AUDIT_PATTERN).map((match) => match[1]));
+    const scanned = new Set(names);
+    const unscanned = referenced.difference(scanned);
+    if (unscanned.size > 0) {
+        const sorted = [...unscanned].toSorted((a, b) => a.localeCompare(b)).join(', ');
+        throw new StaleContractPreconditionError(`referenced in source but missing from the scanned contract, narrower than core's real ` +
+            `run-time dependency: ${sorted}`);
+    }
+}
+export function diffContract(recorded, emitted) {
+    const recordedSet = new Set(recorded);
+    return {
+        missing: recorded.filter((name) => !emitted.has(name)),
+        added: [...emitted]
+            .filter((name) => !recordedSet.has(name))
+            .toSorted((a, b) => a.localeCompare(b)),
+    };
+}

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

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

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

@@ -0,0 +1,18 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertContractPreconditions, buildManifest, discoverSourceFiles, scanCoreContractFromDisk, } from "./core-contract.js";
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CORE_SRC_DIR = path.resolve(HERE, '../../../core/src');
+const CORE_PACKAGE_JSON_PATH = path.resolve(HERE, '../../../core/package.json');
+export function buildCoreContractManifest() {
+    const corePackage = JSON.parse(readFileSync(CORE_PACKAGE_JSON_PATH, 'utf8'));
+    const files = discoverSourceFiles(CORE_SRC_DIR);
+    const rawSourceText = files.map((p) => readFileSync(p, 'utf8')).join('\n');
+    const tokens = scanCoreContractFromDisk(files);
+    assertContractPreconditions(tokens, rawSourceText);
+    return buildManifest(tokens, {
+        name: corePackage.name,
+        version: corePackage.version,
+    });
+}