fix(viewer): defer preview font stylesheets (#7134)

Author: lefarcen

apps/web/src/components/FileViewer.tsx

@@ -10372,6 +10372,7 @@ function HtmlViewer({
           paletteBridge: false,
           previewFocusGuard: true,
           previewObservability: true,
+          deferFontStylesheets: true,
           // Embed the reload counter so the srcdoc string differs across reloads
           // even when the fetched HTML bytes are identical (issue #4650).
           reloadKey,

apps/web/src/runtime/deck-thumbnail-parser.ts

@@ -77,7 +77,7 @@ const FONT_HOSTS = new Set([
 // must be an https URL whose HOST is exactly an approved font CDN — a substring
 // match would accept `https://evil.example/fonts.googleapis.com.css` and inject
 // arbitrary CSS into the app document.
-function isApprovedFontHref(href: string): boolean {
+export function isApprovedFontStylesheetHref(href: string): boolean {
   // Font-CDN links are always absolute https URLs; a relative href cannot be an
   // approved CDN and is correctly treated as an untrusted external stylesheet.
   let url: URL;
@@ -127,7 +127,7 @@ export function parseDeckThumbnails(html: string, baseHref?: string): ParsedDeck
     if (!/\bstylesheet\b/.test(rel)) continue;
     const href = link.getAttribute('href') || '';
     if (!href) continue;
-    if (isApprovedFontHref(href)) {
+    if (isApprovedFontStylesheetHref(href)) {
       if (!fontLinks.includes(href)) fontLinks.push(href);
     } else {
       return unrenderable('external-stylesheet');
@@ -468,7 +468,7 @@ function extractStylesheetImports(css: string): StylesheetImportExtraction {
     const match = CSS_IMPORT_HREF_RE.exec(statement);
     const href = match?.slice(1).find((value): value is string => typeof value === 'string')?.trim() ?? '';
     const condition = match ? statement.slice(match[0].length, -1).trim() : '';
-    if (!href || condition || !isApprovedFontHref(href)) unsafe = true;
+    if (!href || condition || !isApprovedFontStylesheetHref(href)) unsafe = true;
     else if (!fontLinks.includes(href)) fontLinks.push(href);
 
     chunks.push(css.slice(chunkStart, i));

apps/web/src/runtime/srcdoc.ts

@@ -31,6 +31,7 @@ import {
   MANUAL_EDIT_DISCOVERY_SELECTOR,
   MANUAL_EDIT_SOURCE_PATH_ATTR,
 } from '../edit-mode/bridge';
+import { isApprovedFontStylesheetHref } from './deck-thumbnail-parser';
 
 export type SrcdocOptions = {
   deck?: boolean;
@@ -48,6 +49,9 @@ export type SrcdocOptions = {
   /** Install the live-preview error and white-screen reporting bridge. Keep
    * this disabled for exports, captures, thumbnails, and historical previews. */
   previewObservability?: boolean;
+  /** Let trusted font-CDN stylesheets load without blocking the live preview's
+   * first paint. Keep disabled for exports and other capture surfaces. */
+  deferFontStylesheets?: boolean;
   /**
    * Force every CSS animation/transition to complete instantly so the
    * document settles at its final visual state and stops repainting. Meant
@@ -395,7 +399,10 @@ export function buildSrcdoc(
   const withOdIds = annotateMissingOdIds(withSafeTitle);
   const withSourcePaths = options.editBridge ? annotateManualEditSourcePaths(withOdIds) : withOdIds;
   const withBase = options.baseHref ? injectBaseHref(withSourcePaths, options.baseHref) : withSourcePaths;
-  const withShim = injectSandboxShim(withBase);
+  const withDeferredFonts = options.deferFontStylesheets
+    ? deferTrustedFontStylesheets(withBase)
+    : withBase;
+  const withShim = injectSandboxShim(withDeferredFonts);
   const blockLoadTimeScriptRedirect = htmlHasLoadTimeLocationNavigation(withBase);
   // Always on: a redirect loop can freeze ANY previewed artifact, and the guard
   // is inert on documents that never self-redirect. Injected right after the
@@ -1301,6 +1308,62 @@ function injectManualEditBridge(doc: string): string {
   return injectBeforeBodyEnd(withStyle, buildManualEditBridge(false));
 }
 
+const DEFERRED_FONT_STYLESHEET_ATTR = 'data-od-deferred-font-stylesheet';
+
+function deferTrustedFontStylesheets(doc: string): string {
+  if (typeof DOMParser === 'undefined') return doc;
+  let parsed: Document;
+  try {
+    parsed = new DOMParser().parseFromString(doc, 'text/html');
+  } catch {
+    return doc;
+  }
+
+  let deferred = false;
+  parsed.querySelectorAll<HTMLLinkElement>('link[rel~="stylesheet"][href]').forEach((link) => {
+    const href = link.getAttribute('href') ?? '';
+    if (!isApprovedFontStylesheetHref(href)) return;
+    const authoredMedia = link.getAttribute('media')?.trim() ?? '';
+    if (authoredMedia.toLowerCase() === 'print') return;
+    link.setAttribute(DEFERRED_FONT_STYLESHEET_ATTR, authoredMedia);
+    link.setAttribute('media', 'print');
+    deferred = true;
+  });
+  if (!deferred) return doc;
+
+  const script = `<script data-od-font-stylesheet-loader>(function(){
+  var attr = '${DEFERRED_FONT_STYLESHEET_ATTR}';
+  var selector = 'link[' + attr + ']';
+  function activate(link){
+    if (!link || !link.hasAttribute(attr)) return;
+    var media = link.getAttribute(attr) || 'all';
+    link.setAttribute('media', media);
+    link.removeAttribute(attr);
+  }
+  function watch(link){
+    if (!link || link.__odFontStylesheetWatched) return;
+    link.__odFontStylesheetWatched = true;
+    link.addEventListener('load', function(){ activate(link); }, { once: true });
+    try { if (link.sheet) activate(link); } catch (_) {}
+  }
+  function scan(root){
+    if (!root) return;
+    if (root.matches && root.matches(selector)) watch(root);
+    var links = root.querySelectorAll ? root.querySelectorAll(selector) : [];
+    for (var i = 0; i < links.length; i += 1) watch(links[i]);
+  }
+  var observer = typeof MutationObserver === 'function' ? new MutationObserver(function(records){
+    for (var i = 0; i < records.length; i += 1) {
+      var added = records[i].addedNodes || [];
+      for (var j = 0; j < added.length; j += 1) scan(added[j]);
+    }
+  }) : null;
+  if (observer && document.documentElement) observer.observe(document.documentElement, { childList: true, subtree: true });
+  scan(document);
+})();</script>`;
+  return injectAfterHeadOpen(serializeHtmlDocument(parsed), script);
+}
+
 function injectAfterHeadOpen(doc: string, payload: string): string {
   if (/<head[^>]*>/i.test(doc)) return doc.replace(/<head[^>]*>/i, (m) => `${m}${payload}`);
   return payload + doc;

apps/web/tests/runtime/srcdoc.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { JSDOM } from 'jsdom';
 import { DECK_STRUCTURED_SLIDE_SELECTOR } from '@open-design/contracts/runtime/deck-stage-fallback';
 import { buildSrcdoc } from '../../src/runtime/srcdoc';
@@ -108,6 +108,46 @@ describe('buildSrcdoc', () => {
     expect(buildSrcdoc(html)).not.toContain('data-od-preview-observability');
   });
 
+  it('defers trusted font stylesheets without changing authored layout CSS', async () => {
+    const parserWindow = new JSDOM('').window;
+    vi.stubGlobal('DOMParser', parserWindow.DOMParser);
+    const fontHref = 'https://fonts.googleapis.com/css2?family=Inter&display=swap';
+    const html = `<!doctype html><html><head>
+      <link href="${fontHref}" rel="stylesheet">
+      <link href="/layout.css" rel="stylesheet">
+    </head><body><main>Preview</main></body></html>`;
+    try {
+      const srcdoc = buildSrcdoc(html, { deferFontStylesheets: true });
+      const document = new JSDOM(srcdoc).window.document;
+      const fontLink = document.querySelector<HTMLLinkElement>('link[href^="https://fonts.googleapis.com/"]');
+      const layoutLink = document.querySelector<HTMLLinkElement>('link[href="/layout.css"]');
+
+      expect(fontLink?.media).toBe('print');
+      expect(fontLink?.hasAttribute('data-od-deferred-font-stylesheet')).toBe(true);
+      expect(layoutLink?.media).toBe('');
+      expect(layoutLink?.hasAttribute('data-od-deferred-font-stylesheet')).toBe(false);
+      expect(srcdoc.indexOf('data-od-font-stylesheet-loader')).toBeLessThan(
+        srcdoc.indexOf('fonts.googleapis.com'),
+      );
+
+      const runtime = new JSDOM(srcdoc, { runScripts: 'dangerously' });
+      await new Promise<void>((resolve) => runtime.window.queueMicrotask(resolve));
+      const runtimeFontLink = runtime.window.document.querySelector<HTMLLinkElement>(
+        'link[href^="https://fonts.googleapis.com/"]',
+      );
+      runtimeFontLink?.dispatchEvent(new runtime.window.Event('load'));
+      expect(runtimeFontLink?.media).toBe('all');
+      expect(runtimeFontLink?.hasAttribute('data-od-deferred-font-stylesheet')).toBe(false);
+      runtime.window.close();
+
+      const unchanged = new JSDOM(buildSrcdoc(html)).window.document;
+      expect(unchanged.querySelector<HTMLLinkElement>('link[href^="https://fonts.googleapis.com/"]')?.media).toBe('');
+    } finally {
+      vi.unstubAllGlobals();
+      parserWindow.close();
+    }
+  });
+
   it('echoes the host challenge token from the srcDoc transport readiness probe', () => {
     const srcdoc = buildSrcdoc('<main>Preview</main>', {
       transportActivationGeneration: 'generation-42',