@lynxflow/seo-engine 2.4.0 → 2.5.0

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.4.0-orange.svg)](https://www.npmjs.com/package/@lynxflow/seo-engine)
+[![Version](https://img.shields.io/badge/Version-2.5.0-orange.svg)](https://www.npmjs.com/package/@lynxflow/seo-engine)
 
 ---
 

package/dist/competitor-gap-blueprint.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 🥊 Competitor Gap Blueprint & "Beat Them" Content Architect
+ * Ported & optimized from Python competitor_gap_analyzer.py.
+ * Identifies thin sections, unsupported claims, missing perspectives, and outdated information in competitor content.
+ */
+export type ContentGapType = "thin_section" | "unsupported_claim" | "missing_perspective" | "outdated_info" | "structural_gap";
+export interface CompetitorContentGap {
+    gapType: ContentGapType;
+    description: string;
+    locationHeading: string;
+    competitorUrl: string;
+    priority: "high" | "medium" | "low";
+    counterOpportunity: string;
+}
+export interface CompetitorArticleInput {
+    url: string;
+    title: string;
+    wordCount: number;
+    headings: string[];
+    contentSnippet?: string;
+}
+export interface BeatThemBlueprint {
+    mustFillGaps: CompetitorContentGap[];
+    expectedCommonHeadings: string[];
+    differentiationAngles: string[];
+    outdatedToUpdate: string[];
+    winningOutlineRecommendation: string[];
+}
+export declare class CompetitorGapBlueprintEngine {
+    /**
+     * Analyzes competitors and builds an actionable "Beat Them" blueprint.
+     */
+    static buildBlueprint(targetTopic: string, userWordCount: number, competitors: CompetitorArticleInput[]): BeatThemBlueprint;
+}

package/dist/engagement-hook-analyzer.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 🪝 Engagement Hook & Viral Reading Rhythm Analyzer
+ * Ported & optimized from Python engagement_analyzer.py.
+ * Evaluates the 4 viral reading criteria: Hook quality, sentence length variety, contextual CTA distribution, and paragraph breathability.
+ */
+export interface HookEvaluation {
+    openingSentence: string;
+    isStrongHook: boolean;
+    hookType: "question" | "statistic" | "quote" | "thought_experiment" | "concrete_story" | "generic_bad_opener";
+    feedback: string;
+    suggestedHookUpgrade?: string;
+}
+export interface RhythmEvaluation {
+    sentenceCount: number;
+    averageWords: number;
+    standardDeviation: number;
+    hasVariedRhythm: boolean;
+    score: number;
+}
+export interface CtaDistributionEvaluation {
+    totalCtasDetected: number;
+    isDistributedAcrossArticle: boolean;
+    hasAboveTheFoldCta: boolean;
+    hasMidArticleCta: boolean;
+    hasBottomCta: boolean;
+}
+export interface ParagraphDensityEvaluation {
+    totalParagraphs: number;
+    longParagraphsCount: number;
+    isMobileBreathable: boolean;
+}
+export interface ArticleEngagementReport {
+    engagementScore: number;
+    allPassed: boolean;
+    passedCount: number;
+    hook: HookEvaluation;
+    rhythm: RhythmEvaluation;
+    ctas: CtaDistributionEvaluation;
+    paragraphs: ParagraphDensityEvaluation;
+    actionableFixes: string[];
+}
+export declare class EngagementHookAnalyzer {
+    private static readonly GENERIC_BAD_OPENERS;
+    private static readonly GOOD_HOOK_STARTERS;
+    private static readonly CTA_REGEX;
+    /**
+     * Analyzes an article's engagement mechanics.
+     */
+    static analyze(content: string): ArticleEngagementReport;
+}

package/dist/index.d.ts

@@ -122,6 +122,9 @@ import { ContextTemplatesGenerator } from "./context-templates-generator";
 import { SearchIntentClassifier } from "./search-intent-classifier";
 import { SeoOpportunityPrioritizer } from "./seo-opportunity-prioritizer";
 import { TrustSignalsExtractor } from "./trust-signals-extractor";
+import { CompetitorGapBlueprintEngine } from "./competitor-gap-blueprint";
+import { EngagementHookAnalyzer } from "./engagement-hook-analyzer";
+import { KeywordDensityGuard } from "./keyword-density-guard";
 export declare function createLynxSeoEngine(config: EngineConfig): LynxSeoEngine;
 export declare const LynxSeo: {
     createEngine: typeof createLynxSeoEngine;
@@ -141,6 +144,9 @@ export declare const LynxSeo: {
     searchIntent: typeof SearchIntentClassifier;
     opportunityPrioritizer: typeof SeoOpportunityPrioritizer;
     trustSignals: typeof TrustSignalsExtractor;
+    competitorGap: typeof CompetitorGapBlueprintEngine;
+    engagementHook: typeof EngagementHookAnalyzer;
+    keywordDensity: typeof KeywordDensityGuard;
     inspectMeta: typeof SiteAuditor.inspectMeta;
     crawlDomain: typeof DeepCrawlerAuditor.crawlAndAuditDomain;
     inspectHtmlSnapshot: typeof DeepCrawlerAuditor.inspectHtmlSnapshot;
@@ -182,6 +188,9 @@ export declare const LynxSeo: {
     marketingSkills: typeof MarketingSkillsEngine;
     regenerationTracker: typeof PageRegenerationTracker;
 };
+export * from "./competitor-gap-blueprint";
+export * from "./engagement-hook-analyzer";
+export * from "./keyword-density-guard";
 export * from "./search-intent-classifier";
 export * from "./seo-opportunity-prioritizer";
 export * from "./trust-signals-extractor";

package/dist/index.js

@@ -10782,6 +10782,273 @@ class TrustSignalsExtractor {
   }
 }
 
+// src/competitor-gap-blueprint.ts
+class CompetitorGapBlueprintEngine {
+  static buildBlueprint(targetTopic, userWordCount, competitors) {
+    const gaps = [];
+    const headingCounts = {};
+    const outdatedItems = [];
+    const diffAngles = [];
+    for (const comp of competitors) {
+      for (const h of comp.headings) {
+        const cleanH = h.toLowerCase().trim();
+        headingCounts[cleanH] = (headingCounts[cleanH] || 0) + 1;
+      }
+      if (comp.wordCount < 1500) {
+        gaps.push({
+          gapType: "thin_section",
+          description: `Competitor article is surface-level (${comp.wordCount} words) and lacks concrete implementation steps.`,
+          locationHeading: comp.headings[0] || "Overview",
+          competitorUrl: comp.url,
+          priority: "high",
+          counterOpportunity: `Publish an exhaustive, deep-dive section with interactive code examples, tables, and verifiable benchmarks.`
+        });
+      }
+      if (comp.contentSnippet) {
+        if (/202[0-4]/i.test(comp.contentSnippet)) {
+          outdatedItems.push(`Competitor ${comp.url} contains outdated 2020-2024 benchmarks and legacy screenshots.`);
+        }
+      }
+    }
+    const minThreshold = Math.max(1, Math.floor(competitors.length * 0.4));
+    const expectedCommonHeadings = Object.entries(headingCounts).filter(([_, count]) => count >= minThreshold).map(([h]) => h.charAt(0).toUpperCase() + h.slice(1));
+    diffAngles.push(`Real-Time Performance & In-Memory (O(1)) Speed Benchmarks (Zero competitors currently measure latency)`);
+    diffAngles.push(`AI Engine Optimization (SearchGPT, Perplexity & Gemini citations) with structured direct answer cards`);
+    diffAngles.push(`Interactive ROI / Cost Calculators embeddable directly in the content`);
+    const winningOutlineRecommendation = [
+      `1. Executive Summary & Direct Answer Card (For Google AI Overview & Perplexity)`,
+      ...expectedCommonHeadings.map((h, i) => `${i + 2}. ${h} (With Real Case Studies & Data)`),
+      `${expectedCommonHeadings.length + 2}. Proprietary Benchmark & Comparison Matrix (Our Unique Angle)`,
+      `${expectedCommonHeadings.length + 3}. Step-by-Step Implementation Guide for 2026`,
+      `${expectedCommonHeadings.length + 4}. Frequently Asked Questions (Structured JSON-LD FAQPage)`
+    ];
+    return {
+      mustFillGaps: gaps,
+      expectedCommonHeadings,
+      differentiationAngles: diffAngles,
+      outdatedToUpdate: outdatedItems,
+      winningOutlineRecommendation
+    };
+  }
+}
+
+// src/engagement-hook-analyzer.ts
+class EngagementHookAnalyzer {
+  static GENERIC_BAD_OPENERS = [
+    /^[A-Z][^.!?]*\bis\s+(?:a|an|the)\b/i,
+    /^[A-Z][^.!?]*\bare\s+(?:a|an|the)\b/i,
+    /^When it comes to/i,
+    /^In (?:today['’]s|the|this)\s+(?:digital|modern|world|age|fast-paced)/i,
+    /^If you['’]re (?:looking|searching|trying)/i,
+    /^(?:Many|Most|Some)\s+(?:people|companies|businesses|founders)/i,
+    /^There are (?:many|several|numerous)/i,
+    /^It['’]s (?:no secret|important|essential)/i,
+    /^De nos jours/i,
+    /^Dans le monde digital d'aujourd'hui/i
+  ];
+  static GOOD_HOOK_STARTERS = [
+    { type: "question", pattern: /\?$/ },
+    { type: "statistic", pattern: /^(?:\d+%|\d{1,3}(?:,\d{3})*|\$\d+)/ },
+    { type: "quote", pattern: /^["'«]/ },
+    { type: "thought_experiment", pattern: /^(?:What if|Imagine|Picture this|Here['’]s (?:the truth|what happened)|Et si|Imaginez)/i },
+    { type: "concrete_story", pattern: /^(?:Last (?:week|month|year)|In \d{4}|Hier|Le mois dernier|[A-Z][a-z]+ spent \d+)/i }
+  ];
+  static CTA_REGEX = /(?:Start|Try|Get|Claim|Download|Sign up|Essayer|Démarrer|Obtenir|Profiter|Découvrir|\[.*?→\]|\*\*\[.*?\]\*\*)/gi;
+  static analyze(content) {
+    const lines = content.split(`
+`).map((l) => l.trim()).filter(Boolean);
+    const textOnlyLines = lines.filter((l) => !l.startsWith("#") && !l.startsWith("---") && !l.startsWith("**Meta"));
+    const firstParagraph = textOnlyLines[0] || "";
+    const firstSentence = firstParagraph.split(/[.?!]/)[0]?.trim() || "";
+    const fixes = [];
+    let isStrongHook = false;
+    let hookType = "generic_bad_opener";
+    let hookFeedback = "Opening is generic. Replace with a punchy question, surprising stat, or narrative scenario.";
+    const isGeneric = this.GENERIC_BAD_OPENERS.some((r) => r.test(firstSentence));
+    if (!isGeneric) {
+      for (const h of this.GOOD_HOOK_STARTERS) {
+        if (h.pattern.test(firstSentence) || h.pattern.test(firstParagraph)) {
+          isStrongHook = true;
+          hookType = h.type;
+          hookFeedback = `Excellent hook using a ${h.type.replace("_", " ")}. Captures attention instantly.`;
+          break;
+        }
+      }
+      if (!isStrongHook) {
+        isStrongHook = true;
+        hookType = "concrete_story";
+        hookFeedback = "Opening avoids cliché LLM patterns.";
+      }
+    } else {
+      fixes.push(`Replace generic opener ("${firstSentence.slice(0, 45)}...") with a dramatic question or verified statistic.`);
+    }
+    const hook = {
+      openingSentence: firstSentence,
+      isStrongHook,
+      hookType,
+      feedback: hookFeedback,
+      suggestedHookUpgrade: `What if you could eliminate 80% of manual repetitive tasks in less than 48 hours?`
+    };
+    const rawSentences = content.replace(/([.?!])\s*(?=[A-Z0-9])/g, "$1|").split("|").map((s) => s.trim()).filter((s) => s.length > 5);
+    const sentenceLengths = rawSentences.map((s) => s.split(/\s+/).filter(Boolean).length);
+    const sCount = Math.max(1, sentenceLengths.length);
+    const avgWords = Math.round(sentenceLengths.reduce((a, b) => a + b, 0) / sCount * 10) / 10;
+    const variance = sentenceLengths.reduce((acc, len) => acc + Math.pow(len - avgWords, 2), 0) / sCount;
+    const stdDev = Math.round(Math.sqrt(variance) * 10) / 10;
+    const hasVariedRhythm = stdDev >= 5 && avgWords <= 18;
+    const rhythmScore = Math.min(100, Math.round(stdDev / 8 * 100));
+    if (!hasVariedRhythm) {
+      fixes.push("Vary sentence lengths: Alternate short punchy statements (4-7 words) with explanatory sentences (14-18 words).");
+    }
+    const rhythm = {
+      sentenceCount: sCount,
+      averageWords: avgWords,
+      standardDeviation: stdDev,
+      hasVariedRhythm,
+      score: rhythmScore
+    };
+    const thirdOfText = Math.floor(content.length / 3);
+    const topPart = content.slice(0, thirdOfText);
+    const midPart = content.slice(thirdOfText, thirdOfText * 2);
+    const botPart = content.slice(thirdOfText * 2);
+    const hasAboveTheFoldCta = this.CTA_REGEX.test(topPart);
+    const hasMidArticleCta = this.CTA_REGEX.test(midPart);
+    const hasBottomCta = this.CTA_REGEX.test(botPart);
+    const allCtas = content.match(this.CTA_REGEX) || [];
+    const isDistributed = (hasAboveTheFoldCta || hasMidArticleCta) && hasBottomCta;
+    if (!isDistributed) {
+      fixes.push("Add a mid-article contextual CTA box to capture readers who don't reach the bottom footer.");
+    }
+    const ctas = {
+      totalCtasDetected: allCtas.length,
+      isDistributedAcrossArticle: isDistributed,
+      hasAboveTheFoldCta,
+      hasMidArticleCta,
+      hasBottomCta
+    };
+    const paragraphs = content.split(/\n\s*\n/).filter((p) => p.trim().length > 20 && !p.startsWith("#"));
+    let longParas = 0;
+    for (const p of paragraphs) {
+      const pSentences = p.split(/[.?!]/).filter((s) => s.trim().length > 3).length;
+      if (pSentences > 4)
+        longParas++;
+    }
+    const isMobileBreathable = longParas <= Math.max(1, Math.floor(paragraphs.length * 0.15));
+    if (!isMobileBreathable) {
+      fixes.push(`Split ${longParas} bulky paragraphs into 2-3 sentence chunks to improve mobile scannability.`);
+    }
+    const paragraphEval = {
+      totalParagraphs: paragraphs.length,
+      longParagraphsCount: longParas,
+      isMobileBreathable
+    };
+    const passedArray = [isStrongHook, hasVariedRhythm, isDistributed, isMobileBreathable];
+    const passedCount = passedArray.filter(Boolean).length;
+    const engagementScore = Math.round(passedCount / 4 * 100);
+    return {
+      engagementScore,
+      allPassed: passedCount === 4,
+      passedCount,
+      hook,
+      rhythm,
+      ctas,
+      paragraphs: paragraphEval,
+      actionableFixes: fixes
+    };
+  }
+}
+
+// src/keyword-density-guard.ts
+class KeywordDensityGuard {
+  static audit(content, primaryKeyword, metaTitle) {
+    if (!content || !primaryKeyword) {
+      return {
+        keyword: primaryKeyword,
+        totalOccurrences: 0,
+        totalWords: 0,
+        densityPercent: 0,
+        status: "too_low",
+        placements: [],
+        consecutiveSentencesWithKeyword: 0,
+        stuffingAlert: false,
+        recommendations: ["Provide content and a target keyword to audit."]
+      };
+    }
+    const words = content.split(/\s+/).filter(Boolean);
+    const totalWords = words.length;
+    const escapedKw = primaryKeyword.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
+    const kwRegex = new RegExp(`\\b${escapedKw}\\b`, "gi");
+    const testKw = (str) => new RegExp(`\\b${escapedKw}\\b`, "i").test(str);
+    const occurrences = (content.match(kwRegex) || []).length;
+    const densityPercent = totalWords > 0 ? Math.round(occurrences / totalWords * 1000) / 10 : 0;
+    const lines = content.split(`
+`);
+    const h1Line = lines.find((l) => l.trim().startsWith("# ")) || "";
+    const h2Lines = lines.filter((l) => l.trim().startsWith("## ")).join(" ");
+    const first100Words = words.slice(0, 100).join(" ");
+    const last100Words = words.slice(-100).join(" ");
+    const inTitle = metaTitle ? testKw(metaTitle) : false;
+    const inH1 = testKw(h1Line);
+    const inFirst100 = testKw(first100Words);
+    const inH2s = (h2Lines.match(new RegExp(`\\b${escapedKw}\\b`, "gi")) || []).length;
+    const inConclusion = testKw(last100Words);
+    const inFaq = /faq|frequently asked/i.test(content) && testKw(content);
+    const placements = [
+      { location: "title", present: inTitle, count: inTitle ? 1 : 0 },
+      { location: "h1", present: inH1, count: inH1 ? 1 : 0 },
+      { location: "first_100_words", present: inFirst100, count: inFirst100 ? 1 : 0 },
+      { location: "h2_headings", present: inH2s > 0, count: inH2s },
+      { location: "conclusion", present: inConclusion, count: inConclusion ? 1 : 0 },
+      { location: "faq", present: inFaq, count: inFaq ? 1 : 0 }
+    ];
+    const sentences = content.split(/[.?!]/).map((s) => s.trim()).filter((s) => s.length > 5);
+    let maxConsecutive = 0;
+    let currentConsecutive = 0;
+    for (const s of sentences) {
+      if (kwRegex.test(s)) {
+        currentConsecutive++;
+        if (currentConsecutive > maxConsecutive)
+          maxConsecutive = currentConsecutive;
+      } else {
+        currentConsecutive = 0;
+      }
+    }
+    const stuffingAlert = densityPercent > 2.2 || maxConsecutive >= 3;
+    let status = "optimal";
+    const recommendations = [];
+    if (densityPercent < 0.8) {
+      status = "too_low";
+      recommendations.push(`Primary keyword density is low (${densityPercent}%). Target: 1.0% - 1.8%.`);
+    } else if (densityPercent > 2.2) {
+      status = "stuffing_risk";
+      recommendations.push(`Keyword stuffing risk detected (${densityPercent}%). Reduce usage and replace with semantic LSI synonyms.`);
+    }
+    if (!inFirst100) {
+      recommendations.push("Include primary keyword naturally in the first 100 words.");
+    }
+    if (!inH1) {
+      recommendations.push("Include primary keyword in the main H1 heading.");
+    }
+    if (inH2s === 0) {
+      recommendations.push("Include primary keyword in at least one H2 subheading.");
+    }
+    if (maxConsecutive >= 3) {
+      recommendations.push(`Keyword appears in ${maxConsecutive} consecutive sentences. Space out mentions to improve natural reading flow.`);
+    }
+    return {
+      keyword: primaryKeyword,
+      totalOccurrences: occurrences,
+      totalWords,
+      densityPercent,
+      status,
+      placements,
+      consecutiveSentencesWithKeyword: maxConsecutive,
+      stuffingAlert,
+      recommendations
+    };
+  }
+}
+
 // src/index.ts
 function createLynxSeoEngine(config) {
   return new LynxSeoEngine(config);
@@ -10804,6 +11071,9 @@ var LynxSeo = {
   searchIntent: SearchIntentClassifier,
   opportunityPrioritizer: SeoOpportunityPrioritizer,
   trustSignals: TrustSignalsExtractor,
+  competitorGap: CompetitorGapBlueprintEngine,
+  engagementHook: EngagementHookAnalyzer,
+  keywordDensity: KeywordDensityGuard,
   inspectMeta: SiteAuditor.inspectMeta,
   crawlDomain: DeepCrawlerAuditor.crawlAndAuditDomain,
   inspectHtmlSnapshot: DeepCrawlerAuditor.inspectHtmlSnapshot,
@@ -10911,6 +11181,7 @@ export {
   KnowledgeGraphLinker,
   KnowledgeBankBuilder,
   KeywordPermutatorEngine,
+  KeywordDensityGuard,
   IsrCacheManager,
   InternalPageRankEngine,
   InstantMatrixSearchEngine,
@@ -10926,12 +11197,14 @@ export {
   FeaturesKnowledgeHarvester,
   ExtendedSchemaGraphBuilder,
   ExistingMediaHarvester,
+  EngagementHookAnalyzer,
   EmbeddableSeoWidgetGenerator,
   DeepCrawlerAuditor,
   CrosslinkScorerEngine,
   CroCopywritingEngine,
   CopywritingFrameworksMaster,
   ContextTemplatesGenerator,
+  CompetitorGapBlueprintEngine,
   CONTENT_AI_40_TOOLS,
   BrandDnaCalendarEngine,
   BacklinksClient,

package/dist/index.mjs

@@ -10782,6 +10782,273 @@ class TrustSignalsExtractor {
   }
 }
 
+// src/competitor-gap-blueprint.ts
+class CompetitorGapBlueprintEngine {
+  static buildBlueprint(targetTopic, userWordCount, competitors) {
+    const gaps = [];
+    const headingCounts = {};
+    const outdatedItems = [];
+    const diffAngles = [];
+    for (const comp of competitors) {
+      for (const h of comp.headings) {
+        const cleanH = h.toLowerCase().trim();
+        headingCounts[cleanH] = (headingCounts[cleanH] || 0) + 1;
+      }
+      if (comp.wordCount < 1500) {
+        gaps.push({
+          gapType: "thin_section",
+          description: `Competitor article is surface-level (${comp.wordCount} words) and lacks concrete implementation steps.`,
+          locationHeading: comp.headings[0] || "Overview",
+          competitorUrl: comp.url,
+          priority: "high",
+          counterOpportunity: `Publish an exhaustive, deep-dive section with interactive code examples, tables, and verifiable benchmarks.`
+        });
+      }
+      if (comp.contentSnippet) {
+        if (/202[0-4]/i.test(comp.contentSnippet)) {
+          outdatedItems.push(`Competitor ${comp.url} contains outdated 2020-2024 benchmarks and legacy screenshots.`);
+        }
+      }
+    }
+    const minThreshold = Math.max(1, Math.floor(competitors.length * 0.4));
+    const expectedCommonHeadings = Object.entries(headingCounts).filter(([_, count]) => count >= minThreshold).map(([h]) => h.charAt(0).toUpperCase() + h.slice(1));
+    diffAngles.push(`Real-Time Performance & In-Memory (O(1)) Speed Benchmarks (Zero competitors currently measure latency)`);
+    diffAngles.push(`AI Engine Optimization (SearchGPT, Perplexity & Gemini citations) with structured direct answer cards`);
+    diffAngles.push(`Interactive ROI / Cost Calculators embeddable directly in the content`);
+    const winningOutlineRecommendation = [
+      `1. Executive Summary & Direct Answer Card (For Google AI Overview & Perplexity)`,
+      ...expectedCommonHeadings.map((h, i) => `${i + 2}. ${h} (With Real Case Studies & Data)`),
+      `${expectedCommonHeadings.length + 2}. Proprietary Benchmark & Comparison Matrix (Our Unique Angle)`,
+      `${expectedCommonHeadings.length + 3}. Step-by-Step Implementation Guide for 2026`,
+      `${expectedCommonHeadings.length + 4}. Frequently Asked Questions (Structured JSON-LD FAQPage)`
+    ];
+    return {
+      mustFillGaps: gaps,
+      expectedCommonHeadings,
+      differentiationAngles: diffAngles,
+      outdatedToUpdate: outdatedItems,
+      winningOutlineRecommendation
+    };
+  }
+}
+
+// src/engagement-hook-analyzer.ts
+class EngagementHookAnalyzer {
+  static GENERIC_BAD_OPENERS = [
+    /^[A-Z][^.!?]*\bis\s+(?:a|an|the)\b/i,
+    /^[A-Z][^.!?]*\bare\s+(?:a|an|the)\b/i,
+    /^When it comes to/i,
+    /^In (?:today['’]s|the|this)\s+(?:digital|modern|world|age|fast-paced)/i,
+    /^If you['’]re (?:looking|searching|trying)/i,
+    /^(?:Many|Most|Some)\s+(?:people|companies|businesses|founders)/i,
+    /^There are (?:many|several|numerous)/i,
+    /^It['’]s (?:no secret|important|essential)/i,
+    /^De nos jours/i,
+    /^Dans le monde digital d'aujourd'hui/i
+  ];
+  static GOOD_HOOK_STARTERS = [
+    { type: "question", pattern: /\?$/ },
+    { type: "statistic", pattern: /^(?:\d+%|\d{1,3}(?:,\d{3})*|\$\d+)/ },
+    { type: "quote", pattern: /^["'«]/ },
+    { type: "thought_experiment", pattern: /^(?:What if|Imagine|Picture this|Here['’]s (?:the truth|what happened)|Et si|Imaginez)/i },
+    { type: "concrete_story", pattern: /^(?:Last (?:week|month|year)|In \d{4}|Hier|Le mois dernier|[A-Z][a-z]+ spent \d+)/i }
+  ];
+  static CTA_REGEX = /(?:Start|Try|Get|Claim|Download|Sign up|Essayer|Démarrer|Obtenir|Profiter|Découvrir|\[.*?→\]|\*\*\[.*?\]\*\*)/gi;
+  static analyze(content) {
+    const lines = content.split(`
+`).map((l) => l.trim()).filter(Boolean);
+    const textOnlyLines = lines.filter((l) => !l.startsWith("#") && !l.startsWith("---") && !l.startsWith("**Meta"));
+    const firstParagraph = textOnlyLines[0] || "";
+    const firstSentence = firstParagraph.split(/[.?!]/)[0]?.trim() || "";
+    const fixes = [];
+    let isStrongHook = false;
+    let hookType = "generic_bad_opener";
+    let hookFeedback = "Opening is generic. Replace with a punchy question, surprising stat, or narrative scenario.";
+    const isGeneric = this.GENERIC_BAD_OPENERS.some((r) => r.test(firstSentence));
+    if (!isGeneric) {
+      for (const h of this.GOOD_HOOK_STARTERS) {
+        if (h.pattern.test(firstSentence) || h.pattern.test(firstParagraph)) {
+          isStrongHook = true;
+          hookType = h.type;
+          hookFeedback = `Excellent hook using a ${h.type.replace("_", " ")}. Captures attention instantly.`;
+          break;
+        }
+      }
+      if (!isStrongHook) {
+        isStrongHook = true;
+        hookType = "concrete_story";
+        hookFeedback = "Opening avoids cliché LLM patterns.";
+      }
+    } else {
+      fixes.push(`Replace generic opener ("${firstSentence.slice(0, 45)}...") with a dramatic question or verified statistic.`);
+    }
+    const hook = {
+      openingSentence: firstSentence,
+      isStrongHook,
+      hookType,
+      feedback: hookFeedback,
+      suggestedHookUpgrade: `What if you could eliminate 80% of manual repetitive tasks in less than 48 hours?`
+    };
+    const rawSentences = content.replace(/([.?!])\s*(?=[A-Z0-9])/g, "$1|").split("|").map((s) => s.trim()).filter((s) => s.length > 5);
+    const sentenceLengths = rawSentences.map((s) => s.split(/\s+/).filter(Boolean).length);
+    const sCount = Math.max(1, sentenceLengths.length);
+    const avgWords = Math.round(sentenceLengths.reduce((a, b) => a + b, 0) / sCount * 10) / 10;
+    const variance = sentenceLengths.reduce((acc, len) => acc + Math.pow(len - avgWords, 2), 0) / sCount;
+    const stdDev = Math.round(Math.sqrt(variance) * 10) / 10;
+    const hasVariedRhythm = stdDev >= 5 && avgWords <= 18;
+    const rhythmScore = Math.min(100, Math.round(stdDev / 8 * 100));
+    if (!hasVariedRhythm) {
+      fixes.push("Vary sentence lengths: Alternate short punchy statements (4-7 words) with explanatory sentences (14-18 words).");
+    }
+    const rhythm = {
+      sentenceCount: sCount,
+      averageWords: avgWords,
+      standardDeviation: stdDev,
+      hasVariedRhythm,
+      score: rhythmScore
+    };
+    const thirdOfText = Math.floor(content.length / 3);
+    const topPart = content.slice(0, thirdOfText);
+    const midPart = content.slice(thirdOfText, thirdOfText * 2);
+    const botPart = content.slice(thirdOfText * 2);
+    const hasAboveTheFoldCta = this.CTA_REGEX.test(topPart);
+    const hasMidArticleCta = this.CTA_REGEX.test(midPart);
+    const hasBottomCta = this.CTA_REGEX.test(botPart);
+    const allCtas = content.match(this.CTA_REGEX) || [];
+    const isDistributed = (hasAboveTheFoldCta || hasMidArticleCta) && hasBottomCta;
+    if (!isDistributed) {
+      fixes.push("Add a mid-article contextual CTA box to capture readers who don't reach the bottom footer.");
+    }
+    const ctas = {
+      totalCtasDetected: allCtas.length,
+      isDistributedAcrossArticle: isDistributed,
+      hasAboveTheFoldCta,
+      hasMidArticleCta,
+      hasBottomCta
+    };
+    const paragraphs = content.split(/\n\s*\n/).filter((p) => p.trim().length > 20 && !p.startsWith("#"));
+    let longParas = 0;
+    for (const p of paragraphs) {
+      const pSentences = p.split(/[.?!]/).filter((s) => s.trim().length > 3).length;
+      if (pSentences > 4)
+        longParas++;
+    }
+    const isMobileBreathable = longParas <= Math.max(1, Math.floor(paragraphs.length * 0.15));
+    if (!isMobileBreathable) {
+      fixes.push(`Split ${longParas} bulky paragraphs into 2-3 sentence chunks to improve mobile scannability.`);
+    }
+    const paragraphEval = {
+      totalParagraphs: paragraphs.length,
+      longParagraphsCount: longParas,
+      isMobileBreathable
+    };
+    const passedArray = [isStrongHook, hasVariedRhythm, isDistributed, isMobileBreathable];
+    const passedCount = passedArray.filter(Boolean).length;
+    const engagementScore = Math.round(passedCount / 4 * 100);
+    return {
+      engagementScore,
+      allPassed: passedCount === 4,
+      passedCount,
+      hook,
+      rhythm,
+      ctas,
+      paragraphs: paragraphEval,
+      actionableFixes: fixes
+    };
+  }
+}
+
+// src/keyword-density-guard.ts
+class KeywordDensityGuard {
+  static audit(content, primaryKeyword, metaTitle) {
+    if (!content || !primaryKeyword) {
+      return {
+        keyword: primaryKeyword,
+        totalOccurrences: 0,
+        totalWords: 0,
+        densityPercent: 0,
+        status: "too_low",
+        placements: [],
+        consecutiveSentencesWithKeyword: 0,
+        stuffingAlert: false,
+        recommendations: ["Provide content and a target keyword to audit."]
+      };
+    }
+    const words = content.split(/\s+/).filter(Boolean);
+    const totalWords = words.length;
+    const escapedKw = primaryKeyword.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
+    const kwRegex = new RegExp(`\\b${escapedKw}\\b`, "gi");
+    const testKw = (str) => new RegExp(`\\b${escapedKw}\\b`, "i").test(str);
+    const occurrences = (content.match(kwRegex) || []).length;
+    const densityPercent = totalWords > 0 ? Math.round(occurrences / totalWords * 1000) / 10 : 0;
+    const lines = content.split(`
+`);
+    const h1Line = lines.find((l) => l.trim().startsWith("# ")) || "";
+    const h2Lines = lines.filter((l) => l.trim().startsWith("## ")).join(" ");
+    const first100Words = words.slice(0, 100).join(" ");
+    const last100Words = words.slice(-100).join(" ");
+    const inTitle = metaTitle ? testKw(metaTitle) : false;
+    const inH1 = testKw(h1Line);
+    const inFirst100 = testKw(first100Words);
+    const inH2s = (h2Lines.match(new RegExp(`\\b${escapedKw}\\b`, "gi")) || []).length;
+    const inConclusion = testKw(last100Words);
+    const inFaq = /faq|frequently asked/i.test(content) && testKw(content);
+    const placements = [
+      { location: "title", present: inTitle, count: inTitle ? 1 : 0 },
+      { location: "h1", present: inH1, count: inH1 ? 1 : 0 },
+      { location: "first_100_words", present: inFirst100, count: inFirst100 ? 1 : 0 },
+      { location: "h2_headings", present: inH2s > 0, count: inH2s },
+      { location: "conclusion", present: inConclusion, count: inConclusion ? 1 : 0 },
+      { location: "faq", present: inFaq, count: inFaq ? 1 : 0 }
+    ];
+    const sentences = content.split(/[.?!]/).map((s) => s.trim()).filter((s) => s.length > 5);
+    let maxConsecutive = 0;
+    let currentConsecutive = 0;
+    for (const s of sentences) {
+      if (kwRegex.test(s)) {
+        currentConsecutive++;
+        if (currentConsecutive > maxConsecutive)
+          maxConsecutive = currentConsecutive;
+      } else {
+        currentConsecutive = 0;
+      }
+    }
+    const stuffingAlert = densityPercent > 2.2 || maxConsecutive >= 3;
+    let status = "optimal";
+    const recommendations = [];
+    if (densityPercent < 0.8) {
+      status = "too_low";
+      recommendations.push(`Primary keyword density is low (${densityPercent}%). Target: 1.0% - 1.8%.`);
+    } else if (densityPercent > 2.2) {
+      status = "stuffing_risk";
+      recommendations.push(`Keyword stuffing risk detected (${densityPercent}%). Reduce usage and replace with semantic LSI synonyms.`);
+    }
+    if (!inFirst100) {
+      recommendations.push("Include primary keyword naturally in the first 100 words.");
+    }
+    if (!inH1) {
+      recommendations.push("Include primary keyword in the main H1 heading.");
+    }
+    if (inH2s === 0) {
+      recommendations.push("Include primary keyword in at least one H2 subheading.");
+    }
+    if (maxConsecutive >= 3) {
+      recommendations.push(`Keyword appears in ${maxConsecutive} consecutive sentences. Space out mentions to improve natural reading flow.`);
+    }
+    return {
+      keyword: primaryKeyword,
+      totalOccurrences: occurrences,
+      totalWords,
+      densityPercent,
+      status,
+      placements,
+      consecutiveSentencesWithKeyword: maxConsecutive,
+      stuffingAlert,
+      recommendations
+    };
+  }
+}
+
 // src/index.ts
 function createLynxSeoEngine(config) {
   return new LynxSeoEngine(config);
@@ -10804,6 +11071,9 @@ var LynxSeo = {
   searchIntent: SearchIntentClassifier,
   opportunityPrioritizer: SeoOpportunityPrioritizer,
   trustSignals: TrustSignalsExtractor,
+  competitorGap: CompetitorGapBlueprintEngine,
+  engagementHook: EngagementHookAnalyzer,
+  keywordDensity: KeywordDensityGuard,
   inspectMeta: SiteAuditor.inspectMeta,
   crawlDomain: DeepCrawlerAuditor.crawlAndAuditDomain,
   inspectHtmlSnapshot: DeepCrawlerAuditor.inspectHtmlSnapshot,
@@ -10911,6 +11181,7 @@ export {
   KnowledgeGraphLinker,
   KnowledgeBankBuilder,
   KeywordPermutatorEngine,
+  KeywordDensityGuard,
   IsrCacheManager,
   InternalPageRankEngine,
   InstantMatrixSearchEngine,
@@ -10926,12 +11197,14 @@ export {
   FeaturesKnowledgeHarvester,
   ExtendedSchemaGraphBuilder,
   ExistingMediaHarvester,
+  EngagementHookAnalyzer,
   EmbeddableSeoWidgetGenerator,
   DeepCrawlerAuditor,
   CrosslinkScorerEngine,
   CroCopywritingEngine,
   CopywritingFrameworksMaster,
   ContextTemplatesGenerator,
+  CompetitorGapBlueprintEngine,
   CONTENT_AI_40_TOOLS,
   BrandDnaCalendarEngine,
   BacklinksClient,

package/dist/keyword-density-guard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 🛡️ Keyword Density Guard & Section Distribution Heatmap
+ * Ported & optimized from Python keyword_analyzer.py.
+ * Calculates exact keyword density, detects keyword stuffing risks (> 2.2%),
+ * and validates placement across Title, H1, First 100 Words, H2s, and FAQ.
+ */
+export interface KeywordPlacementCheck {
+    location: "title" | "h1" | "first_100_words" | "h2_headings" | "conclusion" | "faq";
+    present: boolean;
+    count: number;
+}
+export interface KeywordAnalysisReport {
+    keyword: string;
+    totalOccurrences: number;
+    totalWords: number;
+    densityPercent: number;
+    status: "too_low" | "optimal" | "stuffing_risk";
+    placements: KeywordPlacementCheck[];
+    consecutiveSentencesWithKeyword: number;
+    stuffingAlert: boolean;
+    recommendations: string[];
+}
+export declare class KeywordDensityGuard {
+    /**
+     * Analyzes keyword density and placement integrity.
+     */
+    static audit(content: string, primaryKeyword: string, metaTitle?: string): KeywordAnalysisReport;
+}

package/package.json

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