@vertesia/ui 1.5.0 → 1.6.0-dev.20260918.061604Z

package/src/boot/index.test.ts

@@ -0,0 +1,216 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+    BOOT_SCREEN_STYLES,
+    createBootScreenVitePlugin,
+    injectBootScreenHtml,
+    renderBootScreenHead,
+    renderBootScreenRuntime,
+    renderDefaultBootContent,
+} from './index.js';
+
+interface BootScreenApi {
+    ensureLoadingIndicator: () => void;
+    hideLoadingIndicatorOnFirstRender: () => void;
+    scheduleSlowLoadingNotice: () => void;
+    hideLoadingIndicator: () => void;
+}
+
+function bootApi(): BootScreenApi {
+    return (window as unknown as { __vertesiaBoot: BootScreenApi }).__vertesiaBoot;
+}
+
+function runRuntime({ dark = false, storageKey = 'test-theme' }: { dark?: boolean; storageKey?: string } = {}) {
+    Object.defineProperty(window, 'matchMedia', {
+        configurable: true,
+        value: vi.fn(() => ({ matches: dark })),
+    });
+    new Function(renderBootScreenRuntime({ storageKey }))();
+}
+
+afterEach(() => {
+    document.getElementById('loading-indicator')?.remove();
+    vi.useRealTimers();
+    localStorage.clear();
+    document.documentElement.className = '';
+    document.documentElement.removeAttribute('style');
+    document.body.removeAttribute('style');
+    document.body.innerHTML = '';
+    document.title = '';
+    vi.restoreAllMocks();
+});
+
+describe('boot screen HTML integration', () => {
+    it('injects the shared styles and runtime before app assets', () => {
+        const plugin = createBootScreenVitePlugin({ storageKey: 'auth-ui-theme', iconSrc: '/auth-icon.svg' });
+        const html = plugin.transformIndexHtml(
+            '<html><head><meta charset="UTF-8"><script src="/app.js"></script></head><body><div id="root"></div></body></html>',
+        );
+
+        expect(html.indexOf('<meta charset="UTF-8">')).toBeLessThan(html.indexOf('id="vertesia-boot-styles"'));
+        expect(html.indexOf('id="vertesia-boot-styles"')).toBeLessThan(html.indexOf('src="/app.js"'));
+        expect(html).toContain(BOOT_SCREEN_STYLES);
+        expect(html).toContain('auth-ui-theme');
+        expect(html).toContain('/auth-icon.svg');
+        const content = document.createElement('div');
+        content.innerHTML = renderDefaultBootContent();
+        expect(content.querySelector('.vboot-spinner')?.getAttribute('width')).toBe('40');
+        expect(content.querySelector('.vboot-spinner')?.getAttribute('height')).toBe('40');
+        expect(html).toContain('window.__vertesiaBoot.hideLoadingIndicatorOnFirstRender()');
+    });
+
+    it('can render the same bootstrap into server-generated HTML', () => {
+        const html = renderBootScreenHead({ storageKey: 'vite-ui-theme' });
+
+        expect(html).toContain('id="vertesia-boot-styles"');
+        expect(html).toContain('window.__vertesiaBoot');
+        expect(html).toContain('vite-ui-theme');
+    });
+
+    it('injects the bootstrap before scripts in a document without a charset meta tag', () => {
+        const html = injectBootScreenHtml(
+            '<!doctype html><html><head><script src="handler.js"></script></head><body></body></html>',
+            { storageKey: 'auth-ui-theme', iconSrc: '/auth-icon.svg' },
+        );
+
+        expect(html.indexOf('id="vertesia-boot-styles"')).toBeLessThan(html.indexOf('src="handler.js"'));
+        expect(html).toContain('auth-ui-theme');
+        expect(html).toContain('/auth-icon.svg');
+        expect(html).toContain('window.__vertesiaBoot.ensureLoadingIndicator()');
+    });
+
+    it('handles tag and attribute casing without regular expressions', () => {
+        const html = injectBootScreenHtml(
+            '<!doctype html><HTML><HEAD><META CHARSET = "UTF-8"><script src="handler.js"></script></HEAD><BODY></BODY></HTML>',
+        );
+
+        expect(html.indexOf('<META CHARSET = "UTF-8">')).toBeLessThan(html.indexOf('id="vertesia-boot-styles"'));
+        expect(html.indexOf('id="vertesia-boot-styles"')).toBeLessThan(html.indexOf('src="handler.js"'));
+        expect(html.indexOf('window.__vertesiaBoot.ensureLoadingIndicator()')).toBeLessThan(html.indexOf('</BODY>'));
+    });
+
+    it('scans repeated malformed tag prefixes in linear time', () => {
+        const malformedPrefixes = '<metadata>'.repeat(10_000);
+        const html = `<!doctype html><html><head>${malformedPrefixes}<script src="handler.js"></script></head><body></body></html>`;
+
+        const injected = injectBootScreenHtml(html);
+
+        expect(injected.indexOf('id="vertesia-boot-styles"')).toBeLessThan(injected.indexOf(malformedPrefixes));
+        expect(injected).toContain('window.__vertesiaBoot.ensureLoadingIndicator()');
+    });
+});
+
+describe('boot screen runtime', () => {
+    it('paints dark before React when the system prefers dark mode', () => {
+        runRuntime({ dark: true });
+
+        expect(document.documentElement.classList.contains('dark')).toBe(true);
+        expect(document.documentElement.style.backgroundColor).toBe('rgb(10, 10, 10)');
+        expect(document.documentElement.style.colorScheme).toBe('dark');
+    });
+
+    it('lets an explicit stored theme override the system preference', () => {
+        localStorage.setItem('test-theme', 'light');
+        runRuntime({ dark: true });
+
+        expect(document.documentElement.classList.contains('light')).toBe(true);
+        expect(document.documentElement.style.backgroundColor).toBe('rgb(255, 255, 255)');
+        expect(document.documentElement.style.colorScheme).toBe('light');
+    });
+
+    it('shows the shared loader and hands the document back after the app renders', async () => {
+        document.body.innerHTML = '<div id="root"></div>';
+        runRuntime({ dark: true });
+        bootApi().ensureLoadingIndicator();
+        bootApi().hideLoadingIndicatorOnFirstRender();
+
+        const loadingIndicator = document.getElementById('loading-indicator');
+        expect(loadingIndicator).not.toBeNull();
+        expect(loadingIndicator?.parentElement).toBe(document.documentElement);
+        document.getElementById('root')?.append(document.createElement('main'));
+        await vi.waitFor(() => expect(document.getElementById('loading-indicator')?.style.display).toBe('none'));
+
+        expect(document.documentElement.classList.contains('dark')).toBe(true);
+        expect(document.documentElement.style.backgroundColor).toBe('');
+        expect(document.documentElement.style.colorScheme).toBe('');
+    });
+});
+
+describe('custom boot branding', () => {
+    it('copies the document title as text into app-owned title elements', () => {
+        document.title = '<My application>';
+        new Function(renderBootScreenRuntime({ html: '<h1 data-boot-title>Welcome</h1>' }))();
+        bootApi().ensureLoadingIndicator();
+        expect(document.querySelector('[data-boot-title]')?.textContent).toBe('<My application>');
+        expect(document.querySelector('[data-boot-title]')?.children.length).toBe(0);
+    });
+
+    it('renders app HTML without the default spinner and hands off even when React already rendered', () => {
+        document.body.innerHTML = '<div id="root"><main>React application</main></div>';
+        new Function(renderBootScreenRuntime({ html: '<section>My custom brand</section>' }))();
+        bootApi().ensureLoadingIndicator();
+        const loader = document.getElementById('loading-indicator');
+        expect(loader?.parentElement).toBe(document.body);
+        expect(loader?.textContent).toBe('My custom brand');
+        expect(loader?.querySelector('.vboot-spinner')).toBeNull();
+        bootApi().hideLoadingIndicatorOnFirstRender();
+        expect(loader?.style.display).toBe('none');
+        expect(document.getElementById('root')?.textContent).toBe('React application');
+    });
+
+    it('escapes script terminators in trusted HTML while preserving the supplied content', () => {
+        const html = '<p>Brand</p><!-- </script><script>unexpected()</script> -->';
+        const runtime = renderBootScreenRuntime({ html });
+        expect(runtime).not.toContain('</script>');
+        new Function(runtime)();
+        bootApi().ensureLoadingIndicator();
+        expect(document.getElementById('loading-indicator')?.innerHTML).toBe(html);
+    });
+
+    it('inlines app styles after the defaults and respects a custom document background', () => {
+        const styles = ':root { --vertesia-boot-background: rgb(12, 34, 56); }';
+        const html = renderBootScreenHead({ styles });
+        expect(html.indexOf(styles)).toBeGreaterThan(html.indexOf(BOOT_SCREEN_STYLES));
+        document.documentElement.style.setProperty('--vertesia-boot-background', 'rgb(12, 34, 56)');
+        runRuntime();
+        expect(document.documentElement.style.backgroundColor).toBe('rgb(12, 34, 56)');
+    });
+
+    it('reveals app-owned slow-load recovery and cancels timers on handoff', async () => {
+        vi.useFakeTimers();
+        document.body.innerHTML = '<div id="root"></div>';
+        new Function(
+            renderBootScreenRuntime({
+                html: `
+            <p>Branded startup</p>
+            <div id="loading-slow-notice" style="display:none">Taking longer
+                <div id="loading-slow-reload" style="display:none"><button data-boot-reload>Reload</button></div>
+            </div>`,
+            }),
+        )();
+        bootApi().ensureLoadingIndicator();
+        bootApi().hideLoadingIndicatorOnFirstRender();
+        bootApi().scheduleSlowLoadingNotice();
+        await vi.advanceTimersByTimeAsync(10000);
+        expect(document.getElementById('loading-slow-notice')?.style.display).toBe('');
+        expect(document.getElementById('loading-slow-reload')?.style.display).toBe('none');
+        await vi.advanceTimersByTimeAsync(20000);
+        expect(document.getElementById('loading-slow-reload')?.style.display).toBe('');
+        document.getElementById('root')?.append(document.createElement('main'));
+        await Promise.resolve();
+        expect(document.getElementById('loading-indicator')?.style.display).toBe('none');
+        expect(vi.getTimerCount()).toBe(0);
+    });
+
+    it('cancels pending slow-load notices when React renders promptly', async () => {
+        vi.useFakeTimers();
+        document.body.innerHTML = '<div id="root"></div>';
+        runRuntime();
+        bootApi().ensureLoadingIndicator();
+        bootApi().hideLoadingIndicatorOnFirstRender();
+        bootApi().scheduleSlowLoadingNotice();
+        document.getElementById('root')?.append(document.createElement('main'));
+        await Promise.resolve();
+        expect(vi.getTimerCount()).toBe(0);
+        expect(document.getElementById('loading-slow-notice')?.style.display).toBe('none');
+    });
+});

package/src/boot/index.ts

@@ -0,0 +1,356 @@
+export interface BootScreenOptions {
+    storageKey?: string;
+    iconSrc?: string;
+    darkIconSrc?: string;
+    slowLoadingLabel?: string;
+    reloadLabel?: string;
+    loadingLabel?: string;
+    autoStart?: boolean;
+    /** Trusted, app-authored HTML inside the loading container. Never pass user content. */
+    html?: string;
+    /** Inline CSS appended after the defaults; available before application styles load. */
+    styles?: string;
+}
+
+export interface BootScreenHtmlPlugin {
+    name: string;
+    transformIndexHtml: (html: string) => string;
+}
+
+const DEFAULT_STORAGE_KEY = 'vite-ui-theme';
+const DEFAULT_ICON_SRC = '/icon.svg';
+const DEFAULT_LOADING_LABEL = 'Loading';
+
+export const BOOT_SCREEN_STYLES = `
+  .vboot {
+    --vb-bg: #ffffff;
+    --vb-fg: #0a0a0a;
+    --vb-muted: #636363;
+    --vb-muted-bg: #f5f5f5;
+    --vb-border: #e5e5e5;
+    --vb-primary: #0048bd;
+    --vb-primary-fg: #ffffff;
+    --vb-glow: rgba(50, 49, 189, 0.12);
+    font-family: Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif;
+    color: var(--vb-fg);
+  }
+  .vboot.vboot-dark {
+    --vb-bg: #0a0a0a;
+    --vb-fg: #fafafa;
+    --vb-muted: #a1a1a1;
+    --vb-muted-bg: #262626;
+    --vb-border: rgba(255, 255, 255, 0.1);
+    --vb-primary: #2b69d1;
+    --vb-primary-fg: #fafafa;
+    --vb-glow: rgba(79, 70, 229, 0.2);
+  }
+  @keyframes vboot-spin {
+    from { transform: rotate(0deg); }
+    to { transform: rotate(360deg); }
+  }
+  .vboot-overlay {
+    position: absolute !important;
+    inset: 0 !important;
+    box-sizing: border-box !important;
+    width: 100% !important;
+    height: 100% !important;
+    margin: 0 !important;
+    padding: 0 !important;
+    display: flex !important;
+    flex-direction: column !important;
+    align-items: center !important;
+    justify-content: center !important;
+    gap: 1.5rem !important;
+    transform: none !important;
+    background: var(--vb-bg) !important;
+  }
+  #loading-indicator {
+    position: fixed !important;
+    inset: 0 !important;
+    z-index: 2147483647 !important;
+    box-sizing: border-box !important;
+    width: 100vw !important;
+    height: 100vh !important;
+    margin: 0 !important;
+    padding: 0 !important;
+    transform: none !important;
+  }
+  .vboot-spinner {
+    width: 2.5rem !important;
+    min-width: 2.5rem !important;
+    max-width: 2.5rem !important;
+    height: 2.5rem !important;
+    min-height: 2.5rem !important;
+    max-height: 2.5rem !important;
+    margin: 0 !important;
+    padding: 0 !important;
+    object-fit: contain !important;
+    flex: none !important;
+    border-radius: 100% !important;
+    animation: var(--vertesia-loading-animation, vboot-spin 2s linear infinite) !important;
+  }
+  .vboot-icon-dark { display: none; }
+  .vboot-dark .vboot-icon-light { display: none; }
+  .vboot-dark .vboot-icon-dark { display: block; }
+  .vboot-slow {
+    text-align: center;
+  }
+  .vboot-slow p {
+    color: var(--vb-muted);
+    font-size: 0.875rem;
+    margin: 0 0 0.75rem;
+  }
+  .vboot-btn {
+    display: inline-block;
+    padding: 0.5rem 1rem;
+    background: var(--vb-primary);
+    color: var(--vb-primary-fg);
+    border: none;
+    border-radius: 0.375rem;
+    font: inherit;
+    font-size: 0.875rem;
+    font-weight: 500;
+    cursor: pointer;
+  }
+  .vboot-btn:hover {
+    opacity: 0.9;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .vboot-spinner { animation: none !important; }
+  }
+`;
+
+function inlineJson(value: string): string {
+    return JSON.stringify(value).replaceAll('<', '\\u003c');
+}
+
+function normalizedOptions(options: BootScreenOptions) {
+    return {
+        storageKey: options.storageKey ?? DEFAULT_STORAGE_KEY,
+        iconSrc: options.iconSrc ?? DEFAULT_ICON_SRC,
+        loadingLabel: options.loadingLabel ?? DEFAULT_LOADING_LABEL,
+        autoStart: options.autoStart ?? true,
+        html: options.html,
+        styles: options.styles,
+    };
+}
+
+/** Default markup shared by Studio and configurable applications. */
+export function renderDefaultBootContent(options: BootScreenOptions = {}): string {
+    const escapeMarkup = (value: string) =>
+        value.replace(
+            /[&<>"']/g,
+            (char) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char] ?? char,
+        );
+    const { iconSrc, loadingLabel } = normalizedOptions(options);
+    const icon = (src: string, className = '') =>
+        `<img class="vboot-spinner ${className}" width="40" height="40" src="${escapeMarkup(src)}" alt="${escapeMarkup(loadingLabel)}" />`;
+    return `<div class="vboot-overlay" role="status" aria-live="polite">${options.darkIconSrc ? icon(iconSrc, 'vboot-icon-light') + icon(options.darkIconSrc, 'vboot-icon-dark') : icon(iconSrc)}
+<div id="loading-slow-notice" class="vboot-slow" style="display: none;">
+<p>${escapeMarkup(options.slowLoadingLabel ?? 'Still loading — this is taking longer than usual.')}</p>
+<div id="loading-slow-reload" style="display: none;"><button type="button" class="vboot-btn" data-boot-reload>${escapeMarkup(options.reloadLabel ?? 'Reload page')}</button></div></div></div>`;
+}
+
+export function renderBootScreenRuntime(options: BootScreenOptions = {}): string {
+    const { storageKey, html } = normalizedOptions(options);
+    const defaultHtml = renderDefaultBootContent(options);
+    return `(() => {
+  const storageKey = ${inlineJson(storageKey)};
+
+  const customHtml = ${html === undefined ? 'undefined' : inlineJson(html)};
+  let slowNoticeTimer;
+  let slowReloadTimer;
+  const previewTheme = (() => {
+    try {
+      const value = new URL(window.location.href).searchParams.get('__vertesia_boot_theme');
+      return value === 'dark' || value === 'light' ? value : null;
+    } catch (_error) {
+      return null;
+    }
+  })();
+  const prefersDarkTheme = () => {
+    if (previewTheme) return previewTheme === 'dark';
+    try {
+      const stored = window.localStorage.getItem(storageKey);
+      if (stored === 'dark') return true;
+      if (stored === 'light') return false;
+    } catch (_error) {
+      // Storage can be unavailable in private or restricted browsing contexts.
+    }
+    try {
+      return typeof window.matchMedia === 'function' && window.matchMedia('(prefers-color-scheme: dark)').matches;
+    } catch (_error) {
+      return false;
+    }
+  };
+  const applyTheme = () => {
+    const dark = prefersDarkTheme();
+    const root = document.documentElement;
+    root.classList.remove('light', 'dark');
+    root.classList.add(dark ? 'dark' : 'light');
+    return dark;
+  };
+  const paintDocumentBackground = () => {
+    const dark = applyTheme();
+    const root = document.documentElement;
+    const background = window.getComputedStyle(root).getPropertyValue('--vertesia-boot-background').trim()
+      || (dark ? '#0a0a0a' : '#ffffff');
+    root.style.backgroundColor = background;
+    root.style.colorScheme = dark ? 'dark' : 'light';
+    if (document.body) document.body.style.backgroundColor = background;
+  };
+  const restoreDocumentBackground = () => {
+    applyTheme();
+    const root = document.documentElement;
+    root.style.removeProperty('background-color');
+    root.style.removeProperty('color-scheme');
+    if (document.body) document.body.style.removeProperty('background-color');
+  };
+  const bootThemeClass = () => prefersDarkTheme() ? 'vboot vboot-dark' : 'vboot';
+  const ensureLoadingIndicator = () => {
+    if (document.getElementById('loading-indicator') || !document.body) return;
+    paintDocumentBackground();
+    const loading = document.createElement('div');
+    loading.id = 'loading-indicator';
+    loading.className = bootThemeClass();
+    loading.innerHTML = customHtml ?? ${inlineJson(defaultHtml)};
+    loading.querySelectorAll('[data-boot-title]').forEach((heading) => {
+      if (document.title) heading.textContent = document.title;
+    });
+    loading.querySelectorAll('[data-boot-reload]').forEach((button) => {
+      button.addEventListener('click', () => window.location.reload());
+    });
+    // Custom landmarks and controls must stay in body to enter the accessibility tree.
+    const loadingParent = customHtml === undefined && typeof document.documentElement.appendChild === 'function'
+      ? document.documentElement
+      : document.body;
+    loadingParent.appendChild(loading);
+  };
+  const hideLoadingIndicator = () => {
+    clearTimeout(slowNoticeTimer);
+    clearTimeout(slowReloadTimer);
+    const loading = document.getElementById('loading-indicator');
+    if (loading) loading.style.display = 'none';
+  };
+  const hasAppRendered = (rootId = 'root') => {
+    const root = document.getElementById(rootId);
+    return Boolean(root && root.innerHTML && root.innerHTML.trim() !== '');
+  };
+  const hideLoadingIndicatorOnFirstRender = (rootId = 'root') => {
+    if (typeof MutationObserver !== 'function') return;
+    const root = document.getElementById(rootId);
+    if (!root) return;
+    if (hasAppRendered(rootId)) {
+      hideLoadingIndicator();
+      restoreDocumentBackground();
+      return;
+    }
+    const observer = new MutationObserver(() => {
+      if (!hasAppRendered(rootId)) return;
+      hideLoadingIndicator();
+      restoreDocumentBackground();
+      observer.disconnect();
+    });
+    observer.observe(root, { childList: true });
+  };
+  // Used by standalone apps. Hosts with their own error handler keep autoStart disabled.
+  const scheduleSlowLoadingNotice = () => {
+    clearTimeout(slowNoticeTimer);
+    clearTimeout(slowReloadTimer);
+    if (hasAppRendered()) return;
+    slowNoticeTimer = setTimeout(() => {
+      const notice = document.getElementById('loading-slow-notice');
+      if (notice) notice.style.display = '';
+    }, 10000);
+    slowReloadTimer = setTimeout(() => {
+      const reload = document.getElementById('loading-slow-reload');
+      if (reload) reload.style.display = '';
+    }, 30000);
+  };
+  window.__vertesiaBoot = {
+    scheduleSlowLoadingNotice,
+    applyTheme,
+    bootThemeClass,
+    ensureLoadingIndicator,
+    hasAppRendered,
+    hideLoadingIndicator,
+    hideLoadingIndicatorOnFirstRender,
+    paintDocumentBackground,
+    prefersDarkTheme,
+    restoreDocumentBackground,
+  };
+  paintDocumentBackground();
+})();`;
+}
+
+export function renderBootScreenHead(options: BootScreenOptions = {}): string {
+    return `<style id="vertesia-boot-styles">${BOOT_SCREEN_STYLES}\n${options.styles ?? ''}</style>\n<script>${renderBootScreenRuntime(options)}</script>`;
+}
+
+export function renderBootScreenInitializer(): string {
+    return `<script>window.__vertesiaBoot.ensureLoadingIndicator(); window.__vertesiaBoot.hideLoadingIndicatorOnFirstRender(); window.__vertesiaBoot.scheduleSlowLoadingNotice();</script>`;
+}
+
+function isHtmlWhitespace(character: string | undefined): boolean {
+    return character === ' ' || character === '\t' || character === '\n' || character === '\r' || character === '\f';
+}
+
+function hasAttribute(openingTag: string, attributeName: string): boolean {
+    const lowerTag = openingTag.toLowerCase();
+    let searchFrom = 0;
+    while (searchFrom < lowerTag.length) {
+        const attributeIndex = lowerTag.indexOf(attributeName, searchFrom);
+        if (attributeIndex === -1) return false;
+
+        const before = lowerTag[attributeIndex - 1];
+        let afterIndex = attributeIndex + attributeName.length;
+        while (isHtmlWhitespace(lowerTag[afterIndex])) afterIndex += 1;
+        if (isHtmlWhitespace(before) && lowerTag[afterIndex] === '=') return true;
+        searchFrom = attributeIndex + attributeName.length;
+    }
+    return false;
+}
+
+function findOpeningTagEnd(html: string, tagName: string, attributeName?: string): number | undefined {
+    const lowerHtml = html.toLowerCase();
+    const tagStart = `<${tagName}`;
+    let searchFrom = 0;
+    while (searchFrom < lowerHtml.length) {
+        const start = lowerHtml.indexOf(tagStart, searchFrom);
+        if (start === -1) return undefined;
+
+        const boundary = lowerHtml[start + tagStart.length];
+        if (boundary === '>' || isHtmlWhitespace(boundary)) {
+            const end = lowerHtml.indexOf('>', start + tagStart.length);
+            if (end === -1) return undefined;
+            if (!attributeName || hasAttribute(lowerHtml.slice(start, end + 1), attributeName)) return end + 1;
+            searchFrom = end + 1;
+        } else {
+            searchFrom = start + tagStart.length;
+        }
+    }
+    return undefined;
+}
+
+function insertAt(html: string, index: number, content: string): string {
+    return `${html.slice(0, index)}${content}${html.slice(index)}`;
+}
+
+export function injectBootScreenHtml(html: string, options: BootScreenOptions = {}): string {
+    const normalized = normalizedOptions(options);
+    const head = renderBootScreenHead(normalized);
+    const insertionPoint = findOpeningTagEnd(html, 'meta', 'charset') ?? findOpeningTagEnd(html, 'head');
+    const withHead = insertionPoint === undefined ? html : insertAt(html, insertionPoint, `\n${head}`);
+    if (!normalized.autoStart) return withHead;
+    const bodyEnd = withHead.toLowerCase().indexOf('</body>');
+    return bodyEnd === -1 ? withHead : insertAt(withHead, bodyEnd, `${renderBootScreenInitializer()}\n`);
+}
+
+export function createBootScreenVitePlugin(options: BootScreenOptions = {}): BootScreenHtmlPlugin {
+    return {
+        name: 'vertesia-boot-screen',
+        transformIndexHtml: (html) => injectBootScreenHtml(html, options),
+    };
+}
+
+export * from './branding.js';

package/src/boot/vite.test.ts

@@ -0,0 +1,93 @@
+// @vitest-environment node
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createAppBrandingPlugin, resolveBrandingAssets } from './vite.js';
+
+const directories: string[] = [];
+function fixture() {
+    const dir = mkdtempSync(join(tmpdir(), 'ui-branding-'));
+    directories.push(dir);
+    mkdirSync(join(dir, 'assets'));
+    writeFileSync(join(dir, 'assets/logo.svg'), '<svg xmlns="http://www.w3.org/2000/svg"/>');
+    writeFileSync(join(dir, 'assets/font.woff2'), 'font-bytes');
+    return { dir, moduleUrl: pathToFileURL(join(dir, 'index.ts')) };
+}
+afterEach(() => {
+    for (const dir of directories.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe('branding Vite adapter', () => {
+    it('resolves local assets once for both React and first paint independently of deployment paths', () => {
+        const { moduleUrl } = fixture();
+        const plugin = createAppBrandingPlugin(
+            {
+                name: 'A & B',
+                logo: { light: './assets/logo.svg' },
+                loadingIcon: { light: './assets/logo.svg', dark: './assets/logo.svg', animation: 'none' },
+                font: { family: 'Brand', regular: './assets/font.woff2' },
+                favicon: './assets/logo.svg',
+            },
+            moduleUrl,
+        );
+        const addWatchFile = vi.fn();
+        const id = plugin.resolveId('virtual:vertesia-branding') ?? '';
+        const code = plugin.load.call({ addWatchFile }, id) ?? '';
+        const resolved = JSON.parse(code.slice('export default '.length, -1));
+        expect(resolved.logo.light).toMatch(/^data:image\/svg\+xml;base64,/);
+        expect(resolved.loadingIcon).toEqual({
+            light: resolved.logo.light,
+            dark: resolved.logo.light,
+            animation: 'none',
+        });
+        expect(resolved.font.regular).toBe('data:font/woff2;base64,Zm9udC1ieXRlcw==');
+        expect(addWatchFile).toHaveBeenCalledTimes(2);
+        const html = plugin.transformIndexHtml(
+            '<html><head><title>Old</title><link rel="icon" href="old.ico"></head><body></body></html>',
+        );
+        expect(html).toContain('<title>A &amp; B</title>');
+        expect(html).toContain(resolved.logo.light);
+        expect(html).not.toContain('old.ico');
+        expect(html).not.toContain('./assets/');
+    });
+
+    it('fails for missing assets and resolves custom boot assets relative to their own files', () => {
+        const { moduleUrl, dir } = fixture();
+        expect(() => resolveBrandingAssets({ name: 'Test', logo: { light: './missing.svg' } }, moduleUrl)).toThrow();
+        writeFileSync(
+            join(dir, 'assets/boot.html'),
+            '<img src="logo.svg"><a href="./help">Help</a><svg><use href="#icon"/></svg>',
+        );
+        writeFileSync(join(dir, 'assets/boot.css'), '@font-face{src:url(font.woff2)}');
+        const brand = resolveBrandingAssets(
+            { name: 'Test', boot: { html: './assets/boot.html', styles: './assets/boot.css' } },
+            moduleUrl,
+        );
+        expect(brand.boot?.html).toContain('data:image/svg+xml;base64,');
+        expect(brand.boot?.styles).toContain('data:font/woff2;base64,');
+        expect(brand.boot?.html).toContain('<a href="./help">Help</a>');
+        expect(brand.boot?.html).toContain('href="#icon"');
+    });
+
+    it('refreshes the virtual module when a watched logo changes', () => {
+        const { moduleUrl, dir } = fixture();
+        const plugin = createAppBrandingPlugin({ name: 'Test', logo: { light: './assets/logo.svg' } }, moduleUrl);
+        const id = plugin.resolveId('virtual:vertesia-branding') ?? '';
+        plugin.load.call({ addWatchFile: vi.fn() }, id);
+        const module = {};
+        const invalidateModule = vi.fn();
+        const send = vi.fn();
+        plugin.handleHotUpdate({
+            file: join(dir, 'assets/logo.svg'),
+            server: { moduleGraph: { getModuleById: () => module, invalidateModule }, ws: { send } },
+        });
+        expect(invalidateModule).toHaveBeenCalledWith(module);
+        expect(send).toHaveBeenCalledWith({ type: 'full-reload' });
+        writeFileSync(join(dir, 'assets/logo.svg'), '<svg>changed</svg>');
+        expect(plugin.load.call({ addWatchFile: vi.fn() }, id)).toContain(
+            Buffer.from('<svg>changed</svg>').toString('base64'),
+        );
+    });
+});