@lynxflow/seo-engine 1.5.8 → 1.6.0

package/README.md

@@ -57,47 +57,101 @@ The SDK structures programmatic content across **10 canonical root pillars** exp
 
 ## Quickstart
 
-### 1. Initialize Engine
+### 1. Initialize Engine & Configure Minimal Inputs
+
+The SDK runs **in-memory inside the client application** (< 0.05ms) and automatically provisions verified cities, populations, GPS coordinates, and currencies from its built-in global demographic database.
 
 ```typescript
 import { PseoMatrixEngine } from "@lynxflow/seo-engine";
 
-export const matrixEngine = new PseoMatrixEngine({
-  companyName: "Acme Cloud",
-  language: "en", // "en" default, supports "fr", "de", "es", "it", "pt", etc.
-  correctionsEmail: "compliance@acme.com",
-});
-```
+export const matrixEngine = new PseoMatrixEngine();
 
-### 2. Resolve Programmatic Pages
+export const SEO_CONFIG = {
+  brandName: "Acme Cloud",
+  languages: ["fr", "en", "es"], // Supported site languages
+  countries: ["france", "espagne", "belgique"], // Or "europe" / "international" — SDK auto-provisions verified cities!
+  cleanDirectRoutes: true, // Eliminates parasite words (/solutions/, etc.) for direct /{service}/{city}
+};
 
-```typescript
-const pages = matrixEngine.generateAllMatrices("https://example.com", {
+export const PSEO_DATASET = {
   services: [
-    { slug: "crm-pipeline", name: "Sales CRM", category: "Sales", keyFeatures: ["Kanban"], description: "CRM" }
+    { 
+      slug: "autopost-facebook", 
+      name: "Autopost Facebook & Instagram", 
+      category: "Social Media", 
+      keyFeatures: ["AI Scheduling", "Visual Calendar", "Auto-Hashtags"],
+      description: "Automated social media posting engine" 
+    },
+    { 
+      slug: "crm-pipeline", 
+      name: "Visual CRM Pipeline", 
+      category: "Sales", 
+      keyFeatures: ["Kanban", "Lead scoring"],
+      description: "Visual deal tracking software" 
+    },
   ],
   targets: [
-    { slug: "law-firms", name: "Law Firms", type: "industry", painPoints: ["Billing"], benefits: ["Security"] }
+    { slug: "agences", name: "Marketing Agencies", type: "industry", painPoints: ["Manual Posting"], benefits: ["10x Output"] }
   ],
   integrations: [
-    { slug: "slack", name: "Slack", category: "Communication", syncFeatures: ["Alerts"] }
+    { slug: "shopify", name: "Shopify", category: "E-Commerce", syncFeatures: ["Catalog sync"] }
   ],
   templates: [
-    { slug: "pipeline-excel", title: "Sales Pipeline", topic: "Sales", format: "excel", benefits: ["Free"] }
+    { slug: "social-calendar-excel", title: "Social Media Calendar", topic: "Social Media", format: "excel", benefits: ["Free download"] }
   ],
   glossaryTerms: [
-    { slug: "mrr", term: "MRR", shortDefinition: "Monthly Recurring Revenue" }
+    { slug: "engagement-rate", term: "Engagement Rate", shortDefinition: "Percentage of audience interacting with content" }
   ]
-}, { brandName: "Acme" });
+};
+```
 
-console.log(pages[0].urlPath);      // "/for/law-firms"
-console.log(pages[0].schemaGraph);  // Injected Schema.org JSON-LD graph
+### 2. Next.js Universal Dynamic Catch-All (`app/[...slug]/page.tsx`)
+
+```tsx
+import { notFound } from "next/navigation";
+import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
+
+export async function generateMetadata({ params }: { params: { slug: string[] } }) {
+  const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
+  const page = matrixEngine.resolvePage(params.slug, domain, PSEO_DATASET, SEO_CONFIG);
+  if (!page) return {};
+  return { title: page.title, description: page.description, alternates: { canonical: page.canonicalUrl }, robots: page.robots };
+}
+
+export default async function ProgrammaticPage({ params }: { params: { slug: string[] } }) {
+  const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
+  // ⚡ Resolved mathematically in local RAM in < 0.05ms
+  const page = matrixEngine.resolvePage(params.slug, domain, PSEO_DATASET, SEO_CONFIG);
+  if (!page) notFound();
+
+  return (
+    <article className="min-h-screen bg-background text-foreground py-12 px-6 max-w-5xl mx-auto space-y-8">
+      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(page.schemaGraph) }} />
+      <h1 className="text-4xl font-extrabold">{page.h1}</h1>
+      <p className="text-lg text-muted-foreground">{page.description}</p>
+      {page.neighboringLinks && (
+        <nav className="flex flex-wrap gap-2 pt-6">
+          {page.neighboringLinks.map((l) => (
+            <a key={l.url} href={l.url} className="px-3 py-1 bg-secondary rounded text-xs">{l.name}</a>
+          ))}
+        </nav>
+      )}
+    </article>
+  );
+}
 ```
 
-### 3. URL Slug Cleansing (6 Golden Rules)
+### 3. XML Sitemap & `/llms.txt` Feeds (1 Line of Code)
 
 ```typescript
-import { cleanSeoSlug, validateSeoSlug } from "@lynxflow/seo-engine";
+// app/sitemap.ts
+export default function sitemap() {
+  const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
+  return matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG)
+    .filter(p => p.robots.includes("index"))
+    .map(p => ({ url: p.canonicalUrl, lastModified: new Date() }));
+}
+```
 
 const slug = cleanSeoSlug("The best software for managing client invoices in 2026", { language: "en" });
 console.log(slug); // "best-software-managing-client-invoices"

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 = {

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 = {
@@ -6464,6 +6554,7 @@ export {
   SerpClient,
   SeoOpportunitiesDecayDetector,
   SchemaGraphBuilder,
+  SUPPORTED_CANONICAL_LOCALES,
   SCHEMA_LOCAL_BUSINESS_MAP,
   RssSyndicationFeedGenerator,
   RealReviewsSyncEngine,
@@ -6487,6 +6578,7 @@ export {
   IsrCacheManager,
   InstantMatrixSearchEngine,
   IndexNowClient,
+  I18nDetector,
   HyperswitchGateway,
   GeoMeshLinkingEngine,
   ExtendedSchemaGraphBuilder,

package/dist/matrix-engine.d.ts

@@ -127,6 +127,7 @@ export interface GeneratedPageMeta {
 export interface MatrixOptions {
     brandName: string;
     language?: string;
+    languages?: string[];
     countries?: string[] | string;
     territories?: string[] | string;
     cleanDirectRoutes?: boolean;
@@ -220,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.8",
+  "version": "1.6.0",
   "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/matrix-engine.ts

@@ -156,6 +156,7 @@ export interface GeneratedPageMeta {
 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}
@@ -882,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.
    */
@@ -904,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(),
+    };
+  }
 }