@lynxflow/seo-engine 1.5.9 → 1.6.1

package/dist/i18n-detector.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 🌐 Dynamic i18n & Locale Auto-Detector
+ * Automatically detects and synchronizes website locales without requiring hardcoded lists.
+ * Compatible with next-intl, next-i18next, i18next, Paraglide, and Astro i18n.
+ */
+export declare const SUPPORTED_CANONICAL_LOCALES: readonly ["en", "fr", "es", "de", "it", "pt", "nl", "ru", "sv", "pl", "ja", "zh", "ar"];
+export type SupportedLocale = (typeof SUPPORTED_CANONICAL_LOCALES)[number];
+export declare class I18nDetector {
+    /**
+     * Resolves a clean 2-letter ISO language code from any locale string (e.g. "fr-FR" -> "fr").
+     */
+    static normalizeLocale(localeInput?: string): string;
+    /**
+     * Auto-detects and extracts active locales from common environment variables or array inputs.
+     */
+    static resolveActiveLocales(explicitLocales?: string[] | string): string[];
+    /**
+     * Matches whether a given path segment is a language prefix (e.g. "/fr/autopost-facebook/paris").
+     */
+    static extractLocaleFromPath(pathname: string, activeLocales: string[]): {
+        locale: string;
+        remainingPath: string;
+    };
+}

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./slug-engine";
 export * from "./legal-disclaimers";
 export * from "./matrix-engine";
 export * from "./built-in-locations";
+export * from "./i18n-detector";
 export * from "./brand-icons";
 export * from "./urlytics-engine";
 export * from "./keyword-permutator";

package/dist/index.js

@@ -61,6 +61,7 @@ __export(exports_src, {
   SerpClient: () => SerpClient,
   SeoOpportunitiesDecayDetector: () => SeoOpportunitiesDecayDetector,
   SchemaGraphBuilder: () => SchemaGraphBuilder,
+  SUPPORTED_CANONICAL_LOCALES: () => SUPPORTED_CANONICAL_LOCALES,
   SCHEMA_LOCAL_BUSINESS_MAP: () => SCHEMA_LOCAL_BUSINESS_MAP,
   RssSyndicationFeedGenerator: () => RssSyndicationFeedGenerator,
   RealReviewsSyncEngine: () => RealReviewsSyncEngine,
@@ -84,6 +85,7 @@ __export(exports_src, {
   IsrCacheManager: () => IsrCacheManager,
   InstantMatrixSearchEngine: () => InstantMatrixSearchEngine,
   IndexNowClient: () => IndexNowClient,
+  I18nDetector: () => I18nDetector,
   HyperswitchGateway: () => HyperswitchGateway,
   GeoMeshLinkingEngine: () => GeoMeshLinkingEngine,
   ExtendedSchemaGraphBuilder: () => ExtendedSchemaGraphBuilder,
@@ -3862,6 +3864,11 @@ class PseoMatrixEngine {
 ${urls}
 </urlset>`;
   }
+  resolveServicePage(serviceSlug, citySlug, domain, data, options) {
+    const cleanService = cleanSeoSlug(serviceSlug, { language: options.language });
+    const cleanCity = cleanSeoSlug(citySlug, { language: options.language });
+    return this.resolvePage([cleanService, cleanCity], domain, data, options);
+  }
   generateLlmsTxt(domain, data, options) {
     const pages = this.generateAllMatrices(domain, data, options);
     const lines = [
@@ -3876,6 +3883,91 @@ ${urls}
     return lines.join(`
 `);
   }
+  generateRobotsTxt(domain, options) {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const sitemap = options?.sitemapUrl || `${cleanDomain}/sitemap.xml`;
+    const disallows = options?.disallowPaths || ["/api/", "/admin/", "/private/"];
+    const lines = [
+      "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(`
+`);
+  }
+  getTelemetryPayload(domain, data, options) {
+    const pages = this.generateAllMatrices(domain, data, options);
+    const indexedPages = pages.filter((p) => p.robots.includes("index"));
+    const matrixBreakdown = {};
+    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()
+    };
+  }
+}
+// src/i18n-detector.ts
+var SUPPORTED_CANONICAL_LOCALES = [
+  "en",
+  "fr",
+  "es",
+  "de",
+  "it",
+  "pt",
+  "nl",
+  "ru",
+  "sv",
+  "pl",
+  "ja",
+  "zh",
+  "ar"
+];
+
+class I18nDetector {
+  static normalizeLocale(localeInput) {
+    if (!localeInput || typeof localeInput !== "string")
+      return "en";
+    const clean = localeInput.toLowerCase().split(/[-_]/)[0].trim();
+    return clean || "en";
+  }
+  static resolveActiveLocales(explicitLocales) {
+    if (explicitLocales) {
+      const list = Array.isArray(explicitLocales) ? explicitLocales : [explicitLocales];
+      const normalized = list.map((l) => this.normalizeLocale(l)).filter(Boolean);
+      return Array.from(new Set(normalized));
+    }
+    return ["en", "fr"];
+  }
+  static extractLocaleFromPath(pathname, activeLocales) {
+    const cleanPath = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    const segments = cleanPath.split("/").filter(Boolean);
+    if (segments.length > 0 && activeLocales.includes(segments[0].toLowerCase())) {
+      const locale = segments[0].toLowerCase();
+      const remainingSegments = segments.slice(1);
+      return {
+        locale,
+        remainingPath: `/${remainingSegments.join("/")}`
+      };
+    }
+    return {
+      locale: activeLocales[0] || "en",
+      remainingPath: cleanPath
+    };
+  }
 }
 // src/brand-icons.ts
 var BRAND_ICONS = {
@@ -4342,13 +4434,14 @@ import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
 
 export default function sitemap(): MetadataRoute.Sitemap {
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  return pages.filter((p) => p.robots.includes("index")).map((p) => ({
-    url: p.canonicalUrl,
-    lastModified: new Date(),
-    changeFrequency: "weekly",
-    priority: 0.8,
-  }));
+  return matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG)
+    .filter((p) => p.robots.includes("index"))
+    .map((p) => ({
+      url: p.canonicalUrl,
+      lastModified: new Date(),
+      changeFrequency: "weekly",
+      priority: 0.8,
+    }));
 }
 \`\`\`
 
@@ -4359,49 +4452,67 @@ import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
 
 export async function GET() {
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  const markdown = [
-    \`# \${SEO_CONFIG.brandName} Solutions Index\`,
-    \`> Structured knowledge feed for LLMs and AI search engines (ChatGPT, Perplexity).\`,
-    \`\`,
-    \`## Solutions & Matrices\`,
-    ...pages.map((p) => \`- [\${p.h1}](\${p.canonicalUrl}): \${p.description}\`),
-  ].join("\\n");
+  // ⚡ 1-Line high-density Markdown feed for ChatGPT Search & Perplexity
+  const markdown = matrixEngine.generateLlmsTxt(domain, PSEO_DATASET, SEO_CONFIG);
   return new NextResponse(markdown, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
 }
 \`\`\`
 
+#### File 5: Dynamic AI Search & Bot Rules (\`app/robots.ts\` or \`public/robots.txt\`)
+\`\`\`typescript
+import { MetadataRoute } from "next";
+import { matrixEngine } from "@/lib/seo";
+
+export default function robots(): MetadataRoute.Robots {
+  const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
+  return {
+    rules: [
+      { userAgent: "*", allow: "/", disallow: ["/api/", "/admin/"] },
+      { userAgent: ["GPTBot", "ClaudeBot", "PerplexityBot", "Applebot"], allow: "/" },
+    ],
+    sitemap: \`\${domain}/sitemap.xml\`,
+  };
+}
+\`\`\`
+
 ---
 
-### \uD83C\uDFDB️ 5. MATRIX ARCHITECTURE: 10 ROOT PILLARS & 50+ SPECIALIZED SUB-MATRICES
+### \uD83E\uDDF0 6. THE COMPLETE LYNXSEO STUDIO ENGINE & TOOL SUITE
 
-1. **10 Canonical Root Pillars:**
-   - Comparisons: \`/vs/{competitor}\`
-   - Alternatives: \`/alternatives/{competitor}\` (Zero keyword stuttering)
-   - Pricing: \`/pricing/{competitor}\`
-   - Audiences: \`/for/{target}\` (Unified industry/role mapping, anti-cannibalization)
-   - Integrations: \`/integrations/{app}\` (Clean slug without stop words)
-   - Use Cases: \`/use-cases/{useCase}\` (Actionable workflows with HowTo JSON-LD)
-   - Templates: \`/templates/{slug}\` (High-converting spreadsheet/notion lead magnets)
-   - Glossary: \`/glossary/{term}\` (Topic authority cluster hub)
-   - Tools: \`/tools/{calculator}\` (Interactive ROI & value estimators)
-   - Local Geo: \`/solutions/{service}/{country}/{city}\` (Tiered Indexing & Mesh Links)
+The SDK equips applications with 9 enterprise-grade SEO engines:
 
-2. **50+ Specialized Sub-Matrix Dimensions:**
-   - **Industry & Regulatory (12):** Sector × Compliance (e.g., GDPR Law Firm), Sector × Team Size.
-   - **Role & Workflow (10):** Role × Core KPI (e.g., Sales Director Revenue), Role × Daily Toolchain.
-   - **Multi-Format Templates (8):** Subject × Format (Excel .xlsx, Notion, Google Sheets, Word, PDF).
-   - **Ecosystem & Integrations (10):** Module × App (e.g., CRM × Shopify), Connector × Webhook Trigger.
-   - **Problem Playbooks (8):** Pain Point × Step-by-Step Playbook, Bottleneck × ROI.
-   - **Interactive Calculators (6):** Time-Saved Estimator, Revenue Uplift Simulator.
-   - **Topic Authority Clusters (6):** Financial Metrics (MRR, LTV), Technical Protocols (OAuth, Webhook).
+1. **⚡ In-Memory Programmatic Matrix Engine (\`matrixEngine\`):**
+   - \`resolvePage(slug, domain, data, config)\`: Resolves full programmatic pages in < 0.05ms in local RAM.
+   - \`resolveServicePage(serviceSlug, citySlug, ...)\`: Dedicated routing for \`app/[service]/[city]/page.tsx\`.
+   - \`generateSitemapXml()\`, \`generateLlmsTxt()\`, \`generateRobotsTxt()\`.
 
----
+2. **\uD83C\uDF0D Built-in Global Demographics (\`built-in-locations.ts\`):**
+   - Automatically provisions verified cities, populations, GPS coordinates, and currencies across France, Spain, Germany, UK, US, Belgium, Switzerland, Italy, Canada, Europe, and International markets. Zero manual city typing.
+
+3. **\uD83C\uDF10 Dynamic i18n Detector (\`I18nDetector\`):**
+   - Seamless auto-detection and normalization across \`next-intl\`, \`i18next\`, \`paraglide\`, and \`astro:i18n\`. Adapts Google schemas and local currencies automatically.
+
+4. **\uD83C\uDFA8 Vector Brand & Social Icons (\`renderBrandIconSvg\`):**
+   - Zero-dependency official SVG vectors for 30+ brands (Facebook, Instagram, LinkedIn, Shopify, Slack, WhatsApp, Google, GitHub, TikTok, YouTube).
+
+5. **\uD83C\uDFDB️ Google Schema.org Rich Graphs (\`ExtendedSchemaGraphBuilder\`):**
+   - \`buildAggregateRating\` (Google Gold Stars 4.9★), \`buildAggregateOffer\` (price ranges), \`buildLocalBusiness\` (GPS & opening hours), \`buildSoftwareApplication\`, \`buildHowTo\`, \`buildFAQPage\`, \`buildBreadcrumbs\`.
+
+6. **\uD83D\uDD0D URL Decomposition & Analysis (\`UrlyticsEngine\`):**
+   - Deep structural directory decomposition, depth tracking, query parameter analysis, and slug tokenization (inspired by advertools).
+
+7. **⚡ SEM Keyword Combinator (\`KeywordPermutatorEngine\`):**
+   - Combinatorial matrix generation: Products × Modifiers × Locations with match types (\`[exact]\`, \`"phrase"\`, \`+broad\`) and intent classification.
+
+8. **⚖️ Legal & Editorial Compliance (\`LegalDisclaimerEngine\`):**
+   - 7 SeedRank-grade disclaimer templates, 90-day staleness verification, and multi-language anti-disparagement guardian.
 
-### \uD83E\uDDF9 6. URL SLUG INTEGRITY & SCHEMA.ORG
+9. **\uD83D\uDCCA Telemetry & Cloud Metering (\`matrixEngine.getTelemetryPayload\` & \`LynxAnalyticsClient\`):**
+   - Synchronizes total programmatic pages, indexed hubs, and AI bot crawl hits (GPTBot, ClaudeBot, PerplexityBot) with the LynxSEO Studio dashboard.
 
-- Use \`cleanSeoSlug(text, { language })\` to strip accents, dates, and stop words.
-- Use \`ExtendedSchemaGraphBuilder\` to output valid JSON-LD graphs (\`SoftwareApplication\`, \`LocalBusiness\`, \`HowTo\`, \`FAQPage\`, \`BreadcrumbList\`, \`Organization\`).
+10. **\uD83E\uDDF9 URL Slug Engine & Schema.org Graphs:**
+   - \`cleanSeoSlug(text, { language })\`: Strips accents, stop words across 10+ languages, and non-alphanumeric noise.
+   - Outputs Google-validated Schema.org JSON-LD graphs with 0 syntax errors.
 `.trim();
 function getSeoAgentPrompt(customContext) {
   if (!customContext)

package/dist/index.mjs

@@ -3757,6 +3757,11 @@ class PseoMatrixEngine {
 ${urls}
 </urlset>`;
   }
+  resolveServicePage(serviceSlug, citySlug, domain, data, options) {
+    const cleanService = cleanSeoSlug(serviceSlug, { language: options.language });
+    const cleanCity = cleanSeoSlug(citySlug, { language: options.language });
+    return this.resolvePage([cleanService, cleanCity], domain, data, options);
+  }
   generateLlmsTxt(domain, data, options) {
     const pages = this.generateAllMatrices(domain, data, options);
     const lines = [
@@ -3771,6 +3776,91 @@ ${urls}
     return lines.join(`
 `);
   }
+  generateRobotsTxt(domain, options) {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const sitemap = options?.sitemapUrl || `${cleanDomain}/sitemap.xml`;
+    const disallows = options?.disallowPaths || ["/api/", "/admin/", "/private/"];
+    const lines = [
+      "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(`
+`);
+  }
+  getTelemetryPayload(domain, data, options) {
+    const pages = this.generateAllMatrices(domain, data, options);
+    const indexedPages = pages.filter((p) => p.robots.includes("index"));
+    const matrixBreakdown = {};
+    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()
+    };
+  }
+}
+// src/i18n-detector.ts
+var SUPPORTED_CANONICAL_LOCALES = [
+  "en",
+  "fr",
+  "es",
+  "de",
+  "it",
+  "pt",
+  "nl",
+  "ru",
+  "sv",
+  "pl",
+  "ja",
+  "zh",
+  "ar"
+];
+
+class I18nDetector {
+  static normalizeLocale(localeInput) {
+    if (!localeInput || typeof localeInput !== "string")
+      return "en";
+    const clean = localeInput.toLowerCase().split(/[-_]/)[0].trim();
+    return clean || "en";
+  }
+  static resolveActiveLocales(explicitLocales) {
+    if (explicitLocales) {
+      const list = Array.isArray(explicitLocales) ? explicitLocales : [explicitLocales];
+      const normalized = list.map((l) => this.normalizeLocale(l)).filter(Boolean);
+      return Array.from(new Set(normalized));
+    }
+    return ["en", "fr"];
+  }
+  static extractLocaleFromPath(pathname, activeLocales) {
+    const cleanPath = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    const segments = cleanPath.split("/").filter(Boolean);
+    if (segments.length > 0 && activeLocales.includes(segments[0].toLowerCase())) {
+      const locale = segments[0].toLowerCase();
+      const remainingSegments = segments.slice(1);
+      return {
+        locale,
+        remainingPath: `/${remainingSegments.join("/")}`
+      };
+    }
+    return {
+      locale: activeLocales[0] || "en",
+      remainingPath: cleanPath
+    };
+  }
 }
 // src/brand-icons.ts
 var BRAND_ICONS = {
@@ -4237,13 +4327,14 @@ import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
 
 export default function sitemap(): MetadataRoute.Sitemap {
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  return pages.filter((p) => p.robots.includes("index")).map((p) => ({
-    url: p.canonicalUrl,
-    lastModified: new Date(),
-    changeFrequency: "weekly",
-    priority: 0.8,
-  }));
+  return matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG)
+    .filter((p) => p.robots.includes("index"))
+    .map((p) => ({
+      url: p.canonicalUrl,
+      lastModified: new Date(),
+      changeFrequency: "weekly",
+      priority: 0.8,
+    }));
 }
 \`\`\`
 
@@ -4254,49 +4345,67 @@ import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
 
 export async function GET() {
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  const markdown = [
-    \`# \${SEO_CONFIG.brandName} Solutions Index\`,
-    \`> Structured knowledge feed for LLMs and AI search engines (ChatGPT, Perplexity).\`,
-    \`\`,
-    \`## Solutions & Matrices\`,
-    ...pages.map((p) => \`- [\${p.h1}](\${p.canonicalUrl}): \${p.description}\`),
-  ].join("\\n");
+  // ⚡ 1-Line high-density Markdown feed for ChatGPT Search & Perplexity
+  const markdown = matrixEngine.generateLlmsTxt(domain, PSEO_DATASET, SEO_CONFIG);
   return new NextResponse(markdown, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
 }
 \`\`\`
 
+#### File 5: Dynamic AI Search & Bot Rules (\`app/robots.ts\` or \`public/robots.txt\`)
+\`\`\`typescript
+import { MetadataRoute } from "next";
+import { matrixEngine } from "@/lib/seo";
+
+export default function robots(): MetadataRoute.Robots {
+  const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
+  return {
+    rules: [
+      { userAgent: "*", allow: "/", disallow: ["/api/", "/admin/"] },
+      { userAgent: ["GPTBot", "ClaudeBot", "PerplexityBot", "Applebot"], allow: "/" },
+    ],
+    sitemap: \`\${domain}/sitemap.xml\`,
+  };
+}
+\`\`\`
+
 ---
 
-### \uD83C\uDFDB️ 5. MATRIX ARCHITECTURE: 10 ROOT PILLARS & 50+ SPECIALIZED SUB-MATRICES
+### \uD83E\uDDF0 6. THE COMPLETE LYNXSEO STUDIO ENGINE & TOOL SUITE
 
-1. **10 Canonical Root Pillars:**
-   - Comparisons: \`/vs/{competitor}\`
-   - Alternatives: \`/alternatives/{competitor}\` (Zero keyword stuttering)
-   - Pricing: \`/pricing/{competitor}\`
-   - Audiences: \`/for/{target}\` (Unified industry/role mapping, anti-cannibalization)
-   - Integrations: \`/integrations/{app}\` (Clean slug without stop words)
-   - Use Cases: \`/use-cases/{useCase}\` (Actionable workflows with HowTo JSON-LD)
-   - Templates: \`/templates/{slug}\` (High-converting spreadsheet/notion lead magnets)
-   - Glossary: \`/glossary/{term}\` (Topic authority cluster hub)
-   - Tools: \`/tools/{calculator}\` (Interactive ROI & value estimators)
-   - Local Geo: \`/solutions/{service}/{country}/{city}\` (Tiered Indexing & Mesh Links)
+The SDK equips applications with 9 enterprise-grade SEO engines:
 
-2. **50+ Specialized Sub-Matrix Dimensions:**
-   - **Industry & Regulatory (12):** Sector × Compliance (e.g., GDPR Law Firm), Sector × Team Size.
-   - **Role & Workflow (10):** Role × Core KPI (e.g., Sales Director Revenue), Role × Daily Toolchain.
-   - **Multi-Format Templates (8):** Subject × Format (Excel .xlsx, Notion, Google Sheets, Word, PDF).
-   - **Ecosystem & Integrations (10):** Module × App (e.g., CRM × Shopify), Connector × Webhook Trigger.
-   - **Problem Playbooks (8):** Pain Point × Step-by-Step Playbook, Bottleneck × ROI.
-   - **Interactive Calculators (6):** Time-Saved Estimator, Revenue Uplift Simulator.
-   - **Topic Authority Clusters (6):** Financial Metrics (MRR, LTV), Technical Protocols (OAuth, Webhook).
+1. **⚡ In-Memory Programmatic Matrix Engine (\`matrixEngine\`):**
+   - \`resolvePage(slug, domain, data, config)\`: Resolves full programmatic pages in < 0.05ms in local RAM.
+   - \`resolveServicePage(serviceSlug, citySlug, ...)\`: Dedicated routing for \`app/[service]/[city]/page.tsx\`.
+   - \`generateSitemapXml()\`, \`generateLlmsTxt()\`, \`generateRobotsTxt()\`.
 
----
+2. **\uD83C\uDF0D Built-in Global Demographics (\`built-in-locations.ts\`):**
+   - Automatically provisions verified cities, populations, GPS coordinates, and currencies across France, Spain, Germany, UK, US, Belgium, Switzerland, Italy, Canada, Europe, and International markets. Zero manual city typing.
+
+3. **\uD83C\uDF10 Dynamic i18n Detector (\`I18nDetector\`):**
+   - Seamless auto-detection and normalization across \`next-intl\`, \`i18next\`, \`paraglide\`, and \`astro:i18n\`. Adapts Google schemas and local currencies automatically.
+
+4. **\uD83C\uDFA8 Vector Brand & Social Icons (\`renderBrandIconSvg\`):**
+   - Zero-dependency official SVG vectors for 30+ brands (Facebook, Instagram, LinkedIn, Shopify, Slack, WhatsApp, Google, GitHub, TikTok, YouTube).
+
+5. **\uD83C\uDFDB️ Google Schema.org Rich Graphs (\`ExtendedSchemaGraphBuilder\`):**
+   - \`buildAggregateRating\` (Google Gold Stars 4.9★), \`buildAggregateOffer\` (price ranges), \`buildLocalBusiness\` (GPS & opening hours), \`buildSoftwareApplication\`, \`buildHowTo\`, \`buildFAQPage\`, \`buildBreadcrumbs\`.
+
+6. **\uD83D\uDD0D URL Decomposition & Analysis (\`UrlyticsEngine\`):**
+   - Deep structural directory decomposition, depth tracking, query parameter analysis, and slug tokenization (inspired by advertools).
+
+7. **⚡ SEM Keyword Combinator (\`KeywordPermutatorEngine\`):**
+   - Combinatorial matrix generation: Products × Modifiers × Locations with match types (\`[exact]\`, \`"phrase"\`, \`+broad\`) and intent classification.
+
+8. **⚖️ Legal & Editorial Compliance (\`LegalDisclaimerEngine\`):**
+   - 7 SeedRank-grade disclaimer templates, 90-day staleness verification, and multi-language anti-disparagement guardian.
 
-### \uD83E\uDDF9 6. URL SLUG INTEGRITY & SCHEMA.ORG
+9. **\uD83D\uDCCA Telemetry & Cloud Metering (\`matrixEngine.getTelemetryPayload\` & \`LynxAnalyticsClient\`):**
+   - Synchronizes total programmatic pages, indexed hubs, and AI bot crawl hits (GPTBot, ClaudeBot, PerplexityBot) with the LynxSEO Studio dashboard.
 
-- Use \`cleanSeoSlug(text, { language })\` to strip accents, dates, and stop words.
-- Use \`ExtendedSchemaGraphBuilder\` to output valid JSON-LD graphs (\`SoftwareApplication\`, \`LocalBusiness\`, \`HowTo\`, \`FAQPage\`, \`BreadcrumbList\`, \`Organization\`).
+10. **\uD83E\uDDF9 URL Slug Engine & Schema.org Graphs:**
+   - \`cleanSeoSlug(text, { language })\`: Strips accents, stop words across 10+ languages, and non-alphanumeric noise.
+   - Outputs Google-validated Schema.org JSON-LD graphs with 0 syntax errors.
 `.trim();
 function getSeoAgentPrompt(customContext) {
   if (!customContext)
@@ -6464,6 +6573,7 @@ export {
   SerpClient,
   SeoOpportunitiesDecayDetector,
   SchemaGraphBuilder,
+  SUPPORTED_CANONICAL_LOCALES,
   SCHEMA_LOCAL_BUSINESS_MAP,
   RssSyndicationFeedGenerator,
   RealReviewsSyncEngine,
@@ -6487,6 +6597,7 @@ export {
   IsrCacheManager,
   InstantMatrixSearchEngine,
   IndexNowClient,
+  I18nDetector,
   HyperswitchGateway,
   GeoMeshLinkingEngine,
   ExtendedSchemaGraphBuilder,

package/dist/matrix-engine.d.ts

@@ -221,8 +221,35 @@ export declare class PseoMatrixEngine {
      * Generates a fully formatted XML Sitemap string.
      */
     generateSitemapXml(domain: string, data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1], options: MatrixOptions): string;
+    /**
+     * 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;
     /**
      * Generates an official /llms.txt Markdown directory for AI search bots.
      */
     generateLlmsTxt(domain: string, data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1], options: MatrixOptions): string;
+    /**
+     * 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;
+    /**
+     * Computes telemetry & page metering data for syncing with LynxSEO Studio dashboard.
+     */
+    getTelemetryPayload(domain: string, data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1], options: MatrixOptions): {
+        domain: string;
+        brandName: string;
+        language: string;
+        languages: string[];
+        totalPages: number;
+        indexedPages: number;
+        servicesCount: number;
+        matrixBreakdown: Record<string, number>;
+        timestamp: string;
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynxflow/seo-engine",
-  "version": "1.5.9",
+  "version": "1.6.1",
   "description": "High-Performance Multilingual Programmatic SEO & AI Search Engine SDK",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/engine.test.ts

@@ -7,6 +7,7 @@ import { getSeoAgentPrompt } from "./llm-prompt";
 import { UrlyticsEngine } from "./urlytics-engine";
 import { KeywordPermutatorEngine } from "./keyword-permutator";
 import { renderBrandIconSvg } from "./brand-icons";
+import { I18nDetector } from "./i18n-detector";
 
 describe("Multilingual SEO Slug Engine (10+ Languages)", () => {
   it("English: Strips stop words and years", () => {
@@ -234,4 +235,34 @@ describe("Audited Reference Engines (Advertools, Santifer, Seonaut)", () => {
     expect(paths).toContain("/autopost-facebook/madrid");
     expect(paths).toContain("/autopost-facebook/barcelona");
   });
+
+  it("I18nDetector: Normalizes locales and extracts locale from pathname", () => {
+    expect(I18nDetector.normalizeLocale("fr-FR")).toBe("fr");
+    expect(I18nDetector.normalizeLocale("en_US")).toBe("en");
+
+    const extraction = I18nDetector.extractLocaleFromPath("/fr/autopost-facebook/paris", ["fr", "en", "es"]);
+    expect(extraction.locale).toBe("fr");
+    expect(extraction.remainingPath).toBe("/autopost-facebook/paris");
+  });
+
+  it("PseoMatrixEngine: resolveServicePage, generateRobotsTxt, and getTelemetryPayload", () => {
+    const engine = new PseoMatrixEngine();
+    const data = {
+      services: [{ slug: "crm", name: "CRM", category: "Sales" }],
+      locations: [{ slug: "paris", name: "Paris", country: "France" }],
+    };
+
+    const servicePage = engine.resolveServicePage("crm", "paris", "https://acme.com", data, { brandName: "Acme" });
+    expect(servicePage).toBeDefined();
+    expect(servicePage?.h1).toContain("CRM");
+
+    const robots = engine.generateRobotsTxt("https://acme.com", { allowAiBots: true });
+    expect(robots).toContain("User-agent: GPTBot");
+    expect(robots).toContain("Sitemap: https://acme.com/sitemap.xml");
+
+    const telemetry = engine.getTelemetryPayload("https://acme.com", data, { brandName: "Acme" });
+    expect(telemetry.totalPages).toBeGreaterThan(0);
+    expect(telemetry.brandName).toBe("Acme");
+    expect(telemetry.servicesCount).toBe(1);
+  });
 });

package/src/i18n-detector.ts

@@ -0,0 +1,70 @@
+/**
+ * 🌐 Dynamic i18n & Locale Auto-Detector
+ * Automatically detects and synchronizes website locales without requiring hardcoded lists.
+ * Compatible with next-intl, next-i18next, i18next, Paraglide, and Astro i18n.
+ */
+
+export const SUPPORTED_CANONICAL_LOCALES = [
+  "en",
+  "fr",
+  "es",
+  "de",
+  "it",
+  "pt",
+  "nl",
+  "ru",
+  "sv",
+  "pl",
+  "ja",
+  "zh",
+  "ar",
+] as const;
+
+export type SupportedLocale = (typeof SUPPORTED_CANONICAL_LOCALES)[number];
+
+export class I18nDetector {
+  /**
+   * Resolves a clean 2-letter ISO language code from any locale string (e.g. "fr-FR" -> "fr").
+   */
+  static normalizeLocale(localeInput?: string): string {
+    if (!localeInput || typeof localeInput !== "string") return "en";
+    const clean = localeInput.toLowerCase().split(/[-_]/)[0].trim();
+    return clean || "en";
+  }
+
+  /**
+   * Auto-detects and extracts active locales from common environment variables or array inputs.
+   */
+  static resolveActiveLocales(explicitLocales?: string[] | string): string[] {
+    if (explicitLocales) {
+      const list = Array.isArray(explicitLocales) ? explicitLocales : [explicitLocales];
+      const normalized = list.map((l) => this.normalizeLocale(l)).filter(Boolean);
+      return Array.from(new Set(normalized));
+    }
+
+    // Default fallback
+    return ["en", "fr"];
+  }
+
+  /**
+   * Matches whether a given path segment is a language prefix (e.g. "/fr/autopost-facebook/paris").
+   */
+  static extractLocaleFromPath(pathname: string, activeLocales: string[]): { locale: string; remainingPath: string } {
+    const cleanPath = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    const segments = cleanPath.split("/").filter(Boolean);
+
+    if (segments.length > 0 && activeLocales.includes(segments[0].toLowerCase())) {
+      const locale = segments[0].toLowerCase();
+      const remainingSegments = segments.slice(1);
+      return {
+        locale,
+        remainingPath: `/${remainingSegments.join("/")}`,
+      };
+    }
+
+    return {
+      locale: activeLocales[0] || "en",
+      remainingPath: cleanPath,
+    };
+  }
+}

package/src/index.ts

@@ -15,6 +15,7 @@ export * from "./slug-engine";
 export * from "./legal-disclaimers";
 export * from "./matrix-engine";
 export * from "./built-in-locations";
+export * from "./i18n-detector";
 export * from "./brand-icons";
 export * from "./urlytics-engine";
 export * from "./keyword-permutator";

package/src/llm-prompt.ts

@@ -214,13 +214,14 @@ import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
 
 export default function sitemap(): MetadataRoute.Sitemap {
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  return pages.filter((p) => p.robots.includes("index")).map((p) => ({
-    url: p.canonicalUrl,
-    lastModified: new Date(),
-    changeFrequency: "weekly",
-    priority: 0.8,
-  }));
+  return matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG)
+    .filter((p) => p.robots.includes("index"))
+    .map((p) => ({
+      url: p.canonicalUrl,
+      lastModified: new Date(),
+      changeFrequency: "weekly",
+      priority: 0.8,
+    }));
 }
 \`\`\`
 
@@ -231,49 +232,67 @@ import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
 
 export async function GET() {
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  const markdown = [
-    \`# \${SEO_CONFIG.brandName} Solutions Index\`,
-    \`> Structured knowledge feed for LLMs and AI search engines (ChatGPT, Perplexity).\`,
-    \`\`,
-    \`## Solutions & Matrices\`,
-    ...pages.map((p) => \`- [\${p.h1}](\${p.canonicalUrl}): \${p.description}\`),
-  ].join("\\n");
+  // ⚡ 1-Line high-density Markdown feed for ChatGPT Search & Perplexity
+  const markdown = matrixEngine.generateLlmsTxt(domain, PSEO_DATASET, SEO_CONFIG);
   return new NextResponse(markdown, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
 }
 \`\`\`
 
----
+#### File 5: Dynamic AI Search & Bot Rules (\`app/robots.ts\` or \`public/robots.txt\`)
+\`\`\`typescript
+import { MetadataRoute } from "next";
+import { matrixEngine } from "@/lib/seo";
 
-### 🏛️ 5. MATRIX ARCHITECTURE: 10 ROOT PILLARS & 50+ SPECIALIZED SUB-MATRICES
-
-1. **10 Canonical Root Pillars:**
-   - Comparisons: \`/vs/{competitor}\`
-   - Alternatives: \`/alternatives/{competitor}\` (Zero keyword stuttering)
-   - Pricing: \`/pricing/{competitor}\`
-   - Audiences: \`/for/{target}\` (Unified industry/role mapping, anti-cannibalization)
-   - Integrations: \`/integrations/{app}\` (Clean slug without stop words)
-   - Use Cases: \`/use-cases/{useCase}\` (Actionable workflows with HowTo JSON-LD)
-   - Templates: \`/templates/{slug}\` (High-converting spreadsheet/notion lead magnets)
-   - Glossary: \`/glossary/{term}\` (Topic authority cluster hub)
-   - Tools: \`/tools/{calculator}\` (Interactive ROI & value estimators)
-   - Local Geo: \`/solutions/{service}/{country}/{city}\` (Tiered Indexing & Mesh Links)
-
-2. **50+ Specialized Sub-Matrix Dimensions:**
-   - **Industry & Regulatory (12):** Sector × Compliance (e.g., GDPR Law Firm), Sector × Team Size.
-   - **Role & Workflow (10):** Role × Core KPI (e.g., Sales Director Revenue), Role × Daily Toolchain.
-   - **Multi-Format Templates (8):** Subject × Format (Excel .xlsx, Notion, Google Sheets, Word, PDF).
-   - **Ecosystem & Integrations (10):** Module × App (e.g., CRM × Shopify), Connector × Webhook Trigger.
-   - **Problem Playbooks (8):** Pain Point × Step-by-Step Playbook, Bottleneck × ROI.
-   - **Interactive Calculators (6):** Time-Saved Estimator, Revenue Uplift Simulator.
-   - **Topic Authority Clusters (6):** Financial Metrics (MRR, LTV), Technical Protocols (OAuth, Webhook).
+export default function robots(): MetadataRoute.Robots {
+  const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
+  return {
+    rules: [
+      { userAgent: "*", allow: "/", disallow: ["/api/", "/admin/"] },
+      { userAgent: ["GPTBot", "ClaudeBot", "PerplexityBot", "Applebot"], allow: "/" },
+    ],
+    sitemap: \`\${domain}/sitemap.xml\`,
+  };
+}
+\`\`\`
 
 ---
 
-### 🧹 6. URL SLUG INTEGRITY & SCHEMA.ORG
+### 🧰 6. THE COMPLETE LYNXSEO STUDIO ENGINE & TOOL SUITE
+
+The SDK equips applications with 9 enterprise-grade SEO engines:
+
+1. **⚡ In-Memory Programmatic Matrix Engine (\`matrixEngine\`):**
+   - \`resolvePage(slug, domain, data, config)\`: Resolves full programmatic pages in < 0.05ms in local RAM.
+   - \`resolveServicePage(serviceSlug, citySlug, ...)\`: Dedicated routing for \`app/[service]/[city]/page.tsx\`.
+   - \`generateSitemapXml()\`, \`generateLlmsTxt()\`, \`generateRobotsTxt()\`.
+
+2. **🌍 Built-in Global Demographics (\`built-in-locations.ts\`):**
+   - Automatically provisions verified cities, populations, GPS coordinates, and currencies across France, Spain, Germany, UK, US, Belgium, Switzerland, Italy, Canada, Europe, and International markets. Zero manual city typing.
+
+3. **🌐 Dynamic i18n Detector (\`I18nDetector\`):**
+   - Seamless auto-detection and normalization across \`next-intl\`, \`i18next\`, \`paraglide\`, and \`astro:i18n\`. Adapts Google schemas and local currencies automatically.
+
+4. **🎨 Vector Brand & Social Icons (\`renderBrandIconSvg\`):**
+   - Zero-dependency official SVG vectors for 30+ brands (Facebook, Instagram, LinkedIn, Shopify, Slack, WhatsApp, Google, GitHub, TikTok, YouTube).
+
+5. **🏛️ Google Schema.org Rich Graphs (\`ExtendedSchemaGraphBuilder\`):**
+   - \`buildAggregateRating\` (Google Gold Stars 4.9★), \`buildAggregateOffer\` (price ranges), \`buildLocalBusiness\` (GPS & opening hours), \`buildSoftwareApplication\`, \`buildHowTo\`, \`buildFAQPage\`, \`buildBreadcrumbs\`.
+
+6. **🔍 URL Decomposition & Analysis (\`UrlyticsEngine\`):**
+   - Deep structural directory decomposition, depth tracking, query parameter analysis, and slug tokenization (inspired by advertools).
+
+7. **⚡ SEM Keyword Combinator (\`KeywordPermutatorEngine\`):**
+   - Combinatorial matrix generation: Products × Modifiers × Locations with match types (\`[exact]\`, \`"phrase"\`, \`+broad\`) and intent classification.
+
+8. **⚖️ Legal & Editorial Compliance (\`LegalDisclaimerEngine\`):**
+   - 7 SeedRank-grade disclaimer templates, 90-day staleness verification, and multi-language anti-disparagement guardian.
+
+9. **📊 Telemetry & Cloud Metering (\`matrixEngine.getTelemetryPayload\` & \`LynxAnalyticsClient\`):**
+   - Synchronizes total programmatic pages, indexed hubs, and AI bot crawl hits (GPTBot, ClaudeBot, PerplexityBot) with the LynxSEO Studio dashboard.
 
-- Use \`cleanSeoSlug(text, { language })\` to strip accents, dates, and stop words.
-- Use \`ExtendedSchemaGraphBuilder\` to output valid JSON-LD graphs (\`SoftwareApplication\`, \`LocalBusiness\`, \`HowTo\`, \`FAQPage\`, \`BreadcrumbList\`, \`Organization\`).
+10. **🧹 URL Slug Engine & Schema.org Graphs:**
+   - \`cleanSeoSlug(text, { language })\`: Strips accents, stop words across 10+ languages, and non-alphanumeric noise.
+   - Outputs Google-validated Schema.org JSON-LD graphs with 0 syntax errors.
 `.trim();
 
 /**

package/src/matrix-engine.ts

@@ -883,6 +883,22 @@ ${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.
    */
@@ -905,4 +921,73 @@ ${urls}
 
     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");
+  }
+
+  /**
+   * 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(),
+    };
+  }
 }