@clidey/dory 1.9.0 → 1.10.0

package/docs/components/layout.mdx

@@ -122,6 +122,8 @@ Use `sticky` on the code column so it stays visible while the prose scrolls.
 
 </Specimen>
 
+Rows stack on narrow screens and use the requested column count from the small-screen breakpoint (640px). Columns can shrink within their grid so long content stays inside the preview.
+
 ## Specimen
 
 `<Specimen>` frames a component example with **Preview**, **Code** and **Props** tabs. Put the MDX source in an ` ```mdx ` fence, the rendered example after it, and optional `<Prop>` rows inside `<SpecimenProps>`. Tabs only appear for the parts you include.
@@ -149,6 +151,7 @@ Use `sticky` on the code column so it stays visible while the prose scrolls.
 <SpecimenProps>
 
 <Prop name="label" type="string">Mono caption in the header, usually the component tag. Write angle brackets as `&lt;` and `&gt;`.</Prop>
+<Prop name="padding" type="'default' | 'none'">Preview spacing. Defaults to an inset preview. Use `none` only when the example provides its own padding.</Prop>
 <Prop name="children" type="ReactNode">An ` ```mdx ` fence (Code tab), a `<SpecimenProps>` block (Props tab), and the preview.</Prop>
 
 </SpecimenProps>

package/docs/components/lists.mdx

@@ -123,12 +123,12 @@ Standard Markdown list items support inline formatting:
 - **Bold item** — important information
 - *Italic item* — supplementary detail
 - Item with `inline code` — technical terms
-- Item with a [link](https://dory.clidey.com) — external reference
+- Item with a [link](https://clidey.github.io/dory/) — external reference
 ```
 
 - **Bold item** — important information
 - *Italic item* — supplementary detail
 - Item with `inline code` — technical terms
-- Item with a [link](https://dory.clidey.com) — external reference
+- Item with a [link](https://clidey.github.io/dory/) — external reference
 
 </Specimen>

package/docs/components/overview.mdx

@@ -36,7 +36,7 @@ Dory ships with **24 built-in MDX components** you can use directly in `.mdx` fi
   <Card title="Mermaid Diagrams" href="/components/mermaid" icon="git-branch" description="Flowcharts, sequence diagrams, ER diagrams, and more." />
   <Card title="LaTeX Math" href="/components/latex" icon="sigma" description="Render mathematical expressions using KaTeX." />
   <Card title="Images" href="/components/images" icon="image" description="Clickable images with fullscreen modal overlay." />
-  <Card title="Icons" href="/components/icons" icon="star" description="Inline icons from the WhoDB suite." />
+  <Card title="Icons" href="/components/icons" icon="star" description="Inline icons from the shared Clidey UX catalog." />
 </CardGroup>
 
 ## Utility Components

package/docs/components/typography.mdx

@@ -19,14 +19,14 @@ Markdown headings map to the display scale. Inline formatting covers emphasis, c
 ### Heading 3
 #### Heading 4
 
-**Bold**, *italic*, `inline code`, [a link](https://dory.clidey.com), <kbd>⌘K</kbd>, and <mark>a highlight</mark>.
+**Bold**, *italic*, `inline code`, [a link](https://clidey.github.io/dory/), <kbd>⌘K</kbd>, and <mark>a highlight</mark>.
 
 > Blockquotes hold asides and quotes.
 ```
 
 <TypeScale />
 
-**Bold**, *italic*, `inline code`, [a link](https://dory.clidey.com), <kbd>⌘K</kbd>, and <mark>a highlight</mark>.
+**Bold**, *italic*, `inline code`, [a link](https://clidey.github.io/dory/), <kbd>⌘K</kbd>, and <mark>a highlight</mark>.
 
 > Blockquotes hold asides and quotes.
 
@@ -67,10 +67,10 @@ Use standard Markdown link syntax for hyperlinks:
 <Specimen label="[link](url)">
 
 ```mdx
-[Visit the Dory site](https://dory.clidey.com)
+[Visit the Dory site](https://clidey.github.io/dory/)
 ```
 
-[Visit the Dory site](https://dory.clidey.com)
+[Visit the Dory site](https://clidey.github.io/dory/)
 
 </Specimen>
 

package/docs/configuration/navigation.mdx

@@ -205,10 +205,10 @@ Add a `lead` string to show a larger introductory paragraph directly under the p
 ```mdx
 ---
 title: 'Introduction'
-description: 'What WhoDB is and how to get started.'
-lead: 'WhoDB is a database management tool for exploring schemas, managing data and visualizing relationships.'
+description: 'What Dory is and how to get started.'
+lead: 'Dory turns MDX pages into a documentation site with navigation, search, and interactive components.'
 meta:
-  Edition: Community
+  License: MIT
   Updated: 2026-10-12
   Read: 4 min
 ---

package/docs/contributing.mdx

@@ -0,0 +1,47 @@
+---
+title: 'Contributing to Dory'
+description: 'Develop Dory, review its own documentation, and understand the publishing workflow.'
+---
+
+Dory's public README introduces the product. This guide covers work on the repository itself. To create a separate documentation site, use the [quick start](/getting-started/quick-start).
+
+## Run the repository
+
+```bash
+git clone https://github.com/clidey/dory.git
+cd dory
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm dev
+```
+
+Edit Dory's own pages under `docs/`. Keep dependency lifecycle scripts disabled and preserve the repository's dependency integrity and release-age policies.
+
+## Validate changes
+
+```bash
+pnpm test
+node --import tsx --test bin/dependency-overlay.test.mts bin/preview-static.test.mts
+pnpm build
+node bin/dist/dory.js check
+node scripts/verify-component-examples.mjs
+```
+
+The component browser check uses installed Chrome (or `DORY_CHROME_PATH`), measures preview padding and clipping, exercises tabs, and verifies math loading and failure states on desktop and mobile. It saves screenshots and a report under ignored `.dory/component-review/`; inspect these before publishing.
+
+Review browser behavior in light and dark modes. For custom components, verify interactions and focus handling; compilation alone cannot do that.
+
+## Preview the production site
+
+```bash
+pnpm preview --host 127.0.0.1 --port 3188 --strictPort
+```
+
+Open `http://127.0.0.1:3188/dory/`. Review code and the exact generated site before pushing or publishing changes.
+
+## Publish this repository's docs
+
+The documentation workflow validates pull requests and deploys main-branch documentation to `https://clidey.github.io/dory/`. Its canonical URL and path are configured in `docs/dory.json`; GitHub Pages uses GitHub Actions as the publishing source.
+
+Publish only the generated `dist/` artifact. Static Pages hosting includes navigation and search. Documentation chat and HTTP MCP need a separately hosted Dory server; do not put server credentials into static assets.
+
+Imported MDX and component modules are executable source. Review them, build untrusted contributions without secrets or deployment credentials, and deploy reviewed artifacts separately. See the repository security policy for the trust boundary.

package/docs/dory.json

@@ -1,8 +1,8 @@
 {
   "name": "Dory",
-  "url": "https://dory.clidey.com",
+  "url": "https://clidey.github.io",
   "image": "/social-card.png",
-  "version": "1.0.8 · Latest",
+  "version": "1.10.0 \u00b7 Latest",
   "copyright": "Clidey",
   "repository": {
     "url": "https://github.com/clidey/dory",
@@ -11,7 +11,7 @@
   },
   "description": "Static documentation site generator for modern teams. Build beautiful docs from MDX files.",
   "seo": {
-    "titleTemplate": "%s — Dory"
+    "titleTemplate": "%s \u2014 Dory"
   },
   "favicon": "./favicon.svg",
   "fonts": {
@@ -39,8 +39,8 @@
               "getting-started/installation",
               "getting-started/quick-start",
               "getting-started/automation",
-              "getting-started/whodb-ee-apps",
-              "getting-started/configuration"
+              "getting-started/configuration",
+              "getting-started/custom-components"
             ]
           },
           {
@@ -55,6 +55,12 @@
               "configuration/internationalization",
               "configuration/embed"
             ]
+          },
+          {
+            "group": "Contribute",
+            "pages": [
+              "contributing"
+            ]
           }
         ]
       },
@@ -125,5 +131,6 @@
         ]
       }
     ]
-  }
+  },
+  "basePath": "/dory"
 }

package/docs/getting-started/automation.mdx

@@ -30,8 +30,8 @@ A Dory site served with `dory preview` also exposes a public, read-only Streamab
 Add the endpoint once in your MCP client:
 
 ```bash
-codex mcp add whodb-docs --url https://docs.whodb.com/mcp
-claude mcp add --transport http whodb-docs https://docs.whodb.com/mcp
+codex mcp add example-docs --url https://docs.example.com/mcp
+claude mcp add --transport http example-docs https://docs.example.com/mcp
 ```
 
 Replace the example URL with your Dory site. If the docs run behind a reverse proxy, forward `/mcp` to the Dory preview server. Its `dory.json` `url` must match the public hostname; for an additional preview hostname, set `DORY_MCP_ALLOWED_HOSTS` to a comma-separated list. The endpoint rejects other hostnames and cross-origin browser requests.

package/docs/getting-started/custom-components.mdx

@@ -0,0 +1,60 @@
+---
+title: 'Custom interactive components'
+description: 'Import a local component into static MDX and let readers try its real behavior.'
+---
+
+Static Dory projects can import JSX components into an MDX page. Use a local component module for hooks, events, and stateful interactions; Dory preserves its imported name during preprocessing.
+
+## Put the implementation under docs
+
+```tsx
+// docs/examples/counter.tsx
+import { useState } from 'react';
+import { Button } from '@clidey/ux';
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <div>
+    <Button onClick={() => setCount(value => value + 1)}>Add one</Button>
+    <p role="status">Clicked {count} times</p>
+  </div>;
+}
+```
+
+## Import it into a page
+
+```mdx
+---
+title: 'Try the button'
+---
+
+import { Counter } from '../examples/counter.tsx';
+
+<Counter />
+```
+
+Default imports, named aliases, and namespace imports are supported. Keep imported component names explicit. An unimported custom tag retains the existing prose-escaping behavior; a name mentioned inside a fenced example does not register a component.
+
+## Keep state in the module
+
+Dory treats inline MDX text expressions as literal code. Put state displays, event handlers, and business logic in the imported component module instead of inline MDX expressions. Import a scoped stylesheet from the module if the example needs layout styling.
+
+Static builds and prerendering alias React to Preact compatibility. Keep browser-only work in effects or event handlers, and make the initial render work without `window` or `document`.
+
+## Build boundaries
+
+The CLI stages the documentation directory into an isolated build workspace. Keep local modules and styles under that directory. Imports reaching into a sibling application source tree do not survive staging.
+
+The build resolves Dory's installed dependencies first, then makes missing installed dependencies from the consuming project available up to its nearest workspace or lockfile root. React uses Dory's Preact compatibility aliases.
+
+For an intentional package replacement, set `DORY_PACKAGE_OVERRIDES` to a JSON object mapping package names to absolute package directories. Dory validates each name, directory, and matching package manifest before creating the isolated dependency overlay. Installed dependencies are not modified.
+
+## Security and trusted source
+
+Imported components are executable application code. Their modules may execute during bundling and server rendering with the build process's privileges, then in the reader's browser. Review their source and dependencies before building. The staging directory is not a security sandbox. Build pull requests on disposable runners without secrets, persisted checkout credentials, or deployment tokens, and deploy a reviewed artifact in a separate job. See the repository security policy.
+
+## Static source and embedded content
+
+This feature applies to trusted documentation built from a local checkout. It does not enable custom imports in Dory's sandboxed embedded runtime. That runtime keeps its existing component allowlist, import restrictions, and content security policy.
+
+Run `dory check`, build the site, then test the interactions in the actual output. Compilation alone does not prove a button updates state or an overlay handles focus correctly.

package/docs/social-card.svg

@@ -13,5 +13,5 @@
 <text x="76" y="420" fill="#b2bdd0" font-family="Hanken Grotesk,Arial,sans-serif" font-size="26">Build beautiful documentation from MDX.</text>
 <path d="M76 512H1124" stroke="#344767"/>
 <text x="76" y="559" fill="#aebace" font-family="Hanken Grotesk,Arial,sans-serif" font-size="21">Open source. Built for teams.</text>
-<text x="1124" y="559" text-anchor="end" fill="#8caffb" font-family="Hanken Grotesk,Arial,sans-serif" font-size="21">dory.clidey.com</text>
+<text x="1124" y="559" text-anchor="end" fill="#8caffb" font-family="Hanken Grotesk,Arial,sans-serif" font-size="21">clidey.github.io/dory</text>
 </svg>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clidey/dory",
   "private": false,
-  "version": "1.9.0",
+  "version": "1.10.0",
   "type": "module",
   "description": "A CLI tool for building and previewing documentation sites",
   "keywords": [

package/scripts/verify-component-examples.mjs

@@ -0,0 +1,126 @@
+import assert from 'node:assert/strict';
+import {mkdir, readFile, writeFile} from 'node:fs/promises';
+import {dirname, join, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {chromium} from 'playwright-core';
+import {preview} from 'vite';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const config = JSON.parse(await readFile(join(root, 'docs/dory.json'), 'utf8'));
+const routes = config.navigation.tabs.flatMap(tab => tab.groups.flatMap(group => group.pages))
+  .map(page => typeof page === 'string' ? page : page.page).filter(page => page.startsWith('components/'));
+const output = join(root, '.dory/component-review');
+await mkdir(output, {recursive: true});
+const report = {pages: 0, previews: 0, errors: [], screenshots: []};
+let server;
+let browser;
+try {
+  let base = process.argv[2];
+  if (!base) {
+    server = await preview({root, preview: {host: '127.0.0.1', port: 3189, strictPort: true}});
+    base = server.resolvedUrls.local[0];
+  }
+  if (!base.endsWith('/')) base += '/';
+  browser = await chromium.launch({channel: 'chrome', headless: true, ...(process.env.DORY_CHROME_PATH ? {executablePath: process.env.DORY_CHROME_PATH} : {})});
+  // A missing lazy math asset must leave a readable equation and an error, not
+  // a blank spinner. This context has its own cache so the request is real.
+  const unavailable = await browser.newContext({viewport: {width: 390, height: 844}});
+  const failedMath = await unavailable.newPage();
+  await failedMath.route(/\/assets\/katex-[^/]+\.js$/, route => route.abort());
+  await failedMath.goto(new URL('components/latex/', base).href, {waitUntil: 'domcontentloaded'});
+  await failedMath.getByRole('alert').filter({hasText: 'The equation could not be rendered.'}).first().waitFor();
+  assert.ok((await failedMath.locator('[data-latex-fallback]').first().innerText()).trim(), 'Failed math retains readable content');
+  assert.equal(await failedMath.locator('.dory-latex .animate-spin').count(), 0, 'Failed math does not spin forever');
+  await unavailable.close();
+  report.mathFailureFallback = true;
+  for (const scenario of [
+    {name: 'desktop-dark', viewport: {width: 1440, height: 1000}, colorScheme: 'dark'},
+    {name: 'mobile-light', viewport: {width: 390, height: 844}, colorScheme: 'light'},
+  ]) {
+    const context = await browser.newContext({viewport: scenario.viewport, colorScheme: scenario.colorScheme});
+    const page = await context.newPage();
+    page.on('pageerror', error => report.errors.push(`${scenario.name}: ${error.message}`));
+    for (const route of routes) {
+      const label = `${scenario.name} ${route}`;
+      try {
+        const response = await page.goto(new URL(route + '/', base).href, {waitUntil: 'domcontentloaded'});
+        assert.equal(response.status(), 200, `${label}: HTTP status`);
+        await page.locator('article').waitFor();
+        await page.evaluate(() => document.fonts.ready);
+        assert.equal(await page.getByText('This page failed to render', {exact: true}).count(), 0, `${label}: render boundary`);
+        const previews = page.locator('[data-dory-preview]:visible');
+        assert.equal(await previews.count(), await page.locator('.dory-specimen:visible').count(), `${label}: every example has a visible preview`);
+        for (let index = 0; index < await previews.count(); index++) {
+          const panel = previews.nth(index);
+          const padding = await panel.evaluate(element => {
+            const style = getComputedStyle(element);
+            return [style.paddingTop, style.paddingRight, style.paddingBottom, style.paddingLeft].map(parseFloat);
+          });
+          const expected = await panel.getAttribute('data-padding');
+          assert.ok(padding.every(value => expected === 'none' ? value === 0 : value >= 16), `${label} preview ${index + 1}: missing inset (${padding})`);
+          const clipped = await panel.evaluate(element => {
+            const box = element.getBoundingClientRect();
+            const style = getComputedStyle(element);
+            const left = box.left + parseFloat(style.paddingLeft);
+            const right = box.right - parseFloat(style.paddingRight);
+            return [...element.querySelectorAll('.dory-latex, .dory-expandable, .dory-accordion, .dory-table, .dory-card, .dory-callout')]
+              .filter(child => child.getBoundingClientRect().width > 0)
+              .filter(child => { const bounds = child.getBoundingClientRect(); return bounds.left < left - 1 || bounds.right > right + 1; })
+              .map(child => child.className);
+          });
+          assert.deepEqual(clipped, [], `${label} preview ${index + 1}: content clipped by frame`);
+          report.previews++;
+        }
+        if (route === 'components/latex') {
+          await page.waitForFunction(() => {
+            const formulas = [...document.querySelectorAll('.dory-latex, .dory-latex-inline')];
+            return formulas.length > 0 && formulas.every(element => element.querySelector('.katex'));
+          }, undefined, {timeout: 15000});
+          assert.equal(await page.locator('[data-latex-fallback]').count(), 0, `${label}: math still loading`);
+          assert.equal(await page.locator('.katex-error').count(), 0, `${label}: invalid formula`);
+        }
+        if (route === 'components/typography') {
+          assert.equal(await page.locator('.dory-type-scale > div').count(), 4, `${label}: heading samples`);
+          assert.equal(await page.locator('.dory-type-scale').evaluate(element => element.scrollWidth > element.clientWidth + 1), false, `${label}: heading sample overflows`);
+        }
+        if (route === 'components/expandable') {
+          const specimen = page.locator('.dory-specimen').first();
+          const inner = specimen.locator('.dory-expandable').first();
+          const outerBounds = await specimen.boundingBox();
+          const innerBounds = await inner.boundingBox();
+          assert.ok(innerBounds.x - outerBounds.x >= 16, `${label}: nested border touches frame`);
+          await inner.getByRole('button', {name: 'Response Body', exact: true}).click();
+          await inner.locator('[data-state="open"]').first().waitFor();
+        }
+        const specimen = page.locator('.dory-specimen').first();
+        if (await specimen.count()) {
+          const codeTab = specimen.getByRole('tab', {name: 'Code', exact: true}).first();
+          if (await codeTab.count()) {
+            await codeTab.click();
+            await page.waitForFunction(element => element.getAttribute('aria-selected') === 'true', await codeTab.elementHandle());
+            assert.ok(await specimen.locator('[role="tabpanel"]:visible code').count(), `${label}: source panel missing`);
+            await specimen.getByRole('tab', {name: 'Preview', exact: true}).first().click();
+          }
+          if (['components/typography', 'components/expandable', 'components/latex', 'components/callouts'].includes(route)) {
+            const file = `${scenario.name}-${route.split('/')[1]}.png`;
+            await specimen.screenshot({path: join(output, file)});
+            report.screenshots.push(file);
+          }
+        }
+        assert.equal(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1), true, `${label}: page overflows horizontally`);
+        report.pages++;
+        console.log(`PASS ${label}`);
+      } catch (error) {
+        report.errors.push(error.message);
+        console.error(`FAIL ${error.message}`);
+      }
+    }
+    await context.close();
+  }
+} finally {
+  await browser?.close();
+  await new Promise(resolve => server ? server.httpServer.close(resolve) : resolve());
+  await writeFile(join(output, 'report.json'), JSON.stringify(report, null, 2) + '\n');
+}
+console.log(JSON.stringify(report, null, 2));
+if (report.errors.length) process.exitCode = 1;

package/scripts/verify-runtime-parity.mjs

@@ -6,7 +6,7 @@ import { preview } from 'vite';
 
 const root = resolve(fileURLToPath(new URL('..', import.meta.url)));
 const docsRoot = join(root, 'docs');
-const pagePath = 'getting-started/whodb-ee-apps';
+const pagePath = 'getting-started/automation';
 
 function docsFiles(directory = docsRoot) {
   return readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
@@ -19,6 +19,7 @@ function docsFiles(directory = docsRoot) {
 }
 
 const config = JSON.parse(readFileSync(join(docsRoot, 'dory.json'), 'utf8'));
+const basePath = String(config.basePath || '').replace(/\/$/, '');
 const logo = readFileSync(join(docsRoot, 'logo/logo.svg')).toString('base64');
 config.logo = {
   light: `data:image/svg+xml;base64,${logo}`,
@@ -100,17 +101,17 @@ try {
   browser = await chromium.launch({ channel: 'chrome', headless: true });
   for (const theme of ['light', 'dark']) {
     const full = await browser.newPage({ viewport: { width: 2048, height: 1200 } });
-    await full.goto(`${origin}/${pagePath}`, { waitUntil: 'networkidle' });
+    await full.goto(`${origin}${basePath}/${pagePath}`, { waitUntil: 'networkidle' });
     if (theme === 'dark') await full.locator('html').evaluate(element => { element.classList.remove('light'); element.classList.add('dark'); });
     await full.evaluate(() => document.fonts.ready);
     const fullMetrics = await full.evaluate(visualMetrics);
 
     const embed = await browser.newPage({ viewport: { width: 2048, height: 1200 } });
-    await embed.goto(`${origin}/runtime/dory-runtime.html`, { waitUntil: 'networkidle' });
+    await embed.goto(`${origin}${basePath}/runtime/dory-runtime.html`, { waitUntil: 'networkidle' });
     await embed.evaluate(({ files, config, theme, pagePath }) => {
       window.postMessage({ __dory_docs: true, type: 'load', files, path: `docs/${pagePath}.mdx`, theme, locale: 'en_US', config }, '*');
     }, { files: docsFiles(), config, theme, pagePath });
-    await embed.getByRole('heading', { name: 'Document WhoDB EE apps' }).waitFor();
+    await embed.getByRole('heading', { name: 'CLI and MCP automation' }).waitFor();
     await embed.evaluate(() => document.fonts.ready);
     const embedMetrics = await embed.evaluate(visualMetrics);
     compare(fullMetrics, embedMetrics, theme);

package/src/app.css

@@ -3,6 +3,9 @@
 @import "tailwindcss/theme.css" layer(theme);
 @import "tailwindcss/utilities.css" layer(utilities);
 
+/* Emit UX variants alongside Dory’s utilities so responsive rules stay ordered. */
+@source "../node_modules/@clidey/ux/dist";
+
 @custom-variant dark (&:where(.dark, .dark *));
 
 .mermaid-wrapper .mermaid svg {

package/src/main.tsx

@@ -43,7 +43,7 @@ if (embedTheme) document.documentElement.style.colorScheme = embedTheme;
 
 const tree = (
     <ThemeProvider defaultTheme={defaultTheme} storageKey={embedTheme ? `@clidey/dory/embed-theme-${embedTheme}` : '@clidey/dory/theme'}>
-        <Toaster />
+        <Toaster closeButton />
         <ErrorBoundary>
             <Router base={BASE_PATH}>
                 <AppWithMDX />

package/src/mdx/latex.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { createElement } from 'preact';
+import { renderToString } from 'preact-render-to-string';
+import katex from 'katex';
+import { Latex, renderLatexExpression } from './latex';
+
+describe('LaTeX rendering', () => {
+  it('server-renders a readable display fallback with the same client shell', () => {
+    const html = renderToString(createElement(Latex, { children: 'E = mc^2' }));
+    expect(html).toContain('dory-latex not-prose');
+    expect(html).toContain('aria-busy="true"');
+    expect(html).toContain('data-latex-fallback');
+    expect(html).toContain('E = mc^2');
+    expect(html).not.toContain('animate-spin');
+  });
+
+  it('keeps the inline fallback inline and escapes source text', () => {
+    const html = renderToString(createElement(Latex, { inline: true, children: '<img src=x onerror=alert(1)>' }));
+    expect(html).toMatch(/^<span /);
+    expect(html).not.toContain('<div');
+    expect(html).not.toContain('<img');
+    expect(html).toContain('&lt;img');
+  });
+
+  it('renders complex math with KaTeX and the requested mode', () => {
+    const expression = String.raw`\frac{a}{b}`;
+    expect(renderLatexExpression(katex, expression, false)).toContain('katex-display');
+    const inline = renderLatexExpression(katex, expression, true);
+    expect(inline).toContain('mfrac');
+    expect(inline).not.toContain('katex-display');
+  });
+
+  it('does not allow formulas to create trusted links, HTML classes, or image requests', () => {
+    expect(renderLatexExpression(katex, String.raw`\href{javascript:alert(1)}{click}`, true)).not.toMatch(/href=["']javascript:/);
+    expect(renderLatexExpression(katex, String.raw`\htmlClass{injected}{x}`, false)).not.toMatch(/class=["']injected/);
+    expect(renderLatexExpression(katex, String.raw`\includegraphics{https://example.test/tracker.png}`, false)).not.toContain('<img');
+  });
+});