@vertesia/ui 1.5.0-dev.20260806.125520Z → 1.5.0-dev.20260826.064249Z

package/src/shell/apps/IframeAppContextSync.tsx

@@ -0,0 +1,101 @@
+import { useEffect } from 'react';
+import { useTheme } from '../../core/components/shadcn/theme/ThemeProvider.js';
+import { useLanguage } from '../../i18n/LanguageProvider.js';
+import {
+    IFRAME_APP_CONTEXT_REQUEST,
+    IFRAME_APP_HOST_ORIGIN_PARAM,
+    IFRAME_APP_LOCATION_CHANGE,
+    type IframeAppContextRequest,
+    type IframeAppLocationChange,
+    isIframeAppContext,
+    isIframeAppNavigate,
+    resolveIframeHostOrigin,
+} from './iframe-auth.js';
+
+function preserveIframeHostOrigin(url: string | URL | null | undefined): string | URL | null | undefined {
+    if (url === null || url === undefined) return url;
+    const hostOrigin = new URL(window.location.href).searchParams.get(IFRAME_APP_HOST_ORIGIN_PARAM);
+    if (!hostOrigin) return url;
+
+    try {
+        const target = new URL(url, window.location.href);
+        if (target.origin !== window.location.origin) return url;
+        target.searchParams.set(IFRAME_APP_HOST_ORIGIN_PARAM, hostOrigin);
+        return target;
+    } catch {
+        return url;
+    }
+}
+
+/** Applies context and navigation supplied by an embedding Studio without changing standalone preferences. */
+export function IframeAppContextSync() {
+    const { setTheme } = useTheme();
+    const { setLanguage } = useLanguage();
+
+    useEffect(() => {
+        const parentOrigin = resolveIframeHostOrigin();
+        if (!parentOrigin) return;
+
+        const reportLocation = () => {
+            const message = {
+                type: IFRAME_APP_LOCATION_CHANGE,
+                url: window.location.href,
+            } satisfies IframeAppLocationChange;
+            window.parent.postMessage(message, parentOrigin);
+        };
+
+        const originalPushState = window.history.pushState;
+        const originalReplaceState = window.history.replaceState;
+        const pushState: History['pushState'] = (data, unused, url) => {
+            originalPushState.call(window.history, data, unused, preserveIframeHostOrigin(url));
+            reportLocation();
+        };
+        const replaceState: History['replaceState'] = (data, unused, url) => {
+            originalReplaceState.call(window.history, data, unused, preserveIframeHostOrigin(url));
+            reportLocation();
+        };
+        window.history.pushState = pushState;
+        window.history.replaceState = replaceState;
+
+        const onMessage = (event: MessageEvent<unknown>) => {
+            if (event.source !== window.parent || event.origin !== parentOrigin) return;
+            if (isIframeAppContext(event.data)) {
+                const context = event.data;
+                setTheme(context.theme, { persist: false });
+                setLanguage(context.language, { persist: false });
+                return;
+            }
+            if (isIframeAppNavigate(event.data)) {
+                let target: URL;
+                try {
+                    target = new URL(event.data.url, window.location.href);
+                } catch {
+                    return;
+                }
+                if (target.origin !== window.location.origin) return;
+                if (target.href === window.location.href) {
+                    // Acknowledge no-op navigation so the host does not wait forever and suppress later app routing.
+                    reportLocation();
+                    return;
+                }
+                window.history.replaceState(window.history.state, '', target);
+                window.dispatchEvent(new PopStateEvent('popstate', { state: window.history.state }));
+            }
+        };
+        const request = { type: IFRAME_APP_CONTEXT_REQUEST } satisfies IframeAppContextRequest;
+        window.addEventListener('message', onMessage);
+        window.addEventListener('popstate', reportLocation);
+        window.addEventListener('hashchange', reportLocation);
+        window.parent.postMessage(request, parentOrigin);
+        reportLocation();
+        return () => {
+            window.removeEventListener('message', onMessage);
+            window.removeEventListener('popstate', reportLocation);
+            window.removeEventListener('hashchange', reportLocation);
+            if (window.history.pushState === pushState) window.history.pushState = originalPushState;
+            if (window.history.replaceState === replaceState) window.history.replaceState = originalReplaceState;
+        };
+    }, [setLanguage, setTheme]);
+
+    return null;
+}

package/src/shell/apps/iframe-auth.test.ts

@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+    IFRAME_APP_HOST_ORIGIN_PARAM,
+    IFRAME_AUTH_REQUEST,
+    IFRAME_AUTH_RESPONSE,
+    requestIframeHostAuthToken,
+    resolveIframeHostOrigin,
+} from './iframe-auth.js';
+
+const originalParent = Object.getOwnPropertyDescriptor(window, 'parent');
+const originalReferrer = Object.getOwnPropertyDescriptor(document, 'referrer');
+
+afterEach(() => {
+    window.history.replaceState(null, '', '/');
+    window.sessionStorage.clear();
+    if (originalParent) Object.defineProperty(window, 'parent', originalParent);
+    else Reflect.deleteProperty(window, 'parent');
+    if (originalReferrer) Object.defineProperty(document, 'referrer', originalReferrer);
+    else Reflect.deleteProperty(document, 'referrer');
+});
+
+describe('iframe host authentication', () => {
+    it('resolves an explicit trusted host origin', () => {
+        const parentWindow = { postMessage: () => undefined } as unknown as Window;
+        Object.defineProperty(window, 'parent', { configurable: true, value: parentWindow });
+        window.history.replaceState(null, '', `/?${IFRAME_APP_HOST_ORIGIN_PARAM}=https%3A%2F%2Fcloud.vertesia.io`);
+
+        expect(resolveIframeHostOrigin()).toBe('https://cloud.vertesia.io');
+    });
+
+    it('accepts a branch Studio UI origin', () => {
+        const parentWindow = { postMessage: () => undefined } as unknown as Window;
+        Object.defineProperty(window, 'parent', { configurable: true, value: parentWindow });
+        window.history.replaceState(
+            null,
+            '',
+            `/?${IFRAME_APP_HOST_ORIGIN_PARAM}=https%3A%2F%2Fdev-feat-iframe.ui.dev1.vertesia.io`,
+        );
+
+        expect(resolveIframeHostOrigin()).toBe('https://dev-feat-iframe.ui.dev1.vertesia.io');
+    });
+
+    it('rejects untrusted query and referrer origins', () => {
+        const parentWindow = { postMessage: () => undefined } as unknown as Window;
+        Object.defineProperty(window, 'parent', { configurable: true, value: parentWindow });
+        window.history.replaceState(null, '', `/?${IFRAME_APP_HOST_ORIGIN_PARAM}=https%3A%2F%2Fevil.example.com`);
+        Object.defineProperty(document, 'referrer', {
+            configurable: true,
+            value: 'https://referrer.example.com/embed',
+        });
+
+        expect(resolveIframeHostOrigin()).toBeUndefined();
+    });
+
+    it('rejects a shared Vertesia app-gateway origin', () => {
+        const parentWindow = { postMessage: () => undefined } as unknown as Window;
+        Object.defineProperty(window, 'parent', { configurable: true, value: parentWindow });
+        window.history.replaceState(null, '', `/?${IFRAME_APP_HOST_ORIGIN_PARAM}=https%3A%2F%2Fapps.dev1.vertesia.io`);
+
+        expect(resolveIframeHostOrigin()).toBeUndefined();
+    });
+
+    it('rejects an origin containing embedded credentials', () => {
+        const parentWindow = { postMessage: () => undefined } as unknown as Window;
+        Object.defineProperty(window, 'parent', { configurable: true, value: parentWindow });
+        window.history.replaceState(
+            null,
+            '',
+            `/?${IFRAME_APP_HOST_ORIGIN_PARAM}=https%3A%2F%2Fuser%3Asecret%40cloud.vertesia.io`,
+        );
+
+        expect(resolveIframeHostOrigin()).toBeUndefined();
+    });
+
+    it('accepts a loopback host for a loopback child app', () => {
+        const parentWindow = { postMessage: () => undefined } as unknown as Window;
+        Object.defineProperty(window, 'parent', { configurable: true, value: parentWindow });
+        window.history.replaceState(null, '', `/?${IFRAME_APP_HOST_ORIGIN_PARAM}=http%3A%2F%2Flocalhost%3A5173`);
+
+        expect(resolveIframeHostOrigin()).toBe('http://localhost:5173');
+    });
+
+    it('ignores an empty early response and waits for a usable host token', async () => {
+        const requests: unknown[] = [];
+        const parentWindow = { postMessage: (message: unknown) => requests.push(message) } as unknown as Window;
+        Object.defineProperty(window, 'parent', { configurable: true, value: parentWindow });
+        window.history.replaceState(null, '', `/?${IFRAME_APP_HOST_ORIGIN_PARAM}=https%3A%2F%2Fcloud.vertesia.io`);
+
+        let settled = false;
+        const tokenPromise = requestIframeHostAuthToken().then((token) => {
+            settled = true;
+            return token;
+        });
+        const request = requests[0] as { type: string; requestId: string };
+        expect(request.type).toBe(IFRAME_AUTH_REQUEST);
+
+        window.dispatchEvent(
+            new MessageEvent('message', {
+                data: { type: IFRAME_AUTH_RESPONSE, requestId: request.requestId },
+                origin: 'https://cloud.vertesia.io',
+                source: parentWindow,
+            }),
+        );
+        await Promise.resolve();
+        expect(settled).toBe(false);
+
+        window.dispatchEvent(
+            new MessageEvent('message', {
+                data: { type: IFRAME_AUTH_RESPONSE, requestId: request.requestId, token: 'fresh-token' },
+                origin: 'https://cloud.vertesia.io',
+                source: parentWindow,
+            }),
+        );
+        await expect(tokenPromise).resolves.toBe('fresh-token');
+    });
+});

package/src/shell/apps/iframe-auth.ts

@@ -0,0 +1,193 @@
+import { SUPPORTED_LANGUAGES, type SupportedLanguage } from '../../i18n/rtl.js';
+
+export const IFRAME_AUTH_REQUEST = 'vertesia:iframe-auth-request';
+export const IFRAME_AUTH_RESPONSE = 'vertesia:iframe-auth-response';
+export const IFRAME_APP_CONTEXT_REQUEST = 'vertesia:iframe-context-request';
+export const IFRAME_APP_CONTEXT = 'vertesia:iframe-context';
+export const IFRAME_APP_NAVIGATE = 'vertesia:iframe-navigate';
+export const IFRAME_APP_LOCATION_CHANGE = 'vertesia:iframe-location-change';
+export const IFRAME_APP_SLOT_PARAM = '__vertesia_slot';
+export const IFRAME_APP_HOST_ORIGIN_PARAM = '__vertesia_host_origin';
+export const IFRAME_APP_CONTENT_SLOT = 'content';
+
+export interface IframeAuthRequest {
+    type: typeof IFRAME_AUTH_REQUEST;
+    requestId: string;
+}
+
+export interface IframeAuthResponse {
+    type: typeof IFRAME_AUTH_RESPONSE;
+    requestId: string;
+    token?: string;
+}
+
+export interface IframeAppContextRequest {
+    type: typeof IFRAME_APP_CONTEXT_REQUEST;
+}
+
+export interface IframeAppContext {
+    type: typeof IFRAME_APP_CONTEXT;
+    theme: 'dark' | 'light' | 'system';
+    language: SupportedLanguage;
+}
+
+export interface IframeAppNavigate {
+    type: typeof IFRAME_APP_NAVIGATE;
+    url: string;
+}
+
+export interface IframeAppLocationChange {
+    type: typeof IFRAME_APP_LOCATION_CHANGE;
+    url: string;
+}
+
+export function isIframeAuthRequest(value: unknown): value is IframeAuthRequest {
+    if (!value || typeof value !== 'object') return false;
+    const message = value as Partial<IframeAuthRequest>;
+    return message.type === IFRAME_AUTH_REQUEST && typeof message.requestId === 'string' && !!message.requestId;
+}
+
+export function isIframeAuthResponse(value: unknown): value is IframeAuthResponse {
+    if (!value || typeof value !== 'object') return false;
+    const message = value as Partial<IframeAuthResponse>;
+    return (
+        message.type === IFRAME_AUTH_RESPONSE &&
+        typeof message.requestId === 'string' &&
+        !!message.requestId &&
+        (message.token === undefined || typeof message.token === 'string')
+    );
+}
+
+export function isIframeAppContextRequest(value: unknown): value is IframeAppContextRequest {
+    if (!value || typeof value !== 'object') return false;
+    return (value as Partial<IframeAppContextRequest>).type === IFRAME_APP_CONTEXT_REQUEST;
+}
+
+export function isIframeAppContext(value: unknown): value is IframeAppContext {
+    if (!value || typeof value !== 'object') return false;
+    const message = value as Partial<IframeAppContext>;
+    return (
+        message.type === IFRAME_APP_CONTEXT &&
+        (message.theme === 'dark' || message.theme === 'light' || message.theme === 'system') &&
+        typeof message.language === 'string' &&
+        (SUPPORTED_LANGUAGES as readonly string[]).includes(message.language)
+    );
+}
+
+export function isIframeAppNavigate(value: unknown): value is IframeAppNavigate {
+    if (!value || typeof value !== 'object') return false;
+    const message = value as Partial<IframeAppNavigate>;
+    return message.type === IFRAME_APP_NAVIGATE && typeof message.url === 'string' && !!message.url;
+}
+
+export function isIframeAppLocationChange(value: unknown): value is IframeAppLocationChange {
+    if (!value || typeof value !== 'object') return false;
+    const message = value as Partial<IframeAppLocationChange>;
+    return message.type === IFRAME_APP_LOCATION_CHANGE && typeof message.url === 'string' && !!message.url;
+}
+
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+function parseHttpOrigin(value: string | null | undefined): URL | undefined {
+    if (!value) return undefined;
+    try {
+        const url = new URL(value);
+        const isLoopback = LOOPBACK_HOSTS.has(url.hostname);
+        return url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback) ? url : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+function hasEmbeddedCredentials(value: string | null | undefined): boolean {
+    if (!value) return false;
+    const normalized = value.trim();
+    const schemeEnd = normalized.indexOf('://');
+    if (schemeEnd < 0) return false;
+
+    const authorityStart = schemeEnd + 3;
+    const authoritySuffix = normalized.slice(authorityStart);
+    const authorityEnd = authoritySuffix.search(/[/?#]/);
+    const authority = authorityEnd < 0 ? authoritySuffix : authoritySuffix.slice(0, authorityEnd);
+    return authority.includes('@');
+}
+
+function isVertesiaStudioHost(host: string): boolean {
+    if (host === 'studio.vertesia.io') return true;
+
+    const labels = host.split('.');
+    if (labels.at(-2) !== 'vertesia' || labels.at(-1) !== 'io') return false;
+
+    const platformLabels = labels.slice(0, -2);
+    const cloudIndex = platformLabels.lastIndexOf('cloud');
+    if (cloudIndex >= 0 && platformLabels.length - cloudIndex <= 2) return true;
+
+    const uiIndex = platformLabels.lastIndexOf('ui');
+    return uiIndex >= 0 && platformLabels.length - uiIndex === 2;
+}
+
+function parseTrustedIframeHostOrigin(value: string | null | undefined): string | undefined {
+    if (hasEmbeddedCredentials(value)) return undefined;
+    const url = parseHttpOrigin(value);
+    if (!url) return undefined;
+
+    const host = url.hostname;
+    const isStudioHost = isVertesiaStudioHost(host);
+    const isLocalDevelopment = LOOPBACK_HOSTS.has(host) && LOOPBACK_HOSTS.has(window.location.hostname);
+    return (url.protocol === 'https:' && isStudioHost) || isLocalDevelopment ? url.origin : undefined;
+}
+
+/**
+ * Resolve a trusted embedding Studio origin without relying on referrer surviving a reload or auth redirect.
+ * The URL value is a continuity hint rather than a trust anchor: only Studio UI host patterns are accepted, and
+ * loopback parents are accepted only when the child app is also running on loopback.
+ */
+export function resolveIframeHostOrigin(): string | undefined {
+    if (window.parent === window) return undefined;
+
+    const explicitOrigin = parseTrustedIframeHostOrigin(
+        new URL(window.location.href).searchParams.get(IFRAME_APP_HOST_ORIGIN_PARAM),
+    );
+    if (explicitOrigin) return explicitOrigin;
+
+    return parseTrustedIframeHostOrigin(document.referrer);
+}
+
+/**
+ * Ask an embedding Studio window for a fresh Vertesia token. Both sides validate the request nonce,
+ * source window, and exact origin. The explicit host-origin parameter survives framed redirects and
+ * hard navigations; referrer remains a compatibility fallback for older hosts.
+ * Standalone/top-level apps return undefined and continue through the normal sign-in flow.
+ */
+export function requestIframeHostAuthToken(timeoutMs = 5000): Promise<string | undefined> {
+    const parentOrigin = resolveIframeHostOrigin();
+    if (!parentOrigin) return Promise.resolve(undefined);
+
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve) => {
+        let timeout: number;
+        let retry: number;
+        let retryDelay = 250;
+        const finish = (token?: string) => {
+            window.removeEventListener('message', onMessage);
+            clearTimeout(timeout);
+            clearTimeout(retry);
+            resolve(token);
+        };
+        const onMessage = (event: MessageEvent<unknown>) => {
+            if (event.source !== window.parent || event.origin !== parentOrigin || !isIframeAuthResponse(event.data)) {
+                return;
+            }
+            if (event.data.requestId === requestId && event.data.token) finish(event.data.token);
+        };
+        const request = { type: IFRAME_AUTH_REQUEST, requestId } satisfies IframeAuthRequest;
+        const sendRequest = () => {
+            window.parent.postMessage(request, parentOrigin);
+            retry = window.setTimeout(sendRequest, retryDelay);
+            retryDelay = Math.min(retryDelay * 2, 1000);
+        };
+        timeout = window.setTimeout(() => finish(), timeoutMs);
+        window.addEventListener('message', onMessage);
+        sendRequest();
+    });
+}

package/src/shell/apps/index.ts

@@ -1,3 +1,5 @@
 export * from './AppInstallationProvider';
 export * from './AppProjectSelector';
+export * from './IframeAppContextSync';
+export * from './iframe-auth';
 export * from './StandaloneApp';

package/src/widgets/markdown/ArtifactEditingSurface.test.tsx

@@ -44,6 +44,7 @@ function renderSurface(props?: {
     onSendChangesToAgent?: () => void;
     hasUnsentChanges?: boolean;
     toolbarStatus?: React.ReactNode;
+    onContentChange?: (content: string, generation?: string) => void;
     flushChangesRef?: React.MutableRefObject<(() => Promise<false | ArtifactEditingSurfaceDocumentEdit>) | null>;
 }) {
     return render(
@@ -61,6 +62,7 @@ function renderSurface(props?: {
                 onSendChangesToAgent={props?.onSendChangesToAgent}
                 hasUnsentChanges={props?.hasUnsentChanges}
                 toolbarStatus={props?.toolbarStatus}
+                onContentChange={props?.onContentChange}
                 flushChangesRef={props?.flushChangesRef}
             />
         </I18nProvider>,
@@ -292,6 +294,7 @@ describe('ArtifactEditingSurface', () => {
 
     it('rebases focused full-document edits over a non-overlapping agent change after 412', async () => {
         const user = userEvent.setup();
+        const onContentChange = vi.fn();
         const baseContent = 'First paragraph.\n\nSecond paragraph.';
         const remoteContent = 'First paragraph updated remotely.\n\nSecond paragraph.';
         mocks.getArtifactContent
@@ -314,16 +317,22 @@ describe('ArtifactEditingSurface', () => {
             .mockRejectedValueOnce({ status: 412 })
             .mockResolvedValueOnce({ path: 'drafts/document.md', generation: 'generation-merged' });
 
-        const view = renderSurface({ viewMode: 'document' });
+        const view = renderSurface({ viewMode: 'document', onContentChange });
         const editor = await screen.findByRole('textbox', { name: 'Markdown document editor' }, LAZY_EDITOR_WAIT);
         await user.click(editor);
 
         view.rerender(
             <I18nProvider lng="en">
-                <ArtifactEditingSurface runId="run-1" path="drafts/document.md" refreshKey={1} viewMode="document" />
+                <ArtifactEditingSurface
+                    runId="run-1"
+                    path="drafts/document.md"
+                    refreshKey={1}
+                    viewMode="document"
+                    onContentChange={onContentChange}
+                />
             </I18nProvider>,
         );
-        await waitFor(() => expect(mocks.getArtifactContent).toHaveBeenCalledTimes(2));
+        await waitFor(() => expect(onContentChange).toHaveBeenCalledWith(remoteContent, 'generation-agent'));
 
         editor.focus();
         const secondParagraphText = editor.querySelectorAll('p')[1]?.firstChild;

package/src/widgets/markdown/MarkdownRenderer.tsx

@@ -1,7 +1,6 @@
 import type { Element } from 'hast';
 import React from 'react';
 import Markdown, { type Components, defaultUrlTransform } from 'react-markdown';
-import rehypeKatex from 'rehype-katex';
 import { defListHastHandlers, remarkDefinitionList } from 'remark-definition-list';
 import remarkDirective from 'remark-directive';
 import remarkGfm from 'remark-gfm';
@@ -24,6 +23,55 @@ type MarkdownTree = Parameters<typeof visit>[0];
 type MarkdownNode = { value?: unknown };
 type MarkdownParent = { children?: unknown[] };
 type RemarkPluginList = NonNullable<React.ComponentProps<typeof Markdown>['remarkPlugins']>;
+type RehypePluginList = NonNullable<React.ComponentProps<typeof Markdown>['rehypePlugins']>;
+type RehypePlugin = RehypePluginList[number];
+
+// A `$` that the math preprocessor left unescaped — the only way remark-math can produce a math
+// node. Currency is escaped to `\$` by `preprocessMathDelimiters`, so it does not match.
+const MATH_DELIMITER_REGEX = /(?:^|[^\\])\$/;
+const NO_REHYPE_PLUGINS: RehypePluginList = [];
+
+let rehypeKatex: RehypePlugin | undefined;
+let rehypeKatexPromise: Promise<RehypePlugin> | undefined;
+
+function loadRehypeKatex(): Promise<RehypePlugin> {
+    if (!rehypeKatexPromise) {
+        rehypeKatexPromise = import('rehype-katex').then(({ default: plugin }) => {
+            rehypeKatex = plugin;
+            return plugin;
+        });
+    }
+    return rehypeKatexPromise;
+}
+
+/**
+ * KaTeX is ~250 KB and most markdown has no math in it, so it is fetched the first time a document
+ * containing math delimiters is rendered. Until it resolves, math renders unstyled; once loaded it
+ * stays loaded for the rest of the session and later renderers pick it up without a second pass.
+ */
+function useRehypePlugins(markdown: string): RehypePluginList {
+    const hasMath = React.useMemo(() => MATH_DELIMITER_REGEX.test(markdown), [markdown]);
+    const [plugin, setPlugin] = React.useState(() => rehypeKatex);
+
+    React.useEffect(() => {
+        if (!hasMath || plugin) return;
+        let cancelled = false;
+        loadRehypeKatex()
+            .then((loaded) => {
+                if (!cancelled) {
+                    setPlugin(() => loaded);
+                }
+            })
+            .catch((err: unknown) => {
+                console.error('Failed to load KaTeX; math will render unstyled', err);
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, [hasMath, plugin]);
+
+    return React.useMemo(() => (plugin ? [plugin] : NO_REHYPE_PLUGINS), [plugin]);
+}
 
 // Custom URL schemes that we handle in our components
 const ALLOWED_CUSTOM_SCHEMES = [
@@ -151,7 +199,7 @@ export function MarkdownRenderer({
     }, [remarkPlugins, removeComments]);
 
     // Rehype plugins (HTML processing, including KaTeX for math)
-    const rehypePluginsArray = React.useMemo(() => [rehypeKatex], []);
+    const rehypePluginsArray = useRehypePlugins(normalizedMarkdown);
 
     // Remark-rehype bridge options (custom AST handlers for definition lists)
     const remarkRehypeOptions = React.useMemo(

package/src/widgets/markdown/MermaidDiagram.tsx

@@ -1,6 +1,7 @@
-import mermaid from 'mermaid';
 import { useEffect, useId, useRef, useState } from 'react';
 
+type Mermaid = typeof import('mermaid').default;
+
 const MERMAID_FONT_FAMILY =
     'Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif';
 
@@ -78,27 +79,41 @@ export function makeSvgResponsive(svg: string): string {
     });
 }
 
-// Initialize mermaid with a browser-focused config close to Mermaid Playground defaults.
-mermaid.initialize({
-    startOnLoad: false,
-    theme: 'default',
-    securityLevel: 'loose',
-    fontFamily: MERMAID_FONT_FAMILY,
-    suppressErrorRendering: true,
-    flowchart: {
-        htmlLabels: true,
-        useMaxWidth: true,
-        nodeSpacing: 40,
-        rankSpacing: 50,
-        padding: 12,
-    },
-    sequence: {
-        useMaxWidth: true,
-    },
-    themeVariables: {
-        fontFamily: MERMAID_FONT_FAMILY,
-    },
-});
+let mermaidPromise: Promise<Mermaid> | undefined;
+
+/**
+ * Load Mermaid on first render of a diagram, initialized with a browser-focused config close to
+ * Mermaid Playground defaults. Mermaid is several hundred KB and most pages never render a diagram,
+ * so it is imported dynamically to keep it out of the eager bundle of every consuming app.
+ */
+function loadMermaid(): Promise<Mermaid> {
+    if (!mermaidPromise) {
+        mermaidPromise = import('mermaid').then(({ default: mermaid }) => {
+            mermaid.initialize({
+                startOnLoad: false,
+                theme: 'default',
+                securityLevel: 'loose',
+                fontFamily: MERMAID_FONT_FAMILY,
+                suppressErrorRendering: true,
+                flowchart: {
+                    htmlLabels: true,
+                    useMaxWidth: true,
+                    nodeSpacing: 40,
+                    rankSpacing: 50,
+                    padding: 12,
+                },
+                sequence: {
+                    useMaxWidth: true,
+                },
+                themeVariables: {
+                    fontFamily: MERMAID_FONT_FAMILY,
+                },
+            });
+            return mermaid;
+        });
+    }
+    return mermaidPromise;
+}
 
 export interface MermaidDiagramProps {
     /** The mermaid diagram code */
@@ -147,6 +162,7 @@ export function MermaidDiagram({ code, className }: MermaidDiagramProps) {
                 const normalizedCode = normalizeMermaidCodeForBrowser(code);
 
                 // Render the diagram
+                const mermaid = await loadMermaid();
                 const { svg: renderedSvg } = await mermaid.render(id, normalizedCode);
                 const responsiveSvg = makeSvgResponsive(renderedSvg);