@jjlmoya/utils-converters 1.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@jjlmoya/utils-converters",
+  "version": "1.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./data": "./src/data.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro",
+    "lint": "eslint src/ --max-warnings 0 && stylelint \"src/**/*.{css,astro}\"",
+    "check": "astro check",
+    "type-check": "astro check",
+    "test": "vitest run",
+    "preversion": "npm run lint && npm run test",
+    "postversion": "git push && git push --tags",
+    "patch": "npm version patch",
+    "minor": "npm version minor",
+    "major": "npm version major"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,astro}": [
+      "eslint --fix"
+    ]
+  },
+  "dependencies": {
+    "@iconify-json/mdi": "^1.2.3",
+    "@jjlmoya/utils-shared": "1.0.2",
+    "astro": "^6.1.2",
+    "astro-icon": "^1.1.0",
+    "jszip": "^3.10.1"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.8",
+    "eslint": "^9.39.4",
+    "eslint-plugin-astro": "^1.6.0",
+    "eslint-plugin-no-comments": "^1.1.10",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "postcss-html": "^1.8.1",
+    "schema-dts": "^1.1.2",
+    "stylelint": "^17.6.0",
+    "stylelint-config-standard": "^40.0.0",
+    "stylelint-declaration-strict-value": "^1.11.1",
+    "typescript": "^5.4.0",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^4.1.2"
+  }
+}

package/src/category/i18n/en.ts

@@ -0,0 +1,90 @@
+import type { CategoryLocaleContent } from '../../types';
+
+export const content: CategoryLocaleContent = {
+  slug: 'image-converters',
+  title: 'Online Image Converters',
+  description: 'Free tools to convert images between PNG, JPG, WebP, SVG, AVIF, GIF, BMP and ICO formats. Everything is processed locally in your browser without uploading anything to the internet.',
+  seo: [
+    {
+      type: 'summary',
+      title: 'Why use our converters',
+      items: [
+        '100% local conversion: your images never leave your device.',
+        'Support for 21 format combinations: PNG, JPG, WebP, SVG, AVIF, GIF, BMP and ICO.',
+        'Batch processing with ZIP download.',
+        'No registration, no limits, no intrusive ads.',
+      ],
+    },
+    {
+      type: 'title',
+      text: 'Image Conversion: Complete Format Guide',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'Choosing the right image format has a direct impact on web performance, device compatibility and perceived visual quality. Our <strong>online image converters</strong> cover the most demanded conversion routes by designers, web developers and photographers, all without relying on external servers that could compromise the privacy of your files.',
+    },
+    {
+      type: 'title',
+      text: 'PNG, JPG and WebP: The Three Pillars of Modern Web Design',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: '<strong>PNG format</strong> stands out for its lossless compression and transparency support (alpha channel), being the standard for logos, icons and graphics with sharp edges. <strong>JPG format</strong> offers maximum universal compatibility and reduced sizes for photos, but sacrifices quality with each save. <strong>WebP format</strong>, developed by Google, combines the best of both: 30-40% better compression than PNG/JPG with transparency and animation support, now the recommended format by Core Web Vitals to improve LCP.',
+    },
+    {
+      type: 'table',
+      headers: ['Format', 'Transparency', 'Compression', 'Best for'],
+      rows: [
+        ['PNG', 'Yes', 'Lossless', 'Logos, graphics, screenshots'],
+        ['JPG', 'No', 'Lossy', 'Photos, large images'],
+        ['WebP', 'Yes', 'Lossless/Lossy', 'Modern web, performance'],
+        ['SVG', 'Yes', 'Vector', 'Scalable icons, animations'],
+        ['AVIF', 'Yes', 'Superior', 'Next-gen web'],
+        ['ICO', 'Yes', 'Bitmap', 'Favicons, Windows icons'],
+      ],
+    },
+    {
+      type: 'title',
+      text: 'Next-Generation Formats: AVIF and WebP',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: '<strong>AVIF format</strong> (AV1 Image File Format) is the technological successor of WebP, offering up to 50% less file size than JPG at equal subjective quality. Although its adoption grows rapidly, limited compatibility in older systems makes converting AVIF to more established formats like JPG, PNG or WebP a frequent need in production workflows.',
+    },
+    {
+      type: 'tip',
+      title: 'Web performance tip',
+      html: 'To maximize page load speed, use WebP as the primary format on your website with JPG/PNG fallbacks for older browsers. The HTML <code>picture</code> element with multiple <code>source</code> tags lets you serve the optimal format based on the visiting browser\'s support.',
+    },
+    {
+      type: 'title',
+      text: 'SVG, BMP and ICO: Special Use Cases',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: '<strong>SVG files</strong> are mathematical vectors that scale losslessly to any resolution, perfect for logos and graphic design. However, many platforms and editing applications do not support them directly, making it necessary to rasterize them to PNG or JPG for distribution. <strong>BMP files</strong>, though obsolete for web use, remain common in Windows environments and legacy editing software. Finally, the <strong>ICO format</strong> is the standard for web favicons and Windows icon customization, requiring a specific binary header structure that our converter generates natively.',
+    },
+    {
+      type: 'stats',
+      columns: 3,
+      items: [
+        { label: 'Combinations', value: '21', icon: 'mdi:image-sync' },
+        { label: 'Privacy', value: '100% local', icon: 'mdi:shield-lock' },
+        { label: 'Formats', value: '8 types', icon: 'mdi:file-image' },
+      ],
+    },
+    {
+      type: 'title',
+      text: 'Total Privacy: Conversion without Servers',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'Unlike other online tools that upload your images to remote servers (with the privacy and security risks that entails), our converters use exclusively native browser APIs: <strong>Canvas 2D API</strong> for rasterization, <strong>FileReader API</strong> to read files locally and <strong>Blob/URL.createObjectURL</strong> for downloads. This means you can convert confidential images, corporate logos or private documents with complete security.',
+    },
+  ],
+};

package/src/category/i18n/es.ts

@@ -0,0 +1,90 @@
+import type { CategoryLocaleContent } from '../../types';
+
+export const content: CategoryLocaleContent = {
+  slug: 'convertidores-imagen',
+  title: 'Convertidores de Imagen Online',
+  description: 'Herramientas gratuitas para convertir imágenes entre formatos PNG, JPG, WebP, SVG, AVIF, GIF, BMP e ICO. Todo se procesa localmente en tu navegador sin subir nada a internet.',
+  seo: [
+    {
+      type: 'summary',
+      title: 'Por qué usar nuestros convertidores',
+      items: [
+        'Conversión 100% local: tus imágenes nunca salen de tu dispositivo.',
+        'Soporte para 21 combinaciones de formatos: PNG, JPG, WebP, SVG, AVIF, GIF, BMP e ICO.',
+        'Procesamiento por lotes con descarga en ZIP.',
+        'Sin registro, sin límites, sin publicidad intrusiva.',
+      ],
+    },
+    {
+      type: 'title',
+      text: 'Conversión de Imágenes: Guía Completa de Formatos',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'La elección del formato de imagen adecuado tiene un impacto directo en el rendimiento web, la compatibilidad con dispositivos y la calidad visual percibida. Nuestros <strong>convertidores de imagen online</strong> cubren las rutas de conversión más demandadas por diseñadores, desarrolladores web y fotógrafos, todo ello sin depender de servidores externos que podrían comprometer la privacidad de tus archivos.',
+    },
+    {
+      type: 'title',
+      text: 'PNG, JPG y WebP: Los Tres Pilares del Diseño Web Moderno',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'El <strong>formato PNG</strong> destaca por su compresión sin pérdida y soporte para transparencias (canal alfa), siendo el estándar para logotipos, iconos y gráficos con bordes nítidos. El <strong>formato JPG</strong> ofrece la máxima compatibilidad universal y tamaños reducidos para fotografías, pero sacrifica calidad en cada guardado. El <strong>formato WebP</strong>, desarrollado por Google, combina lo mejor de ambos: compresión un 30-40% superior a PNG/JPG con soporte de transparencias y animaciones, siendo hoy el formato recomendado por Core Web Vitals para mejorar el LCP.',
+    },
+    {
+      type: 'table',
+      headers: ['Formato', 'Transparencia', 'Compresión', 'Mejor para'],
+      rows: [
+        ['PNG', 'Sí', 'Sin pérdida', 'Logos, gráficos, capturas'],
+        ['JPG', 'No', 'Con pérdida', 'Fotografías, imágenes grandes'],
+        ['WebP', 'Sí', 'Sin/Con pérdida', 'Web moderna, rendimiento'],
+        ['SVG', 'Sí', 'Vectorial', 'Iconos escalables, animaciones'],
+        ['AVIF', 'Sí', 'Superior', 'Siguiente generación web'],
+        ['ICO', 'Sí', 'Bitmap', 'Favicons, iconos Windows'],
+      ],
+    },
+    {
+      type: 'title',
+      text: 'Formatos de Nueva Generación: AVIF y WebP',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'El <strong>formato AVIF</strong> (AV1 Image File Format) es el sucesor tecnológico del WebP, ofreciendo hasta un 50% menos de peso que el JPG a igual calidad subjetiva. Aunque su adopción crece rápidamente, la compatibilidad limitada en sistemas antiguos hace que convertir AVIF a formatos más establecidos como JPG, PNG o WebP sea una necesidad frecuente en flujos de trabajo de producción.',
+    },
+    {
+      type: 'tip',
+      title: 'Consejo de rendimiento web',
+      html: 'Para maximizar la velocidad de carga, usa WebP como formato principal en tu web con fallbacks JPG/PNG para navegadores antiguos. Herramientas como <code>picture</code> con múltiples <code>source</code> te permiten servir el formato óptimo según el soporte del navegador visitante.',
+    },
+    {
+      type: 'title',
+      text: 'SVG, BMP e ICO: Casos de Uso Especiales',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'Los <strong>archivos SVG</strong> son vectores matemáticos que escalan sin pérdida a cualquier resolución, perfectos para logotipos y diseño gráfico. Sin embargo, muchas plataformas y aplicaciones de edición no los soportan directamente, lo que hace necesario rasterizarlos a PNG o JPG para distribución. Los <strong>archivos BMP</strong>, aunque obsoletos para uso web, siguen siendo comunes en entornos Windows y software de edición legacy. Finalmente, el <strong>formato ICO</strong> es el estándar para favicons web y personalización de iconos en Windows, requiriendo una estructura de cabecera binaria específica que nuestro convertidor genera de forma nativa.',
+    },
+    {
+      type: 'stats',
+      columns: 3,
+      items: [
+        { label: 'Combinaciones', value: '21', icon: 'mdi:image-sync' },
+        { label: 'Privacidad', value: '100% local', icon: 'mdi:shield-lock' },
+        { label: 'Formatos', value: '8 tipos', icon: 'mdi:file-image' },
+      ],
+    },
+    {
+      type: 'title',
+      text: 'Privacidad Total: Conversión sin Servidores',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'A diferencia de otras herramientas online que suben tus imágenes a servidores remotos (con los riesgos de privacidad y seguridad que eso implica), nuestros convertidores utilizan exclusivamente las APIs nativas del navegador: <strong>Canvas 2D API</strong> para la rasterización, <strong>FileReader API</strong> para leer los archivos localmente y <strong>Blob/URL.createObjectURL</strong> para las descargas. Esto significa que puedes convertir imágenes confidenciales, logos corporativos o documentos privados con total seguridad.',
+    },
+  ],
+};

package/src/category/i18n/fr.ts

@@ -0,0 +1,90 @@
+import type { CategoryLocaleContent } from '../../types';
+
+export const content: CategoryLocaleContent = {
+  slug: 'convertisseurs-image',
+  title: 'Convertisseurs d\'Image en Ligne',
+  description: 'Outils gratuits pour convertir des images entre les formats PNG, JPG, WebP, SVG, AVIF, GIF, BMP et ICO. Tout est traité localement dans votre navigateur sans rien télécharger sur internet.',
+  seo: [
+    {
+      type: 'summary',
+      title: 'Pourquoi utiliser nos convertisseurs',
+      items: [
+        'Conversion 100% locale : vos images ne quittent jamais votre appareil.',
+        'Support de 21 combinaisons de formats : PNG, JPG, WebP, SVG, AVIF, GIF, BMP et ICO.',
+        'Traitement par lots avec téléchargement ZIP.',
+        'Sans inscription, sans limites, sans publicité intrusive.',
+      ],
+    },
+    {
+      type: 'title',
+      text: 'Conversion d\'Images : Guide Complet des Formats',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'Le choix du format d\'image approprié a un impact direct sur les performances web, la compatibilité avec les appareils et la qualité visuelle perçue. Nos <strong>convertisseurs d\'image en ligne</strong> couvrent les routes de conversion les plus demandées par les designers, développeurs web et photographes, sans dépendre de serveurs externes qui pourraient compromettre la confidentialité de vos fichiers.',
+    },
+    {
+      type: 'title',
+      text: 'PNG, JPG et WebP : Les Trois Piliers du Web Moderne',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'Le <strong>format PNG</strong> se distingue par sa compression sans perte et son support de la transparence (canal alpha), étant le standard pour les logos, icônes et graphiques aux bords nets. Le <strong>format JPG</strong> offre une compatibilité universelle maximale et des tailles réduites pour les photos, mais sacrifie la qualité à chaque sauvegarde. Le <strong>format WebP</strong>, développé par Google, combine le meilleur des deux : une compression 30-40% supérieure à PNG/JPG avec support de la transparence et des animations.',
+    },
+    {
+      type: 'table',
+      headers: ['Format', 'Transparence', 'Compression', 'Idéal pour'],
+      rows: [
+        ['PNG', 'Oui', 'Sans perte', 'Logos, graphiques, captures'],
+        ['JPG', 'Non', 'Avec perte', 'Photos, grandes images'],
+        ['WebP', 'Oui', 'Sans/Avec perte', 'Web moderne, performance'],
+        ['SVG', 'Oui', 'Vectoriel', 'Icônes scalables, animations'],
+        ['AVIF', 'Oui', 'Supérieure', 'Web nouvelle génération'],
+        ['ICO', 'Oui', 'Bitmap', 'Favicons, icônes Windows'],
+      ],
+    },
+    {
+      type: 'title',
+      text: 'Formats Nouvelle Génération : AVIF et WebP',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'Le <strong>format AVIF</strong> (AV1 Image File Format) est le successeur technologique du WebP, offrant jusqu\'à 50% de poids en moins que le JPG à qualité subjective égale. Bien que son adoption croisse rapidement, la compatibilité limitée sur les systèmes anciens rend souvent nécessaire la conversion d\'AVIF vers des formats plus établis comme JPG, PNG ou WebP.',
+    },
+    {
+      type: 'tip',
+      title: 'Conseil performance web',
+      html: 'Pour maximiser la vitesse de chargement, utilisez WebP comme format principal sur votre site avec des alternatives JPG/PNG pour les navigateurs anciens. L\'élément HTML <code>picture</code> avec plusieurs balises <code>source</code> vous permet de servir le format optimal selon le support du navigateur visiteur.',
+    },
+    {
+      type: 'title',
+      text: 'SVG, BMP et ICO : Cas d\'Usage Spéciaux',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'Les <strong>fichiers SVG</strong> sont des vecteurs mathématiques qui s\'adaptent sans perte à n\'importe quelle résolution, parfaits pour les logos et la conception graphique. Cependant, de nombreuses plateformes ne les supportent pas directement. Les <strong>fichiers BMP</strong>, bien qu\'obsolètes pour le web, restent courants dans les environnements Windows. Enfin, le <strong>format ICO</strong> est le standard pour les favicons web et la personnalisation des icônes Windows.',
+    },
+    {
+      type: 'stats',
+      columns: 3,
+      items: [
+        { label: 'Combinaisons', value: '21', icon: 'mdi:image-sync' },
+        { label: 'Confidentialité', value: '100% local', icon: 'mdi:shield-lock' },
+        { label: 'Formats', value: '8 types', icon: 'mdi:file-image' },
+      ],
+    },
+    {
+      type: 'title',
+      text: 'Confidentialité Totale : Conversion sans Serveurs',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'Contrairement à d\'autres outils en ligne qui téléchargent vos images sur des serveurs distants, nos convertisseurs utilisent exclusivement les APIs natives du navigateur : <strong>Canvas 2D API</strong> pour la rastérisation, <strong>FileReader API</strong> pour lire les fichiers localement et <strong>Blob/URL.createObjectURL</strong> pour les téléchargements. Vous pouvez ainsi convertir des images confidentielles, des logos d\'entreprise ou des documents privés en toute sécurité.',
+    },
+  ],
+};

package/src/category/index.ts

@@ -0,0 +1,39 @@
+import type { ConvertersCategoryEntry } from '../types';
+import { pngAJpg } from '../tool/pngAJpg';
+import { jpgAPng } from '../tool/jpgAPng';
+import { webpAPng } from '../tool/webpAPng';
+import { webpAJpg } from '../tool/webpAJpg';
+import { pngAWebp } from '../tool/pngAWebp';
+import { jpgAWebp } from '../tool/jpgAWebp';
+import { svgAPng } from '../tool/svgAPng';
+import { svgAJpg } from '../tool/svgAJpg';
+import { imagenBase64 } from '../tool/imagenBase64';
+import { bmpAJpg } from '../tool/bmpAJpg';
+import { bmpAPng } from '../tool/bmpAPng';
+import { bmpAWebp } from '../tool/bmpAWebp';
+import { avifAJpg } from '../tool/avifAJpg';
+import { avifAPng } from '../tool/avifAPng';
+import { avifAWebp } from '../tool/avifAWebp';
+import { gifAJpg } from '../tool/gifAJpg';
+import { gifAPng } from '../tool/gifAPng';
+import { gifAWebp } from '../tool/gifAWebp';
+import { pngAIco } from '../tool/pngAIco';
+import { jpgAIco } from '../tool/jpgAIco';
+import { webpAIco } from '../tool/webpAIco';
+
+export const convertersCategory: ConvertersCategoryEntry = {
+  icon: 'mdi:image-sync',
+  tools: [
+    pngAJpg, jpgAPng, webpAPng, webpAJpg, pngAWebp, jpgAWebp,
+    svgAPng, svgAJpg, imagenBase64,
+    bmpAJpg, bmpAPng, bmpAWebp,
+    avifAJpg, avifAPng, avifAWebp,
+    gifAJpg, gifAPng, gifAWebp,
+    pngAIco, jpgAIco, webpAIco,
+  ],
+  i18n: {
+    es: () => import('./i18n/es').then((m) => m.content),
+    en: () => import('./i18n/en').then((m) => m.content),
+    fr: () => import('./i18n/fr').then((m) => m.content),
+  },
+};

package/src/category/seo.astro

@@ -0,0 +1,15 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { convertersCategory } from './index';
+import type { KnownLocale } from '../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'es' } = Astro.props;
+const content = await convertersCategory.i18n[locale]?.();
+---
+
+{content && <SEORenderer content={{ locale, sections: content.seo }} />}
+

package/src/components/PreviewNavSidebar.astro

@@ -0,0 +1,116 @@
+---
+interface NavItem {
+  id: string;
+  title: string;
+  href: string;
+  isActive?: boolean;
+}
+
+interface Props {
+  categoryTitle: string;
+  tools?: NavItem[];
+}
+
+const { categoryTitle, tools = [] } = Astro.props;
+---
+
+<nav class="preview-nav-sidebar">
+  <div class="sidebar-header">
+    <h3>{categoryTitle}</h3>
+  </div>
+
+  <ul class="tools-list">
+    {tools.map((tool) => (
+      <li>
+        <a
+          href={tool.href}
+          class:list={['tool-link', { active: tool.isActive }]}
+        >
+          <span class="tool-title">{tool.title}</span>
+        </a>
+      </li>
+    ))}
+  </ul>
+</nav>
+
+<style>
+  .preview-nav-sidebar {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+    background: var(--bg-surface, #0f172a);
+  }
+
+  .sidebar-header {
+    padding: 2rem 1.5rem 1.5rem;
+    border-bottom: 1px solid var(--border-color, #1e293b);
+  }
+
+  .sidebar-header h3 {
+    margin: 0;
+    font-size: 0.75rem;
+    font-weight: 900;
+    text-transform: uppercase;
+    letter-spacing: 0.1em;
+    color: var(--text-muted, #94a3b8);
+  }
+
+  .tools-list {
+    list-style: none;
+    margin: 0;
+    padding: 0.5rem 0;
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+  }
+
+  .tools-list li {
+    margin: 0;
+  }
+
+  .tool-link {
+    display: flex;
+    align-items: center;
+    padding: 0.75rem 1.5rem;
+    color: var(--text-muted, #94a3b8);
+    text-decoration: none;
+    font-size: 0.9375rem;
+    font-weight: 500;
+    transition: all 0.15s cubic-bezier(0.4, 0, 0.2, 1);
+    border-left: 3px solid transparent;
+    position: relative;
+  }
+
+  .tool-link:hover {
+    color: var(--text-base, #f1f5f9);
+    background: rgba(255, 255, 255, 0.08);
+    padding-left: 1.75rem;
+  }
+
+  .tool-link.active {
+    color: var(--accent, #f43f5e);
+    background: rgba(244, 63, 94, 0.15);
+    border-left-color: var(--accent, #f43f5e);
+    font-weight: 600;
+  }
+
+  .tool-link.active::before {
+    content: '';
+    position: absolute;
+    left: 0;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 3px;
+    height: 24px;
+    background: var(--accent, #f43f5e);
+    border-radius: 0 2px 2px 0;
+  }
+
+  .tool-title {
+    display: block;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+</style>
+

package/src/components/PreviewToolbar.astro

@@ -0,0 +1,152 @@
+---
+import type { KnownLocale } from '../types';
+
+interface Props {
+  currentLocale: KnownLocale;
+  localeUrls?: Partial<Record<KnownLocale, string>>;
+}
+
+const { currentLocale, localeUrls = {} } = Astro.props;
+
+const otherLocales = Object.entries(localeUrls).filter(([l]) => l !== currentLocale) as [
+  KnownLocale,
+  string,
+][];
+---
+
+<nav class="preview-toolbar">
+  {
+    otherLocales.length > 0 && (
+      <div class="locale-group">
+        <span class="locale-current">{currentLocale.toUpperCase()}</span>
+        {otherLocales.map(([locale, url]) => (
+          <a href={url} class="btn-locale">
+            {locale.toUpperCase()}
+          </a>
+        ))}
+      </div>
+    )
+  }
+
+  <button id="theme-toggle" class="btn-theme" aria-label="Toggle theme" title="Toggle theme">
+    <span class="theme-icon"></span>
+  </button>
+</nav>
+
+<script>
+  function initToolbar() {
+    const btn = document.getElementById('theme-toggle');
+    if (!btn) return;
+
+    const applyTheme = (theme: string) => {
+      document.documentElement.classList.remove('theme-light', 'theme-dark');
+      document.documentElement.classList.add(theme);
+      localStorage.setItem('theme', theme);
+    };
+
+    btn.addEventListener('click', () => {
+      const next = document.documentElement.classList.contains('theme-dark')
+        ? 'theme-light'
+        : 'theme-dark';
+      applyTheme(next);
+    });
+  }
+
+  initToolbar();
+  document.addEventListener('astro:after-swap', initToolbar);
+</script>
+
+<style>
+  .preview-toolbar {
+    position: fixed;
+    top: 1rem;
+    right: 1.5rem;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    z-index: 1000;
+    background: var(--bg-surface);
+    padding: 0.4rem;
+    border-radius: 1rem;
+    border: 1px solid var(--border-color);
+    backdrop-filter: blur(12px);
+  }
+
+  .locale-group {
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+    padding-right: 0.5rem;
+    border-right: 1px solid var(--border-color);
+  }
+
+  .locale-current {
+    font-size: 0.7rem;
+    font-weight: 900;
+    color: var(--text-muted);
+    padding: 0.4rem 0.6rem;
+    letter-spacing: 0.08em;
+  }
+
+  .btn-locale {
+    background: transparent;
+    border: 1px solid var(--border-color);
+    color: var(--text-main);
+    cursor: pointer;
+    padding: 0.4rem 0.7rem;
+    border-radius: 0.5rem;
+    font-weight: 700;
+    font-size: 0.7rem;
+    text-decoration: none;
+    letter-spacing: 0.08em;
+    transition: all 0.2s ease;
+  }
+
+  .btn-locale:hover {
+    border-color: var(--accent);
+    color: var(--accent);
+  }
+
+  .btn-theme {
+    background: transparent;
+    border: none;
+    cursor: pointer;
+    padding: 0.5rem;
+    border-radius: 0.6rem;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: background 0.2s ease;
+  }
+
+  .btn-theme:hover {
+    background: rgba(255, 255, 255, 0.08);
+  }
+
+  .theme-icon {
+    display: block;
+    width: 16px;
+    height: 16px;
+    border-radius: 50%;
+  }
+
+  :global(.theme-light) .theme-icon {
+    --sun-color: #f59e0b;
+    --sun-shadow-color: #fbbf24;
+    --sun-shadow-blur: 8px;
+
+    background: var(--sun-color);
+    box-shadow: 0 0 var(--sun-shadow-blur) var(--sun-shadow-color);
+  }
+
+  :global(.theme-dark) .theme-icon {
+    --moon-color: #94a3b8;
+    --moon-shadow-color: #1e293b;
+    --moon-offset-x: -4px;
+    --moon-offset-y: -2px;
+
+    background: var(--moon-color);
+    box-shadow: inset var(--moon-offset-x) var(--moon-offset-y) 0 var(--moon-shadow-color);
+  }
+</style>
+