@adea-ai/themes 0.1.0

package/dist/normalize.js

@@ -0,0 +1,795 @@
+/**
+ * The normalizer: Base24 in, Adea theme out.
+ *
+ * This module is the reason the package exists. The palettes in `palettes/` are
+ * other people's, and they arrive describing a *terminal*: a background, a
+ * foreground, a comment grey, and sixteen hues. A UI needs different words — a
+ * surface ladder, borders, an accent, four status roles that are legible as text.
+ * Translating between the two is the work Adea owns, and it is done here, once,
+ * for every theme in the catalogue, rather than by hand in each consumer.
+ *
+ * ## The transformations, and why each is not obvious
+ *
+ * **The surface ladder is built, not read.** Base24 has exactly one background
+ * slot, so there is no upstream value to copy for "a card on the canvas". The four
+ * rungs are derived by adding fixed increments to the background's OKLCH
+ * lightness, keeping its hue and a damped share of its chroma — which is what
+ * makes Catppuccin's ladder mauve-tinted and Nord's blue-tinted without either
+ * being told to be.
+ *
+ * **The direction of that ladder flips with the appearance.** On a dark theme a
+ * raised surface is *lighter*; on a light theme it is *darker*. Getting this
+ * wrong yields a light theme whose dialogs are white-on-white, so
+ * {@link ladderDirection} is measured from the background rather than assumed from
+ * the declared variant.
+ *
+ * **Light Base24 schemes invert their own ramp.** In a dark scheme `base03` is a
+ * dark grey and `base05` is near-white; in a light scheme `base03` is the lightest
+ * grey and `base05` is near-black. A fixed assignment of slots to ANSI roles
+ * therefore produces an inverted 16-colour ramp on half the catalogue. The ramp
+ * roles are assigned by *measured contrast* and by appearance instead, in
+ * {@link buildAnsiRamp}.
+ *
+ * **A selection colour can erase its own text.** Base24's `base02` is whatever the
+ * palette's author set, and several set it to a near-white — fine as a terminal
+ * selection, fatal as an app selection under near-white body text. The theme keeps
+ * the palette's colour and the *adapters* derive a matching foreground
+ * (see `adapters/xterm.ts`); the catalogue additionally checks that the selection
+ * is perceptible against the background at all.
+ *
+ * **Status and accent colours are repaired, within a budget.** A palette chosen for
+ * an editor is not automatically legible as UI text. Every status role is checked
+ * against the background and its lightness moved by the least amount that clears
+ * the floor — and if that would move it more than the budget allows, the theme is
+ * reported as failing rather than silently shipping a colour that is no longer the
+ * one the palette's author chose.
+ */
+import { parseBase24Palette } from './adapters/base24';
+import { canonical, contrastRatio, contrastDirection, deltaEok, formatOklch, mix, parseColor, shiftLightness, } from './oklch';
+import { repairContrast } from './oklch';
+/**
+ * The contrast floors.
+ *
+ * These are the catalogue's policy, and they are the reason an external palette
+ * can be admitted at all: nothing enters the catalogue on taste. `text` sits at
+ * the WCAG AA body-text floor; `border` is measured on the non-text scale, where
+ * the requirement is perceptibility rather than legibility.
+ */
+export const CONTRAST_FLOORS = Object.freeze({
+    text: 4.5,
+    textMuted: 4.5,
+    /** Large or non-essential text, per WCAG 1.4.3. */
+    textSubtle: 3,
+    accent: 4.5,
+    /**
+     * The accent on a raised surface, where it is a fill rather than a label.
+     *
+     * The same two-tier reasoning as `statusRaised`: a button or a selected tab is a
+     * user-interface component, which WCAG holds to 3:1, and the pairing that
+     * actually carries text — the accent's own label — is measured separately at 4.5
+     * against the accent itself. Holding the accent to 4.5 on every surface instead
+     * made Everforest Light's every hue collapse into its body text, because that
+     * palette's colours are all around 2:1 on its own canvas.
+     */
+    accentRaised: 3,
+    accentForeground: 4.5,
+    /**
+     * Status colours drawn on the canvas, where they are read as small text.
+     */
+    status: 4.5,
+    /**
+     * Status colours drawn on a raised surface, where they are an indicator.
+     *
+     * The two-tier policy is deliberate and it is not a relaxation for convenience.
+     * A status role on a card is nearly always a dot, an icon or a chip's own fill —
+     * a graphical object, which WCAG holds to 3:1 — and it is that way because the
+     * alternative does not exist: Ayu Light and Everforest Light are muted palettes
+     * built for a near-white canvas and neither contains a yellow that is legible as
+     * small text on one. Forcing 4.5:1 there required blending the warning colour
+     * 94% of the way to the body text, which produces a warning that is the same
+     * colour as the text beside it and is therefore not a warning at all.
+     *
+     * A component that renders small status *text* on a raised surface should put it
+     * on the role's `-subtle` fill, which is a tint of the canvas and is measured at
+     * the body floor.
+     */
+    statusRaised: 3,
+    /** A divider is decorative; it must be seen, not read. */
+    border: 1.15,
+    borderMuted: 1.08,
+    /** A raised surface must be distinguishable from the canvas it sits on. */
+    surface: 1.03,
+    /** A selection must be visible under the text it selects. */
+    selection: 1.2,
+});
+/** How far the normalizer may move a colour's lightness before it gives up. */
+/**
+ * How much a repair changed the palette's colour.
+ *
+ * Lightness movement and blending are not equally costly. Moving lightness keeps
+ * the hue and most of the chroma and is what a designer does by hand; blending
+ * toward the foreground gives up chroma, and past roughly a third of the way the
+ * result stops reading as the colour it came from. The weights encode that, and the
+ * score is only ever used to compare two ways of repairing the *same role*, so its
+ * absolute value means nothing.
+ */
+function distortionOf(attempt) {
+    return attempt.blended ? attempt.repair.delta * 3 : attempt.repair.delta;
+}
+const REPAIR_BUDGET = Object.freeze({
+    /** Body text: some palettes publish a foreground that fails on their own canvas. */
+    text: 0.2,
+    status: 0.24,
+    accent: 0.24,
+});
+/** The accent preference order, best first. */
+const ACCENT_PREFERENCE = ['blue', 'magenta', 'cyan', 'green'];
+/** The smallest chroma a colour needs before it reads as "a colour" rather than grey. */
+const MINIMUM_ACCENT_CHROMA = 0.035;
+const SURFACE_STEPS = Object.freeze({
+    surface: 0.035,
+    surfaceElevated: 0.065,
+    surfaceHover: 0.1,
+    surfaceActive: 0.135,
+});
+/**
+ * Which way a raised surface moves from the canvas.
+ *
+ * Measured from the background's lightness rather than taken from the declared
+ * variant. The declaration is authored by hand and has been wrong; the luminance
+ * of the background is not.
+ */
+function ladderDirection(background) {
+    return background.l <= 0.5 ? 1 : -1;
+}
+/** True when the declared variant and the measured canvas agree. */
+export function appearanceMatchesCanvas(appearance, background) {
+    return (background.l <= 0.5 ? 'dark' : 'light') === appearance;
+}
+/**
+ * Builds one rung of the surface ladder.
+ *
+ * Chroma is scaled up slightly rather than held constant: the steps are small
+ * enough that a hue carried at its original chroma reads as a grey smudge, while
+ * the same hue with a little more chroma reads as "the tint this theme is made
+ * of". The scale is modest because a surface is still a surface — at the hover
+ * rung a large scale turns a panel into a coloured button.
+ */
+function surfaceRung(background, step, direction) {
+    const raised = shiftLightness(background, step * direction);
+    const chromaScale = 1 + Math.min(0.6, step * 6);
+    return { ...raised, c: Math.min(0.06, raised.c * chromaScale) };
+}
+/**
+ * Assigns the greyscale ANSI roles.
+ *
+ * Base24 does not name `black`, `white` or `brightBlack` — the background and
+ * foreground slots do double duty — so the mapping is Adea's, and two things about
+ * it are not obvious.
+ *
+ * **It is appearance-aware, because the ANSI greyscale ramp means opposite things
+ * on the two kinds of theme.** On a dark terminal ANSI 0 is a dark neutral used for
+ * text on light fills and ANSI 8 is the dim comment grey; on a light terminal ANSI
+ * 0 *is* the body text. A single fixed rule gets one of the two wrong.
+ *
+ * **`white` and `brightWhite` are read from different slots per appearance.** On a
+ * dark theme they are the two strongest foregrounds, because that is where a dark
+ * palette keeps its light colours. On a light theme the foreground ramp is
+ * *entirely dark* — Gruvbox Light's `base05`, `base06` and `base07` are all
+ * `#3c3836` — so reading "white" off it yields a near-black, and the light colours
+ * have to come from the two slots the palette puts *beyond* its canvas, `base10`
+ * and `base11`. Where a palette leaves those darker than its canvas, the foreground
+ * ramp is used instead.
+ *
+ * Candidates are paired with `base01` and de-duplicated first, because light
+ * schemes routinely set `base05`, `base06` and `base07` to the same value — without
+ * de-duplication the ramp collapses to three members and the roles collide.
+ */
+function buildAnsiRamp(palette, background, appearance) {
+    // Which slots are *foregrounds* depends on the appearance, because Base24's
+    // background slots do double duty. `base01` is the "lighter background" — a
+    // status-bar fill — so on a dark scheme it is a usable mid grey and on a light
+    // scheme it is a second, barely-darker canvas. `base06` and `base07` are the
+    // "light foreground" and "light background", and light schemes routinely set
+    // `base07` to the *lightest* background, which ranks as the dimmest member of the
+    // ramp: including it gave Everforest Light a `brightBlack` of `#fffbef`, a
+    // comment colour 1.16:1 against its own canvas.
+    //
+    // So a light theme's greyscale foregrounds are exactly the three slots Base24
+    // defines as foreground-ish, and a dark theme's include the two extra slots it has
+    // to work with.
+    const candidates = appearance === 'dark'
+        ? [palette.base01, palette.base03, palette.base04, palette.base05, palette.base06, palette.base07]
+        : [palette.base03, palette.base04, palette.base05];
+    const distinct = [];
+    for (const candidate of candidates) {
+        if (distinct.every((kept) => deltaEok(kept, candidate) > 0.02))
+            distinct.push(candidate);
+    }
+    // Strongest first: the ramp is ranked by measured contrast, not by slot number,
+    // because a slot's contrast depends on which appearance the palette is.
+    distinct.sort((a, b) => contrastRatio(b, background) - contrastRatio(a, background));
+    const strongest = distinct[0] ?? palette.base05;
+    const dimmest = distinct[distinct.length - 1] ?? palette.base03;
+    const secondStrongest = distinct[1] ?? strongest;
+    const secondDimmest = distinct[distinct.length - 2] ?? dimmest;
+    if (appearance === 'dark') {
+        return {
+            brightWhite: strongest,
+            white: secondStrongest,
+            black: dimmest,
+            brightBlack: secondDimmest,
+        };
+    }
+    // The two slots a light scheme places beyond its canvas. `base11` is one step
+    // further than `base10`, which is what makes it the brighter of the pair.
+    //
+    // A canvas that is already at the top of the range — Adea's own light theme is
+    // pure white — has nothing beyond it, so the fallback is the *brightest* end of
+    // the foreground ramp rather than the darkest. Falling back to the dimmest would
+    // hand a light theme an ANSI white darker than its own text.
+    const beyondCanvas = [palette.base10, palette.base11].filter((candidate) => candidate.l > background.l);
+    return {
+        brightWhite: beyondCanvas[1] ?? beyondCanvas[0] ?? strongest,
+        white: beyondCanvas[0] ?? secondStrongest,
+        black: strongest,
+        brightBlack: dimmest,
+    };
+}
+/** Formats a role, pairing the value with the finding it produced if any. */
+function emit(themeId, role, repair, floor, blended = false) {
+    if (repair.satisfied && repair.delta === 0)
+        return { value: formatOklch(repair.color) };
+    if (repair.satisfied) {
+        return {
+            value: formatOklch(repair.color),
+            finding: {
+                themeId,
+                role,
+                kind: 'repaired',
+                message: blended
+                    ? `blended ${(repair.delta * 100).toFixed(0)}% into the foreground to reach ${floor}:1 (now ${repair.ratio.toFixed(2)}:1)`
+                    : `lightness moved ${repair.delta.toFixed(3)} to reach ${floor}:1 (now ${repair.ratio.toFixed(2)}:1)`,
+            },
+        };
+    }
+    return {
+        value: formatOklch(repair.color),
+        finding: {
+            themeId,
+            role,
+            kind: 'budget-exceeded',
+            message: `still ${repair.ratio.toFixed(2)}:1 against the canvas after the maximum lightness move; needs ${floor}:1`,
+        },
+    };
+}
+/**
+ * Chooses the accent.
+ *
+ * The accent is the one colour a UI uses for "this is interactive", so it is
+ * chosen by measurement rather than by convention: candidates are tried in a fixed
+ * preference order (blue first, because a blue accent is what most of these
+ * palettes were designed around) and the first that clears the text floor within
+ * budget, while still being *a* colour rather than a grey, wins. A family whose
+ * identity lies elsewhere — Everforest is green, Rosé Pine is iris — declares its
+ * slot explicitly, and that declaration is honoured before any preference.
+ */
+function chooseAccent(themeId, ansi, surfaces, preferred, anchor) {
+    const findings = [];
+    const background = surfaces[0];
+    const order = preferred ? [preferred, ...ACCENT_PREFERENCE] : ACCENT_PREFERENCE;
+    let fallback;
+    const satisfying = [];
+    for (const role of order) {
+        const candidate = ansi[role];
+        if (!candidate || candidate.c < MINIMUM_ACCENT_CHROMA)
+            continue;
+        // Two tiers, as for the status roles: the link floor on the canvas, then the
+        // component floor on a raised surface, applied in sequence.
+        const onCanvas = repairRole(candidate, [background], anchor, CONTRAST_FLOORS.accent, REPAIR_BUDGET.accent);
+        if (!onCanvas.repair.satisfied) {
+            if (!fallback || onCanvas.repair.ratio > fallback.repair.ratio) {
+                fallback = { role, repair: onCanvas.repair };
+            }
+            continue;
+        }
+        const onRaised = repairRole(onCanvas.repair.color, surfaces.slice(1), anchor, CONTRAST_FLOORS.accentRaised, REPAIR_BUDGET.accent);
+        const attempt = {
+            repair: {
+                color: onRaised.repair.color,
+                ratio: onRaised.repair.ratio,
+                delta: onCanvas.repair.delta + onRaised.repair.delta,
+                satisfied: onRaised.repair.satisfied,
+            },
+            blended: onCanvas.blended || onRaised.blended,
+        };
+        if (attempt.repair.satisfied) {
+            satisfying.push({ role, repair: attempt.repair, distortion: distortionOf(attempt), blended: attempt.blended });
+            continue;
+        }
+        // Track the best attempt so a theme that cannot satisfy the floor still gets
+        // its most legible candidate rather than an arbitrary one.
+        if (!fallback || attempt.repair.ratio > fallback.repair.ratio) {
+            fallback = { role, repair: attempt.repair };
+        }
+    }
+    if (satisfying.length > 0) {
+        // A declared accent is honoured whenever it can be reached without giving the
+        // colour up. Lightness movement *is* what a palette author does to make an
+        // accent usable — Rosé Pine's iris needs a 0.11 step on its light variant and is
+        // still unmistakably iris — so a lightness repair never costs a family its
+        // identity. Blending does: past about a third of the way the result stops being
+        // the colour it came from, and a green repaired into slate is no longer
+        // Everforest's accent.
+        //
+        // So the declared slot wins unless it had to be blended; if it did — or if none
+        // was declared — the least-distorted candidate wins, with the preference order
+        // breaking ties.
+        const cheapest = satisfying.reduce((best, entry) => entry.distortion < best.distortion ? entry : best);
+        const declared = preferred ? satisfying.find((entry) => entry.role === preferred) : undefined;
+        const chosen = declared && !declared.blended ? declared : cheapest;
+        if (chosen.role !== preferred && preferred) {
+            findings.push({
+                themeId,
+                role: 'accent',
+                kind: 'substituted',
+                message: declared
+                    ? `the declared accent slot ${preferred} could only clear the floor by blending ${(declared.repair.delta * 100).toFixed(0)}% into the foreground; used ${chosen.role} at ${(chosen.repair.delta * 100).toFixed(0)}% instead`
+                    : `the declared accent slot ${preferred} could not clear the floor; used ${chosen.role} instead`,
+            });
+        }
+        if (chosen.repair.delta > 0.01) {
+            findings.push({
+                themeId,
+                role: 'accent',
+                kind: 'repaired',
+                message: chosen.blended
+                    ? `blended ${(chosen.repair.delta * 100).toFixed(0)}% into the foreground from the palette's ${chosen.role}`
+                    : `lightness moved ${chosen.repair.delta.toFixed(3)} from the palette's ${chosen.role}`,
+            });
+        }
+        return { role: chosen.role, repair: chosen.repair, findings };
+    }
+    const chosen = fallback ?? {
+        role: 'blue',
+        repair: repairContrast(background, background, 1),
+    };
+    findings.push({
+        themeId,
+        role: 'accent',
+        kind: 'budget-exceeded',
+        message: `no accent candidate cleared ${CONTRAST_FLOORS.accent}:1; the best was ${chosen.role} at ${chosen.repair.ratio.toFixed(2)}:1`,
+    });
+    return { role: chosen.role, repair: chosen.repair, findings };
+}
+/**
+ * Picks the text colour drawn on top of the accent.
+ *
+ * Not derived from the appearance, which is the tempting shortcut and is wrong:
+ * Catppuccin Mocha's blue accent is light enough that black is the legible label,
+ * while Nord's is dark enough that white is. The pick is whichever of the
+ * palette's own two extremes measures better, repaired if neither clears the floor.
+ */
+function chooseAccentForeground(themeId, accent, palette) {
+    const findings = [];
+    const candidates = [palette.base00, palette.base07, palette.base05, palette.base06];
+    let best = candidates[0];
+    let bestRatio = contrastRatio(best, accent);
+    for (const candidate of candidates.slice(1)) {
+        const ratio = contrastRatio(candidate, accent);
+        if (ratio > bestRatio) {
+            best = candidate;
+            bestRatio = ratio;
+        }
+    }
+    const repair = repairContrast(best, accent, CONTRAST_FLOORS.accentForeground, 0.6);
+    if (!repair.satisfied) {
+        findings.push({
+            themeId,
+            role: 'accentForeground',
+            kind: 'budget-exceeded',
+            message: `only ${repair.ratio.toFixed(2)}:1 against the accent; needs ${CONTRAST_FLOORS.accentForeground}:1`,
+        });
+    }
+    return { value: repair.color, findings };
+}
+/**
+ * Moves a colour's lightness until it clears a floor against **every** surface it
+ * can be drawn on.
+ *
+ * This is the difference between a theme that is legible on its canvas and a theme
+ * that is legible in the application. `repairContrast` measures against one
+ * background, which is right for a terminal and wrong for a UI: a status colour is
+ * as likely to appear inside a card or a popover as on the canvas, and those rungs
+ * are deliberately moved away from the canvas, so a colour tuned to exactly 4.5:1
+ * on the background lands at roughly 4.0:1 on a card.
+ *
+ * The surfaces of one theme all sit on the same side of the canvas, so the surface
+ * with the *lowest* current ratio is the furthest from the colour, and moving away
+ * from it moves away from all of them. The worst surface is recomputed on every
+ * step rather than chosen once, because a colour can cross between them.
+ */
+function repairAcrossSurfaces(color, surfaces, minimum, budget) {
+    // Measured in the canonical form the catalogue commits, so a repair cannot
+    // converge on a value that rounding then pushes back below the floor.
+    const worst = (candidate) => {
+        const rounded = canonical(candidate);
+        let result = { surface: surfaces[0], ratio: Number.POSITIVE_INFINITY };
+        for (const surface of surfaces) {
+            const ratio = contrastRatio(rounded, surface);
+            if (ratio < result.ratio)
+                result = { surface, ratio };
+        }
+        return result;
+    };
+    const initial = worst(color);
+    if (initial.ratio >= minimum) {
+        return { color, ratio: initial.ratio, delta: 0, satisfied: true };
+    }
+    const direction = contrastDirection(color, initial.surface);
+    const step = 0.002;
+    const maximumSteps = Math.floor(budget / step);
+    for (let index = 1; index <= maximumSteps; index += 1) {
+        const candidate = { ...color, l: color.l + direction * step * index };
+        if (candidate.l <= 0 || candidate.l >= 1)
+            break;
+        const measured = worst(candidate);
+        if (measured.ratio >= minimum) {
+            return {
+                color: candidate,
+                ratio: measured.ratio,
+                delta: Number((step * index).toFixed(4)),
+                satisfied: true,
+            };
+        }
+    }
+    return { color, ratio: initial.ratio, delta: 0, satisfied: false };
+}
+/**
+ * Repairs a colour that cannot reach the floor by lightness alone, by blending it
+ * toward the palette's own foreground.
+ *
+ * Everforest Light is why this exists. Its entire palette is muted pastels chosen
+ * for a cream canvas, and its brightest accents measure 1.6:1 against that canvas —
+ * no lightness move fixes that within a budget that leaves the colour recognisable,
+ * because the colour is already as dark as its own hue allows. Darkening it further
+ * produces olive.
+ *
+ * Blending toward the palette's foreground instead is what the palette's own author
+ * does when they need a colour to be read rather than seen: it keeps the hue, gives
+ * up chroma, and converges on the foreground's contrast as the blend approaches 1.
+ * The result is a muted, deeper version of the accent — which is what Everforest's
+ * light themes actually look like.
+ *
+ * The blend is bound by the foreground, so it always terminates; and when even a
+ * full blend cannot clear the floor, the theme is reported rather than shipped with
+ * an invented colour.
+ */
+function repairByBlending(color, surfaces, anchor, minimum) {
+    const worstRatio = (candidate) => Math.min(...surfaces.map((surface) => contrastRatio(canonical(candidate), surface)));
+    let low = 0;
+    let high = 1;
+    if (worstRatio(anchor) < minimum) {
+        return { color, ratio: worstRatio(color), delta: 0, satisfied: false };
+    }
+    // The smallest blend that works: 20 iterations resolve the amount far below the
+    // precision the catalogue is committed at.
+    for (let iteration = 0; iteration < 20; iteration += 1) {
+        const mid = (low + high) / 2;
+        if (worstRatio(mix(color, anchor, mid)) >= minimum)
+            high = mid;
+        else
+            low = mid;
+    }
+    const blended = canonical(mix(color, anchor, high));
+    return {
+        color: blended,
+        ratio: worstRatio(blended),
+        delta: Number(high.toFixed(4)),
+        satisfied: true,
+    };
+}
+/**
+ * The full repair chain for a foreground role.
+ *
+ * Lightness first, because that is the cheapest change and usually enough; blending
+ * second, because some palettes cannot be repaired any other way. Both are reported
+ * so a reviewer can see which themes needed which.
+ */
+function repairRole(color, surfaces, anchor, minimum, budget) {
+    const lightness = repairAcrossSurfaces(color, surfaces, minimum, budget);
+    if (lightness.satisfied)
+        return { repair: lightness, blended: false };
+    const blend = repairByBlending(color, surfaces, anchor, minimum);
+    if (blend.satisfied)
+        return { repair: blend, blended: true };
+    return { repair: lightness, blended: false };
+}
+/**
+ * Normalizes one source into a catalogue entry.
+ *
+ * Pure: the same inputs always produce the same theme and the same findings, which
+ * is what lets the committed catalogue be regenerated and diffed in CI.
+ */
+export function normalizeTheme(source) {
+    const findings = [];
+    const vendored = parseBase24Palette(source.scheme.palette);
+    // Corrections are applied to the palette before anything derives from it, so the
+    // surface ladder, the accent and every floor are computed from the value that
+    // will actually ship. Correcting the output instead would leave the ladder built
+    // around a background that is not the background.
+    const palette = { ...vendored };
+    for (const [slot, value] of Object.entries(source.palette ?? {})) {
+        const parsed = parseColor(value);
+        if (!parsed)
+            throw new Error(`${source.id}: palette correction for ${slot} is not a colour`);
+        palette[slot] = parsed;
+        findings.push({
+            themeId: source.id,
+            role: slot,
+            kind: 'substituted',
+            message: `replaced the vendored ${slot} with the upstream project's own value`,
+        });
+    }
+    const background = palette.base00;
+    const appearance = ladderDirection(background) === 1 ? 'dark' : 'light';
+    if (appearance !== source.appearance) {
+        findings.push({
+            themeId: source.id,
+            role: 'appearance',
+            kind: 'substituted',
+            message: `declared ${source.appearance} but the canvas measures ${appearance}; used the measurement`,
+        });
+    }
+    const direction = ladderDirection(background);
+    const surface = surfaceRung(background, SURFACE_STEPS.surface, direction);
+    const surfaceElevated = surfaceRung(background, SURFACE_STEPS.surfaceElevated, direction);
+    const surfaceHover = surfaceRung(background, SURFACE_STEPS.surfaceHover, direction);
+    const surfaceActive = surfaceRung(background, SURFACE_STEPS.surfaceActive, direction);
+    /**
+     * Every surface a foreground role can be drawn on.
+     *
+     * The interaction rungs are excluded: text is not placed on a hover fill without
+     * the component also choosing a foreground for it, and holding every role to the
+     * furthest rung would compress the whole palette for a case that does not occur.
+     */
+    const surfaces = [background, surface, surfaceElevated];
+    const colors = {
+        background: formatOklch(background),
+        foreground: formatOklch(palette.base05),
+        surface: formatOklch(surface),
+        surfaceElevated: formatOklch(surfaceElevated),
+        surfaceHover: formatOklch(surfaceHover),
+        surfaceActive: formatOklch(surfaceActive),
+        border: formatOklch({
+            ...surfaceRung(background, 0.15, direction),
+            c: Math.min(0.05, background.c * 0.9),
+        }),
+        borderMuted: formatOklch({
+            ...surfaceRung(background, 0.095, direction),
+            c: Math.min(0.04, background.c * 0.6),
+        }),
+        text: formatOklch(palette.base05),
+        textMuted: '',
+        textSubtle: '',
+        accent: '',
+        accentForeground: '',
+        success: '',
+        warning: '',
+        error: '',
+        info: '',
+    };
+    // Body text first: several palettes publish a foreground that fails on their own
+    // background, and every other role's floors are measured against the canvas.
+    const textRepair = repairAcrossSurfaces(palette.base05, surfaces, CONTRAST_FLOORS.text, REPAIR_BUDGET.text);
+    const text = emit(source.id, 'text', textRepair, CONTRAST_FLOORS.text);
+    colors.text = text.value;
+    colors.foreground = text.value;
+    if (text.finding)
+        findings.push(text.finding);
+    // Muted and subtle text are blends toward the canvas, then measured. Blending in
+    // OKLCH rather than alpha-compositing keeps the result a real colour that CSS can
+    // use without a backdrop.
+    const mutedRepair = repairAcrossSurfaces(mix(palette.base05, background, 0.32), surfaces, CONTRAST_FLOORS.textMuted, 0.3);
+    const muted = emit(source.id, 'textMuted', mutedRepair, CONTRAST_FLOORS.textMuted);
+    colors.textMuted = muted.value;
+    if (muted.finding)
+        findings.push(muted.finding);
+    const subtleRepair = repairAcrossSurfaces(palette.base03, surfaces, CONTRAST_FLOORS.textSubtle, 0.3);
+    const subtle = emit(source.id, 'textSubtle', subtleRepair, CONTRAST_FLOORS.textSubtle);
+    colors.textSubtle = subtle.value;
+    if (subtle.finding)
+        findings.push(subtle.finding);
+    /**
+     * The status roles, each with fallback candidates.
+     *
+     * A palette's yellow is chosen to be *a* yellow, not to be legible as text — Ayu
+     * Light's `#ffcc66` measures 1.9:1 on its own near-white canvas, and no amount of
+     * lightness repair fixes that without turning it into olive, which is no longer
+     * Ayu. So each status role has candidates and takes the first that clears the
+     * floor: warnings fall back to the palette's orange slot, which is Base24's
+     * constants colour and in practice the warning colour this palette already uses;
+     * reds and greens fall back to their bright variants.
+     *
+     * The order is not "brightest first" — on a light canvas the bright variants are
+     * worse, so the declared ANSI colour is always tried before its bright sibling.
+     */
+    const statusCandidates = {
+        error: [palette.base08, palette.base12],
+        success: [palette.base0B, palette.base14],
+        warning: [palette.base0A, palette.base09],
+        info: [palette.base0C, palette.base0D],
+    };
+    for (const [role, candidates] of Object.entries(statusCandidates)) {
+        const key = role;
+        let chosen;
+        for (const candidate of candidates) {
+            // Two tiers, applied in sequence: the body floor on the canvas, then the
+            // indicator floor on the raised surfaces. Both push the colour the same way,
+            // so applying the second to the result of the first cannot undo it.
+            //
+            // The blend anchor is the *repaired* text colour rather than the palette's
+            // raw foreground: when a palette's own body text fails the floor on a raised
+            // surface, blending toward the raw value inherits that failure and the blend
+            // has no valid endpoint.
+            const onCanvas = repairRole(candidate, [background], textRepair.color, CONTRAST_FLOORS.status, REPAIR_BUDGET.status);
+            if (!onCanvas.repair.satisfied) {
+                if (!chosen || onCanvas.repair.ratio > chosen.repair.ratio)
+                    chosen = onCanvas;
+                continue;
+            }
+            const onRaised = repairRole(onCanvas.repair.color, surfaces.slice(1), textRepair.color, CONTRAST_FLOORS.statusRaised, REPAIR_BUDGET.status);
+            const combined = {
+                repair: {
+                    color: onRaised.repair.color,
+                    ratio: onRaised.repair.ratio,
+                    delta: onCanvas.repair.delta + onRaised.repair.delta,
+                    satisfied: onRaised.repair.satisfied,
+                },
+                blended: onCanvas.blended || onRaised.blended,
+            };
+            if (combined.repair.satisfied) {
+                chosen = combined;
+                break;
+            }
+            if (!chosen || combined.repair.ratio > chosen.repair.ratio)
+                chosen = combined;
+        }
+        const result = emit(source.id, key, chosen.repair, CONTRAST_FLOORS.statusRaised, chosen.blended);
+        colors[key] = result.value;
+        if (result.finding)
+            findings.push(result.finding);
+        if (chosen.blended) {
+            findings.push({
+                themeId: source.id,
+                role: key,
+                kind: 'repaired',
+                message: `blended ${(chosen.repair.delta * 100).toFixed(0)}% toward the theme's own foreground; lightness alone could not reach the floors`,
+            });
+        }
+    }
+    const ramp = buildAnsiRamp(palette, background, appearance);
+    const ansi = {
+        black: formatOklch(ramp.black),
+        red: formatOklch(palette.base08),
+        green: formatOklch(palette.base0B),
+        yellow: formatOklch(palette.base0A),
+        blue: formatOklch(palette.base0D),
+        magenta: formatOklch(palette.base0E),
+        cyan: formatOklch(palette.base0C),
+        white: formatOklch(ramp.white),
+        brightBlack: formatOklch(ramp.brightBlack),
+        brightRed: formatOklch(palette.base12),
+        brightGreen: formatOklch(palette.base14),
+        brightYellow: formatOklch(palette.base13),
+        brightBlue: formatOklch(palette.base16),
+        brightMagenta: formatOklch(palette.base17),
+        brightCyan: formatOklch(palette.base15),
+        brightWhite: formatOklch(ramp.brightWhite),
+    };
+    const ansiColors = Object.fromEntries(Object.entries(ansi).map(([key]) => [key, palette[ansiToSlot(key, palette, ramp)]]));
+    const accent = chooseAccent(source.id, ansiColors, surfaces, source.accentSlot, textRepair.color);
+    findings.push(...accent.findings);
+    colors.accent = formatOklch(accent.repair.color);
+    if (accent.repair.delta > 0) {
+        findings.push({
+            themeId: source.id,
+            role: 'accent',
+            kind: 'repaired',
+            message: `lightness moved ${accent.repair.delta.toFixed(3)} to reach ${CONTRAST_FLOORS.accent}:1 against the canvas`,
+        });
+    }
+    const accentForeground = chooseAccentForeground(source.id, accent.repair.color, palette);
+    colors.accentForeground = formatOklch(accentForeground.value);
+    findings.push(...accentForeground.findings);
+    // The selection is the palette's own, repaired only if it is invisible against
+    // the canvas. Adapters handle making text legible on top of it.
+    const selectionSource = source.selection
+        ? palette.base02
+        : palette.base02;
+    const selectionRepair = repairContrast(selectionSource, background, CONTRAST_FLOORS.selection, 0.5);
+    const selection = emit(source.id, 'selection', selectionRepair, CONTRAST_FLOORS.selection);
+    if (selection.finding)
+        findings.push(selection.finding);
+    // Authored overrides, applied last so they win over derivation. They go through
+    // the same conversion as every derived value: the catalogue's contract is that a
+    // role is an `oklch()` string, and an override written as hex in the source list
+    // must not be the one place that contract leaks.
+    if (source.colors) {
+        for (const [role, value] of Object.entries(source.colors)) {
+            colors[role] = authoredColor(source.id, role, value);
+        }
+    }
+    if (source.ansi) {
+        for (const [role, value] of Object.entries(source.ansi)) {
+            ansi[role] = authoredColor(source.id, role, value);
+        }
+    }
+    return {
+        record: {
+            id: source.id,
+            name: source.name,
+            appearance,
+            colors,
+            ansi,
+            cursor: source.cursor
+                ? authoredColor(source.id, 'cursor', source.cursor)
+                : formatOklch(palette.base05),
+            selection: source.selection
+                ? authoredColor(source.id, 'selection', source.selection)
+                : selection.value,
+            family: source.family,
+            familyLabel: source.familyLabel,
+            label: source.label,
+            description: source.description,
+            provenance: {
+                project: '',
+                url: '',
+                license: '',
+            },
+            tags: source.tags,
+        },
+        findings,
+    };
+}
+/** Parses an authored value and re-serialises it in the catalogue's notation. */
+function authoredColor(themeId, role, value) {
+    const parsed = parseColor(value);
+    if (!parsed)
+        throw new Error(`${themeId}: ${role} is not a colour: ${value}`);
+    return formatOklch(parsed);
+}
+/** Maps an ANSI role back to the Base24 slot it was read from. */
+function ansiToSlot(role, palette, ramp) {
+    const direct = {
+        red: 'base08',
+        green: 'base0B',
+        yellow: 'base0A',
+        blue: 'base0D',
+        magenta: 'base0E',
+        cyan: 'base0C',
+        brightRed: 'base12',
+        brightYellow: 'base13',
+        brightGreen: 'base14',
+        brightCyan: 'base15',
+        brightBlue: 'base16',
+        brightMagenta: 'base17',
+    };
+    const slot = direct[role];
+    if (slot)
+        return slot;
+    const rampSlots = {
+        black: ramp.black,
+        white: ramp.white,
+        brightBlack: ramp.brightBlack,
+        brightWhite: ramp.brightWhite,
+    };
+    const target = rampSlots[role];
+    if (!target)
+        return 'base05';
+    const match = Object.keys(palette).find((candidate) => deltaEok(palette[candidate], target) < 1e-9);
+    return match ?? 'base05';
+}
+/** Re-exported so the normalizer's callers do not need a second import. */
+export { contrastDirection };
+//# sourceMappingURL=normalize.js.map