@aleph-alpha/chat-kit 3.1.2 → 3.2.0

package/src/composables/fileUpload/useFileUploadWrapper.spec.ts

@@ -1,6 +1,34 @@
+import { flushPromises } from '@vue/test-utils';
+import { ref } from 'vue';
 import { createDocumentUploadProvider } from './useFileUploadWrapper';
 import type { DocumentUploadConfig } from './types';
 
+const uploadMock = vi.hoisted(() => ({
+  upload: vi.fn().mockResolvedValue({ results: [] }),
+}));
+
+vi.mock('./useFileUpload', () => ({
+  useFileUpload: vi.fn((options) => {
+    const scopedFiles = ref([]);
+    return {
+      files: ref(new Map()),
+      getSupportedFileTypes: () => ({
+        maxFilesPerUpload: options.maxFilesPerUpload ?? 20,
+        allowedMimeTypes: ['application/pdf'],
+        allowedExtensions: ['.pdf'],
+        maxFileSizeBytes: 100 * 1024 * 1024,
+      }),
+      scopeBy: () => ({ files: scopedFiles }),
+      upload: uploadMock.upload,
+      runWorkflow: vi.fn().mockResolvedValue({ close: vi.fn() }),
+      setStoreId: vi.fn(),
+      setWorkflowId: vi.fn(),
+      updateFileMetadata: vi.fn(),
+      removeFile: vi.fn(),
+    };
+  }),
+}));
+
 function createFile(name: string, size = 100): File {
   return new File(['x'.repeat(size)], name, { type: 'application/pdf' });
 }
@@ -31,6 +59,7 @@ function buildConfig(
   return {
     baseUrl: 'https://test.example.com',
     workflowId: 'wf-1',
+    persist: false,
     searchStoreConfig: {
       models: [
         {
@@ -48,16 +77,35 @@ function buildConfig(
   };
 }
 
+async function settleAsyncUploads() {
+  await flushPromises();
+}
+
 describe('useFileUploadWrapper handleFilesSelected', () => {
   let fetchMock: ReturnType<typeof vi.fn>;
 
   beforeEach(() => {
+    uploadMock.upload.mockClear();
+    uploadMock.upload.mockResolvedValue({ results: [] });
+
     fetchMock = vi.fn();
     vi.stubGlobal('fetch', fetchMock);
 
     fetchMock.mockImplementation((url: string, init?: RequestInit) => {
       const method = init?.method ?? 'GET';
 
+      if (method === 'GET' && url.includes('/workflows')) {
+        return createMockFetchResponse({
+          items: [
+            {
+              id: 'workflow-api-1',
+              name: 'wf-1',
+              created_at: '2024-01-01T00:00:00Z',
+            },
+          ],
+          total: 1,
+        });
+      }
       if (method === 'GET' && url.includes('search-stores')) {
         return createMockFetchResponse({
           items: [
@@ -70,27 +118,12 @@ describe('useFileUploadWrapper handleFilesSelected', () => {
           total: 1,
         });
       }
-      if (method === 'POST' && url.includes('/files')) {
-        return createMockFetchResponse([{ id: 'remote-1' }]);
-      }
-      if (method === 'POST' && url.includes('/workflows')) {
-        return createMockFetchResponse({ id: 'run-1' });
-      }
-      if (url.includes('/event-stream')) {
-        return createMockFetchResponse(null, 200).then((res) => ({
-          ...res,
-          body: new ReadableStream({
-            start(controller) {
-              controller.close();
-            },
-          }),
-        }));
-      }
       return createMockFetchResponse({});
     });
   });
 
-  afterEach(() => {
+  afterEach(async () => {
+    await settleAsyncUploads();
     vi.unstubAllGlobals();
   });
 
@@ -115,26 +148,31 @@ describe('useFileUploadWrapper handleFilesSelected', () => {
     const { handleFilesSelected } = provider.useDocumentUpload('conv-1');
 
     const onFilesExceeded = vi.fn();
-    const event = makeInputEvent([createFile('a.pdf'), createFile('b.pdf')]);
+    const files = [createFile('a.pdf'), createFile('b.pdf')];
+    const event = makeInputEvent(files);
 
     handleFilesSelected(event, { onFilesExceeded });
 
     expect(onFilesExceeded).not.toHaveBeenCalled();
+    await settleAsyncUploads();
+    expect(uploadMock.upload).toHaveBeenCalledOnce();
+    expect(uploadMock.upload.mock.calls[0]?.[0].files).toEqual(files);
   });
 
-  it('truncates files to available slots and calls onFilesExceeded', () => {
+  it('truncates files to available slots and calls onFilesExceeded', async () => {
     const provider = createDocumentUploadProvider(
       buildConfig({ maxFilesPerUpload: 2 }),
     );
     const { handleFilesSelected } = provider.useDocumentUpload('conv-1');
 
     const onFilesExceeded = vi.fn();
-    const event = makeInputEvent([
+    const files = [
       createFile('a.pdf'),
       createFile('b.pdf'),
       createFile('c.pdf'),
       createFile('d.pdf'),
-    ]);
+    ];
+    const event = makeInputEvent(files);
 
     handleFilesSelected(event, { onFilesExceeded });
 
@@ -143,9 +181,13 @@ describe('useFileUploadWrapper handleFilesSelected', () => {
       allowed: 2,
       kept: 2,
     });
+    await settleAsyncUploads();
+    expect(uploadMock.upload.mock.calls[0]?.[0].files).toEqual(
+      files.slice(0, 2),
+    );
   });
 
-  it('resets input value after handling', () => {
+  it('resets input value after handling', async () => {
     const provider = createDocumentUploadProvider(
       buildConfig({ maxFilesPerUpload: 5 }),
     );
@@ -159,6 +201,7 @@ describe('useFileUploadWrapper handleFilesSelected', () => {
     handleFilesSelected(event);
 
     expect(valueSetter).toHaveBeenCalledWith('');
+    await settleAsyncUploads();
   });
 
   it('does not upload when no slots are available', async () => {
@@ -177,9 +220,12 @@ describe('useFileUploadWrapper handleFilesSelected', () => {
       allowed: 0,
       kept: 0,
     });
+    await settleAsyncUploads();
+    expect(uploadMock.upload).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
   });
 
-  it('does not call onFilesExceeded when exactly at the limit', () => {
+  it('does not call onFilesExceeded when exactly at the limit', async () => {
     const provider = createDocumentUploadProvider(
       buildConfig({ maxFilesPerUpload: 3 }),
     );
@@ -195,9 +241,11 @@ describe('useFileUploadWrapper handleFilesSelected', () => {
     handleFilesSelected(event, { onFilesExceeded });
 
     expect(onFilesExceeded).not.toHaveBeenCalled();
+    await settleAsyncUploads();
+    expect(uploadMock.upload).toHaveBeenCalledOnce();
   });
 
-  it('works without onFilesExceeded callback (no crash)', () => {
+  it('works without onFilesExceeded callback (no crash)', async () => {
     const provider = createDocumentUploadProvider(
       buildConfig({ maxFilesPerUpload: 1 }),
     );
@@ -206,5 +254,7 @@ describe('useFileUploadWrapper handleFilesSelected', () => {
     const event = makeInputEvent([createFile('a.pdf'), createFile('b.pdf')]);
 
     expect(() => handleFilesSelected(event)).not.toThrow();
+    await settleAsyncUploads();
+    expect(uploadMock.upload).toHaveBeenCalledOnce();
   });
 });

package/src/composables/fileUpload/useFileUploadWrapper.ts

@@ -13,6 +13,7 @@ import type {
   UploadEvent,
 } from './types';
 import { useFileUpload } from './useFileUpload';
+import { defaultEndpoints } from './types';
 
 function buildHttpClient(
   baseUrl: string,
@@ -176,11 +177,21 @@ export function createDocumentUploadProvider(
   };
 
   const httpClient = buildHttpClient(baseUrl, defaultHeaders);
+  const endpoints = defaultEndpoints;
 
   // ---- Search store resolution (one per user) ----
 
   let resolvedStoreId: string | null = null;
   let resolvePromise: Promise<string> | null = null;
+  const resolvedWorkflowIdByStore = new Map<string, string>();
+
+  async function createWorkflowForStore(storeId: string): Promise<string> {
+    const workflowRes = await httpClient.post<{ id: string }>(
+      endpoints.createWorkflow(storeId),
+      workflowConfig,
+    );
+    return workflowRes.id;
+  }
 
   async function createSearchStoreWithWorkflow(): Promise<string> {
     const name = `store-${new Date().toISOString().replace(/[:.]/g, '-')}`;
@@ -190,10 +201,8 @@ export function createDocumentUploadProvider(
     });
     const newStoreId = storeRes.id;
 
-    await httpClient.post(
-      `search-stores/${newStoreId}/workflows`,
-      workflowConfig,
-    );
+    const workflowApiId = await createWorkflowForStore(newStoreId);
+    resolvedWorkflowIdByStore.set(newStoreId, workflowApiId);
 
     return newStoreId;
   }
@@ -207,6 +216,35 @@ export function createDocumentUploadProvider(
     total: number;
   }
 
+  interface WorkflowListResponse {
+    items: Array<{
+      id: string;
+      name: string;
+      created_at: string;
+    }>;
+    total: number;
+  }
+
+  async function fetchOrCreateWorkflow(storeId: string): Promise<string> {
+    const cached = resolvedWorkflowIdByStore.get(storeId);
+    if (cached) return cached;
+
+    const response = await httpClient.get<WorkflowListResponse>(
+      endpoints.workflows(storeId),
+    );
+
+    if (response.items.length > 0) {
+      const match = response.items.find((item) => item.name === workflowId);
+      const selected = match ?? response.items[0]!;
+      resolvedWorkflowIdByStore.set(storeId, selected.id);
+      return selected.id;
+    }
+
+    const workflowApiId = await createWorkflowForStore(storeId);
+    resolvedWorkflowIdByStore.set(storeId, workflowApiId);
+    return workflowApiId;
+  }
+
   async function fetchOrCreateStore(): Promise<string> {
     try {
       const response =
@@ -308,7 +346,9 @@ export function createDocumentUploadProvider(
       if (!files.length) return;
 
       const userStoreId = await resolveSearchStore();
+      const workflowApiId = await fetchOrCreateWorkflow(userStoreId);
       upload.setStoreId(userStoreId);
+      upload.setWorkflowId(workflowApiId);
       storeId.value = userStoreId;
 
       const conversationId = toValue(conversationIdRef);

package/src/handlers/index.ts

@@ -1,5 +1,9 @@
 export { useMessageHandler } from './useMessageHandler';
 export { useMarkdownParser } from './useMarkdownParser';
+export {
+  remarkNormalizeMath,
+  normalizeMathDelimiters,
+} from '../helpers/unified/remarkNormalizeMath';
 export {
   provideChatKitLabels,
   useChatKitLabels,

package/src/handlers/useMarkdownParser.spec.ts

@@ -109,4 +109,69 @@ describe('useMarkdownParser', () => {
 
     expect(html.value).toBe('<p>Hello world</p>');
   });
+
+  it('renders inline math with single dollar signs', () => {
+    const source = ref('The formula $E = mc^2$ is famous.');
+    const { html } = useMarkdownParser(source, ref(undefined));
+
+    expect(html.value).toContain('class="katex"');
+    expect(html.value).toContain('E = mc^2');
+  });
+
+  it('renders display math with double dollar signs', () => {
+    const source = ref('$$\n\\int_0^1 x^2 dx\n$$');
+    const { html } = useMarkdownParser(source, ref(undefined));
+
+    expect(html.value).toContain('class="katex-display"');
+  });
+
+  it('preserves MathML elements through sanitization', () => {
+    const source = ref('$x^2$');
+    const { html } = useMarkdownParser(source, ref(undefined));
+
+    expect(html.value).toContain('<math');
+    expect(html.value).toContain('<semantics>');
+  });
+
+  it('does not treat a lone dollar sign as math', () => {
+    const source = ref('The price is $5.');
+    const { html } = useMarkdownParser(source, ref(undefined));
+
+    expect(html.value).not.toContain('class="katex"');
+    expect(html.value).toContain('$5');
+  });
+
+  it('promotes inline `$$...$$` to block math via the normalizer plugin', () => {
+    const source = ref('Inline before $$E=mc^2$$ inline after');
+    const { html } = useMarkdownParser(source, ref(undefined));
+
+    expect(html.value).toContain('class="katex-display"');
+    expect(html.value).toContain('E=mc^2');
+    expect(html.value).toContain('Inline before');
+    expect(html.value).toContain('inline after');
+  });
+
+  it('renders LaTeX-style `\\(...\\)` as inline math', () => {
+    const source = ref('The expression \\(a+b\\) is small.');
+    const { html } = useMarkdownParser(source, ref(undefined));
+
+    expect(html.value).toContain('class="katex"');
+    expect(html.value).not.toContain('class="katex-display"');
+  });
+
+  it('renders LaTeX-style `\\[...\\]` as block math', () => {
+    const source = ref('See \\[a+b\\] above.');
+    const { html } = useMarkdownParser(source, ref(undefined));
+
+    expect(html.value).toContain('class="katex-display"');
+  });
+
+  it('does not render `$$...$$` inside a fenced code block as math', () => {
+    const source = ref('```\n$$x$$\n```');
+    const { html } = useMarkdownParser(source, ref(undefined));
+
+    expect(html.value).not.toContain('class="katex"');
+    expect(html.value).toContain('<code>');
+    expect(html.value).toContain('$$x$$');
+  });
 });

package/src/handlers/useMarkdownParser.ts

@@ -2,18 +2,91 @@ import { computed, type MaybeRefOrGetter, toValue } from 'vue';
 import { unified, type PluggableList } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
+import remarkMath from 'remark-math';
 import remarkRehype from 'remark-rehype';
+import rehypeKatex from 'rehype-katex';
 import rehypeStringify from 'rehype-stringify';
-import DOMPurify from 'dompurify';
+import DOMPurify, { type Config } from 'dompurify';
+import 'katex/dist/katex.min.css';
+import { remarkNormalizeMath } from '../helpers/unified/remarkNormalizeMath';
 
 type SyncProcessor = { processSync: (value: string) => { toString(): string } };
 
+const KATEX_MATHML_TAGS = [
+  'math',
+  'semantics',
+  'annotation',
+  'mrow',
+  'mi',
+  'mo',
+  'mn',
+  'ms',
+  'mtext',
+  'mspace',
+  'msup',
+  'msub',
+  'msubsup',
+  'mfrac',
+  'mover',
+  'munder',
+  'munderover',
+  'msqrt',
+  'mroot',
+  'mtable',
+  'mtr',
+  'mtd',
+  'menclose',
+  'mpadded',
+  'mphantom',
+] as const;
+
+const KATEX_MATHML_ATTRS = [
+  'xmlns',
+  'encoding',
+  'mathvariant',
+  'displaystyle',
+  'scriptlevel',
+  'fence',
+  'separator',
+  'stretchy',
+  'symmetric',
+  'lspace',
+  'rspace',
+  'movablelimits',
+  'accent',
+  'accentunder',
+  'linethickness',
+  'columnalign',
+  'rowalign',
+  'columnspan',
+  'rowspan',
+  'width',
+  'height',
+  'depth',
+  'minsize',
+  'maxsize',
+  'aria-hidden',
+] as const;
+
+const SANITIZE_CONFIG: Config = {
+  ADD_TAGS: [...KATEX_MATHML_TAGS],
+  ADD_ATTR: [...KATEX_MATHML_ATTRS],
+};
+
 function buildProcessor(plugins: PluggableList): SyncProcessor {
-  let proc = unified().use(remarkParse).use(remarkGfm);
+  // `remarkNormalizeMath` wraps `this.parser`, so it must be registered after
+  // `remark-parse`. The wrap rewrites the markdown source before `remark-math`
+  // sees it, promoting single-line `$$…$$` and LaTeX `\(…\)` / `\[…\]` into
+  // delimiters that `remark-math` recognizes.
+  let proc = unified()
+    .use(remarkParse)
+    .use(remarkNormalizeMath)
+    .use(remarkGfm)
+    .use(remarkMath);
   for (const plugin of plugins) {
     proc = proc.use(plugin as any);
   }
-  return proc.use(remarkRehype).use(rehypeStringify);
+  return proc.use(remarkRehype).use(rehypeKatex).use(rehypeStringify);
 }
 
 export function useMarkdownParser(
@@ -30,16 +103,16 @@ export function useMarkdownParser(
     return cachedProcessor;
   }
 
-  const html = computed(() => {
+  const html = computed<string>(() => {
     const markdown = toValue(source);
     if (!markdown) return '';
     try {
       const raw = String(
         getProcessor(toValue(plugins) ?? []).processSync(markdown),
       );
-      return DOMPurify.sanitize(raw);
+      return DOMPurify.sanitize(raw, SANITIZE_CONFIG) as string;
     } catch {
-      return DOMPurify.sanitize(markdown);
+      return DOMPurify.sanitize(markdown, SANITIZE_CONFIG) as string;
     }
   });
 

package/src/helpers/unified/remarkNormalizeMath.spec.ts

@@ -0,0 +1,84 @@
+import { normalizeMathDelimiters } from '../../helpers/unified/remarkNormalizeMath';
+
+describe('normalizeMathDelimiters', () => {
+  it('returns an empty string for empty input', () => {
+    expect(normalizeMathDelimiters('')).toBe('');
+  });
+
+  it('leaves text without math untouched', () => {
+    const input = 'Hello world, nothing to see here.';
+    expect(normalizeMathDelimiters(input)).toBe(input);
+  });
+
+  it('promotes inline `$$...$$` to a block math fence', () => {
+    const out = normalizeMathDelimiters('before $$E=mc^2$$ after');
+    expect(out).toBe('before \n\n$$\nE=mc^2\n$$\n\n after');
+  });
+
+  it('promotes multiple inline `$$...$$` occurrences on the same line', () => {
+    const out = normalizeMathDelimiters('$$a$$ and $$b$$');
+    expect(out).toBe('\n\n$$\na\n$$\n\n and \n\n$$\nb\n$$\n\n');
+  });
+
+  it('leaves a properly fenced multi-line block math expression unchanged', () => {
+    const input = '$$\n\\int_0^1 x^2 dx\n$$';
+    expect(normalizeMathDelimiters(input)).toBe(input);
+  });
+
+  it('converts LaTeX-style `\\(...\\)` to inline math', () => {
+    const out = normalizeMathDelimiters('The expression \\(a+b\\) is small.');
+    expect(out).toBe('The expression $a+b$ is small.');
+  });
+
+  it('converts LaTeX-style `\\[...\\]` to a block math fence', () => {
+    const out = normalizeMathDelimiters('See \\[a+b\\] above.');
+    expect(out).toBe('See \n\n$$\na+b\n$$\n\n above.');
+  });
+
+  it('handles multi-line `\\[...\\]` bodies', () => {
+    const out = normalizeMathDelimiters('\\[\n a+b \n\\]');
+    expect(out).toBe('\n\n$$\na+b\n$$\n\n');
+  });
+
+  it('does not transform `$$...$$` inside a fenced code block', () => {
+    const input = '```\n$$x$$\n```';
+    expect(normalizeMathDelimiters(input)).toBe(input);
+  });
+
+  it('does not transform `$$...$$` inside a tilde-fenced code block', () => {
+    const input = '~~~\n$$x$$\n~~~';
+    expect(normalizeMathDelimiters(input)).toBe(input);
+  });
+
+  it('does not transform `$$...$$` inside an inline code span', () => {
+    const input = 'see `$$x$$` here';
+    expect(normalizeMathDelimiters(input)).toBe(input);
+  });
+
+  it('does not transform LaTeX delimiters inside a fenced code block', () => {
+    const input = '```\nuse \\(x\\) and \\[y\\] verbatim\n```';
+    expect(normalizeMathDelimiters(input)).toBe(input);
+  });
+
+  it('still transforms math outside the code block when both coexist', () => {
+    const input = '```\n$$inside$$\n```\noutside $$x$$ after';
+    const out = normalizeMathDelimiters(input);
+    expect(out).toContain('```\n$$inside$$\n```');
+    expect(out).toContain('\n\n$$\nx\n$$\n\n');
+  });
+
+  it('leaves a lone dollar sign alone', () => {
+    const input = 'The price is $5.';
+    expect(normalizeMathDelimiters(input)).toBe(input);
+  });
+
+  it('leaves two unrelated dollar amounts alone', () => {
+    const input = 'It costs $5 and $10 in total.';
+    expect(normalizeMathDelimiters(input)).toBe(input);
+  });
+
+  it('trims internal whitespace inside transformed `$$...$$`', () => {
+    const out = normalizeMathDelimiters('$$  x + y  $$');
+    expect(out).toBe('\n\n$$\nx + y\n$$\n\n');
+  });
+});

package/src/helpers/unified/remarkNormalizeMath.ts

@@ -0,0 +1,134 @@
+import type { Plugin } from 'unified';
+
+const PLACEHOLDER_PREFIX = '\uE000PH_';
+const PLACEHOLDER_SUFFIX = '\uE000';
+const PLACEHOLDER_RE = /\uE000PH_(\d+)\uE000/g;
+
+const FENCE_START_RE = /^[ \t]{0,3}(`{3,}|~{3,})/;
+const INLINE_CODE_RE = /`[^`\n]+`/g;
+
+const LATEX_BLOCK_RE = /\\\[([\s\S]+?)\\\]/g;
+const LATEX_INLINE_RE = /\\\(([^\n]+?)\\\)/g;
+const SINGLE_LINE_DOUBLE_DOLLAR_RE = /\$\$([^\n$]+?)\$\$/g;
+
+type Stash = (value: string) => string;
+
+function isClosingFence(
+  line: string,
+  fenceChar: string,
+  minLen: number,
+): boolean {
+  let i = 0;
+  let indent = 0;
+  while (
+    i < line.length &&
+    (line[i] === ' ' || line[i] === '\t') &&
+    indent < 4
+  ) {
+    indent++;
+    i++;
+  }
+  if (indent >= 4) return false;
+  let runLen = 0;
+  while (i < line.length && line[i] === fenceChar) {
+    runLen++;
+    i++;
+  }
+  if (runLen < minLen) return false;
+  while (i < line.length) {
+    if (line[i] !== ' ' && line[i] !== '\t') return false;
+    i++;
+  }
+  return true;
+}
+
+/**
+ * Walk the source line-by-line and stash fenced code blocks (```/~~~) so
+ * their contents are not rewritten by subsequent math regexes. A line-based
+ * scanner avoids the catastrophic-backtracking risk of a single regex over the
+ * whole document.
+ */
+function protectFencedCode(input: string, stash: Stash): string {
+  const lines = input.split('\n');
+  const out: string[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const match = FENCE_START_RE.exec(lines[i]);
+    if (match) {
+      const fence = match[1];
+      const fenceChar = fence[0];
+      const minLen = fence.length;
+      const block: string[] = [lines[i]];
+      i++;
+      while (i < lines.length) {
+        const current = lines[i];
+        block.push(current);
+        i++;
+        if (isClosingFence(current, fenceChar, minLen)) break;
+      }
+      out.push(stash(block.join('\n')));
+    } else {
+      out.push(lines[i]);
+      i++;
+    }
+  }
+  return out.join('\n');
+}
+
+/**
+ * Normalize math delimiters in a markdown source string so they survive
+ * `remark-math`'s CommonMark-style parsing:
+ *
+ * - LaTeX-style block delimiters `\[ ... \]` become a fenced `$$ ... $$` block.
+ * - LaTeX-style inline delimiters `\( ... \)` become inline `$ ... $`.
+ * - Single-line `$$ ... $$` (which `remark-math` treats as inline math)
+ *   is promoted to a proper block math fence on its own lines.
+ *
+ * Content inside fenced (``` / ~~~) or inline (`) code spans is preserved
+ * verbatim and is not subject to any of these rewrites.
+ */
+export function normalizeMathDelimiters(input: string): string {
+  if (!input) return input;
+
+  const placeholders: string[] = [];
+  const stash: Stash = (value) => {
+    const id = placeholders.length;
+    placeholders.push(value);
+    return `${PLACEHOLDER_PREFIX}${id}${PLACEHOLDER_SUFFIX}`;
+  };
+
+  let s = protectFencedCode(input, stash);
+  s = s.replace(INLINE_CODE_RE, stash);
+
+  s = s.replace(
+    LATEX_BLOCK_RE,
+    (_m, body: string) => `\n\n$$\n${body.trim()}\n$$\n\n`,
+  );
+  s = s.replace(LATEX_INLINE_RE, (_m, body: string) => `$${body.trim()}$`);
+  s = s.replace(
+    SINGLE_LINE_DOUBLE_DOLLAR_RE,
+    (_m, body: string) => `\n\n$$\n${body.trim()}\n$$\n\n`,
+  );
+
+  s = s.replace(PLACEHOLDER_RE, (_m, id: string) => placeholders[Number(id)]);
+  return s;
+}
+
+type ParserLike = (document: string, file: unknown) => unknown;
+
+/**
+ * Unified plugin that wraps `this.parser` so the markdown source is run
+ * through {@link normalizeMathDelimiters} before parsing.
+ *
+ * Register this plugin *after* `remark-parse`, otherwise `this.parser` is not
+ * yet defined when the plugin is invoked at freeze time and the wrap is a
+ * no-op.
+ */
+export const remarkNormalizeMath: Plugin<[]> = function () {
+  const processor = this as unknown as { parser?: ParserLike };
+  const originalParser = processor.parser;
+  if (typeof originalParser !== 'function') return;
+
+  processor.parser = (document, file) =>
+    originalParser(normalizeMathDelimiters(document), file);
+};