story-theme-mcp 1.0.0

package/src/theme/loader.js

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SCHEMA_RE = /\{%-?\s*schema\s*-?%\}([\s\S]*?)\{%-?\s*endschema\s*-?%\}/;
+const COMMENT_RE = /\{%-?\s*comment\s*-?%\}[\s\S]*?\{%-?\s*endcomment\s*-?%\}/g;
+const DOC_RE = /\{%-?\s*doc\s*-?%\}[\s\S]*?\{%-?\s*enddoc\s*-?%\}/g;
+const STATIC_RE = /content_for\s+['"]block['"]\s*,/g;
+
+// Theme JSON files (templates, locales, settings_data) may open with a /* ... */ notice.
+export function stripJsonComment(text) {
+  return text.replace(/^/, '').replace(/^\s*\/\*[\s\S]*?\*\/\s*/, '');
+}
+
+export function parseThemeJson(text) {
+  return JSON.parse(stripJsonComment(text));
+}
+
+function readJson(file) {
+  return parseThemeJson(fs.readFileSync(file, 'utf8'));
+}
+
+function staticBlocks(liquid) {
+  const code = liquid.replace(SCHEMA_RE, '').replace(COMMENT_RE, '').replace(DOC_RE, '');
+  const found = [];
+  for (const match of code.matchAll(STATIC_RE)) {
+    // Inside {% liquid %} a statement ends with its line, so type and id sit before the next tag end.
+    const rest = code.slice(match.index + match[0].length);
+    const end = rest.search(/-?%\}/);
+    const tag = end === -1 ? rest.slice(0, 400) : rest.slice(0, end);
+    const type = tag.match(/\btype:\s*['"]([^'"]+)['"]/);
+    const id = tag.match(/\bid:\s*['"]([^'"]+)['"]/);
+    if (type && id && !found.some((entry) => entry.type === type[1] && entry.id === id[1])) {
+      found.push({ type: type[1], id: id[1] });
+    }
+  }
+  return found;
+}
+
+function loadSchemaFiles(dir, kind) {
+  const result = new Map();
+  if (!fs.existsSync(dir)) return result;
+  for (const file of fs.readdirSync(dir).sort()) {
+    if (!file.endsWith('.liquid')) continue;
+    const type = file.slice(0, -'.liquid'.length);
+    const source = fs.readFileSync(path.join(dir, file), 'utf8');
+    const match = source.match(SCHEMA_RE);
+    const entry = { type, kind, file: `${kind === 'section' ? 'sections' : 'blocks'}/${file}`, schema: null, statics: staticBlocks(source), error: null };
+    if (match) {
+      try {
+        entry.schema = JSON.parse(match[1]);
+      } catch (error) {
+        entry.error = `schema JSON: ${error.message}`;
+      }
+    }
+    result.set(type, entry);
+  }
+  return result;
+}
+
+function loadTemplates(dir) {
+  const templates = new Map();
+  const walk = (folder, prefix) => {
+    if (!fs.existsSync(folder)) return;
+    for (const file of fs.readdirSync(folder).sort()) {
+      const full = path.join(folder, file);
+      if (fs.statSync(full).isDirectory()) walk(full, `${prefix}${file}/`);
+      else if (file.endsWith('.json')) {
+        try {
+          templates.set(`${prefix}${file}`, readJson(full));
+        } catch (error) {
+          templates.set(`${prefix}${file}`, { __error: error.message });
+        }
+      }
+    }
+  };
+  walk(dir, 'templates/');
+  return templates;
+}
+
+function loadGroups(dir) {
+  const groups = new Map();
+  if (!fs.existsSync(dir)) return groups;
+  for (const file of fs.readdirSync(dir).sort()) {
+    if (!file.endsWith('.json')) continue;
+    try {
+      groups.set(`sections/${file}`, readJson(path.join(dir, file)));
+    } catch (error) {
+      groups.set(`sections/${file}`, { __error: error.message });
+    }
+  }
+  return groups;
+}
+
+export function loadTheme(themeDir) {
+  if (!fs.existsSync(path.join(themeDir, 'config', 'settings_schema.json'))) {
+    throw new Error(`No Shopify theme at ${themeDir} (config/settings_schema.json is missing). Set STORY_THEME_DIR.`);
+  }
+  const settingsSchema = readJson(path.join(themeDir, 'config', 'settings_schema.json'));
+  const info = settingsSchema.find((group) => group.name === 'theme_info') || {};
+  const localesDir = path.join(themeDir, 'locales');
+  const localeFiles = fs.existsSync(localesDir) ? fs.readdirSync(localesDir) : [];
+  const schemaLanguages = localeFiles
+    .filter((file) => file.endsWith('.schema.json'))
+    .map((file) => file.replace('.schema.json', '').replace('.default', ''));
+  const defaultLanguage = (localeFiles.find((file) => /\.default\.schema\.json$/.test(file)) || 'en.default.schema.json').split('.')[0];
+
+  return {
+    dir: themeDir,
+    name: info.theme_name || 'Theme',
+    version: info.theme_version || 'unknown',
+    sections: loadSchemaFiles(path.join(themeDir, 'sections'), 'section'),
+    blocks: loadSchemaFiles(path.join(themeDir, 'blocks'), 'block'),
+    settingsSchema,
+    settingsData: fs.existsSync(path.join(themeDir, 'config', 'settings_data.json'))
+      ? readJson(path.join(themeDir, 'config', 'settings_data.json'))
+      : { current: {} },
+    templates: loadTemplates(path.join(themeDir, 'templates')),
+    groups: loadGroups(path.join(themeDir, 'sections')),
+    schemaLanguages,
+    defaultLanguage,
+    loadSchemaLocale(language) {
+      const file = path.join(localesDir, language === defaultLanguage ? `${language}.default.schema.json` : `${language}.schema.json`);
+      return fs.existsSync(file) ? readJson(file) : null;
+    },
+    loadStorefrontLocale(language) {
+      const file = path.join(localesDir, language === defaultLanguage ? `${language}.default.json` : `${language}.json`);
+      return fs.existsSync(file) ? readJson(file) : null;
+    },
+  };
+}

package/src/theme/source.js

@@ -0,0 +1,242 @@
+// =====================================================================
+// D'où vient le thème que le MCP connaît
+// =====================================================================
+// Trois origines possibles, dans cet ordre :
+//
+//   dashboard  le compte a un jeton (STORY_MCP_TOKEN) : le MCP demande à l'espace membre la
+//              DERNIÈRE VERSION PUBLIÉE, la télécharge une fois, et travaille dessus. C'est le
+//              mode des clients : ils n'ont rien à mettre à jour, le thème suit les sorties.
+//   cache      même chose, mais hors ligne ou l'espace membre injoignable : on repart sur la
+//              dernière version téléchargée. Un avion ne doit pas rendre l'assistant muet.
+//   local      STORY_THEME_DIR pointe sur un dossier de thème : mode développement (le thème en
+//              cours d'écriture), prioritaire sur tout le reste quand il est posé explicitement.
+//
+// Embarquer une copie du thème dans le paquet npm aurait été plus simple, et faux : le MCP
+// aurait connu le thème du jour de sa publication, pas celui que le client vient d'installer.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { unzipSync } from 'fflate';
+
+const AIDE_JETON = `Aucun thème disponible. Deux façons de brancher le MCP :
+  • un jeton : générez-le dans votre espace membre Story Thème (menu « MCP & Appli »), puis ajoutez STORY_MCP_TOKEN à la configuration du MCP ;
+  • un dossier : pointez STORY_THEME_DIR sur un thème Story déjà décompressé.`;
+
+/** Erreur de licence : le jeton est refusé ou l'abonnement n'est plus actif. Jamais un repli. */
+export class LicenceError extends Error {}
+
+const safeVersion = (version) => String(version || 'inconnue').replace(/[^0-9A-Za-z._-]/g, '_');
+
+const rmrf = (dir) => fs.rmSync(dir, { recursive: true, force: true });
+
+/** Un dossier de thème utilisable ? Le fichier que le chargeur exige de toute façon. */
+export const isThemeDir = (dir) => Boolean(dir) && fs.existsSync(path.join(dir, 'config', 'settings_schema.json'));
+
+/**
+ * Écrit l'archive du thème dans `dir`. Le zip du dashboard a ses fichiers à la racine, celui
+ * d'une boutique Shopify peut tout ranger sous un dossier : on repère la racine au fichier qui
+ * est toujours là, puis on ne garde que ce qui est dessous.
+ */
+export function extractTheme(buffer, dir) {
+  const archive = unzipSync(new Uint8Array(buffer));
+  const names = Object.keys(archive);
+  const marker = names.find((name) => name.endsWith('config/settings_schema.json') && !name.includes('__MACOSX'));
+  if (!marker) throw new Error("L'archive reçue n'est pas un thème Shopify (config/settings_schema.json absent).");
+  const root = marker.slice(0, marker.length - 'config/settings_schema.json'.length);
+
+  let written = 0;
+  for (const name of names) {
+    if (!name.startsWith(root) || name.endsWith('/') || name.includes('__MACOSX')) continue;
+    const rel = name.slice(root.length);
+    // Une entrée de zip est une chaîne fournie par un tiers : `a/../../.ssh/id_rsa` écrirait
+    // hors du dossier. On refuse tout ce qui ne reste pas dedans plutôt que de l'assainir.
+    const full = path.resolve(dir, rel);
+    if (rel.startsWith('/') || !full.startsWith(path.resolve(dir) + path.sep)) continue;
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, Buffer.from(archive[name]));
+    written += 1;
+  }
+  if (!written) throw new Error("L'archive reçue est vide.");
+  return written;
+}
+
+export class ThemeSource {
+  /**
+   * @param {object} config — voir src/config.js (apiBase, token, canal, themeDir, homeDir)
+   * @param {{ fetch?: Function, log?: Function }} [deps] — injectés par les tests
+   */
+  constructor(config, deps = {}) {
+    this.config = config;
+    this.fetch = deps.fetch || globalThis.fetch;
+    this.log = deps.log || (() => {});
+    this.cacheRoot = path.join(config.homeDir, 'themes');
+    this.statePath = path.join(this.cacheRoot, 'state.json');
+    this.info = { origin: null, version: null, canal: null, dir: null, checkedAt: 0, message: null };
+  }
+
+  get dir() {
+    return this.info.dir;
+  }
+
+  readState() {
+    try {
+      return JSON.parse(fs.readFileSync(this.statePath, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  writeState(state) {
+    fs.mkdirSync(this.cacheRoot, { recursive: true });
+    fs.writeFileSync(this.statePath, JSON.stringify(state, null, 2));
+  }
+
+  /** Dossier de travail d'une version en cache (existe ou non). */
+  versionDir(version) {
+    return path.join(this.cacheRoot, safeVersion(version));
+  }
+
+  async call(chemin, { timeoutMs = 10000, ...options } = {}) {
+    const url = `${this.config.apiBase.replace(/\/+$/, '')}/api/v1/mcp${chemin}`;
+    const reponse = await this.fetch(url, {
+      ...options,
+      headers: {
+        Authorization: `Bearer ${this.config.token}`,
+        Accept: 'application/json',
+        'User-Agent': `story-theme-mcp/${this.config.version || ''}`,
+        ...(options.headers || {}),
+      },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+
+    if (reponse.status === 401 || reponse.status === 403) {
+      const corps = await reponse.json().catch(() => null);
+      throw new LicenceError(corps?.message || 'Jeton MCP refusé par l’espace membre Story Thème.');
+    }
+    return reponse;
+  }
+
+  /**
+   * Le thème est prêt à être lu : rend `{ dir, origin, version, canal, changed }`.
+   *
+   * Appelé une fois au démarrage (sans bloquer plus que `timeoutMs`), puis à la demande par
+   * l'outil `theme_source`. Une panne réseau ne fait jamais échouer si un cache existe ; un
+   * jeton refusé, si : c'est une licence, pas un incident.
+   */
+  async ensure({ force = false, timeoutMs = 10000 } = {}) {
+    // 1. Dossier local explicite : le mode développement gagne, sans appel réseau.
+    if (this.config.themeDirExplicit) {
+      if (!isThemeDir(this.config.themeDir)) {
+        throw new Error(`STORY_THEME_DIR ne pointe pas sur un thème Shopify : ${this.config.themeDir} (config/settings_schema.json absent)`);
+      }
+      this.info = { origin: 'local', version: null, canal: null, dir: this.config.themeDir, checkedAt: Date.now(), message: null };
+      return { ...this.info, changed: false };
+    }
+
+    if (this.config.token) {
+      try {
+        return await this.sync({ force, timeoutMs });
+      } catch (error) {
+        if (error instanceof LicenceError) throw error;
+        // Réseau, DNS, 500, timeout : on continue sur ce qu'on a déjà. « fetch failed » ne
+        // dit rien à un marchand : on traduit les pannes de liaison en une seule phrase.
+        const panne = /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET|timed out|aborted|network/i.test(error.message)
+          ? 'espace membre injoignable'
+          : error.message;
+        const cache = this.fromCache(panne);
+        if (cache) return cache;
+        throw new Error(`Espace membre Story Thème injoignable (${error.message}) et aucun thème en cache. Réessayez connecté.`);
+      }
+    }
+
+    // 2. Pas de jeton : un cache déjà téléchargé reste exploitable (le jeton a pu être retiré
+    //    de la configuration), sinon le dossier par défaut, sinon on explique quoi faire.
+    const cache = this.fromCache('aucun jeton configuré');
+    if (cache) return cache;
+    if (isThemeDir(this.config.themeDir)) {
+      this.info = { origin: 'local', version: null, canal: null, dir: this.config.themeDir, checkedAt: Date.now(), message: null };
+      return { ...this.info, changed: false };
+    }
+    throw new Error(AIDE_JETON);
+  }
+
+  fromCache(raison) {
+    const state = this.readState();
+    if (!state?.version) return null;
+    const dir = this.versionDir(state.version);
+    if (!isThemeDir(dir)) return null;
+    this.info = {
+      origin: 'cache',
+      version: state.version,
+      canal: state.canal || 'stable',
+      dir,
+      checkedAt: Date.now(),
+      message: `Thème ${state.version} lu depuis le cache local (${raison}).`,
+    };
+    return { ...this.info, changed: false };
+  }
+
+  /** Interroge l'espace membre et télécharge la version publiée si elle a changé. */
+  async sync({ force = false, timeoutMs = 10000 } = {}) {
+    const canal = this.config.canal === 'test' ? 'test' : 'stable';
+    const reponse = await this.call(`/theme?canal=${canal}`, { timeoutMs });
+    if (!reponse.ok) throw new Error(`réponse ${reponse.status} de l’espace membre`);
+    const corps = await reponse.json();
+    const theme = corps?.data?.theme;
+    if (!theme?.version) throw new Error('aucune version publiée annoncée par l’espace membre');
+
+    const dir = this.versionDir(theme.version);
+    const state = this.readState();
+    const dejaLa = isThemeDir(dir) && state?.version === theme.version && state?.canal === theme.canal;
+    if (dejaLa && !force) {
+      this.info = { origin: 'dashboard', version: theme.version, canal: theme.canal, dir, checkedAt: Date.now(), message: null };
+      return { ...this.info, changed: false };
+    }
+
+    await this.download(theme, dir);
+    this.writeState({ version: theme.version, canal: theme.canal, downloadedAt: new Date().toISOString(), api: this.config.apiBase });
+    this.prune(theme.version);
+    this.info = { origin: 'dashboard', version: theme.version, canal: theme.canal, dir, checkedAt: Date.now(), message: null };
+    return { ...this.info, changed: true, publieLe: theme.publieLe || null };
+  }
+
+  async download(theme, dir) {
+    // Une archive de 1,3 Mo : le délai doit couvrir une connexion lente, pas celui d'un appel JSON.
+    const reponse = await this.call(`/theme/archive?canal=${theme.canal}`, { timeoutMs: 120000 });
+    if (!reponse.ok) throw new Error(`téléchargement refusé (${reponse.status})`);
+    const buffer = Buffer.from(await reponse.arrayBuffer());
+
+    // Extraction dans un dossier temporaire : un téléchargement coupé en route ne doit pas
+    // laisser un thème à moitié écrit que le chargeur prendrait pour valide.
+    const temp = `${dir}.partiel`;
+    rmrf(temp);
+    fs.mkdirSync(temp, { recursive: true });
+    try {
+      extractTheme(buffer, temp);
+      if (!isThemeDir(temp)) throw new Error("l'archive reçue ne contient pas config/settings_schema.json");
+      rmrf(dir);
+      fs.renameSync(temp, dir);
+    } finally {
+      rmrf(temp);
+    }
+    this.log(`Thème ${theme.version} téléchargé (${Math.round(buffer.length / 1024)} Ko).`);
+  }
+
+  /** Garde la version courante et la précédente : de quoi comparer, sans accumuler. */
+  prune(garder) {
+    if (!fs.existsSync(this.cacheRoot)) return;
+    const versions = fs
+      .readdirSync(this.cacheRoot)
+      .filter((name) => name !== 'state.json' && name !== safeVersion(garder) && isThemeDir(path.join(this.cacheRoot, name)))
+      .map((name) => ({ name, at: fs.statSync(path.join(this.cacheRoot, name)).mtimeMs }))
+      .sort((a, b) => b.at - a.at);
+    for (const vieille of versions.slice(1)) rmrf(path.join(this.cacheRoot, vieille.name));
+  }
+}
+
+/** Source figée sur un dossier : utilisée par les tests et les scripts (npm run check). */
+export const localSource = (dir) => ({
+  info: { origin: 'local', version: null, canal: null, dir, checkedAt: Date.now(), message: null },
+  dir,
+  ensure: async () => ({ origin: 'local', version: null, canal: null, dir, changed: false }),
+});

package/src/validate/color.js

@@ -0,0 +1,176 @@
+// Colour math: WCAG contrast, OKLCH for building harmonious palettes.
+
+export function parseColor(value) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  let match = text.match(/^#([0-9a-f]{3,8})$/i);
+  if (match) {
+    let hex = match[1];
+    if (hex.length === 3 || hex.length === 4) hex = [...hex].map((char) => char + char).join('');
+    if (hex.length !== 6 && hex.length !== 8) return null;
+    return { r: parseInt(hex.slice(0, 2), 16), g: parseInt(hex.slice(2, 4), 16), b: parseInt(hex.slice(4, 6), 16), a: hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1 };
+  }
+  match = text.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/i);
+  if (match) return { r: +match[1], g: +match[2], b: +match[3], a: match[4] === undefined ? 1 : +match[4] };
+  return null;
+}
+
+const clamp255 = (value) => Math.max(0, Math.min(255, Math.round(value)));
+
+export function toHex({ r, g, b }) {
+  return '#' + [r, g, b].map((channel) => clamp255(channel).toString(16).padStart(2, '0')).join('').toUpperCase();
+}
+
+function channel(value) {
+  const c = value / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+export function luminance(color) {
+  const c = typeof color === 'string' ? parseColor(color) : color;
+  return 0.2126 * channel(c.r) + 0.7152 * channel(c.g) + 0.0722 * channel(c.b);
+}
+
+export function blend(foreground, background, alpha) {
+  const f = typeof foreground === 'string' ? parseColor(foreground) : foreground;
+  const b = typeof background === 'string' ? parseColor(background) : background;
+  return { r: f.r * alpha + b.r * (1 - alpha), g: f.g * alpha + b.g * (1 - alpha), b: f.b * alpha + b.b * (1 - alpha), a: 1 };
+}
+
+// Translucent colours are measured blended over what is behind them (white behind the background).
+export function contrast(a, b) {
+  let back = typeof b === 'string' ? parseColor(b) : b;
+  if (back.a !== undefined && back.a < 1) back = blend(back, { r: 255, g: 255, b: 255 }, back.a);
+  let front = typeof a === 'string' ? parseColor(a) : a;
+  if (front.a !== undefined && front.a < 1) front = blend(front, back, front.a);
+  const la = luminance(front);
+  const lb = luminance(back);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+export const round2 = (value) => Math.round(value * 100) / 100;
+
+// ---- OKLCH (Björn Ottosson)
+
+const toLinear = (value) => channel(value);
+const fromLinear = (value) => 255 * (value <= 0.0031308 ? 12.92 * value : 1.055 * value ** (1 / 2.4) - 0.055);
+
+export function toOklch(color) {
+  const c = typeof color === 'string' ? parseColor(color) : color;
+  const r = toLinear(c.r);
+  const g = toLinear(c.g);
+  const b = toLinear(c.b);
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  const C = Math.sqrt(A * A + B * B);
+  let H = (Math.atan2(B, A) * 180) / Math.PI;
+  if (H < 0) H += 360;
+  return { l: L, c: C, h: H };
+}
+
+function oklchToLinear({ l: L, c: C, h: H }) {
+  const A = C * Math.cos((H * Math.PI) / 180);
+  const B = C * Math.sin((H * Math.PI) / 180);
+  const l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3;
+  const m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3;
+  const s = (L - 0.0894841775 * A - 1.291485548 * B) ** 3;
+  return [4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s, -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s, -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s];
+}
+
+// Converts to sRGB, lowering chroma until the colour fits the gamut.
+export function fromOklch(color) {
+  let { l, c, h } = color;
+  l = Math.max(0, Math.min(1, l));
+  for (let i = 0; i < 40; i++) {
+    const rgb = oklchToLinear({ l, c, h });
+    if (rgb.every((value) => value >= -0.0005 && value <= 1.0005)) {
+      return { r: fromLinear(Math.max(0, rgb[0])), g: fromLinear(Math.max(0, rgb[1])), b: fromLinear(Math.max(0, rgb[2])), a: 1 };
+    }
+    c *= 0.9;
+  }
+  const rgb = oklchToLinear({ l, c: 0, h });
+  return { r: fromLinear(Math.max(0, Math.min(1, rgb[0]))), g: fromLinear(Math.max(0, Math.min(1, rgb[1]))), b: fromLinear(Math.max(0, Math.min(1, rgb[2]))), a: 1 };
+}
+
+export const oklchHex = (l, c, h) => toHex(fromOklch({ l, c, h }));
+
+// Moves a colour's lightness (keeping hue and as much chroma as fits) until it reaches `target`
+// contrast against `against`. Returns the original when it already passes.
+export function ensureContrast(hex, against, target, direction = null) {
+  if (contrast(hex, against) >= target) return { hex: toHex(parseColor(hex)), changed: false };
+  const base = toOklch(hex);
+  const dir = direction || (luminance(against) > 0.18 ? -1 : 1);
+  for (let step = 1; step <= 100; step++) {
+    const candidate = toHex(fromOklch({ ...base, l: base.l + dir * step * 0.01 }));
+    if (contrast(candidate, against) >= target) return { hex: candidate, changed: true };
+  }
+  return { hex: dir < 0 ? '#000000' : '#FFFFFF', changed: true };
+}
+
+// Which colours a theme button uses, from its palette choice (snippets/css-variables.liquid).
+export function buttonColors(palette, scheme) {
+  switch (palette) {
+    case 'accent-1':
+      return { background: scheme['accent-1'], label: scheme.background };
+    case 'accent-2':
+      return { background: scheme['accent-2'], label: scheme.background };
+    case 'text':
+      return { background: scheme.text, label: scheme.background };
+    case 'bg_fade':
+      return { background: scheme.background_secondary, label: scheme.text };
+    case 'accent-1-outline':
+      return { background: scheme.background, label: scheme['accent-1'], outline: true };
+    case 'accent-2-outline':
+      return { background: scheme.background, label: scheme['accent-2'], outline: true };
+    case 'text-outline':
+      return { background: scheme.background, label: scheme.text, outline: true };
+    default:
+      return null;
+  }
+}
+
+function grade(ratio, pass, floor) {
+  if (ratio >= pass) return 'ok';
+  if (ratio >= floor) return 'warning';
+  return 'error';
+}
+
+// Audits one colour scheme the way the theme paints it: headings use `text`, body copy
+// `text_secondary`, muted copy `text_secondary` at 75 %, buttons follow the button palettes.
+export function auditScheme(id, settings, buttonPalettes = {}) {
+  const findings = [];
+  const bg = parseColor(settings.background || '');
+  if (!bg) return [{ scheme: id, check: 'fond', level: 'error', message: 'couleur de fond manquante ou invalide' }];
+  const push = (check, fg, background, pass, floor, extra = '') => {
+    const fc = parseColor(fg || '');
+    if (!fc) return;
+    const ratio = contrast(fc, background);
+    const level = grade(ratio, pass, floor);
+    findings.push({ scheme: id, check, ratio: round2(ratio), level, message: `${check} : ${round2(ratio)}:1${level === 'ok' ? '' : ` (${pass}:1 attendu)`}${extra}` });
+  };
+  const gradientNote = settings.background_gradient ? ' — fond en dégradé : mesuré sur la couleur de fond unie' : '';
+  push('titres sur fond', settings.text, bg, 4.5, 3, gradientNote);
+  push('texte sur fond', settings.text_secondary, bg, 4.5, 3, gradientNote);
+  const secondary = parseColor(settings.text_secondary || '');
+  if (secondary) {
+    const muted = blend(secondary, bg, 0.75);
+    const ratio = contrast(muted, bg);
+    findings.push({ scheme: id, check: 'texte discret (75 %)', ratio: round2(ratio), level: ratio >= 4.5 ? 'ok' : 'warning', message: `texte discret (75 %) : ${round2(ratio)}:1${ratio >= 4.5 ? '' : ' (4.5:1 conseillé pour les petits textes)'}` });
+  }
+  for (const [style, palette] of Object.entries(buttonPalettes)) {
+    const colors = buttonColors(palette, settings);
+    if (!colors) continue;
+    const background = parseColor(colors.background || '');
+    if (!background) continue;
+    push(`bouton ${style} (${palette})`, colors.label, background, 4.5, 3);
+  }
+  return findings;
+}
+
+export function auditSchemes(schemes, buttonPalettes) {
+  return Object.entries(schemes || {}).flatMap(([id, scheme]) => auditScheme(id, scheme?.settings || {}, buttonPalettes));
+}