fix(ui,sdk)!: carry the font faces in the entry chunk and harden the font pipeline

Author: librowski

.changeset/font-assets.md

@@ -1,7 +1,13 @@
 ---
-'@workflowbuilder/ui': minor
-'@workflowbuilder/sdk': minor
+'@workflowbuilder/ui': major
+'@workflowbuilder/sdk': major
 ---
 
 Fonts now ship as `.woff2` assets next to the stylesheets, with only the two dominant faces inlined.
-A Content-Security-Policy that lists `font-src` now needs `'self'` or the serving origin instead of `data:`.
+
+Breaking changes:
+
+- Preserve the published `dist/assets` directory next to copied stylesheets so their relative font URLs keep resolving.
+- If a Content Security Policy defines `font-src`, add `'self'` or the serving origin while retaining `data:` for the inlined faces.
+
+Only Poppins latin 400 and 600 are inline. Other weights, Inter, and non-ASCII glyphs use `font-display: swap` assets and may briefly render in the fallback font; preload the relevant files when that flash of unstyled text (FOUT) is unacceptable.

apps/docs/src/components/ui-examples/component-preview.tsx

@@ -1,15 +1,15 @@
-import componentCss from '@workflowbuilder/ui/index.css?raw';
-import globalCss from '@workflowbuilder/ui/styles.css?raw';
 import { type ReactNode, useEffect, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 
 import styles from './component-preview.module.css';
 
+import previewCss from '../../../../../packages/ui/dist/docs-preview.css?raw';
+
 // Examples render in a shadow root so Starlight's rules cannot reach them and
 // the library's cannot leak out. Inherited and custom properties still cross
 // the boundary - that is how the docs theme reaches the examples. Inside a
 // shadow root `:root` matches nothing, hence the retarget to `:host`.
-const shadowCss = `${`${globalCss}\n${componentCss}`.replaceAll(':root', ':host')}
+const shadowCss = `${previewCss.replaceAll(':root', ':host')}
 :host > :not(style) { max-width: 100%; }`;
 
 export function ComponentPreview({ children }: { children: ReactNode }) {

apps/docs/src/content/docs/get-started/theming.md

@@ -9,7 +9,9 @@ The aggregated `style.css` ships with the SDK's default visual layer. Override C
 
 ## Typography
 
-Poppins is bundled into `style.css` as inline base64 woff2 (latin + latin-ext, weights 300–700). No external font CDN is contacted at runtime — works under strict CSP, behind GDPR-controlled consent flows, and in air-gapped deployments.
+`style.css` inlines Poppins latin 400 and 600 and references the remaining Poppins and Inter faces in the adjacent `assets` directory. Preserve that `dist` layout when copying the stylesheet. A Content Security Policy (CSP) that defines `font-src` must allow both `data:` and `'self'` or the origin serving those assets. No external font CDN is contacted at runtime, so the SDK still works behind consent controls and in air-gapped deployments.
+
+Other weights, Inter, and non-ASCII glyphs use `font-display: swap` assets. They can briefly appear in the fallback font while the matching file loads; preload the relevant `.woff2` files when that flash of unstyled text (FOUT) is unacceptable.
 
 Override `--wb-font-family` to use a different face:
 

apps/docs/src/content/docs/ui-library/overview.mdx

@@ -42,6 +42,15 @@ The package has five style surfaces:
 The stylesheets reference `./assets/*.woff2`, so preserve the package's `dist`
 layout when copying or serving them.
 
+Only Poppins latin 400 and 600 are inline. Other weights, Inter, and non-ASCII
+glyphs use `font-display: swap` assets, so they can briefly appear in the
+fallback font while loading. Preload the relevant `.woff2` files when that
+flash of unstyled text (FOUT) is unacceptable:
+
+```html
+<link rel="preload" href="/assets/poppins-latin-ext-400-normal.woff2" as="font" type="font/woff2" crossorigin />
+```
+
 With the root barrel, add only the design tokens:
 
 ```ts

knip.config.js

@@ -55,7 +55,7 @@ export default {
     },
     'packages/ui': {
       entry: ['src/index.ts', 'vite.config.mts', 'scripts/check-built-css.ts'],
-      project: ['src/**/*.{ts,tsx,mts}', '*.mts', 'scripts/**/*.ts'],
+      project: ['src/**/*.{ts,tsx}', '*.mts', 'scripts/**/*.ts'],
       // Built tokens are copied by relative path (../tokens/dist) in vite.config,
       // and the fontsource families feed the post-build font generator - real
       // dependencies knip's JS/TS walk cannot see.

packages/sdk/package.json

@@ -60,7 +60,7 @@
     "lint": "eslint",
     "test": "vitest run",
     "test:watch": "vitest",
-    "build:lib": "vite build",
+    "build:lib": "vite build && pnpm exec tsx ../ui/scripts/check-built-css.ts dist",
     "prepublishOnly": "pnpm build:lib"
   },
   "peerDependencies": {

packages/sdk/src/index.css

@@ -6,8 +6,6 @@
    See packages/ui/css-layers.md. */
 @layer ui.base, ui.component;
 
-/* Poppins and Inter ship with @workflowbuilder/ui (next to the wb-text-*
-   classes that require them) and arrive through the JS module graph. */
 @import '@workflowbuilder/ui/tokens.css';
 
 /* @workflowbuilder/ui styles arrive through the JS module graph - importing

packages/sdk/vite.config.mts

@@ -61,15 +61,38 @@ function emitUiFontAssets(): Plugin {
     closeBundle() {
       const uiDistribution = path.resolve(import.meta.dirname, '../ui/dist');
       const stylesheetPath = path.resolve(distributionDirectory, 'style.css');
-      const fontStyles = fs.readFileSync(path.resolve(uiDistribution, 'fonts.css'), 'utf8');
+      const fontStylesPath = path.resolve(uiDistribution, 'fonts.css');
       const assetsDirectory = path.resolve(distributionDirectory, 'assets');
 
+      if (!fs.existsSync(fontStylesPath)) {
+        throw new Error(
+          '@workflowbuilder/ui dist is missing fonts.css - build the UI first: `pnpm build:ui`',
+        );
+      }
+      if (!fs.existsSync(stylesheetPath)) {
+        throw new Error(
+          `wb-sdk:emit-ui-font-assets: ${stylesheetPath} is missing - ` +
+            'the Vite build emitted no SDK stylesheet to receive the font faces',
+        );
+      }
+
+      const fontStyles = fs
+        .readFileSync(fontStylesPath, 'utf8')
+        .replace(/^@layer ui\.base, ui\.component;\s*/, '');
+      const stylesheet = fs
+        .readFileSync(stylesheetPath, 'utf8')
+        .replaceAll(
+          /@font-face\s*{(?=[^{}]*font-family:\s*["']?(?:Poppins|Inter)["']?\s*;)[^{}]*}/g,
+          '',
+        );
+
       fs.mkdirSync(assetsDirectory, { recursive: true });
       for (const file of fs.readdirSync(path.resolve(uiDistribution, 'assets'))) {
         if (!file.endsWith('.woff2')) continue;
         fs.copyFileSync(path.resolve(uiDistribution, 'assets', file), path.resolve(assetsDirectory, file));
       }
 
+      fs.writeFileSync(stylesheetPath, stylesheet);
       fs.appendFileSync(stylesheetPath, `\n${fontStyles}`);
     },
   };

packages/ui/combine-css-bundle.mts

@@ -6,14 +6,13 @@ import type { Plugin } from 'vite';
 /**
  * Post-build CSS steps for the multi-entry library bundle. See css-layers.md.
  *
- * Emits `index.css` (all component styles, prefixed with the @layer order)
- * and `styles.css` (the global layer order, reset, typography and fonts), then
- * stamps the @layer order statement into every per-component stylesheet in
- * `dist/assets/`. Duplicate statements are no-ops, so whichever stylesheet
- * loads first establishes the correct order. Do not rely on import order
- * instead: in the built barrel the injected per-chunk CSS evaluates before
- * the entry CSS, so "the declaration loads first" is true in src/ but false
- * in dist/ (the inverted-cascade bug class).
+ * Emits the standalone stylesheets, font assets, and a font-free stylesheet
+ * for docs previews, then stamps the @layer order statement into every
+ * per-component stylesheet in `dist/assets/`. Duplicate statements are
+ * no-ops, so whichever stylesheet loads first establishes the correct order.
+ * Do not rely on import order instead: in the built barrel the injected
+ * per-chunk CSS evaluates before the entry CSS, so "the declaration loads
+ * first" is true in src/ but false in dist/ (the inverted-cascade bug class).
  */
 export function combineCssBundle(rootDirectory: string): Plugin {
   const distributionDirectory = path.resolve(rootDirectory, 'dist');
@@ -23,11 +22,13 @@ export function combineCssBundle(rootDirectory: string): Plugin {
     name: 'wb-ui:combine-css-bundle',
     apply: 'build',
     closeBundle() {
+      assetsDirectoryOf(distributionDirectory);
       const fontStyles = emitFontAssets(distributionDirectory);
       const layerOrder = readLayerOrder(stylesDirectory);
       fs.writeFileSync(path.resolve(distributionDirectory, 'fonts.css'), `${layerOrder}\n${fontStyles}\n`);
       writeCombinedStylesheet(distributionDirectory, stylesDirectory, fontStyles);
       writeGlobalStylesheet(distributionDirectory, stylesDirectory, fontStyles);
+      appendFontStylesToEntryChunk(distributionDirectory, fontStyles);
       prependLayerOrderToAssets(distributionDirectory, stylesDirectory);
     },
   };
@@ -94,7 +95,7 @@ const FONT_FACES: FontFaceDefinition[] = [
 
 const require = createRequire(import.meta.url);
 
-export function emitFontAssets(distributionDirectory: string): string {
+function emitFontAssets(distributionDirectory: string): string {
   const assetsDirectory = path.resolve(distributionDirectory, 'assets');
   fs.mkdirSync(assetsDirectory, { recursive: true });
 
@@ -189,8 +190,9 @@ function writeCombinedStylesheet(distributionDirectory: string, stylesDirectory:
     .map((file) => fs.readFileSync(path.resolve(assetsDirectory, file), 'utf8'))
     .join('\n');
 
-  const combined = `${readLayerOrder(stylesDirectory)}\n${styles}\n${fontStyles}`;
-  fs.writeFileSync(path.resolve(distributionDirectory, 'index.css'), combined);
+  const combined = `${readLayerOrder(stylesDirectory)}\n${styles}`;
+  fs.writeFileSync(path.resolve(distributionDirectory, 'index.css'), `${combined}\n${fontStyles}`);
+  fs.writeFileSync(path.resolve(distributionDirectory, 'docs-preview.css'), combined);
 }
 
 function writeGlobalStylesheet(distributionDirectory: string, stylesDirectory: string, fontStyles: string) {
@@ -201,6 +203,19 @@ function writeGlobalStylesheet(distributionDirectory: string, stylesDirectory: s
   fs.writeFileSync(path.resolve(distributionDirectory, 'styles.css'), `${globals}\n${fontStyles}`);
 }
 
+function appendFontStylesToEntryChunk(distributionDirectory: string, fontStyles: string) {
+  const stylesheetPath = path.resolve(assetsDirectoryOf(distributionDirectory), 'index.css');
+  if (!fs.existsSync(stylesheetPath)) {
+    throw new Error(
+      `wb-ui:combine-css-bundle: ${stylesheetPath} is missing - ` +
+        'the root JS barrel has no entry-chunk stylesheet to carry the font faces',
+    );
+  }
+
+  const entryChunkFontStyles = fontStyles.replaceAll('url(./assets/', 'url(./');
+  fs.appendFileSync(stylesheetPath, `\n${entryChunkFontStyles}`);
+}
+
 function prependLayerOrderToAssets(distributionDirectory: string, stylesDirectory: string) {
   const assetsDirectory = assetsDirectoryOf(distributionDirectory);
   const layerOrder = readLayerOrder(stylesDirectory);