@compilr-dev/sdk 0.18.9 → 0.18.11

package/dist/canvas/color.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Colour arithmetic for canvas checks and for the host's surface ramp.
+ *
+ * ⚠️ WHY THIS EXISTS. Three real terminal palettes, as the host injects them today:
+ * Tokyo Night puts `--canvas-card` 2.1% from `--canvas-bg`, Catppuccin Latte 0.0%,
+ * Gruvbox Dark 1.8%. A card that shares its ground's value is a rectangle of text, and
+ * no prompt has ever prevented it — the values simply are not far apart enough. The
+ * agent is not doing anything wrong.
+ *
+ * So the numbers have to be computed somewhere. Here, as pure functions with no I/O, so
+ * the same maths serves the validator (does this canvas fail?) and the host (what ramp
+ * should I inject?) without either owning it.
+ *
+ * ⚠️ OKLab lightness, not HSL's. HSL calls #FFFF00 and #0000FF both "50% lightness",
+ * which would rate yellow-on-blue as a zero-contrast pair. OKLab's L tracks perceived
+ * lightness, which is what "5–7% apart" has to mean to be worth asserting.
+ *
+ * WCAG contrast is separate and deliberately NOT OKLab — the 4.5:1 threshold is defined
+ * against sRGB relative luminance, so using anything else would be asserting a different
+ * rule than the one being cited.
+ */
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * A CSS colour literal → rgb in 0..1, or null when it is not one.
+ *
+ * ⚠️ Returns null for `var(--x)` ON PURPOSE, and callers depend on it: a custom property
+ * has no value until the host resolves it, and guessing one would produce confident
+ * arithmetic about a colour nobody has chosen yet.
+ */
+export declare function parseColor(input: string): Rgb | null;
+/** sRGB relative luminance, per WCAG 2.x. */
+export declare function relativeLuminance({ r, g, b }: Rgb): number;
+/** WCAG contrast ratio, 1..21. Order-independent. */
+export declare function contrastRatio(a: Rgb, b: Rgb): number;
+/**
+ * OKLab lightness, 0..1 — perceived lightness, which is what the 5–7% target means.
+ * Coefficients from Björn Ottosson's OKLab definition.
+ */
+export declare function oklabLightness({ r, g, b }: Rgb): number;
+/** Perceived lightness distance between two colours, in percentage points. */
+export declare function lightnessDeltaPct(a: Rgb, b: Rgb): number;
+/**
+ * Is this colour a neutral (a grey), rather than a hue?
+ *
+ * Used to count "non-neutral hues": greys are the ground the composition sits on and
+ * never count against the accent budget, however many of them there are.
+ */
+export declare function isNeutral({ r, g, b }: Rgb, tolerance?: number): boolean;
+/** Hue angle in degrees, 0..360. Meaningless for a neutral — check `isNeutral` first. */
+export declare function hueAngle({ r, g, b }: Rgb): number;
+/** The floor for text, per WCAG AA at normal size. */
+export declare const AA_TEXT = 4.5;
+/**
+ * The target separation between adjacent surfaces, in OKLab percentage points.
+ *
+ * Below MIN it disappears; above MAX the card reads as a separate page rather than a
+ * raised surface. Exported so the host's ramp and the validator cannot disagree.
+ *
+ * ⚠️ MIN IS CALIBRATED TO THE HANDOFF'S SPECIMENS, NOT TO ITS STATED NUMBER, and the
+ * difference matters. Section 01 says "below 3%" and reports its three palettes at 2.1%,
+ * 0.0% and 1.8% — but those figures reproduce under no standard metric: Tokyo Night's
+ * pair measures 3.5 in OKLab, 4.0 in CIE L*, 3.9 in HSL. The formula behind them is not
+ * stated, so adopting the number would be asserting arithmetic nobody can check.
+ *
+ * The SPECIMENS are sound, though — they are real palettes a designer looked at and
+ * judged muddy, and the same section gives a corrected ramp for each. So MIN is set where
+ * it separates the two groups in the metric actually used here:
+ *
+ *     as injected (must fail)   3.5 · 0.0 · 3.4
+ *     derived ramp (must pass)  5.6 · 7.5 · 6.1
+ *
+ * 4 sits between them with room on both sides. `canvas-color.test.ts` asserts that
+ * separation directly rather than any single figure, so a future metric change has to
+ * keep sorting the real palettes correctly instead of matching a constant.
+ */
+export declare const SURFACE_DELTA_MIN = 4;
+export declare const SURFACE_DELTA_TARGET = 6;
+export declare const SURFACE_DELTA_MAX = 12;
+/** A hairline sits this far toward the foreground — never more. */
+export declare const HAIRLINE_MIN_PCT = 10;
+export declare const HAIRLINE_MAX_PCT = 15;

package/dist/canvas/color.js

@@ -0,0 +1,216 @@
+/**
+ * Colour arithmetic for canvas checks and for the host's surface ramp.
+ *
+ * ⚠️ WHY THIS EXISTS. Three real terminal palettes, as the host injects them today:
+ * Tokyo Night puts `--canvas-card` 2.1% from `--canvas-bg`, Catppuccin Latte 0.0%,
+ * Gruvbox Dark 1.8%. A card that shares its ground's value is a rectangle of text, and
+ * no prompt has ever prevented it — the values simply are not far apart enough. The
+ * agent is not doing anything wrong.
+ *
+ * So the numbers have to be computed somewhere. Here, as pure functions with no I/O, so
+ * the same maths serves the validator (does this canvas fail?) and the host (what ramp
+ * should I inject?) without either owning it.
+ *
+ * ⚠️ OKLab lightness, not HSL's. HSL calls #FFFF00 and #0000FF both "50% lightness",
+ * which would rate yellow-on-blue as a zero-contrast pair. OKLab's L tracks perceived
+ * lightness, which is what "5–7% apart" has to mean to be worth asserting.
+ *
+ * WCAG contrast is separate and deliberately NOT OKLab — the 4.5:1 threshold is defined
+ * against sRGB relative luminance, so using anything else would be asserting a different
+ * rule than the one being cited.
+ */
+const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
+const HEX = /^#?([0-9a-f]{3,8})$/i;
+/** `#abc` · `#aabbcc` · `#aabbccdd` → rgb. Alpha is parsed and discarded, not rejected. */
+function parseHex(input) {
+    const m = HEX.exec(input.trim());
+    if (!m)
+        return null;
+    let hex = m[1];
+    // 3 and 4 digit forms double each nibble; 4 and 8 carry alpha we drop.
+    if (hex.length === 3 || hex.length === 4) {
+        hex = hex
+            .split('')
+            .map((c) => c + c)
+            .join('');
+    }
+    if (hex.length !== 6 && hex.length !== 8)
+        return null;
+    return {
+        r: parseInt(hex.slice(0, 2), 16) / 255,
+        g: parseInt(hex.slice(2, 4), 16) / 255,
+        b: parseInt(hex.slice(4, 6), 16) / 255,
+    };
+}
+/** One `rgb()`/`rgba()` channel: `200`, `78%`, or `.5` for alpha (which we drop). */
+function channel(raw) {
+    const t = raw.trim();
+    if (!t)
+        return null;
+    const pct = t.endsWith('%');
+    const n = Number.parseFloat(pct ? t.slice(0, -1) : t);
+    if (!Number.isFinite(n))
+        return null;
+    return clamp01(pct ? n / 100 : n / 255);
+}
+const FUNC = /^(rgba?|hsla?)\s*\(([^)]*)\)$/i;
+/**
+ * ⚠️ Splits on commas AND whitespace, because both spellings are legal and in the wild:
+ * `rgb(10, 20, 30)` and `rgb(10 20 30 / 50%)`. The slash-separated alpha is dropped with
+ * the rest — every caller here asks about hue and lightness, never transparency.
+ */
+const parts = (body) => body
+    .replace(/\//g, ' ')
+    .split(/[,\s]+/)
+    .map((p) => p.trim())
+    .filter(Boolean);
+function hueToRgb(p, q, t) {
+    let x = t;
+    if (x < 0)
+        x += 1;
+    if (x > 1)
+        x -= 1;
+    if (x < 1 / 6)
+        return p + (q - p) * 6 * x;
+    if (x < 1 / 2)
+        return q;
+    if (x < 2 / 3)
+        return p + (q - p) * (2 / 3 - x) * 6;
+    return p;
+}
+function parseHsl(body) {
+    const p = parts(body);
+    if (p.length < 3)
+        return null;
+    const h = Number.parseFloat(p[0]);
+    const s = Number.parseFloat(p[1]) / 100;
+    const l = Number.parseFloat(p[2]) / 100;
+    if (!Number.isFinite(h) || !Number.isFinite(s) || !Number.isFinite(l))
+        return null;
+    const hn = (((h % 360) + 360) % 360) / 360;
+    const sn = clamp01(s);
+    const ln = clamp01(l);
+    if (sn === 0)
+        return { r: ln, g: ln, b: ln };
+    const q = ln < 0.5 ? ln * (1 + sn) : ln + sn - ln * sn;
+    const pp = 2 * ln - q;
+    return {
+        r: hueToRgb(pp, q, hn + 1 / 3),
+        g: hueToRgb(pp, q, hn),
+        b: hueToRgb(pp, q, hn - 1 / 3),
+    };
+}
+/**
+ * A CSS colour literal → rgb in 0..1, or null when it is not one.
+ *
+ * ⚠️ Returns null for `var(--x)` ON PURPOSE, and callers depend on it: a custom property
+ * has no value until the host resolves it, and guessing one would produce confident
+ * arithmetic about a colour nobody has chosen yet.
+ */
+export function parseColor(input) {
+    const t = input.trim();
+    if (!t)
+        return null;
+    const hex = parseHex(t);
+    if (hex)
+        return hex;
+    const m = FUNC.exec(t);
+    if (!m)
+        return null;
+    const fn = m[1].toLowerCase();
+    if (fn === 'hsl' || fn === 'hsla')
+        return parseHsl(m[2]);
+    const p = parts(m[2]);
+    if (p.length < 3)
+        return null;
+    const [r, g, b] = [channel(p[0]), channel(p[1]), channel(p[2])];
+    if (r === null || g === null || b === null)
+        return null;
+    return { r, g, b };
+}
+const linear = (c) => c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+/** sRGB relative luminance, per WCAG 2.x. */
+export function relativeLuminance({ r, g, b }) {
+    return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+/** WCAG contrast ratio, 1..21. Order-independent. */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const [hi, lo] = la >= lb ? [la, lb] : [lb, la];
+    return (hi + 0.05) / (lo + 0.05);
+}
+/**
+ * OKLab lightness, 0..1 — perceived lightness, which is what the 5–7% target means.
+ * Coefficients from Björn Ottosson's OKLab definition.
+ */
+export function oklabLightness({ r, g, b }) {
+    const lr = linear(r);
+    const lg = linear(g);
+    const lb = linear(b);
+    const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+    const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+    const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+    return clamp01(0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s);
+}
+/** Perceived lightness distance between two colours, in percentage points. */
+export function lightnessDeltaPct(a, b) {
+    return Math.abs(oklabLightness(a) - oklabLightness(b)) * 100;
+}
+/**
+ * Is this colour a neutral (a grey), rather than a hue?
+ *
+ * Used to count "non-neutral hues": greys are the ground the composition sits on and
+ * never count against the accent budget, however many of them there are.
+ */
+export function isNeutral({ r, g, b }, tolerance = 0.06) {
+    return Math.max(r, g, b) - Math.min(r, g, b) <= tolerance;
+}
+/** Hue angle in degrees, 0..360. Meaningless for a neutral — check `isNeutral` first. */
+export function hueAngle({ r, g, b }) {
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const d = max - min;
+    if (d === 0)
+        return 0;
+    let h;
+    if (max === r)
+        h = ((g - b) / d) % 6;
+    else if (max === g)
+        h = (b - r) / d + 2;
+    else
+        h = (r - g) / d + 4;
+    h *= 60;
+    return h < 0 ? h + 360 : h;
+}
+/** The floor for text, per WCAG AA at normal size. */
+export const AA_TEXT = 4.5;
+/**
+ * The target separation between adjacent surfaces, in OKLab percentage points.
+ *
+ * Below MIN it disappears; above MAX the card reads as a separate page rather than a
+ * raised surface. Exported so the host's ramp and the validator cannot disagree.
+ *
+ * ⚠️ MIN IS CALIBRATED TO THE HANDOFF'S SPECIMENS, NOT TO ITS STATED NUMBER, and the
+ * difference matters. Section 01 says "below 3%" and reports its three palettes at 2.1%,
+ * 0.0% and 1.8% — but those figures reproduce under no standard metric: Tokyo Night's
+ * pair measures 3.5 in OKLab, 4.0 in CIE L*, 3.9 in HSL. The formula behind them is not
+ * stated, so adopting the number would be asserting arithmetic nobody can check.
+ *
+ * The SPECIMENS are sound, though — they are real palettes a designer looked at and
+ * judged muddy, and the same section gives a corrected ramp for each. So MIN is set where
+ * it separates the two groups in the metric actually used here:
+ *
+ *     as injected (must fail)   3.5 · 0.0 · 3.4
+ *     derived ramp (must pass)  5.6 · 7.5 · 6.1
+ *
+ * 4 sits between them with room on both sides. `canvas-color.test.ts` asserts that
+ * separation directly rather than any single figure, so a future metric change has to
+ * keep sorting the real palettes correctly instead of matching a constant.
+ */
+export const SURFACE_DELTA_MIN = 4;
+export const SURFACE_DELTA_TARGET = 6;
+export const SURFACE_DELTA_MAX = 12;
+/** A hairline sits this far toward the foreground — never more. */
+export const HAIRLINE_MIN_PCT = 10;
+export const HAIRLINE_MAX_PCT = 15;

package/dist/canvas/index.d.ts

@@ -4,3 +4,9 @@
  */
 export * from './types.js';
 export * from './validate.js';
+export { parseColor, relativeLuminance, contrastRatio, oklabLightness, lightnessDeltaPct, isNeutral, hueAngle, AA_TEXT, SURFACE_DELTA_MIN, SURFACE_DELTA_TARGET, SURFACE_DELTA_MAX, HAIRLINE_MIN_PCT, HAIRLINE_MAX_PCT, } from './color.js';
+export type { Rgb } from './color.js';
+export { runQualityChecks, checkSurfaceTokens, checkTextContrast, checkHueCount, checkDeadTweaks, primaryVarNames, } from './quality-checks.js';
+export type { QualityIssue } from './quality-checks.js';
+export { deriveSurfaceRamp, withLightness } from './ramp.js';
+export type { SurfaceRamp } from './ramp.js';

package/dist/canvas/index.js

@@ -4,3 +4,13 @@
  */
 export * from './types.js';
 export * from './validate.js';
+/*
+  ⚠️ Renderer-safe on purpose. Both modules are pure arithmetic with no imports beyond
+  each other, so Desktop's renderer can use them for the surface ramp without pulling the
+  SDK main entry (which reaches node:util and breaks a browser bundle). The host and the
+  validator must agree on the ramp's targets, so they share the constants rather than
+  each keeping a copy.
+*/
+export { parseColor, relativeLuminance, contrastRatio, oklabLightness, lightnessDeltaPct, isNeutral, hueAngle, AA_TEXT, SURFACE_DELTA_MIN, SURFACE_DELTA_TARGET, SURFACE_DELTA_MAX, HAIRLINE_MIN_PCT, HAIRLINE_MAX_PCT, } from './color.js';
+export { runQualityChecks, checkSurfaceTokens, checkTextContrast, checkHueCount, checkDeadTweaks, primaryVarNames, } from './quality-checks.js';
+export { deriveSurfaceRamp, withLightness } from './ramp.js';

package/dist/canvas/quality-checks.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The deterministic half of canvas quality.
+ *
+ * ⚠️ WHY THESE ARE CODE AND NOT PROMPT. Each one is arithmetic on values the canvas
+ * declares, and each has already failed to hold as prose. The surface check in
+ * particular is the defect no prompt has ever prevented, because the agent is not doing
+ * anything wrong — it uses the token it was given, and on a terminal-derived palette
+ * `--canvas-card` lands within a few percent of `--canvas-bg`.
+ *
+ * ⚠️ WHAT IS DELIBERATELY MISSING: contrast between two *tokens*. The SDK never sees the
+ * theme palette — `canvas_validate` takes html and type, and nothing in the platform
+ * context carries colours — so `var(--canvas-muted)` on `var(--canvas-surface-2)` cannot
+ * be resolved here. Rather than plumb a palette through on spec, the checks below cover
+ * the two cases that need no palette: token PAIRINGS that are wrong whatever they
+ * resolve to, and literal colours, whose values are right there in the markup.
+ */
+import type { ControlManifest } from './types.js';
+export interface QualityIssue {
+    level: 'error' | 'warn';
+    message: string;
+}
+/**
+ * The custom properties a value actually USES — primaries only, never fallbacks.
+ *
+ * ⚠️ THIS EXISTS BECAUSE A SUBSTRING TEST GETS IT BACKWARDS. The handoff tells authors to
+ * write `var(--canvas-surface-1, var(--canvas-card))` so a canvas degrades on a host
+ * without the ramp, and to KEEP that fallback afterwards. A plain
+ * `/var\(--canvas-card/` test matches the fallback and fires the surface error on the
+ * exact corrected form the error message asks for — a validator that punishes compliance
+ * teaches an agent to ignore it. Caught by the negative test, not by reading the regex.
+ *
+ * So: walk to each `var(`, take the name up to the first comma, then skip the whole
+ * fallback by tracking paren depth.
+ */
+export declare function primaryVarNames(value: string): string[];
+/**
+ * A card that shares its ground's value is a rectangle of text.
+ *
+ * ⚠️ This flags the TOKEN PAIRING, not a measured delta, and that is the whole point:
+ * whether `--canvas-card` is 0.0% or 2.1% from `--canvas-bg` depends on the user's
+ * theme, and it is under 4% on every palette anyone measured. The fix is the same in
+ * all of them — use the ramp — so the check needs no palette to be right.
+ */
+export declare function checkSurfaceTokens(html: string): QualityIssue[];
+/**
+ * Text that cannot be read on the surface it actually sits on.
+ *
+ * Two halves, both palette-free:
+ *   - a literal colour on a literal background, measured exactly;
+ *   - white on `var(--canvas-accent)`, which is a pairing rather than a measurement —
+ *     the accent is a mid-tone in every theme we ship (#FF5722 gives 3.2:1), so the pair
+ *     is wrong whatever it resolves to.
+ */
+export declare function checkTextContrast(html: string): QualityIssue[];
+/**
+ * More hues than reasons.
+ *
+ * ⚠️ Greys never count. They are the ground a composition sits on, and a palette of six
+ * greys is a perfectly good canvas — what makes one look machine-made is four competing
+ * *hues* with nothing to distinguish. Warn, never error: multiple hues are legitimate
+ * when they encode categories a reader must tell apart.
+ */
+export declare function checkHueCount(html: string): QualityIssue[];
+/**
+ * A Tweak the user can drag that changes nothing.
+ *
+ * ⚠️ SKIPPED ENTIRELY WHEN THE CANVAS DEFINES `applyParams`. That is the host bridge's
+ * fourth binding path — a canvas can take the whole params object in JS and do what it
+ * likes with it, in which case no static reference to the param name need exist. Without
+ * this guard the check would report confident errors about a legitimate pattern, which is
+ * worse than not checking at all.
+ */
+export declare function checkDeadTweaks(html: string, manifest?: ControlManifest): QualityIssue[];
+/** Every quality check, in the order their messages should be read. */
+export declare function runQualityChecks(html: string, manifest?: ControlManifest): QualityIssue[];

package/dist/canvas/quality-checks.js

@@ -0,0 +1,217 @@
+import { parseColor, contrastRatio, isNeutral, hueAngle, AA_TEXT } from './color.js';
+/** Every `style="…"` attribute body and every `{…}` CSS rule body, as separate scopes. */
+function declarationScopes(html) {
+    const scopes = [];
+    for (const m of html.matchAll(/style\s*=\s*"([^"]*)"/gi))
+        scopes.push(m[1]);
+    for (const m of html.matchAll(/style\s*=\s*'([^']*)'/gi))
+        scopes.push(m[1]);
+    for (const m of html.matchAll(/\{([^{}]*)\}/g))
+        scopes.push(m[1]);
+    return scopes;
+}
+const declaration = (scope, property) => {
+    const m = property.exec(scope);
+    return m ? m[1].trim() : null;
+};
+const TEXT_COLOR = /(?:^|[;{\s])color\s*:\s*([^;}]+)/i;
+const BACKGROUND = /(?:^|[;{\s])background(?:-color)?\s*:\s*([^;}]+)/i;
+/**
+ * The custom properties a value actually USES — primaries only, never fallbacks.
+ *
+ * ⚠️ THIS EXISTS BECAUSE A SUBSTRING TEST GETS IT BACKWARDS. The handoff tells authors to
+ * write `var(--canvas-surface-1, var(--canvas-card))` so a canvas degrades on a host
+ * without the ramp, and to KEEP that fallback afterwards. A plain
+ * `/var\(--canvas-card/` test matches the fallback and fires the surface error on the
+ * exact corrected form the error message asks for — a validator that punishes compliance
+ * teaches an agent to ignore it. Caught by the negative test, not by reading the regex.
+ *
+ * So: walk to each `var(`, take the name up to the first comma, then skip the whole
+ * fallback by tracking paren depth.
+ */
+export function primaryVarNames(value) {
+    const names = [];
+    for (let i = value.indexOf('var('); i !== -1; i = value.indexOf('var(', i)) {
+        let j = i + 4;
+        while (j < value.length && /\s/.test(value[j]))
+            j++;
+        let name = '';
+        while (j < value.length && /[-\w]/.test(value[j]))
+            name += value[j++];
+        if (name.startsWith('--'))
+            names.push(name);
+        // Skip to the matching close paren — the fallback is deliberately not scanned.
+        let depth = 1;
+        while (j < value.length && depth > 0) {
+            if (value[j] === '(')
+                depth++;
+            else if (value[j] === ')')
+                depth--;
+            j++;
+        }
+        i = j;
+    }
+    return names;
+}
+const usesVar = (value, name) => primaryVarNames(value).some((n) => n.toLowerCase() === name);
+/**
+ * A card that shares its ground's value is a rectangle of text.
+ *
+ * ⚠️ This flags the TOKEN PAIRING, not a measured delta, and that is the whole point:
+ * whether `--canvas-card` is 0.0% or 2.1% from `--canvas-bg` depends on the user's
+ * theme, and it is under 4% on every palette anyone measured. The fix is the same in
+ * all of them — use the ramp — so the check needs no palette to be right.
+ */
+export function checkSurfaceTokens(html) {
+    const usesCardAsSurface = declarationScopes(html).some((scope) => {
+        const bg = declaration(scope, BACKGROUND);
+        return bg !== null && usesVar(bg, '--canvas-card');
+    });
+    if (!usesCardAsSurface)
+        return [];
+    return [
+        {
+            level: 'error',
+            message: 'A card is filled with var(--canvas-card) over a var(--canvas-bg) ground. On a ' +
+                'theme-derived palette those two sit within a few percent of each other, so the ' +
+                'card disappears and only its border holds the layout together. Use the elevation ' +
+                'ramp instead: background: var(--canvas-surface-1, var(--canvas-card)) for a raised ' +
+                'card, var(--canvas-surface-2, var(--canvas-card)) for an inset area (tables, code), ' +
+                'and border-color: var(--canvas-hairline, var(--canvas-border)). Keep the fallbacks ' +
+                'so the canvas still renders on a host that has not shipped the ramp.',
+        },
+    ];
+}
+/** Near-white, for the "white on the accent" trap. */
+function isNearWhite(value) {
+    if (/^\s*white\s*$/i.test(value))
+        return true;
+    const c = parseColor(value);
+    return c !== null && c.r > 0.85 && c.g > 0.85 && c.b > 0.85;
+}
+/**
+ * Text that cannot be read on the surface it actually sits on.
+ *
+ * Two halves, both palette-free:
+ *   - a literal colour on a literal background, measured exactly;
+ *   - white on `var(--canvas-accent)`, which is a pairing rather than a measurement —
+ *     the accent is a mid-tone in every theme we ship (#FF5722 gives 3.2:1), so the pair
+ *     is wrong whatever it resolves to.
+ */
+export function checkTextContrast(html) {
+    const issues = [];
+    let whiteOnAccent = false;
+    const failures = [];
+    for (const scope of declarationScopes(html)) {
+        const fg = declaration(scope, TEXT_COLOR);
+        const bg = declaration(scope, BACKGROUND);
+        if (fg === null || bg === null)
+            continue;
+        if (usesVar(bg, '--canvas-accent') && isNearWhite(fg)) {
+            whiteOnAccent = true;
+            continue;
+        }
+        const fgc = parseColor(fg);
+        const bgc = parseColor(bg);
+        // ⚠️ A null here means a token or a keyword, NOT a failure — skip rather than guess.
+        if (!fgc || !bgc)
+            continue;
+        const ratio = contrastRatio(fgc, bgc);
+        if (ratio < AA_TEXT) {
+            failures.push(`${fg.trim()} on ${bg.trim()} — ${ratio.toFixed(1)}:1`);
+        }
+    }
+    if (whiteOnAccent) {
+        issues.push({
+            level: 'error',
+            message: 'White text on var(--canvas-accent). The accent is a mid-tone in every theme — ' +
+                'on the default it is 3.2:1, below the 4.5:1 floor. Either put a dark ink label on ' +
+                'the accent fill, or drop the fill and use the accent as the text colour on the ' +
+                'page ground.',
+        });
+    }
+    if (failures.length) {
+        issues.push({
+            level: 'error',
+            message: `Text below the 4.5:1 floor against the surface it sits on: ${failures.slice(0, 4).join('; ')}` +
+                (failures.length > 4 ? ` (+${String(failures.length - 4)} more)` : '') +
+                '. Check a muted grey against the INSET surface, not the page — one that passes on ' +
+                'white will fail on surface-2.',
+        });
+    }
+    return issues;
+}
+/** Hues within this many degrees are the same hue wearing two tints. */
+const HUE_BUCKET = 30;
+/**
+ * More hues than reasons.
+ *
+ * ⚠️ Greys never count. They are the ground a composition sits on, and a palette of six
+ * greys is a perfectly good canvas — what makes one look machine-made is four competing
+ * *hues* with nothing to distinguish. Warn, never error: multiple hues are legitimate
+ * when they encode categories a reader must tell apart.
+ */
+export function checkHueCount(html) {
+    const buckets = new Set();
+    for (const m of html.matchAll(/#[0-9a-f]{3,8}\b|\b(?:rgb|hsl)a?\s*\([^)]*\)/gi)) {
+        const c = parseColor(m[0]);
+        if (!c || isNeutral(c))
+            continue;
+        buckets.add(Math.round(hueAngle(c) / HUE_BUCKET));
+    }
+    if (buckets.size <= 2)
+        return [];
+    return [
+        {
+            level: 'warn',
+            message: `${String(buckets.size)} distinct hues are hardcoded in this canvas. Count the hues, then ` +
+                'count the reasons — if there are more hues than things a reader must tell apart, ' +
+                'colour is decoration. One accent marking the finding, and greys for everything else.',
+        },
+    ];
+}
+/**
+ * A Tweak the user can drag that changes nothing.
+ *
+ * ⚠️ SKIPPED ENTIRELY WHEN THE CANVAS DEFINES `applyParams`. That is the host bridge's
+ * fourth binding path — a canvas can take the whole params object in JS and do what it
+ * likes with it, in which case no static reference to the param name need exist. Without
+ * this guard the check would report confident errors about a legitimate pattern, which is
+ * worse than not checking at all.
+ */
+export function checkDeadTweaks(html, manifest) {
+    const controls = manifest?.controls ?? [];
+    if (controls.length === 0)
+        return [];
+    if (/\bapplyParams\s*[=:(]/.test(html))
+        return [];
+    const dead = controls
+        .map((c) => c.param)
+        .filter((param) => {
+        if (!param)
+            return false;
+        const safe = param.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const bound = new RegExp(`var\\(\\s*--${safe}\\b|data-bind\\s*=\\s*["']${safe}["']|data-show\\s*=\\s*["']${safe}["']`, 'i');
+        return !bound.test(html);
+    });
+    if (dead.length === 0)
+        return [];
+    return [
+        {
+            level: 'error',
+            message: `Tweak${dead.length > 1 ? 's' : ''} declared but bound to nothing: ${dead.join(', ')}. ` +
+                'A control the user can drag that changes nothing reads as a broken canvas. Either ' +
+                'reference it — var(--param) in CSS, data-bind="param" for text, data-show="param" ' +
+                'to toggle — or remove it from the manifest.',
+        },
+    ];
+}
+/** Every quality check, in the order their messages should be read. */
+export function runQualityChecks(html, manifest) {
+    return [
+        ...checkSurfaceTokens(html),
+        ...checkTextContrast(html),
+        ...checkHueCount(html),
+        ...checkDeadTweaks(html, manifest),
+    ];
+}

package/dist/canvas/ramp.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The surface ramp the host injects.
+ *
+ * ⚠️ WHY THE HOST AND NOT CSS. A single `color-mix` cannot serve both polarities: a light
+ * theme's ground has no headroom above it (Catppuccin Latte sits at ~95% lightness, so a
+ * card 6% "above" it would be past white), while a dark theme's has plenty. CSS cannot
+ * branch on a palette's polarity. Whatever computes this has to know the luminance, so it
+ * lives here — pure, testable, and shared with the validator so the two cannot disagree
+ * about what "5–7% apart" means.
+ *
+ * ⚠️ THE GROUND MOVES ONLY WHEN IT MUST. The handoff's worked examples darken the ground
+ * in every case; this does it only when there is no room for the raised surface, so a
+ * dark theme's canvas keeps exactly the background its theme specifies and nothing about
+ * an existing canvas shifts. Latte has no room, so it darkens — there is no alternative
+ * that also keeps the card raised, which is the point of the ramp.
+ */
+import { type Rgb } from './color.js';
+export interface SurfaceRamp {
+    /** The page ground. Equal to the input unless there was no room for the ramp. */
+    bg: string;
+    /** Raised — cards. */
+    surface1: string;
+    /** Inset — tables, code, an app screen's work area. */
+    surface2: string;
+    /** 1px borders. */
+    hairline: string;
+}
+/**
+ * The same colour at a different perceived lightness.
+ *
+ * ⚠️ Binary search over a mix toward white or black rather than an OKLab inverse. It
+ * keeps the hue of the ground (a tinted terminal ground stays tinted, which is most of
+ * why these palettes look like themselves) and cannot produce an out-of-gamut value,
+ * which an inverse transform can.
+ */
+export declare function withLightness(color: Rgb, targetL: number): Rgb;
+/**
+ * Derive the three ramp tokens from a theme's ground and foreground.
+ *
+ * Raised is always lighter and inset always darker, in both polarities — a card that
+ * recedes from its page does not read as a card. When the ground cannot support both
+ * steps, the ground itself is moved just far enough to make room, and the returned `bg`
+ * says so.
+ */
+export declare function deriveSurfaceRamp(bgInput: string, fgInput: string): SurfaceRamp | null;