describe-me 0.5.0-next.2 → 0.5.0

package/README.md

@@ -24,11 +24,24 @@ describe-me dev                  # viewer on http://localhost:6006, live while v
 describe-me build --out docs     # self-contained static site: viewer + __data/
 ```
 
-| Flag     | Default            | Meaning                           |
-| -------- | ------------------ | --------------------------------- |
-| `--data` | `.describe-me`     | The directory the reporter wrote. |
-| `--out`  | `describe-me-dist` | Output directory for `build`.     |
-| `--port` | `6006`             | Port for `dev`.                   |
+| Flag                | Default              | Meaning                               |
+| ------------------- | -------------------- | ------------------------------------- |
+| `--data`            | `.describe-me`       | The directory the reporter wrote.     |
+| `--out`             | `describe-me-dist`   | Output directory for `build`.         |
+| `--port`            | `6006`               | Port for `dev`.                       |
+| `--no-vendor-fonts` | fonts are downloaded | `build`: keep web fonts on their CDN. |
+
+The viewer has search, collapsible suites, keyboard navigation, custom
+viewport sizes and shareable links
+([Viewer](https://github.com/grzehub/describe-me#viewer)).
+
+`build` downloads the web fonts that the preview head and the snapshots load
+from Google Fonts, Bunny Fonts and Fontsource on jsDelivr into the site, so
+the docs show them offline. Adobe Fonts stay remote, because their license
+does not allow self-hosting, and so do fonts on any other host. The build
+lists both. Downloads are cached in `node_modules/.cache/describe-me/fonts`.
+A font that does not download keeps loading from the network, and the build
+never fails because of it.
 
 The static site uses relative URLs, so it works from a sub-path such as
 GitHub Pages.

package/dist-cli/chrome-user-agent.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The User-Agent of a current desktop Chrome. Google Fonts serves woff2 split
+ * by `unicode-range` only to browsers it knows.
+ */
+export declare const CHROME_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36";

package/dist-cli/chrome-user-agent.js

@@ -0,0 +1,5 @@
+/**
+ * The User-Agent of a current desktop Chrome. Google Fonts serves woff2 split
+ * by `unicode-range` only to browsers it knows.
+ */
+export const CHROME_USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36';

package/dist-cli/download.d.ts

@@ -0,0 +1,27 @@
+import type { FontKind } from './font-provider.js';
+/** How to request one file. */
+export interface DownloadOptions {
+    /** What the URL must stay after every redirect. */
+    kind: FontKind;
+    fetch: typeof fetch;
+    timeoutMs: number;
+    maxBytes: number;
+    /** Hosts that failed on the network in this run, with the reason. Read and written. */
+    unreachableHosts: Map<string, string>;
+}
+/** A downloaded body, or why there is none. `network` marks a failure before any HTTP answer. */
+export type DownloadResult = {
+    ok: true;
+    bytes: Uint8Array;
+    finalUrl: string;
+    contentType: string;
+} | {
+    ok: false;
+    reason: string;
+    network: boolean;
+};
+/**
+ * Download one file from an allowlisted `https:` URL. Redirects are followed
+ * by hand and must stay on the allowlist with the same kind. Never throws.
+ */
+export declare function download(url: URL, options: DownloadOptions): Promise<DownloadResult>;

package/dist-cli/download.js

@@ -0,0 +1,132 @@
+import { CHROME_USER_AGENT } from './chrome-user-agent.js';
+import { fontProvider } from './font-provider.js';
+const MAX_REDIRECTS = 5;
+const STYLESHEET_ACCEPT = 'text/css,*/*;q=0.1';
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+function failure(reason, network = false) {
+    return { ok: false, reason, network };
+}
+function megabytes(bytes) {
+    return `${Math.round(bytes / 1_000_000)} MB`;
+}
+/** Node rejects with `TypeError('fetch failed')` and keeps the system error code in `cause`. */
+function networkReason(error, timeoutMs) {
+    if (error instanceof Error && error.name === 'TimeoutError') {
+        return `no answer within ${timeoutMs / 1000} s`;
+    }
+    const code = error?.cause?.code;
+    if (typeof code === 'string') {
+        return code;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function headersFor(kind) {
+    if (kind === 'stylesheet') {
+        return { 'User-Agent': CHROME_USER_AGENT, Accept: STYLESHEET_ACCEPT };
+    }
+    return { 'User-Agent': CHROME_USER_AGENT };
+}
+/** The body, or null once it grows past `maxBytes`. */
+async function readBody(response, maxBytes) {
+    const length = response.headers.get('content-length');
+    if (length !== null && Number(length) > maxBytes) {
+        await response.body?.cancel();
+        return null;
+    }
+    if (response.body === null) {
+        return new Uint8Array();
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    let chunk = await reader.read();
+    while (!chunk.done) {
+        total += chunk.value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            return null;
+        }
+        chunks.push(chunk.value);
+        chunk = await reader.read();
+    }
+    return Buffer.concat(chunks);
+}
+/** `url` resolved against `base` and upgraded to `https:`, or null for other schemes. */
+function httpsUrl(url, base) {
+    if (!URL.canParse(url, base)) {
+        return null;
+    }
+    const target = new URL(url, base);
+    if (target.protocol === 'http:') {
+        target.protocol = 'https:';
+    }
+    return target.protocol === 'https:' ? target : null;
+}
+/** The next hop of a redirect, checked against the allowlist before it is requested. */
+function nextHop(response, current, kind) {
+    const location = response.headers.get('location');
+    if (location === null) {
+        return failure(`HTTP ${response.status} without a location`);
+    }
+    const target = httpsUrl(location, current);
+    if (target === null) {
+        return failure('redirect to an invalid URL');
+    }
+    const provider = fontProvider(target);
+    if (!provider?.vendorable || provider.kind !== kind) {
+        return failure(`redirect to ${target.hostname}, off the font allowlist`);
+    }
+    return target;
+}
+/** One request. A URL is the next hop of a redirect. */
+async function request(url, options) {
+    const response = await options.fetch(url.href, {
+        headers: headersFor(options.kind),
+        redirect: 'manual',
+        signal: AbortSignal.timeout(options.timeoutMs),
+    });
+    if (REDIRECT_STATUSES.has(response.status)) {
+        await response.body?.cancel();
+        return nextHop(response, url, options.kind);
+    }
+    if (!response.ok) {
+        await response.body?.cancel();
+        return failure(`HTTP ${response.status}`);
+    }
+    const bytes = await readBody(response, options.maxBytes);
+    if (bytes === null) {
+        return failure(`larger than ${megabytes(options.maxBytes)}`);
+    }
+    const contentType = response.headers.get('content-type') ?? '';
+    return { ok: true, bytes, finalUrl: url.href, contentType };
+}
+/**
+ * Download one file from an allowlisted `https:` URL. Redirects are followed
+ * by hand and must stay on the allowlist with the same kind. Never throws.
+ */
+export async function download(url, options) {
+    let current = httpsUrl(url.href, url);
+    if (current === null) {
+        return failure('not an http(s) URL');
+    }
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        const unreachable = options.unreachableHosts.get(current.hostname);
+        if (unreachable !== undefined) {
+            return failure(unreachable, true);
+        }
+        let outcome;
+        try {
+            outcome = await request(current, options);
+        }
+        catch (error) {
+            const reason = networkReason(error, options.timeoutMs);
+            options.unreachableHosts.set(current.hostname, reason);
+            return failure(reason, true);
+        }
+        if (!(outcome instanceof URL)) {
+            return outcome;
+        }
+        current = outcome;
+    }
+    return failure(`more than ${MAX_REDIRECTS} redirects`);
+}

package/dist-cli/find-remote-urls.d.ts

@@ -0,0 +1,15 @@
+/** A remote URL found in a text. */
+export interface RemoteUrl {
+    /** The URL as written. A rewrite replaces it whole. */
+    raw: string;
+    /** The `https:` URL to request. */
+    url: string;
+    /** Offset of `raw` in the text. */
+    start: number;
+    /** Offset just past `raw`. */
+    end: number;
+}
+/** How the text is written. Only HTML escapes `&` as `&` inside URLs. */
+export type TextSyntax = 'json' | 'css' | 'html';
+/** Every remote URL in a snapshot, a stylesheet or the preview head, in source order. */
+export declare function findRemoteUrls(text: string, syntax: TextSyntax): RemoteUrl[];

package/dist-cli/find-remote-urls.js

@@ -0,0 +1,24 @@
+/**
+ * `http://`, `https://` and protocol-relative `//` URLs. A `//` after a word
+ * character, `:` or `/` is part of something else, such as `a//b`. A URL ends
+ * where JSON, CSS or HTML would end it: `\"` in JSON, `)` in an unquoted
+ * `url()`. Google Fonts URLs contain `;`, `&`, `@`, `,` and `:`, so those do not.
+ */
+const REMOTE_URL = /(?<![\w:/])(?:https?:)?\/\/[^\s"'`\\()<>]+/gi;
+function requestUrl(raw, syntax) {
+    const decoded = syntax === 'html' ? raw.replaceAll('&amp;', '&') : raw;
+    const scheme = decoded.slice(0, decoded.indexOf('//')).toLowerCase();
+    const https = scheme === 'https:' ? decoded : `https:${decoded.slice(scheme.length)}`;
+    return URL.canParse(https) ? new URL(https).href : null;
+}
+/** Every remote URL in a snapshot, a stylesheet or the preview head, in source order. */
+export function findRemoteUrls(text, syntax) {
+    const found = [];
+    for (const match of text.matchAll(REMOTE_URL)) {
+        const url = requestUrl(match[0], syntax);
+        if (url !== null) {
+            found.push({ raw: match[0], url, start: match.index, end: match.index + match[0].length });
+        }
+    }
+    return found;
+}

package/dist-cli/font-cache-dir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Where downloaded fonts are cached: `node_modules/.cache/describe-me/fonts`
+ * in the nearest `node_modules` at or above the source data directory, as
+ * other build tools do. Without one it is a directory in the system temp dir.
+ */
+export declare function fontCacheDir(sourceDataDir: string): string;

package/dist-cli/font-cache-dir.js

@@ -0,0 +1,25 @@
+import { existsSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+function isDirectory(path) {
+    return existsSync(path) && statSync(path).isDirectory();
+}
+/**
+ * Where downloaded fonts are cached: `node_modules/.cache/describe-me/fonts`
+ * in the nearest `node_modules` at or above the source data directory, as
+ * other build tools do. Without one it is a directory in the system temp dir.
+ */
+export function fontCacheDir(sourceDataDir) {
+    let dir = sourceDataDir;
+    while (true) {
+        const nodeModules = join(dir, 'node_modules');
+        if (isDirectory(nodeModules)) {
+            return join(nodeModules, '.cache', 'describe-me', 'fonts');
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            return join(tmpdir(), 'describe-me-fonts');
+        }
+        dir = parent;
+    }
+}

package/dist-cli/font-cache.d.ts

@@ -0,0 +1,25 @@
+/** A cached response that passed validation. */
+export interface CachedResponse {
+    /** The URL as requested. */
+    url: string;
+    /** The URL after redirects, which relative URLs inside a stylesheet resolve against. */
+    finalUrl: string;
+    contentType: string;
+    /** `Date.now()` of the download. */
+    fetchedAt: number;
+    body: Uint8Array;
+}
+/**
+ * Downloaded stylesheets and fonts on disk, keyed by User-Agent and URL, so a
+ * build works offline after one online build. Every problem counts as a miss.
+ */
+export declare class FontCache {
+    private readonly dir;
+    private readonly userAgent;
+    constructor(dir: string, userAgent: string);
+    /** The entry for `url`, or null when there is none or it cannot be read. */
+    read(url: string): CachedResponse | null;
+    /** The body goes first, so an entry whose metadata exists is complete. */
+    write(entry: CachedResponse): void;
+    private key;
+}

package/dist-cli/font-cache.js

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+function isMeta(value, url) {
+    const meta = value;
+    return (typeof meta === 'object' &&
+        meta !== null &&
+        meta.url === url &&
+        typeof meta.finalUrl === 'string' &&
+        URL.canParse(meta.finalUrl) &&
+        typeof meta.contentType === 'string' &&
+        typeof meta.fetchedAt === 'number');
+}
+/**
+ * Downloaded stylesheets and fonts on disk, keyed by User-Agent and URL, so a
+ * build works offline after one online build. Every problem counts as a miss.
+ */
+export class FontCache {
+    dir;
+    userAgent;
+    constructor(dir, userAgent) {
+        this.dir = dir;
+        this.userAgent = userAgent;
+    }
+    /** The entry for `url`, or null when there is none or it cannot be read. */
+    read(url) {
+        const key = this.key(url);
+        try {
+            const meta = JSON.parse(readFileSync(join(this.dir, `${key}.json`), 'utf8'));
+            if (!isMeta(meta, url)) {
+                return null;
+            }
+            return { ...meta, body: readFileSync(join(this.dir, `${key}.body`)) };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The body goes first, so an entry whose metadata exists is complete. */
+    write(entry) {
+        const key = this.key(entry.url);
+        const meta = {
+            url: entry.url,
+            finalUrl: entry.finalUrl,
+            contentType: entry.contentType,
+            fetchedAt: entry.fetchedAt,
+        };
+        try {
+            mkdirSync(this.dir, { recursive: true });
+            writeFileSync(join(this.dir, `${key}.body`), entry.body);
+            writeFileSync(join(this.dir, `${key}.json`), JSON.stringify(meta));
+        }
+        catch {
+            // A read-only cache only costs the next build a download.
+        }
+    }
+    key(url) {
+        return createHash('sha1').update(`${this.userAgent}\n${url}`).digest('hex');
+    }
+}

package/dist-cli/font-extension.d.ts

@@ -0,0 +1,2 @@
+/** The extension of a font file from its magic bytes, or null when the bytes are not a font. */
+export declare function fontExtension(bytes: Uint8Array): string | null;

package/dist-cli/font-extension.js

@@ -0,0 +1,15 @@
+/** File signatures of the font formats a browser loads, read from the first four bytes. */
+const SIGNATURES = [
+    [[0x77, 0x4f, 0x46, 0x32], '.woff2'],
+    [[0x77, 0x4f, 0x46, 0x46], '.woff'],
+    [[0x4f, 0x54, 0x54, 0x4f], '.otf'],
+    [[0x00, 0x01, 0x00, 0x00], '.ttf'],
+    [[0x74, 0x72, 0x75, 0x65], '.ttf'],
+];
+/** The extension of a font file from its magic bytes, or null when the bytes are not a font. */
+export function fontExtension(bytes) {
+    const match = SIGNATURES.find(([signature]) => {
+        return signature.every((byte, i) => bytes[i] === byte);
+    });
+    return match === undefined ? null : match[1];
+}

package/dist-cli/font-provider.d.ts

@@ -0,0 +1,17 @@
+/** What a URL on a font host points at. */
+export type FontKind = 'stylesheet' | 'font';
+/** A font host that serves a URL: vendorable with its kind, or remote for a reason. */
+export type FontProvider = {
+    name: string;
+    vendorable: true;
+    kind: FontKind;
+} | {
+    name: string;
+    vendorable: false;
+    reason: string;
+};
+/**
+ * The font host behind a URL, or null when the URL is not a stylesheet or a
+ * font of a known host. Bare origins, such as a `preconnect`, are null too.
+ */
+export declare function fontProvider(url: URL): FontProvider | null;

package/dist-cli/font-provider.js

@@ -0,0 +1,66 @@
+const FONT_EXTENSIONS = ['.woff2', '.woff', '.ttf', '.otf'];
+const FONTSOURCE_PACKAGES = ['/npm/@fontsource/', '/npm/@fontsource-variable/'];
+const FONTSOURCE_FILES = '/fontsource/fonts/';
+const GOOGLE_STYLESHEETS = new Set(['/css', '/css2', '/icon']);
+const BUNNY_STYLESHEETS = new Set(['/css', '/css2']);
+const ADOBE_HOSTS = new Set([
+    'use.typekit.net',
+    'use.typekit.com',
+    'p.typekit.net',
+    'fonts.adobe.com',
+]);
+const ADOBE = {
+    name: 'Adobe Fonts',
+    vendorable: false,
+    reason: 'Adobe Fonts do not allow self-hosting',
+};
+function hasFontExtension(pathname) {
+    const lower = pathname.toLowerCase();
+    return FONT_EXTENSIONS.some((extension) => lower.endsWith(extension));
+}
+function googleApis(pathname) {
+    return GOOGLE_STYLESHEETS.has(pathname) ? 'stylesheet' : null;
+}
+function googleStatic(pathname) {
+    return pathname === '/' ? null : 'font';
+}
+function bunny(pathname) {
+    if (BUNNY_STYLESHEETS.has(pathname)) {
+        return 'stylesheet';
+    }
+    return pathname.includes('/files/') ? 'font' : null;
+}
+function fontsource(pathname) {
+    if (FONTSOURCE_PACKAGES.some((prefix) => pathname.startsWith(prefix))) {
+        if (pathname.toLowerCase().endsWith('.css')) {
+            return 'stylesheet';
+        }
+        return hasFontExtension(pathname) ? 'font' : null;
+    }
+    return pathname.startsWith(FONTSOURCE_FILES) ? 'font' : null;
+}
+/** The allowlist, by exact hostname. */
+const HOSTS = new Map([
+    ['fonts.googleapis.com', { name: 'Google Fonts', kind: googleApis }],
+    ['fonts.gstatic.com', { name: 'Google Fonts', kind: googleStatic }],
+    ['fonts.bunny.net', { name: 'Bunny Fonts', kind: bunny }],
+    ['cdn.jsdelivr.net', { name: 'Fontsource on jsDelivr', kind: fontsource }],
+]);
+/**
+ * The font host behind a URL, or null when the URL is not a stylesheet or a
+ * font of a known host. Bare origins, such as a `preconnect`, are null too.
+ */
+export function fontProvider(url) {
+    if ((url.protocol !== 'https:' && url.protocol !== 'http:') || url.port !== '') {
+        return null;
+    }
+    if (ADOBE_HOSTS.has(url.hostname)) {
+        return url.pathname === '/' ? null : ADOBE;
+    }
+    const host = HOSTS.get(url.hostname);
+    const kind = host?.kind(url.pathname) ?? null;
+    if (host === undefined || kind === null) {
+        return null;
+    }
+    return { name: host.name, vendorable: true, kind };
+}

package/dist-cli/main.js

@@ -4,7 +4,7 @@ import { runDev } from './run-dev.js';
 const USAGE = `describe-me — living component docs from your tests
 
   describe-me dev   [--data .describe-me] [--port 6006]   viewer with live updates
-  describe-me build [--data .describe-me] [--out describe-me-dist]   static site
+  describe-me build [--data .describe-me] [--out describe-me-dist] [--no-vendor-fonts]   static site
 `;
 /** Entry point of the `describe-me` binary. */
 async function main() {
@@ -14,7 +14,7 @@ async function main() {
         return;
     }
     if (options.command === 'build') {
-        await runBuild(options.data, options.out);
+        await runBuild(options.data, options.out, { vendorFonts: options.vendorFonts });
         return;
     }
     await runDev(options.data, options.port);

package/dist-cli/map-with-concurrency.d.ts

@@ -0,0 +1,2 @@
+/** Run `run` over `items` with at most `limit` calls in flight, and keep the results in order. */
+export declare function mapWithConcurrency<Item, Result>(items: readonly Item[], limit: number, run: (item: Item) => Promise<Result>): Promise<Result[]>;

package/dist-cli/map-with-concurrency.js

@@ -0,0 +1,13 @@
+/** Run `run` over `items` with at most `limit` calls in flight, and keep the results in order. */
+export async function mapWithConcurrency(items, limit, run) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await run(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}

package/dist-cli/parse-args.d.ts

@@ -7,6 +7,11 @@ export interface CliOptions {
     out: string;
     /** Port for `dev`. */
     port: number;
+    /** `build`: download web fonts from known font hosts into the site. */
+    vendorFonts: boolean;
 }
-/** Turn `describe-me <command> [--data dir] [--out dir] [--port n]` into options with defaults. */
+/**
+ * Turn `describe-me <command> [--data dir] [--out dir] [--port n] [--no-vendor-fonts]`
+ * into options with defaults.
+ */
 export declare function parseArgs(argv: string[]): CliOptions;

package/dist-cli/parse-args.js

@@ -8,16 +8,21 @@ function commandFrom(positional, help) {
     }
     return 'dev';
 }
-/** Turn `describe-me <command> [--data dir] [--out dir] [--port n]` into options with defaults. */
+/**
+ * Turn `describe-me <command> [--data dir] [--out dir] [--port n] [--no-vendor-fonts]`
+ * into options with defaults.
+ */
 export function parseArgs(argv) {
     const { values, positionals } = parseNodeArgs({
         args: argv,
         allowPositionals: true,
+        allowNegative: true,
         options: {
             data: { type: 'string', default: '.describe-me' },
             out: { type: 'string', default: 'describe-me-dist' },
             port: { type: 'string', default: '6006' },
             help: { type: 'boolean', short: 'h', default: false },
+            'vendor-fonts': { type: 'boolean', default: true },
         },
     });
     return {
@@ -25,5 +30,6 @@ export function parseArgs(argv) {
         data: values.data,
         out: values.out,
         port: Number(values.port),
+        vendorFonts: values['vendor-fonts'],
     };
 }

package/dist-cli/print-vendor-report.d.ts

@@ -0,0 +1,3 @@
+import type { VendorReport } from './vendor-fonts.js';
+/** Tell the user what `describe-me build` vendored and what keeps loading from the network. */
+export declare function printVendorReport(report: VendorReport): void;

package/dist-cli/print-vendor-report.js

@@ -0,0 +1,35 @@
+const MAX_FAILURE_LINES = 5;
+function plural(count, word) {
+    return `${count} ${word}${count === 1 ? '' : 's'}`;
+}
+function size(bytes) {
+    if (bytes < 1_000_000) {
+        return `${Math.round(bytes / 1000)} kB`;
+    }
+    return `${(bytes / 1_000_000).toFixed(1)} MB`;
+}
+function summary(report) {
+    const parts = report.stylesheets.map(({ host, count }) => {
+        return `${plural(count, 'stylesheet')} from ${host}`;
+    });
+    parts.push(`${plural(report.fontFiles, 'font file')} (${size(report.fontBytes)})`);
+    const last = parts.pop();
+    const listed = parts.length === 0 ? last : `${parts.join(', ')} and ${last}`;
+    return `describe-me: vendored ${listed} into __data/assets`;
+}
+/** Tell the user what `describe-me build` vendored and what keeps loading from the network. */
+export function printVendorReport(report) {
+    if (report.stylesheets.length > 0 || report.fontFiles > 0) {
+        console.log(summary(report));
+    }
+    for (const { host, reason } of report.leftRemote) {
+        console.log(`describe-me: left remote: ${host} (${reason})`);
+    }
+    for (const { url, reason } of report.failures.slice(0, MAX_FAILURE_LINES)) {
+        console.warn(`describe-me: ${url} did not download (${reason}). It keeps loading from the network.`);
+    }
+    const more = report.failures.length - MAX_FAILURE_LINES;
+    if (more > 0) {
+        console.warn(`describe-me: and ${more} more that did not download.`);
+    }
+}

package/dist-cli/run-build.d.ts

@@ -1,2 +1,10 @@
-/** Produce a self-contained static site: the viewer plus the data directory under `__data/`. */
-export declare function runBuild(data: string, out: string): Promise<void>;
+/** What `build` does besides the Vite build. */
+export interface RunBuildOptions {
+    /** Download web fonts from known font hosts into the site. */
+    vendorFonts: boolean;
+}
+/**
+ * Produce a self-contained static site: the viewer plus the data directory
+ * under `__data/`. Font vendoring works on that copy and never fails the build.
+ */
+export declare function runBuild(data: string, out: string, options: RunBuildOptions): Promise<void>;

package/dist-cli/run-build.js

@@ -1,8 +1,15 @@
-import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { build } from 'vite';
+import { fontCacheDir } from './font-cache-dir.js';
+import { printVendorReport } from './print-vendor-report.js';
+import { vendorFonts } from './vendor-fonts.js';
 import { viewerRoot } from './viewer-root.js';
-/** Produce a self-contained static site: the viewer plus the data directory under `__data/`. */
-export async function runBuild(data, out) {
+/**
+ * Produce a self-contained static site: the viewer plus the data directory
+ * under `__data/`. Font vendoring works on that copy and never fails the build.
+ */
+export async function runBuild(data, out, options) {
     process.env.DESCRIBE_ME_DIR = resolve(data);
     const root = viewerRoot();
     await build({
@@ -10,4 +17,19 @@ export async function runBuild(data, out) {
         configFile: resolve(root, 'vite.config.ts'),
         build: { outDir: resolve(out), emptyOutDir: true },
     });
+    if (!options.vendorFonts) {
+        return;
+    }
+    // The Vite plugin has already warned when there was no data to copy.
+    const dataDir = join(resolve(out), '__data');
+    if (!existsSync(dataDir)) {
+        return;
+    }
+    try {
+        printVendorReport(await vendorFonts(dataDir, { cacheDir: fontCacheDir(resolve(data)) }));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`describe-me: font vendoring stopped (${message}). Fonts keep loading from the network.`);
+    }
 }

package/dist-cli/store-vendored-file.d.ts

@@ -0,0 +1,2 @@
+/** Write a downloaded file into `assets/` under its content hash and return the name. */
+export declare function storeVendoredFile(assetsDir: string, bytes: Uint8Array, extension: string): string;