@lynxflow/seo-engine 2.0.1 → 2.1.1

package/README.md

@@ -4,7 +4,7 @@ High-Performance Universal Programmatic SEO & Structured Data Engine for Modern
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/License-Proprietary-green.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/Version-2.0.0-orange.svg)](https://www.npmjs.com/package/@lynxflow/seo-engine)
+[![Version](https://img.shields.io/badge/Version-2.1.1-orange.svg)](https://www.npmjs.com/package/@lynxflow/seo-engine)
 
 ---
 

package/dist/generation-tracker.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 📊 Page Generation & Multi-Cycle Regeneration Tracker
+ *
+ * Tracks:
+ * 1. Unique Live Programmatic Pages in Index
+ * 2. Total Generation Cycles (Initial Creation + 2x, 3x+ Re-Optimizations)
+ * 3. Execution Mode: 'standard' (Deterministic 0€, 0 Token) vs 'ai-enhanced' (LLM Custom Copy with Token Billing)
+ * 4. Market Demand Signals & Emerging Country Opportunities (e.g. Brazil, US, Spain)
+ */
+export interface PageGenerationRecord {
+    urlPath: string;
+    service: string;
+    location: string;
+    country: string;
+    language: string;
+    generationCount: number;
+    mode: "standard" | "ai-enhanced";
+    tokensConsumed: number;
+    firstGeneratedAt: string;
+    lastGeneratedAt: string;
+}
+export interface MarketOpportunitySignal {
+    country: string;
+    countryCode: string;
+    detectedRequests: number;
+    activeIndexedPages: number;
+    coverageStatus: "optimal" | "underserved" | "opportunity_detected";
+    estimatedMonthlyTrafficUpside: number;
+    recommendation: string;
+}
+export interface GenerationMetricsReport {
+    uniquePagesCount: number;
+    totalGenerationCycles: number;
+    regenerationFrequency: {
+        singleGeneration: number;
+        doubleGeneration: number;
+        multiGeneration: number;
+    };
+    modeDistribution: {
+        standardDeterministicCount: number;
+        aiEnhancedCount: number;
+    };
+    totalAiTokensConsumed: number;
+    activeCountriesCount: number;
+    marketOpportunities: MarketOpportunitySignal[];
+}
+export declare class PageRegenerationTracker {
+    private records;
+    private demandSignals;
+    /**
+     * Records a page generation or regeneration event.
+     */
+    recordGeneration(params: {
+        urlPath: string;
+        service?: string;
+        location?: string;
+        country?: string;
+        language?: string;
+        mode?: "standard" | "ai-enhanced";
+        tokensConsumed?: number;
+    }): PageGenerationRecord;
+    /**
+     * Ingests external traffic or search demand signals (e.g. from Cloudflare / Nginx Edge / Google Search Console).
+     */
+    recordMarketDemand(country: string, requestVolume?: number): void;
+    /**
+     * Computes comprehensive analytics report for admin dashboards.
+     */
+    getMetricsReport(): GenerationMetricsReport;
+}

package/dist/index.d.ts

@@ -110,6 +110,7 @@ import { LynxRateLimitedTranslator } from "./rate-limited-translator";
 import { InternalPageRankEngine } from "./internal-pagerank-graph";
 import { GeoCitationScorer } from "./geo-citation-scorer";
 import { MarketingSkillsEngine } from "./marketing-skills-engine";
+import { PageRegenerationTracker } from "./generation-tracker";
 export declare function createLynxSeoEngine(config: EngineConfig): LynxSeoEngine;
 export declare const LynxSeo: {
     createEngine: typeof createLynxSeoEngine;
@@ -157,7 +158,9 @@ export declare const LynxSeo: {
     pageRankGraph: typeof InternalPageRankEngine;
     geoCitation: typeof GeoCitationScorer;
     marketingSkills: typeof MarketingSkillsEngine;
+    regenerationTracker: typeof PageRegenerationTracker;
 };
+export * from "./generation-tracker";
 export * from "./internal-pagerank-graph";
 export * from "./geo-citation-scorer";
 export * from "./marketing-skills-engine";

package/dist/index.js

@@ -3787,7 +3787,7 @@ class PseoMatrixEngine {
             ])
           ]
         };
-        pages.push({
+        const pageItem = {
           matrixFamily: "local-geo",
           urlPath,
           canonicalUrl: fullUrl,
@@ -3799,7 +3799,9 @@ class PseoMatrixEngine {
           neighboringLinks: neighborLinks,
           service: s,
           location: loc
-        });
+        };
+        pageItem.ogImageUrl = OgImageGenerator.generateOgImageUrl(cleanDomain, pageItem, options.brandName);
+        pages.push(pageItem);
       }
     }
     return pages;
@@ -4145,7 +4147,7 @@ class PseoMatrixEngine {
   generateAllMatrices(domain, data, options) {
     const allPages = [];
     if (data.services) {
-      const locs = data.locations && data.locations.length > 0 ? data.locations : resolveBuiltInLocations(options.countries || options.territories || options.language || "fr");
+      const locs = data.locations && data.locations.length > 0 ? data.locations : resolveBuiltInLocations(options.allowedCountries || options.countries || options.territories || "us");
       allPages.push(...this.generateLocalGeoMatrix(domain, data.services, locs, options));
     }
     if (data.competitors) {
@@ -4212,30 +4214,113 @@ class PseoMatrixEngine {
   }
   resolvePage(slugOrPath, domain, data, options) {
     const path = typeof slugOrPath === "string" ? slugOrPath.startsWith("/") ? slugOrPath : `/${slugOrPath}` : `/${slugOrPath.join("/")}`;
-    const pages = this.generateAllMatrices(domain, data, options);
-    const existing = pages.find((p) => p.urlPath === path);
-    if (existing)
-      return existing;
+    const lang = options.language || "en";
     const segments = path.split("/").filter(Boolean);
-    if (segments.length >= 2 && data.services && data.services.length > 0) {
-      const serviceSlug = segments[0];
-      const locationSlug = segments[segments.length - 1];
-      const matchedService = data.services.find((s) => cleanSeoSlug(s.slug, { language: options.language }) === serviceSlug || s.slug === serviceSlug);
-      if (matchedService) {
-        const countryList = options.allowedCountries || options.countries;
-        const fallbackCountry = Array.isArray(countryList) ? countryList[0] : typeof countryList === "string" && countryList !== "international" ? countryList : "United States";
-        const dynamicLoc = createDynamicLocation(locationSlug, fallbackCountry, {
-          currency: options.defaultCurrency,
-          currencySymbol: options.defaultCurrencySymbol
-        });
-        if (options.strictCountryBoundary && countryList) {
-          const allowed = (Array.isArray(countryList) ? countryList : [countryList]).map((c) => c.toLowerCase());
-          if (!allowed.includes("international") && !allowed.some((c) => dynamicLoc.country.toLowerCase().includes(c))) {
-            return;
+    if (segments.length === 0)
+      return;
+    const vsPrefix = this.getPrefix("vs", lang).replace(/^\//, "");
+    if (segments[0] === vsPrefix && segments[1] && data.competitors) {
+      const compSlug = segments[1];
+      const matched = data.competitors.find((c) => cleanSeoSlug(c.slug, { language: lang }) === compSlug || c.slug === compSlug);
+      if (matched) {
+        return this.generateVsMatrix(domain, [matched], options)[0];
+      }
+    }
+    const altPrefix = this.getPrefix("alternative", lang).replace(/^\//, "");
+    if (segments[0] === altPrefix && segments[1] && data.competitors) {
+      const compSlug = segments[1];
+      const matched = data.competitors.find((c) => cleanSeoSlug(c.slug, { language: lang }) === compSlug || c.slug === compSlug);
+      if (matched) {
+        return this.generateAlternativesMatrix(domain, [matched], options)[0];
+      }
+    }
+    const pricingPrefix = this.getPrefix("pricing", lang).replace(/^\//, "");
+    if (segments[0] === pricingPrefix && segments[1] && data.competitors) {
+      const compSlug = segments[1];
+      const matched = data.competitors.find((c) => cleanSeoSlug(c.slug, { language: lang }) === compSlug || c.slug === compSlug);
+      if (matched) {
+        return this.generatePricingMatrix(domain, [matched], options)[0];
+      }
+    }
+    const targetPrefix = this.getPrefix("target", lang).replace(/^\//, "");
+    if (segments[0] === targetPrefix && segments[1] && data.targets) {
+      const targetSlug = segments[1];
+      const matched = data.targets.find((t) => cleanSeoSlug(t.slug, { language: lang }) === targetSlug || t.slug === targetSlug);
+      if (matched) {
+        return this.generateTargetMatrix(domain, [matched], options)[0];
+      }
+    }
+    const integPrefix = this.getPrefix("integration", lang).replace(/^\//, "");
+    if (segments[0] === integPrefix && segments[1] && data.integrations) {
+      const integSlug = segments[1];
+      const matched = data.integrations.find((i) => cleanSeoSlug(i.slug, { language: lang }) === integSlug || i.slug === integSlug);
+      if (matched) {
+        return this.generateIntegrationMatrix(domain, [matched], options)[0];
+      }
+    }
+    const useCasePrefix = this.getPrefix("useCase", lang).replace(/^\//, "");
+    if (segments[0] === useCasePrefix && segments[1] && data.useCases) {
+      const ucSlug = segments[1];
+      const matched = data.useCases.find((u) => cleanSeoSlug(u.slug, { language: lang }) === ucSlug || u.slug === ucSlug);
+      if (matched) {
+        return this.generateUseCaseMatrix(domain, [matched], options)[0];
+      }
+    }
+    const templatePrefix = this.getPrefix("template", lang).replace(/^\//, "");
+    if (segments[0] === templatePrefix && segments[1] && data.templates) {
+      const tSlug = segments[1];
+      const matched = data.templates.find((t) => cleanSeoSlug(t.slug, { language: lang }) === tSlug || t.slug === tSlug);
+      if (matched) {
+        return this.generateTemplateMatrix(domain, [matched], options)[0];
+      }
+    }
+    const glossaryPrefix = this.getPrefix("glossary", lang).replace(/^\//, "");
+    if (segments[0] === glossaryPrefix && segments[1] && data.glossaryTerms) {
+      const gSlug = segments[1];
+      const matched = data.glossaryTerms.find((g) => cleanSeoSlug(g.slug, { language: lang }) === gSlug || g.slug === gSlug);
+      if (matched) {
+        return this.generateGlossaryMatrix(domain, [matched], options)[0];
+      }
+    }
+    const calcPrefix = this.getPrefix("calculator", lang).replace(/^\//, "");
+    if (segments[0] === calcPrefix && segments[1] && data.calculators) {
+      const cSlug = segments[1];
+      const matched = data.calculators.find((c) => cleanSeoSlug(c.slug, { language: lang }) === cSlug || c.slug === cSlug);
+      if (matched) {
+        return this.generateCalculatorMatrix(domain, [matched], options)[0];
+      }
+    }
+    if (data.services && data.services.length > 0) {
+      let serviceSlug = "";
+      let locationSlug = "";
+      if (segments.length === 2 && options.cleanDirectRoutes !== false) {
+        serviceSlug = segments[0];
+        locationSlug = segments[1];
+      } else if (segments.length >= 3 && segments[0] === this.getPrefix("solutions", lang).replace(/^\//, "")) {
+        serviceSlug = segments[1];
+        locationSlug = segments[segments.length - 1];
+      }
+      if (serviceSlug && locationSlug) {
+        const matchedService = data.services.find((s) => cleanSeoSlug(s.slug, { language: lang }) === serviceSlug || s.slug === serviceSlug);
+        if (matchedService) {
+          let resolvedLoc = (data.locations || []).find((l) => cleanSeoSlug(l.slug, { language: lang }) === locationSlug || l.slug === locationSlug);
+          if (!resolvedLoc) {
+            const countryList = options.allowedCountries || options.countries;
+            const fallbackCountry = Array.isArray(countryList) ? countryList[0] : typeof countryList === "string" && countryList !== "international" ? countryList : "United States";
+            resolvedLoc = createDynamicLocation(locationSlug, fallbackCountry, {
+              currency: options.defaultCurrency,
+              currencySymbol: options.defaultCurrencySymbol
+            });
+            if (options.strictCountryBoundary && countryList) {
+              const allowed = (Array.isArray(countryList) ? countryList : [countryList]).map((c) => c.toLowerCase());
+              if (!allowed.includes("international") && !allowed.some((c) => resolvedLoc.country.toLowerCase().includes(c))) {
+                return;
+              }
+            }
           }
+          const dynamicPages = this.generateLocalGeoMatrix(domain, [matchedService], [resolvedLoc], options);
+          return dynamicPages[0];
         }
-        const dynamicPages = this.generateLocalGeoMatrix(domain, [matchedService], [dynamicLoc], options);
-        return dynamicPages.find((p) => p.urlPath === path) || dynamicPages[0];
       }
     }
     return;
@@ -5045,7 +5130,20 @@ When discovering product modules, features, or services to build the SEO matrice
 
 ---
 
-### \uD83C\uDF10 2. ARCHITECTURAL RULE: THE WEBSITE OWNS ITS LANGUAGES (i18n)
+### \uD83D\uDEA8 2. CRITICAL RULE: ZERO STATIC PRE-COMPILATION AT BUILD TIME (PURE RUNTIME ON-DEMAND)
+
+- **❌ NEVER PRE-COMPILE CITIES OR PAGES AT BUILD TIME (\`generateStaticParams\` / \`getStaticPaths\`):**
+  - DO NOT create static loops over 365, 61, or any hardcoded list of cities during \`next build\`.
+  - DO NOT freeze pages into static HTML files on disk. That is NOT how high-scale programmatic SEO works.
+  - Doing so breaks infinite dynamic expansion, causes build memory crashes, and falsely caps the website to a tiny subset of pages.
+- **✅ ALWAYS USE 100% RUNTIME IN-MEMORY RESOLUTION (\`resolvePage\`):**
+  - In Next.js App Router: Always set \`export const dynamic = "force-dynamic"\` and \`export const dynamicParams = true\`.
+  - When an incoming request arrives (e.g. \`/solutions/ac-repair/austin\`, \`/solutions/ac-repair/paris\`, \`/solutions/ac-repair/90210\`), the server executes \`matrixEngine.resolvePage([service, location], ...)\` in RAM in \`< 0.05ms\`.
+  - Build time remains **under 3 seconds** because 0 localized landing pages are built ahead of time. Every page is synthesized on demand.
+
+---
+
+### \uD83C\uDF10 3. ARCHITECTURAL RULE: THE WEBSITE OWNS ITS LANGUAGES (i18n)
 
 - **The Website (Application) is the sole owner of its languages, routes, and translations:**
   - The website provides its own localized routes (e.g. \`app/[locale]/[...slug]/page.tsx\`) and dictionary files (\`next-intl\`, \`i18next\`, Astro i18n).
@@ -5308,7 +5406,7 @@ The SDK equips applications with 9 enterprise-grade SEO engines:
    - Boosts dwell time, organic backlinks, and visitor-to-customer conversion.
 
 8. **\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\`.
+   - \`buildAggregateRating\` (Verified live reviews synced from Google Places / Trustpilot / WooCommerce), \`buildAggregateOffer\` (price ranges), \`buildLocalBusiness\` (GPS & opening hours), \`buildSoftwareApplication\`, \`buildHowTo\`, \`buildFAQPage\`, \`buildBreadcrumbs\`.
 
 9. **\uD83D\uDD0D URL Decomposition & Analysis (\`UrlyticsEngine\`):**
    - Deep structural directory decomposition, depth tracking, query parameter analysis, and slug tokenization (inspired by advertools).
@@ -9457,6 +9555,114 @@ class MarketingSkillsEngine {
   }
 }
 
+// src/generation-tracker.ts
+class PageRegenerationTracker {
+  records = new Map;
+  demandSignals = new Map;
+  recordGeneration(params) {
+    const key = params.urlPath.trim().toLowerCase();
+    const existing = this.records.get(key);
+    const now = new Date().toISOString();
+    const country = params.country || existing?.country || "United States";
+    const language = params.language || existing?.language || "en";
+    const service = params.service || existing?.service || "General Service";
+    const location = params.location || existing?.location || "National";
+    const mode = params.mode || "standard";
+    const tokens = params.tokensConsumed || 0;
+    if (existing) {
+      existing.generationCount += 1;
+      existing.mode = mode;
+      existing.tokensConsumed += tokens;
+      existing.lastGeneratedAt = now;
+      this.records.set(key, existing);
+      return existing;
+    }
+    const newRecord = {
+      urlPath: key,
+      service,
+      location,
+      country,
+      language,
+      generationCount: 1,
+      mode,
+      tokensConsumed: tokens,
+      firstGeneratedAt: now,
+      lastGeneratedAt: now
+    };
+    this.records.set(key, newRecord);
+    const countryKey = country.toLowerCase();
+    const currentSignal = this.demandSignals.get(countryKey) || { requests: 0, country };
+    currentSignal.requests += 1;
+    this.demandSignals.set(countryKey, currentSignal);
+    return newRecord;
+  }
+  recordMarketDemand(country, requestVolume = 1) {
+    const countryKey = country.trim().toLowerCase();
+    const current = this.demandSignals.get(countryKey) || { requests: 0, country };
+    current.requests += requestVolume;
+    this.demandSignals.set(countryKey, current);
+  }
+  getMetricsReport() {
+    let singleGen = 0;
+    let doubleGen = 0;
+    let multiGen = 0;
+    let standardCount = 0;
+    let aiCount = 0;
+    let totalTokens = 0;
+    const countriesSet = new Set;
+    const countryPageCounts = new Map;
+    for (const record of this.records.values()) {
+      if (record.generationCount === 1)
+        singleGen++;
+      else if (record.generationCount === 2)
+        doubleGen++;
+      else
+        multiGen++;
+      if (record.mode === "ai-enhanced") {
+        aiCount++;
+        totalTokens += record.tokensConsumed;
+      } else {
+        standardCount++;
+      }
+      countriesSet.add(record.country);
+      const cKey = record.country.toLowerCase();
+      countryPageCounts.set(cKey, (countryPageCounts.get(cKey) || 0) + 1);
+    }
+    const marketOpportunities = [];
+    for (const [countryKey, signal] of this.demandSignals.entries()) {
+      const indexedPages = countryPageCounts.get(countryKey) || 0;
+      const countryFormatted = signal.country.charAt(0).toUpperCase() + signal.country.slice(1);
+      if (signal.requests > 100 && indexedPages < 20) {
+        marketOpportunities.push({
+          country: countryFormatted,
+          countryCode: countryKey.slice(0, 2).toUpperCase(),
+          detectedRequests: signal.requests,
+          activeIndexedPages: indexedPages,
+          coverageStatus: "opportunity_detected",
+          estimatedMonthlyTrafficUpside: Math.round(signal.requests * 3.4),
+          recommendation: `High demand detected in ${countryFormatted} (${signal.requests} hits). Upgrade to Pro Growth or activate ${countryFormatted} in SEO_CONFIG to capture +${Math.round(signal.requests * 3.4)} visits/month.`
+        });
+      }
+    }
+    return {
+      uniquePagesCount: this.records.size,
+      totalGenerationCycles: singleGen + doubleGen * 2 + multiGen * 3,
+      regenerationFrequency: {
+        singleGeneration: singleGen,
+        doubleGeneration: doubleGen,
+        multiGeneration: multiGen
+      },
+      modeDistribution: {
+        standardDeterministicCount: standardCount,
+        aiEnhancedCount: aiCount
+      },
+      totalAiTokensConsumed: totalTokens,
+      activeCountriesCount: countriesSet.size,
+      marketOpportunities
+    };
+  }
+}
+
 // src/index.ts
 function createLynxSeoEngine(config) {
   return new LynxSeoEngine(config);
@@ -9506,7 +9712,8 @@ var LynxSeo = {
   translator: LynxRateLimitedTranslator,
   pageRankGraph: InternalPageRankEngine,
   geoCitation: GeoCitationScorer,
-  marketingSkills: MarketingSkillsEngine
+  marketingSkills: MarketingSkillsEngine,
+  regenerationTracker: PageRegenerationTracker
 };
 var src_default = LynxSeo;
 export {
@@ -9546,6 +9753,7 @@ export {
   PublicRoutesManifestEngine,
   PseoMatrixEngine,
   PowerWordsPsychologyEngine,
+  PageRegenerationTracker,
   PSEO_AGENT_SYSTEM_PROMPT,
   OgImageGenerator,
   NGramDensityAnalyzer,

package/dist/index.mjs

@@ -3787,7 +3787,7 @@ class PseoMatrixEngine {
             ])
           ]
         };
-        pages.push({
+        const pageItem = {
           matrixFamily: "local-geo",
           urlPath,
           canonicalUrl: fullUrl,
@@ -3799,7 +3799,9 @@ class PseoMatrixEngine {
           neighboringLinks: neighborLinks,
           service: s,
           location: loc
-        });
+        };
+        pageItem.ogImageUrl = OgImageGenerator.generateOgImageUrl(cleanDomain, pageItem, options.brandName);
+        pages.push(pageItem);
       }
     }
     return pages;
@@ -4145,7 +4147,7 @@ class PseoMatrixEngine {
   generateAllMatrices(domain, data, options) {
     const allPages = [];
     if (data.services) {
-      const locs = data.locations && data.locations.length > 0 ? data.locations : resolveBuiltInLocations(options.countries || options.territories || options.language || "fr");
+      const locs = data.locations && data.locations.length > 0 ? data.locations : resolveBuiltInLocations(options.allowedCountries || options.countries || options.territories || "us");
       allPages.push(...this.generateLocalGeoMatrix(domain, data.services, locs, options));
     }
     if (data.competitors) {
@@ -4212,30 +4214,113 @@ class PseoMatrixEngine {
   }
   resolvePage(slugOrPath, domain, data, options) {
     const path = typeof slugOrPath === "string" ? slugOrPath.startsWith("/") ? slugOrPath : `/${slugOrPath}` : `/${slugOrPath.join("/")}`;
-    const pages = this.generateAllMatrices(domain, data, options);
-    const existing = pages.find((p) => p.urlPath === path);
-    if (existing)
-      return existing;
+    const lang = options.language || "en";
     const segments = path.split("/").filter(Boolean);
-    if (segments.length >= 2 && data.services && data.services.length > 0) {
-      const serviceSlug = segments[0];
-      const locationSlug = segments[segments.length - 1];
-      const matchedService = data.services.find((s) => cleanSeoSlug(s.slug, { language: options.language }) === serviceSlug || s.slug === serviceSlug);
-      if (matchedService) {
-        const countryList = options.allowedCountries || options.countries;
-        const fallbackCountry = Array.isArray(countryList) ? countryList[0] : typeof countryList === "string" && countryList !== "international" ? countryList : "United States";
-        const dynamicLoc = createDynamicLocation(locationSlug, fallbackCountry, {
-          currency: options.defaultCurrency,
-          currencySymbol: options.defaultCurrencySymbol
-        });
-        if (options.strictCountryBoundary && countryList) {
-          const allowed = (Array.isArray(countryList) ? countryList : [countryList]).map((c) => c.toLowerCase());
-          if (!allowed.includes("international") && !allowed.some((c) => dynamicLoc.country.toLowerCase().includes(c))) {
-            return;
+    if (segments.length === 0)
+      return;
+    const vsPrefix = this.getPrefix("vs", lang).replace(/^\//, "");
+    if (segments[0] === vsPrefix && segments[1] && data.competitors) {
+      const compSlug = segments[1];
+      const matched = data.competitors.find((c) => cleanSeoSlug(c.slug, { language: lang }) === compSlug || c.slug === compSlug);
+      if (matched) {
+        return this.generateVsMatrix(domain, [matched], options)[0];
+      }
+    }
+    const altPrefix = this.getPrefix("alternative", lang).replace(/^\//, "");
+    if (segments[0] === altPrefix && segments[1] && data.competitors) {
+      const compSlug = segments[1];
+      const matched = data.competitors.find((c) => cleanSeoSlug(c.slug, { language: lang }) === compSlug || c.slug === compSlug);
+      if (matched) {
+        return this.generateAlternativesMatrix(domain, [matched], options)[0];
+      }
+    }
+    const pricingPrefix = this.getPrefix("pricing", lang).replace(/^\//, "");
+    if (segments[0] === pricingPrefix && segments[1] && data.competitors) {
+      const compSlug = segments[1];
+      const matched = data.competitors.find((c) => cleanSeoSlug(c.slug, { language: lang }) === compSlug || c.slug === compSlug);
+      if (matched) {
+        return this.generatePricingMatrix(domain, [matched], options)[0];
+      }
+    }
+    const targetPrefix = this.getPrefix("target", lang).replace(/^\//, "");
+    if (segments[0] === targetPrefix && segments[1] && data.targets) {
+      const targetSlug = segments[1];
+      const matched = data.targets.find((t) => cleanSeoSlug(t.slug, { language: lang }) === targetSlug || t.slug === targetSlug);
+      if (matched) {
+        return this.generateTargetMatrix(domain, [matched], options)[0];
+      }
+    }
+    const integPrefix = this.getPrefix("integration", lang).replace(/^\//, "");
+    if (segments[0] === integPrefix && segments[1] && data.integrations) {
+      const integSlug = segments[1];
+      const matched = data.integrations.find((i) => cleanSeoSlug(i.slug, { language: lang }) === integSlug || i.slug === integSlug);
+      if (matched) {
+        return this.generateIntegrationMatrix(domain, [matched], options)[0];
+      }
+    }
+    const useCasePrefix = this.getPrefix("useCase", lang).replace(/^\//, "");
+    if (segments[0] === useCasePrefix && segments[1] && data.useCases) {
+      const ucSlug = segments[1];
+      const matched = data.useCases.find((u) => cleanSeoSlug(u.slug, { language: lang }) === ucSlug || u.slug === ucSlug);
+      if (matched) {
+        return this.generateUseCaseMatrix(domain, [matched], options)[0];
+      }
+    }
+    const templatePrefix = this.getPrefix("template", lang).replace(/^\//, "");
+    if (segments[0] === templatePrefix && segments[1] && data.templates) {
+      const tSlug = segments[1];
+      const matched = data.templates.find((t) => cleanSeoSlug(t.slug, { language: lang }) === tSlug || t.slug === tSlug);
+      if (matched) {
+        return this.generateTemplateMatrix(domain, [matched], options)[0];
+      }
+    }
+    const glossaryPrefix = this.getPrefix("glossary", lang).replace(/^\//, "");
+    if (segments[0] === glossaryPrefix && segments[1] && data.glossaryTerms) {
+      const gSlug = segments[1];
+      const matched = data.glossaryTerms.find((g) => cleanSeoSlug(g.slug, { language: lang }) === gSlug || g.slug === gSlug);
+      if (matched) {
+        return this.generateGlossaryMatrix(domain, [matched], options)[0];
+      }
+    }
+    const calcPrefix = this.getPrefix("calculator", lang).replace(/^\//, "");
+    if (segments[0] === calcPrefix && segments[1] && data.calculators) {
+      const cSlug = segments[1];
+      const matched = data.calculators.find((c) => cleanSeoSlug(c.slug, { language: lang }) === cSlug || c.slug === cSlug);
+      if (matched) {
+        return this.generateCalculatorMatrix(domain, [matched], options)[0];
+      }
+    }
+    if (data.services && data.services.length > 0) {
+      let serviceSlug = "";
+      let locationSlug = "";
+      if (segments.length === 2 && options.cleanDirectRoutes !== false) {
+        serviceSlug = segments[0];
+        locationSlug = segments[1];
+      } else if (segments.length >= 3 && segments[0] === this.getPrefix("solutions", lang).replace(/^\//, "")) {
+        serviceSlug = segments[1];
+        locationSlug = segments[segments.length - 1];
+      }
+      if (serviceSlug && locationSlug) {
+        const matchedService = data.services.find((s) => cleanSeoSlug(s.slug, { language: lang }) === serviceSlug || s.slug === serviceSlug);
+        if (matchedService) {
+          let resolvedLoc = (data.locations || []).find((l) => cleanSeoSlug(l.slug, { language: lang }) === locationSlug || l.slug === locationSlug);
+          if (!resolvedLoc) {
+            const countryList = options.allowedCountries || options.countries;
+            const fallbackCountry = Array.isArray(countryList) ? countryList[0] : typeof countryList === "string" && countryList !== "international" ? countryList : "United States";
+            resolvedLoc = createDynamicLocation(locationSlug, fallbackCountry, {
+              currency: options.defaultCurrency,
+              currencySymbol: options.defaultCurrencySymbol
+            });
+            if (options.strictCountryBoundary && countryList) {
+              const allowed = (Array.isArray(countryList) ? countryList : [countryList]).map((c) => c.toLowerCase());
+              if (!allowed.includes("international") && !allowed.some((c) => resolvedLoc.country.toLowerCase().includes(c))) {
+                return;
+              }
+            }
           }
+          const dynamicPages = this.generateLocalGeoMatrix(domain, [matchedService], [resolvedLoc], options);
+          return dynamicPages[0];
         }
-        const dynamicPages = this.generateLocalGeoMatrix(domain, [matchedService], [dynamicLoc], options);
-        return dynamicPages.find((p) => p.urlPath === path) || dynamicPages[0];
       }
     }
     return;
@@ -5045,7 +5130,20 @@ When discovering product modules, features, or services to build the SEO matrice
 
 ---
 
-### \uD83C\uDF10 2. ARCHITECTURAL RULE: THE WEBSITE OWNS ITS LANGUAGES (i18n)
+### \uD83D\uDEA8 2. CRITICAL RULE: ZERO STATIC PRE-COMPILATION AT BUILD TIME (PURE RUNTIME ON-DEMAND)
+
+- **❌ NEVER PRE-COMPILE CITIES OR PAGES AT BUILD TIME (\`generateStaticParams\` / \`getStaticPaths\`):**
+  - DO NOT create static loops over 365, 61, or any hardcoded list of cities during \`next build\`.
+  - DO NOT freeze pages into static HTML files on disk. That is NOT how high-scale programmatic SEO works.
+  - Doing so breaks infinite dynamic expansion, causes build memory crashes, and falsely caps the website to a tiny subset of pages.
+- **✅ ALWAYS USE 100% RUNTIME IN-MEMORY RESOLUTION (\`resolvePage\`):**
+  - In Next.js App Router: Always set \`export const dynamic = "force-dynamic"\` and \`export const dynamicParams = true\`.
+  - When an incoming request arrives (e.g. \`/solutions/ac-repair/austin\`, \`/solutions/ac-repair/paris\`, \`/solutions/ac-repair/90210\`), the server executes \`matrixEngine.resolvePage([service, location], ...)\` in RAM in \`< 0.05ms\`.
+  - Build time remains **under 3 seconds** because 0 localized landing pages are built ahead of time. Every page is synthesized on demand.
+
+---
+
+### \uD83C\uDF10 3. ARCHITECTURAL RULE: THE WEBSITE OWNS ITS LANGUAGES (i18n)
 
 - **The Website (Application) is the sole owner of its languages, routes, and translations:**
   - The website provides its own localized routes (e.g. \`app/[locale]/[...slug]/page.tsx\`) and dictionary files (\`next-intl\`, \`i18next\`, Astro i18n).
@@ -5308,7 +5406,7 @@ The SDK equips applications with 9 enterprise-grade SEO engines:
    - Boosts dwell time, organic backlinks, and visitor-to-customer conversion.
 
 8. **\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\`.
+   - \`buildAggregateRating\` (Verified live reviews synced from Google Places / Trustpilot / WooCommerce), \`buildAggregateOffer\` (price ranges), \`buildLocalBusiness\` (GPS & opening hours), \`buildSoftwareApplication\`, \`buildHowTo\`, \`buildFAQPage\`, \`buildBreadcrumbs\`.
 
 9. **\uD83D\uDD0D URL Decomposition & Analysis (\`UrlyticsEngine\`):**
    - Deep structural directory decomposition, depth tracking, query parameter analysis, and slug tokenization (inspired by advertools).
@@ -9457,6 +9555,114 @@ class MarketingSkillsEngine {
   }
 }
 
+// src/generation-tracker.ts
+class PageRegenerationTracker {
+  records = new Map;
+  demandSignals = new Map;
+  recordGeneration(params) {
+    const key = params.urlPath.trim().toLowerCase();
+    const existing = this.records.get(key);
+    const now = new Date().toISOString();
+    const country = params.country || existing?.country || "United States";
+    const language = params.language || existing?.language || "en";
+    const service = params.service || existing?.service || "General Service";
+    const location = params.location || existing?.location || "National";
+    const mode = params.mode || "standard";
+    const tokens = params.tokensConsumed || 0;
+    if (existing) {
+      existing.generationCount += 1;
+      existing.mode = mode;
+      existing.tokensConsumed += tokens;
+      existing.lastGeneratedAt = now;
+      this.records.set(key, existing);
+      return existing;
+    }
+    const newRecord = {
+      urlPath: key,
+      service,
+      location,
+      country,
+      language,
+      generationCount: 1,
+      mode,
+      tokensConsumed: tokens,
+      firstGeneratedAt: now,
+      lastGeneratedAt: now
+    };
+    this.records.set(key, newRecord);
+    const countryKey = country.toLowerCase();
+    const currentSignal = this.demandSignals.get(countryKey) || { requests: 0, country };
+    currentSignal.requests += 1;
+    this.demandSignals.set(countryKey, currentSignal);
+    return newRecord;
+  }
+  recordMarketDemand(country, requestVolume = 1) {
+    const countryKey = country.trim().toLowerCase();
+    const current = this.demandSignals.get(countryKey) || { requests: 0, country };
+    current.requests += requestVolume;
+    this.demandSignals.set(countryKey, current);
+  }
+  getMetricsReport() {
+    let singleGen = 0;
+    let doubleGen = 0;
+    let multiGen = 0;
+    let standardCount = 0;
+    let aiCount = 0;
+    let totalTokens = 0;
+    const countriesSet = new Set;
+    const countryPageCounts = new Map;
+    for (const record of this.records.values()) {
+      if (record.generationCount === 1)
+        singleGen++;
+      else if (record.generationCount === 2)
+        doubleGen++;
+      else
+        multiGen++;
+      if (record.mode === "ai-enhanced") {
+        aiCount++;
+        totalTokens += record.tokensConsumed;
+      } else {
+        standardCount++;
+      }
+      countriesSet.add(record.country);
+      const cKey = record.country.toLowerCase();
+      countryPageCounts.set(cKey, (countryPageCounts.get(cKey) || 0) + 1);
+    }
+    const marketOpportunities = [];
+    for (const [countryKey, signal] of this.demandSignals.entries()) {
+      const indexedPages = countryPageCounts.get(countryKey) || 0;
+      const countryFormatted = signal.country.charAt(0).toUpperCase() + signal.country.slice(1);
+      if (signal.requests > 100 && indexedPages < 20) {
+        marketOpportunities.push({
+          country: countryFormatted,
+          countryCode: countryKey.slice(0, 2).toUpperCase(),
+          detectedRequests: signal.requests,
+          activeIndexedPages: indexedPages,
+          coverageStatus: "opportunity_detected",
+          estimatedMonthlyTrafficUpside: Math.round(signal.requests * 3.4),
+          recommendation: `High demand detected in ${countryFormatted} (${signal.requests} hits). Upgrade to Pro Growth or activate ${countryFormatted} in SEO_CONFIG to capture +${Math.round(signal.requests * 3.4)} visits/month.`
+        });
+      }
+    }
+    return {
+      uniquePagesCount: this.records.size,
+      totalGenerationCycles: singleGen + doubleGen * 2 + multiGen * 3,
+      regenerationFrequency: {
+        singleGeneration: singleGen,
+        doubleGeneration: doubleGen,
+        multiGeneration: multiGen
+      },
+      modeDistribution: {
+        standardDeterministicCount: standardCount,
+        aiEnhancedCount: aiCount
+      },
+      totalAiTokensConsumed: totalTokens,
+      activeCountriesCount: countriesSet.size,
+      marketOpportunities
+    };
+  }
+}
+
 // src/index.ts
 function createLynxSeoEngine(config) {
   return new LynxSeoEngine(config);
@@ -9506,7 +9712,8 @@ var LynxSeo = {
   translator: LynxRateLimitedTranslator,
   pageRankGraph: InternalPageRankEngine,
   geoCitation: GeoCitationScorer,
-  marketingSkills: MarketingSkillsEngine
+  marketingSkills: MarketingSkillsEngine,
+  regenerationTracker: PageRegenerationTracker
 };
 var src_default = LynxSeo;
 export {
@@ -9546,6 +9753,7 @@ export {
   PublicRoutesManifestEngine,
   PseoMatrixEngine,
   PowerWordsPsychologyEngine,
+  PageRegenerationTracker,
   PSEO_AGENT_SYSTEM_PROMPT,
   OgImageGenerator,
   NGramDensityAnalyzer,

package/package.json

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