@jjlmoya/utils-astronomy 1.18.0 → 1.19.0

package/package.json

@@ -1,13 +1,15 @@
 {
     "name": "@jjlmoya/utils-astronomy",
-    "version": "1.18.0",
+    "version": "1.19.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",
     "exports": {
         ".": "./src/index.ts",
         "./data": "./src/data.ts",
-        "./entries": "./src/entries.ts"
+        "./entries": "./src/entries.ts",
+        "./runtime/*": "./src/tool/*/index.ts",
+        "./category-seo": "./src/category/seo.astro"
     },
     "files": [
         "src",

package/src/category/i18n/de.ts

@@ -12,12 +12,12 @@ export const content: CategoryLocaleContent = {
     },
     {
       type: 'paragraph',
-      html: 'Von der Bewertung der Himmelsqualität mit der Bortle-Skala bis hin zur präzisen Berechnung der optischen Auflösung Ihres Teleskops – jedes Tool nutzt von der internationalen Astronomie-Gemeinschaft validierte Formeln, damit jede Nacht unter den Sternen produktiv und unvergesslich wird.',
+      html: 'Von der Bewertung der Himmelsqualität mit der Bortle-Skala bis hin zur präzisen Berechnung der optischen Auflösung Ihres Teleskops - jedes Tool nutzt von der internationalen Astronomie-Gemeinschaft validierte Formeln, damit jede Nacht unter den Sternen produktiv und unvergesslich wird.',
     },
     { type: 'title', text: 'Lichtverschmutzung: Der größte Feind des Astronomen', level: 2 },
     {
       type: 'paragraph',
-      html: 'Wir leben in einer zunehmend beleuchteten Welt. Die <strong>Lichtverschmutzung</strong> wächst jährlich um 10 % und löscht den Nachthimmel für mehr als 80 % der Weltbevölkerung aus. Die Bortle-Skala mit ihren 9 Stufen ist der internationale Standard zur Quantifizierung dieses Verlusts. Unser Dunkelhimmel-Simulator ermöglicht es Ihnen, interaktiv zu visualisieren, wie künstliches Licht das Firmament verändert – vom absoluten Schwarz einer entlegenen Wüste bis zum bedrückenden Orange einer Metropole.',
+      html: 'Wir leben in einer zunehmend beleuchteten Welt. Die <strong>Lichtverschmutzung</strong> wächst jährlich um 10 % und löscht den Nachthimmel für mehr als 80 % der Weltbevölkerung aus. Die Bortle-Skala mit ihren 9 Stufen ist der internationale Standard zur Quantifizierung dieses Verlusts. Unser Dunkelhimmel-Simulator ermöglicht es Ihnen, interaktiv zu visualisieren, wie künstliches Licht das Firmament verändert - vom absoluten Schwarz einer entlegenen Wüste bis zum bedrückenden Orange einer Metropole.',
     },
     { type: 'title', text: 'Ihr Teleskop: Die wahren Möglichkeiten verstehen', level: 2 },
     {

package/src/category/i18n/pl.ts

@@ -12,12 +12,12 @@ export const content: CategoryLocaleContent = {
     },
     {
       type: 'paragraph',
-      html: 'Od oceny jakości nieba w skali Bortle\'a po precyzyjne obliczanie rozdzielczości optycznej teleskopu – każde narzędzie wykorzystuje wzory zatwierdzone przez międzynarodową społeczność astronomiczną, aby każda noc spędzona pod gwiazdami była produktywna i niezapomniana.',
+      html: 'Od oceny jakości nieba w skali Bortle\'a po precyzyjne obliczanie rozdzielczości optycznej teleskopu - każde narzędzie wykorzystuje wzory zatwierdzone przez międzynarodową społeczność astronomiczną, aby każda noc spędzona pod gwiazdami była produktywna i niezapomniana.',
     },
     { type: 'title', text: 'Zanieczyszczenie Światłem: Największy Wróg Astronoma', level: 2 },
     {
       type: 'paragraph',
-      html: 'Żyjemy w coraz bardziej oświetlonym świecie. <strong>Zanieczyszczenie światłem</strong> rośnie w tempie 10% rocznie i wymazuje nocne niebo dla ponad 80% populacji świata. Skala Bortle\'a, z jej 9 poziomami, jest międzynarodowym standardem ilościowego określania tej straty. Nasz symulator ciemnego nieba pozwala na interaktywną wizualizację tego, jak sztuczne światło zmienia firmament – od absolutnej czerni odległej pustyni po uciążliwy pomarańcz metropolii.',
+      html: 'Żyjemy w coraz bardziej oświetlonym świecie. <strong>Zanieczyszczenie światłem</strong> rośnie w tempie 10% rocznie i wymazuje nocne niebo dla ponad 80% populacji świata. Skala Bortle\'a, z jej 9 poziomami, jest międzynarodowym standardem ilościowego określania tej straty. Nasz symulator ciemnego nieba pozwala na interaktywną wizualizację tego, jak sztuczne światło zmienia firmament - od absolutnej czerni odległej pustyni po uciążliwy pomarańcz metropolii.',
     },
     { type: 'title', text: 'Twój Teleskop: Zrozumienie Jego Rzeczywistych Możliwości', level: 2 },
     {

package/src/category/i18n/ru.ts

@@ -8,11 +8,11 @@ export const content: CategoryLocaleContent = {
     { type: 'title', text: 'Любительская астрономия: инструменты для исследования Вселенной', level: 2 },
     {
       type: 'paragraph',
-      html: 'Любительская астрономия — одна из самых захватывающих гражданских наук в мире. С правильным оборудованием и корректными инструментами планирования любой может исследовать галактики в миллионах световых лет от нас, созерцать туманности, где рождаются новые звезды, или изучать поверхность планет нашей Солнечной системы. Этот набор <strong>бесплатных астрономических калькуляторов</strong> разработан, чтобы поднять ваш опыт наблюдателя на новый уровень.',
+      html: 'Любительская астрономия - одна из самых захватывающих гражданских наук в мире. С правильным оборудованием и корректными инструментами планирования любой может исследовать галактики в миллионах световых лет от нас, созерцать туманности, где рождаются новые звезды, или изучать поверхность планет нашей Солнечной системы. Этот набор <strong>бесплатных астрономических калькуляторов</strong> разработан, чтобы поднять ваш опыт наблюдателя на новый уровень.',
     },
     {
       type: 'paragraph',
-      html: 'От оценки качества неба по шкале Бортля до точного расчета оптического разрешения вашего телескопа — каждый инструмент применяет формулы, подтвержденные международным астрономическим сообществом, чтобы каждая ночь, проведенная под звездами, была продуктивной и запоминающейся.',
+      html: 'От оценки качества неба по шкале Бортля до точного расчета оптического разрешения вашего телескопа - каждый инструмент применяет формулы, подтвержденные международным астрономическим сообществом, чтобы каждая ночь, проведенная под звездами, была продуктивной и запоминающейся.',
     },
     { type: 'title', text: 'Световое загрязнение: враг номер один для астронома', level: 2 },
     {
@@ -22,7 +22,7 @@ export const content: CategoryLocaleContent = {
     { type: 'title', text: 'Ваш телескоп: понимание его реальных возможностей', level: 2 },
     {
       type: 'paragraph',
-      html: 'Рынок переполнен телескопами, которые обещают «увидеть Сатурн с его кольцами» при любой апертуре. Реальность такова, что <strong>апертура объектива</strong> является самым критическим параметром. Она определяет, сколько света он собирает (предельная величина) и сколько деталей он может разрешить (разрешающая способность). Калькуляторы дальности и разрешения в этом разделе дают вам конкретные цифры: какие каталоги объектов доступны вашему оборудованию и какую детализацию можно ожидать на поверхностях планет.',
+      html: 'Рынок переполнен телескопами, которые обещают \"увидеть Сатурн с его кольцами\" при любой апертуре. Реальность такова, что <strong>апертура объектива</strong> является самым критическим параметром. Она определяет, сколько света он собирает (предельная величина) и сколько деталей он может разрешить (разрешающая способность). Калькуляторы дальности и разрешения в этом разделе дают вам конкретные цифры: какие каталоги объектов доступны вашему оборудованию и какую детализацию можно ожидать на поверхностях планет.',
     },
     {
       type: 'list',
@@ -41,7 +41,7 @@ export const content: CategoryLocaleContent = {
     { type: 'title', text: 'Астрофотография глубокого космоса: запечатлейте космос', level: 2 },
     {
       type: 'paragraph',
-      html: 'Астрофотография демократизировала доступ к Вселенной. С помощью стандартной зеркальной камеры и широкоугольного объектива вы можете запечатлеть Млечный Путь во всем его великолепии. С телескопом и экваториальной монтировкой вы можете фотографировать туманности и галактики, которые превосходят то, что лучшие обсерватории могли видеть всего несколько десятилетий назад. Ключ кроется в <strong>времени экспозиции</strong>: слишком короткое — и вы потеряете тусклые детали; слишком длинное — и вы получите звездные треки из-за вращения Земли.',
+      html: 'Астрофотография демократизировала доступ к Вселенной. С помощью стандартной зеркальной камеры и широкоугольного объектива вы можете запечатлеть Млечный Путь во всем его великолепии. С телескопом и экваториальной монтировкой вы можете фотографировать туманности и галактики, которые превосходят то, что лучшие обсерватории могли видеть всего несколько десятилетий назад. Ключ кроется в <strong>времени экспозиции</strong>: слишком короткое - и вы потеряете тусклые детали; слишком длинное - и вы получите звездные треки из-за вращения Земли.',
     },
     {
       type: 'stats',

package/src/category/i18n/sv.ts

@@ -12,7 +12,7 @@ export const content: CategoryLocaleContent = {
     },
     {
       type: 'paragraph',
-      html: 'Från att utvärdera himmelskvalitet med Bortle-skalan till att exakt beräkna den optiska upplösningen på ditt teleskop – varje verktyg tillämpar formler som validerats av det internationella astronomiska samfundet så att varje natt du spenderar under stjärnorna blir produktiv och minnesvärd.',
+      html: 'Från att utvärdera himmelskvalitet med Bortle-skalan till att exakt beräkna den optiska upplösningen på ditt teleskop - varje verktyg tillämpar formler som validerats av det internationella astronomiska samfundet så att varje natt du spenderar under stjärnorna blir produktiv och minnesvärd.',
     },
     { type: 'title', text: 'Ljusföroreningar: Astronomens Fiende Nummer Ett', level: 2 },
     {

package/src/category/i18n/zh.ts

@@ -22,7 +22,7 @@ export const content: CategoryLocaleContent = {
     { type: 'title', text: '你的望远镜：理解其真实能力', level: 2 },
     {
       type: 'paragraph',
-      html: '市场上到处都是承诺在任何口径下都能“清晰看到土星光环”的望远镜。现实情况是，<strong>物镜口径</strong> 是最关键的参数。它决定了能收集多少光线（极限星等）以及能辨别多少细节（分辨力）。本节中的量程和分辨率计算器提供了具体的数值：哪些天体目录在你的观测范围内，以及你对行星表面的细节可以有怎样的期待。',
+      html: '市场上到处都是承诺在任何口径下都能\"清晰看到土星光环\"的望远镜。现实情况是，<strong>物镜口径</strong> 是最关键的参数。它决定了能收集多少光线（极限星等）以及能辨别多少细节（分辨力）。本节中的量程和分辨率计算器提供了具体的数值：哪些天体目录在你的观测范围内，以及你对行星表面的细节可以有怎样的期待。',
     },
     {
       type: 'list',

package/src/data.ts

@@ -1,8 +1,3 @@
-export { bortleVisualizer } from './tool/bortleVisualizer';
-export { deepSpaceScope } from './tool/deepSpaceScope';
-export { starExposureCalculator } from './tool/starExposureCalculator';
-export { telescopeResolution } from './tool/telescopeResolution';
-export { EYEPIECE_CALCULATOR_TOOL as eyepieceCalculator } from './tool/smartEyepieceCalculator';
 export { toolsCategory as astronomyCategory } from './category';
 
 export type { BortleVisualizerUI, BortleVisualizerLocaleContent } from './tool/bortleVisualizer';

package/src/layouts/PreviewLayout.astro

@@ -10,7 +10,12 @@ interface Props {
   hasSidebar?: boolean;
 }
 
-const { title, currentLocale = "es", localeUrls = {}, hasSidebar = false } = Astro.props;
+const {
+  title,
+  currentLocale = "es",
+  localeUrls = {},
+  hasSidebar = false,
+} = Astro.props;
 ---
 
 <!doctype html>
@@ -78,6 +83,7 @@ const { title, currentLocale = "es", localeUrls = {}, hasSidebar = false } = Ast
     transition:
       background-color 0.3s ease,
       color 0.3s ease;
+    font-family: Inter, sans-serif;
   }
 
   main {
@@ -114,4 +120,3 @@ const { title, currentLocale = "es", localeUrls = {}, hasSidebar = false } = Ast
     }
   }
 </style>
-

package/src/tests/diacritics_density.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+
+type LocaleWithDiacritics = keyof typeof DIACRITIC_RULES;
+
+const DIACRITIC_RULES = {
+  de: {
+    language: 'German',
+    expectedCharacters: 'ä ö ü ß',
+    characters: /[äöüÄÖÜß]/g,
+    minPerThousandLetters: 0.1,
+  },
+  es: {
+    language: 'Spanish',
+    expectedCharacters: 'á é í ó ú ü ñ',
+    characters: /[áéíóúüñÁÉÍÓÚÜÑ]/g,
+    minPerThousandLetters: 0.1,
+  },
+  fr: {
+    language: 'French',
+    expectedCharacters: 'à â æ ç é è ê ë î ï ô œ ù û ü ÿ',
+    characters: /[àâæçéèêëîïôœùûüÿÀÂÆÇÉÈÊËÎÏÔŒÙÛÜŸ]/g,
+    minPerThousandLetters: 0.1,
+  },
+  it: {
+    language: 'Italian',
+    expectedCharacters: 'à è é ì í î ò ó ù ú',
+    characters: /[àèéìíîòóùúÀÈÉÌÍÎÒÓÙÚ]/g,
+    minPerThousandLetters: 0.1,
+  },
+  pl: {
+    language: 'Polish',
+    expectedCharacters: 'ą ć ę ł ń ó ś ź ż',
+    characters: /[ąćęłńóśźżĄĆĘŁŃÓŚŹŻ]/g,
+    minPerThousandLetters: 0.1,
+  },
+  pt: {
+    language: 'Portuguese',
+    expectedCharacters: 'á â ã à ç é ê í ó ô õ ú ü',
+    characters: /[áâãàçéêíóôõúüÁÂÃÀÇÉÊÍÓÔÕÚÜ]/g,
+    minPerThousandLetters: 0.1,
+  },
+  sv: {
+    language: 'Swedish',
+    expectedCharacters: 'å ä ö',
+    characters: /[åäöÅÄÖ]/g,
+    minPerThousandLetters: 0.1,
+  },
+  tr: {
+    language: 'Turkish',
+    expectedCharacters: 'ç ğ ı İ ö ş ü',
+    characters: /[çğıöşüÇĞİÖŞÜ]/g,
+    minPerThousandLetters: 0.1,
+  },
+} as const;
+
+const LETTERS = /\p{L}/gu;
+const TRANSLATABLE_KEYS = ['title', 'description', 'ui', 'seo', 'faq', 'howTo'] as const;
+
+function collectStrings(value: unknown): string[] {
+  if (typeof value === 'string') return [value];
+  if (!value || typeof value !== 'object') return [];
+  if (Array.isArray(value)) return value.flatMap(collectStrings);
+  return Object.values(value).flatMap(collectStrings);
+}
+
+function normalizeText(value: unknown): string {
+  return collectStrings(value).join(' ').normalize('NFC');
+}
+
+function translatableContent(content: Record<string, unknown>) {
+  return TRANSLATABLE_KEYS.map((key) => content[key]);
+}
+
+function letterCount(text: string): number {
+  return text.match(LETTERS)?.length ?? 0;
+}
+
+function diacriticCount(text: string, locale: LocaleWithDiacritics): number {
+  return text.match(DIACRITIC_RULES[locale].characters)?.length ?? 0;
+}
+
+function diacriticsPerThousandLetters(text: string, locale: LocaleWithDiacritics): number {
+  const letters = letterCount(text);
+  if (letters === 0) return 0;
+  return diacriticCount(text, locale) / letters * 1000;
+}
+
+describe('Diacritics density validation', () => {
+  ALL_TOOLS.forEach((tool) => {
+    describe(`Tool: ${tool.entry.id}`, () => {
+      Object.keys(DIACRITIC_RULES).forEach((locale) => {
+        it(`${locale} keeps the expected accent and special-letter set`, async () => {
+          const typedLocale = locale as LocaleWithDiacritics;
+          const loader = tool.entry.i18n[typedLocale];
+          if (!loader) return;
+
+          const content = await loader();
+          const text = normalizeText(translatableContent(content as Record<string, unknown>));
+          const rule = DIACRITIC_RULES[typedLocale];
+          const letters = letterCount(text);
+          const matches = diacriticCount(text, typedLocale);
+          const density = diacriticsPerThousandLetters(text, typedLocale);
+
+          expect(
+            density,
+            [
+              `Possible spelling or encoding issue detected in ${tool.entry.id}/${typedLocale} (${rule.language}).`,
+              `The text has ${matches} special characters (${density.toFixed(2)} per 1000 letters, ${letters} letters analyzed).`,
+              `This locale should include some of these characters: ${rule.expectedCharacters}.`,
+              'If the count is 0 or near 0, accents, tildes, or special letters were probably stripped by encoding or normalization.',
+            ].join(' '),
+          ).toBeGreaterThanOrEqual(rule.minPerThousandLetters);
+        });
+      });
+    });
+  });
+});

package/src/tests/inverted_punctuation.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+
+const INVERTED_PUNCTUATION_LOCALES = {
+  es: {
+    language: 'Spanish',
+    questionStart: '¿',
+    questionEnd: '?',
+    exclamationStart: '¡',
+    exclamationEnd: '!',
+  },
+} as const;
+
+type InvertedPunctuationLocale = keyof typeof INVERTED_PUNCTUATION_LOCALES;
+
+const TRANSLATABLE_KEYS = ['title', 'description', 'ui', 'seo', 'faq', 'howTo'] as const;
+
+function collectStrings(value: unknown): string[] {
+  if (typeof value === 'string') return [value];
+  if (!value || typeof value !== 'object') return [];
+  if (Array.isArray(value)) return value.flatMap(collectStrings);
+  return Object.values(value).flatMap(collectStrings);
+}
+
+function translatableStrings(content: Record<string, unknown>): string[] {
+  return TRANSLATABLE_KEYS.flatMap((key) => collectStrings(content[key]));
+}
+
+function sentenceStart(text: string, endIndex: number): string {
+  const beforeMark = text.slice(0, endIndex).trimEnd();
+  const boundary = Math.max(
+    beforeMark.lastIndexOf('.'),
+    beforeMark.lastIndexOf(':'),
+    beforeMark.lastIndexOf(';'),
+    beforeMark.lastIndexOf('\n'),
+  );
+
+  return beforeMark.slice(boundary + 1).trimStart();
+}
+
+function findMissingInvertedMarks(
+  text: string,
+  startMark: string,
+  endMark: string,
+): string[] {
+  return [...text.matchAll(new RegExp(`\\${endMark}`, 'g'))]
+    .map((match) => sentenceStart(text, match.index ?? 0))
+    .filter((segment) => segment.length > 0 && !segment.includes(startMark))
+    .map((segment) => `${segment}${endMark}`);
+}
+
+describe('Inverted punctuation validation', () => {
+  ALL_TOOLS.forEach((tool) => {
+    describe(`Tool: ${tool.entry.id}`, () => {
+      Object.keys(INVERTED_PUNCTUATION_LOCALES).forEach((locale) => {
+        it(`${locale} uses opening punctuation marks for questions and exclamations`, async () => {
+          const typedLocale = locale as InvertedPunctuationLocale;
+          const loader = tool.entry.i18n[typedLocale];
+          if (!loader) return;
+
+          const rule = INVERTED_PUNCTUATION_LOCALES[typedLocale];
+          const content = await loader();
+          const strings = translatableStrings(content as Record<string, unknown>);
+          const missingQuestions = strings.flatMap((text) =>
+            findMissingInvertedMarks(text, rule.questionStart, rule.questionEnd)
+          );
+          const missingExclamations = strings.flatMap((text) =>
+            findMissingInvertedMarks(text, rule.exclamationStart, rule.exclamationEnd)
+          );
+          const failures = [...missingQuestions, ...missingExclamations];
+
+          expect(
+            failures,
+            [
+              `Missing opening punctuation marks in ${tool.entry.id}/${typedLocale} (${rule.language}).`,
+              `Questions must use ${rule.questionStart}...${rule.questionEnd} and exclamations must use ${rule.exclamationStart}...${rule.exclamationEnd}.`,
+              `Examples: ${failures.slice(0, 5).join(' | ')}`,
+            ].join(' '),
+          ).toHaveLength(0);
+        });
+      });
+    });
+  });
+});

package/src/tests/no_en_dash.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+
+function getFiles(dir: string): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) {
+    return results;
+  }
+  const list = fs.readdirSync(dir);
+  for (const file of list) {
+    const fullPath = path.join(dir, file);
+    const stat = fs.statSync(fullPath);
+    if (stat && stat.isDirectory()) {
+      if (file !== 'tests' && file !== 'node_modules' && file !== '.astro') {
+        results.push(...getFiles(fullPath));
+      }
+    } else {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function isContentFile(filePath: string): boolean {
+  return /\\i18n\\/.test(filePath) || filePath.endsWith('bibliography.ts');
+}
+
+const srcDir = path.join(process.cwd(), 'src');
+const scriptsDir = path.join(process.cwd(), 'scripts');
+const filesToTest = [
+  ...getFiles(srcDir).filter(isContentFile),
+  ...getFiles(scriptsDir).filter(isContentFile),
+];
+
+const aiTypographyGarbage = [
+  '\u2013',
+  '\u2014',
+  '\u2026',
+  '\u201C',
+  '\u201D',
+  '\u2018',
+  '\u2019',
+  '\u00AB',
+  '\u00BB',
+  '\u200B',
+  '\u201E',
+];
+
+describe('Typography Garbage Character Validation', () => {
+  filesToTest.forEach((filePath) => {
+    const relativePath = path.relative(process.cwd(), filePath);
+    it(`should not contain typography garbage characters in ${relativePath}`, () => {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const hasAiPatterns = aiTypographyGarbage.some(char => content.includes(char));
+      expect(hasAiPatterns).toBe(false);
+    });
+
+    it(`should not contain space before colon in ${relativePath}`, () => {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const spaceBeforeColon = / : /.test(content);
+      expect(spaceBeforeColon).toBe(false);
+    });
+
+    it(`should not contain double hyphen in ${relativePath}`, () => {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      expect(content).not.toContain('--');
+    });
+  });
+});

package/src/tests/pagespeed_best_practices.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it } from 'vitest';
+import { readdirSync, readFileSync } from 'fs';
+import { join, relative } from 'path';
+import { ALL_TOOLS } from '../tools';
+import type { SEOSection, ToolLocaleContent } from '../types';
+
+const srcDir = join(process.cwd(), 'src');
+const toolDir = join(srcDir, 'tool');
+const geometryReads = [
+  'offsetWidth',
+  'offsetHeight',
+  'offsetTop',
+  'offsetLeft',
+  'clientWidth',
+  'clientHeight',
+  'clientTop',
+  'clientLeft',
+  'scrollWidth',
+  'scrollHeight',
+  'scrollTop',
+  'scrollLeft',
+  'getBoundingClientRect',
+  'getClientRects',
+  'computedStyle',
+  'getComputedStyle',
+];
+const domWrites = [
+  '.style.',
+  '.classList.add',
+  '.classList.remove',
+  '.classList.toggle',
+  '.appendChild',
+  '.insertBefore',
+  '.prepend',
+  '.append',
+  '.remove',
+  '.innerHTML',
+  '.textContent',
+  '.setAttribute',
+];
+
+function findFiles(dir: string, extensions: string[]): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...findFiles(fullPath, extensions));
+    else if (extensions.some((extension) => entry.name.endsWith(extension))) files.push(fullPath);
+  }
+  return files;
+}
+
+function relativePath(file: string): string {
+  return relative(process.cwd(), file).replace(/\\/g, '/');
+}
+
+function findFormControls(content: string, tagName: 'input' | 'select'): RegExpMatchArray[] {
+  return Array.from(content.matchAll(new RegExp(`<${tagName}\\b[^>]*>`, 'gi')));
+}
+
+function attrValue(tag: string, attr: string): string | null {
+  const match = tag.match(new RegExp(`\\b${attr}\\s*=\\s*(?:"([^"]+)"|'([^']+)'|\\{([^}]+)\\})`, 'i'));
+  return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
+}
+
+function booleanAttr(tag: string, attr: string): boolean {
+  return new RegExp(`\\b${attr}\\b`, 'i').test(tag);
+}
+
+function controlStartIndex(content: string, tag: RegExpMatchArray): number {
+  return tag.index ?? content.indexOf(tag[0]);
+}
+
+function hasWrappingLabel(content: string, tag: RegExpMatchArray): boolean {
+  const index = controlStartIndex(content, tag);
+  const before = content.slice(0, index);
+  const labelOpen = before.lastIndexOf('<label');
+  const labelClose = before.lastIndexOf('</label>');
+  const nextLabelClose = content.indexOf('</label>', index + tag[0].length);
+  return labelOpen > labelClose && nextLabelClose !== -1;
+}
+
+function hasAccessibleName(content: string, tag: RegExpMatchArray): boolean {
+  const source = tag[0];
+  if (attrValue(source, 'aria-label')) return true;
+  if (attrValue(source, 'aria-labelledby')) return true;
+  const id = attrValue(source, 'id');
+  if (id && hasExplicitLabel(content, id)) return true;
+  return hasWrappingLabel(content, tag);
+}
+
+function isVisuallyHiddenFileInput(tag: string): boolean {
+  const type = attrValue(tag, 'type')?.toLowerCase() ?? 'text';
+  const attributes = `${attrValue(tag, 'style') ?? ''} ${attrValue(tag, 'class') ?? ''}`.toLowerCase();
+  const hiddenPatterns = ['display:none', 'display: none', 'file-input'];
+  return type === 'file' && hiddenPatterns.some((pattern) => attributes.includes(pattern));
+}
+
+function isIgnoredInput(tag: string): boolean {
+  const type = attrValue(tag, 'type')?.toLowerCase() ?? 'text';
+  return ['hidden', 'button', 'submit', 'reset'].includes(type) || booleanAttr(tag, 'aria-hidden') || isVisuallyHiddenFileInput(tag);
+}
+
+function controlFailures(content: string, tagName: 'input' | 'select'): string[] {
+  return findFormControls(content, tagName)
+    .filter((tag) => tagName !== 'input' || !isIgnoredInput(tag[0]))
+    .filter((tag) => !hasAccessibleName(content, tag))
+    .map((tag) => tag[0]);
+}
+
+function explicitLabelMessage(tagName: string, path: string, failures: string[]): string {
+  return `${tagName} controls without label, wrapping label, aria-label or aria-labelledby in ${path}:\n${failures.join('\n')}`;
+}
+
+function hasExplicitLabel(content: string, id: string): boolean {
+  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return (
+    new RegExp(`<label\\b[^>]*\\bfor\\s*=\\s*["']${escapedId}["'][^>]*>`, 'i').test(content)
+    || new RegExp(`<label\\b[^>]*\\bfor\\s*=\\s*\\{${escapedId}\\}[^>]*>`, 'i').test(content)
+  );
+}
+
+function headingLevels(sections: SEOSection[]): number[] {
+  return sections
+    .filter((section) => section.type === 'title')
+    .map((section) => Number('level' in section ? section.level : 0))
+    .filter((level) => Number.isInteger(level) && level > 0);
+}
+
+function findHeadingLevelJumps(levels: number[]): string[] {
+  const failures: string[] = [];
+  levels.forEach((level, index) => {
+    const previous = index === 0 ? 1 : levels[index - 1];
+    if (previous && level > previous + 1) {
+      failures.push(`h${previous} -> h${level}`);
+    }
+  });
+  return failures;
+}
+
+function hasDomWriteBeforeGeometryRead(content: string): boolean {
+  const normalized = content.replace(/\s+/g, ' ');
+  return domWrites.some((write) => {
+    const writeIndex = normalized.indexOf(write);
+    if (writeIndex === -1) return false;
+    return geometryReads.some((read) => normalized.indexOf(read, writeIndex + write.length) !== -1);
+  });
+}
+
+describe('PageSpeed best-practice guards', () => {
+  const astroToolFiles = findFiles(toolDir, ['.astro']);
+  const scriptFiles = findFiles(toolDir, ['.astro', '.ts', '.js']);
+
+  astroToolFiles.forEach((file) => {
+    const displayPath = relativePath(file);
+
+    it(`${displayPath} labels every input with an explicit label`, () => {
+      const content = readFileSync(file, 'utf-8');
+      const failures = controlFailures(content, 'input');
+
+      expect(failures, explicitLabelMessage('Input', displayPath, failures)).toEqual([]);
+    });
+
+    it(`${displayPath} labels every select with an explicit label`, () => {
+      const content = readFileSync(file, 'utf-8');
+      const failures = controlFailures(content, 'select');
+
+      expect(failures, explicitLabelMessage('Select', displayPath, failures)).toEqual([]);
+    });
+  });
+
+  ALL_TOOLS.forEach((tool) => {
+    Object.entries(tool.entry.i18n).forEach(([locale, loader]) => {
+      it(`${tool.entry.id}/${locale} keeps SEO headings sequential`, async () => {
+        if (!loader) return;
+        const content = (await loader()) as ToolLocaleContent;
+        const levels = headingLevels(content.seo);
+        const failures = findHeadingLevelJumps(levels);
+
+        expect(
+          failures,
+          `SEO headings in ${tool.entry.id}/${locale} skip levels: ${failures.join(', ')}`,
+        ).toEqual([]);
+      });
+    });
+  });
+
+  scriptFiles.forEach((file) => {
+    const displayPath = relativePath(file);
+
+    it(`${displayPath} avoids static forced-reflow patterns`, () => {
+      const content = readFileSync(file, 'utf-8');
+      expect(
+        hasDomWriteBeforeGeometryRead(content),
+        `${displayPath} appears to read layout geometry after DOM/style mutations. Split writes and reads across frames or measure before mutating.`,
+      ).toBe(false);
+    });
+  });
+});