story-theme-mcp 1.0.0

package/src/build/edit.js

@@ -0,0 +1,228 @@
+import { sectionFromPreset, blockFromPreset, collectIds, createIdFactory } from './scaffold.js';
+import { plainText } from '../validate/richtext.js';
+import { isSafeId } from '../validate/template.js';
+
+const clone = (value) => JSON.parse(JSON.stringify(value));
+
+// "hero/group_ab12/button_x" -> { section: 'hero', blocks: ['group_ab12', 'button_x'] }
+export function parseTarget(target) {
+  const parts = String(target || '').split('/').map((part) => part.trim()).filter(Boolean);
+  if (!parts.length) throw new Error('cible vide : indiquez « idSection » ou « idSection/idBloc/… »');
+  const bad = parts.find((part) => !isSafeId(part));
+  if (bad) throw new Error(`identifiant « ${bad} » invalide`);
+  return { section: parts[0], blocks: parts.slice(1) };
+}
+
+function resolveNode(data, target) {
+  const { section, blocks } = parseTarget(target);
+  const node = Object.hasOwn(data.sections || {}, section) ? data.sections[section] : null;
+  if (!node) throw new Error(`section « ${section} » introuvable (sections : ${Object.keys(data.sections || {}).join(', ') || 'aucune'})`);
+  let current = node;
+  let parent = null;
+  let id = section;
+  for (const blockId of blocks) {
+    const next = current.blocks && Object.hasOwn(current.blocks, blockId) ? current.blocks[blockId] : null;
+    if (!next) throw new Error(`bloc « ${blockId} » introuvable dans « ${id} » (blocs : ${Object.keys(current.blocks || {}).join(', ') || 'aucun'})`);
+    parent = current;
+    current = next;
+    id = blockId;
+  }
+  return { node: current, parent, id, isSection: blocks.length === 0, sectionId: section };
+}
+
+function insertAt(list, id, position) {
+  const without = list.filter((item) => item !== id);
+  let index = without.length;
+  if (position === 'start' || position === 0) index = 0;
+  else if (typeof position === 'number') index = Math.max(0, Math.min(without.length, position));
+  else if (position && typeof position === 'object') {
+    const anchor = position.before ?? position.after;
+    const at = without.indexOf(anchor);
+    if (at === -1) throw new Error(`position : « ${anchor} » introuvable (ordre actuel : ${without.join(', ')})`);
+    index = position.before !== undefined ? at : at + 1;
+  }
+  without.splice(index, 0, id);
+  return without;
+}
+
+function applySettings(node, settings, mode) {
+  if (!settings || typeof settings !== 'object') throw new Error('"settings" doit être un objet');
+  if (mode === 'replace') node.settings = {};
+  node.settings = node.settings || {};
+  for (const [key, value] of Object.entries(settings)) {
+    if (value === null) delete node.settings[key];
+    else node.settings[key] = value;
+  }
+}
+
+function refreshIds(catalog, section, nextId) {
+  const walk = (node) => {
+    if (!node.blocks) return;
+    const blocks = {};
+    const mapping = {};
+    for (const [id, block] of Object.entries(node.blocks)) {
+      const newId = block.static ? id : nextId(block.type);
+      mapping[id] = newId;
+      walk(block);
+      blocks[newId] = block;
+    }
+    node.blocks = blocks;
+    if (node.block_order) node.block_order = node.block_order.map((id) => mapping[id] || id);
+  };
+  walk(section);
+  return section;
+}
+
+// Applies edit operations to a template or section group. Throws on the first invalid operation;
+// the caller validates the result before saving anything.
+export function applyOperations(catalog, input, operations, { language = 'fr' } = {}) {
+  const data = clone(input || { sections: {}, order: [] });
+  data.sections = data.sections || {};
+  data.order = data.order || [];
+  const taken = collectIds(data);
+  const nextId = createIdFactory(taken);
+  const log = [];
+
+  operations.forEach((operation, index) => {
+    const where = `opération ${index + 1} (${operation?.op})`;
+    try {
+      switch (operation?.op) {
+        case 'add_section': {
+          const { id, section, preset } = sectionFromPreset(catalog, operation.type, { preset: operation.preset, language, taken, id: operation.id });
+          if (operation.settings) applySettings(section, operation.settings, 'merge');
+          if (operation.disabled) section.disabled = true;
+          data.sections[id] = section;
+          data.order = insertAt(data.order, id, operation.position ?? 'end');
+          log.push(`section ajoutée : ${id} (${operation.type}${preset ? `, preset « ${preset} »` : ''})`);
+          break;
+        }
+        case 'remove_section': {
+          const { section } = parseTarget(operation.section);
+          if (!Object.hasOwn(data.sections, section)) throw new Error(`section « ${section} » introuvable`);
+          delete data.sections[section];
+          data.order = data.order.filter((id) => id !== section);
+          log.push(`section supprimée : ${section}`);
+          break;
+        }
+        case 'move_section': {
+          const { section } = parseTarget(operation.section);
+          if (!Object.hasOwn(data.sections, section)) throw new Error(`section « ${section} » introuvable`);
+          data.order = insertAt(data.order, section, operation.position);
+          log.push(`section déplacée : ${section}`);
+          break;
+        }
+        case 'duplicate_section': {
+          const { section } = parseTarget(operation.section);
+          if (!Object.hasOwn(data.sections, section)) throw new Error(`section « ${section} » introuvable`);
+          const copy = refreshIds(catalog, clone(data.sections[section]), nextId);
+          const id = nextId(copy.type);
+          data.sections[id] = copy;
+          data.order = insertAt(data.order, id, operation.position ?? { after: section });
+          log.push(`section dupliquée : ${section} → ${id}`);
+          break;
+        }
+        case 'replace_section': {
+          const { section } = parseTarget(operation.section);
+          if (!Object.hasOwn(data.sections, section)) throw new Error(`section « ${section} » introuvable`);
+          if (!operation.data?.type) throw new Error('"data" doit être une section complète { type, settings, blocks, block_order }');
+          const replacement = clone(operation.data);
+          for (const id of collectIds({ sections: { [section]: replacement } })) {
+            if (id !== section && taken.has(id)) throw new Error(`le bloc « ${id} » existe déjà ailleurs dans le fichier : donnez-lui un autre identifiant`);
+            taken.add(id);
+          }
+          data.sections[section] = replacement;
+          log.push(`section remplacée : ${section}`);
+          break;
+        }
+        case 'update_settings': {
+          const { node, id } = resolveNode(data, operation.target);
+          applySettings(node, operation.settings, operation.mode);
+          log.push(`réglages modifiés : ${id} (${Object.keys(operation.settings).join(', ')})`);
+          break;
+        }
+        case 'add_block': {
+          const { node, id: parentId } = resolveNode(data, operation.parent);
+          const { id, block } = blockFromPreset(catalog, operation.type, { preset: operation.preset, language, taken, id: operation.id, settings: operation.settings });
+          node.blocks = node.blocks || {};
+          node.blocks[id] = block;
+          node.block_order = insertAt(node.block_order || [], id, operation.position ?? 'end');
+          log.push(`bloc ajouté : ${id} (${operation.type}) dans ${parentId}`);
+          break;
+        }
+        case 'remove_block': {
+          const { parent, id, isSection, node } = resolveNode(data, operation.target);
+          if (isSection) throw new Error('la cible est une section : utilisez remove_section');
+          if (node.static) throw new Error(`« ${id} » est un bloc statique du thème : il ne se supprime pas (masquez-le avec set_disabled ou ses réglages)`);
+          delete parent.blocks[id];
+          parent.block_order = (parent.block_order || []).filter((item) => item !== id);
+          log.push(`bloc supprimé : ${id}`);
+          break;
+        }
+        case 'move_block': {
+          const { parent, id, isSection, node } = resolveNode(data, operation.target);
+          if (isSection) throw new Error('la cible est une section : utilisez move_section');
+          if (node.static) throw new Error(`« ${id} » est statique : sa place est fixée par le thème`);
+          parent.block_order = insertAt(parent.block_order || [], id, operation.position);
+          log.push(`bloc déplacé : ${id}`);
+          break;
+        }
+        case 'set_disabled': {
+          const { node, id } = resolveNode(data, operation.target);
+          if (operation.disabled) node.disabled = true;
+          else delete node.disabled;
+          log.push(`${operation.disabled ? 'masqué' : 'réactivé'} : ${id}`);
+          break;
+        }
+        default:
+          throw new Error('opération inconnue (add_section, remove_section, move_section, duplicate_section, replace_section, update_settings, add_block, remove_block, move_block, set_disabled)');
+      }
+    } catch (error) {
+      throw new Error(`${where} : ${error.message}`);
+    }
+  });
+  return { data, log };
+}
+
+const TEXT_KEYS = ['title', 'heading', 'button_text', 'text', 'description', 'content', 'label', 'subheading', 'text_items', 'items_rich', 'caption', 'question', 'name', 'quote'];
+
+function summary(block) {
+  const settings = block.settings || {};
+  for (const key of TEXT_KEYS) {
+    const value = settings[key];
+    if (typeof value === 'string' && plainText(value)) {
+      const text = plainText(value);
+      return `« ${text.length > 70 ? text.slice(0, 67) + '…' : text} »`;
+    }
+  }
+  return '';
+}
+
+// A compact tree of a template, readable by the model and the merchant.
+export function outline(catalog, data, { language = 'fr', file = '' } = {}) {
+  const lines = [];
+  const order = data?.order || [];
+  lines.push(`${file || 'modèle'} — ${order.length} section(s)`);
+  const walk = (node, depth) => {
+    const ids = [...Object.entries(node.blocks || {}).filter(([, block]) => block.static).map(([id]) => id), ...(node.block_order || [])];
+    for (const id of ids) {
+      const block = node.blocks?.[id];
+      if (!block) continue;
+      const name = catalog.block(block.type) ? catalog.t(catalog.block(block.type).schema?.name, language) : block.type;
+      const flags = [block.static ? 'statique' : null, block.disabled ? 'masqué' : null].filter(Boolean).join(', ');
+      const link = block.settings?.button_link ? ` → ${block.settings.button_link}` : '';
+      lines.push(`${'  '.repeat(depth)}- ${id} · ${block.type} (${name})${flags ? ` [${flags}]` : ''} ${summary(block)}${link}`.trimEnd());
+      walk(block, depth + 1);
+    }
+  };
+  order.forEach((id, index) => {
+    const section = data.sections?.[id];
+    if (!section) return;
+    const entry = catalog.section(section.type);
+    const name = entry?.schema ? catalog.t(entry.schema.name, language) : section.type;
+    const palette = section.settings?.frame_palette || section.settings?.color_palette || section.settings?.color_scheme;
+    const flags = [palette ? `palette ${palette}` : null, section.disabled ? 'masquée' : null].filter(Boolean).join(', ');
+    lines.push(`${index + 1}. ${id} · ${section.type} (${name})${flags ? ` [${flags}]` : ''}`);
+    walk(section, 1);
+  });
+  return lines.join('\n');
+}

package/src/build/localize.js

@@ -0,0 +1,70 @@
+import { plainText } from '../validate/richtext.js';
+
+const TEXT_TYPES = new Set(['text', 'textarea', 'richtext', 'inline_richtext']);
+const clone = (value) => JSON.parse(JSON.stringify(value));
+
+const OUTER_TAG = /^<(p|h[1-6])>([\s\S]*)<\/\1>$/;
+
+const unwrap = (value) => {
+  const match = value.match(OUTER_TAG);
+  return match ? { tag: match[1], inner: match[2] } : { tag: null, inner: value };
+};
+
+// Correspondance de dernier recours : la même phrase, habillée autrement. Le thème range par
+// exemple « Made in small batches. » dans un `<h2>` côté traductions et dans un `<p>` côté
+// modèle ; sans cette passe, 36 textes de l'accueil restaient en anglais alors que leur
+// traduction existait. Réservée aux phrases (au moins 4 caractères et une lettre) : sur « 10 »
+// ou « % », deux réglages sans rapport se ressembleraient.
+const PHRASE = /[a-zà-ÿ]/i;
+function plainPairsOf(pairs) {
+  const map = new Map();
+  for (const [source, cible] of pairs) {
+    const key = plainText(source).trim();
+    if (key.length >= 4 && PHRASE.test(key) && !map.has(key)) map.set(key, cible);
+  }
+  return map;
+}
+
+function translate(pairs, plainPairs, value) {
+  if (pairs.has(value)) return pairs.get(value);
+  // "<p>Text</p>" or "<h1>Text</h1>" around a string the locales hold bare, or as "<p>…</p>".
+  const { tag, inner } = unwrap(value);
+  if (tag) {
+    if (pairs.has(inner)) return `<${tag}>${pairs.get(inner)}</${tag}>`;
+    if (pairs.has(`<p>${inner}</p>`)) {
+      const translated = pairs.get(`<p>${inner}</p>`);
+      return tag === 'p' ? translated : `<${tag}>${translated.replace(/^<p>|<\/p>$/g, '')}</${tag}>`;
+    }
+  }
+  const found = plainPairs.get(plainText(value).trim());
+  if (found === undefined) return null;
+  // Le réglage impose la forme : un titre en `<p>` reste en `<p>`, un réglage `text` ne reçoit
+  // jamais de balise, même si la traduction en porte une.
+  return tag ? `<${tag}>${unwrap(found).inner}</${tag}>` : plainText(found).trim();
+}
+
+// Replaces the theme's English sample texts by the same texts in `language`, taken from the
+// theme's own translations. Returns what could not be translated, for the model to write.
+export function localizeData(catalog, input, language) {
+  const data = clone(input);
+  const pairs = catalog.translationPairs(language);
+  const plainPairs = plainPairsOf(pairs);
+  let translated = 0;
+  const remaining = [];
+  const visit = (kind, node, target) => {
+    const schema = (kind === 'section' ? catalog.section(node.type) : catalog.block(node.type))?.schema;
+    for (const setting of schema?.settings || []) {
+      if (!setting.id || !TEXT_TYPES.has(setting.type)) continue;
+      const value = node.settings?.[setting.id];
+      if (typeof value !== 'string' || !plainText(value)) continue;
+      const result = translate(pairs, plainPairs, value);
+      if (result !== null && result !== value) {
+        node.settings[setting.id] = result;
+        translated += 1;
+      } else if (result === null) remaining.push({ target, key: setting.id, type: setting.type, value });
+    }
+    for (const [id, block] of Object.entries(node.blocks || {})) visit('block', block, `${target}/${id}`);
+  };
+  for (const [id, section] of Object.entries(data.sections || {})) visit('section', section, id);
+  return { data, translated, remaining };
+}

package/src/build/migrate.js

@@ -0,0 +1,63 @@
+import { checkValue } from '../validate/values.js';
+import { NON_VALUE_TYPES } from '../theme/catalog.js';
+
+const clone = (value) => JSON.parse(JSON.stringify(value));
+
+// Brings a project file up to the theme it is exported with, without changing what renders:
+// settings the theme no longer has do nothing and are dropped; a value the theme no longer
+// accepts falls back to the default (or the nearest valid step for a range). Unknown section
+// and block types are left for the validator: removing them would lose content.
+export function migrateData(catalog, input, { schemeIds = [] } = {}) {
+  const data = clone(input);
+  const changes = [];
+
+  const fixSettings = (node, settingsList, path) => {
+    if (!node.settings || typeof node.settings !== 'object') return;
+    const index = new Map((settingsList || []).filter((setting) => setting.id && !NON_VALUE_TYPES.has(setting.type)).map((setting) => [setting.id, setting]));
+    for (const [key, value] of Object.entries(node.settings)) {
+      const setting = index.get(key);
+      if (!setting) {
+        delete node.settings[key];
+        changes.push(`${path}.${key} : réglage retiré du thème, supprimé`);
+        continue;
+      }
+      if (!checkValue(setting, value, { schemeIds }).some((problem) => problem.level === 'error')) continue;
+      if (setting.type === 'range' && typeof value === 'number') {
+        const step = setting.step ?? 1;
+        const clamped = Math.min(setting.max, Math.max(setting.min, setting.min + Math.round((value - setting.min) / step) * step));
+        node.settings[key] = Math.round(clamped * 1000) / 1000;
+        changes.push(`${path}.${key} : ${value} ramené à ${node.settings[key]}`);
+      } else if (setting.type === 'checkbox' && (value === 'true' || value === 'false')) {
+        node.settings[key] = value === 'true';
+        changes.push(`${path}.${key} : « ${value} » converti en booléen`);
+      } else if (['select', 'radio', 'color_scheme', 'text_alignment'].includes(setting.type)) {
+        delete node.settings[key];
+        changes.push(`${path}.${key} : « ${value} » n'existe plus, valeur par défaut du thème`);
+      }
+    }
+  };
+
+  const walk = (node, schema, path) => {
+    fixSettings(node, schema?.settings, path);
+    for (const [id, block] of Object.entries(node.blocks || {})) {
+      if (!block || typeof block !== 'object') continue;
+      const resolved = catalog.resolveChild(schema, block.type);
+      const childSchema = resolved.ok ? resolved.schema : catalog.block(block.type)?.schema;
+      if (resolved.app || !childSchema) continue;
+      walk(block, childSchema, `${path}/${id}`);
+    }
+  };
+
+  for (const [id, section] of Object.entries(data.sections || {})) {
+    const schema = catalog.section(section?.type)?.schema;
+    if (schema) walk(section, schema, id);
+  }
+  const current = typeof data.current === 'object' ? data.current : null;
+  if (current) {
+    for (const [id, section] of Object.entries(current.sections || {})) {
+      const schema = catalog.section(section?.type)?.schema;
+      if (schema) walk(section, schema, `current.sections.${id}`);
+    }
+  }
+  return { data, changes };
+}

package/src/build/palette.js

@@ -0,0 +1,153 @@
+import { parseColor, toHex, toOklch, oklchHex, ensureContrast, contrast, blend, round2, auditSchemes } from '../validate/color.js';
+
+const NEUTRALS = {
+  // hue, chroma of the neutrals (backgrounds, text)
+  tinted: null,
+  warm: { h: 75, c: 0.014 },
+  cool: { h: 250, c: 0.012 },
+  pure: { h: 0, c: 0 },
+};
+
+export const BUTTON_PALETTES = { button_1_palette: 'accent-1', button_2_palette: 'text-outline', button_3_palette: 'bg_fade' };
+
+// Builds the four colour schemes the theme's templates reference (background-1, background-2,
+// inverse, scheme), plus the global palette, from one or two brand colours. Every text and button
+// pair is pushed to WCAG AA; each adjustment of a brand colour is reported.
+export function generateColorSchemes({ primary, secondary = null, background = null, neutral = 'tinted', mood = 'light' }) {
+  const brand = parseColor(primary);
+  if (!brand) throw new Error(`couleur principale « ${primary} » invalide : utilisez #RRGGBB`);
+  const second = secondary ? parseColor(secondary) : null;
+  if (secondary && !second) throw new Error(`couleur secondaire « ${secondary} » invalide`);
+  const P = toOklch(brand);
+  const tone = NEUTRALS[neutral] || { h: P.h, c: Math.min(0.012, P.c * 0.15) };
+  const adjustments = [];
+  const note = (what, from, to) => {
+    if (from.toUpperCase() !== to.toUpperCase()) adjustments.push(`${what} : ${from.toUpperCase()} → ${to} pour atteindre le contraste AA`);
+  };
+
+  // Light base
+  let base = background ? toHex(parseColor(background)) : oklchHex(neutral === 'warm' ? 0.975 : 0.993, neutral === 'warm' ? 0.012 : tone.c * 0.4, tone.h);
+  if (background && contrast(base, '#000000') < 10) {
+    adjustments.push('fond clair demandé trop sombre pour du texte lisible : fond éclairci');
+    base = oklchHex(0.97, toOklch(base).c, toOklch(base).h);
+  }
+  const heading = ensureContrast(oklchHex(0.2, tone.c * 1.6, tone.h), base, 12).hex;
+  const body = ensureContrastBlended(oklchHex(0.33, tone.c * 1.4, tone.h), base, 4.5, 0.75);
+  const surface = oklchHex(toOklch(base).l - 0.035, Math.max(tone.c, 0.004), tone.h);
+
+  const accent1 = ensureContrast(toHex(brand), base, 4.5);
+  note('couleur principale sur fond clair', primary, accent1.hex);
+  const accent2Source = second ? toHex(second) : oklchHex(Math.max(0.2, toOklch(accent1.hex).l - 0.12), P.c, P.h);
+  const accent2 = ensureContrast(accent2Source, base, 4.5);
+  if (second) note('couleur secondaire sur fond clair', secondary, accent2.hex);
+
+  const light = { text: heading, text_secondary: body, background_gradient_text: '', background: base, background_secondary: surface, background_gradient: '', 'accent-1': accent1.hex, 'accent-2': accent2.hex, background_gradient_accent: '' };
+
+  // Soft brand tint
+  const softBg = oklchHex(0.955, Math.min(P.c * 0.22, 0.03), P.h);
+  const soft = {
+    ...light,
+    background: softBg,
+    background_secondary: base,
+    text: ensureContrast(heading, softBg, 12).hex,
+    text_secondary: ensureContrastBlended(body, softBg, 4.5, 0.75),
+    'accent-1': ensureContrast(accent1.hex, softBg, 4.5).hex,
+    'accent-2': ensureContrast(accent2.hex, softBg, 4.5).hex,
+  };
+
+  // Dark
+  const darkBg = oklchHex(0.22, Math.min(P.c * 0.35, 0.045), P.h);
+  const darkText = oklchHex(0.97, tone.c * 0.5, tone.h);
+  const darkAccent = ensureContrast(toHex(brand), darkBg, 4.5, 1);
+  note('couleur principale sur fond sombre', primary, darkAccent.hex);
+  const dark = {
+    text: darkText,
+    text_secondary: ensureContrastBlended(oklchHex(0.9, tone.c * 0.6, tone.h), darkBg, 4.5, 0.75),
+    background_gradient_text: '',
+    background: darkBg,
+    background_secondary: oklchHex(0.28, Math.min(P.c * 0.35, 0.045), P.h),
+    background_gradient: '',
+    'accent-1': darkAccent.hex,
+    'accent-2': darkText,
+    background_gradient_accent: '',
+  };
+
+  // Brand block: the brand colour as background, nudged until its text reads at AA.
+  let brandHex = toHex(brand);
+  const onBrand = contrast('#FFFFFF', brandHex) >= contrast(heading, brandHex) ? '#FFFFFF' : heading;
+  if (contrast(onBrand, brandHex) < 4.5) {
+    const nudged = ensureContrast(brandHex, onBrand, 4.5, onBrand === '#FFFFFF' ? -1 : 1).hex;
+    if (Math.abs(toOklch(nudged).l - P.l) <= 0.08) {
+      note('couleur de marque en fond (palette scheme)', brandHex, nudged);
+      brandHex = nudged;
+    }
+  }
+  const brandBlock = {
+    text: onBrand,
+    text_secondary: onBrand,
+    background_gradient_text: '',
+    background: brandHex,
+    background_secondary: oklchHex(P.l + (onBrand === '#FFFFFF' ? -0.06 : 0.06), P.c, P.h),
+    background_gradient: '',
+    'accent-1': onBrand,
+    'accent-2': onBrand === '#FFFFFF' ? base : heading,
+    background_gradient_accent: '',
+  };
+  const brandContrast = contrast(onBrand, brandHex);
+  if (brandContrast < 4.5) {
+    adjustments.push(`palette « scheme » : le texte sur la couleur de marque n'atteint que ${round2(brandContrast)}:1 ; réservez-la aux grands titres ou utilisez une teinte plus foncée`);
+  }
+
+  // Dark-first store: the dark scheme is the default, a softer dark rhythms the page, the light
+  // scheme becomes the contrast section.
+  const darkSoftBg = oklchHex(0.28, Math.min(P.c * 0.4, 0.05), P.h);
+  const darkSoft = {
+    ...dark,
+    background: darkSoftBg,
+    background_secondary: darkBg,
+    text_secondary: ensureContrastBlended(dark.text_secondary, darkSoftBg, 4.5, 0.75),
+    'accent-1': ensureContrast(darkAccent.hex, darkSoftBg, 4.5, 1).hex,
+  };
+  const schemes = mood === 'dark'
+    ? { 'background-1': { settings: dark }, 'background-2': { settings: darkSoft }, inverse: { settings: light }, scheme: { settings: brandBlock } }
+    : { 'background-1': { settings: light }, 'background-2': { settings: soft }, inverse: { settings: dark }, scheme: { settings: brandBlock } };
+  const main = schemes['background-1'].settings;
+  const palette = {
+    background: main.background,
+    surface: main.background_secondary,
+    text: main.text,
+    text_muted: ensureContrast(oklchHex(mood === 'dark' ? 0.75 : 0.5, tone.c, tone.h), main.background, 4.5).hex,
+    accent_1: main['accent-1'],
+    accent_2: main['accent-2'],
+    border: oklchHex(toOklch(main.background).l + (mood === 'dark' ? 0.1 : -0.08), tone.c, tone.h),
+    shadow: '#000000',
+    stars: '#E8B50C',
+  };
+  const buttonPalettes = { 1: BUTTON_PALETTES.button_1_palette, 2: BUTTON_PALETTES.button_2_palette, 3: BUTTON_PALETTES.button_3_palette };
+  const audit = auditSchemes(schemes, buttonPalettes);
+  return {
+    color_schemes: schemes,
+    palette,
+    button_palettes: BUTTON_PALETTES,
+    adjustments,
+    audit: audit.filter((finding) => finding.level !== 'ok'),
+    usage: {
+      'background-1': 'fond principal, la majorité des sections',
+      'background-2': mood === 'dark' ? 'fond sombre adouci, pour rythmer' : 'fond doux teinté de la marque, pour rythmer (réassurance, FAQ, avis)',
+      inverse: mood === 'dark' ? 'fond clair, pour 1 ou 2 sections de contraste' : 'fond sombre, pour 1 ou 2 sections fortes (bandeau défilant, héro, newsletter, pied de page)',
+      scheme: 'couleur de marque en fond, avec parcimonie (bandeau d’annonce, offre, appel à l’action)',
+    },
+  };
+}
+
+function ensureContrastBlended(hex, background, target, alpha) {
+  let candidate = toHex(parseColor(hex));
+  const bg = parseColor(background);
+  const dark = contrast('#000000', background) > contrast('#FFFFFF', background);
+  const base = toOklch(candidate);
+  for (let step = 0; step <= 100; step++) {
+    candidate = oklchHex(base.l + (dark ? -1 : 1) * step * 0.01, base.c, base.h);
+    if (contrast(blend(parseColor(candidate), bg, alpha), bg) >= target) return candidate;
+  }
+  return dark ? '#000000' : '#FFFFFF';
+}

package/src/build/quick-shared.js

@@ -0,0 +1,2 @@
+// A file name from Content > Files, or its shopify:// reference.
+export const imageRef = (value) => (String(value).startsWith('shopify://') ? String(value) : `shopify://shop_images/${String(value).replace(/^.*\//, '').replace(/\?.*$/, '')}`);