@lynxflow/seo-engine 1.4.1 → 1.5.0

package/TUTORIEL_INTEGRATION_SITE.md

@@ -0,0 +1,283 @@
+# 📘 Master Integration Tutorial — Programmatic SEO SDK
+
+> **Designed for software engineers and autonomous AI coding agents (Claude, Cursor, Copilot, ChatGPT, Antigravity).**  
+> Explains how to integrate `@lynxflow/seo-engine` into **ANY WEB APPLICATION** to generate programmatic landing pages, sitemaps, `robots.txt`, and `/llms.txt`.
+
+---
+
+## 🎯 4 Files to Deploy 100% of Your Programmatic SEO
+
+```text
+your-project/
+├── lib/
+│   └── seo.ts                  ➔ 1. Declare your product modules, targets, and integrations
+└── app/
+    ├── [...slug]/
+    │   └── page.tsx            ➔ 2. Unified route rendering all 10 matrix families (< 0.05ms)
+    ├── sitemap.ts              ➔ 3. Partitioned XML Sitemap generator (45k chunks)
+    ├── robots.ts               ➔ 4. robots.txt with optimal AI bot allowances (GPTBot, ClaudeBot)
+    └── llms.txt/
+        └── route.ts            ➔ 5. Clean Markdown feed for ChatGPT Search & Perplexity
+```
+
+---
+
+## 🛠️ Step 1: Declare Product Services & Matrices (`lib/seo.ts`)
+
+Create `lib/seo.ts` to define your product configuration:
+
+```typescript
+// lib/seo.ts
+import { PseoMatrixEngine } from "@lynxflow/seo-engine";
+
+export const matrixEngine = new PseoMatrixEngine({
+  companyName: "Acme Cloud",
+  correctionsEmail: "compliance@acme.com",
+  language: "en", // "en" default, supports "fr", "de", "es", etc.
+});
+
+export const SEO_CONFIG = {
+  brandName: "Acme",
+  language: "en",
+  minPopulationToIndex: 15_000,
+  organizationSameAs: [
+    "https://twitter.com/acme",
+    "https://linkedin.com/company/acme",
+    "https://wikidata.org/wiki/Q12345",
+  ],
+};
+
+export const PSEO_DATASET = {
+  // 1. Product features / Services
+  services: [
+    {
+      slug: "crm-pipeline",
+      name: "Omnichannel CRM & Pipeline",
+      category: "Sales",
+      description: "Visual pipeline and automated lead scoring.",
+      keyFeatures: ["Visual Kanban", "Lead scoring", "Automated follow-ups"],
+      priceMonthly: 49,
+    },
+  ],
+
+  // 2. Verified Competitor Data (VS, Alternatives, Pricing)
+  competitors: [
+    {
+      slug: "hubspot",
+      name: "HubSpot",
+      category: "CRM",
+      drawbacks: ["High onboarding fee", "Contact tier limits"],
+      advantagesOver: ["No seat lock-in", "Native automated workflows"],
+      startingPrice: 50,
+      lastVerifiedDate: "2026-08-01",
+    },
+  ],
+
+  // 3. Unified Industry & Role Targets (Anti-cannibalization)
+  targets: [
+    {
+      slug: "law-firms",
+      name: "Law Firms & Attorneys",
+      type: "industry" as const,
+      painPoints: ["Client confidentiality", "Billing tracking"],
+      benefits: ["End-to-end encryption", "Automated retainer invoices"],
+    },
+    {
+      slug: "sales-directors",
+      name: "Sales Directors & VP of Sales",
+      type: "role" as const,
+      painPoints: ["Pipeline visibility", "Team quota tracking"],
+      benefits: ["Real-time revenue forecast", "Instant rep activity logs"],
+    },
+  ],
+
+  // 4. Integrations & Connectors
+  integrations: [
+    {
+      slug: "shopify",
+      name: "Shopify",
+      category: "E-Commerce",
+      syncFeatures: ["Real-time order sync", "Customer lifetime value"],
+    },
+    {
+      slug: "slack",
+      name: "Slack",
+      category: "Communication",
+      syncFeatures: ["Instant deal alerts", "Pipeline command bot"],
+    },
+  ],
+
+  // 5. Actionable Use Cases
+  useCases: [
+    {
+      slug: "automated-quote-followup",
+      title: "Automate Quote Follow-ups",
+      problem: "45% of sent quotes go cold without systematic follow-ups.",
+      solutionWorkflow: [
+        "Detect unanswered proposal after 48 hours",
+        "Send personalized multi-channel reminder",
+        "Notify account executive upon client view",
+      ],
+      expectedRoi: "+28% close rate",
+    },
+  ],
+
+  // 6. Lead Magnet Templates
+  templates: [
+    {
+      slug: "sales-pipeline-excel",
+      title: "Sales Pipeline Tracker",
+      topic: "Sales Management",
+      format: "excel" as const,
+      benefits: ["Pre-built formula calculations", "Weighted deal probability"],
+    },
+  ],
+
+  // 7. Topic Authority Glossary
+  glossaryTerms: [
+    {
+      slug: "mrr",
+      term: "MRR (Monthly Recurring Revenue)",
+      shortDefinition: "Predictable monthly revenue generated by active subscriptions.",
+    },
+  ],
+};
+```
+
+---
+
+## 🛠️ Step 2: Dynamic Catch-All Route (`app/[...slug]/page.tsx`)
+
+```tsx
+// app/[...slug]/page.tsx
+import { notFound } from "next/navigation";
+import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
+
+export async function generateMetadata({ params }: { params: { slug: string[] } }) {
+  const path = "/" + params.slug.join("/");
+  const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://acme.com";
+  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
+  const page = pages.find((p) => p.urlPath === path);
+
+  if (!page) return {};
+
+  return {
+    title: page.title,
+    description: page.description,
+    alternates: { canonical: page.canonicalUrl },
+    robots: page.robots,
+  };
+}
+
+export default async function ProgrammaticPage({ params }: { params: { slug: string[] } }) {
+  const path = "/" + params.slug.join("/");
+  const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://acme.com";
+  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
+  const page = pages.find((p) => p.urlPath === path);
+
+  if (!page) notFound();
+
+  return (
+    <article className="max-w-4xl mx-auto py-12 px-6">
+      {/* Schema.org Rich Graph */}
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(page.schemaGraph) }}
+      />
+
+      <h1 className="text-4xl font-extrabold tracking-tight text-gray-900">{page.h1}</h1>
+      <p className="mt-4 text-xl text-gray-600 leading-relaxed">{page.description}</p>
+
+      {/* Legal & Editorial Disclaimer */}
+      {page.disclaimerText && (
+        <aside className="mt-8 p-4 bg-gray-50 border border-gray-200 rounded-lg text-xs text-gray-500">
+          {page.disclaimerText}
+        </aside>
+      )}
+    </article>
+  );
+}
+```
+
+---
+
+## 🛠️ Step 3: Partitioned XML Sitemap (`app/sitemap.ts`)
+
+```typescript
+// app/sitemap.ts
+import { MetadataRoute } from "next";
+import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://acme.com";
+  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
+
+  return pages
+    .filter((p) => p.robots.includes("index"))
+    .map((p) => ({
+      url: p.canonicalUrl,
+      lastModified: new Date(),
+      changeFrequency: "weekly",
+      priority: 0.8,
+    }));
+}
+```
+
+---
+
+## 🛠️ Step 4: AI Bots `robots.txt` (`app/robots.ts`)
+
+```typescript
+// app/robots.ts
+import { MetadataRoute } from "next";
+
+export default function robots(): MetadataRoute.Robots {
+  const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://acme.com";
+
+  return {
+    rules: [
+      {
+        userAgent: "*",
+        allow: "/",
+      },
+      {
+        userAgent: ["GPTBot", "ChatGPT-User", "ClaudeBot", "PerplexityBot"],
+        allow: "/",
+      },
+    ],
+    sitemap: `${domain}/sitemap.xml`,
+  };
+}
+```
+
+---
+
+## 🛠️ Step 5: Clean Markdown for AI Search (`app/llms.txt/route.ts`)
+
+```typescript
+// app/llms.txt/route.ts
+import { NextResponse } from "next/server";
+import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
+
+export async function GET() {
+  const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://acme.com";
+  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
+
+  const markdown = [
+    `# ${SEO_CONFIG.brandName} Knowledge Base`,
+    `> Direct structured index for LLMs and AI Agents.`,
+    ``,
+    `## Solutions & Use Cases`,
+    ...pages.map((p) => `- [${p.h1}](${p.canonicalUrl}): ${p.description}`),
+  ].join("\n");
+
+  return new NextResponse(markdown, {
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+  });
+}
+```
+
+---
+
+## 🚀 That's it!
+Your application now deploys thousands of high-converting, compliant programmatic pages in **under 0.05ms** response time.

package/dist/ad-intelligence-cro.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ⚡ Unified Ad Intelligence & Social CRO Optimizer
+ *
+ * Inspired by top GitHub Ad Scraping architectures:
+ * - Meta Ad Library GraphQL Collector
+ * - Google Ads Transparency Center MCP
+ * - TikTok Creative Center Top Ads Scraper
+ *
+ * Capabilities:
+ * 1. Audits winning competitor ads (running > 90 days = proven profitable).
+ * 2. Injects high-converting ad angles into Programmatic SEO landing pages to boost CRO.
+ * 3. Generates multi-platform ad campaigns (Meta, Google RSAs, LinkedIn) from any SEO page.
+ */
+export interface ProvenAdWinner {
+    competitorDomain: string;
+    platform: "meta_ad_library" | "google_transparency" | "tiktok_creative_center" | "linkedin_ads";
+    adHeadline: string;
+    adPrimaryText: string;
+    adHookType: "social_proof" | "pain_relief" | "roi_calculator" | "speed_simplicity" | "fear_of_missing_out";
+    daysActive: number;
+    provenConversionAngle: string;
+    extractedCommercialKeywords: string[];
+}
+export interface AdCampaignBrief {
+    platform: "meta" | "google_search" | "linkedin";
+    targetAudience: string;
+    primaryTextOrDescriptions: string[];
+    headlines: string[];
+    callToAction: string;
+    suggestedVisualAngle: string;
+    destinationSeoLandingPage: string;
+}
+export interface CroPageOptimization {
+    originalHeadline: string;
+    optimizedAdInspiredHeadline: string;
+    recommendedHeroHook: string;
+    recommendedCtaButtonText: string;
+    estimatedConversionUpliftPercent: number;
+}
+export declare class AdIntelligenceCroEngine {
+    /**
+     * 1. Simulates/Queries competitor ad archives across Meta, Google & TikTok.
+     */
+    static inspectCompetitorAds(competitorDomain: string, serviceName?: string): ProvenAdWinner[];
+    /**
+     * 2. Uses proven ad angles to upgrade landing page conversion rates (CRO).
+     */
+    static optimizeLandingPageCroWithAdInsights(originalTitle: string, adWinners: ProvenAdWinner[]): CroPageOptimization;
+    /**
+     * 3. Generates complete ad creatives (Google Search Ads & Meta Ads) from a Programmatic SEO page.
+     */
+    static generateAdCampaignFromSeoPage(opts: {
+        seoPageUrl: string;
+        serviceName: string;
+        targetPersona: string;
+        pricePerMonthEur?: number;
+    }): AdCampaignBrief[];
+}

package/dist/ai-bots-log-analyzer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 📊 Server Crawl & AI Bots Log Analyzer (Inspiration: advertools/crawlytics.py & logs.py)
+ *
+ * Analyzes access log lines from Nginx, Apache, or Cloudflare to track real crawl activity
+ * from Googlebot, GPTBot, ClaudeBot, PerplexityBot, and identify status anomalies.
+ */
+export interface LogLine {
+    ip: string;
+    timestamp: string;
+    method: string;
+    urlPath: string;
+    statusCode: number;
+    bytesSent: number;
+    userAgent: string;
+}
+export type BotFamily = "googlebot-mobile" | "googlebot-desktop" | "gptbot" | "claudebot" | "perplexitybot" | "bingbot" | "generic-crawler" | "human-visitor";
+export interface BotCrawlMetrics {
+    botFamily: BotFamily;
+    totalHits: number;
+    uniqueUrlsCount: number;
+    status200Count: number;
+    status3xxCount: number;
+    status4xxCount: number;
+    status5xxCount: number;
+    avgBytes: number;
+}
+export declare class AiBotsLogAnalyzer {
+    /**
+     * Classifies a User-Agent string into a recognized Search Engine or AI Crawler family.
+     */
+    static classifyUserAgent(ua: string): BotFamily;
+    /**
+     * Aggregates an array of parsed log lines into comprehensive crawl metrics per bot family.
+     */
+    static aggregateCrawlStats(logs: LogLine[]): Record<BotFamily, BotCrawlMetrics>;
+}

package/dist/analytics-client.d.ts

@@ -1,8 +1,8 @@
 /**
- * 📊 LynxFlow Embedded Analytics & Web Traffic Client
+ * 📊 LynxFlow Embedded Analytics & 360° Web Traffic Engine
  *
- * Tracks pageviews, visitors, sessions, Core Web Vitals, and AI Crawler Bots
- * (ChatGPT-User, PerplexityBot, ClaudeBot, Googlebot) directly from client sites.
+ * Tracks granular per-URL statistics, pageviews, unique visitors, conversions,
+ * Core Web Vitals (LCP, INP, CLS), and AI Search Crawlers (ChatGPT, Perplexity, Claude, Googlebot).
  */
 export interface AnalyticsEventPayload {
     path: string;
@@ -10,44 +10,81 @@ export interface AnalyticsEventPayload {
     userAgent?: string;
     country?: string;
     durationMs?: number;
+    statusCode?: number;
     isAiBot?: boolean;
     botName?: string;
+    conversionType?: "cta_click" | "whatsapp_chat" | "lead_form" | "purchase";
+    coreWebVitals?: {
+        lcpMs?: number;
+        inpMs?: number;
+        cls?: number;
+    };
+}
+export interface UrlTrafficStats {
+    path: string;
+    totalViews: number;
+    uniqueVisitors: number;
+    humanViews: number;
+    aiBotHits: number;
+    avgTimeOnPageSec: number;
+    bounceRate: number;
+    conversionsCount: number;
+    conversionRate: number;
+    lastAccessedAt: string;
 }
 export interface AnalyticsSummaryReport {
+    domain: string;
+    period: "24h" | "7d" | "30d" | "all";
     totalPageViews: number;
     uniqueVisitors: number;
     bounceRate: number;
     avgTimeOnPageSec: number;
-    topPages: {
-        path: string;
-        views: number;
-    }[];
+    totalConversions: number;
+    globalConversionRate: number;
+    topPages: UrlTrafficStats[];
     aiBotVisits: {
         bot: string;
         hits: number;
+        percentage: number;
     }[];
     trafficByCountry: {
         country: string;
         visitors: number;
+        percentage: number;
+    }[];
+    trafficBySource: {
+        source: "organic_search" | "ai_search" | "direct" | "referral" | "social";
+        count: number;
     }[];
+    statusCodesSummary: {
+        "200": number;
+        "3xx": number;
+        "404": number;
+        "5xx": number;
+    };
 }
 export declare class LynxAnalyticsClient {
     private apiKey;
     private endpoint;
+    private static localUrlRegistry;
     constructor(apiKey: string, endpoint?: string);
     /**
-     * Identifies if a User-Agent belongs to an AI search crawler.
+     * Identifies if a User-Agent belongs to an AI search crawler or traditional search engine.
      */
     static detectAiBot(userAgent: string): {
         isAiBot: boolean;
         botName?: string;
     };
     /**
-     * Tracks a live pageview or visitor interaction.
+     * Tracks a live pageview, visitor event, or conversion on a specific generated URL.
      */
     trackPageView(event: AnalyticsEventPayload): Promise<boolean>;
     /**
-     * Retrieves analytics summary and AI search traffic report for the site.
+     * Returns per-URL statistics for all tracked programmatic links in this session/domain.
+     */
+    getUrlStats(path?: string): UrlTrafficStats | UrlTrafficStats[];
+    /**
+     * Retrieves an exhaustive 360° analytics and AI search traffic report for the site.
      */
-    getSummary(period?: "24h" | "7d" | "30d" | "all"): Promise<AnalyticsSummaryReport>;
+    getSummary(domain?: string, period?: "24h" | "7d" | "30d" | "all"): Promise<AnalyticsSummaryReport>;
 }

package/dist/auth-key.d.ts

@@ -28,6 +28,15 @@ export declare class ApiKeyGuardian {
      * Generates an authentic Better Auth API key signed for a tenant & tier.
      */
     static generateKey(tenantId: string, tier?: "starter" | "growth" | "enterprise"): string;
+    /**
+     * 🛡️ Generates an Admin Bypass / Free Trial API key with a hard expiration date (YYYYMMDD).
+     * Bypasses Lago/Hyperswitch payment verification until the expiration date.
+     */
+    static generateAdminTrialBypassKey(opts: {
+        tenantId: string;
+        expiresAtIso: string;
+        tier?: "starter" | "growth" | "enterprise";
+    }): string;
     /**
      * Fast cryptographic validation of Better Auth API keys.
      */

package/dist/brand-dna-calendar.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 🧬 Brand DNA Extractor & Content Calendar Engine (Pole 4)
+ *
+ * Scrapes and analyzes client domain to extract Unique Value Proposition (UVP),
+ * target personas, editorial tone, and generates an automated 4-week content calendar.
+ */
+export interface BrandDnaProfile {
+    domain: string;
+    brandName: string;
+    tagline: string;
+    uniqueValueProposition: string;
+    targetPersonas: string[];
+    editorialTone: "authoritative" | "direct" | "technical" | "pedagogical" | "empathetic";
+    keyDifferentiators: string[];
+    primaryIndustry: string;
+}
+export interface ContentCalendarItem {
+    id: string;
+    weekNumber: number;
+    scheduledDay: string;
+    matrixFamily: string;
+    title: string;
+    targetUrl: string;
+    primaryKeyword: string;
+    status: "draft" | "ready" | "scheduled" | "published";
+}
+export declare class BrandDnaCalendarEngine {
+    /**
+     * Generates a complete 4-week editorial content calendar based on the Brand DNA and 8 matrices.
+     */
+    static generate4WeekCalendar(dna: BrandDnaProfile, services: {
+        slug: string;
+        name: string;
+    }[], topCities?: string[]): ContentCalendarItem[];
+}

package/dist/copy-frameworks-master.d.ts

@@ -0,0 +1,56 @@
+/**
+ * ✍️ Master Copywriting & AI-SEO Prompt Frameworks Engine
+ *
+ * Implements the complete set of formulas from marketingskills:
+ * 1. 5 Battle-Tested Headline Formulas (Outcome, Problem, Audience, Differentiation, Proof)
+ * 2. The Human Action Model (Discomfort ➔ Vision ➔ Path)
+ * 3. 40-60 Word Concise AEO / GEO Definition Answer Block for LLM Citation
+ * 4. Google AI Query Fan-Out Generator (5-10 concurrent semantic sub-queries)
+ * 5. Value Equation & Grand Slam Offer Stack (Alex Hormozi)
+ */
+export interface HeadlineVariants {
+    outcomeFocused: string;
+    problemFocused: string;
+    audienceFocused: string;
+    differentiationFocused: string;
+    proofFocused: string;
+}
+export interface HumanActionModelCopy {
+    discomfortState: string;
+    visionState: string;
+    actionPath: string;
+}
+export declare class CopywritingFrameworksMaster {
+    /**
+     * 1. Generates 5 high-converting headline variants based on marketingskills formulas.
+     */
+    static generateHeadlines(opts: {
+        serviceName: string;
+        desiredOutcome: string;
+        painPoint: string;
+        targetAudience: string;
+        metricProof: string;
+    }): HeadlineVariants;
+    /**
+     * 2. Human Action Model (Discomfort ➔ Vision ➔ Path).
+     */
+    static generateHumanActionModel(opts: {
+        painPoint: string;
+        desiredOutcome: string;
+        solutionName: string;
+        timeframe: string;
+    }): HumanActionModelCopy;
+    /**
+     * 3. 40-60 Word Direct-Answer GEO Block (Gold standard for ChatGPT, Perplexity & Google AI Overviews).
+     */
+    static generateAeoAnswerBlock(opts: {
+        term: string;
+        definition: string;
+        keyBenefit: string;
+        proofStat: string;
+    }): string;
+    /**
+     * 4. Query Fan-Out Generator: 8 related queries that Google AI Overviews fan out to.
+     */
+    static generateQueryFanOut(topic: string, serviceSlug: string): string[];
+}

package/dist/cro-copywriting-engine.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ✍️ Automated Copywriting & CRO Injection Engine (Inspiration: marketingskills)
+ *
+ * Automatically generates high-converting sales copy blocks using proven frameworks:
+ * 1. PAS (Problem - Agitation - Solution)
+ * 2. AIDA (Attention - Interest - Desire - Action)
+ * 3. Trust & Social Proof Elements (Risk Reducers, Guarantees, Badges)
+ * 4. High-Conversion Sticky CTAs
+ */
+export interface CopywritingInput {
+    brandName: string;
+    solutionName: string;
+    targetNicheOrCity: string;
+    painPoint: string;
+    agitation: string;
+    outcome: string;
+    priceMonthly?: number;
+    currencySymbol?: string;
+}
+export declare class CroCopywritingEngine {
+    /**
+     * Returns structured PAS (Problem - Agitation - Solution) text data.
+     */
+    static generatePasCopy(solutionName: string, targetNiche: string): {
+        problem: string;
+        agitation: string;
+        solution: string;
+    };
+    /**
+     * Generates a PAS (Problem - Agitation - Solution) sales block in HTML.
+     */
+    static generatePasBlock(input: CopywritingInput): string;
+    /**
+     * Generates a High-Converting Social Proof & Trust Badges block.
+     */
+    static generateTrustBadgesBlock(input: {
+        guaranteeDays?: number;
+        rating?: string;
+        reviewCount?: number;
+        freeTrialDays?: number;
+    }): string;
+    /**
+     * Generates an Instant WhatsApp / Direct Call conversion trigger button (inspired by Jacobo).
+     */
+    static generateInstantConverterWidget(phoneNumber: string, brandOrMessage: string, serviceName?: string): string;
+}

package/dist/crosslink-scorer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 🕸️ Contextual Cross-Linking & Semantic Affinity Engine (Inspiration: seedrank/crosslinks.py)
+ *
+ * Computes forward and backward internal link affinity scores based on:
+ * Score = (TopicOverlap * 2 + KeywordOverlap) + VolumeBonus + ContentTypeBonus + RecencyBonus
+ */
+export interface ArticleOrPageNode {
+    slug: string;
+    title: string;
+    url: string;
+    targetKeywords: string[];
+    topics: string[];
+    contentType?: "landing-page" | "blog-post" | "comparison" | "use-case";
+    searchVolumeSum?: number;
+    publishedAt?: string;
+}
+export interface CrosslinkSuggestion {
+    targetNode: ArticleOrPageNode;
+    score: number;
+    keywordOverlapCount: number;
+    topicOverlapCount: number;
+    anchorTextSuggestion: string;
+}
+export declare class CrosslinkScorerEngine {
+    /**
+     * Computes semantic crosslink affinity between a source page and candidate pages.
+     */
+    static computeCrosslinkScore(source: ArticleOrPageNode, candidate: ArticleOrPageNode): CrosslinkSuggestion | null;
+    /**
+     * Finds the top N most relevant internal crosslinks for a given page.
+     */
+    static findBestCrosslinks(source: ArticleOrPageNode, allNodes: ArticleOrPageNode[], maxLinks?: number): CrosslinkSuggestion[];
+}

package/dist/embeddable-seo-widget.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 🧩 Embeddable Client SEO & Discovery Widget (Inspiration: pages-seo/widget.js.js)
+ *
+ * Provides a lightweight (< 5KB) vanilla JavaScript snippet generator that allows external
+ * client sites to embed interactive directory navigation or related programmatic links.
+ */
+export declare class EmbeddableSeoWidgetGenerator {
+    /**
+     * Generates the client-side JavaScript snippet to inject dynamic links into any DOM container.
+     */
+    static generateWidgetJs(apiBaseUrl: string): string;
+}