@lynxflow/seo-engine 2.0.0 → 2.1.0

package/README.md

@@ -1,18 +1,19 @@
 # @lynxflow/seo-engine
 
-High-Performance Programmatic SEO & Structured Data Engine for Modern Web Applications.
+High-Performance Universal Programmatic SEO & Structured Data Engine for Modern Web Applications.
 
 [![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)](package.json)
+[![Version](https://img.shields.io/badge/Version-2.1.0-orange.svg)](https://www.npmjs.com/package/@lynxflow/seo-engine)
 
 ---
 
 ## Overview
 
-`@lynxflow/seo-engine` is an enterprise developer SDK providing in-memory programmatic SEO matrix generation, Google-compliant Schema.org structured data, infinite geographic location synthesis, and real-time GeoIP Edge detection worldwide.
+`@lynxflow/seo-engine` is an enterprise developer SDK providing in-memory programmatic SEO matrix generation, Google-compliant Schema.org structured data, infinite geographic location synthesis, strict market boundaries, and real-time GeoIP Edge detection worldwide.
 
 * **10 Canonical Root Pillars & 50+ Specialized Sub-Matrices:** Scales across industries, regulatory frameworks, role KPIs, multi-format templates, integration ecosystems, and ROI tools.
+* **Strict Geographic & Linguistic Scoping:** Easily lock your website to a single country (e.g. 100% US or 100% France) or expand globally across multiple languages and territories with `strictCountryBoundary`.
 * **In-Memory Dynamic Execution:** Resolves millions of programmatic routes in RAM with zero database query overhead and zero MySQL/Postgres saturation.
 * **Infinite Geographic Resolution (`createDynamicLocation`):** Dynamically synthesizes any municipality, county, state, or postal code worldwide (e.g. `austin`, `scottsdale`, `75015`, `90210`, `ec1a-1bb`, `shinjuku`) on the fly without 404 errors.
 * **Edge GeoIP Location Detection (`resolveLocationFromHeaders`):** Reads Cloudflare (`cf-ipcity`, `cf-postal-code`), Vercel, AWS CloudFront, and Nginx edge headers to adapt pages to the visitor's real-time location.
@@ -34,33 +35,36 @@ bun add @lynxflow/seo-engine
 
 ---
 
-## Core Matrix Architecture
+## Market Scoping: Single Country vs. Global Multi-Country
 
-The SDK structures programmatic content across **10 canonical root pillars** expanding into **50+ specialized sub-matrices**:
+### Option 1: 100% US-Only or Local Single-Country Website
+Prevent crawl waste on out-of-scope foreign locations by enabling `strictCountryBoundary`:
 
+```typescript
+export const SEO_CONFIG = {
+  brandName: "LoneStar HVAC Pro",
+  languages: ["en"],
+  countries: ["united-states"],
+  strictCountryBoundary: true, // 🛡️ Rejects non-US locations
+  defaultCurrency: "USD",
+  defaultCurrencySymbol: "$",
+};
 ```
-┌──────────────────────────────────────┬────────────────────────┬────────────────────────────────────────────────────────┐
-│ CANONICAL ROOT PILLAR                │ SPECIALIZED DIMENSIONS │ HIGH-INTENT EXAMPLES                                   │
-├──────────────────────────────────────┼────────────────────────┼────────────────────────────────────────────────────────┤
-│ 👥 /for/{target}                     │ 12 Sub-Matrices        │ Sector × Regulatory Compliance, Role × Daily KPIs      │
-│ 🔌 /integrations/{app}               │ 10 Sub-Matrices        │ App Connector × Real-Time Webhook, Bi-Directional Sync │
-│ 📑 /templates/{slug}                 │ 8 Sub-Matrices         │ Subject × Format (Excel, Notion, Google Sheets, PDF)   │
-│ 🎯 /use-cases/{useCase}              │ 8 Sub-Matrices         │ Operational Pain Point × Step-by-Step Playbook         │
-│ 🧮 /tools/{calculator}               │ 6 Sub-Matrices         │ Hours Saved Estimator, Revenue Uplift Simulator        │
-│ 📚 /glossary/{term}                  │ 6 Sub-Matrices         │ Financial Metrics (MRR/LTV), Technical Protocols (API) │
-│ 🥊 /vs/{competitor}                  │ Optional / Modular     │ Architectural Comparison & Differences                 │
-│ 🔄 /alternatives/{competitor}        │ Optional / Modular     │ Clean Canonical Migration Guides                       │
-│ 💰 /pricing/{competitor}             │ Optional / Modular     │ Transparent Plan Breakdown & Verified Disclaimers      │
-│ 📍 /solutions/{service}/{city}       │ Local Geo Matrix       │ Tiered Indexing (Crawl Budget) & Geodesic Mesh Links   │
-└──────────────────────────────────────┴────────────────────────┴────────────────────────────────────────────────────────┘
+
+### Option 2: Worldwide Multi-Country / Multi-Lingual SaaS
+```typescript
+export const SEO_CONFIG = {
+  brandName: "Apex Global Cloud",
+  languages: ["en", "de", "es", "fr", "ja", "pt-BR"],
+  countries: ["united-states", "united-kingdom", "germany", "france", "japan"],
+  strictCountryBoundary: false, // Allows worldwide expansion
+};
 ```
 
 ---
 
 ## Quickstart & Contrasting Examples
 
-> **Important Note:** All examples below are **non-limiting illustrations**. You can pass any arbitrary language code and any arbitrary city or postal code worldwide.
-
 ### 1. Initialize Engine & Dataset
 
 ```typescript
@@ -68,14 +72,6 @@ import { PseoMatrixEngine } from "@lynxflow/seo-engine";
 
 export const matrixEngine = new PseoMatrixEngine();
 
-// Non-limiting example configuration (Supports ANY country or locale)
-export const SEO_CONFIG = {
-  brandName: "Apex Global",
-  languages: ["en", "de", "es", "fr", "ja", "pt-BR"], // Any ISO-639-1 / BCP-47 locale
-  countries: ["united-states", "united-kingdom", "germany", "japan"], // Or "international" / any country
-  cleanDirectRoutes: true,
-};
-
 export const PSEO_DATASET = {
   services: [
     { 
@@ -93,10 +89,6 @@ export const PSEO_DATASET = {
       description: "Continuous enterprise backup and disaster recovery" 
     },
   ],
-  targets: [
-    { slug: "enterprises", name: "Enterprise Organizations", type: "b2b", painPoints: ["Downtime Risk"], benefits: ["99.99% SLA"] },
-    { slug: "healthcare", name: "Healthcare Providers", type: "industry", painPoints: ["HIPAA Compliance"], benefits: ["Audit-Ready Storage"] }
-  ],
 };
 ```
 
@@ -104,11 +96,10 @@ export const PSEO_DATASET = {
 
 ```typescript
 // Case 1: Standard Pre-Indexed City in English
-const pageStandard = matrixEngine.resolvePage(["commercial-hvac", "london"], "https://example.com", PSEO_DATASET, SEO_CONFIG);
+const pageStandard = matrixEngine.resolvePage(["commercial-hvac", "new-york"], "https://example.com", PSEO_DATASET, SEO_CONFIG);
 
-// Case 2: Contrasting Case — Arbitrary Postal Code / Custom District in Japanese
+// Case 2: Contrasting Case — Arbitrary Postal Code / Custom District
 const pageCustom = matrixEngine.resolvePage(["commercial-hvac", "90210"], "https://example.com", PSEO_DATASET, SEO_CONFIG);
-const pageJapanese = matrixEngine.resolvePage(["ja", "commercial-hvac", "shinjuku"], "https://example.com", PSEO_DATASET, SEO_CONFIG);
 ```
 
 ### 3. Edge GeoIP Resolution Example
@@ -118,7 +109,6 @@ import { resolveLocationFromHeaders, PseoMatrixEngine } from "@lynxflow/seo-engi
 
 export function handleIncomingRequest(request: Request) {
   const geo = resolveLocationFromHeaders(request.headers);
-  // Extracted dynamically from Cloudflare / Vercel / CloudFront headers
   const userCity = geo.city || "new-york";
   
   return matrixEngine.resolvePage(["commercial-hvac", userCity], "https://example.com", PSEO_DATASET, SEO_CONFIG);
@@ -129,11 +119,10 @@ export function handleIncomingRequest(request: Request) {
 
 ## TypeScript API Reference
 
-* **`PseoMatrixEngine`**: Core programmatic matrix compiler across all 10 root pillars and 50+ sub-matrices.
-* **`createDynamicLocation(slugOrInput, fallbackCountry)`**: Dynamic synthesis of any city, postal code or district worldwide at runtime.
+* **`PseoMatrixEngine`**: Core programmatic matrix compiler with geographic boundaries and crawl budget protection.
+* **`createDynamicLocation(slugOrInput, fallbackCountry, options)`**: Dynamic synthesis of any city, postal code or district worldwide.
 * **`resolveLocationFromHeaders(headers)`**: Edge header GeoIP extractor for Cloudflare, Vercel, CloudFront, and Nginx.
 * **`cleanSeoSlug(text, options)`**: Multilingual slug normalizer with stop-word removal for 10+ languages.
-* **`validateSeoSlug(slug)`**: Strict slug validator.
 * **`ExtendedSchemaGraphBuilder`**: 50+ Google Rich Result Schema.org JSON-LD generator.
 * **`LegalDisclaimerEngine`**: Verified compliance notice manager with staleness guards (>90 days).
 * **`getSeoAgentPrompt(context)`**: Built-in LLM operational prompt for AI coding agents.

package/dist/built-in-locations.d.ts

@@ -15,7 +15,11 @@ export declare function resolveBuiltInLocations(territories?: string[] | string)
  * Allows resolving ANY unlisted city, commune, district, or postal code dynamically on demand
  * without returning 404 or requiring hardcoded databases.
  */
-export declare function createDynamicLocation(slugOrInput: string, fallbackCountry?: string): PseoLocation;
+export declare function createDynamicLocation(slugOrInput: string, fallbackCountry?: string, options?: {
+    currency?: string;
+    currencySymbol?: string;
+    region?: string;
+}): PseoLocation;
 /**
  * 📍 GeoIP Edge Headers Resolver (Dynamic User Geolocation)
  * Extracts the user's real-time city and country from Cloudflare / Vercel / Nginx Edge headers.

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

@@ -3524,26 +3524,43 @@ function resolveBuiltInLocations(territories) {
       }
     }
   }
-  return results.length > 0 ? results : [...BUILT_IN_LOCATIONS_DATABASE.fr];
+  return results.length > 0 ? results : [...BUILT_IN_LOCATIONS_DATABASE.us];
 }
-function createDynamicLocation(slugOrInput, fallbackCountry = "France") {
+function createDynamicLocation(slugOrInput, fallbackCountry = "United States", options) {
   const cleanInput = slugOrInput.trim().toLowerCase();
   const slug = cleanInput.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   const formattedName = slug.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
-  const isPostalCode = /^\d{4,5}$/.test(cleanInput);
-  const displayName = isPostalCode ? `Secteur ${cleanInput}` : formattedName;
-  const isUS = fallbackCountry.toLowerCase().includes("us") || fallbackCountry.toLowerCase().includes("state");
-  const isUK = fallbackCountry.toLowerCase().includes("uk") || fallbackCountry.toLowerCase().includes("kingdom");
+  const isUsZip = /^\d{5}(-\d{4})?$/.test(cleanInput);
+  const isFrenchPostal = /^\d{5}$/.test(cleanInput) && (fallbackCountry.toLowerCase().includes("fr") || fallbackCountry.toLowerCase().includes("france"));
+  let displayName = formattedName;
+  let regionName = options?.region || "Metropolitan Area";
+  if (isUsZip) {
+    displayName = `Area ${cleanInput}`;
+    regionName = `ZIP Code ${cleanInput}`;
+  } else if (isFrenchPostal) {
+    displayName = `Secteur ${cleanInput}`;
+    regionName = `Département ${cleanInput.slice(0, 2)}`;
+  }
+  const countryLower = fallbackCountry.toLowerCase();
+  const isUS = countryLower.includes("us") || countryLower.includes("state") || countryLower.includes("america");
+  const isUK = countryLower.includes("uk") || countryLower.includes("kingdom") || countryLower.includes("britain");
+  const isJapan = countryLower.includes("japan") || countryLower.includes("jp") || countryLower.includes("tokyo");
+  const isCanada = countryLower.includes("canada") || countryLower.includes("ca");
+  const isAustralia = countryLower.includes("australia") || countryLower.includes("au");
+  const isBrazil = countryLower.includes("brazil") || countryLower.includes("br") || countryLower.includes("brasil");
+  const isSwitzerland = countryLower.includes("switzerland") || countryLower.includes("swiss") || countryLower.includes("ch");
+  const currency = options?.currency || (isUS ? "USD" : isUK ? "GBP" : isJapan ? "JPY" : isCanada ? "CAD" : isAustralia ? "AUD" : isBrazil ? "BRL" : isSwitzerland ? "CHF" : "EUR");
+  const currencySymbol = options?.currencySymbol || (isUS ? "$" : isUK ? "£" : isJapan ? "¥" : isCanada ? "CAD $" : isAustralia ? "AUD $" : isBrazil ? "R$" : isSwitzerland ? "CHF" : "€");
   return {
     slug,
     name: displayName,
-    region: isPostalCode ? `Département ${cleanInput.slice(0, 2)}` : "Région Métropolitaine",
+    region: regionName,
     country: fallbackCountry,
-    currency: isUS ? "USD" : isUK ? "GBP" : "EUR",
-    currencySymbol: isUS ? "$" : isUK ? "£" : "€",
-    population: 45000,
-    latitude: 48.8566,
-    longitude: 2.3522,
+    currency,
+    currencySymbol,
+    population: 50000,
+    latitude: 40.7128,
+    longitude: -74.006,
     neighborSlugs: []
   };
 }
@@ -4205,7 +4222,18 @@ class PseoMatrixEngine {
       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 dynamicLoc = createDynamicLocation(locationSlug, options.countries?.[0] || "France");
+        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;
+          }
+        }
         const dynamicPages = this.generateLocalGeoMatrix(domain, [matchedService], [dynamicLoc], options);
         return dynamicPages.find((p) => p.urlPath === path) || dynamicPages[0];
       }
@@ -9429,6 +9457,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);
@@ -9478,7 +9614,8 @@ var LynxSeo = {
   translator: LynxRateLimitedTranslator,
   pageRankGraph: InternalPageRankEngine,
   geoCitation: GeoCitationScorer,
-  marketingSkills: MarketingSkillsEngine
+  marketingSkills: MarketingSkillsEngine,
+  regenerationTracker: PageRegenerationTracker
 };
 var src_default = LynxSeo;
 export {
@@ -9518,6 +9655,7 @@ export {
   PublicRoutesManifestEngine,
   PseoMatrixEngine,
   PowerWordsPsychologyEngine,
+  PageRegenerationTracker,
   PSEO_AGENT_SYSTEM_PROMPT,
   OgImageGenerator,
   NGramDensityAnalyzer,

package/dist/index.mjs

@@ -3524,26 +3524,43 @@ function resolveBuiltInLocations(territories) {
       }
     }
   }
-  return results.length > 0 ? results : [...BUILT_IN_LOCATIONS_DATABASE.fr];
+  return results.length > 0 ? results : [...BUILT_IN_LOCATIONS_DATABASE.us];
 }
-function createDynamicLocation(slugOrInput, fallbackCountry = "France") {
+function createDynamicLocation(slugOrInput, fallbackCountry = "United States", options) {
   const cleanInput = slugOrInput.trim().toLowerCase();
   const slug = cleanInput.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   const formattedName = slug.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
-  const isPostalCode = /^\d{4,5}$/.test(cleanInput);
-  const displayName = isPostalCode ? `Secteur ${cleanInput}` : formattedName;
-  const isUS = fallbackCountry.toLowerCase().includes("us") || fallbackCountry.toLowerCase().includes("state");
-  const isUK = fallbackCountry.toLowerCase().includes("uk") || fallbackCountry.toLowerCase().includes("kingdom");
+  const isUsZip = /^\d{5}(-\d{4})?$/.test(cleanInput);
+  const isFrenchPostal = /^\d{5}$/.test(cleanInput) && (fallbackCountry.toLowerCase().includes("fr") || fallbackCountry.toLowerCase().includes("france"));
+  let displayName = formattedName;
+  let regionName = options?.region || "Metropolitan Area";
+  if (isUsZip) {
+    displayName = `Area ${cleanInput}`;
+    regionName = `ZIP Code ${cleanInput}`;
+  } else if (isFrenchPostal) {
+    displayName = `Secteur ${cleanInput}`;
+    regionName = `Département ${cleanInput.slice(0, 2)}`;
+  }
+  const countryLower = fallbackCountry.toLowerCase();
+  const isUS = countryLower.includes("us") || countryLower.includes("state") || countryLower.includes("america");
+  const isUK = countryLower.includes("uk") || countryLower.includes("kingdom") || countryLower.includes("britain");
+  const isJapan = countryLower.includes("japan") || countryLower.includes("jp") || countryLower.includes("tokyo");
+  const isCanada = countryLower.includes("canada") || countryLower.includes("ca");
+  const isAustralia = countryLower.includes("australia") || countryLower.includes("au");
+  const isBrazil = countryLower.includes("brazil") || countryLower.includes("br") || countryLower.includes("brasil");
+  const isSwitzerland = countryLower.includes("switzerland") || countryLower.includes("swiss") || countryLower.includes("ch");
+  const currency = options?.currency || (isUS ? "USD" : isUK ? "GBP" : isJapan ? "JPY" : isCanada ? "CAD" : isAustralia ? "AUD" : isBrazil ? "BRL" : isSwitzerland ? "CHF" : "EUR");
+  const currencySymbol = options?.currencySymbol || (isUS ? "$" : isUK ? "£" : isJapan ? "¥" : isCanada ? "CAD $" : isAustralia ? "AUD $" : isBrazil ? "R$" : isSwitzerland ? "CHF" : "€");
   return {
     slug,
     name: displayName,
-    region: isPostalCode ? `Département ${cleanInput.slice(0, 2)}` : "Région Métropolitaine",
+    region: regionName,
     country: fallbackCountry,
-    currency: isUS ? "USD" : isUK ? "GBP" : "EUR",
-    currencySymbol: isUS ? "$" : isUK ? "£" : "€",
-    population: 45000,
-    latitude: 48.8566,
-    longitude: 2.3522,
+    currency,
+    currencySymbol,
+    population: 50000,
+    latitude: 40.7128,
+    longitude: -74.006,
     neighborSlugs: []
   };
 }
@@ -4205,7 +4222,18 @@ class PseoMatrixEngine {
       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 dynamicLoc = createDynamicLocation(locationSlug, options.countries?.[0] || "France");
+        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;
+          }
+        }
         const dynamicPages = this.generateLocalGeoMatrix(domain, [matchedService], [dynamicLoc], options);
         return dynamicPages.find((p) => p.urlPath === path) || dynamicPages[0];
       }
@@ -9429,6 +9457,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);
@@ -9478,7 +9614,8 @@ var LynxSeo = {
   translator: LynxRateLimitedTranslator,
   pageRankGraph: InternalPageRankEngine,
   geoCitation: GeoCitationScorer,
-  marketingSkills: MarketingSkillsEngine
+  marketingSkills: MarketingSkillsEngine,
+  regenerationTracker: PageRegenerationTracker
 };
 var src_default = LynxSeo;
 export {
@@ -9518,6 +9655,7 @@ export {
   PublicRoutesManifestEngine,
   PseoMatrixEngine,
   PowerWordsPsychologyEngine,
+  PageRegenerationTracker,
   PSEO_AGENT_SYSTEM_PROMPT,
   OgImageGenerator,
   NGramDensityAnalyzer,

package/dist/matrix-engine.d.ts

@@ -131,7 +131,10 @@ export interface MatrixOptions {
     brandName: string;
     language?: string;
     languages?: string[];
+    allowedLanguages?: string[] | string;
     countries?: string[] | string;
+    allowedCountries?: string[] | string;
+    strictCountryBoundary?: boolean;
     territories?: string[] | string;
     cleanDirectRoutes?: boolean;
     enableFreeTools?: boolean;

package/package.json

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