Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: emit only the woff2 KaTeX fonts (#16382)

Daniel Han32d664302b5a
diff --git a/studio/frontend/tests/katex-woff2-only.test.ts b/studio/frontend/tests/katex-woff2-only.test.ts
new file mode 100644
index 00000000000..f3733c5e7e8
--- /dev/null
+++ b/studio/frontend/tests/katex-woff2-only.test.ts
@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { createServer } from "vite";
+
+import { katexWoff2Only, keepWoff2Sources } from "../vite-plugin-katex-woff2.ts";
+
+const require = createRequire(import.meta.url);
+const KATEX_CSS_PATH = require.resolve("katex/dist/katex.min.css");
+const KATEX_CSS = readFileSync(KATEX_CSS_PATH, "utf8");
+
+const FONT_FACE = /@font-face\{[^}]*\}/g;
+
+test("every KaTeX @font-face keeps exactly its woff2 source and nothing else changes", () => {
+ const { css, rules } = keepWoff2Sources(KATEX_CSS);
+ const before = KATEX_CSS.match(FONT_FACE) ?? [];
+ const after = css.match(FONT_FACE) ?? [];
+ assert.ok(before.length >= 20, `expected the KaTeX font set, found ${before.length} rules`);
+ assert.equal(rules, before.length);
+ assert.equal(after.length, before.length);
+ for (const [index, rule] of before.entries()) {
+ const expected = rule.replace(
+ /,url\(fonts\/[\w-]+\.woff\) format\("woff"\),url\(fonts\/[\w-]+\.ttf\) format\("truetype"\)/,
+ "",
+ );
+ assert.notEqual(expected, rule, `rule ${index} lost no fallback: ${rule}`);
+ assert.equal(after[index], expected);
+ }
+ assert.equal(css.replace(FONT_FACE, ""), KATEX_CSS.replace(FONT_FACE, ""));
+ assert.doesNotMatch(css, /\.woff\)|\.ttf\)|format\("woff"\)|format\("truetype"\)/);
+});
+
+test("quoted, spaced and upper-case woff2 sources are kept as written", () => {
+ const css =
+ "@font-face{font-family:A;src:url('a.woff2') format('woff2'),url(a.woff) format(\"woff\")}" +
+ "@font-face{font-family:B;src:url( \"b.woff2\" ) FORMAT( \"WOFF2\" ),url(b.ttf) format(\"truetype\")}" +
+ ".x{src:url(a.woff)}";
+ assert.equal(
+ keepWoff2Sources(css).css,
+ "@font-face{font-family:A;src:url('a.woff2') format('woff2')}" +
+ "@font-face{font-family:B;src:url( \"b.woff2\" ) FORMAT( \"WOFF2\" )}" +
+ ".x{src:url(a.woff)}",
+ );
+});
+
+test("a font-face without a single woff2 source fails the build instead of dropping the font", () => {
+ assert.throws(() => keepWoff2Sources("@font-face{font-family:A;src:url(a.woff) format(\"woff\")}"), /0 woff2/);
+ assert.throws(
+ () =>
+ keepWoff2Sources(
+ "@font-face{font-family:A;src:url(a.woff2) format(\"woff2\"),url(b.woff2) format(\"woff2\")}",
+ ),
+ /2 woff2/,
+ );
+});
+
+test("the plugin runs before vite:css and only on KaTeX's stylesheet", () => {
+ const plugin = katexWoff2Only();
+ assert.equal(plugin.enforce, "pre");
+ const transform = plugin.transform as {
+ filter: { id: RegExp; code: string };
+ handler: (code: string, id: string) => { code: string } | null;
+ };
+ const { id } = transform.filter;
+ for (const path of [
+ "/repo/studio/frontend/node_modules/katex/dist/katex.min.css",
+ "C:\\repo\\studio\\frontend\\node_modules\\katex\\dist\\katex.min.css",
+ "/repo/node_modules/katex/dist/katex.css?direct",
+ KATEX_CSS_PATH,
+ ]) {
+ assert.match(path, id, path);
+ }
+ for (const path of [
+ "/repo/studio/frontend/src/index.css",
+ "/repo/node_modules/katex/dist/contrib/copy-tex.css",
+ "/repo/node_modules/not-katex/dist/katex.min.css",
+ ]) {
+ assert.doesNotMatch(path, id, path);
+ }
+ const result = transform.handler(KATEX_CSS, KATEX_CSS_PATH);
+ assert.ok(result);
+ assert.equal(result.code, keepWoff2Sources(KATEX_CSS).css);
+ assert.throws(() => transform.handler(".katex{color:red}", KATEX_CSS_PATH), /no KaTeX @font-face/);
+});
+
+test("Vite optimizes style imports and preserves raw KaTeX stylesheet imports", async () => {
+ const root = fileURLToPath(new URL("../", import.meta.url));
+ const cacheDir = mkdtempSync(`${root}node_modules/.vite-katex-raw-`);
+ let server: Awaited<ReturnType<typeof createServer>> | undefined;
+ try {
+ server = await createServer({
+ root,
+ cacheDir,
+ logLevel: "silent",
+ server: { host: "127.0.0.1", port: 0, watch: null },
+ optimizeDeps: { noDiscovery: true, include: [] },
+ });
+ await server.listen();
+ const raw = await server.transformRequest("/node_modules/katex/dist/katex.min.css?raw");
+ assert.ok(raw);
+ const loaded = await server.ssrLoadModule("/node_modules/katex/dist/katex.min.css?raw");
+ assert.equal(loaded.default, KATEX_CSS);
+ const direct = await server.transformRequest("/node_modules/katex/dist/katex.min.css?direct");
+ assert.ok(direct);
+ assert.equal(
+ (direct.code.match(/format\(["']?woff2["']?\)/gi) ?? []).length,
+ (KATEX_CSS.match(FONT_FACE) ?? []).length,
+ );
+ assert.doesNotMatch(direct.code, /format\(["']?(?:woff|truetype)["']?\)/i);
+ } finally {
+ await server?.close();
+ rmSync(cacheDir, { recursive: true });
+ }
+});
diff --git a/studio/frontend/vite-plugin-katex-woff2.ts b/studio/frontend/vite-plugin-katex-woff2.ts
new file mode 100644
index 00000000000..f54713b5c25
--- /dev/null
+++ b/studio/frontend/vite-plugin-katex-woff2.ts
@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import postcss from "postcss";
+import type { Plugin } from "vite";
+
+const KATEX_CSS = /[\\/]node_modules[\\/]katex[\\/]dist[\\/]katex(?:\.min)?\.css(?:$|\?)/;
+const WOFF2_SOURCE = /url\(\s*(?:"[^"]*"|'[^']*'|[^)"']*)\s*\)\s*format\(\s*["']?woff2["']?\s*\)/gi;
+
+export function keepWoff2Sources(css: string): { css: string; rules: number } {
+ const root = postcss.parse(css);
+ let rules = 0;
+ root.walkAtRules("font-face", (rule) => {
+ rule.walkDecls("src", (decl) => {
+ const woff2 = decl.value.match(WOFF2_SOURCE);
+ if (!woff2 || woff2.length !== 1) {
+ throw new Error(`@font-face src "${decl.value}" has ${woff2?.length ?? 0} woff2 sources, expected 1`);
+ }
+ decl.value = woff2[0];
+ rules += 1;
+ });
+ });
+ return { css: root.toString(), rules };
+}
+
+export function katexWoff2Only(): Plugin {
+ return {
+ name: "katex-woff2-only",
+ // Rewrite before vite:css emits font assets.
+ enforce: "pre",
+ transform: {
+ filter: { id: KATEX_CSS, code: "@font-face" },
+ handler(code, id) {
+ if (/[?&]raw\b/.test(id)) {
+ return null;
+ }
+ const { css, rules } = keepWoff2Sources(code);
+ if (rules === 0) throw new Error(`no KaTeX @font-face src found in ${id}`);
+ return { code: css, map: null };
+ },
+ },
+ };
+}
diff --git a/studio/frontend/vite.config.ts b/studio/frontend/vite.config.ts
index 463821c96d7..6f7d5e0723d 100644
--- a/studio/frontend/vite.config.ts
+++ b/studio/frontend/vite.config.ts
@@ -8,6 +8,7 @@ import { type Plugin, defineConfig } from "vite";
import { chatPagePreload } from "./vite-plugin-chat-preload";
import { childSelectorOrder } from "./vite-plugin-child-selectors";
import { hasAnchorOrder } from "./vite-plugin-has-anchor";
+import { katexWoff2Only } from "./vite-plugin-katex-woff2";
import { viewportMediaGate } from "./vite-plugin-viewport-media";
import { previewRuntime } from "./vite-preview-runtime.ts";
@@ -34,7 +35,7 @@ export default defineConfig({
cacheDir: process.env.VITE_TEST_CACHE_DIR || "node_modules/.vite",
// Reasoning's highlighter loads only the grammar it needs in its module worker.
worker: { format: "es" },
- plugins: [react(), tailwindcss(), childSelectorOrder(), hasAnchorOrder(), viewportMediaGate(), smokeModuleDelay(), previewRuntime(), chatPagePreload()],
+ plugins: [react(), tailwindcss(), childSelectorOrder(), hasAnchorOrder(), viewportMediaGate(), smokeModuleDelay(), previewRuntime(), chatPagePreload(), katexWoff2Only()],
// prevent ancestor PostCSS configs from leaking into installs; Tailwind uses its Vite plugin.
css: {
postcss: {