@hutusi/amytis 1.15.0 → 1.16.0

package/src/components/RstRenderer.test.tsx

@@ -1,10 +1,10 @@
 import { describe, expect, test } from 'bun:test';
-import { renderToStaticMarkup } from 'react-dom/server';
 import RstRenderer from './RstRenderer';
+import { renderAsync } from '@/test-utils/render';
 
 describe('RstRenderer', () => {
-  test('renders pre-rendered html when available', () => {
-    const html = renderToStaticMarkup(
+  test('renders pre-rendered html when available', async () => {
+    const html = await renderAsync(
       <RstRenderer
         content="Fallback body"
         html={
@@ -28,8 +28,8 @@ describe('RstRenderer', () => {
     expect(html).not.toContain('javascript:alert(4)');
   });
 
-  test('blocks data urls on images', () => {
-    const html = renderToStaticMarkup(
+  test('blocks data urls on images', async () => {
+    const html = await renderAsync(
       <RstRenderer
         content="Fallback body"
         html={'<p><img src="data:image/svg+xml,<svg onload=alert(1)>" alt="Bad" /></p>'}
@@ -40,8 +40,8 @@ describe('RstRenderer', () => {
     expect(html).not.toContain('data:image');
   });
 
-  test('preserves MathML elements', () => {
-    const html = renderToStaticMarkup(
+  test('preserves MathML elements', async () => {
+    const html = await renderAsync(
       <RstRenderer
         content="Fallback body"
         html={'<math xmlns="http://www.w3.org/1998/Math/MathML"><mrow><mi>x</mi><mo>=</mo><mn>2</mn></mrow></math>'}
@@ -53,8 +53,8 @@ describe('RstRenderer', () => {
     expect(html).toContain('<mi>x</mi>');
   });
 
-  test('wraps rendered rst tables with the same scroll container pattern as markdown', () => {
-    const html = renderToStaticMarkup(
+  test('wraps rendered rst tables with the same scroll container pattern as markdown', async () => {
+    const html = await renderAsync(
       <RstRenderer
         content="Fallback body"
         html={'<table><thead><tr><th>A</th></tr></thead><tbody><tr><td>B</td></tr></tbody></table>'}
@@ -67,8 +67,8 @@ describe('RstRenderer', () => {
     expect(html).toContain('<td>B</td>');
   });
 
-  test('renders converted headings, links, and code blocks through the markdown renderer', () => {
-    const html = renderToStaticMarkup(
+  test('renders converted headings, links, and code blocks through the markdown renderer', async () => {
+    const html = await renderAsync(
       <RstRenderer
         content={[
           'Section',
@@ -85,9 +85,9 @@ describe('RstRenderer', () => {
 
     expect(html).toContain('Section');
     expect(html).toContain('https://example.com');
-    expect(html).toContain('language-ts');
-    expect(html).toContain('<code class="language-ts"');
-    expect(html).toContain('token keyword');
-    expect(html).toContain('token number');
+    // Shiki produces a .shiki container with language-aware token spans, not Prism's
+    // legacy class="language-ts" + token markup. Assert the new highlighter ran.
+    expect(html).toContain('class="shiki');
+    expect(html).toContain('export');
   });
 });

package/src/components/RstRenderer.tsx

@@ -2,6 +2,7 @@ import MarkdownRenderer from '@/components/MarkdownRenderer';
 import KatexStyles from '@/components/KatexStyles';
 import type { SlugRegistryEntry } from '@/lib/markdown';
 import { rstToMarkdown } from '@/lib/rst';
+import { applyShikiToRstHtml } from '@/lib/shiki-rst';
 import sanitizeHtml from 'sanitize-html';
 
 interface RstRendererProps {
@@ -30,6 +31,11 @@ const allowedTags = [
   'figure',
   'figcaption',
   'aside',
+  // Tabbed code groups (CSS-only via radio + label). Without these on the
+  // allowlist, the rST path drops to stacked code blocks with no tabs.
+  // transformTags below restricts `input` to type="radio" only.
+  'input',
+  'label',
   'math',
   'annotation',
   'annotation-xml',
@@ -64,6 +70,13 @@ const allowedTags = [
   'semantics',
 ];
 
+// Shiki emits inline `style="--shiki-light:#...; --shiki-dark:#..."` CSS vars on
+// every token <span> when running in dual-theme mode, plus our custom transformers
+// add `data-language`, `data-line-numbers`, `data-highlighted-line`, and `data-title`
+// to <pre>/<span>. Stripping any of these silently kills syntax highlighting in rST
+// output while leaving Markdown unaffected — covered by RstRenderer.test.tsx.
+const codeBlockAttrs = ['style', 'data-language', 'data-line', 'data-line-numbers', 'data-highlighted-line', 'data-title', 'tabindex'];
+
 const allowedAttributes: sanitizeHtml.IOptions['allowedAttributes'] = {
   ...sanitizeHtml.defaults.allowedAttributes,
   '*': ['id', 'class', 'title', 'lang', 'dir', 'role', 'aria-label', 'aria-hidden'],
@@ -77,6 +90,15 @@ const allowedAttributes: sanitizeHtml.IOptions['allowedAttributes'] = {
   math: ['display', 'xmlns'],
   annotation: ['encoding'],
   'annotation-xml': ['encoding'],
+  pre: ['class', 'style', ...codeBlockAttrs],
+  code: ['class', 'style', ...codeBlockAttrs],
+  span: ['class', 'style', ...codeBlockAttrs],
+  div: ['class', 'style', 'data-group-id', 'data-panel', ...codeBlockAttrs],
+  // Tabbed code groups: input is restricted to type=radio via transformTags.
+  // Defense-in-depth: even if an unexpected attr slips in, the CSS-only tab
+  // mechanism can't do anything dangerous with a stray radio button.
+  input: ['type', 'name', 'id', 'checked', 'data-idx', 'aria-controls', 'tabindex', 'class'],
+  label: ['for', 'class', 'role', 'aria-controls', 'tabindex', 'data-cg-icon'],
 };
 
 function sanitizeRenderedHtml(html: string): string {
@@ -88,12 +110,25 @@ function sanitizeRenderedHtml(html: string): string {
       img: ['http', 'https'],
     },
     allowProtocolRelative: false,
+    transformTags: {
+      // Restrict <input> to type="radio" only. Anything else gets stripped.
+      // Prevents an rST author from injecting password/file/etc. inputs.
+      input: (tagName, attribs) => {
+        if (attribs.type !== 'radio') {
+          return { tagName: 'span', attribs: {} };
+        }
+        return { tagName, attribs };
+      },
+    },
   });
 }
 
-export default function RstRenderer({ content, html, latex = false, slug, slugRegistry }: RstRendererProps) {
+export default async function RstRenderer({ content, html, latex = false, slug, slugRegistry }: RstRendererProps) {
   if (html) {
-    const sanitizedHtml = sanitizeRenderedHtml(html).replace(
+    // The docutils pass emits opaque <pre data-amytis-code> markers; run them through
+    // Shiki here (server-side, build-time for SSG) before sanitizing.
+    const highlighted = await applyShikiToRstHtml(html);
+    const sanitizedHtml = sanitizeRenderedHtml(highlighted).replace(
       /<table\b([^>]*)>/g,
       '<div class="rst-table-wrapper"><table$1>'
     ).replace(/<\/table>/g, '</table></div>');

package/src/components/Search.tsx

@@ -130,8 +130,11 @@ export default function Search() {
   // True while debounce is pending — suppress "no results" flash
   const isTyping = query.length > 0 && query !== debouncedQuery;
 
-  // Load recent searches on mount
+  // Load recent searches on mount. localStorage is unavailable during SSR,
+  // so this can't be hoisted into useState's initializer without breaking
+  // hydration — the mount-only effect is the documented React pattern.
   useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     setRecentSearches(loadRecentSearches());
   }, []);
 
@@ -142,16 +145,22 @@ export default function Search() {
     }
   }, [isOpen]);
 
-  // Debounce query
+  // Debounce query. The sync reset when `query` is empty is intentional:
+  // skipping it would leave stale results visible for DEBOUNCE_MS after the
+  // user clears the input.
   useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     if (!query) { setDebouncedQuery(''); return; }
     const timer = setTimeout(() => setDebouncedQuery(query), DEBOUNCE_MS);
     return () => clearTimeout(timer);
   }, [query]);
 
-  // Run Pagefind search on debounced query
+  // Run Pagefind search on debounced query. Synchronous resets when the
+  // query becomes empty are the simplest way to clear results state without
+  // threading conditional renders through every consumer of allResults.
   useEffect(() => {
     if (!debouncedQuery) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
       setAllResults([]);
       setActiveIndex(-1);
       setActiveType('All');
@@ -214,17 +223,22 @@ export default function Search() {
     return () => window.removeEventListener('keydown', handleKeyDown);
   }, []);
 
-  // Focus on open; full reset on close
+  // Focus on open; full reset on close. The 6 resets are batched into a
+  // single React render — the rule's "cascading renders" warning doesn't
+  // apply when state changes are batched as siblings, only when one update
+  // triggers the next.
   useEffect(() => {
     if (isOpen) {
       setTimeout(() => inputRef.current?.focus(), 100);
     } else {
+      /* eslint-disable react-hooks/set-state-in-effect */
       setQuery('');
       setDebouncedQuery('');
       setAllResults([]);
       setActiveIndex(-1);
       setActiveType('All');
       setIsFetching(false);
+      /* eslint-enable react-hooks/set-state-in-effect */
     }
   }, [isOpen]);
 

package/src/components/SeriesCatalog.tsx

@@ -68,7 +68,7 @@ export default function SeriesCatalog({ posts, startIndex = 0, totalPosts, colle
                     <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs font-mono text-muted mb-3">
                       <span>{post.date}</span>
                       <span className="hidden sm:inline">•</span>
-                      <span className="text-accent/80">{post.readingTime}</span>
+                      <span className="text-accent/80">{post.readingMinutes} {t('reading_time')}</span>
                       {post.category && (
                         <>
                           <span className="hidden sm:inline">•</span>

package/src/components/ShareBar.tsx

@@ -77,6 +77,10 @@ export default function ShareBar({ url, title, className = '' }: ShareBarProps)
   const btnClass = 'inline-flex items-center justify-center w-8 h-8 rounded text-muted hover:text-accent hover:bg-muted/10 transition-colors';
 
   return (
+    // suppressHydrationWarning on locale-bound nodes is a band-aid for the
+    // known static-export + client-i18n drift: SSR renders defaultLocale,
+    // `useLanguage()` hook serves the user's saved locale on hydration. The
+    // real fix is per-locale URL routing, tracked as a separate refactor.
     <div className={`flex flex-row flex-wrap gap-1 ${className}`}>
       {platforms.map((platform) => {
         const { label, Icon } = PLATFORM_META[platform];
@@ -90,6 +94,7 @@ export default function ShareBar({ url, title, className = '' }: ShareBarProps)
               title={copyLabel}
               aria-label={copyLabel}
               className={`${btnClass} ${copied ? 'text-accent' : ''}`}
+              suppressHydrationWarning
             >
               {copied ? <LuCheck size={16} /> : <Icon size={16} />}
             </button>

package/src/components/TocPanel.tsx

@@ -19,9 +19,16 @@ export default function TocPanel({ headings, className = '' }: TocPanelProps) {
   if (headings.length === 0) return null;
 
   return (
-    <nav aria-label={t('on_this_page')} className={className}>
+    // suppressHydrationWarning on locale-bound nodes is a band-aid for the
+    // known static-export + client-i18n drift: SSR renders defaultLocale,
+    // `useLanguage()` hook serves the user's saved locale on hydration. The
+    // real fix is per-locale URL routing, tracked as a separate refactor.
+    <nav aria-label={t('on_this_page')} className={className} suppressHydrationWarning>
       <div className="flex items-center justify-between mb-3">
-        <span className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted">
+        <span
+          className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted"
+          suppressHydrationWarning
+        >
           {t('on_this_page')}
         </span>
         <button
@@ -30,6 +37,7 @@ export default function TocPanel({ headings, className = '' }: TocPanelProps) {
           className="text-muted hover:text-foreground transition-colors"
           aria-expanded={!collapsed}
           aria-label={collapsed ? t('toc_expand') : t('toc_collapse')}
+          suppressHydrationWarning
         >
           <svg
             className={`w-3.5 h-3.5 transition-transform duration-200 ${collapsed ? '' : 'rotate-180'}`}

package/src/i18n/translations.ts

@@ -14,6 +14,7 @@ export const translations = {
     view_archive: "View Archive",
     written_by: "Written by",
     reading_time: "min read",
+    words: "words",
     next_page: "Next",
     prev_page: "Prev",
     back_to_home: "Back to Home",
@@ -160,6 +161,7 @@ export const translations = {
     view_archive: "查看归档",
     written_by: "作者",
     reading_time: "分钟阅读",
+    words: "字",
     next_page: "下一页",
     prev_page: "上一页",
     back_to_home: "返回首页",

package/src/layouts/BookLayout.tsx

@@ -1,4 +1,5 @@
-import { BookData, BookChapterData } from '@/lib/markdown';
+import path from 'path';
+import { BookData, BookChapterData, getBookDirPath } from '@/lib/markdown';
 import MarkdownRenderer from '@/components/MarkdownRenderer';
 import BookSidebar from '@/components/BookSidebar';
 import BookMobileNav from '@/components/BookMobileNav';
@@ -16,6 +17,22 @@ interface BookLayoutProps {
 }
 
 export default function BookLayout({ book, chapter }: BookLayoutProps) {
+  const bookDir = getBookDirPath(book.slug);
+  const validChapterIds = new Set(book.chapters.map(c => c.id));
+
+  // `slug` is the public-relative directory used by rehype-image-metadata to
+  // resolve `![](./assets/...)`-style refs. For nested flat chapters
+  // (e.g. id `maths/linear/vectors`) the image's parent dir is the chapter's
+  // parent dir, not the book root — without this, all chapter images point
+  // at `/books/<slug>/assets/...` instead of `/books/<slug>/<dir>/assets/...`.
+  let imageSlug: string;
+  if (chapter.isFolder) {
+    imageSlug = `books/${book.slug}/${chapter.slug}`;
+  } else {
+    const parentDir = path.posix.dirname(chapter.slug);
+    imageSlug = parentDir === '.' ? `books/${book.slug}` : `books/${book.slug}/${parentDir}`;
+  }
+
   return (
     <div className="layout-container lg:max-w-7xl">
       <ReadingProgressBar />
@@ -50,14 +67,18 @@ export default function BookLayout({ book, chapter }: BookLayoutProps) {
                 {t('chapter')}
               </span>
               <span className="w-1 h-1 rounded-full bg-muted/30" />
-              <span className="font-mono">{chapter.readingTime}</span>
+              <span className="font-mono">
+                {chapter.wordCount.toLocaleString()} {t('words')}
+              </span>
+              <span className="w-1 h-1 rounded-full bg-muted/30" />
+              <span className="font-mono text-muted/70">{chapter.readingMinutes} {t('reading_time')}</span>
             </div>
 
             <h1 className="text-3xl md:text-4xl font-serif font-bold text-heading leading-tight mb-4">
               {chapter.title}
             </h1>
 
-            {chapter.excerpt && (
+            {book.showChapterExcerpt && chapter.excerpt && (
               <p className="text-lg text-muted font-serif italic leading-relaxed">
                 {chapter.excerpt}
               </p>
@@ -65,7 +86,17 @@ export default function BookLayout({ book, chapter }: BookLayoutProps) {
           </header>
 
           {/* Content */}
-          <MarkdownRenderer content={chapter.content} latex={chapter.latex} slug={chapter.isFolder ? `books/${book.slug}/${chapter.slug}` : `books/${book.slug}`} />
+          <MarkdownRenderer
+            content={chapter.content}
+            latex={chapter.latex}
+            slug={imageSlug}
+            bookContext={{
+              bookSlug: book.slug,
+              bookDir,
+              chapterSourcePath: chapter.sourcePath,
+              validChapterIds,
+            }}
+          />
 
           {/* Comments */}
           {resolveCommentable(chapter.commentable, 'bookChapters') && (

package/src/layouts/PostLayout.tsx

@@ -85,7 +85,11 @@ export default function PostLayout({ post, relatedPosts, seriesPosts, seriesTitl
               <span className="w-1 h-1 rounded-full bg-muted/30" />
               <time className="font-mono" data-pagefind-meta="date[content]">{post.date}</time>
               <span className="w-1 h-1 rounded-full bg-muted/30" />
-              <span className="font-mono">{post.readingTime}</span>
+              <span className="font-mono">
+                {post.wordCount.toLocaleString()} {t('words')}
+              </span>
+              <span className="w-1 h-1 rounded-full bg-muted/30" />
+              <span className="font-mono text-muted/70">{post.readingMinutes} {t('reading_time')}</span>
             </div>
 
             <h1 className="text-4xl md:text-5xl font-serif font-bold text-heading leading-tight mb-4">

package/src/lib/code-group-icons.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from 'bun:test';
+import { resolveCodeGroupIcon } from './code-group-icons';
+
+describe('resolveCodeGroupIcon', () => {
+  test('exact-label matches for package managers', () => {
+    expect(resolveCodeGroupIcon('npm')).toBe('npm');
+    expect(resolveCodeGroupIcon('yarn')).toBe('yarn');
+    expect(resolveCodeGroupIcon('pnpm')).toBe('pnpm');
+    expect(resolveCodeGroupIcon('bun')).toBe('bun');
+    expect(resolveCodeGroupIcon('deno')).toBe('deno');
+  });
+
+  test('exact-label matches are case-insensitive and trim whitespace', () => {
+    expect(resolveCodeGroupIcon('NPM')).toBe('npm');
+    expect(resolveCodeGroupIcon('  Yarn  ')).toBe('yarn');
+  });
+
+  test('exact-label matches for tools', () => {
+    expect(resolveCodeGroupIcon('docker')).toBe('docker');
+    expect(resolveCodeGroupIcon('vite')).toBe('vite');
+    expect(resolveCodeGroupIcon('next.js')).toBe('nextjs');
+    expect(resolveCodeGroupIcon('nodejs')).toBe('node');
+    expect(resolveCodeGroupIcon('tailwindcss')).toBe('tailwind');
+  });
+
+  test('filename matches win over extension matches', () => {
+    // tsconfig.json maps to typescript via the filename table; otherwise
+    // its `.json` extension would route it to the json icon.
+    expect(resolveCodeGroupIcon('tsconfig.json')).toBe('typescript');
+    expect(resolveCodeGroupIcon('package.json')).toBe('node');
+    expect(resolveCodeGroupIcon('Dockerfile')).toBe('docker');
+    expect(resolveCodeGroupIcon('vite.config.ts')).toBe('vite');
+    expect(resolveCodeGroupIcon('next.config.mjs')).toBe('nextjs');
+    expect(resolveCodeGroupIcon('tailwind.config.js')).toBe('tailwind');
+  });
+
+  test('filename match strips directory paths', () => {
+    expect(resolveCodeGroupIcon('src/app/Dockerfile')).toBe('docker');
+    expect(resolveCodeGroupIcon('apps/web/package.json')).toBe('node');
+  });
+
+  test('extension match for arbitrary file paths', () => {
+    expect(resolveCodeGroupIcon('foo.ts')).toBe('typescript');
+    expect(resolveCodeGroupIcon('src/index.tsx')).toBe('typescript');
+    expect(resolveCodeGroupIcon('hello.py')).toBe('python');
+    expect(resolveCodeGroupIcon('main.rs')).toBe('rust');
+    expect(resolveCodeGroupIcon('config.yml')).toBe('yaml');
+    expect(resolveCodeGroupIcon('README.md')).toBe('markdown');
+    expect(resolveCodeGroupIcon('install.sh')).toBe('bash');
+  });
+
+  test('language-name aliases resolve to a canonical icon key', () => {
+    expect(resolveCodeGroupIcon('TypeScript')).toBe('typescript');
+    expect(resolveCodeGroupIcon('ts')).toBe('typescript');
+    expect(resolveCodeGroupIcon('Python')).toBe('python');
+    expect(resolveCodeGroupIcon('Go')).toBe('go');
+    expect(resolveCodeGroupIcon('golang')).toBe('go');
+    expect(resolveCodeGroupIcon('c++')).toBe('cpp');
+  });
+
+  test('returns null for labels that do not match any rule', () => {
+    expect(resolveCodeGroupIcon('mystery')).toBeNull();
+    expect(resolveCodeGroupIcon('totally-fake-name')).toBeNull();
+    expect(resolveCodeGroupIcon('')).toBeNull();
+    expect(resolveCodeGroupIcon('   ')).toBeNull();
+  });
+
+  test('does not match Object.prototype keys via the `in` operator', () => {
+    // `'constructor' in {}` is true because of the prototype chain; using
+    // Object.hasOwn (instead of `in`) prevents the resolver from returning
+    // prototype values for crafted labels.
+    expect(resolveCodeGroupIcon('constructor')).toBeNull();
+    expect(resolveCodeGroupIcon('toString')).toBeNull();
+    expect(resolveCodeGroupIcon('hasOwnProperty')).toBeNull();
+    expect(resolveCodeGroupIcon('valueOf')).toBeNull();
+    expect(resolveCodeGroupIcon('__proto__')).toBeNull();
+  });
+});

package/src/lib/code-group-icons.ts

@@ -0,0 +1,148 @@
+/**
+ * Maps a code-group tab label to an icon key. The key drives a CSS rule in
+ * globals.css that paints the icon via .cg-tab[data-cg-icon="<key>"]::before.
+ *
+ * Match cascade (first hit wins):
+ *   1. exact label match  ("npm", "yarn", "vite", "deno")
+ *   2. filename match     ("package.json", "vite.config.ts", "Dockerfile")
+ *   3. extension match    ("foo.ts" → typescript, "x.yml" → yaml)
+ *   4. language alias     ("ts" → typescript, "py" → python)
+ *
+ * Returns null when nothing matches — caller renders the tab without an icon.
+ */
+
+const EXACT: Record<string, string> = {
+  npm: 'npm',
+  yarn: 'yarn',
+  pnpm: 'pnpm',
+  bun: 'bun',
+  deno: 'deno',
+  vite: 'vite',
+  docker: 'docker',
+  node: 'node',
+  nodejs: 'node',
+  'node.js': 'node',
+  react: 'react',
+  vue: 'vue',
+  nextjs: 'nextjs',
+  'next.js': 'nextjs',
+  next: 'nextjs',
+  tailwind: 'tailwind',
+  tailwindcss: 'tailwind',
+};
+
+const FILENAMES: Record<string, string> = {
+  'package.json': 'node',
+  'package-lock.json': 'npm',
+  'yarn.lock': 'yarn',
+  'pnpm-lock.yaml': 'pnpm',
+  'bun.lockb': 'bun',
+  'tsconfig.json': 'typescript',
+  'jsconfig.json': 'javascript',
+  dockerfile: 'docker',
+  '.dockerignore': 'docker',
+  'docker-compose.yml': 'docker',
+  'docker-compose.yaml': 'docker',
+  'vite.config.ts': 'vite',
+  'vite.config.js': 'vite',
+  'vite.config.mts': 'vite',
+  'vite.config.mjs': 'vite',
+  'next.config.ts': 'nextjs',
+  'next.config.js': 'nextjs',
+  'next.config.mjs': 'nextjs',
+  'tailwind.config.ts': 'tailwind',
+  'tailwind.config.js': 'tailwind',
+};
+
+const EXTENSIONS: Record<string, string> = {
+  ts: 'typescript',
+  tsx: 'typescript',
+  cts: 'typescript',
+  mts: 'typescript',
+  js: 'javascript',
+  jsx: 'javascript',
+  cjs: 'javascript',
+  mjs: 'javascript',
+  py: 'python',
+  rs: 'rust',
+  go: 'go',
+  java: 'java',
+  rb: 'ruby',
+  php: 'php',
+  c: 'c',
+  h: 'c',
+  cpp: 'cpp',
+  cc: 'cpp',
+  cxx: 'cpp',
+  hpp: 'cpp',
+  html: 'html',
+  htm: 'html',
+  css: 'css',
+  scss: 'css',
+  sass: 'css',
+  json: 'json',
+  yml: 'yaml',
+  yaml: 'yaml',
+  md: 'markdown',
+  mdx: 'markdown',
+  sh: 'bash',
+  bash: 'bash',
+  zsh: 'bash',
+  vue: 'vue',
+};
+
+const LANGUAGE_ALIASES: Record<string, string> = {
+  typescript: 'typescript',
+  ts: 'typescript',
+  javascript: 'javascript',
+  js: 'javascript',
+  python: 'python',
+  py: 'python',
+  rust: 'rust',
+  rs: 'rust',
+  go: 'go',
+  golang: 'go',
+  java: 'java',
+  ruby: 'ruby',
+  rb: 'ruby',
+  php: 'php',
+  c: 'c',
+  cpp: 'cpp',
+  'c++': 'cpp',
+  cxx: 'cpp',
+  html: 'html',
+  css: 'css',
+  json: 'json',
+  yaml: 'yaml',
+  yml: 'yaml',
+  markdown: 'markdown',
+  md: 'markdown',
+  bash: 'bash',
+  sh: 'bash',
+  shell: 'bash',
+  zsh: 'bash',
+};
+
+export function resolveCodeGroupIcon(label: string): string | null {
+  const trimmed = label.trim().toLowerCase();
+  if (!trimmed) return null;
+
+  // Use Object.hasOwn instead of the `in` operator so we don't accidentally
+  // return prototype-chain values (e.g. `constructor`, `toString`) for crafted
+  // labels — `'constructor' in EXACT` would otherwise be `true`.
+  if (Object.hasOwn(EXACT, trimmed)) return EXACT[trimmed];
+
+  // Filename lookup uses the basename (strip any path prefix).
+  const basename = trimmed.includes('/') ? trimmed.slice(trimmed.lastIndexOf('/') + 1) : trimmed;
+  if (Object.hasOwn(FILENAMES, basename)) return FILENAMES[basename];
+
+  // Extension fallback — take the portion after the LAST dot in the basename.
+  const dot = basename.lastIndexOf('.');
+  if (dot >= 0 && dot < basename.length - 1) {
+    const ext = basename.slice(dot + 1);
+    if (Object.hasOwn(EXTENSIONS, ext)) return EXTENSIONS[ext];
+  }
+
+  if (Object.hasOwn(LANGUAGE_ALIASES, trimmed)) return LANGUAGE_ALIASES[trimmed];
+  return null;
+}