@lynxflow/seo-engine 1.4.1 → 1.5.0

package/src/matrix-engine.ts

@@ -0,0 +1,818 @@
+/**
+ * Global Multilingual Programmatic SEO Matrix Engine
+ * Defaults to English with international localization support across 10+ languages (EN, FR, DE, ES, IT, PT, NL, etc.)
+ *
+ * Implements strict SEO golden rules:
+ * - Clean canonical URL paths (no keyword stuttering, no stop words across 10+ languages)
+ * - Anti-cannibalization target clustering
+ * - Google Rich Result Schema.org Graphs (SoftwareApplication, LocalBusiness, HowTo, FAQ, Breadcrumbs)
+ * - SeedRank legal compliance disclaimers & staleness checks
+ * - Tiered Indexing (crawl budget protection) & Geodesic Mesh Linking
+ */
+
+import { cleanSeoSlug } from "./slug-engine";
+import { LegalDisclaimerEngine } from "./legal-disclaimers";
+import { ExtendedSchemaGraphBuilder } from "./extended-schemas";
+
+export type MatrixFamily =
+  | "local-geo"
+  | "vs-comparison"
+  | "alternative"
+  | "pricing"
+  | "target"
+  | "industry"
+  | "persona"
+  | "integration"
+  | "use-case"
+  | "template"
+  | "glossary"
+  | "calculator";
+
+export interface PseoService {
+  slug: string;
+  name: string;
+  category: string;
+  description: string;
+  keyFeatures: string[];
+  priceMonthly?: number;
+}
+
+export interface PseoLocation {
+  slug: string;
+  name: string;
+  region: string;
+  country: string;
+  currency: string;
+  currencySymbol: string;
+  population?: number;
+  latitude?: number;
+  longitude?: number;
+  neighborSlugs?: string[];
+}
+
+export interface PseoCompetitor {
+  slug: string;
+  name: string;
+  category: string;
+  drawbacks: string[];
+  advantagesOver: string[];
+  startingPrice?: number;
+  pricingUrl?: string;
+  lastVerifiedDate?: string;
+}
+
+export interface PseoTarget {
+  slug: string;
+  name: string;
+  type: "industry" | "role";
+  painPoints: string[];
+  benefits: string[];
+  workflowSteps?: string[];
+}
+
+export interface PseoIndustry {
+  slug: string;
+  name: string;
+  category?: string;
+  singular?: string;
+  painPoints?: string[];
+  benefits?: string[];
+}
+
+export interface PseoPersona {
+  slug: string;
+  role: string;
+  department?: string;
+  responsibilities?: string[];
+}
+
+export interface PseoIntegration {
+  slug: string;
+  name: string;
+  category: string;
+  syncFeatures: string[];
+}
+
+export interface PseoUseCase {
+  slug: string;
+  title: string;
+  problem: string;
+  solutionWorkflow: string[];
+  expectedRoi: string;
+}
+
+export interface PseoTemplate {
+  slug: string;
+  title: string;
+  topic: string;
+  format: "excel" | "sheets" | "notion" | "word" | "pdf";
+  downloadUrl?: string;
+  benefits: string[];
+}
+
+export interface PseoGlossaryTerm {
+  slug: string;
+  term: string;
+  shortDefinition: string;
+  fullMarkdown?: string;
+  relatedTermsSlugs?: string[];
+}
+
+export interface PseoCalculator {
+  slug: string;
+  title: string;
+  formulaDescription: string;
+  savingsMetric: string;
+}
+
+export interface SchemaOrgGraph {
+  "@context": "https://schema.org";
+  "@graph": Record<string, unknown>[];
+}
+
+export interface GeneratedPageMeta {
+  matrixFamily: MatrixFamily;
+  urlPath: string;
+  canonicalUrl: string;
+  title: string;
+  description: string;
+  h1: string;
+  robots: "index, follow" | "noindex, follow";
+  schemaGraph: SchemaOrgGraph;
+  disclaimerText?: string;
+  neighboringLinks?: { name: string; url: string }[];
+  service?: PseoService;
+  location?: PseoLocation;
+  competitor?: PseoCompetitor;
+  target?: PseoTarget;
+  integration?: PseoIntegration;
+  useCase?: PseoUseCase;
+  template?: PseoTemplate;
+  glossary?: PseoGlossaryTerm;
+  calculator?: PseoCalculator;
+}
+
+export interface MatrixOptions {
+  brandName: string;
+  language?: string; // Default: "en", supports "fr", "de", "es", "pt", "it", etc.
+  minPopulationToIndex?: number;
+  defaultCurrency?: string;
+  defaultCurrencySymbol?: string;
+  organizationSameAs?: string[];
+  correctionsEmail?: string;
+}
+
+export class PseoMatrixEngine {
+  private legalEngine: LegalDisclaimerEngine;
+
+  constructor(legalOptions?: { correctionsEmail?: string; companyName?: string; language?: string }) {
+    this.legalEngine = new LegalDisclaimerEngine({
+      companyName: legalOptions?.companyName || "Our Platform",
+      correctionsEmail: legalOptions?.correctionsEmail || "compliance@platform.com",
+      language: legalOptions?.language || "en",
+    });
+  }
+
+  /**
+   * Helper: Resolves route prefixes according to language (English default).
+   */
+  private getPrefix(family: string, lang: string = "en"): string {
+    if (lang === "fr") {
+      const frMap: Record<string, string> = {
+        vs: "/comparatif",
+        alternative: "/alternatives",
+        pricing: "/tarifs",
+        target: "/pour",
+        integration: "/integrations",
+        useCase: "/cas-usage",
+        template: "/modeles",
+        glossary: "/glossaire",
+        calculator: "/outils",
+        solutions: "/solutions",
+      };
+      return frMap[family] || `/${family}`;
+    }
+
+    if (lang === "de") {
+      const deMap: Record<string, string> = {
+        vs: "/vergleich",
+        alternative: "/alternativen",
+        pricing: "/preise",
+        target: "/fuer",
+        integration: "/integrationen",
+        useCase: "/anwendungsfaelle",
+        template: "/vorlagen",
+        glossary: "/glossar",
+        calculator: "/rechner",
+        solutions: "/loesungen",
+      };
+      return deMap[family] || `/${family}`;
+    }
+
+    if (lang === "es") {
+      const esMap: Record<string, string> = {
+        vs: "/comparativa",
+        alternative: "/alternativas",
+        pricing: "/precios",
+        target: "/para",
+        integration: "/integraciones",
+        useCase: "/casos-uso",
+        template: "/plantillas",
+        glossary: "/glosario",
+        calculator: "/herramientas",
+        solutions: "/soluciones",
+      };
+      return esMap[family] || `/${family}`;
+    }
+
+    // English Default
+    const enMap: Record<string, string> = {
+      vs: "/vs",
+      alternative: "/alternatives",
+      pricing: "/pricing",
+      target: "/for",
+      integration: "/integrations",
+      useCase: "/use-cases",
+      template: "/templates",
+      glossary: "/glossary",
+      calculator: "/tools",
+      solutions: "/solutions",
+    };
+    return enMap[family] || `/${family}`;
+  }
+
+  /**
+   * 1. Local & GEO Matrix (`/solutions/{service}/{country}/{city}`)
+   */
+  generateLocalGeoMatrix(
+    domain: string,
+    services: PseoService[],
+    locations: PseoLocation[],
+    options: MatrixOptions,
+  ): GeneratedPageMeta[] {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const lang = options.language || "en";
+    const minPop = options.minPopulationToIndex ?? 15_000;
+    const pages: GeneratedPageMeta[] = [];
+    const locMap = new Map(locations.map((l) => [l.slug, l]));
+    const prefix = this.getPrefix("solutions", lang);
+
+    for (const s of services) {
+      for (const loc of locations) {
+        const countryCode = cleanSeoSlug(loc.country, { language: lang });
+        const citySlug = cleanSeoSlug(loc.slug, { language: lang });
+        const serviceSlug = cleanSeoSlug(s.slug, { language: lang });
+
+        const urlPath = `${prefix}/${serviceSlug}/${countryCode}/${citySlug}`;
+        const fullUrl = `${cleanDomain}${urlPath}`;
+
+        const isIndexed = (loc.population ?? 20_000) >= minPop;
+        const robots: "index, follow" | "noindex, follow" = isIndexed
+          ? "index, follow"
+          : "noindex, follow";
+
+        const title = `${s.name} in ${loc.name} (${loc.region}) — ${options.brandName}`;
+        const description = `Discover ${s.name} software tailored for businesses in ${loc.name}, ${loc.country}. Fast setup, local support in ${loc.currencySymbol}.`;
+        const h1 = `${s.name} for Professionals in ${loc.name}`;
+
+        const neighborLinks = (loc.neighborSlugs || [])
+          .map((slug) => locMap.get(slug))
+          .filter((n): n is PseoLocation => Boolean(n))
+          .map((n) => ({
+            name: n.name,
+            url: `${cleanDomain}${prefix}/${serviceSlug}/${cleanSeoSlug(n.country, { language: lang })}/${cleanSeoSlug(n.slug, { language: lang })}`,
+          }));
+
+        const schemaGraph: SchemaOrgGraph = {
+          "@context": "https://schema.org",
+          "@graph": [
+            ExtendedSchemaGraphBuilder.buildSoftwareApplication({
+              name: `${options.brandName} — ${s.name} ${loc.name}`,
+              description,
+              url: fullUrl,
+              priceMonthly: s.priceMonthly,
+              currency: loc.currency,
+            }),
+            ExtendedSchemaGraphBuilder.buildLocalBusiness({
+              name: `${options.brandName} ${loc.name}`,
+              url: fullUrl,
+              city: loc.name,
+              region: loc.region,
+              country: loc.country,
+              latitude: loc.latitude,
+              longitude: loc.longitude,
+            }),
+            ExtendedSchemaGraphBuilder.buildBreadcrumbs([
+              { name: "Home", url: cleanDomain },
+              { name: "Solutions", url: `${cleanDomain}${prefix}` },
+              { name: s.name, url: `${cleanDomain}${prefix}/${serviceSlug}` },
+              { name: loc.name, url: fullUrl },
+            ]),
+          ],
+        };
+
+        pages.push({
+          matrixFamily: "local-geo",
+          urlPath,
+          canonicalUrl: fullUrl,
+          title,
+          description,
+          h1,
+          robots,
+          schemaGraph,
+          neighboringLinks: neighborLinks,
+          service: s,
+          location: loc,
+        });
+      }
+    }
+    return pages;
+  }
+
+  /**
+   * 2. VS Comparisons Matrix (`/vs/{competitor}` in English default)
+   */
+  generateVsMatrix(
+    domain: string,
+    competitors: PseoCompetitor[],
+    options: MatrixOptions,
+  ): GeneratedPageMeta[] {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const lang = options.language || "en";
+    const prefix = this.getPrefix("vs", lang);
+
+    return competitors.map((comp) => {
+      const compSlug = cleanSeoSlug(comp.slug, { language: lang });
+      const urlPath = `${prefix}/${compSlug}`;
+      const fullUrl = `${cleanDomain}${urlPath}`;
+      const title = `${options.brandName} vs ${comp.name} Comparison & Key Differences`;
+      const description = `In-depth comparison between ${options.brandName} and ${comp.name}. Features, pricing transparency, and architectural differences.`;
+      const h1 = `${options.brandName} vs ${comp.name} : The Complete Comparison`;
+      const disclaimerText = this.legalEngine.getDisclaimer("comparison", comp.lastVerifiedDate, lang);
+
+      const schemaGraph: SchemaOrgGraph = {
+        "@context": "https://schema.org",
+        "@graph": [
+          ExtendedSchemaGraphBuilder.buildOrganization({
+            name: options.brandName,
+            url: cleanDomain,
+            sameAs: options.organizationSameAs,
+          }),
+          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
+            { name: "Home", url: cleanDomain },
+            { name: "Comparisons", url: `${cleanDomain}${prefix}` },
+            { name: `vs ${comp.name}`, url: fullUrl },
+          ]),
+        ],
+      };
+
+      return {
+        matrixFamily: "vs-comparison",
+        urlPath,
+        canonicalUrl: fullUrl,
+        title,
+        description,
+        h1,
+        robots: "index, follow",
+        disclaimerText,
+        schemaGraph,
+        competitor: comp,
+      };
+    });
+  }
+
+  /**
+   * 3. Alternatives Matrix (`/alternatives/{competitor}`)
+   */
+  generateAlternativesMatrix(
+    domain: string,
+    competitors: PseoCompetitor[],
+    options: MatrixOptions,
+  ): GeneratedPageMeta[] {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const lang = options.language || "en";
+    const prefix = this.getPrefix("alternative", lang);
+
+    return competitors.map((comp) => {
+      const compSlug = cleanSeoSlug(comp.slug, { language: lang });
+      const urlPath = `${prefix}/${compSlug}`;
+      const fullUrl = `${cleanDomain}${urlPath}`;
+      const title = `Best ${comp.name} Alternative — ${options.brandName}`;
+      const description = `Looking for a modern alternative to ${comp.name}? Explore why teams migrate to ${options.brandName}.`;
+      const h1 = `Why ${options.brandName} is the Best Alternative to ${comp.name}`;
+      const disclaimerText = this.legalEngine.getDisclaimer("alternative", comp.lastVerifiedDate, lang);
+
+      const schemaGraph: SchemaOrgGraph = {
+        "@context": "https://schema.org",
+        "@graph": [
+          ExtendedSchemaGraphBuilder.buildSoftwareApplication({
+            name: `${options.brandName} — Alternative to ${comp.name}`,
+            description,
+            url: fullUrl,
+          }),
+          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
+            { name: "Home", url: cleanDomain },
+            { name: "Alternatives", url: `${cleanDomain}${prefix}` },
+            { name: comp.name, url: fullUrl },
+          ]),
+        ],
+      };
+
+      return {
+        matrixFamily: "alternative",
+        urlPath,
+        canonicalUrl: fullUrl,
+        title,
+        description,
+        h1,
+        robots: "index, follow",
+        disclaimerText,
+        schemaGraph,
+        competitor: comp,
+      };
+    });
+  }
+
+  /**
+   * 4. Pricing Matrix (`/pricing/{competitor}` in English default)
+   */
+  generatePricingMatrix(
+    domain: string,
+    competitors: PseoCompetitor[],
+    options: MatrixOptions,
+  ): GeneratedPageMeta[] {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const lang = options.language || "en";
+    const prefix = this.getPrefix("pricing", lang);
+
+    return competitors.map((comp) => {
+      const compSlug = cleanSeoSlug(comp.slug, { language: lang });
+      const urlPath = `${prefix}/${compSlug}`;
+      const fullUrl = `${cleanDomain}${urlPath}`;
+      const title = `${comp.name} Pricing & Cost Breakdown — ${options.brandName}`;
+      const description = `Detailed ${comp.name} pricing guide. Tiers, hidden fees, add-on costs, and how it compares to ${options.brandName}.`;
+      const h1 = `${comp.name} Pricing, Plans & Hidden Costs`;
+      const disclaimerText = this.legalEngine.getDisclaimer("pricing", comp.lastVerifiedDate, lang);
+
+      const schemaGraph: SchemaOrgGraph = {
+        "@context": "https://schema.org",
+        "@graph": [
+          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
+            { name: "Home", url: cleanDomain },
+            { name: "Pricing Guides", url: `${cleanDomain}${prefix}` },
+            { name: `${comp.name} Pricing`, url: fullUrl },
+          ]),
+        ],
+      };
+
+      return {
+        matrixFamily: "pricing",
+        urlPath,
+        canonicalUrl: fullUrl,
+        title,
+        description,
+        h1,
+        robots: "index, follow",
+        disclaimerText,
+        schemaGraph,
+        competitor: comp,
+      };
+    });
+  }
+
+  /**
+   * 5. Unified Target Audience Matrix (`/for/{target}` in English default)
+   */
+  generateTargetMatrix(
+    domain: string,
+    targets: PseoTarget[],
+    options: MatrixOptions,
+  ): GeneratedPageMeta[] {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const lang = options.language || "en";
+    const prefix = this.getPrefix("target", lang);
+
+    return targets.map((t) => {
+      const targetSlug = cleanSeoSlug(t.slug, { language: lang });
+      const urlPath = `${prefix}/${targetSlug}`;
+      const fullUrl = `${cleanDomain}${urlPath}`;
+      const title = `${options.brandName} for ${t.name} — Dedicated Solution`;
+      const description = `Streamline operations and automate workflows designed specifically for ${t.name}.`;
+      const h1 = `The Operating System Designed for ${t.name}`;
+
+      const schemaGraph: SchemaOrgGraph = {
+        "@context": "https://schema.org",
+        "@graph": [
+          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
+            { name: "Home", url: cleanDomain },
+            { name: "Solutions", url: `${cleanDomain}${prefix}` },
+            { name: t.name, url: fullUrl },
+          ]),
+        ],
+      };
+
+      return {
+        matrixFamily: "target",
+        urlPath,
+        canonicalUrl: fullUrl,
+        title,
+        description,
+        h1,
+        robots: "index, follow",
+        schemaGraph,
+        target: t,
+      };
+    });
+  }
+
+  /**
+   * 6. Integrations Matrix (`/integrations/{software}`)
+   */
+  generateIntegrationMatrix(
+    domain: string,
+    integrations: PseoIntegration[],
+    options: MatrixOptions,
+  ): GeneratedPageMeta[] {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const lang = options.language || "en";
+    const prefix = this.getPrefix("integration", lang);
+
+    return integrations.map((itg) => {
+      const itgSlug = cleanSeoSlug(itg.slug, { language: lang });
+      const urlPath = `${prefix}/${itgSlug}`;
+      const fullUrl = `${cleanDomain}${urlPath}`;
+      const title = `${options.brandName} & ${itg.name} Integration : 2-Way Sync`;
+      const description = `Connect ${options.brandName} with ${itg.name} to automate workflows and sync data without code.`;
+      const h1 = `${options.brandName} × ${itg.name} Native Integration`;
+
+      const schemaGraph: SchemaOrgGraph = {
+        "@context": "https://schema.org",
+        "@graph": [
+          ExtendedSchemaGraphBuilder.buildSoftwareApplication({
+            name: `${options.brandName} ${itg.name} Connector`,
+            description,
+            url: fullUrl,
+            category: "IntegrationApplication",
+          }),
+          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
+            { name: "Home", url: cleanDomain },
+            { name: "Integrations", url: `${cleanDomain}${prefix}` },
+            { name: itg.name, url: fullUrl },
+          ]),
+        ],
+      };
+
+      return {
+        matrixFamily: "integration",
+        urlPath,
+        canonicalUrl: fullUrl,
+        title,
+        description,
+        h1,
+        robots: "index, follow",
+        schemaGraph,
+        integration: itg,
+      };
+    });
+  }
+
+  /**
+   * 7. Use Cases Matrix (`/use-cases/{useCase}` in English default)
+   */
+  generateUseCaseMatrix(
+    domain: string,
+    useCases: PseoUseCase[],
+    options: MatrixOptions,
+  ): GeneratedPageMeta[] {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const lang = options.language || "en";
+    const prefix = this.getPrefix("useCase", lang);
+
+    return useCases.map((uc) => {
+      const ucSlug = cleanSeoSlug(uc.slug, { language: lang });
+      const urlPath = `${prefix}/${ucSlug}`;
+      const fullUrl = `${cleanDomain}${urlPath}`;
+      const title = `${uc.title} : Step-by-Step Guide with ${options.brandName}`;
+      const description = `Operational playbook: ${uc.problem}. Discover how to solve and automate this with ${options.brandName}.`;
+      const h1 = `${uc.title} — Automation Workflow`;
+
+      const schemaGraph: SchemaOrgGraph = {
+        "@context": "https://schema.org",
+        "@graph": [
+          ExtendedSchemaGraphBuilder.buildHowTo({
+            name: uc.title,
+            description: uc.problem,
+            steps: uc.solutionWorkflow,
+          }),
+          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
+            { name: "Home", url: cleanDomain },
+            { name: "Use Cases", url: `${cleanDomain}${prefix}` },
+            { name: uc.title, url: fullUrl },
+          ]),
+        ],
+      };
+
+      return {
+        matrixFamily: "use-case",
+        urlPath,
+        canonicalUrl: fullUrl,
+        title,
+        description,
+        h1,
+        robots: "index, follow",
+        schemaGraph,
+        useCase: uc,
+      };
+    });
+  }
+
+  /**
+   * 8. Templates & Lead Magnets Matrix (`/templates/{slug}` in English default)
+   */
+  generateTemplateMatrix(
+    domain: string,
+    templates: PseoTemplate[],
+    options: MatrixOptions,
+  ): GeneratedPageMeta[] {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const lang = options.language || "en";
+    const prefix = this.getPrefix("template", lang);
+
+    return templates.map((tmpl) => {
+      const tmplSlug = cleanSeoSlug(tmpl.slug, { language: lang });
+      const urlPath = `${prefix}/${tmplSlug}`;
+      const fullUrl = `${cleanDomain}${urlPath}`;
+      const title = `Free ${tmpl.title} (${tmpl.format.toUpperCase()}) — ${options.brandName}`;
+      const description = `Download our free ${tmpl.title} template for ${tmpl.format.toUpperCase()}. Save time and automate your workflow.`;
+      const h1 = `Free ${tmpl.title} Template`;
+
+      const schemaGraph: SchemaOrgGraph = {
+        "@context": "https://schema.org",
+        "@graph": [
+          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
+            { name: "Home", url: cleanDomain },
+            { name: "Templates", url: `${cleanDomain}${prefix}` },
+            { name: tmpl.title, url: fullUrl },
+          ]),
+        ],
+      };
+
+      return {
+        matrixFamily: "template",
+        urlPath,
+        canonicalUrl: fullUrl,
+        title,
+        description,
+        h1,
+        robots: "index, follow",
+        schemaGraph,
+        template: tmpl,
+      };
+    });
+  }
+
+  /**
+   * 9. Glossary Matrix (`/glossary/{term}` in English default)
+   */
+  generateGlossaryMatrix(
+    domain: string,
+    terms: PseoGlossaryTerm[],
+    options: MatrixOptions,
+  ): GeneratedPageMeta[] {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const lang = options.language || "en";
+    const prefix = this.getPrefix("glossary", lang);
+
+    return terms.map((g) => {
+      const termSlug = cleanSeoSlug(g.slug, { language: lang });
+      const urlPath = `${prefix}/${termSlug}`;
+      const fullUrl = `${cleanDomain}${urlPath}`;
+      const title = `What is ${g.term}? Definition & Best Practices — ${options.brandName}`;
+      const description = `${g.shortDefinition.substring(0, 150)}... Learn the core concepts and implementation.`;
+      const h1 = `${g.term} : Definition & Strategy`;
+
+      const schemaGraph: SchemaOrgGraph = {
+        "@context": "https://schema.org",
+        "@graph": [
+          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
+            { name: "Home", url: cleanDomain },
+            { name: "Glossary", url: `${cleanDomain}${prefix}` },
+            { name: g.term, url: fullUrl },
+          ]),
+        ],
+      };
+
+      return {
+        matrixFamily: "glossary",
+        urlPath,
+        canonicalUrl: fullUrl,
+        title,
+        description,
+        h1,
+        robots: "index, follow",
+        schemaGraph,
+        glossary: g,
+      };
+    });
+  }
+
+  /**
+   * 10. Tools & Calculators Matrix (`/tools/{calculator}` in English default)
+   */
+  generateCalculatorMatrix(
+    domain: string,
+    calculators: PseoCalculator[],
+    options: MatrixOptions,
+  ): GeneratedPageMeta[] {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const lang = options.language || "en";
+    const prefix = this.getPrefix("calculator", lang);
+
+    return calculators.map((calc) => {
+      const calcSlug = cleanSeoSlug(calc.slug, { language: lang });
+      const urlPath = `${prefix}/${calcSlug}`;
+      const fullUrl = `${cleanDomain}${urlPath}`;
+      const title = `${calc.title} Online Calculator — ${options.brandName}`;
+      const description = `Free calculator: ${calc.formulaDescription}. Estimate your ${calc.savingsMetric} instantly.`;
+      const h1 = `${calc.title} — Free Interactive Estimator`;
+
+      const schemaGraph: SchemaOrgGraph = {
+        "@context": "https://schema.org",
+        "@graph": [
+          ExtendedSchemaGraphBuilder.buildSoftwareApplication({
+            name: calc.title,
+            description,
+            url: fullUrl,
+          }),
+          ExtendedSchemaGraphBuilder.buildBreadcrumbs([
+            { name: "Home", url: cleanDomain },
+            { name: "Calculators", url: `${cleanDomain}${prefix}` },
+            { name: calc.title, url: fullUrl },
+          ]),
+        ],
+      };
+
+      return {
+        matrixFamily: "calculator",
+        urlPath,
+        canonicalUrl: fullUrl,
+        title,
+        description,
+        h1,
+        robots: "index, follow",
+        schemaGraph,
+        calculator: calc,
+      };
+    });
+  }
+
+  /**
+   * Master Generator: Produces all programmatic families simultaneously.
+   */
+  generateAllMatrices(
+    domain: string,
+    data: {
+      services?: PseoService[];
+      locations?: PseoLocation[];
+      competitors?: PseoCompetitor[];
+      targets?: PseoTarget[];
+      integrations?: PseoIntegration[];
+      useCases?: PseoUseCase[];
+      templates?: PseoTemplate[];
+      glossaryTerms?: PseoGlossaryTerm[];
+      calculators?: PseoCalculator[];
+    },
+    options: MatrixOptions,
+  ): GeneratedPageMeta[] {
+    const allPages: GeneratedPageMeta[] = [];
+
+    if (data.services && data.locations) {
+      allPages.push(...this.generateLocalGeoMatrix(domain, data.services, data.locations, options));
+    }
+    if (data.competitors) {
+      allPages.push(...this.generateVsMatrix(domain, data.competitors, options));
+      allPages.push(...this.generateAlternativesMatrix(domain, data.competitors, options));
+      allPages.push(...this.generatePricingMatrix(domain, data.competitors, options));
+    }
+    if (data.targets) {
+      allPages.push(...this.generateTargetMatrix(domain, data.targets, options));
+    }
+    if (data.integrations) {
+      allPages.push(...this.generateIntegrationMatrix(domain, data.integrations, options));
+    }
+    if (data.useCases) {
+      allPages.push(...this.generateUseCaseMatrix(domain, data.useCases, options));
+    }
+    if (data.templates) {
+      allPages.push(...this.generateTemplateMatrix(domain, data.templates, options));
+    }
+    if (data.glossaryTerms) {
+      allPages.push(...this.generateGlossaryMatrix(domain, data.glossaryTerms, options));
+    }
+    if (data.calculators) {
+      allPages.push(...this.generateCalculatorMatrix(domain, data.calculators, options));
+    }
+
+    return allPages;
+  }
+}