story-theme-mcp 1.0.0

package/src/format.js

@@ -0,0 +1,64 @@
+// Text output helpers: tool results are read by the model, so they stay compact and explicit.
+
+export const ok = (text) => ({ content: [{ type: 'text', text: typeof text === 'string' ? text : JSON.stringify(text, null, 2) }] });
+export const fail = (text) => ({ content: [{ type: 'text', text: `⛔ ${text}` }], isError: true });
+
+export function parseContent(content) {
+  if (typeof content !== 'string') return content;
+  try {
+    return JSON.parse(content.replace(/^/, '').replace(/^\s*\/\*[\s\S]*?\*\/\s*/, ''));
+  } catch (error) {
+    throw new Error(`JSON invalide : ${error.message}`);
+  }
+}
+
+const short = (value) => {
+  const text = typeof value === 'string' ? value : JSON.stringify(value);
+  return text.length > 60 ? `${text.slice(0, 57)}…` : text;
+};
+
+export function formatSettings(settings) {
+  const lines = [];
+  let group = null;
+  for (const setting of settings) {
+    if (setting.group !== group) {
+      group = setting.group;
+      if (group) lines.push(`  [${group}]`);
+    }
+    const parts = [`- ${setting.id} (${setting.type}) « ${setting.label} »`];
+    if (setting.default !== undefined) parts.push(`défaut ${short(setting.default)}`);
+    if (setting.options) parts.push(`options ${setting.options.map((option) => option.value).join('|')}`);
+    if (setting.min !== undefined) parts.push(`${setting.min}–${setting.max} pas ${setting.step ?? 1}${setting.unit ? ' ' + setting.unit : ''}`);
+    if (setting.limit) parts.push(`max ${setting.limit}`);
+    if (setting.visible_if) parts.push(`visible si ${setting.visible_if.replace(/\{\{\s*|\s*\}\}/g, '')}`);
+    let line = parts.join(' · ');
+    if (setting.info) line += ` — ${setting.info}`;
+    lines.push(line);
+  }
+  return lines.join('\n');
+}
+
+export function formatValidation(result, { max = 25 } = {}) {
+  const lines = [];
+  if (result.errors.length) {
+    lines.push(`❌ ${result.errors.length} erreur(s) bloquante(s) :`);
+    for (const error of result.errors.slice(0, max)) lines.push(`- ${error.path || '(racine)'} : ${error.message}`);
+    if (result.errors.length > max) lines.push(`- … et ${result.errors.length - max} autre(s)`);
+  } else lines.push('✅ Valide : Shopify acceptera ce fichier.');
+  if (result.warnings.length) {
+    lines.push(`⚠️ ${result.warnings.length} avertissement(s) :`);
+    for (const warning of result.warnings.slice(0, 10)) lines.push(`- ${warning.path || '(racine)'} : ${warning.message}`);
+  }
+  return lines.join('\n');
+}
+
+export function formatFindings(findings, { max = 20 } = {}) {
+  if (!findings.length) return '✨ Revue design : rien à signaler.';
+  const icon = { important: '🔴', suggestion: '🟡', info: 'ℹ️' };
+  const order = { important: 0, suggestion: 1, info: 2 };
+  const sorted = [...findings].sort((a, b) => order[a.level] - order[b.level]);
+  const lines = [`Revue design : ${findings.filter((f) => f.level === 'important').length} à corriger, ${findings.filter((f) => f.level === 'suggestion').length} suggestion(s), ${findings.filter((f) => f.level === 'info').length} info(s)`];
+  for (const finding of sorted.slice(0, max)) lines.push(`- ${icon[finding.level]} ${finding.path || '(page)'} : ${finding.message}`);
+  if (sorted.length > max) lines.push(`- … et ${sorted.length - max} autre(s) (review_project pour tout voir)`);
+  return lines.join('\n');
+}

package/src/index.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+import { loadConfig } from './config.js';
+import { ThemeSource, LicenceError } from './theme/source.js';
+
+// stdout porte le protocole MCP : tout le reste part sur stderr (visible dans les journaux de
+// Claude, jamais dans la conversation).
+const journal = (message) => console.error(`[story-theme] ${message}`);
+
+const config = loadConfig();
+
+// `npx story-theme-mcp --version` sert à vérifier l'installation avant même d'avoir un jeton :
+// il répond sans thème, sans réseau et sans protocole MCP.
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+  console.log(config.version);
+  process.exit(0);
+}
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(
+    [
+      `MCP Story Thème ${config.version}`,
+      '',
+      "Serveur MCP à déclarer dans Claude (ou tout client MCP) : il connaît le Story Thème et",
+      'construit des boutiques Shopify prêtes à importer. Il ne s’utilise pas à la main.',
+      '',
+      'Variables d’environnement :',
+      '  STORY_MCP_TOKEN     jeton personnel (espace membre Story Thème > MCP & Appli) — indispensable',
+      '  STORY_MCP_HOME      dossier des projets et exports (défaut : ~/Documents/Story Theme MCP)',
+      '  STORY_MCP_LANGUAGE  langue des textes (défaut : fr)',
+      '  STORY_MCP_CANAL     « test » pour la version en test du thème (comptes testeurs)',
+      '  STORY_THEME_DIR     dossier de thème local, prioritaire (développement du thème)',
+      '  STORY_MCP_API       espace membre à interroger (défaut : https://story-theme.com)',
+      '',
+      'Installation et mode d’emploi : https://story-theme.com/mcp',
+    ].join('\n'),
+  );
+  process.exit(0);
+}
+
+const source = new ThemeSource(config, { log: journal });
+
+// Le thème est résolu AVANT d'accepter le premier appel : l'assistant ne doit jamais répondre
+// « je ne connais pas cette section » parce que le téléchargement n'était pas fini. Un jeton
+// refusé arrête ici, avec le message de l'espace membre — il n'y a rien à faire sans thème.
+try {
+  const resolu = await source.ensure({ timeoutMs: 20000 });
+  journal(
+    `thème ${resolu.version || ''} (${resolu.origin}) : ${resolu.dir}${resolu.changed ? ' — téléchargé à l’instant' : ''}`,
+  );
+  if (resolu.message) journal(resolu.message);
+} catch (error) {
+  journal(error instanceof LicenceError ? `licence : ${error.message}` : error.message);
+  if (error instanceof LicenceError) process.exit(1);
+  // Sans thème du tout, le serveur démarre quand même : les outils renvoient l'erreur avec la
+  // marche à suivre, ce qui vaut mieux qu'un serveur MCP « en échec » sans explication dans
+  // l'interface de Claude.
+}
+
+const server = createServer({ ...config, source });
+await server.connect(new StdioServerTransport());
+journal(`prêt (projets : ${config.homeDir})`);

package/src/knowledge/descriptions.js

@@ -0,0 +1,192 @@
+// Curated notes on Story Theme 4.0 sections and blocks, for the model choosing what to build.
+// `fr`: what it is. `use`: when it is the right choice. `keywords`: extra search terms.
+// Anything not listed here still comes out of the catalog from its schema.
+
+export const SECTION_NOTES = {
+  'advanced-custom-section': {
+    fr: 'Section libre : un cadre vide (largeur, direction, alignement, espacements, palette, séparateurs) dans lequel on compose n’importe quels blocs, y compris des groupes imbriqués.',
+    use: 'Quand aucune section spécialisée ne convient. Préférer d’abord une section avec preset : elle part d’une composition déjà réglée.',
+    keywords: 'custom personnalisee libre composer groupe mise en page',
+  },
+  'announcement-bar': {
+    fr: 'Barre d’annonce au-dessus de l’en-tête, en trois zones (gauche, centre, droite) : messages qui tournent, défilent ou s’écrivent, compte à rebours, liens, sélecteur de pays.',
+    use: 'Livraison offerte, retours gratuits, offre en cours. Un seul message court par annonce ; trois annonces maximum.',
+    keywords: 'bandeau annonce top bar promo livraison offerte',
+  },
+  apps: { fr: 'Section qui accueille des blocs d’applications (avis, fidélité, etc.) dans le cadre du thème.', use: 'Pour placer un bloc d’application là où l’application le demande.' },
+  banner: {
+    fr: 'Bannière héro : image, vidéo (fichier ou YouTube/Vimeo) avec média mobile distinct, en superposition ou côte à côte, hauteur écran ou ratio, voile, boîte de contenu, animations d’entrée. Trois presets : image, split (média à côté), vidéo.',
+    use: 'Première section de la page d’accueil ou d’une landing : une promesse, un sous-titre, un ou deux boutons.',
+    keywords: 'hero banniere image principale accueil haut de page video fond',
+  },
+  'before-after': { fr: 'Comparateur avant / après avec curseur glissant.', use: 'Résultats visibles : cosmétique, nettoyage, rénovation, retouche.', keywords: 'avant apres comparaison resultat' },
+  'blog-posts': { fr: 'Liste d’articles de blog : grille, carrousel, article mis en avant, journal.', use: 'Contenu éditorial et SEO en bas de page d’accueil.', keywords: 'blog articles journal actualites' },
+  breadcrumb: { fr: 'Fil d’Ariane avec données structurées BreadcrumbList.', use: 'Haut des pages produit, collection et pages de contenu.' },
+  'bundle-builder': {
+    fr: 'Créateur de lot : le client choisit plusieurs produits d’une collection ou d’une liste, avec minimum, maximum, paliers de remise et récapitulatif.',
+    use: 'Coffrets, packs à composer, « 3 achetés = -15 % ». Les remises doivent exister comme réductions automatiques dans Shopify.',
+    keywords: 'lot coffret pack bundle composer box',
+  },
+  calculator: { fr: 'Calculateur d’économies : nous contre eux, abonnement contre achat unique, ou coût par utilisation.', use: 'Justifier un prix (produit durable, abonnement).', keywords: 'calculateur economies prix comparaison cout' },
+  'cart-drawer': { fr: 'Tiroir panier (rendu par le layout, ses blocs vivent dans config/settings_data.json) : en-tête, lignes, récompenses, ventes additionnelles, récapitulatif, paiement.', use: 'Se règle dans les réglages du thème (cart_type = drawer).' },
+  'cart-notification': { fr: 'Pop-up d’ajout au panier avec blocs de récompenses, ventes additionnelles, minuteur, livraison.', use: 'Quand cart_type = notification.' },
+  'collection-list': {
+    fr: 'Liste de collections : grille, carrousel, catégories rondes, bannières, bento. Source : collections choisies, collections d’un menu, ou toutes.',
+    use: 'Aider à naviguer dans un catalogue de plusieurs familles de produits.',
+    keywords: 'collections categories univers rayons',
+  },
+  comparison: { fr: 'Tableau comparatif : « nous contre eux » ou comparaison de produits, cases coche / croix / texte, colonne mise en avant.', use: 'Se différencier d’une alternative (concurrent, grande surface, ancienne méthode).', keywords: 'comparatif tableau nous vs eux concurrent' },
+  contact: { fr: 'Contact : coordonnées et/ou formulaire à champs configurables.', use: 'Page contact.', keywords: 'contact formulaire email telephone' },
+  countdown: { fr: 'Compte à rebours vers une date (fuseau de la boutique), en section ou en bannière d’offre limitée.', use: 'Uniquement pour une échéance réelle (soldes, lancement). Jamais d’urgence inventée.', keywords: 'compte a rebours timer urgence offre limitee' },
+  'custom-liquid': { fr: 'Code Liquid/HTML libre.', use: 'Intégrations ponctuelles. À éviter pour du contenu : non modifiable proprement par le marchand.' },
+  faq: { fr: 'FAQ en accordéons, avec données structurées FAQPage en option. Presets : simple, avec contact, par thème.', use: 'Lever les objections (livraison, retours, taille, composition). Une seule FAQ structurée par page.', keywords: 'faq questions reponses accordeon' },
+  'featured-product': { fr: 'Produit en vedette : galerie et blocs de fiche produit (prix, variantes, achat, offres) pour un produit choisi, hors de la fiche produit.', use: 'Mettre en avant un produit phare sur l’accueil ou une landing.', keywords: 'produit vedette phare mise en avant acheter' },
+  'floating-video': { fr: 'Vidéo flottante en bulle dans un coin, qui s’ouvre en lecteur ; ciblage de pages.', use: 'Vidéo de présentation ou témoignage vidéo, sans prendre de place dans la page.' },
+  footer: { fr: 'Pied de page composé de groupes de blocs (menus, réseaux sociaux, newsletter, coordonnées, logo, paiement, mentions). Presets : colonnes, centré, nom de marque géant.', use: 'Groupe footer uniquement.' },
+  gallery: { fr: 'Galerie d’images : grille, masonry, bento ou carrousel, avec visionneuse.', use: 'Lookbook, univers de marque, réalisations.', keywords: 'galerie photos lookbook images' },
+  header: { fr: 'En-tête composé : trois rangées (haut, principale, bas) de trois zones chacune, plus un tiroir mobile. Menu, méga menu, recherche, compte, panier, logo, sélecteur de pays placés en blocs.', use: 'Groupe header uniquement. Se modifie dans sections/header-group.json.' },
+  hotspots: { fr: 'Image interactive avec points cliquables liés à des produits ou des textes. Presets : « Shop the look », produit expliqué.', use: 'Mise en situation (tenue, pièce de maison) ou anatomie d’un produit.', keywords: 'hotspots points image interactive shop the look' },
+  'image-with-text': {
+    fr: 'Image avec texte, entièrement composée de blocs. Presets : bénéfices produit, histoire de la marque, détails qui comptent.',
+    use: 'Raconter la marque, expliquer un produit, alterner image et texte pour rythmer la page.',
+    keywords: 'image texte histoire marque storytelling benefices',
+  },
+  'landing-mode': {
+    fr: 'Masque en-tête, pied de page, barres d’annonce ou éléments flottants sur toutes les pages qui utilisent ce modèle.',
+    use: 'Page de vente ou d’atterrissage publicitaire : on retire la navigation pour ne laisser qu’un seul chemin, l’achat. Une seule par modèle, à poser dans un modèle de page dédié (jamais sur l’accueil).',
+    keywords: 'landing atterrissage publicite masquer entete pied de page tunnel',
+  },
+  'logo-list': { fr: 'Liste de logos (presse, partenaires, labels) en rangée.', use: 'Preuve sociale : « Ils parlent de nous », certifications.', keywords: 'logos presse partenaires labels' },
+  map: { fr: 'Plan d’accès Google Maps (chargé au clic) avec coordonnées et horaires, une ou plusieurs adresses.', use: 'Boutique physique, showroom, click and collect.' },
+  marquee: { fr: 'Bandeau défilant : textes, logos ou images.', use: 'Réassurance rapide (livraison, retours, avis) ou rythme visuel. Un seul par page en général.', keywords: 'defilant marquee bandeau texte defile' },
+  multicolumn: { fr: 'Multicolonne : icônes avec texte, cartes avec images, étapes numérotées, bénéfices.', use: 'Réassurance, points forts, « comment ça marche ».', keywords: 'colonnes icones avantages benefices etapes reassurance' },
+  newsletter: { fr: 'Inscription newsletter (consentement, prénom, SMS en option, code promo à copier). Presets : simple, avec image, avec réduction.', use: 'Fin de page d’accueil. Donner une vraie raison de s’inscrire.', keywords: 'newsletter inscription email' },
+  'order-tracking': { fr: 'Suivi de commande (17TRACK) et historique pour les clients connectés.', use: 'Page de suivi de colis.', keywords: 'suivi commande colis tracking' },
+  popup: { fr: 'Pop-up : newsletter, réduction, vérification d’âge ; déclencheurs (délai, défilement, intention de sortie, lien #popup-nom) et fréquence.', use: 'Une seule pop-up automatique par boutique. La vérification d’âge seulement quand la loi l’impose.', keywords: 'popup pop-up modal newsletter reduction age' },
+  'product-list': {
+    fr: 'Liste de produits : collection, produits choisis, recommandations, vus récemment, liste de souhaits ; grille, carrousel ou bento ; carte produit composée de blocs.',
+    use: 'Meilleures ventes, nouveautés, produits associés. Presets : collection en vedette, carrousel, onglets de collections, produits associés, vus récemment, produits avec image, immersif, liste compacte, favoris.',
+    keywords: 'produits liste grille carrousel best sellers nouveautes recommandations',
+  },
+  reviews: { fr: 'Avis clients : résumé des notes, bandeau de note, widget Trustpilot.', use: 'Preuve sociale chiffrée. Les notes affichées doivent être réelles.', keywords: 'avis notes etoiles trustpilot' },
+  'quick-order-list': {
+    fr: 'Liste de commande rapide : toutes les variantes d’un produit ou d’une collection avec une quantité par ligne, ajoutées au panier en une fois (images, références, tarifs dégressifs, stock).',
+    use: 'Vente en gros, réassort professionnel, gamme à décliner en tailles ou coloris — quand le client achète plusieurs variantes d’un coup plutôt qu’un produit.',
+    keywords: 'commande rapide gros b2b quantites variantes reassort',
+  },
+  'rich-text': { fr: 'Texte enrichi : titre, texte, boutons. Presets : texte, citation, titre de section, grande déclaration.', use: 'Manifeste de marque, transition entre deux sections, titre de page.', keywords: 'texte titre citation manifeste' },
+  'scroll-cards': { fr: 'Cartes qui s’empilent au défilement.', use: 'Présenter 3 à 5 étapes ou arguments de façon mémorable. Effet fort : une fois par page.', keywords: 'cartes empilees scroll effet' },
+  'scroll-horizontal': { fr: 'Rangée épinglée qui défile horizontalement pendant le défilement vertical.', use: 'Galerie ou collection mise en scène. Effet fort : une fois par page.' },
+  'scroll-story': { fr: 'Scrollytelling : média épinglé qui change avec chaque étape de texte.', use: 'Raconter la fabrication ou les ingrédients d’un produit phare.', keywords: 'scrollytelling histoire etapes defilement' },
+  'scroll-zoom': { fr: 'Média qui grandit d’un cadre arrondi jusqu’au plein écran au défilement.', use: 'Moment « waouh » pour une marque premium, après le héro.' },
+  slideshow: { fr: 'Diaporama de slides héro (mêmes réglages que la bannière), transitions fondu, zoom, révélation, parallaxe ou glissement, autoplay avec barres de progression.', use: 'Plusieurs messages de même importance (collections, campagnes). Sinon préférer une bannière : un message fort convertit mieux.', keywords: 'diaporama slider carrousel hero slides' },
+  specifications: { fr: 'Caractéristiques techniques en liste (clé / valeur).', use: 'Fiche produit technique : dimensions, matière, entretien.', keywords: 'caracteristiques specifications fiche technique' },
+  stats: { fr: 'Statistiques et chiffres clés avec compteurs animés.', use: 'Résultats mesurés, chiffres de la marque. Uniquement des chiffres vérifiables.', keywords: 'chiffres statistiques compteurs resultats' },
+  stories: { fr: 'Stories photo et vidéo façon Instagram, en bulles.', use: 'Contenu social, coulisses, nouveautés.' },
+  testimonials: { fr: 'Témoignages : carrousel, grille, mur, témoignage avec image.', use: 'Preuve sociale qualitative. De vrais avis, avec prénom et si possible photo.', keywords: 'temoignages avis clients' },
+  timeline: { fr: 'Frise chronologique : notre histoire ou comment ça marche.', use: 'Page à propos, processus de fabrication ou de commande.', keywords: 'frise chronologie histoire etapes' },
+  ugc: { fr: 'Photos et vidéos clients (UGC), grille façon Instagram ou vidéos clients.', use: 'Preuve sociale visuelle, produits portés ou utilisés.', keywords: 'ugc instagram photos clients videos' },
+  video: { fr: 'Vidéo : lecteur, vidéo avec texte, vidéo collante (storytelling produit), vidéo d’arrière-plan.', use: 'Démonstration produit, film de marque.', keywords: 'video film demonstration' },
+  'main-product-composed': {
+    fr: 'Fiche produit composée de blocs : galerie, titre, prix, variantes, stock, quantité, achat, offres, livraison, description, accordéons, barre d’achat collante. Presets : fiche produit, fiche avec offres.',
+    use: 'Modèle product uniquement.',
+    keywords: 'fiche produit page produit acheter',
+  },
+  'main-collection': { fr: 'Page collection : bannière de collection, filtres (barre latérale, barre ou tiroir), tri, densité, grille de produits paginée, tuiles promo.', use: 'Modèle collection.' },
+  'main-search': { fr: 'Page de recherche : titre, onglets de types de résultats, filtres, grille.', use: 'Modèle search.' },
+  'main-cart': { fr: 'Page panier en deux zones (lignes, récapitulatif) plus panier vide.', use: 'Modèle cart.' },
+  'main-page': { fr: 'Contenu d’une page Shopify (titre et texte saisis dans l’administration).', use: 'Modèles page.*.' },
+  'main-404': { fr: 'Page 404.', use: 'Modèle 404.' },
+  'main-article': { fr: 'Article de blog : titre, infos, image, contenu, sommaire, partage, auteur, navigation, commentaires, données BlogPosting.', use: 'Modèle article.' },
+  'main-blog': { fr: 'Page de blog : liste des articles.', use: 'Modèle blog.' },
+  'main-list-collections': { fr: 'Page listant toutes les collections.', use: 'Modèle list-collections.' },
+  'main-password': { fr: 'Page mot de passe (boutique en préparation) : image ou vidéo, logo, titre, compte à rebours, newsletter, connexion propriétaire.', use: 'Modèle password.' },
+  'main-login': { fr: 'Connexion client (anciens comptes clients) : formulaire, validation en ligne.', use: 'Modèle customers/login.' },
+  'main-register': { fr: 'Création de compte client.', use: 'Modèle customers/register.' },
+  'main-account': { fr: 'Espace client : informations du compte et historique des commandes.', use: 'Modèle customers/account.' },
+  'main-order': { fr: 'Détail d’une commande client.', use: 'Modèle customers/order.' },
+  'main-addresses': { fr: 'Carnet d’adresses du client.', use: 'Modèle customers/addresses.' },
+  'main-activate-account': { fr: 'Activation d’un compte client invité.', use: 'Modèle customers/activate_account.' },
+  'main-reset-password': { fr: 'Nouveau mot de passe client.', use: 'Modèle customers/reset_password.' },
+};
+
+export const BLOCK_NOTES = {
+  group: { fr: 'Groupe : conteneur flex (horizontal ou vertical, alignements, espacement, fond, bordure, collant) qui peut contenir n’importe quels blocs, y compris d’autres groupes.', keywords: 'groupe conteneur colonne ligne' },
+  heading: { fr: 'Titre (texte riche : <h1>…<h6> ou <p>), sous-titre, mots qui tournent, taille personnalisée, style de titre du thème.', keywords: 'titre h1 h2 heading' },
+  text: { fr: 'Paragraphe en texte riche.', keywords: 'texte paragraphe' },
+  button: { fr: 'Bouton ou lien, styles du thème 1 / 2 / 3 ou personnalisé.', keywords: 'bouton cta lien' },
+  image: { fr: 'Image avec ratio, hauteur, coins, lien, effets au défilement.', keywords: 'image photo visuel' },
+  video: { fr: 'Vidéo en lecteur ou en arrière-plan, avec blocs superposés.', keywords: 'video' },
+  icon: { fr: 'Icône de la bibliothèque du thème ou image.', keywords: 'icone pictogramme' },
+  checklist: { fr: 'Liste à puces avec coches ou icônes (réassurance).', keywords: 'liste puces coches avantages' },
+  accordion: { fr: 'Accordéon : question / réponse, avec balisage FAQ optionnel.', keywords: 'accordeon faq question' },
+  tabs: { fr: 'Onglets contenant chacun des blocs.', keywords: 'onglets tabs' },
+  carousel: { fr: 'Carrousel générique de blocs.', keywords: 'carrousel slider' },
+  'content-over-image': { fr: 'Contenu superposé à une image de fond.', keywords: 'texte sur image overlay' },
+  spacer: { fr: 'Espace ou séparateur.', keywords: 'espace separateur ligne' },
+  badge: { fr: 'Badge (pastille de texte).', keywords: 'badge pastille etiquette' },
+  counter: { fr: 'Compteur animé ({120}K+).', keywords: 'compteur chiffre statistique' },
+  rating: { fr: 'Note en étoiles saisie à la main.', keywords: 'note etoiles' },
+  'review-summary': { fr: 'Résumé des notes (moyenne, répartition).', keywords: 'avis resume notes' },
+  testimonial: { fr: 'Témoignage : texte, auteur, photo, note.', keywords: 'temoignage avis client' },
+  trustpilot: { fr: 'Widget Trustpilot (identifiant d’entreprise requis).', keywords: 'trustpilot avis' },
+  'trust-badges': { fr: 'Badges de confiance (icône ou image de certification, titre, texte).', keywords: 'confiance paiement securise garantie labels' },
+  'payment-icons': { fr: 'Icônes des moyens de paiement actifs.', keywords: 'paiement cartes' },
+  countdown: { fr: 'Compte à rebours vers une date.', keywords: 'compte a rebours timer' },
+  'progress-bar': { fr: 'Barre de progression (objectif, quantité).', keywords: 'progression barre' },
+  newsletter: { fr: 'Formulaire newsletter (consentement, prénom, SMS, code promo).', keywords: 'newsletter email inscription' },
+  'contact-form': { fr: 'Formulaire de contact à champs configurables.', keywords: 'formulaire contact' },
+  'contact-info': { fr: 'Coordonnées : e-mail, téléphone, WhatsApp, adresse, horaires avec statut ouvert/fermé.', keywords: 'coordonnees adresse horaires telephone' },
+  map: { fr: 'Plan Google Maps chargé au clic.', keywords: 'carte plan adresse' },
+  menu: { fr: 'Liste de liens (menu Shopify), repliable sur mobile.', keywords: 'menu liens' },
+  'social-links': { fr: 'Liens réseaux sociaux (depuis les réglages du thème).', keywords: 'reseaux sociaux instagram tiktok' },
+  logo: { fr: 'Logo de la boutique (version fond sombre possible).', keywords: 'logo' },
+  wordmark: { fr: 'Nom de marque géant sur toute la largeur.', keywords: 'nom marque geant' },
+  copyright: { fr: 'Mention de copyright.', keywords: 'copyright' },
+  'policy-links': { fr: 'Liens vers les politiques (CGV, confidentialité, remboursement).', keywords: 'mentions legales cgv politiques' },
+  localization: { fr: 'Sélecteur de pays / langue.', keywords: 'pays langue devise' },
+  'back-to-top': { fr: 'Bouton retour en haut.', keywords: 'retour haut' },
+  share: { fr: 'Boutons de partage.', keywords: 'partage' },
+  'marquee-text': { fr: 'Texte défilant (une phrase par ligne, séparateur).', keywords: 'texte defilant' },
+  'marquee-images': { fr: 'Images défilantes.', keywords: 'images defilantes' },
+  'logo-list': { fr: 'Liste de logos.', keywords: 'logos' },
+  gallery: { fr: 'Galerie d’images (grille, masonry, bento, carrousel).', keywords: 'galerie' },
+  'ugc-gallery': { fr: 'Galerie de photos et vidéos clients.', keywords: 'ugc photos clients' },
+  stories: { fr: 'Stories en bulles.', keywords: 'stories' },
+  'image-before-after': { fr: 'Avant / après à curseur.', keywords: 'avant apres' },
+  'image-hotspots': { fr: 'Image à points cliquables.', keywords: 'hotspots' },
+  timeline: { fr: 'Frise chronologique.', keywords: 'frise' },
+  'comparison-table': { fr: 'Tableau comparatif.', keywords: 'comparatif' },
+  calculator: { fr: 'Calculateur d’économies.', keywords: 'calculateur' },
+  specs: { fr: 'Liste de caractéristiques clé / valeur.', keywords: 'caracteristiques' },
+  pictogram: { fr: 'Pictogramme flottant décoratif.', keywords: 'pictogramme decoratif' },
+  'text-reveal': { fr: 'Texte dont les mots s’illuminent au défilement.', keywords: 'texte revele scroll' },
+  custom_liquid: { fr: 'Code Liquid libre.', keywords: 'liquid code' },
+  'product-list': { fr: 'Liste de produits (collection, choix, recommandations, vus récemment, favoris) avec carte produit composée.', keywords: 'produits liste' },
+  'collection-list': { fr: 'Liste de collections avec carte composée.', keywords: 'collections' },
+  'blog-posts': { fr: 'Liste d’articles.', keywords: 'articles blog' },
+  'bundle-builder': { fr: 'Créateur de lot.', keywords: 'lot bundle' },
+  'product-media': { fr: 'Galerie du produit (miniatures, zoom, vidéos, 3D).', keywords: 'galerie produit photos' },
+  'product-title': { fr: 'Titre du produit (niveau de titre réglable : h1 sur la fiche produit).', keywords: 'titre produit' },
+  'product-price': { fr: 'Prix, prix barré, badge promo, mention taxes, paiement en plusieurs fois (Shop Pay).', keywords: 'prix promo' },
+  'product-variants': { fr: 'Sélecteur de variantes (boutons, pastilles, liste).', keywords: 'variantes taille couleur' },
+  'product-quantity': { fr: 'Sélecteur de quantité (règles de quantité, prix dégressifs B2B).', keywords: 'quantite' },
+  'product-buy': { fr: 'Boutons d’achat : ajouter au panier, paiement accéléré, retrait en magasin, carte cadeau à offrir.', keywords: 'ajouter au panier acheter' },
+  'product-offers': { fr: 'Offres : paliers de quantité, X achetés Y offert, packs, lots, cadeaux. Le thème affiche, Shopify facture : chaque offre exige une réduction automatique ou un code.', keywords: 'offres paliers quantite bogo packs remise' },
+  'product-subscription': { fr: 'Options d’achat : abonnement (plans de vente d’une app d’abonnement) ou achat unique.', keywords: 'abonnement' },
+  'product-addons': { fr: 'Compléments : produits ajoutés avec le produit, cadeau à choisir, souvent achetés ensemble.', keywords: 'complements cross sell cadeau achetes ensemble' },
+  'product-description': { fr: 'Description du produit.', keywords: 'description' },
+  'product-rating': { fr: 'Note du produit (métachamps d’avis d’une application, ou saisie).', keywords: 'note avis produit' },
+  'product-stock': { fr: 'Stock : stock réel Shopify ou chiffre simulé (à éviter : l’urgence doit être réelle).', keywords: 'stock inventaire' },
+  'product-delivery': { fr: 'Date de livraison estimée (jours ouvrés, heure limite, jours fermés).', keywords: 'livraison date estimee' },
+  'product-shipping-bar': { fr: 'Barre de progression vers la livraison offerte.', keywords: 'livraison offerte barre' },
+  'product-spin-message': { fr: 'Messages tournants sous le bouton d’achat.', keywords: 'messages reassurance' },
+  'product-size-guide': { fr: 'Guide des tailles en fenêtre (tableau cm / in).', keywords: 'guide des tailles' },
+  'product-custom-field': { fr: 'Champ de personnalisation (gravure, photo, emballage cadeau), envoyé en propriété de ligne.', keywords: 'personnalisation gravure' },
+  'product-sticky-bar': { fr: 'Barre d’ajout au panier collante (bas, haut ou carte flottante).', keywords: 'barre collante sticky ajout panier' },
+  facets: { fr: 'Filtres de collection (barre latérale, barre, tiroir).', keywords: 'filtres' },
+  'product-grid': { fr: 'Grille de produits paginée des pages collection et recherche.', keywords: 'grille produits' },
+  'collection-header': { fr: 'Bannière de collection (titre, description, image).', keywords: 'banniere collection' },
+  'page-title': { fr: 'Titre de la page Shopify.', keywords: 'titre page' },
+  'page-content': { fr: 'Contenu de la page Shopify.', keywords: 'contenu page' },
+};

package/src/knowledge/directions.js

@@ -0,0 +1,85 @@
+// Art directions: the whole look of a store, not only its colours. Each one sets the theme's
+// global style settings, decorates sections (shape separators, their animation) and picks the
+// signature moments of the home page. Every value is an option of the theme's own schema
+// (tests check them).
+
+export const DIRECTIONS = {
+  editorial: {
+    label: 'Éditorial chic',
+    for: 'mode, bijoux, maroquinerie, marque premium',
+    fonts: 'editorial',
+    settings: { radius_preset: 'sharp', subheadings_uppercase: true, subheadings_letter_spacing: 3, heading_separator: false, buttons_font: 'body', hover_button_effect: 'fill', hover_card_effect: 'zoom', page_transition_style: 'curtain', button_1_shadow: false, media_container_border: 'none', content_container_border: 'none', collapsible_icon: 'plus_rotating' },
+    separator: null,
+    signatures: ['manifesto', 'showcase'],
+  },
+  minimal: {
+    label: 'Minimal scandinave',
+    for: 'maison, déco, objets, grand catalogue',
+    fonts: 'minimal',
+    settings: { radius_preset: 'soft', subheadings_uppercase: true, subheadings_letter_spacing: 2, heading_separator: false, hover_button_effect: 'lift', hover_card_effect: 'zoom', page_transition_style: 'fade', button_1_shadow: false, media_container_border: 'none', content_container_border: 'border--1' },
+    separator: null,
+    signatures: ['manifesto', 'cards'],
+  },
+  organique: {
+    label: 'Naturel organique',
+    for: 'bougies, épicerie fine, cosmétique naturelle, bio, fait main',
+    fonts: 'natural',
+    settings: { radius_preset: 'rounded', subheadings_uppercase: false, heading_separator: true, hover_button_effect: 'lift', hover_card_effect: 'lift', page_transition_style: 'dissolve', button_1_shadow: false, collapsible_icon: 'plus_minus' },
+    separator: { shape: 'organic', animation: 'flow' },
+    signatures: ['process', 'manifesto'],
+  },
+  artisan: {
+    label: 'Atelier artisanal',
+    for: 'artisanat, céramique, maroquinerie faite main, producteur',
+    fonts: 'heritage',
+    settings: { radius_preset: 'soft', subheadings_uppercase: true, subheadings_letter_spacing: 2, heading_separator: true, hover_button_effect: 'lift', hover_card_effect: 'zoom', page_transition_style: 'tiles', button_1_shadow: false },
+    separator: { shape: 'torn', animation: 'none' },
+    signatures: ['process', 'manifesto'],
+  },
+  douceur: {
+    label: 'Douceur beauté',
+    for: 'beauté, soin, bien-être, maternité',
+    fonts: 'soft-modern',
+    settings: { radius_preset: 'round', subheadings_uppercase: false, heading_separator: false, hover_button_effect: 'lift', hover_card_effect: 'lift', page_transition_style: 'blur', card_style: 'card', button_1_shadow: true },
+    separator: { shape: 'curve', animation: 'swell' },
+    signatures: ['cards', 'manifesto'],
+  },
+  pop: {
+    label: 'Pop coloré',
+    for: 'enfants, animaux, snacks, accessoires fun, marque joyeuse',
+    fonts: 'friendly',
+    settings: { radius_preset: 'round', subheadings_uppercase: true, subheadings_letter_spacing: 1, heading_separator: false, hover_button_effect: 'magnetic', hover_card_effect: 'tilt', page_transition_style: 'circle', card_style: 'card', button_1_shadow: true },
+    separator: { shape: 'scallop', animation: 'swell' },
+    signatures: ['cards', 'rotating'],
+  },
+  energie: {
+    label: 'Sport énergique',
+    for: 'sport, nutrition, outdoor, streetwear',
+    fonts: 'bold-sport',
+    settings: { radius_preset: 'sharp', headings_uppercase: true, headings_letter_spacing: 1, subheadings_uppercase: true, subheadings_letter_spacing: 2, heading_separator: false, hover_button_effect: 'shine', hover_card_effect: 'lift_zoom', page_transition_style: 'diagonal', button_1_shadow: false },
+    separator: { shape: 'slope', animation: 'none' },
+    signatures: ['cards', 'rotating'],
+  },
+  tech: {
+    label: 'Tech précis',
+    for: 'électronique, accessoires, gadgets, produit technique',
+    fonts: 'tech',
+    settings: { radius_preset: 'soft', subheadings_uppercase: true, subheadings_letter_spacing: 2, heading_separator: false, hover_button_effect: 'magnetic', hover_card_effect: 'spotlight', page_transition_style: 'blur', button_1_shadow: false, media_container_border: 'none' },
+    separator: null,
+    signatures: ['cards', 'rotating'],
+  },
+};
+
+// Default direction for each style of build_store.
+export const STYLE_DIRECTION = {
+  essentiel: 'minimal',
+  premium: 'editorial',
+  mode: 'editorial',
+  beaute: 'douceur',
+  nature: 'organique',
+  maison: 'minimal',
+  tech: 'tech',
+  sport: 'energie',
+  enfant: 'pop',
+  'produit-unique': 'energie',
+};

package/src/knowledge/fonts.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import { normalizeText } from '../theme/catalog.js';
+
+const LIBRARY = JSON.parse(fs.readFileSync(new URL('../data/shopify-fonts.json', import.meta.url), 'utf8'));
+
+const byHandle = new Map();
+for (const family of LIBRARY.available) for (const handle of family.handles) byHandle.set(handle, { family: family.family, deprecated: false, alternative: family.alternative || null });
+for (const family of LIBRARY.deprecated) for (const handle of family.handles) if (!byHandle.has(handle)) byHandle.set(handle, { family: family.family, deprecated: true, replacement: family.replacement });
+
+export const FONT_LIBRARY = LIBRARY;
+
+export function fontInfo(handle) {
+  return byHandle.get(handle) || null;
+}
+
+function familyHandles(name) {
+  const family = LIBRARY.available.find((entry) => normalizeText(entry.family) === normalizeText(name));
+  return family ? family.handles : [];
+}
+
+// Checks a font_picker value. Unknown handles are refused at upload; deprecated ones still render
+// but Shopify has announced their removal.
+export function checkFontHandle(handle) {
+  if (typeof handle !== 'string' || !handle) return [{ level: 'error', message: 'police vide : choisissez un identifiant de la bibliothèque Shopify (ex. jost_n4)' }];
+  const info = byHandle.get(handle);
+  if (!info) {
+    const base = handle.replace(/_[nio]\d$/, '');
+    const sameFamily = [...byHandle.keys()].filter((candidate) => candidate.startsWith(base + '_')).slice(0, 6);
+    return [{ level: 'error', message: `police « ${handle} » inconnue de la bibliothèque Shopify${sameFamily.length ? ` (graisses existantes : ${sameFamily.join(', ')})` : ''}. Utilisez find_fonts.` }];
+  }
+  if (info.deprecated) {
+    const replacement = familyHandles(info.replacement);
+    const weight = handle.match(/_([nio]\d)$/)?.[1]?.replace('o', 'i');
+    const suggestion = replacement.find((candidate) => candidate.endsWith(`_${weight}`)) || replacement.find((candidate) => candidate.endsWith('_n4'));
+    return [{ level: 'warning', message: `la police ${info.family} est dépréciée par Shopify (remplaçante : ${info.replacement}${suggestion ? `, ex. ${suggestion}` : ''}). Changez-la avant qu'elle ne disparaisse.` }];
+  }
+  return [];
+}
+
+export function searchFonts(query, limit = 20) {
+  const target = normalizeText(query);
+  return LIBRARY.available
+    .filter((family) => normalizeText(family.family).includes(target))
+    .slice(0, limit)
+    .map((family) => ({ family: family.family, handles: family.handles, ...(family.alternative ? { licensed: true, free_alternative: family.alternative } : {}) }));
+}
+
+// Pairings verified against the library by the tests. Weights: heading, body.
+export const FONT_PAIRINGS = [
+  { id: 'editorial', style: 'Éditorial, luxe, mode', heading: 'cormorant_n5', body: 'jost_n4', note: 'Serif à fort contraste pour les titres, sans-serif géométrique pour le texte. Titres grands et aérés, pas en majuscules.' },
+  { id: 'classic-serif', style: 'Élégant, bijoux, cosmétique haut de gamme', heading: 'playfair_display_n4', body: 'dm_sans_n4', note: 'Classique et lisible. Éviter le gras sur Playfair.' },
+  { id: 'soft-modern', style: 'Beauté, bien-être, clean beauty', heading: 'fraunces_n4', body: 'manrope_n4', note: 'Serif douce et chaleureuse, texte très lisible.' },
+  { id: 'minimal', style: 'Minimaliste, scandinave, maison et déco', heading: 'jost_n5', body: 'jost_n4', note: 'Une seule famille, deux graisses : cohérent et rapide à charger.' },
+  { id: 'tech', style: 'Tech, accessoires, électronique', heading: 'space_grotesk_n6', body: 'inter_n4', note: 'Grotesque technique pour les titres, Inter pour le texte.' },
+  { id: 'bold-sport', style: 'Sport, énergie, streetwear', heading: 'bebas_neue_n4', body: 'barlow_n4', note: 'Titres condensés en majuscules, texte robuste. Réserver Bebas aux titres courts.' },
+  { id: 'natural', style: 'Naturel, artisanal, épicerie fine', heading: 'young_serif_n4', body: 'work_sans_n4', note: 'Serif généreuse et authentique.' },
+  { id: 'friendly', style: 'Enfants, animaux, marque joyeuse', heading: 'fredoka_n6', body: 'nunito_n4', note: 'Formes arrondies, ton chaleureux.' },
+  { id: 'contemporary', style: 'Contemporain, DTC, marque produit unique', heading: 'bricolage_grotesque_n6', body: 'plus_jakarta_sans_n4', note: 'Caractère affirmé pour les titres, texte net.' },
+  { id: 'heritage', style: 'Maison historique, vins, savoir-faire', heading: 'libre_caslon_text_n4', body: 'libre_franklin_n4', note: 'Tradition typographique, sérieux et chaleureux.' },
+  { id: 'clean-sans', style: 'Neutre, polyvalent, gros catalogue', heading: 'dm_sans_n6', body: 'dm_sans_n4', note: 'Sobre et très lisible, ne vole pas la vedette aux produits.' },
+  { id: 'fashion-sans', style: 'Mode urbaine, prêt-à-porter', heading: 'syne_n6', body: 'inter_n4', note: 'Titres expressifs à utiliser en grand.' },
+];