recker 1.0.43 → 1.0.44

package/dist/browser/seo/rules/i18n.js

@@ -0,0 +1,288 @@
+import { createResult } from './types.js';
+export const i18nRules = [
+    {
+        id: 'i18n-hreflang-exists',
+        name: 'Hreflang Tags',
+        category: 'technical',
+        severity: 'warning',
+        description: 'Multi-language sites should have hreflang tags for proper language targeting',
+        check: (ctx) => {
+            if (!ctx.hreflangTags || ctx.hreflangTags.length === 0) {
+                if (ctx.hasLang && ctx.langValue && ctx.langValue !== 'en') {
+                    return createResult({ id: 'i18n-hreflang-exists', name: 'Hreflang Tags', category: 'technical', severity: 'warning' }, 'info', 'No hreflang tags found (recommended for multi-language sites)', {
+                        recommendation: 'Add hreflang tags to indicate language/region alternatives',
+                        evidence: {
+                            expected: '<link rel="alternate" hreflang="en" href="https://example.com/en/">',
+                            example: '<link rel="alternate" hreflang="en" href="https://example.com/en/">\n<link rel="alternate" hreflang="es" href="https://example.com/es/">\n<link rel="alternate" hreflang="x-default" href="https://example.com/">',
+                            impact: 'Without hreflang, search engines may show wrong language version to users in different countries',
+                            learnMore: 'https://developers.google.com/search/docs/specialty/international/localized-versions',
+                        },
+                    });
+                }
+                return createResult({ id: 'i18n-hreflang-exists', name: 'Hreflang Tags', category: 'technical', severity: 'warning' }, 'info', 'No hreflang tags found', {
+                    recommendation: 'Consider adding hreflang tags if you have multi-language versions of this page',
+                });
+            }
+            return createResult({ id: 'i18n-hreflang-exists', name: 'Hreflang Tags', category: 'technical', severity: 'warning' }, 'pass', `${ctx.hreflangTags.length} hreflang tag(s) found`, { value: ctx.hreflangTags.length });
+        },
+    },
+    {
+        id: 'i18n-hreflang-self',
+        name: 'Hreflang Self-Reference',
+        category: 'technical',
+        severity: 'warning',
+        description: 'Hreflang tags should include a self-referencing tag for the current page',
+        check: (ctx) => {
+            if (!ctx.hreflangTags || ctx.hreflangTags.length === 0) {
+                return createResult({ id: 'i18n-hreflang-self', name: 'Hreflang Self-Reference', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no hreflang tags)', {
+                    recommendation: 'Add hreflang tags first, then ensure self-reference is included',
+                });
+            }
+            if (!ctx.url) {
+                return createResult({ id: 'i18n-hreflang-self', name: 'Hreflang Self-Reference', category: 'technical', severity: 'warning' }, 'info', 'Cannot verify (URL not available)');
+            }
+            const currentUrl = ctx.url.toLowerCase().replace(/\/$/, '');
+            const hasSelfRef = ctx.hreflangTags.some((tag) => {
+                const href = tag.href?.toLowerCase().replace(/\/$/, '');
+                return href === currentUrl;
+            });
+            if (!hasSelfRef) {
+                return createResult({ id: 'i18n-hreflang-self', name: 'Hreflang Self-Reference', category: 'technical', severity: 'warning' }, 'warn', 'Missing self-referencing hreflang tag', {
+                    recommendation: 'Add a hreflang tag that points to the current page',
+                    evidence: {
+                        found: `Current URL: ${ctx.url}`,
+                        expected: `<link rel="alternate" hreflang="${ctx.langValue || 'en'}" href="${ctx.url}">`,
+                        impact: 'Google recommends including a self-referencing hreflang tag for clarity',
+                        example: `<link rel="alternate" hreflang="en" href="${ctx.url}">\n<link rel="alternate" hreflang="es" href="${ctx.url.replace(/\/en\//, '/es/')}">`,
+                    },
+                });
+            }
+            return createResult({ id: 'i18n-hreflang-self', name: 'Hreflang Self-Reference', category: 'technical', severity: 'warning' }, 'pass', 'Self-referencing hreflang tag present');
+        },
+    },
+    {
+        id: 'i18n-hreflang-x-default',
+        name: 'Hreflang X-Default',
+        category: 'technical',
+        severity: 'info',
+        description: 'Include x-default hreflang for users outside defined regions',
+        check: (ctx) => {
+            if (!ctx.hreflangTags || ctx.hreflangTags.length < 2) {
+                return createResult({ id: 'i18n-hreflang-x-default', name: 'Hreflang X-Default', category: 'technical', severity: 'info' }, 'info', 'Not applicable (need 2+ hreflang tags for x-default)', {
+                    recommendation: 'Add multiple hreflang tags to support international visitors',
+                });
+            }
+            const hasXDefault = ctx.hreflangTags.some((tag) => tag.lang === 'x-default');
+            if (!hasXDefault) {
+                return createResult({ id: 'i18n-hreflang-x-default', name: 'Hreflang X-Default', category: 'technical', severity: 'info' }, 'info', 'No x-default hreflang tag found', {
+                    recommendation: 'Add hreflang="x-default" to specify the fallback page for unmatched languages',
+                    evidence: {
+                        expected: '<link rel="alternate" hreflang="x-default" href="https://example.com/">',
+                        impact: 'Without x-default, users in unsupported regions may not see the best version',
+                    },
+                });
+            }
+            return createResult({ id: 'i18n-hreflang-x-default', name: 'Hreflang X-Default', category: 'technical', severity: 'info' }, 'pass', 'x-default hreflang tag present');
+        },
+    },
+    {
+        id: 'i18n-hreflang-valid-codes',
+        name: 'Hreflang Valid Codes',
+        category: 'technical',
+        severity: 'warning',
+        description: 'Hreflang language codes must be valid ISO 639-1 codes',
+        check: (ctx) => {
+            if (!ctx.hreflangTags || ctx.hreflangTags.length === 0) {
+                return createResult({ id: 'i18n-hreflang-valid-codes', name: 'Hreflang Valid Codes', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no hreflang tags)');
+            }
+            const validLanguageCodes = new Set([
+                'aa', 'ab', 'af', 'ak', 'sq', 'am', 'ar', 'an', 'hy', 'as', 'av', 'ae', 'ay', 'az',
+                'ba', 'bm', 'eu', 'be', 'bn', 'bh', 'bi', 'bo', 'bs', 'br', 'bg', 'my', 'ca', 'cs',
+                'ch', 'ce', 'zh', 'cu', 'cv', 'kw', 'co', 'cr', 'cy', 'da', 'de', 'dv', 'nl', 'dz',
+                'en', 'eo', 'et', 'ee', 'fo', 'fa', 'fj', 'fi', 'fr', 'fy', 'ff', 'ka', 'el', 'gn',
+                'gu', 'ht', 'ha', 'he', 'hz', 'hi', 'ho', 'hr', 'hu', 'ig', 'is', 'io', 'ii', 'iu',
+                'ie', 'ia', 'id', 'ik', 'it', 'jv', 'ja', 'kl', 'kn', 'ks', 'kr', 'kk', 'km', 'ki',
+                'rw', 'ky', 'kv', 'kg', 'ko', 'kj', 'ku', 'lo', 'la', 'lv', 'li', 'ln', 'lt', 'lb',
+                'lu', 'lg', 'mk', 'mh', 'ml', 'mi', 'mr', 'ms', 'mg', 'mt', 'mn', 'na', 'nv', 'nr',
+                'nd', 'ng', 'ne', 'nn', 'nb', 'no', 'ny', 'oc', 'oj', 'or', 'om', 'os', 'pa', 'pi',
+                'pl', 'pt', 'ps', 'qu', 'rm', 'ro', 'rn', 'ru', 'sg', 'sa', 'si', 'sk', 'sl', 'se',
+                'sm', 'sn', 'sd', 'so', 'st', 'es', 'sc', 'sr', 'ss', 'su', 'sw', 'sv', 'ty', 'ta',
+                'tt', 'te', 'tg', 'tl', 'th', 'ti', 'to', 'tn', 'ts', 'tk', 'tr', 'tw', 'ug', 'uk',
+                'ur', 'uz', 've', 'vi', 'vo', 'wa', 'wo', 'xh', 'yi', 'yo', 'za', 'zu',
+                'x-default',
+            ]);
+            const invalidTags = [];
+            for (const tag of ctx.hreflangTags) {
+                const lang = tag.lang?.toLowerCase().split('-')[0];
+                if (lang && !validLanguageCodes.has(lang)) {
+                    invalidTags.push(tag.lang);
+                }
+            }
+            if (invalidTags.length > 0) {
+                return createResult({ id: 'i18n-hreflang-valid-codes', name: 'Hreflang Valid Codes', category: 'technical', severity: 'warning' }, 'warn', `Invalid hreflang codes: ${invalidTags.join(', ')}`, {
+                    recommendation: 'Use valid ISO 639-1 language codes',
+                    evidence: {
+                        found: invalidTags,
+                        expected: 'Valid ISO 639-1 codes like: en, es, fr, de, pt-BR, zh-CN',
+                        impact: 'Invalid language codes will be ignored by search engines, breaking international targeting',
+                        example: '<link rel="alternate" hreflang="en-US" href="https://example.com/en/">\n<link rel="alternate" hreflang="es-ES" href="https://example.com/es/">',
+                        learnMore: 'https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes',
+                    },
+                });
+            }
+            return createResult({ id: 'i18n-hreflang-valid-codes', name: 'Hreflang Valid Codes', category: 'technical', severity: 'warning' }, 'pass', 'All hreflang codes are valid ISO 639-1');
+        },
+    },
+    {
+        id: 'i18n-hreflang-return-links',
+        name: 'Hreflang Return Links',
+        category: 'technical',
+        severity: 'warning',
+        description: 'All hreflang URLs should return links back to this page (bidirectional)',
+        check: (ctx) => {
+            if (!ctx.hreflangTags || ctx.hreflangTags.length < 2) {
+                return createResult({ id: 'i18n-hreflang-return-links', name: 'Hreflang Return Links', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (need 2+ hreflang tags)', {
+                    recommendation: 'Add hreflang tags to enable return link verification',
+                });
+            }
+            return createResult({ id: 'i18n-hreflang-return-links', name: 'Hreflang Return Links', category: 'technical', severity: 'warning' }, 'info', 'Hreflang return links cannot be verified from HTML alone', {
+                recommendation: 'Ensure all alternate pages link back to this page with matching hreflang tags',
+                evidence: {
+                    impact: 'Missing return links can cause Google to ignore hreflang annotations',
+                    learnMore: 'https://developers.google.com/search/docs/specialty/international/localized-versions#bidirectional',
+                },
+            });
+        },
+    },
+    {
+        id: 'i18n-content-language',
+        name: 'Content-Language Header',
+        category: 'technical',
+        severity: 'info',
+        description: 'Content-Language header can indicate the language of the document',
+        check: (ctx) => {
+            if (!ctx.responseHeaders) {
+                return createResult({ id: 'i18n-content-language', name: 'Content-Language Header', category: 'technical', severity: 'info' }, 'info', 'Cannot verify (response headers not available)');
+            }
+            const contentLang = ctx.responseHeaders['content-language'] || ctx.responseHeaders['Content-Language'];
+            if (!contentLang) {
+                return createResult({ id: 'i18n-content-language', name: 'Content-Language Header', category: 'technical', severity: 'info' }, 'info', 'Content-Language header not set', {
+                    recommendation: `Consider adding Content-Language: ${ctx.langValue || 'en'} header`,
+                    evidence: {
+                        impact: 'While not critical for SEO, it helps with content negotiation',
+                    },
+                });
+            }
+            if (ctx.langValue) {
+                const headerLang = Array.isArray(contentLang) ? contentLang[0] : contentLang;
+                const headerLangPrimary = headerLang.toLowerCase().split('-')[0].split(',')[0].trim();
+                const htmlLangPrimary = ctx.langValue.toLowerCase().split('-')[0];
+                if (headerLangPrimary !== htmlLangPrimary) {
+                    return createResult({ id: 'i18n-content-language', name: 'Content-Language Header', category: 'technical', severity: 'info' }, 'warn', `Content-Language (${headerLang}) doesn't match html lang (${ctx.langValue})`, {
+                        recommendation: 'Ensure Content-Language header matches the html lang attribute',
+                        evidence: {
+                            found: `Content-Language: ${headerLang}, html lang="${ctx.langValue}"`,
+                            expected: 'Both should declare the same language',
+                            impact: 'Mismatched language declarations can confuse browsers and search engines',
+                        },
+                    });
+                }
+            }
+            return createResult({ id: 'i18n-content-language', name: 'Content-Language Header', category: 'technical', severity: 'info' }, 'pass', `Content-Language: ${contentLang}`);
+        },
+    },
+    {
+        id: 'i18n-lang-consistency',
+        name: 'Language Consistency',
+        category: 'technical',
+        severity: 'warning',
+        description: 'HTML lang attribute should match the og:locale if present',
+        check: (ctx) => {
+            if (!ctx.hasLang && !ctx.ogLocale) {
+                return createResult({ id: 'i18n-lang-consistency', name: 'Language Consistency', category: 'technical', severity: 'warning' }, 'info', 'No lang attribute or og:locale to compare', {
+                    recommendation: 'Add html lang attribute and og:locale for language consistency',
+                });
+            }
+            if (!ctx.hasLang || !ctx.ogLocale) {
+                return createResult({ id: 'i18n-lang-consistency', name: 'Language Consistency', category: 'technical', severity: 'warning' }, 'info', ctx.hasLang ? 'No og:locale to compare with html lang' : 'No html lang to compare with og:locale', {
+                    recommendation: ctx.hasLang
+                        ? 'Add og:locale meta tag for social platforms'
+                        : 'Add html lang attribute for language declaration',
+                });
+            }
+            const htmlLang = ctx.langValue?.toLowerCase().split('-')[0];
+            const ogLocaleLang = ctx.ogLocale.toLowerCase().split('_')[0];
+            if (htmlLang !== ogLocaleLang) {
+                return createResult({ id: 'i18n-lang-consistency', name: 'Language Consistency', category: 'technical', severity: 'warning' }, 'warn', `Language mismatch: html lang="${ctx.langValue}" vs og:locale="${ctx.ogLocale}"`, {
+                    recommendation: 'Ensure html lang and og:locale represent the same language',
+                    evidence: {
+                        found: [`html lang="${ctx.langValue}"`, `og:locale="${ctx.ogLocale}"`],
+                        expected: 'Both attributes should use the same language code',
+                        impact: 'Inconsistent language signals can confuse search engines and social platforms',
+                        example: '<html lang="en">\n<meta property="og:locale" content="en_US">',
+                    },
+                });
+            }
+            return createResult({ id: 'i18n-lang-consistency', name: 'Language Consistency', category: 'technical', severity: 'warning' }, 'pass', `Language consistent: html lang="${ctx.langValue}", og:locale="${ctx.ogLocale}"`);
+        },
+    },
+    {
+        id: 'i18n-lang-region',
+        name: 'Language Region Specificity',
+        category: 'technical',
+        severity: 'info',
+        description: 'Consider using region-specific language codes for better targeting',
+        check: (ctx) => {
+            if (!ctx.hasLang || !ctx.langValue) {
+                return createResult({ id: 'i18n-lang-region', name: 'Language Region Specificity', category: 'technical', severity: 'info' }, 'info', 'No lang attribute to analyze', {
+                    recommendation: 'Add html lang attribute first',
+                });
+            }
+            const multiRegionalLangs = ['en', 'es', 'pt', 'zh', 'fr', 'de', 'ar'];
+            const langPrimary = ctx.langValue.toLowerCase().split('-')[0];
+            if (multiRegionalLangs.includes(langPrimary) && !ctx.langValue.includes('-')) {
+                return createResult({ id: 'i18n-lang-region', name: 'Language Region Specificity', category: 'technical', severity: 'info' }, 'info', `Consider using region-specific lang code (e.g., ${langPrimary}-US, ${langPrimary}-GB)`, {
+                    recommendation: 'For multi-regional languages, specify the region for better targeting',
+                    evidence: {
+                        found: ctx.langValue,
+                        expected: `${langPrimary}-XX (e.g., en-US, es-ES, pt-BR, zh-CN)`,
+                        impact: 'Helps search engines serve the right regional variant',
+                    },
+                });
+            }
+            return createResult({ id: 'i18n-lang-region', name: 'Language Region Specificity', category: 'technical', severity: 'info' }, 'pass', `Lang attribute: ${ctx.langValue}`);
+        },
+    },
+    {
+        id: 'hreflang-language-mismatch',
+        name: 'Hreflang Language Mismatch',
+        category: 'technical',
+        severity: 'warning',
+        description: 'Hreflang language should match page content language',
+        check: (ctx) => {
+            if (!ctx.hreflangTags || ctx.hreflangTags.length === 0) {
+                return createResult({ id: 'hreflang-language-mismatch', name: 'Hreflang Language Mismatch', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no hreflang tags)');
+            }
+            if (!ctx.detectedLanguage) {
+                return createResult({ id: 'hreflang-language-mismatch', name: 'Hreflang Language Mismatch', category: 'technical', severity: 'warning' }, 'info', 'Cannot verify (language detection not available)');
+            }
+            const selfHreflang = ctx.hreflangTags.find(tag => tag.href === ctx.url || tag.href === ctx.canonicalUrl);
+            if (selfHreflang && ctx.detectedLanguage) {
+                const hreflangLang = selfHreflang.lang.split('-')[0].toLowerCase();
+                const detectedLang = ctx.detectedLanguage.toLowerCase();
+                if (hreflangLang !== detectedLang && hreflangLang !== 'x-default') {
+                    return createResult({ id: 'hreflang-language-mismatch', name: 'Hreflang Language Mismatch', category: 'technical', severity: 'warning' }, 'warn', `Hreflang declares "${selfHreflang.lang}" but content appears to be "${ctx.detectedLanguage}"`, {
+                        recommendation: 'Verify the hreflang attribute matches the actual page language',
+                        evidence: {
+                            found: `hreflang="${selfHreflang.lang}", detected content language: "${ctx.detectedLanguage}"`,
+                            expected: `hreflang="${ctx.detectedLanguage}"`,
+                            impact: 'Language mismatch may confuse search engines and affect international SEO',
+                            example: `<link rel="alternate" hreflang="${ctx.detectedLanguage}" href="${ctx.url}">`,
+                        }
+                    });
+                }
+            }
+            return createResult({ id: 'hreflang-language-mismatch', name: 'Hreflang Language Mismatch', category: 'technical', severity: 'warning' }, 'pass', 'Hreflang language matches detected content language');
+        },
+    },
+];

package/dist/browser/seo/rules/images.d.ts

@@ -0,0 +1,2 @@
+import { SeoRule } from './types.js';
+export declare const imageRules: SeoRule[];

package/dist/browser/seo/rules/images.js

@@ -0,0 +1,255 @@
+import { createResult } from './types.js';
+import { SEO_THRESHOLDS } from './thresholds.js';
+export const imageRules = [
+    {
+        id: 'images-alt-text',
+        name: 'Image Alt Text',
+        category: 'images',
+        severity: 'error',
+        description: 'All images must have alt text',
+        check: (ctx) => {
+            if (ctx.totalImages === undefined || ctx.totalImages === 0) {
+                return createResult({ id: 'images-alt-text', name: 'Image Alt Text', category: 'images', severity: 'error' }, 'info', 'Not applicable (no images detected)', { recommendation: 'This rule ensures all images have descriptive alt text for accessibility and SEO' });
+            }
+            const withoutAlt = ctx.imagesWithoutAlt ?? 0;
+            if (withoutAlt > 0) {
+                const percentage = Math.round((withoutAlt / ctx.totalImages) * 100);
+                const severity = withoutAlt > ctx.totalImages / 2 ? 'fail' : 'warn';
+                return createResult({ id: 'images-alt-text', name: 'Image Alt Text', category: 'images', severity: 'error' }, severity, `${withoutAlt} of ${ctx.totalImages} images missing alt text (${percentage}%)`, {
+                    value: withoutAlt,
+                    recommendation: 'Add descriptive alt text to all images. Describe what the image shows and its relevance to the content.',
+                    evidence: {
+                        found: `${withoutAlt} images without alt attribute`,
+                        expected: 'All images should have meaningful alt text',
+                        impact: 'Missing alt text hurts accessibility (screen readers) and prevents images from appearing in Google Image Search. Alt text is also used as anchor text when images are linked.',
+                        example: '<img src="product.jpg" alt="Red leather wallet with zipper closure - front view">',
+                        learnMore: 'https://developers.google.com/search/docs/appearance/google-images#use-descriptive-alt-text'
+                    }
+                });
+            }
+            return createResult({ id: 'images-alt-text', name: 'Image Alt Text', category: 'images', severity: 'error' }, 'pass', 'All images have alt text');
+        },
+    },
+    {
+        id: 'images-dimensions',
+        name: 'Image Dimensions',
+        category: 'images',
+        severity: 'warning',
+        description: 'Images should have width and height attributes to prevent CLS',
+        check: (ctx) => {
+            if (ctx.totalImages === undefined || ctx.totalImages === 0) {
+                return createResult({ id: 'images-dimensions', name: 'Image Dimensions', category: 'images', severity: 'warning' }, 'info', 'Not applicable (no images detected)', { recommendation: 'This rule checks that images have width and height attributes to prevent layout shifts' });
+            }
+            const missing = ctx.imagesMissingDimensions ?? 0;
+            if (missing > 0) {
+                const percentage = Math.round((missing / ctx.totalImages) * 100);
+                return createResult({ id: 'images-dimensions', name: 'Image Dimensions', category: 'images', severity: 'warning' }, 'warn', `${missing} of ${ctx.totalImages} images missing width/height (${percentage}%)`, {
+                    value: missing,
+                    recommendation: 'Add explicit width and height attributes to all images to reserve space and prevent layout shifts.',
+                    evidence: {
+                        found: `${missing} images without dimensions`,
+                        expected: 'All images should have width and height attributes',
+                        impact: 'Images without dimensions cause Cumulative Layout Shift (CLS), which negatively affects Core Web Vitals and user experience.',
+                        example: '<img src="photo.jpg" width="800" height="600" alt="Description">',
+                        learnMore: 'https://web.dev/optimize-cls/#images-without-dimensions'
+                    }
+                });
+            }
+            return createResult({ id: 'images-dimensions', name: 'Image Dimensions', category: 'images', severity: 'warning' }, 'pass', 'All images have dimensions defined');
+        },
+    },
+    {
+        id: 'images-lazy-loading',
+        name: 'Lazy Loading',
+        category: 'images',
+        severity: 'info',
+        description: 'Below-the-fold images should use lazy loading',
+        check: (ctx) => {
+            if (ctx.totalImages === undefined || ctx.totalImages <= 3) {
+                return createResult({ id: 'images-lazy-loading', name: 'Lazy Loading', category: 'images', severity: 'info' }, 'info', 'Not applicable (too few images to require lazy loading)', { recommendation: 'This rule checks for lazy loading on pages with multiple images' });
+            }
+            const lazy = ctx.imagesWithLazyLoad ?? 0;
+            if (lazy === 0) {
+                return createResult({ id: 'images-lazy-loading', name: 'Lazy Loading', category: 'images', severity: 'info' }, 'info', 'No images use lazy loading', {
+                    recommendation: 'Add loading="lazy" to below-the-fold images to defer loading until they are near the viewport.',
+                    evidence: {
+                        found: 'No images with loading="lazy"',
+                        expected: 'Below-the-fold images should use lazy loading',
+                        impact: 'Lazy loading reduces initial page load time, saves bandwidth, and improves Core Web Vitals (LCP).',
+                        example: '<img src="photo.jpg" loading="lazy" alt="Description">',
+                        learnMore: 'https://web.dev/browser-level-image-lazy-loading/'
+                    }
+                });
+            }
+            return createResult({ id: 'images-lazy-loading', name: 'Lazy Loading', category: 'images', severity: 'info' }, 'pass', `${lazy} images use lazy loading`);
+        },
+    },
+    {
+        id: 'images-format-modern',
+        name: 'Modern Image Formats',
+        category: 'images',
+        severity: 'info',
+        description: 'Images should use modern formats like WebP or AVIF',
+        check: (ctx) => {
+            if (ctx.totalImages === undefined || ctx.totalImages === 0) {
+                return createResult({ id: 'images-format-modern', name: 'Modern Image Formats', category: 'images', severity: 'info' }, 'info', 'Not applicable (no images detected)', { recommendation: 'This rule checks for modern image formats like WebP and AVIF for better performance' });
+            }
+            const modern = ctx.imagesUsingModernFormats ?? 0;
+            if (ctx.totalImages > 0 && modern === 0) {
+                return createResult({ id: 'images-format-modern', name: 'Modern Image Formats', category: 'images', severity: 'info' }, 'info', 'No images using modern formats (WebP/AVIF)', {
+                    value: modern,
+                    recommendation: 'Convert images to WebP or AVIF format for 25-50% smaller file sizes with same quality.',
+                    evidence: {
+                        found: 'Only traditional formats (JPEG, PNG, GIF)',
+                        expected: 'At least some images in WebP or AVIF format',
+                        impact: 'Modern formats significantly reduce page weight and improve load times. WebP has 94% browser support.',
+                        example: '<picture>\n  <source srcset="image.avif" type="image/avif">\n  <source srcset="image.webp" type="image/webp">\n  <img src="image.jpg" alt="Description">\n</picture>',
+                        learnMore: 'https://web.dev/uses-webp-images/'
+                    }
+                });
+            }
+            return createResult({ id: 'images-format-modern', name: 'Modern Image Formats', category: 'images', severity: 'info' }, 'pass', `${modern} images using modern formats`, { value: modern });
+        },
+    },
+    {
+        id: 'images-empty-alt',
+        name: 'Empty Alt Text',
+        category: 'images',
+        severity: 'info',
+        description: 'Images with empty alt="" are treated as decorative',
+        check: (ctx) => {
+            const emptyAlt = ctx.imagesWithEmptyAlt ?? 0;
+            if (emptyAlt > 0) {
+                return createResult({ id: 'images-empty-alt', name: 'Empty Alt Text', category: 'images', severity: 'info' }, 'info', `${emptyAlt} image(s) with empty alt="" (decorative)`, { value: emptyAlt, recommendation: 'Ensure these images are truly decorative' });
+            }
+            return createResult({ id: 'images-empty-alt', name: 'Empty Alt Text', category: 'images', severity: 'info' }, 'pass', 'No images with empty alt attributes');
+        },
+    },
+    {
+        id: 'images-alt-length',
+        name: 'Alt Text Length',
+        category: 'images',
+        severity: 'warning',
+        description: 'Alt text should be descriptive (ideal 80-120, max 150 chars)',
+        check: (ctx) => {
+            if (!ctx.altTextLengths || ctx.altTextLengths.length === 0) {
+                return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'warning' }, 'info', 'Not applicable (no alt text data available)', { recommendation: 'This rule checks alt text length to ensure descriptions are meaningful' });
+            }
+            const { minLength, idealLength, maxLength } = SEO_THRESHOLDS.images.alt;
+            let shortAlts = 0;
+            let longAlts = 0;
+            let nonIdealAlts = 0;
+            ctx.altTextLengths.forEach(len => {
+                if (len < minLength)
+                    shortAlts++;
+                else if (len > maxLength)
+                    longAlts++;
+                else if (len < idealLength.min || len > idealLength.max)
+                    nonIdealAlts++;
+            });
+            if (shortAlts > 0) {
+                return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'warning' }, 'warn', `${shortAlts} alt text(s) are too short (min: ${minLength} chars)`, {
+                    value: shortAlts,
+                    recommendation: `Make alt texts more descriptive, at least ${minLength} characters.`,
+                    evidence: {
+                        found: `${shortAlts} alt text(s) with less than ${minLength} characters`,
+                        expected: `Alt text should be at least ${minLength} characters to be meaningful`,
+                        impact: 'Very short alt text (like "logo" or "pic") doesn\'t provide enough context for screen readers or search engines, reducing accessibility and SEO value.',
+                        example: 'Instead of alt="logo", use alt="Acme Corp logo - handshake symbol representing trust"',
+                        learnMore: 'https://www.w3.org/WAI/tutorials/images/'
+                    }
+                });
+            }
+            if (longAlts > 0) {
+                return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'warning' }, 'warn', `${longAlts} alt text(s) are too long (max: ${maxLength} chars)`, {
+                    value: longAlts,
+                    recommendation: `Shorten alt texts to be concise, under ${maxLength} characters.`,
+                    evidence: {
+                        found: `${longAlts} alt text(s) exceeding ${maxLength} characters`,
+                        expected: `Alt text should be under ${maxLength} characters for optimal accessibility`,
+                        impact: 'Excessively long alt text can be tedious for screen reader users and may get truncated in search results. Keep it concise while still being descriptive.',
+                        example: 'Instead of a long paragraph, use concise descriptions like: alt="Professional headshot of Jane Smith, CEO, wearing navy blue suit"',
+                        learnMore: 'https://www.w3.org/WAI/tutorials/images/'
+                    }
+                });
+            }
+            if (nonIdealAlts > 0) {
+                return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'info' }, 'info', `${nonIdealAlts} alt text(s) are not in the ideal length range (${idealLength.min}-${idealLength.max} chars)`, { value: nonIdealAlts, recommendation: `Aim for alt texts between ${idealLength.min} and ${idealLength.max} characters for best results.` });
+            }
+            return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'warning' }, 'pass', 'All alt text lengths are within ideal range');
+        },
+    },
+    {
+        id: 'images-clean-filenames',
+        name: 'Image Filenames',
+        category: 'images',
+        severity: 'info',
+        description: 'Image filenames should be descriptive and use keywords, not generic names.',
+        check: (ctx) => {
+            if (!ctx.imageFilenames || ctx.imageFilenames.length === 0) {
+                return createResult({ id: 'images-clean-filenames', name: 'Image Filenames', category: 'images', severity: 'info' }, 'info', 'Not applicable (no image filename data available)', { recommendation: 'This rule checks for descriptive image filenames with keywords' });
+            }
+            const genericFilenames = ctx.imageFilenames.filter(name => /^(img|image|photo|pic)\d*\.(jpg|jpeg|png|webp|avif|gif)$/i.test(name) ||
+                /^screenshot_\d*\.(jpg|jpeg|png)$/i.test(name) ||
+                /^untitled-\d*\.(jpg|jpeg|png)$/i.test(name));
+            if (genericFilenames.length > 0) {
+                return createResult({ id: 'images-clean-filenames', name: 'Image Filenames', category: 'images', severity: 'warning' }, 'warn', `${genericFilenames.length} image(s) have generic filenames`, {
+                    value: genericFilenames.length,
+                    recommendation: 'Rename image files to be descriptive and include relevant keywords.',
+                    evidence: {
+                        found: genericFilenames.slice(0, 5),
+                        expected: 'Descriptive filenames with keywords (e.g., red-leather-wallet-front.jpg)',
+                        impact: 'Image filenames are used by search engines to understand image content and can appear in Google Image Search.',
+                        example: 'Instead of "IMG_1234.jpg", use "blue-running-shoes-nike-air.jpg"',
+                        learnMore: 'https://developers.google.com/search/docs/appearance/google-images#descriptive-titles-captions-filenames'
+                    }
+                });
+            }
+            return createResult({ id: 'images-clean-filenames', name: 'Image Filenames', category: 'images', severity: 'info' }, 'pass', 'All image filenames are descriptive');
+        },
+    },
+    {
+        id: 'images-decoding-async',
+        name: 'Image Decoding Async',
+        category: 'images',
+        severity: 'info',
+        description: 'Use decoding="async" for non-critical images to improve rendering performance.',
+        check: (ctx) => {
+            if (ctx.totalImages === undefined || ctx.totalImages === 0) {
+                return createResult({ id: 'images-decoding-async', name: 'Image Decoding Async', category: 'images', severity: 'info' }, 'info', 'Not applicable (no images detected)', { recommendation: 'This rule checks for async decoding on images for better rendering performance' });
+            }
+            if (ctx.imagesWithAsyncDecoding === undefined) {
+                return createResult({ id: 'images-decoding-async', name: 'Image Decoding Async', category: 'images', severity: 'info' }, 'info', 'Not applicable (async decoding data unavailable)', { recommendation: 'This rule checks for async decoding on images for better rendering performance' });
+            }
+            const nonAsync = ctx.totalImages - ctx.imagesWithAsyncDecoding;
+            if (nonAsync > 0 && ctx.totalImages > 3) {
+                return createResult({ id: 'images-decoding-async', name: 'Image Decoding Async', category: 'images', severity: 'info' }, 'info', `${nonAsync} image(s) do not use decoding="async"`, { value: nonAsync, recommendation: 'Consider adding decoding="async" to non-critical images for performance benefits.' });
+            }
+            return createResult({ id: 'images-decoding-async', name: 'Image Decoding Async', category: 'images', severity: 'info' }, 'pass', 'All images use async decoding or too few images to require it');
+        },
+    },
+    {
+        id: 'broken-external-images',
+        name: 'Broken External Images',
+        category: 'images',
+        severity: 'warning',
+        description: 'External images should be accessible',
+        check: (ctx) => {
+            if (ctx.brokenExternalImages === undefined) {
+                return createResult({ id: 'broken-external-images', name: 'Broken External Images', category: 'images', severity: 'warning' }, 'info', 'Not applicable (broken external images data unavailable)', { recommendation: 'This rule checks for broken external image references' });
+            }
+            if (ctx.brokenExternalImages > 0) {
+                return createResult({ id: 'broken-external-images', name: 'Broken External Images', category: 'images', severity: 'warning' }, 'warn', `${ctx.brokenExternalImages} broken external images`, {
+                    value: ctx.brokenExternalImages,
+                    recommendation: 'Fix or remove broken external image references',
+                    evidence: {
+                        found: ctx.brokenExternalImageUrls?.slice(0, 5) || [],
+                        expected: 'All images should load successfully',
+                        impact: 'Broken images negatively affect user experience and may signal poor maintenance'
+                    }
+                });
+            }
+            return createResult({ id: 'broken-external-images', name: 'Broken External Images', category: 'images', severity: 'warning' }, 'pass', 'No broken external images detected');
+        },
+    },
+];

package/dist/browser/seo/rules/index.d.ts

@@ -0,0 +1,52 @@
+import { SeoRule, RuleCategory, RuleSeverity, RuleContext, RuleResult } from './types.js';
+export * from './types.js';
+export * from './thresholds.js';
+export declare const ALL_SEO_RULES: SeoRule[];
+export declare const SCORING_WEIGHTS: {
+    readonly severity: {
+        readonly error: {
+            readonly pass: 10;
+            readonly fail: -15;
+            readonly warn: -10;
+            readonly info: 0;
+        };
+        readonly warning: {
+            readonly pass: 5;
+            readonly fail: -8;
+            readonly warn: -5;
+            readonly info: 0;
+        };
+        readonly info: {
+            readonly pass: 2;
+            readonly fail: -3;
+            readonly warn: -2;
+            readonly info: 0;
+        };
+    };
+    readonly category: Record<RuleCategory, number>;
+};
+export declare function calculateWeightedScore(results: RuleResult[]): {
+    score: number;
+    maxPossible: number;
+    details: {
+        category: RuleCategory;
+        score: number;
+        weight: number;
+    }[];
+};
+export interface RulesEngineOptions {
+    categories?: RuleCategory[];
+    excludeCategories?: RuleCategory[];
+    rules?: string[];
+    excludeRules?: string[];
+    minSeverity?: RuleSeverity;
+}
+export declare class SeoRulesEngine {
+    private rules;
+    constructor(options?: RulesEngineOptions);
+    evaluate(context: RuleContext): RuleResult[];
+    getRules(): SeoRule[];
+    getRulesByCategory(category: RuleCategory): SeoRule[];
+    getCategories(): RuleCategory[];
+}
+export declare function createRulesEngine(options?: RulesEngineOptions): SeoRulesEngine;