@nifrajs/web 0.1.0-alpha.1

package/dist/fonts-google.js

@@ -0,0 +1,291 @@
+/**
+ * Build-time Google Fonts automation — the `next/font/google` equivalent. At **build time** (never on
+ * the request path) it: builds the Google Fonts CSS2 URL, downloads the stylesheet, parses the
+ * `@font-face` rules, downloads each `.woff2`, content-hashes it, writes it next to your assets, and
+ * hands back a **self-hosted** `@font-face` stylesheet + the matching `<link rel="preload">`s. The
+ * result is identical to dropping the files in yourself and calling {@link fontFace} — no runtime CDN
+ * hotlink, no layout shift, hashed filenames for immutable caching.
+ *
+ *   // fonts.build.ts — run once at build time (e.g. a prebuild step)
+ *   import { loadGoogleFont } from "@nifrajs/web/fonts"
+ *   const inter = await loadGoogleFont(
+ *     { family: "Inter", weights: [400, 700], subsets: ["latin"] },
+ *     { outDir: "public/fonts" },               // → public/fonts/inter-latin-normal-400-<hash>.woff2
+ *   )
+ *   await Bun.write("app/fonts.css", inter.css) // import this stylesheet from your app
+ *   // inter.preloads → spread into a root layout's `meta.link`
+ *
+ * Security: this fetches remote content and writes it to disk, so every input is validated and the
+ * font-file host is **allowlisted to `fonts.gstatic.com` over https** — a tampered/MITM'd stylesheet
+ * cannot make the build fetch an arbitrary URL (SSRF) or write an attacker-chosen blob. Downloads are
+ * size-capped. Filenames are derived only from validated tokens + a content hash (no path traversal).
+ */
+import { writeFile as fsWriteFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fontFace, fontPreload } from "./fonts.js";
+const CSS2_ENDPOINT = "https://fonts.googleapis.com/css2";
+/** Only this host, only over https, may supply a font file we download + write to disk. The SSRF gate:
+ * a tampered stylesheet listing any other `src: url(...)` is rejected, not fetched. */
+const ALLOWED_FONT_HOSTS = new Set(["fonts.gstatic.com"]);
+/** A modern desktop-Chrome UA so Google serves `woff2` (it falls back to bulky `ttf` for unknown UAs). */
+const WOFF2_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+const DEFAULT_MAX_FONT_BYTES = 5 * 1024 * 1024;
+const MAX_CSS_BYTES = 512 * 1024;
+const MAX_TEXT_LEN = 2048;
+const VALID_DISPLAY = new Set([
+    "auto",
+    "block",
+    "swap",
+    "fallback",
+    "optional",
+]);
+/** `true` iff `raw` is an `https://fonts.gstatic.com/…` URL — the only host we'll download from. */
+export function isAllowedFontUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    return url.protocol === "https:" && ALLOWED_FONT_HOSTS.has(url.hostname);
+}
+/** Validate a family name (letters/digits/spaces only). It goes into both a URL and a filename, so a
+ * strict allowlist closes injection + path-traversal at the source. */
+function validateFamily(family) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9 ]{0,62}$/.test(family)) {
+        throw new Error(`loadGoogleFont: invalid family ${JSON.stringify(family)} (letters, digits, and spaces only)`);
+    }
+    return family;
+}
+/** Normalize a weight to the token Google expects: `400`, `"700"`, `normal`→`400`, `bold`→`700`, or a
+ * variable range `"100 900"`. Rejects anything else (these land in the request URL). */
+function normalizeWeight(weight) {
+    if (typeof weight === "number") {
+        if (!Number.isInteger(weight) || weight < 1 || weight > 1000) {
+            throw new Error(`loadGoogleFont: invalid weight ${weight} (1–1000)`);
+        }
+        return String(weight);
+    }
+    const w = weight.trim();
+    if (w === "normal")
+        return "400";
+    if (w === "bold")
+        return "700";
+    // A single numeric weight, or a variable range like "100 900".
+    if (/^\d{1,4}$/.test(w) || /^\d{1,4} \d{1,4}$/.test(w))
+        return w;
+    throw new Error(`loadGoogleFont: invalid weight ${JSON.stringify(weight)}`);
+}
+function validateSubset(subset) {
+    if (!/^[a-z0-9-]{1,32}$/.test(subset)) {
+        throw new Error(`loadGoogleFont: invalid subset ${JSON.stringify(subset)}`);
+    }
+    return subset;
+}
+/** Build the Google Fonts CSS2 request URL. Pure + fully validated, so it's safe to feed a dynamic
+ * family/weights/text. Exported for advanced callers who fetch + parse the stylesheet themselves. */
+export function googleFontsCssUrl(options) {
+    const family = validateFamily(options.family);
+    const styles = options.styles ?? ["normal"];
+    for (const s of styles) {
+        if (s !== "normal" && s !== "italic") {
+            throw new Error(`loadGoogleFont: invalid style ${JSON.stringify(s)}`);
+        }
+    }
+    const display = options.display ?? "swap";
+    if (!VALID_DISPLAY.has(display)) {
+        throw new Error(`loadGoogleFont: invalid display ${JSON.stringify(display)}`);
+    }
+    // De-dupe + sort weights numerically (variable ranges sort by their lower bound).
+    const weights = [...new Set((options.weights ?? [400]).map(normalizeWeight))].sort((a, b) => Number.parseInt(a, 10) - Number.parseInt(b, 10));
+    const hasItalic = styles.includes("italic");
+    const hasNormal = styles.includes("normal") || !hasItalic;
+    // CSS2 wants spaces in the family as `+`; the `:`, `@`, `,`, `;` axis syntax stays literal.
+    const familyName = encodeURIComponent(family).replace(/%20/g, "+");
+    let axis;
+    if (hasItalic) {
+        // `ital,wght@` with tuples; all normal (ital=0) tuples must precede italic (ital=1).
+        const tuples = [];
+        if (hasNormal)
+            for (const w of weights)
+                tuples.push(`0,${w}`);
+        for (const w of weights)
+            tuples.push(`1,${w}`);
+        axis = `ital,wght@${tuples.join(";")}`;
+    }
+    else {
+        axis = `wght@${weights.join(";")}`;
+    }
+    const params = [`family=${familyName}:${axis}`, `display=${display}`];
+    if (options.text !== undefined) {
+        if (options.text.length > MAX_TEXT_LEN) {
+            throw new Error(`loadGoogleFont: text exceeds ${MAX_TEXT_LEN} chars`);
+        }
+        if (options.text.length > 0)
+            params.push(`text=${encodeURIComponent(options.text)}`);
+    }
+    return `${CSS2_ENDPOINT}?${params.join("&")}`;
+}
+const FACE_RE = /(?:\/\*\s*([^*]+?)\s*\*\/\s*)?@font-face\s*\{([^}]*)\}/g;
+const SRC_RE = /url\(\s*(['"]?)([^'")]+)\1\s*\)(?:\s*format\(\s*(['"]?)([^'")]+)\3\s*\))?/g;
+function declOf(body, prop) {
+    const m = body.match(new RegExp(`${prop}\\s*:\\s*([^;]+);`, "i"));
+    return m?.[1]?.trim();
+}
+/** Parse Google's stylesheet into structured faces, capturing the `/* subset *​/` label that precedes
+ * each `@font-face`. Pure — exported so callers can run their own download/write pipeline. */
+export function parseGoogleFontCss(css) {
+    const faces = [];
+    for (const match of css.matchAll(FACE_RE)) {
+        const subset = (match[1] ?? "").trim() || "default";
+        const body = match[2] ?? "";
+        const familyRaw = declOf(body, "font-family");
+        if (familyRaw === undefined)
+            continue;
+        const family = familyRaw.replace(/^['"]|['"]$/g, "");
+        const src = [];
+        for (const s of body.matchAll(SRC_RE)) {
+            const url = s[2];
+            if (url === undefined)
+                continue;
+            src.push(s[4] === undefined ? { url } : { url, format: s[4] });
+        }
+        if (src.length === 0)
+            continue;
+        const unicodeRange = declOf(body, "unicode-range");
+        faces.push({
+            family,
+            style: declOf(body, "font-style") ?? "normal",
+            weight: declOf(body, "font-weight") ?? "400",
+            subset,
+            ...(unicodeRange === undefined ? {} : { unicodeRange }),
+            src,
+        });
+    }
+    return faces;
+}
+/** First 16 hex chars of the SHA-256 of the bytes — a content hash for an immutable, cache-busting
+ * filename. Web Crypto, so it runs identically on Bun/Node/edge build hosts. `Uint8Array<ArrayBuffer>`
+ * (not the generic `ArrayBufferLike`) to satisfy WebCrypto's `BufferSource` under TS 5.7+ generics. */
+async function contentHash(bytes) {
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    let hex = "";
+    for (const b of new Uint8Array(digest))
+        hex += b.toString(16).padStart(2, "0");
+    return hex.slice(0, 16);
+}
+/** Lowercase a validated token into a filename-safe slug. */
+const slug = (s) => s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/** Host of a URL for error messages — we never echo the full untrusted URL+path. */
+const hostOf = (raw) => {
+    try {
+        return new URL(raw).host;
+    }
+    catch {
+        return "<invalid-url>";
+    }
+};
+/** Fetch with a hard byte ceiling. Checks the advertised `Content-Length` first (cheap reject), then
+ * re-checks the materialized body (a lying header can't smuggle a larger payload past us). */
+async function fetchBounded(fetchImpl, url, maxBytes, headers) {
+    const res = await fetchImpl(url, headers ? { headers } : {});
+    if (!res.ok) {
+        throw new Error(`loadGoogleFont: fetch failed (${res.status}) from ${hostOf(url)}`);
+    }
+    const advertised = Number(res.headers.get("content-length"));
+    if (Number.isFinite(advertised) && advertised > maxBytes) {
+        throw new Error(`loadGoogleFont: response from ${hostOf(url)} exceeds ${maxBytes} bytes`);
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (bytes.byteLength > maxBytes) {
+        throw new Error(`loadGoogleFont: response from ${hostOf(url)} exceeds ${maxBytes} bytes`);
+    }
+    return bytes;
+}
+const defaultWriteFile = async (path, bytes) => {
+    await mkdir(dirname(path), { recursive: true });
+    await fsWriteFile(path, bytes);
+};
+/**
+ * Download a Google font, self-host it, and return a CLS-safe `@font-face` stylesheet + preloads.
+ * See the module header for the full flow and security model. I/O (`fetch`, `writeFile`) is injectable
+ * so this is unit-testable without the network.
+ */
+export async function loadGoogleFont(options, io) {
+    const family = validateFamily(options.family);
+    const fetchImpl = io.fetch ?? fetch;
+    const writeFile = io.writeFile ?? defaultWriteFile;
+    const publicPath = (io.publicPath ?? "/fonts").replace(/\/+$/, "");
+    const maxBytes = io.maxBytesPerFile ?? DEFAULT_MAX_FONT_BYTES;
+    const wantedSubsets = options.subsets?.map(validateSubset);
+    const cssUrl = googleFontsCssUrl(options);
+    const cssBytes = await fetchBounded(fetchImpl, cssUrl, MAX_CSS_BYTES, { "user-agent": WOFF2_UA });
+    const css = new TextDecoder().decode(cssBytes);
+    let faces = parseGoogleFontCss(css);
+    if (faces.length === 0) {
+        throw new Error(`loadGoogleFont: Google returned no @font-face rules for ${JSON.stringify(family)}`);
+    }
+    // Filter to requested named subsets — but only when not glyph-subsetting (text mode labels faces
+    // `[0]`, `[1]`, … which carry no subset name).
+    if (wantedSubsets && wantedSubsets.length > 0 && options.text === undefined) {
+        faces = faces.filter((f) => wantedSubsets.includes(f.subset));
+        if (faces.length === 0) {
+            throw new Error(`loadGoogleFont: no faces for subsets [${wantedSubsets.join(", ")}]`);
+        }
+    }
+    const assets = [];
+    const rules = [];
+    const preloads = [];
+    for (const face of faces) {
+        // Prefer woff2; the CSS2 endpoint with a Chrome UA only ever returns woff2, but be defensive.
+        const source = face.src.find((s) => s.format === "woff2") ?? face.src[0];
+        if (!source)
+            continue;
+        if (!isAllowedFontUrl(source.url)) {
+            throw new Error(`loadGoogleFont: refusing to download a font from a non-Google host (${hostOf(source.url)}); ` +
+                "the stylesheet may be tampered with");
+        }
+        const bytes = await fetchBounded(fetchImpl, source.url, maxBytes);
+        const hash = await contentHash(bytes);
+        const style = face.style === "italic" ? "italic" : "normal";
+        const fileName = `${slug(family)}-${slug(face.subset)}-${style}-${face.weight.replace(/\s+/g, "_")}-${hash}.woff2`;
+        const path = join(io.outDir, fileName);
+        await writeFile(path, bytes);
+        const href = `${publicPath}/${fileName}`;
+        assets.push({
+            fileName,
+            href,
+            sourceUrl: source.url,
+            bytes,
+            subset: face.subset,
+            weight: face.weight,
+            style,
+        });
+        rules.push(fontFace({
+            family,
+            src: [{ url: href, format: "woff2" }],
+            weight: face.weight,
+            style,
+            display: options.display ?? "swap",
+            ...(face.unicodeRange === undefined ? {} : { unicodeRange: face.unicodeRange }),
+            ...(options.sizeAdjust === undefined ? {} : { sizeAdjust: options.sizeAdjust }),
+            ...(options.ascentOverride === undefined ? {} : { ascentOverride: options.ascentOverride }),
+            ...(options.descentOverride === undefined
+                ? {}
+                : { descentOverride: options.descentOverride }),
+            ...(options.lineGapOverride === undefined
+                ? {}
+                : { lineGapOverride: options.lineGapOverride }),
+        }));
+        preloads.push(fontPreload({ href }));
+    }
+    if (assets.length === 0) {
+        throw new Error(`loadGoogleFont: no downloadable woff2 sources for ${JSON.stringify(family)}`);
+    }
+    return { family, css: rules.join("\n\n"), assets, preloads };
+}
+//# sourceMappingURL=fonts-google.js.map

package/dist/fonts-google.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fonts-google.js","sourceRoot":"","sources":["../src/fonts-google.ts"],"names":[],"mappings":"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"}

package/dist/fonts.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Font optimization primitives — generate a **CLS-safe `@font-face`** rule and the matching
+ * **preload `<link>`** for a self-hosted font. The two fixes that matter most (the ones `next/font`
+ * automates) are right here: `font-display: swap` (text paints immediately, no invisible-text FOIT)
+ * plus a preload so the file downloads with the document, and optional metric overrides
+ * (`size-adjust`/`ascent-override`/…) so swapping from the fallback to the web font doesn't shift layout.
+ *
+ * Self-host the file (drop a `.woff2` in your assets — never hotlink Google's CDN), then:
+ *
+ *   // fonts.css (imported by your app — the CSS pipeline bundles + links it)
+ *   import { fontFace } from "@nifrajs/web"
+ *   export default fontFace({ family: "Inter", src: [{ url: "/fonts/inter.woff2" }], weight: "100 900" })
+ *
+ *   // a root layout's meta — becomes a <link rel="preload" as="font"> in <head>
+ *   export const meta = { link: [fontPreload({ href: "/fonts/inter.woff2" })] }
+ */
+/** `font-display` strategy. `swap` (the default here) paints fallback text immediately, then swaps. */
+export type FontDisplay = "auto" | "block" | "swap" | "fallback" | "optional";
+export interface FontSource {
+    /** URL of the self-hosted font file. */
+    readonly url: string;
+    /** `format()` hint (`woff2`, `woff`, `truetype`, …). Inferred from the URL extension when omitted. */
+    readonly format?: string;
+}
+export interface FontFace {
+    readonly family: string;
+    /** One or more sources (best format first; the browser picks the first it supports). */
+    readonly src: readonly FontSource[];
+    /** `400`, `"700"`, or a variable-font range like `"100 900"`. */
+    readonly weight?: number | string;
+    readonly style?: "normal" | "italic" | "oblique";
+    /** Defaults to `"swap"` (no flash of invisible text). */
+    readonly display?: FontDisplay;
+    /** Restrict the glyphs this face covers, e.g. `"U+0000-00FF"` — lets the browser skip the download
+     * for pages without those characters. */
+    readonly unicodeRange?: string;
+    /** Metric overrides that eliminate layout shift when the fallback swaps to the web font (the
+     * `next/font` technique). e.g. `sizeAdjust: "105%"`, `ascentOverride: "90%"`. */
+    readonly sizeAdjust?: string;
+    readonly ascentOverride?: string;
+    readonly descentOverride?: string;
+    readonly lineGapOverride?: string;
+}
+/**
+ * Build a single `@font-face` CSS rule. Defaults to `font-display: swap`; infers each source's
+ * `format()` from its extension. All values are CSS-escaped, so a dynamic family/URL can't inject CSS.
+ * Put the result in a stylesheet your app imports (nifra's CSS pipeline bundles + links it).
+ */
+export declare function fontFace(face: FontFace): string;
+export interface FontPreloadInput {
+    /** URL of the self-hosted font file to preload. */
+    readonly href: string;
+    /** MIME type (`font/woff2`, …). Inferred from the extension when omitted. */
+    readonly type?: string;
+    /** `crossorigin` mode — defaults to `"anonymous"`. Fonts are always fetched in CORS mode, and a
+     * preload whose `crossorigin` doesn't match the actual fetch is **wasted** (downloaded twice), so
+     * this is on by default. */
+    readonly crossOrigin?: "anonymous" | "use-credentials";
+}
+/**
+ * Build a font preload as a `<link>` attribute set for a route/layout's `meta.link` — nifra injects it
+ * into `<head>` (`<link rel="preload" as="font" type="font/woff2" crossorigin="anonymous">`). Values are
+ * escaped at injection by the head renderer. Preloading the font file removes a render-blocking round
+ * trip (the browser would otherwise discover the font only after parsing the CSS).
+ */
+export declare function fontPreload(input: FontPreloadInput): Record<string, string>;
+//# sourceMappingURL=fonts.d.ts.map

package/dist/fonts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../src/fonts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,uGAAuG;AACvG,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAA;AAE7E,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,sGAAsG;IACtG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wFAAwF;IACxF,QAAQ,CAAC,GAAG,EAAE,SAAS,UAAU,EAAE,CAAA;IACnC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;IAChD,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAA;IAC9B;6CACyC;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B;qFACiF;IACjF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AAwCD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CA4B/C;AAED,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;;gCAE4B;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,iBAAiB,CAAA;CACvD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS3E"}

package/dist/fonts.js

@@ -0,0 +1,103 @@
+/**
+ * Font optimization primitives — generate a **CLS-safe `@font-face`** rule and the matching
+ * **preload `<link>`** for a self-hosted font. The two fixes that matter most (the ones `next/font`
+ * automates) are right here: `font-display: swap` (text paints immediately, no invisible-text FOIT)
+ * plus a preload so the file downloads with the document, and optional metric overrides
+ * (`size-adjust`/`ascent-override`/…) so swapping from the fallback to the web font doesn't shift layout.
+ *
+ * Self-host the file (drop a `.woff2` in your assets — never hotlink Google's CDN), then:
+ *
+ *   // fonts.css (imported by your app — the CSS pipeline bundles + links it)
+ *   import { fontFace } from "@nifrajs/web"
+ *   export default fontFace({ family: "Inter", src: [{ url: "/fonts/inter.woff2" }], weight: "100 900" })
+ *
+ *   // a root layout's meta — becomes a <link rel="preload" as="font"> in <head>
+ *   export const meta = { link: [fontPreload({ href: "/fonts/inter.woff2" })] }
+ */
+const FORMAT_BY_EXT = {
+    woff2: "woff2",
+    woff: "woff",
+    ttf: "truetype",
+    otf: "opentype",
+    eot: "embedded-opentype",
+    svg: "svg",
+};
+const MIME_BY_EXT = {
+    woff2: "font/woff2",
+    woff: "font/woff",
+    ttf: "font/ttf",
+    otf: "font/otf",
+};
+/** Lowercased file extension of a URL, ignoring any `?query`/`#hash`. */
+function extOf(url) {
+    const clean = url.split(/[?#]/, 1)[0] ?? url;
+    const dot = clean.lastIndexOf(".");
+    return dot === -1 ? "" : clean.slice(dot + 1).toLowerCase();
+}
+/** Escape a value placed inside a double-quoted CSS string (`font-family`, `url("…")`, `format("…")`):
+ * neutralize the quote, the escape char, and newlines so a value can't break out of the declaration. */
+function cssQuoted(value) {
+    return value.replace(/[\\"]/g, "\\$&").replace(/[\r\n]+/g, " ");
+}
+/** Sanitize an **unquoted** CSS token value (`font-weight`, `unicode-range`, `size-adjust`, …): drop the
+ * characters that could end the declaration or the rule and inject more CSS. */
+function cssToken(value) {
+    return value
+        .replace(/[;{}<>]/g, "")
+        .replace(/[\r\n]+/g, " ")
+        .trim();
+}
+/**
+ * Build a single `@font-face` CSS rule. Defaults to `font-display: swap`; infers each source's
+ * `format()` from its extension. All values are CSS-escaped, so a dynamic family/URL can't inject CSS.
+ * Put the result in a stylesheet your app imports (nifra's CSS pipeline bundles + links it).
+ */
+export function fontFace(face) {
+    if (face.src.length === 0) {
+        throw new Error("fontFace: `src` needs at least one source");
+    }
+    const src = face.src
+        .map((source) => {
+        const format = source.format ?? FORMAT_BY_EXT[extOf(source.url)];
+        const formatPart = format === undefined ? "" : ` format("${cssQuoted(format)}")`;
+        return `url("${cssQuoted(source.url)}")${formatPart}`;
+    })
+        .join(", ");
+    const declarations = [
+        `font-family: "${cssQuoted(face.family)}"`,
+        `src: ${src}`,
+        `font-display: ${face.display ?? "swap"}`,
+    ];
+    if (face.weight !== undefined)
+        declarations.push(`font-weight: ${cssToken(String(face.weight))}`);
+    if (face.style !== undefined)
+        declarations.push(`font-style: ${face.style}`);
+    if (face.unicodeRange !== undefined)
+        declarations.push(`unicode-range: ${cssToken(face.unicodeRange)}`);
+    if (face.sizeAdjust !== undefined)
+        declarations.push(`size-adjust: ${cssToken(face.sizeAdjust)}`);
+    if (face.ascentOverride !== undefined)
+        declarations.push(`ascent-override: ${cssToken(face.ascentOverride)}`);
+    if (face.descentOverride !== undefined)
+        declarations.push(`descent-override: ${cssToken(face.descentOverride)}`);
+    if (face.lineGapOverride !== undefined)
+        declarations.push(`line-gap-override: ${cssToken(face.lineGapOverride)}`);
+    return `@font-face {\n  ${declarations.join(";\n  ")};\n}`;
+}
+/**
+ * Build a font preload as a `<link>` attribute set for a route/layout's `meta.link` — nifra injects it
+ * into `<head>` (`<link rel="preload" as="font" type="font/woff2" crossorigin="anonymous">`). Values are
+ * escaped at injection by the head renderer. Preloading the font file removes a render-blocking round
+ * trip (the browser would otherwise discover the font only after parsing the CSS).
+ */
+export function fontPreload(input) {
+    const type = input.type ?? MIME_BY_EXT[extOf(input.href)];
+    return {
+        rel: "preload",
+        as: "font",
+        href: input.href,
+        ...(type === undefined ? {} : { type }),
+        crossorigin: input.crossOrigin ?? "anonymous",
+    };
+}
+//# sourceMappingURL=fonts.js.map

package/dist/fonts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fonts.js","sourceRoot":"","sources":["../src/fonts.ts"],"names":[],"mappings":"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"}

package/dist/fs.d.ts

@@ -0,0 +1,10 @@
+import { type Manifest } from "./manifest.js";
+/** Options for {@link discoverRoutes}. */
+export interface DiscoverRoutesOptions {
+    /** Appended (as `?<importQuery>`) to each route's dynamic import — the dev server sets a
+     * changing value to bust Bun's module cache so SSR picks up edited route files. */
+    readonly importQuery?: string;
+}
+/** Scan a `routes/` directory (recursively) and build the route manifest. */
+export declare function discoverRoutes(dir: string, options?: DiscoverRoutesOptions): Manifest;
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAMA,OAAO,EAAiB,KAAK,QAAQ,EAAoB,MAAM,eAAe,CAAA;AAE9E,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC;uFACmF;IACnF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,QAAQ,CASzF"}

package/dist/fs.js

@@ -0,0 +1,24 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * @nifrajs/web/fs — filesystem route discovery. Separated from the main entry so `app.fetch`
+ * (and the rest of @nifrajs/web) stays fs-free + edge-portable: this runs at build/startup
+ * only. It scans a routes dir and feeds the pure `buildManifest`.
+ */
+import { readdirSync } from "node:fs";
+import { buildManifest } from "./manifest.js";
+/** Scan a `routes/` directory (recursively) and build the route manifest. */
+export function discoverRoutes(dir, options = {}) {
+    const files = readdirSync(dir, { recursive: true })
+        .map((file) => file.replaceAll("\\", "/")) // normalize Windows separators
+        .filter((file) => /\.(tsx|jsx|svelte|vue|mdx)$/.test(file));
+    const query = options.importQuery ? `?${options.importQuery}` : "";
+    return buildManifest(files, (file) => () => import(__rewriteRelativeImportExtension(`${dir}/${file}${query}`)));
+}
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":";;;;;;;;AAAA;;;;GAIG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,aAAa,EAAmC,MAAM,eAAe,CAAA;AAS9E,6EAA6E;AAC7E,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,UAAiC,EAAE;IAC7E,MAAM,KAAK,GAAI,WAAW,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAc;SAC9D,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,+BAA+B;SACzE,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAClE,OAAO,aAAa,CAClB,KAAK,EACL,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,kCAAC,GAAG,GAAG,IAAI,IAAI,GAAG,KAAK,EAAE,EAAyB,CACzE,CAAA;AACH,CAAC"}