@hutusi/amytis 1.15.0 → 1.16.0

package/tests/integration/code-group.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, test } from 'bun:test';
+import MarkdownRenderer from '@/components/MarkdownRenderer';
+import RstRenderer from '@/components/RstRenderer';
+import { renderAsync } from '@/test-utils/render';
+
+describe('Integration: Code Group Tabs', () => {
+  describe('Markdown / MDX :::code-group', () => {
+    test('three-tab npm/yarn/bun group renders the radio + label + panel structure', async () => {
+      const content = [
+        ':::code-group',
+        '```bash [npm]',
+        'npm install foo',
+        '```',
+        '```bash [yarn]',
+        'yarn add foo',
+        '```',
+        '```bash [bun]',
+        'bun add foo',
+        '```',
+        ':::',
+      ].join('\n');
+
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      expect(html).toContain('class="code-group');
+      expect((html.match(/type="radio"/g) || []).length).toBe(3);
+      expect((html.match(/class="cg-panel"/g) || []).length).toBe(3);
+      // First tab checked by default.
+      expect(html).toMatch(/data-idx="0"[^>]*checked/);
+      expect(html).not.toMatch(/data-idx="1"[^>]*checked/);
+      // All three labels surfaced.
+      expect(html).toContain('>npm<');
+      expect(html).toContain('>yarn<');
+      expect(html).toContain('>bun<');
+      // Resolver-driven tab icons: each label gets a data-cg-icon attribute on
+      // the <label> element. The CSS in globals.css paints the matching icon.
+      expect(html).toContain('data-cg-icon="npm"');
+      expect(html).toContain('data-cg-icon="yarn"');
+      expect(html).toContain('data-cg-icon="bun"');
+    });
+
+    test('missing [label] falls back to the language name', async () => {
+      const content = [
+        ':::code-group',
+        '```bash',
+        'echo bare',
+        '```',
+        '```python',
+        'print("bare")',
+        '```',
+        ':::',
+      ].join('\n');
+
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      expect(html).toContain('>bash<');
+      expect(html).toContain('>python<');
+    });
+
+    test('inner blocks still go through Shiki', async () => {
+      const content = [
+        ':::code-group',
+        '```ts [TS]',
+        'export const x: number = 1;',
+        '```',
+        '```python [Py]',
+        'def f(): return 1',
+        '```',
+        ':::',
+      ].join('\n');
+
+      const html = await renderAsync(MarkdownRenderer({ content }));
+
+      // Both panels should contain a Shiki-highlighted <pre>.
+      expect((html.match(/class="shiki/g) || []).length).toBe(2);
+    });
+  });
+
+  describe('rST .. code-group:: (fallback parser path)', () => {
+    test('rST code-group with :label: per inner block renders the same structure', async () => {
+      const content = [
+        'Heading',
+        '=======',
+        '',
+        '.. code-group::',
+        '',
+        '   .. code-block:: bash',
+        '      :label: npm',
+        '',
+        '      npm install foo',
+        '',
+        '   .. code-block:: bash',
+        '      :label: yarn',
+        '',
+        '      yarn add foo',
+      ].join('\n');
+
+      const html = await renderAsync(RstRenderer({ content }));
+
+      expect(html).toContain('class="code-group');
+      expect((html.match(/type="radio"/g) || []).length).toBe(2);
+      expect((html.match(/class="cg-panel"/g) || []).length).toBe(2);
+      expect(html).toContain('>npm<');
+      expect(html).toContain('>yarn<');
+    });
+
+    test('sanitize-html keeps the radio + label markup intact on the html-path', async () => {
+      // Simulate what the Python rST renderer would emit: a div data-amytis-code-group
+      // wrapper around <pre data-amytis-code> marker children. The applyShikiToRstHtml
+      // pass then expands it into the tab structure, and sanitize-html must keep the
+      // <input type=radio> and <label for=...> markup intact.
+      const wrapperHtml =
+        '<div data-amytis-code-group="" data-labels="[&quot;npm&quot;,&quot;yarn&quot;]" data-group-id="rst-test1">' +
+        '<pre data-amytis-code="" data-language="bash"><code>npm install foo</code></pre>' +
+        '<pre data-amytis-code="" data-language="bash"><code>yarn add foo</code></pre>' +
+        '</div>';
+
+      const html = await renderAsync(RstRenderer({ content: 'unused', html: wrapperHtml }));
+
+      expect(html).toContain('class="code-group');
+      expect(html).toContain('type="radio"');
+      expect((html.match(/type="radio"/g) || []).length).toBe(2);
+      expect(html).toContain('for="cg-rst-test1-0"');
+      expect(html).toContain('>npm<');
+      expect(html).toContain('>yarn<');
+    });
+
+    test('two adjacent code-groups with identical labels keep independent radio groups', async () => {
+      // Regression test for the coderabbit-flagged collision: two groups with the
+      // same tab labels used to get the same data-group-id (hashed from labels),
+      // which coupled their radio buttons. Each group must have its own name="".
+      const wrapperHtml =
+        '<div data-amytis-code-group="" data-labels="[&quot;npm&quot;,&quot;yarn&quot;]" data-group-id="rst-1">' +
+        '<pre data-amytis-code="" data-language="bash"><code>npm install a</code></pre>' +
+        '<pre data-amytis-code="" data-language="bash"><code>yarn add a</code></pre>' +
+        '</div>' +
+        '<div data-amytis-code-group="" data-labels="[&quot;npm&quot;,&quot;yarn&quot;]" data-group-id="rst-2">' +
+        '<pre data-amytis-code="" data-language="bash"><code>npm install b</code></pre>' +
+        '<pre data-amytis-code="" data-language="bash"><code>yarn add b</code></pre>' +
+        '</div>';
+
+      const html = await renderAsync(RstRenderer({ content: 'unused', html: wrapperHtml }));
+
+      // Each group's radios must use a distinct `name` attribute so checking a tab
+      // in one doesn't deselect a tab in the other.
+      expect(html).toContain('name="cg-rst-1"');
+      expect(html).toContain('name="cg-rst-2"');
+      // 4 radios total (2 per group), 4 panels total.
+      expect((html.match(/type="radio"/g) || []).length).toBe(4);
+      expect((html.match(/class="cg-panel"/g) || []).length).toBe(4);
+    });
+
+    test('rST tab labels get a data-cg-icon attribute that survives sanitize-html', async () => {
+      // The label allowlist in RstRenderer.tsx must permit `data-cg-icon` or the
+      // icons silently disappear on the rST path while MDX works. Synthesize the
+      // rST html-path input directly so we exercise applyShikiToRstHtml + sanitize.
+      const wrapperHtml =
+        '<div data-amytis-code-group="" data-labels="[&quot;npm&quot;,&quot;yarn&quot;,&quot;mystery&quot;]" data-group-id="rst-icon">' +
+        '<pre data-amytis-code="" data-language="bash"><code>npm i</code></pre>' +
+        '<pre data-amytis-code="" data-language="bash"><code>yarn add</code></pre>' +
+        '<pre data-amytis-code="" data-language="bash"><code>echo</code></pre>' +
+        '</div>';
+
+      const html = await renderAsync(RstRenderer({ content: 'unused', html: wrapperHtml }));
+
+      expect(html).toContain('data-cg-icon="npm"');
+      expect(html).toContain('data-cg-icon="yarn"');
+      // No icon resolves for `mystery`; the corresponding label has no attribute.
+      expect(html).not.toContain('data-cg-icon="mystery"');
+    });
+
+    test('non-radio inputs are downgraded by transformTags', async () => {
+      // If an rST author tries to inject a non-radio input through raw HTML, the
+      // transformTags rule should strip the tagName down to <span>.
+      const malicious = '<p>before</p><input type="password" name="x"><p>after</p>';
+      const html = await renderAsync(RstRenderer({ content: 'unused', html: malicious }));
+
+      expect(html).not.toContain('<input');
+      expect(html).toContain('before');
+      expect(html).toContain('after');
+    });
+  });
+});

package/tests/integration/code-notation.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from 'bun:test';
+import MarkdownRenderer from '@/components/MarkdownRenderer';
+import { renderAsync } from '@/test-utils/render';
+
+describe('Integration: Shiki Notation Comments', () => {
+  test('// [!code focus] dims non-focused lines via .has-focused on <pre> and .focused on the line', async () => {
+    const content = [
+      '```ts',
+      'const a = 1',
+      'const b = 2 // [!code focus]',
+      'const c = 3',
+      '```',
+    ].join('\n');
+
+    const html = await renderAsync(MarkdownRenderer({ content }));
+
+    expect(html).toContain('has-focused');
+    expect(html).toMatch(/class="line focused"/);
+  });
+
+  test('// [!code error] and // [!code warning] add .line.error / .line.warning classes', async () => {
+    const content = [
+      '```ts',
+      'failHere() // [!code error]',
+      'warnHere() // [!code warning]',
+      'okHere()',
+      '```',
+    ].join('\n');
+
+    const html = await renderAsync(MarkdownRenderer({ content }));
+
+    // transformerNotationErrorLevel adds `highlighted` plus the error/warning class.
+    expect(html).toMatch(/class="line[^"]*\berror\b/);
+    expect(html).toMatch(/class="line[^"]*\bwarning\b/);
+  });
+
+  test('// [!code highlight] adds .line.highlighted (same class as {1,3-5} fence meta)', async () => {
+    const content = ['```ts', 'pickMe() // [!code highlight]', 'ignoreMe()', '```'].join('\n');
+    const html = await renderAsync(MarkdownRenderer({ content }));
+
+    expect(html).toMatch(/class="line[^"]*\bhighlighted\b/);
+  });
+
+  test('// [!code ++] / [!code --] add .diff.add / .diff.remove (same classes as raw diff fences)', async () => {
+    const content = [
+      '```ts',
+      'const old = 1 // [!code --]',
+      'const next = 2 // [!code ++]',
+      '```',
+    ].join('\n');
+
+    const html = await renderAsync(MarkdownRenderer({ content }));
+
+    expect(html).toContain('diff add');
+    expect(html).toContain('diff remove');
+  });
+
+  test('notation diff and raw diff (in a ```diff fence) coexist without conflict', async () => {
+    // Two blocks in the same render. The raw-diff transformer fires for the
+    // ```diff fence's +/- lines; the notation transformer fires for the
+    // [!code ++/--] comments in the ts fence. Same class names; no clash.
+    const content = [
+      '```diff',
+      '-old line',
+      '+new line',
+      '```',
+      '',
+      '```ts',
+      'const x = 1 // [!code --]',
+      'const y = 2 // [!code ++]',
+      '```',
+    ].join('\n');
+
+    const html = await renderAsync(MarkdownRenderer({ content }));
+
+    // Two blocks × one add + one remove each = at least 2 of each.
+    const addCount = (html.match(/diff add/g) || []).length;
+    const removeCount = (html.match(/diff remove/g) || []).length;
+    expect(addCount).toBeGreaterThanOrEqual(2);
+    expect(removeCount).toBeGreaterThanOrEqual(2);
+  });
+
+  test('Python `# [!code focus]` style comment works for non-C languages', async () => {
+    const content = [
+      '```python',
+      'def fib(n):',
+      '    if n < 2: return n  # [!code focus]',
+      '    return fib(n-1) + fib(n-2)',
+      '```',
+    ].join('\n');
+
+    const html = await renderAsync(MarkdownRenderer({ content }));
+
+    expect(html).toContain('has-focused');
+    expect(html).toMatch(/class="line focused"/);
+  });
+});

package/tests/integration/github-alerts.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from 'bun:test';
+import MarkdownRenderer from '@/components/MarkdownRenderer';
+import RstRenderer from '@/components/RstRenderer';
+import { renderAsync } from '@/test-utils/render';
+
+describe('Integration: GitHub-flavored Alerts', () => {
+  const types = [
+    { marker: 'NOTE', cssClass: 'alert-note', label: 'Note' },
+    { marker: 'TIP', cssClass: 'alert-tip', label: 'Tip' },
+    { marker: 'IMPORTANT', cssClass: 'alert-important', label: 'Important' },
+    { marker: 'WARNING', cssClass: 'alert-warning', label: 'Warning' },
+    { marker: 'CAUTION', cssClass: 'alert-caution', label: 'Caution' },
+  ];
+
+  test.each(types)('renders [!$marker] as <aside class="alert $cssClass"> with the $label title', async ({ marker, cssClass, label }) => {
+    const content = `> [!${marker}]\n> body content for ${marker.toLowerCase()}`;
+    const html = await renderAsync(MarkdownRenderer({ content }));
+
+    expect(html).toContain(`class="alert ${cssClass}"`);
+    expect(html).toContain(`>${label}<`);
+    expect(html).toContain(`body content for ${marker.toLowerCase()}`);
+  });
+
+  test('plain blockquote without a marker stays as <blockquote>', async () => {
+    const html = await renderAsync(
+      MarkdownRenderer({ content: '> just a plain quote\n> over two lines' }),
+    );
+
+    expect(html).toContain('<blockquote');
+    expect(html).not.toContain('class="alert');
+  });
+
+  test('unknown [!UNKNOWN] type passes through as a plain blockquote (no transform)', async () => {
+    const html = await renderAsync(
+      MarkdownRenderer({ content: '> [!UNKNOWN]\n> body' }),
+    );
+
+    expect(html).toContain('<blockquote');
+    expect(html).not.toContain('class="alert');
+    // The literal marker should still be visible since we didn't transform.
+    expect(html).toContain('[!UNKNOWN]');
+  });
+
+  test('alert body keeps markdown formatting (links, code, lists)', async () => {
+    const content = [
+      '> [!TIP]',
+      '> Read the [docs](https://example.com) and run `bun test`.',
+      '>',
+      '> - first item',
+      '> - second item',
+    ].join('\n');
+
+    const html = await renderAsync(MarkdownRenderer({ content }));
+
+    expect(html).toContain('class="alert alert-tip"');
+    expect(html).toContain('href="https://example.com"');
+    expect(html).toContain('<code');
+    expect(html).toContain('<ul');
+  });
+
+  test('rST .. note:: produces a docutils admonition that inherits the same alert color palette via CSS', async () => {
+    // rST goes through rstToMarkdown → MarkdownRenderer on systems without docutils.
+    // The resulting blockquote is NOT a GitHub-alert marker (it's the docutils
+    // "Note" admonition path), but the CSS rules in globals.css color the
+    // .rst-rendered aside.admonition-note element with the same --alert-accent
+    // variable as the MDX .alert-note. This test exercises the fallback path
+    // (no Python docutils available locally) — it should at least render the
+    // body content somewhere.
+    const content = [
+      'Heading',
+      '=======',
+      '',
+      '.. note::',
+      '',
+      '   rst-side note content',
+    ].join('\n');
+
+    const html = await renderAsync(RstRenderer({ content }));
+
+    expect(html).toContain('rst-side note content');
+  });
+});

package/tests/integration/markdown-external-links.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from 'bun:test';
+import MarkdownRenderer from '@/components/MarkdownRenderer';
+import { renderAsync } from '@/test-utils/render';
+import { isExternalUrl } from '@/lib/urls';
+import { siteConfig } from '../../site.config';
+
+describe('Unit: isExternalUrl', () => {
+  test('absolute http(s) to a different host is external', () => {
+    expect(isExternalUrl('https://en.wikipedia.org/wiki/Feature_engineering')).toBe(true);
+    expect(isExternalUrl('http://example.com/')).toBe(true);
+  });
+
+  test('absolute URL pointing back at siteConfig.baseUrl is internal', () => {
+    const u = new URL(siteConfig.baseUrl);
+    expect(isExternalUrl(`${u.origin}/posts/foo`)).toBe(false);
+  });
+
+  test('protocol-relative URL is compared by host', () => {
+    expect(isExternalUrl('//en.wikipedia.org/wiki/Vector')).toBe(true);
+    const u = new URL(siteConfig.baseUrl);
+    expect(isExternalUrl(`//${u.host}/posts/foo`)).toBe(false);
+  });
+
+  test('protocol-relative with auth or port: classified by parsed host', () => {
+    // `//user:pass@host/...` — host is `host`, NOT `user:pass@host`. Substring
+    // splitting on `/` would have got this wrong.
+    expect(isExternalUrl('//user:pass@en.wikipedia.org/wiki/Vector')).toBe(true);
+    // `//host:8080/...` — port is part of host.
+    expect(isExternalUrl('//en.wikipedia.org:8080/wiki/Vector')).toBe(true);
+    // `//:80/path` — no host, URL parsing rejects it → false (non-external).
+    expect(isExternalUrl('//:80/path')).toBe(false);
+  });
+
+  test('relative paths, hash, and query are internal', () => {
+    expect(isExternalUrl('/posts/foo')).toBe(false);
+    expect(isExternalUrl('foo.md')).toBe(false);
+    expect(isExternalUrl('#section')).toBe(false);
+    expect(isExternalUrl('?tab=2')).toBe(false);
+  });
+
+  test('non-http schemes are not treated as external links', () => {
+    // Semantically external, but click semantics differ — no outward arrow.
+    expect(isExternalUrl('mailto:foo@bar.com')).toBe(false);
+    expect(isExternalUrl('tel:+1234')).toBe(false);
+    expect(isExternalUrl('ftp://example.com/')).toBe(false);
+    expect(isExternalUrl('javascript:void(0)')).toBe(false);
+  });
+
+  test('empty / nullish / malformed returns false', () => {
+    expect(isExternalUrl('')).toBe(false);
+    expect(isExternalUrl(undefined)).toBe(false);
+    expect(isExternalUrl(null)).toBe(false);
+    expect(isExternalUrl('http://[malformed')).toBe(false);
+  });
+});
+
+describe('Integration: external-link icon in MarkdownRenderer', () => {
+  test('external link gets the LuArrowUpRight icon and target=_blank', async () => {
+    const content = 'See [Wikipedia](https://en.wikipedia.org/wiki/Vector) for details.';
+    const html = await renderAsync(MarkdownRenderer({ content }));
+    // react-icons/lu renders an inline <svg>; LuArrowUpRight has a distinctive path.
+    // We assert on stable surface: presence of an <svg> inside the anchor + new-tab attrs.
+    expect(html).toMatch(/<a [^>]*href="https:\/\/en\.wikipedia\.org\/wiki\/Vector"[^>]*target="_blank"/);
+    expect(html).toContain('rel="noopener noreferrer"');
+    // The icon is an inline svg appended directly after the link text inside the anchor.
+    expect(html).toMatch(/Wikipedia<svg/);
+  });
+
+  test('internal link gets no icon and no target=_blank', async () => {
+    const content = 'See [vectors](/books/dmla/maths/linear/vectors/) for details.';
+    const html = await renderAsync(MarkdownRenderer({ content }));
+    expect(html).toContain('href="/books/dmla/maths/linear/vectors/"');
+    expect(html).not.toMatch(/href="\/books\/dmla\/maths\/linear\/vectors\/"[^>]*target="_blank"/);
+    // No svg inside this specific anchor.
+    expect(html).not.toMatch(/vectors<\/a>[^<]*<svg/);
+  });
+
+  test('mailto link is not decorated', async () => {
+    const content = 'Email [me](mailto:foo@bar.com).';
+    const html = await renderAsync(MarkdownRenderer({ content }));
+    expect(html).toContain('href="mailto:foo@bar.com"');
+    expect(html).not.toMatch(/href="mailto:[^"]+"[^>]*target="_blank"/);
+  });
+
+  test('absolute URL to the site host stays internal', async () => {
+    const u = new URL(siteConfig.baseUrl);
+    const content = `See [home](${u.origin}/posts/foo).`;
+    const html = await renderAsync(MarkdownRenderer({ content }));
+    // Escape regex metacharacters in the interpolated origin — without this,
+    // dots in e.g. `amytis.vercel.app` would match any character, making the
+    // `not.toMatch` assertion too lax.
+    const escapeRegex = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    expect(html).not.toMatch(new RegExp(`href="${escapeRegex(u.origin)}/posts/foo"[^>]*target="_blank"`));
+  });
+
+  test('image-as-link skips the icon (image already signals the destination)', async () => {
+    const content = '[![logo](/logo.png)](https://example.com/)';
+    const html = await renderAsync(MarkdownRenderer({ content }));
+    // Anchor is still external (target=_blank), but no icon appended after the <img>.
+    expect(html).toContain('target="_blank"');
+    expect(html).not.toMatch(/<img[^>]*>\s*<svg/);
+  });
+});

package/tests/integration/normalize-vuepress-math.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, test } from "bun:test";
+import { normalizeVuepressBlockMath } from "../../src/lib/normalize-vuepress-math";
+import MarkdownRenderer from "@/components/MarkdownRenderer";
+import { renderAsync } from "@/test-utils/render";
+
+describe("Integration: normalizeVuepressBlockMath", () => {
+  test("splits an inline-style $$ opener+closer onto their own lines", () => {
+    const src = [
+      "$$ \\mathbf{A} = \\begin{bmatrix}",
+      "a & b \\\\",
+      "c & d",
+      "\\end{bmatrix} $$",
+    ].join("\n");
+    const out = normalizeVuepressBlockMath(src);
+    expect(out.split("\n")).toEqual([
+      "$$",
+      "\\mathbf{A} = \\begin{bmatrix}",
+      "a & b \\\\",
+      "c & d",
+      "\\end{bmatrix}",
+      "$$",
+    ]);
+  });
+
+  test("expands single-line $$ x $$ onto three lines so remark-math treats it as block", () => {
+    // micromark-extension-math requires `$$` on its own line; single-line
+    // collapses to inline (no katex-display, no centering, no block margin).
+    const src = "$$ x^2 + y^2 = 1 $$";
+    expect(normalizeVuepressBlockMath(src).split("\n")).toEqual([
+      "$$",
+      "x^2 + y^2 = 1",
+      "$$",
+    ]);
+  });
+
+  test("leaves degenerate empty $$$$ alone", () => {
+    expect(normalizeVuepressBlockMath("$$$$")).toBe("$$$$");
+    expect(normalizeVuepressBlockMath("$$  $$")).toBe("$$  $$");
+  });
+
+  test("preserves the opener indent when expanding a single-line block", () => {
+    const src = "    $$ y = mx + b $$";
+    expect(normalizeVuepressBlockMath(src).split("\n")).toEqual([
+      "    $$",
+      "    y = mx + b",
+      "    $$",
+    ]);
+  });
+
+  test("does not touch inline $...$ math", () => {
+    const src = "An equation: $x = 1$ in the middle of a paragraph.";
+    expect(normalizeVuepressBlockMath(src)).toBe(src);
+  });
+
+  test("is idempotent — already-normalized blocks pass through unchanged", () => {
+    const src = ["$$", "x = 1", "$$"].join("\n");
+    expect(normalizeVuepressBlockMath(src)).toBe(src);
+    expect(normalizeVuepressBlockMath(normalizeVuepressBlockMath(src))).toBe(src);
+  });
+
+  test("skips $$ inside fenced code blocks (doc examples)", () => {
+    const src = [
+      "Here is the source:",
+      "",
+      "```",
+      "$$ \\mathbf{A} = \\begin{bmatrix} a \\end{bmatrix} $$",
+      "```",
+      "",
+      "Real math follows:",
+      "",
+      "$$ y = mx + b $$",
+    ].join("\n");
+    const out = normalizeVuepressBlockMath(src);
+    // The code-block example is preserved verbatim — no split.
+    expect(out).toContain("$$ \\mathbf{A} = \\begin{bmatrix} a \\end{bmatrix} $$");
+    // The real single-line block math after the fence is expanded onto its
+    // own three lines so remark-math recognizes it as block.
+    expect(out).toContain("$$\ny = mx + b\n$$");
+    expect(out).not.toContain("$$ y = mx + b $$");
+  });
+
+  test("preserves opener indent on split lines for list-nested block math", () => {
+    // A 4-space-indented block inside a bullet item. Without indent
+    // preservation, the split body lines drop out of the list and the
+    // following inline math gets parsed as one big malformed math span.
+    const src = [
+      "- Item with embedded math:",
+      "",
+      "    $$\\mathbf{A} = \\begin{bmatrix}",
+      "    a & b",
+      "    \\end{bmatrix}$$",
+      "",
+      "- Next item with inline math: $\\mathbf{X}$, comma here.",
+    ].join("\n");
+    const out = normalizeVuepressBlockMath(src);
+    // Synthetic opener line carries the original 4-space indent so it stays
+    // inside the list item.
+    expect(out).toContain("    $$\n    \\mathbf{A}");
+    // Closer's `$$` likewise stays indented.
+    expect(out).toContain("    \\end{bmatrix}\n    $$");
+  });
+
+  test("handles multiple block-math runs in the same source", () => {
+    const src = [
+      "$$ a = 1",
+      "b = 2 $$",
+      "",
+      "Some prose.",
+      "",
+      "$$ c = 3",
+      "d = 4 $$",
+    ].join("\n");
+    const out = normalizeVuepressBlockMath(src);
+    // Both runs split, prose preserved.
+    expect(out.split(/^\$\$$/m).length).toBeGreaterThanOrEqual(5);
+    expect(out).toContain("Some prose.");
+  });
+});
+
+describe("Integration: end-to-end LaTeX rendering for VuePress-style block math", () => {
+  test("a multi-line bmatrix block renders as a katex-display, not katex-error", async () => {
+    const html = await renderAsync(
+      MarkdownRenderer({
+        content: [
+          "$$ \\mathbf{A} = \\begin{bmatrix}",
+          "a & b \\\\",
+          "c & d",
+          "\\end{bmatrix} $$",
+        ].join("\n"),
+        latex: true,
+      }),
+    );
+    expect(html).toContain("katex-display");
+    expect(html).not.toContain("katex-error");
+  });
+
+  test("normalization only runs when latex is true (idempotent so this is a perf hint)", async () => {
+    // With latex disabled, the math fences are passed through unchanged
+    // to ReactMarkdown — same input the engine would have always seen.
+    // We just verify the page renders without crashing.
+    const html = await renderAsync(
+      MarkdownRenderer({
+        content: "$$ x $$",
+        latex: false,
+      }),
+    );
+    expect(html).toContain("$$"); // not turned into math because latex was off
+  });
+});

package/tests/integration/reading-time-headings.test.ts

@@ -2,22 +2,24 @@ import { describe, expect, test } from "bun:test";
 import { getAllPosts, getPostBySlug } from "../../src/lib/markdown";
 
 describe("Integration: Reading Time & Headings", () => {
-  test("posts have readingTime matching expected format", () => {
+  test("posts have a positive whole-minute readingMinutes", () => {
     const posts = getAllPosts();
     expect(posts.length).toBeGreaterThan(0);
 
     posts.forEach((post) => {
-      expect(post.readingTime).toMatch(/^\d+ min read$/);
+      expect(Number.isInteger(post.readingMinutes)).toBe(true);
+      expect(post.readingMinutes).toBeGreaterThanOrEqual(1);
     });
   });
 
-  test("kitchen-sink post has readingTime in correct format", () => {
+  test("kitchen-sink post has a positive readingMinutes", () => {
     const post = getPostBySlug("kitchen-sink");
     if (!post) {
       console.warn("Skipping: kitchen-sink post not found");
       return;
     }
-    expect(post.readingTime).toMatch(/^\d+ min read$/);
+    expect(Number.isInteger(post.readingMinutes)).toBe(true);
+    expect(post.readingMinutes).toBeGreaterThanOrEqual(1);
   });
 
   test("headings on real posts have correct structure", () => {
@@ -49,13 +51,13 @@ describe("Integration: Reading Time & Headings", () => {
     });
   });
 
-  test("short posts have 1 min read", () => {
+  test("short posts have readingMinutes === 1 (floor)", () => {
     const shortPost = getPostBySlug("legacy-markdown");
     expect(shortPost).toBeDefined();
     if (!shortPost) {
       throw new Error("fixture 'legacy-markdown' not found");
     }
-    expect(shortPost.readingTime).toBe("1 min read");
+    expect(shortPost.readingMinutes).toBe(1);
   });
 
   test("multilingual post has headings with correct IDs", () => {