story-theme-mcp 1.0.0

package/src/shops/client.js

@@ -0,0 +1,38 @@
+// Client de la passerelle multi-boutiques de Story Apps (l'appli Shopify du Story Thème).
+// Le jeton est celui du MCP (STORY_MCP_TOKEN) : aucune clé Shopify n'est jamais stockée ici.
+
+const DEFAULT_APPS = 'https://apps.story-theme.com';
+
+export function appsBase(env = process.env) {
+  return (env.STORY_APPS_URL || DEFAULT_APPS).trim().replace(/\/$/, '');
+}
+
+export class ShopsError extends Error {}
+
+export function createShopsClient({ token, base = appsBase(), fetchImpl = globalThis.fetch }) {
+  const appel = async (chemin, options = {}) => {
+    if (!token) {
+      throw new ShopsError(
+        "Aucun jeton : générez-le dans votre espace Story Thème (Story Thème > MCP), puis ajoutez STORY_MCP_TOKEN à la configuration de Claude.",
+      );
+    }
+    let res;
+    try {
+      res = await fetchImpl(`${base}${chemin}`, {
+        ...options,
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...(options.headers || {}) },
+        signal: AbortSignal.timeout(30000),
+      });
+    } catch {
+      throw new ShopsError('Story Apps injoignable. Vérifiez votre connexion, puis réessayez.');
+    }
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) throw new ShopsError(data.error || `Erreur ${res.status}`);
+    return data;
+  };
+  return {
+    list: ({ overview = false } = {}) => appel(`/mcp/shops${overview ? '?overview=1' : ''}`),
+    graphql: ({ shops, query, variables, confirm }) =>
+      appel('/mcp/graphql', { method: 'POST', body: JSON.stringify({ shops, query, variables, confirm }) }),
+  };
+}

package/src/shops/format.js

@@ -0,0 +1,58 @@
+// Mise en forme « Story Thème » des résultats multi-boutiques : lisible par le modèle comme par
+// l'utilisateur quand il la recopie.
+
+const BANDEAU = '◆ Story Thème · Vos boutiques';
+const n = (v) => (v === null || v === undefined ? '—' : new Intl.NumberFormat('fr-FR').format(v));
+
+const etatTheme = (t = {}) => {
+  if (!t.version) return 'thème inconnu';
+  const base = `${t.compatible ? 'Story Thème' : t.name || 'autre thème'} ${t.version}`;
+  return t.updateAvailable ? `${base} (mise à jour dispo)` : base;
+};
+
+const etatLicence = (l) => ({ active: 'licence active', inactive: '⚠️ licence inactive', unknown: '⚠️ boutique non rattachée' })[l] || l || '';
+
+export function formatShopList(data) {
+  const shops = data.shops || [];
+  const lignes = [BANDEAU, `Compte : ${data.account?.email || '?'} · ${shops.length} boutique${shops.length > 1 ? 's' : ''} connectée${shops.length > 1 ? 's' : ''}`, ''];
+  if (!shops.length) {
+    lignes.push(
+      "Aucune boutique connectée. Pour en connecter une : installez l'appli Story Apps sur la boutique (depuis l'App Store Shopify ou l'espace Story Thème), et vérifiez qu'elle est déclarée dans votre espace membre (Boutiques).",
+    );
+    return lignes.join('\n');
+  }
+  for (const s of shops) {
+    lignes.push(`● ${s.name} — ${s.domain || s.shop}`);
+    lignes.push(`  handle : ${s.handle || s.shop} · ${etatTheme(s.theme)} · ${etatLicence(s.licence)}`);
+  }
+  lignes.push('', 'shop_graphql accepte un handle, un domaine, une liste ou "all".');
+  return lignes.join('\n');
+}
+
+export function formatOverview(data) {
+  const shops = data.shops || [];
+  const lignes = [BANDEAU, `Vue d'ensemble · ${shops.length} boutique${shops.length > 1 ? 's' : ''}`, ''];
+  for (const s of shops) {
+    lignes.push(`● ${s.name}${s.url ? ` — ${s.url}` : ''}`);
+    lignes.push(`  ${etatTheme(s.theme)} · ${etatLicence(s.licence)}${s.plan ? ` · Shopify ${s.plan}` : ''}`);
+    lignes.push(`  ${n(s.products)} produits · ${n(s.collections)} collections`);
+    const m = s.modules || {};
+    lignes.push(
+      `  Story Apps : ${n(m.reviews)} avis${m.reviewsPending ? ` (${m.reviewsPending} à modérer)` : ''} · ${n(m.abTests)} test${m.abTests > 1 ? 's' : ''} A/B · ${n(m.postPurchaseOffers)} offre${m.postPurchaseOffers > 1 ? 's' : ''} après paiement`,
+    );
+    if (s.errors?.length) lignes.push(`  ⚠️ ${s.errors.map((e) => e.message).join(' · ')}`);
+  }
+  return lignes.join('\n');
+}
+
+export function formatGraphql(data) {
+  const res = data.results || [];
+  const ok = res.filter((r) => !r.errors?.length).length;
+  const lignes = [`${BANDEAU} · ${data.operation === 'mutation' ? 'écriture' : 'lecture'} sur ${res.length} boutique${res.length > 1 ? 's' : ''} (${ok} OK)`];
+  for (const r of res) {
+    lignes.push('', `## ${r.name} (${r.shop})`);
+    if (r.errors?.length) lignes.push(`⛔ ${r.errors.map((e) => e.message).join(' · ')}`);
+    if (r.data) lignes.push(JSON.stringify(r.data, null, 2));
+  }
+  return lignes.join('\n');
+}

package/src/shops/tools.js

@@ -0,0 +1,77 @@
+// Outils « multi-boutiques » du MCP Story Thème : lire et modifier TOUTES les boutiques d'un
+// client en même temps, sans se déconnecter, via l'appli Shopify Story Apps.
+//
+// Branchement : dans src/server.js, juste avant `return server;` de createServer :
+//     registerShopTools(server, config);
+// (import { registerShopTools } from './shops/tools.js';)
+
+import { z } from 'zod';
+import { createShopsClient, appsBase, ShopsError } from './client.js';
+import { formatShopList, formatOverview, formatGraphql } from './format.js';
+
+const ok = (text, structured) => ({ content: [{ type: 'text', text }], ...(structured ? { structuredContent: structured } : {}) });
+const fail = (text) => ({ content: [{ type: 'text', text: `⛔ ${text}` }], isError: true });
+
+const garde = (fn) => async (args) => {
+  try {
+    return await fn(args || {});
+  } catch (e) {
+    return fail(e instanceof ShopsError ? e.message : `Erreur inattendue : ${e.message}`);
+  }
+};
+
+const cibleSchema = z
+  .union([z.string(), z.array(z.string())])
+  .describe('Boutique(s) : handle (ex. "maison-lumen"), domaine, liste, ou "all" pour toutes.');
+
+export function registerShopTools(server, config, { fetchImpl } = {}) {
+  const client = createShopsClient({ token: config.token, base: appsBase(), fetchImpl });
+
+  server.registerTool(
+    'list_shops',
+    {
+      title: 'Vos boutiques',
+      description:
+        "Lists every Shopify store of this Story Theme account that has the Story Apps app installed: name, domain, handle, theme version, licence. Call it first before any multi-store work. Stores are reached through Story Apps: no Shopify key needed.",
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    garde(async () => {
+      const data = await client.list();
+      return ok(formatShopList(data), data);
+    }),
+  );
+
+  server.registerTool(
+    'shops_overview',
+    {
+      title: "Vue d'ensemble des boutiques",
+      description:
+        'Key figures of all connected stores in one call: products, collections, Shopify plan, theme version and pending update, licence, and Story Apps modules (reviews, pending reviews, A/B tests, post-purchase offers).',
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    garde(async () => {
+      const data = await client.list({ overview: true });
+      return ok(formatOverview(data), data);
+    }),
+  );
+
+  server.registerTool(
+    'shop_graphql',
+    {
+      title: 'Requête sur une ou plusieurs boutiques',
+      description:
+        'Runs one Shopify Admin GraphQL operation (API 2025-10) on one, several or all connected stores, in parallel. Queries and mutations within the Story Apps scopes (products, collections, pages, menus, files, discounts, themes read). A mutation on several stores needs confirm: true, only after the user explicitly agreed. Every access is logged.',
+      inputSchema: {
+        shops: cibleSchema,
+        query: z.string().describe('Requête ou mutation GraphQL Admin.'),
+        variables: z.record(z.string(), z.any()).optional(),
+        confirm: z.boolean().optional().describe("Obligatoire pour une écriture sur plusieurs boutiques, après accord de l'utilisateur."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    },
+    garde(async ({ shops, query, variables, confirm }) => {
+      const data = await client.graphql({ shops: shops ?? 'all', query, variables, confirm });
+      return ok(formatGraphql(data), data);
+    }),
+  );
+}

package/src/theme/catalog.js

@@ -0,0 +1,415 @@
+import { SECTION_NOTES, BLOCK_NOTES } from '../knowledge/descriptions.js';
+
+export const NON_VALUE_TYPES = new Set(['header', 'paragraph']);
+
+export function normalizeText(value) {
+  return String(value ?? '')
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+}
+
+// "templates/page.contact.json" -> "page", "templates/customers/account.json" -> "customers/account".
+export function templateTypeOf(file) {
+  const name = file.replace(/^templates\//, '').replace(/\.json$/, '');
+  if (name.startsWith('customers/')) return name;
+  return name.split('.')[0];
+}
+
+export function isInternalTemplate(file) {
+  return /\.qa[\w-]*\.json$|\/[a-z]+\.qa[\w-]*\.json$|hero-test|\/product\.v4\.json$/.test(file);
+}
+
+function levenshtein(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i++) {
+    let previous = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const current = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+      previous = current;
+    }
+  }
+  return row[b.length];
+}
+
+export function closest(value, candidates, max = 3) {
+  const target = String(value).toLowerCase();
+  return [...candidates]
+    .map((candidate) => ({ candidate, score: levenshtein(target, String(candidate).toLowerCase()) - (String(candidate).includes(target) || target.includes(candidate) ? 2 : 0) }))
+    .filter(({ score, candidate }) => score <= Math.max(3, Math.floor(String(candidate).length / 2)))
+    .sort((a, b) => a.score - b.score)
+    .slice(0, max)
+    .map(({ candidate }) => candidate);
+}
+
+export class Catalog {
+  constructor(theme) {
+    this.theme = theme;
+    this.version = theme.version;
+    this.name = theme.name;
+    this.locales = new Map();
+    this.defaultLanguage = theme.defaultLanguage;
+    this.globalSettings = this.#buildGlobalSettings();
+    this.schemeDefinition = this.globalSettings.find((setting) => setting.type === 'color_scheme_group') || null;
+  }
+
+  // ---- translations
+
+  locale(language) {
+    if (!this.locales.has(language)) this.locales.set(language, this.theme.loadSchemaLocale(language));
+    return this.locales.get(language);
+  }
+
+  get languages() {
+    return this.theme.schemaLanguages;
+  }
+
+  resolveKey(key, language) {
+    for (const lang of [language, this.defaultLanguage]) {
+      const tree = this.locale(lang);
+      let node = tree;
+      for (const part of key.split('.')) {
+        if (!node || typeof node !== 'object' || !(part in node)) {
+          node = undefined;
+          break;
+        }
+        node = node[part];
+      }
+      if (typeof node === 'string') return node;
+    }
+    return null;
+  }
+
+  t(value, language = 'fr') {
+    if (typeof value === 'string' && value.startsWith('t:')) {
+      const resolved = this.resolveKey(value.slice(2), language);
+      return resolved ?? value;
+    }
+    return value;
+  }
+
+  // English text -> the same text in `language`, from the theme's editor and storefront
+  // translations. Used to localise the English sample content of the shipped templates.
+  translationPairs(language) {
+    this._pairs ||= new Map();
+    if (this._pairs.has(language)) return this._pairs.get(language);
+    const pairs = new Map();
+    const add = (source, target) => {
+      const walk = (node, other) => {
+        for (const [key, value] of Object.entries(node || {})) {
+          if (typeof value === 'string' && typeof other?.[key] === 'string') {
+            if (!pairs.has(value) && value.trim()) pairs.set(value, other[key]);
+          } else if (value && typeof value === 'object') walk(value, other?.[key]);
+        }
+      };
+      walk(source, target);
+    };
+    if (language !== this.defaultLanguage) {
+      add(this.locale(this.defaultLanguage), this.locale(language));
+      add(this.theme.loadStorefrontLocale(this.defaultLanguage), this.theme.loadStorefrontLocale(language));
+    }
+    this._pairs.set(language, pairs);
+    return pairs;
+  }
+
+  // Resolves every t: string in a preset tree (sample content) for one language.
+  translateDeep(value, language) {
+    if (typeof value === 'string') return value.startsWith('t:') ? this.resolveKey(value.slice(2), language) ?? '' : value;
+    if (Array.isArray(value)) return value.map((item) => this.translateDeep(item, language));
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, this.translateDeep(item, language)]));
+    }
+    return value;
+  }
+
+  // ---- definitions
+
+  section(type) {
+    return this.theme.sections.get(type) || null;
+  }
+
+  block(type) {
+    return this.theme.blocks.get(type) || null;
+  }
+
+  get sectionTypes() {
+    return [...this.theme.sections.keys()];
+  }
+
+  get blockTypes() {
+    return [...this.theme.blocks.keys()];
+  }
+
+  isPrivate(type) {
+    return type.startsWith('_');
+  }
+
+  isAppBlock(type) {
+    return typeof type === 'string' && type.startsWith('shopify://apps/');
+  }
+
+  // What a section or block schema accepts as children.
+  childPolicy(schema) {
+    const declared = schema?.blocks || [];
+    return {
+      theme: declared.some((entry) => entry.type === '@theme'),
+      app: declared.some((entry) => entry.type === '@app'),
+      explicit: declared.filter((entry) => !entry.type.startsWith('@')).map((entry) => entry.type),
+      local: Object.fromEntries(declared.filter((entry) => !entry.type.startsWith('@') && (entry.settings || entry.name)).map((entry) => [entry.type, entry])),
+      maxBlocks: schema?.max_blocks ?? 50,
+    };
+  }
+
+  // Returns the definition a child block is validated against, or a reason it is refused.
+  resolveChild(parentSchema, type) {
+    const policy = this.childPolicy(parentSchema);
+    if (this.isAppBlock(type)) {
+      return policy.app ? { ok: true, app: true } : { ok: false, reason: "n'accepte pas les blocs d'application (@app)" };
+    }
+    if (Object.hasOwn(policy.local, type)) return { ok: true, schema: policy.local[type], local: true };
+    const entry = this.block(type);
+    if (!entry) return { ok: false, reason: `le bloc « ${type} » n'existe pas dans le thème`, unknown: true };
+    if (!entry.schema) return { ok: false, reason: `blocks/${type}.liquid n'a pas de schéma lisible` };
+    if (policy.explicit.includes(type)) return { ok: true, schema: entry.schema };
+    if (policy.theme && !this.isPrivate(type)) return { ok: true, schema: entry.schema };
+    return {
+      ok: false,
+      reason: this.isPrivate(type)
+        ? `« ${type} » est un bloc privé : seul un parent qui le déclare explicitement peut le contenir`
+        : "ce parent n'accepte pas les blocs du thème (@theme) et ne déclare pas ce type",
+    };
+  }
+
+  acceptedChildTypes(schema) {
+    const policy = this.childPolicy(schema);
+    const types = new Set(policy.explicit);
+    if (policy.theme) for (const type of this.blockTypes) if (!this.isPrivate(type)) types.add(type);
+    return [...types];
+  }
+
+  // Every section or block that can hold a block type directly.
+  parentsOf(type) {
+    const parents = [];
+    for (const [kind, map] of [['section', this.theme.sections], ['block', this.theme.blocks]]) {
+      for (const [parentType, entry] of map) {
+        if (!entry.schema?.blocks) continue;
+        const policy = this.childPolicy(entry.schema);
+        if (policy.explicit.includes(type)) parents.push({ kind, type: parentType, via: 'explicit' });
+        else if (policy.theme && !this.isPrivate(type)) parents.push({ kind, type: parentType, via: '@theme' });
+      }
+    }
+    return parents;
+  }
+
+  staticChildren(kind, type) {
+    const entry = kind === 'section' ? this.section(type) : this.block(type);
+    return entry?.statics || [];
+  }
+
+  // ---- placement rules
+
+  sectionAllowedIn(schema, context) {
+    const enabled = schema?.enabled_on;
+    const disabled = schema?.disabled_on;
+    const match = (rule) => {
+      if (!rule) return false;
+      if (context.template) {
+        const list = rule.templates || [];
+        return list.includes('*') || list.includes(context.template);
+      }
+      if (context.group) {
+        const list = rule.groups || [];
+        return list.includes('*') || list.includes(context.group) || (context.group.startsWith('custom.') && list.includes('custom.*'));
+      }
+      return false;
+    };
+    if (enabled && !match(enabled)) return false;
+    if (disabled && match(disabled)) return false;
+    return true;
+  }
+
+  describePlacement(schema, language = 'fr') {
+    const parts = [];
+    const describe = (rule) => [...(rule.templates || []).map((t) => `modèle ${t}`), ...(rule.groups || []).map((g) => `groupe ${g}`)].join(', ');
+    if (schema?.enabled_on) parts.push(`${language === 'fr' ? 'uniquement' : 'only'} : ${describe(schema.enabled_on)}`);
+    if (schema?.disabled_on) parts.push(`${language === 'fr' ? 'interdit' : 'not in'} : ${describe(schema.disabled_on)}`);
+    return parts.join(' ; ') || (language === 'fr' ? 'partout' : 'anywhere');
+  }
+
+  // ---- settings
+
+  normalizeSettings(settings, language = 'fr') {
+    const out = [];
+    let group = null;
+    for (const setting of settings || []) {
+      if (setting.type === 'header') {
+        group = this.t(setting.content, language);
+        continue;
+      }
+      if (setting.type === 'paragraph') continue;
+      const item = { id: setting.id, type: setting.type, label: this.t(setting.label, language) ?? setting.id };
+      if (group) item.group = group;
+      if ('default' in setting) item.default = typeof setting.default === 'string' ? this.t(setting.default, language) : setting.default;
+      if (setting.options) item.options = setting.options.map((option) => ({ value: option.value, label: this.t(option.label, language) }));
+      for (const key of ['min', 'max', 'step', 'unit', 'visible_if', 'limit', 'accept']) if (key in setting) item[key] = setting[key];
+      if (setting.info) item.info = this.t(setting.info, language);
+      if (setting.placeholder) item.placeholder = this.t(setting.placeholder, language);
+      if (setting.definition) item.definition = this.normalizeSettings(setting.definition, language);
+      out.push(item);
+    }
+    return out;
+  }
+
+  settingIndex(schema) {
+    return new Map((schema?.settings || []).filter((setting) => setting.id).map((setting) => [setting.id, setting]));
+  }
+
+  #buildGlobalSettings() {
+    const list = [];
+    for (const group of this.theme.settingsSchema) {
+      if (group.name === 'theme_info') continue;
+      for (const setting of group.settings || []) if (setting.id) list.push({ ...setting, __group: group.name });
+    }
+    return list;
+  }
+
+  globalSettingIndex() {
+    return new Map(this.globalSettings.map((setting) => [setting.id, setting]));
+  }
+
+  defaultSchemeIds() {
+    return Object.keys(this.theme.settingsData?.current?.color_schemes || {});
+  }
+
+  // ---- presets
+
+  presetsOf(schema) {
+    return schema?.presets || [];
+  }
+
+  findPreset(schema, name, language = 'fr') {
+    const presets = this.presetsOf(schema);
+    if (name === undefined || name === null || name === '') return { preset: presets[0] || null, index: 0 };
+    if (typeof name === 'number') return { preset: presets[name] || null, index: name };
+    const target = normalizeText(name);
+    const index = presets.findIndex((preset) =>
+      [this.t(preset.name, 'en'), this.t(preset.name, language), this.t(preset.name, 'fr'), preset.name].some((label) => normalizeText(label) === target),
+    );
+    return { preset: index === -1 ? null : presets[index], index };
+  }
+
+  presetNames(schema, language = 'fr') {
+    return this.presetsOf(schema).map((preset) => this.t(preset.name, language));
+  }
+
+  // ---- summaries for the model
+
+  notes(kind, type) {
+    return (kind === 'section' ? SECTION_NOTES : BLOCK_NOTES)[type] || null;
+  }
+
+  sectionSummary(type, language = 'fr') {
+    const entry = this.section(type);
+    if (!entry?.schema) return null;
+    const schema = entry.schema;
+    const policy = this.childPolicy(schema);
+    const notes = this.notes('section', type);
+    return {
+      type,
+      name: this.t(schema.name, language),
+      name_en: this.t(schema.name, 'en'),
+      description: notes?.fr || null,
+      use_for: notes?.use || null,
+      placement: this.describePlacement(schema, language),
+      presets: this.presetsOf(schema).map((preset) => ({ name: this.t(preset.name, language), name_en: this.t(preset.name, 'en'), category: this.t(preset.category, language) })),
+      children: policy.theme ? `tous les blocs publics du thème${policy.explicit.length ? ` + ${policy.explicit.join(', ')}` : ''}${policy.app ? ' + blocs d’applications' : ''}` : policy.explicit.join(', ') || 'aucun',
+      static_blocks: entry.statics,
+      limit: schema.limit || null,
+      settings_count: (schema.settings || []).filter((setting) => setting.id).length,
+    };
+  }
+
+  blockSummary(type, language = 'fr') {
+    const entry = this.block(type);
+    if (!entry?.schema) return null;
+    const schema = entry.schema;
+    const policy = this.childPolicy(schema);
+    const notes = this.notes('block', type);
+    return {
+      type,
+      name: this.t(schema.name, language),
+      name_en: this.t(schema.name, 'en'),
+      private: this.isPrivate(type),
+      description: notes?.fr || null,
+      presets: this.presetsOf(schema).map((preset) => this.t(preset.name, language)),
+      category: this.presetsOf(schema)[0] ? this.t(this.presetsOf(schema)[0].category, language) : null,
+      children: policy.theme ? 'tous les blocs publics' + (policy.explicit.length ? ` + ${policy.explicit.join(', ')}` : '') : policy.explicit.join(', ') || null,
+      static_blocks: entry.statics,
+      settings_count: (schema.settings || []).filter((setting) => setting.id).length,
+    };
+  }
+
+  // ---- search
+
+  searchIndex() {
+    if (this._index) return this._index;
+    const docs = [];
+    const push = (kind, key, title, texts) => docs.push({ kind, key, title, text: normalizeText(texts.filter(Boolean).join(' ')), titleText: normalizeText(title) });
+    for (const [type, entry] of this.theme.sections) {
+      if (!entry.schema) continue;
+      const notes = this.notes('section', type);
+      const presetNames = this.presetsOf(entry.schema).flatMap((preset) => [this.t(preset.name, 'fr'), this.t(preset.name, 'en')]);
+      push('section', type, `${this.t(entry.schema.name, 'fr')} (${type})`, [type, this.t(entry.schema.name, 'fr'), this.t(entry.schema.name, 'en'), notes?.fr, notes?.use, notes?.keywords, ...presetNames]);
+      for (const setting of entry.schema.settings || []) {
+        if (!setting.id) continue;
+        push('setting', `${type}.${setting.id}`, `section ${type} › ${setting.id}`, [setting.id, this.t(setting.label, 'fr'), this.t(setting.label, 'en'), this.t(setting.info, 'fr')]);
+      }
+    }
+    for (const [type, entry] of this.theme.blocks) {
+      if (!entry.schema) continue;
+      const notes = this.notes('block', type);
+      const presetNames = this.presetsOf(entry.schema).flatMap((preset) => [this.t(preset.name, 'fr'), this.t(preset.name, 'en')]);
+      push('block', type, `${this.t(entry.schema.name, 'fr')} (${type})`, [type, this.t(entry.schema.name, 'fr'), this.t(entry.schema.name, 'en'), notes?.fr, notes?.keywords, ...presetNames]);
+      for (const setting of entry.schema.settings || []) {
+        if (!setting.id) continue;
+        push('setting', `${type}.${setting.id}`, `bloc ${type} › ${setting.id}`, [setting.id, this.t(setting.label, 'fr'), this.t(setting.label, 'en'), this.t(setting.info, 'fr')]);
+      }
+    }
+    for (const setting of this.globalSettings) {
+      push('global_setting', setting.id, `réglage du thème › ${setting.id}`, [setting.id, this.t(setting.label, 'fr'), this.t(setting.label, 'en'), this.t(setting.info, 'fr'), this.t(setting.__group, 'fr')]);
+    }
+    this._index = docs;
+    return docs;
+  }
+
+  search(query, { kinds = null, limit = 25, extra = [] } = {}) {
+    const terms = normalizeText(query).split(' ').filter((term) => term.length > 1);
+    if (!terms.length) return [];
+    const docs = [...this.searchIndex(), ...extra];
+    const scored = [];
+    // Short queries need every word; longer ones tolerate one miss.
+    const needed = terms.length <= 2 ? terms.length : terms.length - 1;
+    for (const doc of docs) {
+      if (kinds && !kinds.includes(doc.kind)) continue;
+      let score = 0;
+      let matched = 0;
+      for (const term of terms) {
+        const stem = term.length > 4 ? term.slice(0, term.length - 1) : term;
+        if (doc.titleText.includes(stem)) score += 4;
+        if (doc.text.includes(stem)) {
+          score += 1;
+          matched += 1;
+        }
+      }
+      if (matched < needed) continue;
+      if (doc.kind === 'setting' || doc.kind === 'global_setting') score -= 1;
+      if (score > 0) scored.push({ ...doc, score });
+    }
+    return scored.sort((a, b) => b.score - a.score).slice(0, limit).map(({ kind, key, title, score }) => ({ kind, key, title, score: Math.round(score * 10) / 10 }));
+  }
+}