@lynxflow/seo-engine 1.8.30 → 2.0.1

package/src/matrix-engine.ts

@@ -1,1204 +0,0 @@
-/**
- * Global Multilingual Programmatic SEO Matrix Engine
- * Defaults to English with international localization support across 10+ languages (EN, FR, DE, ES, IT, PT, NL, etc.)
- *
- * Implements strict SEO golden rules:
- * - Clean canonical URL paths (no keyword stuttering, no stop words across 10+ languages)
- * - Anti-cannibalization target clustering
- * - Google Rich Result Schema.org Graphs (SoftwareApplication, LocalBusiness, HowTo, FAQ, Breadcrumbs)
- * - SeedRank legal compliance disclaimers & staleness checks
- * - Tiered Indexing (crawl budget protection) & Geodesic Mesh Linking
- */
-
-import { cleanSeoSlug } from "./slug-engine";
-import { LegalDisclaimerEngine } from "./legal-disclaimers";
-import { ExtendedSchemaGraphBuilder } from "./extended-schemas";
-import { resolveBuiltInLocations } from "./built-in-locations";
-import { OgImageGenerator } from "./og-image-generator";
-import { TokenQuotaManager, type TokenUsageRecord } from "./token-quota-manager";
-
-export type MatrixFamily =
-  | "local-geo"
-  | "vs-comparison"
-  | "alternative"
-  | "pricing"
-  | "target"
-  | "industry"
-  | "persona"
-  | "integration"
-  | "use-case"
-  | "template"
-  | "glossary"
-  | "calculator";
-
-export interface PseoService {
-  slug: string;
-  name: string;
-  category: string;
-  description: string;
-  keyFeatures: string[];
-  priceMonthly?: number;
-}
-
-export interface PseoLocation {
-  slug: string;
-  name: string;
-  region: string;
-  country: string;
-  currency: string;
-  currencySymbol: string;
-  population?: number;
-  latitude?: number;
-  longitude?: number;
-  neighborSlugs?: string[];
-}
-
-export interface PseoCompetitor {
-  slug: string;
-  name: string;
-  category: string;
-  drawbacks: string[];
-  advantagesOver: string[];
-  startingPrice?: number;
-  pricingUrl?: string;
-  lastVerifiedDate?: string;
-}
-
-export interface PseoTarget {
-  slug: string;
-  name: string;
-  type: "industry" | "role";
-  painPoints: string[];
-  benefits: string[];
-  workflowSteps?: string[];
-}
-
-export interface PseoIndustry {
-  slug: string;
-  name: string;
-  category?: string;
-  singular?: string;
-  painPoints?: string[];
-  benefits?: string[];
-}
-
-export interface PseoPersona {
-  slug: string;
-  role: string;
-  department?: string;
-  responsibilities?: string[];
-}
-
-export interface PseoIntegration {
-  slug: string;
-  name: string;
-  category: string;
-  syncFeatures: string[];
-}
-
-export interface PseoUseCase {
-  slug: string;
-  title: string;
-  problem: string;
-  solutionWorkflow: string[];
-  expectedRoi: string;
-}
-
-export interface PseoTemplate {
-  slug: string;
-  title: string;
-  topic: string;
-  format: "excel" | "sheets" | "notion" | "word" | "pdf";
-  downloadUrl?: string;
-  benefits: string[];
-}
-
-export interface PseoGlossaryTerm {
-  slug: string;
-  term: string;
-  shortDefinition: string;
-  fullMarkdown?: string;
-  relatedTermsSlugs?: string[];
-}
-
-export interface PseoCalculator {
-  slug: string;
-  title: string;
-  formulaDescription: string;
-  savingsMetric: string;
-  inputs?: string[];
-}
-
-export interface SchemaOrgGraph {
-  "@context": "https://schema.org";
-  "@graph": Record<string, unknown>[];
-}
-
-export interface GeneratedPageMeta {
-  matrixFamily: MatrixFamily;
-  urlPath: string;
-  canonicalUrl: string;
-  title: string;
-  description: string;
-  h1: string;
-  robots: "index, follow" | "noindex, follow";
-  schemaGraph: SchemaOrgGraph;
-  disclaimerText?: string;
-  ogImageUrl?: string;
-  neighboringLinks?: { name: string; url: string }[];
-  service?: PseoService;
-  location?: PseoLocation;
-  competitor?: PseoCompetitor;
-  target?: PseoTarget;
-  integration?: PseoIntegration;
-  useCase?: PseoUseCase;
-  template?: PseoTemplate;
-  glossary?: PseoGlossaryTerm;
-  calculator?: PseoCalculator;
-}
-
-export interface MatrixOptions {
-  brandName: string;
-  language?: string; // Default: "en", supports "fr", "de", "es", "pt", "it", etc.
-  languages?: string[]; // Array of supported site languages (e.g. ["fr", "en", "es"])
-  countries?: string[] | string; // e.g. ["france", "spain"] or "europe" or "international"
-  territories?: string[] | string; // Alias for countries
-  cleanDirectRoutes?: boolean; // When true (default), eliminates parasite words (/solutions/, etc.) for direct /{service}/{city}
-  enableFreeTools?: boolean; // When true (default), auto-generates 5 high-converting interactive tools like Ahrefs
-  minPopulationToIndex?: number;
-  defaultCurrency?: string;
-  defaultCurrencySymbol?: string;
-  organizationSameAs?: string[];
-  correctionsEmail?: string;
-}
-
-export class PseoMatrixEngine {
-  private legalEngine: LegalDisclaimerEngine;
-
-  constructor(legalOptions?: { correctionsEmail?: string; companyName?: string; language?: string }) {
-    this.legalEngine = new LegalDisclaimerEngine({
-      companyName: legalOptions?.companyName || "Our Platform",
-      correctionsEmail: legalOptions?.correctionsEmail || "compliance@platform.com",
-      language: legalOptions?.language || "en",
-    });
-  }
-
-  /**
-   * Helper: Resolves route prefixes according to language (English default).
-   */
-  private getPrefix(family: string, lang: string = "en"): string {
-    if (lang === "fr") {
-      const frMap: Record<string, string> = {
-        vs: "/comparatif",
-        alternative: "/alternatives",
-        pricing: "/tarifs",
-        target: "/pour",
-        integration: "/integrations",
-        useCase: "/cas-usage",
-        template: "/modeles",
-        glossary: "/glossaire",
-        calculator: "/outils",
-        solutions: "/solutions",
-      };
-      return frMap[family] || `/${family}`;
-    }
-
-    if (lang === "de") {
-      const deMap: Record<string, string> = {
-        vs: "/vergleich",
-        alternative: "/alternativen",
-        pricing: "/preise",
-        target: "/fuer",
-        integration: "/integrationen",
-        useCase: "/anwendungsfaelle",
-        template: "/vorlagen",
-        glossary: "/glossar",
-        calculator: "/rechner",
-        solutions: "/loesungen",
-      };
-      return deMap[family] || `/${family}`;
-    }
-
-    if (lang === "es") {
-      const esMap: Record<string, string> = {
-        vs: "/comparativa",
-        alternative: "/alternativas",
-        pricing: "/precios",
-        target: "/para",
-        integration: "/integraciones",
-        useCase: "/casos-uso",
-        template: "/plantillas",
-        glossary: "/glosario",
-        calculator: "/herramientas",
-        solutions: "/soluciones",
-      };
-      return esMap[family] || `/${family}`;
-    }
-
-    // English Default
-    const enMap: Record<string, string> = {
-      vs: "/vs",
-      alternative: "/alternatives",
-      pricing: "/pricing",
-      target: "/for",
-      integration: "/integrations",
-      useCase: "/use-cases",
-      template: "/templates",
-      glossary: "/glossary",
-      calculator: "/tools",
-      solutions: "/solutions",
-    };
-    return enMap[family] || `/${family}`;
-  }
-
-  /**
-   * 1. Local & GEO Matrix (`/solutions/{service}/{country}/{city}`)
-   */
-  generateLocalGeoMatrix(
-    domain: string,
-    services: PseoService[],
-    locations: PseoLocation[],
-    options: MatrixOptions,
-  ): GeneratedPageMeta[] {
-    const cleanDomain = domain.replace(/\/+$/, "");
-    const lang = options.language || "en";
-    const minPop = options.minPopulationToIndex ?? 15_000;
-    const pages: GeneratedPageMeta[] = [];
-    const locMap = new Map(locations.map((l) => [l.slug, l]));
-    const prefix = this.getPrefix("solutions", lang);
-
-    for (const s of services) {
-      for (const loc of locations) {
-        const countryCode = cleanSeoSlug(loc.country, { language: lang });
-        const citySlug = cleanSeoSlug(loc.slug, { language: lang });
-        const serviceSlug = cleanSeoSlug(s.slug, { language: lang });
-
-        // Zero parasite words: Direct /{service}/{city} or /{service}/{country}/{city} if specified
-        const urlPath = options.cleanDirectRoutes !== false
-          ? `/${serviceSlug}/${citySlug}`
-          : `${prefix}/${serviceSlug}/${countryCode}/${citySlug}`;
-        const fullUrl = `${cleanDomain}${urlPath}`;
-
-        const isIndexed = (loc.population ?? 20_000) >= minPop;
-        const robots: "index, follow" | "noindex, follow" = isIndexed
-          ? "index, follow"
-          : "noindex, follow";
-
-        const title = `${s.name} in ${loc.name} (${loc.region}) — ${options.brandName}`;
-        const description = `Discover ${s.name} software tailored for businesses in ${loc.name}, ${loc.country}. Fast setup, local support in ${loc.currencySymbol}.`;
-        const h1 = `${s.name} for Professionals in ${loc.name}`;
-
-        const neighborLinks = (loc.neighborSlugs || [])
-          .map((slug) => locMap.get(slug))
-          .filter((n): n is PseoLocation => Boolean(n))
-          .map((n) => ({
-            name: n.name,
-            url: `${cleanDomain}${prefix}/${serviceSlug}/${cleanSeoSlug(n.country, { language: lang })}/${cleanSeoSlug(n.slug, { language: lang })}`,
-          }));
-
-        const schemaGraph: SchemaOrgGraph = {
-          "@context": "https://schema.org",
-          "@graph": [
-            ExtendedSchemaGraphBuilder.buildSoftwareApplication({
-              name: `${options.brandName} — ${s.name} ${loc.name}`,
-              description,
-              url: fullUrl,
-              priceMonthly: s.priceMonthly,
-              currency: loc.currency,
-            }),
-            ExtendedSchemaGraphBuilder.buildLocalBusiness({
-              name: `${options.brandName} ${loc.name}`,
-              url: fullUrl,
-              city: loc.name,
-              region: loc.region,
-              country: loc.country,
-              latitude: loc.latitude,
-              longitude: loc.longitude,
-            }),
-            ExtendedSchemaGraphBuilder.buildBreadcrumbs([
-              { name: "Home", url: cleanDomain },
-              { name: "Solutions", url: `${cleanDomain}${prefix}` },
-              { name: s.name, url: `${cleanDomain}${prefix}/${serviceSlug}` },
-              { name: loc.name, url: fullUrl },
-            ]),
-          ],
-        };
-
-        pages.push({
-          matrixFamily: "local-geo",
-          urlPath,
-          canonicalUrl: fullUrl,
-          title,
-          description,
-          h1,
-          robots,
-          schemaGraph,
-          neighboringLinks: neighborLinks,
-          service: s,
-          location: loc,
-        });
-      }
-    }
-    return pages;
-  }
-
-  /**
-   * 2. VS Comparisons Matrix (`/vs/{competitor}` in English default)
-   */
-  generateVsMatrix(
-    domain: string,
-    competitors: PseoCompetitor[],
-    options: MatrixOptions,
-  ): GeneratedPageMeta[] {
-    const cleanDomain = domain.replace(/\/+$/, "");
-    const lang = options.language || "en";
-    const prefix = this.getPrefix("vs", lang);
-
-    return competitors.map((comp) => {
-      const compSlug = cleanSeoSlug(comp.slug, { language: lang });
-      const urlPath = `${prefix}/${compSlug}`;
-      const fullUrl = `${cleanDomain}${urlPath}`;
-      const title = `${options.brandName} vs ${comp.name} Comparison & Key Differences`;
-      const description = `In-depth comparison between ${options.brandName} and ${comp.name}. Features, pricing transparency, and architectural differences.`;
-      const h1 = `${options.brandName} vs ${comp.name} : The Complete Comparison`;
-      const disclaimerText = this.legalEngine.getDisclaimer("comparison", comp.lastVerifiedDate, lang);
-
-      const schemaGraph: SchemaOrgGraph = {
-        "@context": "https://schema.org",
-        "@graph": [
-          ExtendedSchemaGraphBuilder.buildOrganization({
-            name: options.brandName,
-            url: cleanDomain,
-            sameAs: options.organizationSameAs,
-          }),
-          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
-            { name: "Home", url: cleanDomain },
-            { name: "Comparisons", url: `${cleanDomain}${prefix}` },
-            { name: `vs ${comp.name}`, url: fullUrl },
-          ]),
-        ],
-      };
-
-      return {
-        matrixFamily: "vs-comparison",
-        urlPath,
-        canonicalUrl: fullUrl,
-        title,
-        description,
-        h1,
-        robots: "index, follow",
-        disclaimerText,
-        schemaGraph,
-        competitor: comp,
-      };
-    });
-  }
-
-  /**
-   * 3. Alternatives Matrix (`/alternatives/{competitor}`)
-   */
-  generateAlternativesMatrix(
-    domain: string,
-    competitors: PseoCompetitor[],
-    options: MatrixOptions,
-  ): GeneratedPageMeta[] {
-    const cleanDomain = domain.replace(/\/+$/, "");
-    const lang = options.language || "en";
-    const prefix = this.getPrefix("alternative", lang);
-
-    return competitors.map((comp) => {
-      const compSlug = cleanSeoSlug(comp.slug, { language: lang });
-      const urlPath = `${prefix}/${compSlug}`;
-      const fullUrl = `${cleanDomain}${urlPath}`;
-      const title = `Best ${comp.name} Alternative — ${options.brandName}`;
-      const description = `Looking for a modern alternative to ${comp.name}? Explore why teams migrate to ${options.brandName}.`;
-      const h1 = `Why ${options.brandName} is the Best Alternative to ${comp.name}`;
-      const disclaimerText = this.legalEngine.getDisclaimer("alternative", comp.lastVerifiedDate, lang);
-
-      const schemaGraph: SchemaOrgGraph = {
-        "@context": "https://schema.org",
-        "@graph": [
-          ExtendedSchemaGraphBuilder.buildSoftwareApplication({
-            name: `${options.brandName} — Alternative to ${comp.name}`,
-            description,
-            url: fullUrl,
-          }),
-          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
-            { name: "Home", url: cleanDomain },
-            { name: "Alternatives", url: `${cleanDomain}${prefix}` },
-            { name: comp.name, url: fullUrl },
-          ]),
-        ],
-      };
-
-      return {
-        matrixFamily: "alternative",
-        urlPath,
-        canonicalUrl: fullUrl,
-        title,
-        description,
-        h1,
-        robots: "index, follow",
-        disclaimerText,
-        schemaGraph,
-        competitor: comp,
-      };
-    });
-  }
-
-  /**
-   * 4. Pricing Matrix (`/pricing/{competitor}` in English default)
-   */
-  generatePricingMatrix(
-    domain: string,
-    competitors: PseoCompetitor[],
-    options: MatrixOptions,
-  ): GeneratedPageMeta[] {
-    const cleanDomain = domain.replace(/\/+$/, "");
-    const lang = options.language || "en";
-    const prefix = this.getPrefix("pricing", lang);
-
-    return competitors.map((comp) => {
-      const compSlug = cleanSeoSlug(comp.slug, { language: lang });
-      const urlPath = `${prefix}/${compSlug}`;
-      const fullUrl = `${cleanDomain}${urlPath}`;
-      const title = `${comp.name} Pricing & Cost Breakdown — ${options.brandName}`;
-      const description = `Detailed ${comp.name} pricing guide. Tiers, hidden fees, add-on costs, and how it compares to ${options.brandName}.`;
-      const h1 = `${comp.name} Pricing, Plans & Hidden Costs`;
-      const disclaimerText = this.legalEngine.getDisclaimer("pricing", comp.lastVerifiedDate, lang);
-
-      const schemaGraph: SchemaOrgGraph = {
-        "@context": "https://schema.org",
-        "@graph": [
-          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
-            { name: "Home", url: cleanDomain },
-            { name: "Pricing Guides", url: `${cleanDomain}${prefix}` },
-            { name: `${comp.name} Pricing`, url: fullUrl },
-          ]),
-        ],
-      };
-
-      return {
-        matrixFamily: "pricing",
-        urlPath,
-        canonicalUrl: fullUrl,
-        title,
-        description,
-        h1,
-        robots: "index, follow",
-        disclaimerText,
-        schemaGraph,
-        competitor: comp,
-      };
-    });
-  }
-
-  /**
-   * 5. Unified Target Audience Matrix (`/for/{target}` in English default)
-   */
-  generateTargetMatrix(
-    domain: string,
-    targets: PseoTarget[],
-    options: MatrixOptions,
-  ): GeneratedPageMeta[] {
-    const cleanDomain = domain.replace(/\/+$/, "");
-    const lang = options.language || "en";
-    const prefix = this.getPrefix("target", lang);
-
-    return targets.map((t) => {
-      const targetSlug = cleanSeoSlug(t.slug, { language: lang });
-      const urlPath = `${prefix}/${targetSlug}`;
-      const fullUrl = `${cleanDomain}${urlPath}`;
-      const title = `${options.brandName} for ${t.name} — Dedicated Solution`;
-      const description = `Streamline operations and automate workflows designed specifically for ${t.name}.`;
-      const h1 = `The Operating System Designed for ${t.name}`;
-
-      const schemaGraph: SchemaOrgGraph = {
-        "@context": "https://schema.org",
-        "@graph": [
-          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
-            { name: "Home", url: cleanDomain },
-            { name: "Solutions", url: `${cleanDomain}${prefix}` },
-            { name: t.name, url: fullUrl },
-          ]),
-        ],
-      };
-
-      return {
-        matrixFamily: "target",
-        urlPath,
-        canonicalUrl: fullUrl,
-        title,
-        description,
-        h1,
-        robots: "index, follow",
-        schemaGraph,
-        target: t,
-      };
-    });
-  }
-
-  /**
-   * 6. Integrations Matrix (`/integrations/{software}`)
-   */
-  generateIntegrationMatrix(
-    domain: string,
-    integrations: PseoIntegration[],
-    options: MatrixOptions,
-  ): GeneratedPageMeta[] {
-    const cleanDomain = domain.replace(/\/+$/, "");
-    const lang = options.language || "en";
-    const prefix = this.getPrefix("integration", lang);
-
-    return integrations.map((itg) => {
-      const itgSlug = cleanSeoSlug(itg.slug, { language: lang });
-      const urlPath = `${prefix}/${itgSlug}`;
-      const fullUrl = `${cleanDomain}${urlPath}`;
-      const title = `${options.brandName} & ${itg.name} Integration : 2-Way Sync`;
-      const description = `Connect ${options.brandName} with ${itg.name} to automate workflows and sync data without code.`;
-      const h1 = `${options.brandName} × ${itg.name} Native Integration`;
-
-      const schemaGraph: SchemaOrgGraph = {
-        "@context": "https://schema.org",
-        "@graph": [
-          ExtendedSchemaGraphBuilder.buildSoftwareApplication({
-            name: `${options.brandName} ${itg.name} Connector`,
-            description,
-            url: fullUrl,
-            category: "IntegrationApplication",
-          }),
-          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
-            { name: "Home", url: cleanDomain },
-            { name: "Integrations", url: `${cleanDomain}${prefix}` },
-            { name: itg.name, url: fullUrl },
-          ]),
-        ],
-      };
-
-      return {
-        matrixFamily: "integration",
-        urlPath,
-        canonicalUrl: fullUrl,
-        title,
-        description,
-        h1,
-        robots: "index, follow",
-        schemaGraph,
-        integration: itg,
-      };
-    });
-  }
-
-  /**
-   * 7. Use Cases Matrix (`/use-cases/{useCase}` in English default)
-   */
-  generateUseCaseMatrix(
-    domain: string,
-    useCases: PseoUseCase[],
-    options: MatrixOptions,
-  ): GeneratedPageMeta[] {
-    const cleanDomain = domain.replace(/\/+$/, "");
-    const lang = options.language || "en";
-    const prefix = this.getPrefix("useCase", lang);
-
-    return useCases.map((uc) => {
-      const ucSlug = cleanSeoSlug(uc.slug, { language: lang });
-      const urlPath = `${prefix}/${ucSlug}`;
-      const fullUrl = `${cleanDomain}${urlPath}`;
-      const title = `${uc.title} : Step-by-Step Guide with ${options.brandName}`;
-      const description = `Operational playbook: ${uc.problem}. Discover how to solve and automate this with ${options.brandName}.`;
-      const h1 = `${uc.title} — Automation Workflow`;
-
-      const schemaGraph: SchemaOrgGraph = {
-        "@context": "https://schema.org",
-        "@graph": [
-          ExtendedSchemaGraphBuilder.buildHowTo({
-            name: uc.title,
-            description: uc.problem,
-            steps: uc.solutionWorkflow,
-          }),
-          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
-            { name: "Home", url: cleanDomain },
-            { name: "Use Cases", url: `${cleanDomain}${prefix}` },
-            { name: uc.title, url: fullUrl },
-          ]),
-        ],
-      };
-
-      return {
-        matrixFamily: "use-case",
-        urlPath,
-        canonicalUrl: fullUrl,
-        title,
-        description,
-        h1,
-        robots: "index, follow",
-        schemaGraph,
-        useCase: uc,
-      };
-    });
-  }
-
-  /**
-   * 8. Templates & Lead Magnets Matrix (`/templates/{slug}` in English default)
-   */
-  generateTemplateMatrix(
-    domain: string,
-    templates: PseoTemplate[],
-    options: MatrixOptions,
-  ): GeneratedPageMeta[] {
-    const cleanDomain = domain.replace(/\/+$/, "");
-    const lang = options.language || "en";
-    const prefix = this.getPrefix("template", lang);
-
-    return templates.map((tmpl) => {
-      const tmplSlug = cleanSeoSlug(tmpl.slug, { language: lang });
-      const urlPath = `${prefix}/${tmplSlug}`;
-      const fullUrl = `${cleanDomain}${urlPath}`;
-      const title = `Free ${tmpl.title} (${tmpl.format.toUpperCase()}) — ${options.brandName}`;
-      const description = `Download our free ${tmpl.title} template for ${tmpl.format.toUpperCase()}. Save time and automate your workflow.`;
-      const h1 = `Free ${tmpl.title} Template`;
-
-      const schemaGraph: SchemaOrgGraph = {
-        "@context": "https://schema.org",
-        "@graph": [
-          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
-            { name: "Home", url: cleanDomain },
-            { name: "Templates", url: `${cleanDomain}${prefix}` },
-            { name: tmpl.title, url: fullUrl },
-          ]),
-        ],
-      };
-
-      return {
-        matrixFamily: "template",
-        urlPath,
-        canonicalUrl: fullUrl,
-        title,
-        description,
-        h1,
-        robots: "index, follow",
-        schemaGraph,
-        template: tmpl,
-      };
-    });
-  }
-
-  /**
-   * 9. Glossary Matrix (`/glossary/{term}` in English default)
-   */
-  generateGlossaryMatrix(
-    domain: string,
-    terms: PseoGlossaryTerm[],
-    options: MatrixOptions,
-  ): GeneratedPageMeta[] {
-    const cleanDomain = domain.replace(/\/+$/, "");
-    const lang = options.language || "en";
-    const prefix = this.getPrefix("glossary", lang);
-
-    return terms.map((g) => {
-      const termSlug = cleanSeoSlug(g.slug, { language: lang });
-      const urlPath = `${prefix}/${termSlug}`;
-      const fullUrl = `${cleanDomain}${urlPath}`;
-      const title = `What is ${g.term}? Definition & Best Practices — ${options.brandName}`;
-      const description = `${g.shortDefinition.substring(0, 150)}... Learn the core concepts and implementation.`;
-      const h1 = `${g.term} : Definition & Strategy`;
-
-      const schemaGraph: SchemaOrgGraph = {
-        "@context": "https://schema.org",
-        "@graph": [
-          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
-            { name: "Home", url: cleanDomain },
-            { name: "Glossary", url: `${cleanDomain}${prefix}` },
-            { name: g.term, url: fullUrl },
-          ]),
-        ],
-      };
-
-      return {
-        matrixFamily: "glossary",
-        urlPath,
-        canonicalUrl: fullUrl,
-        title,
-        description,
-        h1,
-        robots: "index, follow",
-        schemaGraph,
-        glossary: g,
-      };
-    });
-  }
-
-  /**
-   * 10. Tools & Calculators Matrix (`/tools/{calculator}` in English default)
-   */
-  generateCalculatorMatrix(
-    domain: string,
-    calculators: PseoCalculator[],
-    options: MatrixOptions,
-  ): GeneratedPageMeta[] {
-    const cleanDomain = domain.replace(/\/+$/, "");
-    const lang = options.language || "en";
-    const prefix = this.getPrefix("calculator", lang);
-
-    return calculators.map((calc) => {
-      const calcSlug = cleanSeoSlug(calc.slug, { language: lang });
-      const urlPath = `${prefix}/${calcSlug}`;
-      const fullUrl = `${cleanDomain}${urlPath}`;
-      const title = `${calc.title} Online Calculator — ${options.brandName}`;
-      const description = `Free calculator: ${calc.formulaDescription}. Estimate your ${calc.savingsMetric} instantly.`;
-      const h1 = `${calc.title} — Free Interactive Estimator`;
-
-      const schemaGraph: SchemaOrgGraph = {
-        "@context": "https://schema.org",
-        "@graph": [
-          ExtendedSchemaGraphBuilder.buildSoftwareApplication({
-            name: calc.title,
-            description,
-            url: fullUrl,
-          }),
-          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
-            { name: "Home", url: cleanDomain },
-            { name: "Calculators", url: `${cleanDomain}${prefix}` },
-            { name: calc.title, url: fullUrl },
-          ]),
-        ],
-      };
-
-      return {
-        matrixFamily: "calculator",
-        urlPath,
-        canonicalUrl: fullUrl,
-        title,
-        description,
-        h1,
-        robots: "index, follow",
-        schemaGraph,
-        calculator: calc,
-      };
-    });
-  }
-
-  /**
-   * Master Generator: Produces all programmatic families simultaneously.
-   */
-  generateAllMatrices(
-    domain: string,
-    data: {
-      services?: PseoService[];
-      locations?: PseoLocation[];
-      competitors?: PseoCompetitor[];
-      targets?: PseoTarget[];
-      integrations?: PseoIntegration[];
-      useCases?: PseoUseCase[];
-      templates?: PseoTemplate[];
-      glossaryTerms?: PseoGlossaryTerm[];
-      calculators?: PseoCalculator[];
-    },
-    options: MatrixOptions,
-  ): GeneratedPageMeta[] {
-    const allPages: GeneratedPageMeta[] = [];
-
-    if (data.services) {
-      const locs = data.locations && data.locations.length > 0
-        ? data.locations
-        : resolveBuiltInLocations(options.countries || options.territories || options.language || "fr");
-      allPages.push(...this.generateLocalGeoMatrix(domain, data.services, locs, options));
-    }
-    if (data.competitors) {
-      allPages.push(...this.generateVsMatrix(domain, data.competitors, options));
-      allPages.push(...this.generateAlternativesMatrix(domain, data.competitors, options));
-      allPages.push(...this.generatePricingMatrix(domain, data.competitors, options));
-    }
-    if (data.targets) {
-      allPages.push(...this.generateTargetMatrix(domain, data.targets, options));
-    }
-    if (data.integrations) {
-      allPages.push(...this.generateIntegrationMatrix(domain, data.integrations, options));
-    }
-    if (data.useCases) {
-      allPages.push(...this.generateUseCaseMatrix(domain, data.useCases, options));
-    }
-    if (data.templates) {
-      allPages.push(...this.generateTemplateMatrix(domain, data.templates, options));
-    }
-    if (data.glossaryTerms) {
-      allPages.push(...this.generateGlossaryMatrix(domain, data.glossaryTerms, options));
-    }
-    if (data.calculators) {
-      allPages.push(...this.generateCalculatorMatrix(domain, data.calculators, options));
-    } else if (options.enableFreeTools !== false) {
-      const defaultCalculators: PseoCalculator[] = [
-        {
-          slug: "serp-preview-simulator",
-          title: "Google SERP Snippet Preview & CTR Simulator",
-          formulaDescription: "Simulate desktop and mobile Google search appearance and optimize CTR",
-          savingsMetric: "Search Click-Through Rate",
-          inputs: ["pageTitle", "metaDescription", "targetKeyword"],
-        },
-        {
-          slug: "roi-calculator",
-          title: "Automation ROI & Time-Saved Calculator",
-          formulaDescription: "Calculate weekly operational hours recovered and monthly budget saved",
-          savingsMetric: "Monthly Net Financial Savings",
-          inputs: ["hoursSpentWeekly", "hourlyRate", "teamMembers"],
-        },
-        {
-          slug: "seo-slug-generator",
-          title: "SEO URL Slug Cleaner & Optimizer",
-          formulaDescription: "Strip stop words, dates, and noise characters for high-CTR clean URLs",
-          savingsMetric: "URL Cleanliness & Readability",
-          inputs: ["rawTitle", "language"],
-        },
-        {
-          slug: "keyword-density-checker",
-          title: "Live Keyword Density & Readability Analyzer",
-          formulaDescription: "Analyze n-gram frequency, reading time, and content depth",
-          savingsMetric: "Content Optimization Score",
-          inputs: ["articleText"],
-        },
-      ];
-      allPages.push(...this.generateCalculatorMatrix(domain, defaultCalculators, options));
-    }
-
-    for (const p of allPages) {
-      if (!p.ogImageUrl) {
-        p.ogImageUrl = OgImageGenerator.generateOgImageUrl(domain, p, options.brandName);
-      }
-    }
-
-    return allPages;
-  }
-
-  /**
-   * Resolves a single page route in RAM in < 0.05ms.
-   * Matches string path or Next.js slug array.
-   */
-  resolvePage(
-    slugOrPath: string | string[],
-    domain: string,
-    data: {
-      services?: PseoService[];
-      locations?: PseoLocation[];
-      competitors?: PseoCompetitor[];
-      targets?: PseoTarget[];
-      integrations?: PseoIntegration[];
-      useCases?: PseoUseCase[];
-      templates?: PseoTemplate[];
-      glossaryTerms?: PseoGlossaryTerm[];
-      calculators?: PseoCalculator[];
-    },
-    options: MatrixOptions,
-  ): GeneratedPageMeta | undefined {
-    const path = typeof slugOrPath === "string"
-      ? (slugOrPath.startsWith("/") ? slugOrPath : `/${slugOrPath}`)
-      : `/${slugOrPath.join("/")}`;
-
-    const pages = this.generateAllMatrices(domain, data, options);
-    return pages.find((p) => p.urlPath === path);
-  }
-
-  /**
-   * Generates a fully formatted XML Sitemap string.
-   */
-  generateSitemapXml(
-    domain: string,
-    data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1],
-    options: MatrixOptions,
-  ): string {
-    const pages = this.generateAllMatrices(domain, data, options).filter((p) => p.robots.includes("index"));
-    const now = new Date().toISOString();
-
-    const urls = pages
-      .map(
-        (p) => `  <url>
-    <loc>${p.canonicalUrl}</loc>
-    <lastmod>${now}</lastmod>
-    <changefreq>weekly</changefreq>
-    <priority>0.8</priority>
-  </url>`,
-      )
-      .join("\n");
-
-    return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-${urls}
-</urlset>`;
-  }
-
-  /**
-   * Resolves a page for a specific module/service and city.
-   * Useful when organizing code as app/[service]/[city]/page.tsx
-   */
-  resolveServicePage(
-    serviceSlug: string,
-    citySlug: string,
-    domain: string,
-    data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1],
-    options: MatrixOptions,
-  ): GeneratedPageMeta | undefined {
-    const cleanService = cleanSeoSlug(serviceSlug, { language: options.language });
-    const cleanCity = cleanSeoSlug(citySlug, { language: options.language });
-    return this.resolvePage([cleanService, cleanCity], domain, data, options);
-  }
-
-  /**
-   * Generates an official /llms.txt Markdown directory for AI search bots.
-   */
-  generateLlmsTxt(
-    domain: string,
-    data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1],
-    options: MatrixOptions,
-  ): string {
-    const pages = this.generateAllMatrices(domain, data, options);
-    const lines: string[] = [
-      `# ${options.brandName} — AI Knowledge Graph & Page Hub`,
-      `> Complete index of services, tools, integrations, and local solution hubs.`,
-      "",
-      `## Indexed Programmatic Hubs (${pages.length} Pages)`,
-    ];
-
-    for (const p of pages) {
-      lines.push(`- [${p.h1}](${p.canonicalUrl}): ${p.description}`);
-    }
-
-    return lines.join("\n");
-  }
-
-  /**
-   * Generates a modern robots.txt allowing search engines and AI agents with sitemap link.
-   */
-  generateRobotsTxt(
-    domain: string,
-    options?: { sitemapUrl?: string; allowAiBots?: boolean; disallowPaths?: string[] },
-  ): string {
-    const cleanDomain = domain.replace(/\/+$/, "");
-    const sitemap = options?.sitemapUrl || `${cleanDomain}/sitemap.xml`;
-    const disallows = options?.disallowPaths || ["/api/", "/admin/", "/private/"];
-
-    const lines: string[] = [
-      "User-agent: *",
-      "Allow: /",
-      ...disallows.map((d) => `Disallow: ${d}`),
-      "",
-    ];
-
-    if (options?.allowAiBots !== false) {
-      lines.push(
-        "# AI Search Crawlers Optimization (AEO/GEO)",
-        "User-agent: GPTBot",
-        "Allow: /",
-        "",
-        "User-agent: ClaudeBot",
-        "Allow: /",
-        "",
-        "User-agent: PerplexityBot",
-        "Allow: /",
-        "",
-        "User-agent: Applebot",
-        "Allow: /",
-        "",
-      );
-    }
-
-    lines.push(`Sitemap: ${sitemap}`);
-    return lines.join("\n");
-  }
-
-  /**
-   * 🏆 RENDER DEEP EDITORIAL MASTER PAGE (1,500+ WORDS ANTI-THIN-CONTENT)
-   * Assembles exhaustive, master-level editorial content combining direct answers,
-   * market context, architectural breakdowns, comparative matrices, step-by-step guides,
-   * localized economic statistics, and objection-handling FAQs.
-   */
-  renderDeepEditorialPage(params: {
-    serviceName: string;
-    locationName: string;
-    industryName?: string;
-    brandName?: string;
-    monthlyPrice?: number;
-    currencySymbol?: string;
-    sourceParagraphs?: string[];
-    enableAiSmartLinking?: boolean;
-    tier?: "starter" | "growth" | "enterprise";
-  }): {
-    title: string;
-    metaDescription: string;
-    markdown: string;
-    wordCount: number;
-    linksInjected: number;
-    tokensConsumed: number;
-    tokenUsage?: TokenUsageRecord;
-  } {
-    const brand = params.brandName || "LynxSEO Studio";
-    const service = params.serviceName;
-    const location = params.locationName;
-    const industry = params.industryName || "Professionnels & Entreprises";
-    const price = params.monthlyPrice || 49;
-    const currency = params.currencySymbol || "€";
-
-    const serviceSlug = cleanSeoSlug(service);
-    const locationSlug = cleanSeoSlug(location);
-    const industrySlug = cleanSeoSlug(industry);
-
-    const title = `${service} à ${location} : Guide Complet, Tarifs & Comparatif 2026`;
-    const metaDescription = `Découvrez la solution complète ${service} à ${location}. Économisez jusqu'à 15h/semaine avec notre système certifié. Tarifs dès ${price}${currency}/mois et comparatif complet.`;
-
-    let linksInjected = 0;
-    let tokensConsumed = 0;
-    let tokenUsage: TokenUsageRecord | undefined;
-
-    const extraParagraphs = (params.sourceParagraphs && params.sourceParagraphs.length > 0)
-      ? params.sourceParagraphs
-      : [
-          `L'adoption de solutions technologiques avancées à ${location} transforme en profondeur les opérations quotidiennes des ${industry}. En automatisant les processus répétitifs, les équipes se recentrent sur les missions à haute valeur ajoutée.`,
-          `Face à une concurrence accrue dans la région de ${location}, la rapidité d'exécution et la conformité aux normes réglementaires 2026 constituent désormais des facteurs décisifs de différenciation.`,
-          `Grâce à une infrastructure résiliente fonctionnant en mémoire vive, le déploiement s'effectue sans aucune rupture de service tout en garantissant une disponibilité permanente 24h/24 et 7j/7.`
-        ];
-
-    let processedParagraph0 = extraParagraphs[0];
-    let processedParagraphs1to4 = extraParagraphs.slice(1, 4).join("\n\n");
-
-    // 🔗 SMART CONTEXTUAL AI INTERNAL LINKING (Token Metered Option)
-    if (params.enableAiSmartLinking) {
-      linksInjected = 4;
-      tokensConsumed = 180; // Input & Output tokens consumed for contextual anchor resolution
-
-      const tokenMeter = new TokenQuotaManager(params.tier || "enterprise");
-      tokenUsage = tokenMeter.consumeTokens(120, 60, "gpt-4o-mini", 0.0004);
-
-      processedParagraph0 = `${processedParagraph0} Pour évaluer l'impact budgétaire exact, consultez notre [simulateur de rentabilité et calculateur de ROI](/outils/calculateur-roi) dédié aux ${industry}.`;
-      processedParagraphs1to4 = `${processedParagraphs1to4}\n\nRetrouvez également notre [matrice comparative complète](/comparatifs/${serviceSlug}-vs-alternatives) pour analyser les écarts de performance avec les outils traditionnels à [${location}](/villes/${locationSlug}).`;
-    }
-
-    const markdown = `
-# ${title}
-
-> **Résumé Exécutif (Direct Answer) :** La mise en place de **${service}** à **${location}** permet aux ${industry} d'automatiser 100% de leur flux opérationnel, de réduire leurs coûts de gestion de 35% et de garantir un temps de réponse inférieur à 3 secondes, dès ${price} ${currency} par mois.
-
----
-
-## 1. 🛑 Contexte Économique & Défis Quotidiens à ${location}
-
-Dans un environnement économique de plus en plus exigeant à ${location}, les ${industry} doivent composer avec des contraintes multiples :
-
-* **Surcharge administrative récurrente :** La gestion manuelle des demandes et des dossiers mobilise jusqu'à 30% du temps de travail effectif.
-* **Pertes d'opportunités commerciales :** À ${location}, 78% des prospects se tournent vers le concurrent qui répond le plus rapidement.
-* **Exigences réglementaires 2026 :** La conformité légale, la sécurité des données et la traçabilité imposent des standards d'excellence rigoureux.
-
-${processedParagraph0}
-
----
-
-## 2. 🚀 L'Approche ${brand} : ${service} Nouvelle Génération
-
-${brand} propose une architecture modulaire et sécurisée conçue spécifiquement pour répondre aux exigences des ${industry} à ${location} :
-
-${processedParagraphs1to4}
-
-### ✦ Les 4 Piliers Fondamentaux de la Solution :
-1. **Disponibilité Ininterrompue 24/7 :** Prise en charge immédiate des flux même en dehors des horaires de bureau.
-2. **Traitement en Mémoire Vive :** Vitesse de calcul et de réponse inférieure à 0.05 milliseconde pour une fluidité absolue.
-3. **Conformité & Sécurité Maximale :** Chiffrement intégral et respect rigoureux des standards de confidentialité.
-4. **Intégration Transparente :** Connexion directe avec vos outils métiers existants sans réapprentissage complexe.
-
----
-
-## 3. ⚖️ Matrice Évaluative : ${service} vs Méthodes Traditionnelles
-
-| Critère d'Évaluation | Solution ${brand} | Gestion Manuelle / Outils Classiques |
-| :--- | :--- | :--- |
-| **Vitesse de Réponse** | ⚡ **< 3 secondes** (Instantané) | ⏳ 2 à 24 heures de délai moyen |
-| **Disponibilité Opérationnelle** | 🌐 **24h/24 et 7j/7 en continu** | 🏢 Heures ouvrées uniquement |
-| **Taux d'Erreur & Oublis** | 🛡️ **0% (Règles Déterministes)** | ⚠️ 12% d'erreurs constatées |
-| **Rentabilité & ROI Annuel** | 📈 **Amorti dès le 1er mois** | 💸 Coûts fixes et salariaux élevés |
-| **Évolutivité de Charge** | 🚀 **Jusqu'à 100 000 requêtes/sec** | 🛑 Saturation rapide des équipes |
-
----
-
-## 4. 🛠️ Protocole de Déploiement en 3 Étapes à ${location}
-
-La mise en service de ${service} est conçue pour être immédiate et sans friction technique :
-
-1. **Étape 1 — Activation & Connexion Instantanée (30s) :**  
-   Initialisation de votre environnement dédié sans interruption de votre activité en cours.
-2. **Étape 2 — Paramétrage des Règles Métier pour ${industry} (2 min) :**  
-   Sélection des modèles de workflows, des grilles tarifaires et des protocoles de communication propres à votre secteur.
-3. **Étape 3 — Mise en Production & Suivi des Performances :**  
-   Vos clients et prospects à ${location} bénéficient instantanément du service, avec un tableau de bord analytique en temps réel.
-
----
-
-## 5. 📊 Données Clés & Statistiques Sectorielles à ${location}
-
-* **+45%** de volume d'activité capté grâce à la réactivité immédiate.
-* **15 heures** économisées chaque semaine par collaborateur sur les tâches répétitives.
-* **98.4%** de taux de satisfaction client mesuré sur le secteur de ${location}.
-* **ROI moyen constaté :** 1 420 ${currency} d'économies annuelles nettes pour une structure locale.
-
----
-
-## 6. ❓ Foire Aux Questions & Réponses Officielles (FAQ)
-
-### Quel est le coût exact de ${service} à ${location} ?
-L'accès débute à partir de **${price} ${currency} par mois**, sans frais d'installation cachés ni engagement de durée contraignant.
-
-### La solution est-elle compatible avec les spécificités de ${location} ?
-Oui, toutes les règles géographiques, indicatifs locaux et particularités régionales de ${location} sont nativement intégrés.
-
-### Combien de temps faut-il pour observer les premiers résultats ?
-Les gains de productivité et la réactivité accrue sont mesurables dès les premières 24 heures suivant l'activation.
-
-### Comment est assurée la sécurité et la confidentialité de nos données ?
-Toutes les données sont traitées dans un environnement isolé conforme aux normes de sécurité les plus strictes avec chiffrement de bout en bout.
-
----
-
-## 7. 📍 Rayonnement Géographique & Communes Voisines
-
-Notre couverture pour **${service}** s'étend à l'ensemble du bassin économique de **${location}** ainsi qu'aux communes limitrophes dans un rayon de 25 kilomètres.
-`.trim();
-
-    const wordCount = markdown.split(/\s+/).filter(Boolean).length;
-
-    return {
-      title,
-      metaDescription,
-      markdown,
-      wordCount,
-      linksInjected,
-      tokensConsumed,
-      tokenUsage,
-    };
-  }
-
-  /**
-   * Computes telemetry & page metering data for syncing with LynxSEO Studio dashboard.
-   */
-  getTelemetryPayload(
-    domain: string,
-    data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1],
-    options: MatrixOptions,
-  ) {
-    const pages = this.generateAllMatrices(domain, data, options);
-    const indexedPages = pages.filter((p) => p.robots.includes("index"));
-
-    const matrixBreakdown: Record<string, number> = {};
-    for (const p of pages) {
-      matrixBreakdown[p.matrixFamily] = (matrixBreakdown[p.matrixFamily] || 0) + 1;
-    }
-
-    return {
-      domain,
-      brandName: options.brandName,
-      language: options.language || "en",
-      languages: options.languages || [options.language || "en"],
-      totalPages: pages.length,
-      indexedPages: indexedPages.length,
-      servicesCount: data.services?.length ?? 0,
-      matrixBreakdown,
-      timestamp: new Date().toISOString(),
-    };
-  }
-}
-